@hew-lang/sandbox-vm 0.6.2 → 0.6.3

package/README.md

@@ -5,8 +5,9 @@
 borrows, cleanup, checked failures, actor protocols and suspension edges.
 
 Actors, tasks and pipes use resumable frames on a deterministic scheduler.
-Timers advance virtual time. Native filesystem and network operations are
-refused before execution; other missing operations are reported separately as
+Timers advance virtual time. Hosts can supply real origin-private filesystem
+(OPFS) directory handles; network and ambient filesystem operations are refused
+before execution. Other missing operations are reported separately as
 `not_implemented`. The loader is the capability admission authority.
 
 ## Browser API
@@ -17,16 +18,43 @@ import { runBytecode } from "@hew-lang/sandbox-vm";
 
 const { diagnostics, bytecode } = JSON.parse(compileToSandboxBytecode(source));
 if (bytecode) {
-  const trace = runBytecode(bytecode, { replay: { step_budget: 100000 } });
+  const trace = await runBytecode(bytecode, {
+    replay: { step_budget: 100000 },
+  });
 }
 ```
 
 Initialize the Wasm compiler using its generated default export before calling
 it. `runProgram(source, stdin)` is also available for existing page bridges;
-install `globalThis.compileToSandboxBytecode` first. Its result includes
+install `globalThis.compileToSandboxBytecode` first. Both entrypoints return a Promise. The page result includes
 `stdout`, `exit_code`, `diagnostics`, `status`, `sandbox_rejections`,
 `compiler_version` and `hew_version`.
 
+To grant filesystem authority, pass only the directories the program needs:
+
+```js
+const trace = await runBytecode(bytecode, {
+  directoryRoots: { read: inputDirectory, write: outputDirectory },
+  signal: controller.signal,
+});
+```
+
+Both roots are optional and default to no authority. The handles must belong to
+this origin's OPFS; external picker-backed handles are refused because their
+symlink confinement is not standardized. Existing Hew `fs.open_read_dir(".")`
+and `fs.open_write_dir(".")` acquire the supplied roots. Relative traversal stays
+beneath the current directory owner, including after narrowing with `subdir`.
+Children remain usable after closing a parent. Each `file.write` publishes its
+bytes before it returns, even while the file owner remains open.
+
+`AbortSignal` requests cancellation through the source's authored cleanup edges.
+Filesystem acquisition publishes its owner before observing cancellation, as on
+native hosts. An in-progress file operation drains or aborts its browser writer
+before cancellation releases its inputs. Pure execution retains the deterministic
+virtual scheduler and runs until a host wait or completion. Pass the same options
+as the fourth argument to `runProgram(source, stdin, files, options)`; signals are
+for direct calls rather than worker message payloads.
+
 A `sandbox_rejected` result includes rejection entries with `category`, `code`,
 `capability`, `message` and `span`. Categories are `native_only`,
 `not_implemented` and `invalid_package`. Compiler errors, language panics,
@@ -48,6 +76,13 @@ 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.
 
+With `hew-wasm/pkg` and `hew-sandbox-vm/dist` built, serve the repository on
+localhost and open `hew-sandbox-vm/test/browser/directory-handles.html` to run the
+real browser filesystem controls. They compile the ordinary Hew source fixture,
+use a temporary OPFS directory, verify disk contents, confinement and cancellation,
+then remove their entries. The page accepts a `compiler` module URL query parameter
+to reuse another built compiler package.
+
 `RunOptions.argv` supplies process arguments, including the executable name at
 index zero. It defaults to `["main.hew"]` and is copied for each run. For example,
 `runBytecode(bytecode, { argv: ["greet", "--", "Zoë", ""] })` supplies those exact
@@ -58,3 +93,7 @@ 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.
+
+UTC calendar operations also require the initialized `executeCalendar`
+export as `calendarBridge`. Both hosts use the shared Chrono calendar engine;
+the bridge preserves integer seconds and nanoseconds exactly.

package/cli/test-runner.mjs

@@ -22,6 +22,7 @@ try {
   const args = parseArgs(process.argv.slice(2));
   const packageValue = JSON.parse(fs.readFileSync(args.path, "utf8"));
   let codecBridge;
+  let calendarBridge;
   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");
@@ -31,11 +32,13 @@ try {
       await wasm.default({ module_or_path: fs.readFileSync(new URL(resolved.replace(/\.js$/, "_bg.wasm"))) });
     }
     codecBridge = wasm.executeCodec ?? wasm.default?.executeCodec;
+    calendarBridge = wasm.executeCalendar ?? wasm.default?.executeCalendar;
     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, {
+  const trace = await runBytecode(packageValue, {
     codecBridge,
+    calendarBridge,
     propertyInput: propertyPath && fs.existsSync(propertyPath) ? [...fs.readFileSync(propertyPath)] : [],
     fixtureId: "hew-test",
     traceId: "trace:hew-test",

package/dist/interpreter/interpreter.d.ts

@@ -1,2 +1,2 @@
 import type { RunOptions, SandboxTrace } from "./types.js";
-export declare function runBytecode(input: unknown, options?: RunOptions): SandboxTrace;
+export declare function runBytecode(input: unknown, options?: RunOptions): Promise<SandboxTrace>;

package/dist/interpreter/interpreter.js

@@ -1,7 +1,7 @@
 import { validateBytecodePackage } from "./schema-validator.js";
 import { runPackageV1 } from "./v1/exec.js";
 import { TraceBuilder } from "./trace.js";
-export function runBytecode(input, options = {}) {
+export async function runBytecode(input, options = {}) {
     let bytecode;
     try {
         bytecode = validateBytecodePackage(input);

package/dist/interpreter/parity-runner.js

@@ -45,7 +45,7 @@ function parseArgs(argv) {
 try {
     const args = parseArgs(process.argv.slice(2));
     const bytecode = JSON.parse(fs.readFileSync(args.bytecodePath, "utf8"));
-    const trace = runBytecode(bytecode, {
+    const trace = await runBytecode(bytecode, {
         replay: {
             seed: args.seed,
             step_budget: DEFAULT_STEP_BUDGET,

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

@@ -1,5 +1,5 @@
 import type { PackageV1 } from "./v1/package.js";
-import type { JsonValue, RuntimeStatus, SandboxRejection } from "./types.js";
+import type { RunOptions, JsonValue, RuntimeStatus, SandboxRejection } from "./types.js";
 export interface Diagnostic {
     severity: string;
     phase: string;
@@ -24,7 +24,8 @@ type SandboxCompiler = (source: string, profile?: string, files?: Map<string, st
 declare global {
     var __hewSandboxCompileToSandboxBytecode: SandboxCompiler | undefined;
     var __hewSandboxExecuteCodec: ((request: string) => string) | undefined;
+    var __hewSandboxExecuteCalendar: ((request: string) => string) | undefined;
     var compileToSandboxBytecode: SandboxCompiler | undefined;
 }
-export declare function runProgram(source: string, stdin: string, files?: Map<string, string | Uint8Array>): RunProgramResult;
+export declare function runProgram(source: string, stdin: string, files?: Map<string, string | Uint8Array>, options?: RunOptions): Promise<RunProgramResult>;
 export {};

package/dist/interpreter/run-program.js

@@ -1,6 +1,6 @@
 import { runBytecode } from "./interpreter.js";
 const SANDBOX_PROFILE = "sandbox-vm-export";
-export function runProgram(source, stdin, files) {
+export async function runProgram(source, stdin, files, options = {}) {
     const compileOutput = compileSource(source, files);
     if (hasErrorDiagnostics(compileOutput.diagnostics) ||
         compileOutput.bytecode === null) {
@@ -15,9 +15,11 @@ export function runProgram(source, stdin, files) {
         };
     }
     const bytecode = compileOutput.bytecode;
-    const trace = runBytecode(bytecode, {
+    const trace = await runBytecode(bytecode, {
+        ...options,
         fixtureId: "page-run",
-        codecBridge: globalThis.__hewSandboxExecuteCodec,
+        codecBridge: options.codecBridge ?? globalThis.__hewSandboxExecuteCodec,
+        calendarBridge: options.calendarBridge ?? globalThis.__hewSandboxExecuteCalendar,
         traceId: "trace:page-run",
         replay: { inputs: [{ kind: "stdin", data: stdin }] },
     });

package/dist/interpreter/schema-validator.d.ts

@@ -1,8 +1,13 @@
-import { type PackageV1 } from "./v1/package.js";
+import type { PackageV1 } from "./v1/package.js";
+declare const checkedPackage: unique symbol;
+export type CheckedPackage = PackageV1 & {
+    readonly [checkedPackage]: true;
+};
 export declare class BytecodeValidationError extends Error {
     readonly errors: string[];
     constructor(errors: string[]);
 }
-/** Check the package envelope before capability admission traverses its tables.
- * Operation support belongs to v1/validate, with one shared executor registry. */
-export declare function validateBytecodePackage(input: unknown): PackageV1;
+/** Decode an isolated package before capability admission or any host effect.
+ * Cloning prevents a caller or host callback from changing the checked input. */
+export declare function validateBytecodePackage(input: unknown): CheckedPackage;
+export {};

package/dist/interpreter/schema-validator.js

@@ -1,4 +1,5 @@
-import { isPackageV1 } from "./v1/package.js";
+import { validPackage } from "./v1/package-validator.generated.js";
+import { validatePackageGraph } from "./v1/package-graph.js";
 export class BytecodeValidationError extends Error {
     errors;
     constructor(errors) {
@@ -7,55 +8,20 @@ export class BytecodeValidationError extends Error {
         this.name = "BytecodeValidationError";
     }
 }
-/** Check the package envelope before capability admission traverses its tables.
- * Operation support belongs to v1/validate, with one shared executor registry. */
+/** Decode an isolated package before capability admission or any host effect.
+ * Cloning prevents a caller or host callback from changing the checked input. */
 export function validateBytecodePackage(input) {
-    if (!isPackageV1(input))
-        throw new BytecodeValidationError(["expected hew.sandbox.bytecode.v1"]);
-    const errors = [];
-    for (const key of ["profile", "hew_version", "compiler_version"]) {
-        if (typeof input[key] !== "string")
-            errors.push(`${key} must be a string`);
-    }
-    for (const key of [
-        "functions",
-        "strings",
-        "bytes",
-        "regex_patterns",
-        "aggregates",
-        "variants",
-        "runtime_families",
-        "externs",
-        "suspend_kinds",
-        "value_capabilities",
-        "closures",
-        "vtables",
-    ]) {
-        if (!Array.isArray(input[key]))
-            errors.push(`${key} must be an array`);
-    }
-    if (errors.length)
-        throw new BytecodeValidationError(errors);
-    for (const fn of input.functions) {
-        if (!fn ||
-            !Number.isInteger(fn.id) ||
-            !Array.isArray(fn.params) ||
-            !Array.isArray(fn.places) ||
-            !Array.isArray(fn.blocks)) {
-            errors.push("malformed function");
-            continue;
-        }
-        for (const block of fn.blocks) {
-            if (!block ||
-                !Number.isInteger(block.id) ||
-                !Array.isArray(block.params) ||
-                !Array.isArray(block.ops) ||
-                !block.term ||
-                typeof block.term.op !== "string")
-                errors.push("malformed block");
+    try {
+        const decoded = structuredClone(input);
+        if (!validPackage(decoded)) {
+            const reasons = (validPackage.errors ?? []).map((issue) => `${issue.instancePath || "/"} ${issue.message ?? "invalid value"}`);
+            throw new Error(reasons.join("; ") || "malformed sandbox bytecode package");
         }
+        const pkg = decoded;
+        validatePackageGraph(pkg);
+        return pkg;
+    }
+    catch (error) {
+        throw new BytecodeValidationError([String(error)]);
     }
-    if (errors.length)
-        throw new BytecodeValidationError(errors);
-    return input;
 }

package/dist/interpreter/types.d.ts

@@ -117,9 +117,13 @@ export interface SandboxTrace {
     };
 }
 export interface RunOptions {
+    /** Explicit browser filesystem authority; absent roots grant no access. */
+    directoryRoots?: import("./v1/browser-directory.js").DirectoryRoots;
+    signal?: AbortSignal;
     /** Supplied process arguments including argv[0]. Defaults to ["main.hew"]. */
     argv?: readonly string[];
     codecBridge?: (request: string) => string;
+    calendarBridge?: (request: string) => string;
     propertyInput?: number[];
     fixtureId?: string;
     traceId?: string;

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;
+    }
+}