@oliphaunt/wasix-ts 0.1.0

package/lib/storage-snapshot.js

@@ -0,0 +1,274 @@
+export const VOLATILE_DATABASE_FILES = new Set(['postmaster.opts', 'postmaster.pid']);
+export function splitStorageDeltaDeletes(delta) {
+    const upserts = new Set([...delta.directories, ...delta.files.map(({ path }) => path)]);
+    return {
+        replacements: delta.deleted.filter((path) => upserts.has(path)),
+        removals: delta.deleted.filter((path) => !upserts.has(path)),
+    };
+}
+export async function snapshotStorageDirectory(directory, filter = {}) {
+    const directories = [];
+    const files = [];
+    const walk = async (parent) => {
+        const entries = [...(await directory.readDir(parent))].sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            validateDirectoryEntryName(entry.name);
+            const path = parent.length === 0 ? entry.name : `${parent}/${entry.name}`;
+            if (parent.length === 0 && VOLATILE_DATABASE_FILES.has(entry.name))
+                continue;
+            if (entry.type === 'dir') {
+                directories.push(path);
+                if (filter.skipDirectoryContents?.(path) !== true)
+                    await walk(path);
+            }
+            else if (entry.type === 'file') {
+                if (filter.skipFile?.(path) === true)
+                    continue;
+                files.push({ path, bytes: (await directory.readFile(path)).slice() });
+            }
+            else {
+                throw new Error(`Wasmer cannot snapshot PGDATA entry ${JSON.stringify(path)} of unknown type`);
+            }
+        }
+    };
+    await walk('');
+    return {
+        schema: 'oliphaunt-wasix-directory-snapshot-v1',
+        directories,
+        files,
+    };
+}
+/**
+ * Read only journaled PGDATA paths, falling back to a complete snapshot when
+ * the host does not expose mutation tracking or no durable generation exists.
+ */
+export async function snapshotStorageDelta(directory, persistedEntries, forceFull = false) {
+    if (forceFull || directory.changedPaths === undefined || directory.entryType === undefined) {
+        const snapshot = await snapshotStorageDirectory(directory);
+        const current = new Map([
+            ...snapshot.directories.map((path) => [path, 'dir']),
+            ...snapshot.files.map(({ path }) => [path, 'file']),
+        ]);
+        return {
+            directories: snapshot.directories,
+            files: snapshot.files,
+            deleted: [...persistedEntries]
+                .filter(([path, type]) => current.get(path) !== type)
+                .map(([path]) => path)
+                .sort(comparePathDepthDescending),
+        };
+    }
+    const touched = collapseTouchedPaths(await directory.changedPaths());
+    if (touched.length === 0) {
+        return { directories: [], files: [], deleted: [] };
+    }
+    const directories = new Map();
+    const files = new Map();
+    const current = new Map();
+    const inspect = async (path) => {
+        if (isVolatilePath(path))
+            return;
+        const type = await directory.entryType?.(path);
+        if (type === 'missing')
+            return;
+        if (type !== 'dir' && type !== 'file') {
+            throw new Error(`Wasmer cannot persist PGDATA entry ${JSON.stringify(path)} of unknown type`);
+        }
+        if (path.length > 0)
+            current.set(path, type);
+        if (type === 'file') {
+            files.set(path, {
+                path,
+                bytes: (await directory.readFile(path)).slice(),
+            });
+            return;
+        }
+        if (path.length > 0)
+            directories.set(path, path);
+        const entries = [...(await directory.readDir(path))].sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            validateDirectoryEntryName(entry.name);
+            const child = path.length === 0 ? entry.name : `${path}/${entry.name}`;
+            await inspect(child);
+        }
+    };
+    for (const path of touched)
+        await inspect(path);
+    const deleted = [...persistedEntries]
+        .filter(([path, type]) => touched.some((root) => pathIsWithin(path, root)) && current.get(path) !== type)
+        .map(([path]) => path)
+        .sort(comparePathDepthDescending);
+    return {
+        directories: [...directories.keys()].sort(compareDirectoryDepth),
+        files: [...files.values()].sort((left, right) => left.path.localeCompare(right.path)),
+        deleted,
+    };
+}
+export function applyStorageDeltaToEntries(persistedEntries, delta) {
+    for (const path of delta.deleted)
+        persistedEntries.delete(path);
+    for (const path of delta.directories)
+        persistedEntries.set(path, 'dir');
+    for (const { path } of delta.files)
+        persistedEntries.set(path, 'file');
+}
+export function validateStoredSnapshot(value, expectedPostgresMajor, context) {
+    let snapshot;
+    try {
+        snapshot = requireRecord(value, `${context.label} snapshot`);
+    }
+    catch (error) {
+        throw context.corrupt(`has a malformed directory snapshot: ${describeError(error)}`, error);
+    }
+    if (snapshot.schema !== 'oliphaunt-wasix-directory-snapshot-v1') {
+        throw context.corrupt('has an unsupported directory snapshot');
+    }
+    if (!Array.isArray(snapshot.directories) || !Array.isArray(snapshot.files)) {
+        throw context.corrupt('has malformed directory or file rows');
+    }
+    const directories = [];
+    const files = [];
+    const paths = new Set();
+    for (const path of snapshot.directories) {
+        validateStoredPath(path, context);
+        if (paths.has(path))
+            throw context.corrupt(`repeats snapshot path ${JSON.stringify(path)}`);
+        paths.add(path);
+        directories.push(path);
+    }
+    for (const value of snapshot.files) {
+        let file;
+        try {
+            file = requireRecord(value, `${context.label} file row`);
+        }
+        catch (error) {
+            throw context.corrupt(`has a malformed file row: ${describeError(error)}`, error);
+        }
+        validateStoredPath(file.path, context);
+        if (!(file.bytes instanceof Uint8Array)) {
+            throw context.corrupt(`has non-binary contents for ${JSON.stringify(file.path)}`);
+        }
+        if (paths.has(file.path)) {
+            throw context.corrupt(`repeats snapshot path ${JSON.stringify(file.path)}`);
+        }
+        paths.add(file.path);
+        files.push({ path: file.path, bytes: file.bytes.slice() });
+    }
+    validateSnapshotSemantics(directories, files, paths, expectedPostgresMajor, context);
+    return {
+        schema: 'oliphaunt-wasix-directory-snapshot-v1',
+        directories: directories.sort(compareDirectoryDepth),
+        files: files.sort((left, right) => left.path.localeCompare(right.path)),
+    };
+}
+export function snapshotToMount(snapshot) {
+    return {
+        files: Object.fromEntries(snapshot.files.map((file) => [file.path, file.bytes])),
+        directories: [...snapshot.directories],
+    };
+}
+export function requireRecord(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${label} must be an object`);
+    }
+    return value;
+}
+function validateSnapshotSemantics(directories, files, paths, expectedPostgresMajor, context) {
+    for (const volatile of VOLATILE_DATABASE_FILES) {
+        if (paths.has(volatile)) {
+            throw context.corrupt(`contains transient PostgreSQL process state ${JSON.stringify(volatile)}`);
+        }
+    }
+    const directoryPaths = new Set(directories);
+    const fileByPath = new Map(files.map((file) => [file.path, file.bytes]));
+    for (const path of paths) {
+        for (const parent of parentPaths(path)) {
+            if (fileByPath.has(parent)) {
+                throw context.corrupt(`contains path ${JSON.stringify(path)} below file ${JSON.stringify(parent)}`);
+            }
+            if (!directoryPaths.has(parent)) {
+                throw context.corrupt(`contains path ${JSON.stringify(path)} without parent directory ${JSON.stringify(parent)}`);
+            }
+        }
+    }
+    const pgVersion = fileByPath.get('PG_VERSION');
+    const pgControl = fileByPath.get('global/pg_control');
+    if (pgVersion === undefined || pgControl === undefined || !directoryPaths.has('pg_wal')) {
+        throw context.corrupt('is missing PG_VERSION, global/pg_control, or pg_wal');
+    }
+    if (pgControl.length === 0)
+        throw context.corrupt('contains an empty global/pg_control');
+    let actualPostgresMajor;
+    try {
+        actualPostgresMajor = new TextDecoder('utf-8', { fatal: true }).decode(pgVersion).trim();
+    }
+    catch (error) {
+        throw context.corrupt(`contains a non-UTF-8 PG_VERSION: ${describeError(error)}`, error);
+    }
+    if (actualPostgresMajor !== expectedPostgresMajor) {
+        throw context.corrupt(`contains PG_VERSION ${JSON.stringify(actualPostgresMajor)}, expected ${JSON.stringify(expectedPostgresMajor)}`);
+    }
+}
+export function validateDirectoryEntryName(name) {
+    if (name.length === 0 ||
+        name === '.' ||
+        name === '..' ||
+        name.includes('/') ||
+        name.includes('\\') ||
+        name.includes('\0')) {
+        throw new Error(`Wasmer returned an unsafe PGDATA entry name ${JSON.stringify(name)}`);
+    }
+}
+function validateStoredPath(value, context) {
+    if (typeof value !== 'string' || value.length === 0 || value.startsWith('/')) {
+        throw context.corrupt(`contains invalid snapshot path ${JSON.stringify(value)}`);
+    }
+    const segments = value.split('/');
+    if (value.includes('\\') ||
+        value.includes('\0') ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw context.corrupt(`contains unsafe snapshot path ${JSON.stringify(value)}`);
+    }
+}
+function parentPaths(path) {
+    const segments = path.split('/');
+    const parents = [];
+    for (let length = 1; length < segments.length; length += 1) {
+        parents.push(segments.slice(0, length).join('/'));
+    }
+    return parents;
+}
+function compareDirectoryDepth(left, right) {
+    return left.split('/').length - right.split('/').length || left.localeCompare(right);
+}
+function collapseTouchedPaths(values) {
+    const paths = [...new Set(values.map(validateTouchedPath))].sort(compareDirectoryDepth);
+    return paths.filter((path, index) => !paths.slice(0, index).some((parent) => pathIsWithin(path, parent)));
+}
+function validateTouchedPath(path) {
+    if (path === '')
+        return path;
+    if (typeof path !== 'string' || path.startsWith('/')) {
+        throw new Error(`Wasmer returned an unsafe changed PGDATA path ${JSON.stringify(path)}`);
+    }
+    const segments = path.split('/');
+    if (path.includes('\\') ||
+        path.includes('\0') ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`Wasmer returned an unsafe changed PGDATA path ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+function pathIsWithin(path, root) {
+    return root.length === 0 || path === root || path.startsWith(`${root}/`);
+}
+function isVolatilePath(path) {
+    const root = path.split('/')[0];
+    return root !== undefined && VOLATILE_DATABASE_FILES.has(root);
+}
+function comparePathDepthDescending(left, right) {
+    return right.split('/').length - left.split('/').length || right.localeCompare(left);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/storage.d.ts

@@ -0,0 +1,46 @@
+declare const storageDescriptorBrand: unique symbol;
+declare const persistentStorageDescriptorBrand: unique symbol;
+/**
+ * An opaque storage selection created by this package's storage factories.
+ * The descriptor is deliberately not a bag of user-authored paths or assets.
+ */
+export type WasixStorage = Readonly<{
+    [storageDescriptorBrand]: 'oliphaunt-wasix-storage';
+}>;
+/** Opaque persistent storage accepted by static physical restore. */
+export type PersistentWasixStorage = WasixStorage & Readonly<{
+    [persistentStorageDescriptorBrand]: 'oliphaunt-wasix-persistent-storage';
+}>;
+export type SerializedWasixStorage = Readonly<{
+    schema: 'oliphaunt-wasix-storage-v1';
+    kind: 'memory';
+}> | Readonly<{
+    schema: 'oliphaunt-wasix-storage-v1';
+    kind: 'indexed-db';
+    name: string;
+}> | Readonly<{
+    schema: 'oliphaunt-wasix-storage-v1';
+    kind: 'opfs';
+    name: string;
+}> | Readonly<{
+    schema: 'oliphaunt-wasix-storage-v1';
+    kind: 'directory';
+    path: string;
+}>;
+/**
+ * Select a fresh in-memory database. This is also the default when `storage`
+ * is omitted. Reusing the descriptor does not preserve data.
+ */
+export declare function memory(): WasixStorage;
+/** @internal Used by the selectively imported IndexedDB adapter. */
+export declare function defineIndexedDbStorage(name: string): PersistentWasixStorage;
+/** @internal Used by the selectively imported OPFS adapter. */
+export declare function defineOpfsStorage(name: string): PersistentWasixStorage;
+/** @internal Used by the selectively imported Node directory adapter. */
+export declare function defineDirectoryStorage(path: string): PersistentWasixStorage;
+/** @internal Validate and project the opaque main-thread value for the worker. */
+export declare function serializeWasixStorage(storage: WasixStorage | undefined): SerializedWasixStorage;
+export declare function validateIndexedDbDatabaseName(name: unknown): asserts name is string;
+export declare function validateOpfsDatabaseName(name: unknown): asserts name is string;
+export declare function validateHostDirectoryPath(path: unknown): asserts path is string;
+export {};

package/lib/storage.js

@@ -0,0 +1,83 @@
+const descriptorValues = new WeakMap();
+/**
+ * Select a fresh in-memory database. This is also the default when `storage`
+ * is omitted. Reusing the descriptor does not preserve data.
+ */
+export function memory() {
+    return defineStorage({
+        schema: 'oliphaunt-wasix-storage-v1',
+        kind: 'memory',
+    });
+}
+/** @internal Used by the selectively imported IndexedDB adapter. */
+export function defineIndexedDbStorage(name) {
+    validateIndexedDbDatabaseName(name);
+    return defineStorage({
+        schema: 'oliphaunt-wasix-storage-v1',
+        kind: 'indexed-db',
+        name,
+    });
+}
+/** @internal Used by the selectively imported OPFS adapter. */
+export function defineOpfsStorage(name) {
+    validateOpfsDatabaseName(name);
+    return defineStorage({
+        schema: 'oliphaunt-wasix-storage-v1',
+        kind: 'opfs',
+        name,
+    });
+}
+/** @internal Used by the selectively imported Node directory adapter. */
+export function defineDirectoryStorage(path) {
+    validateHostDirectoryPath(path);
+    return defineStorage({
+        schema: 'oliphaunt-wasix-storage-v1',
+        kind: 'directory',
+        path,
+    });
+}
+/** @internal Validate and project the opaque main-thread value for the worker. */
+export function serializeWasixStorage(storage) {
+    if (storage === undefined) {
+        return { schema: 'oliphaunt-wasix-storage-v1', kind: 'memory' };
+    }
+    const value = descriptorValues.get(storage);
+    if (value === undefined) {
+        throw new TypeError('storage must come from @oliphaunt/wasix-ts or one of its storage adapter subpaths');
+    }
+    switch (value.kind) {
+        case 'memory':
+            return { ...value };
+        case 'indexed-db':
+            return { ...value, name: value.name };
+        case 'opfs':
+            return { ...value, name: value.name };
+        case 'directory':
+            return { ...value, path: value.path };
+    }
+}
+export function validateIndexedDbDatabaseName(name) {
+    if (typeof name !== 'string' || name.length === 0 || name.length > 200 || name.includes('\0')) {
+        throw new TypeError('IndexedDB storage name must be 1-200 characters without NUL bytes');
+    }
+}
+export function validateOpfsDatabaseName(name) {
+    if (typeof name !== 'string' ||
+        name.length === 0 ||
+        name.length > 100 ||
+        name === '.' ||
+        name === '..' ||
+        !/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new TypeError('OPFS storage name must be 1-100 ASCII letters, digits, dot, dash, or underscore');
+    }
+}
+export function validateHostDirectoryPath(path) {
+    if (typeof path !== 'string' || path.length === 0 || path.includes('\0')) {
+        throw new TypeError('host directory storage path must be a non-empty string without NUL bytes');
+    }
+}
+function defineStorage(value) {
+    const descriptor = Object.freeze({});
+    descriptorValues.set(descriptor, Object.freeze(value));
+    return descriptor;
+}

package/lib/tool-runtime.d.ts

@@ -0,0 +1,43 @@
+import type { Directory, RunWasixOptions } from './host/index.mjs';
+import type { SerializedAssetSource } from './rpc.js';
+export type WasixToolDescriptor = Readonly<{
+    name: 'pg_dump' | 'psql';
+    sha256: string;
+    size: number;
+    source: SerializedAssetSource;
+}>;
+export type WasixToolProcessOptions = Readonly<{
+    runtimeVersion: string;
+    tool: WasixToolDescriptor;
+    args: readonly string[];
+    /** @internal An exact ArrayBuffer-backed view is transferred and consumed. */
+    stdin?: Uint8Array;
+}>;
+export type WasixToolProcessResult = Readonly<{
+    exitCode: number;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}>;
+/** @internal The already-open database worker does not need carrier runtime metadata again. */
+export type WasixPgDumpProcessOptions = Readonly<{
+    tool: WasixToolDescriptor;
+    args: readonly string[];
+}>;
+export type PreparedWasixToolAsset = Readonly<{
+    name: 'pg_dump' | 'psql';
+    bytes: Uint8Array;
+    module: WebAssembly.Module;
+}>;
+/** @internal Verify and compile one immutable frontend program once per owning worker. */
+export declare function prepareWasixToolAsset(descriptor: WasixToolDescriptor): Promise<PreparedWasixToolAsset>;
+/** @internal Create only the fresh mutable paths a standalone frontend program uses. */
+export declare function materializeWasixToolMounts(DirectoryConstructor: typeof Directory, tool: PreparedWasixToolAsset): Promise<Record<string, Directory>>;
+/** @internal Release every mount and retain both execution and cleanup failures. */
+export declare function releaseWasixToolMounts(mounts: Record<string, Directory>): void;
+export declare function releaseWasixToolMounts(mounts: Record<string, Directory>, failure: Readonly<{
+    primary: unknown;
+}>): never;
+/** @internal Build the identical fresh-process contract for both execution topologies. */
+export declare function wasixToolRunOptions(tool: PreparedWasixToolAsset, args: readonly string[], mounts: Record<string, Directory>, stdin?: Uint8Array): RunWasixOptions;
+export declare function validateWasixToolDescriptor(tool: WasixToolDescriptor): void;
+export declare function wasixToolAssetIdentity(descriptor: WasixToolDescriptor): string;

package/lib/tool-runtime.js

@@ -0,0 +1,93 @@
+import { assertSha256 } from './extensions.js';
+import { loadAsset } from './archive.js';
+/** @internal Verify and compile one immutable frontend program once per owning worker. */
+export async function prepareWasixToolAsset(descriptor) {
+    validateWasixToolDescriptor(descriptor);
+    const loaded = await loadAsset(descriptor.source, `WASIX ${descriptor.name} module`);
+    const bytes = standaloneBytes(loaded);
+    if (bytes.length !== descriptor.size) {
+        throw new Error(`WASIX ${descriptor.name} module size mismatch`);
+    }
+    await assertSha256(bytes, descriptor.sha256, `WASIX ${descriptor.name} module`);
+    return {
+        name: descriptor.name,
+        bytes,
+        module: await WebAssembly.compile(bytes),
+    };
+}
+/** @internal Create only the fresh mutable paths a standalone frontend program uses. */
+export async function materializeWasixToolMounts(DirectoryConstructor, tool) {
+    const mounts = {};
+    try {
+        mounts['/bin'] = new DirectoryConstructor({ [tool.name]: tool.bytes });
+        const home = new DirectoryConstructor();
+        mounts['/home'] = home;
+        await home.createDir('postgres');
+        mounts['/tmp'] = new DirectoryConstructor();
+        return mounts;
+    }
+    catch (error) {
+        releaseWasixToolMounts(mounts, { primary: error });
+    }
+}
+export function releaseWasixToolMounts(mounts, failure) {
+    const cleanupFailures = [];
+    for (const directory of Object.values(mounts)) {
+        try {
+            directory.free();
+        }
+        catch (error) {
+            cleanupFailures.push(error);
+        }
+    }
+    if (failure !== undefined) {
+        if (cleanupFailures.length === 0)
+            throw failure.primary;
+        throw new AggregateError([failure.primary, ...cleanupFailures], 'WASIX tool execution and mount cleanup both failed', { cause: failure.primary });
+    }
+    if (cleanupFailures.length !== 0) {
+        throw new AggregateError(cleanupFailures, 'WASIX tool mount cleanup failed');
+    }
+}
+/** @internal Build the identical fresh-process contract for both execution topologies. */
+export function wasixToolRunOptions(tool, args, mounts, stdin) {
+    return {
+        program: `/bin/${tool.name}`,
+        args: [...args],
+        cwd: '/',
+        env: {
+            PGUSER: 'postgres',
+            PGPASSWORD: 'password',
+            PGSSLMODE: 'disable',
+            PGCLIENTENCODING: 'UTF8',
+            ...(tool.name === 'psql' ? { OLIPHAUNT_PSQL_NONINTERACTIVE: '1' } : {}),
+            HOME: '/home/postgres',
+            PATH: '/bin',
+            LC_CTYPE: 'C.UTF-8',
+            TZ: 'UTC',
+        },
+        mount: mounts,
+        stdin,
+    };
+}
+export function validateWasixToolDescriptor(tool) {
+    if (tool.name !== 'pg_dump' && tool.name !== 'psql') {
+        throw new TypeError('unsupported Oliphaunt WASIX tool');
+    }
+    if (!/^[0-9a-f]{64}$/u.test(tool.sha256)) {
+        throw new TypeError(`WASIX ${tool.name} SHA-256 is invalid`);
+    }
+    if (!Number.isSafeInteger(tool.size) || tool.size <= 0) {
+        throw new TypeError(`WASIX ${tool.name} size is invalid`);
+    }
+}
+export function wasixToolAssetIdentity(descriptor) {
+    return `${descriptor.name}:${descriptor.sha256}:${descriptor.size}`;
+}
+function standaloneBytes(bytes) {
+    return bytes.buffer instanceof ArrayBuffer &&
+        bytes.byteOffset === 0 &&
+        bytes.byteLength === bytes.buffer.byteLength
+        ? bytes
+        : Uint8Array.from(bytes);
+}

package/lib/tool-worker-common.d.ts

@@ -0,0 +1,48 @@
+import { type WasixByteChannel } from './byte-channel.js';
+import type { Directory, OliphauntPreparedTool, OliphauntToolOutput, RunWasixOptions } from './host/index.mjs';
+import { type WasixToolDescriptor } from './tool-runtime.js';
+export type WasixToolWorkerRequest = WasixToolPrepareRequest | WasixToolRunRequest;
+export type WasixToolPrepareRequest = Readonly<{
+    id: number;
+    kind: 'prepare';
+    tool: WasixToolDescriptor & Readonly<{
+        name: 'psql';
+    }>;
+}>;
+export type WasixToolRunRequest = Readonly<{
+    id: number;
+    kind: 'run';
+    tool: 'psql';
+    args: string[];
+    stdin?: Uint8Array;
+    frontend: WasixByteChannel;
+    backend: WasixByteChannel;
+}>;
+export type WasixToolWorkerResponse = Readonly<{
+    id: number;
+    ok: true;
+    kind: 'prepared';
+}> | Readonly<{
+    id: number;
+    ok: true;
+    kind: 'completed';
+    exitCode: number;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}> | Readonly<{
+    id: number;
+    ok: false;
+    message: string;
+}>;
+export type WasixToolHost = Readonly<{
+    Directory: typeof Directory;
+    init(): Promise<unknown>;
+    prepareOliphauntTool(module: WebAssembly.Module, moduleBytes: Uint8Array): OliphauntPreparedTool;
+    runOliphauntToolDirect(prepared: OliphauntPreparedTool, options: RunWasixOptions, protocolRead: (maximumBytes: number) => Uint8Array, 
+    /** Borrowed bytes: synchronously copy; never mutate or retain this view. */
+    protocolWrite: (chunk: Uint8Array) => void): Promise<OliphauntToolOutput>;
+}>;
+/** @internal Stateful dispatcher owned by one persistent outer tool worker. */
+export declare function createWasixToolWorkerDispatcher(host: WasixToolHost): (request: WasixToolWorkerRequest) => Promise<WasixToolWorkerResponse>;
+/** @internal Transfer owned tool outputs without another table-sized structured clone. */
+export declare function toolWorkerResponseTransfers(response: WasixToolWorkerResponse): ArrayBuffer[];

package/lib/tool-worker-common.js

@@ -0,0 +1,97 @@
+import { closeWasixByteChannel, failWasixByteChannel, markWasixByteChannelProtocolComplete, markWasixByteChannelProtocolStarted, readWasixByteChannelSync, wasixByteChannelProtocolOutcomeUnknown, writeWasixByteChannelSync, } from './byte-channel.js';
+import { materializeWasixToolMounts, prepareWasixToolAsset, releaseWasixToolMounts, wasixToolAssetIdentity, wasixToolRunOptions, } from './tool-runtime.js';
+/** @internal Stateful dispatcher owned by one persistent outer tool worker. */
+export function createWasixToolWorkerDispatcher(host) {
+    let hostInitialization;
+    let tool;
+    const dispatch = async (request) => {
+        try {
+            hostInitialization ??= host.init();
+            await hostInitialization;
+            if (request.kind === 'prepare') {
+                const toolIdentity = wasixToolAssetIdentity(request.tool);
+                if (tool === undefined) {
+                    const asset = await prepareWasixToolAsset(request.tool);
+                    tool = {
+                        identity: toolIdentity,
+                        asset,
+                        prepared: host.prepareOliphauntTool(asset.module, asset.bytes),
+                    };
+                }
+                else if (tool.identity !== toolIdentity) {
+                    throw new Error('Oliphaunt WASIX tool worker cannot replace psql');
+                }
+                return { id: request.id, ok: true, kind: 'prepared' };
+            }
+            if (tool === undefined)
+                throw new Error(`WASIX ${request.tool} module is not prepared`);
+            return await runPreparedTool(request, host, tool);
+        }
+        catch (error) {
+            if (request.kind === 'run') {
+                finishFailedToolChannels(request);
+            }
+            return { id: request.id, ok: false, message: describeWorkerError(error) };
+        }
+    };
+    return dispatch;
+}
+/** @internal Transfer owned tool outputs without another table-sized structured clone. */
+export function toolWorkerResponseTransfers(response) {
+    if (!response.ok || response.kind !== 'completed')
+        return [];
+    const buffers = new Set();
+    for (const bytes of [response.stdout, response.stderr]) {
+        if (bytes.buffer instanceof ArrayBuffer)
+            buffers.add(bytes.buffer);
+    }
+    return [...buffers];
+}
+async function runPreparedTool(request, host, tool) {
+    const mounts = await materializeWasixToolMounts(host.Directory, tool.asset);
+    let response;
+    let failure;
+    try {
+        const output = await host.runOliphauntToolDirect(tool.prepared, wasixToolRunOptions(tool.asset, request.args, mounts, request.stdin), (maximumBytes) => {
+            markWasixByteChannelProtocolStarted(request.frontend);
+            return readWasixByteChannelSync(request.backend, maximumBytes);
+        }, (chunk) => {
+            markWasixByteChannelProtocolStarted(request.frontend);
+            writeWasixByteChannelSync(request.frontend, chunk);
+        });
+        markWasixByteChannelProtocolComplete(request.frontend);
+        closeWasixByteChannel(request.frontend);
+        response = {
+            id: request.id,
+            ok: true,
+            kind: 'completed',
+            exitCode: output.code,
+            stdout: output.stdoutBytes,
+            stderr: output.stderrBytes,
+        };
+    }
+    catch (error) {
+        failure = { primary: error };
+    }
+    if (failure !== undefined)
+        releaseWasixToolMounts(mounts, failure);
+    releaseWasixToolMounts(mounts);
+    if (response === undefined)
+        throw new Error('WASIX psql completed without a response');
+    return response;
+}
+function finishFailedToolChannels(request) {
+    if (wasixByteChannelProtocolOutcomeUnknown(request.frontend)) {
+        // Mark uncertainty before EOF so the database cannot observe a clean
+        // connection close and reset while a later public tool failure escapes.
+        failWasixByteChannel(request.frontend);
+        failWasixByteChannel(request.backend);
+    }
+    closeWasixByteChannel(request.frontend);
+}
+function describeWorkerError(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = 'cause' in error ? error.cause : undefined;
+    return cause === undefined ? error.message : `${error.message}: ${describeWorkerError(cause)}`;
+}