@hew-lang/sandbox-vm 0.6.1 → 0.6.3

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

@@ -1,31 +1,6 @@
 import { type VmValue } from "../values.js";
-interface Field {
-    name: string;
-    recipe: number;
-}
-export type StructuralRecipe = {
-    kind: "scalar" | "unit";
-} | {
-    kind: "display";
-    callee: number;
-} | {
-    kind: "identity";
-    name: string;
-} | {
-    kind: "tuple" | "vector" | "map";
-    members: number[];
-} | {
-    kind: "record";
-    name: string;
-    fields: Field[];
-} | {
-    kind: "enum";
-    cases: Array<{
-        name: string;
-        kind: "unit" | "tuple" | "struct";
-        fields: Field[];
-    }>;
-};
+import type { StructuralRecipe } from "./package.js";
+export type { StructuralRecipe } from "./package.js";
 /** A borrowed traversal. Display callbacks can suspend, so their callers retain
  * this stack and resume it with the returned string. No later sibling is read
  * after a callback fails. */
@@ -41,4 +16,3 @@ export declare class StructuralRenderer {
     };
     private sequence;
 }
-export {};

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

@@ -0,0 +1,7 @@
+import type { VmValue } from "../values.js";
+import type { PackageV1, TermV1 } from "./package.js";
+type TimestampBinary = Extract<TermV1, {
+    op: "timestamp.binary";
+}>;
+export declare function timestampBinary(pkg: PackageV1, term: TimestampBinary, lhs: VmValue, rhs: VmValue): VmValue | null;
+export {};

package/dist/interpreter/v1/timestamp.js

@@ -0,0 +1,54 @@
+const BILLION = 1000000000n;
+const MIN_I64 = -(1n << 63n);
+const MAX_I64 = (1n << 63n) - 1n;
+function exactNanos(pkg, value, timestamp) {
+    if (!timestamp) {
+        if (value.kind !== "i64" || value.value < MIN_I64 || value.value > MAX_I64)
+            throw new TypeError("timestamp offset is not a duration");
+        return value.value;
+    }
+    if (value.kind !== "record" ||
+        value.fields.length !== 2 ||
+        value.shape === undefined ||
+        pkg.aggregates[value.shape]?.builtin !== "Timestamp")
+        throw new TypeError("timestamp lacks its normalized pair");
+    const [seconds, nanos] = value.fields;
+    if (seconds?.kind !== "i64" ||
+        nanos?.kind !== "i64" ||
+        seconds.value < MIN_I64 ||
+        seconds.value > MAX_I64 ||
+        nanos.value < 0n ||
+        nanos.value >= BILLION)
+        throw new TypeError("invalid normalized timestamp");
+    return seconds.value * BILLION + nanos.value;
+}
+export function timestampBinary(pkg, term, lhs, rhs) {
+    const left = exactNanos(pkg, lhs, term.lhs_timestamp);
+    const right = exactNanos(pkg, rhs, term.rhs_timestamp);
+    const exact = term.binary_op === "Add" ? left + right : left - right;
+    if (term.shape === null) {
+        return exact < MIN_I64 || exact > MAX_I64
+            ? null
+            : { kind: "i64", value: exact };
+    }
+    if (exact < MIN_I64 * BILLION || exact > MAX_I64 * BILLION + BILLION - 1n)
+        return null;
+    let seconds = exact / BILLION;
+    let nanos = exact % BILLION;
+    if (nanos < 0n) {
+        seconds -= 1n;
+        nanos += BILLION;
+    }
+    const shape = pkg.aggregates[term.shape];
+    if (!shape)
+        throw new TypeError("timestamp result shape is absent");
+    return {
+        kind: "record",
+        typeId: shape.name,
+        shape: term.shape,
+        fields: [
+            { kind: "i64", value: seconds },
+            { kind: "i64", value: nanos },
+        ],
+    };
+}

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

@@ -1,3 +1,9 @@
 import type { SandboxRejection } from "../types.js";
