…-as-ADT (closes #573 phase 1)

Pre-fix every map_new / map_insert / map_remove allocated a new
entry in `_map_store` (Python-side dict in vera/codegen/api.py)
without releasing transient predecessors.  A 10 000-iteration
array_fold over map_insert left 10 001 entries at execute() exit;
bounded by Python GC at process exit so single-shot programs were
unaffected, but long-running execution contexts leaked monotonically.

Post-fix the heap-wrap-as-ADT design from the issue body:

* Every Map<K, V> value is a pointer to an 8-byte wrapper ADT on
  the GC heap (tag at offset 0, raw host handle at offset 4).

* New 64 KiB wrap-table region in linear memory tracks every
  wrapper allocation as (ptr, kind, handle) entries.
  $register_wrapper appends; sweep walks and compacts.

* Phase 2c of $gc_collect — a new pass between mark and sweep —
  walks the wrap table.  Marked entries are kept (compacted in
  place).  Unmarked entries fire host_decref_handle(kind, handle)
  which evicts the corresponding entry from _map_store.

* Every Map call-site in vera/wasm/calls_containers.py wraps on
  construction (new/insert/remove) and unwraps on consumption
  (get/contains/size/keys/values) via i32.load offset=4.

* JSON's JObject and HTML's HtmlElement attrs use the same
  wrapper path via _alloc_map_wrapper in api.py — the prelude's
  json_has_field dispatches to map_contains on JObject's Map
  field, so the field MUST be a wrapper pointer for unwrap to
  produce the correct raw handle.

* `Map` removed from _HOST_HANDLE_TYPES — wrapper pointers ARE
  Vera-heap pointers and need shadow-stack rooting across
  allocating calls.  Set / Decimal stay in the set until their
  own follow-ups (#575, #576).

* Browser parity in vera/browser/runtime.mjs: host_decref_handle,
  allocMapWrapper, JObject + HtmlElement wrap on write, unwrap
  on read.

* ExecuteResult.host_store_sizes — new field exposing post-
  execution store population so tests can verify reclamation
  without invasive linker introspection.

Three regression tests in TestHostHandleReclamation573:

* 10 000-iteration map_insert chain via array_fold:
  _map_store has 1 entry at exit (was 10 001).
* 5 000 transient JObject parses via array_fold:
  _map_store < 1 500 (was monotonic in iterations).
* Functional integrity: map_get returns correct values across
  heavy GC pressure.

Plus the post-#573 expectation flip in
TestOpaqueHandleParamRooting347::test_map_param_shadow_pushed_after_573:
Map params now MUST appear in shadow_push (was: must not).
Set / Decimal pinning tests unchanged.

Phase 2 (Set, #575) and phase 3 (Decimal, #576) are mechanical
mirrors filed as separate follow-ups.

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

After Map's heap-wrap-as-ADT migration de-risked the design, the
remaining Set and Decimal migrations are mechanical mirrors —
same wrap-table, same destructor host import, same Phase 2c
sweep, only the call-site translators and the ``kind``
discriminator change.  Doing all three in one PR keeps each
commit independently bisectable, gives reviewers one design
conversation instead of three, and avoids two more release
cycles for clearly-mechanical work.

Set migration (closes #575):
- vera/wasm/calls_containers.py — wrap on set_new / set_add /
  set_remove; unwrap on set_contains / set_size / set_to_array.
- vera/codegen/api.py — host_decref_handle now dispatches
  kind=2 to _set_store.pop.
- vera/browser/runtime.mjs — same JS dispatch.

Decimal migration (closes #576):
- vera/wasm/calls_containers.py — wrap on Decimal-returning
  ops (decimal_from_int / _from_float / _neg / _add / _sub /
  _mul / _round); unwrap on Decimal-consuming ops
  (_to_string / _to_float / _eq / _compare).
  decimal_from_string and decimal_div construct Option<Decimal>
  host-side; their inner Decimal handle is wrapped via
  _wrap_handle (new helper in api.py) before Some.
- vera/codegen/api.py — _wrap_handle(caller, kind, raw_handle)
  generic wrapper helper, factored out of _alloc_map_wrapper.
  host_decref_handle dispatches kind=3 to _decimal_store.pop.
- vera/browser/runtime.mjs — wrapHandle JS counterpart, used
  in decimal_from_string and decimal_div.

Correctness fix found while writing stress tests:
- vera/wasm/calls_containers.py::_emit_wrap_handle — now
  shadow-pushes the wrapper pointer right after construction,
  matching the existing ADT-constructor pattern in data.py.
  Without this, nested expressions like
  decimal_add(decimal_from_int(a), decimal_from_int(b)) were
  unsafe — the inner wrapper sits on the operand stack while
  the second decimal_from_int invokes $alloc, and a GC fire
  there would sweep the unmarked wrapper.  Affects all three
  types; the function epilogue's $gc_sp restore clears these
  per-call pushes so the shadow stack doesn't grow unbounded
  across iterations of an enclosing array_fold.

GC-rooting hygiene:
- vera/wasm/helpers.py — _HOST_HANDLE_TYPES is now empty (was
  {Map, Set, Decimal}).  All three are real Vera-heap pointers
  post-#573 and MUST be shadow-stack-rooted.

Test updates:
- tests/test_codegen.py — TestOpaqueHandleParamRooting347
  Set + Decimal tests flipped from "must NOT be shadow-pushed"
  to "MUST be shadow-pushed after #573".
  TestArrayFoldHandleRooting490 helper renamed to
  _assert_handle_extra_rooted_after_573 with strictly-greater
  assertion (Decimal accumulators / elements MUST add
  per-iteration root pushes).
  TestHostHandleReclamation573 grew from 3 to 7 stress tests:
  * test_set_chain_reclaims_transients (10K set_add chain,
    < 2000 entries at exit)
  * test_set_value_correct_after_gc_pressure (1K set_add +
    multiple lookups + size, all on live Set)
  * test_decimal_chain_reclaims_transients (5K decimal_add
    chain, < 1500 entries at exit)
  * test_decimal_value_correct_after_gc_pressure (1K
    decimal_add+mul + decimal_eq on live Decimal)

Release docs:
- CHANGELOG entry rewritten to cover all three types.
- ROADMAP priority table now down to one entry (#507);
  campaign-progress paragraph notes the campaign is closed.
- KNOWN_ISSUES drops the #575 / #576 placeholder bug rows.
- HISTORY row updated.

Validation: 3,713 pytest, 99 browser parity, mypy clean,
82 conformance, 33 examples, all sync scripts pass.

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

Five findings; verified each.  Skipped 1 + 2 (false claims about
test count and tag count); fixed 3, 4, 5.

Finding 1 (HISTORY.md test count) — SKIPPED.  Reviewer claimed
``pytest --collect-only`` shows 1,608 tests with 15 collection
errors.  Actual: 3,714 tests, 0 errors.  No change needed.

Finding 2 (134 tagged releases / "current git tag count is 0")
— SKIPPED.  ``git tag | wc -l`` shows 134 tags locally (v0.0.1
through v0.0.133, plus the v0.0.134 line is the version in the
current PR which gets tagged after merge per the established
tag-on-branch + CHANGELOG-during-PR pattern).  Reviewer's "0"
claim is wrong.

Finding 3 (test_codegen.py:15886 — Map reclamation bound) —
FIXED.  Tightened the assertion bound from <=100 to <=10 in
``test_map_chain_reclaims_transients``.  Empirically the 10K-
iter chain ends with size=1 (only the live final Map); the
single-digit bound enforces "only the live final Map" semantics
rather than the slacker "GC fires occasionally" reading.

Finding 4 (test_codegen.py:15535 — push regex doesn't verify
sp advance) — FIXED.  Extended the regex in all three positive
shadow-push assertions (Map, Set, Decimal) to require BOTH
halves of the gc_shadow_push idiom in order:
  global.get $gc_sp; local.get N; i32.store      (push)
  global.get $gc_sp; i32.const 4; i32.add;
  global.set $gc_sp                              (advance)
Without the advance, every subsequent push would overwrite the
same slot.  The original ``_assert_param0_not_shadow_pushed``
(negative assertion) is unchanged — if the push isn't there,
no advance either.

Finding 5 (api.py — host_decref_handle gating) — FIXED.  Real
bug: JSON-only and HTML-only programs that didn't directly use
any user-level map_*/set_*/decimal_* op weren't flipping
``_needs_wrap_table`` on the WAT side, so:
  * ``register_wrapper`` wasn't exported
  * ``host_decref_handle`` import wasn't declared
  * Phase 2c of ``$gc_collect`` wasn't emitted

But ``write_json``'s JObject branch and ``write_html``'s
HtmlElement attrs branch internally call ``_alloc_map_wrapper``,
which calls ``$register_wrapper`` via the export.  Pre-fix the
host-side call would silently no-op (the export missing means
``caller["register_wrapper"]`` returns None and we early-return),
leaving the host-store entries to leak indefinitely.

Two-line fix:
* ``vera/codegen/assembly.py`` — flip ``_needs_wrap_table`` if
  ``_json_ops_used or _html_ops_used`` is non-empty.
* ``vera/codegen/api.py`` — extend the ``_decref_used``
  predicate to include ``json_ops_used or html_ops_used`` so
  the destructor host import is defined whenever the WAT side
  references it.

Plus a new ``test_json_only_module_includes_wrap_table``
regression test that asserts a JSON-only program emits the
wrap-table imports, exports, and sweep machinery.

Validation: 3,714 pytest, 99 browser, mypy clean, 82
conformance, 33 examples, all sync scripts pass.

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

Five additional findings beyond round 1's batch.  Verified each;
fixed the critical worklist bug and three smaller items, deferred
one (latent conservative-scan retention) to a follow-up issue.

Finding 8 (assembly.py:346 — CRITICAL: worklist overlapping
wrap-table) — FIXED.  The mark phase used $gc_heap_start as the
worklist upper bound, on the (correct-at-the-time) assumption
that the worklist sat directly before the heap.  After #573
inserted the 64 KiB wrap-table region between worklist and
heap, that assumption broke: the worklist would think it had
``worklist_size + wraptable_size`` of capacity and could grow
into the wrap-table, corrupting (obj_ptr, kind, handle) entries.
Phase 2c would then operate on garbage and evict arbitrary
host-store entries.

Two-line fix:
* New $gc_worklist_end global, always = $gc_stack_limit +
  worklist_size regardless of wrap-table presence.
* $gc_collect's "wl_end" load reads from $gc_worklist_end
  rather than $gc_heap_start.

Finding 6 (CHANGELOG.md — leak-scope wording) — FIXED.  Pre-fix
text read "leaked monotonically across repeated execute()
calls" but each store is execute()-local — the leak is *within*
a single execute(), not across them.  Reworded to clarify that
the failure mode is one long-running execute() (server request
loop, interactive session, Game-of-Life-style multi-generation
program), not a multi-execute() pattern.

Finding 7 (TESTING.md arithmetic) — FIXED.  Row said
"3,714 across 29 files (3,695 passed, 14 skipped)" — the
pass/skip don't add up to 3,714.  Updated to "3,700 passed,
14 skipped" (matches the live pytest output).

Finding 10 (helpers.py docstring) — FIXED.  ``_HOST_HANDLE_TYPES``
is now empty post-#573 phases 1-3, but ``_is_host_handle_type``'s
docstring still described Map / Set / Decimal as "i32 indices
into Python-side host stores".  Rewrote to explain the
historical (pre-#573) purpose AND the post-#573 always-False
return, and why the function is kept rather than deleted (a
hook for future host-handle types added without wrapper
migration).

Finding 9 (assembly.py:832 — wrapper payloads conservatively
scanned) — DEFERRED to follow-up #578.  Phase 2b's word-by-word
scan treats every i32 in a wrapper's payload as a candidate
heap pointer.  For typical programs the host-handle field
(small integer) is well below ``gc_heap_start`` (~147 KiB) so
the heap-range check rejects it, producing no false marks.
For very-long-running programs that allocate hundreds of
thousands of host handles, a handle could exceed the heap-base
threshold and (with the right alignment) be falsely classified
as a heap pointer, spuriously retaining an unrelated heap
object.  Retention bug, not correctness — the falsely-marked
object is still valid; it just sticks around longer than it
should.  Filed as #578 with four candidate fix designs.

Skipped (false claims, addressed in round 1 commit):
* Finding 1 — pytest collects 3,714 tests, not 1,608.
* Finding 2 — git tag count is 134, not 0.

Validation: 3,714 pytest, 99 browser, mypy clean, 82 conformance,
33 examples, all sync scripts pass.

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

… 1 duplicate

Six findings; verified each.  Fixed 4, skipped the assembly.py:340
finding as duplicate (already addressed in d33a778's
$gc_worklist_end refactor).

Finding A (test_codegen.py:15931 — stale class docstring) —
FIXED.  ``TestHostHandleReclamation573``'s docstring still said
"Map only" with Set/Decimal "in their own follow-ups", but the
class now contains all three.  Rewrote to enumerate the three
failure modes per type (chain reclaims transients, value
correct after pressure, JSON-only / HTML-only wrap-table
inclusion).

Finding B (test_codegen.py:16220 — missing HTML-only test) —
FIXED.  Added ``test_html_only_module_includes_wrap_table`` as
a sibling of ``test_json_only_module_includes_wrap_table``.
Asserts ``host_decref_handle`` import, ``$register_wrapper``
helper, and the export are all present in WAT for an
html_parse-using program.  Note: html_parse transitively pulls
in the prelude's ``html_attr`` (which calls map_get) so
``_map_ops_used`` ends up set anyway in practice — but the
``_needs_wrap_table`` flip on ``_html_ops_used`` is the load-
bearing fix if that prelude transitivity ever changes (e.g.
if a future codegen DCE eliminates unused prelude functions).

Finding C (api.py:1729 — host_decref_handle map_ops_used gating)
— FIXED.  Real bug: ``kind == 1 and result.map_ops_used`` skips
the pop for JSON-only / HTML-only programs (where
``map_ops_used`` is False but JObject / HtmlElement allocations
still create Map wrappers — ``_map_store`` exists because
its creation is gated on ``map_ops_used or json_ops_used or
html_ops_used``).  Drop the ``map_ops_used`` part of the gate;
the runtime invariant "kind == 1 ⟹ _map_store exists" holds
because the wrap-table only emits kind=1 when the Map store
is created.  ``kind == 2`` and ``kind == 3`` keep their gates
because their stores have a single creation condition.

Finding D (api.py:3114 outside-of-diff — ExecuteResult missing
host_store_sizes in IO.exit early returns) — FIXED.  The two
early-return ``ExecuteResult(...)`` sites in the IO.exit error
paths omitted ``host_store_sizes``, leaving the field empty
even when host stores existed.  Threaded
``{k: len(v) for k, v in _host_store_refs.items()}`` through
both sites so the field is always populated, mirroring the
normal-completion path.

Skipped:
* assembly.py:340 (duplicate) — reviewer suggests using
  ``gc_wraptable_base`` as the worklist end.  This is
  mathematically equivalent to the ``$gc_worklist_end`` global
  introduced in d33a778's round-2 fix
  (``gc_worklist_end = gc_stack_limit + worklist_size`` and
  ``gc_wraptable_base = data_end + gc_stack_size +
  worklist_size``; they refer to the same address when wrap-
  table is enabled and the new constant is independent of
  whether wrap-table is enabled).  Already fixed.

Validation: 3,715 pytest, 99 browser, mypy clean, 82
conformance, 33 examples, all sync scripts pass.

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

CodeRabbit round 4 finding: $register_wrapper traps on overflow
instead of trying $gc_collect compaction first.  Real
limitation but bounded in practice (every wrapper is also a
heap allocation so wrap-table-full and heap-full happen at
similar cadences and GC fires first; 10K-iter Map stress test
validates).  Implementation requires re-entrancy-safe GC from
inside register_wrapper which warrants its own design + new
stress tests.

Filed as #579 with full design sketch.  Added to KNOWN_ISSUES
per the project rule that PR-generated new issues must land in
ROADMAP or KNOWN_ISSUES in the same PR.

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

Round-4 finding from CodeRabbit, originally deferred in 6e2e9ce
but the user pushed back asking whether to defer or fix.  The
implementation is ~20 lines of WAT and the re-entrancy concerns
are tractable, so fix it in this PR rather than carrying #579
as a known issue.

Pre-fix $register_wrapper traps with `unreachable` the moment
$gc_wrap_ptr >= $gc_wrap_end — even if Phase 2c compaction
would have freed thousands of dead entries.

Post-fix slow path on overflow:
1. Push the in-flight wrapper ptr onto the shadow stack as a
   temporary root (with overflow check matching gc_shadow_push).
   Without this, Phase 2b would mark the in-flight wrapper
   unreachable and Phase 3 would link it to the free list — we'd
   then append to a freed object after the collect.
2. Call $gc_collect (Phase 2c walks the wrap-table, drops dead
   entries, resets $gc_wrap_ptr to the compacted end).
3. Pop the temporary root.
4. Re-check the overflow condition; trap only if still full
   (which now indicates 4096+ genuinely-live wrappers and a
   real out-of-budget condition).

Re-entrancy: $gc_collect's Phase 2c calls
$vera.host_decref_handle (host import) for unmarked wrappers
but doesn't allocate or wrap, so no recursion through
$register_wrapper.

Test coverage: structural pin
`test_register_wrapper_has_compaction_slow_path` asserts the
slow path is wired up — verifies the $gc_collect call,
shadow-push of $ptr before the call, and the post-compaction
re-check are all present in the generated WAT.  End-to-end
exercise of the slow path is hard (every wrapper is also a
heap allocation, so wrap-table-full and heap-full happen at
similar cadences and $alloc triggers GC first under normal
conditions); the structural test catches refactors that revert
to the unconditional trap.

Closes #579.  Removed from KNOWN_ISSUES.  CHANGELOG entry
extended to cover the slow-path fix in addition to the original
phase 1-3 migration.

Validation: 3,716 pytest, mypy clean, doc counts consistent.

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

CodeRabbit follow-up on #579's slow-path implementation:
"the pop of the temp root happens unconditionally — i.e., even
on the trap branch — so the shadow-stack is never left in a
dirty state on abnormal exit."

The current implementation already has this property: the pop
runs immediately after $gc_collect returns and BEFORE the
re-check guard, so on trap the pop has already executed.
`unreachable` aborts the WASM module so the imbalance has no
observable effect today, but treating WAT shadow-stack
discipline as a hard invariant catches regressions before any
future change converts the trap to a recoverable error path.

Extended `test_register_wrapper_has_compaction_slow_path` to
match the pop sequence appearing strictly between
`call $gc_collect` and the re-check `i32.ge_u` — a structural
pin that fails if a refactor reorders the slow path's tail.

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