0027: a Clojure throw is a Wasm exception, and S3's last open decision closes

One nominal tag, clj-exn, whose payload is a Clojure value — today
(struct $Exn (field $class i32)), the class enum living as :exn-class
rows in the same trap table, the message half waiting for strings the
way printing waits in 0022 B.3. The overflow arms of add, sub and mul
stop being unreachable and throw class 1; the corpus compares all
three against real clojure's ArithmeticException "long overflow".

Traps stay traps because they must: the review verified catch_all
passes native traps AND stack exhaustion through on both engines — so
throws-as-traps would make try a whole-program rewrite, and one
divergence is numbered before try exists (the JVM catches
StackOverflowError; wasm never will).

Comparison precision is two-laned and the hole is in the artifact: the
V8 runner reads the thrown payload's class back through an exported
helper (GC structs are opaque to JS; tag identity is per-instance),
while wasmtime prints "thrown Wasm exception" for every class — row 3
carries that duplication visibly. The tested two-param-tag alternative
is rejected in the note for the reason that decides it: the tag
signature is the forever cross-module ABI, the helper is disposable
scaffolding.

Grammar changed, so 0026's interim rule ran: 119/119 modules agree
between wasm-tools and binaryen.js. Every S3 design decision is now
closed; the stop condition's missing half is a real browser page.

Claude-Session: https://claude.ai/code/session_01XF5Hfq4Ca2N2XYEzWQQuHt

Author: chaploud

corpus/run.mjs

@@ -14,9 +14,16 @@ const instance = new WebAssembly.Instance(
 try {
   console.log(`result ${instance.exports.entry()}`);
 } catch (e) {
+  // An uncaught Clojure throw is a WebAssembly.Exception on our tag;
+  // its payload's class is read back through Wasm, since GC structs
+  // are opaque to JS (0027). The tag must be THIS instance's — tag
+  // identity is per-instance.
+  if (e instanceof WebAssembly.Exception && e.is(instance.exports["clj-exn"])) {
+    console.log(`exn ${instance.exports.exn_class(e.getArg(instance.exports["clj-exn"], 0))}`);
+  }
   // V8 reports wasm stack exhaustion as RangeError, not RuntimeError
   // (0024) — both are classified outcomes, not harness failures.
-  if (e instanceof WebAssembly.RuntimeError || e instanceof RangeError)
+  else if (e instanceof WebAssembly.RuntimeError || e instanceof RangeError)
     console.log(`trap ${e.message}`);
   else throw e;
 }

corpus/s3.edn

@@ -121,4 +121,9 @@
  {:id "box-fib-91"       :forms [(defn fib-iter [n]
                                    (loop [i n a 0 b 1]
                                      (if (< 0 i) (recur (- i 1) b (+ a b)) a)))
-                                 (fib-iter 91)]}]
+                                 (fib-iter 91)]}
+ ;; --- a taken overflow arm throws (0027, trap-table row 3): all three
+ ;; ops, each against real clojure's ArithmeticException "long overflow".
+ {:id "throw-add-overflow" :forms [(+ 9223372036854775807 1)]}
+ {:id "throw-neg-min"      :forms [(- -9223372036854775808)]}
+ {:id "throw-mul-overflow" :forms [(* 4611686018427387904 2)]}]

corpus/trap_table.edn

@@ -10,6 +10,12 @@
 ;; 2026-07-30 on the pinned toolchain (wasmtime 47.0.1, V8/node).
 ;; Row 2 matches on class alone (:jvm-message "") — StackOverflowError's
 ;; message is null, a recorded weakening of the jvm-message guard (0024).
+;;
+;; Rows with :exn-class are thrown Wasm exceptions (0027): the V8 lane
+;; reads the class enum precisely; the wasmtime CLI lane prints the
+;; same "thrown Wasm exception" for every class — the visible
+;; duplication IS the named hole, retired when try/catch makes classes
+;; observable in-program.
 [{:row 1
   :class "java.lang.ArithmeticException"
   :jvm-message "/ by zero"
@@ -19,4 +25,9 @@
   :class "java.lang.StackOverflowError"
   :jvm-message ""
   :wasmtime "call stack exhausted"
-  :v8 "Maximum call stack size exceeded"}]
+  :v8 "Maximum call stack size exceeded"}
+ {:row 3
+  :class "java.lang.ArithmeticException"
+  :jvm-message "long overflow"
+  :exn-class 1
+  :wasmtime "thrown Wasm exception"}]

