@oliphaunt/wasix-ts 0.1.0

package/lib/native-session.js

@@ -0,0 +1,565 @@
+import { WasixStorageError, } from './errors.js';
+import { loadNativeWasixAddon, } from './native-addon.js';
+import { normalizeWasixDatabaseIdentity, } from './database.js';
+import { validateWasixToolDescriptor } from './tool-runtime.js';
+/** @internal A synchronous Rust Oliphaunt owned by the importing JavaScript realm. */
+export class NativeWasixSession {
+    identity;
+    terminalState;
+    #addon;
+    #handle;
+    #runtimeVersion;
+    #closed = false;
+    #closeAttempt;
+    constructor(addon, handle, identity, runtimeVersion) {
+        this.#addon = addon;
+        this.#handle = handle;
+        this.identity = identity;
+        this.#runtimeVersion = runtimeVersion;
+        this.terminalState = new NativeHandleTerminalState(() => this.#handle.closed, 'Oliphaunt WASIX direct owner stopped unexpectedly');
+    }
+    static async open(options) {
+        const addon = requireCompatibleNativeWasixAddon(options);
+        let nativeOptions;
+        if (options.storage.kind === 'memory') {
+            nativeOptions = nativeWasixOpenOptions(options, { kind: 'memory' });
+        }
+        else if (options.storage.kind === 'directory') {
+            nativeOptions = nativeWasixOpenOptions(options, {
+                kind: 'directory',
+                path: options.storage.path,
+            });
+        }
+        else {
+            const provider = options.storage.kind === 'indexed-db' ? 'IndexedDB' : 'OPFS';
+            throw new TypeError(`@oliphaunt/wasix-ts ${provider} storage is browser-only`);
+        }
+        try {
+            const handle = addon.NativeWasixDatabase.open(nativeOptions);
+            validateDatabaseHandle(handle);
+            return new NativeWasixSession(addon, handle, normalizeWasixDatabaseIdentity(options.username, options.database), options.runtime.version);
+        }
+        catch (error) {
+            throw mapNativeError(error);
+        }
+    }
+    async exec(input, _persistence = 'sync') {
+        this.#assertOpen();
+        try {
+            return binaryView(this.#handle.execProtocolRaw(input));
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+    }
+    async execStream(input, onChunk, _persistence = 'sync') {
+        this.#assertOpen();
+        let outcome;
+        try {
+            outcome = this.#handle.execProtocolRawStream(input, (chunk) => onChunk(binaryView(chunk)));
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+        if (outcome === 'complete')
+            return outcome;
+        if (outcome === 'callbackAborted')
+            return outcome;
+        throw new Error(`Oliphaunt WASIX native addon returned invalid stream outcome ${outcome}`);
+    }
+    async sync(_boundary) {
+        this.#assertOpen();
+        // Rust's host-directory filesystem publishes and flushes inside each
+        // synchronous protocol operation. Memory storage has no host boundary.
+    }
+    async backup() {
+        this.#assertOpen();
+        try {
+            return binaryView(this.#handle.backup());
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+    }
+    runPgDump(options) {
+        return this.runTool({
+            runtimeVersion: '',
+            tool: options.tool,
+            args: options.args,
+        });
+    }
+    async runTool(options) {
+        this.#assertOpen();
+        if (options.runtimeVersion !== '' && options.runtimeVersion !== this.#runtimeVersion) {
+            throw new Error(`WASIX tools runtime ${options.runtimeVersion} is incompatible with database runtime ${this.#runtimeVersion}`);
+        }
+        validateWasixToolDescriptor(options.tool);
+        const expectedIdentity = `${options.tool.sha256}:${options.tool.size}`;
+        if (this.#addon.toolIdentity(options.tool.name) !== expectedIdentity) {
+            throw new Error(`WASIX ${options.tool.name} descriptor does not match the tool embedded in the native addon`);
+        }
+        if (options.tool.name === 'pg_dump') {
+            try {
+                return toolProcessResult(this.#handle.pgDump(userPgDumpArguments(options.args, this.identity)));
+            }
+            catch (error) {
+                throw this.#mapFailure(error);
+            }
+        }
+        const parsed = userPsqlArguments(options.args, options.stdin, this.identity);
+        try {
+            return toolProcessResult(this.#handle.psql(parsed.args, parsed.command, parsed.script));
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+    }
+    close() {
+        if (this.#closeAttempt !== undefined)
+            return this.#closeAttempt;
+        this.#closed = true;
+        this.terminalState.beginOrderlyClose();
+        this.#closeAttempt = this.#close();
+        return this.#closeAttempt;
+    }
+    async #close() {
+        try {
+            this.#handle.close();
+        }
+        catch (error) {
+            throw mapNativeError(error);
+        }
+    }
+    #assertOpen() {
+        if (this.#closed) {
+            throw new Error('Oliphaunt WASIX native session is closed');
+        }
+        this.terminalState.assertActive();
+    }
+    #mapFailure(error) {
+        const mapped = mapNativeError(error);
+        this.terminalState.recordFailure(mapped);
+        return mapped;
+    }
+}
+/** @internal A Rust-owner actor whose Promise completions return to the importing realm. */
+export class NativeWasixActorSession {
+    identity;
+    terminalState;
+    #addon;
+    #handle;
+    #runtimeVersion;
+    #closed = false;
+    #closeAttempt;
+    constructor(addon, handle, identity, runtimeVersion) {
+        this.#addon = addon;
+        this.#handle = handle;
+        this.identity = identity;
+        this.#runtimeVersion = runtimeVersion;
+        this.terminalState = new NativeHandleTerminalState(() => this.#handle.closed, 'Oliphaunt WASIX actor owner stopped unexpectedly');
+    }
+    static async open(options) {
+        const addon = requireCompatibleNativeWasixAddon(options);
+        try {
+            const handle = await addon.NativeWasixActorDatabase.open(nativeWasixOpenOptions(options, nativeStorage(options)));
+            validateActorDatabaseHandle(handle);
+            return new NativeWasixActorSession(addon, handle, normalizeWasixDatabaseIdentity(options.username, options.database), options.runtime.version);
+        }
+        catch (error) {
+            throw mapNativeError(error);
+        }
+    }
+    async exec(input, _persistence = 'sync') {
+        this.#assertOpen();
+        try {
+            return binaryView(await this.#handle.execProtocolRaw(input));
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+    }
+    async execStream(input, onChunk, _persistence = 'sync') {
+        this.#assertOpen();
+        let outcome;
+        try {
+            outcome = await this.#handle.execProtocolRawStream(input, (chunk) => onChunk(binaryView(chunk)));
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+        if (outcome === 'complete' || outcome === 'callbackAborted')
+            return outcome;
+        throw new Error(`Oliphaunt WASIX native actor returned invalid stream outcome ${outcome}`);
+    }
+    async sync(_boundary) {
+        this.#assertOpen();
+        // Rust publishes host-directory storage at the operation boundary.
+    }
+    async backup() {
+        this.#assertOpen();
+        try {
+            return binaryView(await this.#handle.backup());
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+    }
+    runPgDump(options) {
+        return this.runTool({ runtimeVersion: '', tool: options.tool, args: options.args });
+    }
+    async runTool(options) {
+        this.#assertOpen();
+        validateNativeToolCall(this.#addon, this.#runtimeVersion, options);
+        try {
+            if (options.tool.name === 'pg_dump') {
+                return toolProcessResult(await this.#handle.pgDump(userPgDumpArguments(options.args, this.identity)));
+            }
+            const parsed = userPsqlArguments(options.args, options.stdin, this.identity);
+            return toolProcessResult(await this.#handle.psql(parsed.args, parsed.command, parsed.script));
+        }
+        catch (error) {
+            throw this.#mapFailure(error);
+        }
+    }
+    close() {
+        if (this.#closeAttempt !== undefined)
+            return this.#closeAttempt;
+        this.#closed = true;
+        this.terminalState.beginOrderlyClose();
+        this.#closeAttempt = this.#close();
+        return this.#closeAttempt;
+    }
+    async #close() {
+        try {
+            await this.#handle.close();
+        }
+        catch (error) {
+            throw mapNativeError(error);
+        }
+    }
+    #assertOpen() {
+        if (this.#closed) {
+            throw new Error('Oliphaunt WASIX native actor session is closed');
+        }
+        this.terminalState.assertActive();
+    }
+    #mapFailure(error) {
+        const mapped = mapNativeError(error);
+        this.terminalState.recordFailure(mapped);
+        return mapped;
+    }
+}
+/** @internal Stable observation of a native owner which can retire below TypeScript. */
+class NativeHandleTerminalState {
+    #isClosed;
+    #ownerLossMessage;
+    #orderlyClose = false;
+    #failure;
+    constructor(isClosed, ownerLossMessage) {
+        this.#isClosed = isClosed;
+        this.#ownerLossMessage = ownerLossMessage;
+    }
+    get terminal() {
+        this.#observeOwnerLoss();
+        return this.#failure !== undefined;
+    }
+    get failure() {
+        return this.#failure;
+    }
+    assertActive() {
+        this.#observeOwnerLoss();
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+    beginOrderlyClose() {
+        this.#orderlyClose = true;
+    }
+    recordFailure(error) {
+        if (this.#orderlyClose || !this.#closedAfterFailure())
+            return;
+        this.#failure ??= terminalError(error, this.#ownerLossMessage);
+    }
+    #observeOwnerLoss() {
+        if (this.#orderlyClose || this.#failure !== undefined)
+            return;
+        try {
+            if (this.#isClosed())
+                this.#failure = new Error(this.#ownerLossMessage);
+        }
+        catch (error) {
+            this.#failure = terminalError(error, this.#ownerLossMessage);
+        }
+    }
+    #closedAfterFailure() {
+        try {
+            return this.#isClosed();
+        }
+        catch {
+            // A synchronous failure while observing the native owner's terminal bit
+            // is itself loss of that owner. Preserve the operation's original error.
+            return true;
+        }
+    }
+}
+/** @internal Restore through the synchronous Rust archive validator. */
+export async function restoreNativeWasix(options, bytes) {
+    const addon = requireCompatibleNativeWasixAddon(options);
+    return restoreNativeWasixStorage(options.storage, bytes, addon);
+}
+/** @internal Worker-side restore after the parent has validated package config. */
+export async function restoreNativeWasixStorage(storage, bytes, addon = loadNativeWasixAddon()) {
+    if (storage.kind !== 'directory') {
+        throw new TypeError('WASIX restore requires Node-compatible directory storage');
+    }
+    try {
+        await addon.restore(storage.path, bytes);
+    }
+    catch (error) {
+        throw mapNativeError(error);
+    }
+}
+/** @internal Restore synchronously inside `/direct` or its dedicated Worker realm. */
+export async function restoreNativeWasixDirect(options, bytes) {
+    const addon = requireCompatibleNativeWasixAddon(options);
+    return restoreNativeWasixStorageDirect(options.storage, bytes, addon);
+}
+/** @internal Worker-side synchronous restore after the parent validates config. */
+export async function restoreNativeWasixStorageDirect(storage, bytes, addon = loadNativeWasixAddon()) {
+    if (storage.kind !== 'directory') {
+        throw new TypeError('WASIX restore requires Node-compatible directory storage');
+    }
+    try {
+        addon.restoreDirect(storage.path, bytes);
+    }
+    catch (error) {
+        throw mapNativeError(error);
+    }
+}
+/** @internal Validate serialized package descriptors against the selected addon. */
+export function requireCompatibleNativeWasixAddon(options) {
+    const addon = loadNativeWasixAddon();
+    if (options.runtime.product !== 'liboliphaunt-wasix' ||
+        options.runtime.version !== addon.runtimeVersion()) {
+        throw new Error(`WASIX runtime ${options.runtime.version} is incompatible with native runtime ${addon.runtimeVersion()}`);
+    }
+    if (options.icu !== undefined &&
+        options.icu.compatibility.runtimeVersion !== options.runtime.version) {
+        throw new Error('WASIX ICU descriptor is incompatible with the selected native runtime');
+    }
+    requireEmbeddedPayloadIdentity(addon, 'runtimeArchive', options.runtime.runtimeArchive, 'runtime archive');
+    requireEmbeddedPayloadIdentity(addon, 'standardSeedArchive', options.runtime.standardSeedArchive, 'standard cluster seed archive');
+    requireEmbeddedPayloadIdentity(addon, 'standardSeedManifest', options.runtime.standardSeedManifest, 'standard cluster seed manifest');
+    if (options.icu !== undefined) {
+        requireEmbeddedPayloadIdentity(addon, 'icuDataArchive', options.icu.dataArchive, 'ICU data archive');
+        requireEmbeddedPayloadIdentity(addon, 'icuSeedArchive', options.icu.clusterSeedArchive, 'ICU cluster seed archive');
+        requireEmbeddedPayloadIdentity(addon, 'icuSeedManifest', options.icu.clusterSeedManifest, 'ICU cluster seed manifest');
+    }
+    for (const [sqlName, carrier] of Object.entries(options.extensionCarriers)) {
+        if (carrier.sqlName !== sqlName) {
+            throw new Error(`WASIX extension carrier key ${sqlName} does not match ${carrier.sqlName}`);
+        }
+        const expectedIdentity = `${carrier.sha256}:${carrier.size}`;
+        if (addon.extensionIdentity(sqlName) !== expectedIdentity) {
+            throw new Error(`WASIX extension ${sqlName} descriptor does not match the archive embedded in the native addon`);
+        }
+    }
+    return addon;
+}
+function requireEmbeddedPayloadIdentity(addon, component, descriptor, label) {
+    if (addon.payloadIdentity(component) !== `${descriptor.sha256}:${descriptor.size}`) {
+        throw new Error(`WASIX ${label} descriptor does not match the native addon payload`);
+    }
+}
+/** @internal Project already-validated TS config onto the narrow native ABI. */
+export function nativeWasixOpenOptions(options, storage) {
+    const identity = normalizeWasixDatabaseIdentity(options.username, options.database);
+    return {
+        profile: options.icu === undefined ? 'standard' : 'icu',
+        storage,
+        username: identity.username,
+        database: identity.database,
+        startupGucs: { ...options.startupGUCs },
+        extensions: [...options.extensions],
+    };
+}
+function nativeStorage(options) {
+    if (options.storage.kind === 'memory')
+        return { kind: 'memory' };
+    if (options.storage.kind === 'directory') {
+        return { kind: 'directory', path: options.storage.path };
+    }
+    const provider = options.storage.kind === 'indexed-db' ? 'IndexedDB' : 'OPFS';
+    throw new TypeError(`@oliphaunt/wasix-ts ${provider} storage is browser-only`);
+}
+function validateNativeToolCall(addon, runtimeVersion, options) {
+    if (options.runtimeVersion !== '' && options.runtimeVersion !== runtimeVersion) {
+        throw new Error(`WASIX tools runtime ${options.runtimeVersion} is incompatible with database runtime ${runtimeVersion}`);
+    }
+    validateWasixToolDescriptor(options.tool);
+    const expectedIdentity = `${options.tool.sha256}:${options.tool.size}`;
+    if (addon.toolIdentity(options.tool.name) !== expectedIdentity) {
+        throw new Error(`WASIX ${options.tool.name} descriptor does not match the tool embedded in the native addon`);
+    }
+}
+function validateDatabaseHandle(handle) {
+    if (typeof handle !== 'object' ||
+        handle === null ||
+        typeof handle.closed !== 'boolean' ||
+        typeof handle.execProtocolRaw !== 'function' ||
+        typeof handle.execProtocolRawStream !== 'function' ||
+        typeof handle.backup !== 'function' ||
+        typeof handle.pgDump !== 'function' ||
+        typeof handle.psql !== 'function' ||
+        typeof handle.close !== 'function') {
+        throw new Error('Oliphaunt WASIX native addon returned an invalid database handle');
+    }
+}
+function validateActorDatabaseHandle(handle) {
+    if (typeof handle !== 'object' ||
+        handle === null ||
+        typeof handle.closed !== 'boolean' ||
+        typeof handle.execProtocolRaw !== 'function' ||
+        typeof handle.execProtocolRawStream !== 'function' ||
+        typeof handle.backup !== 'function' ||
+        typeof handle.pgDump !== 'function' ||
+        typeof handle.psql !== 'function' ||
+        typeof handle.close !== 'function') {
+        throw new Error('Oliphaunt WASIX native addon returned an invalid actor database handle');
+    }
+}
+function binaryView(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    throw new TypeError('Oliphaunt WASIX native addon returned a non-binary value');
+}
+function toolProcessResult(result) {
+    if (typeof result !== 'object' ||
+        result === null ||
+        !Number.isSafeInteger(result.status) ||
+        !isBinary(result.stdout) ||
+        !isBinary(result.stderr)) {
+        throw new TypeError('Oliphaunt WASIX native tool returned an invalid process result');
+    }
+    return {
+        exitCode: result.status,
+        stdout: binaryView(result.stdout),
+        stderr: binaryView(result.stderr),
+    };
+}
+function userPgDumpArguments(args, identity) {
+    const suffix = [
+        '--encoding=UTF8',
+        '--no-password',
+        `--username=${identity.username}`,
+        '--host=127.0.0.1',
+        '--port=65432',
+        `--dbname=${identity.database}`,
+    ];
+    return stripManagedSuffix('pg_dump', args, suffix);
+}
+function userPsqlArguments(args, stdin, identity) {
+    const managed = [
+        '--no-psqlrc',
+        '--no-password',
+        '--set=ON_ERROR_STOP=1',
+        `--username=${identity.username}`,
+        '--host=127.0.0.1',
+        '--port=65432',
+        `--dbname=${identity.database}`,
+    ];
+    const start = findExactSequence(args, managed);
+    if (start < 0)
+        throw new Error('Oliphaunt WASIX psql call has an invalid managed argument set');
+    const user = args.slice(0, start);
+    const input = args.slice(start + managed.length);
+    if (input.length === 0)
+        return { args: user };
+    if (input.length === 2 && input[0] === '--command' && input[1] !== undefined) {
+        return { args: user, command: input[1] };
+    }
+    if (input.length === 1 && input[0] === '--file=-' && stdin !== undefined) {
+        return {
+            args: user,
+            script: new TextDecoder('utf-8', { fatal: true }).decode(stdin),
+        };
+    }
+    throw new Error('Oliphaunt WASIX psql call has invalid managed input arguments');
+}
+function stripManagedSuffix(tool, args, suffix) {
+    if (args.length < suffix.length ||
+        !suffix.every((argument, index) => args[args.length - suffix.length + index] === argument)) {
+        throw new Error(`Oliphaunt WASIX ${tool} call has an invalid managed argument set`);
+    }
+    return args.slice(0, -suffix.length);
+}
+function findExactSequence(values, expected) {
+    for (let start = values.length - expected.length; start >= 0; start -= 1) {
+        if (expected.every((value, offset) => values[start + offset] === value))
+            return start;
+    }
+    return -1;
+}
+/** @internal Translate only the exact tagged native storage contract. */
+export function mapNativeError(error) {
+    if (error instanceof WasixStorageError)
+        return error;
+    const details = nativeStorageError(error);
+    if (details === undefined)
+        return error;
+    return new WasixStorageError(describeError(error), { ...details, cause: error });
+}
+const STORAGE_CODES = [
+    'busy',
+    'corrupt',
+    'incomplete',
+    'incompatible',
+    'publication-failed',
+    'unavailable',
+];
+const STORAGE_COMMIT_STATES = [
+    'not-persisted',
+    'persisted',
+    'unchanged',
+    'unknown',
+];
+const STORAGE_PHASES = [
+    'ownership',
+    'open',
+    'open-publication',
+    'operation',
+    'backup',
+    'close',
+    'restore-validation',
+    'restore-staging',
+    'restore-publication',
+    'restore-durability',
+];
+function nativeStorageError(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const candidate = error;
+    if (candidate.oliphauntWasixError !== 'storage' ||
+        candidate.oliphauntWasixAddonAbi !== 1 ||
+        !memberOf(candidate.code, STORAGE_CODES) ||
+        !memberOf(candidate.commitState, STORAGE_COMMIT_STATES) ||
+        !memberOf(candidate.phase, STORAGE_PHASES)) {
+        return undefined;
+    }
+    return {
+        code: candidate.code,
+        commitState: candidate.commitState,
+        phase: candidate.phase,
+    };
+}
+function memberOf(value, values) {
+    return typeof value === 'string' && values.includes(value);
+}
+function isBinary(value) {
+    return value instanceof Uint8Array;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function terminalError(error, fallback) {
+    return error instanceof Error ? error : new Error(fallback, { cause: error });
+}

package/lib/node-actor.d.ts

@@ -0,0 +1,7 @@
+import { NativeWasixActorSession } from './native-session.js';
+import type { SerializedOpenOptions } from './rpc.js';
+import type { OliphauntDatabase } from './types.js';
+/** @internal Open one Rust-owner actor without blocking the importing event loop. */
+export declare function openNodeActorSession(options: SerializedOpenOptions): Promise<NativeWasixActorSession>;
+/** @internal Open the public database contract over the native Rust owner. */
+export declare function openNodeActor(options: SerializedOpenOptions): Promise<OliphauntDatabase>;

package/lib/node-actor.js

@@ -0,0 +1,10 @@
+import { WasixDatabaseImpl } from './database.js';
+import { NativeWasixActorSession } from './native-session.js';
+/** @internal Open one Rust-owner actor without blocking the importing event loop. */
+export async function openNodeActorSession(options) {
+    return NativeWasixActorSession.open(options);
+}
+/** @internal Open the public database contract over the native Rust owner. */
+export async function openNodeActor(options) {
+    return new WasixDatabaseImpl(await openNodeActorSession(options));
+}

package/lib/node-client-common.d.ts

@@ -0,0 +1,9 @@
+import type { SerializedOpenOptions } from './rpc.js';
+import type { PersistentWasixStorage } from './storage.js';
+import type { BinaryInput } from './types.js';
+/** @internal Restore a physical archive through the Rust WASIX implementation. */
+export declare function restoreNodeWasix(storage: PersistentWasixStorage, bytes: BinaryInput): Promise<void>;
+/** @internal Restore synchronously in the importing realm for `/direct`. */
+export declare function restoreNodeWasixDirect(storage: PersistentWasixStorage, bytes: BinaryInput): Promise<void>;
+/** @internal Validate and normalize storage shared by direct and Worker entrypoints. */
+export declare function requireNodeStorage(options: SerializedOpenOptions): void;

package/lib/node-client-common.js

@@ -0,0 +1,35 @@
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { serializeOpenConfig } from './client-common.js';
+import { hostRuntime } from './host-runtime.js';
+import { restoreNativeWasix, restoreNativeWasixDirect } from './native-session.js';
+import { toUint8Array } from './query.js';
+/** @internal Restore a physical archive through the Rust WASIX implementation. */
+export async function restoreNodeWasix(storage, bytes) {
+    const options = serializeOpenConfig({ storage });
+    requireNodeStorage(options);
+    return restoreNativeWasix(options, toUint8Array(bytes).slice());
+}
+/** @internal Restore synchronously in the importing realm for `/direct`. */
+export async function restoreNodeWasixDirect(storage, bytes) {
+    const options = serializeOpenConfig({ storage });
+    requireNodeStorage(options);
+    return restoreNativeWasixDirect(options, toUint8Array(bytes).slice());
+}
+/** @internal Validate and normalize storage shared by direct and Worker entrypoints. */
+export function requireNodeStorage(options) {
+    if (options.storage.kind === 'indexed-db' || options.storage.kind === 'opfs') {
+        const provider = options.storage.kind === 'indexed-db' ? 'IndexedDB' : 'OPFS';
+        throw new TypeError(`@oliphaunt/wasix-ts ${provider} storage is browser-only; use memory or the storage/${hostRuntime()} adapter`);
+    }
+    if (options.storage.kind === 'directory') {
+        options.storage = {
+            ...options.storage,
+            path: resolveNodeDirectoryPath(options.storage.path),
+        };
+    }
+}
+function resolveNodeDirectoryPath(input) {
+    const requested = input.startsWith('file:') ? fileURLToPath(input) : input;
+    return isAbsolute(requested) ? requested : resolve(requested);
+}

package/lib/node-client.d.ts

@@ -0,0 +1,4 @@
+import type { OliphauntClient, OliphauntDatabase, OpenConfig } from './types.js';
+/** Open PostgreSQL on a dedicated Rust owner while keeping the caller event loop responsive. */
+export declare function openWasix(config?: OpenConfig): Promise<OliphauntDatabase>;
+export declare const Oliphaunt: OliphauntClient;

package/lib/node-client.js

@@ -0,0 +1,13 @@
+import { serializeOpenConfig } from './client-common.js';
+import { requireNodeStorage, restoreNodeWasix } from './node-client-common.js';
+import { openNodeActor } from './node-actor.js';
+/** Open PostgreSQL on a dedicated Rust owner while keeping the caller event loop responsive. */
+export async function openWasix(config = {}) {
+    const openOptions = serializeOpenConfig(config);
+    requireNodeStorage(openOptions);
+    return openNodeActor(openOptions);
+}
+export const Oliphaunt = {
+    open: openWasix,
+    restore: restoreNodeWasix,
+};

package/lib/node-direct.d.ts

@@ -0,0 +1,7 @@
+import { NativeWasixSession } from './native-session.js';
+import type { SerializedOpenOptions } from './rpc.js';
+import type { OliphauntDatabase } from './types.js';
+/** @internal Own one synchronous Rust WASIX session in the current JS realm. */
+export declare function openNodeDirectSession(options: SerializedOpenOptions): Promise<NativeWasixSession>;
+/** @internal Open the public database contract in the current Node realm. */
+export declare function openNodeDirect(options: SerializedOpenOptions): Promise<OliphauntDatabase>;

package/lib/node-direct.js

@@ -0,0 +1,10 @@
+import { WasixDatabaseImpl } from './database.js';
+import { NativeWasixSession } from './native-session.js';
+/** @internal Own one synchronous Rust WASIX session in the current JS realm. */
+export async function openNodeDirectSession(options) {
+    return NativeWasixSession.open(options);
+}
+/** @internal Open the public database contract in the current Node realm. */
+export async function openNodeDirect(options) {
+    return new WasixDatabaseImpl(await openNodeDirectSession(options));
+}

package/lib/node-worker-options.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Keep runtime configuration flags while removing invocation modes which
+ * replace a file-backed Worker program.
+ */
+export declare function nodeWorkerExecArgv(execArgv?: readonly string[]): string[];