Post-S27 doc reconciliation: CLAUDE, handoff, S16 contract, both ledger cells

P13-S27 landed at 4df8e25. Four documents carried live statements that the
landing invalidated, and they had to move together: updating the ledger alone
would have left the active S16 contract contradicting it.

CLAUDE.md
- Track head: P13-S27 LANDED; P13-S16 unblocked, contract still DRAFT.
- The T1b/S27 collision is resolved. T1b is NOT thereby free -- it stays
  blocked on Ruling B blocker (ii), versioned decode. A future
  epiphany-bundle rung re-creates the collision on its own terms.
- Green baseline 1570 -> 1577, and marked as the single origin for the count.
- "One live constraint" rewritten: the blanket no-canonical-base prohibition
  is lifted, replaced by the authority check (accepted when
  reduction_algorithm_version equals CURRENT_REDUCTION_ALGORITHM_VERSION,
  currently 0; CanonicalBaseRequiresRebuild on both read and write paths;
  legacy epoch still refuses outright), plus the bump discipline and the
  synthetic_for_fixture / production_caps split.

spec/HANDOFF_2026-08-07.md -- a dated snapshot, so it keeps its text and gains
a POST-S27 UPDATE block at the top that is the single place the new state is
given. Each invalidated site now points there instead of restating:
§1.2 constraint (dated record), the suspended conformance wiring (restored),
ReductionAuthorityUnavailable (deleted, replaced), §1.4 chain state, §2.6 and
§4.3 collision, §4.3 items 7 and 9. The three 1570 repetitions are replaced by
a pointer to CLAUDE.md -- a figure kept in four places goes stale in three.

spec/CONTRACT_P13S16_PROJECTION.md
- Status: DRAFT, UNBLOCKED 2026-08-09, NOT RATIFIED and therefore NOT
  dispatchable. Pin 0's blocker is discharged; core_spec.tex:11614 is met.
  Original status retained verbatim.
- Pin 11 amended: it mandated a ledger state of "blocked on P13-S27," which is
  now false -- a pin requiring a false ledger state would put the contract in
  contradiction with the ledger it governs. Its instruction to file S27 in the
  same edit is discharged.

