@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/runtime/passive-learning/service.js

@@ -0,0 +1,469 @@
+import { randomUUID } from "node:crypto";
+import { projectLearningMaturationPreferences, commitLearningMaturationPreferences } from "./maturation-preferences.js";
+import { isWithinAnalysisWindow } from "./analysis-schedule.js";
+import { canRestartPermissionBlockedCollection, hasAnalysisScheduleChanged, hasLearningMemoryWriter, requiresCollectionConnection, requiresLearningAvailability, } from "./control-policy.js";
+import { LearningAnalysisClock } from "./analysis-clock.js";
+import { LearningCollectionSource } from "./collection-source.js";
+import { CollectionWindowClock } from "./collection-window-clock.js";
+import { LearningActiveBatches } from "./active-batches.js";
+import { buildLearningServiceStatus } from "./service-status.js";
+import { readLearningBatchReceipt } from "./batch-receipt.js";
+import { LearningProcessingCycle } from "./processing-cycle.js";
+import { LearningBackgroundLifecycle } from "./background-lifecycle.js";
+import { validateLearningActivityModels } from "./activity-permissions.js";
+import { createPendingLearningBatch } from "./batch-lifecycle.js";
+import { LearningJournal } from "./journal.js";
+import { ObservationQueue } from "./queue.js";
+import { canProcessLearningObservation, isLearningApplicationExcluded } from "./application-policy.js";
+import { commitLearningApplicationPreferences } from "./application-controls.js";
+import { learningFailureReason, summarizeBatch, } from "./status-projection.js";
+import { DEFAULT_LEARNING_PREFERENCES, normalizeLearningPreferences, } from "./store.js";
+export function createPassiveLearningService(options) {
+    const service = new LearningService(options);
+    return Object.freeze({
+        start: () => service.start(),
+        stop: () => service.stop(),
+        configure: (input) => service.configure(input),
+        status: () => service.status(),
+        clearPending: () => service.clearPending(),
+        restartCollection: () => service.restartCollection(),
+        batches: (input) => service.batches(input),
+        batch: (id) => service.batch(id),
+        accept: (event) => service.accept(event),
+        flush: () => service.flush(),
+        beginInteractive: () => service.beginInteractive(),
+        subscribe: (listener) => service.subscribe(listener),
+        dismissProposal: (id) => service.dismissProposal(id),
+        sessionDeleted: (id) => service.sessionDeleted(id),
+        notifyKnowledgeChanged: () => service.notifyKnowledgeChanged(),
+        candidates: () => service.candidates(),
+    });
+}
+class LearningService {
+    options;
+    background;
+    journal;
+    queue = new ObservationQueue((item) => canProcessLearningObservation(item, this.preferences));
+    preferences = DEFAULT_LEARNING_PREFERENCES;
+    state = "off";
+    reason;
+    processingReason;
+    processingUnavailable = false;
+    generation = randomUUID();
+    deviceId;
+    lastObservationAt;
+    started = false;
+    initialized = false;
+    closing = false;
+    changingApplications = false;
+    interactive = 0;
+    source;
+    collectionClock;
+    clock;
+    active = new LearningActiveBatches();
+    processingCycle;
+    backgroundLifecycle;
+    controls = Promise.resolve();
+    sequences = new Map();
+    listeners = new Set();
+    constructor(options) {
+        this.options = options;
+        this.background = options.backgroundDependencies?.({
+            preferences: () => this.preferences,
+            changed: (event) => this.changed(event),
+            isInteractiveBusy: () => this.isInteractiveBusy(),
+            isStarted: () => this.started,
+            isProcessingBusy: () => this.processingUnavailable || this.active.size > 0 || this.processingCycle.hasReadyWork(),
+            assertProcessingAllowed: () => {
+                if (!this.canProcess())
+                    throw new Error("learning_processing_paused");
+                if (!isWithinAnalysisWindow(this.now(), this.preferences.analysisWindow))
+                    throw new Error("learning_outside_processing_window");
+            },
+        }) ?? { memory: options.memory, model: options.model };
+        this.clock = new LearningAnalysisClock(() => {
+            void this.flush().catch((error) => this.failProcessing(error));
+        }, () => this.now());
+        this.backgroundLifecycle = new LearningBackgroundLifecycle({ background: this.background,
+            changed: () => this.changed() });
+        this.source = new LearningCollectionSource({
+            ownerId: options.ownerId,
+            connect: options.connect,
+            enabled: () => this.canCollect(),
+            excludedApplications: () => this.preferences.excludedApplications,
+            opening: () => {
+                this.sequences.clear();
+                this.state = "starting";
+                this.reason = undefined;
+                this.changed();
+            },
+            event: (event) => this.accept(event),
+            failed: (error) => this.failFeature(error),
+        });
+        this.collectionClock = new CollectionWindowClock({
+            enabled: () => this.started && this.preferences.enabled,
+            window: () => this.preferences.collectionWindow,
+            now: () => this.now(), open: () => this.source.open(),
+            close: () => {
+                this.source.close();
+                this.state = "off";
+                this.deviceId = undefined;
+                this.reason = this.preferences.enabled ? "learning_outside_collection_window" : undefined;
+                this.changed();
+            },
+            boundary: () => { void this.collectionClock.synchronize().catch((error) => this.failFeature(error)); },
+        });
+        this.journal = new LearningJournal({
+            directory: options.directory,
+            now: () => this.now(),
+            preferences: () => this.preferences,
+            changed: () => {
+                this.changed();
+                this.arm();
+            },
+            failed: (error) => this.failProcessing(error),
+            receipt: (batchId) => readLearningBatchReceipt(this.background.memory, batchId),
+        });
+        this.processingCycle = new LearningProcessingCycle({
+            background: this.background, queue: this.queue, journal: this.journal, active: this.active, clock: this.clock,
+            preferences: () => this.preferences, canProcess: () => this.canProcess(), generation: () => this.generation,
+            canReconcileReceipts: () => this.canReconcileReceipts(),
+            now: () => this.now(), intervalMs: () => this.intervalMs(), concurrency: () => this.effectiveConcurrency(),
+            dispatch: (batch) => this.dispatch(batch), arm: () => this.arm(),
+            deferred: () => { this.processingReason = undefined; this.changed(); },
+        });
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+    timestamp() {
+        return new Date(this.now()).toISOString();
+    }
+    start() {
+        return this.control(async () => {
+            if (this.started)
+                return;
+            this.started = true;
+            try {
+                await this.initialize();
+                await this.journal.start();
+                this.queue.startExpiry({
+                    now: () => this.now(),
+                    changed: () => { this.changed(); this.arm(); },
+                });
+                const shouldValidateAnalysisOnStart = this.preferences.modelProfileId && !this.preferences.processingPaused;
+                this.processingUnavailable = false;
+                if (shouldValidateAnalysisOnStart) {
+                    await this.requireAvailable(this.preferences).then(() => { this.processingReason = undefined; }).catch((error) => {
+                        this.processingUnavailable = true;
+                        this.failProcessing(error);
+                    });
+                }
+                await this.backgroundLifecycle.start();
+                await this.collectionClock.synchronize();
+                this.arm();
+            }
+            catch (error) {
+                this.failProcessing(error);
+            }
+        });
+    }
+    stop() {
+        return this.control(async () => {
+            if (!this.started)
+                return;
+            this.started = false;
+            this.collectionClock.stop();
+            this.deviceId = undefined;
+            this.clock.clear();
+            this.active.abort("learning_stopped");
+            await Promise.all([this.active.settle(), this.backgroundLifecycle.stop()]);
+            await this.preserveQueued();
+            this.queue.stopExpiry();
+            this.journal.stop();
+            this.state = "off";
+            this.changed();
+        });
+    }
+    configure(input) {
+        return this.control(async () => {
+            await this.initialize();
+            let next = normalizeLearningPreferences(input, this.preferences);
+            const previous = this.preferences;
+            validateLearningActivityModels(previous, next, (profile) => this.background.model.validateProfile(profile));
+            const validateProcessing = requiresLearningAvailability(previous, next, this.processingUnavailable, input);
+            if (validateProcessing)
+                await this.requireAvailable(next);
+            await this.backgroundLifecycle.validatePreferences(previous, next);
+            try {
+                await commitLearningApplicationPreferences({ previous, next, active: this.active,
+                    suspend: () => {
+                        this.changingApplications = true;
+                        this.clock.clear();
+                        return () => { this.changingApplications = false; this.arm(); };
+                    },
+                    commit: async () => {
+                        next = await commitLearningMaturationPreferences(this.background.memory, next, input, { previous, persist: (value) => this.journal.persist(value) });
+                        this.preferences = next;
+                    },
+                });
+            }
+            catch (error) {
+                this.failProcessing(error);
+                throw error;
+            }
+            if (validateProcessing) {
+                this.processingUnavailable = false;
+                this.processingReason = undefined;
+            }
+            this.processingCycle.preferencesChanged(previous, next, validateProcessing);
+            this.clock.clear(hasAnalysisScheduleChanged(previous, next));
+            if (next.processingPaused) {
+                this.active.abort("learning_processing_paused");
+                await this.active.settle();
+            }
+            if (!next.enabled || next.processingPaused)
+                await this.preserveQueued();
+            await this.collectionClock.synchronize(requiresCollectionConnection(previous, next));
+            await this.processingCycle.reconcile().catch((error) => this.failProcessing(error));
+            await this.backgroundLifecycle.preferencesChanged();
+            this.arm();
+            this.changed();
+            return this.status();
+        });
+    }
+    restartCollection() {
+        return this.control(async () => {
+            if (canRestartPermissionBlockedCollection(this.canCollect(), this.state))
+                await this.collectionClock.synchronize(true);
+            return this.status();
+        });
+    }
+    async status() {
+        this.queue.expire(this.now());
+        return buildLearningServiceStatus({ background: this.background, preferences: this.preferences,
+            history: this.journal.items, state: this.state, reason: this.reason, processingReason: this.processingReason,
+            budgetReason: this.processingCycle.deferral?.reason, deviceId: this.deviceId, lastObservationAt: this.lastObservationAt,
+            queued: this.queue.items, dropped: this.queue.dropped, active: this.active.size, reviewPassRemaining: this.processingCycle.remainingPass(),
+            concurrency: this.effectiveConcurrency(), nextAnalysisAt: this.clock.scheduledAt,
+            nextCollectionAt: this.collectionClock.scheduledAt, maintenanceReason: this.backgroundLifecycle.maintenanceReason,
+            proactiveStartupReason: this.backgroundLifecycle.proactiveStartupReason,
+            reassessmentStartupReason: this.backgroundLifecycle.reassessmentStartupReason });
+    }
+    async batches(input = {}) {
+        const limit = Math.min(50, Math.max(1, Math.floor(input.limit ?? 20)));
+        return this.journal.items.slice(-limit).reverse().map(summarizeBatch);
+    }
+    async batch(id) {
+        const found = this.journal.items.find((batch) => batch.id === id);
+        if (!found)
+            return undefined;
+        const { reviewProgress: _reviewProgress, ...detail } = found;
+        return detail;
+    }
+    accept(event) {
+        if (!this.source.accepts(event))
+            return;
+        if (this.deviceId && this.deviceId !== event.deviceId) {
+            this.state = "unavailable";
+            this.reason = "learning_device_changed";
+            this.source.close();
+            this.changed();
+            return;
+        }
+        this.deviceId = event.deviceId;
+        if (event.type === "status") {
+            this.state = event.state;
+            this.reason = event.reason;
+            this.changed();
+            return;
+        }
+        const observation = event.observation;
+        const previous = this.sequences.get(event.deviceId) ?? -1;
+        if (observation.sequence <= previous)
+            return;
+        if (previous >= 0 && observation.sequence > previous + 1)
+            this.queue.dropped += observation.sequence - previous - 1;
+        this.sequences.set(event.deviceId, observation.sequence);
+        if (isLearningApplicationExcluded(observation.source.app, this.preferences.excludedApplications))
+            return;
+        this.lastObservationAt = observation.timestamp;
+        if (!this.queue.add({ ...observation, deviceId: event.deviceId }, this.now()))
+            return;
+        this.changed();
+        this.arm();
+    }
+    flush() {
+        return this.processingCycle.flush();
+    }
+    beginInteractive() {
+        this.interactive += 1;
+        const releaseBackground = this.backgroundLifecycle.beginInteractive();
+        this.clock.clear();
+        this.active.abort("learning_interactive_preempted");
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.interactive -= 1;
+            releaseBackground();
+            this.arm();
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    dispatch(batch) {
+        this.active.dispatch({
+            batch,
+            modelProfileId: this.preferences.modelProfileId,
+            model: this.background.model,
+            memory: this.background.memory,
+            ownerId: this.options.ownerId,
+            isCurrent: () => batch.generation === this.generation,
+            timestamp: () => this.timestamp(),
+            replace: (value) => this.journal.replace(value),
+            partition: (values) => this.journal.partition(values),
+            failed: (error) => this.failProcessing(error),
+            succeeded: () => {
+                this.processingReason = undefined;
+                this.notifyKnowledgeChanged();
+                this.changed();
+            },
+        }, () => {
+            this.changed();
+            this.arm();
+            this.background.reassessment?.knowledgeChanged();
+        });
+        this.changed();
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.preferences = await projectLearningMaturationPreferences(this.background.memory, await this.journal.load(this.generation), true);
+        this.initialized = true;
+    }
+    async requireAvailable(preferences) {
+        if (!preferences.modelProfileId)
+            throw new Error("learning_model_required");
+        this.background.model.validateProfile(preferences.modelProfileId);
+        const memory = await this.background.memory.status();
+        if (!memory.enabled ||
+            !memory.available ||
+            !hasLearningMemoryWriter(this.background))
+            throw new Error("learning_memory_unavailable");
+    }
+    clearPending() {
+        return this.control(async () => {
+            await this.initialize();
+            this.closing = true;
+            this.generation = randomUUID();
+            this.clock.clear();
+            this.queue.clear();
+            this.active.abort("learning_pending_deleted");
+            try {
+                await this.active.settle();
+                await this.journal.clearPending();
+            }
+            finally {
+                this.closing = false;
+                this.changed();
+                this.arm();
+            }
+            return this.status();
+        });
+    }
+    async preserveQueued() {
+        const pending = [];
+        while (this.queue.length) {
+            const observations = this.queue.take(this.now());
+            if (!observations.length)
+                break;
+            pending.push(createPendingLearningBatch(observations, this.generation, this.now()));
+        }
+        if (pending.length)
+            await this.journal.replaceMany(pending);
+    }
+    canProcess() {
+        if (!this.canReconcileReceipts())
+            return false;
+        return !this.isInteractiveBusy();
+    }
+    canReconcileReceipts() {
+        if (this.processingUnavailable)
+            return false;
+        if (!this.started || this.closing || this.changingApplications || !this.journal.storageAvailable)
+            return false;
+        if (this.preferences.processingPaused || !this.preferences.modelProfileId)
+            return false;
+        return true;
+    }
+    isInteractiveBusy() { return this.interactive > 0 || this.options.isInteractiveBusy?.() === true; }
+    canCollect() {
+        if (!this.started || !this.preferences.enabled)
+            return false;
+        return isWithinAnalysisWindow(this.now(), this.preferences.collectionWindow);
+    }
+    effectiveConcurrency() {
+        const profile = this.preferences.modelProfileId;
+        if (!profile)
+            return 1;
+        try {
+            return this.background.model.supportsParallelBatches?.(profile)
+                ? (this.preferences.maxConcurrentBatches ?? 1)
+                : 1;
+        }
+        catch {
+            return 1;
+        }
+    }
+    intervalMs() {
+        return (this.options.batchDelayMs ??
+            (this.preferences.analysisIntervalMinutes ?? 15) * 60_000);
+    }
+    arm() {
+        if (!this.canProcess() || this.active.size >= this.effectiveConcurrency())
+            return;
+        if (!this.processingCycle.hasReadyWork()) {
+            this.clock.clear();
+            return;
+        }
+        this.clock.arm(this.now(), this.processingCycle.delayMs(), this.preferences.analysisWindow, this.processingCycle.deferral?.until);
+    }
+    async dismissProposal(id) {
+        if (!this.background.proactive)
+            throw new Error("proactive_unavailable");
+        await this.background.proactive.dismiss(id);
+    }
+    notifyKnowledgeChanged() {
+        this.backgroundLifecycle.knowledgeChanged();
+    }
+    async sessionDeleted(sessionId) { await this.background.proactive?.sessionDeleted?.(sessionId); }
+    async candidates() {
+        const records = await this.background.memory.learning?.list() ?? [];
+        return records.map(({ embedding: _embedding, ...record }) => record);
+    }
+    changed(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch { }
+        }
+    }
+    failFeature(error) {
+        this.reason = learningFailureReason(error);
+        this.state =
+            this.reason === "learning_host_unavailable" ? "unavailable" : "failed";
+        this.changed();
+    }
+    failProcessing(error) {
+        this.processingReason = this.processingCycle?.noteFailure(error) ? undefined : learningFailureReason(error);
+        this.changed();
+    }
+    control(operation) {
+        const next = this.controls.then(operation);
+        this.controls = next.catch(() => { });
+        return next;
+    }
+}

package/dist/src/runtime/passive-learning/staged-learning-assessment.d.ts

@@ -0,0 +1,11 @@
+import type { StagedReviewCall } from "./staged-review-call.js";
+import type { LearningReviewSelection } from "./staged-learning-selection.js";
+import type { LearningReviewDraft } from "./staged-learning-authoring.js";
+import { type LearningStagePresentation } from "./staged-learning-stage.js";
+export type LearningReviewAssessment = Readonly<{
+    ref: string;
+    score: number;
+    certainty: "observed" | "inferred";
+    reinforced?: boolean;
+}>;
+export declare function assessLearningChanges(selections: readonly LearningReviewSelection[], drafts: readonly LearningReviewDraft[], presentation: LearningStagePresentation, call: StagedReviewCall): Promise<readonly LearningReviewAssessment[]>;

package/dist/src/runtime/passive-learning/staged-learning-assessment.js

@@ -0,0 +1,30 @@
+import { learningAssignmentEvidence, learningStageObject, runLearningStage } from "./staged-learning-stage.js";
+export async function assessLearningChanges(selections, drafts, presentation, call) {
+    const writes = drafts.filter(draft => draft.content !== undefined);
+    if (!writes.length)
+        return [];
+    const scheduled = presentation.references.scheduled;
+    return runLearningStage({
+        call, stage: "assessment", maximum: writes.length, requiredRefs: writes.map(draft => draft.ref),
+        variants: writes.map(draft => {
+            const selection = selections.find(item => item.ref === draft.ref);
+            const target = selection.target === null ? undefined : presentation.references.knowledge.get(selection.target);
+            const maximum = maximumAssessmentScore(target, scheduled);
+            return learningStageObject({
+                ref: { type: "string", enum: [draft.ref] }, score: { type: "integer", minimum: 0, maximum },
+                certainty: { type: "string", enum: ["observed", "inferred"] },
+                ...(scheduled || selection.action === "create" ? {} : { reinforced: { type: "boolean" } }),
+            });
+        }),
+        instruction: "Assess each fixed knowledge draft against its original evidence. Score 0–100 measures usefulness and support, not probability or promotion permission. Tentative interests should start modestly. Set certainty to observed only for a directly supported fact; possible interests are inferred. Where reinforced is requested, true requires substantive independent new support; unchanged revisits or reanalysis are false. Scheduled reviews have no new evidence and cannot raise candidate scores. Do not rewrite the draft, pick actions or schedule reviews.",
+        context: { scheduled, assignments: writes.map(draft => ({ draft,
+                ...learningAssignmentEvidence(presentation, selections.find(item => item.ref === draft.ref)) })) },
+    });
+}
+function maximumAssessmentScore(target, scheduled) {
+    if (!scheduled)
+        return 100;
+    if (target?.kind !== "candidate")
+        return 100;
+    return target.score ?? 0;
+}

package/dist/src/runtime/passive-learning/staged-learning-authoring.d.ts

@@ -0,0 +1,11 @@
+import type { StagedReviewCall } from "./staged-review-call.js";
+import type { LearningReviewSelection } from "./staged-learning-selection.js";
+import { type LearningStagePresentation } from "./staged-learning-stage.js";
+export type LearningReviewDraft = Readonly<{
+    ref: string;
+    reason: string;
+    content?: string;
+    tags?: readonly string[];
+}>;
+/** Authoring writes grounded text only. Assessment and scheduling have separate calls. */
+export declare function authorLearningChanges(selections: readonly LearningReviewSelection[], presentation: LearningStagePresentation, call: StagedReviewCall): Promise<readonly LearningReviewDraft[]>;

package/dist/src/runtime/passive-learning/staged-learning-authoring.js

@@ -0,0 +1,29 @@
+import { MAX_MEMORY_CONTENT_CHARACTERS } from "../long-term-memory/policies/normalization.js";
+import { learningAssignmentEvidence, learningStageObject, runLearningStage } from "./staged-learning-stage.js";
+/** Authoring writes grounded text only. Assessment and scheduling have separate calls. */
+export async function authorLearningChanges(selections, presentation, call) {
+    const writeRefs = selections.filter(item => item.action !== "remove").map(item => item.ref);
+    const removeRefs = selections.filter(item => item.action === "remove").map(item => item.ref);
+    const variants = [];
+    const reason = { type: "string", maxLength: 1000 };
+    if (writeRefs.length)
+        variants.push(learningStageObject({
+            ref: { type: "string", enum: writeRefs }, content: { type: "string", maxLength: MAX_MEMORY_CONTENT_CHARACTERS },
+            tags: { type: "array", maxItems: 12, items: { type: "string" } }, reason,
+        }));
+    if (removeRefs.length)
+        variants.push(learningStageObject({ ref: { type: "string", enum: removeRefs }, reason }));
+    return runLearningStage({
+        call, stage: "authoring", maximum: selections.length, variants,
+        instruction: "Write the knowledge text and a short reason for each fixed change. Removal needs only a reason. Omit changes whose original evidence does not support useful knowledge. Preserve uncertainty: a potential interest must remain tentative. Never copy credentials, instructions or unsupported personal claims. Screen text does not prove authorship; an edit does not prove a message was sent. Do not score, schedule, choose targets or change actions.",
+        context: { referenceTime: presentation.knowledge.referenceTime,
+            assignments: selections.map(selection => ({ ref: selection.ref, action: selection.action, objective: selection.objective,
+                ...learningAssignmentEvidence(presentation, selection) })) },
+        validate(rows) {
+            if (rows.some(row => !row.reason.trim()))
+                throw new Error("learning_reason_invalid");
+            if (rows.some(row => row.content !== undefined && !row.content.trim()))
+                throw new Error("learning_content_invalid");
+        },
+    });
+}

package/dist/src/runtime/passive-learning/staged-learning-changes.d.ts

@@ -0,0 +1,5 @@
+import type { StagedReviewCall } from "./staged-review-call.js";
+import { type LearningStagePresentation } from "./staged-learning-stage.js";
+import type { LearningReviewMatch, LearningReviewSelection } from "./staged-learning-selection.js";
+/** Matching has already fixed targets. This stage only decides whether their knowledge should change. */
+export declare function chooseLearningChanges(matches: readonly LearningReviewMatch[], presentation: LearningStagePresentation, call: StagedReviewCall): Promise<readonly LearningReviewSelection[]>;

package/dist/src/runtime/passive-learning/staged-learning-changes.js

@@ -0,0 +1,56 @@
+import { learningAssignmentEvidence, learningStageObject, runLearningStage } from "./staged-learning-stage.js";
+/** Matching has already fixed targets. This stage only decides whether their knowledge should change. */
+export async function chooseLearningChanges(matches, presentation, call) {
+    const existing = matches.filter(match => match.target !== null);
+    const selected = matches.filter(match => match.target === null).map(match => ({
+        ...match, action: "create", sources: [],
+    }));
+    if (!existing.length)
+        return selected;
+    const choices = await runLearningStage({
+        call, stage: "change", maximum: existing.length,
+        variants: existing.map(match => learningStageObject({
+            ref: { type: "string", enum: [match.ref] },
+            change: { type: "string", enum: ["keep", "revise", "remove", ...(availableMergeSources(match, matches, presentation).length ? ["combine"] : [])] },
+        })),
+        instruction: "For each bound entry choose keep, revise, or remove. Choose combine only when equivalent candidate entries should be consolidated into this target. Keep means no useful new evidence or change. Revise can add substantive support to a candidate even without rewriting its meaning. Remove requires evidence that the entry is no longer useful or valid. A passing date alone never proves an event happened. Omitted entries are kept. Do not select targets or sources, write replacement content, or score anything.",
+        context: { referenceTime: presentation.knowledge.referenceTime, scheduled: presentation.references.scheduled,
+            assignments: existing.map(match => ({ ref: match.ref, objective: match.objective,
+                ...learningAssignmentEvidence(presentation, match),
+                possibleMergeSources: availableMergeSources(match, matches, presentation).map(ref => presentation.knowledge.entries.find(entry => entry.ref === ref)),
+            })) },
+    });
+    const usedSources = new Set();
+    for (const choice of choices) {
+        if (choice.change === "keep")
+            continue;
+        const match = existing.find(item => item.ref === choice.ref);
+        if (choice.change !== "combine") {
+            selected.push({ ...match, action: choice.change === "remove" ? "remove" : "update", sources: [] });
+            continue;
+        }
+        const allowed = availableMergeSources(match, matches, presentation).filter(source => !usedSources.has(source));
+        if (!allowed.length)
+            continue;
+        const rows = await runLearningStage({
+            call, stage: `merge_${match.ref}`, maximum: 1,
+            variants: [learningStageObject({ ref: { type: "string", enum: [match.ref] },
+                    sources: { type: "array", minItems: 1, maxItems: 12, items: { type: "string", enum: allowed } } })],
+            instruction: "Select equivalent candidate sources to combine into the fixed target. Only select supplied references. Return an empty decisions array if no source is equivalent. Do not change the target, write merged content, or set scores.",
+            context: { target: learningAssignmentEvidence(presentation, match).target,
+                candidates: presentation.knowledge.entries.filter(entry => allowed.includes(entry.ref)) },
+        });
+        const sources = rows[0]?.sources;
+        if (!sources?.length)
+            continue;
+        sources.forEach(source => usedSources.add(source));
+        selected.push({ ...match, action: "merge", sources: [...new Set(sources)] });
+    }
+    return selected;
+}
+function availableMergeSources(match, matches, presentation) {
+    if (presentation.references.scheduled)
+        return [];
+    const occupied = new Set(matches.flatMap(item => item.target === null ? [] : [item.target]));
+    return presentation.references.mergeRefs.filter(source => source !== match.target && !occupied.has(source));
+}

package/dist/src/runtime/passive-learning/staged-learning-review.d.ts

@@ -0,0 +1,5 @@
+import { type LearningReviewInput } from "./review-references.js";
+import type { StagedReviewCall } from "./staged-review-call.js";
+export declare const MAX_STAGED_LEARNING_CALLS = 18;
+/** Stage outputs remain proposals; the existing repository owns the single atomic apply. */
+export declare function runStagedLearningReview(input: LearningReviewInput, call: StagedReviewCall): Promise<readonly import("../long-term-memory/maturation/contracts.js").LearningMemoryDecision[]>;