@a2ml-metadata launcher header: ship a compat reader before converting mint (ruled 2026-09-22)

[hyperpolymath]

Owner-ruled 2026-09-22: compat reader first, then convert. Recorded here with acceptance
criteria so the sequencing is not lost.

Why this one is not like D73-C

PR #36 converted launcher-standard to a praxis DEED. That file is read only by this crate,
so a hard switch was safe.

The @a2ml-metadata block is different in kind. It is emitted into every launcher by
templates/launcher.sh.tera and parsed back by crates/launcher-common/src/metadata_block.rs —
so it is a wire format shared between mint and realign. A hard cutover does not break a
build; it strands every launcher already minted on disk, silently, until someone re-mints it.
That is why #36 deliberately left it alone and named it as deferred rather than missed.

The two phases, in this order

Phase 1 — realign accepts both. Teach metadata_block.rs to parse the existing
# @a2ml-metadata begin … end block and a new deed-shaped block. Ship this alone and let
it reach installed copies. mint is untouched and keeps emitting the old form.

Phase 2 — mint switches. Only once phase 1 has baked, change the template to emit the new
form. On-disk launchers then migrate naturally on their next realign, because the reader from
phase 1 still understands what they carry.

Shipping these together is the failure mode: a launcher minted before the change meets a binary
that no longer reads it.

⚠ The fixture must be captured BEFORE mint changes

The whole test rests on one artefact: a launcher minted by the current mint, committed as a
fixture. Capture it after phase 2 and you are asserting the new emitter against the new parser —
which passes regardless of whether backwards compatibility survived. That is the
generate-then-compare blindness: when generation and comparison share a predicate, a mutation in
it cancels itself out and the mutant survives both kills.

So: commit the fixture first, in its own commit, before a line of either phase lands.

Acceptance criteria

• A launcher minted by today's mint is committed as a fixture, in a commit that changes
  nothing else, before either phase begins.
• Phase 1 ships alone. metadata_block.rs parses that fixture and a deed-shaped block;
  a test asserts both, and a test asserts the old fixture specifically.
• Phase 1 does not change templates/launcher.sh.tera. Verify with git diff --name-only.
• Phase 2 changes the emitter. The phase-1 fixture test still passes unchanged — if it
  needed editing to pass, backwards compatibility was broken and the edit hid it.
• A round-trip test: mint → parse → realign → parse, on both forms.
• Mutant kill: revert the compat branch of the reader and confirm the old-fixture test goes
  red. A green suite proves nothing here until that mutant dies.

Not in scope

The per-app <app>.launcher.a2ml config (config.rs, discovery.rs, cmd_config.rs) is a
separate surface tracked as hyperpolymath/standards#960 and ruled to be picked up next — do not
fold it into this. docs/ruleset-audit-2026-04-10/ and docs/compliance-audit-2026-04-10.adoc
are dated audit records and stay as written.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo

[hyperpolymath]

Phase 2 is open as #46 — mint now emits the DEED block

Phase 1 (the compat reader) and #43 (the pre-phase fixture) are in. #46 converts
the emitter.

What it turns on. The compliance data is byte-identical across the two
dialects, so this is a pure dialect change — which is what makes the strongest
available test possible: the new emitter's flattened output is asserted equal
to the committed pre-phase fixture's, field for field, rather than merely
"the new block parses".

Two questions this phase had to answer, both settled by measurement rather
than assumption:

1. The :standards claim. Flagged as a possible AC4 currency-gate failure,
   since D73-C moved the standard to .deed. Measured:
   docs/UX-standards/launcher-standard.adoc still exists on standards main
   (it was the .a2ml that was deleted), and
   scripts/check-launcher-standard-currency.sh:34-37 states verbatim that it
   is "a DIFFERENT document … deliberately NOT checked here." The emitted
   block is correct and the gate exempts it by design. No owner ruling needed.

2. config set breaks on every newly-minted launcher. rewrite_scalar
   refuses a DEED form in place, so this is an observable CLI behaviour change.
   Put to the owner and ruled: leave it refusing — a deed block is a
   generated artefact, the config file stays the single source of truth, and
   re-mint is the only edit path. Zero new code.

Four mutants killed, and mutant D found a real hole: the
"both dialects agree" test builds its legacy leg from the deed the emitter
just produced, so it is structurally blind to any change that moves both legs
at once. It proves the transform, never the value. The cure is the two
committed fixtures — one captured before the change, one during — neither
derived from the other, both captured from the real emitter.

