@xopcai/xopc 0.0.218 → 0.0.220

package/dist/src/knowledge/connected-knowledge-pipeline.d.ts

@@ -11,11 +11,17 @@ export type KnowledgeSynthesisBatchResult = {
     failed: number;
     recordIds: string[];
 };
+export type ConnectedKnowledgePruneResult = {
+    rawDeleted: number;
+    derivedDeleted: number;
+};
 export declare class ConnectedKnowledgePipeline {
     private readonly options;
     private readonly workerId;
     private readonly batchSize;
     constructor(options: ConnectedKnowledgePipelineOptions);
     processPending(sourceInstanceId?: string): Promise<KnowledgeSynthesisBatchResult>;
+    /** Remove bounded raw items and every content-bearing memory derived only from them. */
+    pruneBoundedRetention(sourceInstanceId: string, olderThanMs: number): ConnectedKnowledgePruneResult;
     private rebuildDailySummary;
 }

package/dist/src/knowledge/connected-knowledge-pipeline.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { attachMemoryEvidence, claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, deleteMemoryEvidenceForRecord, listKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
-import { getMemoryRecord, upsertMemoryRecord } from "../storage/sqlite/memory-records-repository.js";
+import { attachMemoryEvidence, claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, deleteMemoryEvidenceForRecord, listKnowledgeSourceItems, pruneBoundedKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
+import { deleteMemoryRecord, getMemoryRecord, upsertMemoryRecord } from "../storage/sqlite/memory-records-repository.js";
 import "../storage/sqlite/index.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/knowledge/connected-knowledge-pipeline.ts
@@ -180,13 +180,43 @@ var ConnectedKnowledgePipeline = class {
 		}
 		return result;
 	}
-	rebuildDailySummary(sourceInstanceId, day) {
+	/** Remove bounded raw items and every content-bearing memory derived only from them. */
+	pruneBoundedRetention(sourceInstanceId, olderThanMs) {
+		const expired = [];
+		for (let offset = 0;; offset += 500) {
+			const page = listKnowledgeSourceItems({
+				sourceInstanceId,
+				retentionClass: "bounded",
+				retentionBeforeMs: olderThanMs,
+				includeDeleted: true,
+				limit: 500,
+				offset
+			});
+			expired.push(...page);
+			if (page.length < 500) break;
+		}
+		if (!expired.length) return {
+			rawDeleted: 0,
+			derivedDeleted: 0
+		};
+		const affectedDays = new Set(expired.map(dayFor));
+		let derivedDeleted = 0;
+		for (const item of expired) if (deleteMemoryRecord(knowledgeRecordId(item.id))) derivedDeleted += 1;
+		const rawDeleted = pruneBoundedKnowledgeSourceItems(sourceInstanceId, olderThanMs);
+		for (const day of affectedDays) if (this.rebuildDailySummary(sourceInstanceId, day, true)) derivedDeleted += 1;
+		return {
+			rawDeleted,
+			derivedDeleted
+		};
+	}
+	rebuildDailySummary(sourceInstanceId, day, deleteWhenEmpty = false) {
 		const items = listKnowledgeSourceItems({
 			sourceInstanceId,
 			limit: 500
 		}).filter((item) => dayFor(item) === day && item.synthesisStatus === "completed").slice(0, MAX_SUMMARY_ITEMS);
 		if (items.length === 0) {
 			const existing = getMemoryRecord(summaryRecordId(sourceInstanceId, day));
+			if (existing && deleteWhenEmpty) return deleteMemoryRecord(existing.id);
 			if (existing) upsertMemoryRecord({
 				id: existing.id,
 				providerId: "connected-knowledge",
@@ -210,7 +240,7 @@ var ConnectedKnowledgePipeline = class {
 				expiresAt: existing.expiresAt,
 				canonicalKey: existing.canonicalKey
 			});
-			return;
+			return false;
 		}
 		const sourceProvider = providerId(items[0]);
 		const lines = [`# ${sourceProvider} updates for ${day}`, ""];
@@ -263,6 +293,7 @@ var ConnectedKnowledgePipeline = class {
 			confidence: .72,
 			observedAt: item.occurredAt ?? item.sourceUpdatedAt
 		});
+		return false;
 	}
 };
 //#endregion

package/dist/src/knowledge/connected-understanding-pipeline.d.ts

@@ -13,5 +13,5 @@ export declare function renderConnectedObservation(observation: ClaimObservation
 export declare class ConnectedUnderstandingPipeline {
     private readonly memoryManager;
     constructor(memoryManager: MemoryManager);
-    process(agentId: string): Promise<UnderstandingReviewResult>;
+    process(agentId: string, extractionRunId: string): Promise<UnderstandingReviewResult>;
 }

package/dist/src/knowledge/connected-understanding-pipeline.js

@@ -226,7 +226,7 @@ var ConnectedUnderstandingPipeline = class {
 	constructor(memoryManager) {
 		this.memoryManager = memoryManager;
 	}
-	async process(agentId) {
+	async process(agentId, extractionRunId) {
 		const observations = deriveConnectedClaimObservations(listKnowledgeSourceItems({
 			agentId,
 			includeDeleted: false,
@@ -253,12 +253,14 @@ var ConnectedUnderstandingPipeline = class {
 					provider: "connected-sources",
 					...sourceInstanceIds.length === 1 ? { sourceInstanceId: sourceInstanceIds[0] } : {}
 				},
-				reviewSource: "background"
+				reviewSource: "background",
+				extractionRunId
 			});
 			totals.created += result.created;
 			totals.deduplicated += result.deduplicated;
 			totals.rejected += result.rejected;
 			totals.createdRecords.push(...result.createdRecords);
+			totals.writeOutputs = [...totals.writeOutputs ?? [], ...result.writeOutputs ?? []];
 		}
 		return totals;
 	}

package/dist/src/providers/auth-runtime/resolve-auth.js

@@ -1,5 +1,5 @@
-import { getApiKeyFromEnv, init_env_keys } from "../env-keys.js";
 import { init_sync_provider_auth, resolveProviderApiKeyForAgentSync } from "../../auth/sync-provider-auth.js";
+import { getApiKeyFromEnv, init_env_keys } from "../env-keys.js";
 import { getDefaultAuthProfileStore } from "./auth-profile-store.js";
 //#region src/providers/auth-runtime/resolve-auth.ts
 init_env_keys();

package/dist/src/providers/index.js

@@ -1,11 +1,11 @@
 import { __esmMin, __exportAll } from "../../_virtual/_rolldown/runtime.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
+import { getOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
+import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
 import { PROVIDER_ENV_MAP, getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { init_model_ref, splitProviderModelRef } from "./model-ref.js";
 import { ModelRegistry, getModelRegistry, init_model_registry, prewarmModelRegistry, resetModelRegistry } from "./model-registry.js";
-import { getOAuthProviderIds, init_registry } from "../auth/oauth/registry.js";
 import { CredentialResolver, hasCredentials, init_credentials } from "../auth/credentials.js";
-import { hasProviderAuthOnDiskSync, init_sync_provider_auth } from "../auth/sync-provider-auth.js";
 import { EXTENSION_PROVIDER_BASE_URL, init_constants } from "./constants.js";
 import { applyOfficialModelMetadataCorrections, getSupplementalModels, init_model_supplements } from "./model-supplements.js";
 import { getProviderRegistry, init_plugin_registry } from "./plugin-registry.js";

package/dist/src/providers/model-registry.js

@@ -1,8 +1,8 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
 import { resolveModelsJsonPath } from "../config/paths.js";
+import { init_resolve_config_value, resolveConfigValue, resolveHeaders } from "../config/resolve-config-value.js";
 import { getDefaultModelValues, init_models_json, validateModelsConfig } from "../config/models-json.js";
 import { getApiKeyFromEnv, init_env_keys } from "./env-keys.js";
 import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";

package/dist/src/providers/register-runtime-providers.js

@@ -1,6 +1,6 @@
 import { __esmMin } from "../../_virtual/_rolldown/runtime.js";
-import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { getOAuthProviderDefinition, init_registry } from "../auth/oauth/registry.js";
+import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
 import { XOPC_CLOUD_PROVIDER_ID, init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 //#region src/providers/register-runtime-providers.ts
 function registerRuntimeProvider(modelRuntime, source) {

package/dist/src/retrieval/queryProfile.d.ts

@@ -6,11 +6,14 @@ export interface RetrievalScope {
 }
 export interface RetrievalQueryProfile {
     normalized: string;
+    expanded: string;
     terms: string[];
     cjkBigrams: string[];
     identifiers: string[];
     intentKinds: string[];
     timeHints: RetrievalTimeHint[];
+    selfReview: boolean;
     scope: RetrievalScope;
 }
+export declare function isSelfReviewQuery(query: string): boolean;
 export declare function buildRetrievalQueryProfile(query: string, scope?: RetrievalScope): RetrievalQueryProfile;

package/dist/src/retrieval/queryProfile.js

@@ -1,5 +1,14 @@
 import { extractCjkBigrams, extractLexicalTerms, extractRetrievalIdentifiers, normalizeRetrievalText } from "./textFeatures.js";
 //#region src/retrieval/queryProfile.ts
+const SELF_REVIEW_PATTERNS = [
+	/(?:你|xopc).{0,10}(?:了解|知道|认识|记得).{0,8}(?:我|用户)/i,
+	/介绍.{0,8}(?:你.{0,6})?(?:了解|知道|认识|记得).{0,4}的?我/i,
+	/\bwhat\s+(?:do\s+)?you\s+(?:know|remember)\s+about\s+me\b/i,
+	/\b(?:describe|introduce)\s+me\s+(?:from|based on)\s+(?:what|everything)\s+you\s+(?:know|remember)\b/i
+];
+function isSelfReviewQuery(query) {
+	return SELF_REVIEW_PATTERNS.some((pattern) => pattern.test(query.normalize("NFKC")));
+}
 const INTENT_RULES = [
 	{
 		kinds: ["boundary"],
@@ -48,19 +57,28 @@ const TIME_RULES = [
 		pattern: /\b(?:future|next|later|upcoming)\b|未来|下次|之后|即将/i
 	}
 ];
+const TIME_EXPANSIONS = {
+	current: "now current active today 现在 当前 今天",
+	recent: "recent recently latest 近期 最近 最新",
+	historical: "previous before history past 之前 以前 历史 上次",
+	future: "future next later upcoming 未来 下次 之后 即将"
+};
 function buildRetrievalQueryProfile(query, scope = {}) {
 	const normalized = normalizeRetrievalText(query);
 	const intentKinds = INTENT_RULES.filter((rule) => rule.pattern.test(normalized)).flatMap((rule) => rule.kinds);
 	const timeHints = TIME_RULES.filter((rule) => rule.pattern.test(normalized)).map((rule) => rule.hint);
+	const uniqueTimeHints = [...new Set(timeHints)];
 	return {
 		normalized,
+		expanded: [normalized, ...uniqueTimeHints.map((hint) => TIME_EXPANSIONS[hint])].join(" ").trim(),
 		terms: extractLexicalTerms(normalized),
 		cjkBigrams: extractCjkBigrams(normalized),
 		identifiers: extractRetrievalIdentifiers(normalized),
 		intentKinds: [...new Set(intentKinds)],
-		timeHints: [...new Set(timeHints)],
+		timeHints: uniqueTimeHints,
+		selfReview: isSelfReviewQuery(normalized),
 		scope: { ...scope }
 	};
 }
 //#endregion
-export { buildRetrievalQueryProfile };
+export { buildRetrievalQueryProfile, isSelfReviewQuery };

package/dist/src/session/client-history.d.ts

@@ -11,6 +11,17 @@ export interface ClientHistoryMessage {
     /** Persisted inbound attachment metadata used by chat clients to reload media. */
     media?: Message['media'];
     timestamp?: number;
+    /** Whitelisted display metadata; never includes source snapshot text. */
+    metadata?: {
+        sourceContexts: Array<{
+            kind: 'note';
+            sourceId: string;
+            version: string;
+            title: string;
+            tokenEstimate?: number;
+            truncated?: boolean;
+        }>;
+    };
     kind?: 'message' | 'compaction' | 'context' | 'bash' | 'custom' | 'branch';
     tokensBefore?: number;
     tokensAfter?: number;

package/dist/src/session/client-history.js

@@ -1,5 +1,25 @@
+import { stripRuntimeContextFromUserMessage } from "./user-message-display.js";
 import { buildTranscriptOutline } from "./transcript-outline.js";
 //#region src/session/client-history.ts
+function sourceContextDisplayMetadata(metadata) {
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return void 0;
+	const rows = metadata.sourceContexts;
+	if (!Array.isArray(rows)) return void 0;
+	const sourceContexts = rows.flatMap((value) => {
+		if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+		const row = value;
+		if (row.kind !== "note" || typeof row.sourceId !== "string" || typeof row.version !== "string" || typeof row.title !== "string") return [];
+		return [{
+			kind: "note",
+			sourceId: row.sourceId,
+			version: row.version,
+			title: row.title,
+			...typeof row.tokenEstimate === "number" ? { tokenEstimate: row.tokenEstimate } : {},
+			...row.truncated === true ? { truncated: true } : {}
+		}];
+	});
+	return sourceContexts.length ? { sourceContexts } : void 0;
+}
 function flattenMessageContent(content) {
 	if (typeof content === "string") return content;
 	if (!Array.isArray(content)) return "";
@@ -111,8 +131,9 @@ function messagesToClientHistory(messages, opts) {
 			out.push({
 				role: m.role,
 				...typeof m.turnId === "string" ? { turnId: m.turnId } : {},
-				content: text,
+				content: m.role === "user" ? stripRuntimeContextFromUserMessage(text) : text,
 				...m.media?.length ? { media: m.media } : {},
+				...sourceContextDisplayMetadata(m.metadata) ? { metadata: sourceContextDisplayMetadata(m.metadata) } : {},
 				timestamp: parseTimestamp(m.timestamp)
 			});
 			continue;
@@ -413,8 +434,9 @@ function transcriptRowsToClientHistory(rows, opts) {
 				...messageRow.turnId ? { turnId: messageRow.turnId } : {},
 				role: messageRow.role,
 				kind: "message",
-				content: flattenMessageContent(messageRow.content ?? ""),
+				content: messageRow.role === "user" ? stripRuntimeContextFromUserMessage(flattenMessageContent(messageRow.content ?? "")) : flattenMessageContent(messageRow.content ?? ""),
 				...messageRow.media?.length ? { media: messageRow.media } : {},
+				...sourceContextDisplayMetadata(messageRow.metadata) ? { metadata: sourceContextDisplayMetadata(messageRow.metadata) } : {},
 				...displayIndex !== void 0 ? { displayIndex } : {},
 				timestamp: parseTimestampValue(messageRow.timestamp)
 			});

package/dist/src/session/config-types.d.ts

@@ -13,6 +13,6 @@ export interface SessionAgentConfig {
     providerOverride?: string;
     workingDirectoryOverride?: string;
     responseLanguage?: ResponseLanguage;
-    userContextMode?: 'enabled' | 'off';
+    userContextMode?: 'enabled' | 'off' | 'temporary';
     updatedAt?: number;
 }

package/dist/src/session/session-title.js

@@ -5,8 +5,7 @@ import { init_session_key, parseSessionKey } from "../routing/session-key.js";
 import { init_providers, resolveModel } from "../providers/index.js";
 import { completeWithResolvedCredentials } from "../providers/model-call.js";
 import { readAgentMessageContent } from "../agent/memory/agent-message-access.js";
-import { stripSessionStartupContextFromUserText } from "../agent/reply/startup-context.js";
-import { stripEnvelopeTimestampPrefix } from "../channels/envelope-timestamp.js";
+import { stripRuntimeContextFromUserMessage } from "./user-message-display.js";
 //#region src/session/session-title.ts
 init_session_key();
 init_providers();
@@ -56,7 +55,7 @@ function stripSkillCommandForTitle(text) {
 	return match[2]?.trim() || match[1]?.trim() || text;
 }
 function normalizeUserTextForTitle(raw) {
-	return stripSkillCommandForTitle(stripExpandedSkillBlockForTitle(stripMediaClaimChecks(stripEnvelopeTimestampPrefix(stripSessionStartupContextFromUserText(raw))))).trim();
+	return stripSkillCommandForTitle(stripExpandedSkillBlockForTitle(stripMediaClaimChecks(stripRuntimeContextFromUserMessage(raw)))).trim();
 }
 /** First assistant message that has visible text (skips tool-only assistant rows). */
 function firstAssistantText(messages) {

package/dist/src/session/store.js

@@ -725,6 +725,7 @@ var SessionStore = class {
 				name: m.name
 			};
 			if (Array.isArray(m.media) && m.media.length > 0) row.media = m.media;
+			if (m.metadata && typeof m.metadata === "object") row.metadata = m.metadata;
 			const rawUsage = m.usage;
 			if (rawUsage && typeof rawUsage === "object") {
 				const inputTokens = typeof rawUsage.input === "number" ? rawUsage.input : void 0;

package/dist/src/session/transcript-outline.js

@@ -1,4 +1,5 @@
 import { isTranscriptBashExecutionEntry, isTranscriptContextEntry, isTranscriptCustomMessageEntry, isTranscriptLabelEntry, isTranscriptMetadataEntry, isTranscriptSummaryMessageEntry } from "./session-context-for-llm.js";
+import { stripRuntimeContextFromUserMessage } from "./user-message-display.js";
 //#region src/session/transcript-outline.ts
 function asRecord(value) {
 	return value && typeof value === "object" ? value : null;
@@ -170,7 +171,8 @@ function rowPreview(row) {
 	}
 	const record = asRecord(row);
 	if (record?.type === "compaction") return truncateText(stringValue(record.summary) ?? "compaction checkpoint");
-	const preview = contentPreview(record?.content);
+	const content = contentText(record?.content);
+	const preview = truncateText(record?.role === "user" ? stripRuntimeContextFromUserMessage(content) : content);
 	if (record?.role === "assistant" && !preview) {
 		if (record.stopReason === "aborted") return "(aborted)";
 		const errorMessage = stringValue(record.errorMessage);
@@ -194,7 +196,8 @@ function rowContentText(row) {
 	if (isTranscriptSummaryMessageEntry(row)) return row.summary;
 	const record = asRecord(row);
 	if (record?.type === "compaction") return stringValue(record.summary);
-	const text = contentText(record?.content).trim();
+	const rawText = contentText(record?.content);
+	const text = (record?.role === "user" ? stripRuntimeContextFromUserMessage(rawText) : rawText).trim();
 	return text ? text : void 0;
 }
 function roleForTimeline(role) {

package/dist/src/session/types.d.ts

@@ -38,6 +38,7 @@ export interface Message {
         uri: string;
         path: string;
     }>;
+    metadata?: unknown;
 }
 /** Session status enum */
 export declare enum SessionStatus {

package/dist/src/session/user-message-display.d.ts

@@ -0,0 +1,4 @@
+/** Client-facing form of a persisted model-facing user message. */
+export declare function stripRuntimeContextFromUserMessage(text: string): string;
+/** Preserve structured content while cleaning every user text block. */
+export declare function stripRuntimeContextFromUserContent(content: string | unknown[]): string | unknown[];

package/dist/src/session/user-message-display.js

@@ -0,0 +1,22 @@
+import { stripRuntimeUserMessageEnvelope } from "../../packages/gateway-contract/src/user-message-display.js";
+import { stripSessionStartupContextFromUserText } from "../agent/reply/startup-context.js";
+//#region src/session/user-message-display.ts
+/** Client-facing form of a persisted model-facing user message. */
+function stripRuntimeContextFromUserMessage(text) {
+	return stripRuntimeUserMessageEnvelope(stripSessionStartupContextFromUserText(text));
+}
+/** Preserve structured content while cleaning every user text block. */
+function stripRuntimeContextFromUserContent(content) {
+	if (typeof content === "string") return stripRuntimeContextFromUserMessage(content);
+	return content.map((block) => {
+		if (!block || typeof block !== "object") return block;
+		const row = block;
+		if (row.type !== "text" || typeof row.text !== "string") return block;
+		return {
+			...row,
+			text: stripRuntimeContextFromUserMessage(row.text)
+		};
+	});
+}
+//#endregion
+export { stripRuntimeContextFromUserContent, stripRuntimeContextFromUserMessage };

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

@@ -0,0 +1,57 @@
+export type ContextExtractionStatus = 'running' | 'completed' | 'skipped' | 'failed';
+export type ContextObjectType = 'profile' | 'rule' | 'focus' | 'understanding';
+export type ContextExtractionRun = {
+    id: string;
+    principalId: string;
+    sourceRef: string;
+    extractorId: string;
+    extractorVersion: string;
+    processingPolicy: 'local_only' | 'remote_allowed';
+    destination: 'deterministic' | 'local_model' | 'remote_model';
+    inputHash: string;
+    status: ContextExtractionStatus;
+    errorCode?: string;
+    startedAt: number;
+    completedAt?: number;
+};
+export type ContextExtractionOutput = {
+    id: string;
+    runId: string;
+    ordinal: number;
+    candidateKey: string;
+    objectType?: ContextObjectType;
+    objectId?: string;
+    versionId?: string;
+    outcome: 'created' | 'deduplicated' | 'rejected';
+    createdAt: number;
+};
+export declare function claimContextExtractionRun(input: {
+    sourceRef: string;
+    extractorId: string;
+    extractorVersion: string;
+    processingPolicy: ContextExtractionRun['processingPolicy'];
+    destination: ContextExtractionRun['destination'];
+    inputHash: string;
+    principalId?: string;
+    nowMs?: number;
+}): {
+    run: ContextExtractionRun;
+    shouldExecute: boolean;
+};
+export declare function finishContextExtractionRun(input: {
+    runId: string;
+    status: Exclude<ContextExtractionStatus, 'running'>;
+    errorCode?: string;
+    outputs?: Array<Omit<ContextExtractionOutput, 'id' | 'runId' | 'ordinal' | 'createdAt'>>;
+    nowMs?: number;
+}): ContextExtractionRun | null;
+export declare function listContextExtractionRuns(filter?: {
+    sourceRef?: string;
+    extractorId?: string;
+    extractorVersion?: string;
+    status?: ContextExtractionStatus;
+    limit?: number;
+}): ContextExtractionRun[];
+export declare function getContextExtractionRun(id: string): ContextExtractionRun | null;
+export declare function listContextExtractionOutputs(runId: string): ContextExtractionOutput[];
+export declare function hasIndependentExtractionOutput(runIds: string[], objectType: ContextObjectType, objectId: string): boolean;

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

@@ -0,0 +1,119 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import "../../user-context/domain.js";
+import { randomUUID } from "node:crypto";
+//#region src/storage/sqlite/context-extraction-repository.ts
+function runFromRow(row) {
+	return {
+		id: row.extraction_run_id,
+		principalId: row.principal_id,
+		sourceRef: row.source_ref,
+		extractorId: row.extractor_id,
+		extractorVersion: row.extractor_version,
+		processingPolicy: row.processing_policy,
+		destination: row.destination,
+		inputHash: row.input_hash,
+		status: row.status,
+		...row.error_code ? { errorCode: row.error_code } : {},
+		startedAt: row.started_at,
+		...row.completed_at == null ? {} : { completedAt: row.completed_at }
+	};
+}
+function outputFromRow(row) {
+	return {
+		id: row.output_id,
+		runId: row.extraction_run_id,
+		ordinal: row.ordinal,
+		candidateKey: row.candidate_key,
+		...row.object_type ? { objectType: row.object_type } : {},
+		...row.object_id ? { objectId: row.object_id } : {},
+		...row.version_id ? { versionId: row.version_id } : {},
+		outcome: row.outcome,
+		createdAt: row.created_at
+	};
+}
+function claimContextExtractionRun(input) {
+	const principalId = input.principalId ?? "local-owner";
+	const now = input.nowMs ?? Date.now();
+	return runSqliteWriteTransaction((db) => {
+		const existing = db.prepare(`SELECT * FROM context_extraction_runs
+      WHERE principal_id = ? AND source_ref = ? AND extractor_id = ? AND extractor_version = ?`).get(principalId, input.sourceRef, input.extractorId, input.extractorVersion);
+		if (existing) {
+			if (existing.input_hash !== input.inputHash) throw new Error("Extraction source changed without a new source reference");
+			if (existing.status !== "failed") return {
+				run: runFromRow(existing),
+				shouldExecute: false
+			};
+			db.prepare(`UPDATE context_extraction_runs
+        SET status = 'running', error_code = NULL, started_at = ?, completed_at = NULL
+        WHERE extraction_run_id = ?`).run(now, existing.extraction_run_id);
+			return {
+				run: runFromRow(db.prepare("SELECT * FROM context_extraction_runs WHERE extraction_run_id = ?").get(existing.extraction_run_id)),
+				shouldExecute: true
+			};
+		}
+		const id = randomUUID();
+		db.prepare(`INSERT INTO context_extraction_runs (
+      extraction_run_id, principal_id, source_ref, extractor_id, extractor_version,
+      processing_policy, destination, input_hash, status, started_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', ?)`).run(id, principalId, input.sourceRef, input.extractorId, input.extractorVersion, input.processingPolicy, input.destination, input.inputHash, now);
+		return {
+			run: runFromRow(db.prepare("SELECT * FROM context_extraction_runs WHERE extraction_run_id = ?").get(id)),
+			shouldExecute: true
+		};
+	});
+}
+function finishContextExtractionRun(input) {
+	const now = input.nowMs ?? Date.now();
+	return runSqliteWriteTransaction((db) => {
+		if (!db.prepare(`UPDATE context_extraction_runs SET status = ?, error_code = ?, completed_at = ?
+      WHERE extraction_run_id = ?`).run(input.status, input.errorCode ?? null, now, input.runId).changes) return null;
+		db.prepare("DELETE FROM context_extraction_outputs WHERE extraction_run_id = ?").run(input.runId);
+		const insert = db.prepare(`INSERT INTO context_extraction_outputs (
+      output_id, extraction_run_id, ordinal, candidate_key, object_type, object_id,
+      version_id, outcome, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+		for (const [ordinal, output] of (input.outputs ?? []).entries()) insert.run(randomUUID(), input.runId, ordinal, output.candidateKey, output.objectType ?? null, output.objectId ?? null, output.versionId ?? null, output.outcome, now);
+		return runFromRow(db.prepare("SELECT * FROM context_extraction_runs WHERE extraction_run_id = ?").get(input.runId));
+	});
+}
+function listContextExtractionRuns(filter = {}) {
+	const clauses = [];
+	const values = [];
+	if (filter.sourceRef) {
+		clauses.push("source_ref = ?");
+		values.push(filter.sourceRef);
+	}
+	if (filter.extractorId) {
+		clauses.push("extractor_id = ?");
+		values.push(filter.extractorId);
+	}
+	if (filter.extractorVersion) {
+		clauses.push("extractor_version = ?");
+		values.push(filter.extractorVersion);
+	}
+	if (filter.status) {
+		clauses.push("status = ?");
+		values.push(filter.status);
+	}
+	values.push(Math.max(1, Math.min(500, filter.limit ?? 100)));
+	return getSqliteDatabase().prepare(`SELECT * FROM context_extraction_runs
+    ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""} ORDER BY started_at DESC LIMIT ?`).all(...values).map(runFromRow);
+}
+function getContextExtractionRun(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM context_extraction_runs WHERE extraction_run_id = ?").get(id);
+	return row ? runFromRow(row) : null;
+}
+function listContextExtractionOutputs(runId) {
+	return getSqliteDatabase().prepare(`SELECT * FROM context_extraction_outputs
+    WHERE extraction_run_id = ? ORDER BY ordinal`).all(runId).map(outputFromRow);
+}
+function hasIndependentExtractionOutput(runIds, objectType, objectId) {
+	if (!runIds.length) return false;
+	const placeholders = runIds.map(() => "?").join(", ");
+	return Boolean(getSqliteDatabase().prepare(`SELECT 1 FROM context_extraction_outputs o
+    JOIN context_extraction_runs r ON r.extraction_run_id = o.extraction_run_id
+    WHERE o.extraction_run_id NOT IN (${placeholders}) AND o.object_type = ? AND o.object_id = ?
+      AND r.status = 'completed' LIMIT 1`).get(...runIds, objectType, objectId));
+}
+//#endregion
+export { claimContextExtractionRun, finishContextExtractionRun, getContextExtractionRun, hasIndependentExtractionOutput, listContextExtractionOutputs, listContextExtractionRuns };

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

@@ -0,0 +1,50 @@
+import type { ContextObjectType } from './context-extraction-repository.js';
+export type ContextObjectRelation = {
+    id: string;
+    subjectType: ContextObjectType;
+    subjectId: string;
+    subjectVersionId?: string;
+    predicate: 'supersedes' | 'supports' | 'contradicts' | 'related_to';
+    objectType: ContextObjectType;
+    objectId: string;
+    objectVersionId?: string;
+    factual: boolean;
+    extractionRunId?: string;
+    createdAt: number;
+};
+export type ContextTemporalAssertion = {
+    id: string;
+    objectType: 'focus' | 'understanding';
+    objectId: string;
+    objectVersionId?: string;
+    assertionType: 'current_state' | 'routine' | 'relationship' | 'project_status';
+    value: Record<string, unknown>;
+    confidence: number;
+    validFrom?: number;
+    validTo?: number;
+    status: 'candidate' | 'active' | 'closed' | 'rejected';
+    extractionRunId?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+export declare function linkContextObjects(input: Omit<ContextObjectRelation, 'id' | 'createdAt'> & {
+    nowMs?: number;
+}): ContextObjectRelation;
+export declare function listContextObjectRelations(input?: {
+    objectType?: ContextObjectType;
+    objectId?: string;
+    extractionRunId?: string;
+}): ContextObjectRelation[];
+export declare function createTemporalAssertion(input: Omit<ContextTemporalAssertion, 'id' | 'createdAt' | 'updatedAt'> & {
+    nowMs?: number;
+}): ContextTemporalAssertion;
+export declare function closeTemporalAssertions(input: {
+    objectType: ContextTemporalAssertion['objectType'];
+    objectId: string;
+    validTo?: number;
+}): number;
+export declare function listTemporalAssertions(input?: {
+    objectType?: ContextTemporalAssertion['objectType'];
+    objectId?: string;
+    status?: ContextTemporalAssertion['status'];
+}): ContextTemporalAssertion[];