AILang/docs/specs/0015-roundtrip-invariant.md

Roundtrip Invariant — Design Spec

Date: 2026-05-12 Status: Draft — awaiting user spec review Authors: Brummel (orchestrator) + Claude

Goal

Establish that .ail.json ↔ .ailx form a structurally lossless bijection on the module level, and lift this property from a Decision-6-internal constraint to a prominently anchored top-level invariant of the language. Enforce it workspace-wide by a coordinated test suite that collects fixtures dynamically (no hardcoded fixture lists) and verifies that every AST schema variant is exercised by at least one fixture.

Two motivating uses:

1. Independent value. Per Decision 6, .ailx is "the AI authoring projection". If programs are expressible in one form but not the other, the projection claim is partial — a first-class bug class that the language design admits no allowance for.
2. Prerequisite for the cross-model authoring-form test (P2 roadmap entry). Measured form-preference across multiple downstream LLM subjects is only interpretable if both forms are exactly equipotent in expressive power. Without this milestone the cross-model test confounds expressive-power gaps with authoring ergonomics.

Architecture

Three coordinated test layers plus a DESIGN.md anchor:

1. DESIGN.md anchor. A new top-level section "Roundtrip Invariant", positioned between the Decisions block and the schema spec block, on the same visibility level as the existing "Feature-acceptance criterion" section. It states both directions of the bijection explicitly, names the Float bits-hex encoding as a mechanism inside the invariant (not an exception to it), and references the test files below as the enforcement mechanism. Decision 6 Constraint 2 stays in place and gains an upward reference to the new section.

2. Machine roundtrip (existing, unchanged): the current print_then_parse_round_trips_every_fixture in crates/ailang-surface/tests/round_trip.rs already iterates dynamically over every .ail.json fixture under examples/ and verifies JSON → print → parse → canonical-bytes-equal. Provides the JSON-anchored half of the bijection.

3. Hand cross-check (replacing the 3-pair static test): a new dynamic test every_ailx_fixture_matches_its_json_counterpart replaces handwritten_exhibits_match_json_fixtures. It iterates over every .ailx file in examples/, locates the same-stem .ail.json counterpart, and asserts canonical_bytes(parse(ailx_text)) == canonical_bytes(load_module(json_path)). For a .ailx file without a counterpart (today: none; reserved for future), only parse success is required — drift detection needs both sides.

4. Schema-coverage audit (new): a new test crates/ailang-core/tests/schema_coverage.rs iterates over every module loaded from examples/, runs an exhaustive AST visitor that — via match arms without a wildcard _ => ... — populates a HashSet<VariantTag> of observed variants. The test asserts that every expected variant (one per enum case in Def / Term / Pattern / Literal / Type / ParamMode) appears at least once. The Rust compiler enforces synchronization between the AST definition and the visitor: any new AST enum variant will not compile until the visitor and VariantTag are extended, guaranteeing that the coverage table cannot silently fall behind the schema.

5. Workspace CLI roundtrip (new): a new integration test crates/ail/tests/roundtrip_cli.rs iterates over every .ail.json fixture in examples/, runs the fixture through the public ail render → tempfile → ail parse CLI flow (two subprocesses, tempfile-mediated because ail parse reads from a file path, not stdin), and verifies BLAKE3 hash identity between the original canonicalised JSON and the round-tripped canonical JSON captured from ail parse's stdout. This is the user-facing- surface defence line: it catches drift in the CLI layer that crate-internal tests miss.

Components

DESIGN.md edit

A new top-level section approximately 40–70 lines long. Outline:

• Statement (both directions, explicit). Every valid AILang module has both a .ail.json and a .ailx representation; print and parse are mutual inverses on the canonical-bytes level.
• Float-bits-hex encoding as the mechanism that keeps Float literals (including NaN, ±Inf, subnormals) inside the invariant rather than outside it.
• Enforcement points — the four test files below, by path.
• Why this is top-level: the property is load-bearing on the language identity, not just on Decision 6's surface-design rationale.
• Cross-reference from Decision 6 Constraint 2 up to this section, replacing the inline form of the same claim.

Test files

Path	Status	Purpose
crates/ailang-surface/tests/round_trip.rs::print_then_parse_round_trips_every_fixture	Unchanged	Machine roundtrip (.ail.json → .ailx → .ail.json)
crates/ailang-surface/tests/round_trip.rs::every_ailx_fixture_matches_its_json_counterpart	Replaces hardcoded-pair test; dynamic	Hand cross-check (.ailx → .ail.json ≡ static JSON counterpart)
crates/ailang-core/tests/schema_coverage.rs	New	Schema-variant coverage audit
crates/ail/tests/roundtrip_cli.rs	New	CLI roundtrip — BLAKE3 hash identity through ail render → tempfile → ail parse

Data flow

Machine roundtrip (existing):

<stem>.ail.json
  → ailang_core::load_module
  → ailang_surface::print
  → ailang_surface::parse
  → ailang_core::canonical::to_bytes
  ≡ canonical::to_bytes(<original>)

