Brummel
176821c2e7
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.
RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.
Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.
Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
# Roundtrip Invariant
|
|
|
|
## Roundtrip Invariant
|
|
|
|
Every well-formed AILang module has a canonical `.ail.json`
|
|
representation (the hashable, content-addressed JSON-AST) and a
|
|
hand-authored `.ail` representation (Form A, the authoring
|
|
projection). The JSON-AST is derived from `.ail` in-process by
|
|
consumers that need it; the round-trip is now the *property* of
|
|
that derivation, not the byte-level agreement of two on-disk forms.
|
|
|
|
Concretely:
|
|
|
|
1. **Parse-determinism.** For every well-formed `.ail` text `t`,
|
|
`ailang_surface::parse(t)` produces a unique AST. The parser is
|
|
a pure function of input — no randomness, no time dependence,
|
|
no environment leak. Hashing `canonical::to_bytes(parse(t))` is
|
|
therefore well-defined for any `.ail` source.
|
|
|
|
2. **Idempotency under print.** For every well-formed `.ail` text
|
|
`t`, `canonical(parse(t)) == canonical(parse(print(parse(t))))`.
|
|
The printer is a left-inverse of the parser modulo canonical
|
|
form: print-then-parse is a no-op on the canonical bytes.
|
|
|
|
3. **CLI-pipeline idempotency.** For every `.ail` fixture, the
|
|
public CLI pipeline `ail parse | ail render | ail parse` is
|
|
byte-identical to direct `ail parse` of the source `.ail`.
|
|
Pins drift that crate-internal tests cannot see.
|
|
|
|
4. **Carve-out anchor.** Seven `.ail.json`-only fixtures
|
|
(subject-matter rejection tests) survive in the corpus by
|
|
structural necessity. They participate in their own dedicated
|
|
rejection-shape tests, not in the round-trip gate. (The prelude is
|
|
embedded as `examples/prelude.ail` in `ailang-surface` and parsed
|
|
at compile time via `ailang_surface::parse_prelude`.)
|
|
|
|
Hashing is the consequence the language depends on: BLAKE3 of the
|
|
canonical bytes is well-defined for any `.ail` source via parse-
|
|
determinism. An LLM author writes `.ail`; the build derives the
|
|
canonical hash without ambiguity.
|
|
|
|
### Float literals are inside the invariant
|
|
|
|
Float literals carry an IEEE-754 bit pattern, not a decimal
|
|
approximation. The canonical encoding is
|
|
`{"kind":"float","bits":"<16-lowercase-hex>"}` and the surface
|
|
emits the same bits-hex string. NaN, ±Inf, signed zero, and subnormals all
|
|
round-trip exactly because the JSON-number path is bypassed (see
|
|
§"Float semantics", "Form-A serialisation"). Floats are not an
|
|
exception to the invariant — the bits-hex encoding is the
|
|
mechanism that keeps them *inside* it.
|
|
|
|
### Enforcement
|
|
|
|
The invariant is workspace-CI-enforced by five tests, each
|
|
operating on the `examples/` corpus via dynamic `read_dir`
|
|
collection (no hardcoded fixture list, so newly added fixtures
|
|
inherit the gate automatically):
|
|
|
|
- `crates/ailang-surface/tests/round_trip.rs::parse_is_deterministic_over_every_ail_fixture`
|
|
— for every `.ail`, parse twice and assert canonical-byte
|
|
equality between the two ASTs. Direction 1 above.
|
|
- `crates/ailang-surface/tests/round_trip.rs::parse_then_print_then_parse_is_idempotent_on_every_ail_fixture`
|
|
— for every `.ail` text `t`, `parse(t)` and `parse(print(parse(t)))`
|
|
produce canonical-byte-equal AST. Direction 2 above.
|
|
- `crates/ail/tests/roundtrip_cli.rs::cli_parse_then_render_then_parse_is_idempotent`
|
|
— for every `.ail`, the public CLI pipeline `ail parse | ail render | ail parse`
|
|
reproduces canonical bytes byte-identical to direct `ail parse`.
|
|
Pins drift internal tests cannot see.
|
|
- `crates/ailang-core/tests/schema_coverage.rs::every_ast_variant_is_observed_in_the_fixture_corpus`
|
|
— every variant of `Def`, `Term`, `Pattern`, `Literal`, `Type`,
|
|
and `ParamMode` appears in at least one `.ail` fixture (corpus
|
|
flipped from `.ail.json` to `.ail` at iter form-a.1). New AST
|
|
variants fail compile until the visitor and corpus are extended
|
|
in lockstep.
|
|
- `crates/ailang-core/tests/carve_out_inventory.rs::examples_ail_json_inventory_matches_carve_outs`
|
|
— exactly the seven named carve-out files exist under
|
|
`examples/*.ail.json` at any commit. A new `.ail.json` or a
|
|
missing carve-out fails the test.
|
|
|
|
A new fixture or a new AST variant that violates the invariant
|
|
fails one of these tests; the fix is in render or parse code,
|
|
never by relaxing the test.
|
|
|
|
### Why this is anchored at top level
|
|
|
|
The invariant is a property of the language identity, not of any
|
|
one surface-design Decision. Decision 6 introduces the `.ail`
|
|
surface and lists round-trip-as-property as one of its
|
|
constraints, but the property is load-bearing for every
|
|
downstream concern that treats the two forms as exchangeable:
|
|
content-addressed hashing, the LLM-author's choice of authoring
|
|
form, the integrity of fixture cross-references, and the
|
|
prerequisite for empirical cross-model authoring-form studies.
|
|
Lifting it out of Decision 6 makes the property quotable on its
|
|
own and reviewable by the architect agent at every milestone
|
|
close.
|
|
|
|
Ratified by: `crates/ailang-surface/tests/round_trip.rs`.
|