Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/decisions.log.md
Original file line number Diff line number Diff line change
Expand Up @@ -2392,3 +2392,36 @@ Architectural decisions go to [`adr/`](adr/) instead.
and any real-/full-corpus labeling remain separately gated (ADR-0033
Decision 10), and any implementation deviation from the accepted contract
reopens acceptance rather than being decided in code.

- 2026-08-18 — In the context of SWG-4A-05 completing the exact writer, facing
an `ExactWriteError::NotYetWritten` variant that had described the writer's
build progress rather than any property of a `Score`, we decided for
**removing it now**, together with `check_slice_frontier`, and against
keeping it until SWG-4A-10 or later, to achieve a refusal that means exactly
one thing — your `Score` violates an invariant `griff-core` itself declares
— and to spare the CLI a match arm for a case that cannot occur. Accepting
that this is a breaking change to a public enum, which is why it is made now
rather than after the level-2 freeze: the variant is unreachable the moment
the writer is complete, and an API that outlives its meaning is harder to
retire the longer it waits. The five tests that guarded it are sunset rather
than deleted — each owned a structural property that survives the
refusal — and no SWG-4A-03 or 4A-04 byte-golden changed, which is what
those goldens exist to say. Verified by nineteen writer mutations, none of
which survived; the attempt to reintroduce a `NotYetWritten` path is now a
compile error rather than a test failure.

- 2026-08-20 — In the context of closing SWG-4A-05, facing an independent
review that found the acceptance evidence weaker than the closure claimed,
we decided for two tests-only continuation commits and against amending the
four already made, to achieve a history where the gap and its repair are
both legible, accepting two more commits on the branch. Two findings, both
in the evidence rather than in the writer — no production line changed. The
musical mutation matrix asserted only that the bytes moved, never that
`ExactSemanticDiff` saw the same fact: the comparator is separately well
covered, and two suites agreeing independently is not the composition
witness the contract asked for. And the span-evidence row moved `source` and
confidence together, so "a matrix over every added fact" was false by one
field. Accepting that the bound assertions state the comparator's *coarse*
paths — `NotePosition` and `TechniqueEvidence` are composite canonical
fields to the exact walker on purpose, and improving the comparator to make
the test prettier would be 4A-05 editing something it was told not to touch.
41 changes: 29 additions & 12 deletions docs/swang/foundation-backlog.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ recorded in `decisions.log.md` if reversed.
| SWG-4A-02 | `ExactScoreDocument` as a transient syntax form | code | 4A-01 |
| SWG-4A-03 | Writer: transport and master timeline | code | 4A-01 |
| SWG-4A-04 | Writer: tracks, voices, groups, atoms | code | 4A-03 |
| SWG-4A-05 | Writer: techniques, positions, evidence, losses | code | 4A-04, CORE-01 |
| SWG-4A-05 | Writer: techniques, positions, evidence, losses *(done)* | code | 4A-04, CORE-01 |
| SWG-4A-06 | Parser skeleton and level/root dispatch | code | 4A-01, INF-04, INF-06 |
| SWG-4A-07 | Parser: exact scalar types | code | 4A-06 |
| SWG-4A-08 | Parser: structural tree | code | 4A-07, 4A-02 |
Expand Down Expand Up @@ -548,22 +548,36 @@ Non-negotiable:
Acceptance is measured by `ExactSemanticDiff`, not by "the MIDI sounds
about right".

### SWG-4A-05 — Writer: techniques, positions, evidence, metadata, losses
### SWG-4A-05 — Writer: techniques, positions, evidence, metadata, losses *(done)*

**Kind:** code. **Depends on:** 4A-04, CORE-01 — both **done**, so this task
is unblocked. CORE-01 ran first so the metadata writer is built on the final
`u64` payload indices rather than rewritten onto them.
**Kind:** code. **Depends on:** 4A-04, CORE-01 — both done before it.
CORE-01 ran first so the metadata writer was built on the final `u64` payload
indices rather than rewritten onto them.

The remaining facts: note marks, technique spans and their ranges, evidence,
The facts it added: note marks, technique spans and their ranges, evidence,
string/fret position, position evidence and confidence (`ConfidenceBps`),
source metadata, import warnings, loss facts.
escaped strings, source metadata, import warnings, loss facts.

