@xopcai/xopc 0.0.217 → 0.0.219

package/dist/src/user-context/retriever.js

@@ -1,5 +1,5 @@
 import { summarizeUnderstandingFeedback } from "../storage/sqlite/user-context-quality-repository.js";
-import { listUnderstandings, searchActiveUnderstandings } from "../storage/sqlite/user-context-repository.js";
+import { listUnderstandingEvidence, listUnderstandings, searchActiveUnderstandings } from "../storage/sqlite/user-context-repository.js";
 import { normalizeRetrievalText, retrievalLexicalSimilarity } from "../retrieval/textFeatures.js";
 import { buildRetrievalQueryProfile } from "../retrieval/queryProfile.js";
 import "../storage/sqlite/index.js";
@@ -12,9 +12,62 @@ function authorityBonus(item) {
 }
 function baseline(item) {
 	if (item.kind === "boundary" && item.explicitness === "explicit") return .8;
-	if (item.kind === "preference" && item.explicitness === "explicit") return .35;
+	if (item.kind === "preference" && item.explicitness === "explicit") return .12;
 	return 0;
 }
+function temporalAdjustment(item, hints, now) {
+	if (!hints.length) return 0;
+	let score = 0;
+	if (hints.includes("historical")) score += item.validTo !== void 0 || item.status === "archived" || item.status === "stale" ? .14 : -.6;
+	if (hints.includes("current")) {
+		if (item.kind === "current_state" || item.validFrom !== void 0 || item.validTo !== void 0) {
+			const validNow = (item.validFrom === void 0 || item.validFrom <= now) && (item.validTo === void 0 || item.validTo > now);
+			score += validNow ? .08 : -.15;
+			if (item.kind === "current_state") score += .06;
+		}
+	}
+	if (hints.includes("recent")) score += now - item.updatedAt <= 2160 * 60 * 6e4 ? .08 : -.04;
+	if (hints.includes("future")) {
+		if ((item.validFrom ?? 0) > now || item.kind === "long_term_goal") score += .1;
+	}
+	return score;
+}
+function sourceBucket(item) {
+	if (item.explicitness === "explicit") return "user";
+	const evidence = listUnderstandingEvidence(item.id)[0];
+	if (!evidence) return `unknown:${item.id}`;
+	if (evidence.sourceInstanceId) return `${evidence.sourceType}:${evidence.sourceInstanceId}`;
+	return `${evidence.sourceType}:${evidence.sourceRef.split(":entry:")[0]}`;
+}
+function diversify(results, limit) {
+	const remaining = [...results];
+	const selected = [];
+	const sourceCounts = /* @__PURE__ */ new Map();
+	const sourceBuckets = new Map(results.map((result) => [result.understanding.id, sourceBucket(result.understanding)]));
+	while (remaining.length && selected.length < limit) {
+		let bestIndex = 0;
+		let bestScore = Number.NEGATIVE_INFINITY;
+		for (const [index, candidate] of remaining.entries()) {
+			const redundancy = selected.reduce((maximum, chosen) => Math.max(maximum, retrievalLexicalSimilarity(candidate.understanding.statement, chosen.understanding.statement)), 0);
+			const bucket = sourceBuckets.get(candidate.understanding.id);
+			const sourcePenalty = candidate.understanding.explicitness === "explicit" ? 0 : (sourceCounts.get(bucket) ?? 0) * .04;
+			const adjusted = candidate.score - redundancy * .18 - sourcePenalty;
+			if (adjusted > bestScore) {
+				bestScore = adjusted;
+				bestIndex = index;
+			}
+		}
+		const candidate = remaining.splice(bestIndex, 1)[0];
+		const bucket = sourceBuckets.get(candidate.understanding.id);
+		sourceCounts.set(bucket, (sourceCounts.get(bucket) ?? 0) + 1);
+		selected.push({
+			...candidate,
+			score: Math.max(0, bestScore),
+			reasons: bestScore < candidate.score ? [...candidate.reasons, "diversified"] : candidate.reasons
+		});
+	}
+	return selected;
+}
 function feedbackAdjustment(summary) {
 	if (!summary || summary.total < 3) return 0;
 	const helpfulRate = (summary.helpful + 1) / (summary.total + 2);
@@ -30,35 +83,42 @@ var UserUnderstandingRetriever = class {
 		});
 		if (!profile.normalized) return [];
 		const maxCandidates = Math.max(1, Math.min(200, Math.floor(params.maxCandidates)));
-		const fts = searchActiveUnderstandings(profile.normalized, Math.max(50, maxCandidates));
+		const fts = searchActiveUnderstandings(profile.expanded, Math.max(50, maxCandidates));
 		const ftsScores = new Map(fts.map((result) => [result.understanding.id, result.score]));
 		const recentLimit = Math.max(200, Math.min(500, maxCandidates * 5));
-		const recent = listUnderstandings(["active"]).slice(0, recentLimit);
+		const recent = listUnderstandings([...profile.timeHints.includes("historical") ? [
+			"active",
+			"archived",
+			"stale"
+		] : ["active"]]).slice(0, recentLimit);
 		const candidates = /* @__PURE__ */ new Map();
 		for (const result of fts) candidates.set(result.understanding.id, result.understanding);
 		for (const item of recent) candidates.set(item.id, item);
 		const feedback = new Map(summarizeUnderstandingFeedback([...candidates.keys()]).map((summary) => [summary.understandingId, summary]));
-		return [...candidates.values()].map((item) => {
-			const lexical = retrievalLexicalSimilarity(profile.normalized, item.statement);
+		const now = Date.now();
+		return diversify([...candidates.values()].map((item) => {
+			const lexical = Math.max(retrievalLexicalSimilarity(profile.normalized, item.statement), retrievalLexicalSimilarity(profile.expanded, item.statement));
 			const ftsScore = ftsScores.get(item.id) ?? 0;
 			const textScore = Math.max(lexical, ftsScore);
 			const kindMatched = profile.intentKinds.includes(item.kind);
 			const normalizedStatement = normalizeRetrievalText(item.statement);
 			const identifierMatched = profile.identifiers.some((identifier) => normalizedStatement.includes(identifier));
 			const feedbackScore = feedbackAdjustment(feedback.get(item.id));
+			const kindAdjustment = profile.intentKinds.length > 0 && !kindMatched && profile.timeHints.length === 0 ? -.35 : 0;
 			return {
 				understanding: item,
-				score: Math.min(1, Math.max(0, Math.max(baseline(item), textScore * .7 + lexical * .1 + item.confidence * .1 + authorityBonus(item) + (kindMatched ? .08 : 0) + (identifierMatched ? .12 : 0) + (matchesUserContextScope(item.scope, params) && item.scope.type !== "global" ? .05 : 0)) + feedbackScore)),
+				score: Math.min(1, Math.max(0, Math.max(baseline(item), textScore * .7 + lexical * .1 + item.confidence * .1 + authorityBonus(item) + (kindMatched ? .08 : 0) + kindAdjustment + (identifierMatched ? .12 : 0) + temporalAdjustment(item, profile.timeHints, now) + (matchesUserContextScope(item.scope, params) && item.scope.type !== "global" ? .05 : 0)) + feedbackScore)),
 				reasons: [
 					ftsScore > 0 ? "fts" : "",
 					lexical > 0 ? "lexical" : "",
 					identifierMatched ? "identifier" : "",
 					kindMatched ? "kind" : "",
 					item.explicitness === "explicit" ? "explicit" : "",
-					feedbackScore !== 0 ? "feedback" : ""
+					feedbackScore !== 0 ? "feedback" : "",
+					temporalAdjustment(item, profile.timeHints, now) !== 0 ? "temporal" : ""
 				].filter(Boolean)
 			};
-		}).sort((left, right) => Number(matchesUserContextScope(right.understanding.scope, params)) - Number(matchesUserContextScope(left.understanding.scope, params)) || right.score - left.score || right.understanding.updatedAt - left.understanding.updatedAt).slice(0, maxCandidates);
+		}).sort((left, right) => Number(matchesUserContextScope(right.understanding.scope, params)) - Number(matchesUserContextScope(left.understanding.scope, params)) || right.score - left.score || right.understanding.updatedAt - left.understanding.updatedAt), maxCandidates);
 	}
 };
 //#endregion

package/dist/src/user-context/sources/catalog.js

@@ -18,7 +18,7 @@ const COMMON = [
 		category: "recent_documents",
 		platform: "all",
 		displayName: "Recent files",
-		description: "Read-only metadata for recent documents on Desktop, Documents, and Downloads.",
+		description: "Bounded text from recent readable documents on Desktop, Documents, and Downloads.",
 		availability: "available",
 		permission: "not_requested",
 		defaultAccessMode: "once",
@@ -114,6 +114,13 @@ const PLATFORM = {
 			"Recent unlocked notes selected through macOS Automation",
 			true
 		],
+		[
+			"apple-mail",
+			"mail",
+			"Apple Mail",
+			"Recent inbox and sent-message content selected through macOS Automation",
+			true
+		],
 		[
 			"apple-calendar",
 			"calendar",
@@ -138,7 +145,7 @@ const PLATFORM = {
 		permission: "not_requested",
 		defaultAccessMode: "once",
 		supportedAccessModes: ["once"],
-		recommended: category !== "notes",
+		recommended: category !== "notes" && category !== "mail",
 		sensitive: Boolean(sensitive)
 	})),
 	win32: [{

package/dist/src/user-context/sources/index.js

@@ -1,4 +1,4 @@
-import { createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant, upsertUserFocus } from "./repository.js";
+import { createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocusEvidence, listUserFocuses, revokeUnderstandingSourceGrant, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceGrantPolicies, updateUnderstandingSourceRun, updateUserFocus, upsertUnderstandingSourceGrant, upsertUserFocus } from "./repository.js";
 import { clusterUnderstandingSignals, tokenizeUnderstandingSignal } from "./signal-clustering.js";
 import { listUnderstandingSourceDefinitions } from "./catalog.js";
-export { clusterUnderstandingSignals, createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceDefinitions, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus, tokenizeUnderstandingSignal, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant, upsertUserFocus };
+export { clusterUnderstandingSignals, createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceDefinitions, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocusEvidence, listUserFocuses, revokeUnderstandingSourceGrant, tokenizeUnderstandingSignal, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceGrantPolicies, updateUnderstandingSourceRun, updateUserFocus, upsertUnderstandingSourceGrant, upsertUserFocus };

package/dist/src/user-context/sources/local-source-contract.d.ts

@@ -1,3 +1,3 @@
-export declare const LOCAL_UNDERSTANDING_SOURCE_IDS: readonly ["local-recent-files", "chromium-bookmarks", "apple-notes", "apple-calendar", "apple-reminders", "windows-recent-documents", "linux-recent-documents"];
+export declare const LOCAL_UNDERSTANDING_SOURCE_IDS: readonly ["local-recent-files", "chromium-bookmarks", "apple-notes", "apple-mail", "apple-calendar", "apple-reminders", "windows-recent-documents", "linux-recent-documents"];
 export type LocalUnderstandingSourceId = typeof LOCAL_UNDERSTANDING_SOURCE_IDS[number];
 export declare function isLocalUnderstandingSourceId(value: string): value is LocalUnderstandingSourceId;

package/dist/src/user-context/sources/local-source-contract.js

@@ -3,6 +3,7 @@ const LOCAL_UNDERSTANDING_SOURCE_IDS = [
 	"local-recent-files",
 	"chromium-bookmarks",
 	"apple-notes",
+	"apple-mail",
 	"apple-calendar",
 	"apple-reminders",
 	"windows-recent-documents",

package/dist/src/user-context/sources/processing-policy.d.ts

@@ -0,0 +1,2 @@
+import type { UnderstandingSourceProcessingPolicy } from './types.js';
+export declare function allowsRemoteSourceProcessing(policies: Iterable<UnderstandingSourceProcessingPolicy>): boolean;

package/dist/src/user-context/sources/processing-policy.js

@@ -0,0 +1,7 @@
+//#region src/user-context/sources/processing-policy.ts
+function allowsRemoteSourceProcessing(policies) {
+	for (const policy of policies) if (policy !== "remote_allowed") return false;
+	return true;
+}
+//#endregion
+export { allowsRemoteSourceProcessing };

package/dist/src/user-context/sources/repository.d.ts

@@ -1,4 +1,18 @@
+import { type ContextEvidence, type UserContextScope } from '../domain.js';
 import type { UnderstandingSourceGrant, UnderstandingSourceRun, UserFocus } from './types.js';
+type UserFocusInput = Omit<UserFocus, 'id' | 'versionId' | 'principalId' | 'scope' | 'explicitness' | 'sensitivity' | 'disclosurePolicy' | 'validFrom' | 'validTo' | 'reviewAt' | 'createdAt' | 'updatedAt'> & {
+    principalId?: string;
+    scope?: UserContextScope;
+    explicitness?: UserFocus['explicitness'];
+    sensitivity?: UserFocus['sensitivity'];
+    disclosurePolicy?: UserFocus['disclosurePolicy'];
+    validFrom?: number;
+    validTo?: number;
+    reviewAt?: number;
+    changeReason?: string;
+    nowMs?: number;
+};
+export declare function listUserFocusEvidence(focusId: string): ContextEvidence[];
 export declare function listUnderstandingSourceGrants(options?: {
     includeRevoked?: boolean;
 }): UnderstandingSourceGrant[];
@@ -13,6 +27,12 @@ export declare function updateUnderstandingSourceGrantCheckpoint(id: string, inp
     lastCollectedAt?: number;
     nowMs?: number;
 }): UnderstandingSourceGrant | null;
+export declare function updateUnderstandingSourceGrantPolicies(id: string, patch: {
+    accessMode?: UnderstandingSourceGrant['accessMode'];
+    retentionPolicy?: UnderstandingSourceGrant['retentionPolicy'];
+    processingPolicy?: UnderstandingSourceGrant['processingPolicy'];
+    nowMs?: number;
+}): UnderstandingSourceGrant | null;
 export declare function revokeUnderstandingSourceGrant(id: string, nowMs?: number): UnderstandingSourceGrant | null;
 export declare function createUnderstandingSourceRun(input: {
     grantId: string;
@@ -33,9 +53,8 @@ export declare function updateUnderstandingSourceRun(id: string, patch: {
     completed?: boolean;
     nowMs?: number;
 }): UnderstandingSourceRun | null;
-export declare function upsertUserFocus(input: Omit<UserFocus, 'id' | 'createdAt' | 'updatedAt'> & {
-    nowMs?: number;
-}): UserFocus;
+export declare function upsertUserFocus(input: UserFocusInput): UserFocus;
 export declare function listUserFocuses(statuses?: UserFocus['status'][]): UserFocus[];
-export declare function setUserFocusStatus(id: string, status: UserFocus['status'], nowMs?: number): UserFocus | null;
+export declare function updateUserFocus(id: string, patch: Partial<Pick<UserFocus, 'title' | 'summary' | 'status'>>, nowMs?: number): UserFocus | null;
 export declare function deleteUserFocus(id: string): boolean;
+export {};

package/dist/src/user-context/sources/repository.js

@@ -1,4 +1,5 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import "../domain.js";
 import { randomUUID } from "node:crypto";
 //#region src/user-context/sources/repository.ts
 function record(value) {
@@ -53,19 +54,82 @@ function runFromRow(row) {
 function focusFromRow(row) {
 	return {
 		id: row.focus_id,
+		versionId: row.current_version_id,
+		principalId: row.principal_id,
 		canonicalKey: row.canonical_key,
 		title: row.title,
 		summary: row.summary,
 		horizon: row.horizon,
 		status: row.status,
 		confidence: row.confidence,
-		...row.project_id ? { projectId: row.project_id } : {},
+		scope: {
+			type: row.scope_type,
+			...row.scope_id ? { id: row.scope_id } : {}
+		},
+		explicitness: row.explicitness,
+		sensitivity: row.sensitivity,
+		disclosurePolicy: row.disclosure_policy,
+		...row.valid_from == null ? {} : { validFrom: row.valid_from },
+		...row.valid_to == null ? {} : { validTo: row.valid_to },
+		...row.review_at == null ? {} : { reviewAt: row.review_at },
 		evidenceRefs: strings(row.evidence_refs_json),
 		...row.source_run_id ? { sourceRunId: row.source_run_id } : {},
 		createdAt: row.created_at,
 		updatedAt: row.updated_at
 	};
 }
+function focusSnapshot(row) {
+	return {
+		horizon: row.horizon,
+		status: row.status,
+		confidence: row.confidence,
+		scopeType: row.scope_type,
+		scopeId: row.scope_id,
+		explicitness: row.explicitness,
+		sensitivity: row.sensitivity,
+		disclosurePolicy: row.disclosure_policy,
+		validFrom: row.valid_from,
+		validTo: row.valid_to,
+		reviewAt: row.review_at,
+		evidenceRefs: strings(row.evidence_refs_json)
+	};
+}
+function sameFocusVersion(left, right) {
+	return Boolean(left && left.title === right.title && left.summary === right.summary && JSON.stringify(focusSnapshot(left)) === JSON.stringify(focusSnapshot(right)));
+}
+function linkFocusEvidence(versionId, evidenceRefs, confidence) {
+	if (!evidenceRefs.length) return;
+	const placeholders = evidenceRefs.map(() => "?").join(", ");
+	getSqliteDatabase().prepare(`INSERT OR IGNORE INTO user_focus_evidence_links (
+    version_id, evidence_id, relation, confidence
+  ) SELECT ?, evidence_id, 'supports', ? FROM context_evidence WHERE source_ref IN (${placeholders})`).run(versionId, confidence, ...evidenceRefs);
+}
+function listUserFocusEvidence(focusId) {
+	return getSqliteDatabase().prepare(`SELECT DISTINCT e.* FROM context_evidence e
+    JOIN user_focus_evidence_links l ON l.evidence_id = e.evidence_id
+    JOIN user_focus_versions v ON v.version_id = l.version_id
+    WHERE v.focus_id = ? ORDER BY e.observed_at DESC`).all(focusId).map((row) => ({
+		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 listUnderstandingSourceGrants(options = {}) {
 	return getSqliteDatabase().prepare(`SELECT * FROM understanding_source_grants ${options.includeRevoked ? "" : "WHERE status = 'active'"} ORDER BY updated_at DESC`).all().map(grantFromRow);
 }
@@ -85,8 +149,7 @@ function upsertUnderstandingSourceGrant(input) {
     ) VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(source_key) DO UPDATE SET
       adapter_id = excluded.adapter_id, category = excluded.category, platform = excluded.platform,
-      display_name = excluded.display_name, status = 'active', access_mode = excluded.access_mode,
-      retention_policy = excluded.retention_policy, processing_policy = excluded.processing_policy,
+      display_name = excluded.display_name, status = 'active',
       config_json = excluded.config_json, checkpoint_json = excluded.checkpoint_json,
       last_collected_at = COALESCE(excluded.last_collected_at, understanding_source_grants.last_collected_at),
       updated_at = excluded.updated_at
@@ -104,6 +167,16 @@ function updateUnderstandingSourceGrantCheckpoint(id, input) {
   `).run(JSON.stringify(input.checkpoint ?? current.checkpoint), input.lastCollectedAt ?? current.lastCollectedAt ?? null, now, id));
 	return getUnderstandingSourceGrant(id);
 }
+function updateUnderstandingSourceGrantPolicies(id, patch) {
+	const current = getUnderstandingSourceGrant(id);
+	if (!current) return null;
+	runSqliteWriteTransaction((db) => db.prepare(`
+    UPDATE understanding_source_grants
+    SET access_mode = ?, retention_policy = ?, processing_policy = ?, updated_at = ?
+    WHERE grant_id = ?
+  `).run(patch.accessMode ?? current.accessMode, patch.retentionPolicy ?? current.retentionPolicy, patch.processingPolicy ?? current.processingPolicy, patch.nowMs ?? Date.now(), id));
+	return getUnderstandingSourceGrant(id);
+}
 function revokeUnderstandingSourceGrant(id, nowMs = Date.now()) {
 	runSqliteWriteTransaction((db) => db.prepare("UPDATE understanding_source_grants SET status = 'revoked', updated_at = ? WHERE grant_id = ?").run(nowMs, id));
 	return getUnderstandingSourceGrant(id);
@@ -138,11 +211,20 @@ function updateUnderstandingSourceRun(id, patch) {
 function upsertUserFocus(input) {
 	const id = randomUUID();
 	const now = input.nowMs ?? Date.now();
-	runSqliteWriteTransaction((db) => db.prepare(`
+	const scope = input.scope ?? { type: "global" };
+	const explicitness = input.explicitness ?? "inferred";
+	const sensitivity = input.sensitivity ?? "normal";
+	const disclosurePolicy = input.disclosurePolicy ?? "referenceable";
+	const existingRow = getSqliteDatabase().prepare("SELECT * FROM user_focuses WHERE canonical_key = ?").get(input.canonicalKey);
+	if (existingRow?.explicitness === "explicit" && explicitness !== "explicit") return focusFromRow(existingRow);
+	let currentVersionId = existingRow?.current_version_id;
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`
     INSERT INTO user_focuses (
-      focus_id, canonical_key, title, summary, horizon, status, confidence, project_id,
-      evidence_refs_json, source_run_id, created_at, updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      focus_id, principal_id, canonical_key, title, summary, horizon, status, confidence,
+      scope_type, scope_id, explicitness, sensitivity, disclosure_policy,
+      valid_from, valid_to, review_at, evidence_refs_json, source_run_id, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(canonical_key) DO UPDATE SET title = excluded.title, summary = excluded.summary,
       horizon = excluded.horizon,
       status = CASE
@@ -151,9 +233,23 @@ function upsertUserFocus(input) {
         ELSE excluded.status
       END,
       confidence = excluded.confidence,
-      project_id = excluded.project_id, evidence_refs_json = excluded.evidence_refs_json,
+      scope_type = excluded.scope_type, scope_id = excluded.scope_id,
+      explicitness = excluded.explicitness, sensitivity = excluded.sensitivity,
+      disclosure_policy = excluded.disclosure_policy, valid_from = excluded.valid_from,
+      valid_to = excluded.valid_to, review_at = excluded.review_at,
+      evidence_refs_json = excluded.evidence_refs_json,
       source_run_id = excluded.source_run_id, updated_at = excluded.updated_at
-  `).run(id, input.canonicalKey, input.title, input.summary, input.horizon, input.status, input.confidence, input.projectId ?? null, JSON.stringify(input.evidenceRefs), input.sourceRunId ?? null, now, now));
+  `).run(id, input.principalId ?? "local-owner", input.canonicalKey, input.title, input.summary, input.horizon, input.status, input.confidence, scope.type, scope.id ?? null, explicitness, sensitivity, disclosurePolicy, input.validFrom ?? null, input.validTo ?? null, input.reviewAt ?? null, JSON.stringify(input.evidenceRefs), input.sourceRunId ?? null, now, now);
+		const nextRow = db.prepare("SELECT * FROM user_focuses WHERE canonical_key = ?").get(input.canonicalKey);
+		if (!sameFocusVersion(existingRow, nextRow)) {
+			currentVersionId = randomUUID();
+			db.prepare(`INSERT INTO user_focus_versions (
+        version_id, focus_id, title, summary, snapshot_json, created_by, change_reason, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(currentVersionId, nextRow.focus_id, nextRow.title, nextRow.summary, JSON.stringify(focusSnapshot(nextRow)), explicitness === "explicit" ? "user" : input.sourceRunId ? "connector" : "runtime", input.changeReason ?? (existingRow ? "Focus updated" : "Focus created"), now);
+			db.prepare("UPDATE user_focuses SET current_version_id = ? WHERE focus_id = ?").run(currentVersionId, nextRow.focus_id);
+		}
+	});
+	if (currentVersionId) linkFocusEvidence(currentVersionId, input.evidenceRefs, input.confidence);
 	return focusFromRow(getSqliteDatabase().prepare("SELECT * FROM user_focuses WHERE canonical_key = ?").get(input.canonicalKey));
 }
 function listUserFocuses(statuses) {
@@ -161,8 +257,22 @@ function listUserFocuses(statuses) {
 	const placeholders = statuses.map(() => "?").join(", ");
 	return getSqliteDatabase().prepare(`SELECT * FROM user_focuses WHERE status IN (${placeholders}) ORDER BY updated_at DESC`).all(...statuses).map(focusFromRow);
 }
-function setUserFocusStatus(id, status, nowMs = Date.now()) {
-	runSqliteWriteTransaction((db) => db.prepare("UPDATE user_focuses SET status = ?, updated_at = ? WHERE focus_id = ?").run(status, nowMs, id));
+function updateUserFocus(id, patch, nowMs = Date.now()) {
+	const currentRow = getSqliteDatabase().prepare("SELECT * FROM user_focuses WHERE focus_id = ?").get(id);
+	if (!currentRow) return null;
+	const current = focusFromRow(currentRow);
+	if ((patch.title ?? current.title) === current.title && (patch.summary ?? current.summary) === current.summary && (patch.status ?? current.status) === current.status) return current;
+	const versionId = randomUUID();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE user_focuses
+      SET title = ?, summary = ?, status = ?, updated_at = ? WHERE focus_id = ?`).run(patch.title ?? current.title, patch.summary ?? current.summary, patch.status ?? current.status, nowMs, id);
+		const nextRow = db.prepare("SELECT * FROM user_focuses WHERE focus_id = ?").get(id);
+		db.prepare(`INSERT INTO user_focus_versions (
+      version_id, focus_id, title, summary, snapshot_json, created_by, change_reason, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, 'Focus updated', ?)`).run(versionId, id, nextRow.title, nextRow.summary, JSON.stringify(focusSnapshot(nextRow)), current.explicitness === "explicit" ? "user" : "runtime", nowMs);
+		db.prepare("UPDATE user_focuses SET current_version_id = ? WHERE focus_id = ?").run(versionId, id);
+	});
+	linkFocusEvidence(versionId, current.evidenceRefs, current.confidence);
 	const row = getSqliteDatabase().prepare("SELECT * FROM user_focuses WHERE focus_id = ?").get(id);
 	return row ? focusFromRow(row) : null;
 }
@@ -170,4 +280,4 @@ function deleteUserFocus(id) {
 	return Number(getSqliteDatabase().prepare("DELETE FROM user_focuses WHERE focus_id = ?").run(id).changes) > 0;
 }
 //#endregion
-export { createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant, upsertUserFocus };
+export { createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocusEvidence, listUserFocuses, revokeUnderstandingSourceGrant, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceGrantPolicies, updateUnderstandingSourceRun, updateUserFocus, upsertUnderstandingSourceGrant, upsertUserFocus };

package/dist/src/user-context/sources/types.d.ts

@@ -1,3 +1,4 @@
+import type { UserContextScope, UserUnderstanding } from '../domain.js';
 export type UnderstandingSourcePlatform = 'darwin' | 'win32' | 'linux' | 'all';
 export type UnderstandingSourceCategory = 'files' | 'recent_documents' | 'calendar' | 'tasks' | 'notes' | 'mail' | 'messages' | 'code_activity';
 export type UnderstandingSourceAccessMode = 'once' | 'continuous';
@@ -75,13 +76,21 @@ export interface UnderstandingSourceRun {
 }
 export interface UserFocus {
     id: string;
+    versionId: string;
+    principalId: string;
     canonicalKey: string;
     title: string;
     summary: string;
     horizon: 'current' | 'ongoing' | 'long_term';
     status: 'candidate' | 'active' | 'paused' | 'completed' | 'rejected';
     confidence: number;
-    projectId?: string;
+    scope: UserContextScope;
+    explicitness: UserUnderstanding['explicitness'];
+    sensitivity: UserUnderstanding['sensitivity'];
+    disclosurePolicy: UserUnderstanding['disclosurePolicy'];
+    validFrom?: number;
+    validTo?: number;
+    reviewAt?: number;
     evidenceRefs: string[];
     sourceRunId?: string;
     createdAt: number;

package/dist/src/user-context/understanding-writing.d.ts

@@ -0,0 +1 @@
+export declare const USER_FACING_UNDERSTANDING_WRITING_GUIDANCE = "Write each understanding as concise, neutral profile copy that can be shown directly to the person described, not as an internal note about \"the user\". Prefer a subject-omitted predicate or noun phrase. For example, write \u201C\u503E\u5411\u4F7F\u7528 pnpm \u4F5C\u4E3A\u5305\u7BA1\u7406\u5668\u201D or \u201Cxopc \u9879\u76EE\u7684\u6838\u5FC3\u5F00\u53D1\u8005\u201D, not \u201C\u7528\u6237\u503E\u5411\u4E8E\u4F7F\u7528 pnpm\u201D or \u201C\u7528\u6237\u662F xopc \u9879\u76EE\u7684\u5F00\u53D1\u8005\u201D; write \u201CPrefers pnpm as the package manager\u201D or \u201CCore maintainer of xopc\u201D, not \u201CThe user prefers pnpm\u201D or \u201CThe user is a maintainer of xopc\u201D. Do not begin with generic subject labels or pronouns such as \u201C\u7528\u6237\u201D, \u201C\u8BE5\u7528\u6237\u201D, \u201C\u6B64\u7528\u6237\u201D, \u201C\u4F60\u201D, \u201C\u6211\u201D, \u201Cthe user\u201D, \u201Cuser\u201D, \u201Cyou\u201D, or \u201CI\u201D.";

package/dist/src/user-context/understanding-writing.js

@@ -0,0 +1,4 @@
+//#region src/user-context/understanding-writing.ts
+const USER_FACING_UNDERSTANDING_WRITING_GUIDANCE = `Write each understanding as concise, neutral profile copy that can be shown directly to the person described, not as an internal note about "the user". Prefer a subject-omitted predicate or noun phrase. For example, write “倾向使用 pnpm 作为包管理器” or “xopc 项目的核心开发者”, not “用户倾向于使用 pnpm” or “用户是 xopc 项目的开发者”; write “Prefers pnpm as the package manager” or “Core maintainer of xopc”, not “The user prefers pnpm” or “The user is a maintainer of xopc”. Do not begin with generic subject labels or pronouns such as “用户”, “该用户”, “此用户”, “你”, “我”, “the user”, “user”, “you”, or “I”.`;
+//#endregion
+export { USER_FACING_UNDERSTANDING_WRITING_GUIDANCE };

package/dist/src/user-context/understanding.js

@@ -8,7 +8,7 @@ function canonicalUnderstandingKey(kind, statement) {
 function isSameUserContextScope(left, right) {
 	return left.type === right.type && left.id === right.id;
 }
-const NEGATION = /\b(?:do not|don't|never|avoid|without)\b|(?:不要|不用|无需|从不|避免|禁止)/i;
+const NEGATION = /\b(?:do not|don't|not|never|avoid|without)\b|(?:不要|不用|无需|从不|避免|禁止)/i;
 function withoutNegation(statement) {
 	return statement.replace(NEGATION, "").replace(/\s+/g, " ").trim();
 }

package/dist/src/work-discovery/analyzer.d.ts

@@ -10,6 +10,11 @@ export declare function analyzeWorkContext(input: {
     modelRef: string;
     result: WorkDiscoveryResult;
 }>;
+export type UnderstandingSourceAnalysisStatus = {
+    sourceId: string;
+    status: 'completed' | 'partial' | 'failed';
+    error?: string;
+};
 export declare function analyzeUnderstandingSources(input: {
     config: Config;
     items: UnderstandingSourceItem[];
@@ -19,5 +24,6 @@ export declare function analyzeUnderstandingSources(input: {
     modelRef: string;
     profileCandidates: WorkDiscoveryProfileCandidate[];
     workThreadCandidates: WorkUnderstandingThreadCandidate[];
+    sourceStatuses: UnderstandingSourceAnalysisStatus[];
 }>;
 export declare function workDiscoveryResultMarkdown(result: WorkDiscoveryResult): string;