docs: S16 Swang — pattern-first roadmap, ADR-0029, and the proposed semantic core

[PhysShell]

Summary

Formalize S16: Swang language and verified lifting as Griff's deterministic musical authoring and decompilation roadmap — reworked after the full design interview on #108 and rebased over the merged theme work (#110, #112).

What changed since the first cut

• ADR renumbered to 0029 — ADR-0028 belongs to the merged ui-core theme; its missing index row is added on the way. The ADR gains the prior-art section the repo's rules require (four surveys: TidalCycles/Strudel, alphaTex, COSIATEC/Decomposer, bounded-DSL design — with scoped claims and UPIC as the contrasting fixed-axis design).
• Pattern-first phase order. The first implementation phases prove the risky hypothesis (a fractal kernel through the unchanged S6 generator into an audible riff) before any parser exists. Canonical score text moves behind the vertical slice.
• docs/swang/spec.md — the normative semantics, split by stability: a proposed semantic core — frozen at Phase 0 acceptance — (language levels, determinism law, units, layered budgets, kernel/traversal/time-slot semantics, swang-prune-hash-v1, rhythm-override precedence, independent seeds, the expansion artifact) versus an explicitly temporary Phase-2 CLI transport syntax with sixteen acceptance tests. The grammar is deliberately absent until the operators survive contact with a real riff.
• Glossary §0 stays canonical. The earlier cut switched roadmap canonicality to docs/stages/; that was a constitutional amendment hiding in a docs PR. Reverted: S15/S16 are added to §0 instead, SPEC points back at §0, AGENTS routing catches up to S0…S16.
• Fractal lifting demoted from a promised phase to a deferred research candidate with an explicit admission bar (L-system inference from a single terminal string is unsolved; lifter hierarchy comes from pattern-class covers / straight-line grammars).
• Two crates: griff-pattern (std-only structural algebra) + griff-swang (AST, parser, lowering); griff-core never depends on either.
• Decisions log records the constitution repair and the verification posture (proptest + golden vectors + fuzz now; non-blocking Kani later; no Verus).

Developer impact

• documentation only; no runtime or generation behavior changes;
• no new crate, parser, score type, or dependency yet;
• TonalContext Phase 1 remains frozen; no automatic tonal policy enters through Swang.

Validation

• branch updated from main after Cockpit band legibility, plus the CI gate that should have caught it #110/ADR-0028: one palette, two renderers, contrast asserted #112 merged; ADR index now carries both 0028 (theme) and 0029 (Swang);
• cross-links checked: ADR ↔ stage doc ↔ spec ↔ glossary §0;
• no stale ADR-0028-as-Swang or S0…S14 references outside append-only history.

Refs #108

🤖 Generated with Claude Code

https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM

Summary by CodeRabbit

• New Features

  • Added roadmap documentation for stages S15 and S16.
  • Introduced the proposed Swang language specification, including deterministic authoring, bounded evaluation, diagnostics, rhythm mapping, and verified lifting.
  • Added a stage plan covering executable musical text and score verification.

• Documentation

  • Updated architecture records, specifications, glossary entries, routing links, and decision logs to reflect the expanded roadmap.
  • Documented planned verification checks and deferred CI harness work.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR extends the documented roadmap through S16 and adds ADR, stage, glossary, process, and normative specification documentation for Swang deterministic authoring and verified lifting.

Changes

Swang S16 roadmap and specification

Layer / File(s)	Summary
Canonical roadmap and stage references AGENTS.md, README.md, docs/SPEC.md, docs/glossary.md	Roadmap references now cover S0–S16, with S15 and S16 glossary entries and a rule requiring executable musical text to lower into and verify against the canonical score model.
Architecture decision and verification records docs/adr/0029-..., docs/adr/README.md, docs/decisions.log.md, docs/process-backlog.md	ADR-0029 defines Swang’s architecture, semantics, lifting modes, and constraints; related index, decision, and backlog records are updated.
S16 stage implementation plan docs/stages/S16-swang-language-and-verified-lifting.md	The S16 proposal documents language layers, deterministic bounded execution, verified lifting, phased implementation, controls, acceptance criteria, and non-goals.
Normative Swang language specification docs/swang/spec.md	The specification defines language levels, deterministic semantics, budgets, diagnostics, pattern traversal, rhythm mapping, CLI transport, artifacts, and acceptance tests.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• PhysShell/griff#103: Adds the S15 tonal-context stage and related roadmap ownership updates.

