@hew-lang/sandbox-vm 0.6.0-rc7 → 0.6.0

package/README.md

@@ -47,3 +47,9 @@ make sandbox-fixtures-check
 The [package contract](bytecode/package-v1.md) describes the SIR projection.
 Source fixtures are compiled by the public compiler and executed to record
 deterministic traces. Tests also compare executable sources with native Hew.
+
+Typed serialization executes the shared Rust codecs in `@hew-lang/wasm`.
+Pass its initialized `executeCodec` export as `runBytecode`'s `codecBridge`
+option. The Node test host loads that package automatically; in a source
+checkout, run `make wasm` to build `hew-wasm/pkg` first. An explicit
+`HEW_WASM_MODULE` module URL can select another build of the same package.

package/cli/test-runner.mjs

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import process from "node:process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { classifyHewFault, runBytecode, traceToDownloadJson } from "../dist/interpreter/index.js";
+
+function parseArgs(args) {
+  if (args.length !== 7 || args[1] !== "--schedule" || args[3] !== "--seed" || args[5] !== "--step-budget") {
+    throw new Error("usage: test-runner <bytecode.json> --schedule fifo|random --seed N --step-budget N");
+  }
+  const schedule = args[2];
+  if (schedule !== "fifo" && schedule !== "random") throw new Error(`unknown schedule: ${schedule}`);
+  const seed = BigInt(args[4]);
+  const budget = Number(args[6]);
+  if (!Number.isSafeInteger(budget) || budget <= 0) throw new Error("step budget must be a positive safe integer");
+  return { path: args[0], schedule, seed, budget };
+}
+
+const reportPath = process.env.HEW_TEST_REPORT;
+const tracePath = process.env.HEW_TEST_TRACE_PATH;
+try {
+  const args = parseArgs(process.argv.slice(2));
+  const packageValue = JSON.parse(fs.readFileSync(args.path, "utf8"));
+  let codecBridge;
+  if (packageValue.codecs?.length) {
+    const local = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../hew-wasm/pkg/hew_wasm.js");
+    const location = process.env.HEW_WASM_MODULE ?? (fs.existsSync(local) ? pathToFileURL(local).href : "@hew-lang/wasm");
+    const wasm = await import(location);
+    if (typeof wasm.default === "function") {
+      const resolved = location.startsWith("file:") ? location : import.meta.resolve(location);
+      await wasm.default({ module_or_path: fs.readFileSync(new URL(resolved.replace(/\.js$/, "_bg.wasm"))) });
+    }
+    codecBridge = wasm.executeCodec ?? wasm.default?.executeCodec;
+    if (typeof codecBridge !== "function") throw new Error("hew-wasm executeCodec export is missing; rebuild the Wasm package");
+  }
+  const propertyPath = reportPath ? path.join(path.dirname(reportPath), "property.cbor") : null;
+  const trace = runBytecode(packageValue, {
+    codecBridge,
+    propertyInput: propertyPath && fs.existsSync(propertyPath) ? [...fs.readFileSync(propertyPath)] : [],
+    fixtureId: "hew-test",
+    traceId: "trace:hew-test",
+    schedulerPolicy: args.schedule === "random" ? "chaos" : "round_robin",
+    replay: {
+      seed: args.seed.toString(),
+      step_budget: args.budget,
+      virtual_clock: { epoch_ms: 0, tick_ms: 1, current_ms: 0 },
+      inputs: [],
+    },
+  });
+  if (tracePath) fs.writeFileSync(tracePath, traceToDownloadJson(trace));
+  const final = trace.final_state;
+  const rejection = final.sandbox_rejections[0];
+  const fault = final.runtime_failures[0];
+  const hewFault = classifyHewFault(trace);
+  const passed = trace.result === "ok" && final.exit_code === 0;
+  const outcome = passed ? "passed" : rejection ? "refused" : fault ? "fault" : "exit";
+  const message = rejection?.message ?? fault?.message ?? (passed ? null : `VM result: ${trace.result}`);
+  const faultKind = hewFault?.kind ?? fault?.kind ?? null;
+  const report = {
+    version: 1,
+    coverage: final.coverage ?? {},
+    outcome,
+    status: passed ? 0 : 1,
+    fault_kind: faultKind,
+    fault_code: hewFault?.code ?? null,
+    message,
+    site_offset: null,
+    assertion: fault?.assertion ?? null,
+    schedule: args.schedule,
+    seed: args.seed.toString(),
+    steps: final.step_count,
+    virtual_time_ms: final.virtual_clock.current_ms,
+  };
+  if (reportPath) fs.writeFileSync(reportPath, JSON.stringify(report));
+  process.stdout.write(final.stdout.join(""));
+  process.stderr.write(final.stderr.join(""));
+  if (message) process.stderr.write(`${message}\n`);
+  process.exitCode = report.status;
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (reportPath) fs.writeFileSync(reportPath, JSON.stringify({ version: 1, outcome: "launch", status: 1, message }));
+  process.stderr.write(`hew test VM: ${message}\n`);
+  process.exitCode = 1;
+}

