Skip to main content
Status: design. No slice has shipped. Each slice needs the reviews in the implementation plan before it lands. The people registry is the single source of truth for the people that Mira and the agent fleet know about. It stores who someone is, how to reach them on each channel, which conversations they take part in, how they relate to the workspace owner and to each other, what Mira should do when they write, what they have consented to, and what Mira remembers about them, each with its provenance. Desks, Cloudflare responders and fleet lanes read and write it through the Tuturuuu API and the ttr CLI. No machine keeps an authoritative copy.

Scope and default

  • Scope: every surface that stores or reads facts about a person for Mira or the fleet: the Mira desks (Zalo, WhatsApp, Discord), the Mira cloud responder, fleet lanes, Mastermind web and mobile, the ttr people commands, and the /api/v1/people/** and /api/v1/workspaces/{wsId}/people-registry/** APIs.
  • Tenancy: every record belongs to exactly one workspace. Each Mira tenant is one workspace, and Tuturuuu’s own Mira runs in the root workspace. Nothing resolves, joins or returns a person across workspaces, even when two workspaces hold the same phone number or Discord account.
  • Default: deny. Only the workspace’s registry owner and the managers that owner names can read or change the registry. Workspace roles, admin, creator status and default permissions never grant registry access.
  • Unknown senders: a recall for an unlinked identity returns no person and stores nothing. Capturing new people from chat is a per-workspace setting that is off by default.
  • Supplements, never replaces: Contacts, workspace membership, Fleet access grants and assistant memory keep their own rules. The registry links to them and never widens what they expose. No registry record grants Fleet access capability.
  • Exceptions: the read-only desk mirror during the migration, until cutover.

Authority

Registry owner and managers

people_registry_control holds one row per workspace: the registry owner, the capture setting, the personal-session switch, the stop flag and a generation number.
  • In the root workspace the registry owner is the Fleet access owner: the configured owner UUID that also holds a live explicit root manage_mastermind grant.
  • In a tenant workspace the registry owner is set when the tenant enables Mira, by the workspace creator after a fresh sign-in. Changing it later needs the current registry owner’s step-up confirmation.
  • people_registry_managers lists named users the owner adds, each with an optional expiry. Only the registry owner can add or remove a manager. Managers cannot delegate.
  • Managers browse and edit records: people, identity proposals and decisions, facts, rules and relationships. Owner-only actions are those that change authority, consent or retention: managers, bindings, flags, principals, consent records, merges, deletion, erasure and lifting a suppression.
This is a registry table, not a workspace_role_permissions value, so no role, wildcard or default permission can reach it.

Database execution

  • Tables live in the private schema with RLS enabled. PUBLIC, anon, authenticated and service_role have no table privileges.
  • Tables and functions are owned by people_registry_definer, a NOLOGIN role that holds privileges only on registry tables, plus EXECUTE on private.fleet_consume_registry_event, private.fleet_list_user_channel_identities and private.fleet_is_owner.
  • Every function is SECURITY DEFINER with set search_path = pg_catalog, pg_temp and schema-qualified references. Each function is created, revoked from PUBLIC, anon, authenticated and service_role, and granted to service_role only, in one migration transaction.
  • The API calls functions with the service role. It passes the actor user ID from the verified session, or the principal ID from a verified request signature, and never a client-supplied ID. Each function rechecks the live manager row or principal, the control generation and the stop flag, then writes the audit event in the same transaction.
  • Every child table carries ws_id, and foreign keys are composite (ws_id, id), so a link, edge, merge target, membership or ledger row cannot point into another workspace.

Data model

A person in the registry is separate from a Contacts row. Contacts (workspace_users) are readable by every workspace member, so private facts about a person cannot live there. A registry person can link to a contact and to a Tuturuuu account, and each link is explicit and audited.

People and organisations

people_persons.kind is person or organisation, so a company, school or family group is a node in the same graph. Status is active, merged, deleting or deleted. version increases on every change to the person or anything attached to it. consent_version increases on every consent change. The owner’s own row is flagged is_owner, once per workspace.
  • contact_id references a workspace_users row in the same workspace.
  • linked_user_id references a Tuturuuu account. It comes from the existing consent-based contact account link or a verified Fleet channel identity, never from a desk’s assertion alone.

Channel identities

Channels are zalo, whatsapp, discord, email and phone.
  • Lookup hash: HMAC-SHA-256 with a per-workspace lookup key over a canonical encoding, in which each field is a 4-byte big-endian length followed by its UTF-8 bytes, of (purpose, key_version, ws_id, channel, provider_account_id, normalised_external_id). purpose is sender_lookup or conversation_lookup. It is unique per (ws_id, channel, provider_account_id, lookup_hash).
  • Normalisation: each identifier has one canonical form, so a deleted identity cannot come back under another spelling.
    • Phone numbers must carry their country code, as + or 00, and become + and digits. A national spelling is rejected rather than guessed.
    • WhatsApp phone IDs, including @s.whatsapp.net user parts, already carry the country code and are treated as phone numbers even as bare digits. Other WhatsApp IDs are lowercased.
    • Email addresses are lowercased.
    • Anything else on the phone channel is rejected.
  • Display value: the phone number or handle, encrypted with AES-256-GCM under the workspace display key, with the workspace, person, channel and provider account as associated data. The ciphertext starts with the two-byte key version, which is also authenticated. Only registry managers can read it.
  • Verification: asserted (entered by the owner or imported, with provenance), desk_observed (seen through signed ingress evidence) or code_verified (proven through Fleet access linking).
  • Link state: proposed, confirmed or rejected, with a basis (owner_statement, self_introduction, same_phone, same_name, migration, fleet_verified), who proposed and decided it, and an evidence pointer. Only confirmed identities resolve. A same_name basis can only produce a proposal.
When a person’s linked_user_id has verified Fleet channel identities, the registry shows them through private.fleet_list_user_channel_identities. That function returns only confirmed links (channel, provider account, verified time), never hashes. The API passes it the account ID from the person’s verified link and audits each read. A linked identity proves channel ownership inside this workspace only. It grants nothing in Fleet access.

Keys

Each workspace has random 256-bit key material per purpose and version, created when the registry is enabled. It is stored wrapped (AES-256-GCM) under a versioned root key named by a kid, so it cannot be derived from anything else. A wrapped key is 0x02, the 4-byte kid, the IV, the ciphertext and the tag, with the kid in the associated data. Rotating the root key re-wraps rows with a compare-and-swap and leaves hashes and ciphertexts unchanged. Deleting the wrapped material makes the workspace’s hashes and ciphertexts unrecoverable, and workspace deletion does exactly that. The purposes are sender_lookup, conversation_lookup, suppression, display and audit. Each purpose is also part of the hashed input, so sender and chat hashes can never collide.
  • Display encryption: uses the display key with a random 96-bit nonce per write, stored with the ciphertext. Every rewrite of a value gets a fresh nonce.
  • Rotation: adds a new version. Uniqueness holds per key version. Lookups try the current version and then older ones, and re-hash a matching row to the current version when the raw ID is presented. Records that are never seen again keep their old version, so a version retires only after an owner re-entry pass or after its dormant records are deleted.
  • Suppression versions: stay available to suppression checks while any token uses them. Suppression tokens have no automatic expiry.

Conversations

Mira remembers most things per chat: a group chat has its own topics, decisions, links and arrangements. people_conversations stores one row per chat, hashed like identities, with kind dm or group. people_conversation_members records which known people take part and under which identity, as seen in signed ingress evidence.

Relationships

people_relationships stores a directed edge between two persons in the same workspace. Kinds are owner, family, partner, friend, colleague, manager, report, client, vendor, member_of and other, with an optional label, confidence and provenance. member_of connects a person to an organisation.

Facts and briefs

  • Facts are typed key/value records such as preferred name, pronouns, form of address, language, timezone and role. Every edit carries base_revision. A stale revision returns a conflict with the current value.
  • Briefs summarise a person or conversation. A brief records the fact and memory IDs it cites and the consent version it was built under. A brief is built only from records usable under current consent. It is withheld and rebuilt when any cited record changes or the consent version moves.

Rules

Rules are enumerated values, never free text. Each rule has a scope (a channel default for the workspace, a conversation or a person), an optional expires_at, and provenance. A person rule overrides a conversation rule, and a conversation rule overrides the channel default. Restrictive values always win, whatever their scope: never, hold and hold_topics. An expired rule stops applying at its expiry, and the audit log records that. Mira’s desk behaviour maps to these rules. The never-silent rule is addressed_response: acknowledge_always with group_response: when_addressed_or_helpful. Quiet hours are 22:30–07:00, mode shorten, bypassed for owner and urgent. The commitment topics are hold_topics with holding_line_then_escalate. initiate is never. A test conversation gets reply_mode: never. The interim owner-group arrangement is a conversation rule owner_instructions: relay_untagged_work_requests with an expiry. WhatsApp group mentions are mention_sender: when_requested. Desks and responders act only on rules. A fact, brief or memory can never change a rule or trigger an action. Only a manager publishes a rule. Rules from imports or machine principals are proposals until a manager reviews them, and the review shows each rule’s scope and the replies, tags or escalations it would change.

Stores and bases

people_consents holds one row per subject (a person or a conversation) and store. The stores are profile (facts and briefs), memory (memories) and capture (creating identities and people from chat). Each row records:
  • state: granted, unknown, denied, revoked or expired;
  • basis: subject_given (with a provider message reference from signed evidence), owner_attested (with the owner’s written note) or imported (carrying the source’s own evidence);
  • the verified subject, the granted scope (purposes and audience), the actor and time it was recorded, and an optional expiry.
A conversation’s memory consent is recorded by the owner for that chat. Every member’s own state still applies: a member’s denied or revoked consent blocks memories about that member, even in a granted conversation.

Use matrix

Every path enforces this matrix, including derived data (briefs, embeddings, search results, snapshots, exports): The one exception is that owner-entered profile facts (preferred name, form of address, language) can be used under unknown consent, so Mira can address someone correctly. Data held under denied, revoked or expired consent is visible to managers for review, export or erasure only, and is labelled as held. Imported records start as unknown. An import carries a source grant over only when the source has verifiable evidence for the same subject, workspace, store and purpose. It then keeps that evidence and expiry. Source denials and revocations are always carried over. Imported memories with unknown consent are not written to the memory service. They wait in people_import_staging, encrypted with the workspace key and visible to managers only. They are excluded from recall, briefs, embeddings and export. The owner reviews them by subject: a grant writes them to the memory service, and a denial deletes them. Review is due within 30 days. Items still unreviewed at the deadline stay staged and are flagged, never promoted. The desk originals are kept throughout.

Memories

Store boundary

Memories live in the existing memory service, inside a separate authorisation namespace. A product filter alone does not create a boundary, so the service itself enforces it:
  • Container tags are tuturuuu.people.{wsId}.person.{personId} and tuturuuu.people.{wsId}.conversation.{conversationId}.
  • The registry calls the memory service with its own caller credential, MEMORY_PEOPLE_CALLER_SECRET. The service accepts that caller only on tuturuuu.people.* tags, and rejects every other caller on those tags.
  • The registry derives the workspace and subject on the server for every search, write, edit, merge, forget and purge.
  • Tests cover both directions: ordinary assistant memory, Meet memory, Fleet quotes and other tenants cannot read people memories, and the people caller cannot read them either. The contract and its acceptance cases are @tuturuuu/ai/memory/people-namespace; see the memory service people namespace.

Ledger and idempotency

Each memory has a people_memory_ledger row. The row is reserved as pending, with a stable memory service customId, before the write is sent. It becomes active once the service confirms the memory ID and revision. A write with an unknown outcome is reconciled by customId before any retry. A ledger row records:
  • kind: fact, preference, language, topic, decision, link, outcome or commitment, with a work status (current, open, pending, blocked, held, resolved, delivered, verified) and, for commitments, due and done times;
  • provenance taken from verified ingress evidence (channel, provider account, conversation, message ID and observed time), or labelled imported with the run and source key, or manager with the actor;
  • the writer principal or actor, and the consent version at write time;
  • state: pending, active, superseded, retained, forgotten or purged.
The idempotency key is (ws_id, channel, provider_account_id, event_namespace, provider_message_id, target_kind, target_id, kind). Two providers or accounts with the same message ID cannot collide, and one message can produce one memory of each kind per target. A replay returns the existing row. An edit with a stale revision returns a conflict.

Consolidation

Background merging is not admitted. A consolidation job may only write merge proposals for a manager to review. Applying one follows the memory service’s merge_memories rule. The replacement’s durable ID and revision are confirmed before any original is forgotten. The result lists confirmed and retained originals separately, and only retained ones are retried.

Untrusted content

Recalled facts, names, briefs, memories and source messages are untrusted data through every derivation. They are never instructions.
  • Recall for generation returns a chat-safe projection: preferred name, form of address, language and pronouns, the effective rules as enumerated values, the brief, and memories as quoted data. On a personal session, generation gets only the addressing projection described under Ingress evidence.
  • Audience: every memory and fact records its origin conversation and an audience. The default audience is the origin conversation only. Recall for conversation C returns only records whose audience includes C. Shared membership in two chats never widens the audience. A wider audience, the owner’s DM included, needs an explicit grant on that record by a manager. That grant is a record edit, not a consent change, and it never widens what the subject’s consent allows. A derived brief includes a source only when that source’s audience includes the brief’s conversation and its subject’s consent covers the use. A group record that names several people needs usable consent from every named subject. An unknown or expired state for any of them withholds the record. Owner review of records happens in the separately authorised manager flow.
  • The responder’s tools, recipients, outbound fields and sends are decided by rules and per-conversation allowlists outside the model. A model output cannot widen them.
  • Manager context, mutations and sends run in separately authorised flows. Logs, traces and telemetry carry IDs and reason codes, never content.

Deletion

Deleting a person or conversation

Deletion is a durable state machine.
  1. Fence. One transaction sets status deleting, writes suppression tokens, bumps version and consent_version, and writes a delete change event. From then on, every read path except the deletion status returns nothing. Every writer is refused, including imports, merges, consolidation, retries and in-flight requests that commit later.
  2. Purge. Memories are purged from the memory service for every ledger row, pending rows included. The subject’s containers are then listed to catch writes the service accepted before their ledger row committed. Purging removes content, summary and embedding, which goes beyond forgetting.
  3. Remove. Facts, briefs, rules, relationships, memberships, identities, staging rows and quarantine copies are deleted.
  4. Finish. The status becomes deleted only after every step is confirmed.
A failed purge leaves its row retained. It is still unreadable through normal paths, and it is reported and retried. The result always lists confirmed and retained items separately.

What remains

  • Suppression tokens: people_suppressions keeps, for each deleted identity, an HMAC of its lookup hash under the workspace suppression key, plus the deletion time. Ingress recomputes the lookup hash from the raw ID and derives the token to check it. It holds no name, content or raw identifier. It is linkable only to someone who presents the same raw identifier. It is used only to stop capture, imports and replays from re-creating the person, it is readable only by fence checks, and lifting it is an audited owner action. Tokens last until the owner lifts them or the workspace is deleted.
  • Audit events keep opaque UUIDs and reason codes, never content, for 400 days.
  • Database backups follow the hosting provider’s point-in-time recovery window. Every deletion and suppression is also appended to a deletion ledger kept outside the database, in an append-only R2 object per workspace, so it survives a restored snapshot. After a restore, the registry stays closed until that ledger has been replayed: deletions are re-run and suppressions re-applied, while erasures that dropped their token re-run without one. Slice 6 tests this restore path before it ships.
The owner-facing delete dialog states what remains. An erasure that also drops the suppression token is available and warns that the person could then be re-created automatically.

Forgetting one memory

The ledger row becomes forgotten only after the memory service confirms the forget. Correcting a memory is a revision-checked edit.

Dedup and merge

Duplicate detection runs within one workspace. It matches on lookup hashes, the linked contact and the linked account, then on normalised label similarity, which only produces a proposal. A merge is owner-only, because it rewrites consent and moves suppressions, and it cannot cross workspaces:
  • Consent: the result takes the most restrictive state per store. Two conflicting grants with different scopes block the merge until the owner picks one.
  • Memories move by re-writing each one into the surviving person’s container under the merge rule above. The source container is purged only after every copy is confirmed.
  • Identities, facts, rules, relationships, memberships and suppressions move with their provenance. Conflicting facts or rules keep both until a manager chooses.
  • The merged person becomes merged, with merged_into set. Its old ID resolves to the survivor for managers only.

Machine access

Principals

people_principals holds machine principals. Each is bound to one workspace, one kind and one workload: There are no bearer tokens. Each principal registers one or two Ed25519 public keys. Every request carries a signature over the method, path, body hash, audience (people-registry), principal ID, timestamp and a nonce. The server rejects requests more than 30 seconds in the future, requests older than 5 minutes, and repeated nonces. That proof binds the request to the key holder, so a copied header is useless. The private key lives in the E2EE secrets vault once it is available, and in the deployment secret store until then. It never lives in a repository or a local file. Header values are redacted from logs.
  • Only the registry owner can register a principal, after a fresh sign-in. Tenants receive a responder principal when they enable Mira. Disabling Mira or deleting the workspace revokes all of the tenant’s principals.
  • Every call checks the principal’s live status, generation and kind.
  • Each principal has per-minute limits on recalls and writes. Lookups are audited by principal and provider account.
  • No principal covers more than one workspace.

Ingress evidence

A principal signature proves which workload is calling. It does not prove who sent a message. So recall, observe and memory writes for a conversation also need ingress evidence. That reuses the Fleet access event contract in apps/web/src/lib/fleet/desk-event.ts:
  • The trusted ingress signs the channel, provider account, sender, conversation, conversation type, event ID, operation and input hash.
  • Registry operations are registry.recall and registry.write. Observation travels inside the write bundle and has no operation of its own. A fixed per-operation map allows private_1_to_1 or group for registry operations, and private_1_to_1 only for Fleet operations. The verifier rejects any other pair before touching the database.
  • The server derives the person and conversation from the evidence. A request field that disagrees with the evidence is refused.
  • One event, one bundle: a provider event admits at most one recall and one write bundle. The bundle is a single request to POST /api/v1/people/events that carries every observation and memory derived from that event, at most one per kind and target. It commits atomically: all items commit or none do. Recall and write consume the event through private.fleet_consume_registry_event, a narrow Fleet-owned wrapper over private.fleet_provider_events, inside the operation’s transaction:
    • There is one record per (channel, provider account, event ID), with three slots: fleet, registry_recall and registry_write.
    • fleet and registry_write exclude each other. Whichever consumes first wins, so one provider event never serves both a Fleet action and a registry write.
    • registry_recall can coexist with either.
    • Every attempt, across all slots and redeliveries, increments one durable counter per event. Once the counter passes five, every slot is refused.
    • The proof is verified before anything is consumed. A refusal returns rather than raising, so each counted attempt commits.
    • The Fleet retention purge resets an event’s record. After a purge, replay safety depends on every ingress refusing provider events older than the 5-minute evidence window, including redeliveries, and never re-signing a fresh proof for an expired event.
  • Retries: a retry of the same bundle with the same input hash returns the original receipt. An unknown outcome is resolved by reading that receipt by event, never by sending a different bundle. A different bundle for a consumed event is refused.
  • Live binding: the workspace-to-account binding is checked when the ingress signs and again when the server verifies. Reassigning an account invalidates every unconsumed event signed for the old binding.
  • Ingress verifies group membership and the sender with the provider itself.
  • Personal sessions: on a personal account (an internal Zalo or WhatsApp login whose connector signs its own envelopes), a compromised connector could vouch for any sender. Evidence from such a session is not Fleet actor authority, and it gets only the addressing projection:
    • Fields: the owner-entered preferred_name, form_of_address and language facts, and the speech rules addressed_response, group_response, reply_mode and mention_sender. Routing and schedule rules (quiet hours and their bypass, hold topics, hold action, escalate, owner instructions, initiate) are never returned. Neither are pronouns, timezone, role, relationships, labels, briefs, memories, internal IDs or versions. When the desk needs a delivery decision, the server returns one computed for this event (send, shorten, hold or draft), never the policy behind it.
    • Eligibility: only identities the owner confirmed (basis owner_statement or fleet_verified), with consent and audience applied. Under denied, revoked or expired profile consent, the answer is the miss body: no facts and no person speech rules.
    • Uniform answer: a hit, a miss, the switch being off, a denial, a suppression and a deletion all return the same response shape. A miss returns the channel-default speech rules and no facts. Off, denied, suppressed and deleted outcomes all return that miss body. Writes get one refusal code. Response timing is padded so outcomes are indistinguishable. A semantic query is not accepted. Each personal session has a low recall cap, applied before any lookup. Each inbound event gets one recall, recorded in people_personal_recalls after the freshness check passes. Those rows are kept for at least the 5-minute evidence window, so a replay inside the window is refused.
    • No side effects: registry.write (and so observation, capture and membership) is refused on the session class before any person, consent, capture, suppression or membership lookup. Neither a personal recall nor that refusal calls fleet_consume_registry_event, increments the event’s attempt counter, emits a change event or bumps a version. It takes no if_version, never returns not_modified, and uses a cache namespace that full-recall callers never read or write. A personal fill is served only for the event whose live recall produced it, and never reused.
    • Switch: personal_sessions_enabled on the control row is false by default, and a missing row counts as false. Only the owner changes it, and a change bumps the generation. Every personal recall rechecks it together with the stop flag. Turning it off ends the projection on the next request after the change commits, and the check drops any cached personal fills.
    • Audit: an event records the principal, channel, binding, purpose and reason. A confirmed hit also stores the identity UUID; any other outcome stores an HMAC under the audit key. Every outcome writes the same shape, with no raw external ID, phone number, session secret, name or rule value.
    Full recall on personal accounts needs a second, independent attestation of the sender, which waits on a host review.
  • Signers and bindings: Fleet operations accept only the registered Fleet desks. Registry operations also accept the Mira ingress signer, whose versioned public keys come from MIRA_INGRESS_PUBLIC_KEYS. For every registry operation, the server checks that the signed (channel, provider_account_id) is bound to the calling principal’s workspace in people_channel_bindings. That table is unique on (channel, provider_account_id), so one provider account serves at most one workspace. Only the registry owner adds or removes bindings, and removing one stops every registry operation for that account at once.

API

Service routes

Responder routes require a principal signature and ingress evidence. fleet recall requires only the signature and returns the reduced projection.
  • Request signing: every service route request carries x-people-principal, x-people-key-id, x-people-timestamp (milliseconds), x-people-nonce (16 to 32 random bytes, base64url) and x-people-signature. The signature is Ed25519 over people-registry-request-v1 and a newline, followed by the JSON array ["people-registry", METHOD, path and query, body SHA-256 hex, principal ID, key ID, timestamp, nonce]. A request that carries an Authorization header is refused.
  • Ingress evidence headers: x-people-event-key-id selects a key from MIRA_INGRESS_PUBLIC_KEYS, x-people-event is the base64url JSON proof {version: 1, kid, channel, account, sender, conversation, conversationType, eventId, operation, inputSha256, issuedAt}, and x-people-event-signature is Ed25519 over people-registry-event-v1. and the proof. The event hash is the SHA-256 of eventId, the same derivation Fleet uses, so both consume one provider event record.
  • POST /api/v1/people/recall — body {if_version?}. The person and conversation come from the evidence. The response is {person_id | null, conversation_id | null, versions, etag, snapshot | not_modified, memories}. snapshot is the chat-safe projection: the person’s label (granted consent only), consent state, facts under the consent matrix and their audience, the relationship to the owner, briefs, the conversation kind, and every rule that applies to the channel, conversation and person. The owner-entered addressing facts apply wherever the person is recalled. Every other fact needs the resolved conversation to match its audience: its origin, a listed conversation, or one the person takes part in (the direct message with this sender, or a group with a membership row). A brief applies only under its subject’s current consent version, while every record it cites still exists and every person it can describe (the conversation’s members and the subjects of its cited records) keeps a granted profile. Rules apply whatever the consent state, so a restrictive rule is never dropped. etag hashes the snapshot and versions; sending it as if_version returns not_modified when nothing changed, rule expiry included. Each provider event serves one recall. A second recall for the same event returns event_consumed, and the responder answers with the workspace default. Semantic recall (query, k up to 20) belongs to the memory service namespace (slice 3). This route returns an empty memories array and refuses unknown fields. A personal session gets none of this: its recall takes no query or if_version, and returns only the uniform addressing projection and delivery decision, with no IDs, versions, memories or not_modified.
  • Account binding before consumption: the database checks that the signed (channel, account) is bound to the principal’s workspace and is not a Fleet desk account before it consumes the provider event. A refused event takes no slot, so a tenant can never spend the Fleet slot of an account it does not own.
  • POST /api/v1/people/events — the event’s write bundle, body {items: [...]}. The route accepts one item kind:
    • observe_sender (with an optional label) records that a confirmed person spoke in the conversation named by the evidence. It creates the conversation under the current lookup key when it is new, records the membership, and marks an asserted identity as desk_observed. It needs a confirmed sender identity and a profile consent that is not denied, revoked or expired.
    • For an unknown sender, a labelled observe_sender proposes a new person when capture is on and the owner granted capture consent for that conversation. The server derives the capture material: a new person ID, the sender’s current lookup hash, suppression tokens for every lookup and suppression key version, and the encrypted display value. The proposal is a person with every store at unknown, a proposed identity marked desk_observed with evidence desk_capture, and a membership. A suppressed sender is refused, and a sender with any existing identity (proposed, confirmed or rejected) is a duplicate. A proposal is never recalled until a manager confirms it. Proposals for one sender are serialised by a transaction lock on its lookup hash.
    memories items ({text, kind, status?, due_at?, target: person | conversation}, through the memory service namespace in slice 3) are not accepted by this route; unknown item kinds and fields are refused. The response is one receipt per item, created, proposed or duplicate, or the whole bundle is refused with one reason: unknown_sender, consent_required, suppressed, deleting, scope_denied or event_consumed. Every check runs before any write. The outcome, accepted or refused, is stored as a receipt keyed by the event, so a retry with the same body returns the original receipt marked replayed, and a different body for a consumed event is refused. A receipt outlives the Fleet purge of its provider event, and receipts have no retention job yet. A memory edit with a stale revision is a manager action and returns revision_conflict.
  • GET /api/v1/people/changes?after={cursor}&limit={1-500} — drain principals only. The response is {events, next}. The cursor is a per-workspace sequence allocated under a row lock held until commit, so a cursor never passes an uncommitted event and reveals nothing about other workspaces.

Manager routes

/api/v1/workspaces/{wsId}/people-registry/ serves persons, persons/{id}, conversations, facts, rules, relationships, identities, consents, memories, merge, duplicates, principals, imports and managers. They accept the platform web session, the Mastermind app-session audience and the CLI session. Mutations take base_revision wherever the record has a revision. Responses send Cache-Control: private, no-store. Clients live in @tuturuuu/internal-api as people-registry.ts.

Caching and invalidation

Responders may cache snapshot content in a Durable Object, but serving it is always gated by a live check. This section describes full recall. Personal sessions never use if_version or not_modified. Their fills live in a separate namespace that full-recall callers never read or write, and the switch check drops them.
  • Every reply starts with recall and if_version. The server checks the principal, evidence, status, consent and suppression live, and returns either not_modified or a fresh snapshot. When the check fails or the server is unreachable, the responder serves no protected data. It replies with the workspace’s default behaviour, without person context.
  • Outbound sends recheck the effective rules for the conversation at send time.
  • Cache fills carry version. A fill older than the cached version or a deletion tombstone is dropped, so a stale refresh cannot repopulate a purged entry.
Change events help caches drop entries early. Each event is written in the same transaction as the mutation:
  • Fields: {event_id, workspace_id, person_id | conversation_id, version, consent_version, kind}, where kind is update, revoke or delete. event_id is monotonic per workspace.
  • A Cloudflare drain Worker reads the events with a workspace-bound cursor. It acknowledges a batch only after the Queue accepts it.
  • Consumers apply events idempotently, keeping the highest version they have seen. Failed deliveries go to a dead-letter queue and are retried.
  • Lag is measured and alerted.
  • The drain sees invalidation metadata only.
The latency target for recall with not_modified is measured in slice 2. Semantic recall stays off the first-token path.

Mastermind

The registry appears inside the single Mastermind shell on web and in the mobile Mastermind module, using the shared navigation and design.
  • Discover: search by name, channel, conversation or relationship. Filter by relationship kind, channel, consent state and recent activity. A relationship graph centres on the owner.
  • Observe: each person and conversation has a timeline of what Mira and the fleet read and wrote, built from audit events and ledger rows. Each item shows its channel, conversation, principal, purpose and provenance. Briefs show their cited records. Held and staged data is labelled.
  • Tune: edit facts with revision checks; correct or forget memories; set rules with optional expiry; record consent with its basis; review staged imports and merge proposals; merge duplicates; delete with a suppression token or full erasure. Destructive actions use the shared confirmation dialog and report confirmed and retained items.
  • Web: apps/mastermind/src/routes/$locale/people.tsx, with code under apps/mastermind/src/people/, one owner-scoped shell navigation entry and the shell’s PageHeader. Reads and writes go through server functions and a people client that forwards the verified Mastermind app session to the manager routes. The client refuses redirects, applies a timeout and validates response schemas. Mastermind admission stays owner-only.
  • Mobile: a pushed route /mastermind/people under features/mastermind/people/, opened from a Today navbar action (PeopleTodayAction, registered in fleet_today_page.dart the way Fleet access registers its action). It adds no dock tab and calls the same manager routes.
All strings ship in English and Vietnamese.

CLI

ttr people commands use the CLI session and the manager routes: The CLI implements ls, search, show, status, add, link, confirm / reject, relate, fact set / fact rm, person-scope rules set / rules rm, consent set and flags (in packages/sdk/src/cli/people.ts). The other rows need their manager routes first. Routes that require a fresh tuturuuu.com sign-in, such as enabling the registry and registering principals, refuse the CLI session. Every command takes --workspace and --json. Raw identifiers such as phone numbers or provider IDs are never command-line arguments. ttr people link reads the external ID from a hidden prompt or from standard input, so it never reaches shell history or process listings. Command output, errors and diagnostics show only the encrypted display value’s masked form.

Migration plan

Mira’s desks keep a person registry, profiles, per-chat memory with nightly consolidation, commitments and per-chat rules in local files on the desk host. The migration moves them into the registry without losing data, and keeps the originals until the copy is confirmed.

Store mapping

These stores stay out of the registry:
  • Operational state (replay ledgers, send ledgers, queues, dedupe caches, reply timings, wake spools) belongs to the Mira runtime and moves with it.
  • Encrypted chat history has its own keys. It needs its own consent decision and vault-held keys before it moves anywhere.
  • Fleet agent memory indexes agent notes, not people, and stays separate.

Steps

  1. Inventory: export schemas, field names, counts and writer processes only. No personal content leaves the host for review.
  2. Plan: ttr people import plan maps each store to registry records and prints counts per record type, unmapped fields and detected duplicates. It writes nothing.
  3. Run: ttr people import run sends records in batches under an import principal. Each record has a stable source key, a hash of the store, the file and the record ID, so a rerun is idempotent. Each record gets a receipt: created, duplicate, staged, conflict or failed. The run records a high-water mark per store.
  4. Freeze and delta: every desk writer of the migrated stores is fenced, covering edits and deletes as well as appends, and the run imports everything past the high-water mark. Messages that arrive during the freeze are not buffered in memory. The provider event stream is checkpointed at the freeze, and after the switch the desk replays it from that checkpoint through the API. Where a provider cannot replay, the desk writes the event IDs to a durable journal. That journal holds IDs only, no content, and the desk re-fetches the content from the provider when it replays.
  5. Verify: ttr people import verify reads every record back through the manager API, duplicates included. It checks the destination ID, revision, workspace, consent state, provenance and content checksum against the source. Conflicts must be resolved first. A store is confirmed only when every record verifies.
  6. Switch: desks read and write only through the API. The API becomes the only writer. Desks keep only ephemeral caches. A write that cannot land after bounded retries is reported, never silently dropped. The local registry stays as a read-only routing mirror until cutover is accepted. Rollback has been exercised before the switch. It returns desks to the local stores, with every registry write made after the switch exported back to them, and it keeps registry deletions and suppressions in force.
  7. Retire: confirmed stores and their backup copies move to a quarantine directory readable only by the desk’s own user. Deleting a person in the registry also purges their quarantined records, and suppressions stop a replayed import. After 14 days and the owner’s confirmation, ttr people import retire re-verifies the exact manifest against the quarantine and the registry, then deletes the quarantined files. Staged items the owner has denied are deleted from both the registry and the quarantine. Items still unreviewed keep their originals in quarantine until they are reviewed.
Nightly consolidation on the desk host becomes the proposal-only job described in Consolidation. It runs on Cloudflare.

Implementation plan

Acceptance gates

A slice ships only when its gates pass:
  • Slice 1:
    • One-time, atomic bootstrap of each workspace’s registry.
    • Live checks of the root owner and manager expiry.
    • Authority, consent and retention mutations restricted to the owner, with tests that an active manager can edit records but cannot perform them.
    • Serialised generations.
    • Proof that people_registry_definer has no Fleet table privileges and reaches Fleet only through fleet_consume_registry_event, fleet_list_user_channel_identities and fleet_is_owner.
  • Slice 2:
    • Personal-session tests:
      • no memories, briefs, pronouns, routing or schedule rules, IDs or versions;
      • a delivery decision without policy;
      • identical bodies and padded timing for hit, miss, off, denied, suppressed and deleted;
      • the cap applied before lookup, and one recall per event, recorded in people_personal_recalls after the freshness check;
      • no observation, capture or write, no replay wrapper call, no attempt increment, no change event, and no if_version or not_modified;
      • the audit shape on every outcome;
      • the switch false by default and when the row is missing, owner-only, bumping the generation, rechecked with the stop flag, and ending the projection on the next request after the change commits;
      • a personal fill never reused for another event, and recall rows kept for at least the 5-minute evidence window;
      • no read or fill of the full-recall cache, and full-recall callers never reading the personal namespace.
    • A live account binding checked at signing and at verification.
    • Tests for evidence mismatches and account reassignment.
    • Single use of a provider event across Fleet and the registry: fleet and registry_write exclude each other, and registry_recall coexists with either. Personal-session recalls and refusals call no replay wrapper and leave the attempt counter unchanged.
    • A verifier test that stale provider events and redeliveries outside the evidence window are refused before any slot is consumed.
    • Canonical signature bytes, covering the exact query and the key ID.
    • Nonce admission shared across replicas for the whole acceptance window.
    • Key revocation and rollover under retries.
    • Rate limits and replay state keyed to the verified principal.
    • Revalidation bound to the principal’s projection, conversation, subject, consent, audience and expiry.
    • A recheck of permission, membership, consent and deletion immediately before sending, with stale drafts discarded.
    • Tests that hostile recalled content cannot enable actions, change rules, or reach privileged flows, briefs, audit or telemetry.
    • Fleet recall restricted to people on the owner’s list and filtered by consent.
  • Slice 3:
    • Every read, search, write, edit, forget and purge path tested under both caller classes and across tenants.
    • A fenced, resumable merge that intersects grants or takes fresh evidence.
    • Completed deletion verified against writes the service had already accepted.
    • Memory routes stay disabled until slice 3 passes.
  • Slice 6:
    • The R2 deletion ledger, with its restore path tested before the registry reopens.
    • A commit-safe cursor.
    • Idempotent recovery after Queue acceptance, partial delivery and gaps in outbox retention.
  • Slice 7:
    • Rollback exercised.
    • Durable replay journal.
    • Every writer fenced.
    • Each staged item given an explicit disposition before retirement.

Configuration

Regression coverage

Each slice links its coverage here when it lands.
  • Slice 1 (database): people-registry.sql covers:
    • privileges and ownership, and the Fleet wrappers;
    • replay slots and the attempt cap;
    • one-time bootstrap with rollback;
    • owner and manager authority, live root ownership, transfer, revocation and manager expiry;
    • bindings;
    • revision conflicts, rule values and consent bases;
    • suppression coverage;
    • deletion fences, hidden deleting people and tombstones;
    • append-only audit.
    people-registry-replay-race.sql races two sessions for a write-first event, a purge then redelivery, and a record that vanishes between conflict and update.
  • Slice 2, manager routes:
    • The route tests cover session-only actors, strict bodies, refusal mapping, wrapped keys staying server-side, identities stored as hashes, tokens and bound ciphertext, and Fleet desk accounts refused as bindings.
    • The key tests cover wrapping, lookup separation, suppression tokens and display binding.
  • Slice 2b, machine routes:
    • people-registry-recall.sql covers the consent matrix in recall, fact audience in DMs and groups, rule expiry and the etag, group briefs withheld when a member denies consent, one recall per event, unbound, cross-tenant and Fleet desk accounts refused without taking a slot, group recall never touching the Fleet slot or Fleet identities, principal kind and tenant checks, lookup keys limited to responders, and the gapless per-workspace change cursor.
    • The request signature and ingress evidence tests cover replay onto another body, path or method, foreign keys, bearer refusal, Fleet operations and domains, and the evidence window.
    • people-registry-writes.sql covers observation, membership and desk-observed verification, replayed and conflicting receipts, the registry write slot excluding Fleet, refused bundles writing nothing, and unbound, desk and cross-tenant refusals.
    • people-registry-capture.sql covers capture off, conversation capture consent, proposals, duplicates for proposed and rejected senders, suppression, proposals staying out of recall, and malformed capture material refused before the event is consumed.
    • The route tests cover hashed lookups (raw sender IDs never reach the database), not_modified, refusal mapping and the change feed cursor.