@oliphaunt/wasix-ts 0.1.0

package/lib/storage/opfs-provider.d.ts

@@ -0,0 +1,4 @@
+import type { WasixClusterSeedLoader, WasixPhysicalIdentity, WasixStorageLease } from '../storage-provider.js';
+import type { StoredSnapshot } from '../storage-snapshot.js';
+export declare function acquireOpfsStorage(name: string, loadClusterSeed: WasixClusterSeedLoader, physicalIdentity: WasixPhysicalIdentity): Promise<WasixStorageLease>;
+export declare function restoreOpfsStorage(name: string, snapshot: StoredSnapshot, physicalIdentity: WasixPhysicalIdentity): Promise<void>;

package/lib/storage/opfs-provider.js

@@ -0,0 +1,257 @@
+import { composeWasixStorageFailure, WasixStorageError } from '../errors.js';
+import { acquireIncrementalStorage } from './incremental-storage.js';
+import { applyPooledOpfsDelta, DirectOpfsPool, inspectPooledOpfsDatabase, openPooledDatabaseDirectory, openPooledOpfsRoot, preparePooledOpfsDatabase, } from './opfs-pool.js';
+import { releaseRestoreLock } from './restore-cleanup.js';
+import { acquireExclusiveWebLock } from './web-lock.js';
+const DIRECT_BRIDGE_CAPACITY = 1024 * 1024;
+export async function acquireOpfsStorage(name, loadClusterSeed, physicalIdentity) {
+    const label = `OPFS storage ${JSON.stringify(name)}`;
+    let lock;
+    let lockHandedToFallback = false;
+    let directPool;
+    let directAttempted = false;
+    try {
+        lock = await acquireExclusiveWebLock(`@oliphaunt/wasix-ts:opfs:${name}`, label);
+        if (canUseDirectOpfsPool()) {
+            directAttempted = true;
+            try {
+                directPool = await DirectOpfsPool.open(name, loadClusterSeed, physicalIdentity);
+            }
+            catch (error) {
+                if (!isDirectPoolUnavailable(error))
+                    throw normalizeOpfsOpenError(name, error);
+            }
+        }
+        if (directPool !== undefined) {
+            return new DirectOpfsLease(name, lock, directPool);
+        }
+        const database = await openPooledDatabaseDirectory(name);
+        let initializationState = 'new';
+        lockHandedToFallback = true;
+        return await acquireIncrementalStorage(label, loadClusterSeed, {
+            writeFailureCommitState: 'unknown',
+            acquireLock: async () => lock,
+            async openStore() {
+                return {
+                    async read() {
+                        // A failed direct acquisition has already reset an unpublished
+                        // generation. Placements that never attempted it reset here.
+                        const opened = await (directAttempted
+                            ? inspectPooledOpfsDatabase(database, name, physicalIdentity)
+                            : preparePooledOpfsDatabase(database, name, loadClusterSeed, physicalIdentity));
+                        initializationState = opened.state;
+                        return opened.snapshot;
+                    },
+                    initializationState: () => initializationState,
+                    apply: (delta) => applyPooledOpfsDelta(database, name, physicalIdentity, delta),
+                    close() { },
+                };
+            },
+        });
+    }
+    catch (error) {
+        if (lock !== undefined && !lockHandedToFallback) {
+            try {
+                await lock.release();
+            }
+            catch (releaseError) {
+                const primary = normalizeOpfsOpenError(name, error);
+                throw composeWasixStorageFailure(primary, 'ownership release also failed', releaseError);
+            }
+        }
+        throw normalizeOpfsOpenError(name, error);
+    }
+}
+export async function restoreOpfsStorage(name, snapshot, physicalIdentity) {
+    const label = `OPFS storage ${JSON.stringify(name)}`;
+    const lock = await acquireExclusiveWebLock(`@oliphaunt/wasix-ts:opfs:${name}`, label);
+    let root;
+    let cleanupDestination = false;
+    let destinationExisted = false;
+    let commitState = 'unchanged';
+    let failure;
+    try {
+        root = await openPooledOpfsRoot();
+        let database;
+        try {
+            database = await root.getDirectoryHandle(name);
+            destinationExisted = true;
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            database = await root.getDirectoryHandle(name, { create: true });
+        }
+        const destination = await inspectPooledOpfsDatabase(database, name, physicalIdentity);
+        if (destination.state === 'existing') {
+            throw new WasixStorageError(`${label} already exists`, {
+                code: 'incomplete',
+                commitState: 'unchanged',
+            });
+        }
+        cleanupDestination = true;
+        if (destination.snapshot !== undefined) {
+            // An initializing generation was never published and is disposable.
+            // Replace it instead of merging a restore over its unpublished seed contents.
+            await root.removeEntry(name, { recursive: true });
+            database = await root.getDirectoryHandle(name, { create: true });
+        }
+        commitState = 'unknown';
+        await applyPooledOpfsDelta(database, name, physicalIdentity, {
+            directories: snapshot.directories,
+            files: snapshot.files,
+            deleted: [],
+        });
+        cleanupDestination = false;
+        commitState = 'persisted';
+    }
+    catch (error) {
+        failure = error;
+        if (cleanupDestination && root !== undefined) {
+            try {
+                await root.removeEntry(name, { recursive: true });
+                if (destinationExisted) {
+                    await root.getDirectoryHandle(name, { create: true });
+                }
+                commitState = 'unchanged';
+            }
+            catch (cleanupError) {
+                failure = new AggregateError([error, cleanupError], `${label} restore cleanup failed`);
+                commitState = 'unknown';
+            }
+        }
+    }
+    finally {
+        failure = await releaseRestoreLock(lock, label, commitState, failure);
+    }
+    if (failure !== undefined)
+        throw failure;
+}
+class DirectOpfsLease {
+    state;
+    #name;
+    #lock;
+    #pool;
+    #directory;
+    #closed = false;
+    constructor(name, lock, pool) {
+        this.#name = name;
+        this.state = pool.state;
+        this.#lock = lock;
+        this.#pool = pool;
+    }
+    createPgdataDirectory = async (DirectoryConstructor) => {
+        if (this.#closed)
+            throw this.#unavailable('is closed', 'unchanged');
+        if (this.#directory !== undefined) {
+            throw this.#unavailable('already materialized its direct filesystem', 'unchanged');
+        }
+        if (typeof DirectoryConstructor.createSync !== 'function') {
+            throw this.#unavailable('requires a host with the direct filesystem bridge', 'unchanged');
+        }
+        const directory = DirectoryConstructor.createSync(this.#pool, DIRECT_BRIDGE_CAPACITY);
+        // Take ownership before validating the bridge so the normal close path
+        // releases a failed materialization exactly once.
+        this.#directory = directory;
+        const pgVersion = (await directory.readTextFile('PG_VERSION')).trim();
+        if (pgVersion.length === 0) {
+            throw this.#unavailable('direct filesystem returned an empty PG_VERSION', 'unchanged');
+        }
+        return directory;
+    };
+    async sync(_directory, boundary) {
+        if (this.#closed)
+            throw this.#unavailable('is closed', 'unchanged');
+        try {
+            await this.#pool.sync(boundary);
+        }
+        catch (error) {
+            if (error instanceof WasixStorageError)
+                throw error;
+            throw new WasixStorageError(`could not persist OPFS storage ${JSON.stringify(this.#name)}: ${describeError(error)}`, { code: 'publication-failed', commitState: 'unknown', cause: error });
+        }
+    }
+    async close(_directory, outcome) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        let failure;
+        let commitState = 'unknown';
+        if (outcome === 'clean') {
+            try {
+                await this.#pool.sync('close');
+                commitState = 'persisted';
+            }
+            catch (error) {
+                failure =
+                    error instanceof WasixStorageError
+                        ? error
+                        : new WasixStorageError(`OPFS storage ${JSON.stringify(this.#name)} could not persist on close`, { code: 'publication-failed', commitState: 'unknown', cause: error });
+            }
+        }
+        try {
+            await this.#pool.close(false);
+        }
+        catch (error) {
+            const cleanup = this.#unavailable(`could not close its pool: ${describeError(error)}`, commitState, error);
+            failure =
+                failure === undefined
+                    ? cleanup
+                    : composeWasixStorageFailure(failure, 'pool cleanup also failed', cleanup);
+        }
+        const directory = this.#directory;
+        this.#directory = undefined;
+        try {
+            directory?.free();
+        }
+        catch (error) {
+            const release = this.#unavailable(`could not release its host filesystem: ${describeError(error)}`, commitState, error);
+            failure =
+                failure === undefined
+                    ? release
+                    : composeWasixStorageFailure(failure, 'host filesystem release also failed', release);
+        }
+        try {
+            await this.#lock.release();
+        }
+        catch (error) {
+            const release = this.#unavailable(`closed but its ownership lock could not be released: ${describeError(error)}`, commitState, error);
+            failure =
+                failure === undefined
+                    ? release
+                    : composeWasixStorageFailure(failure, 'ownership release also failed', release);
+        }
+        if (failure !== undefined)
+            throw failure;
+    }
+    #unavailable(detail, commitState, cause) {
+        return new WasixStorageError(`OPFS storage ${JSON.stringify(this.#name)} ${detail}`, {
+            code: 'unavailable',
+            commitState,
+            ...(cause === undefined ? {} : { cause }),
+        });
+    }
+}
+function canUseDirectOpfsPool() {
+    return (typeof document === 'undefined' && globalThis.navigator?.storage?.getDirectory !== undefined);
+}
+function isDirectPoolUnavailable(error) {
+    const name = errorName(error);
+    return (name === 'NotSupportedError' ||
+        name === 'NoModificationAllowedError' ||
+        name === 'QuotaExceededError');
+}
+function normalizeOpfsOpenError(name, error) {
+    if (error instanceof WasixStorageError)
+        return error;
+    return new WasixStorageError(`could not open OPFS storage ${JSON.stringify(name)}: ${describeError(error)}`, { code: 'unavailable', commitState: 'unchanged', cause: error });
+}
+function isNotFound(error) {
+    return errorName(error) === 'NotFoundError';
+}
+function errorName(error) {
+    return typeof error === 'object' && error !== null && 'name' in error ? String(error.name) : '';
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/storage/opfs.d.ts

@@ -0,0 +1,8 @@
+import { type PersistentWasixStorage } from '../storage.js';
+/**
+ * Select an origin-private opaque database pool. Worker execution uses
+ * same-realm synchronous exact-range I/O; other placements publish to the
+ * same format through the portable journaled path.
+ */
+export declare function opfs(name: string): PersistentWasixStorage;
+export default opfs;

package/lib/storage/opfs.js

@@ -0,0 +1,10 @@
+import { defineOpfsStorage } from '../storage.js';
+/**
+ * Select an origin-private opaque database pool. Worker execution uses
+ * same-realm synchronous exact-range I/O; other placements publish to the
+ * same format through the portable journaled path.
+ */
+export function opfs(name) {
+    return defineOpfsStorage(name);
+}
+export default opfs;

package/lib/storage/restore-cleanup.d.ts

@@ -0,0 +1,4 @@
+import { type WasixStorageCommitState } from '../errors.js';
+import type { ExclusiveStorageLock } from './incremental-storage.js';
+/** Preserve a restore failure while making ownership-release failure observable. */
+export declare function releaseRestoreLock(lock: ExclusiveStorageLock, label: string, commitState: WasixStorageCommitState, primary: unknown): Promise<unknown>;

package/lib/storage/restore-cleanup.js

@@ -0,0 +1,22 @@
+import { composeWasixStorageFailure, WasixStorageError, } from '../errors.js';
+/** Preserve a restore failure while making ownership-release failure observable. */
+export async function releaseRestoreLock(lock, label, commitState, primary) {
+    try {
+        await lock.release();
+        return primary;
+    }
+    catch (error) {
+        const release = new WasixStorageError(`${label} ownership lock could not be released`, {
+            code: 'unavailable',
+            commitState,
+            cause: error,
+        });
+        if (primary instanceof Error) {
+            return composeWasixStorageFailure(primary, 'ownership release also failed', release);
+        }
+        if (primary !== undefined) {
+            return new AggregateError([primary, release], `${label} ownership release also failed`);
+        }
+        return release;
+    }
+}

package/lib/storage/web-lock.d.ts

@@ -0,0 +1,2 @@
+import type { ExclusiveStorageLock } from './incremental-storage.js';
+export declare function acquireExclusiveWebLock(lockName: string, label: string): Promise<ExclusiveStorageLock>;

package/lib/storage/web-lock.js

@@ -0,0 +1,64 @@
+import { WasixStorageError } from '../errors.js';
+export async function acquireExclusiveWebLock(lockName, label) {
+    const locks = globalThis.navigator.locks;
+    if (locks === undefined) {
+        throw new WasixStorageError(`${label} requires the browser Web Locks API`, {
+            code: 'unavailable',
+            commitState: 'unchanged',
+        });
+    }
+    let releaseHold;
+    const hold = new Promise((resolve) => {
+        releaseHold = resolve;
+    });
+    let acquisitionSettled = false;
+    let resolveAcquisition;
+    let rejectAcquisition;
+    const acquired = new Promise((resolve, reject) => {
+        resolveAcquisition = resolve;
+        rejectAcquisition = reject;
+    });
+    const request = locks
+        .request(lockName, { mode: 'exclusive', ifAvailable: true }, async (lock) => {
+        acquisitionSettled = true;
+        if (lock === null) {
+            resolveAcquisition?.(false);
+            return;
+        }
+        resolveAcquisition?.(true);
+        await hold;
+    })
+        .catch((error) => {
+        if (!acquisitionSettled)
+            rejectAcquisition?.(error);
+        throw error;
+    });
+    let available;
+    try {
+        available = await acquired;
+    }
+    catch (error) {
+        void request.catch(() => undefined);
+        throw new WasixStorageError(`could not acquire ownership of ${label}: ${describeError(error)}`, { code: 'unavailable', commitState: 'unchanged', cause: error });
+    }
+    if (!available) {
+        await request;
+        throw new WasixStorageError(`${label} is already open in this origin`, {
+            code: 'busy',
+            commitState: 'unchanged',
+        });
+    }
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            releaseHold?.();
+            await request;
+        },
+    };
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/storage-provider.d.ts

@@ -0,0 +1,47 @@
+import type { WasixDirectoryMount } from './archive.js';
+import type { Directory } from './host/index.mjs';
+import type { SerializedWasixStorage } from './storage.js';
+import type { StoredSnapshot } from './storage-snapshot.js';
+/** Stable fields that determine whether a WASIX runtime may open stored PGDATA. */
+export type WasixPhysicalIdentity = Readonly<{
+    schema: 'oliphaunt-physical-format-v1';
+    engineFamily: 'wasix';
+    postgresMajor: number;
+    physicalFormat: string;
+}>;
+export declare const WASIX_PHYSICAL_IDENTITY: WasixPhysicalIdentity;
+export type StorageDirectoryEntry = Readonly<{
+    type: 'dir' | 'file' | 'unknown';
+    name: string;
+}>;
+/** Narrow surface currently offered by Wasmer's in-memory `Directory`. */
+export type StorageDirectory = {
+    readDir(path: string): Promise<StorageDirectoryEntry[]>;
+    readFile(path: string): Promise<Uint8Array>;
+    /** Host-patched mutation journal. Older/untracked directories fall back to a full scan. */
+    changedPaths?(): readonly string[] | Promise<readonly string[]>;
+    clearChanges?(): void | Promise<void>;
+    entryType?(path: string): string | Promise<string>;
+};
+/** Internal publication strength; `full` is used for initialization, not SQL dispatch. */
+export type WasixStorageSyncBoundary = 'operation' | 'full' | 'close';
+/** Load the package-owned seed only after exclusive storage inspection finds a new root. */
+export type WasixClusterSeedLoader = () => Promise<WasixDirectoryMount>;
+export type WasixStorageLease = {
+    /** Whether PGDATA came from the packaged cluster seed or persistent storage. */
+    readonly state: 'new' | 'existing';
+    /** Initial contents for a portable `/base` Wasmer memory mount. */
+    readonly mount?: WasixDirectoryMount;
+    /** Optional direct PGDATA materializer; portable providers omit it. */
+    createPgdataDirectory?(DirectoryConstructor: typeof Directory): Promise<Directory>;
+    /** Complete the provider's PostgreSQL-safe persistence boundary. */
+    sync(directory: StorageDirectory, boundary: WasixStorageSyncBoundary): Promise<void>;
+    close(directory: StorageDirectory | undefined, outcome: 'clean' | 'failed'): Promise<void>;
+};
+/** Restore a validated snapshot into a closed, empty persistent destination. */
+export declare function restoreWasixStorage(storage: SerializedWasixStorage, snapshot: StoredSnapshot, identity: WasixPhysicalIdentity): Promise<void>;
+export declare function acquireWasixStorage(storage: SerializedWasixStorage, loadClusterSeed: WasixClusterSeedLoader, identity: WasixPhysicalIdentity): Promise<WasixStorageLease>;
+export declare function assertWasixPhysicalIdentity(identity: WasixPhysicalIdentity): WasixPhysicalIdentity;
+export declare function physicalIdentityMatches(stored: unknown, selected: WasixPhysicalIdentity): boolean;
+/** Stable JSON for hashing or comparing JSON-compatible runtime identities. */
+export declare function canonicalJson(value: unknown): string;

package/lib/storage-provider.js

@@ -0,0 +1,141 @@
+import { DATABASE_ROOT_POSTGRES_MAJOR, WASIX_PHYSICAL_FORMAT } from './database-root.js';
+import { WasixStorageError } from './errors.js';
+import { validateIndexedDbDatabaseName, validateOpfsDatabaseName } from './storage.js';
+export const WASIX_PHYSICAL_IDENTITY = Object.freeze({
+    schema: 'oliphaunt-physical-format-v1',
+    engineFamily: 'wasix',
+    postgresMajor: DATABASE_ROOT_POSTGRES_MAJOR,
+    physicalFormat: WASIX_PHYSICAL_FORMAT,
+});
+/** Restore a validated snapshot into a closed, empty persistent destination. */
+export async function restoreWasixStorage(storage, snapshot, identity) {
+    switch (storage.kind) {
+        case 'memory':
+            throw new WasixStorageError('physical restore requires persistent WASIX storage', {
+                code: 'unavailable',
+                commitState: 'unchanged',
+            });
+        case 'indexed-db': {
+            validateIndexedDbDatabaseName(storage.name);
+            const { restoreIndexedDbStorage } = await import('./storage/indexed-db-provider.js');
+            return restoreIndexedDbStorage(storage.name, snapshot, identity);
+        }
+        case 'opfs': {
+            validateOpfsDatabaseName(storage.name);
+            const { restoreOpfsStorage } = await import('./storage/opfs-provider.js');
+            return restoreOpfsStorage(storage.name, snapshot, identity);
+        }
+        case 'directory':
+            throw new WasixStorageError('directory restore is owned directly by the native Rust runtime', { code: 'unavailable', commitState: 'unchanged' });
+    }
+}
+export async function acquireWasixStorage(storage, loadClusterSeed, identity) {
+    if (storage.schema !== 'oliphaunt-wasix-storage-v1') {
+        throw new WasixStorageError('WASIX storage descriptor has an unsupported schema', {
+            code: 'unavailable',
+            commitState: 'unchanged',
+        });
+    }
+    switch (storage.kind) {
+        case 'memory':
+            return memoryLease(await loadClusterSeed());
+        case 'indexed-db': {
+            validateIndexedDbDatabaseName(storage.name);
+            const { acquireIndexedDbStorage } = await import('./storage/indexed-db-provider.js');
+            return acquireIndexedDbStorage(storage.name, loadClusterSeed, identity);
+        }
+        case 'opfs': {
+            validateOpfsDatabaseName(storage.name);
+            const { acquireOpfsStorage } = await import('./storage/opfs-provider.js');
+            return acquireOpfsStorage(storage.name, loadClusterSeed, identity);
+        }
+        case 'directory':
+            throw new WasixStorageError('directory storage is owned directly by the native Rust runtime', {
+                code: 'unavailable',
+                commitState: 'unchanged',
+            });
+    }
+}
+export function assertWasixPhysicalIdentity(identity) {
+    if (identity.schema !== WASIX_PHYSICAL_IDENTITY.schema ||
+        identity.engineFamily !== WASIX_PHYSICAL_IDENTITY.engineFamily ||
+        identity.postgresMajor !== WASIX_PHYSICAL_IDENTITY.postgresMajor ||
+        identity.physicalFormat !== WASIX_PHYSICAL_IDENTITY.physicalFormat) {
+        throw new TypeError('WASIX storage has an unsupported physical identity');
+    }
+    return identity;
+}
+export function physicalIdentityMatches(stored, selected) {
+    const storedKey = parseWasixPhysicalIdentity(stored);
+    if (storedKey === undefined) {
+        throw new TypeError('WASIX storage has malformed physical identity metadata');
+    }
+    const selectedKey = assertWasixPhysicalIdentity(selected);
+    return (storedKey.schema === selectedKey.schema &&
+        storedKey.engineFamily === selectedKey.engineFamily &&
+        storedKey.postgresMajor === selectedKey.postgresMajor &&
+        storedKey.physicalFormat === selectedKey.physicalFormat);
+}
+function parseWasixPhysicalIdentity(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const key = value;
+    const keys = Object.keys(key).sort();
+    if (keys.length !== 4 ||
+        keys[0] !== 'engineFamily' ||
+        keys[1] !== 'physicalFormat' ||
+        keys[2] !== 'postgresMajor' ||
+        keys[3] !== 'schema' ||
+        key.schema !== 'oliphaunt-physical-format-v1' ||
+        key.engineFamily !== 'wasix' ||
+        !Number.isInteger(key.postgresMajor) ||
+        key.postgresMajor <= 0 ||
+        typeof key.physicalFormat !== 'string' ||
+        key.physicalFormat.length === 0) {
+        return undefined;
+    }
+    return key;
+}
+/** Stable JSON for hashing or comparing JSON-compatible runtime identities. */
+export function canonicalJson(value) {
+    const active = new Set();
+    const canonicalize = (candidate) => {
+        if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
+            return candidate;
+        }
+        if (typeof candidate === 'number') {
+            if (!Number.isFinite(candidate)) {
+                throw new TypeError('JSON identity contains a non-finite number');
+            }
+            return candidate;
+        }
+        if (typeof candidate !== 'object') {
+            throw new TypeError('identity is not JSON-compatible');
+        }
+        if (active.has(candidate)) {
+            throw new TypeError('identity contains a cycle');
+        }
+        active.add(candidate);
+        try {
+            if (Array.isArray(candidate)) {
+                return candidate.map(canonicalize);
+            }
+            const record = candidate;
+            return Object.fromEntries(Object.keys(record)
+                .sort()
+                .map((key) => [key, canonicalize(record[key])]));
+        }
+        finally {
+            active.delete(candidate);
+        }
+    };
+    return JSON.stringify(canonicalize(value));
+}
+function memoryLease(clusterSeed) {
+    return {
+        state: 'new',
+        mount: clusterSeed,
+        async sync() { },
+        async close() { },
+    };
+}

