@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-plugins/dist/infrastructure/state/local-lock-filesystem.js

@@ -0,0 +1,101 @@
+import { chmod, lstat, mkdir, statfs, } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep, parse } from "node:path";
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_DATABASE_MODE = 0o600;
+/**
+ * Filesystem types whose locking semantics are known to be local enough for
+ * the SQLite adapter. The allowlist is intentionally conservative: an
+ * unknown mount is a capability failure, not permission to silently fall back
+ * to process-local coordination.
+ */
+const LOCAL_FILESYSTEM_TYPES_BY_PLATFORM = {
+    // Only filesystems whose SQLite locking behavior is covered by this
+    // adapter's capability boundary are accepted. Unknown platform/type pairs
+    // fail closed rather than inheriting a Linux guess.
+    linux: new Set([
+        0x0000ef53, // ext2/3/4
+        0x01021994, // tmpfs
+        0x3153464a, // jfs
+        0x52654973, // reiserfs
+        0x58465342, // xfs
+        0x794c7630, // overlayfs
+        0x9123683e, // btrfs
+        0xf2f52010, // f2fs
+        0x2fc12fc1, // zfs
+        0x858458f6, // ramfs
+    ]),
+    win32: new Set([0x5346544e]), // NTFS
+    darwin: new Set([0x41504653, 0x48465300]), // APFS, HFS+
+    freebsd: new Set([0x011954, 0x09011954]), // UFS, UFS2
+};
+function filesystemMode(mode) {
+    return mode & 0o777;
+}
+function filesystemFailure(message) {
+    return new Error(message);
+}
+async function ensureDirectory(path) {
+    try {
+        const stats = await lstat(path);
+        if (stats.isSymbolicLink())
+            throw filesystemFailure("lock root contains a symbolic link");
+        if (!stats.isDirectory())
+            throw filesystemFailure("lock root component is not a directory");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        try {
+            await mkdir(path, { mode: PRIVATE_DIRECTORY_MODE });
+        }
+        catch (mkdirError) {
+            // Another process may create the same first-use component after our
+            // ENOENT observation. Accept only that race, then revalidate the winner
+            // without following a symlink below.
+            if (mkdirError.code !== "EEXIST")
+                throw mkdirError;
+        }
+        const stats = await lstat(path);
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw filesystemFailure("lock root component is not a private directory");
+        }
+    }
+}
+/** Create and validate a private root without following any path symlink. */
+export async function ensurePrivateLockRoot(input) {
+    if (typeof input !== "string" || input.length === 0 || !isAbsolute(input)) {
+        throw new TypeError("lockRoot must be a non-empty absolute path");
+    }
+    const root = resolve(input);
+    const parsed = parse(root);
+    const remainder = relative(parsed.root, root);
+    let current = parsed.root;
+    for (const component of remainder.split(sep)) {
+        if (component.length === 0)
+            continue;
+        current = join(current, component);
+        await ensureDirectory(current);
+    }
+    await chmod(root, PRIVATE_DIRECTORY_MODE);
+    const stats = await lstat(root);
+    if (stats.isSymbolicLink() || !stats.isDirectory() || filesystemMode(stats.mode) !== PRIVATE_DIRECTORY_MODE) {
+        throw filesystemFailure("lock root is not private");
+    }
+    return root;
+}
+/**
+ * Verify the mounted filesystem rather than assuming that a successful SQLite
+ * open proves cross-process exclusion. Callers may inject a stricter policy
+ * when a platform has a better local-filesystem classifier.
+ */
+export async function verifyLocalFilesystemCapability(root) {
+    const stats = await statfs(root);
+    const type = Number(stats.type);
+    const supportedTypes = LOCAL_FILESYSTEM_TYPES_BY_PLATFORM[process.platform];
+    if (supportedTypes === undefined || !Number.isSafeInteger(type) || !supportedTypes.has(type >>> 0)) {
+        throw filesystemFailure("filesystem locking capability is unknown or unsupported on this platform");
+    }
+}
+export const LOCAL_LOCK_DIRECTORY_MODE = PRIVATE_DIRECTORY_MODE;
+export const LOCAL_LOCK_DATABASE_MODE = PRIVATE_DATABASE_MODE;
+//# sourceMappingURL=local-lock-filesystem.js.map

