@hachej/boring-files 0.0.0-stage → 0.2.1

package/dist/sqlite-filesystem.js

@@ -0,0 +1,423 @@
+import { FileError, LineScanner, err, ok } from '@earendil-works/pi-durable/env';
+import { randomUUID } from './platform.js';
+import { registerSqliteBatch } from './sqlite-batch.js';
+function normalize(path) {
+    const parts = [];
+    for (const part of path.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..')
+            parts.pop();
+        else
+            parts.push(part);
+    }
+    return `/${parts.join('/')}`;
+}
+const dirname = (path) => path.slice(0, path.lastIndexOf('/')) || '/';
+const basename = (path) => path.slice(path.lastIndexOf('/') + 1);
+const within = (base, path) => path === base || path.startsWith(base === '/' ? '/' : `${base}/`);
+// Results, errors and line scans are Pi's own (`@earendil-works/pi-durable/env`, its portable contracts: no engine), so this file
+// system answers exactly like Pi's environments.
+const fileError = (code, message, path) => new FileError(code, message, path);
+const isFileError = (error) => error instanceof FileError;
+/**
+ * How often a watcher compares snapshots. A write through this file system (this connection) is compared at once, right after
+ * its transaction; polling remains for writes through another connection to the same database (`mode: 'polling'`).
+ */
+const WATCH_INTERVAL_MS = 1000;
+/** A FileError whose message starts with the POSIX code, as shells and Git read it. */
+const failure = (code, errno, path, what) => fileError(code, `${errno}: ${what}, '${path}'`, path);
+const missing = (path) => failure('not_found', 'ENOENT', path, 'no such file or directory');
+export function openSqliteFileSystem(options) {
+    const { connection: db, workspace } = options;
+    if (typeof workspace !== 'string' || workspace === '')
+        throw new TypeError('A workspace name is required');
+    if (typeof options.cwd !== 'string' || !options.cwd.startsWith('/'))
+        throw new TypeError('An absolute working directory is required');
+    const now = () => Date.now();
+    function row(path) {
+        if (path === '/')
+            return { kind: 'directory', size: 0, mtime: 0 };
+        const found = db.get('SELECT kind, coalesce(length(bytes), 0) AS size, mtime_ms FROM boring_workspace_files WHERE workspace = ? AND path = ?', workspace, path);
+        return found ? { kind: found.kind, size: Number(found.size), mtime: Number(found.mtime_ms) } : undefined;
+    }
+    /** Why `path` does not exist: an ancestor that is a file makes it `ENOTDIR`, otherwise `ENOENT`. */
+    function absent(path) {
+        for (let ancestor = dirname(path); ancestor !== '/'; ancestor = dirname(ancestor)) {
+            const found = row(ancestor);
+            if (found)
+                return found.kind === 'directory' ? missing(path) : failure('not_directory', 'ENOTDIR', path, 'not a directory');
+        }
+        return missing(path);
+    }
+    function existing(path) {
+        const found = row(path);
+        if (!found)
+            throw absent(path);
+        return found;
+    }
+    function directory(path) {
+        if (existing(path).kind !== 'directory')
+            throw failure('not_directory', 'ENOTDIR', path, 'not a directory');
+    }
+    /** The parent of a path about to be created must be a directory; the error names the path. */
+    function parent(path) {
+        const found = row(dirname(path));
+        if (!found)
+            throw absent(path);
+        if (found.kind !== 'directory')
+            throw failure('not_directory', 'ENOTDIR', path, 'not a directory');
+    }
+    /** Paths written, renamed or removed by this file system since the last comparison: reported as changed even when size and time look alike. */
+    const touched = new Set();
+    function bytes(path) {
+        if (existing(path).kind === 'directory')
+            throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
+        const found = db.get('SELECT bytes FROM boring_workspace_files WHERE workspace = ? AND path = ?', workspace, path);
+        if (!(found?.bytes instanceof Uint8Array))
+            throw fileError('unknown', 'Invalid stored bytes', path);
+        return Uint8Array.from(found.bytes);
+    }
+    function put(path, kind, content) {
+        touched.add(path);
+        db.run('INSERT INTO boring_workspace_files (workspace, path, parent, kind, bytes, mtime_ms) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(workspace, path) DO UPDATE SET kind = excluded.kind, bytes = excluded.bytes, mtime_ms = excluded.mtime_ms', workspace, path, dirname(path), kind, content, now());
+    }
+    function write(path, content) {
+        if (path === '/')
+            throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
+        const found = row(path);
+        if (found?.kind === 'directory')
+            throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
+        // Like Pi's own environments (NodeExecutionEnv), a write creates the missing parent directories; a parent that is a file still fails.
+        if (!found) {
+            if (!row(dirname(path)))
+                makeDirectory(dirname(path), true);
+            parent(path);
+        }
+        put(path, 'file', content);
+    }
+    function makeDirectory(path, recursive) {
+        const found = row(path);
+        if (found) {
+            if (found.kind !== 'directory')
+                throw failure('invalid', 'EEXIST', path, 'file already exists');
+            if (!recursive)
+                throw failure('invalid', 'EEXIST', path, 'file already exists');
+            return;
+        }
+        if (recursive)
+            makeDirectory(dirname(path), true);
+        else
+            parent(path);
+        put(path, 'directory', null);
+    }
+    const children = (path) => db.all('SELECT path FROM boring_workspace_files WHERE workspace = ? AND parent = ? ORDER BY path', workspace, path).map(item => item.path);
+    /** Every row at or below `path`. */
+    const subtree = (path) => `workspace = ? AND (path = ? OR substr(path, 1, ?) = ?)`;
+    const subtreeArgs = (path) => [workspace, path, path.length + 1, `${path}/`];
+    const info = (path, found) => ({ name: basename(path), path, kind: found.kind === 'directory' ? 'directory' : 'file', size: found.size, mtimeMs: found.mtime });
+    db.transaction('write', () => {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS boring_workspaces (workspace TEXT PRIMARY KEY, incarnation TEXT NOT NULL) STRICT;
+      CREATE TABLE IF NOT EXISTS boring_workspace_files (
+        workspace TEXT NOT NULL, path TEXT NOT NULL, parent TEXT NOT NULL, kind TEXT NOT NULL, bytes BLOB, mtime_ms INTEGER NOT NULL,
+        PRIMARY KEY (workspace, path)
+      ) STRICT;
+      CREATE INDEX IF NOT EXISTS boring_workspace_files_parent ON boring_workspace_files (workspace, parent);
+    `);
+        db.run('INSERT OR IGNORE INTO boring_workspaces VALUES (?, ?)', workspace, randomUUID());
+        makeDirectory(normalize(options.cwd), true);
+    });
+    const incarnation = db.get('SELECT incarnation FROM boring_workspaces WHERE workspace = ?', workspace)?.incarnation;
+    if (typeof incarnation !== 'string')
+        throw new Error('The workspace has no incarnation');
+    /** Each open watcher's comparison, run right after a write through this file system commits. */
+    const watchers = new Set();
+    let notifying = false;
+    function notify() {
+        if (watchers.size === 0) {
+            touched.clear();
+            return;
+        }
+        if (notifying)
+            return;
+        notifying = true;
+        // After the current synchronous work: a batch write inside a caller's transaction is compared once it has committed.
+        queueMicrotask(() => { notifying = false; const paths = [...touched]; touched.clear(); for (const check of [...watchers])
+            check(paths); });
+    }
+    async function run(path, context, mode, work) {
+        if (context.abortSignal?.aborted)
+            return err(fileError('aborted', 'Operation aborted', path));
+        if (typeof path !== 'string' || path.includes('\0'))
+            return err(fileError('invalid', 'Invalid path', String(path)));
+        try {
+            const value = db.transaction(mode, () => work(normalize(path.startsWith('/') ? path : `${fs.cwd}/${path}`)));
+            if (mode === 'write')
+                notify();
+            return ok(value);
+        }
+        catch (error) {
+            return err(isFileError(error) ? error : fileError('unknown', error instanceof Error ? error.message : String(error), path));
+        }
+    }
+    async function temporary(prefix, suffix, kind, context) {
+        if (`${prefix}${suffix}`.includes('/'))
+            return err(fileError('invalid', 'Temporary names must be basenames'));
+        return run('/tmp', context, 'write', () => {
+            makeDirectory('/tmp', true);
+            const path = `/tmp/${prefix}${randomUUID()}${suffix}`;
+            put(path, kind, kind === 'file' ? new Uint8Array() : null);
+            return path;
+        });
+    }
+    const text = (path) => new TextDecoder().decode(bytes(path));
+    /** The size and modification time of every watched path, to compare between polls. */
+    function snapshot(targets) {
+        const seen = new Map();
+        const hidden = (name, target) => (target.exclude?.hidden && name.startsWith('.')) || target.exclude?.names?.includes(name);
+        for (const target of targets) {
+            const root = normalize(target.path.startsWith('/') ? target.path : `${fs.cwd}/${target.path}`), found = row(root);
+            seen.set(root, found ? `${found.kind}:${found.size}:${found.mtime}` : 'missing');
+            if (found?.kind !== 'directory')
+                continue;
+            const rows = target.recursive
+                ? db.all(`SELECT path, kind, coalesce(length(bytes), 0) AS size, mtime_ms FROM boring_workspace_files WHERE ${subtree(root)} AND path != ?`, ...subtreeArgs(root), root)
+                : db.all('SELECT path, kind, coalesce(length(bytes), 0) AS size, mtime_ms FROM boring_workspace_files WHERE workspace = ? AND parent = ?', workspace, root);
+            for (const item of rows) {
+                if (item.path.slice(root.length + (root === '/' ? 0 : 1)).split('/').some(name => hidden(name, target)))
+                    continue;
+                seen.set(item.path, `${item.kind}:${Number(item.size)}:${Number(item.mtime_ms)}`);
+            }
+        }
+        return seen;
+    }
+    const encode = (content) => typeof content === 'string' ? new TextEncoder().encode(content) : Uint8Array.from(content);
+    const fs = {
+        id: `sqlite:${workspace}`, cwd: normalize(options.cwd), incarnation,
+        absolutePath: (path, context) => run(path, context, 'read', absolute => absolute),
+        joinPath: async (parts, context) => {
+            if (context.abortSignal?.aborted)
+                return err(fileError('aborted', 'Operation aborted'));
+            const joined = parts.join('/');
+            return ok(joined.startsWith('/') ? normalize(joined) : normalize(`/${joined}`).slice(1) || '.');
+        },
+        readTextFile: (path, context) => run(path, context, 'read', text),
+        readBinaryFile: (path, context) => run(path, context, 'read', bytes),
+        // The reader holds the bytes as they were when opened: it keeps reading that file even if its path is renamed or rewritten.
+        // There are no symbolic links here, so `noFollow` changes nothing.
+        openBinaryReader: (path, _options, context) => run(path, context, 'read', absolute => {
+            const content = bytes(absolute), opened = info(absolute, existing(absolute));
+            let closed = false;
+            const guard = (inner) => inner.abortSignal?.aborted ? fileError('aborted', 'Operation aborted', absolute)
+                : closed ? fileError('invalid', 'Binary reader is closed', absolute) : undefined;
+            const reader = {
+                info: async (inner) => { const failed = guard(inner); return failed ? err(failed) : ok({ ...opened }); },
+                read: async (offset, length, inner) => {
+                    const failed = guard(inner);
+                    if (failed)
+                        return err(failed);
+                    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 0)
+                        return err(fileError('invalid', 'Offset and length must be non-negative integers', absolute));
+                    return ok(content.slice(offset, offset + length));
+                },
+                scanLines: async ({ startLine, endLine }, inner) => {
+                    const failed = guard(inner);
+                    if (failed)
+                        return err(failed);
+                    if (!Number.isSafeInteger(startLine) || startLine < 0 || (endLine !== undefined && (!Number.isSafeInteger(endLine) || endLine <= startLine))) {
+                        return err(fileError('invalid', 'Line range must be non-negative integers with endLine > startLine', absolute));
+                    }
+                    // Pi's own scanner over the bytes held in the row: the same answer as Pi's Node environment for the same file.
+                    const scanner = new LineScanner(startLine, endLine);
+                    scanner.push(content);
+                    return ok(scanner.finish());
+                },
+                close: async () => { closed = true; },
+            };
+            return reader;
+        }),
+        readTextLines: (path, options, context) => run(path, context, 'read', absolute => {
+            const lines = text(absolute).split('\n');
+            if (lines.at(-1) === '')
+                lines.pop();
+            return options?.maxLines === undefined ? lines : lines.slice(0, Math.max(0, options.maxLines));
+        }),
+        openTextLineReader: (path, context) => run(path, context, 'read', absolute => {
+            const content = text(absolute);
+            let offset = 0, closed = false;
+            const reader = {
+                readLine: async (inner) => {
+                    if (inner.abortSignal?.aborted)
+                        return err(fileError('aborted', 'Operation aborted', absolute));
+                    if (closed)
+                        return err(fileError('invalid', 'Text line reader is closed', absolute));
+                    if (offset === content.length)
+                        return ok(undefined);
+                    const newline = content.indexOf('\n', offset);
+                    const line = { text: content.slice(offset, newline === -1 ? undefined : newline), terminated: newline !== -1 };
+                    offset = newline === -1 ? content.length : newline + 1;
+                    return ok(line);
+                },
+                close: async () => { closed = true; },
+            };
+            return reader;
+        }),
+        writeFile: (path, content, context) => run(path, context, 'write', absolute => write(absolute, encode(content))),
+        appendFile: (path, content, context) => run(path, context, 'write', absolute => {
+            const added = encode(content);
+            if (!row(absolute))
+                return write(absolute, added);
+            const before = bytes(absolute), joined = new Uint8Array(before.length + added.length);
+            joined.set(before);
+            joined.set(added, before.length);
+            write(absolute, joined);
+        }),
+        truncateFile: (path, size, context) => run(path, context, 'write', absolute => {
+            if (!Number.isSafeInteger(size) || size < 0)
+                throw fileError('invalid', 'File size must be a non-negative safe integer', absolute);
+            const before = bytes(absolute), after = new Uint8Array(size);
+            after.set(before.subarray(0, size));
+            write(absolute, after);
+        }),
+        // Every write is already a committed SQLite transaction.
+        flushFile: (path, context) => run(path, context, 'read', absolute => { existing(absolute); }),
+        // One transaction: a reader sees the old or the new path, never both or neither. A directory moves with everything below it.
+        renameFile: (source, destination, context) => run(source, context, 'write', from => {
+            const to = normalize(destination.startsWith('/') ? destination : `${fs.cwd}/${destination}`);
+            const moved = existing(from);
+            if (from === to)
+                return;
+            touched.add(from);
+            touched.add(to);
+            if (from === '/' || within(from, to))
+                throw failure('invalid', 'EINVAL', to, 'cannot move a directory into itself');
+            const target = row(to);
+            if (target) {
+                if (moved.kind !== 'directory' && target.kind === 'directory')
+                    throw failure('is_directory', 'EISDIR', to, 'illegal operation on a directory');
+                if (moved.kind === 'directory' && target.kind !== 'directory')
+                    throw failure('not_directory', 'ENOTDIR', to, 'not a directory');
+                if (target.kind === 'directory' && children(to).length)
+                    throw failure('invalid', 'ENOTEMPTY', to, 'directory not empty');
+                db.run('DELETE FROM boring_workspace_files WHERE workspace = ? AND path = ?', workspace, to);
+            }
+            else
+                parent(to);
+            db.run(`UPDATE boring_workspace_files SET path = ? || substr(path, ?), parent = CASE WHEN path = ? THEN ? ELSE ? || substr(parent, ?) END WHERE ${subtree(from)}`, to, from.length + 1, from, dirname(to), to, from.length + 1, ...subtreeArgs(from));
+        }),
+        fileInfo: (path, context) => run(path, context, 'read', absolute => info(absolute, existing(absolute))),
+        listDir: (path, context) => run(path, context, 'read', absolute => {
+            directory(absolute);
+            return children(absolute).map(child => info(child, existing(child)));
+        }),
+        // The entries as they were when opened, in path order, paged by `next`.
+        openDirReader: (path, context) => run(path, context, 'read', absolute => {
+            directory(absolute);
+            const entries = children(absolute).map(child => info(child, existing(child)));
+            let offset = 0, closed = false;
+            const reader = {
+                next: async (maxEntries, inner) => {
+                    if (inner.abortSignal?.aborted)
+                        return err(fileError('aborted', 'Operation aborted', absolute));
+                    if (closed)
+                        return err(fileError('invalid', 'Directory reader is closed', absolute));
+                    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1)
+                        return err(fileError('invalid', 'maxEntries must be a positive integer', absolute));
+                    const page = entries.slice(offset, offset + maxEntries);
+                    offset += page.length;
+                    return ok({ entries: page, done: offset >= entries.length });
+                },
+                close: async () => { closed = true; },
+            };
+            return reader;
+        }),
+        // SQLite reports no changes, so the watcher compares snapshots of the watched rows: at once after each write through this file
+        // system, and every second for other connections. The first snapshot is taken before the watcher is returned, so a change made
+        // after `watch` resolves is always seen.
+        watch: async (targets, onChange, context) => {
+            if (context.abortSignal?.aborted)
+                return err(fileError('aborted', 'Operation aborted'));
+            if (!Array.isArray(targets) || targets.some(target => typeof target?.path !== 'string' || target.path.includes('\0')))
+                return err(fileError('invalid', 'Invalid watch target'));
+            let previous;
+            try {
+                previous = db.transaction('read', () => snapshot(targets));
+            }
+            catch (error) {
+                return err(isFileError(error) ? error : fileError('unknown', String(error)));
+            }
+            let stopped = false;
+            const report = (change) => { if (!stopped)
+                try {
+                    onChange(change);
+                }
+                catch { /* the host's callback cannot stop the watcher */ } };
+            const hidden = (name, target) => (target.exclude?.hidden && name.startsWith('.')) || target.exclude?.names?.includes(name);
+            /** Whether a path this file system just wrote lies under a watched target, as the snapshot would have listed it. */
+            const covered = (path) => targets.some(target => {
+                const root = normalize(target.path.startsWith('/') ? target.path : `${fs.cwd}/${target.path}`);
+                if (path === root)
+                    return true;
+                if (!within(root, path))
+                    return false;
+                const names = path.slice(root.length + (root === '/' ? 0 : 1)).split('/');
+                return (target.recursive || names.length === 1) && !names.some(name => hidden(name, target));
+            });
+            const check = (direct = []) => {
+                if (stopped)
+                    return;
+                let next;
+                try {
+                    next = db.transaction('read', () => snapshot(targets));
+                }
+                catch (error) {
+                    report({ error: isFileError(error) ? error : fileError('unknown', String(error)) });
+                    stop();
+                    return;
+                }
+                const written = new Set(direct.filter(covered));
+                const changed = [...new Set([...previous.keys(), ...next.keys(), ...written])].filter(path => written.has(path) || previous.get(path) !== next.get(path));
+                previous = next;
+                if (changed.length)
+                    report({ paths: changed });
+            };
+            const timer = setInterval(() => check(), WATCH_INTERVAL_MS);
+            const stop = () => { stopped = true; clearInterval(timer); watchers.delete(check); };
+            watchers.add(check);
+            const watcher = { mode: 'polling', close: async () => { stop(); } };
+            return ok(watcher);
+        },
+        canonicalPath: (path, context) => run(path, context, 'read', absolute => { existing(absolute); return absolute; }),
+        exists: (path, context) => run(path, context, 'read', absolute => row(absolute) !== undefined),
+        createDir: (path, options, context) => run(path, context, 'write', absolute => {
+            // Like `mkdir -p`, an existing directory is fine when recursive (the default).
+            if (options?.recursive !== false && row(absolute)?.kind === 'directory')
+                return;
+            makeDirectory(absolute, options?.recursive !== false);
+        }),
+        remove: (path, options, context) => run(path, context, 'write', absolute => {
+            const found = row(absolute);
+            if (!found) {
+                if (options?.force)
+                    return;
+                throw absent(absolute);
+            }
+            if (absolute === '/' || absolute === fs.cwd)
+                throw failure('permission_denied', 'EPERM', absolute, 'the workspace root cannot be removed');
+            if (found.kind === 'directory' && !options?.recursive && children(absolute).length)
+                throw failure('invalid', 'ENOTEMPTY', absolute, 'directory not empty');
+            touched.add(absolute);
+            db.run(`DELETE FROM boring_workspace_files WHERE ${subtree(absolute)}`, ...subtreeArgs(absolute));
+        }),
+        createTempDir: (prefix, context) => temporary(prefix ?? 'tmp-', '', 'directory', context),
+        createTempFile: (options, context) => temporary(options?.prefix ?? 'tmp-', options?.suffix ?? '', 'file', context),
+        cleanup: async () => { },
+    };
+    registerSqliteBatch(fs, {
+        connection: db,
+        bytes: path => { const found = row(normalize(path)); return !found ? null : found.kind === 'directory' ? undefined : bytes(normalize(path)); },
+        write: (path, content) => { const absolute = normalize(path); makeDirectory(dirname(absolute), true); write(absolute, content); notify(); },
+    });
+    return fs;
+}

package/dist/sqlite-settings.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The one place v4 chooses SQLite connection settings (journal mode, locking mode, busy timeout, synchronous, temp store).
+ * Every opener (`openNodeConnection`, `openNodeDatabase` for Pi's own storage, the browser's SQLite Wasm) takes a
+ * `SqliteSettings` and turns it into statements here; `npm run check` refuses `PRAGMA journal_mode` and `PRAGMA locking_mode`
+ * anywhere else. Values are allow-listed: there is no free-form pragma name or value, so a setting cannot inject SQL.
+ * Pure: no `node:*` import, safe in a browser bundle.
+ */
+/** `wal` needs shared memory between the connections of one host: never on a network file system. */
+export type SqliteJournalMode = 'wal' | 'delete' | 'truncate' | 'persist';
+/** `exclusive`: the connection takes the file's lock when it opens and keeps it until it closes (one owner per file). */
+export type SqliteLockingMode = 'normal' | 'exclusive';
+export type SqliteSynchronous = 'off' | 'normal' | 'full' | 'extra';
+export type SqliteTempStore = 'default' | 'file' | 'memory';
+export interface SqliteSettings {
+    readonly journalMode?: SqliteJournalMode;
+    readonly lockingMode?: SqliteLockingMode;
+    /** How long a statement waits for another connection's lock before failing with `database is locked`. 0 to 600 000 ms. */
+    readonly busyTimeoutMs?: number;
+    readonly synchronous?: SqliteSynchronous;
+    readonly tempStore?: SqliteTempStore;
+}
+/** Complete settings: what an opener applies after filling the caller's partial settings from `sqliteSettings.localDisk`. */
+export type ResolvedSqliteSettings = Required<SqliteSettings>;
+/**
+ * Presets. `localDisk` is the default of every v4 opener (and what `openNodeConnection` always did). `networkFilesystem` is for a
+ * file on NFS such as Amazon EFS, owned by one process (one writer per SQLite file, docs/architecture/HOST-RECIPE-AWS.md):
+ * rollback journal instead of WAL (WAL's shared-memory index is unsafe across hosts), the lock taken once at open and held
+ * (no per-transaction lock round trips; a second opener fails with `SqliteLockedError` instead of writing beside the owner),
+ * full sync, temporary tables in memory.
+ */
+export declare const sqliteSettings: {
+    readonly localDisk: ResolvedSqliteSettings;
+    readonly networkFilesystem: ResolvedSqliteSettings;
+};
+/** Checks `settings` and returns a frozen copy of the given fields only. Throws a `TypeError` naming the first invalid field. */
+export declare function validateSqliteSettings(settings: SqliteSettings): SqliteSettings;
+/** `settings` over `base` (the local-disk preset unless given), validated. */
+export declare function resolveSqliteSettings(settings?: SqliteSettings, base?: ResolvedSqliteSettings): ResolvedSqliteSettings;
+/**
+ * The statements for the given fields, in the order they must run: the busy timeout first (so the others wait for a lock),
+ * the locking mode before the journal mode (exclusive WAL then needs no shared memory).
+ */
+export declare function sqlitePragmas(settings: SqliteSettings): string[];
+/** The file is held by another connection (`lockingMode: 'exclusive'` elsewhere, or a writer that outlasted the busy timeout). */
+export declare class SqliteLockedError extends Error {
+    readonly filename: string;
+    readonly code = "sqlite-locked";
+    constructor(filename: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Applies resolved settings to an open database through its `exec`/`get`, checks the journal mode took effect (`memory` is what an
+ * in-memory database reports for any of them), and under `exclusive` takes the lock now with an empty exclusive transaction,
+ * so the owner is decided at open. A lock held elsewhere becomes `SqliteLockedError`.
+ */
+export declare function applySqliteSettings(db: {
+    readonly exec: (sql: string) => void;
+    readonly get: (sql: string) => Record<string, unknown> | undefined;
+}, settings: ResolvedSqliteSettings, filename: string): void;
+//# sourceMappingURL=sqlite-settings.d.ts.map

package/dist/sqlite-settings.js

@@ -0,0 +1,104 @@
+/**
+ * The one place v4 chooses SQLite connection settings (journal mode, locking mode, busy timeout, synchronous, temp store).
+ * Every opener (`openNodeConnection`, `openNodeDatabase` for Pi's own storage, the browser's SQLite Wasm) takes a
+ * `SqliteSettings` and turns it into statements here; `npm run check` refuses `PRAGMA journal_mode` and `PRAGMA locking_mode`
+ * anywhere else. Values are allow-listed: there is no free-form pragma name or value, so a setting cannot inject SQL.
+ * Pure: no `node:*` import, safe in a browser bundle.
+ */
+/**
+ * Presets. `localDisk` is the default of every v4 opener (and what `openNodeConnection` always did). `networkFilesystem` is for a
+ * file on NFS such as Amazon EFS, owned by one process (one writer per SQLite file, docs/architecture/HOST-RECIPE-AWS.md):
+ * rollback journal instead of WAL (WAL's shared-memory index is unsafe across hosts), the lock taken once at open and held
+ * (no per-transaction lock round trips; a second opener fails with `SqliteLockedError` instead of writing beside the owner),
+ * full sync, temporary tables in memory.
+ */
+export const sqliteSettings = Object.freeze({
+    localDisk: Object.freeze({ journalMode: 'wal', lockingMode: 'normal', busyTimeoutMs: 5000, synchronous: 'full', tempStore: 'default' }),
+    networkFilesystem: Object.freeze({ journalMode: 'delete', lockingMode: 'exclusive', busyTimeoutMs: 10000, synchronous: 'full', tempStore: 'memory' }),
+});
+const allowed = {
+    journalMode: ['wal', 'delete', 'truncate', 'persist'],
+    lockingMode: ['normal', 'exclusive'],
+    synchronous: ['off', 'normal', 'full', 'extra'],
+    tempStore: ['default', 'file', 'memory'],
+};
+const KEYS = new Set(['journalMode', 'lockingMode', 'busyTimeoutMs', 'synchronous', 'tempStore']);
+/** Checks `settings` and returns a frozen copy of the given fields only. Throws a `TypeError` naming the first invalid field. */
+export function validateSqliteSettings(settings) {
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings))
+        throw new TypeError('SQLite settings must be an object');
+    const copy = {};
+    for (const [key, value] of Object.entries(settings)) {
+        if (!KEYS.has(key))
+            throw new TypeError(`Unknown SQLite setting ${JSON.stringify(key)}`);
+        if (value === undefined)
+            continue;
+        if (key === 'busyTimeoutMs') {
+            if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 600_000)
+                throw new TypeError('busyTimeoutMs must be an integer from 0 to 600000');
+        }
+        else if (!allowed[key].includes(value)) {
+            throw new TypeError(`${key} must be one of ${allowed[key].join(', ')}`);
+        }
+        copy[key] = value;
+    }
+    return Object.freeze(copy);
+}
+/** `settings` over `base` (the local-disk preset unless given), validated. */
+export function resolveSqliteSettings(settings = {}, base = sqliteSettings.localDisk) {
+    return Object.freeze({ ...base, ...validateSqliteSettings(settings) });
+}
+/**
+ * The statements for the given fields, in the order they must run: the busy timeout first (so the others wait for a lock),
+ * the locking mode before the journal mode (exclusive WAL then needs no shared memory).
+ */
+export function sqlitePragmas(settings) {
+    const valid = validateSqliteSettings(settings), statements = [];
+    if (valid.busyTimeoutMs !== undefined)
+        statements.push(`PRAGMA busy_timeout = ${valid.busyTimeoutMs}`);
+    if (valid.lockingMode !== undefined)
+        statements.push(`PRAGMA locking_mode = ${valid.lockingMode.toUpperCase()}`);
+    if (valid.journalMode !== undefined)
+        statements.push(`PRAGMA journal_mode = ${valid.journalMode.toUpperCase()}`);
+    if (valid.synchronous !== undefined)
+        statements.push(`PRAGMA synchronous = ${valid.synchronous.toUpperCase()}`);
+    if (valid.tempStore !== undefined)
+        statements.push(`PRAGMA temp_store = ${valid.tempStore.toUpperCase()}`);
+    return statements;
+}
+/** The file is held by another connection (`lockingMode: 'exclusive'` elsewhere, or a writer that outlasted the busy timeout). */
+export class SqliteLockedError extends Error {
+    filename;
+    code = 'sqlite-locked';
+    constructor(filename, options) {
+        super(`The SQLite file ${filename} is locked by another connection (one writer per file); it was not opened`, options);
+        this.filename = filename;
+        this.name = 'SqliteLockedError';
+    }
+}
+const isLocked = (error) => /database is locked|SQLITE_BUSY|database table is locked/i.test(String(error?.message ?? ''));
+/**
+ * Applies resolved settings to an open database through its `exec`/`get`, checks the journal mode took effect (`memory` is what an
+ * in-memory database reports for any of them), and under `exclusive` takes the lock now with an empty exclusive transaction,
+ * so the owner is decided at open. A lock held elsewhere becomes `SqliteLockedError`.
+ */
+export function applySqliteSettings(db, settings, filename) {
+    try {
+        for (const statement of sqlitePragmas(settings)) {
+            if (!statement.startsWith('PRAGMA journal_mode')) {
+                db.exec(statement);
+                continue;
+            }
+            const mode = String(db.get(statement)?.journal_mode ?? '').toLowerCase();
+            if (mode !== settings.journalMode && mode !== 'memory')
+                throw new Error(`SQLite kept journal_mode ${mode || '(none)'} instead of ${settings.journalMode} for ${filename}`);
+        }
+        if (settings.lockingMode === 'exclusive')
+            db.exec('BEGIN EXCLUSIVE; COMMIT');
+    }
+    catch (error) {
+        if (isLocked(error))
+            throw new SqliteLockedError(filename, { cause: error });
+        throw error;
+    }
+}

package/dist/sqlite.d.ts

@@ -0,0 +1,37 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { SqliteValue } from '@earendil-works/pi-durable/storage/sqlite';
+import { type SqliteSettings } from './sqlite-settings.js';
+/**
+ * The synchronous SQL surface the SQLite workspace backend (`openSqliteFileSystem`) and the workspace journal
+ * (`createWorkspaceJournal`) need: the statement methods of Pi Durable's `SqliteExecutor` (same names, positional
+ * `SqliteValue` bindings, rows as plain objects) without promises, plus a transaction. It is synchronous on purpose: a conditional
+ * write is one critical section (conflict check, file rows, receipt) that must commit or roll back as a unit, and a synchronous
+ * callback cannot interleave with another operation. Pi's own `SqliteDatabase` is asynchronous, so it needs a queue to give that
+ * guarantee; engines whose SQL is synchronous (`node:sqlite`, a Durable Object's `ctx.storage.sql`) satisfy this directly.
+ */
+export interface SqliteConnection {
+    readonly exec: (sql: string) => void;
+    readonly run: (sql: string, ...params: SqliteValue[]) => void;
+    readonly get: <Row extends object = Record<string, unknown>>(sql: string, ...params: SqliteValue[]) => Row | undefined;
+    readonly all: <Row extends object = Record<string, unknown>>(sql: string, ...params: SqliteValue[]) => Row[];
+    /**
+     * Run `work` atomically: every statement it issues commits together, or none does when it throws (the error is rethrown).
+     * `write` takes the write lock up front where the engine distinguishes it. `work` must not await. A transaction opened inside
+     * `work` joins the outer one.
+     */
+    readonly transaction: <Value>(mode: 'read' | 'write', work: () => Value) => Value;
+    /** Optional: release the connection. Its owner calls it; the file system and the journal borrow the connection and never close it. */
+    readonly close?: () => void;
+}
+export * from './sqlite-settings.js';
+/**
+ * A `node:sqlite` database with `settings` applied (partial settings are filled from `sqliteSettings.localDisk`: WAL, full sync,
+ * 5 s busy timeout). For Pi's own durable storage on the same settings, hand it to Pi's public adapter:
+ * `SqliteStorage.open(new NodeSqliteDatabase(openNodeDatabase(file, sqliteSettings.networkFilesystem)))`. Throws
+ * `SqliteLockedError` when another connection holds the file under `lockingMode: 'exclusive'`. Loaded without a static import so
+ * other runtimes can bundle this module.
+ */
+export declare function openNodeDatabase(filename: string, settings?: SqliteSettings): DatabaseSync;
+/** A `node:sqlite` file as a connection (`openNodeDatabase` with the same settings), `BEGIN IMMEDIATE` for writes. */
+export declare function openNodeConnection(filename: string, settings?: SqliteSettings): SqliteConnection;
+//# sourceMappingURL=sqlite.d.ts.map