…etup-python-6

ci: bump actions/setup-python from 5 to 6

Fourth bug surfaced during the Game of Life agent run: Vera's
compiler doesn't emit WASM return_call in tail positions, so
tail-recursive functions — the documented for/while replacement —
blow the call stack at ~tens of thousands of frames.

Added:
- KNOWN_ISSUES.md: new row under Bugs describing the missing
  TCO and the SKILL.md idiom-vs-reality gap.
- ROADMAP.md: #517 inserted at position 4 in the short-term
  implementation-order table; #475 pushed to #5, #507 to #6.

No code changes.

Co-Authored-By: Claude <noreply@anthropic.invalid>

…nt-integration

Reframed "What's next" to acknowledge the stabilisation work uncovered
by the v0.0.119–v0.0.137 bug-killing campaign. Two patterns worth
closing out before declaring runtime-correctness floor raised:

1. Scale-dependent bugs slip past the standard test suite (#515,
   #570, #487, now #593 — all required real-world programs at scale
   to surface; none would have been caught by the existing 3,747
   small focused tests).

2. Walker-completeness gaps are silent failures of the same shape
   (#588 found _walk_free_vars missing 8 AST branches; we don't yet
   know if other walkers in the codebase have similar incompleteness).

The "Implementation order" table is now split into two tiers:

  - Stabilisation tier (priority): #593, #596, #597, #595
  - Agent-integration tier (resumes after): #222, #523, #370

#596 (stress-test harness) and #597 (walker-completeness audit) are
new issues filed in this PR — they convert "I think we're stabilising"
into evidence by building the infrastructure that prevents recurrence
of the bug classes #588 and #593 surfaced.

#593 retains the lead position because it's the largest open codegen
unknown — bisection narrows it to 12x30 + recursive run_loop with
allocating call argument, but the root cause hasn't been isolated.
Until then, "WASM codegen is stable at scale" is unverified.

#595 sits last in the stabilisation tier because it likely shares a
root cause with #593 (both surface together at the same scale); fixing
#593 may close it. The v0.0.137 KeyboardInterrupt guard already
prevents the Python-traceback half.

Order #5 (LSP) doesn't start until orders #1-#4 close (or are
explicitly deferred with an open follow-up). Tier separator is
explicit so future readers don't have to reverse-engineer the
ordering rationale.

Co-Authored-By: Claude <noreply@anthropic.invalid>

1. HISTORY.md "137 tagged releases" -> 138 (line 315): the v0.0.138
   row was added but the rollup footer count still said 137.

2. ROADMAP.md stabilisation-gate sentence: "order #5 starts when
   #1-#4 are closed" -> "order #4 starts when #1-#3 are closed".
   The earlier deletion of the #593 row (now closed) shifted the
   stabilisation tier to three items; the agent-integration tier
   numbering is also renumbered 5/6/7 -> 4/5/6 to match.

3. New test: test_eager_gc_array_mapi_with_non_allocating_string_closure
   mirrors the existing array_map String eager-GC test for the
   array_mapi unwind path with a fn(@Bool, @nat -> @string) closure
   returning pick(@Bool.0).  The existing array_mapi ADT test
   (test_array_mapi_non_allocating_closure_emits_balanced_push)
   covered the i32 branch; this new test covers the i32-pair branch.

4. Tighten the structural #593 predicate.  Pre-fix it accepted any
   "global.set $gc_sp" + absent "call $alloc"; CodeRabbit observed
   that a bare "global.set $gc_sp" could in principle be a stack-
   restore rather than a push.  In practice the prologue's
   gc_sp_save/restore is gated on ctx.needs_alloc and the regex
   already excludes call $alloc, so a non-allocating body cannot
   contain a restore -- but the literal predicate was weaker than
   the intent.  Adds _has_gc_shadow_push helper that anchors on the
   canonical "i32.const 4 / i32.add / global.set $gc_sp" SP-increment
   sequence emitted by gc_shadow_push (vera/wasm/helpers.py).  Used
   by both the i32-pair and i32-ADT structural tests; a non-push
   artefact in the body can no longer satisfy the assertion.

Plus: HISTORY.md tooling section gains a v0.0.138 row for
VERA_EAGER_GC alongside the existing tooling milestones (cross-
linked to ENVIRONMENT.md, which already has the full reference
section for it).

