@hew-lang/sandbox-vm 0.6.1 → 0.6.3

package/dist/interpreter/unicode.d.ts

@@ -0,0 +1,3 @@
+/** The native Unicode operations, independent of the JavaScript host's version. */
+export declare function charProperty(value: string, bit: number): boolean;
+export declare function charCase(value: string, kind: "upper" | "lower" | "title"): string;

package/dist/interpreter/unicode.js

@@ -0,0 +1,35 @@
+import { CATEGORY_RANGES, UPPER_MAPPING, LOWER_MAPPING, TITLE_MAPPING, } from "./unicode-data.js";
+/** The native Unicode operations, independent of the JavaScript host's version. */
+export function charProperty(value, bit) {
+    const scalar = value.codePointAt(0);
+    let low = 0, high = CATEGORY_RANGES.length / 3;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (CATEGORY_RANGES[middle * 3 + 1] < scalar)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return (low * 3 < CATEGORY_RANGES.length &&
+        CATEGORY_RANGES[low * 3] <= scalar &&
+        (CATEGORY_RANGES[low * 3 + 2] & (1 << bit)) !== 0);
+}
+export function charCase(value, kind) {
+    const table = kind === "upper"
+        ? UPPER_MAPPING
+        : kind === "lower"
+            ? LOWER_MAPPING
+            : TITLE_MAPPING;
+    const scalar = value.codePointAt(0);
+    let low = 0, high = table.length / 2;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (table[middle * 2] < scalar)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return table[low * 2] === scalar
+        ? String.fromCodePoint(table[low * 2 + 1])
+        : value;
+}

package/dist/interpreter/v1/actor-identity.d.ts

@@ -0,0 +1,3 @@
+import type { VmValue } from "../values.js";
+/** Role handles retain their own identity independently of their occupant. */
+export declare function actorIdentical(left: VmValue | undefined, right: VmValue | undefined): boolean;

package/dist/interpreter/v1/actor-identity.js

@@ -0,0 +1,7 @@
+/** Role handles retain their own identity independently of their occupant. */
+export function actorIdentical(left, right) {
+    if ((left?.kind !== "actor" && left?.kind !== "supervisor") ||
+        (right?.kind !== "actor" && right?.kind !== "supervisor"))
+        throw new Error("actor identity requires actor or supervisor handles");
+    return left.kind === right.kind && left.id === right.id;
+}

package/dist/interpreter/v1/actor-waits.d.ts

@@ -0,0 +1,6 @@
+/** Pending strict actor turns. Keys identify incarnations, never role handles. */
+export declare class ActorWaits<T> {
+    private readonly edges;
+    ready(owner: T): void;
+    pending(owner: T, targets: readonly T[]): T[] | null;
+}

package/dist/interpreter/v1/actor-waits.js

@@ -0,0 +1,33 @@
+/** Pending strict actor turns. Keys identify incarnations, never role handles. */
+export class ActorWaits {
+    edges = new Map();
+    ready(owner) {
+        this.edges.delete(owner);
+    }
+    pending(owner, targets) {
+        this.edges.set(owner, targets);
+        const blocked = new Set([...this.edges]
+            .filter(([, targets]) => targets.length > 0)
+            .map(([owner]) => owner));
+        for (;;) {
+            const escaped = [...blocked].filter((actor) => this.edges.get(actor).some((target) => !blocked.has(target)));
+            if (escaped.length === 0)
+                break;
+            for (const actor of escaped)
+                blocked.delete(actor);
+        }
+        if (!blocked.has(owner))
+            return null;
+        const path = [];
+        const seen = new Set();
+        let next = owner;
+        while (!seen.has(next)) {
+            seen.add(next);
+            path.push(next);
+            next = this.edges.get(next)[0];
+        }
+        path.push(next);
+        this.ready(owner);
+        return path;
+    }
+}

package/dist/interpreter/v1/browser-directory.d.ts