Acceptance:
**The exact writer is complete.** This was the last slice, so
`check_slice_frontier` and `ExactWriteError::NotYetWritten` were removed with
it: the writer no longer declines any part of the canonical tree, and its one
remaining refusal is a judgement about the `Score` rather than about itself.
Removing the variant here rather than after 4A-10 spares the CLI a case that
cannot occur.

Acceptance, all met:

- mutating any one of these fields changes the exact text;
- mutating any one of these fields changes the exact text **and** is
reported by `ExactSemanticDiff` at its expected path — one mutation
binding both, over every added fact, plus twenty writer mutations of which
none survived;
- `NormalizedMusicalDiff` may call some of those mutations equal;
`ExactSemanticDiff` must see every one of them;
- source and loss facts do not disappear merely because they make no sound.
- source and loss facts do not disappear merely because they make no sound —
checked as the triple it actually is: normalized-equal, exact-different,
bytes-different;
- §6.1's reference document is produced whole and compared byte for byte,
which is the first proof that every part composes.

### SWG-4A-06 — Parser skeleton and level/root dispatch

Expand Down Expand Up @@ -1202,10 +1216,13 @@ INF-01 status sync (done)
└─→ 4A-01 exact grammar (done)
│
├─→ 4A-03 → 4A-04 → CORE-01 → 4A-05 → 4A-10 writer lane
│ (done) (done) (done) ↑
│ │ next
│ (done) (done) (done) (done) ↑
│ │ next
│ └─→ also gated 4A-12 and the level-2 freeze
│
│ the exact writer is complete at 4A-05; 4A-10 is a CLI
│ surface over it, not another slice of it
│
└─→ 4A-02 → INF-04 → INF-06 → 4A-06 parser skeleton
-> 4A-02..4A-09 writer / parser / builder
-> 4A-10..4A-14 dump / verify / laws / fuzz
Expand Down
9 changes: 5 additions & 4 deletions swang/src/exact.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@
//! This module is the writer half: a canonical `Score` in, one canonical
//! level-2 document out. The parser half arrives later and separately.
//!
//! Written incrementally by slice. SWG-4A-03 covers the header, `ppqn`, and
//! the master timeline; tracks and everything below them are SWG-4A-04 and
//! after, and a `Score` carrying them is refused with
//! [`ExactWriteError::NotYetWritten`] rather than half-written.
//! Built in slices — SWG-4A-03 the transport, 4A-04 the structure, 4A-05 the
//! leaves and metadata — and **complete** since the last of them. There is no
//! part of the canonical tree it declines to spell, so the only refusal left
//! is [`ExactWriteError::OutsideWriterDomain`]: your `Score` breaks an
//! invariant `griff-core` itself declares.

mod error;
mod write;
Expand Down
31 changes: 8 additions & 23 deletions swang/src/exact/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,12 @@ use griff_core::event::ValidationError;

/// A refusal from the exact-text writer.
///
/// The two variants say different things and must not be collapsed. One is
/// a judgement about the `Score`; the other is a statement about how much
/// of the writer exists yet.
/// One variant, and that is the point. While the writer was built in slices
/// this enum also carried `NotYetWritten`, a statement about how much of the
/// writer existed rather than about the score. SWG-4A-05 finished the writer,
/// so that variant described nothing and retired with the frontier it named:
/// a refusal now means exactly one thing, and no caller has to handle a case
/// that cannot occur.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExactWriteError {
/// The `Score` violates an invariant `griff-core` itself declares, so
Expand All @@ -26,30 +29,12 @@ pub enum ExactWriteError {
/// The model's own verdict.
reason: ValidationError,
},
/// The `Score` is perfectly writable in principle; this increment of
/// the writer does not reach that part of the tree yet.
///
/// A slice boundary, never a claim that an inhabited state is
/// unspellable — the census forbids the latter, and reporting a
/// build-stage limit as a domain judgement would smuggle it in.
NotYetWritten {
/// The part of the tree that is still unimplemented.
what: &'static str,
/// The task that will write it.
task: &'static str,
},
}

impl Display for ExactWriteError {
fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
match self {
Self::OutsideWriterDomain { at, reason } => {
write!(f, "{at} is outside the exact writer's domain: {reason:?}")
}
Self::NotYetWritten { what, task } => {
write!(f, "{what} is not written yet; {task} adds it")
}
}
let Self::OutsideWriterDomain { at, reason } = self;
write!(f, "{at} is outside the exact writer's domain: {reason:?}")
}
}

Expand Down
Loading
Loading