Suite: 3,747 passed (+1 from new array_mapi String test), 14 skipped.

Co-Authored-By: Claude <noreply@anthropic.invalid>

Two Conway's Life agent experiments on --target browser surfaced
five concrete blockers (issues #602/#603/#604/#609/#610) and an
explicit design memo (#608) mapping each obstacle to a concrete
runtime-only fix.  The current stabilisation framing covers
codegen reliability and walker completeness but treats browser-
target reliability as a separate concern.  The agent's diagnosis
makes that split harder to defend: "write once, run anywhere"
is currently true for pure computation and approximate-to-false
for anything with timing or screen output.  Two of the fixes
(#609 JSPI-driven IO.sleep, #610 ANSI subset interpreter) close
the timing and rendering halves of the seam without language
changes -- adding them to the stabilisation tier commits to
"browser-target Vera is something you'd actually use" before
the agent-integration push.

Changes:
- Expanded the campaign-pattern list from two patterns to three;
  third pattern documents the browser-target seam with links to
  the umbrella issue (#608) and the five concrete blockers.
- Added #609 (JSPI-driven IO.sleep) as item 3 in the stabilisation
  tier, with rationale + the WebAssembly JSPI / Asyncify mechanism.
- Added #610 (ANSI subset interpreter) as item 4 in the same tier,
  paired with #609 -- together they close the seam and let life.vera
  (terminal version) run unchanged on --target browser.
- Renumbered #595 from item 3 to item 5 (now last in stabilisation,
  since it's contingent on an upstream wasmtime-py release).
- Renumbered the agent-integration tier items 4/5/6 -> 6/7/8 to
  match.
- Updated the "What moves when" gate from "#4 starts when #1-#3
  are closed" to "#6 starts when #1-#5 are closed".

Co-Authored-By: Claude <noreply@anthropic.invalid>

…parsing

Two more valid CodeRabbit findings, both fixed:

## Stale-allowlist tracking

ALLOWED_SKIPS entries that never matched any warning during a
scan were silently suppressing nothing — and would silently mask
a future regression that re-introduces the same skip.  Mirrors
the pattern already in scripts/check_skill_examples.py.

Added a 'used_allowlist: set[str]' parameter to _scan_paths that
records each fn_name → allowlist match.  main collates 'set(ALLOWED_SKIPS) -
used_allowlist' and prints a 'STALE ALLOWLIST ENTRIES' section
with each stale entry's [code], tracking issue, and reason —
plus rationale paragraph telling the user to remove the entry
unless the affected program is being deliberately removed.  Exit
code 1 on any stale entries.

Verified by injecting a fake 'fake_stale_fn' entry: gate prints
the stale section + rationale + exits 1.

## Manifest-defensive parsing

The manifest_path.open + json.load chain previously assumed (a)
the file was valid UTF-8, (b) the parsed JSON was a list, (c)
every entry was a dict, (d) every dict had a 'file' key.  A
malformed manifest would crash with a Python traceback rather
than the structured stderr diagnostic the gate promises.

Three new defensive checks:

- 'except UnicodeDecodeError' on the open + 'except
  json.JSONDecodeError' on the parse, each producing a structured
  error message with file path + cause.
- 'isinstance(manifest, list)' check after parse with
  '{type}'.__name__ wording.
- Per-entry: 'isinstance(entry, dict)' check + explicit
  'entry.get("file")' validation with 'isinstance + non-empty
  string' shape check.  Errors include the entry id (or
  '<entry N>' fallback) for debugging.

Verified all three paths empirically: invalid JSON, JSON object
instead of array, and entry missing 'file' all produce clean
ERROR messages + exit 1.

Validated final clean run: 'Allowlisted skips suppressed: 11
known functions (11 matched, 0 stale)' — no behaviour change
when allowlist is current and manifest is well-formed.

Both findings are precision-tightening on artefacts added in
`0205f9c`.

CR-4 (CHANGELOG line 13)
The new `_error()` bullet ended with "No existing call sites
change", which contradicted the rest of the bullet — the [E699]
catch handlers in `_compile_fn` and `_compile_lifted_closure`
both DO change (route through `_error()` instead of `_warning()`).
The intended meaning was "no user-facing API surface changes", but
the loose shorthand was misleading.

Fix: rewrite to be explicit about what changed (the two named
internal handlers, both routed through the new `_error()` method),
and qualify the "no other call sites" claim to "no user-facing
API surface or other `_warning()` call sites".

CR-5 (test_codegen.py line 15939)
The span assertion in
`test_e602_location_points_at_offending_call_not_fn_header` used
`assert loc_line > 2` — too loose.  A regression that drifted the
catch-handler's span onto `IO.print(...)` (line 6) instead of
`map_insert(...)` (line 5) would slip past the test silently.

Fix: tighten to `assert loc_line == 5`.  Verified by running the
fixture through `_compile()` and reading `d.location.line`
directly (5, column 31 — the start of the `map_insert(...)` call).
Updated the assertion failure message to call out both regression
paths the loose check allowed: dropping back to the legacy
enclosing-fn span (line 2) AND drifting to any later call.

Validation
- pytest tests/test_codegen.py::TestE602NodeLevelReasons626Layer3 -v
  → 2 passed
- The full suite was last verified green in 0205f9c; this commit
  only touches comment text + an assertion bound, no production
  code

Refs #626 #658

Co-Authored-By: Claude <noreply@anthropic.invalid>

Five findings from CodeRabbit's review of #659 — three 🟠 Major
correctness issues and two 🟡 Minor quality-of-life
improvements.  All five verified valid against current code and
addressed minimally.

CR-1 (`scripts/check_e602_clean.py:174`) — 🟠
`_extract_skips()` filtered only `("E602", "E604")` but the
CHANGELOG entry and the suppression pass in
`vera/codegen/core.py` both treat `[E605]` as part of the same
template-warning surface.  A future E605 silent skip would have
slipped past the gate.  Added `"E605"` to the filter tuple +
inline comment cross-referencing the suppression pass.

CR-2 (`tests/test_codegen.py:15880`) — 🟡
`test_mono_suffix_correct_for_slotref_fn_alias_arg` asserted WAT
suffix strings but didn't execute the compiled module — a
regression that produced correct WAT but broken indirect-call
wiring would slip past.  Added `execute(result, fn_name="main")`
+ `assert exec_result.value == 20` to pin the runtime contract.
Also added a sibling test
`test_parameterised_alias_substitutes_type_args` exercising the
CR-4/CR-5 fix with the same execute+assert shape (21 for
`Some(7) * 3`).

CR-3 (`vera/codegen/core.py:552`) — 🟠
Pre-fix the template-warning suppression checked `_fn_sigs` for
the existence of mono clones.  But `_fn_sigs` is populated in
Pass 1.5 (registration) *before* any mono body is compiled — so
a clone that `_compile_fn(mdecl)` later rejects with `None` would
still be counted as "compiled" and wrongly suppress its
template's diagnostic.  That hides the only pre-runtime signal
for a genuinely-broken generic.  Introduced
`compiled_mono_bases: set[str]` populated only inside the
`if fn_wat is not None:` branch of the mono-clone compile loop.
Suppression now uses `compiled_mono_bases & forall_decl_names`.

CR-4 (`vera/codegen/monomorphize.py::_resolve_arg_fn_shape`) — 🟠
For a *parameterised* FnType alias like
`type Mapper<T> = fn(T -> T)`, `@Mapper<Int>.0` resolved to the
raw alias body `fn(T -> T)` without substituting `T → Int`.
Downstream `_infer_fn_alias_type_args` then bound alias-local
names (`A → T`, `B → T`) instead of concrete ones, producing
mono suffixes like `option_map$T_T` rather than
`option_map$Int_Int`.  Fixed by substituting the SlotRef's
`type_args` into the alias body before returning.

CR-5 (`vera/wasm/calls.py::_resolve_arg_fn_shape_wasm`) — 🟠
Same gap on the WASM call-site rewriting side.  Same fix applied.

Shared substitution helper
Rather than duplicate the type-var substitution logic in two
codegen modules, extended the existing module-level
`substitute_type_vars` in `vera/wasm/inference.py` (used by
`InferenceMixin` canonicaliser + `CodeGenerator._type_expr_to_wasm_type`)
to also handle `FnType` (it previously handled only `NamedType`
and `RefinementType`).  Both `_resolve_arg_fn_shape` helpers now
import + use the canonical implementation — same semantics
across all four callers, no drift risk.

Validation
- mypy: clean (59 source files)
- pytest: 3,794 passed, 14 skipped (was 3,793 + 1 new test)
- e602 gate: 116 files clean, 6 allowlist entries matched, 0 stale
- All 86 conformance programs pass; all 34 examples pass
  `vera check` + `vera verify`

Refs #604 #655 #659

Co-Authored-By: Claude <noreply@anthropic.invalid>

Following user direction to pull all 7 deferred pr-review
findings into this PR rather than file a follow-up.  The 4
small code fixes (items 2/3/5/8) plus 2 new test files
(items 6/7) land here.

Code fixes:

- **#2 ModuleCall path-drop** (`vera/wasm/inference.py:289-292`
  and `:~973`) — both `_infer_expr_wasm_type::ModuleCall` and
  `_infer_vera_type::ModuleCall` previously synthesised a fake
  `ast.FnCall(name=expr.name, args=expr.args)` for dispatch,
  silently dropping `expr.path: tuple[str, ...]`.  If a
  regression ever flowed a ModuleCall to either helper, the
  fake-FnCall lookup could match a same-name local fn from a
  different module — silent wrong-answer rather than safe
  failure.  Now both return `None` so the unknown-type surfaces
  cleanly.

- **#3 AnonFn placeholder** (`vera/wasm/inference.py:~967`) —
  `_infer_vera_type::AnonFn` previously returned the literal
  string `"Fn"` as a placeholder.  No callsite recognised
  `"Fn"` as a real Vera type; downstream type-arg mangling
  paths (`vera/wasm/calls.py:1525,1533`) would feed it into
  mangled names like `option_map$Int_Fn`.  Now returns `None`
  for the same reason.

- **#5 Factually wrong "closure pipeline" comments**
  (`vera/codegen/compilability.py:~236, ~393`, both WALKER_
  COVERAGE checklists + inline pre-branch comments) — the
  `AnonFn` defensive branches were described as "masked today
  by closure pipeline running its own scan", but pr-review
  surfaced that `vera/codegen/closures.py::_compile_lifted_
  closure` does NOT call `_scan_io_ops` or
  `_scan_body_for_state_handlers` on lifted bodies.  The
  AnonFn branch is the PRIMARY defence, not redundant.
  Comments now state this directly.

- **#8 Dead `is not None` guards** (`vera/wasm/inference.py:~954,
  ~961`) — `Block.expr` and `HandleExpr.body.expr` are non-
  Optional in the AST schema (`vera/ast.py:470, 481`).  The
  guards in the `_infer_vera_type` defensive branches were
  unreachable defensive code.  Removed; direct calls now.

Test additions:

- **#6 Synthetic-AST tests for defensive branches**
  (`tests/test_walker_defensive_branches_597.py`, 21 tests,
  296 lines) — direct AST invocation pinning each of the 11
  defensive branches plus the 5 pr-review fixes.  Without
  these the defensive branches have 0% coverage (`coverage
  run` confirmed) — a future refactor breaking one would
  land silently.

- **#7 Unit tests for the enforcement script**
  (`tests/test_check_walker_coverage_597.py`, 12 tests, 255
  lines) — pins the script's parsing logic: Expr subclass
  extraction, isinstance flattening (incl. tuple form),
  checklist-block anchoring (incl. CR-3 regression test:
  `# Foo → bar` outside the WALKER_COVERAGE block must not
  be counted), section-header tolerance, auto-discovery
  invariants, end-to-end exit code.

CHANGELOG/HISTORY:

- Extended the v0.0.151 entry with two new sub-sections under
  "Fixed" (pr-review follow-ups) and a new "Tests" section
  documenting the two regression-test files.

Doc counts (auto-validated by `check_doc_counts.py`):

- TESTING.md total: 3,827 → 3,860 tests (+33), 29 → 31 files
- TESTING.md table: two new rows for the test files
- ROADMAP.md: 3,827 → 3,860
- README.md: 3,827 → 3,860

Validation:

- `pytest tests/ -q` → 3,846 passed, 14 skipped (+33 net new)
- `mypy vera/` → clean
- `python scripts/check_walker_coverage.py` → 9 walkers cover
  all 29 Expr subclasses (clean)
- `python scripts/check_doc_counts.py` → consistent across all
  surfaces

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>