@@ -0,0 +1,107 @@
+import { type VmValue } from "../values.js";
+/** Authority comes only from the embedding host, never from a path or cwd. */
+export interface DirectoryRoots {
+    read?: FileSystemDirectoryHandle;
+    write?: FileSystemDirectoryHandle;
+}
+export type BrowserFileOwner = {
+    access: "read" | "write";
+    handle: FileSystemFileHandle | null;
+    cursor: number;
+    closed: boolean;
+    tail: Promise<void>;
+};
+export type BrowserDirectoryOwner = {
+    access: "read" | "write";
+    handle: FileSystemDirectoryHandle | null;
+    closed: boolean;
+};
+export type BrowserFsOwner = BrowserFileOwner | BrowserDirectoryOwner;
+export interface BrowserIoError {
+    kind: number;
+    message: string;
+}
+export interface BrowserIoResult {
+    value: VmValue;
+    error: BrowserIoError | null;
+}
+export declare const DIRECTORY_OPERATIONS: {
+    readonly hew_dir_open_read: {
+        readonly release: "hew_dir_read_close";
+        readonly action: "root";
+        readonly access: "read";
+    };
+    readonly hew_dir_open_write: {
+        readonly release: "hew_dir_write_close";
+        readonly action: "root";
+        readonly access: "write";
+    };
+    readonly hew_dir_read_subdir: {
+        readonly release: "hew_dir_read_close";
+        readonly action: "subdir";
+        readonly access: "read";
+    };
+    readonly hew_dir_write_subdir: {
+        readonly release: "hew_dir_write_close";
+        readonly action: "subdir";
+        readonly access: "write";
+    };
+    readonly hew_dir_read_open_file: {
+        readonly release: "hew_file_read_close";
+        readonly action: "file";
+        readonly access: "read";
+    };
+    readonly hew_dir_write_open_file: {
+        readonly release: "hew_file_write_close";
+        readonly action: "file";
+        readonly access: "write";
+    };
+    readonly hew_dir_read_is_valid: {
+        readonly action: "valid";
+        readonly access: "read";
+    };
+    readonly hew_dir_write_is_valid: {
+        readonly action: "valid";
+        readonly access: "write";
+    };
+    readonly hew_file_read_is_valid: {
+        readonly action: "valid";
+        readonly access: "read";
+    };
+    readonly hew_file_write_is_valid: {
+        readonly action: "valid";
+        readonly access: "write";
+    };
+    readonly hew_dir_read_close: {
+        readonly action: "close";
+        readonly access: "read";
+    };
+    readonly hew_dir_write_close: {
+        readonly action: "close";
+        readonly access: "write";
+    };
+    readonly hew_file_read_close: {
+        readonly action: "close";
+        readonly access: "read";
+    };
+    readonly hew_file_write_close: {
+        readonly action: "close";
+        readonly access: "write";
+    };
+};
+export type DirectoryOperation = (typeof DIRECTORY_OPERATIONS)[keyof typeof DIRECTORY_OPERATIONS];
+export declare class BrowserDirectories {
+    private readonly roots;
+    private readonly owners;
+    retire(release: (value: Extract<VmValue, {
+        kind: "host_resource";
+    }>) => void): void;
+    /** OPFS has no symlink entries. Picker-backed filesystem link confinement is
+     * not standardized, so this adapter refuses those handles before execution. */
+    static admission(roots: DirectoryRoots | undefined): Promise<string | null>;
+    constructor(roots?: DirectoryRoots);
+    call(operation: DirectoryOperation, args: VmValue[], resource?: number | null): VmValue | Promise<BrowserIoResult>;
+    private acquire;
+    private owned;
+    io(operation: "FileRead" | "FileWrite", args: VmValue[], cancelled: () => boolean): Promise<BrowserIoResult>;
+}

package/dist/interpreter/v1/browser-directory.js

