@oliphaunt/wasix-ts 0.1.0

package/lib/internal-common.js

@@ -0,0 +1,274 @@
+import defaultWasixRuntime from '@oliphaunt/liboliphaunt-wasix';
+import { closeWasixByteChannel, createWasixByteChannel, failWasixByteChannel, wasixByteChannelProtocolOutcomeUnknown, } from './byte-channel.js';
+import { assertWasixProtocolConnectionTarget, registerWasixDatabaseResource, reserveWasixProtocolConnection, runWasixPgDumpProcess, } from './database.js';
+import { validateWasixToolDescriptor, } from './tool-runtime.js';
+const controllers = new WeakMap();
+/** @internal Shared browser/server tool orchestration; public API lives in the optional package. */
+export function runWasixToolProcess(database, options, createWorker) {
+    if (options.runtimeVersion !== defaultWasixRuntime.version) {
+        throw new Error(`WASIX tools runtime ${options.runtimeVersion} is incompatible with database runtime ${defaultWasixRuntime.version}`);
+    }
+    validateWasixToolDescriptor(options.tool);
+    if (options.tool.name === 'pg_dump') {
+        return runWasixPgDumpProcess(database, options);
+    }
+    assertWasixProtocolConnectionTarget(database);
+    let controller = controllers.get(database);
+    if (controller === undefined) {
+        controller = new WasixToolController(database, createWorker);
+        registerWasixDatabaseResource(database, controller);
+        controllers.set(database, controller);
+    }
+    return controller.run(options);
+}
+class WasixToolController {
+    #database;
+    #createWorker;
+    #pending = new Map();
+    #preparedPsqlIdentity;
+    #retiredWorkerTerminations = new Set();
+    #connections = new Set();
+    #worker;
+    #nextId = 1;
+    #tail = Promise.resolve();
+    #closing = false;
+    #fatal;
+    #termination;
+    constructor(database, createWorker) {
+        this.#database = database;
+        this.#createWorker = createWorker;
+    }
+    run(options) {
+        if (this.#closing) {
+            return Promise.reject(new Error('Oliphaunt WASIX tool worker is closing'));
+        }
+        if (this.#fatal !== undefined)
+            return Promise.reject(this.#fatal);
+        if (options.tool.name !== 'psql') {
+            return Promise.reject(new TypeError('the bounded tool worker supports only psql'));
+        }
+        let connection;
+        try {
+            // Reserve the database FIFO during the public call. Preparing a cold
+            // tool must not let a later query or tool overtake this invocation.
+            connection = this.#reserveConnection();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const operation = this.#tail.then(() => this.#runOne(options, connection));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async close() {
+        if (this.#termination !== undefined)
+            return this.#termination;
+        this.#closing = true;
+        const error = this.#fatal ?? new Error('Oliphaunt WASIX tool worker is closing');
+        this.#fatal = error;
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+        this.#failConnections(error);
+        const worker = this.#worker;
+        this.#worker = undefined;
+        this.#preparedPsqlIdentity = undefined;
+        const terminations = [...this.#retiredWorkerTerminations];
+        if (worker !== undefined)
+            terminations.push(terminateWorker(worker));
+        this.#termination = Promise.all(terminations).then(() => undefined);
+        return this.#termination;
+    }
+    async #runOne(options, connection) {
+        const { frontend, backend } = connection;
+        try {
+            if (this.#closing)
+                throw this.#fatal;
+            if (this.#fatal !== undefined)
+                throw this.#fatal;
+            if (connection.failure !== undefined)
+                throw connection.failure;
+            await this.#prepare(options.tool);
+            if (this.#closing)
+                throw this.#fatal;
+            if (this.#fatal !== undefined)
+                throw this.#fatal;
+            if (connection.failure !== undefined)
+                throw connection.failure;
+            const databaseServing = connection.database.start();
+            connection.started = true;
+            const serving = databaseServing.then(() => ({ ok: true }), (error) => {
+                connection.failure ??= asError(error);
+                failWasixByteChannel(frontend);
+                failWasixByteChannel(backend);
+                return { ok: false, error };
+            });
+            connection.serving = serving;
+            const stdin = options.stdin;
+            let response;
+            let responseFailure;
+            try {
+                response = await this.#request({
+                    kind: 'run',
+                    tool: 'psql',
+                    args: [...options.args],
+                    stdin,
+                    frontend,
+                    backend,
+                }, stdin === undefined ||
+                    !(stdin.buffer instanceof ArrayBuffer) ||
+                    stdin.byteOffset !== 0 ||
+                    stdin.byteLength !== stdin.buffer.byteLength
+                    ? []
+                    : [stdin.buffer]);
+                if (!response.ok)
+                    throw new Error(response.message);
+                if (response.kind !== 'completed') {
+                    throw new Error('Oliphaunt WASIX tool worker returned an invalid completion response');
+                }
+                closeWasixByteChannel(frontend);
+            }
+            catch (error) {
+                responseFailure = error;
+                finishFailedToolChannels(connection);
+            }
+            if (responseFailure !== undefined)
+                throw responseFailure;
+            const served = await serving;
+            if (!served.ok)
+                throw served.error;
+            if (response === undefined || !response.ok || response.kind !== 'completed') {
+                throw new Error('Oliphaunt WASIX tool worker did not return a result');
+            }
+            return {
+                exitCode: response.exitCode,
+                stdout: response.stdout,
+                stderr: response.stderr,
+            };
+        }
+        finally {
+            closeWasixByteChannel(frontend);
+            if (!connection.started)
+                connection.database.cancel();
+            if (connection.serving !== undefined && !this.#closing)
+                await connection.serving;
+            closeWasixByteChannel(backend);
+            this.#connections.delete(connection);
+        }
+    }
+    #reserveConnection() {
+        const frontend = createWasixByteChannel();
+        const backend = createWasixByteChannel();
+        try {
+            const database = reserveWasixProtocolConnection(this.#database, { frontend, backend }, 'tool');
+            const connection = {
+                frontend,
+                backend,
+                database,
+                started: false,
+            };
+            this.#connections.add(connection);
+            return connection;
+        }
+        catch (error) {
+            failWasixByteChannel(frontend);
+            failWasixByteChannel(backend);
+            throw error;
+        }
+    }
+    #failConnections(error) {
+        for (const connection of this.#connections) {
+            connection.failure ??= error;
+            if (!connection.started)
+                connection.database.cancel();
+            finishFailedToolChannels(connection);
+        }
+    }
+    async #prepare(tool) {
+        const identity = `${tool.sha256}:${tool.size}`;
+        if (this.#preparedPsqlIdentity === identity)
+            return;
+        const response = await this.#request({
+            kind: 'prepare',
+            tool,
+        });
+        if (!response.ok)
+            throw new Error(response.message);
+        if (response.kind !== 'prepared') {
+            throw new Error('Oliphaunt WASIX tool worker returned an invalid preparation response');
+        }
+        this.#preparedPsqlIdentity = identity;
+    }
+    #request(request, transfer = []) {
+        if (this.#fatal !== undefined)
+            return Promise.reject(this.#fatal);
+        const worker = this.#ensureWorker();
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            try {
+                worker.postMessage({ ...request, id }, transfer);
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                reject(asError(error));
+            }
+        });
+    }
+    #ensureWorker() {
+        if (this.#worker !== undefined)
+            return this.#worker;
+        const worker = this.#createWorker();
+        this.#worker = worker;
+        worker.onMessage((response) => {
+            if (this.#worker !== worker)
+                return;
+            const pending = this.#pending.get(response.id);
+            if (pending === undefined)
+                return;
+            this.#pending.delete(response.id);
+            pending.resolve(response);
+        });
+        worker.onFatal((error) => {
+            if (this.#worker !== worker)
+                return;
+            this.#handleFatal(error);
+        });
+        return worker;
+    }
+    #handleFatal(error) {
+        const protocolOutcomeUnknown = [...this.#connections].some((connection) => wasixByteChannelProtocolOutcomeUnknown(connection.frontend));
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+        this.#failConnections(error);
+        const worker = this.#worker;
+        this.#worker = undefined;
+        if (worker !== undefined) {
+            const termination = terminateWorker(worker);
+            // The worker fatal path has no awaiting caller, but database.close()
+            // must still observe a failed termination instead of reporting a clean
+            // shutdown while the retired worker may remain alive.
+            void termination.catch(() => undefined);
+            this.#retiredWorkerTerminations.add(termination);
+        }
+        this.#preparedPsqlIdentity = undefined;
+        if (protocolOutcomeUnknown || this.#closing)
+            this.#fatal = error;
+    }
+}
+function finishFailedToolChannels(connection) {
+    if (wasixByteChannelProtocolOutcomeUnknown(connection.frontend)) {
+        failWasixByteChannel(connection.frontend);
+        failWasixByteChannel(connection.backend);
+    }
+    closeWasixByteChannel(connection.frontend);
+}
+function terminateWorker(worker) {
+    return Promise.resolve()
+        .then(() => worker.terminate())
+        .then(() => undefined);
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/lib/internal.d.ts

@@ -0,0 +1,5 @@
+import type { OliphauntDatabase } from './types.js';
+import { type WasixToolProcessOptions, type WasixToolProcessResult } from './internal-common.js';
+export { getWasixDatabaseIdentity } from './database.js';
+export type { WasixToolDescriptor, WasixToolProcessOptions, WasixToolProcessResult, } from './internal-common.js';
+export declare function runWasixToolProcess(database: OliphauntDatabase, options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;

package/lib/internal.js

@@ -0,0 +1,42 @@
+import { runWasixToolProcess as runTool, } from './internal-common.js';
+export { getWasixDatabaseIdentity } from './database.js';
+export function runWasixToolProcess(database, options) {
+    return runTool(database, options, createBrowserToolWorker);
+}
+function createBrowserToolWorker() {
+    if (typeof Worker === 'undefined') {
+        throw new Error('WASIX tools require Web Workers');
+    }
+    const worker = new Worker(new URL('./tool-worker.js', import.meta.url), {
+        type: 'module',
+        name: 'oliphaunt-wasix-tool',
+    });
+    let messageListener;
+    let fatalListener;
+    let fatalDelivered = false;
+    worker.addEventListener('message', (event) => {
+        messageListener?.(event.data);
+    });
+    worker.addEventListener('error', (event) => {
+        if (fatalDelivered)
+            return;
+        fatalDelivered = true;
+        fatalListener?.(new Error(event.message || 'Oliphaunt WASIX tool worker crashed'));
+    });
+    worker.addEventListener('messageerror', () => {
+        if (fatalDelivered)
+            return;
+        fatalDelivered = true;
+        fatalListener?.(new Error('Oliphaunt WASIX tool worker returned an unreadable response'));
+    });
+    return {
+        postMessage: (request, transfer = []) => worker.postMessage(request, transfer),
+        onMessage: (listener) => {
+            messageListener = listener;
+        },
+        onFatal: (listener) => {
+            fatalListener = listener;
+        },
+        terminate: () => worker.terminate(),
+    };
+}

package/lib/internal.node.d.ts

@@ -0,0 +1,5 @@
+import type { OliphauntDatabase } from './types.js';
+import type { WasixToolProcessOptions, WasixToolProcessResult } from './internal-common.js';
+export { getWasixDatabaseIdentity } from './database.js';
+export type { WasixToolDescriptor, WasixToolProcessOptions, WasixToolProcessResult, } from './internal-common.js';
+export declare function runWasixToolProcess(database: OliphauntDatabase, options: WasixToolProcessOptions): Promise<WasixToolProcessResult>;

package/lib/internal.node.js

@@ -0,0 +1,8 @@
+import { tryRunWasixNativeToolProcess } from './database.js';
+export { getWasixDatabaseIdentity } from './database.js';
+export function runWasixToolProcess(database, options) {
+    const native = tryRunWasixNativeToolProcess(database, options);
+    if (native !== undefined)
+        return native;
+    throw new Error('this database is not backed by the Oliphaunt WASIX native runtime required by Node.js, Bun, Deno, and Electron tools');
+}

package/lib/native-addon.d.ts

@@ -0,0 +1,111 @@
+export type NativeWasixStorage = Readonly<{
+    kind: 'memory';
+}> | Readonly<{
+    kind: 'directory';
+    path: string;
+}>;
+export type NativeProfile = 'standard' | 'icu';
+export type NativeWasixOpenOptions = Readonly<{
+    profile: NativeProfile;
+    storage: NativeWasixStorage;
+    username: string;
+    database: string;
+    startupGucs: Record<string, string>;
+    extensions: string[];
+}>;
+export type NativeWasixServerListen = Readonly<{
+    transport: 'tcp';
+    port?: number;
+}> | Readonly<{
+    transport: 'unix';
+    directory: string;
+    port?: number;
+}>;
+export type NativeWasixServerOpenOptions = NativeWasixOpenOptions & Readonly<{
+    listen: NativeWasixServerListen;
+}>;
+export type NativeWasixDatabaseHandle = {
+    readonly closed: boolean;
+    execProtocolRaw(request: Uint8Array): Uint8Array;
+    execProtocolRawStream(request: Uint8Array, onChunk: (chunk: Uint8Array) => void): 'complete' | 'callbackAborted';
+    backup(): Uint8Array;
+    pgDump(args: string[]): NativeWasixToolResult;
+    psql(args: string[], command?: string, script?: string): NativeWasixToolResult;
+    close(): void;
+};
+export type NativeWasixActorDatabaseHandle = {
+    readonly closed: boolean;
+    execProtocolRaw(request: Uint8Array): Promise<Uint8Array>;
+    execProtocolRawStream(request: Uint8Array, onChunk: (chunk: Uint8Array) => void): Promise<'complete' | 'callbackAborted'>;
+    backup(): Promise<Uint8Array>;
+    pgDump(args: string[]): Promise<NativeWasixToolResult>;
+    psql(args: string[], command?: string, script?: string): Promise<NativeWasixToolResult>;
+    close(): Promise<void>;
+};
+export type NativeWasixToolResult = Readonly<{
+    status: number;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+}>;
+export type NativeWasixServerHandle = {
+    readonly connectionString: string;
+    readonly closed: boolean;
+    close(): Promise<void>;
+};
+export type NativeWasixAddon = {
+    NativeWasixDatabase: {
+        open(options: NativeWasixOpenOptions): NativeWasixDatabaseHandle;
+        readonly prototype: NativeWasixDatabaseHandle;
+    };
+    NativeWasixActorDatabase: {
+        open(options: NativeWasixOpenOptions): Promise<NativeWasixActorDatabaseHandle>;
+        readonly prototype: NativeWasixActorDatabaseHandle;
+    };
+    NativeWasixServer: {
+        open(options: NativeWasixServerOpenOptions): Promise<NativeWasixServerHandle>;
+        readonly prototype: NativeWasixServerHandle;
+    };
+    restore(destination: string, bytes: Uint8Array): Promise<void>;
+    restoreDirect(destination: string, bytes: Uint8Array): void;
+    addonAbiVersion(): number;
+    nodeApiVersion(): number;
+    runtimeVersion(): string;
+    supportedProfiles(): readonly NativeProfile[];
+    payloadIdentity(component: 'runtimeArchive' | 'standardSeedArchive' | 'standardSeedManifest' | 'icuDataArchive' | 'icuSeedArchive' | 'icuSeedManifest'): string;
+    extensionIdentity(sqlName: string): string;
+    toolIdentity(name: 'pg_dump' | 'psql'): string;
+};
+type WasixPackageMetadata = Readonly<{
+    name?: string;
+    oliphaunt?: {
+        runtimeProduct?: string;
+        runtimeVersion?: string;
+        wasixNapiProduct?: string;
+        wasixNapiVersion?: string;
+        wasixAddonAbiVersion?: number;
+        nodeApiVersion?: number;
+    };
+}>;
+type NativeTarget = Readonly<{
+    id: string;
+    packageName: string;
+    libc?: 'glibc';
+}>;
+type LinuxLibc = 'glibc' | 'musl' | 'unknown';
+type LinuxDiagnosticReport = Readonly<{
+    header?: Readonly<{
+        glibcVersionRuntime?: unknown;
+    }>;
+    sharedObjects?: unknown;
+}>;
+/** @internal Load and verify the platform addon selected by the server runtime. */
+export declare function loadNativeWasixAddon(): NativeWasixAddon;
+/** @internal Read an optional override without making Deno env permission mandatory. */
+export declare function optionalEnvironmentValue(name: string, read?: (name: string) => string | undefined, denoRuntime?: boolean): string | undefined;
+/** @internal Resolve only the GNU Linux carriers; musl addons are not published. */
+export declare function nativeTarget(currentPlatform: string, currentArch: string, currentLibc?: LinuxLibc): NativeTarget;
+/** @internal Detect Linux libc without probing mutable external commands. */
+export declare function detectLinuxLibc(report?: LinuxDiagnosticReport | undefined, versions?: Readonly<Record<string, string | undefined>>, denoTarget?: string | undefined): LinuxLibc;
+/** @internal Enforce the complete v1 release surface before any database opens. */
+export declare function validateNativeWasixAddon(addon: NativeWasixAddon, path: string, metadata: WasixPackageMetadata): void;
+export {};

package/lib/native-addon.js

@@ -0,0 +1,223 @@
+import { readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { arch, platform } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const require = createRequire(import.meta.url);
+const ADDON_ENV = 'OLIPHAUNT_WASIX_NAPI';
+const ADDON_STEM = 'oliphaunt_wasix_napi';
+const EXPECTED_NAPI_VERSION = 8;
+const PRODUCT = 'oliphaunt-wasix-napi';
+let loadedAddon;
+/** @internal Load and verify the platform addon selected by the server runtime. */
+export function loadNativeWasixAddon() {
+    if (loadedAddon !== undefined)
+        return loadedAddon;
+    const runtimeNapi = Number(process.versions.napi);
+    if (!Number.isSafeInteger(runtimeNapi) || runtimeNapi < EXPECTED_NAPI_VERSION) {
+        throw new Error(`this runtime does not provide the Node-API ${EXPECTED_NAPI_VERSION} ABI required by @oliphaunt/wasix-ts`);
+    }
+    const runtimePlatform = platform();
+    const runtimeLibc = runtimePlatform === 'linux' ? detectLinuxLibc() : 'unknown';
+    if (runtimePlatform === 'linux')
+        requireSupportedLinuxLibc(runtimeLibc);
+    const metadata = packageMetadata();
+    const path = resolveNativeAddonPath(metadata, runtimePlatform, runtimeLibc);
+    const loaded = require(path);
+    const addon = normalizeAddon(loaded);
+    validateNativeWasixAddon(addon, path, metadata);
+    loadedAddon = addon;
+    return addon;
+}
+function resolveNativeAddonPath(metadata, runtimePlatform, runtimeLibc) {
+    const explicit = optionalEnvironmentValue(ADDON_ENV);
+    if (explicit !== undefined && explicit.trim().length > 0) {
+        if (explicit.includes('\0'))
+            throw new Error(`${ADDON_ENV} must not contain NUL bytes`);
+        const path = resolve(explicit);
+        requireRegularFile(path, ADDON_ENV);
+        return path;
+    }
+    for (const candidate of packageAdjacentAddons()) {
+        if (isRegularFile(candidate))
+            return candidate;
+    }
+    const version = metadata.oliphaunt?.wasixNapiVersion;
+    if (version === undefined || !/^\d+\.\d+\.\d+$/u.test(version)) {
+        throw new Error('@oliphaunt/wasix-ts package metadata does not pin wasixNapiVersion');
+    }
+    const target = nativeTarget(runtimePlatform, arch(), runtimeLibc);
+    let packageJsonPath;
+    try {
+        packageJsonPath = require.resolve(`${target.packageName}/package.json`);
+    }
+    catch {
+        throw new Error(`${target.packageName} ${version} is not installed; reinstall @oliphaunt/wasix-ts with optional dependencies enabled`);
+    }
+    const carrier = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    if (carrier.name !== target.packageName ||
+        carrier.version !== version ||
+        JSON.stringify(carrier.libc) !==
+            JSON.stringify(target.libc === undefined ? undefined : [target.libc]) ||
+        carrier.oliphaunt?.target !== target.id ||
+        carrier.oliphaunt?.runtimeProduct !== metadata.oliphaunt?.runtimeProduct ||
+        carrier.oliphaunt?.runtimeVersion !== metadata.oliphaunt?.runtimeVersion ||
+        carrier.oliphaunt?.addonAbiVersion !== metadata.oliphaunt?.wasixAddonAbiVersion ||
+        carrier.oliphaunt?.nodeApiVersion !== metadata.oliphaunt?.nodeApiVersion ||
+        JSON.stringify(carrier.oliphaunt?.profiles) !== JSON.stringify(['standard', 'icu'])) {
+        throw new Error(`${target.packageName} metadata is incompatible with @oliphaunt/wasix-ts`);
+    }
+    const addonPath = require.resolve(`${target.packageName}/${ADDON_STEM}.node`);
+    requireRegularFile(addonPath, `${target.packageName} addon`);
+    return addonPath;
+}
+/** @internal Read an optional override without making Deno env permission mandatory. */
+export function optionalEnvironmentValue(name, read = (key) => process.env[key], denoRuntime = 'Deno' in globalThis) {
+    try {
+        return read(name);
+    }
+    catch (error) {
+        if (denoRuntime &&
+            error instanceof Error &&
+            (error.name === 'NotCapable' || error.name === 'PermissionDenied')) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function packageMetadata() {
+    const path = fileURLToPath(new URL('../package.json', import.meta.url));
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function packageAdjacentAddons() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const file = `${ADDON_STEM}.node`;
+    return [join(here, file), join(here, '..', file)];
+}
+/** @internal Resolve only the GNU Linux carriers; musl addons are not published. */
+export function nativeTarget(currentPlatform, currentArch, currentLibc = currentPlatform === 'linux' ? detectLinuxLibc() : 'unknown') {
+    if (currentPlatform === 'darwin' && currentArch === 'arm64') {
+        return { id: 'macos-arm64', packageName: '@oliphaunt/wasix-napi-darwin-arm64' };
+    }
+    if (currentPlatform === 'linux')
+        requireSupportedLinuxLibc(currentLibc);
+    if (currentPlatform === 'linux' && currentArch === 'arm64') {
+        return {
+            id: 'linux-arm64-gnu',
+            packageName: '@oliphaunt/wasix-napi-linux-arm64-gnu',
+            libc: 'glibc',
+        };
+    }
+    if (currentPlatform === 'linux' && currentArch === 'x64') {
+        return {
+            id: 'linux-x64-gnu',
+            packageName: '@oliphaunt/wasix-napi-linux-x64-gnu',
+            libc: 'glibc',
+        };
+    }
+    if (currentPlatform === 'win32' && currentArch === 'x64') {
+        return { id: 'windows-x64-msvc', packageName: '@oliphaunt/wasix-napi-win32-x64-msvc' };
+    }
+    throw new Error(`no Oliphaunt WASIX Node-API package is defined for ${currentPlatform}/${currentArch}`);
+}
+/** @internal Detect Linux libc without probing mutable external commands. */
+export function detectLinuxLibc(report = undefined, versions = process.versions, denoTarget = denoBuildTarget()) {
+    if (typeof versions.musl === 'string' && versions.musl.length > 0)
+        return 'musl';
+    if (denoTarget?.endsWith('-linux-musl'))
+        return 'musl';
+    if (denoTarget?.endsWith('-linux-gnu'))
+        return 'glibc';
+    const diagnostic = report ?? process.report?.getReport?.();
+    if (Array.isArray(diagnostic?.sharedObjects) &&
+        diagnostic.sharedObjects.some((member) => typeof member === 'string' && /(?:^|[/\\])ld-musl-/iu.test(member))) {
+        return 'musl';
+    }
+    if (typeof diagnostic?.header?.glibcVersionRuntime === 'string' &&
+        diagnostic.header.glibcVersionRuntime.length > 0) {
+        return 'glibc';
+    }
+    return 'unknown';
+}
+function denoBuildTarget() {
+    const deno = globalThis.Deno;
+    return typeof deno?.build?.target === 'string' ? deno.build.target : undefined;
+}
+function requireSupportedLinuxLibc(libc) {
+    if (libc === 'musl') {
+        throw new Error('Oliphaunt WASIX Node-API does not support Linux musl; install on a glibc-based system');
+    }
+    if (libc !== 'glibc') {
+        throw new Error('Oliphaunt WASIX Node-API could not verify a supported Linux glibc runtime');
+    }
+}
+function normalizeAddon(loaded) {
+    const maybeDefault = loaded;
+    return (maybeDefault.default ?? loaded);
+}
+/** @internal Enforce the complete v1 release surface before any database opens. */
+export function validateNativeWasixAddon(addon, path, metadata) {
+    const databasePrototype = addon?.NativeWasixDatabase?.prototype;
+    const actorDatabasePrototype = addon?.NativeWasixActorDatabase?.prototype;
+    const serverPrototype = addon?.NativeWasixServer?.prototype;
+    if (metadata.name !== '@oliphaunt/wasix-ts' ||
+        typeof addon !== 'object' ||
+        addon === null ||
+        typeof addon.NativeWasixDatabase?.open !== 'function' ||
+        typeof databasePrototype?.execProtocolRaw !== 'function' ||
+        typeof databasePrototype.execProtocolRawStream !== 'function' ||
+        typeof databasePrototype.backup !== 'function' ||
+        typeof databasePrototype.pgDump !== 'function' ||
+        typeof databasePrototype.psql !== 'function' ||
+        typeof databasePrototype.close !== 'function' ||
+        typeof addon.NativeWasixActorDatabase?.open !== 'function' ||
+        typeof actorDatabasePrototype?.execProtocolRaw !== 'function' ||
+        typeof actorDatabasePrototype.execProtocolRawStream !== 'function' ||
+        typeof actorDatabasePrototype.backup !== 'function' ||
+        typeof actorDatabasePrototype.pgDump !== 'function' ||
+        typeof actorDatabasePrototype.psql !== 'function' ||
+        typeof actorDatabasePrototype.close !== 'function' ||
+        typeof addon.NativeWasixServer?.open !== 'function' ||
+        typeof serverPrototype?.close !== 'function' ||
+        typeof addon.restore !== 'function' ||
+        typeof addon.restoreDirect !== 'function' ||
+        typeof addon.addonAbiVersion !== 'function' ||
+        typeof addon.nodeApiVersion !== 'function' ||
+        typeof addon.runtimeVersion !== 'function' ||
+        typeof addon.supportedProfiles !== 'function' ||
+        typeof addon.payloadIdentity !== 'function' ||
+        typeof addon.extensionIdentity !== 'function' ||
+        typeof addon.toolIdentity !== 'function') {
+        throw new Error(`Oliphaunt WASIX native addon ${path} has an invalid export surface`);
+    }
+    const expectedAbi = metadata.oliphaunt?.wasixAddonAbiVersion;
+    if (expectedAbi !== 1 || addon.addonAbiVersion() !== expectedAbi) {
+        throw new Error(`Oliphaunt WASIX native addon ${path} has an incompatible addon ABI`);
+    }
+    const expectedNodeApi = metadata.oliphaunt?.nodeApiVersion;
+    if (expectedNodeApi !== EXPECTED_NAPI_VERSION || addon.nodeApiVersion() !== expectedNodeApi) {
+        throw new Error(`Oliphaunt WASIX native addon ${path} does not use Node-API ${EXPECTED_NAPI_VERSION}`);
+    }
+    const expectedRuntime = metadata.oliphaunt?.runtimeVersion;
+    if (expectedRuntime === undefined || addon.runtimeVersion() !== expectedRuntime) {
+        throw new Error(`Oliphaunt WASIX native addon ${path} has an incompatible runtime version`);
+    }
+    if (metadata.oliphaunt?.wasixNapiProduct !== PRODUCT) {
+        throw new Error('@oliphaunt/wasix-ts package metadata has an invalid WASIX N-API product');
+    }
+    if (JSON.stringify(addon.supportedProfiles()) !== JSON.stringify(['standard', 'icu'])) {
+        throw new Error(`Oliphaunt WASIX native addon ${path} has incompatible catalog profiles`);
+    }
+}
+function requireRegularFile(path, source) {
+    if (!isRegularFile(path))
+        throw new Error(`${source} does not point to a regular file: ${path}`);
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}