@xopcai/xopc 0.0.246 → 0.0.248

package/dist/src/share/site-share-store.js

@@ -1,33 +1,22 @@
-import { resolveStateDir } from "../config/paths-state.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { init_paths } from "../config/paths.js";
+import { requireXopcDatabase } from "../storage/sqlite/connection.js";
+import { runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { DurableState } from "../storage/sqlite/durable-state.js";
 import { SITE_SHARE_CONFIG_DEFAULTS } from "./site-share-types.js";
 import { isPathUnderWorkspace } from "../gateway/workspace-editor-path.js";
-import { join, relative, resolve } from "node:path";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
 import { randomBytes, randomUUID } from "node:crypto";
 import { lstat, readdir, realpath, stat } from "node:fs/promises";
 //#region src/share/site-share-store.ts
-init_paths();
 init_logger();
 const log = createLogger("SiteShareStore");
-const SITE_SHARES_FILE = "site-shares.json";
 const CLEANUP_INTERVAL_MS = 10 * 6e4;
 const EXPIRED_RETENTION_MS = 1440 * 6e4;
-const MAX_STORED = 200;
-const REQUEST_COUNT_DEBOUNCE_MS = 5e3;
 const SUBDOMAIN_PATTERN = /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/;
-function resolveStorePath() {
-	return join(resolveStateDir(), SITE_SHARES_FILE);
-}
 var SiteShareStore = class {
-	shares = /* @__PURE__ */ new Map();
-	byToken = /* @__PURE__ */ new Map();
-	bySubdomain = /* @__PURE__ */ new Map();
+	shares = new DurableState("site-shares");
 	config;
-	dirty = false;
-	debounceTimer = null;
 	cleanupTimer = null;
 	/** Optional cleanup hook invoked when a record is dropped (e.g. delete staging dir). */
 	onCleanup = null;
@@ -36,9 +25,15 @@ var SiteShareStore = class {
 			...SITE_SHARE_CONFIG_DEFAULTS,
 			...config
 		};
-		this.load();
 		this.startCleanupTimer();
 	}
+	saveNew(record) {
+		requireXopcDatabase();
+		runSqliteWriteTransaction(() => {
+			if (this.getActiveShares().length >= this.config.maxActiveSites) throw new Error("Maximum active shares reached");
+			this.shares.set(record.id, record);
+		});
+	}
 	updateConfig(config) {
 		this.config = {
 			...this.config,
@@ -75,10 +70,7 @@ var SiteShareStore = class {
 			uniqueClientCount: 0,
 			maxRequests: params.maxRequests ?? null
 		};
-		this.shares.set(id, record);
-		this.byToken.set(token, id);
-		if (subdomain) this.bySubdomain.set(subdomain, id);
-		this.persistSync();
+		this.saveNew(record);
 		log.info({
 			id,
 			tokenPrefix: token.slice(0, 8),
@@ -132,19 +124,17 @@ var SiteShareStore = class {
 		if (!preferred) return null;
 		const lower = preferred.trim().toLowerCase();
 		if (!SUBDOMAIN_PATTERN.test(lower)) throw new Error("Subdomain must match /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/");
-		if (this.bySubdomain.has(lower)) throw new Error(`Subdomain '${lower}' already in use`);
+		if (this.hasSubdomain(lower)) throw new Error(`Subdomain '${lower}' already in use`);
 		return lower;
 	}
 	getById(id) {
 		return this.shares.get(id) ?? null;
 	}
 	getByToken(token) {
-		const id = this.byToken.get(token);
-		return id ? this.shares.get(id) ?? null : null;
+		return this.shares.values().find((record) => record.token === token) ?? null;
 	}
 	getBySubdomain(subdomain) {
-		const id = this.bySubdomain.get(subdomain.toLowerCase());
-		return id ? this.shares.get(id) ?? null : null;
+		return this.shares.values().find((record) => record.subdomain === subdomain.toLowerCase()) ?? null;
 	}
 	/**
 	* Look up a record by token first, then by subdomain. Subdomain label may
@@ -175,134 +165,98 @@ var SiteShareStore = class {
 		};
 		return { valid: true };
 	}
-	/** Increment counters when a request lands. Debounced persist. */
+	/** Increment counters when a request lands. Persisted before returning. */
 	recordRequest(id, clientIp) {
-		const record = this.shares.get(id);
-		if (!record) return;
-		record.requestCount++;
-		const recent = record.recentClientIps ??= [];
-		if (!recent.includes(clientIp)) {
-			recent.unshift(clientIp);
-			if (recent.length > 200) recent.length = 200;
-			record.uniqueClientCount = recent.length;
-		}
-		this.scheduleDebouncedPersist();
+		this.shares.update(id, (record) => {
+			if (record) {
+				record.requestCount++;
+				const recent = record.recentClientIps ??= [];
+				if (!recent.includes(clientIp)) {
+					recent.unshift(clientIp);
+					if (recent.length > 200) recent.length = 200;
+					record.uniqueClientCount = recent.length;
+				}
+			}
+			return {
+				value: record,
+				result: void 0
+			};
+		});
 	}
 	setThumbnailStatus(id, status) {
-		const record = this.shares.get(id);
-		if (!record) return;
-		record.thumbnailStatus = status;
-		if (status === "ready") record.thumbnailGeneratedAt = (/* @__PURE__ */ new Date()).toISOString();
-		if (status === "failed") record.thumbnailFailedAt = (/* @__PURE__ */ new Date()).toISOString();
-		this.persistSync();
+		requireXopcDatabase();
+		return runSqliteWriteTransaction(() => {
+			const record = this.shares.get(id);
+			if (!record) return;
+			record.thumbnailStatus = status;
+			if (status === "ready") record.thumbnailGeneratedAt = (/* @__PURE__ */ new Date()).toISOString();
+			if (status === "failed") record.thumbnailFailedAt = (/* @__PURE__ */ new Date()).toISOString();
+			this.shares.set(record.id, record);
+		});
 	}
 	revoke(id) {
-		const record = this.shares.get(id);
-		if (!record) return false;
-		record.revoked = true;
-		this.persistSync();
-		if (this.onCleanup) try {
-			this.onCleanup(record);
-		} catch (err) {
-			log.warn({
-				err,
-				id
-			}, "Site share cleanup hook threw on revoke");
-		}
-		log.info({
-			id,
-			tokenPrefix: record.token.slice(0, 8)
-		}, "Site share revoked");
-		return true;
+		requireXopcDatabase();
+		return runSqliteWriteTransaction(() => {
+			const record = this.shares.get(id);
+			if (!record) return false;
+			record.revoked = true;
+			this.shares.set(record.id, record);
+			if (this.onCleanup) try {
+				this.onCleanup(record);
+			} catch (err) {
+				log.warn({
+					err,
+					id
+				}, "Site share cleanup hook threw on revoke");
+			}
+			log.info({
+				id,
+				tokenPrefix: record.token.slice(0, 8)
+			}, "Site share revoked");
+			return true;
+		});
 	}
 	revokeMany(ids) {
-		let count = 0;
-		for (const id of ids) {
-			const record = this.shares.get(id);
-			if (record && !record.revoked) {
-				record.revoked = true;
-				count++;
+		requireXopcDatabase();
+		return runSqliteWriteTransaction(() => {
+			let count = 0;
+			for (const id of ids) {
+				const record = this.shares.get(id);
+				if (record && !record.revoked) {
+					record.revoked = true;
+					this.shares.set(record.id, record);
+					count++;
+				}
 			}
-		}
-		if (count > 0) this.persistSync();
-		return count;
+			return count;
+		});
 	}
 	revokeExpired() {
-		const now = Date.now();
-		let count = 0;
-		for (const record of this.shares.values()) if (!record.revoked && now >= new Date(record.expiresAt).getTime()) {
-			record.revoked = true;
-			count++;
-		}
-		if (count > 0) this.persistSync();
-		return count;
-	}
-	update(id, patch) {
-		const record = this.shares.get(id);
-		if (!record) return null;
-		if (patch.extendTtlMs !== void 0) record.expiresAt = new Date(Date.now() + patch.extendTtlMs).toISOString();
-		if (patch.maxRequests !== void 0) record.maxRequests = patch.maxRequests;
-		this.persistSync();
-		return record;
-	}
-	load() {
-		const path = resolveStorePath();
-		if (!existsSync(path)) return;
-		try {
-			const raw = readFileSync(path, "utf8");
-			const data = JSON.parse(raw);
-			if (data.version !== 1 || !Array.isArray(data.shares)) return;
+		requireXopcDatabase();
+		return runSqliteWriteTransaction(() => {
 			const now = Date.now();
-			let cleaned = 0;
-			for (const record of data.shares) {
-				if (now - new Date(record.expiresAt).getTime() > EXPIRED_RETENTION_MS) {
-					cleaned++;
-					continue;
-				}
+			let count = 0;
+			for (const record of this.shares.values()) if (!record.revoked && now >= new Date(record.expiresAt).getTime()) {
+				record.revoked = true;
 				this.shares.set(record.id, record);
-				this.byToken.set(record.token, record.id);
-				if (record.subdomain) this.bySubdomain.set(record.subdomain, record.id);
-			}
-			if (cleaned > 0) {
-				log.info({ cleaned }, `Cleaned ${cleaned} expired site-share records on load`);
-				this.persistSync();
+				count++;
 			}
-		} catch (err) {
-			log.warn({ err }, "Failed to load site-shares.json");
-		}
+			return count;
+		});
 	}
-	persistSync() {
-		const path = resolveStorePath();
-		mkdirSync(resolveStateDir(), { recursive: true });
-		let records = [...this.shares.values()];
-		if (records.length > MAX_STORED) {
-			records.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
-			records = records.slice(0, MAX_STORED);
-			this.shares.clear();
-			this.byToken.clear();
-			this.bySubdomain.clear();
-			for (const r of records) {
-				this.shares.set(r.id, r);
-				this.byToken.set(r.token, r.id);
-				if (r.subdomain) this.bySubdomain.set(r.subdomain, r.id);
-			}
-		}
-		writeFileSync(path, `${JSON.stringify({
-			version: 1,
-			shares: records
-		}, null, 2)}\n`, "utf8");
+	update(id, patch) {
+		requireXopcDatabase();
+		return runSqliteWriteTransaction(() => {
+			const record = this.shares.get(id);
+			if (!record) return null;
+			if (patch.extendTtlMs !== void 0) record.expiresAt = new Date(Date.now() + patch.extendTtlMs).toISOString();
+			if (patch.maxRequests !== void 0) record.maxRequests = patch.maxRequests;
+			this.shares.set(record.id, record);
+			return record;
+		});
 	}
-	scheduleDebouncedPersist() {
-		this.dirty = true;
-		if (this.debounceTimer) return;
-		this.debounceTimer = setTimeout(() => {
-			this.debounceTimer = null;
-			if (this.dirty) {
-				this.dirty = false;
-				this.persistSync();
-			}
-		}, REQUEST_COUNT_DEBOUNCE_MS);
-		this.debounceTimer.unref?.();
+	hasSubdomain(subdomain) {
+		return this.getBySubdomain(subdomain) !== null;
 	}
 	startCleanupTimer() {
 		this.cleanupTimer = setInterval(() => {
@@ -310,8 +264,6 @@ var SiteShareStore = class {
 			let removed = 0;
 			for (const [id, record] of this.shares) if (now - new Date(record.expiresAt).getTime() > EXPIRED_RETENTION_MS) {
 				this.shares.delete(id);
-				this.byToken.delete(record.token);
-				if (record.subdomain) this.bySubdomain.delete(record.subdomain);
 				if (this.onCleanup) try {
 					this.onCleanup(record);
 				} catch (err) {
@@ -322,10 +274,7 @@ var SiteShareStore = class {
 				}
 				removed++;
 			}
-			if (removed > 0) {
-				this.persistSync();
-				log.debug({ removed }, `Cleaned ${removed} expired site shares`);
-			}
+			if (removed > 0) log.debug({ removed }, `Cleaned ${removed} expired site shares`);
 		}, CLEANUP_INTERVAL_MS);
 		this.cleanupTimer.unref?.();
 	}
@@ -334,14 +283,6 @@ var SiteShareStore = class {
 			clearInterval(this.cleanupTimer);
 			this.cleanupTimer = null;
 		}
-		if (this.debounceTimer) {
-			clearTimeout(this.debounceTimer);
-			this.debounceTimer = null;
-		}
-		if (this.dirty) {
-			this.dirty = false;
-			this.persistSync();
-		}
 	}
 };
 async function scanStatic(root, maxFileCount, maxRootDirSize) {

package/dist/src/share/site-share-types.d.ts

@@ -49,10 +49,6 @@ export interface SiteShareRecord {
     thumbnailGeneratedAt?: string;
     thumbnailFailedAt?: string;
 }
-export interface SiteShareStoreData {
-    version: 1;
-    shares: SiteShareRecord[];
-}
 export interface CreateSiteShareParams {
     /** 'static' uses workspace path; 'proxy' uses upstreamUrl. */
     kind: SiteSourceKind;

package/dist/src/storage/sqlite/connection.d.ts

@@ -10,8 +10,7 @@ export type SqliteConnectionPragmaOptions = {
     checkpointMode?: SqliteWalCheckpointMode;
     busyTimeoutMs?: number;
     foreignKeys?: boolean;
-    synchronous?: 'NORMAL';
-    databasePath?: string;
+    synchronous?: 'NORMAL' | 'FULL';
     onCheckpointError?: (error: unknown) => void;
 };
 export type XopcDatabase = {

package/dist/src/storage/sqlite/connection.js

@@ -88,44 +88,38 @@ function isPathWithinMount(targetPath, mountPoint) {
 	const resolvedMountPoint = path.resolve(mountPoint);
 	return resolvedTarget === resolvedMountPoint || resolvedMountPoint === path.parse(resolvedMountPoint).root || resolvedTarget.startsWith(`${resolvedMountPoint}${path.sep}`);
 }
-function isNfsMountType(fsType) {
-	return fsType.toLowerCase().startsWith("nfs");
+function isNetworkMountType(fsType) {
+	const type = fsType.toLowerCase();
+	return type.startsWith("nfs") || [
+		"cifs",
+		"smbfs",
+		"smb3",
+		"fuse.sshfs"
+	].includes(type);
 }
-function isNfsMountEntryPath(targetPath) {
+function isNetworkMountEntryPath(targetPath) {
 	const mountEntry = readMountEntries().filter((entry) => isPathWithinMount(targetPath, entry.mountPoint)).toSorted((a, b) => b.mountPoint.length - a.mountPoint.length)[0];
-	return mountEntry ? isNfsMountType(mountEntry.fsType) : false;
+	return mountEntry ? isNetworkMountType(mountEntry.fsType) : false;
 }
-function isNfsBackedPath(targetPath) {
-	if (typeof fs.statfsSync !== "function") return isNfsMountEntryPath(targetPath);
+function isNetworkBackedPath(targetPath) {
+	if (typeof fs.statfsSync !== "function") return isNetworkMountEntryPath(targetPath);
 	const checkedPath = findExistingVolumePath(targetPath);
 	if (!checkedPath) return false;
 	try {
-		if (fs.statfsSync(checkedPath).type === LINUX_NFS_SUPER_MAGIC) return true;
+		if ([
+			LINUX_NFS_SUPER_MAGIC,
+			4283649346,
+			4266872130,
+			20859
+		].includes(fs.statfsSync(checkedPath).type >>> 0)) return true;
 	} catch {
-		return isNfsMountEntryPath(checkedPath);
+		return isNetworkMountEntryPath(checkedPath);
 	}
-	return isNfsMountEntryPath(checkedPath);
-}
-function readJournalModeResult(row) {
-	if (!row || typeof row !== "object") return null;
-	const record = row;
-	const value = record.journal_mode ?? Object.values(record)[0];
-	return typeof value === "string" ? value.toLowerCase() : null;
-}
-function requireRollbackJournalMode(db, dbPath) {
-	const mode = readJournalModeResult(db.prepare("PRAGMA journal_mode = DELETE;").get());
-	if (mode !== "delete") throw new Error(`xopc.db at ${dbPath} is on an NFS-backed volume but SQLite kept journal_mode=${mode ?? "unknown"}. WAL mode is unsafe on NFS. Move ~/.xopc to a local filesystem, or set XOPC_STATE_DIR to a local path.`);
+	return isNetworkMountEntryPath(checkedPath);
 }
 function configureSqliteConnectionPragmas(db, options = {}) {
 	const busyTimeoutMs = options.busyTimeoutMs ?? XOPC_SQLITE_BUSY_TIMEOUT_MS;
 	db.exec(`PRAGMA busy_timeout = ${normalizeNonNegativeInteger(busyTimeoutMs, "busyTimeoutMs")};`);
-	if (options.databasePath && isNfsBackedPath(options.databasePath)) {
-		requireRollbackJournalMode(db, options.databasePath);
-		return {
-			checkpoint: () => true,
-			close: () => true
-		};
-	}
 	db.exec("PRAGMA journal_mode = WAL;");
 	const autoCheckpointPages = normalizeNonNegativeInteger(options.autoCheckpointPages ?? 1e3, "autoCheckpointPages");
 	db.exec(`PRAGMA wal_autocheckpoint = ${autoCheckpointPages};`);
@@ -136,8 +130,7 @@ function configureSqliteConnectionPragmas(db, options = {}) {
 	const checkpointIntervalMs = normalizeNonNegativeInteger(options.checkpointIntervalMs ?? 1800 * 1e3, "checkpointIntervalMs");
 	const runCheckpoint = (mode) => {
 		try {
-			db.exec(`PRAGMA wal_checkpoint(${mode});`);
-			return true;
+			return db.prepare(`PRAGMA wal_checkpoint(${mode});`).get().busy === 0;
 		} catch (error) {
 			options.onCheckpointError?.(error);
 			return false;
@@ -174,29 +167,39 @@ function ensureDatabasePermissions(pathname) {
 }
 function openDatabaseAtPath(pathname) {
 	installSqliteTransientRejectionHandler();
+	if (pathname !== ":memory:" && isNetworkBackedPath(pathname)) throw new Error("SQLite requires a local filesystem; run the Gateway on the NAS instead of opening a network-mounted database.");
 	ensureDatabasePermissions(pathname);
 	const { DatabaseSync } = requireNodeSqlite();
 	const db = new DatabaseSync(pathname);
-	const walMaintenance = configureSqliteConnectionPragmas(db, {
-		databasePath: pathname,
-		synchronous: "NORMAL",
-		foreignKeys: true,
-		onCheckpointError: (error) => {
-			const em = error instanceof Error ? error.message : String(error);
-			log.warn({
-				err: error instanceof Error ? error : void 0,
-				errorMessage: em
-			}, `SQLite WAL checkpoint failed: ${em}`);
+	let walMaintenance;
+	try {
+		walMaintenance = configureSqliteConnectionPragmas(db, {
+			synchronous: "FULL",
+			foreignKeys: true,
+			onCheckpointError: (error) => {
+				const em = error instanceof Error ? error.message : String(error);
+				log.warn({
+					err: error instanceof Error ? error : void 0,
+					errorMessage: em
+				}, `SQLite WAL checkpoint failed: ${em}`);
+			}
+		});
+		ensureXopcDatabaseSchema(db, { databasePath: pathname });
+		ensureDatabasePermissions(pathname);
+		log.info({ path: pathname }, "Opened xopc SQLite database");
+		return {
+			db,
+			path: pathname,
+			walMaintenance
+		};
+	} catch (error) {
+		try {
+			walMaintenance?.close();
+		} finally {
+			db.close();
 		}
-	});
-	ensureXopcDatabaseSchema(db, { databasePath: pathname });
-	ensureDatabasePermissions(pathname);
-	log.info({ path: pathname }, "Opened xopc SQLite database");
-	return {
-		db,
-		path: pathname,
-		walMaintenance
-	};
+		throw error;
+	}
 }
 function openXopcDatabase(options = {}) {
 	const env = options.env ?? process.env;

package/dist/src/storage/sqlite/durable-queue.d.ts

@@ -0,0 +1,16 @@
+export declare class DurableQueue<T> {
+    readonly queue: string;
+    readonly scope: string;
+    constructor(queue: string, scope: string);
+    enqueue(id: string, payload: T, now?: number): void;
+    pending(limit?: number): T[];
+    delete(id: string): void;
+    claim(leaseMs: number): {
+        id: string;
+        payload: T;
+        token: string;
+    } | null;
+    renew(id: string, token: string, leaseMs: number): boolean;
+    finish(id: string, token: string, success: boolean): void;
+    clearProcessed(olderThanMs?: number): number;
+}

package/dist/src/storage/sqlite/durable-queue.js

@@ -0,0 +1,52 @@
+import { requireXopcDatabase } from "./connection.js";
+import { runSqliteWriteTransaction } from "./transaction.js";
+import { randomUUID } from "node:crypto";
+//#region src/storage/sqlite/durable-queue.ts
+var DurableQueue = class {
+	constructor(queue, scope) {
+		this.queue = queue;
+		this.scope = scope;
+	}
+	enqueue(id, payload, now = Date.now()) {
+		requireXopcDatabase().db.prepare(`INSERT INTO durable_messages(queue, scope, id, payload, enqueued_at)
+      VALUES (?, ?, ?, ?, ?) ON CONFLICT(queue, scope, id) DO NOTHING`).run(this.queue, this.scope, id, JSON.stringify(payload), now);
+	}
+	pending(limit = 2147483647) {
+		return requireXopcDatabase().db.prepare(`SELECT payload FROM durable_messages
+      WHERE queue = ? AND scope = ? AND processed_at IS NULL ORDER BY sequence LIMIT ?`).all(this.queue, this.scope, Math.max(0, Math.floor(limit))).map((row) => JSON.parse(row.payload));
+	}
+	delete(id) {
+		requireXopcDatabase().db.prepare("DELETE FROM durable_messages WHERE queue = ? AND scope = ? AND id = ?").run(this.queue, this.scope, id);
+	}
+	claim(leaseMs) {
+		requireXopcDatabase();
+		return runSqliteWriteTransaction((db) => {
+			const now = Date.now();
+			const row = db.prepare(`SELECT id, payload FROM durable_messages
+        WHERE queue = ? AND scope = ? AND processed_at IS NULL AND (lease_until IS NULL OR lease_until <= ?)
+        ORDER BY sequence LIMIT 1`).get(this.queue, this.scope, now);
+			if (!row) return null;
+			const token = randomUUID();
+			db.prepare("UPDATE durable_messages SET lease_token = ?, lease_until = ? WHERE queue = ? AND scope = ? AND id = ?").run(token, now + leaseMs, this.queue, this.scope, row.id);
+			return {
+				id: row.id,
+				payload: JSON.parse(row.payload),
+				token
+			};
+		});
+	}
+	renew(id, token, leaseMs) {
+		return requireXopcDatabase().db.prepare(`UPDATE durable_messages SET lease_until = ?
+      WHERE queue = ? AND scope = ? AND id = ? AND lease_token = ? AND processed_at IS NULL`).run(Date.now() + leaseMs, this.queue, this.scope, id, token).changes > 0;
+	}
+	finish(id, token, success) {
+		requireXopcDatabase().db.prepare(`UPDATE durable_messages SET processed_at = ?, lease_token = NULL, lease_until = NULL
+      WHERE queue = ? AND scope = ? AND id = ? AND lease_token = ?`).run(success ? Date.now() : null, this.queue, this.scope, id, token);
+	}
+	clearProcessed(olderThanMs) {
+		return Number(requireXopcDatabase().db.prepare(`DELETE FROM durable_messages
+      WHERE queue = ? AND scope = ? AND processed_at IS NOT NULL AND processed_at <= ?`).run(this.queue, this.scope, Date.now() - (olderThanMs ?? 0)).changes);
+	}
+};
+//#endregion
+export { DurableQueue };

package/dist/src/storage/sqlite/durable-state.d.ts

@@ -0,0 +1,16 @@
+/** Small namespaced extension/runtime documents. Domain histories use dedicated tables. */
+export declare class DurableState<T> {
+    readonly namespace: string;
+    readonly scope: string;
+    constructor(namespace: string, scope?: string);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): boolean;
+    entries(): Array<[string, T]>;
+    [Symbol.iterator](): Iterator<[string, T]>;
+    values(limit?: number, newestFirst?: boolean): T[];
+    update<R>(key: string, operation: (value: T | undefined) => {
+        value: T | undefined;
+        result: R;
+    }): R;
+}

package/dist/src/storage/sqlite/durable-state.js

@@ -0,0 +1,43 @@
+import { requireXopcDatabase } from "./connection.js";
+import { runSqliteWriteTransaction } from "./transaction.js";
+//#region src/storage/sqlite/durable-state.ts
+/** Small namespaced extension/runtime documents. Domain histories use dedicated tables. */
+var DurableState = class {
+	constructor(namespace, scope = "") {
+		this.namespace = namespace;
+		this.scope = scope;
+	}
+	get(key) {
+		const row = requireXopcDatabase().db.prepare("SELECT payload FROM durable_state WHERE namespace = ? AND scope = ? AND key = ?").get(this.namespace, this.scope, key);
+		return row ? JSON.parse(row.payload) : void 0;
+	}
+	set(key, value) {
+		requireXopcDatabase().db.prepare(`INSERT INTO durable_state(namespace, scope, key, payload)
+      VALUES (?, ?, ?, ?) ON CONFLICT(namespace, scope, key) DO UPDATE SET payload = excluded.payload`).run(this.namespace, this.scope, key, JSON.stringify(value));
+	}
+	delete(key) {
+		return requireXopcDatabase().db.prepare("DELETE FROM durable_state WHERE namespace = ? AND scope = ? AND key = ?").run(this.namespace, this.scope, key).changes > 0;
+	}
+	entries() {
+		return requireXopcDatabase().db.prepare("SELECT key, payload FROM durable_state WHERE namespace = ? AND scope = ? ORDER BY rowid").all(this.namespace, this.scope).map((row) => [row.key, JSON.parse(row.payload)]);
+	}
+	[Symbol.iterator]() {
+		return this.entries()[Symbol.iterator]();
+	}
+	values(limit, newestFirst = false) {
+		if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit < 0)) throw new Error("Invalid record limit");
+		return requireXopcDatabase().db.prepare(`SELECT payload FROM durable_state
+      WHERE namespace = ? AND scope = ? ORDER BY rowid ${newestFirst ? "DESC" : "ASC"} LIMIT ?`).all(this.namespace, this.scope, limit ?? -1).map((row) => JSON.parse(row.payload));
+	}
+	update(key, operation) {
+		requireXopcDatabase();
+		return runSqliteWriteTransaction(() => {
+			const next = operation(this.get(key));
+			if (next.value === void 0) this.delete(key);
+			else this.set(key, next.value);
+			return next.result;
+		});
+	}
+};
+//#endregion
+export { DurableState };

package/dist/src/storage/sqlite/migrations/146_understanding_focus_exclusions.sql

@@ -0,0 +1,9 @@
+CREATE TABLE understanding_focus_exclusions (
+  understanding_id TEXT NOT NULL REFERENCES user_understandings(understanding_id) ON DELETE CASCADE,
+  focus_id TEXT NOT NULL REFERENCES user_focuses(focus_id) ON DELETE CASCADE,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (understanding_id, focus_id)
+);
+
+CREATE INDEX idx_understanding_focus_exclusions_focus
+  ON understanding_focus_exclusions(focus_id);