package/node_modules/@nklisch/pi-plugins/dist/infrastructure/state/local-lock-filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-lock-filesystem.js","sourceRoot":"","sources":["../../../src/infrastructure/state/local-lock-filesystem.ts"],"names":[],"mappings":"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"}

package/node_modules/@nklisch/pi-plugins/dist/infrastructure/state/sqlite-lifecycle-state-store.d.ts

@@ -0,0 +1,30 @@
+import type { LifecycleStateInventoryPort } from "../../application/ports/lifecycle-state-inventory.js";
+import type { LifecycleStateStore } from "../../application/ports/lifecycle-state-store.js";
+import { toScopeReference, type ScopeContext } from "../../domain/state/scope.js";
+import type { Sha256 } from "../../domain/source.js";
+export declare class LifecycleStateAdapterError extends Error {
+    readonly code: "STATE_CORRUPT" | "STATE_ADAPTER_FAILED";
+    constructor(code: LifecycleStateAdapterError["code"], message: string, cause?: unknown);
+    toJSON(): Readonly<{
+        code: string;
+        message: string;
+    }>;
+}
+type LifecycleStatePathPlan = Readonly<{
+    stateRoot: string;
+    stateDatabase(scope: ReturnType<typeof toScopeReference>): string;
+}>;
+export type NodeLifecycleStateAdapters = Readonly<{
+    state: LifecycleStateStore;
+    inventory: LifecycleStateInventoryPort;
+    close(): Promise<void>;
+}>;
+export declare function createNodeLifecycleStateAdapters(input: Readonly<{
+    paths: LifecycleStatePathPlan;
+    currentProject: Extract<ScopeContext, {
+        kind: "project";
+    }>;
+    sha256: Sha256;
+    verifyLocalFilesystem?: (root: string) => Promise<void>;
+}>): Promise<NodeLifecycleStateAdapters>;
+export {};

package/node_modules/@nklisch/pi-plugins/dist/infrastructure/state/sqlite-lifecycle-state-store.js

