@abot-ai/runtime 1.3.1 → 1.5.0

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

@@ -0,0 +1,66 @@
+/** Shape metadata only: no model text, property names or decision values. */
+export class LearningDecisionEnvelopeError extends Error {
+    shape;
+    constructor(reason, shape) {
+        super(reason);
+        this.shape = shape;
+        this.name = "LearningDecisionEnvelopeError";
+    }
+}
+export function readLearningDecisionEnvelope(text, decisionLimit) {
+    let decoded;
+    try {
+        decoded = JSON.parse(text);
+    }
+    catch {
+        throw new LearningDecisionEnvelopeError("learning_output_invalid_json", {
+            decisionLimit, invalidJsonShape: classifyInvalidJsonShape(text),
+        });
+    }
+    const rootType = learningOutputType(decoded);
+    if (!isLearningEnvelopeObject(decoded)) {
+        throw new LearningDecisionEnvelopeError("learning_output_object_required", { rootType, decisionLimit });
+    }
+    if (!Object.hasOwn(decoded, "decisions")) {
+        throw new LearningDecisionEnvelopeError("learning_output_decisions_missing", {
+            rootType, decisionsType: "missing", decisionLimit,
+        });
+    }
+    const decisions = decoded.decisions;
+    const shape = { rootType, decisionsType: learningOutputType(decisions), decisionLimit };
+    if (!Array.isArray(decisions)) {
+        throw new LearningDecisionEnvelopeError("learning_output_decisions_not_array", shape);
+    }
+    if (decisions.length > decisionLimit) {
+        throw new LearningDecisionEnvelopeError("learning_output_decision_limit", { ...shape, decisionCount: decisions.length });
+    }
+    return decisions;
+}
+function classifyInvalidJsonShape(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return "empty";
+    if (trimmed.startsWith("```"))
+        return "markdown_fence";
+    if (trimmed.startsWith("{"))
+        return trimmed.endsWith("}") ? "object_delimited" : "object_missing_closer";
+    if (trimmed.startsWith("["))
+        return trimmed.endsWith("]") ? "array_delimited" : "array_missing_closer";
+    return "other";
+}
+function isLearningEnvelopeObject(value) {
+    if (value === null)
+        return false;
+    if (Array.isArray(value))
+        return false;
+    return typeof value === "object";
+}
+function learningOutputType(value) {
+    if (value === undefined)
+        return "missing";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

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

@@ -0,0 +1,5 @@
+import type { LearningKnowledgeContext, LearningMemoryDecision, LearningReviewCause } from "./contracts.js";
+export declare const MAX_LEARNING_DECISIONS = 12;
+export declare function parseLearningDecisions(text: string): readonly LearningMemoryDecision[];
+export declare function normalizeLearningDecisions(decisions: readonly unknown[]): readonly LearningMemoryDecision[];
+export declare function assertLearningDecisionBindings(decisions: readonly LearningMemoryDecision[], context: LearningKnowledgeContext, observationIds: readonly string[], now: number, cause?: LearningReviewCause): void;

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

@@ -0,0 +1,131 @@
+import { isMemoryCandidateWithinLimits, normalizeMemoryCandidate, MAX_MEMORY_CONTENT_CHARACTERS } from "../policies/normalization.js";
+import { containsSensitiveMemoryCandidateData, containsSensitiveMemoryData } from "../policies/sensitive-data.js";
+import { assertScheduledReviewCause, isScheduledKnowledgeReview } from "./scheduled-review.js";
+import { readLearningDecisionEnvelope } from "./decision-envelope.js";
+import { assertConversationReviewCause } from "./conversation-evidence.js";
+export const MAX_LEARNING_DECISIONS = 12;
+export function parseLearningDecisions(text) {
+    const decisions = readLearningDecisionEnvelope(text, MAX_LEARNING_DECISIONS);
+    for (const decision of decisions) {
+        if (isObject(decision) && typeof decision.content === "string" && decision.content.length > MAX_MEMORY_CONTENT_CHARACTERS)
+            throw new Error("learning_content_exceeds_limit");
+    }
+    return normalizeLearningDecisions(decisions);
+}
+export function normalizeLearningDecisions(decisions) {
+    if (!Array.isArray(decisions) || decisions.length > MAX_LEARNING_DECISIONS)
+        throw new Error("learning_decisions_invalid");
+    return Object.freeze(decisions.map(parseDecision));
+}
+export function assertLearningDecisionBindings(decisions, context, observationIds, now, cause) {
+    assertScheduledReviewCause(cause);
+    assertConversationReviewCause(cause, now);
+    if (decisions.length > MAX_LEARNING_DECISIONS)
+        throw new Error("learning_decisions_invalid");
+    const touched = new Set();
+    for (const raw of decisions) {
+        const decision = parseDecision(raw);
+        if (isScheduledKnowledgeReview(cause))
+            assertScheduledDecision(decision, context, cause);
+        if (cause?.kind === "conversation_memory_review" && decision.observationIds.length)
+            throw new Error("learning_decision_source_unknown");
+        if (!cause && (!decision.observationIds.length || decision.observationIds.some((id) => !observationIds.includes(id))))
+            throw new Error("learning_decision_source_unknown");
+        if (decision.reconsiderAt && Date.parse(decision.reconsiderAt) <= now && !preservesBoundReviewDeadline(decision, context, cause))
+            throw new Error("learning_reconsideration_not_future");
+        if (decision.action === "create") {
+            if (decision.targetKind !== "candidate" || decision.targetId !== null || decision.targetVersion !== null)
+                throw new Error("learning_create_target_invalid");
+        }
+        else {
+            const target = context.entries.find((entry) => entry.kind === decision.targetKind && entry.id === decision.targetId);
+            if (!target || target.version !== decision.targetVersion)
+                throw new Error("learning_decision_target_unknown");
+            if (!target.mutable)
+                throw new Error("learning_memory_protected");
+            touch(touched, `${target.kind}:${target.id}`);
+        }
+        if (decision.action !== "merge" && decision.mergedCandidateIds.length)
+            throw new Error("learning_merge_binding_invalid");
+        if (decision.action === "merge" && !decision.mergedCandidateIds.length)
+            throw new Error("learning_merge_binding_invalid");
+        for (const id of decision.mergedCandidateIds) {
+            const source = context.entries.find((entry) => entry.kind === "candidate" && entry.id === id);
+            if (!source)
+                throw new Error("learning_merge_source_unknown");
+            touch(touched, `candidate:${id}`);
+        }
+    }
+}
+function preservesBoundReviewDeadline(decision, context, cause) {
+    if (isScheduledKnowledgeReview(cause) || decision.action === "create")
+        return false;
+    return context.entries.some(entry => entry.kind === decision.targetKind && entry.id === decision.targetId &&
+        entry.version === decision.targetVersion && entry.reconsiderAt === decision.reconsiderAt);
+}
+function assertScheduledDecision(decision, context, cause) {
+    if (decision.action !== "update" && decision.action !== "remove")
+        throw new Error("learning_review_action_invalid");
+    if (decision.observationIds.length || decision.reinforced)
+        throw new Error("learning_review_cannot_reinforce");
+    const due = cause.dueEntries.find((entry) => entry.kind === decision.targetKind && entry.id === decision.targetId && entry.version === decision.targetVersion);
+    if (!due)
+        throw new Error("learning_review_target_not_due");
+    const target = context.entries.find((entry) => entry.kind === due.kind && entry.id === due.id);
+    if (!target)
+        throw new Error("learning_decision_target_unknown");
+    if (decision.action === "remove" || target.kind === "memory")
+        return;
+    if (decision.score > (target.score ?? 0))
+        throw new Error("learning_review_cannot_raise_score");
+}
+function touch(touched, id) {
+    if (touched.has(id))
+        throw new Error("learning_decision_target_repeated");
+    touched.add(id);
+}
+function parseDecision(raw) {
+    if (!isObject(raw))
+        throw new Error("learning_decision_invalid");
+    const { action, targetKind, targetId, targetVersion, reconsiderAt, certainty } = raw;
+    if (action !== "create" && action !== "update" && action !== "remove" && action !== "merge")
+        throw new Error("learning_action_invalid");
+    if (targetKind !== "candidate" && targetKind !== "memory")
+        throw new Error("learning_target_kind_invalid");
+    if (!isNullableText(targetId) || !isNullableText(targetVersion))
+        throw new Error("learning_target_invalid");
+    if (!isNullableText(reconsiderAt) || (reconsiderAt !== null && !Number.isFinite(Date.parse(reconsiderAt))))
+        throw new Error("learning_reconsideration_invalid");
+    if (certainty !== "observed" && certainty !== "inferred")
+        throw new Error("learning_certainty_invalid");
+    if (typeof raw.reinforced !== "boolean")
+        throw new Error("learning_reinforcement_invalid");
+    if (typeof raw.score !== "number" || !Number.isInteger(raw.score) || raw.score < 0 || raw.score > 100)
+        throw new Error("learning_score_invalid");
+    if (typeof raw.content !== "string" || (action !== "remove" && !raw.content.trim()))
+        throw new Error("learning_content_invalid");
+    if (typeof raw.reason !== "string" || !raw.reason.trim() || raw.reason.length > 1000)
+        throw new Error("learning_reason_invalid");
+    const tags = stringList(raw.tags, 12);
+    if (!isMemoryCandidateWithinLimits({ content: raw.content, tags }))
+        throw new Error("learning_content_exceeds_limit");
+    if (containsSensitiveMemoryCandidateData({ content: raw.content, tags }) || containsSensitiveMemoryData(raw.reason))
+        throw new Error("learning_content_sensitive");
+    const candidate = normalizeMemoryCandidate({ content: raw.content, tags }) ?? { content: "", tags: [] };
+    return Object.freeze({
+        action, targetKind, targetId, targetVersion, reconsiderAt, certainty,
+        ...candidate, score: raw.score, reason: raw.reason.trim(), reinforced: raw.reinforced,
+        mergedCandidateIds: stringList(raw.mergedCandidateIds, 12), observationIds: stringList(raw.observationIds, 16),
+    });
+}
+function stringList(value, max) {
+    if (!Array.isArray(value) || value.length > max || value.some((item) => typeof item !== "string" || !item.trim()))
+        throw new Error("learning_decision_list_invalid");
+    return Object.freeze([...new Set(value)]);
+}
+function isNullableText(value) {
+    return value === null || (typeof value === "string" && value.trim().length > 0 && value.length <= 128);
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -0,0 +1,5 @@
+import type { LongTermMemoryRepositorySnapshot, MemoryVectorIndexEntry } from "../contracts.js";
+type EmbeddingBinding = Pick<MemoryVectorIndexEntry, "dimensions" | "modelFingerprint">;
+export declare function currentLearningEmbeddingBinding(current: LongTermMemoryRepositorySnapshot, now: number): EmbeddingBinding | undefined;
+export declare function assertCompatibleLearningEmbeddings(vectors: Iterable<EmbeddingBinding>, binding: EmbeddingBinding | undefined): void;
+export {};

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

@@ -0,0 +1,20 @@
+import { isCandidateUnexpired } from "./retention.js";
+export function currentLearningEmbeddingBinding(current, now) {
+    const candidates = (current.learningCandidates ?? []).filter((record) => isCandidateUnexpired(record, now));
+    const vectors = [...current.vectors, ...candidates.map((record) => record.embedding)];
+    const binding = vectors[0];
+    if (!binding)
+        return undefined;
+    assertCompatibleLearningEmbeddings(vectors, binding);
+    return { dimensions: binding.dimensions, modelFingerprint: binding.modelFingerprint };
+}
+export function assertCompatibleLearningEmbeddings(vectors, binding) {
+    if (!binding)
+        return;
+    for (const vector of vectors) {
+        if (vector.dimensions !== binding.dimensions)
+            throw new Error("learning_embedding_reindex_required");
+        if (vector.modelFingerprint !== binding.modelFingerprint)
+            throw new Error("learning_embedding_reindex_required");
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { LongTermMemoryEmbeddingClient } from "../contracts.js";
+import type { LearningEmbeddingReservation } from "./contracts.js";
+export declare function reserveLearningEmbeddings(client: LongTermMemoryEmbeddingClient, reserve?: LearningEmbeddingReservation): LongTermMemoryEmbeddingClient;

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

@@ -0,0 +1,17 @@
+export function reserveLearningEmbeddings(client, reserve) {
+    if (!reserve)
+        return client;
+    return {
+        ...client,
+        async embed(input) {
+            const release = await reserve({ characters: input.texts.reduce((sum, text) => sum + text.length, 0), signal: input.abortSignal });
+            try {
+                input.abortSignal.throwIfAborted();
+                return await client.embed(input);
+            }
+            finally {
+                release();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,33 @@
+import type { ObservationMemorySource } from "../observation-contracts.js";
+import type { LearningKnowledgeEntry } from "./contracts.js";
+/** Bound by the runtime, never supplied by the authoring model. */
+export type ConversationMemoryEvidence = Readonly<{
+    sourceSessionId: string;
+    sourceRequestId: string;
+    observedAt: string;
+    evidenceDigest: string;
+}>;
+export type ConversationMemorySource = ConversationMemoryEvidence & Readonly<{
+    kind: "passive_response";
+    reason: string;
+    certainty: "observed" | "inferred";
+}>;
+export type LearningMemorySource = ObservationMemorySource | ConversationMemorySource;
+/** Bounded independent opportunities, not a count of captures or model calls. */
+export type LearningReinforcement = Readonly<{
+    key: string;
+    observedAt: string;
+}>;
+export type ConversationMemoryAssessment = Readonly<{
+    score: number;
+    reason: string;
+    reinforced: boolean;
+    /** Set only after a model quote is bound to this request's user-authored text. */
+    explicitlyRequested?: boolean;
+    evidence: ConversationMemoryEvidence;
+    target?: LearningKnowledgeEntry;
+}>;
+export type LearningMemoryReplacement = Readonly<{
+    id: string;
+    version: string;
+}>;

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

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

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

@@ -0,0 +1,7 @@
+import type { ApplyLearningDecisionsInput, LearningMemoryDecision } from "./contracts.js";
+import type { LearningMemorySource, LearningReinforcement } from "./evidence-contracts.js";
+export declare const MINIMUM_MEMORY_REINFORCEMENTS = 2;
+export declare function bindLearningMemorySource(input: ApplyLearningDecisionsInput, decision: LearningMemoryDecision): LearningMemorySource | undefined;
+/** A previously seen source cannot count as another opportunity. */
+export declare function advanceLearningReinforcements(previous: readonly LearningReinforcement[] | undefined, source: LearningMemorySource | undefined, reinforced: boolean, now: number): readonly LearningReinforcement[];
+export declare function hasIndependentLearningEvidence(evidence: readonly LearningReinforcement[]): boolean;

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

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { bindObservationSource } from "../observation-source.js";
+import { isScheduledKnowledgeReview } from "./scheduled-review.js";
+export const MINIMUM_MEMORY_REINFORCEMENTS = 2;
+export function bindLearningMemorySource(input, decision) {
+    if (isScheduledKnowledgeReview(input.cause))
+        return undefined;
+    if (input.cause?.kind !== "conversation_memory_review")
+        return bindObservationSource({ ...input, proposals: [] }, decision);
+    return {
+        kind: "passive_response",
+        ...input.cause.evidence,
+        reason: decision.reason,
+        certainty: decision.certainty,
+    };
+}
+/** A previously seen source cannot count as another opportunity. */
+export function advanceLearningReinforcements(previous = [], source, reinforced, now) {
+    if (!source || !reinforced)
+        return previous;
+    const key = learningEvidenceKey(source);
+    if (previous.some((entry) => entry.key === key))
+        return previous;
+    const timestamp = Date.parse(source.observedAt);
+    if (!Number.isFinite(timestamp) || timestamp > now)
+        return previous;
+    return [...previous, { key, observedAt: source.observedAt }].slice(-MINIMUM_MEMORY_REINFORCEMENTS);
+}
+export function hasIndependentLearningEvidence(evidence) {
+    return evidence.length >= MINIMUM_MEMORY_REINFORCEMENTS;
+}
+function learningEvidenceKey(source) {
+    const binding = source.kind === "passive_response"
+        ? [source.kind, source.sourceSessionId, source.evidenceDigest]
+        : [
+            source.kind,
+            source.environmentId,
+            source.deviceId,
+            [...source.observationIds].sort(),
+        ];
+    return createHash("sha256").update(JSON.stringify(binding)).digest("hex");
+}

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

@@ -0,0 +1,31 @@
+import type { LearningMemoryMaintenance, LearningMemoryService, MaturationPolicy } from "./contracts.js";
+type MaintenanceClockOptions = Readonly<{
+    memory: Pick<LearningMemoryService, "maintenance" | "nextExpiryAt">;
+    policy(): MaturationPolicy | Promise<MaturationPolicy>;
+    now?: () => number;
+    changed?(result: LearningMemoryMaintenance): void;
+    failed?(error: unknown): void;
+    refreshed?(): void;
+}>;
+/** One actual retention deadline, independent of collection/model activity switches. */
+export declare class LearningMaintenanceClock {
+    private readonly options;
+    private timer;
+    private started;
+    private refreshRequested;
+    private policyChanged;
+    private refreshTask;
+    scheduledAt: number | undefined;
+    constructor(options: MaintenanceClockOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    preferencesChanged(): Promise<void>;
+    knowledgeChanged(): Promise<void>;
+    private requestRefresh;
+    private drain;
+    private refreshDeadline;
+    private arm;
+    private clearTimer;
+    private now;
+}
+export {};

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

@@ -0,0 +1,118 @@
+// Node clamps larger setTimeout delays to 1 ms; long candidate retention must not spin.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** One actual retention deadline, independent of collection/model activity switches. */
+export class LearningMaintenanceClock {
+    options;
+    timer;
+    started = false;
+    refreshRequested = false;
+    policyChanged = false;
+    refreshTask;
+    scheduledAt;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.started)
+            return this.refreshTask ?? Promise.resolve();
+        this.started = true;
+        return this.requestRefresh(false);
+    }
+    async stop() {
+        this.started = false;
+        this.refreshRequested = false;
+        this.policyChanged = false;
+        this.clearTimer();
+        await this.refreshTask;
+    }
+    preferencesChanged() { return this.requestRefresh(true); }
+    knowledgeChanged() { return this.requestRefresh(false); }
+    requestRefresh(policyChanged) {
+        if (!this.started)
+            return Promise.resolve();
+        this.refreshRequested = true;
+        this.policyChanged ||= policyChanged;
+        this.refreshTask ??= this.drain().finally(() => {
+            this.refreshTask = undefined;
+            if (this.refreshRequested)
+                void this.requestRefresh(false);
+        });
+        return this.refreshTask;
+    }
+    async drain() {
+        try {
+            while (this.started && this.refreshRequested) {
+                this.refreshRequested = false;
+                const enforcePolicy = this.policyChanged;
+                this.policyChanged = false;
+                await this.refreshDeadline(enforcePolicy);
+            }
+        }
+        catch (error) {
+            this.refreshRequested = false;
+            this.clearTimer();
+            this.options.failed?.(error);
+        }
+    }
+    async refreshDeadline(enforcePolicy) {
+        this.clearTimer();
+        const policy = await this.options.policy();
+        if (!this.started)
+            return;
+        let nextExpiryAt = await this.options.memory.nextExpiryAt(policy);
+        if (!this.started)
+            return;
+        if (requiresRetentionMaintenance(nextExpiryAt, enforcePolicy, this.now())) {
+            const maintainedAt = this.now();
+            const result = await this.options.memory.maintenance(policy);
+            if (!this.started)
+                return;
+            nextExpiryAt = result.nextExpiryAt;
+            if (hasUnadvancedRetentionDeadline(nextExpiryAt, maintainedAt))
+                throw new Error("learning_maintenance_deadline_not_advanced");
+            if (hasRemovedLearningState(result))
+                this.options.changed?.(result);
+        }
+        this.arm(nextExpiryAt);
+        this.options.refreshed?.();
+    }
+    arm(nextExpiryAt) {
+        if (!this.started || nextExpiryAt === null)
+            return;
+        const deadline = Date.parse(nextExpiryAt);
+        if (!Number.isFinite(deadline))
+            throw new Error("learning_maintenance_deadline_invalid");
+        const delay = Math.max(1, deadline - this.now());
+        this.scheduledAt = deadline;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.scheduledAt = undefined;
+            void this.requestRefresh(false);
+        }, Math.min(delay, MAX_TIMER_DELAY_MS));
+        this.timer.unref?.();
+    }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.scheduledAt = undefined;
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+}
+function requiresRetentionMaintenance(nextExpiryAt, enforcePolicy, now) {
+    if (enforcePolicy)
+        return true;
+    if (nextExpiryAt === null)
+        return false;
+    return Date.parse(nextExpiryAt) <= now;
+}
+function hasRemovedLearningState(result) {
+    if (result.removedCandidateCount > 0)
+        return true;
+    return result.removedReceiptCount > 0;
+}
+function hasUnadvancedRetentionDeadline(nextExpiryAt, maintainedAt) {
+    if (nextExpiryAt === null)
+        return false;
+    return Date.parse(nextExpiryAt) <= maintainedAt;
+}

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

@@ -0,0 +1,5 @@
+import type { LongTermMemoryRepository, LongTermMemoryRepositorySnapshot } from "../contracts.js";
+import type { LearningMemoryMaintenance, MaturationPolicy } from "./contracts.js";
+/** Call at an actual expiry/configuration change, not on a frequent polling loop. */
+export declare function maintainLearningMemory(repository: LongTermMemoryRepository, policy: MaturationPolicy, now: number): Promise<LearningMemoryMaintenance>;
+export declare function nextLearningExpiryAt(snapshot: LongTermMemoryRepositorySnapshot, policy: MaturationPolicy): string | null;

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

@@ -0,0 +1,40 @@
+import { candidateRetentionDeadline, retainLearningCandidates, validateMaturationPolicy } from "./retention.js";
+/** Call at an actual expiry/configuration change, not on a frequent polling loop. */
+export async function maintainLearningMemory(repository, policy, now) {
+    validateMaturationPolicy(policy);
+    const initial = await repository.read();
+    const planned = retentionState(initial, policy, now);
+    if (!hasLearningRetentionChanges(planned.result))
+        return planned.result;
+    let result = planned.result;
+    await repository.update((current) => {
+        const retained = retentionState(current, current.maturationPolicy ?? policy, now);
+        result = retained.result;
+        return { ...current, learningCandidates: retained.candidates, learningReceipts: retained.receipts };
+    });
+    return result;
+}
+export function nextLearningExpiryAt(snapshot, policy) {
+    validateMaturationPolicy(policy);
+    let earliest = Infinity;
+    for (const candidate of snapshot.learningCandidates ?? [])
+        earliest = Math.min(earliest, candidateRetentionDeadline(candidate, policy));
+    for (const receipt of snapshot.learningReceipts ?? [])
+        earliest = Math.min(earliest, Date.parse(receipt.expiresAt));
+    return Number.isFinite(earliest) ? new Date(earliest).toISOString() : null;
+}
+function retentionState(snapshot, policy, now) {
+    const candidates = retainLearningCandidates(snapshot.learningCandidates ?? [], policy, now);
+    const receipts = (snapshot.learningReceipts ?? []).filter((receipt) => Date.parse(receipt.expiresAt) > now);
+    const result = {
+        removedCandidateCount: (snapshot.learningCandidates?.length ?? 0) - candidates.length,
+        removedReceiptCount: (snapshot.learningReceipts?.length ?? 0) - receipts.length,
+        nextExpiryAt: nextLearningExpiryAt({ ...snapshot, learningCandidates: candidates, learningReceipts: receipts }, policy),
+    };
+    return { candidates, receipts, result };
+}
+function hasLearningRetentionChanges(result) {
+    if (result.removedCandidateCount > 0)
+        return true;
+    return result.removedReceiptCount > 0;
+}

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

@@ -0,0 +1,12 @@
+import type { LongTermMemoryRecord } from "../contracts.js";
+import type { LearningCandidateRecord, LearningMemoryDecision } from "./contracts.js";
+import type { LearningMemoryReplacement } from "./evidence-contracts.js";
+/** Content changes to established memory go through the same candidate gate. */
+export declare function prepareLearningMemoryUpdate(decision: LearningMemoryDecision, records: ReadonlyMap<string, LongTermMemoryRecord>, candidates: ReadonlyMap<string, LearningCandidateRecord>): {
+    id: string;
+    previous?: LearningCandidateRecord;
+    replacement?: LearningMemoryReplacement;
+    unchanged?: LongTermMemoryRecord;
+};
+export declare function canCommitLearningReplacement(candidate: LearningCandidateRecord, records: ReadonlyMap<string, LongTermMemoryRecord>): boolean;
+export declare function updateMemoryReviewDeadline(record: LongTermMemoryRecord, reconsiderAt: string | null, candidates: Map<string, LearningCandidateRecord>, now: number): LongTermMemoryRecord;

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

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+import { canAutomaticallyManageMemory } from "../automatic-management.js";
+import { normalizeMemoryText } from "../policies/normalization.js";
+/** Content changes to established memory go through the same candidate gate. */
+export function prepareLearningMemoryUpdate(decision, records, candidates) {
+    if (decision.targetKind !== "memory") {
+        const id = decision.targetId ?? randomUUID();
+        const previous = candidates.get(id);
+        return { id, previous, replacement: previous?.replacement };
+    }
+    const record = records.get(decision.targetId);
+    if (!record || !canAutomaticallyManageMemory(record))
+        throw new Error("learning_memory_protected");
+    if (decision.action !== "merge" && hasUnchangedMemoryKnowledge(record, decision))
+        return { id: record.id, unchanged: record };
+    const contentKey = normalizeMemoryText(decision.content);
+    const previous = [...candidates.values()].find(candidate => candidate.replacement?.id === record.id && candidate.replacement.version === record.updatedAt &&
+        normalizeMemoryText(candidate.content) === contentKey);
+    return { id: previous?.id ?? randomUUID(), previous, replacement: { id: record.id, version: record.updatedAt } };
+}
+export function canCommitLearningReplacement(candidate, records) {
+    if (!candidate.replacement)
+        return true;
+    const target = records.get(candidate.replacement.id);
+    if (!target || !canAutomaticallyManageMemory(target))
+        return false;
+    return target.updatedAt === candidate.replacement.version;
+}
+export function updateMemoryReviewDeadline(record, reconsiderAt, candidates, now) {
+    if ((record.reconsiderAt ?? null) === reconsiderAt)
+        return record;
+    const updatedAt = new Date(Math.max(now, Date.parse(record.updatedAt) + 1)).toISOString();
+    for (const [id, candidate] of candidates) {
+        if (candidate.replacement?.id === record.id && candidate.replacement.version === record.updatedAt)
+            candidates.set(id, { ...candidate, replacement: { id: record.id, version: updatedAt } });
+    }
+    return { ...record, reconsiderAt, updatedAt };
+}
+function hasUnchangedMemoryKnowledge(record, decision) {
+    if (record.content !== decision.content)
+        return false;
+    return JSON.stringify(record.tags) === JSON.stringify(decision.tags);
+}

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

@@ -0,0 +1,4 @@
+import type { LongTermMemoryRepositorySnapshot } from "../contracts.js";
+import type { LearningKnowledgeContext } from "./contracts.js";
+/** Bounded recent/due index for proactive review; no embedding or full-store projection. */
+export declare function learningKnowledgeOverview(snapshot: LongTermMemoryRepositorySnapshot, now: number): LearningKnowledgeContext;

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

@@ -0,0 +1,30 @@
+import { candidateKnowledge, memoryKnowledge } from "./context.js";
+import { isCandidateUnexpired } from "./retention.js";
+/** Bounded recent/due index for proactive review; no embedding or full-store projection. */
+export function learningKnowledgeOverview(snapshot, now) {
+    const candidates = (snapshot.learningCandidates ?? []).filter((record) => isCandidateUnexpired(record, now));
+    const entries = [
+        ...candidates.map((record) => ({ entry: candidateKnowledge(record), updatedAt: record.updatedAt })),
+        ...snapshot.records.map((record) => ({ entry: memoryKnowledge(record), updatedAt: record.updatedAt })),
+    ].sort((a, b) => duePriority(b.entry, now) - duePriority(a.entry, now) || b.updatedAt.localeCompare(a.updatedAt));
+    const selected = [];
+    let size = 0;
+    for (const { entry } of entries) {
+        if (selected.length >= 12)
+            break;
+        const length = JSON.stringify(entry).length;
+        if (length + size > 24_000)
+            continue;
+        selected.push(entry);
+        size += length;
+    }
+    return { 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(now).toISOString(), entries: selected, omitted: entries.length - selected.length };
+}
+function duePriority(entry, now) {
+    if (entry.reconsiderAt && Date.parse(entry.reconsiderAt) <= now)
+        return 1;
+    return 0;
+}

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

@@ -0,0 +1,5 @@
+import type { LongTermMemoryRepository, LongTermMemoryRepositorySnapshot } from "../contracts.js";
+import type { MaturationPolicy } from "./contracts.js";
+/** The repository is the sole policy owner, including while collection is off. */
+export declare function learningMaturationPolicy(snapshot: LongTermMemoryRepositorySnapshot): MaturationPolicy;
+export declare function configureLearningMaturationPolicy(repository: LongTermMemoryRepository, requested: MaturationPolicy, initializeOnly?: boolean): Promise<MaturationPolicy>;