docs: the trunk singleton form is BUILT, with its deviations

Author: gluck

plans/progress.md

@@ -1302,3 +1302,52 @@ enough that either can be judged in ninety seconds:
 box=$(mktemp -d); cp -a --reflink=auto ~/.local/state/figaro/arias $box/arias
 FIGARO_PROBE_ROOT=$box/arias go test ./internal/store -run ListingCost -v
 ```
+
+### Phase 8 landed: the hierarchy is a form
+
+`internal/trunk` (296 lines) and `trunks.json` are gone. The presentation
+hierarchy is `store.TopologyTree`, a `store.Form` on a reserved stump.
+
+**Why a stump.** The design wanted an unbound form NODE with a well-known
+id, which needs client-specified trunk ids, which figwal does not have (and
+which Gluck has already asked for: `answers-forms.md` §2). A stump is the
+one node figwal names by a caller-chosen string, so the form needs no marker
+file and no lookup, cannot be forked and cannot be bound. `listStumps`
+filters it out, or the hierarchy grows a row describing itself.
+
+**What it buys, checked rather than claimed:**
+
+- A promote is **one patch naming two edges**
+  (`TestTopologyForm_PromoteIsOneRecord`). The file it replaces rewrote the
+  whole document per edit and could half-land.
+- Durability, versioning and the single writer are the form's: reduce, append,
+  fsync, publish. `Rev()` is the form version.
+- `trunk.mu` is gone — the lock audit's fifth entry.
+- **Parity is the old package's own test suite, ported verbatim**: same
+  diagram, same claims, same names. That is what makes "it behaves as the
+  file did" checkable.
+
+**Migration**: a legacy `trunks.json` is folded in on first open and renamed
+`.migrated`. Ordering rather than a journal — the fold is idempotent, so a
+crash before the rename replays harmlessly, and a form already holding edges
+is never migrated into.
+
+**Live, on an isolated daemon**: `fig ls` draws parent→child, `promote`
+swaps them, `ls -g` shows **no** `@topology` row, and the promote survives a
+daemon restart (replayed from the channel, not re-read from a file).
+
+**Deviation: retention is not built.** durable-forms §8 says the topology
+form compacts to a single segment, which needs figwal's compacting channel
+(phase 7). Until then it keeps every record: correct, and unbounded. Promotes
+are rare so the growth is slow, but it IS growth, and phase 7 should point
+here first.
+
+| phase | state |
+|---|---|
+| 0,1,2,4,5 | done (session 1) |
+| 3 | **wire half done**: outcome + version; `session`/`seq` deliberately not built |
+| 6 | **done**: tombstone, `Reclaimable`, and the delete path calls both |
+| 7 retention | not started (needs figwal) |
+| 8 topology form | **done**, live-validated, `internal/trunk` deleted |
+| 9 libretto | not started; §12.2.2 records a design bug found before it was built |
+| 10 API refactor | not started |

skills/figaro/contributing/README.md

@@ -35,7 +35,7 @@ Read the one you are inside. These describe internals, not usage.
 | File | When to read it |
 |---|---|
 | [trunks-substrate.md](trunks-substrate.md) | Changing `internal/store` or the fork handlers. |
-| [trunk-singleton-form.md](trunk-singleton-form.md) | Changing the presentation hierarchy, `trunks.json`, or figwal channel retention. Holds the slated design: the hierarchy as one form per store. |
+| [trunk-singleton-form.md](trunk-singleton-form.md) | Changing the presentation hierarchy or figwal channel retention. The hierarchy IS one form per store as of phase 8; holds the design and where the build differs from it. |
 | [forms-design.md](forms-design.md) | Changing the form primitive: the single writer, the hub, outfit resolution, observation. |
 | [roles-design.md](roles-design.md) | Changing roles, cast, or how a studied form renders into a model's context. |
 | [reclamation.md](reclamation.md) | Changing the hub, the sweep or the row caches: what a live aria costs and when the daemon reclaims one. |

skills/figaro/contributing/trunk-singleton-form.md

@@ -1,8 +1,30 @@
 # The trunk state, as a singleton form
 
-**Status: designed, not built.** Slated after the presentation-hierarchy
-fixes it depends on. Read this before touching `internal/trunk`,
-`trunks.json`, or anything in figwal about channels and retention.
+**Status: BUILT** (`feat/incantations`, phase 8). `internal/trunk` and
+`trunks.json` are gone; the hierarchy is `store.TopologyTree`, a form on a
+reserved stump. Read this for the WHY; read `internal/store/topology_form.go`
+for what shipped, and the differences below before changing either.
+
+## What shipped, and where it differs from this design
+
+- **The home is a reserved STUMP** (`@topology`), not an unbound form node.
+  A stump is the one node figwal names by a string the caller chooses, so
+  the form needs no marker file and no lookup, and it cannot be forked or
+  bound. An unbound form node would have needed client-specified trunk ids,
+  which figwal does not have yet (and which Gluck wants for other reasons:
+  see `plans/answers-forms.md` §2). `listStumps` filters it out, or the
+  hierarchy grows a row describing itself.
+- **Retention is NOT built.** This document asks for a single rewritten
+  segment, which needs figwal's compacting channel (phase 7). Until then the
+  topology form keeps every record, which is correct and unbounded. A
+  promote is rare, so the growth is slow, but it IS growth: whoever builds
+  phase 7 should point it here first.
+- **The migration folds `trunks.json` in on first open** and renames it to
+  `trunks.json.migrated`. Ordering, not a journal: the fold is idempotent and
+  a form that already holds edges is never migrated into again.
+- **Parity is checked, not claimed.** `internal/trunk`'s own test suite was
+  ported verbatim onto the replacement: same diagram, same claims, same
+  names, in `internal/store/topology_form_test.go`.
 
 ## The claim
 

skills/figaro/reference/trunks.md

@@ -238,7 +238,7 @@ is not instant (it copies the prefix each promoted aria borrows).
 
 Implementation: `runPromote` (`internal/cli/manage.go`), the `figaro.promote`
 RPC, `PromoteResponse{FigaroID, Climbed, AtStump}`, the boundary check in
-`XwalStore.Promote`, and the override state in `internal/trunk`. The listing
+`XwalStore.Promote`, and the override state in the topology form. The listing
 carries both edges: `parent` (history, what `status` prints as forked-from)
 and `present` (where the row is drawn, what the vector follows).
 
@@ -261,16 +261,25 @@ and `present` (where the row is drawn, what the vector follows).
 A refused delete writes nothing at all: the count is taken before any
 repair, because a repair cannot be taken back.
 
-## The trunk state, and where it is going
-
-Today the presentation lives in `trunks.json` beside the store: one JSON
-object of overrides, rewritten whole on every edit, absent an override the
-topology answers.
-
-**Slated:** move it into an unbound SINGLETON FORM, one per store and so
-1:1 with the angelus that owns it. A form is already this project's answer
-to durable, versioned, reducible state, and the trunk state is exactly that
-shape. The document, the patch stream, the migration, and what figwal must
-add for it (one segment, rewritten whole, because only the fold has value
-here) are in
+## The trunk state IS a form
+
+The presentation lives in the **topology form**: a form on the reserved
+stump `@topology`, one per store and so 1:1 with the angelus that owns it.
+It holds OVERRIDES, never a full tree, so a lost topology form degrades to
+"draw every aria where its history puts it" rather than to a wrong tree.
+
+- **A promote is ONE patch naming two edges**, so the pair lands together or
+  not at all. The `trunks.json` it replaces rewrote the whole document per
+  edit and could half-land.
+- **Durability, versioning and the single writer are the form's**, not
+  bespoke: reduce purely, append, fsync, publish. `Rev()` is the form
+  version, which is what a listing's snapshot check reads.
+- **It is never listed, never forked, never bound.** `listStumps` filters it
+  out of the forest.
+- **A legacy `trunks.json` is folded in on first open** and renamed
+  `trunks.json.migrated`.
+- **Retention is not built yet**: it keeps every record until figwal grows a
+  compacting channel.
+
+Design and the deviations from it:
 [contributing/trunk-singleton-form.md](../contributing/trunk-singleton-form.md).