@cfasim-ui/shared 0.9.3 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.9.3",
+  "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/ModelOutput.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { ModelOutput } from "./ModelOutput.js";
+import { ModelOutput, DATE_MISSING, isoDate } from "./ModelOutput.js";
 import type {
   ModelOutputWire,
   ModelOutputsWire,
@@ -207,3 +207,20 @@ describe("transfer protocol with ModelOutputs", () => {
     expect(unwrapResponse(response)).toBe("hello");
   });
 });
+
+describe("date columns", () => {
+  it("decodes days since the epoch to ISO strings and CSV", () => {
+    const output = new ModelOutput(
+      3,
+      [{ name: "when", type: "date" }],
+      [new Uint32Array([0, 20458, DATE_MISSING])],
+    );
+    expect(output.dates("when")).toEqual(["1970-01-01", "2026-01-05", null]);
+    expect(isoDate(20465)).toBe("2026-01-12");
+    expect(isoDate(0)).toBe("1970-01-01");
+    expect(isoDate(2_932_897)).toBe("10000-01-01");
+    expect(isoDate(4_000_000_000)).toBeNull();
+    expect(modelOutputToCSV(output)).toBe("when\n1970-01-01\n2026-01-05\n");
+    expect(() => output.dates("nope")).toThrow();
+  });
+});

package/src/ModelOutput.ts

