AILang/docs/journals/2026-05-16-iter-revert.md

# iter revert — Iteration-discipline milestone surgical forward revert

**Date:** 2026-05-16
**Started from:** abf00131c10ff9287b419439c565480c96fa861b
**Status:** DONE
**Tasks completed:** 11 of 11

## Summary

The Iteration-discipline milestone (it.1 `96db54d` + it.2 `a4be1e5`)
is fully backed out by a single forward iteration, with `1ff7e81`
(the last commit before milestone-start `9973546`) as the per-region
byte oracle. `main` was never rewound — every restore is a forward
working-tree edit, net-new it.1/it.2 surface is `rm`'d, DESIGN.md is
hunk-edited in place (clause 3 / criterion section KEPT, never
wholesale-restored). Feature-acceptance clause 3 and the F3 todo are
retained; the clause-3 worked example is de-claimed from "shipped" to
hypothetical-illustration form (in DESIGN.md and brainstorm SKILL.md
in lockstep); one honest F1/F4 documentation note is added (the only
net addition) and guarded by a doc-presence test. The correctness
gate (Task 11) proved compiler behaviour **pristine**: all 164
surviving `1ff7e81`-era fixtures `ail check`/`ail run` byte-identical
to their pre-milestone behaviour; `cargo test --workspace` 600/0;
zero residual it.1/it.2 production surface. AILang's iteration story
is exactly the pre-`9973546` state (structural / tail recursion;
`tail-app` intact); the genuine total-recursion ambition is preserved
on the roadmap as a deferred P2 milestone sequenced behind a future
`Nat`/refinement-types milestone.

## Per-task notes

- revert.1: AST node family + drift anchors + DESIGN.md §Data-model —
  removed `Term::Loop`/`Term::Recur`/`struct LoopBinder` + 2 serde
  units (ast.rs byte-identical to oracle); loop/recur exemplars +
  match arms removed from design_schema_drift.rs / spec_drift.rs /
  schema_coverage.rs (byte-identical); DESIGN.md §Data-model
  loop/recur JSON + it.1/it.2 prose removed (region byte-identical).
- revert.2: `CheckError` surface — 5 variants + doc comments, 5
  `code()` arms, 3 dedicated `ctx()` arms deleted; `_ =>` catch-all
  preserved; diagnostic.rs confirmed genuine no-op.
- revert.3: it.2 guardedness pass + Diverge-injection — STOP-gate
  cleared (all 6 named helpers it.2-net-new at oracle → all delete,
  no ambiguity). Removed the entire 687-line guardedness cluster
  (verify_structural_recursion, term_contains_loop, adt_families,
  referenced_con_names, mutual_structural_group, adt_param_positions,
  RecCall, TypeUnionFind, MutualGroup, et al.) **plus** the
  transitively-it.2 `module_fns` plumbing through
  check_module/check_def/check_fn signatures (oracle proved net-new;
  resolved via the plan's Oracle convention + recon-by-name mandate —
  see Concerns). 3 Diverge-injection sites restored byte-identical;
  lib.rs `"Diverge"` count 0 == oracle.
- revert.4: it.1 check surface — synth Loop/Recur arms +
  verify_loop_body deleted; loop_stack param + ~30 threaded calls + 9
  local decls removed; verify_tail_positions survives, it.1 arms
  removed, byte-identical to oracle; substitute_rigids_in_term +
  post-mono name arms cleaned. Result:
  `crates/ailang-check/src/lib.rs` FULLY byte-identical to `1ff7e81`.
- revert.5: 9 remaining walker files (lift/mono/linearity/uniqueness/
  reuse_shape/pre_desugar_validation/builtins + core desugar/
  workspace) restored to oracle, all byte-identical; pre-restore diff
  classification proved every hunk it.1/it.2-only.
- revert.6: surface + prose + form-A grammar — parse.rs/print.rs/
  prose lib.rs/form_a.md restored to oracle byte-identical; each
  touched only by 96db54d (it.1) since 1ff7e81; surface+prose build
  clean.
- revert.7: codegen — lib.rs/escape.rs/lambda.rs + ail/main.rs
  restored to oracle byte-identical; `block_terminated = true` count
  == 8 == oracle (it.1 parallel setter gone; the 4 tail-driven + 4
  control-flow setters survive). `cargo build --workspace` clean
  (first full-build gate, lockstep clustering worked as designed).
