@abot-ai/runtime 1.4.0 → 1.6.0

package/dist/src/runtime/long-term-memory/management/contracts.d.ts

@@ -1,4 +1,5 @@
 import type { LongTermMemoryRecord, LongTermMemoryStatus } from "../contracts.js";
+import type { LearningCandidateRecord } from "../maturation/contracts.js";
 export type LongTermMemoryManagementErrorCode = "long_term_memory_disabled" | "long_term_memory_management_conflict" | "long_term_memory_management_duplicate" | "long_term_memory_management_input_invalid" | "long_term_memory_management_not_found" | "long_term_memory_management_sensitive_data" | "long_term_memory_unavailable";
 export type MemoryManagementSource = "web_ui" | "management_api";
 export type LongTermMemoryManagementContext = Readonly<{
@@ -8,6 +9,7 @@ export type LongTermMemoryManagementContext = Readonly<{
 export type MemoryListInput = Readonly<{
     limit?: number;
     offset?: number;
+    origin?: "passive_observation";
 }>;
 export type MemoryListResult = Readonly<{
     items: readonly LongTermMemoryRecord[];
@@ -23,6 +25,8 @@ export type MemoryCreateInput = Readonly<{
     tags: readonly string[];
     source: MemoryManagementSource;
     context: LongTermMemoryManagementContext;
+    /** Atomically replace this exact candidate with the explicitly saved fact. */
+    supersedesCandidate?: Pick<LearningCandidateRecord, "id" | "revision">;
 }>;
 export type MemoryCreateResult = Readonly<{
     record: LongTermMemoryRecord;
@@ -33,6 +37,7 @@ export type MemoryUpdateInput = Readonly<{
     content: string;
     tags: readonly string[];
     context: LongTermMemoryManagementContext;
+    supersedesCandidate?: Pick<LearningCandidateRecord, "id" | "revision">;
 }>;
 export type MemoryUpdateResult = Readonly<{
     record: LongTermMemoryRecord;

package/dist/src/runtime/long-term-memory/management/mutations.js

@@ -1,10 +1,12 @@
 import { randomUUID } from "node:crypto";
+import { normalizeMemoryText } from "../policies/normalization.js";
 import { LongTermMemoryManagementError } from "./errors.js";
 import { clearMemoryRecords } from "./queries.js";
-import { findExactMemoryDuplicate, normalizeMemoryId, prepareCreatedMemory, prepareUpdatedMemory, } from "./validation.js";
+import { assertCandidateSupersessionCurrent, findExactMemoryDuplicate, normalizeMemoryId, prepareCreatedMemory, prepareUpdatedMemory, } from "./validation.js";
 export async function createManagedMemory(params) {
     const prepared = prepareCreatedMemory(params.input);
     const initial = await params.repository.read();
+    assertCandidateSupersessionCurrent(initial.learningCandidates ?? [], params.input.supersedesCandidate);
     const initialDuplicate = findExactMemoryDuplicate(initial.records, prepared.candidate.content);
     if (initialDuplicate) {
         throw new LongTermMemoryManagementError("long_term_memory_management_duplicate", { memoryId: initialDuplicate.id });
@@ -24,11 +26,13 @@ export async function createManagedMemory(params) {
             kind: "manual",
             source: prepared.source,
         }),
+        automaticManagement: "protected",
         createdAt: timestamp,
         updatedAt: timestamp,
     });
     await params.repository.update((current) => {
         params.input.context.abortSignal.throwIfAborted();
+        assertCandidateSupersessionCurrent(current.learningCandidates ?? [], params.input.supersedesCandidate);
         const duplicate = findExactMemoryDuplicate(current.records, record.content);
         if (duplicate) {
             throw new LongTermMemoryManagementError("long_term_memory_management_duplicate", { memoryId: duplicate.id });
@@ -38,6 +42,7 @@ export async function createManagedMemory(params) {
         }
         return {
             records: Object.freeze([...current.records, record]),
+            learningCandidates: retainUnsupersededCandidates(current.learningCandidates ?? [], record.content, undefined, params.input.supersedesCandidate?.id),
             vectors: Object.freeze([
                 ...current.vectors,
                 createVectorEntry(record.id, embedded),
@@ -49,7 +54,7 @@ export async function createManagedMemory(params) {
 export async function updateManagedMemory(params) {
     const prepared = prepareUpdatedMemory(params.input);
     const initial = await findUpdateTarget(params.repository, prepared);
-    if (matchesCandidate(initial, prepared.candidate)) {
+    if (canSkipManagedMemoryUpdate(initial, prepared.candidate, params.input.supersedesCandidate)) {
         return Object.freeze({ record: initial, updated: false });
     }
     const contentChanged = initial.content !== prepared.candidate.content;
@@ -63,6 +68,7 @@ export async function updateManagedMemory(params) {
     let updatedRecord;
     await params.repository.update((current) => {
         params.input.context.abortSignal.throwIfAborted();
+        assertCandidateSupersessionCurrent(current.learningCandidates ?? [], params.input.supersedesCandidate);
         const target = requireCurrentUpdateTarget(current.records, prepared);
         const duplicate = findExactMemoryDuplicate(current.records, prepared.candidate.content, target.id);
         if (duplicate) {
@@ -72,9 +78,11 @@ export async function updateManagedMemory(params) {
             ...target,
             content: prepared.candidate.content,
             tags: prepared.candidate.tags,
+            automaticManagement: "protected",
             updatedAt: nextTimestamp(target.updatedAt, params.now),
         });
         return {
+            learningCandidates: retainUnsupersededCandidates(current.learningCandidates ?? [], updatedRecord.content, target.id, params.input.supersedesCandidate?.id),
             records: Object.freeze(current.records.map((record) => record.id === target.id ? updatedRecord : record)),
             vectors: embedded
                 ? replaceMemoryVector(current.vectors, createVectorEntry(target.id, embedded))
@@ -106,6 +114,16 @@ export async function deleteManagedMemory(repository, input) {
 export function clearManagedMemories(repository) {
     return clearMemoryRecords(repository);
 }
+function retainUnsupersededCandidates(candidates, content, editedMemoryId, supersededCandidateId) {
+    const key = normalizeMemoryText(content);
+    return Object.freeze(candidates.filter((candidate) => {
+        if (candidate.id === supersededCandidateId)
+            return false;
+        const duplicatesExplicitContent = normalizeMemoryText(candidate.content) === key;
+        const replacesEditedMemory = editedMemoryId !== undefined && candidate.replacement?.id === editedMemoryId;
+        return !duplicatesExplicitContent && !replacesEditedMemory;
+    }));
+}
 async function findUpdateTarget(repository, prepared) {
     const snapshot = await repository.read();
     return requireCurrentUpdateTarget(snapshot.records, prepared);
@@ -120,7 +138,11 @@ function requireCurrentUpdateTarget(records, prepared) {
     }
     return target;
 }
-function matchesCandidate(record, candidate) {
+function canSkipManagedMemoryUpdate(record, candidate, supersedesCandidate) {
+    if (supersedesCandidate)
+        return false;
+    if (record.automaticManagement !== "protected")
+        return false;
     return (record.content === candidate.content &&
         record.tags.length === candidate.tags.length &&
         record.tags.every((tag, index) => tag === candidate.tags[index]));

package/dist/src/runtime/long-term-memory/management/queries.js

@@ -24,9 +24,13 @@ export async function readMemoryStatus(params) {
 export async function listMemoryRecords(repository, input = {}) {
     const snapshot = await repository.read();
     const page = normalizeMemoryPage(input);
+    const records = input.origin === "passive_observation"
+        ? snapshot.records.filter((record) => record.provenance.kind === "passive_observation" ||
+            (record.observationSources?.length ?? 0) > 0)
+        : snapshot.records;
     return Object.freeze({
-        items: Object.freeze(snapshot.records.slice(page.offset, page.offset + page.limit)),
-        total: snapshot.records.length,
+        items: Object.freeze(records.slice(page.offset, page.offset + page.limit)),
+        total: records.length,
     });
 }
 export async function clearMemoryRecords(repository) {

package/dist/src/runtime/long-term-memory/management/search.js

@@ -3,12 +3,16 @@ import { normalizeMemoryPage, normalizeSearchQuery } from "./validation.js";
 export async function searchManagedMemories(params) {
     const query = normalizeSearchQuery(params.input.query);
     const page = normalizeMemoryPage(params.input);
-    const ranked = await searchRankedLongTermMemories({
+    const results = await searchRankedLongTermMemories({
         repository: params.repository,
         embeddings: params.embeddings,
         query,
         context: params.input.context,
     });
+    const ranked = params.input.origin === "passive_observation"
+        ? results.filter(({ record }) => record.provenance.kind === "passive_observation" ||
+            (record.observationSources?.length ?? 0) > 0)
+        : results;
     return Object.freeze({
         items: Object.freeze(ranked
             .slice(page.offset, page.offset + page.limit)

package/dist/src/runtime/long-term-memory/management/validation.d.ts

@@ -1,5 +1,7 @@
 import type { MemoryCandidate } from "../contracts.js";
+import type { LearningCandidateRecord } from "../maturation/contracts.js";
 import type { MemoryCreateInput, MemoryListInput, MemoryManagementSource, MemoryUpdateInput } from "./contracts.js";
+export declare function assertCandidateSupersessionCurrent(candidates: readonly LearningCandidateRecord[], target: MemoryCreateInput["supersedesCandidate"]): void;
 export type MemoryPage = Readonly<{
     limit: number;
     offset: number;

package/dist/src/runtime/long-term-memory/management/validation.js

@@ -4,6 +4,14 @@ import { LongTermMemoryManagementError } from "./errors.js";
 const DEFAULT_LIST_LIMIT = 100;
 const MAX_LIST_LIMIT = 500;
 const MAX_SEARCH_QUERY_CHARACTERS = 4_000;
+export function assertCandidateSupersessionCurrent(candidates, target) {
+    if (!target)
+        return;
+    const current = candidates.find((candidate) => candidate.id === target.id);
+    if (current?.revision === target.revision)
+        return;
+    throw new LongTermMemoryManagementError("long_term_memory_management_conflict", { memoryId: target.id });
+}
 export function prepareCreatedMemory(input) {
     const candidate = prepareManualCandidate(input.content, input.tags);
     if (input.source !== "web_ui" && input.source !== "management_api") {

package/dist/src/runtime/long-term-memory/maturation/apply-diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { ApplyLearningDecisionsInput, LearningMemoryReceipt } from "./contracts.js";
+type ApplyStage = "validation" | "admission" | "binding" | "embedding" | "commit";
+/** One content-free terminal event; original errors remain owned by the caller. */
+export declare function createLearningApplyDiagnostics(input: ApplyLearningDecisionsInput): {
+    enter(next: ApplyStage): void;
+    embedded(count: number): void;
+    completed(receipt: LearningMemoryReceipt, receiptReused?: boolean): void;
+    failed(error: unknown): void;
+};
+export {};

package/dist/src/runtime/long-term-memory/maturation/apply-diagnostics.js

@@ -0,0 +1,47 @@
+import { performance } from "node:perf_hooks";
+import { traceDebug } from "../../observability/debug-logger.js";
+/** One content-free terminal event; original errors remain owned by the caller. */
+export function createLearningApplyDiagnostics(input) {
+    const startedAt = performance.now();
+    let stage = "validation";
+    let stageStartedAt = startedAt;
+    let embeddingCount = 0;
+    const stageDurationMs = {
+        validation: 0, admission: 0, binding: 0, embedding: 0, commit: 0,
+    };
+    function settleStage() {
+        const endedAt = performance.now();
+        stageDurationMs[stage] += endedAt - stageStartedAt;
+        stageStartedAt = endedAt;
+        return endedAt;
+    }
+    function finish(receipt, receiptReused = false, error) {
+        const endedAt = settleStage();
+        const completed = receipt !== undefined;
+        traceDebug("runtime.long_term_memory", completed ? "learning.apply_completed" : "learning.apply_failed", {
+            requestId: `learning:${input.batchId}`,
+            batchId: input.batchId,
+            mode: input.cause?.kind === "scheduled_knowledge_review" ? "scheduled" : input.cause?.kind === "conversation_memory_review" ? "conversation" : "observations",
+            stage,
+            status: completed ? "completed" : input.abortSignal.aborted ? "cancelled" : "failed",
+            durationMs: Math.round(endedAt - startedAt),
+            stageDurationMs: Object.fromEntries(Object.entries(stageDurationMs).map(([key, value]) => [key, Math.round(value)])),
+            decisionCount: Array.isArray(input.decisions) ? input.decisions.length : 0,
+            observationCount: input.observations.length,
+            knowledgeEntryCount: input.context.entries.length,
+            embeddingCount,
+            receiptReused,
+            ...(completed ? {
+                recordCount: receipt.recordIds.length,
+                candidateCount: receipt.candidateIds.length,
+                removedCandidateCount: receipt.removedCandidateCount,
+            } : { errorType: input.abortSignal.aborted ? "abort" : error instanceof Error ? "error" : "non_error" }),
+        });
+    }
+    return {
+        enter(next) { settleStage(); stage = next; },
+        embedded(count) { embeddingCount = count; },
+        completed(receipt, receiptReused = false) { finish(receipt, receiptReused); },
+        failed(error) { finish(undefined, false, error); },
+    };
+}

package/dist/src/runtime/long-term-memory/maturation/authoring-policy.d.ts

@@ -0,0 +1,2 @@
+/** Shared semantic quality policy; the core separately enforces score, time, and evidence admission. */
+export declare const MEMORY_KNOWLEDGE_QUALITY_INSTRUCTIONS: readonly string[];

package/dist/src/runtime/long-term-memory/maturation/authoring-policy.js

@@ -0,0 +1,6 @@
+/** Shared semantic quality policy; the core separately enforces score, time, and evidence admission. */
+export const MEMORY_KNOWLEDGE_QUALITY_INSTRUCTIONS = Object.freeze([
+    "Keep only durable user facts, preferences, or supported patterns that are useful across future conversations after the current task ends. No proposal is better than weak or temporary knowledge.",
+    "Exclude task diaries, current workflow or screen activity, transient review status, completed operations, plans without lasting personal relevance, transcripts, guesses, test or QA data, credentials, and anything the user asked not to remember. Relevance to the current answer alone does not make useful memory.",
+    "Distinguish content the user reads or tests from facts about the user. Seeing a name, preference, claim, or instruction on screen or in supplied material does not establish that it describes the user. Preserve authorship and uncertainty; repetition of the same source is not independent support.",
+]);

package/dist/src/runtime/long-term-memory/maturation/candidate-promotion.d.ts

@@ -0,0 +1,12 @@
+import type { ApplyLearningDecisionsInput, LearningCandidateRecord, LearningMemoryDecision } from "./contracts.js";
+import type { LearningMemorySource, LearningReinforcement } from "./evidence-contracts.js";
+/** Semantic reinforcement still requires a new, bound source before it has durable effects. */
+export declare function hasFreshCandidateReinforcement(options: {
+    previous: LearningCandidateRecord | undefined;
+    decision: LearningMemoryDecision;
+    input: ApplyLearningDecisionsInput;
+    source: LearningMemorySource | undefined;
+    mergedSources: readonly LearningMemorySource[];
+}): boolean;
+/** Even a high-scoring first decision must be persisted as a candidate. */
+export declare function canPromoteLearningCandidate(previous: LearningCandidateRecord | undefined, decision: LearningMemoryDecision, input: ApplyLearningDecisionsInput, reinforced: boolean, evidence?: readonly LearningReinforcement[]): boolean;

package/dist/src/runtime/long-term-memory/maturation/candidate-promotion.js

@@ -0,0 +1,51 @@
+import { isScheduledKnowledgeReview } from "./scheduled-review.js";
+import { hasIndependentLearningEvidence } from "./evidence.js";
+/** Semantic reinforcement still requires a new, bound source before it has durable effects. */
+export function hasFreshCandidateReinforcement(options) {
+    const { previous, decision, input, source, mergedSources } = options;
+    const initialAssessedEvidence = decision.action === "create" && decision.score > 0;
+    if (!decision.reinforced && !initialAssessedEvidence)
+        return false;
+    if (isScheduledKnowledgeReview(input.cause))
+        return false;
+    if (!source)
+        return false;
+    const sources = [...(previous?.sources ?? []), ...mergedSources];
+    if (source.kind === "passive_response")
+        return !sources.some(earlier => earlier.kind === "passive_response" && (earlier.sourceRequestId === source.sourceRequestId || earlier.evidenceDigest === source.evidenceDigest));
+    const history = sources.filter((earlier) => earlier.kind === "passive_observation" && sharesObservationOrigin(earlier, source));
+    if (history.some(earlier => earlier.batchId === source.batchId))
+        return false;
+    const knownIds = new Set(history.flatMap(earlier => earlier.observationIds));
+    return input.observations.some(observation => isFreshCitedObservation(observation, source, knownIds));
+}
+/** Even a high-scoring first decision must be persisted as a candidate. */
+export function canPromoteLearningCandidate(previous, decision, input, reinforced, evidence = []) {
+    if (!previous)
+        return false;
+    if (isScheduledKnowledgeReview(input.cause))
+        return false;
+    if (!reinforced)
+        return false;
+    if (!hasIndependentLearningEvidence(evidence))
+        return false;
+    return decision.score >= input.policy.promotionScore;
+}
+function sharesObservationOrigin(earlier, current) {
+    if (earlier.environmentId !== current.environmentId)
+        return false;
+    return earlier.deviceId === current.deviceId;
+}
+function isFreshCitedObservation(observation, source, knownIds) {
+    if (!source.observationIds.includes(observation.id))
+        return false;
+    if (observation.deviceId !== source.deviceId)
+        return false;
+    if (knownIds.has(observation.id))
+        return false;
+    if (observation.revisitsObservationId)
+        return false;
+    if (observation.revisit?.contentUnchanged)
+        return false;
+    return true;
+}

package/dist/src/runtime/long-term-memory/maturation/context.d.ts

@@ -0,0 +1,12 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRecord, LongTermMemoryRepository } from "../contracts.js";
+import type { LearningCandidateRecord, LearningKnowledgeContext, LearningKnowledgeEntry } from "./contracts.js";
+export declare function prepareLearningKnowledge(options: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    query: string;
+    abortSignal: AbortSignal;
+    debugRequestId?: string;
+    now: number;
+}): Promise<LearningKnowledgeContext>;
+export declare function candidateKnowledge(record: LearningCandidateRecord): LearningKnowledgeEntry;
+export declare function memoryKnowledge(record: LongTermMemoryRecord): LearningKnowledgeEntry;

package/dist/src/runtime/long-term-memory/maturation/context.js

@@ -0,0 +1,67 @@
+import { embedLongTermMemoryTexts } from "../embedding-batches.js";
+import { cosineSimilarity } from "../policies/scoring.js";
+import { canAutomaticallyManageMemory } from "../automatic-management.js";
+import { isCandidateUnexpired } from "./retention.js";
+const MAX_CONTEXT_ENTRIES = 12;
+const MAX_CONTEXT_CHARACTERS = 24_000;
+export async function prepareLearningKnowledge(options) {
+    options.abortSignal.throwIfAborted();
+    const snapshot = await options.repository.read();
+    const candidates = (snapshot.learningCandidates ?? []).filter((record) => isCandidateUnexpired(record, options.now));
+    const count = candidates.length + snapshot.records.length;
+    const base = {
+        kind: "learning_knowledge_reference_v1",
+        authority: "passive_reference",
+        presenceEffect: "does_not_authorize_actions_or_add_user_intent",
+        repositoryRevision: snapshot.revision,
+        knowledgeRevision: snapshot.knowledgeRevision ?? snapshot.revision,
+        referenceTime: new Date(options.now).toISOString(),
+    };
+    if (!count || !options.query.trim())
+        return { ...base, entries: [], omitted: count };
+    const embedded = await embedLongTermMemoryTexts({ ...options, texts: [options.query.slice(0, 8000)] });
+    const vectors = [...snapshot.vectors, ...candidates.map(({ embedding }) => embedding)];
+    assertLearningIndexCompatible(vectors, embedded);
+    const byId = new Map(snapshot.vectors.map((entry) => [entry.memoryId, entry]));
+    const entries = [
+        ...candidates.map((record) => ({ entry: candidateKnowledge(record), vector: record.embedding })),
+        ...snapshot.records.map((record) => ({ entry: memoryKnowledge(record), vector: byId.get(record.id) })),
+    ];
+    if (entries.some(({ vector }) => !vector))
+        throw new Error("learning_embedding_reindex_required");
+    const ranked = entries.map(({ entry, vector }) => ({
+        entry, similarity: cosineSimilarity(embedded.vectors[0], vector.vector),
+    })).filter(({ entry, similarity }) => isRelevantLearningEntry(entry, similarity, options.now))
+        .sort((a, b) => b.similarity - a.similarity || a.entry.id.localeCompare(b.entry.id));
+    const selected = [];
+    let size = 0;
+    for (const { entry } of ranked) {
+        const bytes = JSON.stringify(entry).length;
+        if (selected.length >= MAX_CONTEXT_ENTRIES)
+            break;
+        if (size + bytes > MAX_CONTEXT_CHARACTERS)
+            continue;
+        selected.push(entry);
+        size += bytes;
+    }
+    return Object.freeze({ ...base, entries: Object.freeze(selected), omitted: count - selected.length });
+}
+function assertLearningIndexCompatible(entries, binding) {
+    if (entries.some((entry) => entry.dimensions !== binding.dimensions || entry.modelFingerprint !== binding.modelFingerprint))
+        throw new Error("learning_embedding_reindex_required");
+}
+function isRelevantLearningEntry(entry, similarity, now) {
+    if (entry.reconsiderAt && Date.parse(entry.reconsiderAt) <= now)
+        return true;
+    return similarity >= 0.25;
+}
+export function candidateKnowledge(record) {
+    return { kind: "candidate", id: record.id, version: String(record.revision), content: record.content, tags: record.tags,
+        score: record.score, reason: record.reason, certainty: record.certainty, mutable: true,
+        lastReinforcedAt: record.lastReinforcedAt, reconsiderAt: record.reconsiderAt };
+}
+export function memoryKnowledge(record) {
+    return { kind: "memory", id: record.id, version: record.updatedAt, content: record.content, tags: record.tags,
+        score: null, reason: null, certainty: record.provenance.kind === "passive_observation" ? record.provenance.certainty : "unspecified",
+        mutable: canAutomaticallyManageMemory(record), lastReinforcedAt: null, reconsiderAt: record.reconsiderAt ?? null };
+}

package/dist/src/runtime/long-term-memory/maturation/contracts.d.ts

@@ -0,0 +1,120 @@
+import type { MemoryCandidate, MemoryVectorIndexEntry } from "../contracts.js";
+import type { SaveObservationMemoryInput } from "../observation-contracts.js";
+import type { ConversationMemoryEvidence, LearningMemorySource, LearningReinforcement, LearningMemoryReplacement } from "./evidence-contracts.js";
+export type MaturationPolicy = Readonly<{
+    promotionScore: number;
+    retentionDays: number;
+    maxCandidates: number;
+    maxBytes: number;
+}>;
+export type LearningCandidateRecord = Pick<MemoryCandidate, "content" | "tags"> & Readonly<{
+    id: string;
+    revision: number;
+    score: number;
+    reason: string;
+    certainty: "observed" | "inferred";
+    sources: readonly LearningMemorySource[];
+    reinforcements?: readonly LearningReinforcement[];
+    replacement?: LearningMemoryReplacement;
+    createdAt: string;
+    updatedAt: string;
+    lastReinforcedAt: string;
+    expiresAt: string;
+    reconsiderAt: string | null;
+    embedding: MemoryVectorIndexEntry;
+}>;
+export type LearningKnowledgeEntry = Pick<MemoryCandidate, "content" | "tags"> & Readonly<{
+    kind: "candidate" | "memory";
+    id: string;
+    version: string;
+    score: number | null;
+    reason: string | null;
+    certainty: "observed" | "inferred" | "unspecified";
+    mutable: boolean;
+    lastReinforcedAt: string | null;
+    reconsiderAt: string | null;
+}>;
+export type LearningKnowledgeContext = Readonly<{
+    kind: "learning_knowledge_reference_v1";
+    authority: "passive_reference";
+    presenceEffect: "does_not_authorize_actions_or_add_user_intent";
+    repositoryRevision: number;
+    knowledgeRevision: number;
+    entries: readonly LearningKnowledgeEntry[];
+    omitted: number;
+    referenceTime: string;
+}>;
+/** Semantic proposals only. The repository transaction validates every binding. */
+export type LearningMemoryDecision = Pick<MemoryCandidate, "content" | "tags"> & Readonly<{
+    action: "create" | "update" | "merge" | "remove";
+    targetKind: "candidate" | "memory";
+    targetId: string | null;
+    targetVersion: string | null;
+    mergedCandidateIds: readonly string[];
+    observationIds: readonly string[];
+    score: number;
+    reason: string;
+    certainty: "observed" | "inferred";
+    reinforced: boolean;
+    reconsiderAt: string | null;
+}>;
+export type LearningMemoryReceipt = Readonly<{
+    batchId: string;
+    recordIds: readonly string[];
+    candidateIds: readonly string[];
+    removedCandidateCount: number;
+    createdAt: string;
+    expiresAt: string;
+}>;
+export type LearningReviewCause = Readonly<{
+    kind: "scheduled_knowledge_review";
+    dueEntries: readonly Pick<LearningKnowledgeEntry, "kind" | "id" | "version">[];
+}> | Readonly<{
+    kind: "conversation_memory_review";
+    evidence: ConversationMemoryEvidence;
+}>;
+export type ApplyLearningDecisionsInput = Omit<SaveObservationMemoryInput, "proposals"> & Readonly<{
+    cause?: LearningReviewCause;
+    context: LearningKnowledgeContext;
+    decisions: readonly LearningMemoryDecision[];
+    policy: MaturationPolicy;
+    beforeEmbedding?: LearningEmbeddingReservation;
+}>;
+/** Caller-owned background resource policy; ordinary memory calls are unaffected. */
+export type LearningEmbeddingReservation = (input: Readonly<{
+    characters: number;
+    signal: AbortSignal;
+}>) => Promise<() => void>;
+export type LearningMemoryMaintenance = Readonly<{
+    removedCandidateCount: number;
+    removedReceiptCount: number;
+    nextExpiryAt: string | null;
+}>;
+export type LearningReviewAdmission = Readonly<{
+    available: boolean;
+    reason?: "learning_receipt_capacity";
+    retryAt: string | null;
+}>;
+export type ScheduledKnowledgeSelection = Readonly<{
+    exclude?: readonly Pick<LearningKnowledgeEntry, "kind" | "id" | "version">[];
+}>;
+export type LearningMemoryService = Readonly<{
+    policy(): Promise<MaturationPolicy>;
+    configurePolicy(policy: MaturationPolicy, initializeOnly?: boolean): Promise<MaturationPolicy>;
+    reviewAdmission(): Promise<LearningReviewAdmission>;
+    nextReconsiderationAt(input?: ScheduledKnowledgeSelection): Promise<string | null>;
+    reconsiderationContext(input?: ScheduledKnowledgeSelection): Promise<LearningKnowledgeContext>;
+    maintenance(policy: MaturationPolicy): Promise<LearningMemoryMaintenance>;
+    nextExpiryAt(policy: MaturationPolicy): Promise<string | null>;
+    overview(): Promise<LearningKnowledgeContext>;
+    sourceVersions(): Promise<readonly Pick<LearningKnowledgeEntry, "kind" | "id" | "version">[]>;
+    prepare(input: Readonly<{
+        query: string;
+        abortSignal: AbortSignal;
+        debugRequestId?: string;
+        beforeEmbedding?: LearningEmbeddingReservation;
+    }>): Promise<LearningKnowledgeContext>;
+    apply(input: ApplyLearningDecisionsInput): Promise<LearningMemoryReceipt>;
+    list(): Promise<readonly LearningCandidateRecord[]>;
+    receipt(batchId: string): Promise<LearningMemoryReceipt | undefined>;
+}>;

package/dist/src/runtime/long-term-memory/maturation/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/src/runtime/long-term-memory/maturation/conversation-evidence.d.ts

@@ -0,0 +1,3 @@
+import type { LearningReviewCause } from "./contracts.js";
+/** Conversation provenance is supplied by the request owner, never by the model. */
+export declare function assertConversationReviewCause(cause: LearningReviewCause | undefined, now: number): void;

package/dist/src/runtime/long-term-memory/maturation/conversation-evidence.js

@@ -0,0 +1,16 @@
+/** Conversation provenance is supplied by the request owner, never by the model. */
+export function assertConversationReviewCause(cause, now) {
+    if (cause?.kind !== "conversation_memory_review")
+        return;
+    const evidence = cause.evidence;
+    if (!evidence || !isIdentifier(evidence.sourceSessionId) || !isIdentifier(evidence.sourceRequestId))
+        throw new Error("learning_conversation_evidence_invalid");
+    if (!/^[a-f0-9]{64}$/u.test(evidence.evidenceDigest))
+        throw new Error("learning_conversation_evidence_invalid");
+    const timestamp = Date.parse(evidence.observedAt);
+    if (!Number.isFinite(timestamp) || timestamp > now || now - timestamp >= 86_400_000)
+        throw new Error("learning_conversation_evidence_expired");
+}
+function isIdentifier(value) {
+    return typeof value === "string" && value.trim().length > 0 && value.length <= 256;
+}

package/dist/src/runtime/long-term-memory/maturation/current-bindings.d.ts

@@ -0,0 +1,4 @@
+import type { LongTermMemoryRepositorySnapshot } from "../contracts.js";
+import type { ApplyLearningDecisionsInput } from "./contracts.js";
+/** Supplied context is evidence, never authority to recreate or rewrite a target. */
+export declare function assertCurrentLearningDecisionBindings(current: LongTermMemoryRepositorySnapshot, input: ApplyLearningDecisionsInput, now: number): void;

package/dist/src/runtime/long-term-memory/maturation/current-bindings.js

@@ -0,0 +1,53 @@
+import { isDeepStrictEqual } from "node:util";
+import { candidateKnowledge, memoryKnowledge } from "./context.js";
+import { assertLearningDecisionBindings } from "./decisions.js";
+import { isCandidateUnexpired } from "./retention.js";
+import { isScheduledKnowledgeReview } from "./scheduled-review.js";
+import { assertDistinctLearningMemoryWriteTargets } from "./write-targets.js";
+/** Supplied context is evidence, never authority to recreate or rewrite a target. */
+export function assertCurrentLearningDecisionBindings(current, input, now) {
+    // Unrelated batches may commit concurrently; only decision targets and merge
+    // sources are compare-and-swap dependencies, not the whole repository revision.
+    assertLearningDecisionBindings(input.decisions, input.context, input.observations.map(({ id }) => id), now, input.cause);
+    for (const decision of input.decisions) {
+        if (decision.action !== "create")
+            assertCurrentEntry(current, input, decision.targetKind, decision.targetId, now);
+        for (const id of decision.mergedCandidateIds)
+            assertCurrentEntry(current, input, "candidate", id, now);
+    }
+    assertDistinctLearningMemoryWriteTargets(current, input.decisions);
+    if (!isScheduledKnowledgeReview(input.cause))
+        return;
+    if (input.observations.length)
+        throw new Error("learning_review_observations_unexpected");
+    for (const due of input.cause.dueEntries) {
+        assertCurrentEntry(current, input, due.kind, due.id, now);
+        const entry = currentEntry(current, due.kind, due.id, now);
+        if (entry.version !== due.version)
+            throw new Error("learning_knowledge_conflict");
+        if (!entry.reconsiderAt || Date.parse(entry.reconsiderAt) > now)
+            throw new Error("learning_review_target_not_due");
+    }
+}
+function assertCurrentEntry(current, input, kind, id, now) {
+    const supplied = input.context.entries.find((entry) => entry.kind === kind && entry.id === id);
+    const canonical = currentEntry(current, kind, id, now);
+    if (!isDeepStrictEqual(supplied, canonical))
+        throw new Error("learning_knowledge_conflict");
+    if (!canonical.mutable)
+        throw new Error("learning_memory_protected");
+}
+function currentEntry(current, kind, id, now) {
+    if (kind === "memory") {
+        const target = current.records.find((record) => record.id === id);
+        if (!target)
+            throw new Error("learning_decision_target_unknown");
+        return memoryKnowledge(target);
+    }
+    const target = current.learningCandidates?.find((record) => record.id === id);
+    if (!target)
+        throw new Error("learning_decision_target_unknown");
+    if (!isCandidateUnexpired(target, now))
+        throw new Error("learning_candidate_expired");
+    return candidateKnowledge(target);
+}

package/dist/src/runtime/long-term-memory/maturation/decision-envelope.d.ts

@@ -0,0 +1,22 @@
+type LearningOutputType = "missing" | "null" | "array" | "object" | "string" | "number" | "boolean";
+type InvalidJsonShape = "empty" | "markdown_fence" | "object_delimited" | "object_missing_closer" | "array_delimited" | "array_missing_closer" | "other";
+type LearningEnvelopeReason = "learning_output_invalid_json" | "learning_output_object_required" | "learning_output_decisions_missing" | "learning_output_decisions_not_array" | "learning_output_decision_limit";
+/** Shape metadata only: no model text, property names or decision values. */
+export declare class LearningDecisionEnvelopeError extends Error {
+    readonly shape: Readonly<{
+        rootType?: LearningOutputType;
+        decisionsType?: LearningOutputType;
+        decisionCount?: number;
+        invalidJsonShape?: InvalidJsonShape;
+        decisionLimit: number;
+    }>;
+    constructor(reason: LearningEnvelopeReason, shape: Readonly<{
+        rootType?: LearningOutputType;
+        decisionsType?: LearningOutputType;
+        decisionCount?: number;
+        invalidJsonShape?: InvalidJsonShape;
+        decisionLimit: number;
+    }>);
+}
+export declare function readLearningDecisionEnvelope(text: string, decisionLimit: number): readonly unknown[];
+export {};