Skip to content

SWG-4A-05: the exact writer is complete - #190

Merged
PhysShell merged 6 commits into
mainfrom
claude/swang-4a05-writer-metadata
Aug 21, 2026
Merged

PhysShell merged 6 commits into
mainfrom
claude/swang-4a05-writer-metadata

Conversation

@PhysShell

@PhysShell PhysShell commented Aug 20, 2026 •

Copy link
Copy Markdown
Owner

SWG-4A-05 — the exact writer is complete

The last slice of the exact writer. It spells the whole remaining frontier —
note marks, note position and its fretboard evidence, technique spans, the
source block, and the loss block — after which write_score refuses for
exactly one reason: the score is outside the writer's domain.

ExactWriteError::NotYetWritten and the temporary check_slice_frontier
walk are removed together, in the same commit that makes them unreachable.
Reintroducing a not-yet-written path is now a compile error, not a test
failure. Level 2 is untouched and unfrozen; Phase 4A is not closed.

Commits (no squash — the order is the evidence)

# commit what
1 1f6c3eb step A red — the writer's musical leaves
2 020587c step B red — strings, source, and loss
3 5aaec8b green — the exact writer is complete
4 4fbe9ce docs closure
5 a65e3a0 review evidence (tests only) — bind the musical matrix to the exact diff
6 a28e630 review docs — closure correction

Commits 5 and 6 come from an independent review of commits 1–4. It found an
evidence gap, not a writer defect: the musical mutation matrix asserted
only that the bytes moved and never that ExactSemanticDiff saw the same
fact, and the span-evidence row moved source and confidence together so
that "a matrix over every added fact" was false by one field. Both are closed
in commit 5 — no production line changed between 5aaec8b and a28e630.

Falsification: twenty writer mutations, none survived

Every row below comes from a single run of all twenty probes against
a28e630, the head of this branch
— the suite as it actually stands, not
as it stood before commit 5 renamed several of its tests. Each probe is
applied to swang/src/exact/write.rs in isolation and the whole
griff-swang suite is re-run. The runner classifies five outcomes and
never infers a catch from a non-zero exit code:

  • CAUGHT — the mutation compiled in and at least one test failed;
  • CAUGHT-BY-COMPILE — the mutation applied and the crate stopped compiling;
  • SURVIVED — the mutation compiled in and every binary reported ok;
  • INVALID PROBE — the file was unchanged, so the result means nothing;
  • NOT REBUILT — cargo reused an older artifact, so the run says nothing
    about the mutation and gets no verdict at all.

None of the twenty landed in the last three states.

