AILang/docs/journals/2026-05-12-audit-rt.md

audit-rt — Milestone close: Roundtrip Invariant

Date: 2026-05-12 Milestone: Roundtrip Invariant (rt.1 + rt.2) Status: Closed, clean (after rt.tidy fixes)

Architect drift review

ailang-architect reported drift_found with four items over daf9f4f..HEAD:

• [high] DESIGN.md §"Roundtrip Invariant" Direction 2 (text → JSON → text idempotency) is stated as a property but not directly enforced by any of the four listed tests. Test 1 covers Direction 1; test 2 covers .ailx → JSON ≡ counterpart; test 4 covers CLI render → parse. None tests parse → print → parse idempotency on a hand-authored .ailx text directly. Architect recommendation: claim soften OR add a fifth test.
• [high] docs/roadmap.md P1 entry "Round-trip completeness invariant" still - [ ] (open) after the milestone closed. Stale per roadmap convention (finished entries → [x] then removal with one-line journal mirror).
• [low] DESIGN.md wording: <16-hex> in new section vs <16-lowercase-hex> in §"Data model". Casing constraint is load-bearing for canonical-byte equality; should be stated identically.
• [low] rt.1 plan errata note (planner emitted ast.rs-mismatching destructure scaffold). Single occurrence absorbed cleanly by the Step-3.4 escape hatch. Not a deeper drift pattern; informational.

Bench-regression check

bench/check.py && bench/compile_check.py && bench/cross_lang.py:

• check.py: exit 0; 63 metrics; 0 regressed, 0 improved beyond tolerance, 63 stable.
• compile_check.py: exit 0; 24 metrics; 0 regressed, 0 improved beyond tolerance, 24 stable.
• cross_lang.py: exit 0; 25 metrics; 0 regressed, 0 improved beyond tolerance, 25 stable.

All three bench gates green. Bench was the most plausible source of a regression given rt.1 added three new tests but the tests are pure readers and are not exercised by the bench harness; the green signal matches that expectation.

Resolution (rt.tidy, boss-direct edits)

Three fixes, mechanical, no plan/implement dispatch:

1. Direction-2 enforcement — crates/ailang-surface/tests/round_trip.rs gains a third test parse_then_print_then_parse_is_idempotent_on_every_ailx_fixture. For every .ailx fixture asserts canonical_bytes(parse(t)) == canonical_bytes(parse(print(parse(t)))). For the 57 fixtures with a JSON counterpart this is logically derivable from tests 1 + 2; the dedicated test stays robust for future .ailx fixtures without a counterpart. DESIGN.md §"Roundtrip Invariant" "Enforcement" list updated from four to five tests; module doc-comment updated from "two complementary checks" to "three complementary checks". Test PASS first-shot across all 57 fixtures.

2. Roadmap P1 entry removed. The "Round-trip completeness invariant" milestone entry deleted; this journal entry is the one-line mirror per roadmap convention. The P1 todo "Brainstorm Step 7.5" remains; the P1 Show + print-rewire milestone remains.

3. Wording fix. DESIGN.md §"Roundtrip Invariant" Float-bits-hex description changed from <16-hex> to <16-lowercase-hex> to match §"Data model".

The [low] planner-errata carry-on item is retained in the rt.1 journal "Concerns" section; it will surface again only if a future tests-against-AST iteration repeats the pattern.

Spec acceptance criteria — final check

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 (now five) tests. (rt.1 + rt.2 + rt.tidy)
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)

Outcome

Milestone closed clean. Five workspace-wide tests now anchor the .ail.json ↔ .ailx bijection plus AST-variant coverage; the property has a dedicated top-level section in DESIGN.md. No follow-up iterations queued in this milestone.