@@ -0,0 +1,502 @@
+import { readdir } from "node:fs/promises";
+import { DatabaseSync } from "node:sqlite";
+import { basename } from "node:path";
+import { isVerifiedStateMutation, } from "../../application/state-contract.js";
+import { hashStateDocument, decodeStateDocument, encodeStateDocument, StateCodecError, StateVersionCutoverError, StateCorruptionSchema } from "../../domain/state/codec.js";
+import { GenerationSchema } from "../../domain/state/config-state.js";
+import { createStatePointersDocument } from "../../domain/state/pointers.js";
+import { deriveStateBlobRef } from "../../domain/state/references.js";
+import { createScopeContext, ScopeContextSchema, toScopeReference } from "../../domain/state/scope.js";
+import { createLifecycleStateDefaultDocuments } from "./lifecycle-state-defaults.js";
+import { ensurePrivateLockRoot, verifyLocalFilesystemCapability } from "./local-lock-filesystem.js";
+import { openIdentityBoundSqliteDatabase } from "./identity-bound-sqlite.js";
+const PROTOCOL = "pi-plugin-host-lifecycle-state";
+const VERSION = 1;
+const SQLITE_BUSY = 5;
+// Loaded hosts serialize many processes on one scope database; keep the
+// busy budget in the same ~5s class as initialization waits.
+const MAX_BUSY_RETRIES = 24;
+export class LifecycleStateAdapterError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "LifecycleStateAdapterError";
+        this.code = code;
+    }
+    toJSON() {
+        return Object.freeze({ code: this.code, message: this.message });
+    }
+}
+function safeCorruption(scope, code = "DOCUMENT_INVALID") {
+    return StateCorruptionSchema.parse({
+        document: "pointers",
+        scope: toScopeReference(scope),
+        code,
+        location: { kind: "field", id: code === "DIGEST_MISMATCH" ? "digest" : "root" },
+        summary: code === "DIGEST_MISMATCH"
+            ? "state document digest does not match"
+            : "state document is invalid",
+    });
+}
+function sameJson(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function assertFileIdentity(handle) {
+    if (handle.closed)
+        throw new LifecycleStateAdapterError("STATE_ADAPTER_FAILED", "lifecycle state adapter is closed");
+    try {
+        handle.handle.assertIdentity();
+    }
+    catch (cause) {
+        throw new LifecycleStateAdapterError("STATE_ADAPTER_FAILED", "lifecycle state database identity changed", cause);
+    }
+}
+function begin(database) {
+    database.exec("BEGIN IMMEDIATE");
+}
+function rollback(database) {
+    try {
+        if (database.isTransaction)
+            database.exec("ROLLBACK");
+    }
+    catch { /* preserve the operation failure */ }
+}
+function isBusy(error) {
+    return typeof error === "object" && error !== null && error.errcode === SQLITE_BUSY;
+}
+async function waitForBusy(signal, attempt) {
+    signal.throwIfAborted();
+    const delay = Math.min(250, 2 ** Math.min(attempt, 8));
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, delay);
+        const onAbort = () => { clearTimeout(timer); signal.removeEventListener("abort", onAbort); reject(signal.reason); };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function initializeSchema(database) {
+    database.exec(`
+    PRAGMA journal_mode = DELETE;
+    PRAGMA synchronous = FULL;
+    PRAGMA foreign_keys = ON;
+    PRAGMA busy_timeout = 0;
+    CREATE TABLE IF NOT EXISTS protocol (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      protocol TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      scope_json TEXT NOT NULL
+    ) STRICT;
+    CREATE TABLE IF NOT EXISTS state_blobs (
+      blob_ref TEXT PRIMARY KEY,
+      kind TEXT NOT NULL,
+      generation INTEGER NOT NULL CHECK (generation >= 0),
+      digest TEXT NOT NULL,
+      document TEXT NOT NULL
+    ) STRICT;
+    CREATE TABLE IF NOT EXISTS generation_pointers (
+      generation INTEGER PRIMARY KEY CHECK (generation >= 0),
+      pointer_json TEXT NOT NULL
+    ) STRICT;
+    CREATE TABLE IF NOT EXISTS current_pointer (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      generation INTEGER NOT NULL CHECK (generation >= 0),
+      pointer_json TEXT NOT NULL
+    ) STRICT;
+  `);
+}
+function validateSchema(database) {
+    database.exec("PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 0;");
+    const rows = database.prepare("SELECT name, type FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY name").all();
+    const expected = ["current_pointer", "generation_pointers", "protocol", "state_blobs"];
+    if (rows.length !== expected.length || rows.some((row, index) => row.name !== expected[index] || row.type !== "table")) {
+        throw new LifecycleStateAdapterError("STATE_CORRUPT", "lifecycle state schema is invalid");
+    }
+}
+function readProtocol(database) {
+    return database.prepare("SELECT protocol, version, scope_json FROM protocol WHERE singleton = 1")
+        .get();
+}
+function scopeFromProtocol(database, sha256) {
+    const row = readProtocol(database);
+    if (row === undefined || row.protocol !== PROTOCOL || row.version !== VERSION) {
+        throw new LifecycleStateAdapterError("STATE_CORRUPT", "lifecycle state protocol is invalid");
+    }
+    try {
+        return createScopeContext(JSON.parse(row.scope_json), sha256);
+    }
+    catch (cause) {
+        throw new LifecycleStateAdapterError("STATE_CORRUPT", "lifecycle state scope evidence is invalid", cause);
+    }
+}
+function withGeneration(document, generation) {
+    return { ...document, generation };
+}
+function encodeDocument(kind, document, scope, generation, sha256) {
+    const context = { scope, generation: GenerationSchema.parse(generation), sha256 };
+    switch (kind) {
+        case "hostConfig": return encodeStateDocument("hostConfig", document, context);
+        case "installedUser": return encodeStateDocument("installedUser", document, context);
+        case "trust": return encodeStateDocument("trust", document, context);
+        case "projectLocal": return encodeStateDocument("projectLocal", document, context);
+    }
+}
+function writeGeneration(database, scope, generation, documents, sha256, previousGeneration) {
+    const pointers = Object.entries(documents).map(([rawKind, document]) => {
+        const kind = rawKind;
+        const encoded = encodeDocument(kind, document, scope, generation, sha256);
+        const digest = hashStateDocument(encoded, sha256);
+        const blob = deriveStateBlobRef({
+            scope: toScopeReference(scope),
+            generation,
+            kind,
+            digest,
+        }, sha256);
+        database.prepare(`
+      INSERT INTO state_blobs(blob_ref, kind, generation, digest, document)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(blob, kind, generation, digest, JSON.stringify(encoded));
+        return { kind, generation, blob, digest };
+    });
+    const pointer = createStatePointersDocument({
+        schemaVersion: 1,
+        scope: toScopeReference(scope),
+        generation,
+        ...(previousGeneration === undefined ? {} : { previousGeneration }),
+        documents: pointers,
+    });
+    const pointerJson = JSON.stringify(pointer);
+    database.prepare("INSERT INTO generation_pointers(generation, pointer_json) VALUES (?, ?)")
+        .run(generation, pointerJson);
+    database.prepare(`
+    INSERT INTO current_pointer(singleton, generation, pointer_json) VALUES (1, ?, ?)
+    ON CONFLICT(singleton) DO UPDATE SET generation = excluded.generation, pointer_json = excluded.pointer_json
+  `).run(generation, pointerJson);
+    const oldest = generation - 1;
+    database.prepare("DELETE FROM generation_pointers WHERE generation < ?").run(oldest);
+    database.prepare("DELETE FROM state_blobs WHERE generation < ?").run(oldest);
+    return pointer;
+}
+function initializeScope(database, scope, sha256) {
+    if (readProtocol(database) !== undefined)
+        throw new LifecycleStateAdapterError("STATE_CORRUPT", "new lifecycle state database is not empty");
+    database.prepare("INSERT INTO protocol(singleton, protocol, version, scope_json) VALUES (1, ?, ?, ?)")
+        .run(PROTOCOL, VERSION, JSON.stringify(scope));
+    writeScopeDefaults(database, scope, sha256);
+}
+function writeScopeDefaults(database, scope, sha256) {
+    const defaults = createLifecycleStateDefaultDocuments(scope, sha256);
+    writeGeneration(database, scope, 0, scope.kind === "user"
+        ? { hostConfig: defaults.config, installedUser: defaults.installed, trust: defaults.trust }
+        : { projectLocal: defaults.project }, sha256);
+}
+/**
+ * Clean cut-over for a stale pointers index. The pointer document names every
+ * blob in its generation, so no single document can be reinitialized on its
+ * own; the whole scope returns to its fresh generation-0 defaults instead.
+ */
+function reinitializeScope(database, scope, sha256) {
+    database.prepare("DELETE FROM state_blobs").run();
+    database.prepare("DELETE FROM generation_pointers").run();
+    database.prepare("DELETE FROM current_pointer").run();
+    writeScopeDefaults(database, scope, sha256);
+}
+function decodeBlob(database, pointer, scope, sha256) {
+    const row = database.prepare(`
+    SELECT blob_ref, kind, generation, digest, document FROM state_blobs WHERE blob_ref = ?
+  `).get(pointer.blob);
+    if (row === undefined || row.blob_ref !== pointer.blob || row.kind !== pointer.kind ||
+        row.generation !== pointer.generation || row.digest !== pointer.digest) {
+        throw new StateCodecError(safeCorruption(scope));
+    }
+    let raw;
+    try {
+        raw = JSON.parse(row.document);
+    }
+    catch {
+        throw new StateCodecError(safeCorruption(scope));
+    }
+    const context = { scope, generation: pointer.generation, expectedDigest: pointer.digest, sha256 };
+    switch (pointer.kind) {
+        case "hostConfig": return decodeStateDocument("hostConfig", raw, context);
+        case "installedUser": return decodeStateDocument("installedUser", raw, context);
+        case "trust": return decodeStateDocument("trust", raw, context);
+        case "projectLocal": return decodeStateDocument("projectLocal", raw, context);
+    }
+}
+function readSnapshot(database, scope, sha256) {
+    const row = database.prepare("SELECT generation, pointer_json FROM current_pointer WHERE singleton = 1")
+        .get();
+    try {
+        if (row === undefined)
+            throw new StateCodecError(safeCorruption(scope));
+        const generation = GenerationSchema.parse(row.generation);
+        const rawPointer = JSON.parse(row.pointer_json);
+        let decodedPointer;
+        try {
+            decodedPointer = decodeStateDocument("pointers", rawPointer, { scope, generation, sha256 });
+        }
+        catch (error) {
+            if (!(error instanceof StateVersionCutoverError))
+                throw error;
+            // A stale pointers version is a clean cut-over, not corruption:
+            // reinitialize the scope at generation 0 and read the fresh snapshot.
+            reinitializeScope(database, scope, sha256);
+            return readSnapshot(database, scope, sha256);
+        }
+        const pointers = decodedPointer.value;
+        if (pointers.generation !== row.generation)
+            throw new StateCodecError(safeCorruption(scope));
+        const values = new Map();
+        const corruptions = [...decodedPointer.corruptions];
+        for (const pointer of pointers.documents) {
+            const decoded = decodeBlob(database, pointer, scope, sha256);
+            values.set(pointer.kind, decoded.value);
+            corruptions.push(...decoded.corruptions);
+        }
+        const snapshot = scope.kind === "user"
+            ? {
+                scope,
+                generation,
+                pointers,
+                config: values.get("hostConfig"),
+                installed: values.get("installedUser"),
+                trust: values.get("trust"),
+                corruptions,
+            }
+            : {
+                scope,
+                generation,
+                pointers,
+                project: values.get("projectLocal"),
+                corruptions,
+            };
+        return { ok: true, snapshot };
+    }
+    catch (error) {
+        const corruption = error instanceof StateCodecError ? error.corruption : safeCorruption(scope);
+        return { ok: false, scope, corruptions: [corruption] };
+    }
+}
+function projectDigest(projectKey) {
+    const match = /^project-v1:sha256:([0-9a-f]{64})$/u.exec(projectKey);
+    if (match?.[1] === undefined)
+        throw new Error("project key is invalid");
+    return match[1];
+}
+class SqliteLifecycleStateAdapter {
+    paths;
+    sha256;
+    #handles = new Map();
+    #closed = false;
+    constructor(paths, sha256) {
+        this.paths = paths;
+        this.sha256 = sha256;
+    }
+    async open(scopeInput, signal) {
+        if (this.#closed)
+            throw new LifecycleStateAdapterError("STATE_ADAPTER_FAILED", "lifecycle state adapter is closed");
+        const scope = createScopeContext(ScopeContextSchema.parse(scopeInput), this.sha256);
+        const path = this.paths.stateDatabase(toScopeReference(scope));
+        const existing = this.#handles.get(path);
+        if (existing !== undefined) {
+            assertFileIdentity(existing);
+            if (!sameJson(existing.scope, scope))
+                throw new LifecycleStateAdapterError("STATE_CORRUPT", "lifecycle state scope alias detected");
+            return existing;
+        }
+        const bound = await openIdentityBoundSqliteDatabase({
+            root: this.paths.stateRoot,
+            path,
+            signal,
+            initialize: (database) => {
+                initializeSchema(database);
+                initializeScope(database, scope, this.sha256);
+            },
+            validate: (database) => {
+                validateSchema(database);
+                const stored = scopeFromProtocol(database, this.sha256);
+                if (!sameJson(stored, scope))
+                    throw new LifecycleStateAdapterError("STATE_CORRUPT", "lifecycle state scope evidence does not match");
+            },
+        });
+        const handle = {
+            database: bound.database,
+            handle: bound,
+            path,
+            scope,
+            closed: false,
+        };
+        this.#handles.set(path, handle);
+        return handle;
+    }
+    async read(scope, signal) {
+        signal.throwIfAborted();
+        const handle = await this.open(scope, signal);
+        for (let attempt = 0;; attempt += 1) {
+            assertFileIdentity(handle);
+            try {
+                handle.database.exec("BEGIN");
+                signal.throwIfAborted();
+                const snapshot = readSnapshot(handle.database, handle.scope, this.sha256);
+                signal.throwIfAborted();
+                handle.database.exec("COMMIT");
+                return snapshot;
+            }
+            catch (error) {
+                rollback(handle.database);
+                if (signal.aborted)
+                    throw signal.reason;
+                if (!isBusy(error) || attempt >= MAX_BUSY_RETRIES)
+                    throw error;
+                await waitForBusy(signal, attempt);
+            }
+        }
+    }
+    async commit(mutation, signal) {
+        signal.throwIfAborted();
+        if (!isVerifiedStateMutation(mutation))
+            throw new TypeError("lifecycle state commit requires a verified mutation");
+        const handle = await this.open(mutation.scope, signal);
+        for (let attempt = 0;; attempt += 1) {
+            assertFileIdentity(handle);
+            try {
+                begin(handle.database);
+                signal.throwIfAborted();
+                const before = readSnapshot(handle.database, handle.scope, this.sha256);
+                if (!before.ok)
+                    throw new LifecycleStateAdapterError("STATE_CORRUPT", "lifecycle state is corrupt");
+                if (before.snapshot.generation !== mutation.expectedGeneration) {
+                    handle.database.exec("COMMIT");
+                    return {
+                        kind: "stale-generation",
+                        expected: mutation.expectedGeneration,
+                        actual: before.snapshot.generation,
+                    };
+                }
+                const next = GenerationSchema.parse(mutation.expectedGeneration + 1);
+                let documents;
+                if (handle.scope.kind === "user" && "config" in before.snapshot && mutation.scope.kind === "user" && !("project" in mutation.replace)) {
+                    documents = {
+                        hostConfig: withGeneration(mutation.replace.config ?? before.snapshot.config, next),
+                        installedUser: withGeneration(mutation.replace.installed ?? before.snapshot.installed, next),
+                        trust: withGeneration(mutation.replace.trust ?? before.snapshot.trust, next),
+                    };
+                }
+                else if (handle.scope.kind === "project" && "project" in before.snapshot && mutation.scope.kind === "project" && "project" in mutation.replace) {
+                    documents = { projectLocal: withGeneration(mutation.replace.project, next) };
+                }
+                else {
+                    throw new TypeError("lifecycle state mutation scope does not match its database");
+                }
+                writeGeneration(handle.database, handle.scope, next, documents, this.sha256, before.snapshot.generation);
+                // Read and validate the exact expected+1 generation while the writer
+                // still owns the transaction. A later writer can advance immediately
+                // after COMMIT without changing the snapshot acknowledged here.
+                const acknowledged = readSnapshot(handle.database, handle.scope, this.sha256);
+                if (!acknowledged.ok || acknowledged.snapshot.generation !== next || acknowledged.snapshot.pointers.previousGeneration !== mutation.expectedGeneration) {
+                    throw new LifecycleStateAdapterError("STATE_CORRUPT", "written lifecycle generation could not be acknowledged");
+                }
+                signal.throwIfAborted();
+                handle.database.exec("COMMIT");
+                return { kind: "committed", snapshot: acknowledged.snapshot };
+            }
+            catch (error) {
+                rollback(handle.database);
+                if (signal.aborted)
+                    throw signal.reason;
+                if (!isBusy(error) || attempt >= MAX_BUSY_RETRIES)
+                    throw error;
+                await waitForBusy(signal, attempt);
+            }
+        }
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const handle of [...this.#handles.values()].reverse()) {
+            if (handle.closed)
+                continue;
+            handle.closed = true;
+            handle.handle.close();
+        }
+        this.#handles.clear();
+    }
+    async discover(signal) {
+        signal.throwIfAborted();
+        const scopes = [];
+        let complete = true;
+        const names = await readdir(this.paths.stateRoot).catch(() => []);
+        for (const name of names.sort((left, right) => {
+            if (left === "user.sqlite")
+                return -1;
+            if (right === "user.sqlite")
+                return 1;
+            return left.localeCompare(right);
+        })) {
+            signal.throwIfAborted();
+            if (name !== "user.sqlite" && !/^project-[0-9a-f]{64}\.sqlite$/u.test(name))
+                continue;
+            const path = `${this.paths.stateRoot}/${name}`;
+            let temporary;
+            try {
+                const known = this.#handles.get(path);
+                const database = known?.database ?? (temporary = new DatabaseSync(path, { readOnly: true, allowExtension: false, defensive: true }));
+                const scope = scopeFromProtocol(database, this.sha256);
+                if (name === "user.sqlite" ? scope.kind !== "user" : scope.kind !== "project" || basename(name) !== `project-${projectDigest(scope.projectKey)}.sqlite`) {
+                    throw new Error("scope filename mismatch");
+                }
+                database.exec("BEGIN");
+                let loaded;
+                try {
+                    loaded = readSnapshot(database, scope, this.sha256);
+                    database.exec("COMMIT");
+                }
+                catch (error) {
+                    rollback(database);
+                    throw error;
+                }
+                if (!loaded.ok)
+                    throw new Error("scope is corrupt");
+                scopes.push(scope);
+            }
+            catch {
+                complete = false;
+            }
+            finally {
+                temporary?.close();
+            }
+        }
+        return Object.freeze({ scopes: Object.freeze(scopes), complete });
+    }
+}
+export async function createNodeLifecycleStateAdapters(input) {
+    if (input === null || typeof input !== "object" || typeof input.sha256 !== "function") {
+        throw new TypeError("Node lifecycle state adapter options are required");
+    }
+    const stateRoot = await ensurePrivateLockRoot(input.paths.stateRoot);
+    await (input.verifyLocalFilesystem ?? verifyLocalFilesystemCapability)(stateRoot);
+    const project = createScopeContext(input.currentProject, input.sha256);
+    if (project.kind !== "project")
+        throw new TypeError("current project scope is required");
+    const adapter = new SqliteLifecycleStateAdapter(input.paths, input.sha256);
+    try {
+        const signal = new AbortController().signal;
+        // Opening/creating both current scope databases is an adapter check, not a
+        // requirement that every persisted scope be healthy. A decoded corruption
+        // is authoritative read evidence: keep the adapter available so startup can
+        // degrade that scope, expose diagnosis, and preserve healthy siblings
+        // without rewriting quarantined bytes.
+        await adapter.read({ kind: "user" }, signal);
+        await adapter.read(project, signal);
+    }
+    catch (error) {
+        await adapter.close();
+        throw error;
+    }
+    return Object.freeze({
+        state: adapter,
+        inventory: { discover: (signal) => adapter.discover(signal) },
+        close: () => adapter.close(),
+    });
+}
+//# sourceMappingURL=sqlite-lifecycle-state-store.js.map