package/dist/interpreter/parity-runner.js

@@ -57,6 +57,15 @@ try {
     });
     process.stdout.write(trace.final_state.stdout.join(""));
     process.stderr.write(trace.final_state.stderr.join(""));
+    if (trace.final_state.exit_code === null &&
+        trace.final_state.stderr.length === 0) {
+        process.stderr.write(`parity-runner: ${JSON.stringify({
+            status: trace.result,
+            diagnostics: trace.final_state.diagnostics,
+            rejections: trace.final_state.sandbox_rejections,
+            failures: trace.final_state.runtime_failures,
+        })}\n`);
+    }
     process.exitCode = trace.final_state.exit_code ?? 1;
 }
 catch (error) {

package/dist/interpreter/run-program.d.ts

@@ -20,10 +20,11 @@ interface CompileOutput {
     diagnostics: Diagnostic[];
     bytecode: PackageV1 | null;
 }
-type SandboxCompiler = (source: string, profile?: string) => string | CompileOutput;
+type SandboxCompiler = (source: string, profile?: string, files?: Map<string, string | Uint8Array>) => string | CompileOutput;
 declare global {
     var __hewSandboxCompileToSandboxBytecode: SandboxCompiler | undefined;
+    var __hewSandboxExecuteCodec: ((request: string) => string) | undefined;
     var compileToSandboxBytecode: SandboxCompiler | undefined;
 }
-export declare function runProgram(source: string, stdin: string): RunProgramResult;
+export declare function runProgram(source: string, stdin: string, files?: Map<string, string | Uint8Array>): RunProgramResult;
 export {};

package/dist/interpreter/run-program.js

@@ -1,7 +1,7 @@
 import { runBytecode } from "./interpreter.js";
 const SANDBOX_PROFILE = "sandbox-vm-export";
-export function runProgram(source, stdin) {
-    const compileOutput = compileSource(source);
+export function runProgram(source, stdin, files) {
+    const compileOutput = compileSource(source, files);
     if (hasErrorDiagnostics(compileOutput.diagnostics) ||
         compileOutput.bytecode === null) {
         return {
@@ -17,6 +17,7 @@ export function runProgram(source, stdin) {
     const bytecode = compileOutput.bytecode;
     const trace = runBytecode(bytecode, {
         fixtureId: "page-run",
+        codecBridge: globalThis.__hewSandboxExecuteCodec,
         traceId: "trace:page-run",
         replay: { inputs: [{ kind: "stdin", data: stdin }] },
     });
@@ -30,13 +31,13 @@ export function runProgram(source, stdin) {
         diagnostics: [...compileOutput.diagnostics, ...runtimeDiagnostics(trace)],
     };
 }
-function compileSource(source) {
+function compileSource(source, files) {
     const compiler = globalThis.__hewSandboxCompileToSandboxBytecode ??
         globalThis.compileToSandboxBytecode;
     if (!compiler) {
         throw new Error("compile_to_sandbox_bytecode WASM bridge is not initialized");
     }
-    const output = compiler(source, SANDBOX_PROFILE);
+    const output = compiler(source, SANDBOX_PROFILE, files);
     const parsed = typeof output === "string" ? JSON.parse(output) : output;
     if (!isCompileOutput(parsed)) {
         throw new Error("compile_to_sandbox_bytecode returned an invalid payload");

package/dist/interpreter/trace.d.ts

@@ -21,6 +21,7 @@ export declare class TraceBuilder {
     private readonly traceId;
     readonly replay: ReplayConfig;
     private readonly sandboxVersion;
+    readonly coverage: Record<string, number>;
     readonly stdout: string[];
     readonly stderr: string[];
     readonly runtimeFailures: RuntimeFailure[];

package/dist/interpreter/trace.js

@@ -5,6 +5,7 @@ export class TraceBuilder {
     traceId;
     replay;
     sandboxVersion;
+    coverage = {};
     stdout = [];
     stderr = [];
     runtimeFailures = [];
@@ -174,6 +175,9 @@ export class TraceBuilder {
             replay: this.replay,
             events: this.events,
             final_state: {
+                ...(Object.keys(this.coverage).length > 0
+                    ? { coverage: this.coverage }
+                    : {}),
                 status: this.status,
                 exit_code: this.status === "ok" ? this.exitCode : null,
                 step_count: this.stepCount,

package/dist/interpreter/types.d.ts

@@ -91,6 +91,7 @@ export interface SandboxTrace {
     replay: ReplayConfig;
     events: TraceEvent[];
     final_state: {
+        coverage?: Record<string, number>;
         status: RuntimeStatus;
         exit_code: number | null;
         step_count: number;
@@ -116,6 +117,8 @@ export interface SandboxTrace {
     };
 }
 export interface RunOptions {
+    codecBridge?: (request: string) => string;
+    propertyInput?: number[];
     fixtureId?: string;
     traceId?: string;
     replay?: Partial<ReplayConfig>;

package/dist/interpreter/v1/codecs.d.ts

@@ -0,0 +1,9 @@
+import { type VmValue } from "../values.js";
+import { type PackageV1, type TermV1 } from "./package.js";
+import { type ValueProgram } from "./value-operations.js";
+export type CodecBridge = (request: string) => string;
+type CodecTerm = Extract<TermV1, {
+    op: "wire.codec";
+}>;
+export declare function executeCodec(pkg: PackageV1, term: CodecTerm, input: VmValue, bridge: CodecBridge | undefined, propertyInput: number[]): ValueProgram;
+export {};

package/dist/interpreter/v1/codecs.js

@@ -0,0 +1,266 @@
+import { UNIT } from "../values.js";
+import { runtimeTag } from "./package.js";
+import { collectionOperation } from "./value-operations.js";
+class DecodeFailure extends Error {
+}
+class Duplicate extends Error {
+    detail;
+    constructor(detail) {
+        super("duplicate decoded key");
+        this.detail = detail;
+    }
+}
+function array(value) {
+    if (!Array.isArray(value))
+        throw new Error("codec bridge returned a non-positional value");
+    return value;
+}
+function fields(value) {
+    if (value.kind === "record")
+        return value.fields;
+    if (value.kind === "vector")
+        return value.items;
+    throw new Error(`codec aggregate received ${value.kind}`);
+}
+function toBridge(pkg, shape, id, value) {
+    const node = shape.nodes[id];
+    if (node === "Unit")
+        return null;
+    if (node === "Bool" && value.kind === "bool")
+        return value.value;
+    if ((node === "Char" || node === "String") && value.kind === "string")
+        return value.value;
+    if (node === "Bytes")
+        return fields(value).map((byte) => {
+            if (byte.kind !== "i64")
+                throw new Error("invalid byte");
+            return Number(byte.value);
+        });
+    if (typeof node === "string")
+        throw new Error(`invalid codec scalar ${node}`);
+    if ("Float" in node) {
+        if (value.kind !== "f64")
+            throw new Error("codec float has wrong VM kind");
+        const number = value.value;
+        return Object.is(number, -0) ? "-0" : String(number);
+    }
+    if ("Signed" in node || "Unsigned" in node) {
+        if (value.kind !== "i64")
+            throw new Error("codec integer has wrong VM kind");
+        return ("Unsigned" in node ? BigInt.asUintN(64, value.value) : value.value).toString();
+    }
+    if ("Tuple" in node)
+        return fields(value).map((field, i) => toBridge(pkg, shape, node.Tuple[i], field));
+    if ("Record" in node)
+        return fields(value).map((field, i) => toBridge(pkg, shape, node.Record[i][1], field));
+    if ("Array" in node || "Sequence" in node) {
+        const child = "Array" in node ? node.Array.element : node.Sequence;
+        return fields(value).map((item) => toBridge(pkg, shape, child, item));
+    }
+    if ("Option" in node) {
+        if (value.kind !== "enum")
+            throw new Error("codec Option is not a variant");
+        return value.tag === runtimeTag(pkg.variants[value.shape], "OptionNone")
+            ? null
+            : [toBridge(pkg, shape, node.Option, value.payload[0])];
+    }
+    if ("Variant" in node) {
+        if (value.kind !== "enum")
+            throw new Error("codec enum is not a variant");
+        const child = node.Variant[value.tag][1];
+        if (child === null)
+            return [value.tag, null];
+        const payload = shape.grouped_payloads[child]
+            ? { kind: "record", typeId: "", fields: value.payload }
+            : value.payload[0];
+        return [value.tag, toBridge(pkg, shape, child, payload)];
+    }
+    if (value.kind !== "map")
+        throw new Error("codec collection is not a map");
+    if ("Set" in node)
+        return [...value.entries.values()].map((entry) => [
+            toBridge(pkg, shape, node.Set, entry.key),
+            null,
+        ]);
+    return [...value.entries.values()].map((entry) => [
+        toBridge(pkg, shape, node.Map.key, entry.key),
+        toBridge(pkg, shape, node.Map.value, entry.value),
+    ]);
+}
+function* fromBridge(pkg, shape, id, value, context) {
+    if (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.decode_error)
+        throw new DecodeFailure();
+    const node = shape.nodes[id];
+    const name = shape.names[id] ?? "";
+    const aggregate = shape.aggregates[id] ?? undefined;
+    const variant = shape.variants[id];
+    if (node === "Unit")
+        return UNIT;
+    if (node === "Bool")
+        return { kind: "bool", value: Boolean(value) };
+    if (node === "Char" || node === "String")
+        return { kind: "string", value: String(value) };
+    if (node === "Bytes")
+        return {
+            kind: "vector",
+            elementType: "u8",
+            items: array(value).map((byte) => ({
+                kind: "i64",
+                value: BigInt(String(byte)),
+            })),
+        };
+    if (typeof node === "string")
+        throw new Error(`invalid codec scalar ${node}`);
+    if ("Float" in node) {
+        const number = value === "inf" ? Infinity : value === "-inf" ? -Infinity : Number(value);
+        return { kind: "f64", value: number };
+    }
+    if ("Signed" in node || "Unsigned" in node)
+        return { kind: "i64", value: BigInt(String(value)) };
+    if ("Option" in node) {
+        if (variant === null || variant === undefined)
+            throw new Error("codec Option lacks its shape");
+        return {
+            kind: "enum",
+            typeId: name,
+            shape: variant,
+            tag: runtimeTag(pkg.variants[variant], value === null ? "OptionNone" : "OptionSome"),
+            payload: value === null
+                ? []
+                : [
+                    yield* fromBridge(pkg, shape, node.Option, array(value)[0], context),
+                ],
+        };
+    }
+    if ("Variant" in node) {
+        if (variant === null || variant === undefined)
+            throw new Error("codec enum lacks its shape");
+        const pair = array(value), tag = Number(pair[0]), child = node.Variant[tag][1];
+        let payload = [];
+        if (child !== null) {
+            const decoded = yield* fromBridge(pkg, shape, child, pair[1], context);
+            payload = shape.grouped_payloads[child] ? fields(decoded) : [decoded];
+        }
+        return { kind: "enum", typeId: name, shape: variant, tag, payload };
+    }
+    if ("Map" in node || "Set" in node) {
+        const family = "Map" in node ? "Map" : "Set";
+        const map = yield* collectionOperation(pkg, family, "New", [], [], null);
+        for (const item of array(value)) {
+            const itemFields = array(item);
+            const pair = "Map" in node ? itemFields : [itemFields[0], null];
+            const key = yield* fromBridge(pkg, shape, "Map" in node ? node.Map.key : node.Set, pair[0], context);
+            const member = "Map" in node
+                ? yield* fromBridge(pkg, shape, node.Map.value, pair[1], context)
+                : UNIT;
+            if (map.kind !== "map")
+                throw new Error("codec collection has no map storage");
+            const size = map.entries.size;
+            yield* collectionOperation(pkg, family, "Insert", [map, key, member], context.callbacks[id] ?? [], null);
+            if (!context.propertyInput && map.entries.size === size)
+                throw new Duplicate(itemFields["Map" in node ? 2 : 1]);
+        }
+        return map;
+    }
+    const values = [];
+    for (const [i, item] of array(value).entries()) {
+        const child = "Tuple" in node
+            ? node.Tuple[i]
+            : "Record" in node
+                ? node.Record[i][1]
+                : "Array" in node
+                    ? node.Array.element
+                    : node.Sequence;
+        values.push(yield* fromBridge(pkg, shape, child, item, context));
+    }
+    return "Array" in node || "Sequence" in node
+        ? { kind: "vector", elementType: "", items: values }
+        : { kind: "record", typeId: name, shape: aggregate, fields: values };
+}
+export function* executeCodec(pkg, term, input, bridge, propertyInput) {
+    if (!bridge)
+        throw new Error("typed codecs require the hew-wasm executeCodec bridge");
+    const encoded = pkg.codecs?.[term.codec];
+    if (encoded === undefined)
+        throw new Error("codec shape is absent");
+    const shape = JSON.parse(encoded);
+    const request = {
+        shape: encoded,
+        format: term.format,
+        direction: term.direction,
+        error_root: term.decoded?.error_root,
+        ...(term.direction === "encode"
+            ? { value: toBridge(pkg, shape, shape.root, input) }
+            : term.direction === "test_input"
+                ? {
+                    input: propertyInput,
+                    ordinal: input.kind === "i64" ? Number(input.value) : -1,
+                }
+                : {
+                    input: input.kind === "string"
+                        ? [...new TextEncoder().encode(input.value)]
+                        : fields(input).map((byte) => byte.kind === "i64" ? Number(byte.value) : -1),
+                }),
+    };
+    let result = JSON.parse(bridge(JSON.stringify(request)));
+    if (result.failure !== undefined)
+        throw new Error(result.failure);
+    if (term.direction === "encode") {
+        const bytes = array(result.value).map(Number);
+        return term.format === 0 || term.format === 4
+            ? {
+                kind: "vector",
+                elementType: "u8",
+                items: bytes.map((byte) => ({ kind: "i64", value: BigInt(byte) })),
+            }
+            : {
+                kind: "string",
+                value: new TextDecoder("utf-8", {
+                    fatal: true,
+                    ignoreBOM: true,
+                }).decode(new Uint8Array(bytes)),
+            };
+    }
+    const root = result.ok ? shape.root : term.decoded.error_root;
+    const context = {
+        callbacks: term.callbacks,
+        propertyInput: term.direction === "test_input",
+    };
+    let decoded;
+    try {
+        decoded = yield* fromBridge(pkg, shape, root, result.value, context);
+    }
+    catch (error) {
+        if (!term.decoded)
+            throw error;
+        if (error instanceof DecodeFailure && result.error !== undefined) {
+            result = { ok: false, value: result.error };
+        }
+        else if (error instanceof Duplicate) {
+            result = JSON.parse(bridge(JSON.stringify({
+                ...request,
+                direction: "error",
+                input: [],
+                duplicate: error.detail,
+            })));
+        }
+        else {
+            throw error;
+        }
+        if (result.failure !== undefined)
+            throw new Error(result.failure);
+        decoded = yield* fromBridge(pkg, shape, term.decoded.error_root, result.value, context);
+    }
+    if (!term.decoded)
+        return decoded;
+    return {
+        kind: "enum",
+        typeId: pkg.variants[term.decoded.shape].name,
+        shape: term.decoded.shape,
+        tag: result.ok ? term.decoded.ok : term.decoded.error,
+        payload: [decoded],
+    };
+}