package/lib/storage-snapshot.d.ts

@@ -0,0 +1,44 @@
+import type { WasixDirectoryMount } from './archive.js';
+import type { WasixStorageError } from './errors.js';
+import type { StorageDirectory } from './storage-provider.js';
+export declare const VOLATILE_DATABASE_FILES: Set<string>;
+export type StoredSnapshot = {
+    schema: 'oliphaunt-wasix-directory-snapshot-v1';
+    directories: string[];
+    files: {
+        path: string;
+        bytes: Uint8Array;
+    }[];
+};
+/** A current-state delta. Deletions and upserts are committed as one boundary. */
+export type StorageDelta = {
+    directories: string[];
+    files: {
+        path: string;
+        bytes: Uint8Array;
+    }[];
+    deleted: string[];
+};
+export type StorageEntryType = 'dir' | 'file';
+export declare function splitStorageDeltaDeletes(delta: StorageDelta): {
+    replacements: string[];
+    removals: string[];
+};
+export type SnapshotErrorContext = Readonly<{
+    label: string;
+    corrupt(detail: string, cause?: unknown): WasixStorageError;
+}>;
+export declare function snapshotStorageDirectory(directory: StorageDirectory, filter?: Readonly<{
+    skipFile?: (path: string) => boolean;
+    skipDirectoryContents?: (path: string) => boolean;
+}>): Promise<StoredSnapshot>;
+/**
+ * Read only journaled PGDATA paths, falling back to a complete snapshot when
+ * the host does not expose mutation tracking or no durable generation exists.
+ */
+export declare function snapshotStorageDelta(directory: StorageDirectory, persistedEntries: ReadonlyMap<string, StorageEntryType>, forceFull?: boolean): Promise<StorageDelta>;
+export declare function applyStorageDeltaToEntries(persistedEntries: Map<string, StorageEntryType>, delta: StorageDelta): void;
+export declare function validateStoredSnapshot(value: unknown, expectedPostgresMajor: string, context: SnapshotErrorContext): StoredSnapshot;
+export declare function snapshotToMount(snapshot: StoredSnapshot): WasixDirectoryMount;
+export declare function requireRecord(value: unknown, label: string): Record<string, unknown>;
+export declare function validateDirectoryEntryName(name: string): void;