@oliphaunt/wasix-ts 0.1.0

package/lib/database.js

@@ -0,0 +1,1039 @@
+import { composeWasixStorageFailure, WasixStorageError } from './errors.js';
+import { assertNoTransactionChain, decodeQueryResult, describeQuery, errorWithNotices, extendedQuery, inspectManagedTransactionResponse, inspectReadyForQuery, parseCommandResponse, parseDescribeResponse, parseExecResponse, parseQueryRawResponse, planQuery, structuredSimpleQuery, toUint8Array, } from './query.js';
+const transactionPinnedMessage = 'Oliphaunt WASIX database is pinned to an active transaction; use the callback transaction handle';
+const CLOSE_DEADLINE_MS = 120_000;
+/** @internal Buffered protocol fallbacks use the same observable callback granularity. */
+export const WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES = 64 * 1024;
+const pgDumpTargets = new WeakSet();
+const nativeToolTargets = new WeakSet();
+const protocolConnectionTargets = new WeakSet();
+const transactionPinnedTargets = new WeakSet();
+/** @internal Publish a promise before starting reentrant ownership teardown. */
+export function createWasixDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((accept, decline) => {
+        resolve = accept;
+        reject = decline;
+    });
+    return { promise, resolve, reject };
+}
+/** @internal Validate the explicit PostgreSQL startup identity once at open. */
+export function normalizeWasixDatabaseIdentity(username, database) {
+    assertWasixStartupIdentityValue('username', username);
+    assertWasixStartupIdentityValue('database', database);
+    return { username, database };
+}
+function assertWasixStartupIdentityValue(name, value) {
+    if (value.trim().length === 0)
+        throw new TypeError(`${name} must not be empty`);
+    if (value.includes('\0'))
+        throw new TypeError(`${name} must not contain NUL bytes`);
+}
+/**
+ * Tracks only session owners, never their public database handles.
+ *
+ * The finalizer's held value is an opaque generation token. The session lives
+ * in a separately keyed table, so an already queued finalizer can atomically
+ * prove that it still owns the exact registration before scheduling cleanup.
+ *
+ * @internal
+ */
+export class WasixForgottenDatabaseRegistry {
+    #active = new Map();
+    #finalizer;
+    #schedule;
+    constructor(createRegistry = (cleanup) => new FinalizationRegistry(cleanup), schedule = queueMicrotask) {
+        this.#schedule = schedule;
+        this.#finalizer = createRegistry((generation) => this.#finalize(generation));
+    }
+    register(owner, session) {
+        // Object identity is the generation. It cannot wrap, be forged by a stale
+        // callback, or retain the public owner through the held value.
+        const generation = Object.freeze({});
+        this.#finalizer.register(owner, generation, generation);
+        this.#active.set(generation, session);
+        return Object.freeze({ generation });
+    }
+    unregister(registration) {
+        // Remove the cleanup authority first. A finalizer callback that was already
+        // queued then observes a stale generation and is a harmless no-op.
+        this.#active.delete(registration.generation);
+        this.#finalizer.unregister(registration.generation);
+    }
+    #finalize(generation) {
+        const session = this.#active.get(generation);
+        if (session === undefined)
+            return;
+        this.#active.delete(generation);
+        // Finalization callbacks must stay nonblocking. Caller-realm teardown may
+        // execute synchronous guest code, so even invoking close is deferred until
+        // after the callback returns. Cleanup is intentionally unobservable best
+        // effort; explicit close remains the only way to observe its outcome.
+        this.#schedule(() => {
+            void closeForgottenSession(session).catch(() => undefined);
+        });
+    }
+}
+async function closeForgottenSession(session) {
+    if (session.abort !== undefined) {
+        await session.abort();
+        return;
+    }
+    await session.close();
+}
+const forgottenDatabaseRegistry = typeof FinalizationRegistry === 'undefined' ? undefined : new WasixForgottenDatabaseRegistry();
+/** @internal Public database state machine; construction stays behind Oliphaunt.open(). */
+export class WasixDatabaseImpl {
+    #session;
+    #identity;
+    #forgottenRegistry;
+    #forgottenRegistration;
+    #resources = new Set();
+    #pendingProtocolConnections = new Set();
+    #tail = Promise.resolve();
+    #closed = false;
+    #closing = false;
+    #closeAttempt;
+    #persistenceFailure;
+    #transactionFailure;
+    #activeTransaction = false;
+    #transactionRunning = false;
+    #streamCallbackActive = false;
+    constructor(session, forgottenRegistry = forgottenDatabaseRegistry) {
+        this.#session = session;
+        this.#forgottenRegistry = forgottenRegistry;
+        this.#forgottenRegistration = forgottenRegistry?.register(this, session);
+        this.#identity = session.identity ?? {
+            username: 'postgres',
+            database: 'postgres',
+        };
+        if (session.runPgDump !== undefined)
+            pgDumpTargets.add(this);
+        if (session.runTool !== undefined)
+            nativeToolTargets.add(this);
+        if (session.supportsProtocolConnections === true && session.serve !== undefined) {
+            protocolConnectionTargets.add(this);
+        }
+    }
+    get closed() {
+        return this.#closed || this.#session.terminalState?.terminal === true;
+    }
+    async execute(sql, parameters = [], options = {}) {
+        this.#assertAvailable();
+        const plan = planQuery(sql, parameters, snapshotParameterOptions(options));
+        return this.#serialize(() => this.#runDatabasePlanUnlocked(plan, parseCommandResponse));
+    }
+    async query(sql, parameters = [], options = {}) {
+        this.#assertAvailable();
+        const stableOptions = snapshotQueryOptions(options);
+        const plan = planQuery(sql, parameters, stableOptions);
+        return this.#serialize(() => this.#runDatabasePlanUnlocked(plan, (response) => decodeQueryResult(parseQueryRawResponse(response), stableOptions)));
+    }
+    async queryRaw(sql, parameters = [], options = {}) {
+        this.#assertAvailable();
+        const plan = planQuery(sql, parameters, snapshotParameterOptions(options));
+        return this.#serialize(() => this.#runDatabasePlanUnlocked(plan, parseQueryRawResponse));
+    }
+    async exec(sql, options = {}) {
+        this.#assertAvailable();
+        const input = structuredSimpleQuery(sql);
+        const stableOptions = snapshotReadOptions(options);
+        return this.#serialize(() => this.#runDatabaseStructuredUnlocked(input, (response) => parseExecResponse(response, stableOptions)));
+    }
+    async describe(sql, parameterTypeOids = []) {
+        this.#assertAvailable();
+        const input = describeQuery(sql, [...parameterTypeOids]);
+        return this.#serialize(() => this.#runDatabaseStructuredUnlocked(input, parseDescribeResponse));
+    }
+    async execProtocolRaw(input) {
+        return this.#execOwned(toUint8Array(input).slice());
+    }
+    async execProtocolRawStream(input, onChunk) {
+        if (typeof onChunk !== 'function') {
+            throw new TypeError('raw protocol stream callback must be a function');
+        }
+        const consumer = this.#protocolChunkConsumer(onChunk);
+        this.#assertAvailable();
+        const bytes = toUint8Array(input).slice();
+        await this.#serialize(async () => {
+            this.#assertHealthy();
+            if (this.#session.execStream === undefined) {
+                let response;
+                try {
+                    response = await this.#session.exec(bytes, 'sync');
+                }
+                catch (error) {
+                    this.#recordUnknownExchange(error, 'streaming PostgreSQL transport outcome is unknown');
+                    throw error;
+                }
+                for (let offset = 0; offset < response.length; offset += WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES) {
+                    consumer.callback(response.slice(offset, offset + WASIX_PROTOCOL_CALLBACK_CHUNK_BYTES));
+                }
+                return;
+            }
+            let outcome;
+            try {
+                outcome = await this.#session.execStream(bytes, consumer.callback, 'sync');
+            }
+            catch (error) {
+                this.#recordUnknownExchange(error, 'streaming PostgreSQL transport outcome is unknown');
+                throw error;
+            }
+            this.#resolveProtocolStreamOutcome(outcome, consumer.failure);
+        });
+    }
+    async backup() {
+        this.#assertAvailable();
+        return this.#serialize(async () => {
+            this.#assertHealthy();
+            if (this.#session.backup === undefined) {
+                throw new Error('this WASIX execution session does not support physical backup');
+            }
+            const bytes = await this.#session.backup();
+            await this.#syncPersistence('operation');
+            return bytes;
+        });
+    }
+    /** @internal Run pg_dump in the database-owning execution realm without another transport. */
+    runPgDump(options) {
+        this.#assertAvailable();
+        return this.#serialize(async () => {
+            this.#assertHealthy();
+            if (this.#session.runPgDump === undefined) {
+                throw new Error('this WASIX database entrypoint does not support pg_dump');
+            }
+            return this.#session.runPgDump(options);
+        });
+    }
+    /** @internal Run a packaged tool without the legacy Wasmer tool worker. */
+    runNativeTool(options) {
+        this.#assertAvailable();
+        return this.#serialize(async () => {
+            this.#assertHealthy();
+            if (this.#session.runTool === undefined) {
+                throw new Error('this WASIX database entrypoint does not support native tools');
+            }
+            return this.#session.runTool(options);
+        });
+    }
+    /** @internal Serialized connection ownership used by optional server/tool packages. */
+    runProtocolConnection(connection, mode) {
+        return this.reserveProtocolConnection(connection, mode).start();
+    }
+    /** @internal Reserve call order without entering the guest before a client is ready. */
+    reserveProtocolConnection(connection, mode) {
+        this.#assertAvailable();
+        let state = 'pending';
+        let cancellation;
+        let resolveStart;
+        const startDecision = new Promise((resolve) => {
+            resolveStart = resolve;
+        });
+        const pending = {
+            cancel(error) {
+                if (state !== 'pending')
+                    return;
+                state = 'canceled';
+                cancellation = error;
+                resolveStart?.(false);
+            },
+        };
+        this.#pendingProtocolConnections.add(pending);
+        const serving = this.#serialize(async () => {
+            const start = await startDecision;
+            this.#pendingProtocolConnections.delete(pending);
+            if (!start)
+                return;
+            this.#assertHealthy();
+            if (this.#session.serve === undefined) {
+                throw new Error('this WASIX database entrypoint does not support protocol connections');
+            }
+            if (!this.#session.supportsProtocolConnections) {
+                throw new Error('WASIX psql and local servers require @oliphaunt/wasix-ts/worker');
+            }
+            try {
+                await this.#session.serve(connection, mode);
+            }
+            catch (error) {
+                if (error instanceof WasixStorageError)
+                    this.#persistenceFailure = error;
+                throw error;
+            }
+        });
+        return {
+            start() {
+                if (state === 'canceled') {
+                    throw cancellation ?? new Error('Oliphaunt WASIX protocol connection was canceled');
+                }
+                if (state === 'pending') {
+                    state = 'started';
+                    resolveStart?.(true);
+                }
+                return serving;
+            },
+            cancel() {
+                pending.cancel(new Error('Oliphaunt WASIX protocol connection was canceled before start'));
+            },
+        };
+    }
+    #execOwned(bytes) {
+        this.#assertAvailable();
+        return this.#serialize(async () => {
+            // A persistence failure may have been ahead of this operation in the
+            // serialized queue. Recheck here so queued work cannot run against the
+            // unpublished, deliberately poisoned generation.
+            this.#assertHealthy();
+            try {
+                return await this.#session.exec(bytes, 'sync');
+            }
+            catch (error) {
+                if (error instanceof WasixStorageError)
+                    this.#persistenceFailure = error;
+                throw error;
+            }
+        });
+    }
+    async #runDatabasePlanUnlocked(plan, decode) {
+        if (plan.kind === 'complete') {
+            return this.#runDatabaseStructuredUnlocked(plan.input, decode);
+        }
+        const describedExchange = await this.#exchangeKnownUnlocked(plan.input, 'database');
+        if (describedExchange.status !== 'idle') {
+            return this.#finishDatabaseExchangeUnlocked(describedExchange, parseDescribeResponse, 'operation');
+        }
+        let description;
+        try {
+            description = parseDescribeResponse(describedExchange.response);
+        }
+        catch (error) {
+            return this.#publishLogicalFailureUnlocked(error, 'operation');
+        }
+        let input;
+        try {
+            input = plan.bind(description.parameterTypeOids);
+        }
+        catch (error) {
+            return this.#publishLogicalFailureUnlocked(errorWithNotices(error, description.notices), 'operation');
+        }
+        const finalExchange = await this.#exchangeKnownUnlocked(input, 'database');
+        return this.#finishDatabaseExchangeUnlocked(finalExchange, (response) => {
+            try {
+                return prependNotices(decode(response), description.notices);
+            }
+            catch (error) {
+                throw errorWithNotices(error, description.notices);
+            }
+        }, 'operation');
+    }
+    async #runDatabaseStructuredUnlocked(input, decode, boundary = 'operation') {
+        const exchange = await this.#exchangeKnownUnlocked(input, 'database');
+        return this.#finishDatabaseExchangeUnlocked(exchange, decode, boundary);
+    }
+    async #finishDatabaseExchangeUnlocked(exchange, decode, boundary) {
+        if (exchange.status !== 'idle') {
+            await this.#executeTransactionControlUnlocked('ROLLBACK');
+        }
+        let result;
+        let failure;
+        try {
+            result = decode(exchange.response);
+            if (exchange.status !== 'idle') {
+                failure = new Error(`structured database operation ended with PostgreSQL transaction status ${exchange.status}; Oliphaunt rolled it back`);
+                if (isNoticeCarrier(result)) {
+                    failure = errorWithNotices(failure, result.notices);
+                }
+            }
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            await this.#syncPersistence(boundary);
+        }
+        catch (persistenceError) {
+            if (failure !== undefined) {
+                throw composeWasixStorageFailure(persistenceError, 'operation also failed', failure);
+            }
+            throw persistenceError;
+        }
+        if (failure !== undefined)
+            throw failure;
+        return result;
+    }
+    async #publishLogicalFailureUnlocked(failure, boundary) {
+        try {
+            await this.#syncPersistence(boundary);
+        }
+        catch (persistenceError) {
+            throw composeWasixStorageFailure(persistenceError, 'operation also failed', failure);
+        }
+        throw failure;
+    }
+    async #runTransactionPlanUnlocked(plan, decode) {
+        if (plan.kind === 'complete') {
+            return this.#runTransactionStructuredUnlocked(plan.input, decode);
+        }
+        const described = await this.#runTransactionStructuredUnlocked(plan.input, parseDescribeResponse);
+        let input;
+        try {
+            input = plan.bind(described.parameterTypeOids);
+        }
+        catch (error) {
+            throw errorWithNotices(error, described.notices);
+        }
+        try {
+            return prependNotices(await this.#runTransactionStructuredUnlocked(input, decode), described.notices);
+        }
+        catch (error) {
+            throw errorWithNotices(error, described.notices);
+        }
+    }
+    async #runTransactionStructuredUnlocked(input, decode) {
+        const exchange = await this.#exchangeKnownUnlocked(input, 'transaction');
+        return decode(exchange.response);
+    }
+    async #exchangeKnownUnlocked(input, scope) {
+        this.#assertHealthy();
+        let response;
+        try {
+            response = await this.#session.exec(input, 'defer');
+        }
+        catch (error) {
+            this.#recordUnknownExchange(error, 'structured PostgreSQL transport outcome is unknown');
+            throw error;
+        }
+        let status;
+        try {
+            status =
+                scope === 'transaction'
+                    ? inspectManagedTransactionResponse(response)
+                    : inspectReadyForQuery(response);
+        }
+        catch (error) {
+            this.#recordUnknownExchange(error, 'structured PostgreSQL response has no valid readiness boundary');
+            throw error;
+        }
+        return { response, status };
+    }
+    async #executeTransactionControlUnlocked(sql) {
+        const exchange = await this.#exchangeKnownUnlocked(extendedQuery(sql, []), 'control');
+        let result;
+        try {
+            result = parseCommandResponse(exchange.response);
+        }
+        catch (error) {
+            if (sql === 'BEGIN' && exchange.status !== 'idle') {
+                await this.#executeTransactionControlUnlocked('ROLLBACK').catch(() => undefined);
+            }
+            else if (sql !== 'BEGIN') {
+                this.#transactionFailure = asError(error, `${sql} outcome is unknown`);
+            }
+            throw error;
+        }
+        if (sql === 'BEGIN') {
+            if (result.commandTag === 'BEGIN' && exchange.status === 'transaction')
+                return undefined;
+            const error = transactionBoundaryError(sql, result.commandTag, exchange.status);
+            if (exchange.status !== 'idle') {
+                await this.#executeTransactionControlUnlocked('ROLLBACK');
+            }
+            throw error;
+        }
+        if (sql === 'COMMIT') {
+            if (result.commandTag === 'COMMIT' && exchange.status === 'idle')
+                return 'committed';
+            if (result.commandTag === 'ROLLBACK' && exchange.status === 'idle')
+                return 'rolledBack';
+        }
+        else if (result.commandTag === 'ROLLBACK' && exchange.status === 'idle') {
+            return undefined;
+        }
+        const error = transactionBoundaryError(sql, result.commandTag, exchange.status);
+        this.#transactionFailure = error;
+        throw error;
+    }
+    #recordUnknownExchange(error, message) {
+        if (error instanceof WasixStorageError) {
+            this.#persistenceFailure = error;
+        }
+        else {
+            this.#transactionFailure ??= asError(error, message);
+        }
+    }
+    #resolveProtocolStreamOutcome(outcome, failure) {
+        try {
+            resolveProtocolStreamOutcome(outcome, failure);
+        }
+        catch (error) {
+            if (error instanceof WasixProtocolStreamInvariantError) {
+                this.#recordUnknownExchange(error, 'streaming PostgreSQL transport outcome is unknown');
+            }
+            throw error;
+        }
+    }
+    async transaction(body) {
+        this.#assertAvailable();
+        if (typeof body !== 'function') {
+            throw new TypeError('Oliphaunt WASIX transaction body must be a function');
+        }
+        this.#activeTransaction = true;
+        transactionPinnedTargets.add(this);
+        const attempt = this.#serialize(async () => {
+            // A close may cancel this transaction while it is still queued behind
+            // an unstarted protocol reservation. Once execution enters PostgreSQL,
+            // close remains prohibited until the callback transaction is finished.
+            this.#assertOpen();
+            this.#transactionRunning = true;
+            const transaction = new WasixTransactionImpl((plan, decode) => this.#runTransactionPlanUnlocked(plan, decode), (input, decode) => this.#runTransactionStructuredUnlocked(input, decode), () => this.#executeTransactionControlUnlocked('ROLLBACK').then(() => undefined));
+            try {
+                try {
+                    await this.#executeTransactionControlUnlocked('BEGIN');
+                }
+                catch (error) {
+                    if (this.#transactionFailure === undefined && this.#persistenceFailure === undefined) {
+                        try {
+                            await this.#syncPersistence('operation');
+                        }
+                        catch (persistenceError) {
+                            throw composeWasixStorageFailure(persistenceError, 'transaction also failed', error);
+                        }
+                    }
+                    throw error;
+                }
+                let result;
+                try {
+                    result = await body(transaction);
+                    await transaction.sealAndDrain();
+                }
+                catch (error) {
+                    transaction.seal();
+                    await transaction.drain();
+                    let rolledBack = transaction.rolledBack;
+                    let rollbackFailure;
+                    if (transaction.rollbackStarted) {
+                        try {
+                            await transaction.waitForRollback();
+                            rolledBack = transaction.rolledBack;
+                        }
+                        catch (rollbackError) {
+                            rollbackFailure = rollbackError;
+                        }
+                    }
+                    else if (this.#transactionFailure === undefined &&
+                        this.#persistenceFailure === undefined) {
+                        try {
+                            await this.#executeTransactionControlUnlocked('ROLLBACK');
+                            rolledBack = true;
+                        }
+                        catch (rollbackError) {
+                            rollbackFailure = rollbackError;
+                        }
+                    }
+                    if (rollbackFailure !== undefined && rollbackFailure !== error) {
+                        throw transactionCallbackAggregate(error, rollbackFailure, 'transaction callback and rollback both failed');
+                    }
+                    if (rolledBack) {
+                        try {
+                            await this.#syncPersistence('operation');
+                        }
+                        catch (persistenceError) {
+                            throw composeWasixStorageFailure(persistenceError, 'transaction also failed', error);
+                        }
+                    }
+                    const sessionFailure = this.#persistenceFailure ?? this.#transactionFailure;
+                    const databaseFailure = sessionFailure === undefined ? undefined : (transaction.firstFailure ?? sessionFailure);
+                    if (databaseFailure !== undefined && databaseFailure !== error) {
+                        throw transactionCallbackAggregate(error, databaseFailure, 'transaction callback and an independent database failure both occurred');
+                    }
+                    throw error;
+                }
+                if (transaction.rolledBack) {
+                    await this.#syncPersistence('operation');
+                    return result;
+                }
+                if (this.#transactionFailure !== undefined && transaction.firstFailure !== undefined) {
+                    throw transaction.firstFailure;
+                }
+                const outcome = await this.#executeTransactionControlUnlocked('COMMIT');
+                if (outcome === 'committed') {
+                    await this.#syncPersistence('operation');
+                    return result;
+                }
+                const primary = transaction.firstFailure ??
+                    new Error('PostgreSQL rolled back the transaction instead of committing');
+                try {
+                    await this.#syncPersistence('operation');
+                }
+                catch (persistenceError) {
+                    throw composeWasixStorageFailure(persistenceError, 'transaction also failed', primary);
+                }
+                throw primary;
+            }
+            finally {
+                transaction.deactivate();
+                this.#transactionRunning = false;
+            }
+        });
+        return await attempt.finally(() => {
+            this.#activeTransaction = false;
+            transactionPinnedTargets.delete(this);
+        });
+    }
+    close() {
+        try {
+            this.#assertNotInProtocolStreamCallback();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        if (this.#closeAttempt !== undefined) {
+            return this.#closeAttempt;
+        }
+        if (this.#transactionRunning) {
+            return Promise.reject(new Error('cannot close Oliphaunt WASIX while a transaction is active'));
+        }
+        if (this.#forgottenRegistration !== undefined) {
+            this.#forgottenRegistry?.unregister(this.#forgottenRegistration);
+        }
+        this.#closing = true;
+        const closing = new Error('Oliphaunt WASIX database is closing');
+        for (const connection of this.#pendingProtocolConnections)
+            connection.cancel(closing);
+        const orderlyClose = this.#serialize(() => this.#session.close());
+        const sessionClose = this.#session.abort === undefined
+            ? orderlyClose
+            : withDeadline(orderlyClose, CLOSE_DEADLINE_MS, () => this.#session.abort?.());
+        const attempt = (async () => {
+            let sessionFailed = false;
+            let sessionFailure;
+            try {
+                await sessionClose;
+            }
+            catch (error) {
+                sessionFailed = true;
+                sessionFailure = error;
+            }
+            let cleanupFailed = false;
+            let cleanupFailure;
+            try {
+                await this.#closeResources();
+            }
+            catch (error) {
+                cleanupFailed = true;
+                cleanupFailure = error;
+            }
+            finally {
+                // Session close is a terminal ownership transfer, not a retryable
+                // operation. Worker close always destroys its transport, while direct
+                // close always attempts provider and allocation release. Advertising a
+                // reusable handle after either path rejects would be false.
+                this.#closed = true;
+                this.#closing = false;
+            }
+            if (sessionFailed && cleanupFailed) {
+                throw new AggregateError([sessionFailure, cleanupFailure], 'Oliphaunt WASIX database and resource cleanup both failed');
+            }
+            if (sessionFailed)
+                throw sessionFailure;
+            if (cleanupFailed)
+                throw cleanupFailure;
+        })();
+        this.#closeAttempt = attempt;
+        return attempt;
+    }
+    /** @internal Register package-owned state that must not outlive this database. */
+    registerResource(resource) {
+        this.#assertAvailable();
+        this.#resources.add(resource);
+    }
+    /** @internal Identity used by private protocol clients such as pg_dump and psql. */
+    get identity() {
+        return this.#identity;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    #assertOpen() {
+        this.#assertNotInProtocolStreamCallback();
+        const terminalFailure = this.#session.terminalState?.failure;
+        if (this.#closed || terminalFailure !== undefined) {
+            throw new Error('Oliphaunt WASIX database is closed', {
+                ...(terminalFailure === undefined ? {} : { cause: terminalFailure }),
+            });
+        }
+        if (this.#closing) {
+            throw new Error('Oliphaunt WASIX database is closing');
+        }
+        this.#assertHealthy();
+    }
+    #assertAvailable() {
+        this.#assertOpen();
+        if (this.#activeTransaction) {
+            throw new Error(transactionPinnedMessage);
+        }
+    }
+    #assertHealthy() {
+        if (this.#transactionFailure !== undefined) {
+            throw new Error('Oliphaunt WASIX database cannot be used after a transaction outcome became unknown; close and reopen it', { cause: this.#transactionFailure });
+        }
+        if (this.#persistenceFailure !== undefined) {
+            throw new WasixStorageError('Oliphaunt WASIX database cannot be used after a persistence boundary failed; close and reopen it', {
+                code: this.#persistenceFailure.code,
+                commitState: this.#persistenceFailure.commitState,
+                cause: this.#persistenceFailure,
+            });
+        }
+    }
+    #assertNotInProtocolStreamCallback() {
+        if (this.#streamCallbackActive) {
+            throw new Error('raw protocol stream callback must not reenter the same Oliphaunt database or transaction');
+        }
+    }
+    #protocolChunkConsumer(callback) {
+        return synchronousProtocolChunkConsumer(callback, () => {
+            this.#assertNotInProtocolStreamCallback();
+            this.#streamCallbackActive = true;
+        }, () => {
+            this.#streamCallbackActive = false;
+        });
+    }
+    async #syncPersistence(boundary) {
+        try {
+            await this.#session.sync(boundary);
+        }
+        catch (error) {
+            const failure = error instanceof WasixStorageError
+                ? error
+                : new WasixStorageError(`WASIX persistence ${boundary} failed`, {
+                    code: 'publication-failed',
+                    commitState: 'unknown',
+                    cause: error,
+                });
+            // PostgreSQL may already have completed the operation in the live
+            // filesystem. No later query may widen the gap after publication fails.
+            this.#persistenceFailure = failure;
+            throw failure;
+        }
+    }
+    #serialize(operation) {
+        const result = this.#tail.then(operation, operation);
+        this.#tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async #closeResources() {
+        const resources = [...this.#resources];
+        // Every registered owner gets exactly one teardown attempt. Drop the
+        // ownership graph before awaiting userland cleanup so a failed terminal
+        // close cannot retain otherwise collectible resources indefinitely.
+        this.#resources.clear();
+        const results = await Promise.allSettled(resources.map(async (resource) => resource.close()));
+        const failures = [];
+        for (let index = 0; index < results.length; index += 1) {
+            const result = results[index];
+            if (result.status === 'rejected') {
+                failures.push(result.reason);
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, 'Oliphaunt WASIX database resource cleanup failed');
+        }
+    }
+}
+/** @internal Optional packages acquire exclusive ownership without expanding the public class. */
+export function runWasixProtocolConnection(database, connection, mode) {
+    assertWasixProtocolConnectionTarget(database);
+    return database.runProtocolConnection(connection, mode);
+}
+/** @internal Execute pg_dump in the realm that owns this database. */
+export function runWasixPgDumpProcess(database, options) {
+    assertWasixPgDumpTarget(database);
+    return database.runPgDump(options);
+}
+/** @internal Return undefined only when this realm uses the browser Wasmer backend. */
+export function tryRunWasixNativeToolProcess(database, options) {
+    assertWasixDatabaseTarget(database);
+    if (!nativeToolTargets.has(database))
+        return undefined;
+    return database.runNativeTool(options);
+}
+/** @internal Reserve a Worker-owned connection in the database FIFO. */
+export function reserveWasixProtocolConnection(database, connection, mode) {
+    assertWasixProtocolConnectionTarget(database);
+    return database.reserveProtocolConnection(connection, mode);
+}
+/** @internal Fail before loading a tool or opening a listener for unsupported placement. */
+export function assertWasixProtocolConnectionTarget(database) {
+    assertWasixDatabaseTarget(database);
+    if (!protocolConnectionTargets.has(database)) {
+        throw new Error('WASIX psql and local servers require @oliphaunt/wasix-ts/worker');
+    }
+}
+/** @internal Accept both public entrypoints that own the co-located runner. */
+function assertWasixPgDumpTarget(database) {
+    assertWasixDatabaseTarget(database);
+    if (!pgDumpTargets.has(database)) {
+        throw new Error('this WASIX database entrypoint does not support pg_dump');
+    }
+}
+function assertWasixDatabaseTarget(database) {
+    if (!(database instanceof WasixDatabaseImpl)) {
+        throw new TypeError('database is not an @oliphaunt/wasix-ts handle');
+    }
+    if (transactionPinnedTargets.has(database)) {
+        throw new Error(transactionPinnedMessage);
+    }
+}
+/** @internal Attach an optional-package resource without adding public database methods. */
+export function registerWasixDatabaseResource(database, resource) {
+    assertWasixProtocolConnectionTarget(database);
+    database.registerResource(resource);
+}
+/** @internal Return the exact startup identity owned by a WASIX database handle. */
+export function getWasixDatabaseIdentity(database) {
+    assertWasixDatabaseTarget(database);
+    return database.identity;
+}
+function withDeadline(operation, milliseconds, expire) {
+    return new Promise((resolve, reject) => {
+        let expired = false;
+        const timer = setTimeout(() => {
+            expired = true;
+            const timeout = new WasixCloseTimeoutError(milliseconds);
+            void Promise.resolve()
+                .then(expire)
+                .then(() => reject(timeout), (abortFailure) => reject(new AggregateError([timeout, abortFailure], 'Oliphaunt WASIX orderly close timed out and forced termination failed')));
+        }, milliseconds);
+        void operation.then((value) => {
+            if (expired)
+                return;
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            if (expired)
+                return;
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+function transactionCallbackAggregate(callback, secondary, message) {
+    return new AggregateError([callback, secondary], message);
+}
+class WasixCloseTimeoutError extends Error {
+    constructor(milliseconds) {
+        super(`Oliphaunt WASIX close exceeded ${milliseconds}ms; worker termination was requested`);
+        this.name = 'WasixCloseTimeoutError';
+    }
+}
+class WasixTransactionImpl {
+    #runPlan;
+    #runStructured;
+    #rollbackControl;
+    #tail = Promise.resolve();
+    #state = 'active';
+    #failed = false;
+    #firstFailure;
+    #rollbackAttempt;
+    #rolledBack = false;
+    constructor(runPlan, runStructured, rollbackControl) {
+        this.#runPlan = runPlan;
+        this.#runStructured = runStructured;
+        this.#rollbackControl = rollbackControl;
+    }
+    get closed() {
+        return this.#state === 'closed';
+    }
+    get rollbackStarted() {
+        return this.#rollbackAttempt !== undefined;
+    }
+    get rolledBack() {
+        return this.#rolledBack;
+    }
+    get firstFailure() {
+        return this.#firstFailure;
+    }
+    execute(sql, parameters = [], options = {}) {
+        return this.#publicPromise(() => {
+            assertNoTransactionChain(sql);
+            const plan = planQuery(sql, parameters, snapshotParameterOptions(options));
+            return this.#enqueue(() => this.#runPlan(plan, parseCommandResponse));
+        });
+    }
+    query(sql, parameters = [], options = {}) {
+        return this.#publicPromise(() => {
+            assertNoTransactionChain(sql);
+            const stableOptions = snapshotQueryOptions(options);
+            const plan = planQuery(sql, parameters, stableOptions);
+            return this.#enqueue(async () => decodeQueryResult(await this.#runPlan(plan, parseQueryRawResponse), stableOptions));
+        });
+    }
+    queryRaw(sql, parameters = [], options = {}) {
+        return this.#publicPromise(() => {
+            assertNoTransactionChain(sql);
+            const plan = planQuery(sql, parameters, snapshotParameterOptions(options));
+            return this.#enqueue(() => this.#runPlan(plan, parseQueryRawResponse));
+        });
+    }
+    exec(sql, options = {}) {
+        return this.#publicPromise(() => {
+            assertNoTransactionChain(sql);
+            const input = structuredSimpleQuery(sql);
+            const stableOptions = snapshotReadOptions(options);
+            return this.#enqueue(() => this.#runStructured(input, (response) => parseExecResponse(response, stableOptions)));
+        });
+    }
+    describe(sql, parameterTypeOids = []) {
+        return this.#publicPromise(() => {
+            const input = describeQuery(sql, [...parameterTypeOids]);
+            return this.#enqueue(() => this.#runStructured(input, parseDescribeResponse));
+        });
+    }
+    rollback() {
+        try {
+            this.#assertActive();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        this.#state = 'finishing';
+        const operation = this.#enqueueFinishing(this.#rollbackControl);
+        const attempt = operation.then(() => {
+            this.#rolledBack = true;
+            this.#state = 'closed';
+        }, (error) => {
+            this.#state = 'closed';
+            throw error;
+        });
+        this.#rollbackAttempt = attempt;
+        return attempt;
+    }
+    deactivate() {
+        this.#state = 'closed';
+    }
+    seal() {
+        if (this.#state === 'active')
+            this.#state = 'finishing';
+    }
+    async drain() {
+        await this.#tail;
+    }
+    async sealAndDrain() {
+        this.seal();
+        await this.#tail;
+        await this.#rollbackAttempt;
+    }
+    async waitForRollback() {
+        await this.#rollbackAttempt;
+    }
+    #assertActive() {
+        if (this.#state === 'finishing')
+            throw new Error('transaction is finishing');
+        if (this.#state === 'closed')
+            throw new Error('transaction is no longer active');
+    }
+    #publicPromise(operation) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    #enqueue(operation) {
+        try {
+            this.#assertActive();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return this.#enqueueFinishing(operation);
+    }
+    #enqueueFinishing(operation) {
+        const result = this.#tail.then(operation);
+        this.#tail = result.then(() => undefined, (error) => {
+            if (!this.#failed) {
+                this.#failed = true;
+                this.#firstFailure = error;
+            }
+        });
+        return result;
+    }
+}
+function snapshotParameterOptions(options) {
+    return Object.freeze({
+        ...(options.encoders === undefined ? {} : { encoders: Object.freeze({ ...options.encoders }) }),
+    });
+}
+function snapshotReadOptions(options) {
+    return Object.freeze({
+        rowMode: options.rowMode,
+        valueMode: options.valueMode,
+        ...(options.decoders === undefined ? {} : { decoders: Object.freeze({ ...options.decoders }) }),
+    });
+}
+function snapshotQueryOptions(options) {
+    return Object.freeze({
+        ...snapshotReadOptions(options),
+        ...snapshotParameterOptions(options),
+    });
+}
+function prependNotices(result, notices) {
+    if (notices.length > 0)
+        result.notices.unshift(...notices);
+    return result;
+}
+function isNoticeCarrier(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        Array.isArray(value.notices));
+}
+function transactionBoundaryError(expected, actual, status) {
+    return new Error(`PostgreSQL transaction command expected ${expected} with its matching readiness status, got ${actual ?? 'no command tag'} with ${status}`);
+}
+function synchronousProtocolChunkConsumer(callback, enter = () => undefined, leave = () => undefined) {
+    const consumer = {
+        callback(chunk) {
+            enter();
+            try {
+                const result = callback(chunk);
+                if (!isThenable(result))
+                    return;
+                // The returned task cannot participate in synchronous backpressure.
+                // Mark its rejection handled before failing deterministically.
+                void Promise.resolve(result).catch(() => undefined);
+                throw new TypeError('raw protocol stream callback must complete synchronously and must not return a Promise or thenable');
+            }
+            catch (error) {
+                consumer.failure ??= { error };
+                throw error;
+            }
+            finally {
+                leave();
+            }
+        },
+    };
+    return consumer;
+}
+function resolveProtocolStreamOutcome(outcome, failure) {
+    if (outcome === 'callbackAborted' && failure === undefined) {
+        throw new WasixProtocolStreamInvariantError('WASIX runtime confirmed protocol callback recovery without a retained callback failure');
+    }
+    if (outcome === 'complete' && failure !== undefined) {
+        throw new WasixProtocolStreamInvariantError('WASIX runtime reported protocol stream success after rejecting its callback');
+    }
+    if (failure !== undefined) {
+        throw failure.error;
+    }
+}
+class WasixProtocolStreamInvariantError extends Error {
+}
+function isThenable(value) {
+    return (((typeof value === 'object' && value !== null) || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+function asError(value, fallback) {
+    if (value instanceof Error)
+        return value;
+    return new Error(fallback, { cause: value });
+}