# mutation outcome caught by
M1 sort technique_spans CAUGHT span_order_is_visible_to_both_the_diff_and_the_writer, spans_keep_their_vector_order
M2 drop one mark CAUGHT a_marked_note_still_belongs_to_its_group, a_single_mark_keeps_the_note_inline, every_note_leaf_is_one_fact_to_the_diff_and_to_the_writer, marks_are_not_sorted_alphabetically, marks_are_written_in_note_mark_all_order, the_reference_document_is_written_byte_for_byte
M3 alphabetize marks CAUGHT marks_are_not_sorted_alphabetically, marks_are_written_in_note_mark_all_order
M4 drop the position CAUGHT a_note_with_a_position_uses_the_multiline_form, a_position_string_beyond_the_tuning_is_written_not_refused, a_positioned_note_still_belongs_to_its_group, every_note_leaf_is_one_fact_to_the_diff_and_to_the_writer, position_evidence_is_written_without_normalization, the_reference_document_is_written_byte_for_byte
M5 derive the string from the tuning instead of storing it CAUGHT a_note_with_a_position_uses_the_multiline_form, a_position_string_beyond_the_tuning_is_written_not_refused, every_note_leaf_is_one_fact_to_the_diff_and_to_the_writer, the_reference_document_is_written_byte_for_byte
M6 normalize an odd evidence pair CAUGHT every_span_fact_is_one_fact_to_the_diff_and_to_the_writer, position_evidence_is_written_without_normalization
M7 omit Some(SourceMeta { format: None }) CAUGHT a_present_source_without_a_format_is_the_empty_inline_block, the_three_source_states_are_three_documents
M8 spell the empty source as source {} CAUGHT a_present_source_without_a_format_is_the_empty_inline_block, a_source_format_is_escaped, source_metadata_follows_the_transport_it_annotates, the_reference_document_is_written_byte_for_byte, the_three_source_states_are_three_documents
M9 raw-write loss.other.message CAUGHT an_other_warning_message_is_escaped, an_other_warning_stays_one_physical_line
M10 raw-write the track.name call site CAUGHT a_track_name_is_escaped, a_track_name_needing_an_escape_is_written_escaped, characters_just_outside_the_escaped_set_are_written_through, every_enumerated_range_is_escaped_at_both_edges, hex_escapes_are_lowercase_and_unpadded, the_three_named_escapes, the_two_always_escaped_characters
M11 raw-write the source.format call site CAUGHT a_source_format_is_escaped
M12 escape by is_whitespace instead of the enumerated ranges CAUGHT a_track_name_needing_an_escape_is_written_escaped, characters_just_outside_the_escaped_set_are_written_through, every_enumerated_range_is_escaped_at_both_edges, hex_escapes_are_lowercase_and_unpadded
M13 regroup warnings by variant CAUGHT mutating_any_document_level_fact_changes_the_text, warnings_keep_their_vector_order
M14 deduplicate identical warnings CAUGHT duplicate_warnings_are_written_twice, mutating_any_document_level_fact_changes_the_text
M15 truncate a warning u64 through u32 CAUGHT all_four_warning_variants_match_their_canonical_layout, both_payload_indices_are_written_past_u32_max
M16 skip the span TickRange domain check CAUGHT an_inverted_span_tick_range_is_outside_the_writer_domain
M17 clamp a span range to its group CAUGHT a_span_range_outside_its_group_is_written_not_refused, every_span_fact_is_one_fact_to_the_diff_and_to_the_writer
M18 write only the first span CAUGHT every_span_fact_is_one_fact_to_the_diff_and_to_the_writer, spans_keep_their_vector_order
M19 leave a NotYetWritten path reachable CAUGHT-BY-COMPILE the variant no longer exists, so the probe is a compile error
M20 hard-code span confidence to 10000 CAUGHT a_note_with_a_position_uses_the_multiline_form, a_span_confidence_alone_is_one_fact_to_the_diff_and_to_the_writer, every_note_leaf_is_one_fact_to_the_diff_and_to_the_writer, position_evidence_is_written_without_normalization, span_evidence_is_written_without_normalization, the_reference_document_is_written_byte_for_byte

M20 was added during the review round, against the assertions commit 5
introduced.

Three harness bugs found and fixed while running the above

All three are one diagnosis — a check too narrow for the data it runs over
— and each could have reported a false SURVIVED, which is the only
mutation-testing error that matters, because it is the one that reads as
proof.

  1. Missing --no-fail-fast. cargo test stopped at the first failing
    test binary, so the "caught by" column was truncated at whichever suite
    failed first; a mutation caught only by a later binary would have looked
    weaker than it is, and one caught only past the cut could have looked
    uncaught.
  2. The test-name extractor rejected digits. The failure-block parser
    matched ^ [a-z_]+$, which silently dropped every test name
    containing a digit
    — both_payload_indices_are_written_past_u32_max
    among them. A mutation whose only catcher had a digit in its name would
    have been classified SURVIVED. Fixed to ^ [a-z0-9_]+$.
  3. Cargo tested a stale artifact and the runner believed it. Found by
    this rerun, and the reason the rerun was worth doing: M5 came back
    SURVIVED in the batch and CAUGHT when run alone. Cargo decides freshness
    by mtime, and on this container's filesystem two consecutive writes can
    share a timestamp — touch a; touch b; stat returns the same
    nanoseconds — so the restore at the end of one probe and the write at the
    start of the next were indistinguishable to cargo, which then ran the
    previous probe's binary and reported everything passing. Nothing in
    the output betrayed it. Fixed twice over: the mutated file's mtime is
    pushed strictly forward before each run, and the runner now refuses to
    classify any run whose output does not contain Compiling griff-swang —
    an artifact it cannot show was rebuilt gets NOT REBUILT, never SURVIVED.

