Conversations Graph — Recovery, Membership and Privacy
This is the second half of the developer reference for the Conversations graph in src/core/. The first half, Conversations Graph — Custody, Writes and Transfer, explains how records are written, witnessed, replicated and transferred. This page covers the other direction: recovering pending writes, changing or shrinking membership, recovering owner control, retiring old roles, and erasure.
It describes what the shipped code does, taken from module header comments and call sites. It does not add new guarantees. Spec: docs/specs/conversation-effort-hierarchy-v3.md (section 7.2, “installed membership recovery” and the recovery ceremony).
Scope and defaults
Section titled “Scope and defaults”Everything here runs only when graph storage is running — see “Shipped default and how it turns on” on the custody page. In short: the read and corrections switches under multiMachine.conversationGraph are off by default; an external witness needs explicit storage.enabled: true plus witness, membership and owner key settings; the owned-machine default (ConversationGraphDefault) mints its first root only on an owner-admitted request. None of the recovery flows below runs on an agent that never created a graph.
The witness here is the Conversations graph witness (GraphWitnessService and the GraphWitness* modules). It is unrelated to Threadline identity and trust (Threadline internals); no module on this page reads or grants Threadline trust, and nothing here adds a standing permission for any peer.
Membership
Section titled “Membership”A membership is an owner-signed epoch: the list of enrolled machine identities (signing and sealing keys), the writer, the witness id and failure-domain label, and an optional custody profile. Plain shapes live in GraphMembershipTypes; verification (verifyMembershipEpoch) and canonical hashing live in GraphWitnessTypes.
- In owned-machine mode,
ownedGraphInstalledRosterinOwnedGraphCustodysupplies active, unrevoked enrolled identities and their keys as candidates. The graph membership is the owner-signed epoch, not the whole candidate roster. At first creation,multiMachine.conversationGraph.genesisMembersselects which paired machines sign (all paired machines if it is absent); it has no effect afterwards. A machine paired later stays outside the signed graph roster until an owner-signed join. A roster sent in a request body is never authority. - Adding a machine is
GraphCustodyJoinIntent: exactly one new row, nothing else changed. Removing a member is a separate, much stricter path (member loss, below). ConversationGraphCustodyAuthority(verifyGraphCustodyAuthority) requires a completed activation for historical witness roles, not a proposed owner-signed roster; the original acceptance membership stays immutable.GraphCustodyProfileAuthorityholds STAGING as a durable negative write fence during a change. A timeout never unlocks writes. Its stated limit applies here too: it cannot detect rollback of all authority copies.GraphCustodyPeerFrontierlets fresh observations from other members withhold private serving while their state is behind; it never installs a membership.ConversationGraphReplicationLimitsmakes a membership transition dominate every publication rank of the previous membership; exhausting the epoch space holds graph admission rather than wrapping a counter.
Recovering pending writes
Section titled “Recovering pending writes”A write can be interrupted between witness prepare (“Saved”) and the all-member commit described under ConversationGraphCommitCoordinator on the custody page. Recovery rebuilds and revalidates from what was actually stored, never from values supplied over the wire.
GraphWitnessRecoveryCoordinator(revalidate(eventId)) re-checks one pending event against the current verified membership, the current fenced lease held by this machine, the original record read fromConversationGraphReplication, and the certified union of earlier events. It returnsheldwith a reason when anything is missing — for example a certified dependency gap, ambiguous header creator, or stale heads forset-primary-placement/set-front-door. Terminal or erased operations are not revived.ConversationGraphSourceRecovery(reconstructGraphSourceRecord) reconstructs the original accepted control from the sealed source bundle; it never mints a new owner or producer receipt. The caller must zero the decrypted buffers. The wire encoding is shared withConversationGraphSourceEnvelope.ConversationGraphSourceObservationRecoverylets the current native writer revalidate an earlier source observation (seeConversationGraphSourceInventoryon the custody page). Historical producer membership stays frozen.ConversationGraphRecoveryManifestaccumulates a metadata-only manifest of source entries (buildGraphRecoverySourceManifest); source authority is checked separately before any receipt.GraphWitnessTypescaps the manifest size (GRAPH_RECOVERY_MAX_MANIFEST_ENTRIES).ConversationGraphNativeTailandGraphVerifiedNativeTailBarrierrequire every installed member to close its pre-witness tail so recovery starts from one exact prefix.ConversationGraphIntakekeeps its reservations across restarts, so a retried owner write after a crash replays instead of duplicating.
What does not survive a restart: GraphOwnedControlFrameCache frames (callers resubmit), the GraphDurableFileMemo flush memo (it simply flushes again), and the process-local deny cache in ConversationGraphLocalErasure (see erasure below).
Transfer on the recovery side
Section titled “Transfer on the recovery side”Transfer staging is described on the custody page (ConversationGraphReplicationTransfer, ConversationGraphTransferCustody, GraphPreparedTransferEnvelopes, ConversationGraphMaterializationContexts). On the recovery side:
ConversationGraphHistoricalMaterializationaccepts a historical terminal source transfer only with the owner’s exact recovery plan plus every new member’s durable state-transfer receipt. It never rewrites the original certificate or invents an old-epoch receipt.GraphWitnessBootstrapStreamandGraphNativeSourceUploadupload held source into a new witness role’s staging engine one row at a time; finishing still needs the full source-recovery verifier, and the server must recheck the owner action between stage and finish.GraphCustodyStagedRoleopens staged and activated owned roles;GraphCustodyActivationPinStorerecords each member’s activation import. The activation authority needs the complete verified pin set; the store never unlocks a profile on its own.GraphTransferPublicControlandGraphTransferPrivateViewsinspect controls and clean up parsed private views without granting anything.GraphSourceStatusPolltolerates a peer that is briefly unreachable during its final step (up to 120 s).
Permanent member loss
Section titled “Permanent member loss”Removing a machine that is gone for good is a separate, owner-confirmed protocol. It never relaxes the normal “every old member holds and retires” path; it adds a narrower one.
GraphOwnerMemberLoss— verifies the owner’s consent payload. Its header is explicit: there is deliberately no exported mint or permission factory while the owner service and native-authority integration are not implemented and reviewed. Consent is historical proof, not activation authority.GraphMemberLossNativeProof— verifies historical loss intent and native revocation receipts; neither admits a new human action.GraphNativeMemberLossStore(GraphNativeMemberLossProgress) — native lifecycle evidence recorded after owner administration. No method revokes a machine.GraphMemberLossActivation— the separate permanent-loss activation, including a fresh same-epoch holding proof presented at commit (mintGraphMemberLossLeaseProof).GraphMemberLossPlanRevision— a newly signed, negative-only plan revision; it never changes the original creation, consent, role key or transfer namespace.GraphMemberLossHeldPreflight— requires a real held physical source capability. The first adapter supports exactly one surviving installed member; more survivors need equally verified transport.GraphMemberLossInventoryLimits— a 64 MiB local held-snapshot budget (GRAPH_MEMBER_LOSS_MAX_SNAPSHOT_BYTES). Refusal leaves the original custody intact; larger inventories need streaming.GraphMemberLossNegativeCustodyandGraphMemberLossNegativeTransfer— after an explicit loss, pending writes can only be cancelled. A missing Saved proof is never repaired by inventing a witness preparation.GraphMemberLossOwnedRole,GraphMemberLossPinStore,GraphMemberLossSourceImportandGraphMemberLossPublicMetadata— the owned loss-role factory, survivor import pins, wire projection of retained source proofs, and read-only public-byte classification.createMemberLossStagedGraphCustodyTransportinGraphCustodyTransportkeeps the loss role’s transport negative-only.
Owner control recovery
Section titled “Owner control recovery”GraphOwnerRecoveryseals owner-control recovery material only to installed member keys (createGraphOwnerRecoveryEnvelope,recoverGraphOwnerControl). Decryption needs the exact owner root and the member’s own decryption capability, and grants no HTTP admission. If material is missing, no root is invented.GraphOwnerRecoveryStorekeeps those detached encrypted copies. A member signs its receipt (verifyGraphOwnerRecoveryReceipt) only after fsync, reload and self-decryption.ConversationGraphOwnerPolicyandDashboardPinGenerationdecide which dashboard PIN generation is current. Revoking a PIN moves the generation head; replaying an older config does not restore the old one.
Limit: recovery copies live on installed members. If every member is lost, these modules do not provide an outside copy.
Retiring old roles
Section titled “Retiring old roles”GraphCustodyRetiredRoles— current verified negative authority purges every discovered custody role (GraphCustodyRolePurgeDebttracks what is left). No historical signing key is loaded.GraphCustodyRetiredRolesInventory— read-only, bounded disk inventory of role files; claims are not authority until bound to owner-pinned lineage.GraphPreparedCustodyStageV2/GraphCustodyProfileStageV2— paged negative-stage evidence; not retirement or activation by itself.GraphFrozenPhysicalInventoryandGraphPublicMetadataPagesgive these readers bounded, hash-checked data with no authority attached.
Erasure and privacy
Section titled “Erasure and privacy”What the graph keeps is designed to be erasable: titles, previews, transcripts and keys live only in encrypted bundles and per-record envelopes, while signed controls hold opaque hashes (see GraphWitnessControl and GraphWitnessCrypto on the custody page). Effort header titles in EffortHeaderStore resolve through that custody and come back null once it is erased. Erasure works in layers:
- Local fence first.
ConversationGraphLocalErasure(ConversationGraphLocalErasureFence) records owner-local suppression before any network work. It is a deny fence, not a claim that anyone else erased anything. Its in-process deny cache is never cleared after a refresh, but its comment notes it is not evidence that an unsynced deny reached disk. - Durable negative authority.
ConversationGraphErasureAuthorityStorekeeps verified erasure authority. Pins alone never authorize deletion. - Protocol.
GraphErasureProtocoldefines the signed ingress, the fleet plan and per-member receipts, with scopesgraph-source,graph-intake,graph-transferandgraph-source-cache. It carries no title, transcript, content key, owner credential or source bytes. - Fleet coordination.
GraphFleetErasureCoordinatorpurges locally, then forwards anerase-purgeto every other member. A sleeping member that cannot be reached stays a named pending copy rather than a silent success. Its scope is narrow: it does not erase original platform or legacy transcripts, or phone downloads — only graph-captured application custody. - Witness storage.
GraphErasureWitnessLedgerrecords deletion debt in the same transaction inside the witness database;GraphWitnessErasureStorage(enforceGraphWitnessTargetErasure,purgeGraphWitnessStagedBundle, …) is the data-only purge engine, run only after negative authority is established. - Intake.
ConversationGraphIntakereportsGraphIntakeSourceErasedfor reservations whose source was erased.
Honest limits: an erasure acknowledgement means the member’s graph-managed copy was purged by this code. It does not prove that filesystem blocks were overwritten, that backups or snapshots outside Instar were touched, or that a member that never comes back has deleted anything.
Related app-conversation recovery
Section titled “Related app-conversation recovery”AppConversationService handles boot recovery for native app conversations (re-deriving aliases, recovering interrupted requests, answering 503 owner-unavailable after persisting). AppConversationStore deletes by appending a tombstone event, which AppConversationsReplicatedStore replicates to every machine; ConversationPins pins replicate the same way. These are separate from graph erasure: purging graph custody does not rewrite the app conversation JSONL, and a tombstone in the app store is not a graph erasure.
Where to go next
Section titled “Where to go next”- Conversations Graph — Custody, Writes and Transfer
- Machine identity recovery — the enrolled identities a membership is built from.
- Durable Conversation Identity —
ConversationRegistry, which the source sweep reads.