spec/PASS13_CANDIDATES.md -- appended to both cells, per the append-only
convention.
- S16: unblocked, with the "additionally needs pin-2a's disposition" sentence
  explicitly superseded (settled from outside S27 by the format rung's pin 8);
  unblocked is not dispatchable; first act is bumping the authority to 1.
- S27: accepted and landed, with the gate figures, and a correction to pin
  10's own wording -- it said S16 becomes "dispatchable," but by this repo's
  definition S16 is unblocked, not dispatchable. Same unblocked/dispatchable
  conflation S27's round 1 committed.

Documentation only: no .rs or .toml touched, so the gates re-run against the
landed tree stand unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ps1szk2mSfgp4Cz21eVH9x
This commit is contained in:
Levi Neuwirth 2026-08-09 15:24:21 +02:00
parent 4df8e257f3
commit 8df798d907
No known key found for this signature in database
4 changed files with 152 additions and 39 deletions

View File

@ -17,12 +17,14 @@ model with a LaTeX specification suite as its source of truth.
| Track | Lives in | Current head | | Track | Lives in | Current head |
|---|---|---| |---|---|---|
| **Spec / Pass 13** — wire format, bundle, ops, text projection, the `.tex` suite | `spec/`, `crates/epiphany-{core,ops,bundle,textproj,testkit}` | P13-S27 unblocked and dispatchable | | **Spec / Pass 13** — wire format, bundle, ops, text projection, the `.tex` suite | `spec/`, `crates/epiphany-{core,ops,bundle,textproj,testkit}` | **P13-S27 LANDED** (`4df8e25`); **P13-S16 unblocked, contract still DRAFT** |
| **Editor / T4** — the editing seam, engraving, the toolkit spike | `spec/PLAN_EDITOR_APP.md`, `spec/CONTRACT_EDITOR_*`, `spikes/`, `crates/epiphany-{editor-core,editor-gui,engrave,layout-ir,glyphs,render-svg}` | T4 spike, round 2 built but not run | | **Editor / T4** — the editing seam, engraving, the toolkit spike | `spec/PLAN_EDITOR_APP.md`, `spec/CONTRACT_EDITOR_*`, `spikes/`, `crates/epiphany-{editor-core,editor-gui,engrave,layout-ir,glyphs,render-svg}` | T4 spike, round 2 built but not run |
They are currently independent. **They collide when T1b opens**, because T1b They are currently independent. The T1b/P13-S27 collision in
and P13-S27 both land in `epiphany-bundle/src/bundle.rs`. Do not fly those two `epiphany-bundle/src/bundle.rs` is **resolved — S27 landed 2026-08-09.** **This does
together. not make T1b free:** it stays blocked on Ruling B blocker (ii), versioned decode
(handoff §2.3). Any future `epiphany-bundle` rung re-creates a collision with T1b on
its own terms — that is a property of the crate, not of S27.
## How work is done here ## How work is done here
@ -83,16 +85,35 @@ reach today.
## Green baseline ## Green baseline
``` ```
cargo test --workspace # expect 1570 passing, 0 failed cargo test --workspace # expect 1577 passing, 0 failed, 0 ignored
cargo clippy --workspace --all-targets -- -D warnings # clean cargo clippy --workspace --all-targets -- -D warnings # clean
``` ```
**This is the single origin for the count** — `spec/HANDOFF_2026-08-07.md` used to
repeat it in three places and now points here. It moved 1570 → 1577 when P13-S27 landed.
If the count differs on arrival, reconcile that **before** starting new work — If the count differs on arrival, reconcile that **before** starting new work —
the mutation discipline above depends on a known-green baseline. the mutation discipline above depends on a known-green baseline.
## One live constraint ## The canonical-base rule — the "one live constraint" is LIFTED
Until **P13-S27** lands, **no bundle anywhere may carry a canonical base** — not **P13-S27 landed 2026-08-09 (`4df8e25`), so the blanket prohibition is gone.** It read:
in production, tests, or the conformance suite. Base-bearing fixtures must be *until P13-S27 lands, no bundle anywhere may carry a canonical base.* It no longer
hand-built images (see `craft_image` in `epiphany-bundle/src/bundle.rs`). applies, and base-bearing bundles are constructible again through the ordinary API.
Refusals you hit there are the design, not a bug. See handoff §1.2.
**What replaced it, and it is not "anything goes":** a canonical base is accepted only
when its `reduction_algorithm_version` equals the running authority,
`epiphany_ops::CURRENT_REDUCTION_ALGORITHM_VERSION`**currently `0`**. A mismatch is
`CanonicalBaseRequiresRebuild { base, current }`, refused on **both** the read side
(`open`) and the write side (`commit`/`commit_versioned`). Legacy-epoch bundles still
refuse a base outright.
**The bump discipline is the whole guarantee.** Any change to a canonical reduction
verdict MUST bump that constant — **no mechanism can detect a semantics change**, so
nothing will catch a missed bump. P13-S16 is the first rung that must move it to `1`.
Fixtures deliberately exercising arbitrary wire versions take
`BundleCapabilities::synthetic_for_fixture(v)`; production paths take the crate-local
`production_caps()`. Never the former on a production path. `craft_image` /
`craft_image_with_base` still exist for hand-built images, but are no longer the *only*
way to get a base. See handoff §1.2, marked as a dated record.

View File

@ -1,12 +1,29 @@
# Contract — P13-S16: the projection gets maintained # Contract — P13-S16: the projection gets maintained
**Status:** DRAFT — **BLOCKED on P13-S27.** Not executable as written. Pin 0 **Status:** **DRAFT — UNBLOCKED 2026-08-09. NOT RATIFIED, and therefore NOT
exposes that no authority defines the implementation's current reduction dispatchable.**
semantics, and prose saying old canonical bases "must be rebuilt" does not make
them unusable. `core_spec.tex:11614`'s requirement stays **unmet** until S27 **P13-S27 landed and was accepted at `4df8e25`**, so pin 0's blocker is discharged: an
supplies a version authority and a rejection-or-rebuild path. This contract is authority now defines the implementation's current reduction semantics
complete and ratifiable as a *plan*; it may not be dispatched until S27 has a (`epiphany_ops::CURRENT_REDUCTION_ALGORITHM_VERSION`, currently **`0`**), and
disposition. `core_spec.tex:11614`'s requirement is **met** — a stale canonical base is refused with
`CanonicalBaseRequiresRebuild` on both the read and write paths.
**What remains before dispatch is this contract's own ratification.** It is complete and
ratifiable as a *plan* and has **not been through adversarial review rounds**.
*Unblocked* and *dispatchable* are different states, and conflating them is how the S27
contract came to be ratified after a single round and then have that ratification
withdrawn — see its status block.
**This rung's first act is bumping the authority to `1`**, because it changes
`CreateStaffGroup`'s reduction verdict. That bump is the discipline S27 installed: no
mechanism can detect a semantics change, so the bump is the entire guarantee.
> **The original status, retained:** *DRAFT — BLOCKED on P13-S27. Not executable as
> written. Pin 0 exposes that no authority defines the implementation's current
> reduction semantics, and prose saying old canonical bases "must be rebuilt" does not
> make them unusable. `core_spec.tex:11614`'s requirement stays unmet until S27 supplies
> a version authority and a rejection-or-rebuild path.*
**Rung type:** **canonical reduction-semantics change.** This is stronger than **Rung type:** **canonical reduction-semantics change.** This is stronger than
"behaviour change" and the first draft of this contract understated it. The same "behaviour change" and the first draft of this contract understated it. The same
@ -368,8 +385,22 @@ under B — for example **"maintained from `Staff.group`"** and **"must agree"**
so that reverting either comment to its B wording fails the guard. M7 signs so that reverting either comment to its B wording fails the guard. M7 signs
exactly this. exactly this.
**Pin 11 — the ledger.** **Pin 11 — the ledger. AMENDED 2026-08-09: the mandated state changed when S27 landed.**
`spec/PASS13_CANDIDATES.md`'s P13-S16 row → **blocked on P13-S27**, recording the
> **This pin required the P13-S16 row to read "blocked on P13-S27".** S27 landed and was
> accepted at `4df8e25`, so that state is now **false**, and a pin mandating a false
> ledger state would put this contract in contradiction with the ledger it governs.
> **As amended, the row must read: UNBLOCKED — S27 landed; this contract is DRAFT and
> needs ratification before dispatch.** Everything else the pin requires recorded is
> unchanged.
>
> The second paragraph's instruction to **file P13-S27 in the same edit** is
> **discharged** — S27 has its own row, its own ratified contract, and its own
> `RESOLVED — IMPLEMENTED 2026-08-09 (pin 10)` marker. It is no longer this rung's to
> file.
`spec/PASS13_CANDIDATES.md`'s P13-S16 row → **UNBLOCKED, S27 landed** *(was: blocked on
P13-S27)*, recording the
`ContainerNotEmpty` reuse (and that a new reason was considered and proved `ContainerNotEmpty` reuse (and that a new reason was considered and proved
unnecessary), the base-ingest hazard, the `t8b` inversion, the `t6`/`t7`/`t9` unnecessary), the base-ingest hazard, the `t8b` inversion, the `t6`/`t7`/`t9`
revisions, and — per pin 0 — that canonical bases materialized before this rung revisions, and — per pin 0 — that canonical bases materialized before this rung

