@xopcai/xopc 0.0.228 → 0.0.230

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

@@ -4,6 +4,11 @@ import { retrievalQueryAuditValue } from "../../retrieval/audit.js";
 import { buildFts5SearchQuery, fts5RankToScore } from "./fts.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/storage/sqlite/user-context-repository.ts
+function insertUnderstandingStatusEvent(db, input) {
+	db.prepare(`INSERT INTO understanding_status_events (
+    event_id, understanding_id, from_status, to_status, actor_type, source, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), input.understandingId, input.fromStatus ?? null, input.toStatus, input.actorType, input.source, input.createdAt);
+}
 function evidenceFromRow(row) {
 	return {
 		id: row.evidence_id,
@@ -144,6 +149,13 @@ function createUnderstanding(input, principalId = USER_CONTEXT_PRINCIPAL_ID) {
       version_id, understanding_id, statement, payload_json, created_by, change_reason, created_at
     ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(versionId, id, input.statement.trim(), JSON.stringify(input.payload ?? {}), input.createdBy, input.changeReason, now);
 		db.prepare("INSERT INTO user_understanding_fts (statement, understanding_id, version_id) VALUES (?, ?, ?)").run(input.statement.trim(), id, versionId);
+		insertUnderstandingStatusEvent(db, {
+			understandingId: id,
+			toStatus: input.status,
+			actorType: input.createdBy === "user" ? "user" : "runtime",
+			source: `create:${input.changeReason}`,
+			createdAt: now
+		});
 	});
 	return getUnderstanding(id);
 }
@@ -197,17 +209,29 @@ function reviseUnderstanding(id, statement, options) {
 	});
 	return getUnderstanding(id);
 }
-function setUnderstandingStatus(id, status, confirmation) {
+function setUnderstandingStatus(id, status, options) {
+	const current = getUnderstanding(id);
+	if (!current) throw new Error(`User understanding not found: ${id}`);
 	const now = Date.now();
-	getSqliteDatabase().prepare(`UPDATE user_understandings
-    SET status = ?,
-        explicitness = COALESCE(?, explicitness),
-        confidence = COALESCE(?, confidence),
-        updated_at = ?
-    WHERE understanding_id = ?`).run(status, confirmation?.explicitness ?? null, confirmation?.confidence ?? null, now, id);
-	const assertionStatus = status === "active" ? "active" : status === "archived" ? "closed" : status === "rejected" ? "rejected" : "candidate";
-	getSqliteDatabase().prepare(`UPDATE context_temporal_assertions
-    SET status = ?, updated_at = ? WHERE object_type = 'understanding' AND object_id = ?`).run(assertionStatus, now, id);
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE user_understandings
+      SET status = ?,
+          explicitness = COALESCE(?, explicitness),
+          confidence = COALESCE(?, confidence),
+          updated_at = ?
+      WHERE understanding_id = ?`).run(status, options?.explicitness ?? null, options?.confidence ?? null, now, id);
+		const assertionStatus = status === "active" ? "active" : status === "archived" ? "closed" : status === "rejected" ? "rejected" : "candidate";
+		db.prepare(`UPDATE context_temporal_assertions
+      SET status = ?, updated_at = ? WHERE object_type = 'understanding' AND object_id = ?`).run(assertionStatus, now, id);
+		if (current.status !== status) insertUnderstandingStatusEvent(db, {
+			understandingId: id,
+			fromStatus: current.status,
+			toStatus: status,
+			actorType: options?.actorType ?? "runtime",
+			source: options?.source ?? "repository-status-change",
+			createdAt: now
+		});
+	});
 	const result = getUnderstanding(id);
 	if (!result) throw new Error(`User understanding not found: ${id}`);
 	return result;
@@ -219,12 +243,20 @@ function closeUnderstandingValidity(id, validTo = Date.now()) {
 	if (!result) throw new Error(`User understanding not found: ${id}`);
 	return result;
 }
