Pre-fix, Map / Set / Decimal wrapper ADTs stored the raw host-
store handle (a small i32) at body offset 4.  The conservative
GC scan in Phase 2b walks every reachable object's payload
word-by-word, checking whether each i32 looks like a heap
pointer (in heap range, 8-byte aligned).  For typical programs
the handle counter stayed below gc_heap_start (~147 KiB) so the
heap-range check rejected it.  But a long-running program
allocating >100K host-store entries in a single execute() could
see a handle exceed that threshold and (with the right
alignment) be falsely classified as a heap pointer — silently
retaining an unrelated heap object.  Retention bug, not
correctness, but unbounded retention for long sessions.

This was the last open bug in the KNOWN_ISSUES bug-tracker
section (bug list now empty for the first time since ~v0.0.80).

## Fix design

Option 1 from the issue body, "self-describing wrappers".
Store the handle ORed with 0x80000000 at body offset 4 so the
in-heap field is always >= 2 GB, structurally outside any
plausible heap-range check.  Unwrap recovers the raw handle by
ANDing with 0x7FFFFFFF.  Heap-ceiling guard in $alloc enforces
heap_ptr < 0x80000000, so the disjointness invariant (tagged
handles never collide with heap pointers) holds by construction.

Why this design over the other three candidates in the issue:
- Option 2 (skip-scan flag) touches the header layout and every
  header reader (~30 sites).  Option 1 touches two emission
  helpers.
- Option 3 (wrap-table cross-ref in scan) is O(n*m) and slow
  enough to fail "correctness over performance".
- Option 4 (max-handle lower-bound) is broken — once
  max_handle > gc_heap_start, handles and heap pointers share
  the same numeric range and no lower bound can separate them.

Maps cleanly to DESIGN.md principle #1 (checkability) via a
single structural invariant: heap_ptr < 0x80000000 ⇒ tagged
values (>= 2 GB) are outside the scan's heap-range check.

## Code changes

- `vera/wasm/calls_containers.py::_emit_wrap_handle` — OR with
  0x80000000 before `i32.store offset=4`
- `vera/wasm/calls_containers.py::_emit_unwrap_handle` — AND
  loaded value with 0x7FFFFFFF before returning
- `vera/codegen/assembly.py` $alloc — heap-ceiling guard:
  trap if heap_ptr + total >= 0x80000000
- `vera/codegen/api.py::_wrap_handle` — host-side wrapper
  allocator also writes the tagged value (used by Option<Decimal>
  Some payloads etc.)
- `vera/wasm/json_serde.py::read_json` and
  `vera/wasm/html_serde.py::read_html` — host-side readers that
  walk wrapper.handle directly (bypassing _emit_unwrap_handle)
  AND with 0x7FFFFFFF to recover the raw handle for map_store
  lookup

## Tests

- `tests/test_codegen.py::TestWrapperHandleTagging578` — 5 tests
  pinning the contract:
  1. Wrap site emits `i32.const 0x80000000; i32.or`
  2. Unwrap site emits `i32.load offset=4; i32.const 0x7FFFFFFF; i32.and`
  3. $alloc body contains the heap-ceiling guard
  4. End-to-end wrap/unwrap round trip preserves the raw handle
  5. html_to_string produces correct length (pins host-side mask)

## Documentation

- `KNOWN_ISSUES.md` — removed #578.  Bug list empty.
- `CHANGELOG.md` v0.0.155 entry
- `HISTORY.md` v0.0.155 row + footer "155 tagged releases"
- README test count 3893 → 3898

Validation: pytest 3868/3868, mypy clean, ruff S clean,
conformance 86/86, examples 34/34, doc-counts consistent,
site assets up to date.

Closes #578.

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

Per feedback on #673: retain the Bugs section heading but use a
plain "No known bugs." rather than the longer self-referential
note about the section having been empty before.  The HISTORY.md
cross-reference doesn't add operational value at this point —
anyone reading KNOWN_ISSUES who needs that context can follow
the top-of-file pointer to the issue tracker.

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

