Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
2 changes: 1 addition & 1 deletion docs/adr/0029-swang-authoring-and-verified-lifting.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# ADR 0029: Adopt Swang as a deterministic authoring and verified lifting language

Date: 2026-07-14
Status: Proposed
Status: Accepted (Phases 0–3 shipped and frozen, PRs #109–#121; Phases 4–9 remain future work under this decision)
Comment thread
PhysShell marked this conversation as resolved.

## Context

Expand Down
19 changes: 19 additions & 0 deletions docs/decisions.log.md
Original file line number Diff line number Diff line change
Expand Up @@ -1715,3 +1715,22 @@ Architectural decisions go to [`adr/`](adr/) instead.
parameter (its dense-demo cut was excellent but unisolated) and buries
`thin` in favour of the operation that was actually proven — seeded density
pruning, already named by `fractalize density/seed`.

- 2026-07-15 — In the context of closing S16 Phase 3 (PRs #117–#121: the
Swang grammar, canonical formatter, `check | fmt | expand | build`, the
seven §3.5 acceptance laws, and fuzz targets), with a fresh nightly
compiling the previously-excluded `fuzz/` crate for the first time in one
turn, we decided to make the **bounded fuzz smoke plus corpus replay a
blocking CI gate** (an eleven-way matrix per implemented target) rather
than keep deferring the ADR-0010 hard rule, to achieve the robustness
layer the policy always prescribed, accepting that its very first run
reported real findings. It did: F-002 (a `midly` SMPTE-fps negate
overflow, and its second bite through a later `MThd` chunk), F-003 (an
unvalidated direction index inside `guitarpro`, quarantined to
signature-check with written exit criteria), and F-004 (our own
tiny-PPQN/huge-delta OOM — the F-001 family — now bounded by
`MAX_MASTER_BARS`). Each fix ships with a minimized regression seed. The
Swang semantic core (spec §1) and surface grammar (spec §3) are now
**frozen**: further change requires a new language level. ADR-0029 moves
to Accepted for Phases 0–3; Phases 4–9 remain future work, and the next
scope is S8 Swang Playground — the human-facing authoring loop.
18 changes: 14 additions & 4 deletions docs/stages/S16-swang-language-and-verified-lifting.md
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,17 @@ set of rewrite rules makes it useful.

## Phases

### Phase 0 — design contract and golden fixture
**Status:** Phases 0–3 are **shipped, accepted, and frozen** (PRs
#109–#121). The Swang semantic core (spec §1) and surface grammar (spec §3)
are frozen — further change requires a new language level. `griff swang
check | fmt | expand | build` exist and are held to the seven §3.5 laws;
the parser and pattern core are fuzzed on the blocking CI gate. Phases 4–9
(exact score text, patches, structural recognizers, optimizing verified
lift, recipes, script-generating composers, graph/DP recipes) remain future
work under ADR-0029. The next scope is **S8 Swang Playground** — the
authoring loop that lets a human actually play these four verbs.

### Phase 0 — design contract and golden fixture *(done)*

- accept or revise ADR-0029; land `docs/swang/spec.md` and **freeze its
semantic core by this phase's acceptance** — until then it is Proposed,
Expand All @@ -278,7 +288,7 @@ set of rewrite rules makes it useful.

No generation behavior changes.

### Phase 1 — pure pattern core (`griff-pattern`)
### Phase 1 — pure pattern core (`griff-pattern`) *(done)*

Add domain-neutral primitives, std-only:

Expand Down Expand Up @@ -312,7 +322,7 @@ Acceptance:
`swang-prune-hash-v1` vectors; property tests over depth, shape, pruning,
and degenerate inputs.

### Phase 2 — pattern-to-rhythm vertical slice
### Phase 2 — pattern-to-rhythm vertical slice *(done)*

Map `ActivitySequence` into placed `(offset, duration)` `RhythmTemplate`
values, cut per bar with an explicit tail policy, and feed them through the
Expand Down Expand Up @@ -356,7 +366,7 @@ Acceptance (the full list lives in the spec):
This is the stage's killer demo: a fractal kernel audibly realized through
the unchanged generator, reproducible from a one-line delta.

### Phase 3 — minimal Swang parser and canonical formatter
### Phase 3 — minimal Swang parser and canonical formatter *(done)*

The grammar covers only what the Phase 2 killer demo **audibly earned**
(spec §3, the closure verdict on #116): `pattern`, `ascii`,
Expand Down
18 changes: 9 additions & 9 deletions docs/swang/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ Decision: [ADR-0029](../adr/0029-swang-authoring-and-verified-lifting.md).
Delivery plan: [S16](../stages/S16-swang-language-and-verified-lifting.md).

This document is normative. It is split by stability, and the split is the
point: the **semantic core** below freezes when S16 Phase 0 is accepted —
from that point, changing anything in it requires a new language level —
while the surface grammar stays explicitly unstable until S16 Phase 3
closes, and the transport syntax is a temporary experiment contract, not
early grammar.
point: the **semantic core** froze when S16 Phase 0 was accepted — from that
point, changing anything in it requires a new language level — and the
**surface grammar** froze when S16 Phase 3 closed (PRs #117–#121, the seven
§3.5 acceptance laws proven and fuzzed). The transport syntax was a
temporary experiment contract, now superseded by §3.

Status of each section:

| Section | Stability |
|---|---|
| 1. Proposed semantic core | **Proposed; freezes at Phase 0 acceptance.** After that, changes require a new language level. |
| 2. Experimental transport syntax | Temporary Phase-2 contract; superseded by §3 once Phase 3 closes. |
| 3. Surface grammar | **Unstable until Phase 3 closes.** Records only operators that earned syntax by audible demo. |
| 1. Semantic core | **Frozen (Phase 0 accepted).** Changes require a new language level. |
| 2. Experimental transport syntax | **Superseded** by §3 at Phase 3 closure; retained as historical record of the Phase-2 contract. |
| 3. Surface grammar | **Frozen (Phase 3 closed).** The operators the audible demo earned; changes require a new language level. |
| 4. Deferred research | No promised names, no promised semantics. |

## 1. Proposed semantic core
Expand Down Expand Up @@ -445,7 +445,7 @@ griff generate seed.gp5 out.mid \
16. Artifact fingerprints equal `rhythm_diagnostics` fingerprints for the
same templates.

## 3. Surface grammar (unstable until Phase 3 closes)
## 3. Surface grammar (frozen — Phase 3 closed)

Every construct below **earned its syntax through the Phase 2 killer demo**
(the DGD fractal riffs, review verdict on #116's closure): nothing here is
Expand Down
Loading