@xopcai/xopc 0.0.248 → 0.0.250

package/dist/src/user-model/domain.js

@@ -0,0 +1,33 @@
+//#region src/user-model/domain.ts
+const USER_MODEL_PRINCIPAL_ID = "local-owner";
+function validateScope(scope) {
+	const id = scope.id?.trim();
+	if (scope.type === "global") {
+		if (id) throw new Error("Global user-model scope must not have an id.");
+		return;
+	}
+	if (!id) throw new Error(`${scope.type} user-model scope requires an id.`);
+}
+function validateCandidate(candidate) {
+	validateScope(candidate.scope);
+	if (!candidate.subject.id.trim()) throw new Error("Assertion subject id is required.");
+	if (!candidate.predicate.trim()) throw new Error("Assertion predicate is required.");
+	if (!candidate.normalizedValue.trim()) throw new Error("Assertion normalized value is required.");
+	if (!candidate.statement.trim()) throw new Error("Assertion statement is required.");
+	if (!Number.isFinite(candidate.observedAt)) throw new Error("Assertion observedAt must be finite.");
+	for (const [field, value] of [
+		["validFrom", candidate.validFrom],
+		["validTo", candidate.validTo],
+		["reviewAt", candidate.reviewAt]
+	]) if (value !== void 0 && !Number.isFinite(value)) throw new Error(`${field} must be finite.`);
+	for (const [field, value] of [
+		["confidence", candidate.confidence],
+		["inferredImportance", candidate.inferredImportance],
+		["actionability", candidate.actionability],
+		["declaredImportance", candidate.declaredImportance],
+		["evidenceConfidence", candidate.evidenceConfidence]
+	]) if (value !== void 0 && (!Number.isFinite(value) || value < 0 || value > 1)) throw new Error(`${field} must be between 0 and 1.`);
+	if (candidate.validFrom !== void 0 && candidate.validTo !== void 0 && candidate.validTo < candidate.validFrom) throw new Error("Assertion validTo must be greater than or equal to validFrom.");
+}
+//#endregion
+export { USER_MODEL_PRINCIPAL_ID, validateCandidate, validateScope };

package/dist/src/user-model/goals.d.ts

@@ -0,0 +1,62 @@
+import { type AssertionAuthority, type UserModelScope } from './domain.js';
+export type UserGoalStatus = 'proposed' | 'active' | 'paused' | 'achieved' | 'abandoned';
+export interface UserGoal {
+    id: string;
+    principalId: string;
+    status: UserGoalStatus;
+    scope: UserModelScope;
+    title: string;
+    desiredOutcome: string;
+    declaredImportance?: number;
+    confidence: number;
+    authority: AssertionAuthority;
+    targetAt?: number;
+    validFrom?: number;
+    validTo?: number;
+    reviewAt?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface UserPriorityWindow {
+    id: string;
+    principalId: string;
+    targetType: 'goal' | 'project' | 'task' | 'assertion' | 'topic';
+    targetId: string;
+    rank: 'primary' | 'secondary' | 'background';
+    declaredImportance?: number;
+    urgency: number;
+    scope: UserModelScope;
+    validFrom: number;
+    validTo: number;
+    reviewAt: number;
+    status: 'active' | 'paused' | 'completed' | 'expired';
+    createdAt: number;
+    updatedAt: number;
+}
+export declare function listUserGoals(principalId?: string): UserGoal[];
+export declare function createUserGoal(input: {
+    title: string;
+    desiredOutcome: string;
+    scope: UserModelScope;
+    declaredImportance?: number;
+    targetAt?: number;
+    status?: Extract<UserGoalStatus, 'proposed' | 'active'>;
+    authority?: AssertionAuthority;
+    confidence?: number;
+    createdBy?: 'user' | 'runtime';
+    now?: number;
+}): UserGoal;
+export declare function setUserGoalStatus(id: string, status: UserGoalStatus, now?: number): UserGoal | undefined;
+export declare function listPriorityWindows(principalId?: string): UserPriorityWindow[];
+export declare function createPriorityWindow(input: {
+    targetType: UserPriorityWindow['targetType'];
+    targetId: string;
+    rank: UserPriorityWindow['rank'];
+    urgency: number;
+    scope: UserModelScope;
+    validFrom: number;
+    validTo: number;
+    reviewAt?: number;
+    declaredImportance?: number;
+    now?: number;
+}): UserPriorityWindow;

package/dist/src/user-model/goals.js

@@ -0,0 +1,91 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { USER_MODEL_PRINCIPAL_ID, validateScope } from "./domain.js";
+import { randomUUID } from "node:crypto";
+//#region src/user-model/goals.ts
+function optionalNumber(value) {
+	return value === null ? void 0 : value;
+}
+function listUserGoals(principalId = USER_MODEL_PRINCIPAL_ID) {
+	return getSqliteDatabase().prepare(`SELECT g.*, r.title, r.desired_outcome
+    FROM user_goals g JOIN user_goal_revisions r ON r.revision_id = g.current_revision_id
+    WHERE g.principal_id = ? ORDER BY g.updated_at DESC`).all(principalId).map((row) => ({
+		id: row.goal_id,
+		principalId: row.principal_id,
+		status: row.status,
+		scope: {
+			type: row.scope_type,
+			...row.scope_id ? { id: row.scope_id } : {}
+		},
+		title: row.title,
+		desiredOutcome: row.desired_outcome,
+		...optionalNumber(row.declared_importance) === void 0 ? {} : { declaredImportance: row.declared_importance },
+		confidence: row.confidence,
+		authority: row.authority,
+		...optionalNumber(row.target_at) === void 0 ? {} : { targetAt: row.target_at },
+		...optionalNumber(row.valid_from) === void 0 ? {} : { validFrom: row.valid_from },
+		...optionalNumber(row.valid_to) === void 0 ? {} : { validTo: row.valid_to },
+		...optionalNumber(row.review_at) === void 0 ? {} : { reviewAt: row.review_at },
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	}));
+}
+function createUserGoal(input) {
+	validateScope(input.scope);
+	if (!input.title.trim() || !input.desiredOutcome.trim()) throw new Error("Goal title and desired outcome are required.");
+	if (input.declaredImportance !== void 0 && (input.declaredImportance < 0 || input.declaredImportance > 1)) throw new Error("Goal declared importance must be between 0 and 1.");
+	const now = input.now ?? Date.now();
+	const confidence = input.confidence ?? 1;
+	if (confidence < 0 || confidence > 1) throw new Error("Goal confidence must be between 0 and 1.");
+	const goalId = randomUUID();
+	const revisionId = randomUUID();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`INSERT INTO user_goals (
+      goal_id, principal_id, status, scope_type, scope_id, declared_importance,
+      confidence, authority, target_at, current_revision_id, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(goalId, USER_MODEL_PRINCIPAL_ID, input.status ?? "active", input.scope.type, input.scope.id ?? null, input.declaredImportance ?? null, confidence, input.authority ?? "user_explicit", input.targetAt ?? null, revisionId, now, now);
+		db.prepare(`INSERT INTO user_goal_revisions (
+      revision_id, goal_id, title, desired_outcome, created_by, change_reason, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(revisionId, goalId, input.title.trim(), input.desiredOutcome.trim(), input.createdBy ?? "user", input.createdBy === "runtime" ? "Goal extracted from user evidence." : "Goal created by user.", now);
+	});
+	return listUserGoals().find((goal) => goal.id === goalId);
+}
+function setUserGoalStatus(id, status, now = Date.now()) {
+	return getSqliteDatabase().prepare(`UPDATE user_goals SET status = ?, updated_at = ? WHERE goal_id = ?`).run(status, now, id).changes ? listUserGoals().find((goal) => goal.id === id) : void 0;
+}
+function listPriorityWindows(principalId = USER_MODEL_PRINCIPAL_ID) {
+	return getSqliteDatabase().prepare(`SELECT * FROM user_priority_windows
+    WHERE principal_id = ? ORDER BY valid_from DESC`).all(principalId).map((row) => ({
+		id: row.priority_id,
+		principalId: row.principal_id,
+		targetType: row.target_type,
+		targetId: row.target_id,
+		rank: row.rank,
+		...row.declared_importance === null ? {} : { declaredImportance: row.declared_importance },
+		urgency: row.urgency,
+		scope: {
+			type: row.scope_type,
+			...row.scope_id ? { id: row.scope_id } : {}
+		},
+		validFrom: row.valid_from,
+		validTo: row.valid_to,
+		reviewAt: row.review_at,
+		status: row.status,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	}));
+}
+function createPriorityWindow(input) {
+	validateScope(input.scope);
+	if (!input.targetId.trim()) throw new Error("Priority target id is required.");
+	if (input.validTo < input.validFrom) throw new Error("Priority validTo must be after validFrom.");
+	for (const value of [input.urgency, input.declaredImportance]) if (value !== void 0 && (value < 0 || value > 1)) throw new Error("Priority scores must be between 0 and 1.");
+	const now = input.now ?? Date.now();
+	const id = randomUUID();
+	getSqliteDatabase().prepare(`INSERT INTO user_priority_windows (
+    priority_id, principal_id, target_type, target_id, rank, declared_importance,
+    urgency, scope_type, scope_id, valid_from, valid_to, review_at, status, created_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)`).run(id, USER_MODEL_PRINCIPAL_ID, input.targetType, input.targetId.trim(), input.rank, input.declaredImportance ?? null, input.urgency, input.scope.type, input.scope.id ?? null, input.validFrom, input.validTo, input.reviewAt ?? input.validTo, now, now);
+	return listPriorityWindows().find((item) => item.id === id);
+}
+//#endregion
+export { createPriorityWindow, createUserGoal, listPriorityWindows, listUserGoals, setUserGoalStatus };

package/dist/src/user-model/importance.d.ts

@@ -0,0 +1,11 @@
+import type { AssertionConsequence } from './domain.js';
+export interface ExecutionValueInput {
+    declaredImportance?: number;
+    inferredImportance: number;
+    consequence: AssertionConsequence;
+    actionability: number;
+    taskRelevance: number;
+    urgency: number;
+}
+/** Ranks eligible context. Confidence is deliberately absent: it is an admission signal. */
+export declare function calculateExecutionValue(input: ExecutionValueInput): number;

package/dist/src/user-model/importance.js

@@ -0,0 +1,17 @@
+//#region src/user-model/importance.ts
+const CONSEQUENCE_SCORE = {
+	low: .15,
+	medium: .45,
+	high: .75,
+	critical: 1
+};
+function clamp(value) {
+	return Math.min(1, Math.max(0, value));
+}
+/** Ranks eligible context. Confidence is deliberately absent: it is an admission signal. */
+function calculateExecutionValue(input) {
+	const importance = input.declaredImportance ?? input.inferredImportance;
+	return clamp(.28 * clamp(input.taskRelevance) + .22 * clamp(importance) + .2 * CONSEQUENCE_SCORE[input.consequence] + .18 * clamp(input.actionability) + .12 * clamp(input.urgency));
+}
+//#endregion
+export { calculateExecutionValue };

package/dist/src/user-model/index.d.ts

@@ -0,0 +1,5 @@
+export * from './domain.js';
+export * from './importance.js';
+export * from './goals.js';
+export * from './repository.js';
+export * from './temporal.js';

package/dist/src/user-model/index.js

@@ -0,0 +1,6 @@
+import { USER_MODEL_PRINCIPAL_ID, validateCandidate, validateScope } from "./domain.js";
+import { calculateExecutionValue } from "./importance.js";
+import { createPriorityWindow, createUserGoal, listPriorityWindows, listUserGoals, setUserGoalStatus } from "./goals.js";
+import { defaultReviewAt, isAssertionValidAt, requiresBoundedValidity, resolveCurrentAssertion } from "./temporal.js";
+import { getActiveAssertionByPredicate, getActiveAssertionForSlot, getAssertionSlot, getUserAssertion, getUserTimezone, linkAssertionEvidence, listSlotAssertions, listUserAssertions, reconcileAssertion, setAssertionStatus } from "./repository.js";
+export { USER_MODEL_PRINCIPAL_ID, calculateExecutionValue, createPriorityWindow, createUserGoal, defaultReviewAt, getActiveAssertionByPredicate, getActiveAssertionForSlot, getAssertionSlot, getUserAssertion, getUserTimezone, isAssertionValidAt, linkAssertionEvidence, listPriorityWindows, listSlotAssertions, listUserAssertions, listUserGoals, reconcileAssertion, requiresBoundedValidity, resolveCurrentAssertion, setAssertionStatus, setUserGoalStatus, validateCandidate, validateScope };

package/dist/src/user-model/repository.d.ts

@@ -0,0 +1,23 @@
+import { type AssertionCandidate, type AssertionSlot, type AssertionStatus, type ReconciliationResult, type UserAssertion } from './domain.js';
+export declare function reconcileAssertion(candidate: AssertionCandidate, now?: number): ReconciliationResult;
+export declare function getUserAssertion(id: string): UserAssertion | undefined;
+export declare function getAssertionSlot(id: string): AssertionSlot | undefined;
+export declare function listSlotAssertions(slotId: string): UserAssertion[];
+export declare function listUserAssertions(input?: {
+    principalId?: string;
+    statuses?: AssertionStatus[];
+    limit?: number;
+}): UserAssertion[];
+export declare function getActiveAssertionByPredicate(predicate: string): UserAssertion | undefined;
+export declare function getActiveAssertionForSlot(input: {
+    subject: AssertionSlot['subject'];
+    predicate: string;
+    scope: AssertionSlot['scope'];
+}): UserAssertion | undefined;
+export declare function getUserTimezone(): string | undefined;
+export declare function linkAssertionEvidence(assertionId: string, evidenceId: string, relation: 'supports' | 'contradicts' | 'supersedes', confidence: number, now?: number): void;
+export declare function setAssertionStatus(assertionId: string, status: AssertionStatus, input: {
+    actor: 'user' | 'runtime' | 'maintenance' | 'migration';
+    reason: string;
+    now?: number;
+}): UserAssertion;

package/dist/src/user-model/repository.js

@@ -0,0 +1,268 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { USER_MODEL_PRINCIPAL_ID, validateCandidate, validateScope } from "./domain.js";
+import { defaultReviewAt, requiresBoundedValidity } from "./temporal.js";
+import { randomUUID } from "node:crypto";
+//#region src/user-model/repository.ts
+function slotFromRow(row) {
+	return {
+		id: row.slot_id,
+		principalId: row.principal_id,
+		subject: {
+			type: row.subject_type,
+			id: row.subject_id
+		},
+		predicate: row.predicate,
+		cardinality: row.cardinality,
+		scope: {
+			type: row.scope_type,
+			...row.scope_id ? { id: row.scope_id } : {}
+		},
+		createdAt: row.created_at
+	};
+}
+function assertionFromRow(row) {
+	return {
+		id: row.assertion_id,
+		slotId: row.slot_id,
+		kind: row.kind,
+		value: JSON.parse(row.value_json),
+		normalizedValue: row.normalized_value,
+		statement: row.statement,
+		authority: row.authority,
+		status: row.status,
+		confidence: row.confidence,
+		...row.declared_importance === null ? {} : { declaredImportance: row.declared_importance },
+		inferredImportance: row.inferred_importance,
+		consequence: row.consequence,
+		actionability: row.actionability,
+		volatility: row.volatility,
+		sensitivity: row.sensitivity,
+		disclosurePolicy: row.disclosure_policy,
+		applicability: JSON.parse(row.applicability_json),
+		...row.valid_from === null ? {} : { validFrom: row.valid_from },
+		...row.valid_to === null ? {} : { validTo: row.valid_to },
+		observedAt: row.observed_at,
+		recordedAt: row.recorded_at,
+		...row.review_at === null ? {} : { reviewAt: row.review_at },
+		...row.supersedes_assertion_id === null ? {} : { supersedesAssertionId: row.supersedes_assertion_id },
+		createdBy: row.created_by,
+		createdAt: row.created_at
+	};
+}
+function findOrCreateSlot(db, candidate, now) {
+	const principalId = candidate.principalId ?? "local-owner";
+	const scopeId = candidate.scope.id?.trim() ?? null;
+	const existing = db.prepare(`SELECT * FROM user_assertion_slots
+    WHERE principal_id = ? AND subject_type = ? AND subject_id = ? AND predicate = ?
+      AND scope_type = ? AND COALESCE(scope_id, '') = COALESCE(?, '')`).get(principalId, candidate.subject.type, candidate.subject.id.trim(), candidate.predicate.trim(), candidate.scope.type, scopeId);
+	if (existing) {
+		if (existing.cardinality !== candidate.cardinality) throw new Error(`Assertion slot cardinality mismatch for ${candidate.predicate}.`);
+		return slotFromRow(existing);
+	}
+	const id = randomUUID();
+	db.prepare(`INSERT INTO user_assertion_slots (
+    slot_id, principal_id, subject_type, subject_id, predicate, cardinality,
+    scope_type, scope_id, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, candidate.subject.type, candidate.subject.id.trim(), candidate.predicate.trim(), candidate.cardinality, candidate.scope.type, scopeId, now);
+	return slotFromRow(db.prepare("SELECT * FROM user_assertion_slots WHERE slot_id = ?").get(id));
+}
+function intervalsOverlap(left, candidate) {
+	const leftStart = left.validFrom ?? Number.NEGATIVE_INFINITY;
+	const leftEnd = left.validTo ?? Number.POSITIVE_INFINITY;
+	const rightStart = candidate.validFrom ?? Number.NEGATIVE_INFINITY;
+	return leftStart <= (candidate.validTo ?? Number.POSITIVE_INFINITY) && rightStart <= leftEnd;
+}
+function listReconcilableAssertions(db, slotId) {
+	return db.prepare(`SELECT * FROM user_assertions WHERE slot_id = ?
+    AND status NOT IN ('rejected', 'archived') ORDER BY recorded_at DESC`).all(slotId).map(assertionFromRow);
+}
+function sortByAuthorityAndRecorded(assertions) {
+	return assertions.sort((left, right) => authorityRank(right.authority) - authorityRank(left.authority) || right.recordedAt - left.recordedAt);
+}
+function initialStatus(candidate) {
+	if (requiresBoundedValidity(candidate.kind, candidate.volatility) && candidate.validTo === void 0) return "needs_review";
+	return candidate.authority === "user_explicit" ? "active" : "candidate";
+}
+function insertAssertion(db, slotId, candidate, status, now, supersedesAssertionId) {
+	const id = randomUUID();
+	const reviewAt = candidate.reviewAt ?? defaultReviewAt(candidate.volatility, candidate.observedAt) ?? null;
+	db.prepare(`INSERT INTO user_assertions (
+    assertion_id, slot_id, kind, value_json, normalized_value, statement, authority, status,
+    confidence, declared_importance, inferred_importance, consequence, actionability,
+    volatility, sensitivity, disclosure_policy, applicability_json, valid_from, valid_to,
+    observed_at, recorded_at, review_at, supersedes_assertion_id, created_by, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, slotId, candidate.kind, JSON.stringify(candidate.value), candidate.normalizedValue.trim(), candidate.statement.trim(), candidate.authority, status, candidate.confidence, candidate.declaredImportance ?? null, candidate.inferredImportance, candidate.consequence, candidate.actionability, candidate.volatility, candidate.sensitivity, candidate.disclosurePolicy, JSON.stringify(candidate.applicability ?? {}), candidate.validFrom ?? null, candidate.validTo ?? null, candidate.observedAt, now, reviewAt, supersedesAssertionId ?? null, candidate.createdBy, now);
+	db.prepare(`INSERT INTO user_assertions_fts(statement, assertion_id, slot_id) VALUES (?, ?, ?)`).run(candidate.statement.trim(), id, slotId);
+	recordStatusEvent(db, id, null, status, candidate.createdBy === "connector" ? "runtime" : candidate.createdBy, "Assertion admitted.", now);
+	if (candidate.evidenceId) db.prepare(`INSERT INTO user_assertion_evidence (
+      assertion_id, evidence_id, relation, confidence, created_at
+    ) VALUES (?, ?, 'supports', ?, ?)
+    ON CONFLICT(assertion_id, evidence_id, relation) DO UPDATE SET confidence = excluded.confidence`).run(id, candidate.evidenceId, candidate.evidenceConfidence ?? candidate.confidence, now);
+	return assertionFromRow(db.prepare("SELECT * FROM user_assertions WHERE assertion_id = ?").get(id));
+}
+function recordStatusEvent(db, assertionId, fromStatus, toStatus, actor, reason, now) {
+	db.prepare(`INSERT INTO user_assertion_status_events (
+    event_id, assertion_id, from_status, to_status, actor_type, reason, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), assertionId, fromStatus, toStatus, actor, reason, now);
+}
+function attachEvidence(db, assertionId, candidate, now) {
+	if (!candidate.evidenceId) return;
+	db.prepare(`INSERT INTO user_assertion_evidence (
+    assertion_id, evidence_id, relation, confidence, created_at
+  ) VALUES (?, ?, 'supports', ?, ?)
+  ON CONFLICT(assertion_id, evidence_id, relation) DO UPDATE SET confidence = excluded.confidence`).run(assertionId, candidate.evidenceId, candidate.evidenceConfidence ?? candidate.confidence, now);
+}
+function closeValidity(db, assertion, boundary, now) {
+	if (assertion.validFrom !== void 0 && boundary <= assertion.validFrom) {
+		updateStatus(db, assertion, "archived", "Superseded before its validity began.", now);
+		return;
+	}
+	const end = boundary - 1;
+	db.prepare(`UPDATE user_assertions SET valid_to = ?
+    WHERE assertion_id = ? AND (valid_to IS NULL OR valid_to >= ?)`).run(end, assertion.id, boundary);
+}
+function updateStatus(db, assertion, status, reason, now) {
+	if (assertion.status === status) return;
+	db.prepare("UPDATE user_assertions SET status = ? WHERE assertion_id = ?").run(status, assertion.id);
+	recordStatusEvent(db, assertion.id, assertion.status, status, "runtime", reason, now);
+}
+function authorityRank(authority) {
+	return {
+		external_untrusted: 0,
+		system_inferred: 1,
+		user_observed: 2,
+		user_explicit: 3
+	}[authority];
+}
+function reconcileAssertion(candidate, now = Date.now()) {
+	validateCandidate(candidate);
+	return runSqliteWriteTransaction((db) => {
+		const slot = findOrCreateSlot(db, candidate, now);
+		const existing = listReconcilableAssertions(db, slot.id);
+		if (candidate.correctionOfAssertionId) {
+			if (candidate.authority !== "user_explicit") throw new Error("Only an explicit user assertion can correct an existing assertion.");
+			const target = existing.find((item) => item.id === candidate.correctionOfAssertionId);
+			if (!target) throw new Error("Correction target does not belong to the resolved assertion slot.");
+			if (target.normalizedValue === candidate.normalizedValue.trim()) {
+				attachEvidence(db, target.id, candidate, now);
+				return {
+					action: "deduplicated",
+					assertion: target
+				};
+			}
+			const assertion = insertAssertion(db, slot.id, candidate, "active", now, target.id);
+			closeValidity(db, target, candidate.validFrom ?? candidate.observedAt, now);
+			return {
+				action: "superseded",
+				assertion,
+				previousAssertion: getUserAssertion(target.id)
+			};
+		}
+		const overlapping = sortByAuthorityAndRecorded(existing.filter((item) => intervalsOverlap(item, candidate)));
+		const duplicate = overlapping.find((item) => item.normalizedValue === candidate.normalizedValue.trim());
+		if (duplicate) {
+			attachEvidence(db, duplicate.id, candidate, now);
+			return {
+				action: "deduplicated",
+				assertion: duplicate
+			};
+		}
+		const status = initialStatus(candidate);
+		if (slot.cardinality === "multiple" || !overlapping.length) return {
+			action: "created",
+			assertion: insertAssertion(db, slot.id, candidate, status, now)
+		};
+		const current = overlapping[0];
+		if (candidate.authority === "user_explicit" && authorityRank(candidate.authority) > authorityRank(current.authority)) {
+			const assertion = insertAssertion(db, slot.id, candidate, status, now, current.id);
+			closeValidity(db, current, candidate.validFrom ?? candidate.observedAt, now);
+			return {
+				action: "superseded",
+				assertion,
+				previousAssertion: getUserAssertion(current.id)
+			};
+		}
+		const assertion = insertAssertion(db, slot.id, candidate, candidate.authority === "user_explicit" ? "needs_review" : "conflicted", now);
+		if (current.authority !== "user_explicit" && candidate.authority !== "user_explicit") updateStatus(db, current, "conflicted", "Overlapping assertion has a different value.", now);
+		return {
+			action: "conflicted",
+			assertion,
+			previousAssertion: getUserAssertion(current.id)
+		};
+	});
+}
+function getUserAssertion(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM user_assertions WHERE assertion_id = ?").get(id);
+	return row ? assertionFromRow(row) : void 0;
+}
+function getAssertionSlot(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM user_assertion_slots WHERE slot_id = ?").get(id);
+	return row ? slotFromRow(row) : void 0;
+}
+function listSlotAssertions(slotId) {
+	return getSqliteDatabase().prepare(`SELECT * FROM user_assertions
+    WHERE slot_id = ? ORDER BY recorded_at DESC`).all(slotId).map(assertionFromRow);
+}
+function listUserAssertions(input = {}) {
+	const principalId = input.principalId ?? "local-owner";
+	const statuses = input.statuses ?? [
+		"active",
+		"candidate",
+		"needs_review",
+		"conflicted"
+	];
+	if (!statuses.length) return [];
+	const placeholders = statuses.map(() => "?").join(", ");
+	const limit = Math.max(1, Math.min(2e3, input.limit ?? 200));
+	return getSqliteDatabase().prepare(`SELECT a.* FROM user_assertions a
+    JOIN user_assertion_slots s ON s.slot_id = a.slot_id
+    WHERE s.principal_id = ? AND a.status IN (${placeholders})
+    ORDER BY a.recorded_at DESC LIMIT ?`).all(principalId, ...statuses, limit).map(assertionFromRow);
+}
+function getActiveAssertionByPredicate(predicate) {
+	const row = getSqliteDatabase().prepare(`SELECT a.* FROM user_assertions a
+    JOIN user_assertion_slots s ON s.slot_id = a.slot_id
+    WHERE s.principal_id = ? AND s.predicate = ? AND a.status = 'active'
+      AND (a.valid_from IS NULL OR a.valid_from <= ?)
+      AND (a.valid_to IS NULL OR a.valid_to >= ?)
+    ORDER BY CASE a.authority WHEN 'user_explicit' THEN 0 WHEN 'user_observed' THEN 1
+      WHEN 'system_inferred' THEN 2 ELSE 3 END, a.recorded_at DESC LIMIT 1`).get(USER_MODEL_PRINCIPAL_ID, predicate, Date.now(), Date.now());
+	return row ? assertionFromRow(row) : void 0;
+}
+function getActiveAssertionForSlot(input) {
+	validateScope(input.scope);
+	const row = getSqliteDatabase().prepare(`SELECT a.* FROM user_assertions a
+    JOIN user_assertion_slots s ON s.slot_id = a.slot_id
+    WHERE s.principal_id = ? AND s.subject_type = ? AND s.subject_id = ?
+      AND s.predicate = ? AND s.scope_type = ?
+      AND COALESCE(s.scope_id, '') = COALESCE(?, '') AND a.status = 'active'
+      AND (a.valid_from IS NULL OR a.valid_from <= ?)
+      AND (a.valid_to IS NULL OR a.valid_to >= ?)
+    ORDER BY CASE a.authority WHEN 'user_explicit' THEN 0 WHEN 'user_observed' THEN 1
+      WHEN 'system_inferred' THEN 2 ELSE 3 END, a.recorded_at DESC LIMIT 1`).get(USER_MODEL_PRINCIPAL_ID, input.subject.type, input.subject.id.trim(), input.predicate.trim(), input.scope.type, input.scope.id?.trim() ?? null, Date.now(), Date.now());
+	return row ? assertionFromRow(row) : void 0;
+}
+function getUserTimezone() {
+	const value = getActiveAssertionByPredicate("preference.timezone")?.value;
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function linkAssertionEvidence(assertionId, evidenceId, relation, confidence, now = Date.now()) {
+	if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("Evidence confidence must be between 0 and 1.");
+	getSqliteDatabase().prepare(`INSERT INTO user_assertion_evidence (
+    assertion_id, evidence_id, relation, confidence, created_at
+  ) VALUES (?, ?, ?, ?, ?)
+  ON CONFLICT(assertion_id, evidence_id, relation) DO UPDATE SET confidence = excluded.confidence`).run(assertionId, evidenceId, relation, confidence, now);
+}
+function setAssertionStatus(assertionId, status, input) {
+	const current = getUserAssertion(assertionId);
+	if (!current) throw new Error(`User assertion not found: ${assertionId}`);
+	if (current.status === status) return current;
+	const now = input.now ?? Date.now();
+	runSqliteWriteTransaction((db) => {
+		db.prepare("UPDATE user_assertions SET status = ? WHERE assertion_id = ?").run(status, assertionId);
+		recordStatusEvent(db, assertionId, current.status, status, input.actor, input.reason, now);
+	});
+	return getUserAssertion(assertionId);
+}
+//#endregion
+export { getActiveAssertionByPredicate, getActiveAssertionForSlot, getAssertionSlot, getUserAssertion, getUserTimezone, linkAssertionEvidence, listSlotAssertions, listUserAssertions, reconcileAssertion, setAssertionStatus };

package/dist/src/user-model/temporal.d.ts

@@ -0,0 +1,10 @@
+import type { AssertionKind, AssertionVolatility, UserAssertion } from './domain.js';
+export declare function defaultReviewAt(volatility: AssertionVolatility, observedAt: number): number | undefined;
+export declare function requiresBoundedValidity(kind: AssertionKind, volatility: AssertionVolatility): boolean;
+export declare function isAssertionValidAt(assertion: UserAssertion, asOf: number): boolean;
+export interface CurrentAssertionResolution {
+    assertion?: UserAssertion;
+    conflict: boolean;
+    contenders: UserAssertion[];
+}
+export declare function resolveCurrentAssertion(assertions: UserAssertion[], asOf?: number): CurrentAssertionResolution;

package/dist/src/user-model/temporal.js

@@ -0,0 +1,44 @@
+//#region src/user-model/temporal.ts
+const REVIEW_INTERVAL_MS = {
+	stable: void 0,
+	slow: 4320 * 60 * 60 * 1e3,
+	dynamic: 720 * 60 * 60 * 1e3,
+	event: 10080 * 60 * 1e3
+};
+function defaultReviewAt(volatility, observedAt) {
+	const interval = REVIEW_INTERVAL_MS[volatility];
+	return interval === void 0 ? void 0 : observedAt + interval;
+}
+function requiresBoundedValidity(kind, volatility) {
+	return kind === "current_state" || volatility === "event";
+}
+function isAssertionValidAt(assertion, asOf) {
+	return assertion.status === "active" && (assertion.validFrom === void 0 || assertion.validFrom <= asOf) && (assertion.validTo === void 0 || assertion.validTo >= asOf);
+}
+const AUTHORITY_RANK = {
+	external_untrusted: 0,
+	system_inferred: 1,
+	user_observed: 2,
+	user_explicit: 3
+};
+function resolveCurrentAssertion(assertions, asOf = Date.now()) {
+	const contenders = assertions.filter((item) => isAssertionValidAt(item, asOf));
+	if (!contenders.length) return {
+		conflict: false,
+		contenders: []
+	};
+	contenders.sort((left, right) => AUTHORITY_RANK[right.authority] - AUTHORITY_RANK[left.authority] || right.recordedAt - left.recordedAt);
+	const best = contenders[0];
+	if (contenders.filter((item) => AUTHORITY_RANK[item.authority] === AUTHORITY_RANK[best.authority] && item.normalizedValue !== best.normalizedValue).length) return {
+		assertion: void 0,
+		conflict: true,
+		contenders
+	};
+	return {
+		assertion: best,
+		conflict: false,
+		contenders
+	};
+}
+//#endregion
+export { defaultReviewAt, isAssertionValidAt, requiresBoundedValidity, resolveCurrentAssertion };

package/dist/src/voice/realtime/memory-context.d.ts

@@ -1,7 +1,12 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
-import { type AutomaticContextSelection } from '../../user-context/automatic-context.js';
-export interface VoiceMemorySnapshot extends AutomaticContextSelection {
+export interface VoiceMemorySnapshot {
+    block: string;
+    references: Array<{
+        kind: 'assertion' | 'knowledge';
+        id: string;
+        updatedAt: number;
+    }>;
     isCurrent: () => boolean;
     subscribe: (invalidate: () => void) => () => void;
 }