- revert.8: STOP-gate re-verify cleared (live `git diff --stat`
  matched plan's net-new/modified/absent classification exactly).
  Deleted 2 pin files + 16 fixtures + bench/it3-oracle via plain
  `rm` (no git-index touch). 2 RC fixtures restored byte-identical.
  e2e.rs + codegen_import_map_fallback_pin.rs + carve_out_inventory.rs
  restored byte-identical (carve = "Twelve carve-outs", last entry
  test_mut_var_captured_by_lambda.ail.json). it.{1,2,3} stats json
  KEPT. cargo test --workspace 599/0.
- revert.9: DESIGN.md Decision 3 → 1ff7e81 placeholder (byte-identical,
  hunk-only); clause-3 worked example de-claimed to hypothetical form
  (criterion section + clause-3 discriminator KEPT); brainstorm
  SKILL.md de-claimed in lockstep; F1/F4 note added verbatim;
  doc-presence test added verbatim, PASSES.
- revert.10: roadmap Iteration-discipline [~] block + blocking-fork
  sub-section removed; deferred "Iteration-totality story" entry
  added verbatim at top of P2 (per plan + spec sequencing); F3 +
  Stateful-islands untouched; superseded header prepended to the old
  spec; Step-4 STOP-check clean (no residual A1 amendment).
- revert.11 (correctness gate): 1ff7e81 ref compiler built in
  throwaway worktree; 164-fixture check/run oracle captured;
  post-revert compiler diffed byte-for-byte — fail=0, ZERO DRIFT,
  behaviour PRISTINE. cargo test --workspace 600/0. Residual
  it.1/it.2 production-surface grep clean. Worktree removed; main
  HEAD never moved.

## Concerns

- revert.3: the plan's Task-3 file-map enumerated the guardedness
  helpers + call site but did NOT explicitly list the `module_fns`
  signature threading through check_module/check_def/check_fn. The
  `1ff7e81` oracle unambiguously proved that threading it.2-net-new;
  leaving it would have been dead it.2 surface referencing deleted
  helpers. Resolved correctly via the plan's own "Oracle convention"
  + "re-locate by symbol name, oracle is authority on every byte"
  mandate + the spec §Data-flow ("restored to pure pre-it.1 role").
  This is the recon-map-drifts-but-oracle-is-authority mechanism
  working as designed, not a plan defect — no bounce. Flagged so the
  Boss is aware the plan file-map under-enumerated one signature
  edge; the end-state is verified correct (lib.rs byte-identical to
  oracle).
- revert.9: the plan's Task-9 Step-6 single-line grep heuristic
  (`grep -c 'clauses 1 and 2 yet fail clause 3' ...`) returned 0
  because the verbatim-applied replacement text line-wraps ("yet
  fail\n   clause 3"). The substantive acceptance criterion
  (clause-3 block retained, only de-claimed) is positively verified
  multiline + by the intact `## Feature-acceptance criterion` section
  and "criterion 3 is the discriminator" sentence. Not a defect;
  flagged so the Boss does not misread the heuristic.

## Known debt

(none — the revert is byte-pristine against `1ff7e81` for all
production surface; behaviour is byte-identical over the surviving
corpus.)

## Blocked detail

(none — DONE.)

## Files touched

90 working-tree paths (Boss commits all as one cohesive revert iter):

- Deleted (59): `crates/ailang-check/tests/loop_recur_pin.rs`,
  `crates/ailang-check/tests/structural_recursion_pin.rs`; 16 it.1/it.2
  fixtures under `examples/` (loop_*.ail, struct_rec_*.ail,
  test_recur_*.ail.json, test_loop_missing_diverge / test_mutual_cross_family
  / test_non_structural_recursion .ail.json); `bench/it3-oracle/`
  (MANIFEST.tsv + 40 .out).
- Modified — source revert to 1ff7e81 (byte-identical):
  `crates/ailang-core/src/ast.rs`, `desugar.rs`, `workspace.rs`;
  `crates/ailang-check/src/lib.rs`, `lift.rs`, `mono.rs`,
  `linearity.rs`, `uniqueness.rs`, `reuse_shape.rs`,
  `pre_desugar_validation.rs`, `builtins.rs`;
  `crates/ailang-codegen/src/lib.rs`, `escape.rs`, `lambda.rs`;
  `crates/ail/src/main.rs`; `crates/ailang-surface/src/parse.rs`,
  `print.rs`; `crates/ailang-prose/src/lib.rs`;
  `crates/ailang-core/specs/form_a.md`.
- Modified — tests revert to 1ff7e81 (byte-identical):
  `crates/ailang-core/tests/spec_drift.rs`, `schema_coverage.rs`,
  `carve_out_inventory.rs`; `crates/ail/tests/e2e.rs`,
  `codegen_import_map_fallback_pin.rs`.
- Modified — net-add / hunk-edit:
  `crates/ailang-core/tests/design_schema_drift.rs` (loop/recur
  anchors removed + new doc-presence test added),
  `docs/DESIGN.md` (Decision 3 placeholder + clause-3 de-claim +
  F1/F4 note; hunk-edited, clause 3 kept), `docs/roadmap.md`
  (Iteration-discipline block removed, deferred P2 entry added),
  `docs/specs/2026-05-15-iteration-discipline.md` (superseded
  header), `skills/brainstorm/SKILL.md` (worked-example de-claim).
- Modified — fixtures restored to 1ff7e81:
  `examples/rc_pin_recurse_implicit.ail`,
  `examples/rc_let_alias_implicit_param.ail`.
- KEPT (no-op, Boss decision):
  `bench/orchestrator-stats/2026-05-15-iter-it.{1,2,3}.json`.

E2E coverage: none (revert iteration — the Task-11 behavioural-
equivalence sweep over all 164 surviving fixtures is a stronger
correctness proof than new E2E; the doc-presence test guards the
only net-new artefact).

## Stats

bench/orchestrator-stats/2026-05-16-iter-revert.json