Brummel
e3b0dd20c5
New top-level section '## Roundtrip Invariant' between Decision 11 and '## Mangling scheme'. States both directions of the .ail.json ↔ .ailx bijection, names Float-bits-hex encoding as the in- invariant mechanism (not an exception), lists the four enforcement tests by path, and explains why the property is top-level (load-bearing on language identity, not on Decision 6's surface- design rationale). Decision 6 Constraint 2 rewritten as upward cross-reference to the new section; the substantive content now lives at the anchor. Direct boss edit (no planner/implement dispatch): spec Architecture #1 fully specified the content, no design judgement deferred to execution. The iter is a deterministic projection of the spec onto DESIGN.md prose.
72 lines
2.9 KiB
Markdown
72 lines
2.9 KiB
Markdown
# iter rt.2 — Roundtrip Invariant anchored at top level in DESIGN.md
|
|
|
|
**Date:** 2026-05-12
|
|
**Started from:** b6046bbf (post-rt.1, working tree clean)
|
|
**Status:** DONE
|
|
**Tasks completed:** 1 of 1
|
|
|
|
## Summary
|
|
|
|
DESIGN.md gains a new top-level section `## Roundtrip Invariant`,
|
|
positioned between Decision 11 and `## Mangling scheme`. The
|
|
section states both directions of the `.ail.json` ↔ `.ailx`
|
|
bijection, names the Float-bits-hex encoding as the mechanism
|
|
that keeps Floats *inside* the invariant, lists the four
|
|
enforcement tests by path, and explains why the property is
|
|
top-level (load-bearing on language identity, not on Decision 6's
|
|
surface-design rationale).
|
|
|
|
Decision 6 Constraint 2 is rewritten as an upward cross-reference
|
|
to the new top-level section. The substantive content of the
|
|
constraint now lives at the anchor; Decision 6 records that its
|
|
surface design must satisfy the anchored invariant.
|
|
|
|
## Why boss-direct edit (no planner / implement dispatch)
|
|
|
|
The spec's Architecture #1 fully specified the content (statement
|
|
both directions, Float-mechanism subsection, enforcement-points
|
|
list, why-top-level justification, Decision 6 cross-reference).
|
|
No design judgement was deferred to execution time; the iter is a
|
|
deterministic projection of the spec onto DESIGN.md prose. Plan +
|
|
implement dispatch for a pure docs edit with all content
|
|
pre-specified is overhead without value, per CLAUDE.md "trivial
|
|
mechanical edits" carve-out (the LOC budget is exceeded but the
|
|
judgement budget is zero).
|
|
|
|
## Files touched
|
|
|
|
- `docs/DESIGN.md`:
|
|
- Inserted new `## Roundtrip Invariant` section (Z. 1753+, just
|
|
before `## Mangling scheme`).
|
|
- Rewrote Decision 6 Constraint 2 (Z. 249-253) as an upward
|
|
cross-reference to the new section.
|
|
|
|
## Verification
|
|
|
|
`cargo test --workspace` — all tests green, no regressions. The
|
|
schema-drift tests in `crates/ailang-core/tests/design_schema_drift.rs`
|
|
scan DESIGN.md for anchors and were the most likely place for the
|
|
DESIGN.md edit to surface false-positive failures; they remain
|
|
green.
|
|
|
|
## Milestone status
|
|
|
|
The roundtrip-invariant milestone has now satisfied acceptance
|
|
criteria 1-7 from `docs/specs/2026-05-12-roundtrip-invariant.md`:
|
|
|
|
1. ✓ Top-level `## Roundtrip Invariant` section in DESIGN.md;
|
|
Decision 6 Constraint 2 carries upward cross-reference. (rt.2)
|
|
2. ✓ `every_ailx_fixture_matches_its_json_counterpart` dynamic in
|
|
`crates/ailang-surface/tests/round_trip.rs`. (rt.1)
|
|
3. ✓ `crates/ailang-core/tests/schema_coverage.rs` with
|
|
exhaustive-match visitor; 34/34 variants observed. (rt.1)
|
|
4. ✓ `crates/ail/tests/roundtrip_cli.rs` with BLAKE3 identity
|
|
over `ail render` → tempfile → `ail parse`. (rt.1)
|
|
5. ✓ `cargo test --workspace` green with all four tests. (rt.1 + rt.2)
|
|
6. ✓ No roundtrip gaps surfaced; no render/parse code changes
|
|
needed in this milestone. (rt.1)
|
|
7. ✓ Tests are pure readers; the CLI test's only filesystem side
|
|
effect is `tempfile::TempDir`. (rt.1)
|
|
|
|
Audit skill follows for milestone close.
|