-import type { PackageV1 } from "./package.js";
-export declare function admitPackage(pkg: PackageV1): SandboxRejection | null;
+import type { CheckedPackage } from "../schema-validator.js";
+import { type HostBridges } from "./shims.js";
+export declare class AdmittedPackage {
+    readonly bytecode: CheckedPackage;
+    private constructor();
+    static load(pkg: CheckedPackage, bridges: HostBridges): AdmittedPackage | SandboxRejection;
+}
+export declare function admitPackage(pkg: CheckedPackage, bridges?: HostBridges): SandboxRejection | null;

package/dist/interpreter/v1/validate.js

@@ -1,111 +1,17 @@
-/// Load-time admission for a verified SIR package.
-///
-/// The package declares what it needs: `runtime_families` names every runtime
-/// call family the instruction stream reaches, and `externs` names every
-/// declared C-ABI symbol. This validator matches each against the shim table
-/// the VM implements. A family or symbol with no shim is refused before a
-/// single instruction runs. Unknown is rejected, never allowed.
-///
-/// The check keys on the declared identity: it never matches a symbol prefix
-/// and never reads an instruction stream to guess a capability.
-import { SUPPORTED_NATIVE_IO, SUPPORTED_SUSPEND_KINDS, resolveExternShim, resolveRuntimeShim, } from "./shims.js";
+import { calendarResultFields } from "./calendar.js";
+import { CODEC_REGISTRATION, registrationRefusal, resolveExtern, resolveRuntime, resolveSuspension, suspensionRefusal, } from "./shims.js";
 const UNSUPPORTED = "sandbox.capability.unsupported";