**Finding 1: substring-only WAT checks could false-pass** (valid).
The previous tests asserted constants like `0x80000000`, `i32.or`,
`0x7FFFFFFF`, and `i32.ge_u` in isolation.  But:
- `i32.const 0x80000000` appears in BOTH the wrap-site tag AND
  the heap-ceiling guard.  Stripping the wrap OR would still
  leave the substring (from the guard) and the test would pass.
- `i32.or` also appears in header-mark manipulation, unrelated
  to the wrap path.

Switched all three tests to boundary-safe adjacent-sequence
regex:
- `test_wrap_emits_tag_or`: `re.search(r"i32\.const 0x80000000\s+i32\.or", ...)`
- `test_unwrap_emits_mask_and`: `re.search(r"i32\.load\s+offset=4\s+i32\.const 0x7FFFFFFF\s+i32\.and", ...)`
- `test_alloc_emits_heap_ceiling_guard`: extract `$alloc` via
  `re.search(r"\(func \$alloc\b", ...)` (boundary-safe vs the
  previous `find("(func $alloc")` which could false-match
  `$alloc_xxx`), then assert the EXACT ordered 8-instruction
  guard sequence (`global.get $heap_ptr; local.get $total;
  i32.add; i32.const 0x80000000; i32.ge_u; if; unreachable;
  end`) via a single multi-line regex with `re.DOTALL`.

