@xopcai/xopc 0.0.218 → 0.0.219

package/dist/src/storage/sqlite/migrations/126_focus_context_governance.sql

@@ -0,0 +1,72 @@
+UPDATE understanding_source_grants
+SET processing_policy = 'local_only'
+WHERE adapter_id = 'local-work-folders'
+   OR source_key LIKE 'understanding-source:%';
+
+CREATE TABLE user_focuses_v126 (
+  focus_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL DEFAULT 'local-owner',
+  canonical_key TEXT NOT NULL UNIQUE,
+  title TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  horizon TEXT NOT NULL CHECK (horizon IN ('current', 'ongoing', 'long_term')),
+  status TEXT NOT NULL CHECK (status IN ('candidate', 'active', 'paused', 'completed', 'rejected')),
+  confidence REAL NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+  scope_type TEXT NOT NULL CHECK (scope_type IN ('global', 'workspace', 'project', 'session')),
+  scope_id TEXT,
+  explicitness TEXT NOT NULL CHECK (explicitness IN ('explicit', 'observed', 'inferred')),
+  sensitivity TEXT NOT NULL CHECK (sensitivity IN ('normal', 'personal', 'secret', 'regulated')),
+  disclosure_policy TEXT NOT NULL CHECK (disclosure_policy IN ('silent', 'referenceable', 'ask_before_reference')),
+  valid_from INTEGER,
+  valid_to INTEGER,
+  review_at INTEGER,
+  evidence_refs_json TEXT NOT NULL DEFAULT '[]',
+  source_run_id TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (source_run_id) REFERENCES understanding_source_runs(run_id) ON DELETE SET NULL,
+  CHECK ((scope_type = 'global' AND scope_id IS NULL) OR (scope_type <> 'global' AND scope_id IS NOT NULL))
+);
+
+INSERT INTO user_focuses_v126 (
+  focus_id, principal_id, canonical_key, title, summary, horizon, status, confidence,
+  scope_type, scope_id, explicitness, sensitivity, disclosure_policy,
+  evidence_refs_json, source_run_id, created_at, updated_at
+)
+SELECT
+  focus_id, 'local-owner', canonical_key, title, summary, horizon, status, confidence,
+  CASE WHEN project_id IS NULL THEN 'global' ELSE 'project' END,
+  project_id,
+  CASE WHEN status = 'candidate' THEN 'inferred' ELSE 'explicit' END,
+  'normal', 'referenceable', evidence_refs_json, source_run_id, created_at, updated_at
+FROM user_focuses;
+
+DROP TABLE user_focuses;
+ALTER TABLE user_focuses_v126 RENAME TO user_focuses;
+
+CREATE INDEX idx_user_focuses_status
+  ON user_focuses(principal_id, status, horizon, updated_at DESC);
+CREATE INDEX idx_user_focuses_scope
+  ON user_focuses(principal_id, scope_type, scope_id, status);
+
+CREATE TABLE context_run_items_v126 (
+  context_run_id TEXT NOT NULL REFERENCES context_runs(context_run_id) ON DELETE CASCADE,
+  object_type TEXT NOT NULL CHECK (object_type IN ('profile', 'rule', 'focus', 'understanding')),
+  object_id TEXT NOT NULL,
+  version_id TEXT,
+  decision TEXT NOT NULL CHECK (decision IN (
+    'selected', 'irrelevant', 'expired', 'scope_mismatch', 'sensitive',
+    'needs_consent', 'budget_exceeded', 'conflicted', 'disabled'
+  )),
+  reason TEXT NOT NULL,
+  content_snapshot TEXT NOT NULL,
+  source_label TEXT NOT NULL,
+  rank INTEGER,
+  score REAL,
+  injected_chars INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (context_run_id, object_type, object_id)
+);
+
+INSERT INTO context_run_items_v126 SELECT * FROM context_run_items;
+DROP TABLE context_run_items;
+ALTER TABLE context_run_items_v126 RENAME TO context_run_items;

package/dist/src/storage/sqlite/migrations/127_context_object_origin.sql

@@ -0,0 +1,36 @@
+ALTER TABLE context_run_items ADD COLUMN origin TEXT NOT NULL DEFAULT 'inferred'
+  CHECK (origin IN ('told_by_user', 'observed', 'inferred', 'connected_source'));
+
+UPDATE context_run_items SET origin = 'told_by_user' WHERE object_type IN ('profile', 'rule');
+UPDATE context_run_items SET origin = 'told_by_user'
+WHERE object_type = 'understanding' AND source_label = 'You told xopc';
+UPDATE context_run_items SET origin = 'observed'
+WHERE object_type = 'understanding' AND source_label = 'Observed across prior work';
+
+CREATE TABLE session_config_next (
+  session_key TEXT PRIMARY KEY,
+  thinking_level TEXT,
+  reasoning_level TEXT,
+  verbose_level TEXT,
+  elevated_mode TEXT,
+  model_override TEXT,
+  provider_override TEXT,
+  working_directory_override TEXT,
+  response_language TEXT,
+  user_context_mode TEXT CHECK (user_context_mode IN ('enabled', 'off', 'temporary')),
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (session_key) REFERENCES sessions(session_key) ON DELETE CASCADE
+);
+
+INSERT INTO session_config_next (
+  session_key, thinking_level, reasoning_level, verbose_level, elevated_mode,
+  model_override, provider_override, working_directory_override, response_language,
+  user_context_mode, updated_at
+)
+SELECT session_key, thinking_level, reasoning_level, verbose_level, elevated_mode,
+  model_override, provider_override, working_directory_override, response_language,
+  user_context_mode, updated_at
+FROM session_config;
+
+DROP TABLE session_config;
+ALTER TABLE session_config_next RENAME TO session_config;

package/dist/src/storage/sqlite/migrations/128_context_extraction.sql

@@ -0,0 +1,73 @@
+CREATE TABLE context_extraction_runs (
+  extraction_run_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  source_ref TEXT NOT NULL,
+  extractor_id TEXT NOT NULL,
+  extractor_version TEXT NOT NULL,
+  processing_policy TEXT NOT NULL CHECK (processing_policy IN ('local_only', 'remote_allowed')),
+  destination TEXT NOT NULL CHECK (destination IN ('deterministic', 'local_model', 'remote_model')),
+  input_hash TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('running', 'completed', 'skipped', 'failed')),
+  error_code TEXT,
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER,
+  UNIQUE (principal_id, source_ref, extractor_id, extractor_version)
+);
+
+CREATE INDEX idx_context_extraction_runs_lookup
+  ON context_extraction_runs(extractor_id, status, started_at DESC);
+
+CREATE TABLE context_extraction_outputs (
+  output_id TEXT PRIMARY KEY,
+  extraction_run_id TEXT NOT NULL REFERENCES context_extraction_runs(extraction_run_id) ON DELETE CASCADE,
+  ordinal INTEGER NOT NULL,
+  candidate_key TEXT NOT NULL,
+  object_type TEXT CHECK (object_type IN ('profile', 'rule', 'focus', 'understanding')),
+  object_id TEXT,
+  version_id TEXT,
+  outcome TEXT NOT NULL CHECK (outcome IN ('created', 'deduplicated', 'rejected')),
+  created_at INTEGER NOT NULL,
+  UNIQUE (extraction_run_id, ordinal)
+);
+
+CREATE INDEX idx_context_extraction_outputs_object
+  ON context_extraction_outputs(object_type, object_id);
+
+CREATE TABLE context_object_relations (
+  relation_id TEXT PRIMARY KEY,
+  subject_type TEXT NOT NULL CHECK (subject_type IN ('profile', 'rule', 'focus', 'understanding')),
+  subject_id TEXT NOT NULL,
+  subject_version_id TEXT,
+  predicate TEXT NOT NULL CHECK (predicate IN ('supersedes', 'supports', 'contradicts', 'related_to')),
+  object_type TEXT NOT NULL CHECK (object_type IN ('profile', 'rule', 'focus', 'understanding')),
+  object_id TEXT NOT NULL,
+  object_version_id TEXT,
+  factual INTEGER NOT NULL DEFAULT 1 CHECK (factual IN (0, 1)),
+  extraction_run_id TEXT REFERENCES context_extraction_runs(extraction_run_id) ON DELETE SET NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX idx_context_object_relations_unique
+  ON context_object_relations(
+    subject_type, subject_id, COALESCE(subject_version_id, ''), predicate,
+    object_type, object_id, COALESCE(object_version_id, '')
+  );
+
+CREATE TABLE context_temporal_assertions (
+  assertion_id TEXT PRIMARY KEY,
+  object_type TEXT NOT NULL CHECK (object_type IN ('focus', 'understanding')),
+  object_id TEXT NOT NULL,
+  object_version_id TEXT,
+  assertion_type TEXT NOT NULL CHECK (assertion_type IN ('current_state', 'routine', 'relationship', 'project_status')),
+  value_json TEXT NOT NULL,
+  confidence REAL NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+  valid_from INTEGER,
+  valid_to INTEGER,
+  status TEXT NOT NULL CHECK (status IN ('candidate', 'active', 'closed', 'rejected')),
+  extraction_run_id TEXT REFERENCES context_extraction_runs(extraction_run_id) ON DELETE SET NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_context_temporal_assertions_active
+  ON context_temporal_assertions(object_type, object_id, assertion_type, status);

package/dist/src/storage/sqlite/migrations/129_focus_versions.sql

@@ -0,0 +1,51 @@
+ALTER TABLE user_focuses ADD COLUMN current_version_id TEXT;
+
+CREATE TABLE user_focus_versions (
+  version_id TEXT PRIMARY KEY,
+  focus_id TEXT NOT NULL REFERENCES user_focuses(focus_id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  snapshot_json TEXT NOT NULL,
+  created_by TEXT NOT NULL CHECK (created_by IN ('user', 'runtime', 'connector')),
+  change_reason TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+INSERT INTO user_focus_versions (
+  version_id, focus_id, title, summary, snapshot_json, created_by, change_reason, created_at
+)
+SELECT
+  lower(hex(randomblob(16))), focus_id, title, summary,
+  json_object(
+    'horizon', horizon, 'status', status, 'confidence', confidence,
+    'scopeType', scope_type, 'scopeId', scope_id, 'explicitness', explicitness,
+    'sensitivity', sensitivity, 'disclosurePolicy', disclosure_policy,
+    'validFrom', valid_from, 'validTo', valid_to, 'reviewAt', review_at,
+    'evidenceRefs', json(evidence_refs_json)
+  ),
+  CASE WHEN explicitness = 'explicit' THEN 'user' ELSE 'runtime' END,
+  'Migrated existing focus', created_at
+FROM user_focuses;
+
+UPDATE user_focuses
+SET current_version_id = (
+  SELECT version_id FROM user_focus_versions v WHERE v.focus_id = user_focuses.focus_id LIMIT 1
+);
+
+CREATE INDEX idx_user_focus_versions_focus
+  ON user_focus_versions(focus_id, created_at DESC);
+
+CREATE TABLE user_focus_evidence_links (
+  version_id TEXT NOT NULL REFERENCES user_focus_versions(version_id) ON DELETE CASCADE,
+  evidence_id TEXT NOT NULL REFERENCES context_evidence(evidence_id) ON DELETE CASCADE,
+  relation TEXT NOT NULL CHECK (relation IN ('supports', 'contradicts', 'supersedes')),
+  confidence REAL NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+  PRIMARY KEY (version_id, evidence_id, relation)
+);
+
+INSERT OR IGNORE INTO user_focus_evidence_links (version_id, evidence_id, relation, confidence)
+SELECT f.current_version_id, e.evidence_id, 'supports', f.confidence
+FROM user_focuses f
+JOIN json_each(f.evidence_refs_json) refs
+JOIN context_evidence e ON e.source_ref = refs.value
+WHERE f.current_version_id IS NOT NULL;

package/dist/src/storage/sqlite/migrations/130_context_evidence_provenance.sql

@@ -0,0 +1,18 @@
+ALTER TABLE context_evidence ADD COLUMN source_run_id TEXT;
+ALTER TABLE context_evidence ADD COLUMN source_item_id TEXT;
+ALTER TABLE context_evidence ADD COLUMN session_id TEXT;
+ALTER TABLE context_evidence ADD COLUMN turn_id TEXT;
+ALTER TABLE context_evidence ADD COLUMN message_id TEXT;
+ALTER TABLE context_evidence ADD COLUMN content_hash TEXT;
+ALTER TABLE context_evidence ADD COLUMN retention_policy TEXT;
+ALTER TABLE context_evidence ADD COLUMN processing_policy TEXT;
+ALTER TABLE context_evidence ADD COLUMN extractor_id TEXT;
+ALTER TABLE context_evidence ADD COLUMN extractor_version TEXT;
+ALTER TABLE context_evidence ADD COLUMN ingested_at INTEGER;
+
+UPDATE context_evidence SET ingested_at = created_at WHERE ingested_at IS NULL;
+
+CREATE INDEX idx_context_evidence_run
+  ON context_evidence(source_run_id, observed_at DESC);
+CREATE INDEX idx_context_evidence_message
+  ON context_evidence(session_id, turn_id, message_id);

package/dist/src/storage/sqlite/migrations/131_session_input_contexts.sql

@@ -0,0 +1,2 @@
+ALTER TABLE session_inputs ADD COLUMN context_refs_json TEXT;
+ALTER TABLE session_inputs ADD COLUMN context_snapshots_json TEXT;

package/dist/src/storage/sqlite/migrations/132_transcript_source_context_metadata.sql

@@ -0,0 +1,34 @@
+UPDATE transcript_entries AS entry
+SET payload_json = json_set(
+  entry.payload_json,
+  '$.metadata.sourceContexts',
+  json((
+    SELECT input.context_refs_json
+    FROM session_inputs AS input
+    JOIN transcripts AS transcript
+      ON transcript.session_id = entry.session_id
+     AND transcript.session_key = input.session_key
+    WHERE input.run_id = json_extract(entry.payload_json, '$.turnId')
+      AND input.context_refs_json IS NOT NULL
+      AND json_valid(input.context_refs_json)
+      AND json_type(input.context_refs_json) = 'array'
+    LIMIT 1
+  ))
+)
+WHERE entry.role = 'user'
+  AND json_type(entry.payload_json, '$.metadata.sourceContexts') IS NULL
+  AND (
+    json_type(entry.payload_json, '$.metadata') IS NULL
+    OR json_type(entry.payload_json, '$.metadata') = 'object'
+  )
+  AND EXISTS (
+    SELECT 1
+    FROM session_inputs AS input
+    JOIN transcripts AS transcript
+      ON transcript.session_id = entry.session_id
+     AND transcript.session_key = input.session_key
+    WHERE input.run_id = json_extract(entry.payload_json, '$.turnId')
+      AND input.context_refs_json IS NOT NULL
+      AND json_valid(input.context_refs_json)
+      AND json_type(input.context_refs_json) = 'array'
+  );

package/dist/src/storage/sqlite/migrations/runner.d.ts

@@ -3,7 +3,7 @@ import type { ApplyMigrationsOptions } from './types.js';
 /** Baseline schema version applied from schema.sql on first open. */
 export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-export declare const XOPC_DB_SCHEMA_VERSION = 125;
+export declare const XOPC_DB_SCHEMA_VERSION = 132;
 export declare function resolveMigrationsDir(override?: string): string;
 /**
  * Apply sequential SQL migrations from (currentVersion + 1) through targetVersion.

package/dist/src/storage/sqlite/migrations/runner.js

@@ -12,7 +12,7 @@ const log = createLogger("Sqlite:Migrations");
 /** Baseline schema version applied from schema.sql on first open. */
 const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 /** Latest schema version this release supports (increment when adding migrations). */
-const XOPC_DB_SCHEMA_VERSION = 125;
+const XOPC_DB_SCHEMA_VERSION = 132;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 function backupBeforeTaskCutover(db, databasePath) {
 	db.exec("PRAGMA wal_checkpoint(FULL)");
@@ -57,7 +57,7 @@ function applySingleMigration(db, migration) {
 * Each step runs in its own transaction and updates schema_meta on success.
 */
 function applyPendingMigrations(db, options = {}) {
-	const targetVersion = options.targetVersion ?? 125;
+	const targetVersion = options.targetVersion ?? 132;
 	let currentVersion = readSchemaVersion(db);
 	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
 	if (currentVersion >= targetVersion) return currentVersion;
@@ -94,7 +94,7 @@ function applyPendingMigrations(db, options = {}) {
 }
 /** Inspect schema version without mutating the database. */
 function inspectSchemaMigrationStatus(db, options = {}) {
-	const appVersion = options.targetVersion ?? 125;
+	const appVersion = options.targetVersion ?? 132;
 	const dbVersion = readSchemaVersion(db);
 	if (dbVersion > appVersion) return {
 		dbVersion,

package/dist/src/storage/sqlite/migrations/runner.ts

@@ -19,7 +19,7 @@ const log = createLogger('Sqlite:Migrations');
 export const XOPC_DB_BASELINE_SCHEMA_VERSION = 11;
 
 /** Latest schema version this release supports (increment when adding migrations). */
-export const XOPC_DB_SCHEMA_VERSION = 125;
+export const XOPC_DB_SCHEMA_VERSION = 132;
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 

package/dist/src/storage/sqlite/schema.js

@@ -32,7 +32,7 @@ function ensureXopcDatabaseSchema(db, options = {}) {
 		currentVersion = 11;
 	}
 	applyPendingMigrations(db, {
-		targetVersion: 125,
+		targetVersion: 132,
 		databasePath: options.databasePath
 	});
 }

package/dist/src/storage/sqlite/session-input-repository.d.ts

@@ -1,4 +1,5 @@
 import { type TurnOrigin } from '@xopcai/endpoint-tools-protocol';
+import type { AgentSourceContext, SourceContextRefSummary } from '../../agent/source-context/types.js';
 export type SessionInputDelivery = 'next' | 'steer';
 export type SessionInputStatus = 'queued' | 'running' | 'injecting' | 'completed' | 'cancelled' | 'failed' | 'interrupted';
 export type SessionInput = {
@@ -10,6 +11,8 @@ export type SessionInput = {
     status: SessionInputStatus;
     content: string;
     attachments?: unknown[];
+    contextRefs?: SourceContextRefSummary[];
+    contextSnapshots?: AgentSourceContext[];
     thinking?: string;
     origin: TurnOrigin;
     position: number;
@@ -29,6 +32,7 @@ export type SessionInputState = {
 };
 export declare function getSessionInputState(sessionKey: string): SessionInputState;
 export declare function findSessionInput(sessionKey: string, clientMessageId: string): SessionInput | undefined;
+export declare function getSessionInputById(sessionKey: string, id: string): SessionInput | undefined;
 export declare function insertSessionInput(input: {
     id: string;
     sessionKey: string;
@@ -38,6 +42,8 @@ export declare function insertSessionInput(input: {
     status: 'queued' | 'injecting';
     content: string;
     attachments?: unknown[];
+    contextRefs?: SourceContextRefSummary[];
+    contextSnapshots?: AgentSourceContext[];
     thinking?: string;
     origin: TurnOrigin;
     targetRunId?: string;
@@ -55,6 +61,8 @@ export declare function mutateQueuedSessionInput(input: {
     version: number;
     content?: string;
     attachments?: unknown[];
+    contextRefs?: SourceContextRefSummary[];
+    contextSnapshots?: AgentSourceContext[];
     thinking?: string;
     position?: number;
 }): boolean;

package/dist/src/storage/sqlite/session-input-repository.js

@@ -11,6 +11,8 @@ function mapInput(row) {
 		status: row.status,
 		content: row.content,
 		attachments: row.attachments_json ? JSON.parse(row.attachments_json) : void 0,
+		contextRefs: row.context_refs_json ? JSON.parse(row.context_refs_json) : void 0,
+		contextSnapshots: row.context_snapshots_json ? JSON.parse(row.context_snapshots_json) : void 0,
 		thinking: row.thinking ?? void 0,
 		position: row.position,
 		origin: turnOriginSchema.parse(JSON.parse(row.origin_json)),
@@ -23,7 +25,8 @@ function mapInput(row) {
 	};
 }
 const SELECT_INPUTS = `SELECT id, session_key, client_message_id, requested_delivery,
-  effective_delivery, status, content, attachments_json, thinking, origin_json, position,
+  effective_delivery, status, content, attachments_json, context_refs_json, context_snapshots_json,
+  thinking, origin_json, position,
   target_run_id, run_id, version, error, created_at_ms, updated_at_ms
   FROM session_inputs`;
 function ensureRuntime(db, sessionKey) {
@@ -47,13 +50,20 @@ function getSessionInputState(sessionKey) {
 		revision: runtime?.revision ?? 0,
 		activeRunId: runtime?.active_run_id ?? void 0,
 		activeInputId: runtime?.active_input_id ?? void 0,
-		inputs: rows.map(mapInput)
+		inputs: rows.map((row) => {
+			const { contextSnapshots: _contextSnapshots, ...input } = mapInput(row);
+			return input;
+		})
 	};
 }
 function findSessionInput(sessionKey, clientMessageId) {
 	const row = getSqliteDatabase().prepare(`${SELECT_INPUTS} WHERE session_key = ? AND client_message_id = ?`).get(sessionKey, clientMessageId);
 	return row ? mapInput(row) : void 0;
 }
+function getSessionInputById(sessionKey, id) {
+	const row = getSqliteDatabase().prepare(`${SELECT_INPUTS} WHERE session_key = ? AND id = ?`).get(sessionKey, id);
+	return row ? mapInput(row) : void 0;
+}
 function insertSessionInput(input) {
 	return runSqliteWriteTransaction((db) => {
 		const existing = db.prepare(`${SELECT_INPUTS} WHERE session_key = ? AND client_message_id = ?`).get(input.sessionKey, input.clientMessageId);
@@ -63,8 +73,9 @@ function insertSessionInput(input) {
       WHERE session_key = ? AND status IN ('queued','running','injecting','interrupted')`).get(input.sessionKey);
 		db.prepare(`INSERT INTO session_inputs(id, session_key, client_message_id,
       requested_delivery, effective_delivery, status, content, attachments_json,
-      thinking, origin_json, position, target_run_id, version, created_at_ms, updated_at_ms)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)`).run(input.id, input.sessionKey, input.clientMessageId, input.requestedDelivery, input.effectiveDelivery, input.status, input.content, input.attachments ? JSON.stringify(input.attachments) : null, input.thinking ?? null, JSON.stringify(input.origin), max.value + 1, input.targetRunId ?? null, now, now);
+      context_refs_json, context_snapshots_json, thinking, origin_json, position,
+      target_run_id, version, created_at_ms, updated_at_ms)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)`).run(input.id, input.sessionKey, input.clientMessageId, input.requestedDelivery, input.effectiveDelivery, input.status, input.content, input.attachments ? JSON.stringify(input.attachments) : null, input.contextRefs ? JSON.stringify(input.contextRefs) : null, input.contextSnapshots ? JSON.stringify(input.contextSnapshots) : null, input.thinking ?? null, JSON.stringify(input.origin), max.value + 1, input.targetRunId ?? null, now, now);
 		bumpRevision(db, input.sessionKey);
 		return mapInput(db.prepare(`${SELECT_INPUTS} WHERE id = ?`).get(input.id));
 	});
@@ -119,8 +130,9 @@ function mutateQueuedSessionInput(input) {
 			ordered.splice(Math.max(0, Math.min(input.position, ordered.length)), 0, row);
 			const stmt = db.prepare(`UPDATE session_inputs SET position = ?, version = version + 1, updated_at_ms = ? WHERE id = ?`);
 			ordered.forEach((item, index) => stmt.run(index + 1, now, item.id));
-		} else db.prepare(`UPDATE session_inputs SET content = ?, attachments_json = ?, thinking = ?, version = version + 1,
-        updated_at_ms = ? WHERE id = ?`).run(input.content ?? row.content, input.attachments ? JSON.stringify(input.attachments) : row.attachments_json, input.thinking ?? row.thinking, now, input.id);
+		} else db.prepare(`UPDATE session_inputs SET content = ?, attachments_json = ?, context_refs_json = ?,
+        context_snapshots_json = ?, thinking = ?, version = version + 1,
+        updated_at_ms = ? WHERE id = ?`).run(input.content ?? row.content, input.attachments ? JSON.stringify(input.attachments) : row.attachments_json, input.contextRefs ? JSON.stringify(input.contextRefs) : row.context_refs_json, input.contextSnapshots ? JSON.stringify(input.contextSnapshots) : row.context_snapshots_json, input.thinking ?? row.thinking, now, input.id);
 		bumpRevision(db, input.sessionKey);
 		return true;
 	});
@@ -146,4 +158,4 @@ function recoverSessionInputState() {
 	});
 }
 //#endregion
-export { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputState, insertSessionInput, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus };
+export { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputById, getSessionInputState, insertSessionInput, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus };

package/dist/src/storage/sqlite/session-turn-replace-repository.d.ts

@@ -1,11 +1,14 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
+import type { AgentSourceContext, SourceContextRefSummary } from '../../agent/source-context/types.js';
 export type ReplaceLatestSessionTurnInput = {
     sessionKey: string;
     targetTurnId: string;
     clientMessageId: string;
     content: string;
     attachments?: unknown[];
+    contextRefs?: SourceContextRefSummary[];
+    contextSnapshots?: AgentSourceContext[];
     thinking?: string;
     origin: TurnOrigin;
 };

package/dist/src/storage/sqlite/session-turn-replace-repository.js

@@ -93,8 +93,9 @@ function replaceLatestSessionTurnAndQueueInput(input) {
 		const inputId = randomUUID();
 		db.prepare(`INSERT INTO session_inputs(id, session_key, client_message_id,
        requested_delivery, effective_delivery, status, content, attachments_json,
-       thinking, origin_json, position, target_run_id, version, created_at_ms, updated_at_ms)
-       VALUES (?, ?, ?, 'next', 'next', 'queued', ?, ?, ?, ?, ?, NULL, 1, ?, ?)`).run(inputId, input.sessionKey, input.clientMessageId, input.content, input.attachments ? JSON.stringify(input.attachments) : null, input.thinking ?? null, JSON.stringify(input.origin), maxPosition.value + 1, now, now);
+       context_refs_json, context_snapshots_json, thinking, origin_json, position,
+       target_run_id, version, created_at_ms, updated_at_ms)
+       VALUES (?, ?, ?, 'next', 'next', 'queued', ?, ?, ?, ?, ?, ?, ?, NULL, 1, ?, ?)`).run(inputId, input.sessionKey, input.clientMessageId, input.content, input.attachments ? JSON.stringify(input.attachments) : null, input.contextRefs ? JSON.stringify(input.contextRefs) : null, input.contextSnapshots ? JSON.stringify(input.contextSnapshots) : null, input.thinking ?? null, JSON.stringify(input.origin), maxPosition.value + 1, now, now);
 		db.prepare(`UPDATE session_input_runtime SET revision = revision + 1, updated_at_ms = ?
        WHERE session_key = ?`).run(now, input.sessionKey);
 		return {

package/dist/src/storage/sqlite/transcript-repository.js

@@ -33,20 +33,46 @@ function isUserMessageRow(row) {
 	const classified = classifyStoredRow(row);
 	return classified.entryKind === "message" && classified.role === "user";
 }
+function withSessionInputContextMetadata(db, sessionKey, row) {
+	if (!isUserMessageRow(row)) return row;
+	const message = row;
+	const turnId = typeof message.turnId === "string" ? message.turnId.trim() : "";
+	if (!turnId) return row;
+	const metadata = message.metadata && typeof message.metadata === "object" && !Array.isArray(message.metadata) ? message.metadata : {};
+	if (Array.isArray(metadata.sourceContexts) && metadata.sourceContexts.length > 0) return row;
+	const input = db.prepare(`SELECT context_refs_json FROM session_inputs
+     WHERE session_key = ? AND run_id = ? AND context_refs_json IS NOT NULL
+     LIMIT 1`).get(sessionKey, turnId);
+	if (!input) return row;
+	try {
+		const sourceContexts = JSON.parse(input.context_refs_json);
+		if (!Array.isArray(sourceContexts) || sourceContexts.length === 0) return row;
+		return {
+			...message,
+			metadata: {
+				...metadata,
+				sourceContexts
+			}
+		};
+	} catch {
+		return row;
+	}
+}
 function appendTranscriptEntry(sessionKey, row, opts) {
 	if (isRuntimeOnlyTranscriptMessage(row)) throw new Error("Runtime-only messages cannot be persisted in a session transcript");
 	return runSqliteWriteTransaction((db) => {
 		const sessionId = opts?.sessionId ?? readCurrentSessionId(db, sessionKey);
 		if (!sessionId) throw new Error(`Session not found: ${sessionKey}`);
+		const persistedRow = withSessionInputContextMetadata(db, sessionKey, row);
 		const inserted = insertEntry(db, {
 			sessionId,
 			sessionKey,
-			row
+			row: persistedRow
 		});
-		if (classifyStoredRow(row).entryKind === "message") {
+		if (classifyStoredRow(persistedRow).entryKind === "message") {
 			const tokenDelta = opts?.tokenDelta ?? 0;
 			const now = Date.now();
-			const hiddenUpdate = isUserMessageRow(row) ? `hidden_from_session_list = 0,` : "";
+			const hiddenUpdate = isUserMessageRow(persistedRow) ? `hidden_from_session_list = 0,` : "";
 			db.prepare(`UPDATE sessions SET
           message_count = message_count + 1,
           estimated_tokens = estimated_tokens + ?,

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

@@ -25,6 +25,7 @@ export declare function setUnderstandingStatus(id: string, status: Understanding
     explicitness: UserUnderstanding['explicitness'];
     confidence: number;
 }): UserUnderstanding;
+export declare function closeUnderstandingValidity(id: string, validTo?: number): UserUnderstanding;
 export declare function rejectUnderstanding(id: string, reason: string): UserUnderstanding;
 export declare function deleteUnderstanding(id: string): boolean;
 export declare function isUnderstandingSuppressed(canonicalKey: string, scope: UserContextScope, principalId?: string): boolean;
@@ -34,7 +35,9 @@ export declare function listCollaborationRules(principalId?: string): Collaborat
 export declare function reviseCollaborationRule(id: string, statement: string): CollaborationRule;
 export declare function setCollaborationRuleStatus(id: string, status: CollaborationRule['status']): CollaborationRule;
 export declare function deleteCollaborationRule(id: string): boolean;
-export declare function createContextEvidence(input: Omit<ContextEvidence, 'id' | 'createdAt'>, principalId?: string): ContextEvidence;
+export declare function createContextEvidence(input: Omit<ContextEvidence, 'id' | 'ingestedAt' | 'createdAt'> & {
+    ingestedAt?: number;
+}, principalId?: string): ContextEvidence;
 export declare function linkUnderstandingEvidence(versionId: string, evidenceId: string, relation: 'supports' | 'contradicts' | 'supersedes', confidence: number): void;
 export declare function listUnderstandingEvidence(understandingId: string, relation?: 'supports' | 'contradicts' | 'supersedes'): ContextEvidence[];
 export declare function recordContextRun(input: {