@xopcai/xopc 0.0.218 → 0.0.220

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

@@ -1,14 +1,34 @@
-import { consumeContextConsent, ensureContextConsent, getUserProfile, listCollaborationRules, recordContextRun } from "../storage/sqlite/user-context-repository.js";
+import { consumeContextConsent, ensureContextConsent, getUserProfile, listCollaborationRules, listUnderstandingEvidence, listUnderstandings, recordContextRun } from "../storage/sqlite/user-context-repository.js";
+import { retrievalLexicalSimilarity } from "../retrieval/textFeatures.js";
+import { buildRetrievalQueryProfile } from "../retrieval/queryProfile.js";
 import "../storage/sqlite/index.js";
+import { init_session_key, parseSessionKey } from "../routing/session-key.js";
+import { ProjectStore } from "../projects/project-store.js";
 import { readAgentMessageContent } from "../agent/memory/agent-message-access.js";
 import { buildUserContextBlock } from "../agent/memory/context-fence.js";
-import { listUserFocuses } from "./sources/repository.js";
+import { getUnderstandingSourceGrant, getUnderstandingSourceRun, listUserFocuses } from "./sources/repository.js";
 import { matchesUserContextScope } from "./scope.js";
 import { UserUnderstandingRetriever } from "./retriever.js";
 import { randomUUID } from "node:crypto";
 //#region src/user-context/planner.ts
+init_session_key();
 const DEFAULT_MAX_CONTEXT_CHARS = 6e3;
 const DEFAULT_MAX_RESULTS = 12;
+const SELF_REVIEW_MAX_CONTEXT_CHARS = 16e3;
+const SELF_REVIEW_MAX_RESULTS = 50;
+const MAX_FOCUS_RESULTS = 3;
+const MIN_RELEVANCE_SCORE = .25;
+function selfReviewScore(item) {
+	const authority = item.explicitness === "explicit" ? .2 : item.explicitness === "observed" ? .1 : 0;
+	const durable = item.durability === "durable" ? .1 : item.durability === "recurring" ? .05 : 0;
+	return Math.min(1, item.confidence * .7 + authority + durable);
+}
+function scopeLabel(scope, projects) {
+	if (scope.type === "global") return "Global";
+	if (scope.type === "project") return `Project: ${scope.id ? projects.get(scope.id)?.name ?? scope.id : "unknown"}`;
+	if (scope.type === "workspace") return `Workspace: ${scope.id ?? "unknown"}`;
+	return "This conversation";
+}
 function prependAgentContext(message, block) {
 	if (!block) return message;
 	const prefix = `${block}\n\n`;
@@ -44,29 +64,89 @@ function sectionFor(item) {
 	].includes(item.kind)) return "interaction";
 	return "task";
 }
-function originFor(item) {
-	if (item.explicitness === "explicit") return "told_by_user";
-	if (item.explicitness === "observed") return "observed";
-	return "inferred";
+function sourceDescription(item) {
+	if (item.explicitness === "explicit") return {
+		origin: "told_by_user",
+		label: "You told xopc"
+	};
+	const connected = listUnderstandingEvidence(item.id).find((evidence) => evidence.sourceType === "connector");
+	if (connected) return {
+		origin: "connected_source",
+		label: connected.sourceInstanceId ?? "Connected source"
+	};
+	if (item.explicitness === "observed") return {
+		origin: "observed",
+		label: "Observed across prior work"
+	};
+	return {
+		origin: "inferred",
+		label: "An inference that may be wrong"
+	};
 }
-function sourceLabel(item) {
-	if (item.explicitness === "explicit") return "You told xopc";
-	if (item.explicitness === "observed") return "Observed across prior work";
-	return "An inference that may be wrong";
+function focusSourceDescription(focus) {
+	if (focus.explicitness === "explicit") return {
+		origin: "told_by_user",
+		label: "You set this focus"
+	};
+	const sourceRun = focus.sourceRunId ? getUnderstandingSourceRun(focus.sourceRunId) : null;
+	const grant = sourceRun ? getUnderstandingSourceGrant(sourceRun.grantId) : null;
+	if (grant?.adapterId.startsWith("connector:")) return {
+		origin: "connected_source",
+		label: grant.displayName
+	};
+	if (focus.explicitness === "observed") return {
+		origin: "observed",
+		label: "Observed across prior work"
+	};
+	return {
+		origin: "inferred",
+		label: "Suggested from prior work"
+	};
 }
-function rejectionReason(item, input, now) {
-	if (item.status === "needs_review" || item.status === "stale" || item.status === "candidate") return "needs_review";
-	if (item.status === "archived" || item.status === "rejected") return "disabled";
+function rejectionReason(item, input, now, timeHints) {
+	const historical = timeHints.includes("historical") && item.validTo !== void 0;
+	if (item.status === "needs_review" || item.status === "candidate" || item.status === "stale" && !historical) return "needs_review";
+	if (item.status === "rejected" || item.status === "archived" && !historical) return "disabled";
 	if (!matchesUserContextScope(item.scope, input)) return "scope_mismatch";
-	if (item.validFrom && item.validFrom > now) return "not_yet_valid";
-	if (item.validTo && item.validTo < now || item.expiresAt && item.expiresAt < now) return "expired";
+	if (item.validFrom && item.validFrom > now && !timeHints.includes("future")) return "not_yet_valid";
+	if ((item.validTo && item.validTo < now || item.expiresAt && item.expiresAt < now) && !historical) return "expired";
 	if (item.sensitivity === "secret" || item.sensitivity === "regulated") return "sensitive";
 	if (item.conflictGroupId) return "conflict";
 }
 function ruleMatches(rule, input) {
 	if (rule.status !== "active" || !matchesUserContextScope(rule.scope, input)) return false;
 	const channel = typeof rule.conditions.channel === "string" ? rule.conditions.channel : void 0;
-	return !channel || channel === input.channel;
+	const agentId = typeof rule.conditions.agentId === "string" ? rule.conditions.agentId : void 0;
+	return (!channel || channel === input.channel) && (!agentId || agentId === input.agentId);
+}
+function focusRejectionReason(focus, input, now) {
+	if (focus.status !== "active") return "disabled";
+	if (!matchesUserContextScope(focus.scope, input)) return "scope_mismatch";
+	if (focus.validFrom && focus.validFrom > now) return "not_yet_valid";
+	if (focus.validTo && focus.validTo < now) return "expired";
+	if (focus.sensitivity === "secret" || focus.sensitivity === "regulated") return "sensitive";
+	if (focus.disclosurePolicy === "ask_before_reference") return "requires_consent";
+}
+function focusScore(focus, query, scopeInput) {
+	const lexical = retrievalLexicalSimilarity(buildRetrievalQueryProfile(query, scopeInput).normalized, `${focus.title} ${focus.summary}`);
+	const scoped = focus.scope.type !== "global" && matchesUserContextScope(focus.scope, scopeInput);
+	return Math.min(1, lexical * .75 + focus.confidence * .15 + (scoped ? .25 : 0));
+}
+function renderContextBlock(params) {
+	const understandingItems = params.items.filter((item) => item.objectType === "understanding");
+	return [
+		params.selfReview ? [
+			"<user-context-review>",
+			"The user explicitly asked what xopc understands about them. This is a review of active, non-sensitive structured understanding across scopes.",
+			"Scope labels describe where each item applies. Do not present project facts as global personality traits.",
+			"An empty memory_search result does not mean structured user understanding is empty.",
+			"</user-context-review>"
+		].join("\n") : "",
+		params.profileLines.length ? `<user-profile>\n${params.profileLines.join("\n")}\n</user-profile>` : "",
+		params.focuses.length ? `<active-focuses>\n${params.focuses.map((focus) => `- ${params.selfReview ? `[${scopeLabel(focus.scope, params.projects)}] ` : ""}${focus.title}: ${focus.summary} (${focus.horizon})`).join("\n")}\n</active-focuses>` : "",
+		params.rules.length ? `<collaboration-contract>\n${params.rules.map((rule) => `- ${rule.statement}`).join("\n")}\n</collaboration-contract>` : "",
+		understandingItems.length ? buildUserContextBlock(understandingItems.map((item) => `- ${item.content}\n  Evidence: ${params.understandingSources.get(item.recordId) ?? "Unknown source"}`).join("\n")) : ""
+	].filter(Boolean).join("\n\n");
 }
 var UserContextPlanner = class {
 	retriever = new UserUnderstandingRetriever();
@@ -84,19 +164,37 @@ var UserContextPlanner = class {
 		};
 		const started = Date.now();
 		const now = Date.now();
-		const maxResults = params.allocation?.maxResults ?? DEFAULT_MAX_RESULTS;
-		const maxChars = params.allocation?.maxChars ?? DEFAULT_MAX_CONTEXT_CHARS;
+		const requestedMaxResults = params.allocation?.maxResults;
+		const requestedMaxChars = params.allocation?.maxChars;
 		const scopeInput = {
 			sessionKey: params.sessionKey,
 			workspaceId: params.workspaceId,
 			...params.projectId ? { projectId: params.projectId } : {}
 		};
+		const queryProfile = buildRetrievalQueryProfile(query, scopeInput);
+		const selfReview = queryProfile.selfReview;
+		const maxResults = requestedMaxResults ?? (selfReview ? SELF_REVIEW_MAX_RESULTS : DEFAULT_MAX_RESULTS);
+		const maxChars = requestedMaxChars ?? (selfReview ? SELF_REVIEW_MAX_CONTEXT_CHARS : DEFAULT_MAX_CONTEXT_CHARS);
+		const projects = new ProjectStore();
 		const excluded = new Set(params.excludedRecordIds ?? []);
 		const rejected = [];
 		const consentRequests = [];
 		const traceItems = [];
 		const items = [];
+		const selectedFocuses = [];
+		const selectedRules = [];
+		const understandingSources = /* @__PURE__ */ new Map();
 		let usedChars = 0;
+		const render = (overrides = {}) => renderContextBlock({
+			profileLines,
+			focuses: selectedFocuses,
+			rules: selectedRules,
+			items,
+			understandingSources,
+			selfReview,
+			projects,
+			...overrides
+		});
 		const profile = getUserProfile();
 		const profileLines = [
 			profile.callName ? `Preferred name: ${profile.callName}` : "",
@@ -108,28 +206,105 @@ var UserContextPlanner = class {
 		].filter(Boolean);
 		if (profileLines.length) {
 			const content = profileLines.join("\n");
+			const nextChars = render().length;
+			if (nextChars <= maxChars) {
+				traceItems.push({
+					objectType: "profile",
+					objectId: "profile",
+					decision: "selected",
+					reason: "User-provided profile",
+					content,
+					sourceLabel: "You provided this directly",
+					origin: "told_by_user",
+					rank: 0,
+					score: 1,
+					injectedChars: nextChars
+				});
+				usedChars = nextChars;
+			} else {
+				profileLines.length = 0;
+				traceItems.push({
+					objectType: "profile",
+					objectId: "profile",
+					decision: "budget_exceeded",
+					reason: "Context budget reached",
+					content,
+					sourceLabel: "You provided this directly",
+					origin: "told_by_user",
+					injectedChars: 0
+				});
+			}
+		}
+		const rankedFocuses = listUserFocuses(["active"]).map((focus) => ({
+			focus,
+			score: focusScore(focus, query, scopeInput)
+		})).sort((left, right) => selfReview ? right.focus.confidence - left.focus.confidence || right.focus.updatedAt - left.focus.updatedAt : right.score - left.score || right.focus.updatedAt - left.focus.updatedAt);
+		for (const { focus, score } of rankedFocuses) {
+			const source = focusSourceDescription(focus);
+			let reason = focusRejectionReason(focus, scopeInput, now);
+			if (selfReview && reason === "scope_mismatch") reason = void 0;
+			if (!reason && !selfReview && score <= MIN_RELEVANCE_SCORE) reason = "low_score";
+			if (!reason && selectedFocuses.length >= (selfReview ? maxResults : MAX_FOCUS_RESULTS)) reason = "budget";
+			if (!reason && items.length >= maxResults) reason = "budget";
+			const focusScope = scopeLabel(focus.scope, projects);
+			const content = `${selfReview ? `[${focusScope}] ` : ""}${focus.title}: ${focus.summary} (${focus.horizon})`;
+			const nextChars = render({ focuses: [...selectedFocuses, focus] }).length;
+			if (!reason && nextChars > maxChars) reason = "budget";
+			if (reason) {
+				rejected.push({
+					recordId: focus.id,
+					reason
+				});
+				traceItems.push({
+					objectType: "focus",
+					objectId: focus.id,
+					versionId: focus.versionId,
+					decision: reason === "budget" ? "budget_exceeded" : reason === "requires_consent" ? "needs_consent" : reason === "scope_mismatch" ? "scope_mismatch" : reason === "expired" ? "expired" : reason === "sensitive" ? "sensitive" : reason === "disabled" ? "disabled" : "irrelevant",
+					reason,
+					content,
+					sourceLabel: source.label,
+					origin: source.origin,
+					score,
+					injectedChars: 0
+				});
+				continue;
+			}
+			const addedChars = nextChars - usedChars;
+			usedChars = nextChars;
+			selectedFocuses.push(focus);
+			items.push({
+				recordId: focus.id,
+				objectType: "focus",
+				versionId: focus.versionId,
+				content,
+				score,
+				section: "task",
+				citation: `user-focus://${focus.id}`,
+				origin: source.origin,
+				stability: focus.confidence
+			});
 			traceItems.push({
-				objectType: "profile",
-				objectId: "profile",
+				objectType: "focus",
+				objectId: focus.id,
+				versionId: focus.versionId,
 				decision: "selected",
-				reason: "User-provided profile",
+				reason: "Relevant active focus",
 				content,
-				sourceLabel: "You provided this directly",
-				rank: 0,
-				score: 1,
-				injectedChars: content.length
+				sourceLabel: source.label,
+				origin: source.origin,
+				rank: items.length,
+				score,
+				injectedChars: addedChars
 			});
-			usedChars += content.length;
 		}
-		const activeFocusLines = listUserFocuses(["active"]).slice(0, 5).map((focus) => `- ${focus.title}: ${focus.summary} (${focus.horizon})`);
-		if (activeFocusLines.length) usedChars += activeFocusLines.join("\n").length;
 		const rules = listCollaborationRules().filter((rule) => ruleMatches(rule, {
 			...scopeInput,
-			channel: params.channel
+			channel: params.channel,
+			agentId: parseSessionKey(params.sessionKey)?.agentId
 		}));
-		const selectedRules = [];
 		for (const [index, rule] of rules.entries()) {
-			if (usedChars + rule.statement.length > maxChars) {
+			const nextChars = render({ rules: [...selectedRules, rule] }).length;
+			if (nextChars > maxChars) {
 				traceItems.push({
 					objectType: "rule",
 					objectId: rule.id,
@@ -138,11 +313,13 @@ var UserContextPlanner = class {
 					reason: "Context budget reached",
 					content: rule.statement,
 					sourceLabel: "Your collaboration rule",
+					origin: "told_by_user",
 					injectedChars: 0
 				});
 				continue;
 			}
-			usedChars += rule.statement.length;
+			const addedChars = nextChars - usedChars;
+			usedChars = nextChars;
 			selectedRules.push(rule);
 			traceItems.push({
 				objectType: "rule",
@@ -152,22 +329,27 @@ var UserContextPlanner = class {
 				reason: "Active collaboration rule",
 				content: rule.statement,
 				sourceLabel: "Your collaboration rule",
+				origin: "told_by_user",
 				rank: index + 1,
 				score: 1,
-				injectedChars: rule.statement.length
+				injectedChars: addedChars
 			});
 		}
-		const ranked = this.retriever.retrieve({
+		const ranked = (selfReview ? listUnderstandings(["active"]).map((item) => ({
+			item,
+			score: selfReviewScore(item)
+		})).sort((left, right) => right.score - left.score || right.item.updatedAt - left.item.updatedAt) : this.retriever.retrieve({
 			query,
 			sessionKey: params.sessionKey,
 			workspaceId: params.workspaceId,
 			...params.projectId ? { projectId: params.projectId } : {},
 			maxCandidates: Math.max(maxResults * 5, 50)
-		}).filter((result) => !excluded.has(result.understanding.id)).map((result) => ({
+		}).map((result) => ({
 			item: result.understanding,
 			score: result.score
-		}));
+		}))).filter(({ item }) => !excluded.has(item.id));
 		for (const { item, score } of ranked) {
+			const source = sourceDescription(item);
 			if (items.length >= maxResults) {
 				rejected.push({
 					recordId: item.id,
@@ -180,14 +362,16 @@ var UserContextPlanner = class {
 					decision: "budget_exceeded",
 					reason: "Maximum result count reached",
 					content: item.statement,
-					sourceLabel: sourceLabel(item),
+					sourceLabel: source.label,
+					origin: source.origin,
 					score,
 					injectedChars: 0
 				});
 				continue;
 			}
-			let reason = rejectionReason(item, scopeInput, now);
-			if (!reason && score < .25) reason = "low_score";
+			let reason = rejectionReason(item, scopeInput, now, queryProfile.timeHints);
+			if (selfReview && reason === "scope_mismatch") reason = void 0;
+			if (!reason && !selfReview && score <= MIN_RELEVANCE_SCORE) reason = "low_score";
 			if (!reason && item.disclosurePolicy === "ask_before_reference") {
 				const consentStatus = consumeContextConsent(item.id, params.sessionKey);
 				if (consentStatus !== "granted") {
@@ -215,13 +399,30 @@ var UserContextPlanner = class {
 					decision: reason === "budget" ? "budget_exceeded" : reason === "requires_consent" ? "needs_consent" : reason === "conflict" ? "conflicted" : reason === "expired" ? "expired" : reason === "sensitive" ? "sensitive" : reason === "scope_mismatch" ? "scope_mismatch" : reason === "disabled" ? "disabled" : "irrelevant",
 					reason,
 					content: item.statement,
-					sourceLabel: sourceLabel(item),
+					sourceLabel: source.label,
+					origin: source.origin,
 					score,
 					injectedChars: 0
 				});
 				continue;
 			}
-			if (usedChars + item.statement.length > maxChars) {
+			const plannedItem = {
+				recordId: item.id,
+				objectType: "understanding",
+				versionId: item.versionId,
+				content: selfReview ? `[${scopeLabel(item.scope, projects)}] ${item.statement}` : item.statement,
+				score,
+				section: sectionFor(item),
+				citation: `user-context://${item.id}`,
+				origin: source.origin,
+				stability: item.confidence
+			};
+			const nextSources = new Map(understandingSources).set(item.id, source.label);
+			const nextChars = render({
+				items: [...items, plannedItem],
+				understandingSources: nextSources
+			}).length;
+			if (nextChars > maxChars) {
 				rejected.push({
 					recordId: item.id,
 					reason: "budget"
@@ -233,24 +434,17 @@ var UserContextPlanner = class {
 					decision: "budget_exceeded",
 					reason: "Context budget reached",
 					content: item.statement,
-					sourceLabel: sourceLabel(item),
+					sourceLabel: source.label,
+					origin: source.origin,
 					score,
 					injectedChars: 0
 				});
 				continue;
 			}
-			usedChars += item.statement.length;
-			items.push({
-				recordId: item.id,
-				objectType: "understanding",
-				versionId: item.versionId,
-				content: item.statement,
-				score,
-				section: sectionFor(item),
-				citation: `user-context://${item.id}`,
-				origin: originFor(item),
-				stability: item.confidence
-			});
+			const addedChars = nextChars - usedChars;
+			usedChars = nextChars;
+			understandingSources.set(item.id, source.label);
+			items.push(plannedItem);
 			traceItems.push({
 				objectType: "understanding",
 				objectId: item.id,
@@ -258,18 +452,14 @@ var UserContextPlanner = class {
 				decision: "selected",
 				reason: "Relevant to this request",
 				content: item.statement,
-				sourceLabel: sourceLabel(item),
+				sourceLabel: source.label,
+				origin: source.origin,
 				rank: items.length,
 				score,
-				injectedChars: item.statement.length
+				injectedChars: addedChars
 			});
 		}
-		const block = [
-			profileLines.length ? `<user-profile>\n${profileLines.join("\n")}\n</user-profile>` : "",
-			activeFocusLines.length ? `<active-focuses>\n${activeFocusLines.join("\n")}\n</active-focuses>` : "",
-			selectedRules.length ? `<collaboration-contract>\n${selectedRules.map((rule) => `- ${rule.statement}`).join("\n")}\n</collaboration-contract>` : "",
-			items.length ? buildUserContextBlock(items.map((item) => `- ${item.content}\n  Evidence: ${traceItems.find((trace) => trace.objectId === item.recordId)?.sourceLabel}`).join("\n")) : ""
-		].filter(Boolean).join("\n\n");
+		const block = render();
 		recordContextRun({
 			turnId: params.turnId,
 			sessionKey: params.sessionKey,

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/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/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 {};