@cfasim-ui/shared 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Shared utilities for cfasim-ui",
   "license": "Apache-2.0",
@@ -17,7 +17,8 @@
   ],
   "exports": {
     ".": "./src/index.ts",
-    "./transfer": "./src/transferUtils.ts"
+    "./transfer": "./src/transferUtils.ts",
+    "./workerError": "./src/workerError.ts"
   },
   "peerDependencies": {
     "vue": "^3.5.0"

package/src/index.ts

@@ -4,7 +4,7 @@ export {
   postErrorWithTransfer,
   unwrapResponse,
 } from "./transferUtils.js";
-export type { TransferableResponse } from "./transferUtils.js";
+export type { TransferableResponse, WasmTrapKind } from "./transferUtils.js";
 export { ModelOutput, isoDate, DATE_MISSING } from "./ModelOutput.js";
 export type {
   ColumnDescriptor,
@@ -19,7 +19,13 @@ export type {
   ModelOutputsFileHeader,
   ModelOutputsFileTable,
 } from "./decodeModelOutputs.js";
-export { describeWorkerError, MESSAGEERROR_TEXT } from "./workerError.js";
+export {
+  describeWorkerError,
+  describeWasmTrap,
+  describeWasmInitTrap,
+  isWasmTrap,
+  MESSAGEERROR_TEXT,
+} from "./workerError.js";
 export { formatNumber, isNumberFormat } from "./formatNumber.js";
 export type { NumberFormat, NumberFormatPreset } from "./formatNumber.js";
 export {

package/src/transferUtils.ts

@@ -8,6 +8,8 @@ interface ModelOutputsResponsePayload {
   >;
 }
 
+export type WasmTrapKind = "call" | "init";
+
 export interface TransferableResponse {
   id: number;
   result?: unknown;
@@ -15,6 +17,13 @@ export interface TransferableResponse {
   bufferType?: string;
   modelOutputs?: ModelOutputsResponsePayload;
   error?: string;
+  /**
+   * The call died in a WebAssembly trap and the instance is no longer
+   * trustworthy: `"call"` inside the function, `"init"` while the module was
+   * initializing (its glue keeps the half-initialized instance, so only a new
+   * worker can retry).
+   */
+  trap?: WasmTrapKind;
 }
 
 const TYPED_ARRAY_CONSTRUCTORS: Record<
@@ -94,10 +103,12 @@ export function postErrorWithTransfer(
   port: typeof globalThis,
   id: number,
   error: unknown,
+  options: { trap?: WasmTrapKind } = {},
 ): void {
   port.postMessage({
     id,
     error: error instanceof Error ? error.message : String(error),
+    ...(options.trap ? { trap: options.trap } : {}),
   } satisfies TransferableResponse);
 }
 

package/src/workerError.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  describeWasmTrap,
+  describeWasmInitTrap,
+  describeWorkerError,
+  isWasmTrap,
+} from "./workerError.js";
+import { postErrorWithTransfer } from "./transferUtils.js";
+
+describe("describeWasmTrap", () => {
+  it("reports a recorded panic with its location", () => {
+    expect(
+      describeWasmTrap(
+        "unreachable",
+        "panicked at src/lib.rs:21:9: rate must be <= 5, got 9",
+        true,
+      ),
+    ).toBe("Model panicked at src/lib.rs:21:9: rate must be <= 5, got 9");
+  });
+
+  it("explains an unreachable trap with no panic as OOM or a replaced hook", () => {
+    expect(describeWasmTrap("unreachable", undefined, true)).toMatch(
+      /aborted without a recorded panic message.*out of memory.*replaced the panic hook/,
+    );
+  });
+
+  it("recognizes every engine's wording of the unreachable trap", () => {
+    for (const text of [
+      "unreachable executed",
+      "Unreachable code should not be executed (evaluating 'wasm.simulate(a)')",
+    ]) {
+      expect(describeWasmTrap(text, undefined, true)).toMatch(/aborted/);
+      expect(describeWasmTrap(text, undefined, false)).toMatch(/rebuild/);
+    }
+  });
+
+  it("asks for a rebuild against current cfasim-model when the hook is missing", () => {
+    expect(describeWasmTrap("unreachable", undefined, false)).toMatch(
+      /rebuild it against the current cfasim-model/,
+    );
+  });
+
+  it("passes other trap messages through", () => {
+    expect(
+      describeWasmTrap("memory access out of bounds", undefined, true),
+    ).toBe("Model trapped: memory access out of bounds");
+  });
+});
+
+describe("describeWasmInitTrap", () => {
+  it("explains an abort in init and passes other traps through", () => {
+    expect(describeWasmInitTrap("unreachable executed")).toMatch(
+      /panicked or aborted while initializing/,
+    );
+    expect(describeWasmInitTrap("Maximum call stack size exceeded")).toBe(
+      "Model trapped while initializing: Maximum call stack size exceeded",
+    );
+  });
+});
+
+describe("isWasmTrap", () => {
+  it("recognizes traps and engine stack overflows, not ordinary errors", () => {
+    expect(isWasmTrap(new WebAssembly.RuntimeError("unreachable"))).toBe(true);
+    expect(isWasmTrap(new RangeError("Maximum call stack size exceeded"))).toBe(
+      true,
+    );
+    const spiderMonkey = new Error("too much recursion");
+    spiderMonkey.name = "InternalError";
+    expect(isWasmTrap(spiderMonkey)).toBe(true);
+    expect(isWasmTrap(new RangeError("Invalid array length"))).toBe(false);
+    expect(isWasmTrap(new Error("rate must be <= 5"))).toBe(false);
+    expect(isWasmTrap("unreachable")).toBe(false);
+  });
+});
+
+describe("postErrorWithTransfer", () => {
+  it("flags a trap only when asked", () => {
+    const port = { postMessage: vi.fn() } as unknown as typeof globalThis;
+    postErrorWithTransfer(port, 1, new Error("boom"));
+    postErrorWithTransfer(port, 2, "plain", { trap: "call" });
+    expect(port.postMessage).toHaveBeenNthCalledWith(1, {
+      id: 1,
+      error: "boom",
+    });
+    expect(port.postMessage).toHaveBeenNthCalledWith(2, {
+      id: 2,
+      error: "plain",
+      trap: "call",
+    });
+  });
+});
+
+describe("describeWorkerError", () => {
+  it("falls back to a hint when the event is sanitized", () => {
+    const e = { message: "", filename: "", lineno: 0 } as ErrorEvent;
+    expect(describeWorkerError(e)).toMatch(/no error details/);
+  });
+});

package/src/workerError.ts

@@ -15,3 +15,55 @@ export function describeWorkerError(e: ErrorEvent): string {
 
 export const MESSAGEERROR_TEXT =
   "Worker received a message it could not deserialize (messageerror)";
+
+/**
+ * Message for a call that died in a WebAssembly trap. `panic` is the text
+ * recorded by `cfasim-model`'s panic hook (`panicked at <file>:<line>:<col>:
+ * <message>`) when the model panicked. `canRecord` says the module exports
+ * that hook at all; when it does not, the model is built on a cfasim-model
+ * too old to say. An `unreachable` trap with nothing recorded is an abort:
+ * the allocator giving up, or a panic after the model replaced the hook.
+ * Engines word the trap differently ("unreachable", "unreachable executed",
+ * "Unreachable code should not be executed"), hence the loose match.
+ */
+export function describeWasmTrap(
+  trapMessage: string,
+  panic: string | undefined,
+  canRecord: boolean,
+): string {
+  if (panic) return `Model ${panic}`;
+  if (!/unreachable/i.test(trapMessage)) return `Model trapped: ${trapMessage}`;
+  if (canRecord) {
+    return "Model aborted without a recorded panic message: it ran out of memory, or it replaced the panic hook outside a start function";
+  }
+  return "Model panicked or aborted (unreachable); rebuild it against the current cfasim-model to see the panic message";
+}
+
+/**
+ * Message for a trap while the module initialized. The panic hook is
+ * installed after init, so a start-function panic has no recorded message.
+ */
+export function describeWasmInitTrap(trapMessage: string): string {
+  if (/unreachable/i.test(trapMessage)) {
+    return "Model panicked or aborted while initializing, before the panic hook could be installed";
+  }
+  return `Model trapped while initializing: ${trapMessage}`;
+}
+
+/**
+ * Whether an error thrown by a wasm call left the instance unusable. A
+ * `WebAssembly.RuntimeError` is any trap (a Rust panic or abort ends in
+ * `unreachable`). A stack overflow is not a trap but unwinds through the
+ * wasm frames without running their epilogues, so the shadow stack pointer
+ * is left wherever it was: V8 throws a `RangeError`, SpiderMonkey an
+ * `InternalError`. A JS-side overflow in the worker would match too; the
+ * worker has no recursion of its own, and the cost is one spare replacement.
+ */
+export function isWasmTrap(error: unknown): boolean {
+  if (error instanceof WebAssembly.RuntimeError) return true;
+  if (!(error instanceof Error)) return false;
+  return (
+    (error.name === "RangeError" || error.name === "InternalError") &&
+    /call stack|too much recursion/i.test(error.message)
+  );
+}