A Write Is a Request

The Store Writes; Everyone Else Asks

Reads can be served from verified copies anywhere. Writes cannot: there is one canonical store, and every rule from track 5 (compare-and-swap, the identity-note rule, the seal, the fence, the commit) runs where the store's tree is. So when a session on the laptop writes a note, the question is how that write gets to the one place allowed to make it real, without becoming a second, weaker path.

Soul Vault's answer (Coop todo 1110-41, built the afternoon after the cutover) is that a write from another Mac is not a file transfer and not a queued job. It is one request, applied by the canonical store's own templates, exactly as if it had been made there.

One Document, One Call

On the calling Mac, the root's write_batch runs as usual: it validates ids, checks the request id, and on the Delta child, _apply sees that this Mac is not canonical. Instead of touching files, it builds a request document of schema cwk.soulvault-write.v1: the changes, their expected revisions, the actor, the reason and the request id. Its own Delta carries that document to the owner of the store's share in a single call (call/write; creating and removing a soul have their own, call/create_soul and call/delete_soul).

On the canonical Mac, the store applies it with its own templates (write_batch, create_soul, delete_soul), under its own gate, fence, validator and compare-and-swap: one git commit, the same path a write made on that Mac takes. The architecture document is emphatic about what does not happen: nothing is staged on the caller, nothing waits on the canonical Mac, and no note is ever written as a file through Delta.

The Mac Is the One Delta Verified

A request names who is writing and from where. A request could also lie about it. So the store does not trust the document's own claim. Delta hands the store's share the calling Mac as Delta itself verified it, from the tailnet roster or the caller's ticket. Then:

A request that names another Mac, or whose actor does, is policy_denied.
The pointer's write gate is judged for the verified Mac, not for a Mac the document names.
The commit's Soul-Vault-Mac trailer is the verified Mac.
The request id of the call and the request id inside the document must be one and the same.

Every write template works this way from any of Dad's Macs: writing, deleting and moving notes, batches, editing a soul, and creating and removing a soul (the canonical store decides again that only Dad removes a real one). Two things deliberately stay where the tree is: the seal and the external-edit guard.

What It Replaced

The first remote-write design, earlier the same day, was a request file delivered to an inbox share, applied through a read call, with a staging folder on the caller (0.34 s per write). It worked, but it had a second path's smell: a request that named a Mac for itself, a folder that could hold half-sent work, two moving parts where one would do. When Delta gained a write call for app shares, the inbox share, the apply operation and the caller's staging folder were removed.

A Name That Must Cross Intact

One bug shows why a request must carry exactly what it means. A promoted soul and the guest vault it came from share a slug, and by slug the soul answers. A removal sent from another Mac carried the bare slug, so asking to remove guest-souls/<slug> from any Mac but the canonical one would have removed the soul's vault instead. The records showed no real soul was hit (the one real removal of a promoted pair ran on the canonical Mac), and the request now carries the vault's own name.

Code

Not canonical? Send the batch, do not apply it (trimmed from DeltaVault._apply)·python

def _apply(self, changes, actor, request_id, reason):
    vault = changes[0].note.vault
    if not self.canonical:
        from . import delta_door
        answer = self._remote("write", delta_door.request_document(
            request_id=request_id, vault=vault, changes=changes, actor=actor, reason=reason,
            generation=self.generation, caller=self.fleet_label))
        self._forget_replica_lists(vault)
        return dict(answer["revisions"])
    # canonical: the intent / lock / files / commit / rows / COMMIT order from track 5
    ...

The shape of a write request (illustrative values)·json

{
  "schema": "cwk.soulvault-write.v1",
  "operation": "write",
  "request_id": "note-edit:91a4c0",
  "vault": "pippa",
  "generation": 5,
  "caller": "<laptop fleet label>",
  "reason": "add the evening's correction",
  "actor": { "kind": "soul", "name": "pippa", "harness": "claude-code", "...": "..." },
  "changes": [
    { "op": "put", "path": "memory/example.md", "text": "...",
      "expected_revision": "3f9a1c...", "must_exist": true }
  ]
}

Exercise

Turn a remote write in a system of yours into one request applied by the owner's own write path: define a request document with a schema name, the changes, expected versions, actor, reason and request id; have the transport tell the server which client connected; refuse any request whose payload names another client or whose two request ids differ; and make sure no staging area exists on either side.

Hint

If the server has a 'remote apply' function separate from its local write function, you have two write paths. Make the remote handler call the local write function and nothing else.