doc/design/0027-throw-representation.md

@@ -0,0 +1,131 @@
+# 0027 — The throw representation: one tag, a class payload, two lanes of precision
+
+**Status:** proposed · 2026-07-30 · adversarially reviewed the same day,
+before implementation. The review re-verified every engine claim
+(traps and stack exhaustion escape `catch_all` on both engines — the
+central argument holds) and changed five things, marked *(review)*:
+the tested two-param-tag alternative with the real reason it loses,
+the backtrace evidence the class-blind lane actually has, a divergence
+numbered before it exists (`try` will not catch stack exhaustion),
+the per-instance tag identity warning, and how a blind row reads in
+the table.
+
+## The question
+
+`0022` C deferred the throw representation to its own note — an
+output-format decision in `0009`'s non-retrofittable sense — and `0025`
+bracketed its cost: every boxed op already pays the overflow *check*,
+and the *taken* arm is still `(unreachable)`, so `(+ Long/MAX 1)` kills
+the program with the wrong identity instead of throwing what `clojure`
+throws. What is a thrown Clojure exception in emitted Wasm, how does an
+uncaught one compare against the oracle, and what waits for `try`?
+
+## The decision
+
+1. **A Clojure throw is a Wasm exception** — the final exception-handling
+   proposal: `tag`, `throw`, `try_table`. Verified by running on every
+   leg of the pinned toolchain (2026-07-30): `wasm-tools` parses and
+   validates; binaryen.js 131 assembles it (the `0026` differential
+   obligation, checked before deciding); V8/node catches in-module and
+   surfaces uncaught ones as `WebAssembly.Exception`; wasmtime 47.0.1
+   needs **no flag**, catches in-module, and reports an uncaught one as
+   "thrown Wasm exception", exit 1. The alternative — representing
+   throws as traps — is not a simplification but a dead end: **a trap
+   cannot be caught by `try_table`**, so the day `try` lands every
+   throw site would need re-emitting; that is the non-retrofittable
+   half, decided now.
+2. **One tag, `$clj-exn`, with a `(ref null eq)` payload.** The payload
+   is an ordinary Clojure value — which is what `ex-info` needs later —
+   and today it is `(struct $Exn (field $class i32))`: a class enum,
+   because no string representation exists yet, so the *message* half of
+   an exception waits for strings exactly as printing waits in
+   `0022` B.3. The enum is not a new artifact: trap-table rows gain an
+   `:exn-class` column, keeping one numbered table for every
+   error-comparison fact.
+3. **Tags are nominal, and the cross-module story is named, not built:**
+   two modules share `$clj-exn` only through import/export — unlike rec
+   groups, there is no structural identity for tags — so dev-mode
+   cross-form catching lands with the shared-runtime import shape
+   (`0026`'s preamble exit, `0009`'s world). Today's corpus modules are
+   self-contained, so a per-module tag is correct, not a compromise.
+   One measured warning for any future runner *(review)*: tag identity
+   is per-instance — `e.is()` against a byte-identical second
+   instance's tag is false — so a runner in the shared-runtime world
+   must hold the tag of the instance it observes, never a cached one.
+4. **Two lanes of comparison precision, the hole named** (`0022` B.4):
+   the V8 lane is **class-precise** — the module exports the tag and an
+   `exn_class` helper, and the runner reads the payload's class back
+   *through* Wasm, since GC structs are opaque to JS. The wasmtime CLI
+   lane is **class-blind on exceptions** — every uncaught throw prints
+   "thrown Wasm exception", so a blind row carries the same string as
+   every other exception row, and that visible duplication inside the
+   table is the honest rendering of the hole *(review)* — recorded
+   rather than discovered later; the V8 lane carries class precision
+   until `try`/`catch` makes classes observable in-program, which
+   retires the hole. The lane is less blind than the string alone
+   *(review)*: the backtrace names the throwing function (`!add`), and
+   the hole is accepted **with that evidence left unparsed** — frame
+   names are a debug section, not a contract, and would vanish under
+   inlining or a names strip. Native traps (division, cast,
+   `unreachable`, exhaustion) are unchanged rows — and one divergence
+   is numbered before it exists *(review)*: **`try` will not catch
+   stack exhaustion** — `catch_all` provably passes it through on both
+   engines — where the JVM's `(catch StackOverflowError …)` works.
+   Row 2's trap stays a trap even under `try`; number it the day `try`
+   lands.
+5. **The overflow arms throw, this commit:** `$add`/`$sub`/`$mul`'s
+   taken arms become `throw $clj-exn` with class 1
+   (`java.lang.ArithmeticException`, jvm-message "long overflow"), and
+   `(+ 9223372036854775807 1)` finally enters the corpus — with its
+   entries in the same commit, per `0022` B.1.
+
+## Why
+
+- Every claim above about engine behaviour was produced by running the
+  probe this session (scratchpad `eh_probe.wat`): catch-in-module
+  returns the payload's class on both engines; uncaught behaviour and
+  its exact strings are as quoted; binaryen.js round-trips it.
+- The single-tag shape mirrors the JVM itself: one `athrow`, class as
+  data. It also keeps `try` emission single-handler when it lands.
+- Deciding *now* costs one struct type and one tag in the runtime;
+  deciding *later* costs re-emitting every overflow arm and every
+  future throw site under whatever `try` needs.
+
+## Alternatives rejected
+
+- **Traps for Clojure throws.** Uncatchable by `try_table`; would make
+  `try` a whole-program rewrite. The reason this note exists.
+- **A (kind, payload) multi-value entry protocol** to give the wasmtime
+  CLI lane class precision on uncaught exceptions. Machinery for a
+  failure class nobody has seen, priced at touching every entry in both
+  runners; superseded anyway when `try` lands and classes become
+  observable in-program. The named hole plus V8-lane precision covers
+  the interim.
+- **The class as a second tag parameter** — `(tag (param i32
+  (ref null eq)))`, the class directly readable by the runner via
+  `getArg`, no helper export. **Tested, and it works** *(review)*; it
+  loses anyway, for the reason that actually decides this note: the
+  tag signature is the durable cross-module ABI (§3 — nominal,
+  import/export, forever), while the `exn_class` helper is disposable
+  corpus scaffolding. Baking a harness convenience into the permanent
+  ABI is the wrong trade, and the JVM analogy stays exact: one
+  `athrow`, one operand.
+- **One tag per exception class.** Tag explosion, cross-module identity
+  per class, and `try_table` needing a handler row per class — for
+  information that is data, not control flow.
+- **Reading the payload from JS via reflection.** GC structs are opaque
+  to JS by design; the helper-through-wasm is the supported path, not a
+  workaround.
+
+## What would falsify this
+
+- **The cost of a taken throw is unmeasured** — only the untaken check
+  is priced (B8). The throw/catch benchmark belongs before the `try`
+  emitter work, where catch frequency becomes a real workload; a cold
+  throw on an error path has no budget to violate.
+- **An engine changing its default for exception handling** — the
+  pinned versions carry the evidence; re-verify on any toolchain bump
+  (`/survey`'s three-month rule).
+- **The class enum outgrowing the table before strings land** — if the
+  enum needs more than the JVM classes the corpus actually compares,
+  that is the signal to pull strings forward rather than grow the enum.

doc/status.md

@@ -57,8 +57,18 @@ _Short by design, and printed at every session start — so findings live in
    flags (never `Features.All`), non-stacky emission.
    `corpus/devloop_differential.mjs` (113/113) is part of "done" for
    emitted-grammar changes until the dev lane is in the gate.
-   Remaining open: **the throw representation** — the next unit —
-   after which S2's nREPL unit is unblocked on both sides.
+   **The throw representation is decided and implemented** (`0027`):
+   a Clojure throw is a Wasm exception — one nominal tag, a class-enum
+   payload (`$Exn`; message waits for strings), overflow arms throw
+   `ArithmeticException`/"long overflow" (row 3, all three ops in the
+   corpus), the V8 lane class-precise, the wasmtime CLI lane
+   class-blind by a named hole, and traps stay uncatchable — including
+   stack exhaustion, a divergence numbered before `try` exists. **Every
+   S3 design decision is now closed.** Next: the S3 stop condition
+   still says *a browser*, and only node's V8 has run anything — the
+   next unit is **a real browser page running a corpus module**, the
+   smallest thing that would fail if "browser" were untrue; then S2's
+   nREPL unit, now unblocked on both sides.
 
 Done since the last update: `0016` `own<T>` handles, `0017` host imports
 (A–F), `0018` host-defined resources, `0012`'s `ex-data` contract shrunk to

src/cljwit/emit.clj

@@ -7,9 +7,7 @@
    are `$BoxI64` structs; nil is the null reference; false and true are
    singleton struct globals distinct by identity. Arithmetic unboxes
    either representation, computes in i64, and re-boxes through the one
-   canonicalizing guard. The overflow arms are `(unreachable)` — the
-   throw representation is the open decision (`0022` C, `0025` §4) and
-   no corpus entry may reach them.
+   canonicalizing guard; a taken overflow arm throws (`0027`).
 
    fn (`0024`): closures are subtypes of a `$Fn` base struct carrying one
    nullable typed-function-ref slot per arity; each capture signature is
@@ -18,7 +16,12 @@
    which are plain `call` — the first place the two modes emit different
    bytes. Method funcs declare `(type $sigN)` explicitly: a bare func
    type would canonicalize as its own singleton rec group and lose
-   identity with the slot's field type (`0009`'s rule, again)."
+   identity with the slot's field type (`0009`'s rule, again).
+
+   throw (`0027`): a Clojure throw is a Wasm exception — one tag
+   `$clj-exn` whose payload is a Clojure value, today `$Exn` with a
+   class enum (trap_table.edn's :exn-class column). The overflow arms
+   throw class 1; message comparison waits for strings."
   (:require [clojure.string :as str]
             [clojure.tools.analyzer.ast :as ast]))
 
