Release v0.0.120: trap categorisation + stdout preserved on trap

[aallan]

First pair from the bug-killing campaign. Two paired fixes share the same site (vera/codegen/api.py's except Exception branch) and one test fixture, so they ship together as v0.0.120:

• Closes IO.print output lost when program traps (stdout fully buffered) #522 — IO.print output preserved on trap
• Runtime traps need Vera-native diagnostics, not raw wasmtime stack traces #516 Stage 1 — WASM traps classified to a stable kind

What changes

WasmTrapError (new)

A RuntimeError subclass carrying:

• stdout / stderr — whatever the program wrote before the trap, previously discarded as the exception unwound out of execute()
• kind — stable identifier: divide_by_zero / out_of_bounds / stack_exhausted / unreachable / overflow / contract_violation / unknown

Liskov-substitutable: every existing except RuntimeError block still catches the trap and sees a sensible string. No call-site changes needed in older code.

_classify_trap (new)

Pure function. Maps (wasmtime exc, last_violation) to (kind, message). Contract-violation host-import channel always wins over the wasmtime trap reason — the host import has a more specific Vera-native message. Otherwise the wasmtime exception's str() is matched against the wasm trap: <reason> substring and routed to one of the documented kinds. Stringly-typed against wasmtime's error format, which keeps the classifier free of a wasmtime import — handy for tests and the eventual browser-runtime branch.

cmd_run handler

New except WasmTrapError block before except RuntimeError:

• Text mode: writes captured stdout / stderr to the corresponding actual streams before the error, with an explicit sys.stdout.flush() so 2>&1 redirects show the right merged-stream order. Then f"Error: {exc}" to stderr.
• JSON mode: stdout and stderr go into the envelope; the diagnostic gains a trap_kind field. Streams are NOT touched in JSON mode (would corrupt parsed output).

Folded in: PR #532 (mobile CSS fixes)

Cherry-picked the single commit from mobile-overflow-fixes since it's a CSS-only docs/index.html edit with no overlap with the trap work. Three iOS Safari overflow bugs at iPhone widths fixed: hero image (width:100% missing), VeraBench button (mobile .btn rule was leaking outside .cta-bar), and Runs section shell-command code blocks (white-space:pre with no wrap rule). Authorship preserved; #532 closed with a comment cross-referencing this PR.

Test plan

• 16 new tests in tests/test_runtime_traps.py — classifier per-kind, WasmTrapError shape, end-to-end cmd_run for both text and JSON modes
• Full suite: 3520 → 3536 (+16) passing, 14 skipped, zero existing tests broken
• Real-world reproducer (/tmp/buffer_test.vera from IO.print output lost when program traps (stdout fully buffered) #522) — all four IO.print lines now appear before the error message under 2>&1
• Contract violation path (safe_div(@Int, @Int -> @Int) with second arg 0) still produces "Precondition violation in safe_div..." in text mode and trap_kind: contract_violation in JSON mode
• All doc validators green (version sync, doc counts, limitations sync, site assets)

Doc updates

• Version 0.0.119 → 0.0.120 across pyproject.toml, vera/__init__.py, docs/index.html, README.md
• KNOWN_ISSUES.md: removed IO.print output lost when program traps (stdout fully buffered) #522 row (closed); rewrote Runtime traps need Vera-native diagnostics, not raw wasmtime stack traces #516 row to "Stage 1 done, Stages 2–3 remain"
• ROADMAP.md: row 3 now #516 (Stages 2–3) instead of paired-with-IO.print output lost when program traps (stdout fully buffered) #522; intro updated from "twelve open" to "eleven remain"
• HISTORY.md: v0.0.120 row added to Stage 9 table
• CHANGELOG.md: [Unreleased] content moved to [0.0.120] - 2026-04-26; new empty [Unreleased] block on top
• TESTING.md: total counts 3534→3550, file count 28→29, new row for test_runtime_traps.py

What this does NOT do

• Stages 2 (source mapping the trapping Vera function) and 3 (per-kind Fix: paragraphs) of Runtime traps need Vera-native diagnostics, not raw wasmtime stack traces #516 — both remain open. Stage 2 needs debug-info plumbing through codegen, which is its own piece of work.
• The other ten bugs in the campaign (Closures capturing heap-allocated values produce invalid WASM (nested-closure case is a narrow instance) #514, GC collect itself faults with out-of-bounds memory access under sustained allocation pressure #515, Tail-call optimization missing: deep recursion blows the WASM call stack #517, Nat subtraction silently underflows to negative i64 — refinement-type soundness hole #520, Pre-existing bugs in WASM call translators (surfaced by #474 review) #475, GC $alloc grows memory by only 1 page — large single allocations trap #487, GC worklist overflow for deeply nested object graphs #348, Opaque handle memory leak in host stores #346, GC shadow stack pollution from opaque handle parameters #347, Over-rooting of host-managed handles in array_fold (and future iterative combinators) #490) — independent, sequential.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • stdout and stderr captured during runtime traps are preserved and replayed in text mode (ordering retained under merged redirects) and included in JSON error envelopes.
  • Unexpected WASM traps are relabelled to avoid misclassifying contract violations; generic errors now indicate unhandled WASM traps.

• New Features

  • WASM traps categorised into stable, meaningful kinds; trap_kind appears in JSON diagnostics.

• Tests

  • New test suite covering trap classification and stdout/stderr preservation.

• Documentation

  • Changelog, history, roadmap and docs updated for v0.0.120.

---

Closes #522

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7ef092ed-222a-4ee0-ae89-1dd79cafaa10

📥 Commits

Reviewing files that changed from the base of the PR and between 522303c and ad3eb2e.

📒 Files selected for processing (3)

• ROADMAP.md
• TESTING.md
• tests/test_runtime_traps.py

---

📝 Walkthrough

Walkthrough

Adds Stage‑1 runtime trap diagnostics: introduces WasmTrapError and _classify_trap, preserves/replays captured stdout/stderr on trap, wires trap_kind into JSON/text CLI output, updates CLI handling, adds tests and documentation, and bumps package to v0.0.120.

Changes

Cohort / File(s)	Summary
Version metadata CHANGELOG.md, HISTORY.md, pyproject.toml, vera/__init__.py, README.md	Bump release to v0.0.120; add changelog/history entries documenting trap classification and stdout/stderr preservation; update release/test counters and compare links.
Documentation & planning KNOWN_ISSUES.md, ROADMAP.md, TESTING.md, docs/index.html	Reflect Stage‑1 progress: rewrite known‑issues entry for #516, close #522 in docs, add testing inventory for runtime trap tests, note iOS Safari overflow fixes, and adjust roadmap priorities.
Core trap handling vera/codegen/api.py	Add WasmTrapError(RuntimeError) with stdout, stderr, kind; implement _classify_trap(exc, last_violation); classify wasmtime traps in execute() and raise WasmTrapError carrying captured buffers and kind.
CLI error handling vera/cli.py	Enable capture_stderr=True; store/replay captured stderr; add except WasmTrapError branch to replay buffers and emit JSON/text envelopes including trap_kind; adjust generic trap labeling.
Tests tests/test_runtime_traps.py	New pytest module covering _classify_trap, WasmTrapError shape, stdout/stderr capture/replay, CLI cmd_run behaviour in text and JSON modes, and trap categorisation rules.

Sequence Diagram

sequenceDiagram
    participant WasmExec as WASM Executor (vera/codegen/api.py)
    participant Classifier as Trap Classifier (_classify_trap)
    participant CLI as CLI Handler (vera/cli.py)
    participant Streams as stdout/stderr

    WasmExec->>WasmExec: run WASM, buffer stdout (and stderr)
    WasmExec->>Classifier: _classify_trap(exc, last_violation)
    Classifier-->>WasmExec: (kind, message)
    WasmExec->>WasmExec: raise WasmTrapError(message, stdout, stderr, kind)
    WasmExec-->>CLI: propagate WasmTrapError
    CLI->>Streams: flush and replay captured stdout
    CLI->>Streams: replay captured stderr
    alt JSON mode
        CLI->>Streams: emit JSON envelope { ok:false, trap_kind, stdout, stderr }
    else Text mode
        CLI->>Streams: print formatted error message after replays
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Runtime traps need Vera-native diagnostics, not raw wasmtime stack traces #516 — Implements Stage‑1 runtime trap diagnostics: stable trap_kind classification, Vera‑native messages, and inclusion of trap_kind in JSON diagnostics; this PR implements the code path and wiring referenced by the issue.

Possibly related PRs

• Close #466 and remove stale ergonomic framing from ROADMAP #521 — Implements the runtime‑trap/stdout‑stderr fixes and tests that correspond to the IO.print‑on‑trap work realised here.

Suggested labels

compiler, tests, docs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.39% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarises the two primary changes: trap categorisation (WasmTrapError with stable kind taxonomy) and stdout preservation on trap, both of which are substantive throughout the PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bug-campaign-trap-diagnostics

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 85.18519% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.01%. Comparing base (ee0975f) to head (ad3eb2e).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
vera/cli.py	71.42%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #533      +/-   ##
==========================================
- Coverage   91.03%   91.01%   -0.03%     
==========================================
  Files          58       58              
  Lines       21964    22014      +50     
  Branches      259      259              
==========================================
+ Hits        19995    20036      +41     
- Misses       1962     1971       +9     
  Partials        7        7              

Flag	Coverage Δ
javascript	56.83% <ø> (ø)
python	94.97% <85.18%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@HISTORY.md`:
- Line 257: The new release entry v0.0.120 was added but the roll-up summary
still says "119 tagged releases"; update the summary count to reflect the new
release (change "119 tagged releases" to "120 tagged releases") and scan
HISTORY.md for any other places that mention the total number of tagged releases
to keep them consistent with the newly added v0.0.120 entry.

In `@KNOWN_ISSUES.md`:
- Line 17: The documentation incorrectly refers to the envelope field `kind`;
update the KNOWN_ISSUES.md wording to reference the actual emitted JSON key
`trap_kind` (as produced by cmd_run()) and adjust any examples or explanation
that direct downstream consumers to `kind` so they instead use `trap_kind`;
ensure the note still mentions staged fixes and v0.0.120 but points readers to
`trap_kind` used per diagnostic by cmd_run().

In `@README.md`:
- Line 184: Update the README banner text that currently reads "Vera is in
**active development** at v0.0.120 — 810+ commits, 120 releases, 3,536 tests,
96% code coverage, 80 conformance programs, 32 examples, and a 13-chapter
specification." to use the correct example count "30 examples" (i.e., change "32
examples" to "30 examples"); search for other prose occurrences of the example
count and make them consistent if present (references: the README banner line
containing "v0.0.120" and the mention of "examples").

In `@ROADMAP.md`:
- Line 39: Update the roadmap text to use the shipped JSON field name: replace
the mention of `kind` with `trap_kind` in the sentence that currently reads "the
JSON envelope carries the `kind`" so it instead reads that the JSON envelope
carries `trap_kind`; target the string `kind` in the ROADMAP.md entry for
"Runtime trap diagnostics (Stages 2–3)" and ensure the exact token `trap_kind`
is used to match the codebase.

In `@tests/test_runtime_traps.py`:
- Around line 195-211: The current test
test_json_mode_includes_stdout_in_envelope only covers IO.print/stdout and
misses the stderr-preservation contract; add a sibling regression test (e.g.,
test_json_mode_includes_stderr_in_envelope) that creates a temp file from a
program which writes to IO.stderr(...) before crashing, calls cmd_run(...,
as_json=True), parses the JSON envelope, asserts rc==1 and envelope["ok"] is
False, and verifies the envelope contains a "stderr" field with the expected
stderr lines (similar to the stdout assertions); reference cmd_run and IO.stderr
in the new test to ensure stderr is captured into the envelope.

In `@vera/cli.py`:
- Around line 640-685: The cmd_run execution path currently doesn't capture
runtime stderr so WasmTrapError handler's exc.stderr and JSON "stderr" field are
never populated; update the call site in cmd_run where execute(...) is invoked
to pass capture_stderr=True (matching how stdout is captured), then propagate
and use exec_result.stderr on the non-trap success path (i.e. when not raising
WasmTrapError) to replay or include stderr output the same way you handle
exec_result.stdout/as_json so both text and JSON modes emit the captured stderr
field and replay it to sys.stderr in text mode.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1ffde53b-6bf6-423b-ba72-255e1831a29d

📥 Commits

Reviewing files that changed from the base of the PR and between ee0975f and e51f1e8.

⛔ Files ignored due to path filters (5)

• docs/index.html is excluded by !docs/**
• docs/index.md is excluded by !docs/**
• docs/llms-full.txt is excluded by !docs/**
• docs/llms.txt is excluded by !docs/**
• docs/sitemap.xml is excluded by !docs/**

📒 Files selected for processing (11)

• CHANGELOG.md
• HISTORY.md
• KNOWN_ISSUES.md
• README.md
• ROADMAP.md
• TESTING.md
• pyproject.toml
• tests/test_runtime_traps.py
• vera/__init__.py
• vera/cli.py
• vera/codegen/api.py

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ROADMAP.md`:
- Line 272: Update the release count and version marker in the ROADMAP summary
string: change "119 tagged releases (as of v0.0.119)" to "120 tagged releases
(as of v0.0.120)" so the ROADMAP summary (the sentence containing "810+ commits,
119 tagged releases (as of v0.0.119), 3,551 tests...") matches the new v0.0.120
release referenced in HISTORY.md.

In `@TESTING.md`:
- Line 9: Update the aggregate test summary in TESTING.md to reflect the actual
run: change the total from 3,551 to 2,896 and update the passed/skipped counts
to match the real test run output (recalculate passed = actual passed, skipped =
actual skipped from your test run). Ensure the summary line that currently reads
"| **Tests** | 3,551 across 29 files (~34,200 lines of test code; 3,537 passed,
14 skipped) |" is replaced with the corrected totals and that the per-file
breakdown includes test_runtime_traps.py with 17 tests; verify the numbers are
consistent (total equals sum of per-file counts and passed+failed+skipped equals
total).

In `@tests/test_runtime_traps.py`:
- Around line 195-247: The tests test_json_mode_includes_stdout_in_envelope and
test_json_mode_includes_stderr_in_envelope currently assert envelope contents
but don't assert that nothing was written to the real stderr when cmd_run(...,
as_json=True) is used; update those tests to also assert capsys.readouterr().err
is empty (or specifically does not contain human-readable error text) after
calling cmd_run to ensure cmd_run/execute is invoked with capture_stderr=True
and that JSON mode does not leak messages to real stderr; locate assertions in
these tests and add the stderr-empty check, and consider adding the same check
to the related test functions referencing cmd_run and as_json in this diff.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6d28d7c6-629e-47d4-8b9f-30c7adb49b34

📥 Commits

Reviewing files that changed from the base of the PR and between e51f1e8 and 835dc68.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock, !uv.lock

📒 Files selected for processing (7)

• CHANGELOG.md
• HISTORY.md
• KNOWN_ISSUES.md
• ROADMAP.md
• TESTING.md
• tests/test_runtime_traps.py
• vera/cli.py

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@tests/test_runtime_traps.py`:
- Around line 175-193: Update the
test_text_mode_prints_buffered_stdout_before_error test to verify cross-stream
ordering by capturing stdout and stderr into the same buffer: add imports for io
and redirect_stdout/redirect_stderr, create a single io.StringIO, run
cmd_run(str(path)) while redirecting both stdout and stderr into that buffer,
then assert that the "line 1...line 4" messages appear in order and that "Error"
appears after them in the combined buffer; keep existing separate capsys
assertions optional but rely on the merged-buffer check for the ordering
guarantee.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 35564a33-2674-4b18-a711-c9a53d745891

📥 Commits

Reviewing files that changed from the base of the PR and between 835dc68 and 522303c.

📒 Files selected for processing (3)

• ROADMAP.md
• TESTING.md
• tests/test_runtime_traps.py