Membership & Leave Operations

Forward-only invariant — load-bearing

The apply-time membership check is a function of two things only: the signer's identity and the governance-DAG position the signer signed against. It is not a function of the receiver's current local state. This is the forward-only property: a write authored at governance position P stays valid forever, even if the receiver has since applied a MemberRemoved for the signer at a later position P' in its local DAG.

Why this matters

Without forward-only, two peers receiving the same set of ops in different orders would end up with different state:

• Peer A receives MemberRemoved first, then the pre-removal delta. If "is the signer currently a member?" gates the apply, the delta is rejected.
• Peer B receives the delta first, then MemberRemoved. The delta applies; the later removal doesn't retroactively undo it.

That divergence cascades: any subsequent delta that reads the (different) state diverges further, context root hashes drift apart, and the network has no honest convergence point. Forward-only removes the receive-order dependence: pre-removal writes always apply on every peer, regardless of when the receiver learns about the removal.

How it's implemented

Every state delta carries a governance_position field that names the governance-DAG heads the author observed at sign time. On receive, the apply path calls membership_status_at(signer, delta.governance_position) — which walks the ancestry of the signed heads and replays the membership state machine. The walk visits only the prefix that was already final when the delta was signed; anything causally after the signed cut (including a later MemberRemoved for this signer) is invisible to the walk and cannot retroactively invalidate the delta.

Resolving the current governance cut — ScopeProjections::namespace_current_heads

Current-state membership reads (as opposed to historical signed-position checks) need a "now" frontier: the set of parent hashes that represents the namespace's current DAG head. The static method ScopeProjections::namespace_current_heads provides this:

1. Resolves the supplied ContextGroupId to its owning namespace by walking the parent chain.
2. Reads that namespace's DAG head record from the governance store.
3. Returns the parent hashes of that head — the cut argument passed to membership_status_at (or AclView::is_member_at_cut) for a current-state query.

None return cases. The method returns None when the group cannot be resolved to a namespace (e.g. the group does not exist in the local store) or when the head record itself is unreadable. Callers must fall back to the live membership store (check_group_membership_path) in both cases rather than treating None as an empty cut — an empty cut would falsely deny all access.

Where this can break

Two classes of change would silently re-introduce the divergence described above:

• Calling the check with the wrong position. Any caller of membership_status_at that passes the receiver's current state (or any post-cut heuristic) instead of the signed delta position breaks forward-only. The three production call sites — gossip-receive, governance-pending drain, and snapshot-sync replay — each carry inline comments naming this contract; reviewers should flag any new caller that doesn't pass delta.governance_position verbatim.
• Changing the prefix walk to visit descendants. A "performance optimization" that has the BFS catch up to local heads after visiting the signed heads would observe ops the signer hadn't signed against, including later MemberRemoved ops. The forward-only contract is documented on the public membership_status_at function; the internal BFS in prefix_walk_membership implements it, and the prefix_walk_forward_only_* regression tests pin the boundary.

Scope

Forward-only applies to MemberRemoved and MemberLeft — operations that revoke authorship. It does not apply to role demotions (MemberRoleSet transitioning a Member to ReadOnly): those are enforced against current state at the receive path, separately from the cross-DAG check, because a member who was demoted retains a different relationship to their pre-demotion writes than a member who was fully removed. See is_read_only_for_context for the live-state role gate.

leave_context — local-only opt-out

Stop syncing a context on this node. No DAG op, no broadcast, no key rotation. Other members never observe the leave; from their perspective the leaver is still in the membership list (which is implicit anyway, computed from group membership + auto-follow).

Storage

Two separate stores live side by side: the synced ContextIdentity row (key at crates/store/src/key/context.rs:120, value at crates/store/src/types/context.rs:117) and a node-local ContextLeftMarker tombstone in a new column.

The marker lives in Column::ContextLocal (a new column specifically for node-local context-scoped state — never synchronized). Keying is identical to ContextIdentity so the (context_id, member_pk) pair is the unit of opt-out:

A separate column instead of a flag on ContextIdentity for two reasons: (a) ContextIdentity is part of the synced membership shape, so adding a node-local field to it would conflate replicated and node-local state; (b) extending the existing Borsh value would break deserialization of pre-existing on-disk rows, requiring a migration. The dedicated column makes the node-local-ness explicit at the storage layer and keeps the synced shape clean.