Hand cross-check (new, dynamic):

for every <stem>.ailx where <stem>.ail.json exists:
    <stem>.ailx (file-read)
      → ailang_surface::parse
      → ailang_core::canonical::to_bytes
      ≡ canonical::to_bytes(ailang_core::load_module(<stem>.ail.json))

Schema coverage (new):

for every <stem>.ail.json:
    load_module
    visit AST exhaustively (no `_` wildcard arms)
    accumulate observed: HashSet<VariantTag>
assert: expected_set ⊆ observed_set

The expected_set is computed at runtime by enumerating one VariantTag per AST enum variant. The visitor's exhaustive matches guarantee the two stay synchronized via the compiler.

CLI roundtrip (new):

for every <stem>.ail.json:
    bytes_orig = canonical::to_bytes(load_module(<stem>.ail.json))
    h_orig = blake3(bytes_orig)

    # subprocess 1: render JSON fixture to .ailx text on stdout
    ailx_text = run("ail render <stem>.ail.json")
    write(<tmpdir>/round.ailx, ailx_text)

    # subprocess 2: parse the .ailx back to canonical JSON bytes
    # (ail parse writes canonical bytes + a trailing newline)
    raw_stdout = run("ail parse <tmpdir>/round.ailx")
    bytes_round = strip_trailing_newline(raw_stdout)
    h_round = blake3(bytes_round)

    assert h_orig == h_round

The ail parse subcommand emits the canonical bytes via stdout.write_all(&bytes) followed by a println!(); the test strips the trailing newline before hashing.

Error handling

• Each test failure prints the offending fixture path and a concrete diff: canonical-byte diff for tests 1 and 2; missing-variant list for test 3; hex-hash mismatch plus captured stderr for test 4.
• Failures are aggregated per test: a single cargo test run lists all failing fixtures, not just the first. Existing test 1 already follows this pattern; the new tests adopt it.
• Subprocess errors in the CLI test (non-zero exit) propagate the captured stderr verbatim into the panic message.

Testing strategy

• Hard-fail mode from iteration 1. No allowlist, no aspirational state. The first iteration that adds the new tests will surface every existing roundtrip gap as a test failure. Each gap is a bug to fix in subsequent iterations; the milestone closes only when all four tests are green.
• Dynamic fixture collection. Every test uses read_dir over examples/. No hardcoded fixture list. New fixtures are picked up automatically.
• Float coverage. The schema coverage test includes Literal::Float as a required variant, so the corpus must contain at least one Float-bearing fixture (it already does: examples/floats.ail.json and others). The roundtrip tests then exercise the bits-hex encoding path on those fixtures. NaN / ±Inf are not currently in the corpus; if the audit reveals no fixture carries these bit patterns, a minimal Float-edge-case fixture is added.
• Independence. The four tests are intentionally overlapping in places (e.g. test 1 and test 4 both cover the JSON-anchored direction, at crate-internal vs CLI-surface levels). This redundancy is the point: each test guards a different drift source.

Acceptance criteria

1. docs/DESIGN.md carries a top-level section "Roundtrip Invariant" with the structure outlined above; Decision 6 Constraint 2 carries an upward cross-reference to it.
2. crates/ailang-surface/tests/round_trip.rs has every_ailx_fixture_matches_its_json_counterpart in place of the hardcoded-pair handwritten_exhibits_match_json_fixtures, sourcing all .ailx/.ail.json pairs dynamically.
3. crates/ailang-core/tests/schema_coverage.rs exists; its visitor matches each of Def / Term / Pattern / Literal / Type / ParamMode exhaustively without wildcard arms; every variant appears in at least one fixture.
4. crates/ail/tests/roundtrip_cli.rs exists; iterates dynamically over .ail.json fixtures; verifies BLAKE3 hash identity through the ail render | ail parse subprocess pipeline.
5. cargo test --workspace is green with all four tests active.
6. Any roundtrip gaps surfaced by the new tests are closed in render or parse code, not by relaxing the tests.
7. Tests are pure readers of the repo. None of the four tests writes a file inside the workspace, regenerates a fixture, patches the AST, or otherwise mutates committed content. The only filesystem side effect permitted is the use of a temp directory (e.g. tempfile::TempDir) for the CLI roundtrip's intermediate .ailx file, which lives outside the repo and is cleaned up by the test harness. If a test surfaces a gap, the diagnostic is fail-loud; the fix lands in render/parse code via a separate iteration, never inline by the test.

Scope notes

• In scope: roundtrip property in both directions; DESIGN.md anchor; dynamic test coverage; schema-variant coverage; fixing any gaps surfaced.
• Out of scope: the cross-model authoring-form test (P2 roadmap, gated on this milestone). Property-based generation of random AST instances (the schema-coverage test plus the existing fixture corpus provides equivalent assurance without the generator-authoring burden). The two open P2 todos around .ailx-aware CLI (ail check foo.ailx) and workspace-search beyond the entry module's directory — those are orthogonal and remain on the roadmap.