View File

@ -3,6 +3,30 @@
Written at `ada751c`, pushed to `origin/main`. Working tree clean, no stashes, no Written at `ada751c`, pushed to `origin/main`. Working tree clean, no stashes, no
unpushed commits on any branch. unpushed commits on any branch.
> ## POST-S27 UPDATE — 2026-08-09. Read this before the rest of the document.
>
> **P13-S27 landed and was accepted at `4df8e25`**, after eight independent reviews of
> the staged execution. This handoff is a **dated snapshot of 2026-08-07** and is
> preserved as written; each section S27 invalidated is marked at its own site, and
> **this block is the only place their new state is given** — the sites point here
> rather than restating it.
>
> | Section | Said | Now |
> |---|---|---|
> | **§1.2 the live constraint** | no bundle anywhere may carry a canonical base | **LIFTED.** A base is accepted when its `reduction_algorithm_version` matches the running authority and refused with `CanonicalBaseRequiresRebuild { base, current }` when it does not — read side in `open`, write side in `commit`/`commit_versioned` |
> | §1.2 conformance criterion 4 | canonical-base wiring **suspended** | **RESTORED.** Both lapsed assertions are back and the suspension marker is gone from `testkit/src/roundtrip.rs` |
> | §1.2 the third error | `ReductionAuthorityUnavailable`, temporary | **DELETED**, replaced by `CanonicalBaseRequiresRebuild`. The two permanent repack errors are unchanged |
> | §1.4 chain state | `P13-S27 (UNBLOCKED) → P13-S16 (blocked on S27)` | `P13-S27 (LANDED)`**`P13-S16 (UNBLOCKED, DRAFT — needs ratification)`** |
> | §2.6, §4.3 collision | T1b and P13-S27 must not fly together | **RESOLVED** — S27 has landed. **T1b is NOT thereby free:** it remains blocked on Ruling B blocker (ii), versioned decode — see §2.3, which is still accurate |
> | §3.5, §4.2, §4.3 baseline | 1570 passing | **1577 passing, 0 failed, 0 ignored, 42 suites.** `CLAUDE.md`'s *Green baseline* is the single origin; this document no longer repeats the figure |
> | §4.3 item 7 | dispatch P13-S27 | **done** |
> | §4.3 item 9 | P13-S16 dispatchable the moment S27 lands | **unblocked — but its contract is a DRAFT and needs ratification before dispatch** |
>
> **The authority is `epiphany_ops::CURRENT_REDUCTION_ALGORITHM_VERSION`, currently
> `0`.** Any change to a canonical reduction verdict MUST bump it, and **no mechanism
> can detect a semantics change** — the discipline is the entire guarantee. **P13-S16 is
> the first rung that must move it to `1`.**
**Scope.** Written from the **spec / Pass-13 / format-epoch** session. A second **Scope.** Written from the **spec / Pass-13 / format-epoch** session. A second
session has been committing to this repository in parallel on the **editor / session has been committing to this repository in parallel on the **editor /
T4** track, and its files were out of bounds for this one for most of the work. T4** track, and its files were out of bounds for this one for most of the work.
@ -116,7 +140,12 @@ Normative text: `core_spec.tex` §"The Container Epoch" +
`req:format:container-epoch`; `binary_format.tex` header table (0.17.0); `req:format:container-epoch`; `binary_format.tex` header table (0.17.0);
`text_projection.tex` `req:textproj:roundtrip` (0.14.0). `text_projection.tex` `req:textproj:roundtrip` (0.14.0).
### 1.2 The live constraint — read this before touching bases ### 1.2 The live constraint — LIFTED 2026-08-09 by P13-S27 (`4df8e25`)
> **This section is a dated record, not a live rule. See the POST-S27 UPDATE at the top
> for the state that replaced it.** The constraint below held only until S27 landed, and
> S27 has landed. Bases are now validated against the running authority rather than
> refused categorically. **Everything after this marker describes the pre-S27 world.**
**Until P13-S27 lands, no bundle anywhere may carry a canonical base** — not in **Until P13-S27 lands, no bundle anywhere may carry a canonical base** — not in
production, not in tests, not in the conformance suite. Four rules compose to production, not in tests, not in the conformance suite. Four rules compose to
@ -132,7 +161,10 @@ Consequences you will hit immediately if you forget:
superblock bytes directly through the public `encode()`s. superblock bytes directly through the public `encode()`s.
- Two refusal tests are unit tests over `Manifest`, not end-to-end, for exactly - Two refusal tests are unit tests over `Manifest`, not end-to-end, for exactly
this reason, and say so in their doc comments. this reason, and say so in their doc comments.
- Conformance criterion 4's canonical-base wiring is **suspended**, marked in - *(**POST-S27: no longer suspended.** S27 restored both assertions and deleted the
marker. The warning below about re-homing the snapshot to `acceleration_snapshots`
stands permanently — it was never about the suspension.)*
Conformance criterion 4's canonical-base wiring is **suspended**, marked in
`crates/epiphany-testkit/src/roundtrip.rs` with a comment naming P13-S27. Its `crates/epiphany-testkit/src/roundtrip.rs` with a comment naming P13-S27. Its
serialize → load → decode → reserialize cycle still runs via a direct serialize → load → decode → reserialize cycle still runs via a direct
`ChunkRef` read. **Do not "restore" it by re-homing the snapshot to `ChunkRef` read. **Do not "restore" it by re-homing the snapshot to
@ -146,6 +178,12 @@ both name **repack**), and `ReductionAuthorityUnavailable` (temporary, names
**P13-S27**, must **not** say repack — a major-1 container is already the right **P13-S27**, must **not** say repack — a major-1 container is already the right
epoch). epoch).
> **POST-S27:** the two permanent errors are unchanged. **`ReductionAuthorityUnavailable`
> no longer exists** — S27 deleted it and put `CanonicalBaseRequiresRebuild { base,
> current }` in its place, which is a real capability check rather than a placeholder.
> The "may not degrade to read-only" rule carries over to it verbatim: a stale base is
> the wrong materialization, not a restricted-but-correct view.
### 1.3 Text projection lost a capability, deliberately ### 1.3 Text projection lost a capability, deliberately
Base-bearing documents no longer round-trip through text. All three sides refuse Base-bearing documents no longer round-trip through text. All three sides refuse
@ -164,9 +202,16 @@ serialization already refused.
### 1.4 Chain state ### 1.4 Chain state
``` ```
format-epoch rung (LANDED) → P13-S27 (UNBLOCKED, dispatchable) → P13-S16 (blocked on S27) format-epoch rung (LANDED) → P13-S27 (LANDED 4df8e25) → P13-S16 (UNBLOCKED — DRAFT, needs ratification)
``` ```
> **Updated 2026-08-09.** It read `P13-S27 (UNBLOCKED, dispatchable) → P13-S16 (blocked
> on S27)`. **S16 is unblocked but NOT dispatchable**: its contract
> (`spec/CONTRACT_P13S16_PROJECTION.md`) is a DRAFT and must be ratified through
> adversarial review rounds first. *Unblocked* and *dispatchable* are distinct here —
> the S27 contract's own status block had to disambiguate them in round 1, which is how
> it came to be ratified after a single round.
**P13-S27** — `spec/CONTRACT_P13S27_REDUCTION_AUTHORITY.md`, still DRAFT, now **P13-S27** — `spec/CONTRACT_P13S27_REDUCTION_AUTHORITY.md`, still DRAFT, now
dispatchable. Its pin 2a was **resolved from outside** by the format rung's pin dispatchable. Its pin 2a was **resolved from outside** by the format rung's pin
8, exactly as pin 2a's own prohibition required: *legacy bases are refused by 8, exactly as pin 2a's own prohibition required: *legacy bases are refused by
@ -394,8 +439,14 @@ T4's measurements.
The remaining shared surfaces are the ones already named: `.tex` requirement The remaining shared surfaces are the ones already named: `.tex` requirement
counts in `testkit/tests/requirement_labels.rs`, and — when T1b eventually counts in `testkit/tests/requirement_labels.rs`, and — when T1b eventually
opens — `epiphany-bundle`, which is exactly where §1's rungs live. **T1b and opens — `epiphany-bundle`, which is exactly where §1's rungs live. ~~**T1b and
P13-S27 both land in `bundle.rs` and must not fly together.** P13-S27 both land in `bundle.rs` and must not fly together.**~~
> **RESOLVED 2026-08-09: S27 has landed, so there is nothing left for T1b to collide
> with.** **This does not make T1b free** — it remains blocked on Ruling B blocker (ii),
> versioned decode (§2.3, still accurate). The requirement-label surface is unchanged and
> still shared. Any *future* `epiphany-bundle` rung re-creates a collision with T1b on
> its own terms; that is a property of the crate, not of S27.
## §3. Reproducing the environment on the other machine ## §3. Reproducing the environment on the other machine
@ -437,14 +488,16 @@ form that crosses.
### 3.5 Green baseline to reproduce first ### 3.5 Green baseline to reproduce first
``` ```
cargo test --workspace # 1570 passing, 0 failed cargo test --workspace # count: see CLAUDE.md
cargo clippy --workspace --all-targets -- -D warnings # clean cargo clippy --workspace --all-targets -- -D warnings # clean
cargo fmt -p epiphany-bundle -p epiphany-textproj -p epiphany-testkit --check cargo fmt -p epiphany-bundle -p epiphany-textproj -p epiphany-testkit --check
``` ```
If `cargo test --workspace` is not 1570 on arrival, reconcile that **before** **The expected count lives in `CLAUDE.md`'s *Green baseline* and is NOT repeated here —
starting new work — this thread's whole method depends on a known-green baseline changed 2026-08-09.** This document stated `1570` in three places; S27 moved it to
to mutate against. **1577**, and a figure kept in four places goes stale in three of them. If the observed
count differs from `CLAUDE.md`'s, reconcile that **before** starting new work — this
thread's whole method depends on a known-green baseline to mutate against.
--- ---
@ -475,24 +528,32 @@ to mutate against.
machine does not present both a discrete and an integrated Vulkan adapter, machine does not present both a discrete and an integrated Vulkan adapter,
stop and raise it — Round 1's results were taken under that configuration and stop and raise it — Round 1's results were taken under that configuration and
Round 4's deciding figures are defined by it. Round 4's deciding figures are defined by it.
6. **Reproduce the green baseline in §3.5 before starting new work.** 1570 6. **Reproduce the green baseline in §3.5 before starting new work.** The expected
passing. This thread's whole method depends on a known-green baseline to count is in `CLAUDE.md`'s *Green baseline***not restated here**, and it moved
when S27 landed. This thread's whole method depends on a known-green baseline to
mutate against; if the number differs, reconcile that first. mutate against; if the number differs, reconcile that first.
### 4.3 Then, in priority order ### 4.3 Then, in priority order
**The two threads are independent right now** (§2.6) and can resume in **The two threads are independent right now** (§2.6) and can resume in
parallel. They collide only when T1b opens, since it and P13-S27 both land in parallel. ~~They collide only when T1b opens, since it and P13-S27 both land in
`bundle.rs`. `bundle.rs`.~~ **That collision is gone — S27 landed 2026-08-09.** T1b stays blocked on
versioned decode (§2.3), and a future `epiphany-bundle` rung would create its own
collision.
7. **Spec thread — dispatch P13-S27.** The only unblocked item on the critical path, its 7. ~~**Spec thread — dispatch P13-S27.**~~ **DONE — landed and accepted at `4df8e25`**
contract is complete, and landing it discharges the three inherited after eight independent reviews of the staged execution. It discharged the three
obligations *and* ends the no-canonical-base interval that currently inherited obligations *and* ended the no-canonical-base interval that had
constrains every other piece of bundle work (§1.2). constrained every other piece of bundle work (§1.2).
8. **Editor thread — run Round 2's checks**, whose apparatus is built and 8. **Editor thread — run Round 2's checks**, whose apparatus is built and
whose candidates are wired (§2.2); then Rounds 3, 3b, 4, 5 and the whose candidates are wired (§2.2); then Rounds 3, 3b, 4, 5 and the
`RULING_EDITOR_TOOLKIT.md` verdict. `RULING_EDITOR_TOOLKIT.md` verdict.
9. Then **P13-S16**, dispatchable the moment S27 lands. 9. Then **P13-S16** — **UNBLOCKED as of `4df8e25`, and now the head of the spec track.**
It is **not** dispatchable yet: `spec/CONTRACT_P13S16_PROJECTION.md` is a **DRAFT**
and needs ratification through adversarial review rounds first. **Its first act is
bumping `CURRENT_REDUCTION_ALGORITHM_VERSION` to `1`**, since it changes
`CreateStaffGroup`'s reduction verdict — that is what the authority S27 installed
exists for.
10. Take a ruling on **S8** (reject one spelling vs. keep both canonical) whenever 10. Take a ruling on **S8** (reject one spelling vs. keep both canonical) whenever
convenient — it needs a decision, not an implementation, and blocks nothing in convenient — it needs a decision, not an implementation, and blocks nothing in
the meantime. the meantime.

File diff suppressed because one or more lines are too long