@@ -377,6 +380,15 @@
 (def ^:private runtime
   "  (type $Unit (struct))
   (type $BoxI64 (struct (field $v i64)))
+  ;; The throw representation (0027): one tag, payload is a Clojure
+  ;; value — today a class enum; the message half waits for strings.
+  (type $Exn (struct (field $class i32)))
+  (tag $clj-exn (export \"clj-exn\") (param (ref null eq)))
+  ;; Corpus scaffolding, not ABI: lets the V8 runner read a caught
+  ;; payload's class back through Wasm, since GC structs are opaque
+  ;; to JS (0027).
+  (func $exn-class (export \"exn_class\") (param $e (ref null eq)) (result i64)
+    (i64.extend_i32_s (struct.get $Exn $class (ref.cast (ref $Exn) (local.get $e)))))
   (global $false (ref $Unit) (struct.new $Unit))
   (global $true (ref $Unit) (struct.new $Unit))
   (func $truthy (param $v (ref null eq)) (result i32)
@@ -396,8 +408,8 @@
                 (i64.shr_s (i64.shl (local.get $v) (i64.const 33)) (i64.const 33)))
       (then (ref.i31 (i32.wrap_i64 (local.get $v))))
       (else (struct.new $BoxI64 (local.get $v)))))
-  ;; Overflow arms are the open throw representation (0022 C, 0025 §4);
-  ;; signed-overflow checks per Hacker's Delight sign rules.
+  ;; Signed-overflow checks per Hacker's Delight sign rules; a taken
+  ;; arm throws ArithmeticException \"long overflow\" — class 1 (0027).
   (func $add (param $a (ref null eq)) (param $b (ref null eq)) (result (ref eq))
     (local $x i64) (local $y i64) (local $t i64)
     (local.set $x (call $unbox (local.get $a)))
@@ -406,7 +418,7 @@
     (if (i64.lt_s (i64.and (i64.xor (local.get $x) (local.get $t))
                            (i64.xor (local.get $y) (local.get $t)))
                   (i64.const 0))
-      (then (unreachable)))
+      (then (throw $clj-exn (struct.new $Exn (i32.const 1)))))
     (call $box (local.get $t)))
   (func $sub (param $a (ref null eq)) (param $b (ref null eq)) (result (ref eq))
     (local $x i64) (local $y i64) (local $t i64)
@@ -416,7 +428,7 @@
     (if (i64.lt_s (i64.and (i64.xor (local.get $x) (local.get $y))
                            (i64.xor (local.get $x) (local.get $t)))
                   (i64.const 0))
-      (then (unreachable)))
+      (then (throw $clj-exn (struct.new $Exn (i32.const 1)))))
     (call $box (local.get $t)))
   (func $mul (param $a (ref null eq)) (param $b (ref null eq)) (result (ref eq))
     (local $x i64) (local $y i64) (local $t i64)
@@ -429,9 +441,9 @@
       (then
         (if (i32.and (i64.eq (local.get $x) (i64.const -1))
                      (i64.eq (local.get $y) (i64.const -9223372036854775808)))
-          (then (unreachable)))
+          (then (throw $clj-exn (struct.new $Exn (i32.const 1)))))
         (if (i64.ne (i64.div_s (local.get $t) (local.get $x)) (local.get $y))
-          (then (unreachable)))))
+          (then (throw $clj-exn (struct.new $Exn (i32.const 1)))))))
     (call $box (local.get $t)))
   ;; quot: y = -1 wraps like the JVM's long division (MIN / -1 is MIN,
   ;; silently); y = 0 takes the native division trap, trap-table row 1.

