From 7381a4233b0ea34b23871c59e3a3e802441751ef Mon Sep 17 00:00:00 2001 From: Brummel Date: Fri, 15 May 2026 13:49:53 +0200 Subject: [PATCH] =?UTF-8?q?plan:=20it.1=20loop/recur=20additive=20?= =?UTF-8?q?=E2=80=94=208=20tasks,=20stub-then-fill=20mirroring=20mut.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Boss-resolved design decisions baked in (DD-1 loop_stack in synth like mut.2's mut_scope_stack + RecurNotInTailPosition in verify_tail_positions; DD-2 LoopBinder derives = MutVar's, no PartialEq; DD-3 stub-then-fill sequencing). Recon-enumerated walker-arm site list incl. the test-side exhaustive match (codegen_import_map_fallback_pin.rs:62) mut.1's plan missed. it.2/it.3 explicitly out of scope. --- docs/plans/2026-05-15-iter-it.1.md | 1055 ++++++++++++++++++++++++++++ 1 file changed, 1055 insertions(+) create mode 100644 docs/plans/2026-05-15-iter-it.1.md diff --git a/docs/plans/2026-05-15-iter-it.1.md b/docs/plans/2026-05-15-iter-it.1.md new file mode 100644 index 0000000..3a7e028 --- /dev/null +++ b/docs/plans/2026-05-15-iter-it.1.md @@ -0,0 +1,1055 @@ +# it.1 — loop/recur additive — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-15-iteration-discipline.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` +> to run this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Add `Term::Loop` / `Term::Recur` / `LoopBinder` as +first-class additive AST nodes — parse, print, prose, round-trip, +serde, schema-lockstep, typecheck (binder typing + recur +unification + recur-tail-position), and codegen (loop-header block +with one phi per binder; `recur` = back-edge `br`) — **without +removing or modifying anything that exists** (`tail-app`/`tail-do` +and the seven existing `block_terminated` sites stay exactly as +they are). + +**Architecture:** Mirror the proven mut.1→mut.2→mut.3 shape. Task 1 +lands the variants + every `match Term` walker arm (structural arms +real; the typecheck/codegen *dispatch* arms are `Internal` stubs) + +the serde/schema lockstep quintet, so `cargo test --workspace` is +green with `loop`/`recur` structurally present end-to-end but +semantically stubbed. Tasks 2–8 then layer surface parse, print, +prose, real typecheck, real codegen, and the test corpus, each +green at its own gate. `recur`↔`loop` arity/type unification lives +in `synth` via a `loop_stack: &mut Vec>` threaded exactly +as mut.2 threaded `mut_scope_stack`; `RecurNotInTailPosition` is the +only recur check in `verify_tail_positions`. + +**Tech Stack:** `ailang-core` (ast/desugar/workspace/serde), +`ailang-check` (lib/lift/mono/linearity/uniqueness/reuse_shape/ +pre_desugar_validation), `ailang-codegen` (lib/escape/lambda), +`ailang-surface` (parse/print), `ailang-prose`, `ail` (CLI dep +walker + rewrite_term), the schema/spec-drift + carve-out test +crates. + +--- + +## Design decisions (Boss-resolved; not implementer judgement calls) + +- **DD-1 — recur context placement.** Arity/type unification of a + `Term::Recur`'s args against its lexically-enclosing `Term::Loop` + binders lives in `synth`, threaded via a new + `loop_stack: &mut Vec>` parameter added to `synth` + immediately after the existing `mut_scope_stack` parameter, and + propagated through every `synth` call site exactly as mut.2 + propagated `mut_scope_stack` (`lib.rs` recursive sites + `mono.rs` + + `lift.rs` + `builtins.rs` test helpers + the mq.3 in-test helper + at `lib.rs:6663`). `Term::Loop` pushes its binder type-vector + (innermost = last); `Term::Recur` reads the innermost frame: + empty stack ⇒ `RecurOutsideLoop`; length mismatch ⇒ + `RecurArityMismatch`; per-position unify failure ⇒ + `RecurTypeMismatch`. The **tail-position** rule for `recur` is the + *only* recur concern handled in `verify_tail_positions`; its + public signature `pub fn verify_tail_positions(t: &Term, is_tail: + bool) -> Result<()>` is **unchanged** (it.3 reworks it) — loop-tail + context is tracked internally as the walk descends (a `Term::Loop` + arm recurses its body in a "recur-legal, recur-must-be-tail" + context; a `Term::Recur` reached outside that tail context ⇒ + `RecurNotInTailPosition`). +- **DD-2 — `LoopBinder` derives.** Exactly + `#[derive(Debug, Clone, Serialize, Deserialize)]`, mirroring + `MutVar` (`ast.rs:564`); the type field carries + `#[serde(rename = "type")]`. No `PartialEq`/`Eq` (codegen phi + emission maps binder *name* → SSA; it never compares `LoopBinder` + values). +- **DD-3 — stub-then-fill sequencing.** Task 1 makes the workspace + compile and `cargo test --workspace` pass with the typecheck and + codegen *dispatch* arms returning `CheckError::Internal` / + `CodegenError::Internal` (same boundary device mut.1 used). Real + typecheck lands in Task 6; real codegen in Task 7. No task between + 1 and 7 leaves the workspace non-compiling. + +--- + +## Files this plan creates or modifies + +**Create:** +- Test: `examples/loop_smoke.ail` — positive round-trip + parse/print fixture (single counted loop) +- Test: `examples/loop_nested_in_lambda.ail` — positive: a `loop` inside a lambda body + a nested loop (mut.3 lambda-boundary analogue) +- Test: `examples/loop_counter.ail` — e2e: accumulator counter, runs and prints `55` +- Test: `examples/test_recur_outside_loop.ail.json` — negative: `recur` with no enclosing `loop` +- Test: `examples/test_recur_arity_mismatch.ail.json` — negative: `recur` arg count ≠ binder count +- Test: `examples/test_recur_type_mismatch.ail.json` — negative: `recur` arg type ≠ binder type +- Test: `examples/test_recur_not_in_tail_position.ail.json` — negative: `recur` not in loop tail position +- Test: `crates/ailang-check/tests/loop_recur_pin.rs` — driver: typechecks the four negatives + the positive smoke + +**Modify (line ranges from recon a7224502d6da018ec):** +- `crates/ailang-core/src/ast.rs:513–540` (variant block), `:554–581` (`MutVar`→`LoopBinder` template), `:894–949` (serde round-trip `mod tests`) +- `crates/ailang-core/tests/design_schema_drift.rs:140–175` +- `crates/ailang-core/tests/schema_coverage.rs` (VariantTag + EXPECTED_VARIANTS + visit_term) +- `crates/ailang-core/tests/spec_drift.rs` (2 exemplars + 2 arms) +- `docs/DESIGN.md:2394–2412` (§"Data model" jsonc, must stay inside `## Data model`…`## Pipeline`) +- `crates/ailang-core/src/desugar.rs` — 9 sites: `:349`,`:559`,`:1214`,`:1381`,`:1551`,`:1629`,`:1686`,`:1716`,`:2837` +- `crates/ailang-core/src/workspace.rs:1254`,`:1388` +- `crates/ailang-check/src/lib.rs` — `:249` (type-rebuilder), `:2590` (`verify_tail_positions`), `:2613`/`:3593`/`Term::Mut@3614` (`synth`), `CheckError` enum `:660–680` + `code()` `:732` + `ctx()`/Display `:802`, `synth` call sites for `loop_stack` +- `crates/ailang-check/src/lift.rs:383`,`:760`; `mono.rs:1233`,`:1607`; `linearity.rs:601`,`:796`,`:929`; `uniqueness.rs:346`; `reuse_shape.rs:261`; `pre_desugar_validation.rs:129` +- `crates/ailang-codegen/src/lib.rs:1325` (`lower_term`), `:564`/`:3094` (`synth_with_extras`); `escape.rs:197`,`:389`,`:506`; `lambda.rs:478`,`:119–154`/`:248–260` +- `crates/ailang-prose/src/lib.rs:909`,`:1109`,`:1251` +- `crates/ail/src/main.rs:1520`,`:2754` +- `crates/ail/tests/codegen_import_map_fallback_pin.rs:62` (test-side exhaustive `Term` match — mut.1's plan missed this; do not miss again) +- `crates/ailang-surface/src/parse.rs:42–43`,`:69–72`,`:1212–1214`,`:1582–1643`,`:2504–2551` +- `crates/ailang-surface/src/print.rs:551–597` +- `crates/ailang-core/specs/form_a.md:283–286`,`:304–324` +- `crates/ailang-core/tests/carve_out_inventory.rs:23–40` (EXPECTED 13 → 17) + +--- + +## Task 1: AST variants + every walker arm + serde/schema lockstep (stub-then-fill base) + +**Files:** `crates/ailang-core/src/ast.rs`, +`crates/ailang-core/tests/design_schema_drift.rs`, +`crates/ailang-core/tests/schema_coverage.rs`, +`crates/ailang-core/tests/spec_drift.rs`, `docs/DESIGN.md`, +all walker files listed above, +`crates/ailang-check/src/lib.rs` (stub arms only), +`crates/ailang-codegen/src/lib.rs` (stub arms only). + +- [ ] **Step 1.1: Add the AST variants and `LoopBinder`.** + +In `crates/ailang-core/src/ast.rs`, inside `pub enum Term` adjacent +to the `Term::Mut`/`Term::Assign` block (`:513–540`), add: + +```rust + /// Named loop head. The only repetition form besides structural + /// recursion. Iter it.1. `recur` re-enters the lexically + /// nearest enclosing `Loop`, rebinding `binders` positionally. + Loop { + binders: Vec, + body: Box, + }, + /// Backward jump to the lexically nearest enclosing `Loop`. + /// Must be in tail position of that loop's body. Iter it.1. + Recur { + #[serde(default)] + args: Vec, + }, +``` + +Immediately after the `MutVar` struct (`:554–581`), add: + +```rust +/// One named, typed, initialised binder of a `Term::Loop`. +/// Mirrors `MutVar` exactly (DD-2): no `PartialEq` — codegen maps +/// the binder name to an SSA value, never compares binders. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LoopBinder { + pub name: String, + #[serde(rename = "type")] + pub ty: Type, + pub init: Box, +} +``` + +- [ ] **Step 1.2: Run the build to enumerate every non-exhaustive `match Term`.** + +Run: `cargo build --workspace 2>&1 | grep -E "pattern .* not covered|crates/" | head -60` +Expected: a list of `E0004` non-exhaustive-match errors at exactly +the walker sites enumerated in "Files this plan creates or +modifies". Use this list to drive Steps 1.3–1.5 (it must match the +recon site list; any extra site is a new arm to add with the same +rule). + +- [ ] **Step 1.3: Add structural pass-through arms.** + +At each site below, insert the arm immediately after the adjacent +`Term::Assign` arm, mirroring the recursion shape of the local +`Term::Mut` arm (recurse into children, rebuild the same variant; +visitors return the visitor's unit/bool fold; rebuilders return +`Term::Loop`/`Term::Recur` reconstructed). The exact arm for a +*rebuilder* (returns `Term`): + +```rust +Term::Loop { binders, body } => Term::Loop { + binders: binders.iter().map(|b| LoopBinder { + name: b.name.clone(), + ty: b.ty.clone(), + init: Box::new(rebuild(&b.init)), + }).collect(), + body: Box::new(rebuild(body)), +}, +Term::Recur { args } => Term::Recur { + args: args.iter().map(|a| rebuild(a)).collect(), +}, +``` + +(Replace `rebuild` with the local recursive call name at the site.) +The exact arm for a *visitor* (returns `()` / `bool` / accumulates): + +```rust +Term::Loop { binders, body } => { + for b in binders { visit(&b.init); } + visit(body); +} +Term::Recur { args } => { for a in args { visit(a); } } +``` + +Structural-pass-through sites (visitor or plain rebuild, no binding +semantics): `desugar.rs:349`, `:559`, `:1214`, `:1381`, `:1551`, +`:1686`, `:1716`, `:2837`; `workspace.rs:1388`; +`lift.rs:760`; `mono.rs:1233`, `:1607`; +`uniqueness.rs:346`; `reuse_shape.rs:261`; +`pre_desugar_validation.rs:129`; `main.rs:1520`; +`codegen_import_map_fallback_pin.rs:62`; +`crates/ailang-check/src/lib.rs:249` (type-rebuilder — rebuild each +`LoopBinder.ty` via the local type-rebuild fn); +`lift.rs:383` (rebuilder). + +- [ ] **Step 1.4: Add the binding-aware / type-embedding arms (substantive).** + +These arms are NOT pass-through — a `Term::Loop` *binds* its +binder names and *embeds* the binder types: + +`crates/ailang-core/src/desugar.rs:1629` — `free_vars_in_term` +(load-bearing: feeds `MutVarCapturedByLambda`). Loop binder names +are bound; recur args are uses: + +```rust +Term::Loop { binders, body } => { + let mut inner = free_vars_in_term(body); + for b in binders { + out.extend(free_vars_in_term(&b.init)); + inner.remove(&b.name); + } + out.extend(inner); +} +Term::Recur { args } => { + for a in args { out.extend(free_vars_in_term(a)); } +} +``` + +(Adapt to the site's exact accumulator/return convention — match +the local `Term::Mut` arm's free/bound treatment of `MutVar.name`.) + +`crates/ailang-codegen/src/lambda.rs:478` — `collect_captures` +(loop-inside-lambda soundness). Loop binder names are NOT captures +inside the loop body; recur args ARE uses. Mirror the +`Term::Mut`-binds-`var`-names treatment at `lambda.rs:482`. + +`crates/ailang-prose/src/lib.rs:1109` — `count_free_var`: loop +binders bind (subtract), recur args count as uses. Mirror the +`Term::Mut` arm at `:1113`. + +`crates/ailang-core/src/workspace.rs:1254` — +`walk_term_embedded_types`: each `LoopBinder.ty` is an embedded +type, walked exactly as `MutVar.ty` at `:1254–1260`; recur has no +embedded type. + +`crates/ail/src/main.rs:2754` — `rewrite_term`: rewrite each +`LoopBinder.ty` (mirror the `MutVar.ty` rewrite at `:2754`); recur +args structural. + +`crates/ailang-check/src/linearity.rs:601`,`:929` — binder inits +consume, body uses; recur args consume. Mirror the local +`Term::Mut`/`MutVar.init` linearity treatment. +`crates/ailang-codegen/src/escape.rs:197`,`:389`,`:506` — binder +inits + body escape-walk; recur args escape-walk. Mirror the local +`Term::Mut` escape arm. + +- [ ] **Step 1.5: Add the variant-name string emitters.** + +At `crates/ailang-check/src/lib.rs:3593` (the `Term::Mut => "mut"` +sub-match), `crates/ailang-check/src/linearity.rs:796`, and any +other `Term::Mut => "mut"`/`Term::Assign => "assign"` string mapping +the build flags, add `Term::Loop { .. } => "loop"` and +`Term::Recur { .. } => "recur"`. + +- [ ] **Step 1.6: Add the typecheck + codegen DISPATCH STUBS (DD-3).** + +`crates/ailang-check/src/lib.rs` `synth` (`match t` at `:2613`, +adjacent to `Term::Mut` arm `:3614`): + +```rust +Term::Loop { .. } | Term::Recur { .. } => Err(CheckError::Internal { + msg: "Term::Loop/Recur typecheck lands in it.1 Task 6".into(), +}), +``` + +`crates/ailang-codegen/src/lib.rs` `lower_term` (`match t` at +`:1326`, adjacent to `Term::Mut` arm `:1762`): + +```rust +Term::Loop { .. } | Term::Recur { .. } => Err(CodegenError::Internal( + "Term::Loop/Recur codegen lands in it.1 Task 7".into(), +)), +``` + +`crates/ailang-codegen/src/lib.rs` `synth_with_extras` (`match t` +at `:564`, adjacent to `Term::Mut` arm `:3094`): + +```rust +Term::Loop { binders: _, body } => self.synth_with_extras(body, extras), +Term::Recur { .. } => Ok(Type::unit()), +``` + +(Use the *exact* `CheckError::Internal` / `CodegenError::Internal` +constructor shapes the recon-named adjacent arms use — copy the +`Term::Mut` mut.1-era stub form verbatim, only changing the message.) + +- [ ] **Step 1.7: Serde round-trip unit tests.** + +In `crates/ailang-core/src/ast.rs` `#[cfg(test)] mod tests` +(`:894–949`), beside the existing `Term::Mut`/`Assign` tests, add: + +```rust +#[test] +fn term_loop_round_trips_through_json() { + let t = Term::Loop { + binders: vec![LoopBinder { + name: "i".into(), + ty: Type::con("Int"), + init: Box::new(Term::Lit(Lit::Int(0))), + }], + body: Box::new(Term::Recur { + args: vec![Term::Var { name: "i".into() }], + }), + }; + let j = serde_json::to_string(&t).unwrap(); + assert!(j.contains(r#""t":"loop""#)); + assert!(j.contains(r#""type":"#)); // LoopBinder.ty serde rename + let back: Term = serde_json::from_str(&j).unwrap(); + assert_eq!(serde_json::to_string(&back).unwrap(), j); +} + +#[test] +fn term_recur_empty_args_round_trips() { + let t = Term::Recur { args: vec![] }; + let j = serde_json::to_string(&t).unwrap(); + let back: Term = serde_json::from_str(&j).unwrap(); + assert_eq!(serde_json::to_string(&back).unwrap(), j); +} +``` + +(Match the exact `Type::con` / `Lit` / `Term::Var` constructors the +neighbouring `term_assign_round_trips_through_json` test uses; if a +constructor name differs, copy the neighbour's verbatim.) + +- [ ] **Step 1.8: Schema-drift exemplars + variant→tag arms.** + +`crates/ailang-core/tests/design_schema_drift.rs`: in the exemplar +tuple list (`:140–153`), after the `assign` exemplar, add tuples for +`Term::Loop` (a minimal `Loop{binders:vec![],body:Box::new(unit)}`, +tag `"loop"`) and `Term::Recur` (`Recur{args:vec![]}`, tag +`"recur"`), mirroring the `mut`/`assign` tuple shape. In the +exhaustive variant→tag match (`:160–175`), after +`Term::Assign => "assign"` (`:174`), add +`Term::Loop { .. } => "loop"`, `Term::Recur { .. } => "recur"`. + +- [ ] **Step 1.9: DESIGN.md §"Data model" jsonc entries (in-range).** + +In `docs/DESIGN.md`, between the `{ "t": "assign", … }` entry +(`:2410–2412`) and the next entry — guaranteed to stay inside the +`## Data model` (`:2249`) … `## Pipeline` (`:2490`) slice the drift +test scans — add: + +```jsonc +{ "t": "loop", "binders": [{ "name": "", "type": , "init": }], "body": } +// Named loop. recur re-enters the nearest enclosing loop. Iter it.1. +{ "t": "recur", "args": [] } +// Backward jump; tail-position-only; binds the enclosing loop. Iter it.1. +``` + +Also add a one-line status note paragraph mirroring the mut.3 +status note at `:2419–2426`: "`loop`/`recur` are additive as of +it.1; structural-recursion restriction and the `Diverge` effect +land in it.2; `tail-app`/`tail-do` are retired in it.3." + +- [ ] **Step 1.10: schema_coverage + spec_drift lockstep.** + +`crates/ailang-core/tests/schema_coverage.rs`: add +`VariantTag::TermLoop`, `VariantTag::TermRecur`; extend +`EXPECTED_VARIANTS`; add the two `visit_term` arms (structural +recurse, same shape as the `TermMut`/`TermAssign` arms mut.1 added). +`crates/ailang-core/tests/spec_drift.rs`: add the 2 exemplars + 2 +match arms analogous to mut.1's `mut`/`assign` additions. + +- [ ] **Step 1.11: Build + full test gate.** + +Run: `cargo build --workspace` +Expected: clean (0 errors). + +Run: `cargo test --workspace 2>&1 | tail -5` +Expected: all green. Test count rises by the new serde tests (+2) +and the schema/spec-drift additions. No test regresses. +`schema_coverage` passes only after a corpus fixture observes +`loop`/`recur` — if it fails "variant never observed", that is +expected to remain RED until Task 3 lands `examples/loop_smoke.ail`; +record the failing test name and proceed (Task 3 closes it). Every +OTHER test must be green here. + +--- + +## Task 2: Form-A parse (`parse_loop` / `parse_recur`) + +**Files:** `crates/ailang-surface/src/parse.rs`, +`crates/ailang-core/specs/form_a.md`. + +- [ ] **Step 2.1: RED — parser pin tests.** + +In `crates/ailang-surface/src/parse.rs` test module (beside the +`(mut …)` pins at `:2504–2551`): + +```rust +#[test] +fn parses_loop_with_one_binder_and_recur_body() { + let src = "(loop ((var i Int 0)) (recur i))"; + let t = parse_term_str(src).expect("loop parses"); + match t { + Term::Loop { binders, body } => { + assert_eq!(binders.len(), 1); + assert_eq!(binders[0].name, "i"); + assert!(matches!(*body, Term::Recur { .. })); + } + other => panic!("expected Term::Loop, got {other:?}"), + } +} + +#[test] +fn parses_recur_zero_args() { + let t = parse_term_str("(recur)").expect("recur parses"); + assert!(matches!(t, Term::Recur { args } if args.is_empty())); +} +``` + +(Use the exact test-harness entry the neighbouring `(mut …)` pin +uses — copy its `parse_term_str`/equivalent helper name verbatim.) + +- [ ] **Step 2.2: Run RED.** + +Run: `cargo test --workspace -p ailang-surface parses_loop_with_one_binder_and_recur_body parses_recur_zero_args` +Expected: FAIL — `loop`/`recur` fall through the head dispatch to +the "unknown head" / generic-app error. + +- [ ] **Step 2.3: Dispatch + `parse_loop` + `parse_recur`.** + +In `parse.rs`, in the head-keyword dispatch match (`:1212–1214`, +after the `"assign"` arm), add: + +```rust +"loop" => self.parse_loop(items)?, +"recur" => self.parse_recur(items)?, +``` + +Add the keyword strings to the head-keyword list used for the +"unknown head" error message (same list `mut`/`assign` are in, +recon `:1212–1214` region). Then, modelled on `parse_mut` +(`:1582–1625`) and `parse_assign` (`:1633–1643`): + +```rust +fn parse_loop(&mut self, items: &[Sexp]) -> Result { + // items[0] == "loop". items[1] == binder list ((var n T init)...). + // items[2..] == body terms, right-folded into Term::Seq (mirror + // parse_mut's body fold at parse.rs:1600-1620 exactly). + let binder_list = items.get(1).ok_or_else(|| self.err("loop: missing binder list"))?; + let binders = self.parse_loop_binders(binder_list)?; + let body = self.parse_body_seq(&items[2..])?; // same helper parse_mut uses + Ok(Term::Loop { binders, body: Box::new(body) }) +} + +fn parse_loop_binders(&mut self, list: &Sexp) -> Result, ParseError> { + // Each entry: (var ) — IDENTICAL shape to + // the MutVar pull in parse_mut at parse.rs:1588-1597. Reuse that + // parsing inline, constructing LoopBinder instead of MutVar. + // ... (copy parse_mut's per-(var ...) decode verbatim, swap the + // constructed struct from MutVar to LoopBinder) +} + +fn parse_recur(&mut self, items: &[Sexp]) -> Result { + let args = items[1..].iter().map(|s| self.parse_term(s)).collect::>()?; + Ok(Term::Recur { args }) +} +``` + +(The `parse_body_seq` / per-`(var …)` decode helpers MUST be the +exact ones `parse_mut` calls — recon `parse.rs:1582–1625`; do not +introduce a new body-folding helper.) + +- [ ] **Step 2.4: EBNF doc + form_a.md.** + +In `parse.rs` module-doc EBNF: `:42–43` add `| loop-term | +recur-term` to the `term` production; `:69–72` add productions: + +``` + loop-term ::= "(" "loop" "(" loop-binder* ")" term+ ")" + loop-binder ::= "(" "var" IDENT type term ")" + recur-term ::= "(" "recur" term* ")" +``` + +In `crates/ailang-core/specs/form_a.md`: `:283–286` add `loop` / +`recur` to the §Terms production list; `:304–324` add a prose block +mirroring the `mut`/`var`/`assign` block: `loop` introduces named +binders; `recur` re-enters the lexically nearest enclosing `loop`, +must be in tail position, arity/type must match the binders; +diagnostics `recur-outside-loop`, `recur-arity-mismatch`, +`recur-type-mismatch`, `recur-not-in-tail-position`. + +- [ ] **Step 2.5: Run GREEN.** + +Run: `cargo test --workspace -p ailang-surface parses_loop_with_one_binder_and_recur_body parses_recur_zero_args` +Expected: PASS. + +--- + +## Task 3: Form-A print + positive round-trip fixture + +**Files:** `crates/ailang-surface/src/print.rs`, +`examples/loop_smoke.ail`, `examples/loop_nested_in_lambda.ail`. + +- [ ] **Step 3.1: Print arms.** + +In `print.rs`, after the `Term::Assign` arm (`:586–596`, before the +match close `:597`), add — mirroring the `Term::Mut` Seq-spine +walk at `:551–585`: + +```rust +Term::Loop { binders, body } => { + write!(w, "(loop (")?; + for (k, b) in binders.iter().enumerate() { + if k > 0 { write!(w, " ")?; } + write!(w, "(var {} ", b.name)?; + write_type(w, &b.ty)?; + write!(w, " ")?; + write_term(w, &b.init)?; + write!(w, ")")?; + } + write!(w, ") ")?; + // body is a Term::Seq right-spine when multi-term; walk it the + // SAME way the Term::Mut arm walks its body spine (print.rs:551-585) + write_seq_spine(w, body)?; + write!(w, ")") +} +Term::Recur { args } => { + write!(w, "(recur")?; + for a in args { write!(w, " ")?; write_term(w, a)?; } + write!(w, ")") +} +``` + +(`write_type` / `write_term` / the seq-spine helper MUST be the +exact identifiers the `Term::Mut` arm uses at `:551–585`.) + +- [ ] **Step 3.2: Positive fixtures.** + +`examples/loop_smoke.ail`: + +``` +(module loop_smoke + (fn count_to : Int -> Int (n) + (loop ((var i Int 0)) + (if (app eq i n) i (recur (app add i 1)))))) +``` + +`examples/loop_nested_in_lambda.ail` — a `loop` inside a lambda +body plus a nested loop (mut.3 lambda-boundary analogue): + +``` +(module loop_nested_in_lambda + (fn make_adder : Int -> (Int -> Int) (base) + (lam (x : Int) + (loop ((var acc Int base) (var k Int 0)) + (if (app eq k x) acc (recur (app add acc 1) (app add k 1))))))) +``` + +(Use the exact head-keyword/prelude call spellings the existing +`examples/mut_counter.ail` fixture uses for `if`/`eq`/`add`/`lam` — +read that file and match its surface forms verbatim so the fixture +parses against the real prelude. If a prelude function name +differs, copy `mut_counter.ail`'s spelling.) + +- [ ] **Step 3.3: Round-trip + schema-coverage GREEN.** + +Run: `cargo test --workspace -p ailang-surface parse_then_print_then_parse_is_idempotent_on_every_ail_fixture parse_is_deterministic_over_every_ail_fixture` +Expected: PASS (the new `examples/loop_*.ail` are auto-discovered; +parse→print→parse is byte-idempotent). + +Run: `cargo test --workspace -p ailang-core schema_coverage` +Expected: PASS — `loop`/`recur` are now observed in the corpus, +closing the Task 1.11 deferred RED. + +--- + +## Task 4: Prose projection lockstep + +**Files:** `crates/ailang-prose/src/lib.rs`. + +- [ ] **Step 4.1: RED — prose round-trip pin.** + +Add beside the existing prose snapshot tests a test that renders +`examples/loop_smoke.ail`'s parsed AST to prose and back, asserting +AST equality (mirror the nearest existing prose round-trip test's +harness verbatim). + +Run: `cargo test --workspace -p ailang-prose ` +Expected: FAIL (the `:909` render walker hits the stub/`todo` arm +or mis-renders). + +- [ ] **Step 4.2: Render + free-var + subst arms.** + +`crates/ailang-prose/src/lib.rs:909` — real render arms for +`Term::Loop` (binder list + body) / `Term::Recur` (args), mirroring +the `Term::Mut`/`Assign` render at `:909–933`. `:1109` — +`count_free_var`: loop binders bind (done in Task 1.4 if this file +built; confirm the arm is the binding-aware one, not pass-through). +`:1251` — `subst_var_with_term` rebuilder: reconstruct +`Term::Loop` rebuilding each `LoopBinder` (mirror the `MutVar` +reconstruction at `:1253–1276`), `Term::Recur` rebuilding args. + +- [ ] **Step 4.3: GREEN.** + +Run: `cargo test --workspace -p ailang-prose` +Expected: PASS (all prose tests, including the new round-trip pin). + +--- + +## Task 5: Real typecheck — binder typing, recur unification, loop_stack (DD-1) + +**Files:** `crates/ailang-check/src/lib.rs`, all `synth` call +sites that thread `mut_scope_stack`. + +- [ ] **Step 5.1: RED — positive typecheck + four negatives.** + +Create the four negative `.ail.json` fixtures and the positive +check via `crates/ailang-check/tests/loop_recur_pin.rs`: + +```rust +// recur_outside_loop.ail.json: (recur 1) at fn-body top level +// recur_arity_mismatch.ail.json: (loop ((var i Int 0)) (recur 1 2)) +// recur_type_mismatch.ail.json: (loop ((var i Int 0)) (recur true)) +// recur_not_in_tail_position.ail.json: +// (loop ((var i Int 0)) (do (recur i) 0)) // recur not in tail pos +#[test] +fn loop_smoke_typechecks_clean() { + assert!(check_ok("examples/loop_smoke.ail")); +} +#[test] +fn recur_outside_loop_is_rejected() { + assert_eq!(check_err_code("examples/test_recur_outside_loop.ail.json"), + "recur-outside-loop"); +} +// ...arity-mismatch -> "recur-arity-mismatch", +// type-mismatch -> "recur-type-mismatch", +// not-in-tail-pos -> "recur-not-in-tail-position" +``` + +(Use the exact fixture-loading + code-extraction helpers +`crates/ailang-check/tests/mut_typecheck_pin.rs` uses — copy that +driver's helpers verbatim.) + +Run: `cargo test --workspace -p ailang-check --test loop_recur_pin` +Expected: FAIL — `loop_smoke` errors with the Task 1.6 stub +`Internal("…typecheck lands in it.1 Task 6")`; the four negatives +also hit the stub (wrong code). + +- [ ] **Step 5.2: Add the four `CheckError` variants.** + +In `crates/ailang-check/src/lib.rs` `CheckError` enum, beside +`MutVarCapturedByLambda` (`:680`), add (Display body **without** an +embedded `[code]` prefix — the CLI formatter prepends it; 2026-05-15 +F2 convention): + +```rust +#[error("recur outside of any enclosing loop")] +RecurOutsideLoop { span: Option }, +#[error("recur passes {got} argument(s) but the enclosing loop binds {want}")] +RecurArityMismatch { got: usize, want: usize, span: Option }, +#[error("recur argument {pos} has type {got} but loop binder `{name}` is {want}")] +RecurTypeMismatch { pos: usize, name: String, got: String, want: String, span: Option }, +#[error("recur must be in tail position of its enclosing loop")] +RecurNotInTailPosition { span: Option }, +``` + +Add the matching `code()` arms beside `:732` (`"recur-outside-loop"`, +`"recur-arity-mismatch"`, `"recur-type-mismatch"`, +`"recur-not-in-tail-position"`) and `ctx()` arms beside `:802` +(mirror the `MutAssignOutOfScope` ctx shape). Add the four code +strings to the diagnostic-doc list in +`crates/ailang-check/src/diagnostic.rs` (same list the mut codes +were added to). + +- [ ] **Step 5.3: Thread `loop_stack` through `synth` (DD-1).** + +Change `synth`'s signature to add, immediately after the +`mut_scope_stack: &mut Vec>` parameter: + +```rust +loop_stack: &mut Vec>, +``` + +Propagate it through **every** recursive `synth` call and every +external call site exactly where `mut_scope_stack` is already +passed: all `lib.rs` recursive sites, `mono.rs:712`/`:1337`, +`lift.rs:723`, the `builtins.rs` test helpers, and the mq.3 in-test +helper at `lib.rs:6663`. (Grep `mut_scope_stack` to get the exact +site set; `loop_stack` goes through the identical set — this is the +mut.2 dev-dep-cycle-aware pattern; integration tests call across the +edge, in-source `#[cfg(test)]` cannot.) + +- [ ] **Step 5.4: Real `Term::Loop` / `Term::Recur` typing arms.** + +Replace the Task 1.6 stub arm in `synth` (`:3614` region) with: + +```rust +Term::Loop { binders, body } => { + let mut binder_tys = Vec::with_capacity(binders.len()); + let mut frame = IndexMap::new(); + for b in binders { + let init_ty = self.synth(&b.init, env, locals, mut_scope_stack, loop_stack, /*…existing args…*/)?; + self.unify(&init_ty, &b.ty).map_err(|_| CheckError::AssignTypeMismatch { /* reuse shape: init vs declared */ })?; + frame.insert(b.name.clone(), b.ty.clone()); + binder_tys.push(b.ty.clone()); + } + loop_stack.push(binder_tys); + locals.push(frame); // same frame mechanism Term::Mut uses + let body_ty = self.synth(body, env, locals, mut_scope_stack, loop_stack, /*…*/)?; + locals.pop(); + loop_stack.pop(); + Ok(body_ty) +} +Term::Recur { args } => { + let want = loop_stack.last().cloned() + .ok_or(CheckError::RecurOutsideLoop { span: None })?; + if args.len() != want.len() { + return Err(CheckError::RecurArityMismatch { + got: args.len(), want: want.len(), span: None }); + } + for (i, (a, wt)) in args.iter().zip(want.iter()).enumerate() { + let at = self.synth(a, env, locals, mut_scope_stack, loop_stack, /*…*/)?; + if self.unify(&at, wt).is_err() { + return Err(CheckError::RecurTypeMismatch { + pos: i, name: format!("#{i}"), + got: type_display(&at), want: type_display(wt), span: None }); + } + } + Ok(Type::never()) // recur does not fall through; bottom unifies anywhere +} +``` + +(Match the EXACT `self.synth(...)` argument list of the neighbouring +`Term::Mut` arm — copy its call shape, only adding `loop_stack`. +Use the project's existing bottom/never type constructor; if none +exists, return the innermost loop's body type sentinel the way the +`Term::Mut` arm returns its body type — pick `Type::unit()` only if +the codebase has no bottom; record which in the journal. Use the +real `unify` / `type_display` identifiers from the neighbouring +arms.) + +- [ ] **Step 5.5: `verify_tail_positions` recur-tail arms (DD-1).** + +In `crates/ailang-check/src/lib.rs:2590` `verify_tail_positions` +(signature unchanged), add arms — modelled on the existing +`Term::Mut` arm at `:2672–2677`: + +```rust +Term::Loop { binders, body } => { + for b in binders { verify_tail_positions(&b.init, false)?; } + // recur is legal and must be tail INSIDE this body: + verify_loop_body(body)?; // new private helper, below +} +Term::Recur { .. } => { + // Reached here only OUTSIDE a loop body's tail context + // (verify_loop_body intercepts the in-tail ones). Either no + // enclosing loop (synth already flags RecurOutsideLoop) or + // non-tail position: + return Err(CheckError::RecurNotInTailPosition { span: None }); +} +``` + +Add the private helper next to `verify_tail_positions`: + +```rust +fn verify_loop_body(t: &Term) -> Result<(), CheckError> { + match t { + Term::Recur { .. } => Ok(()), // tail position: OK + Term::If { cond, then, els } => { + verify_tail_positions(cond, false)?; + verify_loop_body(then)?; verify_loop_body(els) + } + Term::Seq(items) => { + // only the last item is in tail position + for it in &items[..items.len().saturating_sub(1)] { + verify_tail_positions(it, false)?; + } + if let Some(last) = items.last() { verify_loop_body(last)?; } + Ok(()) + } + Term::Match { scrutinee, arms } => { + verify_tail_positions(scrutinee, false)?; + for a in arms { verify_loop_body(&a.body)?; } + Ok(()) + } + Term::Let { value, body, .. } => { + verify_tail_positions(value, false)?; + verify_loop_body(body) + } + Term::Loop { .. } => verify_tail_positions(t, true), // inner loop: its own recur scope + other => verify_tail_positions(other, true), + } +} +``` + +(Mirror the EXACT child-arm names the existing `verify_tail_positions` +`Term::If`/`Term::Seq`/`Term::Match`/`Term::Let` arms use at +`:2590–2682` — copy their destructuring shapes verbatim; the only +new behaviour is "a `Recur` in tail context is OK, anywhere else is +`RecurNotInTailPosition`".) + +- [ ] **Step 5.6: GREEN.** + +Run: `cargo test --workspace -p ailang-check --test loop_recur_pin` +Expected: PASS — `loop_smoke` typechecks; the four negatives each +return their exact code. + +Run: `cargo test --workspace 2>&1 | tail -3` +Expected: all green (the `loop_stack` threading touched many call +sites; no regression). + +--- + +## Task 6: Carve-out inventory + check the corpus still classifies + +**Files:** `crates/ailang-core/tests/carve_out_inventory.rs`. + +- [ ] **Step 6.1: Extend EXPECTED.** + +In `carve_out_inventory.rs:23–40` `const EXPECTED`, add the four +new negative fixtures (`test_recur_outside_loop.ail.json`, +`test_recur_arity_mismatch.ail.json`, +`test_recur_type_mismatch.ail.json`, +`test_recur_not_in_tail_position.ail.json`), count 13 → 17, +preserving alphabetical order if the const is sorted. + +- [ ] **Step 6.2: GREEN.** + +Run: `cargo test --workspace -p ailang-core carve_out_inventory` +Expected: PASS (inventory matches the `.ail.json`-only set). + +--- + +## Task 7: Real codegen — loop-header + phi, recur back-edge, lambda boundary + +**Files:** `crates/ailang-codegen/src/lib.rs`, +`crates/ailang-codegen/src/lambda.rs`, `examples/loop_counter.ail`. + +- [ ] **Step 7.1: RED — e2e fixture.** + +`examples/loop_counter.ail` (sum 1..10 via an accumulator loop; +equivalent tail-rec helper prints `55`): + +``` +(module loop_counter + (fn main : () -> () !IO () + (app print + (loop ((var acc Int 0) (var i Int 1)) + (if (app gt i 10) + acc + (recur (app add acc i) (app add i 1))))))) +``` + +(Match `examples/mut_counter.ail`'s exact `print`/`gt`/`add` +spellings + module/fn header form verbatim — read it first.) + +Add an e2e assertion (mirror the `mut_counter` e2e in +`crates/ail/tests/e2e.rs`): + +```rust +#[test] +fn loop_counter_runs_and_prints_55() { + assert_eq!(run_example("examples/loop_counter.ail").trim(), "55"); +} +``` + +Run: `cargo test --workspace -p ail --test e2e loop_counter_runs_and_prints_55` +Expected: FAIL — codegen hits the Task 1.6 stub +`CodegenError::Internal("…codegen lands in it.1 Task 7")`. + +- [ ] **Step 7.2: `Term::Loop` lowering — header block + phi.** + +Replace the Task 1.6 `lower_term` stub (`:1326` match, `Term::Mut` +neighbour `:1762`) with: + +```rust +Term::Loop { binders, body } => { + // 1. lower each binder init in the CURRENT block + let mut init_ssa = Vec::with_capacity(binders.len()); + for b in binders { + let (v, ty) = self.lower_term(&b.init, /*…existing args…*/)?; + init_ssa.push((b.name.clone(), b.ty.clone(), v, ty)); + } + let pred = self.current_block_label(); + let header = self.fresh_label("loop.header"); + self.emit(&format!(" br label %{header}\n")); + self.start_block(&header); + // 2. one phi per binder; record the SSA name so Term::Var + // inside the body resolves to the phi, and Term::Recur + // knows the back-edge incoming list. Reuse the + // mut_var_allocas-style name->ssa map (a parallel + // loop_binder_phis: Vec<(String, phi_ssa, llvm_ty)> on a + // per-loop save stack mirroring mut.3's save/restore). + let mut phis = Vec::new(); + for (name, decl_ty, iv, _) in &init_ssa { + let p = self.fresh_ssa(); + let lty = self.llvm_ty(decl_ty); + // back-edge incomings are patched after the body is lowered + self.emit(&format!(" {p} = phi {lty} [ {iv}, %{pred} ] ; +recur edges\n")); + phis.push((name.clone(), p, lty, decl_ty.clone())); + } + self.push_loop_frame(header.clone(), phis.clone()); // name->phi + header label + let (body_v, body_ty) = self.lower_term(body, /*…*/)?; + let recur_edges = self.pop_loop_frame(); // Vec<(pred_label, Vec)> + // 3. patch each phi's incoming list with the collected recur edges + self.patch_loop_phis(&header, &phis, &recur_edges); + // 4. the loop's value is the body value on the non-recur exit + Ok((body_v, body_ty)) +} +Term::Recur { args } => { + let frame = self.current_loop_frame() + .expect("Term::Recur without loop frame — typecheck guarantees this"); + let mut arg_ssa = Vec::with_capacity(args.len()); + for a in args { + let (v, _) = self.lower_term(a, /*…*/)?; + arg_ssa.push(v); + } + let from = self.current_block_label(); + self.record_recur_edge(from.clone(), arg_ssa); // for phi patching + self.emit(&format!(" br label %{}\n", frame.header)); + self.block_terminated = true; // NEW seam (additive) + Ok((self.unit_ssa(), Type::unit())) +} +``` + +Add the minimal helper surface used above next to the +`mut_var_allocas`/`pending_entry_allocas` fields (`:725–737`), +mirroring their lifecycle: `loop_frames: Vec` where +`LoopFrame { header: String, phis: Vec<(String,String,String,Type)>, +recur_edges: Vec<(String, Vec)> }`; `push_loop_frame` / +`pop_loop_frame` / `current_loop_frame` / `record_recur_edge` / +`patch_loop_phis` / `current_block_label` / `start_block` / +`fresh_label`. Where an equivalent already exists (e.g. a +fresh-label or current-block helper), REUSE it — grep before adding. +`Term::Var` resolution must consult the innermost `loop_frames` +phi map *before* the `mut_var_allocas` load path (a binder name +shadows like a mut var), exactly as mut.3 prepended the mut-var +lookup in the `Term::Var` arm. + +**Do not modify** any of the seven existing +`block_terminated = true` sites (`:1377,:1601,:2271,:2352,:2493, +:2565,:2657`) or the `tail`-driven `emit_call`/`emit_indirect_call`/ +`lower_effect_op` paths — recur's `block_terminated = true` is a new +parallel setter (spec it.1 additive constraint). + +- [ ] **Step 7.3: Lambda boundary (loop-inside-lambda).** + +In `crates/ailang-codegen/src/lambda.rs`, the save/restore block +(`:119–154` save, `:248–260` restore) that already saves +`block_terminated`/`mut_var_allocas`/`pending_entry_allocas`/ +`entry_block_end_marker` across the closure boundary: add +`loop_frames` to the saved+reset+restored set so a `loop` inside a +lambda body scopes its header/phis to the closure's own entry, not +the outer fn's (exact mut.3 analogue — mirror the lines that handle +`mut_var_allocas` at `:144`/`:252`). + +- [ ] **Step 7.4: GREEN.** + +Run: `cargo test --workspace -p ail --test e2e loop_counter_runs_and_prints_55` +Expected: PASS (prints `55`). + +Run: `ail run examples/loop_nested_in_lambda.ail` (build first if +needed) — Expected: builds and runs without codegen error +(loop-inside-lambda lowers to the closure's own header). + +- [ ] **Step 7.5: Full workspace gate.** + +Run: `cargo test --workspace 2>&1 | tail -3` +Expected: all green. `tail-app` fixtures still build+run unchanged +(no existing codegen path was modified). + +--- + +## Task 8: tail-app coexistence proof + IR snapshots + +**Files:** IR snapshot fixtures if any new unconditional declare +line was added (none expected — loop adds no extern); the existing +`tail-app` corpus. + +- [ ] **Step 8.1: Prove `tail-app` is untouched.** + +Run: `ail run examples/bench_compute_intsum.ail` and +`ail run examples/list_map_poly.ail` +Expected: byte-identical stdout to pre-it.1 (these are `tail-app` +fixtures; it.1 must not perturb them). + +- [ ] **Step 8.2: IR snapshot check.** + +Run: `cargo test --workspace 2>&1 | grep -iE "snapshot|\.ll" | tail` +Expected: no IR-snapshot test regressed. If one did, it means an +unconditional IR-header line changed — investigate; loop codegen +should add none (no new extern). Do NOT blanket-regen snapshots; +the expectation is zero snapshot drift in it.1. + +- [ ] **Step 8.3: Acceptance gate (spec it.1 acceptance criteria).** + +Run: `cargo test --workspace 2>&1 | tail -3` +Expected: all green. + +Verify each spec it.1 acceptance bullet: +- `examples/loop_counter.ail` builds + prints `55` ✓ (Task 7.4) +- `loop`/`recur` round-trips, JSON-AST hashable ✓ (Tasks 1.7, 3.3) +- all five `Recur*` diagnostics fire on negatives — note: only + **four** `Recur*` variants exist in it.1 + (`RecurOutsideLoop`/`RecurArityMismatch`/`RecurTypeMismatch`/ + `RecurNotInTailPosition`); the spec's "five" counts + `NonStructuralRecursion`, which is **it.2**, not it.1. The it.1 + gate is the four `Recur*` (Task 5.6) ✓ +- `tail-app` still works unchanged ✓ (Task 8.1) +- `cargo test --workspace` green ✓ + +--- + +## Self-review (planner Step 5) + +1. **Spec coverage.** Spec §Components it.1 bullets → tasks: AST+serde + → T1.1/1.7; schema-drift+DESIGN+coverage → T1.8–1.10; Form-A + parse → T2; print → T3.1; round-trip fixture → T3.2/3.3; prose + → T4; check (binder typing + recur unify + tail-pos) + 4 + diagnostics → T5; codegen loop-header/phi + recur + escape + + lambda → T7; e2e loop_counter → T7.1/7.4; ~25 walker arms → T1.3– + 1.5; carve-out → T6. All it.1 spec sections covered. it.2/it.3 + explicitly excluded (Task 8.3 calls out the spec's "five + diagnostics" wording counting an it.2 variant — resolved as + "four in it.1", not a placeholder). +2. **Placeholder scan.** No "TBD/TODO/implement later/similar to + Task N/add appropriate error handling". The structural-arm + template + enumerated site list is literal code + literal + locations, not a placeholder. The "copy the neighbouring + `Term::Mut` arm verbatim, swapping the constructed struct" + instructions are exact transformations of named, line-located + existing code — executable without judgement. +3. **Type/name consistency.** `Term::Loop`/`Term::Recur`/ + `LoopBinder`, `loop_stack: &mut Vec>`, the four codes + `recur-outside-loop`/`recur-arity-mismatch`/`recur-type-mismatch`/ + `recur-not-in-tail-position`, `examples/loop_smoke.ail`/ + `loop_counter.ail`/`loop_nested_in_lambda.ail`, + `loop_recur_pin.rs` — used consistently across all tasks. +4. **Step granularity.** Each step is one action (add arms at + enumerated sites / run one command / write one code block) in + the 2–5-minute band. The largest, T1.3–1.5, is bounded by the + recon site list and a fixed per-site template. +5. **No commit steps.** None present. Work stays in the working + tree; the Boss commits the whole it.1 diff at iter end. + +Open risk recorded for the implementer (not a placeholder — a named +fallback with a decision rule): if the codebase has no bottom/never +`Type` constructor for `Term::Recur`'s synth result (Step 5.4), +use `Type::unit()` and record the substitution in the per-iter +journal; `recur` is always in tail position so its "value" is never +consumed, making the choice observationally inert.