-function rejectUnderstanding(id, reason) {
+function rejectUnderstanding(id, reason, actorType = "runtime") {
 	const current = getUnderstanding(id);
 	if (!current) throw new Error(`User understanding not found: ${id}`);
 	const now = Date.now();
 	runSqliteWriteTransaction((db) => {
 		db.prepare("UPDATE user_understandings SET status = 'rejected', updated_at = ? WHERE understanding_id = ?").run(now, id);
+		if (current.status !== "rejected") insertUnderstandingStatusEvent(db, {
+			understandingId: id,
+			fromStatus: current.status,
+			toStatus: "rejected",
+			actorType,
+			source: reason,
+			createdAt: now
+		});
 		db.prepare(`INSERT INTO context_suppressions (
       suppression_id, principal_id, canonical_key, scope_type, scope_id, reason, expires_at, created_at
     ) VALUES (?, ?, ?, ?, ?, ?, NULL, ?)
@@ -232,6 +264,18 @@ function rejectUnderstanding(id, reason) {
 	});
 	return getUnderstanding(id);
 }
+function listUnderstandingStatusEvents(id) {
+	return getSqliteDatabase().prepare(`SELECT * FROM understanding_status_events
+    WHERE understanding_id = ? ORDER BY created_at DESC, rowid DESC`).all(id).map((row) => ({
+		id: row.event_id,
+		understandingId: row.understanding_id,
+		...row.from_status ? { fromStatus: row.from_status } : {},
+		toStatus: row.to_status,
+		actorType: row.actor_type,
+		source: row.source,
+		createdAt: row.created_at
+	}));
+}
 function deleteUnderstanding(id) {
 	return runSqliteWriteTransaction((db) => {
 		db.prepare("DELETE FROM user_understanding_fts WHERE understanding_id = ?").run(id);
@@ -442,4 +486,4 @@ function decideContextConsent(id, decision) {
 	return Number(result.changes) > 0;
 }
 //#endregion
-export { closeUnderstandingValidity, consumeContextConsent, createCollaborationRule, createContextEvidence, createUnderstanding, decideContextConsent, deleteCollaborationRule, deleteUnderstanding, ensureContextConsent, getCollaborationRule, getTurnPersonalization, getUnderstanding, getUserProfile, hasContextConsent, isUnderstandingSuppressed, linkUnderstandingEvidence, listCollaborationRules, listUnderstandingEvidence, listUnderstandings, recordContextFeedback, recordContextRun, rejectUnderstanding, reviseCollaborationRule, reviseUnderstanding, searchActiveUnderstandings, setCollaborationRuleStatus, setUnderstandingStatus, updateUserProfile };
+export { closeUnderstandingValidity, consumeContextConsent, createCollaborationRule, createContextEvidence, createUnderstanding, decideContextConsent, deleteCollaborationRule, deleteUnderstanding, ensureContextConsent, getCollaborationRule, getTurnPersonalization, getUnderstanding, getUserProfile, hasContextConsent, isUnderstandingSuppressed, linkUnderstandingEvidence, listCollaborationRules, listUnderstandingEvidence, listUnderstandingStatusEvents, listUnderstandings, recordContextFeedback, recordContextRun, rejectUnderstanding, reviseCollaborationRule, reviseUnderstanding, searchActiveUnderstandings, setCollaborationRuleStatus, setUnderstandingStatus, updateUserProfile };

package/dist/src/user-context/config.d.ts

@@ -96,6 +96,10 @@ export declare const UserMemoryConfigSchema: z.ZodDefault<z.ZodObject<{
 }, z.core.$strict>>;
 export declare const UserUnderstandingConfigSchema: z.ZodDefault<z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
+    processingPolicy: z.ZodDefault<z.ZodEnum<{
+        local_only: "local_only";
+        remote_allowed: "remote_allowed";
+    }>>;
     adaptiveCadence: z.ZodDefault<z.ZodBoolean>;
     reviewIntervalTurns: z.ZodDefault<z.ZodNumber>;
     maxHistoryMessages: z.ZodDefault<z.ZodNumber>;
@@ -204,6 +208,10 @@ export declare const UserContextConfigSchema: z.ZodDefault<z.ZodObject<{
     }, z.core.$strict>>;
     understanding: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
+        processingPolicy: z.ZodDefault<z.ZodEnum<{
+            local_only: "local_only";
+            remote_allowed: "remote_allowed";
+        }>>;
         adaptiveCadence: z.ZodDefault<z.ZodBoolean>;
         reviewIntervalTurns: z.ZodDefault<z.ZodNumber>;
         maxHistoryMessages: z.ZodDefault<z.ZodNumber>;

package/dist/src/user-context/config.js

@@ -91,12 +91,14 @@ var init_config = __esmMin((() => {
 	});
 	UserUnderstandingConfigSchema = z.object({
 		enabled: z.boolean().default(true),
+		processingPolicy: z.enum(["local_only", "remote_allowed"]).default("remote_allowed"),
 		adaptiveCadence: z.boolean().default(true),
 		reviewIntervalTurns: z.number().int().min(1).max(1e3).default(10),
 		maxHistoryMessages: z.number().int().min(1).max(200).default(80),
 		maxDurationMs: z.number().int().min(1e3).max(6e5).default(12e4)
 	}).strict().default({
 		enabled: true,
+		processingPolicy: "remote_allowed",
 		adaptiveCadence: true,
 		reviewIntervalTurns: 10,
 		maxHistoryMessages: 80,
@@ -161,6 +163,7 @@ var init_config = __esmMin((() => {
 		},
 		understanding: {
 			enabled: true,
+			processingPolicy: "remote_allowed",
 			adaptiveCadence: true,
 			reviewIntervalTurns: 10,
 			maxHistoryMessages: 80,

package/dist/src/user-context/consolidation.js

@@ -97,7 +97,10 @@ async function runContextConsolidation(input) {
 			const evidenceCount = distinctEvidenceCount(understanding.id, "supports");
 			const contradictionCount = distinctEvidenceCount(understanding.id, "contradicts");
 			if (understanding.validTo != null && understanding.validTo <= now || understanding.expiresAt != null && understanding.expiresAt <= now) {
-				setUnderstandingStatus(understanding.id, "stale");
+				setUnderstandingStatus(understanding.id, "stale", {
+					actorType: "runtime",
+					source: "consolidation-expired"
+				});
 				recordContextConsolidationDecision({
 					runId: run.runId,
 					understandingId: understanding.id,
@@ -110,7 +113,10 @@ async function runContextConsolidation(input) {
 				continue;
 			}
 			if (contradictionCount > 0) {
-				setUnderstandingStatus(understanding.id, "needs_review");
+				setUnderstandingStatus(understanding.id, "needs_review", {
+					actorType: "runtime",
+					source: "consolidation-contradiction"
+				});
 				recordContextConsolidationDecision({
 					runId: run.runId,
 					understandingId: understanding.id,
@@ -123,7 +129,10 @@ async function runContextConsolidation(input) {
 				continue;
 			}
 			if (understanding.status === "active" && understanding.reviewAt != null && understanding.reviewAt <= now) {
-				setUnderstandingStatus(understanding.id, "needs_review");
+				setUnderstandingStatus(understanding.id, "needs_review", {
+					actorType: "runtime",
+					source: "consolidation-review-due"
+				});
 				recordContextConsolidationDecision({
 					runId: run.runId,
 					understandingId: understanding.id,
@@ -136,7 +145,10 @@ async function runContextConsolidation(input) {
 				continue;
 			}
 			if (understanding.status === "candidate" && evidenceCount >= resolved.minEvidenceSources) {
-				setUnderstandingStatus(understanding.id, "needs_review");
+				setUnderstandingStatus(understanding.id, "needs_review", {
+					actorType: "runtime",
+					source: "consolidation-evidence-threshold"
+				});
 				recordContextConsolidationDecision({
 					runId: run.runId,
 					understandingId: understanding.id,

package/dist/src/user-context/extraction/executor.d.ts

@@ -0,0 +1,22 @@
+import type { Config } from '../../config/schema.js';
+import type { MemoryManager } from '../../agent/memory/manager.js';
+import type { UnderstandingReviewResult } from '../../agent/memory/understanding/types.js';
+import { type ExtractorId } from './registry.js';
+import type { SemanticEvidence, SemanticUnderstandingInterpretation } from './semantic.js';
+export type UnderstandingEvidenceMessage = SemanticEvidence & {
+    createdAt: number;
+    message: unknown;
+};
+export declare function emptyUnderstandingReview(): UnderstandingReviewResult;
+export declare function executeUnderstandingInterpretation(params: {
+    interpretation: SemanticUnderstandingInterpretation;
+    evidence: UnderstandingEvidenceMessage[];
+    extractionRunId: string;
+    extractorId: ExtractorId;
+    sessionKey: string;
+    turnId?: string;
+    memoryManager: MemoryManager;
+    getConfig: () => Config | undefined;
+    reviewSource: 'turn' | 'background';
+    processingPolicy: 'local_only' | 'remote_allowed';
+}): Promise<UnderstandingReviewResult>;

package/dist/src/user-context/extraction/executor.js

@@ -0,0 +1,142 @@
+import { createContextEvidence, getTurnPersonalization, getUnderstanding, recordContextFeedback, rejectUnderstanding, setUnderstandingStatus } from "../../storage/sqlite/user-context-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import "../../storage/sqlite/index.js";
+import { extractionInputHash } from "./registry.js";
+//#region src/user-context/extraction/executor.ts
+function emptyUnderstandingReview() {
+	return {
+		proposed: 0,
+		created: 0,
+		deduplicated: 0,
+		rejected: 0,
+		createdRecords: [],
+		writeOutputs: []
+	};
+}
+function resolveWritePolicy(config) {
+	const memory = config?.userContext.memory;
+	if (!memory || memory.mode === "off" || memory.mode === "readOnly") return "deny";
+	return memory.writePolicy?.understanding ?? (memory.mode === "auto" ? "allow" : "confirm");
+}
+function recordTargetFeedback(turnId, targetIds, rating, reason) {
+	if (!turnId || targetIds.length === 0) return;
+	const personalization = getTurnPersonalization(turnId);
+	if (!personalization) return;
+	for (const objectId of targetIds) recordContextFeedback({
+		turnId,
+		runId: personalization.runId,
+		objectType: "understanding",
+		objectId,
+		rating,
+		reason
+	});
+}
+async function executeUnderstandingInterpretation(params) {
+	const { interpretation } = params;
+	const result = emptyUnderstandingReview();
+	const targets = interpretation.targetUnderstandingIds.flatMap((id) => {
+		const item = getUnderstanding(id);
+		return item ? [item] : [];
+	});
+	const targetIds = targets.map((item) => item.id);
+	const policy = resolveWritePolicy(params.getConfig());
+	if (interpretation.intent === "memory_forget") {
+		for (const target of targets) {
+			const rejected = rejectUnderstanding(target.id, "explicit user forget request", "user");
+			result.writeOutputs.push({
+				candidateKey: rejected.canonicalKey,
+				objectId: rejected.id,
+				versionId: rejected.versionId,
+				outcome: "rejected"
+			});
+		}
+		result.rejected += targets.length;
+		recordTargetFeedback(params.turnId, targetIds, "irrelevant", "explicit_user_forget_request");
+		return result;
+	}
+	if (interpretation.intent === "memory_confirm" && policy !== "deny") {
+		for (const target of targets) {
+			const confirmed = setUnderstandingStatus(target.id, "active", {
+				explicitness: "explicit",
+				confidence: 1,
+				actorType: "user",
+				source: "semantic-memory-confirmation"
+			});
+			result.createdRecords.push({
+				id: confirmed.id,
+				content: confirmed.statement,
+				kind: confirmed.kind,
+				status: confirmed.status
+			});
+			result.writeOutputs.push({
+				candidateKey: confirmed.canonicalKey,
+				objectId: confirmed.id,
+				versionId: confirmed.versionId,
+				outcome: "deduplicated"
+			});
+			result.deduplicated += 1;
+		}
+		recordTargetFeedback(params.turnId, targetIds, "helpful", "explicit_user_confirmation");
+	}
+	if (interpretation.intent === "memory_correct" && targets.length && interpretation.candidates.length === 0) {
+		for (const target of targets) setUnderstandingStatus(target.id, "needs_review", {
+			actorType: "user",
+			source: "semantic-memory-correction"
+		});
+		recordTargetFeedback(params.turnId, targetIds, "wrong", "explicit_user_correction_without_replacement");
+		return result;
+	}
+	if (interpretation.candidates.length === 0) return result;
+	if (policy === "deny") {
+		result.proposed = interpretation.candidates.length;
+		result.rejected = interpretation.candidates.length;
+		return result;
+	}
+	const evidenceByRef = new Map(params.evidence.map((entry) => [entry.ref, entry]));
+	const candidates = interpretation.candidates.map((candidate) => ({
+		...candidate,
+		explicitness: policy === "confirm" && candidate.explicitness === "explicit" ? "observed" : candidate.explicitness
+	}));
+	const evidenceIdsByRef = /* @__PURE__ */ new Map();
+	for (const ref of new Set(candidates.flatMap((candidate) => candidate.evidenceRefs))) {
+		const entry = evidenceByRef.get(ref);
+		if (!entry || entry.role !== "user") continue;
+		const evidence = createContextEvidence({
+			sourceType: "conversation",
+			sourceRef: `session:${params.sessionKey}:entry:${entry.ref}`,
+			sourceRunId: params.extractionRunId,
+			sessionId: params.sessionKey,
+			...params.turnId ? { turnId: params.turnId } : {},
+			messageId: entry.ref,
+			contentHash: extractionInputHash(JSON.stringify(entry.message)),
+			retentionPolicy: "derived_only",
+			processingPolicy: params.processingPolicy,
+			extractorId: params.extractorId,
+			extractorVersion: "1",
+			trustLevel: "owner",
+			observedAt: entry.createdAt
+		});
+		evidenceIdsByRef.set(ref, evidence.id);
+	}
+	const projectId = getSessionMetadata(params.sessionKey)?.projectId;
+	for (const candidate of candidates) {
+		const applied = await params.memoryManager.applyUnderstandingCandidates([candidate], {
+			sessionKey: params.sessionKey,
+			...projectId ? { projectId } : {},
+			evidenceIds: candidate.evidenceRefs.flatMap((ref) => evidenceIdsByRef.get(ref) ?? []),
+			reviewSource: params.reviewSource,
+			extractionRunId: params.extractionRunId,
+			...interpretation.intent === "memory_correct" ? { supersedesRecordIds: targetIds } : {}
+		});
+		result.proposed += applied.proposed;
+		result.created += applied.created;
+		result.deduplicated += applied.deduplicated;
+		result.rejected += applied.rejected;
+		result.createdRecords.push(...applied.createdRecords);
+		result.writeOutputs.push(...applied.writeOutputs ?? []);
+	}
+	if (interpretation.intent === "memory_correct" && result.created > 0) recordTargetFeedback(params.turnId, targetIds, "wrong", "explicit_user_correction_with_replacement");
+	return result;
+}
+//#endregion
+export { emptyUnderstandingReview, executeUnderstandingInterpretation };

package/dist/src/user-context/extraction/registry.d.ts

@@ -1,6 +1,6 @@
 import { type ContextExtractionRun } from '../../storage/sqlite/index.js';
 import type { UnderstandingKind } from '../domain.js';
-export type ExtractorId = 'explicit-command' | 'deterministic-signal' | 'transcript-synthesis' | 'connector-structural' | 'connector-semantic';
+export type ExtractorId = 'turn-semantics' | 'transcript-synthesis' | 'connector-semantic';
 export type ExtractorDefinition = {
     id: ExtractorId;
     version: string;

package/dist/src/user-context/extraction/registry.js

@@ -14,62 +14,33 @@ const UNDERSTANDING_KINDS = [
 	"derived_insight"
 ];
 const DEFINITIONS = {
-	"explicit-command": {
-		id: "explicit-command",
+	"turn-semantics": {
+		id: "turn-semantics",
 		version: "1",
 		inputKinds: ["conversation"],
 		requiredProcessingPolicy: "local_only",
 		authorityCeiling: "user_explicit",
 		candidateKinds: UNDERSTANDING_KINDS,
 		maxAutomaticStatus: "active",
-		timeoutMs: 500
-	},
-	"deterministic-signal": {
-		id: "deterministic-signal",
-		version: "1",
-		inputKinds: ["conversation", "task"],
-		requiredProcessingPolicy: "local_only",
-		authorityCeiling: "user_observed",
-		candidateKinds: UNDERSTANDING_KINDS,
-		maxAutomaticStatus: "candidate",
-		timeoutMs: 500
+		timeoutMs: 3e4
 	},
 	"transcript-synthesis": {
 		id: "transcript-synthesis",
 		version: "1",
 		inputKinds: ["conversation"],
-		requiredProcessingPolicy: "remote_allowed",
+		requiredProcessingPolicy: "local_only",
 		authorityCeiling: "system_inferred",
 		candidateKinds: UNDERSTANDING_KINDS,
 		maxAutomaticStatus: "candidate",
 		timeoutMs: 3e4
 	},
-	"connector-structural": {
-		id: "connector-structural",
-		version: "1",
-		inputKinds: ["connector"],
-		requiredProcessingPolicy: "local_only",
-		authorityCeiling: "external_untrusted",
-		candidateKinds: [
-			"project_context",
-			"current_state",
-			"routine"
-		],
-		maxAutomaticStatus: "candidate",
-		timeoutMs: 1e4
-	},
 	"connector-semantic": {
 		id: "connector-semantic",
 		version: "1",
 		inputKinds: ["connector", "file"],
 		requiredProcessingPolicy: "remote_allowed",
 		authorityCeiling: "external_untrusted",
-		candidateKinds: [
-			"preference",
-			"routine",
-			"current_state",
-			"project_context"
-		],
+		candidateKinds: ["preference", "routine"],
 		maxAutomaticStatus: "candidate",
 		timeoutMs: 3e4
 	}

package/dist/src/user-context/extraction/repair.js

@@ -39,7 +39,10 @@ function repairExtractedContext(filter) {
 				});
 				continue;
 			}
-			setUnderstandingStatus(output.objectId, "archived");
+			setUnderstandingStatus(output.objectId, "archived", {
+				actorType: "runtime",
+				source: "context-extraction-repair"
+			});
 		} else {
 			const focus = listUserFocuses().find((item) => item.id === output.objectId);
 			if (!focus) continue;

package/dist/src/user-context/extraction/semantic.d.ts

@@ -0,0 +1,18 @@
+import type { UnderstandingCandidate } from '../../agent/memory/understanding/types.js';
+export declare const UNDERSTANDING_INTENTS: readonly ["memory_create", "memory_query", "memory_confirm", "memory_correct", "memory_forget", "user_assertion", "task_request", "none"];
+export type UnderstandingIntent = typeof UNDERSTANDING_INTENTS[number];
+export type SemanticEvidence = {
+    ref: string;
+    role: 'user' | 'assistant';
+    text: string;
+};
+export type SemanticUnderstandingCandidate = UnderstandingCandidate & {
+    evidenceRefs: string[];
+};
+export type SemanticUnderstandingInterpretation = {
+    intent: UnderstandingIntent;
+    candidates: SemanticUnderstandingCandidate[];
+    targetUnderstandingIds: string[];
+    abstentionReason?: string;
+};
+export declare function parseSemanticUnderstanding(raw: string, evidence: SemanticEvidence[], allowedTargetIds?: string[]): SemanticUnderstandingInterpretation | null;

package/dist/src/user-context/extraction/semantic.js

@@ -0,0 +1,148 @@
+import { UNDERSTANDING_KINDS } from "../domain.js";
+import { isDurableUnderstandingCandidate } from "../understandingQuality.js";
+import { inferMemorySensitivity } from "../../agent/memory/sensitivity.js";
+import { z } from "zod";
+//#region src/user-context/extraction/semantic.ts
+const UNDERSTANDING_INTENTS = [
+	"memory_create",
+	"memory_query",
+	"memory_confirm",
+	"memory_correct",
+	"memory_forget",
+	"user_assertion",
+	"task_request",
+	"none"
+];
+const EvidenceSchema = z.object({
+	ref: z.string().min(1),
+	quote: z.string().min(1)
+}).strict();
+const CandidateSchema = z.object({
+	factKey: z.string().regex(/^[a-z0-9][a-z0-9:-]{2,119}$/),
+	statement: z.string().min(4).max(600),
+	kind: z.enum(UNDERSTANDING_KINDS),
+	explicitness: z.enum([
+		"explicit",
+		"observed",
+		"inferred"
+	]),
+	durability: z.enum([
+		"ephemeral",
+		"durable",
+		"recurring"
+	]),
+	scopeHint: z.enum([
+		"global",
+		"workspace",
+		"project",
+		"session"
+	]),
+	confidence: z.number().min(0).max(1),
+	importance: z.number().min(0).max(1),
+	sensitivity: z.enum([
+		"normal",
+		"personal",
+		"secret",
+		"regulated"
+	]).optional(),
+	disclosurePolicy: z.enum([
+		"silent",
+		"referenceable",
+		"ask_before_reference"
+	]).optional(),
+	evidence: z.array(EvidenceSchema).min(1).max(8),
+	selfContained: z.boolean(),
+	unresolvedReferences: z.array(z.string()).max(8)
+}).strict();
+const InterpretationSchema = z.object({
+	intent: z.enum(UNDERSTANDING_INTENTS),
+	candidates: z.array(CandidateSchema).max(8),
+	targetUnderstandingIds: z.array(z.string().min(1)).max(8),
+	abstentionReason: z.string().max(500).optional()
+}).strict();
+const CANDIDATE_INTENTS = new Set([
+	"memory_create",
+	"memory_confirm",
+	"memory_correct",
+	"user_assertion"
+]);
+const QUESTION_END = /[?？]\s*$/u;
+function extractJson(raw) {
+	const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(raw)?.[1];
+	const start = raw.indexOf("{");
+	const end = raw.lastIndexOf("}");
+	const candidate = fenced ?? (start >= 0 && end > start ? raw.slice(start, end + 1) : raw);
+	return JSON.parse(candidate);
+}
+function comparableText(value) {
+	return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/g, " ").trim();
+}
+function quoteIsGrounded(quote, source) {
+	return comparableText(source).includes(comparableText(quote));
+}
+function bigramSimilarity(left, right) {
+	const pairs = (value) => {
+		const normalized = comparableText(value).replace(/[^\p{L}\p{N}]/gu, "");
+		const output = /* @__PURE__ */ new Set();
+		for (let index = 0; index < normalized.length - 1; index += 1) output.add(normalized.slice(index, index + 2));
+		return output;
+	};
+	const a = pairs(left);
+	const b = pairs(right);
+	if (!a.size || !b.size) return 0;
+	let overlap = 0;
+	for (const pair of a) if (b.has(pair)) overlap += 1;
+	return 2 * overlap / (a.size + b.size);
+}
+function effectiveExplicitness(intent, declared) {
+	if (intent === "memory_create" || intent === "memory_correct" || intent === "memory_confirm") return declared;
+	return declared === "explicit" ? "observed" : declared;
+}
+function parseSemanticUnderstanding(raw, evidence, allowedTargetIds = []) {
+	let parsed;
+	try {
+		const result = InterpretationSchema.safeParse(extractJson(raw));
+		if (!result.success) return null;
+		parsed = result.data;
+	} catch {
+		return null;
+	}
+	const evidenceByRef = new Map(evidence.map((item) => [item.ref, item]));
+	const allowedTargets = new Set(allowedTargetIds);
+	const candidates = [];
+	if (CANDIDATE_INTENTS.has(parsed.intent)) for (const item of parsed.candidates) {
+		if (!item.selfContained || item.unresolvedReferences.length > 0) continue;
+		if (QUESTION_END.test(item.statement)) continue;
+		if (!isDurableUnderstandingCandidate(item.kind, item.statement)) continue;
+		if (!item.evidence.every((claim) => {
+			const source = evidenceByRef.get(claim.ref);
+			return source?.role === "user" && quoteIsGrounded(claim.quote, source.text);
+		})) continue;
+		if (item.explicitness === "explicit") {
+			const quotedText = item.evidence.map((claim) => claim.quote).join(" ");
+			if (bigramSimilarity(item.statement, quotedText) < .45) continue;
+		}
+		const evidenceRefs = [...new Set(item.evidence.map((claim) => claim.ref))];
+		candidates.push({
+			kind: item.kind,
+			content: item.statement.trim(),
+			canonicalKey: `understanding:${item.kind}:${item.factKey}`,
+			confidence: item.confidence,
+			importance: item.importance,
+			explicitness: effectiveExplicitness(parsed.intent, item.explicitness),
+			durability: item.durability,
+			sensitivity: item.sensitivity ?? inferMemorySensitivity(item.statement),
+			disclosurePolicy: item.disclosurePolicy ?? "referenceable",
+			payload: { scopeHint: item.scopeHint },
+			evidenceRefs
+		});
+	}
+	return {
+		intent: parsed.intent,
+		candidates,
+		targetUnderstandingIds: [...new Set(parsed.targetUnderstandingIds.filter((id) => allowedTargets.has(id)))],
+		...parsed.abstentionReason ? { abstentionReason: parsed.abstentionReason } : {}
+	};
+}
+//#endregion
+export { UNDERSTANDING_INTENTS, parseSemanticUnderstanding };

package/dist/src/user-context/understandingQuality.js

@@ -2,6 +2,8 @@
 const INCOMPLETE_PREFIX = /^(?:and\b|also\b|then\b|plus\b|as\s+well\s+as\b|which\b|that\b|并且|并将|以及|然后|同时|另外|还有|而且|或者|的事项|事项[，,、：:]?)/i;
 const DEFERRED_OR_NEGATED_ACTION = /(?:not\s+now|no\s+need\s+to|do\s+not\s+(?:start|proceed)|don't\s+(?:start|proceed)|later\s+maybe|暂时不用|暂时不(?:用|要|开始)?|先不用|无需|不用开始|不要推进|不需要推进)/i;
 const ONE_OFF_ACTION_PREFIX = /^(?:please\s+|update\b|investigate\b|summari[sz]e\b|fix\b|write\b|add\b|record\b|track\b)|^(?:请|帮我|更新|调查|汇总|整理|修复|写入|加入|记录|跟进)/i;
+const DURABLE_MARKER = /(?:从现在起|今后|以后|长期|每次|每回|始终|一直|默认|下次|教训|原则|习惯|from now on|going forward|long[- ]term|every time|always|by default|next time|lesson|principle|habit)/i;
+const TURN_EXECUTION_INSTRUCTION = /(?:不要再问|别再问|直接执行|立即执行|当前任务|这次|本次|现在就|do not ask|don't ask|just do it|execute directly|proceed now|this task|this time)/i;
 function meaningfulLength(content) {
 	return content.normalize("NFKC").replace(/[\p{P}\p{S}\s]/gu, "").length;
 }
@@ -15,6 +17,8 @@ function isActionableUnderstandingContent(content) {
 function isDurableUnderstandingCandidate(kind, content) {
 	if (!isStandaloneUnderstandingContent(content)) return false;
 	if ((kind === "commitment" || kind === "long_term_goal") && ONE_OFF_ACTION_PREFIX.test(content.trim())) return false;
+	if (kind === "task_lesson" && !DURABLE_MARKER.test(content)) return false;
+	if (kind === "boundary" && TURN_EXECUTION_INSTRUCTION.test(content) && !DURABLE_MARKER.test(content)) return false;
 	return true;
 }
 function comparableText(content) {