Data model
Firestore is the control plane. Cloud Functions are the trusted writers for credentials, authority, approvals, evidence, and cross-tenant state; Security Rules deny direct client writes to those records.
Collection map
| Area | Primary paths | Purpose |
|---|---|---|
| Agent identity | agents/{agentId} | Owner, suspension, session version, current mandate, custody declaration. |
| Mandates | agents/{agentId}/mandates/{version} | Expiring, sealed authority versions; revoked and superseded versions remain readable. |
| Credentials | deviceKeys, scopedKeys, delegations under an agent | Key hashes/ciphertexts, scope, expiry, and revocation metadata. |
mailbox, messages, outbound, drafts under an agent | Provisioning truth, inbound records, approval-bound sends, and delivery outcomes. | |
| Memory | memoryFiles, memory_diffs, and memory objects | Markdown memory, document-level provenance, and expiring review diffs. |
| Tools | tools, toolConnections, secrets under an agent | Signed manifests, destination-bound encrypted credentials, and secret metadata. |
| Approvals | owners/{uid}/approvals/{id} | Pending/decided human gates bound to an action digest. |
| Teams and Pods | owners/{uid}/teamMembers, pods/{podId} | Named roles, membership, invitations, and agent attachments. |
| Budgets | budgets/{agentId}, agent usage/override paths | Estimated spend and enforcement state. |
| Evidence | audit/{seq}, audit_anchors/{seq}, checkpoint/timestamp collections | Hash chain, verified roots, and portable evidence support. |
| Configuration | config/{knownName} | Admin-managed policy, retention, mail, KMS, quotas, and cost-table records. |
Ownership and caller identity
agents/{agentId}.ownerUid is the ownership root. Human callables compare the Firebase user ID
or a validated team membership. Agent callables derive agentId and ownerUid from verified
token claims, then re-check the credential and current mandate as required.
Authority lifecycle
An agent points to currentMandateId and currentMandateDocId. Amendments create a new document
and increment sessionVersion; revocation writes a revoked version, suspends the agent, and also
increments the version. Sessions minted against older authority therefore stop working.
Mandates are not deleted. Working agent data may be removed during offboarding, while the global audit evidence and owner account remain.
Sensitive values
- Device and scoped keys are returned once. Firestore stores lookup hashes and, where needed, KMS ciphertext—not reusable plaintext.
- Tool tokens and connections are encrypted and bound to their registered destination.
- Client rules deny direct reads of secret-bearing credential documents.
- Admin diagnostics expose counts, state, and timing by default; content access requires a separate audited elevation path.
Retention and deletion
Retention is not one global TTL:
- Audit payload erasure preserves the row hash/link and is blocked by legal hold.
- Owner deletion schedules a declared retention window and produces a receipt.
- Agent offboarding invalidates sessions first, retires the mailbox, and removes the agent tree; owner identity and audit rows remain.
- Approvals, idempotency rows, memory diffs, artifacts, and terminal runtime records have their own scheduled cleanup rules.
- Pod deletion is a 30-day soft delete, but user-facing restore is not implemented yet.
The evidence manifest states the retained window; operators remain responsible for configuring policy that satisfies their legal obligations.