diff --git a/docs/plans/2026-05-13-iter-form-a.0.md b/docs/plans/2026-05-13-iter-form-a.0.md new file mode 100644 index 0000000..45513ed --- /dev/null +++ b/docs/plans/2026-05-13-iter-form-a.0.md @@ -0,0 +1,201 @@ +# Iter form-a.0 — Prelude Pilot — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-13-form-a-default-authoring.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` +> to run this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Render `examples/prelude.ail.json` to its Form-A sibling +`examples/prelude.ail` and prove that the existing roundtrip-CI +gate (`every_ail_fixture_matches_its_json_counterpart`) plus the +parallel idempotency test both pass on the new file, validating +the migration mechanism on the hardest single file before iter 1 +commits to the bulk test-infrastructure refactor. + +**Architecture:** One CLI invocation (`ail render`) produces the +Form-A text from the canonical JSON-AST. The two relevant tests +in `crates/ailang-surface/tests/round_trip.rs` auto-discover +fixtures via `read_dir(examples/)`; the freshly added `.ail` +lands in their corpus on the next `cargo test` run with no test- +code changes. Iter 0 deliberately keeps `prelude.ail.json` on +disk alongside the new `.ail` — the JSON counterpart is the +byte-witness the gate uses, and that gate is the safety net that +makes the pilot worth running. + +**Tech Stack:** `ail render` CLI subcommand (Form-A printer in +`ailang-surface::print`), `crates/ailang-surface/tests/round_trip.rs` +(auto-discovering gate + idempotency tests), `docs/journals/` +append convention. + +**Files this plan creates or modifies:** + +- Create: `examples/prelude.ail` — Form-A rendering of `examples/prelude.ail.json`, ~6386 bytes / 116 lines, produced verbatim by `ail render`. +- Create: `docs/journals/2026-05-13-iter-form-a.0.md` — per-iter journal entry. +- Modify: `docs/journals/INDEX.md:53` (append-only, one new line at line 54). + +No source-code edits, no test edits, no CLAUDE.md / DESIGN.md +edits. The two existing roundtrip tests pick up the new fixture +automatically because both use `read_dir(examples/)` discovery. + +--- + +### Task 1: Render `examples/prelude.ail` and verify both auto-discovering roundtrip tests pass + +**Files:** +- Create: `examples/prelude.ail` +- Test (existing, no edit): `crates/ailang-surface/tests/round_trip.rs:120-204` (`every_ail_fixture_matches_its_json_counterpart`) and `crates/ailang-surface/tests/round_trip.rs:216-277` (`parse_then_print_then_parse_is_idempotent_on_every_ail_fixture`). + +- [ ] **Step 1: Render the prelude via `ail render`** + +Run from the workspace root: + +``` +cargo run -q --bin ail -- render examples/prelude.ail.json > examples/prelude.ail +``` + +The CLI dispatch lives at `crates/ail/src/main.rs:424-427`: +```rust +Cmd::Render { path } => { + let m = ailang_surface::load_module(&path)?; + print!("{}", ailang_surface::print(&m)); +} +``` + +`render` takes a single positional path argument and writes Form-A +text to stdout; shell redirection captures it to the target file. + +Expected: exit 0, no stderr output, `examples/prelude.ail` created. + +- [ ] **Step 2: Sanity-check the rendered file's shape** + +Run: + +``` +wc -lc examples/prelude.ail +``` + +Expected output (verified during recon): approximately `116 6386 examples/prelude.ail` — exactly 116 lines, 6386 bytes. A different count by more than ±1 line is a signal that the renderer drifted between recon and execution; investigate before continuing. + +Then verify the file begins with the expected `(module prelude` header by reading the first 5 lines: + +``` +head -n 5 examples/prelude.ail +``` + +Expected first line: `(module prelude`. Expected second line: ` (data Ordering`. If the file does not start this way, the render is wrong; do not continue. + +- [ ] **Step 3: Run the gate test in isolation** + +This is the spec's named witness for iter 0 (§A2). + +Run: + +``` +cargo test -p ailang-surface --test round_trip every_ail_fixture_matches_its_json_counterpart +``` + +Expected: PASS. The test (`crates/ailang-surface/tests/round_trip.rs:120-204`) walks every `.ail` file under `examples/`, looks up the same-stem `.ail.json` counterpart, and asserts that parsing the `.ail` produces canonical bytes byte-equal to loading the JSON. The freshly added `prelude.ail` (with its retained `prelude.ail.json` counterpart) is the new corpus element this iter introduces; the test must report at least one more fixture passing than the previous run (or the same count if the test summary doesn't print per-file). + +If the test FAILS on the new prelude: the failure mode is E1 from the spec (a fixture round-trips before migration but the migrated `.ail` fails to parse, or parses to different bytes). The bug is in `ail render` or `ailang_surface::parse`; this iter halts and the bug fix takes precedence. Do NOT delete or alter `prelude.ail` to make the test pass. + +- [ ] **Step 4: Run the parallel idempotency test** + +The recon flagged this test as the second one that auto-discovers `.ail` fixtures and would react to the new file. It checks a different property (idempotency under print) and must also pass. + +Run: + +``` +cargo test -p ailang-surface --test round_trip parse_then_print_then_parse_is_idempotent_on_every_ail_fixture +``` + +Expected: PASS. The test (`crates/ailang-surface/tests/round_trip.rs:216-277`) walks every `.ail` file and asserts `canonical(parse(t)) == canonical(parse(print(parse(t))))`. If this fails on the new prelude while the gate test passes, the Form-A printer is non-idempotent on some feature prelude uses — a deeper render bug that the gate test does not catch. Same halt rule: do not alter the rendered file. + +- [ ] **Step 5: Run the full workspace test suite for regression safety** + +Run: + +``` +cargo test --workspace +``` + +Expected: PASS, identical pass count to pre-iter baseline plus zero (no new tests are added in this iter). The recon explicitly verified that no `.ail.json`-walking test (`print_then_parse_round_trips_every_fixture`, `every_ast_variant_is_observed_in_the_fixture_corpus`, `cli_render_then_parse_preserves_canonical_bytes_on_every_fixture`) has its corpus changed by adding a sibling `.ail`, so the only tests that should react are the two run in Steps 3-4; the full suite is the sanity check that nothing unexpected fires. + +--- + +### Task 2: Write the per-iter journal entry and append the INDEX line + +**Files:** +- Create: `docs/journals/2026-05-13-iter-form-a.0.md` +- Modify: `docs/journals/INDEX.md` (append one line at the end of file — current last line is 53). + +- [ ] **Step 1: Write the journal file** + +Create `docs/journals/2026-05-13-iter-form-a.0.md` with the +following content. The `116 lines / 6386 bytes` figures are the +recon-observed values; if Task 1 Step 2 observed different values +(it should not, the renderer is byte-stable), use the actual `wc +-lc` output and adjust the INDEX line in Step 2 to match. + +```markdown +# Iter form-a.0 — Prelude Pilot + +**Date:** 2026-05-13 +**Parent spec:** `docs/specs/2026-05-13-form-a-default-authoring.md` +**Parent plan:** `docs/plans/2026-05-13-iter-form-a.0.md` + +## Outcome + +`examples/prelude.ail` rendered from `examples/prelude.ail.json` via +`ail render` (116 lines / 6386 bytes). The two auto-discovering +roundtrip tests in `crates/ailang-surface/tests/round_trip.rs` both +pass on the new fixture without test-code changes: + +- `every_ail_fixture_matches_its_json_counterpart` — green; the + `prelude.ail` parses to canonical bytes byte-equal to + `prelude.ail.json`. +- `parse_then_print_then_parse_is_idempotent_on_every_ail_fixture` + — green; the Form-A printer is idempotent over prelude. + +`prelude.ail.json` is retained on disk per spec §A2; iter 1 deletes +it alongside the bulk test-infrastructure refactor. This is the +only iteration in the milestone where a fixture is dual-form. + +## Why this iter is the pilot + +Spec §A2 names prelude as the pilot because it exercises the widest +cross-section of language features in a single file: typeclasses +with superclasses (`Ord extends Eq`), polymorphic free functions +with constraints (`forall where Show a fn print`), IO-effect +signatures, primitive ctor patterns, and the loader's auto-injection +path. A green roundtrip on prelude is strong evidence the bulk +migration in iter 1+ will not surface render or parse bugs. + +## Verifications run + +- `cargo test -p ailang-surface --test round_trip every_ail_fixture_matches_its_json_counterpart` — PASS +- `cargo test -p ailang-surface --test round_trip parse_then_print_then_parse_is_idempotent_on_every_ail_fixture` — PASS +- `cargo test --workspace` — PASS, no regression + +## Scope NOT touched + +Per spec §"Iteration scope": no test-infrastructure changes, no +CLAUDE.md / DESIGN.md edits, no deletion of `prelude.ail.json`, +no migration script yet. Those land in iter 1. +``` + +- [ ] **Step 2: Append the INDEX line** + +The last existing line in `docs/journals/INDEX.md` is line 53 +(iter `24.tidy`). Append one new line at the end of file: + +```markdown +- 2026-05-13 — iter form-a.0: prelude pilot for Form-A-as-default-authoring milestone — examples/prelude.ail rendered (116 lines / 6386 bytes) via `ail render`; two auto-discovering roundtrip tests (every_ail_fixture_matches_its_json_counterpart + parse_then_print_then_parse_is_idempotent_on_every_ail_fixture) green on the new fixture without test-code changes; prelude.ail.json retained per spec §A2 (singular dual-form iter, deletion lands iter 1 with bulk test-infra refactor); cargo test --workspace green → 2026-05-13-iter-form-a.0.md +``` + +Adjust the byte/line counts in the line if Task 1 Step 2 observed +different numbers. Convention (per INDEX.md header lines 1-7): +append-only, one line per iter, newest at the bottom, em-dash +between iter id and summary, arrow before the journal filename. + +No other files modify in this step; INDEX append is the terminal +working-tree edit of this iter.