@xopcai/xopc 0.0.188 → 0.0.190

package/dist/src/storage/sqlite/migrations/114_user_context_domain.sql

@@ -0,0 +1,193 @@
+CREATE TABLE user_profiles (
+  principal_id TEXT PRIMARY KEY,
+  call_name TEXT NOT NULL DEFAULT '',
+  pronouns TEXT NOT NULL DEFAULT '',
+  timezone TEXT NOT NULL DEFAULT '',
+  locale TEXT NOT NULL DEFAULT '',
+  accessibility_json TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE user_understandings (
+  understanding_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN (
+    'preference', 'boundary', 'relationship', 'routine', 'current_state',
+    'long_term_goal', 'project_context', 'task_lesson', 'derived_insight'
+  )),
+  canonical_key TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN (
+    'candidate', 'active', 'needs_review', 'stale', 'archived', 'rejected'
+  )),
+  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')),
+  durability TEXT NOT NULL CHECK (durability IN ('ephemeral', 'durable', 'recurring')),
+  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')),
+  confidence REAL NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+  valid_from INTEGER,
+  valid_to INTEGER,
+  expires_at INTEGER,
+  review_at INTEGER,
+  current_version_id TEXT NOT NULL REFERENCES user_understanding_versions(version_id)
+    DEFERRABLE INITIALLY DEFERRED,
+  conflict_group_id TEXT,
+  supersedes_id TEXT REFERENCES user_understandings(understanding_id) ON DELETE SET NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE user_understanding_versions (
+  version_id TEXT PRIMARY KEY,
+  understanding_id TEXT NOT NULL REFERENCES user_understandings(understanding_id) ON DELETE CASCADE,
+  statement TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_by TEXT NOT NULL CHECK (created_by IN ('user', 'runtime', 'connector', 'consolidation')),
+  change_reason TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_user_understandings_principal_status
+  ON user_understandings(principal_id, status, updated_at DESC);
+CREATE UNIQUE INDEX idx_user_understandings_active_canonical
+  ON user_understandings(principal_id, canonical_key, scope_type, COALESCE(scope_id, ''))
+  WHERE status IN ('candidate', 'active', 'needs_review', 'stale');
+CREATE INDEX idx_user_understandings_scope
+  ON user_understandings(principal_id, scope_type, scope_id, status);
+CREATE INDEX idx_user_understanding_versions_item
+  ON user_understanding_versions(understanding_id, created_at DESC);
+
+CREATE VIRTUAL TABLE user_understanding_fts USING fts5(
+  statement,
+  understanding_id UNINDEXED,
+  version_id UNINDEXED,
+  tokenize='unicode61'
+);
+
+CREATE TABLE collaboration_rules (
+  rule_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  category TEXT NOT NULL CHECK (category IN ('communication', 'execution', 'boundary', 'routine', 'proactive')),
+  status TEXT NOT NULL CHECK (status IN ('active', 'disabled', 'archived')),
+  priority INTEGER NOT NULL DEFAULT 100,
+  scope_type TEXT NOT NULL CHECK (scope_type IN ('global', 'workspace', 'project', 'session')),
+  scope_id TEXT,
+  conditions_json TEXT NOT NULL DEFAULT '{}',
+  current_revision_id TEXT NOT NULL REFERENCES collaboration_rule_revisions(revision_id)
+    DEFERRABLE INITIALLY DEFERRED,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE collaboration_rule_revisions (
+  revision_id TEXT PRIMARY KEY,
+  rule_id TEXT NOT NULL REFERENCES collaboration_rules(rule_id) ON DELETE CASCADE,
+  statement TEXT NOT NULL,
+  created_by TEXT NOT NULL CHECK (created_by = 'user'),
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_collaboration_rules_principal_status
+  ON collaboration_rules(principal_id, status, priority, updated_at DESC);
+
+CREATE TABLE context_evidence (
+  evidence_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  source_type TEXT NOT NULL CHECK (source_type IN ('conversation', 'connector', 'user', 'runtime')),
+  source_instance_id TEXT,
+  source_ref TEXT NOT NULL,
+  redacted_excerpt TEXT,
+  trust_level TEXT NOT NULL CHECK (trust_level IN ('owner', 'trusted', 'untrusted')),
+  observed_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX idx_context_evidence_source
+  ON context_evidence(principal_id, source_type, COALESCE(source_instance_id, ''), source_ref);
+
+CREATE TABLE understanding_evidence_links (
+  version_id TEXT NOT NULL REFERENCES user_understanding_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)
+);
+
+CREATE TABLE context_runs (
+  context_run_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  turn_id TEXT NOT NULL,
+  session_key TEXT NOT NULL,
+  query TEXT NOT NULL,
+  budget INTEGER NOT NULL,
+  duration_ms INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  UNIQUE (turn_id)
+);
+
+CREATE TABLE context_run_items (
+  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', '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)
+);
+
+CREATE TABLE context_feedback (
+  feedback_id TEXT PRIMARY KEY,
+  turn_id TEXT NOT NULL,
+  context_run_id TEXT NOT NULL REFERENCES context_runs(context_run_id) ON DELETE CASCADE,
+  object_type TEXT,
+  object_id TEXT,
+  rating TEXT NOT NULL CHECK (rating IN ('helpful', 'irrelevant', 'wrong', 'stale', 'sensitive')),
+  reason TEXT,
+  created_at INTEGER NOT NULL,
+  UNIQUE (turn_id, object_type, object_id)
+);
+
+CREATE UNIQUE INDEX idx_context_feedback_response
+  ON context_feedback(turn_id)
+  WHERE object_type IS NULL AND object_id IS NULL;
+
+CREATE TABLE context_suppressions (
+  suppression_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  canonical_key TEXT NOT NULL,
+  scope_type TEXT NOT NULL CHECK (scope_type IN ('global', 'workspace', 'project', 'session')),
+  scope_id TEXT,
+  reason TEXT NOT NULL,
+  expires_at INTEGER,
+  created_at INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX idx_context_suppressions_identity
+  ON context_suppressions(principal_id, canonical_key, scope_type, COALESCE(scope_id, ''));
+
+CREATE TABLE context_consents (
+  consent_id TEXT PRIMARY KEY,
+  principal_id TEXT NOT NULL,
+  understanding_id TEXT NOT NULL REFERENCES user_understandings(understanding_id) ON DELETE CASCADE,
+  session_key TEXT NOT NULL,
+  purpose TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'granted', 'denied', 'consumed')),
+  grant_scope TEXT CHECK (grant_scope IN ('once', 'session', 'always')),
+  expires_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX idx_context_consents_pending
+  ON context_consents(understanding_id, session_key)
+  WHERE status = 'pending';

package/dist/src/storage/sqlite/migrations/115_remove_legacy_user_context.sql

@@ -0,0 +1,6 @@
+DROP TABLE IF EXISTS memory_reference_consents;
+DROP TABLE IF EXISTS user_profile_prompt_state;
+DROP TABLE IF EXISTS user_claim_evidence;
+DROP TABLE IF EXISTS user_claims;
+DROP TABLE IF EXISTS user_entity_handles;
+DROP TABLE IF EXISTS user_entities;

package/dist/src/storage/sqlite/migrations/116_structured_context_consolidation.sql

@@ -0,0 +1,38 @@
+DELETE FROM automations
+WHERE automation_id LIKE 'system-user-context-dreaming:%'
+   OR automation_id IN ('system-dreaming-light', 'system-dreaming-deep', 'system-dreaming-rem');
+
+DELETE FROM memory_records
+WHERE tags_json LIKE '%"user-understanding"%';
+
+DELETE FROM memory_trace_events
+WHERE provider_id = 'user-understanding' OR phase = 'understanding';
+
+DROP TABLE IF EXISTS dreaming_decisions;
+DROP TABLE IF EXISTS dreaming_runs;
+
+CREATE TABLE context_consolidation_runs (
+  run_id TEXT PRIMARY KEY,
+  trigger_kind TEXT NOT NULL CHECK (trigger_kind IN ('schedule', 'manual')),
+  status TEXT NOT NULL CHECK (status IN ('running', 'completed', 'failed')),
+  reason TEXT,
+  metrics_json TEXT NOT NULL DEFAULT '{}',
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER
+);
+
+CREATE INDEX idx_context_consolidation_runs_started
+  ON context_consolidation_runs(started_at DESC);
+
+CREATE TABLE context_consolidation_decisions (
+  decision_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL REFERENCES context_consolidation_runs(run_id) ON DELETE CASCADE,
+  understanding_id TEXT REFERENCES user_understandings(understanding_id) ON DELETE SET NULL,
+  action TEXT NOT NULL CHECK (action IN ('needs_review', 'stale')),
+  reason_code TEXT NOT NULL,
+  evidence_count INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_context_consolidation_decisions_run
+  ON context_consolidation_decisions(run_id, created_at);

package/dist/src/storage/sqlite/migrations/117_unified_understanding_sources.sql

@@ -0,0 +1,110 @@
+ALTER TABLE user_profiles ADD COLUMN role TEXT NOT NULL DEFAULT '';
+ALTER TABLE user_profiles ADD COLUMN primary_goal TEXT NOT NULL DEFAULT '';
+
+CREATE TABLE understanding_source_grants (
+  grant_id TEXT PRIMARY KEY,
+  source_key TEXT NOT NULL UNIQUE,
+  adapter_id TEXT NOT NULL,
+  category TEXT NOT NULL CHECK (category IN (
+    'files', 'recent_documents', 'calendar', 'tasks', 'notes',
+    'mail', 'messages', 'code_activity'
+  )),
+  platform TEXT NOT NULL CHECK (platform IN ('darwin', 'win32', 'linux', 'all')),
+  display_name TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'revoked')),
+  access_mode TEXT NOT NULL CHECK (access_mode IN ('once', 'continuous')),
+  retention_policy TEXT NOT NULL CHECK (retention_policy IN ('metadata_only', 'derived_only', 'bounded_raw')),
+  processing_policy TEXT NOT NULL CHECK (processing_policy IN ('local_only', 'remote_allowed')),
+  config_json TEXT NOT NULL DEFAULT '{}',
+  checkpoint_json TEXT NOT NULL DEFAULT '{}',
+  last_collected_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_understanding_source_grants_status
+  ON understanding_source_grants(status, category, updated_at DESC);
+
+CREATE TABLE understanding_source_runs (
+  run_id TEXT PRIMARY KEY,
+  grant_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('preview', 'bootstrap', 'incremental', 'fingerprint')),
+  status TEXT NOT NULL CHECK (status IN ('queued', 'running', 'completed', 'partial', 'failed', 'canceled')),
+  cursor_before TEXT,
+  cursor_after TEXT,
+  items_seen INTEGER NOT NULL DEFAULT 0,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  error_message TEXT,
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER,
+  FOREIGN KEY (grant_id) REFERENCES understanding_source_grants(grant_id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_understanding_source_runs_grant
+  ON understanding_source_runs(grant_id, started_at DESC);
+CREATE INDEX idx_understanding_source_runs_status
+  ON understanding_source_runs(status, started_at ASC);
+
+CREATE TABLE user_focuses (
+  focus_id TEXT PRIMARY KEY,
+  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),
+  project_id TEXT,
+  evidence_refs_json TEXT NOT NULL DEFAULT '[]',
+  source_run_id TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE SET NULL,
+  FOREIGN KEY (source_run_id) REFERENCES understanding_source_runs(run_id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_user_focuses_status
+  ON user_focuses(status, horizon, updated_at DESC);
+
+-- Replace the work-discovery-only grant foreign key with the unified grant model.
+CREATE TABLE work_understanding_evidence_v117 (
+  evidence_id TEXT PRIMARY KEY,
+  investigation_id TEXT NOT NULL,
+  source_grant_id TEXT,
+  project_id TEXT,
+  source_type TEXT NOT NULL CHECK (source_type IN (
+    'file', 'git', 'project_metadata', 'understanding_source', 'session', 'user_statement'
+  )),
+  source_ref TEXT NOT NULL,
+  observation TEXT NOT NULL,
+  content_hash TEXT,
+  observed_at INTEGER,
+  collected_at INTEGER NOT NULL,
+  sensitivity TEXT NOT NULL DEFAULT 'normal' CHECK (sensitivity IN ('normal', 'restricted')),
+  FOREIGN KEY (investigation_id) REFERENCES work_understanding_investigations(investigation_id) ON DELETE CASCADE,
+  FOREIGN KEY (source_grant_id) REFERENCES understanding_source_grants(grant_id) ON DELETE SET NULL,
+  FOREIGN KEY (project_id) REFERENCES projects(project_id) ON DELETE SET NULL
+);
+
+INSERT INTO work_understanding_evidence_v117 (
+  evidence_id, investigation_id, source_grant_id, project_id, source_type,
+  source_ref, observation, content_hash, observed_at, collected_at, sensitivity
+)
+SELECT
+  evidence_id, investigation_id, NULL, project_id,
+  CASE source_type
+    WHEN 'personal_context' THEN 'understanding_source'
+    ELSE source_type
+  END,
+  source_ref, observation, content_hash, observed_at, collected_at, sensitivity
+FROM work_understanding_evidence;
+
+DROP TABLE work_understanding_evidence;
+ALTER TABLE work_understanding_evidence_v117 RENAME TO work_understanding_evidence;
+
+CREATE INDEX idx_work_understanding_evidence_investigation
+  ON work_understanding_evidence(investigation_id, collected_at ASC);
+CREATE INDEX idx_work_understanding_evidence_source
+  ON work_understanding_evidence(source_grant_id, source_type, collected_at DESC);
+
+DROP TABLE work_discovery_source_refreshes;
+DROP TABLE work_discovery_sources;

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 = 108;
+export declare const XOPC_DB_SCHEMA_VERSION = 117;
 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 = 108;
+const XOPC_DB_SCHEMA_VERSION = 117;
 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 ?? 108;
+	const targetVersion = options.targetVersion ?? 117;
 	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 ?? 108;
+	const appVersion = options.targetVersion ?? 117;
 	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 = 108;
+export const XOPC_DB_SCHEMA_VERSION = 117;
 
 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: 108,
+		targetVersion: 117,
 		databasePath: options.databasePath
 	});
 }

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

@@ -756,26 +756,6 @@ CREATE TABLE IF NOT EXISTS goal_session_links (
 CREATE INDEX IF NOT EXISTS idx_goal_session_links_session
   ON goal_session_links(session_key, linked_at DESC);
 
-CREATE TABLE IF NOT EXISTS memory_reference_consents (
-  consent_id   TEXT PRIMARY KEY,
-  record_id    TEXT NOT NULL,
-  session_key  TEXT NOT NULL,
-  purpose      TEXT NOT NULL,
-  status       TEXT NOT NULL CHECK (status IN ('pending', 'granted', 'denied', 'consumed')),
-  grant_scope  TEXT CHECK (grant_scope IN ('once', 'session', 'always')),
-  expires_at   INTEGER,
-  created_at   INTEGER NOT NULL,
-  updated_at   INTEGER NOT NULL,
-  FOREIGN KEY (record_id) REFERENCES memory_records(record_id) ON DELETE CASCADE
-);
-
-CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_reference_consents_pending
-  ON memory_reference_consents(record_id, session_key)
-  WHERE status = 'pending';
-
-CREATE INDEX IF NOT EXISTS idx_memory_reference_consents_resolution
-  ON memory_reference_consents(record_id, status, session_key, expires_at);
-
 CREATE TABLE IF NOT EXISTS browser_recipes (
   recipe_id TEXT PRIMARY KEY,
   revision INTEGER NOT NULL,

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

@@ -1,3 +1,4 @@
+import { type TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 export type SessionInputDelivery = 'next' | 'steer';
 export type SessionInputStatus = 'queued' | 'running' | 'injecting' | 'completed' | 'cancelled' | 'failed' | 'interrupted';
 export type SessionInput = {
@@ -10,6 +11,7 @@ export type SessionInput = {
     content: string;
     attachments?: unknown[];
     thinking?: string;
+    origin: TurnOrigin;
     position: number;
     targetRunId?: string;
     runId?: string;
@@ -37,6 +39,7 @@ export declare function insertSessionInput(input: {
     content: string;
     attachments?: unknown[];
     thinking?: string;
+    origin: TurnOrigin;
     targetRunId?: string;
 }): SessionInput;
 export declare function claimNextSessionInput(sessionKey: string, runId: string): SessionInput | undefined;

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

@@ -1,4 +1,5 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { turnOriginSchema } from "../../../packages/endpoint-tools-protocol/src/index.js";
 //#region src/storage/sqlite/session-input-repository.ts
 function mapInput(row) {
 	return {
@@ -12,6 +13,7 @@ function mapInput(row) {
 		attachments: row.attachments_json ? JSON.parse(row.attachments_json) : void 0,
 		thinking: row.thinking ?? void 0,
 		position: row.position,
+		origin: turnOriginSchema.parse(JSON.parse(row.origin_json)),
 		targetRunId: row.target_run_id ?? void 0,
 		runId: row.run_id ?? void 0,
 		version: row.version,
@@ -21,7 +23,7 @@ function mapInput(row) {
 	};
 }
 const SELECT_INPUTS = `SELECT id, session_key, client_message_id, requested_delivery,
-  effective_delivery, status, content, attachments_json, thinking, position,
+  effective_delivery, status, content, attachments_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) {
@@ -61,8 +63,8 @@ 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, 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, max.value + 1, input.targetRunId ?? null, now, now);
+      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);
 		bumpRevision(db, input.sessionKey);
 		return mapInput(db.prepare(`${SELECT_INPUTS} WHERE id = ?`).get(input.id));
 	});

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

@@ -0,0 +1,34 @@
+export type UserUnderstandingQualityMetrics = {
+    windowDays: number;
+    since: string;
+    records: {
+        total: number;
+        candidate: number;
+        active: number;
+        rejected: number;
+        needsReview: number;
+        stale: number;
+        archived: number;
+        agingCandidates: number;
+        explicit: number;
+        inferred: number;
+        averageConfidence: number | null;
+    };
+    decisions: {
+        total: number;
+        acceptanceRate: number | null;
+    };
+    recall: {
+        total: number;
+        helpful: number;
+        notHelpful: number;
+        mixed: number;
+        irrelevant: number;
+        helpfulRate: number | null;
+    };
+};
+export declare function summarizeUserUnderstandingQuality(options?: {
+    windowDays?: number;
+    agingCandidateDays?: number;
+    nowMs?: number;
+}): UserUnderstandingQualityMetrics;

package/dist/src/storage/sqlite/user-context-quality-repository.js

@@ -0,0 +1,74 @@
+import { getSqliteDatabase } from "./transaction.js";
+import { USER_CONTEXT_PRINCIPAL_ID } from "../../user-context/domain.js";
+//#region src/storage/sqlite/user-context-quality-repository.ts
+function rate(numerator, denominator) {
+	return denominator > 0 ? Math.round(numerator / denominator * 1e4) / 1e4 : null;
+}
+function summarizeUserUnderstandingQuality(options = {}) {
+	const nowMs = options.nowMs ?? Date.now();
+	const windowDays = Math.max(1, Math.min(365, Math.floor(options.windowDays ?? 30)));
+	const sinceMs = nowMs - windowDays * 864e5;
+	const agingCutoff = nowMs - Math.max(1, Math.min(windowDays, Math.floor(options.agingCandidateDays ?? 7))) * 864e5;
+	const db = getSqliteDatabase();
+	const rows = db.prepare(`SELECT status, explicitness, confidence, created_at, updated_at
+    FROM user_understandings WHERE principal_id = ?`).all(USER_CONTEXT_PRINCIPAL_ID);
+	const records = {
+		total: rows.length,
+		candidate: 0,
+		active: 0,
+		rejected: 0,
+		needsReview: 0,
+		stale: 0,
+		archived: 0,
+		agingCandidates: 0,
+		explicit: 0,
+		inferred: 0,
+		averageConfidence: rows.length ? Math.round(rows.reduce((sum, row) => sum + row.confidence, 0) / rows.length * 1e4) / 1e4 : null
+	};
+	for (const row of rows) {
+		if (row.status === "candidate") records.candidate += 1;
+		if (row.status === "active") records.active += 1;
+		if (row.status === "rejected") records.rejected += 1;
+		if (row.status === "needs_review") records.needsReview += 1;
+		if (row.status === "stale") records.stale += 1;
+		if (row.status === "archived") records.archived += 1;
+		if (row.status === "candidate" && row.created_at <= agingCutoff) records.agingCandidates += 1;
+		if (row.explicitness === "explicit") records.explicit += 1;
+		if (row.explicitness === "inferred") records.inferred += 1;
+	}
+	const recentDecisions = rows.filter((row) => (row.status === "active" || row.status === "rejected") && row.updated_at >= sinceMs);
+	const accepted = recentDecisions.filter((row) => row.status === "active").length;
+	const feedback = db.prepare(`SELECT DISTINCT f.feedback_id, f.rating
+    FROM context_feedback f
+    JOIN context_runs r ON r.context_run_id = f.context_run_id
+    WHERE f.created_at >= ? AND EXISTS (
+      SELECT 1 FROM context_run_items i
+      WHERE i.context_run_id = r.context_run_id
+        AND i.object_type = 'understanding' AND i.decision = 'selected'
+    )`).all(sinceMs);
+	const recall = {
+		total: feedback.length,
+		helpful: feedback.filter((row) => row.rating === "helpful").length,
+		notHelpful: feedback.filter((row) => [
+			"wrong",
+			"stale",
+			"sensitive"
+		].includes(row.rating)).length,
+		mixed: 0,
+		irrelevant: feedback.filter((row) => row.rating === "irrelevant").length,
+		helpfulRate: null
+	};
+	recall.helpfulRate = rate(recall.helpful, recall.total);
+	return {
+		windowDays,
+		since: new Date(sinceMs).toISOString(),
+		records,
+		decisions: {
+			total: recentDecisions.length,
+			acceptanceRate: rate(accepted, recentDecisions.length)
+		},
+		recall
+	};
+}
+//#endregion
+export { summarizeUserUnderstandingQuality };

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

@@ -0,0 +1,64 @@
+import { type CollaborationRule, type ContextEvidence, type PersonalizationItem, type UnderstandingStatus, type UserContextScope, type UserProfile, type UserUnderstanding } from '../../user-context/domain.js';
+export declare function getUserProfile(principalId?: string): UserProfile;
+export declare function updateUserProfile(patch: Partial<Pick<UserProfile, 'callName' | 'role' | 'primaryGoal' | 'pronouns' | 'timezone' | 'locale' | 'accessibility'>>, principalId?: string): UserProfile;
+export type CreateUnderstandingInput = Omit<UserUnderstanding, 'id' | 'versionId' | 'createdAt' | 'updatedAt' | 'statement' | 'payload'> & {
+    statement: string;
+    payload?: Record<string, unknown>;
+    createdBy: 'user' | 'runtime' | 'connector' | 'consolidation';
+    changeReason: string;
+};
+export declare function createUnderstanding(input: CreateUnderstandingInput, principalId?: string): UserUnderstanding;
+export declare function getUnderstanding(id: string): UserUnderstanding | undefined;
+export declare function listUnderstandings(statuses?: UnderstandingStatus[], principalId?: string): UserUnderstanding[];
+export declare function reviseUnderstanding(id: string, statement: string, options: {
+    payload?: Record<string, unknown>;
+    canonicalKey?: string;
+    explicitness?: UserUnderstanding['explicitness'];
+    confidence?: number;
+    changeReason: string;
+}): UserUnderstanding;
+export declare function setUnderstandingStatus(id: string, status: UnderstandingStatus, confirmation?: {
+    explicitness: UserUnderstanding['explicitness'];
+    confidence: 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;
+export declare function createCollaborationRule(input: Pick<CollaborationRule, 'category' | 'priority' | 'scope' | 'conditions' | 'statement'>, principalId?: string): CollaborationRule;
+export declare function getCollaborationRule(id: string): CollaborationRule | undefined;
+export declare function listCollaborationRules(principalId?: string): CollaborationRule[];
+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 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: {
+    turnId: string;
+    sessionKey: string;
+    query: string;
+    budget: number;
+    durationMs: number;
+    items: PersonalizationItem[];
+    principalId?: string;
+}): string;
+export declare function getTurnPersonalization(turnId: string): {
+    runId: string;
+    items: PersonalizationItem[];
+} | undefined;
+export declare function recordContextFeedback(input: {
+    turnId: string;
+    runId: string;
+    objectType?: PersonalizationItem['objectType'];
+    objectId?: string;
+    rating: 'helpful' | 'irrelevant' | 'wrong' | 'stale' | 'sensitive';
+    reason?: string;
+}): void;
+export declare function hasContextConsent(understandingId: string, sessionKey: string): boolean;
+export declare function consumeContextConsent(understandingId: string, sessionKey: string): 'granted' | 'denied' | 'missing';
+export declare function ensureContextConsent(understandingId: string, sessionKey: string, purpose: string): {
+    id: string;
+    understandingId: string;
+    purpose: string;
+};
+export declare function decideContextConsent(id: string, decision: 'once' | 'session' | 'always' | 'deny'): boolean;