Flow

1. Client calls leave_context(context_id).
2. Handler resolves the local ContextIdentity via find_local_signing_identity — scans the column for the row where this node holds the private key. Falls back to the namespace identity if no local row exists.
3. In a single batched store handle (so they land in one commit), the handler:
   1. Writes the ContextLeftMarker row in Column::ContextLocal.
   2. Deletes the corresponding ContextIdentity row, which stops sync (the sync layer iterates these rows).
4. Calls node_client.unsubscribe(&context_id) to leave the gossipsub topic, mirroring join_context's subscribe.
5. Auto-follow handler (auto_follow.rs:255) checks for the marker via has_left_context on every ContextRegistered event and skips the auto-rejoin if it finds one.

Properties

What this is not

• Not a kick. Leaver still appears in any "members of this context" query.
• Not a cryptographic leave. If the user wants forward secrecy on a context, they must leave the group containing it (which rotates the group key).

leave_group — self-removal, no cascade

Self-removal from a single group via GroupOp::MemberLeft. The leaver publishes the leave op; every receiver deletes the leaver's (member, group) row.

As-built caveat — no key rotation on self-leave. Unlike owner-initiated MemberRemoved, MemberLeft deliberately does not trigger the key-rotation pipeline. The publisher of a self-leave is the leaver, and the leaver cannot generate the fresh group key without also retaining it — which would defeat forward secrecy. So MemberLeft is the governance-level departure (the membership row is removed, peers observe the leave, the leaver is deny-listed) without a re-key. The path to a cryptographically-complete leave is an admin/owner-initiated MemberRemoved, which rotates. A two-phase self-leave rotation (a remaining admin's apply hook publishes the new key) is a tracked follow-up, not yet shipped. See the inline note in crates/governance-store/src/ops/group/member_left.rs.

New op

Distinct from MemberRemoved for audit clarity — "this member chose to leave" vs "this member was removed" are semantically different events even when they have similar effects.

Preconditions

• Signer equals the member being removed (SelfLeaveOnly) and has a direct row in the group; reject with MemberNotDirect if the signer is only an inherited member — they must leave the anchor instead.
• Signer is not the group's owner_identity (OwnerCannotSelfLeave; must TransferOwnership first).
• Removing the signer does not leave the group with zero admins (LastAdmin via ensure_not_last_admin_removal).

Flow

1. Leaver's client calls leave_group(group_id).
2. Apply enforces the preconditions above (self-equality, direct-row, owner, last-admin).
3. Leaver publishes MemberLeft { member: signer } via the governance DAG. Signed by the leaver. Targets this group.
4. Op broadcasts to all members of the group. Each receiver applies it: cascade_remove_member_from_group_tree drops the leaver's ContextIdentity rows, remove_member deletes the (leaver, group_id) membership row, and the leaver is added to the group deny-list so their state-delta traffic is dropped until they re-join.
5. The apply emits OpEvent::MemberRemoved; if the leaver's role was ReadOnlyTee it additionally emits OpEvent::TeeMemberRemoved, which drives the leaver's own node to self-purge the group's local key material.
6. No automatic re-key. As noted above, MemberLeft does not rotate the group key — the leaver still holds the last key it received and can decrypt writes made under it. Forward secrecy on future writes requires the owner-initiated MemberRemoved path (or the deferred two-phase self-leave rotation).

Cascade behavior

Failure modes

• No forward secrecy on self-leave (by design, not a failure). Because MemberLeft never rotates, the leaver retains the ability to decrypt writes made under the key they last held. To revoke that, an admin/owner must issue MemberRemoved (which rotates) or the deferred two-phase self-leave rotation must land.
• Inherited-only membership. A signer whose membership is purely inherited (no direct row) is rejected with MemberNotDirect; they must leave the anchoring ancestor instead.

Rejoin

• Restricted group: requires fresh add_group_members from a remaining admin. New keys delivered via the existing membership-add path.
• Open group (if leaver had a redundant direct row): same. If leaver's path to the group was via inheritance from a parent, that inheritance is automatically restored as soon as they rejoin the parent.

leave_namespace — cascading, heaviest

A namespace is the root group. Leaving it is a single MemberLeft at the namespace root whose apply cascades through every descendant group where the leaver has a direct row. This is the only leave operation that fans out across multiple scopes. As with leave_group, the self-leave op does not rotate keys (same publisher-holds-the-key constraint); row removal + deny-listing only.

Preconditions

• Signer has a direct row at the namespace root (MemberNotDirect otherwise).
• Signer is not the owner_identity of the namespace root (OwnerCannotSelfLeave) nor of any subgroup beneath it where they have a direct row (OwnerOwnsSubgroup, reporting the offending scope).
• Removing the signer doesn't leave any scope (namespace or descendant) admin-less. If it would → LastAdmin reports the offending scope, forcing a successor promotion before retry. All these checks run upfront, before any mutation.

Flow

1. Client calls leave_namespace(namespace_id).
2. Apply detects the no-parent (namespace-root) case and walks the subtree:
   • Compute the descendant groups where the signer has a direct row.
   • Run owner check + last-admin check across all of them upfront. If any fails (OwnerOwnsSubgroup, OwnerCannotSelfLeave, LastAdmin) it bails before mutating anything — no half-applied cleanup.
3. Signer publishes a single MemberLeft { member: signer } at the namespace root.
4. The apply cascades: for each direct-row descendant it calls cascade_remove_member_from_group_tree, removes the membership row, deny-lists the leaver, and emits OpEvent::MemberRemoved. For each descendant where the leaver's role was ReadOnlyTee it also emits a per-subgroup OpEvent::TeeMemberRemoved. The same removal then runs for the namespace root, emitting a root MemberRemoved (and a root TeeMemberRemoved if the root role was ReadOnlyTee).
5. No per-scope key rotation. The cascade is row-removal only — there is no KeyDelivery fan-out. Forward secrecy on each scope's future writes is provided by the owner-initiated MemberRemoved rotation pipeline, not by self-leave.
6. Local cleanup on the leaver's node is role-scoped, not a soft/hard toggle:
   • Non-TEE roles: soft leave. Local rows (identity, signing keys, contexts) are kept so rejoin / keyshare / inheritance-rejoin flows can reuse them.
   • ReadOnlyTee: the emitted TeeMemberRemoved events drive the self-purge listener to hard-delete local key material across the whole subtree and unsubscribe from the namespace gossipsub topic.

Edge case — last member of the namespace

If the leaver is the last remaining member, MemberLeft writes locally but has no peers to broadcast to. The namespace effectively dies on the leaver's node.

If the leaver is also the owner AND last member, they're stuck in the cycle — they must transfer ownership but there's no one to transfer to. Use a dedicated DeleteNamespace op (analogous to DeleteGroup but at root) that bypasses the owner-cannot-leave rule.

Failure modes

• No forward secrecy on self-leave across any scope (same constraint as leave_group): the cascade removes rows but does not re-key. Use owner-initiated MemberRemoved for a cryptographically-complete eviction.
• Interrupted TEE self-purge. If the leaver was a ReadOnlyTee node and its local cascade-purge is interrupted (crash, or a signing-key delete error), a durable pending-self-purge marker survives and the startup reconcile_sweep completes the purge on next restart. See TEE self-purge.

Open Questions & Follow-ups

1. Two-phase self-leave rotation. MemberLeft currently does not re-key (the leaver can't generate a key without retaining it). A deferred design has a remaining admin's apply hook publish the new key after the leave. Until it lands, owner-initiated MemberRemoved is the only rotating leave.
2. Local cleanup is role-scoped, not a toggle. The earlier soft-vs-hard default question is resolved by role (ADR 0002): non-TEE removals stay soft; ReadOnlyTee removals hard-purge. No global default knob.
3. Admin-mutual demote. Admins can demote each other. Whether to restrict this to Owner-only is unresolved; current behavior is preserved.
4. Old owner after TransferOwnership. Becomes a regular admin (current behavior) or just a member (alternative)?
5. Subgroup-level self-purge reconcile. The startup reconcile is namespace-level only; a subgroup-only purge has no reconcile retry surface yet (tracked in #2726).
6. Periodic reconcile. A purely-lagged-drop of TeeMemberRemoved writes no marker and is not recovered until a future eviction; a periodic sweep is an open follow-up.