…lity

Empirically demonstrates the bug surfaced by CodeRabbit on PR #693 and
documented in #695: Map<K, T_heap> values stored as Python ints in
_map_store are invisible to the conservative GC scan.  A gc_collect
between map construction and value access reclaims the heap blocks,
producing silent use-after-free.

Reproducer pattern:
- json_parse builds Map<String, Json> with a JArray child block
- VERA_EAGER_GC=1 forces gc_collect on every alloc
- Option alloc inside json_get fires GC between parse and access
- json_array_length reads from freed block, returns 0 instead of 10

The xfail marker uses strict=True so the test will fail when the fix
lands and starts passing, that failure is the canonical handoff
signal to remove the marker.

Sibling regression test for Set<T_heap> (issue #705) will land
alongside the Set side of the fix.

Doc-counts updated: total 3947 -> 3948, test_codegen.py row tests
1129 -> 1130 lines 19293 -> 19367, ROADMAP overview 3947 -> 3948.

Refs #695, #705

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

…mpiler internals"

KNOWN_ISSUES.md "Refactoring needed" is for file decomposition (splitting
big files like test_codegen.py, test_checker.py, codegen/api.py).  The
mirror-to-bucket-as-truth move is an architectural cleanup, not a file
split, so it belongs in ROADMAP.md alongside other internal work.

Adds a new "Compiler internals" subsection under "Continuous: quality
and security hardening" — ROADMAP previously didn't have a place for
runtime-architecture follow-ups (only CI tooling, Verification depth,
Security, Testing gaps).

No code changes.

Skip-changelog: doc cross-reference cleanup, no shipped behaviour change

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CodeRabbit round 1 on PR #707, all five findings verified valid and fixed:

1. vera/browser/runtime.mjs `attach_bucket_to_wrapper` ordering (lines 1235+):
   The mirror bucket was allocated via `alloc(...)` and only linked into
   `wrapperPtr + 8` AFTER the populating loop ran.  Between alloc and link,
   any `allocString` call could trigger `$gc_collect`, find the bucket
   unreachable from the shadow stack (the JS side has no shadow-stack API),
   and reclaim it.  Three-step fix in both Map and Set branches:
     (a) write `bucketPtr` into `wrapperPtr + 8` IMMEDIATELY after alloc
         so the wrapper — which is shadow-pushed by the WAT-side
         `_emit_wrap_handle` in `vera/wasm/calls_containers.py` — roots
         the bucket before any sub-alloc.
     (b) zero-fill the bucket region (`new Uint8Array(...).fill(0)`) so
         free-list reuse can't leave stale i32s that the conservative
         scan would mistake for live heap pointers (extending unrelated
         blocks' lifetimes).  $alloc has no zero-fill on reclaim.
     (c) only then iterate, val_word first (no alloc) to slot-root any
         heap-pointer value before the key allocString fires.

2. vera/browser/runtime.mjs `readJson` (line 1804) + `readHtml` (line 2063):
   Bug introduced by the `wrapHandle` change earlier in this PR.  After
   that change, the wrapper body's +4 field stores `rawHandle | 0x80000000`
   (matching the #578 bit-31-tag discipline on the CLI side) — but
   `readJson` and `readHtml` still read +4 raw, so `mapStore.get(handle)`
   always missed.  Mask with `& 0x7FFFFFFF` before the lookup (the CLI
   uses the same constant in `_emit_unwrap_handle`).

3. vera/codegen/api.py `_alloc_map_wrapper` val_word ordering (line 1368+):
   Same val-word-first pattern that `_attach_bucket_from_dict` uses.  The
   loop body computed `val_word` AFTER calling `_alloc_string(caller, key_str)`,
   so the heap-pointer value `v` was held only in a Python local across
   a potentially-GC-firing alloc.  Now writes `val_word` to `slot + 8`
   first (no alloc), then allocates the key string.  The conservative
   scan traces every i32 word in the heap as a potential pointer
   regardless of any occupied flag, so writing into the slot is enough
   to root via wrapper → bucket → slot[+8].

4. vera/wasm/data.py (line 408 + line 515):
   The match-arm constructor-field shadow-push added for #705 didn't set
   `self.needs_alloc = True`, so `$gc_sp` / `$gc_stack_limit` globals
   could be unexported for a function whose only allocation trigger is
   a heap-pointer match binding — WAT would then reference undefined
   globals.  Added the flag flip.  Plus: the sibling `ast.BindingPattern`
   path (`match @Json.0 { @JSON -> ... }`) was missed entirely by the
   original #705 fix; it now applies the same `gc_shadow_push` +
   `needs_alloc = True` discipline for non-inline i32 scrutinees.

5. HISTORY.md footer (line 347): the totals line still read
   "158 tagged releases" after the v0.0.159 entry was added.  Bumped to
   159 (README was already updated to 159).

Validation:
- mypy clean (59 files).
- Map/Set/GC reachability (50), browser (99), JSON+HTML collection (83),
  match/pattern (47), conformance (425), walker GC + reclamation (15)
  all pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three findings verified valid and fixed:

1. vera/browser/runtime.mjs `attach_bucket_to_wrapper` (Map and Set
   branches): BigInt values were being coerced via `Number(v)` before
   `writeI32` into the slot.  For Vera i64 keys/vals, large BigInts
   could (a) truncate misleadingly in the slot or (b) land inside the
   heap range and be misread as live heap pointers by the conservative
   scan, extending unrelated blocks' lifetimes.  Mirror is write-only
   (actual reads go through `mapStore` / `setStore`), so writing 0
   for BigInt is harmless and structurally safer.  Dropped the
   `typeof v === 'bigint' ? Number(v) : 0` branch so BigInt falls
   through to 0; same fix for the kw (key word) and ew (set element)
   paths.

2. vera/wasm/data.py `_translate_let_destruct` (lines 195-210):
   the parallel of the match-arm constructor-field path, but missing
   the heap-rooting discipline.  `let MyAdt(@JSON) = makeThing();`
   extracted an i32 field into a fresh local that was invisible to
   the conservative scan until shadow-pushed.  Added the same
   `if wt == "i32" and type_name not in _INLINE_I32_TYPES:
     self.needs_alloc = True; gc_shadow_push(local_idx)`
   pattern that round 1 added to `_extract_constructor_fields` and
   the `BindingPattern` branch.  Three rooting paths now matching
   each other:
     - match-arm BindingPattern (round 1)
     - match-arm constructor-field extraction (round 1)
     - let-destruct field extraction (round 2)

3. vera/browser/runtime.mjs `allocMapWrapper`: the wrapper returned
   from `wrapHandle` was registered with the wrap-table but NOT
   rooted via the shadow stack.  The wrap-table region lives below
   `gc_heap_start` and is NOT scanned by Phase 2a marking, so
   `register_wrapper` alone doesn't keep the wrapper alive.  Between
   `wrapHandle` returning and `attach_bucket_to_wrapper`'s internal
   bucket allocation, a `$gc_collect` would have reclaimed the
   fresh wrapper.  Fix: added JS-side `gcShadowPush` / `gcShadowPop`
   helpers using the exported `$gc_sp` / `$gc_stack_limit` mutable
   globals (added in v0.0.158 / #692 but never used from JS), and
   wrapped the attach call in a try/finally push/pop pair —
   mirroring the CLI `_ShadowGuard` discipline.

Validation: mypy clean (59 files); browser (99), Map/Set/GC + walker
(56), let-destruct (5), JSON+HTML (57) all pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Aggregated four review agents (code-reviewer, pr-test-analyzer,
comment-analyzer, silent-failure-hunter) found 4 critical issues and
3 high-leverage test gaps.  All critical issues fixed; test gaps
addressed for CLI side (the new test caught a pre-existing browser
bug that needs its own follow-up, tracked as #708).

## Critical fixes

C1. `vera/browser/runtime.mjs` `gcShadowPush` / `gcShadowPop`: now
    raise `Error` when `$gc_sp` / `$gc_stack_limit` aren't exported,
    matching the CLI `_ShadowGuard.__init__` discipline that raises
    a clear `RuntimeError` for the same condition.  Prior behavior
    silently no-op'd → downstream UAF for any module built without
    GC support that tries to wrap a Map / Set value.

C2. `vera/browser/runtime.mjs` `wrapHandle`: now raises when
    `register_wrapper` isn't exported, matching the CLI-side
    `_call_register_wrapper`.  Prior behavior allocated the wrapper
    and seeded the JS-side mapStore entry but silently skipped the
    wrap-table registration → permanent leak per write.

C3. `tests/test_codegen.py::TestMapHostStoreGCReachability695`
    docstrings: rewrote the class docstring and the
    `test_eager_gc_json_object_with_array_child_post_walk_uaf`
    docstring to describe the mirror approach actually shipped
    (bucket-array reachability anchor), not the deferred "move"
    approach that the comments still described (the move is
    tracked as #706).  Also removed the stale "xfail marker must
    be removed" text — the marker was removed when the fix landed
    in 8b59454 / 7c4fe78.

C4. `vera/codegen/api.py` `host_attach_bucket`: distinguish
    "handle missing from store" (UAF — wrapper outlived its store
    entry, possibly via Phase 2c decref bug or wrap-table corruption)
    from "handle present, empty collection" (legitimate empty
    Map / Set).  Now raises `RuntimeError` for the UAF case.  Also
    split the Set branch's collapsed `kind == SET and set_ops_used`
    check (silent-failure-hunter I4) — unknown kinds + SET-without-
    set_ops_used now raise rather than silently leave bucket_ptr=0.

## High-leverage test additions

I1. `test_eager_gc_let_destruct_with_json_field_post_walk_uaf` —
    exercises BOTH the i32 heap-pointer field rooting (`@Json`)
    and the pair-type field rooting (`@String`) added to
    `_translate_let_destruct` in the round-2 / round-3 fixes via
    `let Tuple<@JSON, @string> = Tuple(...)` with an intervening
    `json_array_length` alloc.

I2. `test_eager_gc_match_binding_pattern_heap_pointer_post_walk_uaf`
    — exercises the bare `match @Json.0 { @JSON -> ... }`
    `ast.BindingPattern` branch added in round 1.  All three
    existing regression tests use `ConstructorPattern` (`Ok(@JSON) ->`)
    which goes through `_extract_constructor_fields`, leaving the
    BindingPattern path with no regression coverage.

I3 (partial). `TestBrowserMapHostStoreGCReachability695` added
    with three regression tests mirroring the CLI ones at
    `--target browser` with `VERA_EAGER_GC=1`.  All three currently
    `@pytest.mark.skip` because they surfaced a pre-existing
    browser-runtime bug: the JS-side bucket IS populated correctly
    but the heap block still gets reclaimed.  Reverting to commit
    `4d69cb8` (before the C1-C4 changes) reproduces the same
    failure — NOT introduced by this round.  Tracked as #708 so
    this PR can ship without being gated on a deeper browser
    investigation.

## Documentation

- `KNOWN_ISSUES.md` Bugs section: added #708 with full reproducer
  and what the debug instrumentation showed (bucket populated
  correctly per console.error, but Json still reclaimed).
- TESTING.md / ROADMAP.md doc counts: 3950 → 3955.

## Lower-priority items deferred

I4-I8 (silent-failure-hunter and comment-analyzer): the larger
comment-rot cleanup (round-number attribution, Phase B/C/D labels,
the `api.py:3050` "Phase D move tracking issue" reference,
`_INLINE_I32_TYPES` duplication) can land in a separate cleanup
commit or be addressed by #706.  None block this PR.

## Validation

- mypy clean (59 files)
- Map/Set + GC reachability: 5 passed (3 existing + 2 new)
- Browser tests: 99 passed + 3 skipped (with #708 rationale)
- JSON+HTML collection: 83 passed
- match/pattern + let-destruct: 11 passed
- Doc counts: consistent (3955 tests, 32 files, 88 conformance, 35 examples)
- Version: 0.0.159 consistent across 6 files

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Root-caused #708 (the pre-existing browser-runtime bug surfaced by
the round-3 EAGER_GC tests) to a missing port of the v0.0.158 #692
`_ShadowGuard` fix from CLI to browser.  The CLI `write_json` /
`write_html` host walkers use `_ShadowGuard` to root intermediate
allocations across multi-alloc walks.  The browser `writeJson` /
`writeHtml` JS-side equivalents never got the same fix.

## Diagnostic

Empirical instrumentation showed the failing `Set<Json>` test had
`Json` at address X with `tag=0, +4=X, +8=10` — a `Result.Ok` shape
allocated on top of the original `JArray`'s freed block.  Tracing
backward: `writeJson([1,...,10])` allocates a JArray's array_backing
of 10 JNumber pointers, then recursively allocates each JNumber.
Under `VERA_EAGER_GC=1` every `alloc()` fires `$gc_collect`.  The
`arrPtr` for the backing is held only in a JS local — invisible to
the conservative scan.  By the time the recursive JNumber writes
into `arrPtr`, the backing block has been reclaimed.  Then the
outer JArray block's `tag` and `+4` get overwritten by subsequent
allocations.  Then `json_parse`'s `allocResultOkI32(jsonPtr)`
allocates a 8-byte block — which gets the freed JArray's block as
its address, with `tag=0` (Result.Ok) and `+4=jsonPtr=self`.

## Fix

1. **`gcGuard(fn)` helper** in `vera/browser/runtime.mjs` — saves
   `$gc_sp` at entry, restores on exit.  JS-side parallel of
   `_ShadowGuard.__enter__/__exit__`.

2. **`writeJson` / `writeHtml`** wrapped in `gcGuard` and updated
   to `gcShadowPush` every intermediate: `arrPtr` (JArray's
   backing), each recursive child result, string ptrs, `wrapperPtr`
   (JObject's map wrapper).  Mirrors the CLI `_ShadowGuard.push`
   discipline from #692.

3. **`json_parse` / `html_parse`** wrap their `allocResultOkI32`
   call in `gcGuard` and shadow-push `jsonPtr` / `nodePtr` so the
   result is rooted across the Result wrapper alloc.

## Tests

The three previously-skipped browser EAGER_GC regression tests
(`TestBrowserMapHostStoreGCReachability695`) all now pass.  The
`@pytest.mark.skip` decorators removed.

## Comment-rot cleanup (pr-review-toolkit comment-analyzer I6-I8)

- Stripped "round 1" / "round 2" / "round 3" / "round 4" from
  inline comments across api.py, runtime.mjs, data.py — these
  round-number attributions lose meaning post-squash-merge.
  Replaced with "PR #707 review" where the attribution adds value.
- Replaced "Phase A" / "Phase B" / "Phase B.3" / "Phase D move
  tracking issue" labels in api.py with concrete prose referring
  to #706 where applicable.  These were labels for an
  implementation plan that wasn't recorded anywhere external.
- Phase 2a / Phase 2c references (the GC architecture's own
  internal mark / wrap-table-compaction phases) preserved —
  those are real, documented phases of `$gc_collect`.

## `_INLINE_I32_TYPES` dedup (pr-review-toolkit code-reviewer S1)

Hoisted `_INLINE_I32_TYPES = frozenset({"Bool", "Byte", "Unit"})`
from `vera/wasm/data.py` and `vera/wasm/context.py` (where it was
duplicated with cross-referencing comments) to `vera/wasm/helpers.py`.
Both consumers now import from the single authoritative location.

## Doc updates

- KNOWN_ISSUES.md: removed #708 from Bugs (now closed); section
  reverts to "No known bugs."
- CHANGELOG.md: added #708 bullet describing the browser-side fix.
- HISTORY.md: extended the v0.0.159 row to cover #708.
- TESTING.md: test_browser.py line count corrected (skip
  decorators removed: 2014 → 1982).

## Validation

- mypy clean (59 files)
- Map/Set + GC reachability (CLI): 5 passed
- Browser EAGER_GC regression suite: 3 passed
- Full browser suite: 102 passed
- Doc counts: consistent (3955 tests, 32 files, 88 conformance,
  35 examples)
- Version: 0.0.159 consistent across 6 files

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ce test

Post-merge documentation sweep across the project after closing #695,
#705, and #708 in PR #707:

- HISTORY.md: trim v0.0.149-v0.0.159 entries to single-sentence canonical
  form (Stage 1 pattern), remove inconsistent bold introduced at v0.0.149.
- tests/conformance/ch09_host_store_gc_reachability.vera: new conformance
  test exercising Map<String, Json> / Set<Json> user-level construction
  patterns (4 functions). Closes a coverage gap identified by the
  pr-test-analyzer agent on #707: the existing CLI/browser pytest tests
  cover the underlying mechanism but a conformance program nails the
  user-level contract.
- tests/conformance/manifest.json: register the new conformance test at
  the `run` level with `map`, `set`, `json`, `gc_reachability` tags.
- vera/README.md: document the JS-side GC reachability discipline
  (gcGuard / gcShadowPush) added for #708, paralleling the v0.0.158
  CLI-side _ShadowGuard discipline.
- Doc counts bumped from 88 → 89 conformance and 3,955 → 3,960 tests
  across SKILL.md, CLAUDE.md, AGENTS.md, README.md, FAQ.md, TESTING.md,
  ROADMAP.md, docs/index.html, docs/SKILL.md, docs/index.md, docs/llms*.

Validation: check_doc_counts.py, check_conformance.py, check_examples.py,
check_site_assets.py all pass.  mypy clean.  pytest tests/test_conformance.py
430 passed.

Skip-changelog: documentation sweep + test-only addition; no runtime behaviour change beyond what v0.0.159 already shipped.

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

7 inline findings from CodeRabbit. 6 fixed, 1 deferred with documented rationale.

ROADMAP.md (CR1): stale "88 conformance programs" in the testing-gaps
table now reads 89, matching the v0.0.159 count (added in 89afcb8 via the
new ch09_host_store_gc_reachability program).

TESTING.md (CR2 + CR3): two count drift fixes.

- CR2: the "Via pytest (parametrized - 440 tests)" comment in the
  conformance-suite-running section now reads 445, matching the table
  row earlier in the file.
- CR3: the Tests row arithmetic (3,920 + 16 + 14 = 3,950 vs claimed
  3,960) reconciles to the actual pytest numbers: 3,929 passed + 16 stress
  + 15 skipped = 3,960.  The 15-skipped table was also missing the
  test_run[ch07_io_read_char] row (added in v0.0.157 with the IO.read_char
  effect, but not propagated to TESTING.md); added it inline with the
  other verify-level run skips.

tests/test_browser.py (CR4): the _run_eager_gc_node helper now asserts
result[error] is falsy before returning stdout - previously a Node
harness error during VERA_EAGER_GC=1 runs would be silently dropped,
hiding a fresh trap behind whatever partial stdout the IO.print buffer
had flushed.

vera/browser/runtime.mjs (CR5): silent return on undefined mapStore /
setStore handle in attach_bucket_to_wrapper now throws.  The only paths
that reach the host call with an unknown handle are real bugs (handle
constructed outside mapAlloc, or wrapper reached the host call after
host_decref_handle already evicted it); silent return left wrapper+8
unwritten and produced a confusing downstream trap.  Symmetric with the
PR #707 round-2 silent-failure-hunter fixes on gcShadowPush / wrapHandle.

vera/browser/runtime.mjs (CR6): the writeJson JArray and writeHtml
children loops now pair gcShadowPush(ep/cp) with gcShadowPop() after
writeI32 stores the pointer.  Once the pointer lives in arrPtr block
and arrPtr is rooted, the conservative scan reaches it via arrPtr -
the per-iteration push is no longer load-bearing.  Without the matching
pop the shadow stack grew O(count) and risked overflowing gc_stack_limit
on large arrays.  The JObject branch was inspected and intentionally
left unchanged with a comment: m.set(k, ep) writes to a JS Map (not WASM
memory), so ep stays on the shadow stack until allocMapWrapper writes
it into the WAT-resident bucket.

vera/codegen/api.py (CR7) DEFERRED with rationale: _alloc_string empty
returns (0, 0), so an empty-string key would collide with the
key_word_0 == 0 empty-slot sentinel in _probe_string_key.  Verified
that _probe_string_key has zero callers - the bucket array is a
write-only GC mirror, lookups go through _map_store / _set_store
Python dicts.  Documented the latent caveat in the bucket layout
docstring and posted a comment on #706 (which tracks the
mirror -> bucket-as-truth migration that will activate the probe
path for real).  Fixing prematurely would lock in an encoding choice
that depends on how probing is restructured under #706.

Validation:
- mypy vera/ clean (59 files)
- pytest tests/ -m "not stress" - 3,929 passed, 15 skipped (matches CR3 numbers)
- pytest tests/test_browser.py -v - 102 passed (full browser parity)
- pytest tests/test_browser.py -k eager_gc -v - 3 passed (regressions)
- check_doc_counts.py, check_site_assets.py, check_conformance.py,
  check_examples.py - all green

Skip-changelog: minor doc + comment cleanup + 3 minor runtime hardening fixes (silent-return -> throw, push/pop bound stack, assert harness error). No user-facing behaviour change beyond what v0.0.159 already shipped.

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