**Finding 2: _wrap_handle doesn't check raw_handle < 0x80000000**
(valid).  If a handle ever has bit 31 set, `raw_handle |
0x80000000` is a no-op and the unwrap mask `& 0x7FFFFFFF`
returns the WRONG handle — silent host-store-lookup corruption
that's exactly the latent failure class #578 itself sought to
eliminate.  Practically infeasible (counters bounded well below
2^31; a 2B-handle session is wall-clock-infeasible) but the
invariant deserves an explicit assertion per DESIGN.md principle
#1 (checkability).  Added `if raw_handle & 0x80000000: raise
RuntimeError(...)` immediately before the `_write_i32` /
`_call_register_wrapper` block in
`vera/codegen/api.py::_wrap_handle`.  Error includes
raw_handle, kind, body_ptr per CR's exact recommendation.

**Not addressed: CR's 3rd finding**
("Missing the long-run high-handle-counter regression that
#578 is meant to prevent" — labelled Major, Heavy lift).

Declined with reasoning:

1. **#578 was a RETENTION bug, not a correctness bug.**  Pre-fix
   the conservative scan could mark unrelated heap objects when
   a handle value matched the heap-range check.  In an
   IMMUTABLE language those objects can't corrupt state — only
   memory grows.  No output assertion can distinguish pre-fix
   from post-fix at modest scale.

2. **A true regression test requires heap-growth inspection.**
   Vera's test infra doesn't expose `$heap_ptr` post-run; adding
   that machinery is a separate infrastructure change.  An
   alternative — measure WASM `memory.size` deltas — needs the
   same instrumentation.

3. **The structural invariants are mathematically sufficient.**
   The 3 tightened tests + `$alloc` heap-ceiling guard prove
   by construction that no tagged value can EVER match the
   heap-range check: heap_ptr is hard-capped at 0x80000000, and
   every tagged value is >= 0x80000000.  Sets don't overlap.
   This is a stronger guarantee than a stochastic
   non-occurrence stress test could provide.

4. **A weaker "scale" test would be misleading.**  200K wrap
   allocations under eager GC complete fine pre-fix too (the
   retention is bounded and self-clearing once the falsely-
   retained object becomes legitimately unreachable in a later
   cycle).  Such a test would pass on broken code, providing
   false confidence.

If we add `$heap_ptr` inspection to the test harness in future
(a worthwhile general improvement), I'd be happy to file a
follow-up that includes a deterministic retention regression.
Tracked as a possible follow-up issue.

Validation: pytest 3868/3868, mypy clean, ruff S clean,
doc-counts consistent.

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

**Finding 1: missing JSON round-trip test for the host-side mask**
(valid).  The previous suite has `test_html_round_trip_uses_host_
side_mask` which pins the mask in `vera/wasm/html_serde.py` but no
analogous test for the symmetric mask in `vera/wasm/json_serde.py`
(both apply `& 0x7FFFFFFF` when reading `wrapper_ptr + 4`
directly).

Added `test_json_round_trip_uses_host_side_mask` modelled on the
HTML test: builds a `JObject(map_insert(map_new(), "name",
JString("hi")))`, serialises via `json_stringify`, asserts the
length is 14 (`{"name": "hi"}` — Python's `json.dumps` default
separators include a space after the colon).  Without the
host-side mask the map_store lookup misses, `read_json` falls
through to the warning + empty-dict path, and `json_stringify`
emits `{}` = 2 chars.  A 14-vs-2 assertion clearly discriminates.

**Finding 2: _wrap_handle bit-31 guard misses values outside the
31-bit non-negative range** (valid).  The previous check `if
raw_handle & 0x80000000:` only caught values WITH bit 31 set.  It
let through:
- Values >= 0x100000000 — wrap on `_write_i32`'s 32-bit truncation
  and silently corrupt the round-trip
- Type-confusion sentinels (e.g. None, non-int objects) — would
  raise TypeError deeper in the stack rather than at the
  diagnosable check point

Tightened to an explicit range check: `if not (isinstance(
raw_handle, int) and 0 <= raw_handle < 0x80000000)`.  Error
message updated to describe the range and enumerate the failure
modes it now catches.  Negative values, integer overflow, and
type confusion all fail fast at the same point.

Validation: pytest 3869/3869, mypy clean, ruff S clean, doc-counts
consistent (test_codegen.py: 1110 → 1111 tests; total 3898 → 3899).

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

Comprehensive PR review (code-reviewer + pr-test-analyzer +
comment-analyzer + silent-failure-hunter, all in parallel)
surfaced 9 actionable items.  Addressed 7, deferred 2 with
reasons.

**Critical**

1. **CHANGELOG test count** (comment-analyzer + code-reviewer).
   The Tests section said "5 new tests" but the class actually
   has 6 (the JSON sibling added in round 3 wasn't back-
   propagated).  Updated to 6 with the new bullet.

2. **`host_html_parse` broad-except swallowed `_wrap_handle`
   invariant violations** (silent-failure-hunter).  The
   `except Exception as exc:` at `vera/codegen/api.py:2784`
   converted any RuntimeError (including the new #578 range-
   check raise) into a user-domain `Result.Err` string,
   masking real invariant violations as "malformed HTML"
   errors.  Narrowed to `(ValueError, TypeError, AttributeError)`
   matching the sibling `host_json_parse` pattern.

**Important**

3. **`_wrap_handle` range guard had zero unit tests** (pr-test-
   analyzer, rating 7).  Extracted the validator to a module-
   level `_validate_wrap_handle` helper so it can be unit-
   tested directly without standing up a wasmtime instance.
   `_wrap_handle` now calls the helper.  Added 5 tests
   covering all failure modes:
   - `test_validate_wrap_handle_accepts_valid_range` (0, 1,
     12345, 0x7FFFFFFE, 0x7FFFFFFF)
   - `test_validate_wrap_handle_rejects_negative` (-1, -12345)
   - `test_validate_wrap_handle_rejects_at_2gb_boundary`
     (0x80000000)
   - `test_validate_wrap_handle_rejects_above_32bit`
     (0x100000000, 0x100000001 — the round-1 bit-only check
     would have missed these)
   - `test_validate_wrap_handle_rejects_non_int` (None, "5",
     1.5, [1], {})

4. **GC mark phase missing defense-in-depth narrative** (silent-
   failure-hunter).  The conservative scan's heap-range check
   relies on the disjointness invariant (`heap_ptr < 2 GiB` so
   tagged handles `>= 2 GiB` can never match).  Added a
   substantial comment block at the scan site documenting the
   invariant and pointing at the two structural tests that pin
   it.  Comment-only (no runtime cost in the GC hot path); the
   structural tests are the mechanical defense.

**Comment accuracy** (comment-analyzer)

5. `test_json_round_trip_uses_host_side_mask` referenced
   `json_serde.py` line 213 by hardcoded number — drifts on
   any nearby edit.  Replaced with the "unknown JObject
   handle" warning reference.

6. `2 GB` → `2 GiB` throughout (assembly.py + tests/test_
   codegen.py).  Strictly `0x80000000 = 2 GiB` (binary), not
   2 GB (decimal = ~1.86 GiB).

7. `"Practical Vera programs use <100 MB"` was an
   unsubstantiated claim stated as fact.  Reworded to
   `"Programs we have measured stay well below the 2 GiB
   ceiling"`.