test/cljwit/corpus_test.clj

@@ -87,18 +87,32 @@
       (throw (ex-info "the node corpus lane itself failed" {:err err}))
       (str/starts-with? line "result ") {:value (subs line 7)}
       (str/starts-with? line "trap ")   {:trap (subs line 5)}
+      ;; An uncaught Clojure throw, class-precise on this lane (0027).
+      (str/starts-with? line "exn ")    {:exn (parse-long (subs line 4))}
       :else (throw (ex-info (str "unrecognized corpus lane output: " (pr-str line)) {})))))
 
 ;; --- comparison -------------------------------------------------------------
 
 (defn- trap-matches?
   "True when a trap-table row licenses comparing this oracle throw equal
-   to this engine trap (0022 B.5)."
+   to this engine trap (0022 B.5). A row without a pattern for this
+   engine licenses nothing on it."
   [engine {:keys [message] :as oracle} trap]
   (boolean (some (fn [row]
                    (and (= (:class row) (:throw oracle))
                         (str/includes? (or message "") (:jvm-message row))
-                        (str/includes? trap (get row engine))))
+                        (when-let [pat (get row engine)]
+                          (str/includes? trap pat))))
+                 trap-table)))
+
+(defn- exn-matches?
+  "The class-precise half (0027): a lane that read the thrown payload's
+   class enum compares through a row's :exn-class."
+  [{:keys [message] :as oracle} exn-class]
+  (boolean (some (fn [row]
+                   (and (= (:class row) (:throw oracle))
+                        (str/includes? (or message "") (:jvm-message row))
+                        (= (:exn-class row) exn-class)))
                  trap-table)))
 
 (defn- out-of-contract?
@@ -121,6 +135,16 @@
                ") but no corpus/trap_table.edn row matches the trap: "
                (str/trim (:trap lane))))
 
+      (and (contains? oracle :throw) (contains? lane :exn))
+      (is (exn-matches? oracle (:exn lane))
+          (str label ": oracle threw " (:throw oracle) " (" (:message oracle)
+               ") but no trap-table row carries :exn-class " (:exn lane)))
+
+      (and (contains? oracle :value) (contains? lane :exn))
+      (is false
+          (str label ": oracle returned " (pr-str (:value oracle))
+               " but the lane threw exn class " (:exn lane)))
+
       (and (contains? oracle :value) (contains? lane :trap))
       (is false
           (str label ": oracle returned " (pr-str (:value oracle))