Suggested reviewers: claude

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the doc-only S16 Swang roadmap, ADR-0029, and semantic-core additions.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/s16-swang-verified-lifting

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: da5c6a7c17

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 8

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/adr/0029-swang-authoring-and-verified-lifting.md`:
- Around line 33-36: Update the prior-art survey count in the ADR introduction
to avoid claiming exactly four surveys when the section covers additional
distinct areas such as UPIC and Euclidean rhythms. Replace “four surveys” with
“several surveys” or revise it to enumerate the exact count and grouping
consistent with the section contents.
- Around line 18-22: Update the source-structure discussion in the ADR to
distinguish flattened MIDI from Guitar Pro: describe repeat markers and
alternate endings as preserved Guitar Pro notation that can be lifted directly,
while reserving the program-synthesis classification for constructs genuinely
absent from the input. Adjust the verification statement accordingly without
changing the broader verified-lifting model.

In `@docs/glossary.md`:
- Around line 121-127: Update the S16 glossary entry to clarify that S1/S3/S6
are only the core dependencies, or align its dependency summary with the full
set documented in the S16 stage page, including S2, S4, and conditional S15.

In `@docs/process-backlog.md`:
- Around line 17-19: Revise the “a pruned parent yields no active descendants”
backlog wording to avoid claiming that proptest proves or pins the semantics.
State that proptest currently exercises or guards the invariants, and retain
that Kani is planned for stronger bounded verification.

In `@docs/swang/spec.md`:
- Around line 278-303: Complete the Phase-2 budget contract by defining whether
fractal depth, cell limits, and lowering limits are required CLI flags or
supplied by a versioned frontend profile. Update docs/swang/spec.md at lines
278-303 to document every required flag or default, and align
docs/stages/S16-swang-language-and-verified-lifting.md at lines 300-315 so its
transport example and acceptance criteria use the same contract.
- Around line 24-31: Expand the first-line language-level section in the Swang
specification with a normative header example and precise lexical rules: define
the exact tokens, permitted whitespace, encoding, and line termination. Specify
pre-parser behavior for missing or duplicate headers, including deterministic
rejection, while preserving the frozen, first-line-only parsing contract.
- Around line 147-149: The canonical conversion rule must be defined in
docs/swang/spec.md lines 147-149: specify whether transport uses integer basis
points or an exact decimal-to-basis-points conversion, including serialization
and rounding behavior. Apply that same rule to the temporary CLI example in
docs/swang/spec.md lines 287-295, replacing ambiguous 0.8 usage, and update the
stage example and acceptance contract in
docs/stages/S16-swang-language-and-verified-lifting.md lines 307-315 to use and
verify the identical deterministic representation.
- Around line 205-216: Define the normative bar geometry for map_rhythm in
docs/swang/spec.md, binding bar length and meter to the canonical master
timeline or requiring explicit geometry input and recording it in the expansion
artifact. Align the Phase-2 vertical slice in
docs/stages/S16-swang-language-and-verified-lifting.md with that same source;
both sites must use one consistent geometry definition.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8175131f-5cf5-4910-9567-3a397f4ddf93

📥 Commits

Reviewing files that changed from the base of the PR and between c0f1d41 and da5c6a7.

📒 Files selected for processing (10)

• AGENTS.md
• README.md
• docs/SPEC.md
• docs/adr/0029-swang-authoring-and-verified-lifting.md
• docs/adr/README.md
• docs/decisions.log.md
• docs/glossary.md
• docs/process-backlog.md
• docs/stages/S16-swang-language-and-verified-lifting.md
• docs/swang/spec.md

[PhysShell]

Architecture review: changes requested before merge

The pattern-first structure, crate split, rhythm-override seam, honest residual model, and demotion of fractal lifting are all materially better than the first cut. The Decomposer reference also supports the stated reconstruction-vs-readability failure mode.

The PR is not merge-ready yet. Codex and CodeRabbit currently have ten unresolved review threads; I verified the major ones as valid. Please address those, plus the two additional contract issues below.

Blocking semantic issues

1. swang-prune-hash-v1 is not fully specified and overclaims injectivity.

   • A 64-bit incremental state cannot be an injective encoding of arbitrary u32 child-index sequences. The canonical path serialization can be injective; its u64 hash cannot promise collision freedom.
   • Separate encode_path(...) -> bytes from hash64(...) -> u64, or retain the fold but explicitly allow collisions and describe their only consequence (correlated keep decisions).
   • Define the structural child-index order independently of traversal.
   • Specify the exact threshold(decay_bps, depth) formula, scale into the u64 comparison domain, floor points, and edge behavior. Golden vectors cannot substitute for a missing normative algorithm.

2. The “frozen semantic core” is not yet closed.

   • The forever-frozen first-line language-level syntax is unspecified.
   • Diagnostic codes remain placeholders (SWG____).
   • Either define the exact header bytes/tokens/UTF-8/BOM/whitespace/EOL/duplicate-header rules now, or mark this section Proposed until Phase 0 closes rather than Frozen.

3. map_rhythm lacks normative bar geometry.

   • Bind PPQN, meter, and bar length to the canonical master timeline used by griff generate, or make them explicit inputs.
   • Record that geometry in the expansion artifact.
   • Define the v0.1 rule when unit does not divide a bar exactly. The simplest contract is a typed error; otherwise note slots can cross bar boundaries and the stated one-bar RhythmTemplate mapping becomes ambiguous.

4. The density-decay transport is ambiguous.

   • Semantics use DensityBps, while examples use 0.8.
   • Prefer --rhythm-density-bps 8000, or specify an exact decimal grammar and decimal-to-bps conversion with no binary float and no implicit rounding.

5. Phase-2 budgets are incomplete.

   • State which limits are required CLI flags and which come from an explicit versioned frontend profile.
   • Cover both structural (max_depth, max_cells) and lowering limits (max_events, min_duration, max_polyphony).

Cross-document corrections

• Remove bars = 4 from the L1 map_rhythm example, or define it. The normative spec says bar count rotates the produced palette outside mapping and never fits/stretches it.
• The claimed v0.1 operator roster includes repeat, rotate, mirror, mask, quantize, and euclid, but their semantics and delivery phase are absent. Call this a candidate roster or reduce v0.1 to operators actually specified and scheduled.
• Distinguish structure preserved by Guitar Pro (for example repeat markers/alternate endings) from structure genuinely absent and requiring synthesis.
• Align S16 dependencies between glossary §0 and the stage header.
• Replace the exact “four surveys” count or make the grouping explicit.
• Reword the process backlog: proptest/goldens/fuzzing exercise invariants; they do not prove them.

Once these are resolved, the architecture is suitable to merge and open Phase 0/1. CI is currently green on da5c6a7c1790a8ca32592092dcef9d6f72d6a21d; the remaining work is contract closure, not implementation behavior.

[PhysShell]

Review fixes landed in f4d510e — thread-by-thread map:

Architecture blockers (comment 4971565841):

1. prune-hash underspecified / injectivity overclaim → spec §1.8 rewritten: the injective thing is the canonical path serialization (structural child order row × width + col, traversal-independent); the 64-bit fold is a hash that may collide, sole consequence a shared keep/prune decision. Full normative algorithm now stated: mix64 (Stafford Mix13, constants inline), DOMAIN = u64::from_le_bytes(*b"swangpr1"), GAMMA, key chain, and the constant per-node threshold floor(decay_bps × 2^64 / 10000) in u128 — cumulative decay is emergent from the empty-subtree law, so no depth term exists to underspecify. Edge laws at 0 and 10000 stated. Golden vectors demoted to illustrations; the algorithm is normative. ADR §6 wording aligned.
2. "frozen" core that isn't → both honest options taken at once: the header grammar is now byte-exact (swang SP level, UTF-8 no BOM → SWG0003, LF or CRLF, 64-byte pre-parser limit, no leading anything, later swang lines are content), and section 1 is restyled Proposed — freezes at Phase 0 acceptance, matching the ADR's own status. Stage Phase 0 wording updated to match.

Automated threads:

• header syntax (Codex P2, CodeRabbit major) → see above.
• SWG____ placeholders → real append-only registry opened: SWG0001–SWG0003 (header/level/BOM), SWG0101–SWG0103 (kernel), SWG0201–SWG0202 (budgets), SWG0301–SWG0304 (mapping incl. meter change).
• S16 dependency mismatch (glossary vs stage) → glossary now reads S1/S2/S3/S4/S6, building on S13/S14 and S15-once-accepted.
• bar geometry undefined → spec §1.11: PPQN/meter bind to the canonical master timeline of the seeded score; v0.1 requires constant meter (SWG0304); slots_per_bar must divide exactly (SWG0301) so a slot never crosses a bar; geometry recorded in the artifact (§1.14).
• DensityBps vs 0.8 → integer transport end to end: --rhythm-density-bps 8000, fractalize(density_bps = 8000); no decimal grammar exists to get rounding wrong.
• Phase-2 budget contract → spec §2.2: --rhythm-fractal-depth required (exact depth doubles as max_depth), --rhythm-max-cells optional with a documented frontend default of 4096 (library still has none), time-domain limits satisfied by construction (monophonic, one-unit slots, events ≤ cells) until an operator can violate them.
• GP flattened to MIDI → ADR context now distinguishes notated repeats/alternate endings (lift as recorded facts per ADR-0022) from the genuinely absent constructs that require synthesis.
• "four surveys" count → kept four, grouping made explicit ("grouped by theme, not one bullet per survey").
• proptest-as-proof → backlog reworded: proptest/goldens exercise invariants; Kani is the step up when semantics freeze.
• map_rhythm(bars = 4) → removed; a note explains --bars rotates the palette outside the mapping.
• v0.1 roster inflation → split into specified-and-scheduled (fractalize, linearize, map_rhythm, thin) and a candidate roster with no promised semantics or phase (repeat rotate mirror mask quantize euclid); ADR's euclid mention now says "candidate".

🤖 Generated with Claude Code

https://claude.ai/code/session_01NkqJUU6d1sW1RAfvyHrqVM