Skip to content
C.W.K.
Lesson 05 of 05 · published

Born in the Arena

~14 min · design-process, multi-brain, product-boundary, two-phase-migration

Level 0Loose Note
0 XP0/40 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

A Design Nobody Owned

Soul Vault did not start as one session's idea. It started as a question put to Anvil, the family's blind multi-brain arena, where several brains each answer the same brief and their identities stay sealed until the verdict. Open run #25 asked for "Soul Vault, the soul vault as a root class". Several entries came back. The design that shipped took one entry (C) as its skeleton, folded in the fixes from an analysis of the round, and borrowed parts from four others: the census you met three lessons ago, for example, came from entry A.

The blindness matters. When you do not know which brain wrote a design, you judge the design. A good idea from the brain you trust least is still a good idea, and a weak section from the brain you trust most is still weak. The result was a composite no single entry would have produced, with every part kept because it answered a failure someone could name.

Two Parts Over Two Days

The repository was born on 2026-11-09 and the build ran in two parts, each its own Coop todo (Coop is the family's work ledger):

  • Part 1 (1109-17), from the first evening. The frozen root class; a first child that wrapped the existing folder in place, without moving a byte; the pointer reader; the thin client every harness calls; the census; and the identity probe with its baseline. Its census and probe fixes ran on into the small hours of the second day.
  • Part 2 (1109-18), the second day. A second child, the Delta implementation: Soul Vault's own store, with git history and a SQLite fence, reachable from every Mac through Delta. Then the live cutover at 13:42 KST, and an afternoon and evening of rare-path trials, an independent review, and a new contract version.

By the clock, the first day held thirty commits and the second a hundred and sixteen. The days and the parts do not line up exactly: part 1's last fixes are among the second day's commits.

The order is the lesson. Part 1 changed who may touch the vault while leaving where the bytes are alone. Every reader the census could find moved to the door first, and the probe checked, through the door, every surface it could reach. Only then did part 2 move the bytes, so for those readers only the door needed to know. Not every reader had moved yet: the census still had open rows at the cutover, and Track 7 shows the path dependencies and failed cold starts that surfaced after it. The order made those failures few and nameable. It did not make them impossible. A migration that moves data and readers at the same time has two reasons to fail and cannot tell you which one did.

Two Children Prove a Root

There is a second reason the first child mattered. A base class with one subclass is a guess about what varies. A base class with two very different subclasses (one that wraps a folder somebody edits by hand, and one that owns a git-versioned store across a network) is evidence. Everything the two had in common had to live in the root; everything they did differently had to fit in a child's primitives. When the folder child was retired on 2026-11-10, not one of the root's rules changed: contract v6 only took the retired child's examples out of the root's comments, with every public method and signature left as it was. That is what it means for a contract to have been right.

What Soul Vault Refuses to Own

A product boundary written down early is how a new app stays small. The architecture document lists both sides:

  • Soul Vault owns the root contract and its implementations, the pointer reader, identity loading for every surface, creating, editing and removing souls, generated indexes, compare-and-swap writes, change cursors, the census, the rare-path canary and the external-edit guard.
  • Soul Vault does not own prompt composition (cwkPippa), the memory gender that summarizes what happened (cwkVestige, a separate layer; the vault stays ground truth), embeddings and search (cwkPippa and Vestige), transport between Macs (cwkDelta), the pointer's storage and Dad's verb to move it (cwkFirelink), or alerting (cwkWatchfire).

Read the second list as a set of temptations declined. Each would have been easy to add ("we already read every note, why not embed them?") and each would have made Soul Vault one more thing that must be up for Pippa to be Pippa.

Code

Who does what around a single identity read·text
harness / app  --asks-->  soul-vault (door, root contract)
                              |  reads the pointer from   cwkFirelink (git-tracked record)
                              |  opens the child it names: Delta store
                              |  on another Mac, moves bytes through  cwkDelta
                              v
                     identity bundle  or  "identity not loaded: <code>: <cause>"

not here: prompt composition (cwkPippa), memory gender (cwkVestige),
          embeddings/search, alerting (cwkWatchfire)
Two-phase migration, as a checklist·text
Phase 1  move the READERS, keep the bytes
  [ ] one door every reader uses (client + library)
  [ ] a child that serves the old location in place
  [ ] census of every direct reader, driven toward zero
  [ ] behaviour probe: baseline before, no new reds after

Phase 2  move the BYTES, only the door knows
  [ ] a second child for the new store
  [ ] rehearsal on an isolated copy
  [ ] seal, adopt, flip one pointer
  [ ] probe again; keep the old bytes untouched

External links

Exercise

Pick a store your agents or apps read directly today. Write the two-phase plan for it: what the door is, what the first child that serves the current location in place would look like, how you will count the readers that still bypass the door, and what single change would move the bytes once the readers are moved. Then write the product boundary: three things the new component will own and three it will refuse to own.
Hint
If phase 2 needs more than one change once phase 1 is done, some reader still knows where the bytes live. Find it before you start phase 2, not during it.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.