An earlier pass in this same series had also grepped for the bare word
error, which matches cargo's own error: test failed and turned CAUGHT
mutations into noise; the runner now matches only ^error[ and
^error: could not compile, which is what distinguishes CAUGHT from
CAUGHT-BY-COMPILE.

The published table before this rerun carried outcomes from the earlier
pass, and its "caught by" column still named
mutating_any_span_fact_changes_the_text and
mutating_any_note_leaf_changes_the_text — two tests commit 5 had replaced.
The outcomes held up; the attribution was stale, and stale attribution is how
a table stops being evidence. Independent review caught it. The table above is
regenerated mechanically from the rerun log, and every one of the 35 distinct
test names in it resolves to a #[test] in swang/tests/ at this head.

Checks

  • cargo test -p griff-swang --no-fail-fast at a28e630 — 187 passed, 0
    failed, across 7 binaries.
  • cargo fmt --check and cargo clippy --all-targets clean for the touched
    crates. The full cargo test --workspace cannot run in this environment
    (cockpit/preview/plugin need libalsa); it is left to CI.

Out of scope, deliberately

The parser, griff swang dump, level 2 admission, cli::bar_at_tick, and
any change to ExactSemanticDiff — including making the comparator report
finer paths so the new bound assertions could name a prettier leaf.
NotePosition and TechniqueEvidence are composite canonical fields to the
exact walker on purpose, and the assertions state those coarse paths as they
are.


Generated by Claude Code

claude added 6 commits August 20, 2026 13:45
Tests-only. Eighteen red, one green — and the green one is deliberate: it
pins SWG-4A-04's inline note byte for byte, because this slice must add
`marks [accent]` and `position { … }` without moving a byte of what already
worked.

What the eighteen pin, all decided by the accepted census:

**`marks` is a set.** Canonical order is `NoteMark::ALL`, which is what
`NoteMarks::iter` already yields. Two tests separate that from the orders a
writer reaches for on its own: `ghost` before `dead_note` is `ALL` order and
the reverse is alphabetical, and the same set written from either insertion
order must produce identical bytes. A set has no author order to preserve.

**A note with a position becomes multiline**, in §6.1's exact shape, while a
note without one stays on its line even when marked. The layout follows the
note's own contents, which is the rule §6.2 states for `group` and `source`.

**Eight span techniques, eight distinct spellings**, checked both ways —
`contains` alone would be satisfied by two techniques mapped to one word,
which is a fact the diff reports and the text would lose.

**Slot order versus element order**, §6.2's two rules meeting in one
construct: every atom precedes every span, and within `technique_spans` the
vector order stands unsorted.

**The ugly inhabited states of §3**, written rather than corrected: a
position's string past the end of the tuning, a span's range far outside its
group's atoms, `Explicit` evidence at 0 bps, `InferredFromMidi` at 10 000.
§2.6 is explicit that the source/confidence pairing is not enforced by the
type, so tidying it here would delete a fact an importer recorded.

**§3's sixth clause becomes reachable.** SWG-4A-04 left span tick ranges out
of the domain walk on purpose — the frontier refused spans, so the writer
could not emit one and the clause had nothing to guard. Writing them changes
that, and an inverted span range must now yield `OutsideWriterDomain`
carrying the model's `InvalidTickRange`.

A seventh clause for `ConfidenceBps` is refused with a test saying why: its
field is private and its constructor is the only way in, so the range is
enforced by the type, and adding a check would be the writer inventing
validation §3 forbids.

Refs SWG-4A-05

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE
Tests-only. Nineteen red; three pass and are the baseline this slice must
not disturb — an absent `source` and a clean `loss` are still omitted, and a
name needing no escape is still written through.

Together with step A this is the whole of what SWG-4A-04's frontier refuses.
One GREEN answers both, because the string encoder is shared by `Track.name`,
`SourceMeta.format`, and `ImportWarning::Other`: splitting the implementation
by field would mean holding two theories of quoting at once, and the second
one always disagrees with the first eventually.

## §6.5, walked at every edge

The escaped set is a frozen range list, so the tests walk the edge of every
range from **both sides**. `\u{8}` and `\u{b}` and `\u{1f}` and `\u{7f}` and
`\u{9f}` are escaped; `\u{9}` is escaped but by the *named* rule; space,
`~`, `é`, `中`, `🎸` are written through.

U+00A0 is the load-bearing one. `char::is_whitespace` says yes and §6.5 says
no, so a predicate that escapes it is a Unicode table wearing §6.5's name —
and §1.2 forbids exactly that, because a formatter whose fixed point moves
when the build relinks a newer table does not have one. `escape_default` and
any JSON encoder fail the same test for the same reason.

Lowercase hex, no leading zeros, asserted positively and negatively:
`\u{1f}` and not `\u{1F}`, `\u{b}` and not `\u{0b}`.

One escaping witness per call site, so a correct shared helper cannot hide
one caller that still writes raw.

## `source` and `loss`

Three source states, three documents: absent, `source { }`, and
`source { format "" }`, with the tight and multiline forms refused by name.

All four warning variants against §6.2's exhaustive illustration, byte for
byte. Vector order preserved, duplicates written as duplicates, and both
payload indices exercised past `u32::MAX` — `track_index` at 2^32 and
`bar_index` at `u64::MAX`. SWG-CORE-01 ran before this task so the metadata
writer would be built on the final width; proving it only with small numbers
would have made that ordering pointless.

`other` stays one physical line with three `\n` in its message, which is the
grammar property §6.2 states rather than a hope about the data.

Two tests state the point of writing inaudible facts at all: adding a
`source` or a `loss` leaves `NormalizedMusicalDiff` empty, leaves
`ExactSemanticDiff` non-empty, and must change the bytes.

## The capstone

§6.1's reference document, built in full and compared whole. It is the first
time every part composes — transport, structure, marks, position, span,
evidence, source, loss — with nothing between them out of place.

The small tests stay beside it. One large golden is excellent at reporting
that something broke and admirably modest about what.

Refs SWG-4A-05

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE
Forty-one red tests to green across steps A and B, and the writer stops
being incremental.

## The leaves

`marks` writes through `NoteMarks::iter`, which is `NoteMark::ALL` order —
the only order a set has. A note with a `position` opens across lines and one
without stays on its line however many marks it carries: the layout follows
the construct's own contents, which is the rule §6.2 already states for
`group` and `source`.

`evidence` is one inline block shared by positions and spans, and it writes
both facts as they stand. `Explicit` at 0 bps and `InferredFromMidi` at
10 000 are model-valid (§2.6) and repairing the pair here would delete what
an importer recorded. Nothing checks that a `string` fits the tuning or that
a span's range sits inside its group; §3 lists both as inhabited, and the
writer is not a fretboard validator.

Eight span techniques, matched exhaustively, written after every atom —
§6.2 rule 1 fixing the order *between* slots while rule 2 leaves the order
*within* `technique_spans` alone.

## One string encoder

`quote` serves `track.name`, `source.format`, and `loss.other.message` — the
only three strings in the canonical tree. One encoder rather than three,
because three eventually disagree, and step B has a witness through each call
site so a correct shared helper cannot hide one caller still writing raw.

The escaped set is §6.5's frozen range list and nothing else. U+00A0 is the
character that proves it: `char::is_whitespace` says escape, §6.5 says write
it through, and §1.2 forbids a formatter whose fixed point moves when the
build relinks a newer Unicode table. `escape_default` and any JSON encoder
fail the same test for the same reason.

`lower_hex` is hand-rolled because `format!` into a `String` is denied by
`clippy::format_push_string`, and the alternative — `fmt::Write` into a sink
that cannot fail — would hand back a `Result` there is no honest way to
handle. Masks and shifts, so it cannot divide by zero either.

## `source` and `loss`

Three source states, three documents. The `loss` block is multiline with one
warning per line, in vector order, duplicates included — `LossReport` appends
and concatenates and the exact walker compares positionally, so grouping or
deduping would delete a fact.

## §3's sixth clause finds its second home

SWG-4A-04 left span tick ranges out of the domain walk deliberately: its
frontier refused spans, so the writer could not emit one and the clause had
nothing to guard. Writing them is what made it reachable, and it is checked
now. Six clauses and no seventh — `Tempo` and `ConfidenceBps` keep their
fields private, so their invariants are enforced rather than advisory, and a
check for either would be the writer inventing validation §3 forbids.

## The frontier is gone, and so is its error

`check_slice_frontier` is deleted and `ExactWriteError::NotYetWritten` with
it, now, before SWG-4A-10 — leaving it would make the CLI handle a case that
cannot occur, and then hold a funeral for a dead API later. Level 2 is not
frozen yet, which is exactly why this is the moment.

`ExactWriteError` has one variant, and that is the point: a refusal now means
one thing. Your `Score` breaks an invariant `griff-core` itself declares.

The five tests that guarded `NotYetWritten` are sunset rather than deleted.
Each owned a structural property that outlived the refusal — a marked note
still belongs to its group, a span still follows its atoms, a `source` still
sits after every track — so each keeps that and hands the leaf itself to the
new suites. No 4A-03 or 4A-04 golden changed by a byte, which is the claim
those goldens exist to make.

Locally: 185 swang tests green, clippy `-D warnings` and fmt clean
workspace-wide, `griff-core` untouched.

Refs SWG-4A-05

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE
Docs-only.

## `foundation-backlog.md`

4A-05 marked done, with its acceptance criteria checked off and the one
structural outcome recorded: the exact writer is complete, so
`check_slice_frontier` and `ExactWriteError::NotYetWritten` went with it.
4A-10 is a CLI surface over a finished writer, not another slice of one, and
the lane diagram now says so.

Two acceptance lines are sharpened rather than merely ticked. "Mutating any
one of these fields changes the exact text" names the nineteen writer
mutations behind it; "source and loss do not disappear because they make no
sound" names the triple it actually is — normalized-equal, exact-different,
bytes-different — because the first two thirds of that claim are the easy
part and the third is the one that catches a writer quietly dropping them.

The reference-document golden is listed too. It is the first evidence that
the parts compose rather than merely each working alone.

## `decisions.log.md`

One Y-statement, because removing a public enum variant is a breaking change
and the timing is the decision. `NotYetWritten` becomes unreachable the
moment the writer is complete; keeping it until 4A-10 would make the CLI
handle a case that cannot occur, and an API outlives its meaning more easily
the longer it waits. Level 2 is not frozen yet, which is precisely what makes
now the cheap moment.

Recorded with what makes the removal safe rather than merely tidy: the five
tests that guarded the variant are sunset, not deleted — each kept the
structural property it owned — no earlier byte-golden moved, and the attempt
to reintroduce a `NotYetWritten` path is now a compile error rather than a
test failure.

Refs SWG-4A-05

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE
…diff

Tests-only, green on unchanged production code. An independent review found
an evidence gap, not a writer defect: nothing in `swang/` had to move, and
nothing did.

## The matrix checked half its own contract

The acceptance contract asked, for every remaining canonical fact, for one
mutation satisfying three things at once:

```
controlled Score mutation
    -> ExactSemanticDiff reports the expected path
    AND write_score(before) != write_score(after)
```

The musical half checked only the second. `ExactSemanticDiff` is separately
well covered in `core/tests/semantic_diff.rs`, and that is exactly why the
gap was easy to miss — but two suites agreeing independently is not a
composition witness. Nothing said the fact the writer spells and the fact the
comparator sees are the *same* fact, which is the whole claim.

`assert_observable` now binds them at one mutation, and the twelve musical
rows go through it.

Expected paths are read off the walker, not off its output.
`diff_note` compares `NotePosition` under a single `Position` option leaf and
records the fretboard mismatch inside that scope with no further segment, so
`string` and `fret` both surface at `.position`; `diff_span` compares
`TechniqueEvidence` whole. Those composite fields are deliberate and 4A-05
does not touch the comparator, so the test states the coarse path rather than
proposing a finer one.

Order and cardinality are not forced into one leaf. A swap changes both
elements, so the honest expectation is a difference under each ordinal plus
moved bytes, and that is what the test asserts.

## A fact the matrix silently did not mutate

`mutating_any_span_fact_changes_the_text` claimed a span-evidence row. Its
baseline was `Explicit` at 10 000 and its mutation `InferredFromMidi` at
10 000 — the source moved and the confidence never did. So the closure claim
"a matrix over every added fact" was false by one field.

A standalone row holds the source still and moves 10 000 to 9 999.

## Falsified, not merely passing

- pointing one expected path at a field that does not exist fails the test,
  so the path assertion is doing work rather than matching anything;
- restoring the confidence mutation to 10 000 -> 10 000 fails the new row,
  so it really is the separation and not decoration;
- a twentieth writer mutation, hard-coding `confidence 10000`, is now caught
  by six tests including the new row. Before this commit it would have been
  caught by the goldens alone, and by nothing that named confidence.

Refs SWG-4A-05

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE
…ew found

Independent review found an evidence gap, not a writer defect:

- the musical writer matrix did not bind its mutations to
  `ExactSemanticDiff` — it asserted only that the bytes moved;
- span evidence confidence lacked a standalone mutation, so the claim of
  "a matrix over every added fact" was false by one field;
- a tests-only continuation commit closed both;
- production code unchanged.

The mutation count in the closure line moves from nineteen to twenty: the
review added one more writer mutation (hard-code span confidence to 10000),
and it too was caught.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE
@coderabbitai

coderabbitai Bot commented Aug 20, 2026

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9d8479b3-2733-45ee-a7b5-505c1f9bc77e


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@PhysShell
PhysShell merged commit b3a140c into main Aug 21, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants