@xopcai/xopc 0.0.374 → 0.0.375

package/dist/src/knowledge/local-folder-adapter.js

@@ -1,3 +1,4 @@
+import { inferMemorySensitivity } from "../agent/memory/sensitivity.js";
 import { extname, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { readFile, readdir, realpath, stat } from "node:fs/promises";
@@ -21,22 +22,19 @@ const MAX_FILES = 2e3;
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 var LocalFolderKnowledgeSourceAdapter = class {
 	kind = "local-folder";
-	constructor(rootPath) {
+	constructor(rootPath, pageSize = MAX_FILES) {
 		this.rootPath = rootPath;
+		this.pageSize = pageSize;
 	}
 	async pull(input) {
 		const scanStartedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const root = await realpath(resolve(this.rootPath));
 		if (!(await stat(root)).isDirectory()) throw new Error(`Local knowledge source is not a directory: ${root}`);
-		const cursorMs = input.cursor ? Date.parse(input.cursor) : NaN;
-		const windowMs = input.windowStart ? Date.parse(input.windowStart) : NaN;
-		const changedAfter = Math.max(Number.isFinite(cursorMs) ? cursorMs : 0, Number.isFinite(windowMs) ? windowMs : 0);
 		const paths = [];
 		const warnings = [];
 		const walk = async (directory) => {
 			if (input.signal.aborted) throw input.signal.reason ?? /* @__PURE__ */ new Error("Local folder sync aborted.");
 			for (const entry of await readdir(directory, { withFileTypes: true })) {
-				if (paths.length >= MAX_FILES) return;
 				if (entry.isSymbolicLink()) continue;
 				const path = resolve(directory, entry.name);
 				if (entry.isDirectory()) {
@@ -47,14 +45,24 @@ var LocalFolderKnowledgeSourceAdapter = class {
 			}
 		};
 		await walk(root);
-		if (paths.length >= MAX_FILES) warnings.push(`Local folder sync was limited to ${MAX_FILES} files.`);
+		paths.sort((left, right) => left.localeCompare(right));
+		let after;
+		try {
+			after = JSON.parse(input.cursor ?? "{}").after;
+		} catch {}
+		const remaining = after ? paths.filter((path) => relative(root, path).localeCompare(after) > 0) : paths;
+		const page = remaining.slice(0, this.pageSize);
+		const hasMore = remaining.length > page.length;
 		const items = [];
-		for (const path of paths) {
+		for (const path of page) {
 			if (input.signal.aborted) throw input.signal.reason ?? /* @__PURE__ */ new Error("Local folder sync aborted.");
 			const fileStat = await stat(path);
-			if (fileStat.size > MAX_FILE_BYTES || fileStat.mtimeMs <= changedAfter) continue;
 			const canonicalPath = await realpath(path);
 			if (canonicalPath !== root && !canonicalPath.startsWith(`${root}${sep}`)) continue;
+			if (fileStat.size > MAX_FILE_BYTES) {
+				warnings.push(`File exceeds ${MAX_FILE_BYTES} bytes and was excluded: ${relative(root, canonicalPath)}`);
+				continue;
+			}
 			const normalizedText = await readFile(canonicalPath, "utf8");
 			const externalId = relative(root, canonicalPath).split(sep).join("/");
 			items.push({
@@ -62,7 +70,7 @@ var LocalFolderKnowledgeSourceAdapter = class {
 				collectionScope: "files",
 				externalId,
 				itemType: "local_file",
-				authorRole: "user",
+				authorRole: "unknown",
 				sourceUpdatedAt: fileStat.mtime.toISOString(),
 				contentHash: createHash("sha256").update(normalizedText).digest("hex"),
 				normalizedText,
@@ -70,16 +78,17 @@ var LocalFolderKnowledgeSourceAdapter = class {
 					path: externalId,
 					rootPath: root
 				},
-				sensitivity: "personal",
-				retentionClass: "durable",
+				sensitivity: inferMemorySensitivity(normalizedText),
+				retentionClass: "bounded",
 				synthesisPipeline: "connected_knowledge"
 			});
 		}
 		return {
 			items,
-			nextCursor: scanStartedAt,
+			nextCursor: hasMore ? JSON.stringify({ after: relative(root, page.at(-1)).split(sep).join("/") }) : scanStartedAt,
+			hasMore,
 			warnings,
-			snapshotExternalIds: paths.length < MAX_FILES ? paths.map((path) => relative(root, path).split(sep).join("/")) : void 0
+			snapshotExternalIds: warnings.length ? void 0 : paths.map((path) => relative(root, path).split(sep).join("/"))
 		};
 	}
 };

package/dist/src/knowledge-memory/domain.d.ts

@@ -12,6 +12,10 @@ export interface KnowledgeReadPolicy {
     contentSources: readonly KnowledgeContentSource[];
 }
 export interface KnowledgeItem {
+    retrievalSnippet?: string;
+    claimMode?: 'explicit' | 'observed' | 'inferred' | 'reported';
+    verification?: 'supported' | 'tentative' | 'conflicted';
+    sensitivity?: 'normal' | 'personal' | 'secret' | 'regulated';
     id: string;
     principalId: string;
     kind: KnowledgeKind;

package/dist/src/knowledge-memory/index.d.ts

@@ -1,2 +1,3 @@
 export * from './domain.js';
 export * from './repository.js';
+export * from './usage-policy.js';

package/dist/src/knowledge-memory/index.js

@@ -1,2 +1,3 @@
+import { canUseKnowledge, knowledgeContentSources, knowledgeExclusion } from "./usage-policy.js";
 import { KnowledgeReviewConflictError, classifyKnowledgeContentSource, deleteKnowledgeItem, getKnowledgeItem, isKnowledgeCurrent, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem } from "./repository.js";
-export { KnowledgeReviewConflictError, classifyKnowledgeContentSource, deleteKnowledgeItem, getKnowledgeItem, isKnowledgeCurrent, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem };
+export { KnowledgeReviewConflictError, canUseKnowledge, classifyKnowledgeContentSource, deleteKnowledgeItem, getKnowledgeItem, isKnowledgeCurrent, knowledgeContentSources, knowledgeExclusion, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem };

package/dist/src/knowledge-memory/repair-evidence.d.ts

@@ -0,0 +1,2 @@
+/** Legacy summaries are usable only when their original retained source can still be verified. */
+export declare function repairLegacyKnowledgeEvidence(): number;

package/dist/src/knowledge-memory/repair-evidence.js

@@ -0,0 +1,57 @@
+import { createContextEvidence, init_context_evidence_repository } from "../storage/sqlite/context-evidence-repository.js";
+import { getKnowledgeSourceItem, init_knowledge_repository } from "../storage/sqlite/knowledge-repository.js";
+import { getActiveUnderstandingConsent } from "../user-context/sources/consent-repository.js";
+import { getUnderstandingSourceRun } from "../user-context/sources/repository.js";
+import { listKnowledgeItems, writeKnowledgeItem } from "./repository.js";
+//#region src/knowledge-memory/repair-evidence.ts
+init_context_evidence_repository();
+init_knowledge_repository();
+/** Legacy summaries are usable only when their original retained source can still be verified. */
+function repairLegacyKnowledgeEvidence() {
+	let repaired = 0;
+	for (const item of listKnowledgeItems({
+		recordClass: "memory",
+		statuses: ["candidate"],
+		limit: 1e3
+	})) {
+		if (item.originClass !== "untrusted" || item.verification !== "tentative" || typeof item.source.sourceRunId !== "string" || !Array.isArray(item.source.evidenceRefs)) continue;
+		const run = getUnderstandingSourceRun(item.source.sourceRunId);
+		const consent = run ? getActiveUnderstandingConsent(run.grantId) : void 0;
+		if (!consent || !consent.purposes.includes("work_assistance")) continue;
+		const sources = item.source.evidenceRefs.filter((ref) => typeof ref === "string").map((ref) => ref.startsWith("knowledge-source://") ? getKnowledgeSourceItem(ref.slice(19)) : void 0);
+		if (!sources.length || sources.some((source) => !source || source.deletedAt || Date.parse(source.updatedAt) > item.updatedAt)) continue;
+		const evidence = sources.map((source) => {
+			return {
+				id: createContextEvidence({
+					sourceType: "connector",
+					sourceInstanceId: source.sourceInstanceId,
+					sourceRef: `knowledge-source://${source.id}`,
+					sourceItemId: source.id,
+					contentHash: source.contentHash,
+					trustLevel: "untrusted",
+					observedAt: Date.parse(source.updatedAt),
+					processingPolicy: consent.processingPolicy
+				}).id,
+				contentHash: source.contentHash,
+				consentReceiptId: consent.id
+			};
+		});
+		writeKnowledgeItem({
+			...item,
+			claimMode: "reported",
+			verification: "supported",
+			status: item.confidence >= .7 ? "active" : "candidate",
+			evidence,
+			replaceExisting: true,
+			source: {
+				...item.source,
+				consentReceiptId: consent.id,
+				sourceInstanceId: sources[0].sourceInstanceId
+			}
+		});
+		repaired += 1;
+	}
+	return repaired;
+}
+//#endregion
+export { repairLegacyKnowledgeEvidence };

package/dist/src/knowledge-memory/repository.d.ts

@@ -1,6 +1,14 @@
 import { type UserModelScope } from '../user-model/domain.js';
 import type { KnowledgeItem, KnowledgeKind, KnowledgeOriginClass, KnowledgeRecordClass, KnowledgeContentSource, KnowledgeReadPolicy, KnowledgeStatus, KnowledgeReviewAction, KnowledgeStatusActor, KnowledgeStatusEvent, KnowledgeVisibilityContext } from './domain.js';
 export interface WriteKnowledgeInput {
+    claimMode?: KnowledgeItem['claimMode'];
+    verification?: KnowledgeItem['verification'];
+    sensitivity?: KnowledgeItem['sensitivity'];
+    evidence?: Array<{
+        id: string;
+        contentHash?: string;
+        consentReceiptId?: string;
+    }>;
     principalId?: string;
     kind: KnowledgeKind;
     scope: UserModelScope;

package/dist/src/knowledge-memory/repository.js

@@ -1,10 +1,12 @@
+import { init_search_text, memorySearchQuery } from "./search-text.js";
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 import { init_domain, validateScope } from "../user-model/domain.js";
-import { buildFts5SearchQuery, init_fts } from "../storage/sqlite/fts.js";
+import { inferMemorySensitivity } from "../agent/memory/sensitivity.js";
 import { clearMemoryAudit, isMemorySuppressed, memoryFingerprint, restoreMemory, suppressMemory } from "../user-context/memory-suppression.js";
+import { canUseKnowledge, knowledgeContentSources } from "./usage-policy.js";
 import { randomUUID } from "node:crypto";
 //#region src/knowledge-memory/repository.ts
-init_fts();
+init_search_text();
 init_transaction();
 init_domain();
 var KnowledgeReviewConflictError = class extends Error {
@@ -16,6 +18,9 @@ var KnowledgeReviewConflictError = class extends Error {
 function fromRow(row) {
 	return {
 		id: row.knowledge_id,
+		claimMode: row.claim_mode,
+		verification: row.verification,
+		sensitivity: row.sensitivity,
 		principalId: row.principal_id,
 		kind: row.kind,
 		scope: {
@@ -62,7 +67,8 @@ function writeKnowledgeItem(input) {
 	if (input.validFrom !== void 0 && input.validTo !== void 0 && input.validTo < input.validFrom) throw new Error("Knowledge validTo must be greater than or equal to validFrom.");
 	const principalId = input.principalId ?? "local-owner";
 	const now = input.now ?? Date.now();
-	const admittedStatus = input.status ?? (input.originClass === "owner" || input.originClass !== "untrusted" && input.confidence >= .7 && !input.derivedFromRecalledContext ? "active" : "candidate");
+	const supportedExternal = input.originClass === "untrusted" && input.verification === "supported" && Boolean(input.evidence?.length) && input.confidence >= .7;
+	const admittedStatus = input.status ?? (supportedExternal || input.originClass === "owner" || input.originClass !== "untrusted" && input.confidence >= .7 && !input.derivedFromRecalledContext ? "active" : "candidate");
 	return runSqliteWriteTransaction((db) => {
 		const keys = knowledgeFingerprints(input);
 		if (input.restoreDeleted && input.originClass === "owner") restoreMemory(db, keys);
@@ -90,13 +96,12 @@ function writeKnowledgeItem(input) {
 			created: false
 		};
 		if (existing) {
+			db.prepare("INSERT INTO knowledge_revisions(revision_id, knowledge_id, content, source_json, created_at) VALUES (?, ?, ?, ?, ?)").run(randomUUID(), existing.knowledge_id, existing.content, existing.source_json, now);
 			const nextStatus = admittedStatus;
 			db.prepare(`UPDATE knowledge_items SET kind = ?, content = ?, record_class = ?, status = ?, confidence = ?,
         importance = ?, valid_from = ?, valid_to = ?, expires_at = ?, review_at = ?,
         origin_class = ?, source_agent_id = ?, source_conversation_id = ?, source_turn_id = ?,
         derived_from_recalled_context = ?, source_json = ?, updated_at = ? WHERE knowledge_id = ?`).run(input.kind, input.content.trim(), input.recordClass ?? "memory", nextStatus, input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, existing.knowledge_id);
-			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(existing.knowledge_id);
-			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), existing.knowledge_id);
 			if (existing.status !== nextStatus) insertStatusEvent(db, {
 				knowledgeId: existing.knowledge_id,
 				fromStatus: existing.status,
@@ -105,6 +110,7 @@ function writeKnowledgeItem(input) {
 				reason: "Knowledge replaced from its source.",
 				now
 			});
+			writeEvidence(db, existing.knowledge_id, input);
 			return {
 				item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(existing.knowledge_id)),
 				created: false
@@ -118,7 +124,6 @@ function writeKnowledgeItem(input) {
       origin_class, source_agent_id, source_conversation_id, source_turn_id,
       derived_from_recalled_context, source_json, created_at, updated_at
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.kind, input.scope.type, input.scope.id ?? null, input.content.trim(), input.canonicalKey.trim(), input.recordClass ?? "memory", status, input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, now);
-		db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), id);
 		insertStatusEvent(db, {
 			knowledgeId: id,
 			fromStatus: null,
@@ -127,6 +132,7 @@ function writeKnowledgeItem(input) {
 			reason: "Knowledge admitted.",
 			now
 		});
+		writeEvidence(db, id, input);
 		return {
 			item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(id)),
 			created: true
@@ -166,9 +172,11 @@ function transitionKnowledgeStatus(input) {
 		db.prepare(`UPDATE knowledge_items SET status = ?, content = COALESCE(?, content),
       origin_class = CASE WHEN ? THEN 'owner' ELSE origin_class END, updated_at = ?
       WHERE knowledge_id = ?`).run(input.status, content ?? null, input.actor === "user" && input.status === "active" ? 1 : 0, now, input.id);
+		if (input.actor === "user" && input.status === "active") db.prepare("UPDATE knowledge_items SET claim_mode = 'explicit', verification = 'supported' WHERE knowledge_id = ?").run(input.id);
 		if (content !== void 0) {
-			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(input.id);
-			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(content, input.id);
+			db.prepare("INSERT INTO knowledge_revisions(revision_id, knowledge_id, content, source_json, created_at) VALUES (?, ?, ?, ?, ?)").run(randomUUID(), input.id, current.content, current.source_json, now);
+			db.prepare("DELETE FROM knowledge_evidence_links WHERE knowledge_id = ?").run(input.id);
+			db.prepare("UPDATE knowledge_items SET claim_mode = 'explicit', verification = 'supported', source_json = '{}' WHERE knowledge_id = ?").run(input.id);
 		}
 		if (input.actor === "user" && (input.status === "rejected" || input.status === "archived")) suppressMemory(db, knowledgeFingerprints(fromRow(current)), now);
 		insertStatusEvent(db, {
@@ -280,43 +288,51 @@ function visibilityClause(context, policy) {
 		values
 	};
 }
-function contentSourceClause(policy) {
-	if (!policy) return "1";
-	const allowed = new Set(policy.contentSources);
-	const importedSource = "COALESCE(json_extract(k.source_json, '$.kind'), '') = 'product_import'";
-	const parts = [];
-	if (allowed.has("memory")) parts.push("k.record_class = 'memory'");
-	if (allowed.has("local_import")) parts.push(`(k.record_class = 'source_index' AND ${importedSource})`);
-	if (allowed.has("connector")) parts.push(`(k.record_class = 'source_index' AND NOT (${importedSource}))`);
-	return `(${parts.length ? parts.join(" OR ") : "0"})`;
-}
 function searchKnowledgeItems(input) {
 	const principalId = input.principalId ?? "local-owner";
 	const asOf = input.asOf ?? Date.now();
 	const limit = Math.max(1, Math.min(100, input.limit ?? 12));
 	const visible = visibilityClause(input.context, input.policy);
-	const contentSource = contentSourceClause(input.policy);
-	const fts = buildFts5SearchQuery(input.query);
+	const fts = memorySearchQuery(input.query);
 	if (!fts) return [];
-	return getSqliteDatabase().prepare(`SELECT k.*, bm25(knowledge_items_fts) AS rank
-    FROM knowledge_items_fts JOIN knowledge_items k ON k.knowledge_id = knowledge_items_fts.knowledge_id
-    WHERE knowledge_items_fts MATCH ? AND k.principal_id = ? AND k.status = 'active'
+	const selected = getSqliteDatabase().prepare(`SELECT k.*, bm25(knowledge_search_fts) AS rank
+    FROM knowledge_search_fts JOIN knowledge_items k ON k.knowledge_id = knowledge_search_fts.knowledge_id
+    WHERE knowledge_search_fts MATCH ? AND k.principal_id = ? AND k.status = 'active'
       AND (k.valid_from IS NULL OR k.valid_from <= ?)
       AND (k.valid_to IS NULL OR k.valid_to >= ?)
       AND (k.expires_at IS NULL OR k.expires_at >= ?)
       AND (k.review_at IS NULL OR k.review_at > ?)
       ${input.recordClass ? "AND k.record_class = ?" : ""}
       ${input.trustedOnly ? "AND k.origin_class != 'untrusted'" : ""}
-      AND ${contentSource}
       AND ${visible.sql}
-    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...visible.values, limit).map(fromRow);
+    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...visible.values, Math.min(1e3, limit * 10)).map(fromRow).filter((item) => canUseKnowledge(item, input.context, input.policy, asOf));
+	const chunks = getSqliteDatabase().prepare(`SELECT k.*, c.text AS chunk_text
+    FROM knowledge_chunks_fts f JOIN knowledge_source_chunks c ON c.chunk_id = f.chunk_id
+    JOIN knowledge_source_items s ON s.item_id = c.source_item_id AND s.content_hash = c.source_version
+    JOIN knowledge_items k ON json_extract(k.source_json, '$.sourceItemId') = s.item_id
+    WHERE knowledge_chunks_fts MATCH ? AND s.deleted_at IS NULL AND k.principal_id = ?
+      AND c.consent_receipt_id = json_extract(k.source_json, '$.consentReceiptId')
+      ${input.recordClass ? "AND k.record_class = ?" : ""} AND ${visible.sql}
+    ORDER BY bm25(knowledge_chunks_fts) LIMIT ?`).all(fts, principalId, ...input.recordClass ? [input.recordClass] : [], ...visible.values, Math.min(1e3, limit * 10));
+	const seen = new Set(selected.map((item) => item.id));
+	for (const row of chunks) {
+		const item = fromRow(row);
+		if (!seen.has(item.id) && (!input.trustedOnly || item.originClass !== "untrusted") && canUseKnowledge(item, input.context, input.policy, asOf)) {
+			selected.push({
+				...item,
+				retrievalSnippet: row.chunk_text
+			});
+			seen.add(item.id);
+		}
+	}
+	return selected.slice(0, limit);
 }
 function classifyKnowledgeContentSource(item) {
 	if (item.recordClass === "memory") return "memory";
 	return item.source.kind === "product_import" ? "local_import" : "connector";
 }
 function knowledgeItemAllowed(item, policy) {
-	return policy.scopes.includes(item.scope.type) && policy.contentSources.includes(classifyKnowledgeContentSource(item));
+	return policy.scopes.includes(item.scope.type) && knowledgeContentSources(item).every((source) => policy.contentSources.includes(source));
 }
 function knowledgeFingerprints(input) {
 	const principal = input.principalId ?? "local-owner";
@@ -347,7 +363,7 @@ function deleteKnowledgeItem(id, now = Date.now()) {
 			const item = fromRow(row);
 			suppressMemory(db, knowledgeFingerprints(item), now);
 			clearMemoryAudit(db, "knowledge", item.id);
-			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(item.id);
+			if (item.recordClass === "source_index" && typeof item.source.sourceItemId === "string") db.prepare("DELETE FROM knowledge_source_chunks WHERE source_item_id = ?").run(item.source.sourceItemId);
 			db.prepare("DELETE FROM knowledge_items WHERE knowledge_id = ?").run(item.id);
 		}
 		return rows.length > 0;
@@ -356,5 +372,10 @@ function deleteKnowledgeItem(id, now = Date.now()) {
 function isKnowledgeCurrent(item, asOf = Date.now()) {
 	return item.status === "active" && (item.validFrom === void 0 || item.validFrom <= asOf) && (item.validTo === void 0 || item.validTo >= asOf) && (item.expiresAt === void 0 || item.expiresAt >= asOf) && (item.reviewAt === void 0 || item.reviewAt > asOf);
 }
+function writeEvidence(db, id, input) {
+	db.prepare("UPDATE knowledge_items SET claim_mode = ?, verification = ?, sensitivity = ? WHERE knowledge_id = ?").run(input.claimMode ?? (input.originClass === "owner" ? "explicit" : input.originClass === "untrusted" ? "reported" : "observed"), input.verification ?? (input.originClass === "untrusted" && (input.recordClass ?? "memory") === "memory" ? "tentative" : "supported"), input.sensitivity ?? inferMemorySensitivity(input.content), id);
+	db.prepare("DELETE FROM knowledge_evidence_links WHERE knowledge_id = ?").run(id);
+	for (const evidence of input.evidence ?? []) db.prepare("INSERT INTO knowledge_evidence_links(knowledge_id, evidence_id, content_hash, consent_receipt_id) VALUES (?, ?, ?, ?)").run(id, evidence.id, evidence.contentHash ?? null, evidence.consentReceiptId ?? null);
+}
 //#endregion
 export { KnowledgeReviewConflictError, classifyKnowledgeContentSource, deleteKnowledgeItem, getKnowledgeItem, isKnowledgeCurrent, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem };

package/dist/src/knowledge-memory/search-text.d.ts

@@ -0,0 +1,3 @@
+/** Preserve original words while indexing Chinese characters and adjacent pairs. */
+export declare function memorySearchText(value: string): string;
+export declare function memorySearchQuery(value: string): string;

package/dist/src/knowledge-memory/search-text.js

@@ -0,0 +1,32 @@
+import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
+//#region src/knowledge-memory/search-text.ts
+/** Preserve original words while indexing Chinese characters and adjacent pairs. */
+function memorySearchText(value) {
+	const normalized = value.normalize("NFKC").toLowerCase();
+	const terms = /* @__PURE__ */ new Set();
+	for (const match of normalized.matchAll(HAN)) {
+		const chars = Array.from(match[0]);
+		for (let i = 0; i < chars.length; i += 1) {
+			terms.add(chars[i]);
+			if (chars[i + 1]) terms.add(chars[i] + chars[i + 1]);
+		}
+	}
+	return `${normalized}\n${[...terms].join(" ")}`;
+}
+function memorySearchQuery(value) {
+	const words = value.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
+	const terms = [];
+	for (const word of words) if (/^\p{Script=Han}+$/u.test(word)) {
+		const chars = Array.from(word);
+		if (chars.length === 1) terms.push(word);
+		else for (let i = 0; i < chars.length - 1; i += 1) terms.push(chars[i] + chars[i + 1]);
+	} else if (word.length > 1) terms.push(word);
+	return [...new Set(terms)].slice(0, 32).map((term) => `"${term.replaceAll("\"", "\"\"")}"`).join(" OR ");
+}
+var HAN;
+var init_search_text = __esmMin((() => {
+	HAN = /\p{Script=Han}+/gu;
+}));
+//#endregion
+init_search_text();
+export { init_search_text, memorySearchQuery, memorySearchText };

package/dist/src/knowledge-memory/usage-policy.d.ts

@@ -0,0 +1,6 @@
+import type { KnowledgeItem, KnowledgeReadPolicy, KnowledgeVisibilityContext } from './domain.js';
+export type KnowledgeExclusion = 'principal' | 'scope' | 'source_not_allowed' | 'expired' | 'conflicted' | 'sensitive' | 'evidence_missing' | 'source_revoked' | 'source_changed' | 'agent_not_allowed';
+export declare function knowledgeContentSources(item: KnowledgeItem): Array<'memory' | 'local_import' | 'connector'>;
+/** Source reliability affects how knowledge is described, never execution authority. */
+export declare function knowledgeExclusion(item: KnowledgeItem, context: KnowledgeVisibilityContext, policy?: KnowledgeReadPolicy, asOf?: number): KnowledgeExclusion | undefined;
+export declare function canUseKnowledge(item: KnowledgeItem, context: KnowledgeVisibilityContext, policy?: KnowledgeReadPolicy, asOf?: number): boolean;

package/dist/src/knowledge-memory/usage-policy.js

@@ -0,0 +1,61 @@
+import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transaction.js";
+import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../storage/sqlite/session-repository.js";
+import { getUnderstandingConsent } from "../user-context/sources/consent-repository.js";
+import { isOwnerIdentity } from "../user-context/identity-bindings.js";
+//#region src/knowledge-memory/usage-policy.ts
+init_transaction();
+init_session_repository();
+function knowledgeContentSources(item) {
+	if (item.source.kind === "product_import") return ["local_import"];
+	if (typeof item.source.sourceInstanceId === "string" && item.source.sourceInstanceId.startsWith("local-folder:")) return item.recordClass === "memory" ? ["memory", "local_import"] : ["local_import"];
+	if (item.recordClass === "source_index" || item.source.sourceInstanceId || item.source.sourceRunId || item.source.consentReceiptId) return item.recordClass === "memory" ? ["memory", "connector"] : ["connector"];
+	return ["memory"];
+}
+/** Source reliability affects how knowledge is described, never execution authority. */
+function knowledgeExclusion(item, context, policy, asOf = Date.now()) {
+	if (item.principalId !== "local-owner") return "principal";
+	if (!(item.scope.type === "global" || item.scope.id === {
+		agent: context.agentId,
+		workspace: context.workspaceId,
+		project: context.projectId,
+		session: context.conversationId
+	}[item.scope.type]) || policy && !policy.scopes.includes(item.scope.type)) return "scope";
+	if (policy && !knowledgeContentSources(item).every((source) => policy.contentSources.includes(source))) return "source_not_allowed";
+	if (item.status !== "active" || item.validFrom !== void 0 && item.validFrom > asOf || item.validTo !== void 0 && item.validTo < asOf || item.expiresAt !== void 0 && item.expiresAt < asOf || item.reviewAt !== void 0 && item.reviewAt <= asOf) return "expired";
+	if (item.verification === "conflicted" || item.verification === "tentative") return "conflicted";
+	if (item.sensitivity === "secret" || item.sensitivity === "regulated") return "sensitive";
+	if (item.originClass !== "owner" && item.sourceConversationId) {
+		const session = getSessionMetadata(item.sourceConversationId);
+		if (!session?.routing || session.routing.peerKind !== "direct" || !isOwnerIdentity(session.routing)) return "source_revoked";
+	}
+	const db = getSqliteDatabase();
+	const links = db.prepare(`SELECT e.*, l.content_hash AS linked_hash, l.consent_receipt_id
+    FROM knowledge_evidence_links l JOIN context_evidence e ON e.evidence_id = l.evidence_id
+    WHERE l.knowledge_id = ?`).all(item.id);
+	if (item.originClass === "untrusted" && !links.length) return "evidence_missing";
+	for (const link of links) {
+		if (link.conversation_id) {
+			const session = getSessionMetadata(link.conversation_id);
+			if (!session?.routing || session.routing.peerKind !== "direct" || !isOwnerIdentity(session.routing)) return "source_revoked";
+		}
+		if (link.linked_hash && link.linked_hash !== link.content_hash) return "source_changed";
+		if (link.source_item_id) {
+			const source = db.prepare("SELECT content_hash, deleted_at FROM knowledge_source_items WHERE item_id = ?").get(link.source_item_id);
+			if (!source || source.deleted_at) return "source_revoked";
+			if (link.linked_hash && link.linked_hash !== source.content_hash) return "source_changed";
+		}
+		if (link.source_type === "connector") {
+			if (!link.consent_receipt_id) return "evidence_missing";
+			const consent = getUnderstandingConsent(link.consent_receipt_id);
+			if (!consent || consent.revokedAt !== void 0 || !consent.purposes.includes("work_assistance")) return "source_revoked";
+			if (db.prepare("SELECT status FROM understanding_source_grants WHERE grant_id = ?").get(consent.grantId)?.status !== "active") return "source_revoked";
+			if (consent.allowedAgentIds && !consent.allowedAgentIds.includes(context.agentId)) return "agent_not_allowed";
+		}
+	}
+}
+function canUseKnowledge(item, context, policy, asOf = Date.now()) {
+	return knowledgeExclusion(item, context, policy, asOf) === void 0;
+}
+//#endregion
+export { canUseKnowledge, knowledgeContentSources, knowledgeExclusion };

package/dist/src/local-apps/service.js

@@ -5,10 +5,10 @@ import { currentOperationId, init_operation_context } from "../infra/operation-c
 import { afterSqliteCommit, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 import { ExtensionCapabilityBindingsSchema, extensionCapabilityPermissions } from "../../packages/gateway-contract/src/extension-capabilities.js";
 import { init_src } from "../../packages/gateway-contract/src/index.js";
-import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { init_paths, resolveExtensionsDir } from "../config/paths.js";
 import { slugifyProjectName } from "../projects/project-store.js";
 import { LocalAppStore } from "./store.js";
+import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
 import { validateLocalAppCapabilityContracts } from "./capabilities/contracts.js";
 import { buildLocalAppFixGuidance } from "./fix-guidance.js";

package/dist/src/memory-learning/repository.d.ts

@@ -0,0 +1,24 @@
+import type { Config } from '../config/schema.js';
+export interface LearningJob {
+    job_id: string;
+    conversation_id: string;
+    transcript_id: string;
+    through_seq: number;
+    policy_hash: string;
+    workspace_id: string;
+    lease_token: string;
+    attempts: number;
+    start_seq?: number | null;
+}
+export declare function learningPolicyHash(config: Config): string;
+/** Recover learning intent from authoritative rows, including notifications lost in a crash. */
+export declare function enqueueConversationLearning(config: Config, conversationId: string, workspaceId: string, force?: boolean, now?: number): string | undefined;
+export declare function claimLearningJob(now?: number): LearningJob | undefined;
+export declare function renewLearningLease(job: LearningJob): boolean;
+/** Apply model results and advance progress atomically under the current lease. */
+export declare function finishLearningJob(job: LearningJob, apply: () => void, processedThrough?: number): boolean;
+export declare function failLearningJob(job: LearningJob, errorCode: string, canceled?: boolean): void;
+export declare function learningStatus(config?: Config): {
+    jobs: unknown[];
+    coverage: unknown[];
+};

package/dist/src/memory-learning/repository.js

@@ -0,0 +1,96 @@
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { resolveUserContextSessionAccess } from "../user-context/access-policy.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/memory-learning/repository.ts
+init_transaction();
+function learningPolicyHash(config) {
+	const catalog = getSqliteDatabase().prepare("SELECT revision FROM agent_catalog_settings WHERE singleton_id = 1").get();
+	return createHash("sha256").update(JSON.stringify({
+		config,
+		catalog
+	})).digest("hex");
+}
+/** Recover learning intent from authoritative rows, including notifications lost in a crash. */
+function enqueueConversationLearning(config, conversationId, workspaceId, force = false, now = Date.now()) {
+	const access = resolveUserContextSessionAccess(config, conversationId);
+	if ((!access.userModel || config.userContext.userModel.writePolicy === "deny") && (!access.knowledge || config.userContext.knowledgeMemory.writePolicy === "deny")) return;
+	const idleMs = config.userContext.knowledgeMemory.learning?.idleFlushMs ?? 6e4;
+	return runSqliteWriteTransaction((db) => {
+		const transcript = db.prepare("SELECT active_transcript_id FROM sessions WHERE conversation_id = ?").get(conversationId);
+		if (!transcript?.active_transcript_id) return;
+		const id = transcript.active_transcript_id;
+		const last = db.prepare(`SELECT MAX(seq) AS seq, MAX(created_at) AS last_at FROM transcript_entries
+      WHERE transcript_id = ? AND role = 'assistant'`).get(id);
+		if (!last.seq) return;
+		db.prepare(`INSERT OR IGNORE INTO memory_learning_cursors(conversation_id, transcript_id, updated_at) VALUES (?, ?, ?)`).run(conversationId, id, now);
+		const cursor = db.prepare("SELECT processed_seq FROM memory_learning_cursors WHERE conversation_id = ? AND transcript_id = ?").get(conversationId, id);
+		if (!force && cursor.processed_seq >= last.seq) return;
+		const count = db.prepare(`SELECT COUNT(*) AS n FROM transcript_entries WHERE transcript_id = ? AND seq > ? AND role = 'user'`).get(id, cursor.processed_seq);
+		const due = force || count.n >= config.userContext.userModel.extraction.reviewIntervalTurns || now - (last.last_at ?? now) >= idleMs;
+		const jobId = randomUUID();
+		const inserted = db.prepare(`INSERT OR IGNORE INTO memory_learning_jobs(job_id, conversation_id, transcript_id,
+      through_seq, start_seq, extractor_version, policy_hash, workspace_id, state, next_attempt_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'queued', ?, ?, ?)`).run(jobId, conversationId, id, last.seq, force ? 0 : null, force ? `rebuild:${jobId}` : `2:${cursor.processed_seq}`, learningPolicyHash(config), workspaceId, due ? now : (last.last_at ?? now) + idleMs, now, now);
+		db.prepare(`UPDATE memory_learning_cursors SET observed_seq = MAX(observed_seq, ?), updated_at = ?
+      WHERE conversation_id = ? AND transcript_id = ?`).run(last.seq, now, conversationId, id);
+		return inserted.changes ? jobId : void 0;
+	});
+}
+function claimLearningJob(now = Date.now()) {
+	return runSqliteWriteTransaction((db) => {
+		db.prepare("UPDATE memory_learning_jobs SET state = 'failed', error_code = 'lease_expired', updated_at = ? WHERE state = 'running' AND attempts >= 3 AND lease_until < ?").run(now, now);
+		const row = db.prepare(`SELECT * FROM memory_learning_jobs j WHERE
+      ((state IN ('queued', 'retry_wait') AND next_attempt_at <= ?) OR (state = 'running' AND lease_until < ?))
+      AND NOT EXISTS (SELECT 1 FROM memory_learning_jobs other WHERE other.conversation_id = j.conversation_id
+        AND other.state = 'running' AND other.lease_until >= ? AND other.job_id != j.job_id)
+      AND attempts < 3 ORDER BY created_at LIMIT 1`).get(now, now, now);
+		if (!row) return;
+		const token = randomUUID();
+		db.prepare(`UPDATE memory_learning_jobs SET state = 'running', lease_token = ?, lease_until = ?,
+      attempts = attempts + 1, updated_at = ? WHERE job_id = ?`).run(token, now + 18e4, now, row.job_id);
+		return {
+			...row,
+			lease_token: token,
+			attempts: row.attempts + 1
+		};
+	});
+}
+function renewLearningLease(job) {
+	return Boolean(getSqliteDatabase().prepare(`UPDATE memory_learning_jobs SET lease_until = ?
+    WHERE job_id = ? AND state = 'running' AND lease_token = ?`).run(Date.now() + 18e4, job.job_id, job.lease_token).changes);
+}
+/** Apply model results and advance progress atomically under the current lease. */
+function finishLearningJob(job, apply, processedThrough = job.through_seq) {
+	return runSqliteWriteTransaction((db) => {
+		if (!db.prepare(`SELECT 1 FROM memory_learning_jobs WHERE job_id = ? AND state = 'running'
+      AND lease_token = ? AND lease_until >= ?`).get(job.job_id, job.lease_token, Date.now())) return false;
+		apply();
+		db.prepare(`UPDATE memory_learning_cursors SET processed_seq = MAX(processed_seq, ?), updated_at = ?
+      WHERE conversation_id = ? AND transcript_id = ?`).run(processedThrough, Date.now(), job.conversation_id, job.transcript_id);
+		db.prepare(`UPDATE memory_learning_jobs SET state = 'succeeded', lease_token = NULL, lease_until = NULL, updated_at = ? WHERE job_id = ?`).run(Date.now(), job.job_id);
+		db.prepare(`UPDATE memory_learning_jobs SET state = 'canceled', updated_at = ? WHERE conversation_id = ?
+      AND transcript_id = ? AND through_seq <= ? AND start_seq IS NULL AND state IN ('queued','retry_wait')`).run(Date.now(), job.conversation_id, job.transcript_id, processedThrough);
+		if (processedThrough < job.through_seq) {
+			const nextId = randomUUID();
+			db.prepare(`INSERT INTO memory_learning_jobs(job_id, conversation_id, transcript_id, through_seq,
+        start_seq, extractor_version, policy_hash, workspace_id, state, next_attempt_at, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'queued', ?, ?, ?)`).run(nextId, job.conversation_id, job.transcript_id, job.through_seq, job.start_seq == null ? null : processedThrough, job.start_seq == null ? `2:${processedThrough}` : `rebuild:${nextId}`, job.policy_hash, job.workspace_id, Date.now(), Date.now(), Date.now());
+		}
+		return true;
+	});
+}
+function failLearningJob(job, errorCode, canceled = false) {
+	getSqliteDatabase().prepare(`UPDATE memory_learning_jobs SET state = ?, error_code = ?, lease_token = NULL,
+    lease_until = NULL, next_attempt_at = ?, updated_at = ? WHERE job_id = ? AND lease_token = ?`).run(canceled ? "canceled" : job.attempts >= 3 ? "failed" : "retry_wait", errorCode, Date.now() + 3e4 * 2 ** job.attempts, Date.now(), job.job_id, job.lease_token);
+}
+function learningStatus(config) {
+	const db = getSqliteDatabase();
+	return {
+		jobs: db.prepare(`SELECT state, error_code AS errorCode, COUNT(*) AS count FROM (
+      SELECT state, error_code, policy_hash FROM memory_learning_jobs UNION ALL SELECT state, error_code, policy_hash FROM memory_source_learning_jobs
+    ) ${config ? "WHERE policy_hash = ?" : ""} GROUP BY state, error_code`).all(...config ? [learningPolicyHash(config)] : []),
+		coverage: db.prepare("SELECT record_class AS recordClass, status, verification, COUNT(*) AS count FROM knowledge_items GROUP BY record_class, status, verification").all()
+	};
+}
+//#endregion
+export { claimLearningJob, enqueueConversationLearning, failLearningJob, finishLearningJob, learningPolicyHash, learningStatus, renewLearningLease };

package/dist/src/memory-learning/service.d.ts

@@ -0,0 +1,17 @@
+import type { Config } from '../config/schema.js';
+import { type LearningJob } from './repository.js';
+export declare class MemoryLearningService {
+    private readonly options;
+    private timer?;
+    private running;
+    private stopped;
+    private lastRetentionSweep;
+    constructor(options: {
+        getConfig: () => Config | undefined;
+        workspaceForSession: (id: string) => string;
+        execute: (job: LearningJob) => Promise<void>;
+    });
+    start(): void;
+    stop(): void;
+    runNow(): Promise<void>;
+}