From 7b1e0a40b31626226d80ae3e7c76f84443e7ab8c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 20 Aug 2026 13:01:55 +0000 Subject: [PATCH] docs(swang): pin the byte layout of the loss block before 4A-05 writes it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docs-only, one commit, one file, one section. No grammar vocabulary, no writer domain, no diagnostics, no code. §6.1's reference document shows exactly one warning — `tempo_approximated`, inline. The other three variants are named by §2.8 and listed by §6.4, but their outer layout was never shown anywhere, so the slice that has to emit them would have had to guess. That is the same gap that let SWG-4A-03 write a `repeat` across four lines where §6.1 spells it on one, and it is cheaper to close now than to discover from a byte-golden afterwards. Settled in §6.2, beside the empty-body rule it belongs with: - `loss` is multiline when the report is non-clean, omitted entirely when it is clean; - one warning is one physical line; - `track_name_invalid_utf8`, `tempo_approximated`, and `other` are inline payload blocks; `smpte_timing_unsupported` is a bare word with no block. With an illustration exhaustive over all four variants, at §6.1's nesting. Two things stated because they are the ones a writer gets wrong: - warning order is vector order, preserved exactly (§2.7). `LossReport` appends and concatenates, the exact walker compares positionally, and duplicates are duplicates. Nothing sorts, groups by variant, or dedupes; - `other` stays one physical line whatever its message holds. A U+000A in the value is `\n` under §6.5's frozen escape policy, never a real line break — so "one warning, one line" is a property of the grammar rather than a hope about the data. The illustration is deliberately not folded into §6.1. That reference stays a single coherent score: its one `tempo_approximated` belongs to the `tempo 100/7` bar above it, and three unrelated warnings bolted on would make it less readable while adding nothing this block does not already say. Refs SWG-4A-05 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_018vdRzztKXy8bA16tEzwgLE --- docs/swang/exact-score-text.md | 48 ++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/swang/exact-score-text.md b/docs/swang/exact-score-text.md index 26858264..eab80f20 100644 --- a/docs/swang/exact-score-text.md +++ b/docs/swang/exact-score-text.md @@ -810,6 +810,54 @@ clean, so it is never written with no warnings in it. No diagnostic code is assigned to the alternative whitespace in either case; that is parser territory and belongs to the task that writes the parser. +#### The `loss` block and its warnings + +§6.1's reference document shows one warning, `tempo_approximated`, inline. +The other three are named by §2.8 and §6.4 but were never shown, so their +outer layout was left to be guessed — the same gap that let a `repeat` be +written across four lines where §6.1 spells it on one. Settled here, before +the slice that has to emit them: + +```text +loss + outer layout multiline when the report is non-clean + omitted entirely when it is clean + +warning element one warning, one physical line + + track_name_invalid_utf8 inline payload block + smpte_timing_unsupported bare word, no block + tempo_approximated inline payload block + other inline payload block +``` + +Exhaustive over the four variants, at the nesting §6.1 uses: + +```text + loss { + track_name_invalid_utf8 { track_index 4294967296 } + smpte_timing_unsupported + tempo_approximated { bar_index 1 nearest_micros 4200000 } + other { message "example" } + } +``` + +Warning order is vector order and is preserved exactly (§2.7): `LossReport` +appends and concatenates, the exact walker compares positionally, and +duplicates are duplicates. Nothing here sorts, groups by variant, or +deduplicates. + +`other` stays one physical line whatever its message contains. A U+000A in +the value is written `\n` under §6.5's frozen escape policy, never as a real +line break — so "one warning, one line" is a property of the grammar rather +than a hope about the data. + +The illustration above is not folded into §6.1's reference document, which +stays a single coherent score: its one `tempo_approximated` belongs to the +`tempo 100/7` bar above it, and three unrelated warnings bolted on would +make the reference less readable while adding nothing this block does not +already say. + Everything else is written every time — including `tuning []` on a track with no tuning and `marks []` on a note with no marks. `ppqn`, `index`, `ticks`, `meter`, `tempo`, `channel`, `tuning`, `id`, `at`, `duration`,