8. The class docstring's `gc_heap_start (~147 KiB)` figure
   actually depends on the string-pool size (`data_end + 144
   KiB`).  Softened to `~144 KiB above the data section, so
   roughly 144 KiB plus the string-pool size`.

**Deferred with reason**

9. `$alloc` heap-ceiling trap is bare `unreachable`, surfaces
   via the trap classifier as `"unreachable"` kind with the
   match-arm Fix message (silent-failure-hunter, Important).
   Polishing this requires either a host-import call from
   `$alloc` to populate `last_violation` (cost on the hot path)
   or a new classifier kind with a heuristic detector
   (brittle).  Practical programs never reach this trap
   (heap << 2 GiB), so deferred.  Marked with a TODO inside
   `assembly.py` as a Python comment (NOT a WAT comment — a
   WAT comment between `if` and `unreachable` would break the
   adjacent-sequence regex in `test_alloc_emits_heap_ceiling_
   guard`).

The other declined findings from the agents:
- silent-failure-hunter `read_json` warn → raise (pre-existing
  behavior, separate concern)
- silent-failure-hunter `_call_register_wrapper` early-return
  → assert (pre-existing pattern, out of scope)
- silent-failure-hunter wasmtime trap-text enrichment (would
  need last_violation channel work; separate PR)
- code-reviewer i32.add wraparound at heap-ceiling guard
  (confidence 60 — self-flagged; defended upstream by
  `memory.grow` and 31-bit-size invariant)

Validation: pytest 3,874/3,874 ✓ (added 5 new tests),
mypy clean, ruff S clean, all 18 pre-commit hooks green,
doc-counts consistent (1,111 → 1,116 tests in
test_codegen.py; total 3,899 → 3,904).

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

**Finding 1: test_wrap_emits_tag_or regex too narrow** (valid for
symmetry).  The previous regex `i32\.const 0x80000000\s+i32\.or`
matched the const-or pair which today is unique to the wrap site,
but the test signalled the WRONG semantic — it pinned an
accidental pair-uniqueness fact rather than the wrapper-store
intent.  Tightened to
`i32\.const 0x80000000\s+i32\.or\s+i32\.store offset=4` to pin
the FULL 3-instruction wrap sequence (const + or + store).

Symmetric with `test_unwrap_emits_mask_and` which already pins
the full 3-instruction unwrap sequence (load + const + and).
Both tests now check the SEMANTIC operation (tag-then-store /
load-then-mask) rather than the accidental presence of distinctive
pairs.

**Finding 2: HTML/JSON tests asserted only length** (valid — real
bug class).  A hypothetical bug producing wrong content with the
right length (e.g. `<p title="WRONG"></p>` is also 21 chars,
`{"name": "BB"}` is also 14 chars) would have slipped past the
length check.  Switched both tests to exact string equality:

- Vera programs now use `IO.print(html_to_string(...))` /
  `IO.print(json_stringify(...))` so the rendered output flows
  to stdout
- Helper switched from `_run` (int result) to `_run_io` (captured
  stdout string)
- Assertion changed from `== 21` / `== 14` to
  `== '<p title="hello"></p>'` / `== '{"name": "hi"}'`

The exact string assertion also documents the expected format in
the test itself rather than requiring a length calculation comment.

Validation: pytest 3,874/3,874, mypy clean, ruff S clean,
doc-counts consistent.

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