@xopcai/xopc 0.0.247 → 0.0.249

package/dist/src/storage/sqlite/connection-wait-repository.js

@@ -0,0 +1,338 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { isXopcDatabaseOpen } from "./connection.js";
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { TaskRunRepository } from "../../tasks/task-run-repository.js";
+import { readCurrentSessionId } from "./session-repository.js";
+import { bumpSessionInputRevision, getSessionInputById, getSessionInputState, insertSessionInput, setSessionInputStatus } from "./session-input-repository.js";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+//#region src/storage/sqlite/connection-wait-repository.ts
+init_logger();
+const log = createLogger("Connectors:Wait");
+const events = new EventEmitter();
+function onConnectionWaitChanged(listener) {
+	events.on("changed", listener);
+	return () => {
+		events.off("changed", listener);
+	};
+}
+function publishConnectionWait(sessionKey) {
+	events.emit("changed", sessionKey);
+}
+function getConnectionWait(id) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const row = getSqliteDatabase().prepare("SELECT data_json FROM session_connection_waits WHERE id = ?").get(id);
+	return row ? JSON.parse(row.data_json) : void 0;
+}
+function getActiveConnectionWait(sessionKey) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const db = getSqliteDatabase();
+	const row = db.prepare(`SELECT data_json FROM session_connection_waits WHERE session_key = ? AND session_id = ?
+    AND status IN ('open','queued')`).get(sessionKey, readCurrentSessionId(db, sessionKey) ?? "");
+	return row ? JSON.parse(row.data_json) : void 0;
+}
+function isConnectionSuspended(sessionKey, runId) {
+	const wait = getActiveConnectionWait(sessionKey);
+	return Boolean(wait && wait.originRunId === runId);
+}
+function updateConnectionWait(wait, expectedVersion) {
+	return runSqliteWriteTransaction((db) => {
+		if (readCurrentSessionId(db, wait.sessionKey) !== wait.sessionId) throw new Error("SESSION_CHANGED");
+		const next = {
+			...wait,
+			version: expectedVersion + 1,
+			updatedAt: Date.now()
+		};
+		if (!db.prepare(`UPDATE session_connection_waits SET status = ?, version = ?, data_json = ? WHERE id = ? AND version = ?`).run(next.status, next.version, JSON.stringify(next), next.id, expectedVersion).changes) throw new Error("WAIT_CHANGED");
+		bumpSessionInputRevision(db, wait.sessionKey);
+		return next;
+	});
+}
+function requireSessionConnection(input) {
+	return runSqliteWriteTransaction((db) => {
+		const sessionId = readCurrentSessionId(db, input.sessionKey);
+		const runtime = getSessionInputState(input.sessionKey);
+		const origin = runtime.activeInputId ? getSessionInputById(input.sessionKey, runtime.activeInputId) : void 0;
+		if (!sessionId || !origin || !runtime.activeRunId) throw new Error("Connection recovery requires a queued chat execution.");
+		const resumed = origin.payload ? getConnectionWait(origin.payload.waitId) : void 0;
+		if (resumed?.resolution === "skipped") return { status: "skipped" };
+		const active = getActiveConnectionWait(input.sessionKey);
+		if (active) {
+			if (active.originInputId !== origin.id && active.objectiveId !== resumed?.objectiveId) return {
+				status: "objective_conflict",
+				waitId: active.id
+			};
+			const needs = new Map(active.needs.map((need) => [need.key, need]));
+			for (const need of input.needs) {
+				const previous = needs.get(need.key);
+				needs.set(need.key, previous ? {
+					...previous,
+					capabilities: [...new Set([...previous.capabilities, ...need.capabilities])]
+				} : need);
+			}
+			if (JSON.stringify([...needs.values()]) !== JSON.stringify(active.needs)) updateConnectionWait({
+				...active,
+				needs: [...needs.values()]
+			}, active.version);
+			return {
+				status: "connection_required",
+				waitId: active.id
+			};
+		}
+		const lastEntry = db.prepare("SELECT entry_id FROM transcript_entries WHERE session_id = ? ORDER BY seq DESC LIMIT 1").get(sessionId);
+		const wait = {
+			...input,
+			needs: [...new Map(input.needs.map((need) => [need.key, need])).values()],
+			id: randomUUID(),
+			sessionId,
+			objectiveId: resumed?.objectiveId ?? origin.id,
+			objectiveRevision: (resumed?.objectiveRevision ?? 0) + 1,
+			objectiveUpdatedAt: resumed?.objectiveUpdatedAt ?? origin.createdAtMs,
+			originInputId: origin.id,
+			originRunId: runtime.activeRunId,
+			taskRunId: origin.taskRunId,
+			checkpoint: {
+				entryId: lastEntry?.entry_id,
+				completedSteps: input.checkpoint?.completedSteps ?? [],
+				pendingSteps: input.checkpoint?.pendingSteps ?? [input.summary],
+				timeRange: input.checkpoint?.timeRange ?? resumed?.checkpoint.timeRange
+			},
+			summary: resumed?.summary ?? origin.content,
+			status: "open",
+			version: 1,
+			createdAt: Date.now(),
+			updatedAt: Date.now()
+		};
+		db.prepare(`INSERT INTO session_connection_waits(id,principal_id,session_key,session_id,status,version,data_json) VALUES (?,?,?,?,?,?,?)`).run(wait.id, wait.principalId, wait.sessionKey, wait.sessionId, wait.status, wait.version, JSON.stringify(wait));
+		if (wait.taskRunId) {
+			const runs = new TaskRunRepository();
+			const run = runs.get(wait.taskRunId);
+			if (run) {
+				runs.createWait({
+					taskId: run.taskId,
+					taskRunId: run.id,
+					kind: "user_input",
+					reason: input.summary,
+					condition: {
+						type: "connection",
+						connectionWaitId: wait.id
+					}
+				});
+				runs.setStatus({
+					runId: run.id,
+					expectedVersion: run.version,
+					from: [run.status],
+					to: "waiting",
+					actor: { kind: "system" }
+				});
+			}
+		}
+		bumpSessionInputRevision(db, wait.sessionKey);
+		log.info({
+			sessionKey: wait.sessionKey,
+			waitId: wait.id,
+			objectiveRevision: wait.objectiveRevision,
+			runId: wait.originRunId,
+			phase: "waiting"
+		}, "Connection requirement saved");
+		return {
+			status: "connection_required",
+			waitId: wait.id
+		};
+	});
+}
+/** The input and the wait transition commit together, using the existing queue's unique key. */
+function queueConnectionResolution(wait, resolution) {
+	return runSqliteWriteTransaction(() => {
+		const current = getConnectionWait(wait.id);
+		if (!current || current.version !== wait.version || current.status !== "open") throw new Error("WAIT_CHANGED");
+		const origin = getSessionInputById(wait.sessionKey, wait.originInputId);
+		if (!origin) throw new Error("Original input is unavailable.");
+		const input = insertSessionInput({
+			id: randomUUID(),
+			sessionKey: wait.sessionKey,
+			expectedSessionId: wait.sessionId,
+			clientMessageId: `connection:${wait.id}:${wait.objectiveRevision}:${resolution}`,
+			requestedDelivery: "next",
+			effectiveDelivery: "next",
+			status: "queued",
+			content: resolution === "skipped" ? `The user skipped the requested connection. Continue this objective using only available information: ${wait.summary}. Do not request these connections again or claim to have read their data.` : `Recovery checkpoint: ${JSON.stringify(wait.checkpoint)}. The user chose to continue the request originally made at ${new Date(wait.objectiveUpdatedAt).toISOString()}: ${wait.summary}. Interpret relative dates against that original request time, unless the user explicitly changed them. The connection requirement has been checked. Search and describe tools again before using them. Use the explicitly selected account. Do not repeat already completed actions.`,
+			origin: {
+				type: "system",
+				source: "internal"
+			},
+			thinking: origin.thinking,
+			contextRefs: origin.contextRefs,
+			contextSnapshots: origin.contextSnapshots,
+			kind: "connection_resume",
+			taskRunId: wait.taskRunId,
+			payload: {
+				waitId: wait.id,
+				objectiveRevision: wait.objectiveRevision,
+				resolution
+			}
+		});
+		return updateConnectionWait({
+			...wait,
+			status: "queued",
+			resolution,
+			queuedInputId: input.id
+		}, wait.version);
+	});
+}
+function consumeConnectionResume(input) {
+	if (input.kind !== "connection_resume") return true;
+	return runSqliteWriteTransaction(() => {
+		const wait = input.payload ? getConnectionWait(input.payload.waitId) : void 0;
+		if (!wait || wait.status !== "queued" || wait.queuedInputId !== input.id || wait.objectiveRevision !== input.payload?.objectiveRevision) return false;
+		if (readCurrentSessionId(getSqliteDatabase(), input.sessionKey) !== wait.sessionId) return false;
+		if (wait.taskRunId) {
+			const runs = new TaskRunRepository();
+			const run = runs.get(wait.taskRunId);
+			if (!run || run.status !== "waiting") return false;
+			const taskWaits = runs.listActiveWaits(run.taskId);
+			if (taskWaits.some((item) => item.taskRunId === run.id && item.condition.connectionWaitId !== wait.id)) {
+				updateConnectionWait({
+					...wait,
+					status: "open",
+					intent: void 0,
+					queuedInputId: void 0,
+					objectiveRevision: wait.objectiveRevision + 1
+				}, wait.version);
+				return false;
+			}
+			for (const taskWait of taskWaits) if (taskWait.condition.connectionWaitId === wait.id) runs.resolveWait({
+				waitId: taskWait.id,
+				actor: { kind: "system" },
+				resolution: { connectionWaitId: wait.id }
+			});
+			runs.setStatus({
+				runId: run.id,
+				expectedVersion: run.version,
+				from: ["waiting"],
+				to: "running",
+				actor: { kind: "system" }
+			});
+		}
+		updateConnectionWait({
+			...wait,
+			status: "closed"
+		}, wait.version);
+		return true;
+	});
+}
+function connectionBindings(sessionKey) {
+	if (!isXopcDatabaseOpen()) return [];
+	const state = getSessionInputState(sessionKey);
+	const input = state.activeInputId ? getSessionInputById(sessionKey, state.activeInputId) : void 0;
+	return input?.payload ? getConnectionWait(input.payload.waitId)?.needs ?? [] : [];
+}
+function connectionBinding(sessionKey, connectorId) {
+	const matches = connectionBindings(sessionKey).filter((need) => need.connectorId === connectorId);
+	return matches.length === 1 ? matches[0].connectionId : void 0;
+}
+/** New input wins over an outstanding auto-resume intent, including an already queued resume. */
+function invalidateConnectionResumeIntent(sessionKey) {
+	const wait = getActiveConnectionWait(sessionKey);
+	if (!wait) return;
+	runSqliteWriteTransaction(() => {
+		if (wait.queuedInputId) setSessionInputStatus(wait.queuedInputId, "cancelled");
+		updateConnectionWait({
+			...wait,
+			status: "open",
+			intent: void 0,
+			queuedInputId: void 0,
+			objectiveRevision: wait.objectiveRevision + 1,
+			scopeConfirmedAt: void 0,
+			reviewRequired: true
+		}, wait.version);
+	});
+	publishConnectionWait(sessionKey);
+}
+function reviseCurrentConnectionObjective(sessionKey, summary) {
+	const wait = getActiveConnectionWait(sessionKey);
+	if (!wait) throw new Error("No connection objective is waiting.");
+	if (!summary) {
+		cancelConnectionObjective(sessionKey);
+		return;
+	}
+	runSqliteWriteTransaction(() => {
+		if (wait.queuedInputId) setSessionInputStatus(wait.queuedInputId, "cancelled");
+		updateConnectionWait({
+			...wait,
+			summary,
+			objectiveUpdatedAt: Date.now(),
+			checkpoint: {
+				...wait.checkpoint,
+				pendingSteps: [summary],
+				timeRange: void 0
+			},
+			status: "open",
+			resolution: void 0,
+			intent: void 0,
+			queuedInputId: void 0,
+			scopeConfirmedAt: void 0,
+			reviewRequired: true,
+			objectiveRevision: wait.objectiveRevision + 1
+		}, wait.version);
+	});
+	publishConnectionWait(sessionKey);
+}
+function cancelConnectionObjective(sessionKey) {
+	const wait = getActiveConnectionWait(sessionKey);
+	if (!wait) return;
+	runSqliteWriteTransaction(() => {
+		if (wait.queuedInputId) setSessionInputStatus(wait.queuedInputId, "cancelled");
+		if (wait.taskRunId) {
+			const runs = new TaskRunRepository();
+			const run = runs.get(wait.taskRunId);
+			if (run?.status === "waiting") {
+				for (const taskWait of runs.listActiveWaits(run.taskId)) if (taskWait.condition.connectionWaitId === wait.id) runs.resolveWait({
+					waitId: taskWait.id,
+					actor: { kind: "system" },
+					resolution: { cancelled: true }
+				});
+				runs.finalize({
+					runId: run.id,
+					expectedVersion: run.version,
+					receipt: {
+						status: "cancelled",
+						summary: "Connection objective cancelled",
+						changes: [],
+						evidence: [],
+						verification: {
+							status: "unverified",
+							checks: []
+						},
+						remainingWork: [],
+						needsUser: false,
+						completionVerdict: "not_achieved"
+					}
+				});
+			}
+		}
+		updateConnectionWait({
+			...wait,
+			status: "closed",
+			resolution: "cancelled",
+			intent: void 0
+		}, wait.version);
+	});
+	publishConnectionWait(sessionKey);
+}
+function getConnectionResumeInput(sessionKey, runId) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const state = getSessionInputState(sessionKey);
+	if (state.activeRunId !== runId || !state.activeInputId) return void 0;
+	const input = getSessionInputById(sessionKey, state.activeInputId);
+	return input?.kind === "connection_resume" ? input : void 0;
+}
+function listConnectionWaitsToCheck() {
+	if (!isXopcDatabaseOpen()) return [];
+	return getSqliteDatabase().prepare(`SELECT wait.data_json FROM session_connection_waits wait
+    JOIN sessions session ON session.session_id = wait.session_id
+    WHERE wait.status = 'open'`).all().map((row) => JSON.parse(row.data_json)).filter((wait) => wait.principalId === "local-owner" && wait.intent && wait.intent.validUntil > Date.now());
+}
+//#endregion
+export { cancelConnectionObjective, connectionBinding, connectionBindings, consumeConnectionResume, getActiveConnectionWait, getConnectionResumeInput, getConnectionWait, invalidateConnectionResumeIntent, isConnectionSuspended, listConnectionWaitsToCheck, onConnectionWaitChanged, publishConnectionWait, queueConnectionResolution, requireSessionConnection, reviseCurrentConnectionObjective, updateConnectionWait };

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/connector-account-repository.js

