ADR 0021: Extended-NL multi-writer write enforcement

How Neo stops two agents that share one App-Worker heap from corrupting each other's Neural Link component writes: a held-until-release subtree-lock model keyed on the (agentId, sessionId) writer pair, composed from small pure cores plus one stateful heap authority — no parallel write pipeline. This is the NL component-write case specifically; multi-writer also arises for multi-tenant push envelopes and add_memory JSONL appends, which are separate problems. This record is why this architecture, not how to use Neural Link.

1. Context

This is enforcement for the co-habitation case: more than one identified agent issuing write-class Neural Link operations against the same live component tree on one heap. It is not network auth (the Bridge owns that), and it is not the single-writer Fleet-Manager case (#13015 is deliberately single-writer).

Two agents driving the same App-Worker heap can issue overlapping write-class operations (set_instance_properties, call_method) against the same component subtree. Without coordination, the later write silently clobbers or interleaves with the earlier one — the classic shared-mutable-state corruption, now across agents rather than threads. The heap is the shared truth, so the coordination authority must live heap-side, and it must be held-until-release (not per-op): a writer holds a subtree while it works, and a different writer's overlapping write is denied for as long as the holder keeps it. Per-op locking would not prevent interleaving between two agents' multi-step edits.

2. Decision — the lock model

A lock is {agentId, sessionId, subtreePath}:

• The writer is the (agentId, sessionId) pair — not agentId alone. The same human/agent identity on two Bridge connections is two writers; a half-stamped pair (either field missing) is no valid writer at all (fail-closed).
• The target is a component subtree, named by its absolute root→node component-id path (subtreePath). Two locks conflict iff their subtrees overlap (one path is a prefix of the other — ancestor/descendant/equal) and they belong to different writers. Same-writer re-acquisition of an overlapping/identical subtree is re-entrant (granted, no duplicate).
• Absolute paths are load-bearing: prefix-overlap is only sound on root→node paths. A relative path would let two unrelated subtrees that share a head id false-overlap (or nested ones false-disjoin).

3. The layers

The subsystem is deliberately decomposed into small pure cores plus one stateful authority, so each contract is unit-provable in isolation (no live heap, socket, or WriteGuard needed to test the decision logic):

4. Request data-flow

Bridge (authenticated agent connection, #13181)
  └─ stamps {type:'agent_message', agentId, sessionId, message}   (sidecar emit, #13196/#13199)
       │
   WebSocket frame → Neo.ai.Client.onSocketMessage
       │
   parseAgentEnvelope(frame) ──→ {jsonrpc, context:{agentId, sessionId}}   (or context:null for legacy)
       │
   Client.handleRequest(method, params, context) ──→ service(params, context)
       │                                                  (context threaded; #13174)
   InstanceService.setInstanceProperties / callMethod
       │
   const {admitted, reason, conflict} = admitWrite({context, componentId: id, parentOf, writeGuard})
       ├─ admitted (legacy / granted / same-writer re-entrant) → mutate
       └─ !admitted (incomplete-identity | unresolvable-target | no-write-guard | conflict) → THROW, no mutate

5. Fail-closed discipline

Every layer fails closed — only a fully-valid, identified, non-conflicting request mutates:

• An absent context is the one fail-open-to-legacy path, and it is not an agent-controllable bypass: the Bridge stamps the agent_message envelope on every authenticated-agent frame, so a context-less frame at the Client is genuinely non-agent. A present-but-malformed object context denies (it is not silently treated as legacy).
• A half-stamped (agentId, sessionId) pair never acquires a lock (normalizeLock / resolveWriteLock deny it).
• An unresolvable target (malformed/cyclic id → deriveSubtreePath returns null) denies rather than locking a corrupt path.
• A missing writeGuard while enforcement is required denies (no-write-guard) rather than mutating unguarded.
• A cross-writer overlap denies and leaves the held-lock table unchanged; conflict is a defensive copy, never a live reference into the authority's state.

6. Status & follow-ups

• Live on dev: the full acquire/hold/deny write path — LockRegistry (#13125), WriteGuard (#13134), deriveSubtreePath (#13138), parseAgentEnvelope + sessionId (#13174 / #13205), resolveWriteLock (#13208), and admitWrite + the InstanceService write-path enforcement + the Client-owned per-heap WriteGuard (#13226).
• Open follow-up (#13229): the agent_disconnected → WriteGuard.releaseAgent sweep that frees a dropped writer's locks (cross-cutting Bridge↔Client; the frame must carry sessionId, not just agentId). Until it lands, a write's lock is held until heap-restart — same-writer re-acquire is re-entrant (no self-block), a different writer is correctly denied. Plus a live two-agent cross-write-denial whitebox-e2e.
• Out of scope: the Bridge auth + sidecar transport (the identity Leaf A, already merged) and cross-harness session-id canonicalization (#12984).

Related

• Epic #13056 (Extended-NL coordination); contract-of-record #13167. Sibling architecture doc: learn/agentos/DockZoneModel.md. Concept anchor: ADR 0020 (Agent Harness).