@xopcai/xopc 0.0.171 → 0.0.172

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

@@ -29,6 +29,7 @@ function sourceItemFromRow(row) {
 	return {
 		id: row.item_id,
 		sourceInstanceId: row.source_instance_id,
+		collectionScope: row.collection_scope,
 		externalId: row.external_id,
 		itemType: row.item_type,
 		...row.author_role ? { authorRole: row.author_role } : {},
@@ -127,16 +128,16 @@ function listKnowledgeSyncRuns(options = {}) {
        ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
        ORDER BY started_at DESC LIMIT ?`).all(...params, limit).map(syncRunFromRow);
 }
-function getKnowledgeSourceCursor(sourceInstanceId) {
-	return getSqliteDatabase().prepare(`SELECT cursor FROM knowledge_source_state WHERE source_instance_id = ?`).get(sourceInstanceId)?.cursor ?? void 0;
+function getKnowledgeSourceCursor(sourceInstanceId, collectionScope) {
+	return getSqliteDatabase().prepare(`SELECT cursor FROM knowledge_collection_state WHERE source_instance_id = ? AND collection_scope = ?`).get(sourceInstanceId, collectionScope)?.cursor ?? void 0;
 }
-function setKnowledgeSourceCursor(sourceInstanceId, cursor) {
+function setKnowledgeSourceCursor(sourceInstanceId, collectionScope, cursor) {
 	runSqliteWriteTransaction((db) => {
-		db.prepare(`INSERT INTO knowledge_source_state (source_instance_id, cursor, updated_at)
-       VALUES (?, ?, ?)
-       ON CONFLICT(source_instance_id) DO UPDATE SET
+		db.prepare(`INSERT INTO knowledge_collection_state (source_instance_id, collection_scope, cursor, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(source_instance_id, collection_scope) DO UPDATE SET
          cursor = excluded.cursor,
-         updated_at = excluded.updated_at`).run(sourceInstanceId, cursor ?? null, Date.now());
+         updated_at = excluded.updated_at`).run(sourceInstanceId, collectionScope, cursor ?? null, Date.now());
 	});
 }
 function upsertKnowledgeSourceItems(inputs, nowMs = Date.now()) {
@@ -147,7 +148,7 @@ function upsertKnowledgeSourceItems(inputs, nowMs = Date.now()) {
 		let unchanged = 0;
 		for (const input of inputs) {
 			const existing = db.prepare(`SELECT * FROM knowledge_source_items
-         WHERE source_instance_id = ? AND external_id = ?`).get(input.sourceInstanceId, input.externalId);
+         WHERE source_instance_id = ? AND collection_scope = ? AND external_id = ?`).get(input.sourceInstanceId, input.collectionScope, input.externalId);
 			const id = existing?.item_id ?? input.id ?? randomUUID();
 			if (existing?.content_hash === input.contentHash && existing.deleted_at === parseTimestamp(input.deletedAt)) {
 				unchanged += 1;
@@ -155,13 +156,14 @@ function upsertKnowledgeSourceItems(inputs, nowMs = Date.now()) {
 				continue;
 			}
 			db.prepare(`INSERT INTO knowledge_source_items (
-          item_id, source_instance_id, external_id, item_type, author_role,
+          item_id, source_instance_id, collection_scope, external_id, item_type, author_role,
           occurred_at, source_updated_at, content_hash, normalized_text,
           payload_ref, metadata_json, sensitivity, retention_class,
           synthesis_pipeline, synthesis_status, deleted_at, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT(source_instance_id, external_id) DO UPDATE SET
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(source_instance_id, collection_scope, external_id) DO UPDATE SET
           item_type = excluded.item_type,
+          collection_scope = excluded.collection_scope,
           author_role = excluded.author_role,
           occurred_at = excluded.occurred_at,
           source_updated_at = excluded.source_updated_at,
@@ -178,7 +180,7 @@ function upsertKnowledgeSourceItems(inputs, nowMs = Date.now()) {
           synthesis_claimed_by = NULL,
           synthesis_error = NULL,
           deleted_at = excluded.deleted_at,
-          updated_at = excluded.updated_at`).run(id, input.sourceInstanceId, input.externalId, input.itemType, input.authorRole ?? null, parseTimestamp(input.occurredAt), parseTimestamp(input.sourceUpdatedAt), input.contentHash, input.normalizedText ?? null, input.payloadRef ?? null, JSON.stringify(input.metadata ?? {}), input.sensitivity ?? "normal", input.retentionClass ?? "bounded", input.synthesisPipeline ?? "user_understanding", input.synthesisStatus ?? "pending", parseTimestamp(input.deletedAt), existing?.created_at ?? nowMs, nowMs);
+          updated_at = excluded.updated_at`).run(id, input.sourceInstanceId, input.collectionScope, input.externalId, input.itemType, input.authorRole ?? null, parseTimestamp(input.occurredAt), parseTimestamp(input.sourceUpdatedAt), input.contentHash, input.normalizedText ?? null, input.payloadRef ?? null, JSON.stringify(input.metadata ?? {}), input.sensitivity ?? "normal", input.retentionClass ?? "bounded", input.synthesisPipeline ?? "user_understanding", input.synthesisStatus ?? "pending", parseTimestamp(input.deletedAt), existing?.created_at ?? nowMs, nowMs);
 			const row = db.prepare(`SELECT * FROM knowledge_source_items WHERE item_id = ?`).get(id);
 			items.push(sourceItemFromRow(row));
 			const changeKind = input.deletedAt ? "deleted" : existing ? "modified" : "added";
@@ -238,6 +240,10 @@ function listKnowledgeSourceItems(options = {}) {
 		where.push("source_instance_id = ?");
 		params.push(options.sourceInstanceId);
 	}
+	if (options.collectionScope) {
+		where.push("collection_scope = ?");
+		params.push(options.collectionScope);
+	}
 	if (options.itemType) {
 		where.push("item_type = ?");
 		params.push(options.itemType);
@@ -254,6 +260,11 @@ function listKnowledgeSourceItems(options = {}) {
        ORDER BY COALESCE(source_updated_at, occurred_at, updated_at) DESC
        LIMIT ? OFFSET ?`).all(...params, limit, offset).map(sourceItemFromRow);
 }
+function pruneBoundedKnowledgeSourceItems(sourceInstanceId, olderThanMs) {
+	return runSqliteWriteTransaction((db) => Number(db.prepare(`DELETE FROM knowledge_source_items
+     WHERE source_instance_id = ? AND retention_class = 'bounded'
+       AND COALESCE(source_updated_at, occurred_at, updated_at) < ?`).run(sourceInstanceId, olderThanMs).changes));
+}
 function setKnowledgeSourceItemSynthesisStatus(itemIds, status, nowMs = Date.now()) {
 	if (itemIds.length === 0) return 0;
 	return runSqliteWriteTransaction((db) => {
@@ -350,4 +361,4 @@ function listMemoryEvidence(recordId) {
 	}));
 }
 //#endregion
-export { attachMemoryEvidence, claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, deleteMemoryEvidenceForRecord, finishKnowledgeSyncRun, getKnowledgeConsumerWatermark, getKnowledgeSourceCursor, getKnowledgeSourceItem, listKnowledgeSourceChanges, listKnowledgeSourceItems, listKnowledgeSyncRuns, listMemoryEvidence, setKnowledgeConsumerWatermark, setKnowledgeSourceCursor, setKnowledgeSourceItemSynthesisStatus, startKnowledgeSyncRun, upsertKnowledgeSourceItems };
+export { attachMemoryEvidence, claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, deleteMemoryEvidenceForRecord, finishKnowledgeSyncRun, getKnowledgeConsumerWatermark, getKnowledgeSourceCursor, getKnowledgeSourceItem, listKnowledgeSourceChanges, listKnowledgeSourceItems, listKnowledgeSyncRuns, listMemoryEvidence, pruneBoundedKnowledgeSourceItems, setKnowledgeConsumerWatermark, setKnowledgeSourceCursor, setKnowledgeSourceItemSynthesisStatus, startKnowledgeSyncRun, upsertKnowledgeSourceItems };

package/dist/src/storage/sqlite/migrations/062_connector_learning_jobs.sql

@@ -0,0 +1,27 @@
+CREATE TABLE connector_learning_jobs (
+  job_id               TEXT PRIMARY KEY,
+  idempotency_key      TEXT NOT NULL UNIQUE,
+  connector_id         TEXT NOT NULL,
+  connection_id        TEXT NOT NULL,
+  source_instance_id   TEXT NOT NULL,
+  agent_id              TEXT NOT NULL,
+  mode                  TEXT NOT NULL CHECK(mode IN ('bootstrap', 'incremental')),
+  status                TEXT NOT NULL CHECK(status IN ('queued', 'running', 'completed', 'failed', 'paused')),
+  phase                 TEXT NOT NULL CHECK(phase IN ('queued', 'fetching', 'indexing', 'deriving', 'completed')),
+  items_discovered      INTEGER NOT NULL DEFAULT 0,
+  items_indexed         INTEGER NOT NULL DEFAULT 0,
+  candidates_created    INTEGER NOT NULL DEFAULT 0,
+  attempt_count         INTEGER NOT NULL DEFAULT 0,
+  error                 TEXT,
+  next_run_at           INTEGER,
+  started_at            INTEGER,
+  finished_at           INTEGER,
+  created_at            INTEGER NOT NULL,
+  updated_at            INTEGER NOT NULL,
+  FOREIGN KEY(connection_id) REFERENCES connector_connections(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_connector_learning_jobs_due
+  ON connector_learning_jobs(status, next_run_at, created_at);
+CREATE INDEX idx_connector_learning_jobs_source
+  ON connector_learning_jobs(source_instance_id, created_at DESC);

package/dist/src/storage/sqlite/migrations/063_knowledge_collection_scopes.sql

@@ -0,0 +1,14 @@
+ALTER TABLE knowledge_source_items ADD COLUMN collection_scope TEXT NOT NULL DEFAULT 'primary';
+
+DROP TABLE knowledge_source_state;
+
+CREATE TABLE knowledge_collection_state (
+  source_instance_id TEXT NOT NULL,
+  collection_scope   TEXT NOT NULL,
+  cursor             TEXT,
+  updated_at         INTEGER NOT NULL,
+  PRIMARY KEY(source_instance_id, collection_scope)
+);
+
+CREATE INDEX idx_knowledge_source_items_collection
+  ON knowledge_source_items(source_instance_id, collection_scope, updated_at DESC);

package/dist/src/storage/sqlite/migrations/064_user_claims.sql

@@ -0,0 +1,60 @@
+CREATE TABLE user_entities (
+  entity_id        TEXT PRIMARY KEY,
+  entity_type      TEXT NOT NULL CHECK(entity_type IN ('person', 'project', 'organization')),
+  canonical_label TEXT NOT NULL,
+  created_at       INTEGER NOT NULL,
+  updated_at       INTEGER NOT NULL
+);
+
+CREATE TABLE user_entity_handles (
+  entity_id        TEXT NOT NULL,
+  handle_type      TEXT NOT NULL CHECK(handle_type IN ('email', 'provider_user', 'display_name')),
+  normalized_value TEXT NOT NULL,
+  source_scope     TEXT NOT NULL,
+  verified         INTEGER NOT NULL CHECK(verified IN (0, 1)),
+  created_at       INTEGER NOT NULL,
+  PRIMARY KEY(handle_type, normalized_value, source_scope),
+  FOREIGN KEY(entity_id) REFERENCES user_entities(entity_id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_user_entity_handles_entity ON user_entity_handles(entity_id);
+
+CREATE TABLE user_claims (
+  claim_id                    TEXT PRIMARY KEY,
+  agent_id                    TEXT NOT NULL,
+  claim_class                 TEXT NOT NULL CHECK(claim_class IN ('relationship', 'project', 'routine')),
+  claim_key                   TEXT NOT NULL,
+  subject_entity_id           TEXT,
+  value_json                  TEXT NOT NULL,
+  state                       TEXT NOT NULL CHECK(state IN ('provisional', 'active', 'rejected', 'stale')),
+  user_state                  TEXT NOT NULL CHECK(user_state IN ('auto', 'confirmed', 'rejected')),
+  confidence                  REAL NOT NULL,
+  independent_evidence_count INTEGER NOT NULL,
+  active_day_count            INTEGER NOT NULL,
+  first_observed_at           INTEGER NOT NULL,
+  last_reinforced_at          INTEGER NOT NULL,
+  memory_record_id            TEXT,
+  created_at                  INTEGER NOT NULL,
+  updated_at                  INTEGER NOT NULL,
+  UNIQUE(agent_id, claim_class, claim_key),
+  FOREIGN KEY(subject_entity_id) REFERENCES user_entities(entity_id) ON DELETE SET NULL,
+  FOREIGN KEY(memory_record_id) REFERENCES memory_records(record_id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_user_claims_agent_state
+  ON user_claims(agent_id, state, confidence DESC, last_reinforced_at DESC);
+
+CREATE TABLE user_claim_evidence (
+  claim_id          TEXT NOT NULL,
+  logical_event_key TEXT NOT NULL,
+  source_item_id    TEXT NOT NULL,
+  source_instance_id TEXT NOT NULL,
+  relation          TEXT NOT NULL CHECK(relation IN ('supports', 'contradicts')),
+  observed_at       INTEGER NOT NULL,
+  created_at        INTEGER NOT NULL,
+  PRIMARY KEY(claim_id, logical_event_key),
+  FOREIGN KEY(claim_id) REFERENCES user_claims(claim_id) ON DELETE CASCADE,
+  FOREIGN KEY(source_item_id) REFERENCES knowledge_source_items(item_id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_user_claim_evidence_source ON user_claim_evidence(source_item_id);

package/dist/src/storage/sqlite/migrations/065_knowledge_item_scope_identity.sql

@@ -0,0 +1,116 @@
+CREATE TABLE memory_evidence_backup AS SELECT * FROM memory_evidence;
+CREATE TABLE knowledge_source_changes_backup AS SELECT * FROM knowledge_source_changes;
+CREATE TABLE user_claim_evidence_backup AS SELECT * FROM user_claim_evidence;
+
+DROP TABLE memory_evidence;
+DROP TABLE knowledge_source_changes;
+DROP TABLE user_claim_evidence;
+
+CREATE TABLE knowledge_source_items_v65 (
+  item_id              TEXT PRIMARY KEY,
+  source_instance_id   TEXT NOT NULL,
+  collection_scope     TEXT NOT NULL,
+  external_id          TEXT NOT NULL,
+  item_type            TEXT NOT NULL,
+  author_role          TEXT,
+  occurred_at          INTEGER,
+  source_updated_at    INTEGER,
+  content_hash         TEXT NOT NULL,
+  normalized_text      TEXT,
+  payload_ref          TEXT,
+  metadata_json        TEXT NOT NULL DEFAULT '{}',
+  sensitivity          TEXT NOT NULL DEFAULT 'normal',
+  retention_class      TEXT NOT NULL DEFAULT 'bounded',
+  synthesis_status     TEXT NOT NULL DEFAULT 'pending',
+  synthesis_pipeline   TEXT NOT NULL DEFAULT 'user_understanding'
+    CHECK(synthesis_pipeline IN ('user_understanding', 'connected_knowledge')),
+  synthesis_attempts   INTEGER NOT NULL DEFAULT 0,
+  synthesis_claimed_at INTEGER,
+  synthesis_claimed_by TEXT,
+  synthesis_error      TEXT,
+  deleted_at           INTEGER,
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL,
+  UNIQUE(source_instance_id, collection_scope, external_id)
+);
+
+INSERT INTO knowledge_source_items_v65 (
+  item_id, source_instance_id, collection_scope, external_id, item_type, author_role,
+  occurred_at, source_updated_at, content_hash, normalized_text, payload_ref, metadata_json,
+  sensitivity, retention_class, synthesis_status, synthesis_pipeline, synthesis_attempts,
+  synthesis_claimed_at, synthesis_claimed_by, synthesis_error, deleted_at, created_at, updated_at
+)
+SELECT
+  item_id, source_instance_id, collection_scope, external_id, item_type, author_role,
+  occurred_at, source_updated_at, content_hash, normalized_text, payload_ref, metadata_json,
+  sensitivity, retention_class, synthesis_status, synthesis_pipeline, synthesis_attempts,
+  synthesis_claimed_at, synthesis_claimed_by, synthesis_error, deleted_at, created_at, updated_at
+FROM knowledge_source_items;
+
+DROP TABLE knowledge_source_items;
+ALTER TABLE knowledge_source_items_v65 RENAME TO knowledge_source_items;
+
+CREATE INDEX idx_knowledge_source_items_source_updated
+  ON knowledge_source_items(source_instance_id, updated_at DESC);
+CREATE INDEX idx_knowledge_source_items_synthesis
+  ON knowledge_source_items(synthesis_status, updated_at);
+CREATE INDEX idx_knowledge_source_items_hash
+  ON knowledge_source_items(content_hash);
+CREATE INDEX idx_knowledge_source_items_synthesis_lease
+  ON knowledge_source_items(synthesis_pipeline, synthesis_status, synthesis_claimed_at, updated_at);
+CREATE INDEX idx_knowledge_source_items_collection
+  ON knowledge_source_items(source_instance_id, collection_scope, updated_at DESC);
+
+CREATE TABLE memory_evidence (
+  evidence_id       TEXT PRIMARY KEY,
+  record_id         TEXT NOT NULL,
+  source_item_id    TEXT,
+  relation          TEXT NOT NULL,
+  excerpt           TEXT,
+  confidence        REAL,
+  observed_at       INTEGER,
+  created_at        INTEGER NOT NULL,
+  FOREIGN KEY(record_id) REFERENCES memory_records(record_id) ON DELETE CASCADE,
+  FOREIGN KEY(source_item_id) REFERENCES knowledge_source_items(item_id) ON DELETE SET NULL
+);
+INSERT INTO memory_evidence SELECT * FROM memory_evidence_backup;
+DROP TABLE memory_evidence_backup;
+CREATE INDEX idx_memory_evidence_record ON memory_evidence(record_id, created_at DESC);
+CREATE INDEX idx_memory_evidence_source_item ON memory_evidence(source_item_id);
+CREATE UNIQUE INDEX idx_memory_evidence_record_source_relation
+  ON memory_evidence(record_id, source_item_id, relation)
+  WHERE source_item_id IS NOT NULL;
+
+CREATE TABLE knowledge_source_changes (
+  sequence            INTEGER PRIMARY KEY AUTOINCREMENT,
+  change_id           TEXT NOT NULL UNIQUE,
+  source_instance_id  TEXT NOT NULL,
+  source_item_id      TEXT NOT NULL,
+  change_kind         TEXT NOT NULL CHECK(change_kind IN ('added', 'modified', 'deleted')),
+  old_hash            TEXT,
+  new_hash            TEXT,
+  changed_at          INTEGER NOT NULL,
+  FOREIGN KEY(source_item_id) REFERENCES knowledge_source_items(item_id) ON DELETE CASCADE
+);
+INSERT INTO knowledge_source_changes SELECT * FROM knowledge_source_changes_backup;
+DROP TABLE knowledge_source_changes_backup;
+CREATE INDEX idx_knowledge_source_changes_source_sequence
+  ON knowledge_source_changes(source_instance_id, sequence);
+CREATE INDEX idx_knowledge_source_changes_changed_at
+  ON knowledge_source_changes(changed_at DESC);
+
+CREATE TABLE user_claim_evidence (
+  claim_id           TEXT NOT NULL,
+  logical_event_key  TEXT NOT NULL,
+  source_item_id     TEXT NOT NULL,
+  source_instance_id TEXT NOT NULL,
+  relation           TEXT NOT NULL CHECK(relation IN ('supports', 'contradicts')),
+  observed_at        INTEGER NOT NULL,
+  created_at         INTEGER NOT NULL,
+  PRIMARY KEY(claim_id, logical_event_key),
+  FOREIGN KEY(claim_id) REFERENCES user_claims(claim_id) ON DELETE CASCADE,
+  FOREIGN KEY(source_item_id) REFERENCES knowledge_source_items(item_id) ON DELETE CASCADE
+);
+INSERT INTO user_claim_evidence SELECT * FROM user_claim_evidence_backup;
+DROP TABLE user_claim_evidence_backup;
+CREATE INDEX idx_user_claim_evidence_source ON user_claim_evidence(source_item_id);

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 = 61;
+export declare const XOPC_DB_SCHEMA_VERSION = 65;
 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 = 61;
+const XOPC_DB_SCHEMA_VERSION = 65;
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 function resolveMigrationsDir(override) {
 	if (override) return override;
@@ -46,7 +46,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 ?? 61;
+	const targetVersion = options.targetVersion ?? 65;
 	let currentVersion = readSchemaVersion(db);
 	if (currentVersion > targetVersion) throw new DatabaseSchemaTooNewError(currentVersion, targetVersion);
 	if (currentVersion >= targetVersion) return currentVersion;
@@ -62,7 +62,7 @@ function applyPendingMigrations(db, options = {}) {
 }
 /** Inspect schema version without mutating the database. */
 function inspectSchemaMigrationStatus(db, options = {}) {
-	const appVersion = options.targetVersion ?? 61;
+	const appVersion = options.targetVersion ?? 65;
 	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 = 61;
+export const XOPC_DB_SCHEMA_VERSION = 65;
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 

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

@@ -31,7 +31,7 @@ function ensureXopcDatabaseSchema(db) {
 		bootstrapFreshDatabase(db);
 		currentVersion = 11;
 	}
-	applyPendingMigrations(db, { targetVersion: 61 });
+	applyPendingMigrations(db, { targetVersion: 65 });
 }
 //#endregion
 export { SCHEMA_META_SCHEMA_VERSION_KEY, XOPC_DB_BASELINE_SCHEMA_VERSION, XOPC_DB_SCHEMA_VERSION, ensureSchemaMetaTable, ensureXopcDatabaseSchema, readSchemaVersion, readSchemaVersionForTest, setSchemaVersion };

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

@@ -0,0 +1,101 @@
+export type UserEntityType = 'person' | 'project' | 'organization';
+export type UserEntityHandleType = 'email' | 'provider_user' | 'display_name';
+export type UserClaimClass = 'relationship' | 'project' | 'routine';
+export type UserClaimState = 'provisional' | 'active' | 'rejected' | 'stale';
+export type UserClaimUserState = 'auto' | 'confirmed' | 'rejected';
+export type UserEntity = {
+    id: string;
+    type: UserEntityType;
+    canonicalLabel: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type UserClaim = {
+    id: string;
+    agentId: string;
+    class: UserClaimClass;
+    key: string;
+    subjectEntityId?: string;
+    value: Record<string, unknown>;
+    state: UserClaimState;
+    userState: UserClaimUserState;
+    confidence: number;
+    independentEvidenceCount: number;
+    activeDayCount: number;
+    firstObservedAt: string;
+    lastReinforcedAt: string;
+    memoryRecordId?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function resolveUserEntity(input: {
+    type: UserEntityType;
+    canonicalLabel: string;
+    handles: Array<{
+        type: UserEntityHandleType;
+        value: string;
+        sourceScope: string;
+        verified: boolean;
+    }>;
+    nowMs?: number;
+}): UserEntity;
+export declare function reinforceUserClaim(input: {
+    agentId: string;
+    class: UserClaimClass;
+    key: string;
+    subjectEntityId?: string;
+    value: Record<string, unknown>;
+    evidence: Array<{
+        logicalEventKey: string;
+        sourceItemId: string;
+        sourceInstanceId: string;
+        relation: 'supports' | 'contradicts';
+        observedAt: string;
+    }>;
+    nowMs?: number;
+}): UserClaim;
+export declare function removeUserClaimEvidenceForSource(sourceInstanceId: string): {
+    deletedClaimCount: number;
+    deletedMemoryRecordIds: string[];
+    retainedClaims: Array<{
+        memoryRecordId: string;
+        state: UserClaimState;
+    }>;
+};
+export declare function setUserClaimDecision(claimId: string, userState: Exclude<UserClaimUserState, 'auto'>): UserClaim | undefined;
+export declare function linkUserClaimMemoryRecord(claimId: string, memoryRecordId: string): void;
+export declare function getUserClaim(claimId: string): UserClaim | undefined;
+export declare function listUserClaims(options?: {
+    agentId?: string;
+    state?: UserClaimState;
+    limit?: number;
+}): UserClaim[];
+export declare function listUserClaimEvidence(claimId: string): Array<{
+    logicalEventKey: string;
+    sourceItemId: string;
+    sourceInstanceId: string;
+    relation: string;
+    observedAt: string;
+}>;
+export declare function listUserPeopleGraphRows(): {
+    people: Array<UserEntity & {
+        handles: Array<{
+            type: UserEntityHandleType;
+            value: string;
+        }>;
+    }>;
+    edges: Array<{
+        entityId: string;
+        sourceInstanceId: string;
+        mentionCount: number;
+        lastObservedAt: string;
+    }>;
+    evidenceCount: number;
+};
+export declare function listUserClaimStatsBySource(): Record<string, {
+    evidenceCount: number;
+    provisionalClaims: number;
+    activeClaims: number;
+    resolvedEntities: number;
+    lastEvidenceAt?: string;
+}>;