@@ -59,7 +59,7 @@ function mergeAccountSourceData(db, connectorId, sourceAccountId, targetAccountI
   `).run(targetId, sourceId);
 	db.prepare("DELETE FROM knowledge_consumer_watermarks WHERE source_instance_id = ?").run(sourceId);
 	db.prepare(`
-    UPDATE memory_records
+    UPDATE knowledge_items
     SET source_json = json_set(source_json, '$.sourceInstanceId', ?)
     WHERE json_extract(source_json, '$.sourceInstanceId') = ?
   `).run(targetId, sourceId);

package/dist/src/storage/sqlite/context-evidence-repository.d.ts

@@ -0,0 +1,24 @@
+export interface ContextEvidence {
+    id: string;
+    sourceType: 'conversation' | 'connector' | 'user' | 'runtime';
+    sourceInstanceId?: string;
+    sourceRef: string;
+    sourceRunId?: string;
+    sourceItemId?: string;
+    sessionId?: string;
+    turnId?: string;
+    messageId?: string;
+    contentHash?: string;
+    retentionPolicy?: string;
+    processingPolicy?: 'local_only' | 'remote_allowed';
+    extractorId?: string;
+    extractorVersion?: string;
+    redactedExcerpt?: string;
+    trustLevel: 'owner' | 'trusted' | 'untrusted';
+    observedAt: number;
+    ingestedAt: number;
+    createdAt: number;
+}
+export declare function createContextEvidence(input: Omit<ContextEvidence, 'id' | 'ingestedAt' | 'createdAt'> & {
+    ingestedAt?: number;
+}, principalId?: string): ContextEvidence;

package/dist/src/storage/sqlite/context-evidence-repository.js

@@ -0,0 +1,52 @@
+import { getSqliteDatabase } from "./transaction.js";
+import { USER_MODEL_PRINCIPAL_ID } from "../../user-model/domain.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/storage/sqlite/context-evidence-repository.ts
+function fromRow(row) {
+	return {
+		id: row.evidence_id,
+		sourceType: row.source_type,
+		...row.source_instance_id ? { sourceInstanceId: row.source_instance_id } : {},
+		sourceRef: row.source_ref,
+		...row.source_run_id ? { sourceRunId: row.source_run_id } : {},
+		...row.source_item_id ? { sourceItemId: row.source_item_id } : {},
+		...row.session_id ? { sessionId: row.session_id } : {},
+		...row.turn_id ? { turnId: row.turn_id } : {},
+		...row.message_id ? { messageId: row.message_id } : {},
+		...row.content_hash ? { contentHash: row.content_hash } : {},
+		...row.retention_policy ? { retentionPolicy: row.retention_policy } : {},
+		...row.processing_policy ? { processingPolicy: row.processing_policy } : {},
+		...row.extractor_id ? { extractorId: row.extractor_id } : {},
+		...row.extractor_version ? { extractorVersion: row.extractor_version } : {},
+		...row.redacted_excerpt ? { redactedExcerpt: row.redacted_excerpt } : {},
+		trustLevel: row.trust_level,
+		observedAt: row.observed_at,
+		ingestedAt: row.ingested_at ?? row.created_at,
+		createdAt: row.created_at
+	};
+}
+function createContextEvidence(input, principalId = USER_MODEL_PRINCIPAL_ID) {
+	const db = getSqliteDatabase();
+	const existing = db.prepare(`SELECT * FROM context_evidence WHERE principal_id = ?
+    AND source_type = ? AND COALESCE(source_instance_id, '') = COALESCE(?, '') AND source_ref = ?`).get(principalId, input.sourceType, input.sourceInstanceId ?? null, input.sourceRef);
+	const contentHash = input.contentHash ?? (input.redactedExcerpt ? createHash("sha256").update(input.redactedExcerpt).digest("hex") : void 0);
+	if (existing) {
+		db.prepare(`UPDATE context_evidence SET
+      source_run_id = ?, source_item_id = ?, session_id = ?, turn_id = ?, message_id = ?,
+      content_hash = ?, retention_policy = ?, processing_policy = ?, extractor_id = ?,
+      extractor_version = ?, redacted_excerpt = ?, trust_level = ?, observed_at = ?, ingested_at = ?
+      WHERE evidence_id = ?`).run(input.sourceRunId ?? null, input.sourceItemId ?? null, input.sessionId ?? null, input.turnId ?? null, input.messageId ?? null, contentHash ?? null, input.retentionPolicy ?? null, input.processingPolicy ?? null, input.extractorId ?? null, input.extractorVersion ?? null, input.redactedExcerpt ?? null, input.trustLevel, input.observedAt, input.ingestedAt ?? Date.now(), existing.evidence_id);
+		return fromRow(db.prepare("SELECT * FROM context_evidence WHERE evidence_id = ?").get(existing.evidence_id));
+	}
+	const createdAt = Date.now();
+	const id = randomUUID();
+	db.prepare(`INSERT INTO context_evidence (
+    evidence_id, principal_id, source_type, source_instance_id, source_ref, source_run_id,
+    source_item_id, session_id, turn_id, message_id, content_hash, retention_policy,
+    processing_policy, extractor_id, extractor_version, redacted_excerpt, trust_level,
+    observed_at, ingested_at, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.sourceType, input.sourceInstanceId ?? null, input.sourceRef, input.sourceRunId ?? null, input.sourceItemId ?? null, input.sessionId ?? null, input.turnId ?? null, input.messageId ?? null, contentHash ?? null, input.retentionPolicy ?? null, input.processingPolicy ?? null, input.extractorId ?? null, input.extractorVersion ?? null, input.redactedExcerpt ?? null, input.trustLevel, input.observedAt, input.ingestedAt ?? createdAt, createdAt);
+	return fromRow(db.prepare("SELECT * FROM context_evidence WHERE evidence_id = ?").get(id));
+}
+//#endregion
+export { createContextEvidence };

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;
+}