plan: form-a.0 — prelude pilot, 2 tasks
Iter 0 of the form-a-default-authoring milestone. One file rendered (examples/prelude.ail.json -> examples/prelude.ail via `ail render`), zero source-code edits, zero test-infra changes. The migration mechanism is validated on the hardest single file in the corpus (prelude exercises every language feature: classes, superclasses, polymorphic free fns, IO effects, ctor patterns, loader auto-injection). The two auto-discovering roundtrip tests in round_trip.rs pick up the new .ail via read_dir without test edits; both must pass for the iter to close. Task 1: render + verify both roundtrip tests green + workspace sanity check (5 steps). Task 2: per-iter journal + INDEX append (2 steps). prelude.ail.json retained per spec §A2 — this is the singular dual-form iter; iter 1 deletes it with the bulk test-infra refactor.
This commit is contained in:
@@ -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<a> 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.
|
||||
Reference in New Issue
Block a user