Data model

Firestore collections and Cloud Storage buckets are grouped by subsystem. Cloud Functions are the only trusted writers for cross-user or agent-owned state.

Collection map

Area	Owner	Purpose	Key collections
identity	Identity callables	Agents, device keys, scoped keys, secrets, delegations	agents, agents/{id}/deviceKeys, agents/{id}/scopedKeys, agents/{id}/secrets
postbox	Inbox callables	Mailboxes, inbound/outbound messages, approvals, bounces	agents/{id}/mailbox, agents/{id}/messages, agents/{id}/outbound
memory	Provenance callables	Markdown-first agent memory plus derived search/index state	agents/{id}/memoryFiles plus Cloud Storage objects
advanced networking	Direct-route compatibility	Hostnames, cert ledger, IP history	agents/{id}/gateway/*
advanced scheduler	Direct-route compatibility	Jobs and runs	agents/{id}/jobs, run subcollections
advanced artifacts	Direct-route compatibility	File grants and signed URLs	agents/{id}/artifacts plus Cloud Storage
budgets	Budget callables	Policy, decisions, budgets, alerts	budgets, usage collections
audit	Cross-cutting	Hash-chained event ledger and exports	audit/*, agents/{id}/audit/*

Ownership: the agentId claim

Agent-owned paths are nested under agents/{agentId}. Agent callables resolve agentId from Firebase token claims minted by session, not from caller-sent request bodies.

Security Rules policy

Client Firestore rules stay deny-by-default for privileged agent data. Reads and writes that cross trust boundaries go through Cloud Functions, which use Firebase Admin credentials and append audit rows where required.

Hash-chained audit

Audit rows carry a previous hash and row hash. Offline export verifies the chain and signed manifest; scheduled verification anchors roots for later evidence checks.

Critical indexes

A handful of indexes carry the platform's performance. Most of them come from migration 0068's advisor fixes:

• Inbox message/outbound indexes by agent and timestamp.
• Provenance search indexes by agent, type, tags, and updated timestamp.
• Advanced networking indexes by agent and hostname.
• Advanced scheduler run indexes by agent, job, and started timestamp.

Tunables via identity.settings

Operator-adjustable knobs live in identity.settings (key jsonb, value jsonb) and are surfaced by /settings/list and /settings/set. Today's keys include:

Key	Type	Default	Meaning
postbox_retention_days	int	90	Hard-delete sent/read messages past this.
memory_retention_days	int	180	Trim old turns.
artifacts_ttl_days	int	30	Default expiry for newly registered artifacts.

See the per-subsystem pages for the full list.