⚠ This repo has no Rust CI (#45), so the local cargo test --workspace
result (83 passed, 0 failed) is the evidence for #46. Stated as what is not
proven in CI, not as coverage.

Still open under this issue after #46: the .deed descriptor migration
itself (the owner's AC2 ruling under standards#960 — migrate all 21 descriptors),
which is gated behind this work and needs its own design issue: a .deed
filename is a closed dispatch set of four, so <app>.launcher.deed is not an
available name, and the descriptors are TOML-shaped while the deed grammar
admits no key = value and no [section]. That is a rewrite, not a rename.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo

[hyperpolymath]

Assessment against all six acceptance criteria

Phase 2 landed via #46 (squash 552ecf4). Each criterion below was checked
against the repository, not against the PR descriptions.

Verdict: 5 of 6 met. Criterion 1 is violated procedurally; its substance held.

#	criterion	verdict
1	fixture minted by today's mint, in a commit that changes nothing else, before either phase	❌ violated procedurally — see below
2	phase 1 ships alone; parses the old fixture and the deed; a test asserts both, and one asserts the old fixture specifically	✅ the_committed_legacy_fixture_still_parses
3	phase 1 does not change templates/launcher.sh.tera	✅ #43's diff is 3 files, none the template
4	phase 2 changes the emitter; the phase-1 fixture test still passes unchanged	✅ — proven byte-identical, see below
5	round-trip mint → parse → realign → parse on both forms	✅ 6 round_trip tests
6	mutant kill: revert the compat branch, the old-fixture test goes red	✅ executed, see below

Criterion 1 — what actually happened

The criterion asked for the fixture to land alone. It did not: #43
(f323fdc) bundled the fixture (471 lines) together with all of phase 1 —
metadata_block.rs (512 lines) and round_trip.rs (198 lines) — in one commit.

This cannot be retroactively cured; the commit is in history.

The substance the criterion exists to protect did survive, and that is
checkable independently: templates/launcher.sh.tera was untouched from #27
(a93e59f) through #43, so the committed fixture is a genuine
pre-phase-2 artefact of the old emitter, not a string written to match the new
parser. the_deed_emitter_agrees_with_the_legacy_fixture_on_every_value
corroborates it from the other direction.

Recording the gap rather than quietly scoring it green: the guarantee is now
inferred from the template's history instead of being structural in the
commit, which is weaker, and a future fixture should land in its own commit.

Criterion 4 — why "84 tests pass" would have been the wrong check

round_trip.rs moved 199 lines (140+/59−) across the #46 squash, and its
phase-1 tests were renamed and inverted:

• ..._for_the_legacy_form → ..._for_the_deed_form
• phase_one_mint_emits_the_legacy_markers_and_not_the_deed_ones
  → phase_two_mint_emits_the_deed_markers_and_not_the_legacy_ones
• helper as_deed_script → as_legacy_script

A green suite would therefore have "satisfied" criterion 4 falsely — those are
the emitter-assertion tests, and inverting them is legitimate for phase 2, but
they are not the test the criterion names.

The actual phase-1 fixture test lives in metadata_block.rs, and its region
is byte-identical across the squash (diff -u empty). That file's only
changes are one widened .context() string and one added test:

-    let block = parse_from_text(text)?.context("no @a2ml-metadata block found in input")?;
+    let block = parse_from_text(text)?
+        .context("no launcher metadata block (@launcher-deed or @a2ml-metadata) found in input")?;

So criterion 4 is met in the strict sense it was written in.

Criterion 6 — the mutant kill, executed

Not asserted from a passing suite. The compat branch was actually disabled —
metadata_block.rs line 170 replaced with
let legacy: Option<(usize, usize)> = None; // MUTANT:

11 failed / 62 passed
  the_committed_legacy_fixture_still_parses ......................... FAILED
  the_deed_emitter_agrees_with_the_legacy_fixture_on_every_value .... FAILED
  rewrites_scalar_in_place .......................................... FAILED
  validates_required_keys ........................................... FAILED

Restored via git checkout --; worktree clean; suite green again at 84/84.
The named fixture test dies when the compat branch dies, so it is load-bearing
rather than vacuous.

Current state

cargo test --workspace at 552ecf4: 84 passed, 0 failed —
73 unit (launcher-common) + 5 deed_corpus + 6 round_trip.

⚠ These 84 tests have never run in CI — #45 (no workflow builds or tests the
Rust crates) is still open, so every number above is from a local run.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo