@parcha/pi-durable-disk 0.0.0-stage → 0.1.0-beta.13

package/dist/status.js

@@ -0,0 +1,264 @@
+// run.json: the run's status, generation, holder, heartbeat and seal, written by the instance that holds the
+// claim with write-to-temp, fsync, rename, and read by the supervisor (over the S3 API or a local mount). It is a hint
+// for the supervisor, never the source of truth: the store is. Any error writing it is a fence. The instance writes it
+// through its claim directory (`ClaimDir`), never by path, so a write cannot land under a mountpoint whose mount is gone.
+import { constants, readFileSync } from "node:fs";
+import { open, readFile, rename, rm, stat } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { FencedError, ownWriteFenced, PdaError } from "./errors.js";
+export const RUN_JSON = "run.json";
+/** The temporary file every write goes through; renamed over `run.json` once it is fsynced. */
+export const RUN_JSON_TEMP = "run.json.tmp";
+/** Heartbeat period: the instance rewrites `heartbeatAt` this often. */
+export const DEFAULT_HEARTBEAT_MS = 20_000;
+/** A lease whose last heartbeat is older than this has expired; the supervisor may revoke. */
+export const DEFAULT_LEASE_EXPIRY_MS = 90_000;
+/** The instance fences itself this long before its lease expires, on its own monotonic clock. */
+export const DEFAULT_LEASE_MARGIN_MS = 15_000;
+export const RUN_STATUSES = ["running", "sleeping", "paused", "done", "failed"];
+/** `run.json` is missing a field, has one of the wrong type, or is not JSON. Exit 65 (EX_DATAERR): a restart cannot fix it. */
+export class RunRecordError extends PdaError {
+    constructor(message, options = {}) {
+        super("RUN_JSON_INVALID", message, { cause: options.cause, exitCode: 65 });
+    }
+}
+const isInstant = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+function holderOf(value) {
+    if (value === null)
+        return null;
+    const h = value;
+    if (typeof h !== "object" || h === undefined || Array.isArray(h))
+        throw new RunRecordError("holder is not an object or null");
+    if (typeof h.driver !== "string" || typeof h.host !== "string")
+        throw new RunRecordError("holder.driver and holder.host must be strings");
+    if (h.bootId !== null && typeof h.bootId !== "string")
+        throw new RunRecordError("holder.bootId must be a string or null");
+    if (!Number.isSafeInteger(h.pid) || h.pid <= 0)
+        throw new RunRecordError("holder.pid must be a positive integer");
+    if (!isInstant(h.since))
+        throw new RunRecordError("holder.since must be an ISO 8601 instant");
+    return { ...h, driver: h.driver, host: h.host, bootId: h.bootId, pid: h.pid, since: h.since };
+}
+/**
+ * Parse and validate the text of a `run.json`. Unknown fields are ignored, so a newer writer stays readable. Throws
+ * RunRecordError on anything else. This is the reader the supervisor uses on the bytes it gets over the S3 API.
+ */
+export function parseRunRecord(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new RunRecordError("run.json is not JSON", { cause });
+    }
+    const r = value;
+    if (typeof r !== "object" || r === null || Array.isArray(r))
+        throw new RunRecordError("run.json is not an object");
+    if (typeof r.run !== "string" || r.run === "")
+        throw new RunRecordError("run must be a non-empty string");
+    if (!RUN_STATUSES.includes(r.status))
+        throw new RunRecordError(`status ${JSON.stringify(r.status)} is not one of ${RUN_STATUSES.join(", ")}`);
+    if (!isCount(r.generation))
+        throw new RunRecordError("generation must be a non-negative integer");
+    if (r.sealedSeq !== null && !isCount(r.sealedSeq))
+        throw new RunRecordError("sealedSeq must be a non-negative integer or null");
+    if (r.wakeAt !== null && !isInstant(r.wakeAt))
+        throw new RunRecordError("wakeAt must be an ISO 8601 instant or null");
+    if (r.heartbeatAt !== null && !isInstant(r.heartbeatAt))
+        throw new RunRecordError("heartbeatAt must be an ISO 8601 instant or null");
+    if (!isInstant(r.updatedAt))
+        throw new RunRecordError("updatedAt must be an ISO 8601 instant");
+    return {
+        run: r.run,
+        status: r.status,
+        generation: r.generation,
+        sealedSeq: r.sealedSeq,
+        wakeAt: r.wakeAt,
+        holder: holderOf(r.holder),
+        heartbeatAt: r.heartbeatAt,
+        updatedAt: r.updatedAt,
+        detail: r.detail === undefined ? null : r.detail,
+    };
+}
+/** The `run.json` under a run's root on a local mount (or in a claim directory), or undefined when the run has none yet. */
+export async function readRunRecord(root) {
+    let text;
+    try {
+        text = await readFile(join(typeof root === "string" ? root : root.at, RUN_JSON), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    return parseRunRecord(text);
+}
+/**
+ * True while the record's last heartbeat is younger than `expiryMs` on the reader's clock. The supervisor allows for
+ * clock skew between hosts inside the expiry.
+ */
+export function isLeaseFresh(record, nowMs = Date.now(), expiryMs = DEFAULT_LEASE_EXPIRY_MS) {
+    if (record.heartbeatAt === null)
+        return false;
+    return nowMs - Date.parse(record.heartbeatAt) < expiryMs;
+}
+/** Write to `run.json.tmp`, fsync it, rename it over `run.json`, fsync the directory. */
+export const persistRecord = async (root, text, signal) => {
+    const temp = join(root, RUN_JSON_TEMP);
+    const file = await open(temp, "w", 0o644);
+    try {
+        await file.writeFile(text);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    // The rename is the commit point: a write that began before a fence must not publish after it. Nothing else runs
+    // between this check and the rename's dispatch.
+    if (signal?.aborted) {
+        await rm(temp, { force: true }).catch(() => undefined);
+        signal.throwIfAborted();
+    }
+    await rename(temp, join(root, RUN_JSON));
+    const dir = await open(root, "r");
+    try {
+        await dir.sync();
+    }
+    finally {
+        await dir.close();
+    }
+};
+/**
+ * Write `record`; any error at all is a fence (`ownWriteFenced`), whatever its errno. Into a claim directory, the write
+ * goes through the open directory, after `assertMounted` (its CLAIM_UNMOUNTED fence is rethrown as is). `signal` as in
+ * `PersistRecord`.
+ */
+export async function writeRunRecord(root, record, persist = persistRecord, signal) {
+    try {
+        if (typeof root !== "string")
+            await root.assertMounted();
+        await persist(typeof root === "string" ? root : root.at, `${JSON.stringify(record, null, 2)}\n`, signal);
+    }
+    catch (error) {
+        if (error instanceof FencedError && error.code === CLAIM_UNMOUNTED)
+            throw error;
+        throw ownWriteFenced(join(typeof root === "string" ? root : root.root, RUN_JSON), error);
+    }
+}
+// ---- the claim directory ----------------------------------------------------------------------------------------------
+/** The FencedError code of a claim root that is no longer the mount the instance opened (unmounted, lazily or not). */
+export const CLAIM_UNMOUNTED = "CLAIM_UNMOUNTED";
+/** The file system type of an Archil mount in the mount table. */
+export const ARCHIL_FSTYPE = "fuse.archil";
+/** `major:minor` of a device number, as `/proc/self/mountinfo` writes it (glibc's encoding). */
+export function deviceName(dev) {
+    const major = ((dev & 0xfff00n) >> 8n) | ((dev & 0xfffff00000000000n) >> 32n);
+    const minor = (dev & 0xffn) | ((dev & 0xffffff00000n) >> 12n);
+    return `${major}:${minor}`;
+}
+const unescapeMount = (s) => s.replace(/\\([0-7]{3})/g, (_, o) => String.fromCharCode(parseInt(o, 8)));
+/** Every mount at `mountpoint` in a mountinfo table: its device and its type. */
+function mountsAt(table, mountpoint) {
+    const found = [];
+    for (const line of table.split("\n")) {
+        const f = line.split(" ");
+        const separator = f.indexOf("-", 6);
+        if (separator < 0 || f.length < separator + 2)
+            continue;
+        if (unescapeMount(f[4]) === mountpoint)
+            found.push({ dev: f[2], fstype: f[separator + 1] });
+    }
+    return found;
+}
+const unmounted = (message, cause) => new FencedError(message, { code: CLAIM_UNMOUNTED, cause });
+/**
+ * Open `root` as the claim's directory. With an `fstype` (default `fuse.archil`), the mount table must list a mount of
+ * that type at `root` on the device of the directory just opened; otherwise, and when the root cannot be opened, a
+ * FencedError CLAIM_UNMOUNTED (exit 75).
+ */
+export async function openClaimDir(root, options = {}) {
+    const fstype = options.fstype === undefined ? ARCHIL_FSTYPE : options.fstype;
+    let handle;
+    try {
+        handle = await open(root, constants.O_RDONLY | constants.O_DIRECTORY);
+    }
+    catch (error) {
+        throw unmounted(`opening the claim root ${root} failed: ${error.message}`, error);
+    }
+    let held;
+    try {
+        held = await handle.stat({ bigint: true });
+        if (fstype !== null) {
+            const table = await readFile(options.mountinfo ?? "/proc/self/mountinfo", "utf8");
+            const dev = deviceName(held.dev);
+            const mounts = mountsAt(table, root);
+            if (!mounts.some((m) => m.fstype === fstype && m.dev === dev)) {
+                const listed = mounts.map((m) => `${m.fstype} on ${m.dev}`).join(", ") || "nothing";
+                throw unmounted(`the claim root ${root} is on device ${dev}, not a ${fstype} mount there (the mount table lists ${listed})`);
+            }
+        }
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error instanceof FencedError ? error : unmounted(`checking the claim root ${root} failed: ${error.message}`, error);
+    }
+    const at = `/proc/self/fd/${handle.fd}`;
+    let closed = false;
+    const same = (path, now, claims) => {
+        if (now.dev === claims.dev && now.ino === claims.ino)
+            return;
+        throw unmounted(`${path} is device ${deviceName(now.dev)} inode ${now.ino}, not the claim's device ${deviceName(claims.dev)} inode ${claims.ino}: the claim's mount is gone`);
+    };
+    const statOf = async (path) => {
+        try {
+            return await stat(path, { bigint: true });
+        }
+        catch (error) {
+            throw unmounted(`stat of ${path} failed, so the claim's mount cannot be trusted: ${error.message}`, error);
+        }
+    };
+    return {
+        root,
+        get at() {
+            if (closed)
+                throw new FencedError(`the claim directory of ${root} is closed`);
+            return at;
+        },
+        async assertMounted() {
+            if (closed)
+                throw unmounted(`the claim directory of ${root} is closed`);
+            same(root, await statOf(root), held);
+        },
+        async assertSame(name) {
+            if (closed)
+                throw unmounted(`the claim directory of ${root} is closed`);
+            const [byPath, inDir] = await Promise.all([statOf(join(root, name)), statOf(join(at, name))]);
+            if (inDir.dev !== held.dev)
+                throw unmounted(`${name} in the claim directory is on device ${deviceName(inDir.dev)}, not the claim's ${deviceName(held.dev)}`);
+            same(join(root, name), byPath, inDir);
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await handle.close();
+        },
+    };
+}
+function bootId() {
+    try {
+        return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * This process as a holder: the host driver's `handle` (default driver `local`, this machine's host name and boot id)
+ * with this process's pid and `since`. A handle whose named fields have the wrong type is refused (RunRecordError).
+ */
+export function currentHolder(handle = {}, since = new Date()) {
+    return holderOf({ driver: "local", host: hostname(), bootId: bootId(), ...handle, pid: process.pid, since: since.toISOString() });
+}

package/dist/store.d.ts

@@ -0,0 +1,103 @@
+import { SqliteStorage } from "@earendil-works/pi-durable/storage/sqlite";
+import type { SqliteDatabase, SqliteExecutor, SqliteValue } from "@earendil-works/pi-durable/storage/sqlite";
+import { FencedError, HeldError } from "./errors.js";
+/** `exclusive`: no `-shm`, one connection. `shared`: WAL with `-shm`, readers on the same mount may connect. */
+export type Profile = "exclusive" | "shared";
+/** Thrown by every call on a fenced handle. `cause` is the storage error that fenced it, `errcode` its SQLite code. */
+export declare class StoreFencedError extends FencedError {
+    readonly errcode: number;
+    constructor(cause: unknown, errcode: number);
+}
+/** Thrown when another connection holds the database file at open (the exclusive profile's "database is locked"). */
+export declare class StoreBusyError extends HeldError {
+    constructor(file: string, profile: Profile, cause: unknown);
+}
+export type PragmaMismatch = {
+    readonly pragma: string;
+    readonly expected: string | number;
+    readonly actual: unknown;
+};
+/** Thrown when the filesystem or SQLite did not accept the profile's pragmas; the store is never opened. */
+export declare class StorePragmaError extends Error {
+    readonly code = "STORE_PRAGMA";
+    readonly profile: Profile;
+    readonly mismatches: readonly PragmaMismatch[];
+    constructor(profile: Profile, mismatches: readonly PragmaMismatch[]);
+}
+/** What each profile must read back after it is set. `synchronous` 2 is FULL. */
+export declare const PROFILE_PRAGMAS: {
+    readonly exclusive: {
+        readonly locking_mode: "exclusive";
+        readonly journal_mode: "wal";
+        readonly synchronous: 2;
+        readonly mmap_size: 0;
+    };
+    readonly shared: {
+        readonly locking_mode: "normal";
+        readonly journal_mode: "wal";
+        readonly synchronous: 2;
+        readonly mmap_size: 0;
+    };
+};
+/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
+export declare function assertPragmas(database: SqliteExecutor, profile: Profile): Promise<void>;
+/**
+ * The fenced state of one handle. The first error whose result code is in the I/O, full or not-a-database class marks it
+ * fenced, runs `onFenced` once (before the error propagates), and from then on every operation fails with the same
+ * StoreFencedError: operations still in flight when it was marked fail too, and their results are discarded.
+ */
+export declare class Fence {
+    #private;
+    constructor(onFenced?: (error: StoreFencedError) => void);
+    get fenced(): boolean;
+    /** The error that fenced the handle, once it is fenced. */
+    get error(): StoreFencedError | undefined;
+    assertLive(): void;
+    /** Run one storage operation under the fence. */
+    guard<T>(operation: () => Promise<T> | T): Promise<T>;
+}
+declare class FencedExecutor implements SqliteExecutor {
+    #private;
+    protected readonly fence: Fence;
+    constructor(fence: Fence, inner: SqliteExecutor);
+    exec(sql: string): Promise<void>;
+    run(sql: string, ...params: SqliteValue[]): Promise<void>;
+    get<T extends object>(sql: string, ...params: SqliteValue[]): Promise<T | undefined>;
+    all<T extends object>(sql: string, ...params: SqliteValue[]): Promise<T[]>;
+}
+/**
+ * pi's `SqliteDatabase` facade with the fence applied by delegation: statements, the transaction handle's statements
+ * and the commit itself all report to the same `Fence`. A fenced handle is abandoned, not closed: `close()` fails at
+ * once without touching the database, because closing runs a checkpoint and a fenced mount may never answer. The
+ * process is expected to exit.
+ */
+export declare class FencedDatabase extends FencedExecutor implements SqliteDatabase {
+    #private;
+    constructor(database: SqliteDatabase, fence?: Fence);
+    get fenced(): boolean;
+    get fencedBy(): StoreFencedError | undefined;
+    transaction<T>(callback: (transaction: SqliteExecutor) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export type OpenOptions = {
+    /** Runs once, synchronously, when the handle is fenced and before the failing call rejects. */
+    readonly onFenced?: (error: StoreFencedError) => void;
+    /** Wraps the raw database inside the fence, for instrumentation and fault injection. */
+    readonly decorate?: (database: SqliteDatabase) => SqliteDatabase;
+};
+export type ArchilStore = {
+    readonly storage: SqliteStorage;
+    /** The fence-aware facade the storage runs on: `database.fenced`, `database.fencedBy`. */
+    readonly database: FencedDatabase;
+    readonly profile: Profile;
+    readonly file: string;
+};
+/**
+ * Open `file` as a pi-durable store in `profile` (default `exclusive`). The exclusive profile sets
+ * `locking_mode = EXCLUSIVE` before `journal_mode = WAL`, so the WAL index lives in heap and no `-shm` file exists; a
+ * second connection gets "database is locked". The shared profile is pi's own WAL opener, with `-shm`. Rejects with
+ * StorePragmaError when a pragma does not read back, StoreBusyError when another connection holds the file, and
+ * StoreFencedError when the storage is already fenced at open (that handle is abandoned, as in FencedDatabase).
+ */
+export declare function openArchilStore(file: string, profile?: Profile, options?: OpenOptions): Promise<ArchilStore>;
+export {};

package/dist/store.js

@@ -0,0 +1,217 @@
+// The store: pi's SqliteStorage over one database file in one of two profiles, behind a fence-aware facade.
+// Both profiles run at synchronous = FULL with mmap off, and every pragma is read back before the store opens. After a
+// storage error of the I/O, full or not-a-database class the handle is fenced: nothing is retried on it, nothing read
+// from it is trusted, and every later call fails at once with StoreFencedError. The facade is the only place the
+// package reads a storage error.
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { SqliteStorage } from "@earendil-works/pi-durable/storage/sqlite";
+import { NodeSqliteDatabase, openNodeSqliteDatabase } from "@earendil-works/pi-durable/storage/sqlite/node";
+import { FencedError, HeldError } from "./errors.js";
+// SQLite primary result codes; an extended code carries its primary code in the low byte.
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+const SQLITE_IOERR = 10;
+const SQLITE_FULL = 13;
+const SQLITE_NOTADB = 26;
+const FENCING_CODES = new Set([SQLITE_IOERR, SQLITE_FULL, SQLITE_NOTADB]);
+const BUSY_CODES = new Set([SQLITE_BUSY, SQLITE_LOCKED]);
+const primary = (errcode) => errcode & 0xff;
+/** Every node:sqlite extended result code in an error, its causes and its aggregate members, outermost first. */
+function resultCodes(error, seen = new Set()) {
+    if (typeof error !== "object" || error === null || seen.has(error))
+        return [];
+    seen.add(error);
+    const codes = [];
+    const { errcode, cause } = error;
+    if (typeof errcode === "number")
+        codes.push(errcode);
+    const members = error instanceof AggregateError ? error.errors : [];
+    for (const inner of [...members, cause])
+        codes.push(...resultCodes(inner, seen));
+    return codes;
+}
+/** Thrown by every call on a fenced handle. `cause` is the storage error that fenced it, `errcode` its SQLite code. */
+export class StoreFencedError extends FencedError {
+    errcode;
+    constructor(cause, errcode) {
+        super(`store fenced by SQLite result code ${errcode}; the handle is unusable`, { cause, code: "STORE_FENCED" });
+        this.errcode = errcode;
+    }
+}
+/** Thrown when another connection holds the database file at open (the exclusive profile's "database is locked"). */
+export class StoreBusyError extends HeldError {
+    constructor(file, profile, cause) {
+        super("store", `store ${file} is held by another connection (${profile} profile)`, { cause });
+    }
+}
+/** Thrown when the filesystem or SQLite did not accept the profile's pragmas; the store is never opened. */
+export class StorePragmaError extends Error {
+    code = "STORE_PRAGMA";
+    profile;
+    mismatches;
+    constructor(profile, mismatches) {
+        const detail = mismatches.map((m) => `${m.pragma} is ${JSON.stringify(m.actual)}, expected ${JSON.stringify(m.expected)}`);
+        super(`${profile} profile not accepted: ${detail.join("; ")}`);
+        this.name = "StorePragmaError";
+        this.profile = profile;
+        this.mismatches = mismatches;
+    }
+}
+/** What each profile must read back after it is set. `synchronous` 2 is FULL. */
+export const PROFILE_PRAGMAS = {
+    exclusive: { locking_mode: "exclusive", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
+    shared: { locking_mode: "normal", journal_mode: "wal", synchronous: 2, mmap_size: 0 },
+};
+/** Read every pragma of `profile` back and refuse (StorePragmaError) when any differs. */
+export async function assertPragmas(database, profile) {
+    const mismatches = [];
+    for (const [pragma, expected] of Object.entries(PROFILE_PRAGMAS[profile])) {
+        const row = await database.get(`PRAGMA ${pragma}`);
+        const actual = row === undefined ? undefined : Object.values(row)[0];
+        if (actual !== expected)
+            mismatches.push({ pragma, expected, actual });
+    }
+    if (mismatches.length > 0)
+        throw new StorePragmaError(profile, mismatches);
+}
+/**
+ * The fenced state of one handle. The first error whose result code is in the I/O, full or not-a-database class marks it
+ * fenced, runs `onFenced` once (before the error propagates), and from then on every operation fails with the same
+ * StoreFencedError: operations still in flight when it was marked fail too, and their results are discarded.
+ */
+export class Fence {
+    #error;
+    #onFenced;
+    constructor(onFenced) {
+        this.#onFenced = onFenced;
+    }
+    get fenced() {
+        return this.#error !== undefined;
+    }
+    /** The error that fenced the handle, once it is fenced. */
+    get error() {
+        return this.#error;
+    }
+    assertLive() {
+        if (this.#error !== undefined)
+            throw this.#error;
+    }
+    /** Run one storage operation under the fence. */
+    async guard(operation) {
+        this.assertLive();
+        let result;
+        try {
+            result = await operation();
+        }
+        catch (error) {
+            throw this.#absorb(error);
+        }
+        this.assertLive();
+        return result;
+    }
+    #absorb(error) {
+        if (this.#error !== undefined)
+            return this.#error;
+        const errcode = resultCodes(error).find((code) => FENCING_CODES.has(primary(code)));
+        if (errcode === undefined)
+            return error;
+        const fenced = new StoreFencedError(error, errcode);
+        this.#error = fenced;
+        try {
+            this.#onFenced?.(fenced);
+        }
+        catch (listenerError) {
+            // A throwing listener must neither hide the fence nor be swallowed: it surfaces as an uncaught exception.
+            queueMicrotask(() => {
+                throw listenerError;
+            });
+        }
+        return fenced;
+    }
+}
+class FencedExecutor {
+    fence;
+    #inner;
+    constructor(fence, inner) {
+        this.fence = fence;
+        this.#inner = inner;
+    }
+    exec(sql) {
+        return this.fence.guard(() => this.#inner.exec(sql));
+    }
+    run(sql, ...params) {
+        return this.fence.guard(() => this.#inner.run(sql, ...params));
+    }
+    get(sql, ...params) {
+        return this.fence.guard(() => this.#inner.get(sql, ...params));
+    }
+    all(sql, ...params) {
+        return this.fence.guard(() => this.#inner.all(sql, ...params));
+    }
+}
+/**
+ * pi's `SqliteDatabase` facade with the fence applied by delegation: statements, the transaction handle's statements
+ * and the commit itself all report to the same `Fence`. A fenced handle is abandoned, not closed: `close()` fails at
+ * once without touching the database, because closing runs a checkpoint and a fenced mount may never answer. The
+ * process is expected to exit.
+ */
+export class FencedDatabase extends FencedExecutor {
+    #database;
+    constructor(database, fence = new Fence()) {
+        super(fence, database);
+        this.#database = database;
+    }
+    get fenced() {
+        return this.fence.fenced;
+    }
+    get fencedBy() {
+        return this.fence.error;
+    }
+    transaction(callback) {
+        return this.fence.guard(() => this.#database.transaction((handle) => callback(new FencedExecutor(this.fence, handle))));
+    }
+    close() {
+        return this.fence.guard(() => this.#database.close());
+    }
+}
+/**
+ * Open `file` as a pi-durable store in `profile` (default `exclusive`). The exclusive profile sets
+ * `locking_mode = EXCLUSIVE` before `journal_mode = WAL`, so the WAL index lives in heap and no `-shm` file exists; a
+ * second connection gets "database is locked". The shared profile is pi's own WAL opener, with `-shm`. Rejects with
+ * StorePragmaError when a pragma does not read back, StoreBusyError when another connection holds the file, and
+ * StoreFencedError when the storage is already fenced at open (that handle is abandoned, as in FencedDatabase).
+ */
+export async function openArchilStore(file, profile = "exclusive", options = {}) {
+    if (profile !== "exclusive" && profile !== "shared")
+        throw new TypeError(`unknown store profile ${JSON.stringify(profile)}`);
+    const fence = new Fence(options.onFenced);
+    const decorate = options.decorate ?? ((database) => database);
+    let database;
+    try {
+        if (file !== ":memory:")
+            await mkdir(dirname(file), { recursive: true });
+        if (profile === "exclusive") {
+            const raw = await fence.guard(() => new NodeSqliteDatabase(new DatabaseSync(file, { timeout: 0 })));
+            database = new FencedDatabase(decorate(raw), fence);
+            await database.exec("PRAGMA locking_mode = EXCLUSIVE"); // before WAL: the WAL index stays in heap
+            await database.exec("PRAGMA journal_mode = WAL");
+        }
+        else {
+            database = new FencedDatabase(decorate(await fence.guard(() => openNodeSqliteDatabase(file))), fence);
+        }
+        await database.exec("PRAGMA synchronous = FULL"); // fsync the WAL on every commit
+        await database.exec("PRAGMA mmap_size = 0"); // no mmap I/O of the database file on a network filesystem
+        await assertPragmas(database, profile);
+        const storage = await SqliteStorage.open(database);
+        return { storage, database, profile, file };
+    }
+    catch (error) {
+        if (database !== undefined && !fence.fenced)
+            await database.close().catch(() => undefined);
+        if (resultCodes(error).some((code) => BUSY_CODES.has(primary(code))))
+            throw new StoreBusyError(file, profile, error);
+        throw error;
+    }
+}