-const NATIVE_FAMILIES = new Set(["AsyncIo", "FileRead", "Tcp"]);
-const NATIVE_SUSPENSIONS = new Set(["NativeIo", "RemoteAsk", "Read", "Accept"]);
-const OPS = new Set([
-    "coverage.hit",
-    "const.int",
-    "const.bool",
-    "const.float",
-    "const.char",
-    "const.unit",
-    "const.duration",
-    "const.str",
-    "const.bytes",
-    "copy_value",
-    "fork",
-    "move",
-    "destroy_value",
-    "begin_borrow",
-    "end_borrow",
-    "finish_linear_receiver",
-    "alloc_place",
-    "store.init",
-    "store.assign",
-    "load.copy",
-    "load.take",
-    "load.borrow",
-    "end_lifetime",
-    "tuple.make",
-    "tuple.get",
-    "aggregate.make",
-    "aggregate.project_copy",
-    "aggregate.project_borrow",
-    "destructure",
-    "array.make",
-    "array.repeat",
-    "variant.make",
-    "variant.is",
-    "variant.project_copy",
-    "variant.project_borrow",
-    "variant.destructure",
-    "unary",
-    "binary",
-    "cast",
-    "str.eq",
-    "bytes.eq",
-    "function.make",
-    "closure.make",
-    "generator.make",
-    "callable.coerce",
-    "dyn.make",
-    "register_defer",
-    "stream.pipe",
-    "task_scope.enter",
-    "task_scope.close",
-    "task.spawn",
-    "task.race",
-]);
-const TERMS = new Set([
-    "goto",
-    "branch",
-    "switch.variant",
-    "return",
-    "checked.binary",
-    "dyn.call",
-    "call",
-    "indirect.call",
-    "actor.call",
-    "runtime.call",
-    "extern.call",
-    "value.call",
-    "wire.codec",
-    "panic",
-    "checked_raise",
-    "trap",
-    "cleanup.dispatch",
-    "enter_defer",
-    "finish_defer",
-    "recover_fault",
-    "resume_unwind",
-    "suspend",
-    "unreachable",
-]);
-const ACTOR_OPS = new Set([
-    "spawn",
-    "self_handle",
-    "stop",
-    "terminate",
-    "await_stopped",
-    "await_restarted",
-    "call_start",
-    "call_take",
-    "submit",
-    "stream_start",
-    "supervisor_spawn",
-    "supervisor_child",
-    "supervisor_pool_view",
-]);
+/// The executor can only be constructed after structural/reference checks and
+/// the canonical host registration have both accepted the same package.
+export class AdmittedPackage {
+    bytecode;
+    constructor(bytecode) {
+        this.bytecode = bytecode;
+    }
+    static load(pkg, bridges) {
+        return admitPackage(pkg, bridges) ?? new AdmittedPackage(pkg);
+    }
+}
 function capabilityMessage(capability, native) {
     const nativeFeatures = {
         FileRead: "Filesystem access",
@@ -114,13 +20,11 @@ function capabilityMessage(capability, native) {
         NativeIo: "Host input and output",
         Read: "Host input and output",
         Accept: "Accepting network connections",
-        RemoteAsk: "Remote actor calls",
     };
     const features = {
         Vector: "This vector operation",
         Map: "This map operation",
         Set: "This set operation",
-        "actor.periodic": "Periodic actor handlers",
         "actor.local_observation": "Actor links and monitors",
         "actor.heap_limit": "Per-actor heap limits",
         "actor.ingress_adapter": "Actor ingress adapters",
@@ -139,8 +43,8 @@ function unavailable(capability) {
         span: null,
     };
 }
-/// The first refusal, or `null` when every declared capability has a shim.
-export function admitPackage(pkg) {
+/// The first refusal, or `null` when all operations and bridges are available.
+export function admitPackage(pkg, bridges = {}) {
     if (!pkg.entry) {
         return {
             category: "invalid_package",
@@ -150,6 +54,7 @@ export function admitPackage(pkg) {
             span: null,
         };
     }
+    const opaqueResources = new Set();
     for (const function_ of pkg.functions) {
         for (const block of function_.blocks) {
             if (block.ops.some((op) => op.op === "actor.ingress_adapter"))
@@ -168,120 +73,299 @@ export function admitPackage(pkg) {
                     span: null,
                 };
             if (block.term.op === "actor.call" &&
-                !ACTOR_OPS.has(block.term.operation.op))
+                block.term.operation.op === "local_observation")
                 return unavailable(`actor.${block.term.operation.op}`);
-            if (block.ops.some((op) => op.op === "coverage.hit" &&
-                (!Number.isSafeInteger(op.counter) ||
-                    op.counter < 0 ||
-                    op.counter > 0xffff_ffff))) {
-                return {
-                    category: "invalid_package",
-                    code: "sandbox.package.invalid_counter",
-                    capability: "coverage.hit",
-                    message: "coverage counter must be a u32",
-                    span: null,
-                };
+            const term = block.term;
+            if (term.op === "runtime.call" &&
+                pkg.runtime_families[term.family]?.family === "TimestampNow") {
+                const shape = term.aggregate_result_shape == null
+                    ? undefined
+                    : pkg.aggregates[term.aggregate_result_shape];
+                if (!shape ||
+                    shape.builtin !== "Timestamp" ||
+                    shape.fields.length !== 2) {
+                    return {
+                        category: "invalid_package",
+                        code: "sandbox.package.timestamp_shape",
+                        capability: "TimestampNow",
+                        message: "timestamp clock lacks its checked result shape",
+                        span: null,
+                    };
+                }
+            }
+            if (term.op === "extern.call") {
+                const symbol = pkg.externs[term.extern]?.symbol ?? "";
+                const fields = calendarResultFields(symbol);
+                if (fields) {
+                    const shape = term.aggregate_result_shape == null
+                        ? undefined
+                        : pkg.aggregates[term.aggregate_result_shape];
+                    if (!shape ||
+                        shape.fields.length !== fields.length ||
+                        shape.fields.some((field, index) => field !== fields[index])) {
+                        return {
+                            category: "invalid_package",
+                            code: "sandbox.package.calendar_shape",
+                            capability: symbol,
+                            message: "calendar operation lacks its checked result shape",
+                            span: null,
+                        };
+                    }
+                }
+            }
+            if (term.op === "timestamp.binary") {
+                const both = term.lhs_timestamp && term.rhs_timestamp;
+                const validOperation = (term.binary_op === "Add" &&
+                    term.lhs_timestamp !== term.rhs_timestamp) ||
+                    (term.binary_op === "Subtract" && term.lhs_timestamp);
+                const shape = term.shape === null ? undefined : pkg.aggregates[term.shape];
+                if (typeof term.lhs_timestamp !== "boolean" ||
+                    typeof term.rhs_timestamp !== "boolean" ||
+                    !validOperation ||
+                    (both
+                        ? term.shape !== null
+                        : !shape ||
+                            shape.fields.length !== 2 ||
+                            shape.builtin !== "Timestamp") ||
+                    term.failures.length !== 1 ||
+                    term.failures[0]?.trap !== "integer_overflow") {
+                    return {
+                        category: "invalid_package",
+                        code: "sandbox.package.timestamp_shape",
+                        capability: "timestamp.binary",
+                        message: "timestamp arithmetic lacks its checked operands, result shape or overflow edge",
+                        span: null,
+                    };
+                }
+            }
+            if (term.op === "runtime.call" &&
+                pkg.runtime_families[term.family]?.family === "BytesDecodeUtf8") {
+                const shapes = term.variant_result_shapes;
+                const error = shapes && pkg.aggregates[shapes.error];
+                const length = shapes && pkg.variants[shapes.error_len];
+                const result = term.result_shape === null
+                    ? undefined
+                    : pkg.variants[term.result_shape];
+                if (!error ||
+                    error.fields.length !== 2 ||
+                    !length ||
+                    !result ||
+                    length.runtime_tags?.OptionSome === undefined ||
+                    length.runtime_tags?.OptionNone === undefined ||
+                    result.runtime_tags?.ResultOk === undefined ||
+                    result.runtime_tags?.ResultErr === undefined)
+                    return {
+                        category: "invalid_package",
+                        code: "sandbox.package.variant_result_shapes",
+                        capability: null,
+                        message: "UTF-8 decode lacks its checked result carrier",
+                        span: null,
+                    };
+            }
+            if (term.op === "extern.call") {
+                const registration = resolveExtern(pkg.externs[term.extern]);
+                if (registration.kind === "directory" &&
+                    "release" in registration.operation) {
+                    const resource = term.result_resource == null
+                        ? undefined
+                        : pkg.resources?.[term.result_resource];
+                    if (resource?.kind !== "nominal" ||
+                        resource.release !== registration.operation.release ||
+                        term.result == null ||
+                        term.result === "never")
+                        return {
+                            category: "invalid_package",
+                            code: "sandbox.package.owner_result",
+                            capability: null,
+                            message: "filesystem acquisition lacks its compiler-selected owner release slot",
+                            span: null,
+                        };
+                }
+            }
+            if (term.op === "actor.call" && term.operation.op === "timer_schedule") {
+                const operation = term.operation;
+                const handler = pkg.actors
+                    ?.find((actor) => actor.id === operation.actor)
+                    ?.handlers.find((handler) => handler.message_id === operation.message);
+                const resource = pkg.resources?.[operation.resource];
+                if (!handler ||
+                    handler.streams ||
+                    term.args.length !== 5 ||
+                    !["reject", "drop_newest"].includes(operation.policy) ||
+                    resource?.kind !== "opaque" ||
+                    resource.close === undefined ||
+                    !pkg.functions.some((fn) => fn.id === resource.close))
+                    return {
+                        category: "invalid_package",
+                        code: "sandbox.package.invalid_timer",
+                        capability: "actor.timer_schedule",
+                        message: "timer schedule lacks its checked handler, timing or non-waiting admission",
+                        span: null,
+                    };
+                opaqueResources.add(operation.resource);
+            }
+            if (term.op === "actor.call" &&
+                term.operation.op === "supervisor_spawn") {
+                const id = term.operation.supervisor;
+                const supervisor = pkg.supervisors?.find((layout) => layout.id === id);
+                const config = term.args.length -
+                    (supervisor?.children.some((child) => child.is_pool) ? 1 : 0);
+                if (!supervisor ||
+                    config < 0 ||
+                    supervisor.children.some((child) => {
+                        const params = pkg.functions.find((fn) => fn.id === child.spawn)?.params;
+                        return !params || ![config, config + 1].includes(params.length);
+                    }))
+                    return {
+                        category: "invalid_package",
+                        code: "sandbox.package.supervisor_constructor",
+                        capability: null,
+                        message: "supervisor constructor signature does not match its config",
+                        span: null,
+                    };
+            }
+            if (term.op === "wire.codec") {
+                const refusal = registrationRefusal(CODEC_REGISTRATION, bridges);
+                if (refusal)
+                    return rejectRegistration(refusal);
+            }
+            if (term.op === "suspend") {
+                const registration = resolveSuspension(term);
+                if (registration.kind === "refused")
+                    return rejectRegistration(registration);
+                const mandatoryClose = (pkg.resources ?? []).some((resource) => "close" in resource && resource.close === function_.id);
+                if (term.kind === "Safepoint"
+                    ? (term.cancel == null) !== mandatoryClose
+                    : term.cancel == null)
+                    return {
+                        category: "invalid_package",
+                        code: "sandbox.package.cancellation_ancestry",
+                        capability: null,
+                        message: "safepoint cancellation ancestry must match its authored close lifecycle",
+                        span: null,
+                    };
             }
-            const unknown = block.ops.find((op) => !OPS.has(op.op))?.op ??
-                (!TERMS.has(block.term.op) ? block.term.op : null);
-            if (unknown)
-                return {
-                    category: "invalid_package",
-                    code: "sandbox.package.unknown_opcode",
-                    capability: unknown,
-                    message: `unknown bytecode opcode ${unknown}`,
-                    span: null,
-                };
         }
     }
-    for (const resource of pkg.resources ?? []) {
-        if (resource.kind === "record" &&
-            (resource.shape === undefined ||
-                !pkg.aggregates.some((shape) => shape.id === resource.shape)))
-            return {
-                category: "invalid_package",
-                code: "sandbox.package.resource_shape_missing",
-                capability: null,
-                message: "record resource has no exact aggregate shape",
-                span: null,
-            };
-        if (resource.kind === "opaque")
+    for (const [index, resource] of (pkg.resources ?? []).entries()) {
+        if (resource.kind === "opaque" && !opaqueResources.has(index))
             return unavailable("resource.opaque_close");
         if (resource.kind === "nominal" &&
-            !resolveExternShim(resource.release ?? ""))
+            registrationRefusal(resolveExtern({ symbol: resource.release ?? "" }), bridges))
             return unavailable("resource.external_close");
     }
     for (const actor of pkg.actors ?? []) {
-        if (actor.handlers.some((handler) => handler.every_ns != null))
-            return unavailable("actor.periodic");
+        if (typeof actor.name !== "string" || actor.name.length === 0)
+            return {
+                category: "invalid_package",
+                code: "sandbox.package.actor_name",
+                capability: null,
+                message: "actor lacks its declared diagnostic name",
+                span: null,
+            };
+        if (actor.crash != null &&
+            (actor.crash_info == null ||
+                !pkg.aggregates[actor.crash_info] ||
+                actor.crash_kind == null ||
+                !pkg.variants[actor.crash_kind] ||
+                actor.crash_action == null ||
+                !pkg.variants[actor.crash_action]))
+            return {
+                category: "invalid_package",
+                code: "sandbox.package.crash_hook_shapes",
+                capability: null,
+                message: "crash hook lacks its exact info, kind or action shape",
+                span: null,
+            };
+        if (actor.handlers.some((handler) => handler.every_ns != null &&
+            (!Number.isInteger(handler.every_ns) ||
+                handler.every_ns < 1_000_000 ||
+                handler.params !== 0 ||
+                handler.streams ||
+                handler.fallible ||
+                !pkg.functions.some((fn) => fn.id === handler.callable && fn.params.length === 1))))
+            return {
+                category: "invalid_package",
+                code: "sandbox.package.invalid_periodic",
+                capability: "actor.periodic",
+                message: "periodic handler lacks its checked interval or zero-argument body",
+                span: null,
+            };
         if (actor.exit != null || actor.down != null)
             return unavailable("actor.local_observation");
         if (actor.max_heap_bytes != null)
             return unavailable("actor.heap_limit");
     }
-    for (const entry of pkg.runtime_families) {
-        if (!resolveRuntimeShim(entry)) {
+    for (const supervisor of pkg.supervisors ?? []) {
+        const order = supervisor.startup_order === undefined
+            ? supervisor.children.map((_child, index) => index)
+            : supervisor.startup_order;
+        if (!Array.isArray(order) ||
+            supervisor.children.some((child) => child.dependencies !== undefined &&
+                (!Array.isArray(child.dependencies) ||
+                    new Set(child.dependencies).size !== child.dependencies.length)))
             return {
-                category: NATIVE_FAMILIES.has(entry.family)
-                    ? "native_only"
-                    : "not_implemented",
-                code: UNSUPPORTED,
-                capability: familyIdentity(entry.family, entry.detail),
-                message: capabilityMessage(entry.family, NATIVE_FAMILIES.has(entry.family)),
+                category: "invalid_package",
+                code: "sandbox.package.supervisor_startup_order",
+                capability: null,
+                message: "supervisor startup order and dependencies must be arrays of unique children",
                 span: null,
             };
-        }
-    }
-    for (const entry of pkg.externs) {
-        if (!resolveExternShim(entry.symbol)) {
-            const native = entry.native_capability;
+        const ranks = new Map(order.map((child, rank) => [child, rank]));
+        if (order.length !== supervisor.children.length ||
+            ranks.size !== order.length ||
+            order.some((child) => !Number.isInteger(child) ||
+                child < 0 ||
+                child >= supervisor.children.length) ||
+            supervisor.children.some((child, index) => (child.dependencies ?? []).some((dependency) => !Number.isInteger(dependency) ||
+                dependency < 0 ||
+                !ranks.has(dependency) ||
+                ranks.get(dependency) >= ranks.get(index))))
             return {
-                category: native === undefined ? "not_implemented" : "native_only",
-                code: UNSUPPORTED,
-                capability: entry.symbol,
-                message: native === undefined
-                    ? "This external-library operation is not available in the browser runtime yet."
-                    : `${native} require native execution.`,
+                category: "invalid_package",
+                code: "sandbox.package.supervisor_startup_order",
+                capability: null,
+                message: "supervisor startup order must precede each declared dependency",
                 span: null,
             };
-        }
-    }
-    for (const kind of pkg.suspend_kinds) {
-        const refused = kind === "NativeIo"
-            ? refusedNativeIo(pkg)
-            : SUPPORTED_SUSPEND_KINDS.has(kind)
-                ? null
-                : kind;
-        if (refused !== null) {
+        if (supervisor.children.some((child) => !pkg.functions.some((fn) => fn.id === child.spawn)))
             return {
-                category: NATIVE_SUSPENSIONS.has(kind)
-                    ? "native_only"
-                    : "not_implemented",
-                code: UNSUPPORTED,
-                capability: refused,
-                message: capabilityMessage(kind, NATIVE_SUSPENSIONS.has(kind)),
+                category: "invalid_package",
+                code: "sandbox.package.supervisor_constructor",
+                capability: null,
+                message: "supervisor child has no constructor callable",
                 span: null,
             };
-        }
     }
-    return null;
-}
-/// The first native I/O suspension whose operation the VM does not serve.
-function refusedNativeIo(pkg) {
-    for (const function_ of pkg.functions) {
-        for (const block of function_.blocks) {
-            const term = block.term;
-            if (term.op !== "suspend" || term.kind !== "NativeIo")
-                continue;
-            const operation = String(term.detail?.operation);
-            if (!SUPPORTED_NATIVE_IO.has(operation))
-                return `NativeIo::${operation}`;
-        }
+    for (const entry of pkg.runtime_families) {
+        const refusal = registrationRefusal(resolveRuntime(entry), bridges);
+        if (refusal)
+            return rejectRegistration(refusal);
+    }
+    for (const entry of pkg.externs) {
+        const refusal = registrationRefusal(resolveExtern(entry), bridges);
+        if (refusal)
+            return rejectRegistration(refusal);
+    }
+    for (const kind of pkg.suspend_kinds) {
+        const refusal = suspensionRefusal(kind);
+        if (refusal)
+            return rejectRegistration(refusal);
     }
     return null;
 }
-function familyIdentity(family, detail) {
-    return typeof detail === "string" && detail.length > 0
-        ? `${family}::${detail}`
-        : family;
+function rejectRegistration(refusal) {
+    return {
+        category: refusal.category,
+        code: UNSUPPORTED,
+        capability: refusal.capability,
+        message: refusal.message ??
+            (refusal.capability === "codecBridge" ||
+                refusal.capability === "calendarBridge"
+                ? `This operation requires the ${refusal.capability === "codecBridge" ? "codec" : "calendar"} Wasm bridge.`
+                : refusal.description !== undefined
+                    ? `${refusal.description} require native execution.`
+                    : capabilityMessage(refusal.capability.split("::")[0], refusal.category === "native_only")),
+        span: null,
+    };
 }