@@ -0,0 +1,288 @@
+import { UNIT } from "../values.js";
+export const DIRECTORY_OPERATIONS = {
+    hew_dir_open_read: {
+        release: "hew_dir_read_close",
+        action: "root",
+        access: "read",
+    },
+    hew_dir_open_write: {
+        release: "hew_dir_write_close",
+        action: "root",
+        access: "write",
+    },
+    hew_dir_read_subdir: {
+        release: "hew_dir_read_close",
+        action: "subdir",
+        access: "read",
+    },
+    hew_dir_write_subdir: {
+        release: "hew_dir_write_close",
+        action: "subdir",
+        access: "write",
+    },
+    hew_dir_read_open_file: {
+        release: "hew_file_read_close",
+        action: "file",
+        access: "read",
+    },
+    hew_dir_write_open_file: {
+        release: "hew_file_write_close",
+        action: "file",
+        access: "write",
+    },
+    hew_dir_read_is_valid: { action: "valid", access: "read" },
+    hew_dir_write_is_valid: { action: "valid", access: "write" },
+    hew_file_read_is_valid: { action: "valid", access: "read" },
+    hew_file_write_is_valid: { action: "valid", access: "write" },
+    hew_dir_read_close: { action: "close", access: "read" },
+    hew_dir_write_close: { action: "close", access: "write" },
+    hew_file_read_close: { action: "close", access: "read" },
+    hew_file_write_close: { action: "close", access: "write" },
+};
+function errorOf(error) {
+    const name = error instanceof DOMException ? error.name : "";
+    return {
+        kind: name === "NotFoundError"
+            ? 1
+            : name === "NotAllowedError" || name === "SecurityError"
+                ? 2
+                : 0,
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+function pathOf(value) {
+    if (value?.kind !== "string")
+        throw new Error("directory operation requires a string path");
+    const path = value.value;
+    if (!path ||
+        path.startsWith("/") ||
+        path.includes("\\") ||
+        path.includes("\0") ||
+        /^[A-Za-z]:/.test(path))
+        throw new DOMException("path must stay beneath the supplied directory", "NotAllowedError");
+    return path;
+}
+function ownerOf(value, access) {
+    if (value?.kind !== "host_resource" ||
+        value.owner.closed ||
+        !value.owner.handle ||
+        value.owner.access !== access)
+        throw new Error("closed or incompatible filesystem owner");
+    return value.owner;
+}
+/** Resolve actual entries in order. A child starts a new confinement boundary;
+ * parent components never recover the parent's authority. FSA exposes no symlink
+ * traversal primitive: each lookup stays beneath its concrete directory handle. */
+async function directory(root, parts) {
+    const stack = [root];
+    for (const part of parts) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..") {
+            if (stack.length === 1)
+                throw new DOMException("path escapes its directory owner", "NotAllowedError");
+            stack.pop();
+        }
+        else
+            stack.push(await stack[stack.length - 1].getDirectoryHandle(part));
+    }
+    return stack[stack.length - 1];
+}
+export class BrowserDirectories {
+    roots;
+    // The adapter retains its physical owner slots until selected release. This
+    // also covers acquisition completed after a terminal VM failure, when its
+    // source continuation must never run.
+    owners = new Set();
+    retire(release) {
+        for (const value of this.owners)
+            release(value);
+    }
+    /** OPFS has no symlink entries. Picker-backed filesystem link confinement is
+     * not standardized, so this adapter refuses those handles before execution. */
+    static async admission(roots) {
+        const supplied = [roots?.read, roots?.write].filter((root) => root !== undefined);
+        if (supplied.length === 0)
+            return null;
+        if (typeof navigator === "undefined" || !navigator.storage?.getDirectory)
+            return "This host does not provide the browser origin-private filesystem.";
+        try {
+            const canonical = await navigator.storage.getDirectory();
+            for (const root of supplied)
+                if (root.kind !== "directory" ||
+                    (await canonical.resolve(root)) === null)
+                    return "Only supplied origin-private directory handles are supported; external picker directory confinement is unavailable.";
+            return null;
+        }
+        catch (error) {
+            return `Cannot validate supplied directory authority: ${errorOf(error).message}`;
+        }
+    }
+    constructor(roots = {}) {
+        this.roots = roots;
+    }
+    call(operation, args, resource) {
+        if (operation.action === "valid") {
+            const value = args[0];
+            return {
+                kind: "bool",
+                value: value?.kind === "host_resource" &&
+                    !value.owner.closed &&
+                    value.owner.handle !== null &&
+                    value.owner.access === operation.access,
+            };
+        }
+        if (operation.action === "close") {
+            const value = args[0];
+            if (value?.kind !== "host_resource")
+                throw new Error("close requires a filesystem owner");
+            value.owner.closed = true;
+            value.owner.handle = null;
+            this.owners.delete(value);
+            return UNIT;
+        }
+        if (resource == null)
+            throw new Error("filesystem acquisition has no compiler-selected owner slot");
+        return this.acquire(operation, args, resource);
+    }
+    async acquire(operation, args, resource) {
+        let owner = operation.action === "file"
+            ? {
+                access: operation.access,
+                handle: null,
+                cursor: 0,
+                closed: false,
+                tail: Promise.resolve(),
+            }
+            : { access: operation.access, handle: null, closed: false };
+        try {
+            const path = pathOf(args[operation.action === "root" ? 0 : 1]);
+            const parent = operation.action === "root"
+                ? this.roots[operation.access]
+                : ownerOf(args[0], operation.access).handle;
+            if (!parent || parent.kind !== "directory")
+                throw new DOMException("no supplied directory authority", "NotAllowedError");
+            const parts = path.split("/");
+            if (operation.action === "file") {
+                const name = parts.pop();
+                if (!name || name === "." || name === "..")
+                    throw new Error("file path must name a regular file");
+                const target = await directory(parent, parts);
+                const file = await target.getFileHandle(name, {
+                    create: operation.access === "write",
+                });
+                if (operation.access === "write") {
+                    // Native open_write truncates before publishing the owner. FSA only
+                    // publishes writes on close, so close this truncation before resuming.
+                    const writer = await file.createWritable();
+                    try {
+                        await writer.close();
+                    }
+                    catch (error) {
+                        await writer.abort().catch(() => { });
+                        throw error;
+                    }
+                }
+                owner = {
+                    access: operation.access,
+                    handle: file,
+                    cursor: 0,
+                    closed: false,
+                    tail: Promise.resolve(),
+                };
+            }
+            else
+                owner.handle = await directory(parent, parts);
+            return this.owned(resource, owner, null);
+        }
+        catch (error) {
+            return this.owned(resource, owner, errorOf(error));
+        }
+    }
+    owned(resource, owner, error) {
+        const value = {
+            kind: "host_resource",
+            resource,
+            owner,
+        };
+        this.owners.add(value);
+        return { value, error };
+    }
+    io(operation, args, cancelled) {
+        const fallback = operation === "FileRead"
+            ? { kind: "vector", elementType: "u8", items: [] }
+            : { kind: "i64", value: -1n };
+        let owner;
+        try {
+            const selected = ownerOf(args[0], operation === "FileRead" ? "read" : "write");
+            if (!("cursor" in selected))
+                throw new Error("file operation requires a file owner");
+            owner = selected;
+        }
+        catch (error) {
+            return Promise.resolve({ value: fallback, error: errorOf(error) });
+        }
+        const result = owner.tail.then(async () => {
+            try {
+                if (cancelled())
+                    return { value: fallback, error: null };
+                const handle = owner.handle;
+                if (!handle || owner.closed)
+                    throw new Error("closed file owner");
+                if (operation === "FileRead") {
+                    const file = await handle.getFile();
+                    if (cancelled())
+                        return { value: fallback, error: null };
+                    const bytes = new Uint8Array(await file.slice(owner.cursor).arrayBuffer());
+                    owner.cursor += bytes.length;
+                    return {
+                        value: {
+                            kind: "vector",
+                            elementType: "u8",
+                            items: Array.from(bytes, (value) => ({
+                                kind: "i64",
+                                value: BigInt(value),
+                            })),
+                        },
+                        error: null,
+                    };
+                }
+                const data = args[1];
+                if (data?.kind !== "vector")
+                    throw new Error("file write requires bytes");
+                const bytes = Uint8Array.from(data.items, (value) => {
+                    if (value.kind !== "i64")
+                        throw new Error("file write requires byte elements");
+                    return Number(value.value);
+                });
+                const writer = await handle.createWritable({ keepExistingData: true });
+                try {
+                    if (cancelled()) {
+                        await writer.abort();
+                        return { value: fallback, error: null };
+                    }
+                    await writer.seek(owner.cursor);
+                    await writer.write(bytes);
+                    if (cancelled()) {
+                        await writer.abort();
+                        return { value: fallback, error: null };
+                    }
+                    await writer.close();
+                }
+                catch (error) {
+                    await writer.abort().catch(() => { });
+                    throw error;
+                }
+                owner.cursor += bytes.length;
+                return { value: { kind: "i64", value: 0n }, error: null };
+            }
+            catch (error) {
+                return { value: fallback, error: errorOf(error) };
+            }
+        });
+        // Independent files progress independently; each cursor serializes its own
+        // borrowed operations as the native file owner's lock does.
+        owner.tail = result.then(() => { });
+        return result;
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type VmValue } from "../values.js";
+import type { AggregateShape } from "./package.js";
+export declare function calendarResultFields(symbol: string): readonly string[] | undefined;
+export declare function executeCalendar(bridge: ((request: string) => string) | undefined, symbol: string, args: VmValue[], shape: AggregateShape | null): VmValue;

package/dist/interpreter/v1/calendar.js

@@ -0,0 +1,64 @@
+import { stringValue } from "../values.js";
+const TIME_FIELDS = ["status", "seconds", "nanoseconds", "message"];
+const CALENDAR_FIELDS = {
+    hew_calendar_format: ["status", "text", "message"],
+    hew_calendar_parse: TIME_FIELDS,
+    hew_calendar_from_parts: TIME_FIELDS,
+    hew_calendar_components: [
+        "status",
+        "year",
+        "month",
+        "day",
+        "hour",
+        "minute",
+        "second",
+        "nanosecond",
+        "weekday",
+        "days_in_month",
+        "message",
+    ],
+};
+export function calendarResultFields(symbol) {
+    return CALENDAR_FIELDS[symbol];
+}
+export function executeCalendar(bridge, symbol, args, shape) {
+    if (!bridge)
+        throw new Error("calendar operations require the hew-wasm executeCalendar bridge");
+    const fields = calendarResultFields(symbol);
+    if (!shape ||
+        !fields ||
+        shape.fields.length !== fields.length ||
+        shape.fields.some((field, index) => field !== fields[index]))
+        throw new Error("calendar operation lacks its checked result shape");
+    const request = {
+        operation: symbol.slice("hew_calendar_".length),
+        args: args.map((value) => {
+            if (value.kind === "i64")
+                return value.value.toString();
+            if (value.kind === "string")
+                return value.value;
+            throw new Error("invalid calendar argument");
+        }),
+    };
+    const result = JSON.parse(bridge(JSON.stringify(request)));
+    if (typeof result.status !== "number" ||
+        ![0, 1, 2, 3].includes(result.status) ||
+        typeof result.message !== "string")
+        throw new Error("calendar bridge returned an invalid result");
+    return {
+        kind: "record",
+        typeId: shape.name,
+        shape: shape.id,
+        fields: shape.fields.map((field) => {
+            const value = result[field];
+            if (result.status === 0 && value === undefined)
+                throw new Error("calendar bridge omitted a successful result field");
+            if (field === "message" || field === "text")
+                return stringValue(value === undefined ? "" : String(value));
+            return {
+                kind: "i64",
+                value: BigInt(value === undefined ? 0 : String(value)),
+            };
+        }),
+    };
+}

package/dist/interpreter/v1/codecs.js

@@ -1,4 +1,4 @@
-import { UNIT } from "../values.js";
+import { UNIT, stringValue } from "../values.js";
 import { runtimeTag } from "./package.js";
 import { collectionOperation } from "./value-operations.js";
 class DecodeFailure extends Error {
@@ -102,7 +102,7 @@ function* fromBridge(pkg, shape, id, value, context) {
     if (node === "Bool")
         return { kind: "bool", value: Boolean(value) };
     if (node === "Char" || node === "String")
-        return { kind: "string", value: String(value) };
+        return stringValue(String(value));
     if (node === "Bytes")
         return {
             kind: "vector",
@@ -148,7 +148,7 @@ function* fromBridge(pkg, shape, id, value, context) {
     }
     if ("Map" in node || "Set" in node) {
         const family = "Map" in node ? "Map" : "Set";
-        const map = yield* collectionOperation(pkg, family, "New", [], [], null);
+        const map = yield* collectionOperation(pkg, { handler: "collection", family, operation: "New" }, [], [], null);
         for (const item of array(value)) {
             const itemFields = array(item);
             const pair = "Map" in node ? itemFields : [itemFields[0], null];
@@ -159,7 +159,7 @@ function* fromBridge(pkg, shape, id, value, context) {
             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);
+            yield* collectionOperation(pkg, { handler: "collection", family, operation: "Insert" }, [map, key, member], context.callbacks[id] ?? [], null);
             if (!context.propertyInput && map.entries.size === size)
                 throw new Duplicate(itemFields["Map" in node ? 2 : 1]);
         }
@@ -216,13 +216,10 @@ export function* executeCodec(pkg, term, input, bridge, propertyInput) {
                 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)),
-            };
+            : stringValue(new TextDecoder("utf-8", {
+                fatal: true,
+                ignoreBOM: true,
+            }).decode(new Uint8Array(bytes)));
     }
     const root = result.ok ? shape.root : term.decoded.error_root;
     const context = {

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

@@ -1,3 +1,3 @@
 import type { RunOptions, SandboxTrace } from "../types.js";
-import type { PackageV1 } from "./package.js";
-export declare function runPackageV1(pkg: PackageV1, options?: RunOptions): SandboxTrace;
+import type { CheckedPackage } from "../schema-validator.js";
+export declare function runPackageV1(pkg: CheckedPackage, options?: RunOptions): Promise<SandboxTrace>;