Rollout and the Write Gate

One Record, Many Answers

A single pointer seems to imply a single switch: every reader on every Mac flips at once. Real migrations want something gentler. You want one harness on one Mac to read the new store first, prove itself, and only then bring the rest. You want to freeze writes for the few minutes when the store is being copied. Soul Vault does both inside the same record, without ever letting the record mean different things to different readers by accident.

The key is Pointer.resolve(fleet_label, harness), described in its docstring as "one total, pure function over (record, Mac, harness)". Total means it answers for every input, never raises for an unknown Mac. Pure means the answer depends on nothing but those three things: no clock, no network, no file. Any Mac can compute any other Mac's answer from the same record and get the same result, and a test can enumerate every case.

Read Rollout

read_rollout is either null or {"backend": ..., "scopes": [...]}, where each scope names a harness and a fleet label. A reader whose harness and Mac match a scope reads the rollout backend; everyone else reads backend. That is a staged switch: point one harness on one Mac at the new store, run the probe, widen the scopes, and finally make the new store backend and clear the rollout.

The source is precise about what a rollout is not. It "never chooses a backend because another one failed." Membership in a scope is decided by Dad's record, not by what happened at runtime. That is the line between a staged switch and a fallback.

The Write Gate

write_gate has three modes:

all: every writer is admitted. This is the normal state, and the state at generation 5.
none: nobody is admitted. The vault is read-only for everyone, as during a transition.
allowlist: only the listed harness-and-Mac scopes may write. A pilot can let one session write while everyone else waits. Its writes still go to the record's backend: a read rollout moves where that session reads, never where anyone writes.

A writer outside the gate gets rollout_hold from the store's lock: "the pointer's write gate does not admit this caller now; the text stays with the caller and nothing was queued". That last clause is a decision. Soul Vault does not keep a queue of writes to replay when the gate opens. A queued write would land later, against notes that may have changed meanwhile, under a pointer that may have moved: exactly the kind of quiet surprise this system exists to prevent. The text stays with the caller, who can retry with a fresh read once writes are admitted.

Gate Versus Seal

The write gate is a property of the record. There is a second, stronger stop that belongs to the store itself: the seal from contract v5. A sealed store refuses every write with writer_sealed, and seal() returns only after the writes already in flight have finished, so nothing lands behind it. Sealing is Dad's step: the actor must be a human, or a caller that names his word in an approval_ref, and it must say which transition it is for. On cutover day the old store was sealed at 13:39:38 KST; the gate is how the record speaks to all readers, the seal is how one store guarantees its last write has landed.

Code

Pointer.resolve: total and pure (from soulvault/pointer.py)·python

def resolve(self, fleet_label: str, harness: str) -> Resolution:
    """One total, pure function over (record, Mac, harness)."""
    reads = self.backend
    if self.rollout_backend and any(s.matches(harness, fleet_label) for s in self.rollout_scopes):
        reads = self.rollout_backend
    if self.write_gate_mode == "all":
        admitted = True
    elif self.write_gate_mode == "none":
        admitted = False
    else:                                   # allowlist
        admitted = any(s.matches(harness, fleet_label) for s in self.write_gate_scopes)
    return Resolution(reads, self.backend, admitted, self.generation)

A staged switch, as a record (illustrative: one harness on one Mac reads first, only it may write)·json

{
  "schema": "cwk.soul-vault-pointer.v1",
  "generation": 12,
  "backend": "old-store",
  "read_rollout": {
    "backend": "new-store",
    "scopes": [{ "harness": "claude-code", "fleet_label": "workbench" }]
  },
  "write_gate": {
    "mode": "allowlist",
    "scopes": [{ "harness": "claude-code", "fleet_label": "workbench" }]
  },
  "stores": { "...": "..." }
}

Exercise

Write a resolve function for a configuration record of yours that takes (record, machine, client) and returns which backend to read and whether writes are admitted, with a staged read rollout and a three-mode write gate. Then write a table test that covers every mode, a matching and a non-matching scope, and an unknown machine, and confirm the function never raises for any of them.

Hint

If you find yourself wanting to pass in 'is the new backend healthy?', stop: that input turns a staged switch into a fallback. Health belongs to monitoring and to the person who moves the record.