@oliphaunt/wasix-ts 0.1.0

package/lib/archive.js

@@ -0,0 +1,336 @@
+import { readPackageAsset } from './asset-source.js';
+import { decompressZstd } from './zstd.js';
+const BLOCK_SIZE = 512;
+const MAX_ARCHIVE_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 512 * 1024 * 1024;
+const MAX_ENTRIES = 65_536;
+const MAX_PATH_BYTES = 1_024;
+const MAX_PATH_DEPTH = 64;
+const ZSTD_MAGIC = [0x28, 0xb5, 0x2f, 0xfd];
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export function extractTar(archive) {
+    if (archive.length > MAX_ARCHIVE_BYTES) {
+        throw new Error(`tar archive exceeds the ${MAX_ARCHIVE_BYTES}-byte extraction limit`);
+    }
+    const files = new Map();
+    const directories = new Set();
+    const explicitPaths = new Set();
+    let offset = 0;
+    let nextPax;
+    let globalPax = {};
+    let nextLongName;
+    let entries = 0;
+    while (offset + BLOCK_SIZE <= archive.length) {
+        const header = archive.subarray(offset, offset + BLOCK_SIZE);
+        offset += BLOCK_SIZE;
+        if (isZeroBlock(header)) {
+            if (nextPax !== undefined || nextLongName !== undefined) {
+                throw new Error('tar archive ends with dangling per-entry path metadata');
+            }
+            if (offset + BLOCK_SIZE > archive.length ||
+                !isZeroBlock(archive.subarray(offset, offset + BLOCK_SIZE)) ||
+                archive.subarray(offset + BLOCK_SIZE).some((byte) => byte !== 0)) {
+                throw new Error('tar archive has an invalid terminator');
+            }
+            return { files, directories };
+        }
+        validateTarHeaderFormat(header);
+        entries += 1;
+        if (entries > MAX_ENTRIES)
+            throw new Error(`tar archive exceeds the ${MAX_ENTRIES}-entry limit`);
+        const type = String.fromCharCode(header[156] ?? 0).replace('\0', '') || '0';
+        const size = parseOctal(header.subarray(124, 136), 'tar entry size');
+        if (size > MAX_ENTRY_BYTES) {
+            throw new Error(`tar entry exceeds the ${MAX_ENTRY_BYTES}-byte size limit`);
+        }
+        const payloadEnd = offset + size;
+        if (payloadEnd > archive.length) {
+            throw new Error('tar archive ended in the middle of an entry payload');
+        }
+        const payload = archive.subarray(offset, payloadEnd);
+        offset += Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+        if (offset > archive.length) {
+            throw new Error('tar archive ended in the middle of entry padding');
+        }
+        const linkName = decodeTarString(header.subarray(157, 257)).replace(/\0.*$/, '');
+        if (linkName.length > 0) {
+            throw new Error('tar archive contains a non-empty link target');
+        }
+        if (type === 'x') {
+            if (nextPax !== undefined || nextLongName !== undefined) {
+                throw new Error('tar archive repeats per-entry path metadata before an entry');
+            }
+            nextPax = parsePaxPayload(payload);
+            validatePaxSemantics(nextPax);
+            continue;
+        }
+        if (type === 'g') {
+            const additions = parsePaxPayload(payload);
+            validatePaxSemantics(additions);
+            for (const key of Object.keys(additions)) {
+                if (Object.hasOwn(globalPax, key)) {
+                    throw new Error(`tar archive repeats global pax key: ${key}`);
+                }
+            }
+            globalPax = { ...globalPax, ...additions };
+            continue;
+        }
+        if (type === 'L') {
+            if (nextPax !== undefined || nextLongName !== undefined) {
+                throw new Error('tar archive repeats per-entry path metadata before an entry');
+            }
+            nextLongName = decodeTarString(payload).replace(/\0+$/, '');
+            continue;
+        }
+        const pax = { ...globalPax, ...(nextPax ?? {}) };
+        nextPax = undefined;
+        if ((pax.linkpath ?? '').length > 0) {
+            throw new Error('tar archive contains a non-empty pax link target');
+        }
+        const path = sanitizeTarPath(pax.path ?? nextLongName ?? tarHeaderPath(header));
+        nextLongName = undefined;
+        if (path === undefined) {
+            continue;
+        }
+        if (explicitPaths.has(path)) {
+            throw new Error(`tar archive repeats entry path: ${path}`);
+        }
+        explicitPaths.add(path);
+        const fileAncestor = parentPaths(path).find((ancestor) => files.has(ancestor));
+        if (fileAncestor !== undefined) {
+            throw new Error(`tar entry ${path} is nested below file: ${fileAncestor}`);
+        }
+        if (type === '5') {
+            if (size !== 0) {
+                throw new Error(`tar directory entry has a non-empty payload: ${path}`);
+            }
+            if (files.has(path)) {
+                throw new Error(`tar entry repeats an existing file as a directory: ${path}`);
+            }
+            addDirectoryWithAncestors(directories, path);
+            continue;
+        }
+        if (type !== '0') {
+            throw new Error(`unsupported tar entry type '${type}' for ${path}`);
+        }
+        if (directories.has(path)) {
+            throw new Error(`tar archive repeats entry path: ${path}`);
+        }
+        files.set(path, payload);
+    }
+    throw new Error('tar archive is missing its two-block terminator');
+}
+function validateTarHeaderFormat(header) {
+    const magic = decodeTarString(header.subarray(257, 263));
+    const version = decodeTarString(header.subarray(263, 265));
+    const posix = magic === 'ustar\0' && version === '00';
+    const gnu = magic === 'ustar ' && version === ' \0';
+    if (!posix && !gnu) {
+        throw new Error('tar entry does not use a supported ustar header');
+    }
+}
+function parentPaths(path) {
+    const segments = path.split('/');
+    const parents = [];
+    for (let length = 1; length < segments.length; length += 1) {
+        parents.push(segments.slice(0, length).join('/'));
+    }
+    return parents;
+}
+/** @internal Validate and project an extracted cluster seed for a `/base` mount. */
+export function clusterSeedMount(clusterSeed) {
+    const pgdataFiles = clusterSeed.files;
+    if (!pgdataFiles.has('PG_VERSION') || !pgdataFiles.has('global/pg_control')) {
+        throw new Error('cluster seed is missing PG_VERSION or global/pg_control');
+    }
+    return {
+        files: mapToDirectory(pgdataFiles),
+        directories: [...clusterSeed.directories],
+    };
+}
+/** @internal Materialize runtime support mounts without loading a cluster seed. */
+export function layoutRuntimeSupport(runtime) {
+    const runtimeFiles = runtime.files;
+    const module = runtimeFiles.get('oliphaunt/bin/postgres');
+    if (module === undefined || module.length === 0) {
+        throw new Error('runtime archive is missing oliphaunt/bin/postgres');
+    }
+    const mounts = {
+        '/home': { files: {}, directories: ['postgres'] },
+        '/tmp': { files: {}, directories: [] },
+    };
+    for (const [path, bytes] of runtimeFiles) {
+        const relative = stripPrefix(path, 'oliphaunt/');
+        const slash = relative.indexOf('/');
+        if (slash <= 0) {
+            continue;
+        }
+        const root = relative.slice(0, slash);
+        const child = relative.slice(slash + 1);
+        const mountPath = `/${root}`;
+        let mount = mounts[mountPath];
+        if (mount === undefined) {
+            mount = { files: {}, directories: [] };
+            mounts[mountPath] = mount;
+        }
+        mount.files[child] = bytes;
+    }
+    for (const path of runtime.directories) {
+        if (path === 'oliphaunt') {
+            continue;
+        }
+        const relative = stripPrefix(path, 'oliphaunt/');
+        const slash = relative.indexOf('/');
+        if (slash <= 0) {
+            continue;
+        }
+        const root = relative.slice(0, slash);
+        const child = relative.slice(slash + 1);
+        const mountPath = `/${root}`;
+        let mount = mounts[mountPath];
+        if (mount === undefined) {
+            mount = { files: {}, directories: [] };
+            mounts[mountPath] = mount;
+        }
+        mount.directories.push(child);
+    }
+    if (mounts['/base'] !== undefined) {
+        throw new Error('runtime archive must not provide the storage-owned /base mount');
+    }
+    for (const required of ['/bin', '/lib', '/share']) {
+        if (mounts[required] === undefined) {
+            throw new Error(`runtime archive did not produce required ${required} mount`);
+        }
+    }
+    return { module, mounts };
+}
+function addDirectoryWithAncestors(directories, path) {
+    const segments = path.split('/');
+    for (let index = 1; index <= segments.length; index += 1) {
+        directories.add(segments.slice(0, index).join('/'));
+    }
+}
+export async function loadAsset(source, label) {
+    if (source instanceof Uint8Array) {
+        return source;
+    }
+    if (source.startsWith('file:')) {
+        return readPackageAsset(source, label);
+    }
+    let response;
+    try {
+        response = await fetch(source);
+    }
+    catch (cause) {
+        throw new Error(`failed to fetch ${label} from ${JSON.stringify(source)}`, { cause });
+    }
+    if (!response.ok) {
+        throw new Error(`failed to fetch ${label} (${response.status} ${response.statusText})`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+export function decompressIfNeeded(bytes) {
+    const isZstd = ZSTD_MAGIC.every((byte, index) => bytes[index] === byte);
+    return isZstd ? decompressZstd(bytes) : bytes;
+}
+function mapToDirectory(files) {
+    return Object.fromEntries(files);
+}
+function stripPrefix(path, prefix) {
+    if (!path.startsWith(prefix)) {
+        throw new Error(`runtime tar entry is outside ${prefix}: ${path}`);
+    }
+    return path.slice(prefix.length);
+}
+function isZeroBlock(block) {
+    return block.every((byte) => byte === 0);
+}
+function parseOctal(bytes, label) {
+    const text = decodeTarString(bytes).replace(/\0.*$/, '').trim();
+    if (text.length === 0) {
+        return 0;
+    }
+    if (!/^[0-7]+$/.test(text)) {
+        throw new Error(`${label} is not an octal tar field`);
+    }
+    const value = Number.parseInt(text, 8);
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${label} is outside the safe integer range`);
+    }
+    return value;
+}
+function tarHeaderPath(header) {
+    const name = decodeTarString(header.subarray(0, 100)).replace(/\0.*$/, '');
+    const prefix = decodeTarString(header.subarray(345, 500)).replace(/\0.*$/, '');
+    return prefix.length > 0 ? `${prefix}/${name}` : name;
+}
+function sanitizeTarPath(path) {
+    if (path.includes('\\')) {
+        throw new Error(`tar entry path contains a backslash: ${path}`);
+    }
+    const normalized = path.replace(/^\.\/+/, '');
+    if (normalized.length === 0 || normalized === '.') {
+        return undefined;
+    }
+    if (normalized.startsWith('/')) {
+        throw new Error(`tar entry path must be relative: ${path}`);
+    }
+    if (normalized.includes('\0')) {
+        throw new Error('tar entry path contains a NUL byte');
+    }
+    const segments = normalized.split('/').filter((segment) => segment.length > 0);
+    if (textByteLength(normalized) > MAX_PATH_BYTES || segments.length > MAX_PATH_DEPTH) {
+        throw new Error(`tar entry path exceeds portability limits: ${path}`);
+    }
+    if (segments.some((segment) => segment === '.' || segment === '..')) {
+        throw new Error(`tar entry path escapes the install root: ${path}`);
+    }
+    return segments.join('/');
+}
+function textByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+function parsePaxPayload(payload) {
+    const values = {};
+    let offset = 0;
+    while (offset < payload.length) {
+        const space = payload.indexOf(0x20, offset);
+        if (space < 0) {
+            throw new Error('malformed pax header record');
+        }
+        const lengthText = decodeTarString(payload.subarray(offset, space));
+        if (!/^[0-9]+$/.test(lengthText)) {
+            throw new Error('invalid pax header record length');
+        }
+        const length = Number.parseInt(lengthText, 10);
+        if (!Number.isSafeInteger(length) || length <= 0) {
+            throw new Error('invalid pax header record length');
+        }
+        const recordEnd = offset + length;
+        if (recordEnd > payload.length || recordEnd <= space + 1 || payload[recordEnd - 1] !== 0x0a) {
+            throw new Error('malformed pax header key/value record');
+        }
+        const record = decodeTarString(payload.subarray(space + 1, recordEnd));
+        const equals = record.indexOf('=');
+        if (equals <= 0 || !record.endsWith('\n')) {
+            throw new Error('malformed pax header key/value record');
+        }
+        const key = record.slice(0, equals);
+        if (Object.hasOwn(values, key)) {
+            throw new Error(`pax header repeats key: ${key}`);
+        }
+        values[key] = record.slice(equals + 1, -1);
+        offset = recordEnd;
+    }
+    return values;
+}
+function validatePaxSemantics(values) {
+    for (const key of Object.keys(values)) {
+        if (key === 'size' || key === 'linkpath' || key.startsWith('GNU.sparse.')) {
+            throw new Error(`tar archive contains unsupported pax key: ${key}`);
+        }
+    }
+}
+function decodeTarString(bytes) {
+    return decoder.decode(bytes);
+}

package/lib/asset-source.d.ts

@@ -0,0 +1,4 @@
+export type PackageAssetReader = (source: URL) => Promise<Uint8Array>;
+/** @internal Installed by the active Node host realm for package-relative file URLs. */
+export declare function installPackageAssetReader(reader: PackageAssetReader): void;
+export declare function readPackageAsset(source: string, label: string): Promise<Uint8Array>;

package/lib/asset-source.js

@@ -0,0 +1,15 @@
+let packageAssetReader;
+/** @internal Installed by the active Node host realm for package-relative file URLs. */
+export function installPackageAssetReader(reader) {
+    if (packageAssetReader !== undefined) {
+        throw new Error('Oliphaunt WASIX package asset reader is already installed');
+    }
+    packageAssetReader = reader;
+}
+export async function readPackageAsset(source, label) {
+    const url = new URL(source);
+    if (url.protocol !== 'file:' || packageAssetReader === undefined) {
+        throw new Error(`cannot read package-relative ${label} URL ${JSON.stringify(source)}`);
+    }
+    return packageAssetReader(url);
+}

package/lib/byte-channel.d.ts

@@ -0,0 +1,27 @@
+/** @internal One bounded single-producer/single-consumer byte channel. */
+export type WasixByteChannel = Readonly<{
+    control: SharedArrayBuffer;
+    data: SharedArrayBuffer;
+}>;
+/** @internal Allocate the fixed-capacity transport used by tools and local sockets. */
+export declare function createWasixByteChannel(): WasixByteChannel;
+/** @internal Signal orderly producer EOF. */
+export declare function closeWasixByteChannel(channel: WasixByteChannel): void;
+/** @internal Signal an unrecoverable transport failure. */
+export declare function failWasixByteChannel(channel: WasixByteChannel): void;
+/** @internal Record that a tool has entered its PostgreSQL protocol callback. */
+export declare function markWasixByteChannelProtocolStarted(channel: WasixByteChannel): void;
+/** @internal Record successful process completion before exposing orderly EOF. */
+export declare function markWasixByteChannelProtocolComplete(channel: WasixByteChannel): void;
+/** @internal Observe protocol activity across the tool/database worker boundary. */
+export declare function wasixByteChannelProtocolStarted(channel: WasixByteChannel): boolean;
+/** @internal Whether a failed tool may have left an unobserved PostgreSQL outcome. */
+export declare function wasixByteChannelProtocolOutcomeUnknown(channel: WasixByteChannel): boolean;
+/** @internal Blocking read for a dedicated worker realm. Empty bytes mean EOF. */
+export declare function readWasixByteChannelSync(channel: WasixByteChannel, maximumBytes?: number): Uint8Array;
+/** @internal Blocking write for a dedicated worker realm. */
+export declare function writeWasixByteChannelSync(channel: WasixByteChannel, input: Uint8Array): void;
+/** @internal Non-blocking-realm read. Empty bytes mean EOF. */
+export declare function readWasixByteChannel(channel: WasixByteChannel, maximumBytes?: number): Promise<Uint8Array>;
+/** @internal Non-blocking-realm write with bounded backpressure. */
+export declare function writeWasixByteChannel(channel: WasixByteChannel, input: Uint8Array): Promise<void>;

package/lib/byte-channel.js

@@ -0,0 +1,170 @@
+const READ_OFFSET = 0;
+const WRITE_OFFSET = 1;
+const CLOSED = 2;
+const FAILED = 3;
+const PROTOCOL_STATE = 4;
+const CONTROL_WORDS = 5;
+const PROTOCOL_IDLE = 0;
+const PROTOCOL_ACTIVE = 1;
+const PROTOCOL_COMPLETE = 2;
+const WASIX_BYTE_CHANNEL_CHUNK_BYTES = 64 * 1024;
+const WASIX_CHANNEL_BYTES = 256 * 1024 + 1;
+/** @internal Allocate the fixed-capacity transport used by tools and local sockets. */
+export function createWasixByteChannel() {
+    return {
+        control: new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * CONTROL_WORDS),
+        data: new SharedArrayBuffer(WASIX_CHANNEL_BYTES),
+    };
+}
+/** @internal Signal orderly producer EOF. */
+export function closeWasixByteChannel(channel) {
+    const control = channelControl(channel);
+    Atomics.store(control, CLOSED, 1);
+    Atomics.notify(control, READ_OFFSET);
+    Atomics.notify(control, WRITE_OFFSET);
+}
+/** @internal Signal an unrecoverable transport failure. */
+export function failWasixByteChannel(channel) {
+    const control = channelControl(channel);
+    Atomics.store(control, FAILED, 1);
+    Atomics.store(control, CLOSED, 1);
+    Atomics.notify(control, READ_OFFSET);
+    Atomics.notify(control, WRITE_OFFSET);
+}
+/** @internal Record that a tool has entered its PostgreSQL protocol callback. */
+export function markWasixByteChannelProtocolStarted(channel) {
+    Atomics.store(channelControl(channel), PROTOCOL_STATE, PROTOCOL_ACTIVE);
+}
+/** @internal Record successful process completion before exposing orderly EOF. */
+export function markWasixByteChannelProtocolComplete(channel) {
+    Atomics.compareExchange(channelControl(channel), PROTOCOL_STATE, PROTOCOL_ACTIVE, PROTOCOL_COMPLETE);
+}
+/** @internal Observe protocol activity across the tool/database worker boundary. */
+export function wasixByteChannelProtocolStarted(channel) {
+    return Atomics.load(channelControl(channel), PROTOCOL_STATE) !== PROTOCOL_IDLE;
+}
+/** @internal Whether a failed tool may have left an unobserved PostgreSQL outcome. */
+export function wasixByteChannelProtocolOutcomeUnknown(channel) {
+    return Atomics.load(channelControl(channel), PROTOCOL_STATE) === PROTOCOL_ACTIVE;
+}
+/** @internal Blocking read for a dedicated worker realm. Empty bytes mean EOF. */
+export function readWasixByteChannelSync(channel, maximumBytes = WASIX_BYTE_CHANNEL_CHUNK_BYTES) {
+    const control = channelControl(channel);
+    const data = new Uint8Array(channel.data);
+    for (;;) {
+        assertChannelHealthy(control);
+        const read = Atomics.load(control, READ_OFFSET);
+        const write = Atomics.load(control, WRITE_OFFSET);
+        if (read !== write)
+            return consume(control, data, read, write, maximumBytes);
+        if (Atomics.load(control, CLOSED) !== 0)
+            return new Uint8Array();
+        Atomics.wait(control, WRITE_OFFSET, write);
+    }
+}
+/** @internal Blocking write for a dedicated worker realm. */
+export function writeWasixByteChannelSync(channel, input) {
+    const control = channelControl(channel);
+    const data = new Uint8Array(channel.data);
+    let offset = 0;
+    while (offset < input.length) {
+        assertChannelWritable(control);
+        const read = Atomics.load(control, READ_OFFSET);
+        const write = Atomics.load(control, WRITE_OFFSET);
+        const writable = writableBytes(read, write, data.length);
+        if (writable === 0) {
+            Atomics.wait(control, READ_OFFSET, read);
+            continue;
+        }
+        const copied = produce(control, data, write, input.subarray(offset), writable);
+        offset += copied;
+    }
+}
+/** @internal Non-blocking-realm read. Empty bytes mean EOF. */
+export async function readWasixByteChannel(channel, maximumBytes = WASIX_BYTE_CHANNEL_CHUNK_BYTES) {
+    const control = channelControl(channel);
+    const data = new Uint8Array(channel.data);
+    for (;;) {
+        assertChannelHealthy(control);
+        const read = Atomics.load(control, READ_OFFSET);
+        const write = Atomics.load(control, WRITE_OFFSET);
+        if (read !== write)
+            return consume(control, data, read, write, maximumBytes);
+        if (Atomics.load(control, CLOSED) !== 0)
+            return new Uint8Array();
+        await waitForChange(control, WRITE_OFFSET, write);
+    }
+}
+/** @internal Non-blocking-realm write with bounded backpressure. */
+export async function writeWasixByteChannel(channel, input) {
+    const control = channelControl(channel);
+    const data = new Uint8Array(channel.data);
+    let offset = 0;
+    while (offset < input.length) {
+        assertChannelWritable(control);
+        const read = Atomics.load(control, READ_OFFSET);
+        const write = Atomics.load(control, WRITE_OFFSET);
+        const writable = writableBytes(read, write, data.length);
+        if (writable === 0) {
+            await waitForChange(control, READ_OFFSET, read);
+            continue;
+        }
+        const copied = produce(control, data, write, input.subarray(offset), writable);
+        offset += copied;
+    }
+}
+function channelControl(channel) {
+    if (!(channel.control instanceof SharedArrayBuffer) ||
+        channel.control.byteLength !== Int32Array.BYTES_PER_ELEMENT * CONTROL_WORDS ||
+        !(channel.data instanceof SharedArrayBuffer) ||
+        channel.data.byteLength !== WASIX_CHANNEL_BYTES) {
+        throw new TypeError('invalid Oliphaunt WASIX byte channel');
+    }
+    return new Int32Array(channel.control);
+}
+function consume(control, data, read, write, maximumBytes) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes <= 0) {
+        throw new TypeError('maximum byte count must be a positive integer');
+    }
+    const available = write >= read ? write - read : data.length - read;
+    const count = Math.min(available, maximumBytes);
+    const output = data.slice(read, read + count);
+    Atomics.store(control, READ_OFFSET, (read + count) % data.length);
+    Atomics.notify(control, READ_OFFSET);
+    return output;
+}
+function writableBytes(read, write, capacity) {
+    if (write < read)
+        return read - write - 1;
+    if (read === 0)
+        return capacity - write - 1;
+    return capacity - write;
+}
+function produce(control, data, write, input, writable) {
+    const count = Math.min(writable, input.length, WASIX_BYTE_CHANNEL_CHUNK_BYTES);
+    data.set(input.subarray(0, count), write);
+    Atomics.store(control, WRITE_OFFSET, (write + count) % data.length);
+    Atomics.notify(control, WRITE_OFFSET);
+    return count;
+}
+function assertChannelHealthy(control) {
+    if (Atomics.load(control, FAILED) !== 0) {
+        throw new Error('Oliphaunt WASIX byte channel failed');
+    }
+}
+function assertChannelWritable(control) {
+    assertChannelHealthy(control);
+    if (Atomics.load(control, CLOSED) !== 0) {
+        throw new Error('Oliphaunt WASIX byte channel is closed');
+    }
+}
+async function waitForChange(control, index, expected) {
+    const waitAsync = Atomics.waitAsync;
+    if (waitAsync !== undefined) {
+        const waiting = waitAsync(control, index, expected);
+        if (waiting.async)
+            await waiting.value;
+        return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1));
+}

package/lib/client-common.d.ts

@@ -0,0 +1,6 @@
+import type { SerializedOpenOptions } from './rpc.js';
+import type { BinaryInput, OpenConfig, WasixRuntimeDescriptor } from './types.js';
+export declare function serializeOpenConfig(config?: OpenConfig, runtimeDescriptor?: WasixRuntimeDescriptor): SerializedOpenOptions;
+export declare function restoreWasix(storage: OpenConfig['storage'], bytes: BinaryInput, validate?: (options: SerializedOpenOptions) => void): Promise<void>;
+/** @internal Restore already-owned archive bytes inside the selected realm. */
+export declare function restoreWasixSerialized(storage: SerializedOpenOptions['storage'], bytes: Uint8Array): Promise<void>;

package/lib/client-common.js

@@ -0,0 +1,36 @@
+import defaultWasixRuntime from '@oliphaunt/liboliphaunt-wasix';
+import { serializeWasixExtensionDescriptors } from './extension-descriptor.js';
+import { serializeWasixIcuDescriptor } from './icu-descriptor.js';
+import { decodePhysicalArchive } from './physical-archive.js';
+import { toUint8Array } from './query.js';
+import { serializeWasixRuntimeDescriptor } from './runtime-descriptor.js';
+import { serializeWasixStorage } from './storage.js';
+import { restoreWasixStorage, WASIX_PHYSICAL_IDENTITY } from './storage-provider.js';
+import { normalizeWasixStartupGUCs } from './startup-config.js';
+export function serializeOpenConfig(config = {}, runtimeDescriptor = defaultWasixRuntime) {
+    const extensions = serializeWasixExtensionDescriptors(config.extensions ?? []);
+    const runtime = serializeWasixRuntimeDescriptor(runtimeDescriptor);
+    const storage = serializeWasixStorage(config.storage);
+    return {
+        runtime,
+        ...(config.icu === undefined ? {} : { icu: serializeWasixIcuDescriptor(config.icu) }),
+        extensionCarriers: extensions.carriers,
+        extensions: extensions.selectedSqlNames,
+        username: config.username ?? 'postgres',
+        database: config.database ?? 'postgres',
+        startupGUCs: normalizeWasixStartupGUCs(config.startupGUCs ?? {}),
+        storage,
+    };
+}
+export async function restoreWasix(storage, bytes, validate) {
+    if (storage === undefined)
+        throw new TypeError('WASIX restore requires persistent storage');
+    const openOptions = serializeOpenConfig({ storage });
+    validate?.(openOptions);
+    await restoreWasixSerialized(openOptions.storage, toUint8Array(bytes).slice());
+}
+/** @internal Restore already-owned archive bytes inside the selected realm. */
+export async function restoreWasixSerialized(storage, bytes) {
+    const snapshot = decodePhysicalArchive(bytes);
+    await restoreWasixStorage(storage, snapshot, WASIX_PHYSICAL_IDENTITY);
+}

package/lib/client.d.ts

@@ -0,0 +1,7 @@
+import { type DirectWasixHost } from './direct-client-common.js';
+import type { OliphauntClient, OliphauntDatabase, OpenConfig } from './types.js';
+/** Open PostgreSQL in the importing browser realm. Guest execution may block that realm. */
+export declare function openWasix(config?: OpenConfig): Promise<OliphauntDatabase>;
+/** @internal Dependency seam for root-entrypoint contract qualification. */
+export declare function openWasixWithHost(config: OpenConfig, loadHost: () => Promise<DirectWasixHost>): Promise<OliphauntDatabase>;
+export declare const Oliphaunt: OliphauntClient;

package/lib/client.js

@@ -0,0 +1,24 @@
+import { restoreWasix, serializeOpenConfig } from './client-common.js';
+import { openWasixDirect, } from './direct-client-common.js';
+/** Open PostgreSQL in the importing browser realm. Guest execution may block that realm. */
+export async function openWasix(config = {}) {
+    return openWasixWithHost(config, () => import('./host/index.mjs'));
+}
+/** @internal Dependency seam for root-entrypoint contract qualification. */
+export async function openWasixWithHost(config, loadHost) {
+    const openOptions = serializeOpenConfig(config);
+    if (globalThis.crossOriginIsolated !== true) {
+        throw new Error('@oliphaunt/wasix-ts requires COOP: same-origin and COEP: require-corp response headers');
+    }
+    const host = await loadHost();
+    return openWasixDirect(openOptions, host, browserRealm());
+}
+export const Oliphaunt = {
+    open: openWasix,
+    restore: restoreWasix,
+};
+function browserRealm() {
+    return typeof WorkerGlobalScope !== 'undefined' && globalThis instanceof WorkerGlobalScope
+        ? 'browser-worker'
+        : 'browser-main';
+}

package/lib/database-root.d.ts

@@ -0,0 +1,19 @@
+export declare const DATABASE_ROOT_DESCRIPTOR = ".oliphaunt.json";
+export declare const DATABASE_ROOT_SCHEMA = "oliphaunt-database-root-v1";
+export declare const DATABASE_ROOT_PGDATA = "pgdata";
+export declare const DATABASE_ROOT_POSTGRES_MAJOR: 18;
+export declare const WASIX_PHYSICAL_FORMAT: "wasix-pg18-v1";
+export declare const NATIVE_PHYSICAL_FORMAT = "native-pg18-v1";
+export type DatabaseRootDescriptor = Readonly<{
+    schema: typeof DATABASE_ROOT_SCHEMA;
+    engineFamily: 'native' | 'wasix';
+    pgdata: typeof DATABASE_ROOT_PGDATA;
+    postgresMajor: number;
+    physicalFormat: string;
+}>;
+export declare function wasixDatabaseRootDescriptor(): DatabaseRootDescriptor;
+export declare function parseDatabaseRootDescriptor(value: unknown): DatabaseRootDescriptor | undefined;
+/** Parse the root descriptor while rejecting duplicate JSON keys. */
+export declare function parseDatabaseRootDescriptorText(text: string): DatabaseRootDescriptor | undefined;
+/** Parse JSON while retaining the duplicate-key rejection lost by JSON.parse(). */
+export declare function parseJsonWithUniqueObjectKeys(text: string): unknown | undefined;