@@ -1,4 +1,8 @@
-export type ColumnType = "i32" | "u32" | "f64" | "bool" | "enum";
+export type ColumnType = "i32" | "u32" | "f64" | "bool" | "enum" | "date";
+
+/** Value of a `date` column with no date (`DATE_MISSING` on the Python side). */
+export const DATE_MISSING = 0xffffffff;
+const DAY_MS = 86_400_000;
 
 export interface ColumnDescriptor {
   name: string;
@@ -20,17 +24,27 @@ export interface ModelOutputsWire {
   outputs: Record<string, ModelOutputWire>;
 }
 
-const COLUMN_TYPE_TO_CTOR: Record<
+export const COLUMN_TYPE_TO_CTOR: Record<
   ColumnType,
-  new (buffer: ArrayBuffer) => TypedColumn
+  { new (buffer: ArrayBuffer): TypedColumn; BYTES_PER_ELEMENT: number }
 > = {
   f64: Float64Array,
   i32: Int32Array,
   u32: Uint32Array,
   bool: Uint8Array,
   enum: Uint32Array,
+  date: Uint32Array,
 };
 
+/** ISO `yyyy-mm-dd` for a `date` column value (days since 1970-01-01). */
+export function isoDate(days: number): string | null {
+  const date = new Date(days * DAY_MS);
+  if (days === DATE_MISSING || Number.isNaN(date.getTime())) return null;
+  // Not toISOString, which writes years past 9999 as "+010000".
+  const pad = (n: number, width = 2) => String(n).padStart(width, "0");
+  return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+}
+
 export class ModelOutput {
   readonly length: number;
   readonly columns: readonly ColumnDescriptor[];
@@ -66,6 +80,14 @@ export class ModelOutput {
     return desc.enumLabels[index];
   }
 
+  /** A `date` column as ISO strings (`null` where the date is missing). */
+  dates(columnName: string): (string | null)[] {
+    if (this.descriptor(columnName).type !== "date") {
+      throw new Error(`Column ${columnName} is not a date`);
+    }
+    return Array.from(this.column(columnName), isoDate);
+  }
+
   get names(): string[] {
     return this.columns.map((c) => c.name);
   }

package/src/csv.ts

@@ -1,4 +1,5 @@
 import type { ModelOutput } from "./ModelOutput.js";
+import { isoDate } from "./ModelOutput.js";
 
 export function modelOutputToCSV(output: ModelOutput): string {
   const header = output.names.join(",");
@@ -10,6 +11,8 @@ export function modelOutputToCSV(output: ModelOutput): string {
       const val = output.buffers[c][r];
       if (desc.type === "enum") {
         cells.push(desc.enumLabels![val as number]);
+      } else if (desc.type === "date") {
+        cells.push(isoDate(val as number) ?? "");
       } else if (desc.type === "bool") {
         cells.push(val ? "true" : "false");
       } else {

package/src/decodeModelOutputs.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { decodeModelOutputs } from "./decodeModelOutputs.js";
+
+// Shared protocol fixtures, written by the Python reference implementation.
+// (__dirname rather than import.meta.url: happy-dom gives the latter an http scheme.)
+const FIXTURES = resolve(__dirname, "../../../cfasim-model-py/tests/fixtures");
+
+function fixtureBuffer(name: string): ArrayBuffer {
+  const bytes = readFileSync(resolve(FIXTURES, name));
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}
+
+const expected = JSON.parse(
+  readFileSync(resolve(FIXTURES, "sample.columns.json"), "utf8"),
+) as Record<string, Record<string, number[]>>;
+
+describe("decodeModelOutputs", () => {
+  it("decodes the shared fixture into ModelOutput tables", () => {
+    const outputs = decodeModelOutputs(fixtureBuffer("sample.cfasim"));
+    expect(Object.keys(outputs).sort()).toEqual(["empty", "series"]);
+    for (const [table, columns] of Object.entries(expected)) {
+      for (const [name, values] of Object.entries(columns)) {
+        expect(Array.from(outputs[table].column(name))).toEqual(values);
+      }
+    }
+    expect(outputs.series.column("time")).toBeInstanceOf(Float64Array);
+    expect(outputs.series.column("delta")).toBeInstanceOf(Int32Array);
+    expect(outputs.series.column("count")).toBeInstanceOf(Uint32Array);
+    expect(outputs.series.column("flag")).toBeInstanceOf(Uint8Array);
+    const status = outputs.series.column("status");
+    expect(outputs.series.label("status", status[1])).toBe("R");
+    expect(outputs.empty.length).toBe(0);
+  });
+
+  it("matches the committed header", () => {
+    const buf = fixtureBuffer("sample.cfasim");
+    const headerLength = new DataView(buf).getUint32(0, true);
+    const header = JSON.parse(
+      new TextDecoder().decode(new Uint8Array(buf, 4, headerLength)),
+    );
+    const dataStart = 4 + headerLength;
+    const committed = JSON.parse(
+      readFileSync(resolve(FIXTURES, "sample.header.json"), "utf8"),
+    );
+    expect(header).toEqual(committed);
+    expect(dataStart % 8).toBe(0);
+  });
+
+  it("rejects truncated and malformed files", () => {
+    const buf = fixtureBuffer("sample.cfasim");
+    expect(() => decodeModelOutputs(buf.slice(0, buf.byteLength - 4))).toThrow(
+      /truncated/,
+    );
+    expect(() => decodeModelOutputs(buf.slice(0, 2))).toThrow(/truncated/);
+    const bad = new Uint8Array(buf.slice(0));
+    const text = new TextDecoder().decode(bad.subarray(4, 24));
+    const idx = 4 + text.indexOf('"version":1') + '"version":'.length;
+    bad[idx] = "2".charCodeAt(0);
+    expect(() => decodeModelOutputs(bad.buffer as ArrayBuffer)).toThrow(
+      /version/,
+    );
+  });
+});

package/src/decodeModelOutputs.ts

@@ -0,0 +1,80 @@
+import type { ColumnDescriptor } from "./ModelOutput.js";
+import { COLUMN_TYPE_TO_CTOR, ModelOutput } from "./ModelOutput.js";
+
+/**
+ * Header of a `.cfasim` outputs file. The file is a little-endian u32 header
+ * length, a UTF-8 JSON header (space-padded to an 8-byte boundary), then the
+ * raw column buffers; `byteOffsets` are relative to the start of the buffers.
+ */
+export interface ModelOutputsFileTable {
+  length: number;
+  columns: ColumnDescriptor[];
+  byteOffsets: number[];
+  /** Unpadded byte length per column. */
+  byteLengths: number[];
+}
+
+export interface ModelOutputsFileHeader {
+  version: number;
+  outputs: Record<string, ModelOutputsFileTable>;
+}
+
+function readModelOutputsHeader(buffer: ArrayBuffer): {
+  header: ModelOutputsFileHeader;
+  dataStart: number;
+} {
+  if (buffer.byteLength < 4) {
+    throw new Error("outputs file is truncated (no header length)");
+  }
+  const headerLength = new DataView(buffer).getUint32(0, true);
+  const dataStart = 4 + headerLength;
+  if (dataStart > buffer.byteLength) {
+    throw new Error("outputs file is truncated (header)");
+  }
+  const text = new TextDecoder().decode(
+    new Uint8Array(buffer, 4, headerLength),
+  );
+  const header = JSON.parse(text) as ModelOutputsFileHeader;
+  if (header.version !== 1) {
+    throw new Error(`unsupported outputs file version ${header.version}`);
+  }
+  return { header, dataStart };
+}
+
+/**
+ * Decode a `.cfasim` outputs file (as served by `GET /api/runs/{id}/outputs`
+ * or read from disk) into named `ModelOutput` tables. Column buffers are
+ * copied out of `buffer`, so the file bytes can be released afterwards.
+ */
+export function decodeModelOutputs(
+  buffer: ArrayBuffer,
+): Record<string, ModelOutput> {
+  const { header, dataStart } = readModelOutputsHeader(buffer);
+  const result: Record<string, ModelOutput> = {};
+  for (const [name, table] of Object.entries(header.outputs)) {
+    const buffers = table.columns.map((col, i) => {
+      const bpe = COLUMN_TYPE_TO_CTOR[col.type]?.BYTES_PER_ELEMENT;
+      if (bpe === undefined) {
+        throw new Error(`column ${col.name} has unknown type ${col.type}`);
+      }
+      const start = dataStart + table.byteOffsets[i];
+      const bytes = table.byteLengths[i];
+      if (bytes !== table.length * bpe) {
+        throw new Error(
+          `column ${col.name} has ${bytes} bytes for ${table.length} rows`,
+        );
+      }
+      if (start + bytes > buffer.byteLength) {
+        throw new Error(`outputs file is truncated (column ${col.name})`);
+      }
+      return buffer.slice(start, start + bytes);
+    });
+    result[name] = ModelOutput.fromWire({
+      __modelOutput: true,
+      length: table.length,
+      columns: table.columns,
+      buffers,
+    });
+  }
+  return result;
+}

package/src/index.ts

@@ -4,8 +4,8 @@ export {
   postErrorWithTransfer,
   unwrapResponse,
 } from "./transferUtils.js";
-export type { TransferableResponse } from "./transferUtils.js";
-export { ModelOutput } from "./ModelOutput.js";
+export type { TransferableResponse, WasmTrapKind } from "./transferUtils.js";
+export { ModelOutput, isoDate, DATE_MISSING } from "./ModelOutput.js";
 export type {
   ColumnDescriptor,
   ColumnType,
@@ -14,7 +14,18 @@ export type {
   ModelOutputsWire,
 } from "./ModelOutput.js";
 export { modelOutputToCSV } from "./csv.js";
-export { describeWorkerError, MESSAGEERROR_TEXT } from "./workerError.js";
+export { decodeModelOutputs } from "./decodeModelOutputs.js";
+export type {
+  ModelOutputsFileHeader,
+  ModelOutputsFileTable,
+} from "./decodeModelOutputs.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)
+  );
+}