@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/passive-learning/processing-cycle.d.ts

@@ -0,0 +1,42 @@
+import type { LearningAnalysisClock } from "./analysis-clock.js";
+import type { LearningActiveBatches } from "./active-batches.js";
+import type { LearningBackgroundDependencies } from "./background-dependencies.js";
+import type { LearningBatch, PassiveLearningPreferences } from "./contracts.js";
+import type { LearningJournal } from "./journal.js";
+import type { ObservationQueue } from "./queue.js";
+import { type LearningBudgetDeferral } from "./processing-budget-policy.js";
+/** One admitted processing cycle; async quota checks cannot duplicate dequeues. */
+export declare class LearningProcessingCycle {
+    private readonly options;
+    deferral: LearningBudgetDeferral | undefined;
+    private running;
+    private lastUsage;
+    private readonly pass;
+    constructor(options: Readonly<{
+        background: LearningBackgroundDependencies;
+        queue: ObservationQueue;
+        journal: LearningJournal;
+        active: LearningActiveBatches;
+        clock: LearningAnalysisClock;
+        preferences(): PassiveLearningPreferences;
+        canReconcileReceipts(): boolean;
+        canProcess(): boolean;
+        generation(): string;
+        now(): number;
+        intervalMs(): number;
+        concurrency(): number;
+        dispatch(batch: LearningBatch): void;
+        arm(): void;
+        deferred(): void;
+    }>);
+    flush(): Promise<void>;
+    reconcile(): Promise<void>;
+    hasReadyWork(): boolean;
+    remainingPass(): number;
+    preferencesChanged(previous: PassiveLearningPreferences, next: PassiveLearningPreferences, availabilityValidated?: boolean): void;
+    delayMs(): number;
+    noteFailure(error: unknown): boolean;
+    private deferredFailureRetryAt;
+    private isProcessingAllowed;
+    private run;
+}

package/dist/src/runtime/passive-learning/processing-cycle.js

@@ -0,0 +1,155 @@
+import { isWithinAnalysisWindow } from "./analysis-schedule.js";
+import { createPendingLearningBatch, isDeferredLearningFailure } from "./batch-lifecycle.js";
+import { availableLearningBatchSlots, isLearningDailyBudgetFailure, learningBudgetDeferral, learningBatchEmbeddingCalls } from "./processing-budget-policy.js";
+import { canProcessLearningBatch } from "./application-policy.js";
+import { prepareApplicationPendingBatch } from "./application-pending.js";
+import { reconcileLearningBatchReceipts } from "./batch-receipt.js";
+import { isObservationTriggered } from "./processing-trigger.js";
+import { LearningProcessingPass } from "./processing-pass.js";
+import { hasLearningProcessingConfigurationChanged } from "./control-policy.js";
+/** One admitted processing cycle; async quota checks cannot duplicate dequeues. */
+export class LearningProcessingCycle {
+    options;
+    deferral;
+    running;
+    lastUsage;
+    pass;
+    constructor(options) {
+        this.options = options;
+        this.pass = new LearningProcessingPass(options);
+    }
+    flush() {
+        this.running ??= this.run().finally(() => { this.running = undefined; });
+        return this.running;
+    }
+    async reconcile() {
+        if (!this.options.canReconcileReceipts())
+            return;
+        await reconcileLearningBatchReceipts({ ...this.options, memory: this.options.background.memory });
+    }
+    hasReadyWork() {
+        return this.pass.hasReadyWork();
+    }
+    remainingPass() { return this.pass.remaining(); }
+    preferencesChanged(previous, next, availabilityValidated = false) {
+        if (availabilityValidated || hasLearningProcessingConfigurationChanged(previous, next))
+            this.deferral = undefined;
+    }
+    delayMs() {
+        if (isObservationTriggered(this.options.preferences()))
+            return 0;
+        return this.options.intervalMs();
+    }
+    noteFailure(error) {
+        if (!isDeferredLearningFailure(error))
+            return false;
+        const budgetStatus = error.message === "learning_receipt_capacity" || isLearningDailyBudgetFailure(error);
+        const until = this.deferredFailureRetryAt(error);
+        if (this.deferral && this.deferral.until >= until)
+            return budgetStatus;
+        this.deferral = { until, reason: error.message };
+        this.options.clock.clear();
+        return budgetStatus;
+    }
+    deferredFailureRetryAt(error) {
+        const now = this.options.now();
+        const retryAt = now + this.options.intervalMs();
+        if (!isLearningDailyBudgetFailure(error))
+            return retryAt;
+        if (!this.lastUsage || now >= this.lastUsage.resetsAt)
+            return retryAt;
+        return this.lastUsage.resetsAt;
+    }
+    isProcessingAllowed() {
+        if (!this.options.canProcess())
+            return false;
+        if (this.deferral && this.options.now() < this.deferral.until)
+            return false;
+        return isWithinAnalysisWindow(this.options.now(), this.options.preferences().analysisWindow);
+    }
+    async run() {
+        const options = this.options;
+        const cycleStartedAt = options.now();
+        await this.reconcile();
+        if (!this.hasReadyWork()) {
+            options.clock.clear(isObservationTriggered(options.preferences()));
+            return;
+        }
+        if (!this.isProcessingAllowed()) {
+            options.arm();
+            return;
+        }
+        const usage = options.background.resourceUsage ? await options.background.resourceUsage() : undefined;
+        this.lastUsage = usage;
+        if (!this.isProcessingAllowed()) {
+            options.arm();
+            return;
+        }
+        const preferences = options.preferences();
+        const embeddingCallsPerBatch = learningBatchEmbeddingCalls(options.background);
+        this.deferral = learningBudgetDeferral(usage, preferences, embeddingCallsPerBatch);
+        options.clock.clear();
+        if (this.deferral) {
+            options.deferred();
+            options.arm();
+            return;
+        }
+        const admission = options.background.memory.learning?.reviewAdmission
+            ? await options.background.memory.learning.reviewAdmission() : undefined;
+        if (admission && !admission.available) {
+            this.deferral = { until: admission.retryAt ? Date.parse(admission.retryAt) : Number.POSITIVE_INFINITY,
+                reason: "learning_receipt_capacity" };
+            options.deferred();
+            options.arm();
+            return;
+        }
+        if (!this.isProcessingAllowed()) {
+            options.arm();
+            return;
+        }
+        const slots = availableLearningBatchSlots(usage, preferences, options.concurrency() - options.active.size, embeddingCallsPerBatch);
+        if (!slots) {
+            options.clock.dispatched(options.now(), options.intervalMs());
+            options.arm();
+            return;
+        }
+        await this.pass.admit();
+        let dispatched = false;
+        for (let remaining = slots; remaining > 0; remaining -= 1) {
+            if (!this.isProcessingAllowed())
+                break;
+            if (!this.hasReadyWork())
+                break;
+            let pending;
+            try {
+                pending = await prepareApplicationPendingBatch({ ...options, memory: options.background.memory,
+                    eligible: (item) => this.pass.allows(item) });
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== "learning_partition_capacity")
+                    throw error;
+                this.deferral = { until: options.now() + options.intervalMs(), reason: error.message };
+                options.deferred();
+                options.arm();
+                return;
+            }
+            if (!this.isProcessingAllowed())
+                break;
+            if (!this.hasReadyWork())
+                break;
+            if (pending && pending.generation !== options.generation())
+                break;
+            if (pending && !canProcessLearningBatch(pending, options.preferences()))
+                break;
+            const observations = pending?.observations ?? options.queue.take(options.now(), (item) => this.pass.allows(item));
+            if (!observations.length)
+                break;
+            options.dispatch(pending ?? createPendingLearningBatch(observations, options.generation(), options.now()));
+            dispatched = true;
+        }
+        if (dispatched)
+            options.clock.dispatched(cycleStartedAt, this.delayMs());
+        options.arm();
+        await options.active.settle();
+    }
+}

package/dist/src/runtime/passive-learning/processing-pass.d.ts

@@ -0,0 +1,29 @@
+import type { LearningObservation, PassiveLearningPreferences } from "./contracts.js";
+import type { LearningActiveBatches } from "./active-batches.js";
+import type { LearningJournal } from "./journal.js";
+import { type ObservationQueue } from "./queue.js";
+type PassOptions = Readonly<{
+    queue: ObservationQueue;
+    journal: LearningJournal;
+    active: LearningActiveBatches;
+    preferences(): PassiveLearningPreferences;
+    generation(): string;
+    now(): number;
+}>;
+/** A bounded snapshot of work admitted together; fresh intake belongs to the next pass. */
+export declare class LearningProcessingPass {
+    private readonly options;
+    constructor(options: PassOptions);
+    hasReadyWork(): boolean;
+    remaining(): number;
+    admit(): Promise<void>;
+    allows(item: LearningObservation): boolean;
+    private isAdmitted;
+    private canStartPass;
+    private hasUnfinishedPass;
+    private pendingObservations;
+    private isPendingBatch;
+}
+/** Optional metadata for old state files; no screen text or new activity history. */
+export declare function readObservationReviewPass(value: unknown): readonly string[] | undefined;
+export {};

package/dist/src/runtime/passive-learning/processing-pass.js

@@ -0,0 +1,104 @@
+import { hasObservationStoragePressure } from "./queue.js";
+import { canProcessLearningObservation } from "./application-policy.js";
+import { isPendingLearningBatch } from "./batch-lifecycle.js";
+import { hasLearningTriggerWork, isObservationTriggered } from "./processing-trigger.js";
+import { traceDebug } from "../observability/debug-logger.js";
+/** A bounded snapshot of work admitted together; fresh intake belongs to the next pass. */
+export class LearningProcessingPass {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    hasReadyWork() {
+        const pending = this.pendingObservations();
+        if (this.hasUnfinishedPass())
+            return pending.some((item) => this.isAdmitted(item));
+        return this.canStartPass(pending);
+    }
+    remaining() {
+        if (!isObservationTriggered(this.options.preferences()))
+            return 0;
+        return this.pendingObservations().filter((item) => this.isAdmitted(item)).length;
+    }
+    async admit() {
+        const preferences = this.options.preferences();
+        if (!isObservationTriggered(preferences))
+            return;
+        if (this.hasUnfinishedPass())
+            return;
+        const pending = this.pendingObservations();
+        if (!this.canStartPass(pending))
+            return;
+        await this.options.journal.setObservationReviewPass(pending.map(observationReviewKey));
+        traceDebug("runtime.passive_learning", "processing.pass_admitted", {
+            observations: pending.length, threshold: preferences.analysisObservationCount,
+            trigger: hasLearningTriggerWork(preferences, pending.length) ? "count" : "storage_pressure",
+        });
+    }
+    allows(item) {
+        const preferences = this.options.preferences();
+        if (!canProcessLearningObservation(item, preferences))
+            return false;
+        if (!isObservationTriggered(preferences))
+            return true;
+        return this.isAdmitted(item);
+    }
+    isAdmitted(item) {
+        return this.options.journal.observationReviewPass?.includes(observationReviewKey(item)) ?? false;
+    }
+    canStartPass(pending) {
+        if (!pending.length)
+            return false;
+        const preferences = this.options.preferences();
+        if (hasLearningTriggerWork(preferences, pending.length))
+            return true;
+        if (!isObservationTriggered(preferences))
+            return false;
+        if (hasObservationStoragePressure(pending))
+            return true;
+        // Blocked intake shares queue capacity, but only eligible queued work is at risk.
+        const queued = this.options.queue.items;
+        if (!queued.some((item) => canProcessLearningObservation(item, preferences)))
+            return false;
+        return hasObservationStoragePressure(queued);
+    }
+    hasUnfinishedPass() {
+        if (!isObservationTriggered(this.options.preferences()))
+            return false;
+        return this.pendingObservations(true).some((item) => this.isAdmitted(item));
+    }
+    pendingObservations(includeActive = false) {
+        const options = this.options;
+        options.queue.expire(options.now());
+        const batches = options.journal.items.filter((batch) => this.isPendingBatch(batch, includeActive));
+        return [...options.queue.items, ...batches.flatMap((batch) => batch.observations)]
+            .filter((item) => canProcessLearningObservation(item, options.preferences()));
+    }
+    isPendingBatch(batch, includeActive) {
+        if (batch.generation !== this.options.generation())
+            return false;
+        if (!isPendingLearningBatch(batch))
+            return false;
+        if (includeActive)
+            return true;
+        return !this.options.active.has(batch.id);
+    }
+}
+function observationReviewKey(item) {
+    return JSON.stringify([item.deviceId, item.id]);
+}
+/** Optional metadata for old state files; no screen text or new activity history. */
+export function readObservationReviewPass(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length > 2048)
+        throw new Error("invalid_learning_state");
+    if (!value.every(isBoundedObservationKey))
+        throw new Error("invalid_learning_state");
+    return Object.freeze([...new Set(value)]);
+}
+function isBoundedObservationKey(value) {
+    if (typeof value !== "string")
+        return false;
+    return value.length > 0 && value.length <= 1024;
+}

package/dist/src/runtime/passive-learning/processing-trigger.d.ts

@@ -0,0 +1,7 @@
+import type { PassiveLearningPreferences } from "./contracts.js";
+export declare const DEFAULT_ANALYSIS_TRIGGER = "interval";
+export declare const DEFAULT_ANALYSIS_OBSERVATION_COUNT = 100;
+/** Count is an admission threshold, not a larger model batch or retention limit. */
+export declare function normalizeLearningTrigger(input: Partial<PassiveLearningPreferences>, previous: PassiveLearningPreferences): Pick<PassiveLearningPreferences, "analysisTrigger" | "analysisObservationCount">;
+export declare function isObservationTriggered(preferences: PassiveLearningPreferences): boolean;
+export declare function hasLearningTriggerWork(preferences: PassiveLearningPreferences, eligibleCount: number): boolean;

package/dist/src/runtime/passive-learning/processing-trigger.js

@@ -0,0 +1,31 @@
+import { MAX_PENDING_OBSERVATIONS } from "./queue.js";
+export const DEFAULT_ANALYSIS_TRIGGER = "interval";
+export const DEFAULT_ANALYSIS_OBSERVATION_COUNT = 100;
+/** Count is an admission threshold, not a larger model batch or retention limit. */
+export function normalizeLearningTrigger(input, previous) {
+    const analysisTrigger = input.analysisTrigger ?? previous.analysisTrigger ?? DEFAULT_ANALYSIS_TRIGGER;
+    const analysisObservationCount = input.analysisObservationCount ?? previous.analysisObservationCount ?? DEFAULT_ANALYSIS_OBSERVATION_COUNT;
+    if (!isLearningTriggerMode(analysisTrigger))
+        throw new Error("invalid_learning_preferences");
+    if (!isLearningObservationThreshold(analysisObservationCount))
+        throw new Error("invalid_learning_preferences");
+    return { analysisTrigger, analysisObservationCount };
+}
+export function isObservationTriggered(preferences) {
+    return preferences.analysisTrigger === "observations";
+}
+export function hasLearningTriggerWork(preferences, eligibleCount) {
+    if (eligibleCount <= 0)
+        return false;
+    if (!isObservationTriggered(preferences))
+        return true;
+    return eligibleCount >= (preferences.analysisObservationCount ?? DEFAULT_ANALYSIS_OBSERVATION_COUNT);
+}
+function isLearningTriggerMode(value) {
+    return value === "interval" || value === "observations";
+}
+function isLearningObservationThreshold(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return false;
+    return value >= 1 && value <= MAX_PENDING_OBSERVATIONS;
+}

package/dist/src/runtime/passive-learning/queue.d.ts

@@ -0,0 +1,29 @@
+import type { LearningObservation } from "./contracts.js";
+export declare const MAX_PENDING_OBSERVATIONS = 256;
+/** Eligible evidence may need review before its count can fill the bounded queue. */
+export declare function hasObservationStoragePressure(observations: readonly LearningObservation[]): boolean;
+export declare class ObservationQueue {
+    private readonly canProcess;
+    private pending;
+    private readonly seen;
+    private lastSource;
+    private lastFingerprint;
+    private expiryTimer;
+    private expiryClock;
+    dropped: number;
+    constructor(canProcess?: (item: LearningObservation) => boolean);
+    get length(): number;
+    get items(): readonly LearningObservation[];
+    clear(): void;
+    startExpiry(clock: {
+        now(): number;
+        changed(): void;
+    }): void;
+    stopExpiry(): void;
+    add(observation: LearningObservation, now: number): boolean;
+    take(now: number, eligible?: (item: LearningObservation) => boolean): readonly LearningObservation[];
+    expire(now: number): void;
+    private armExpiry;
+    private enforceCapacity;
+}
+export declare function documentIdentity(observation: LearningObservation): string;

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

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { PASSIVE_OBSERVATION_RETENTION_MS as RETENTION_MS } from "../../shared/passive-observation.js";
+export const MAX_PENDING_OBSERVATIONS = 256;
+const MAX_PENDING_BYTES = 2 * 1024 * 1024;
+const STORAGE_PRESSURE_BYTES = Math.floor(MAX_PENDING_BYTES * 0.8);
+const STORAGE_PRESSURE_COUNT = Math.floor(MAX_PENDING_OBSERVATIONS * 0.8);
+const observationSizes = new WeakMap();
+/** Eligible evidence may need review before its count can fill the bounded queue. */
+export function hasObservationStoragePressure(observations) {
+    if (observations.length >= STORAGE_PRESSURE_COUNT)
+        return true;
+    let bytes = 0;
+    for (const observation of observations) {
+        bytes += observationStorageSize(observation);
+        if (bytes >= STORAGE_PRESSURE_BYTES)
+            return true;
+    }
+    return false;
+}
+function observationStorageSize(observation) {
+    const cached = observationSizes.get(observation);
+    if (cached !== undefined)
+        return cached;
+    const size = Buffer.byteLength(JSON.stringify(observation));
+    observationSizes.set(observation, size);
+    return size;
+}
+export class ObservationQueue {
+    canProcess;
+    pending = [];
+    seen = new Map();
+    lastSource;
+    lastFingerprint;
+    expiryTimer;
+    expiryClock;
+    dropped = 0;
+    constructor(canProcess = () => true) {
+        this.canProcess = canProcess;
+    }
+    get length() {
+        return this.pending.length;
+    }
+    get items() { return this.pending; }
+    clear() {
+        this.pending = [];
+        this.seen.clear();
+        this.lastSource = undefined;
+        this.lastFingerprint = undefined;
+        this.armExpiry();
+    }
+    startExpiry(clock) {
+        this.expiryClock = clock;
+        this.expire(clock.now());
+    }
+    stopExpiry() {
+        if (this.expiryTimer)
+            clearTimeout(this.expiryTimer);
+        this.expiryTimer = undefined;
+        this.expiryClock = undefined;
+    }
+    add(observation, now) {
+        this.expire(now);
+        if (now - Date.parse(observation.timestamp) >= RETENTION_MS) {
+            this.dropped += 1;
+            return false;
+        }
+        const content = observation.content.replace(/\r\n/gu, "\n").trim();
+        let normalized = Object.freeze({
+            ...observation,
+            content,
+        });
+        const identity = documentIdentity(normalized);
+        const sourceChanged = this.lastSource !== identity;
+        this.lastSource = identity;
+        const explicitRevisit = Boolean(observation.revisitsObservationId);
+        if (!content && !sourceChanged && !explicitRevisit)
+            return false;
+        const fingerprint = createHash("sha256")
+            .update(JSON.stringify([
+            identity,
+            normalized.kind,
+            content,
+            normalized.coverage,
+        ]))
+            .digest("hex");
+        const earlier = this.seen.get(fingerprint);
+        if (fingerprint === this.lastFingerprint &&
+            !sourceChanged &&
+            !explicitRevisit)
+            return false;
+        this.lastFingerprint = fingerprint;
+        if (earlier !== undefined && sourceChanged)
+            normalized = Object.freeze({
+                ...normalized,
+                content: "",
+                kind: "activity",
+                coverage: "metadata_only",
+                coverageReason: "Repeated visit; previously observed content is unchanged.",
+                revisit: {
+                    firstObservedAt: new Date(earlier).toISOString(),
+                    contentUnchanged: true,
+                },
+            });
+        this.seen.set(fingerprint, now);
+        const last = this.pending.at(-1);
+        if (canSettleDraft(last, normalized))
+            this.pending.pop();
+        this.pending.push(normalized);
+        this.enforceCapacity();
+        this.armExpiry();
+        return true;
+    }
+    take(now, eligible = () => true) {
+        this.expire(now);
+        const selected = [];
+        this.pending = this.pending.filter((item) => {
+            if (selected.length >= 16 || !eligible(item))
+                return true;
+            selected.push(item);
+            return false;
+        });
+        this.armExpiry();
+        return Object.freeze(selected);
+    }
+    expire(now) {
+        const before = this.pending.length;
+        this.pending = this.pending.filter((item) => now - Date.parse(item.timestamp) < RETENTION_MS);
+        this.dropped += before - this.pending.length;
+        for (const [key, timestamp] of this.seen)
+            if (now - timestamp > RETENTION_MS)
+                this.seen.delete(key);
+        while (this.seen.size > 4096)
+            this.seen.delete(this.seen.keys().next().value);
+        this.armExpiry();
+    }
+    armExpiry() {
+        if (this.expiryTimer)
+            clearTimeout(this.expiryTimer);
+        this.expiryTimer = undefined;
+        if (!this.expiryClock || !this.pending.length)
+            return;
+        const clock = this.expiryClock;
+        const expiry = Math.min(...this.pending.map((item) => Date.parse(item.timestamp))) +
+            RETENTION_MS;
+        this.expiryTimer = setTimeout(() => {
+            this.expiryTimer = undefined;
+            this.expire(clock.now());
+            clock.changed();
+        }, Math.max(1, expiry - clock.now()));
+        this.expiryTimer.unref?.();
+    }
+    enforceCapacity() {
+        let bytes = this.pending.reduce((total, item) => total + observationStorageSize(item), 0);
+        while (this.pending.length > MAX_PENDING_OBSERVATIONS || bytes > MAX_PENDING_BYTES) {
+            // Intake can fill the queue before an async review starts. Reserve its
+            // bounded capacity for eligible evidence ahead of processing exclusions.
+            const excluded = this.pending.findIndex((item) => !this.canProcess(item));
+            const [removed] = this.pending.splice(Math.max(0, excluded), 1);
+            bytes -= observationStorageSize(removed);
+            this.dropped += 1;
+        }
+    }
+}
+export function documentIdentity(observation) {
+    const source = observation.source;
+    return JSON.stringify([
+        observation.deviceId,
+        source.app,
+        source.processId,
+        source.windowId,
+        source.documentId,
+        source.url,
+        source.title,
+    ]);
+}
+function canSettleDraft(previous, next) {
+    if (!previous || previous.kind !== "edit" || next.kind !== "edit")
+        return false;
+    if (documentIdentity(previous) !== documentIdentity(next))
+        return false;
+    return Date.parse(next.timestamp) - Date.parse(previous.timestamp) <= 10_000;
+}

package/dist/src/runtime/passive-learning/reassessment-receipt.d.ts

@@ -0,0 +1,20 @@
+import type { LearningMemoryService } from "../long-term-memory/maturation/contracts.js";
+import type { createReassessmentStateStore } from "./reassessment-state.js";
+/** Finish local bookkeeping for a committed review without repeating inference. */
+export declare function reconcileCommittedReassessment(store: ReturnType<typeof createReassessmentStateStore>, memory: LearningMemoryService): Promise<Readonly<{
+    schemaVersion: 1;
+    fingerprint: string | null;
+    attemptedAt: number;
+    reason: string | null;
+    blockedEntries: readonly {
+        readonly id: string;
+        readonly kind: "candidate" | "memory";
+        readonly version: string;
+    }[];
+    reviewProgress?: import("./review-progress.js").CoWorkerReviewProgress;
+    reviewEntries?: readonly {
+        readonly id: string;
+        readonly kind: "candidate" | "memory";
+        readonly version: string;
+    }[];
+}>>;

package/dist/src/runtime/passive-learning/reassessment-receipt.js

@@ -0,0 +1,18 @@
+import { traceDebug } from "../observability/debug-logger.js";
+/** Finish local bookkeeping for a committed review without repeating inference. */
+export async function reconcileCommittedReassessment(store, memory) {
+    const state = await store.read();
+    if (!state.fingerprint)
+        return state;
+    const batchId = `reassess-${state.fingerprint}`;
+    if (!await memory.receipt(batchId))
+        return state;
+    const current = await memory.sourceVersions();
+    // Memory commits consume every scheduled trigger, including no-change reviews.
+    // Retain unrelated failed bindings whose exact version is still current.
+    const isCurrentReassessmentBinding = (binding) => current.some((entry) => entry.kind === binding.kind && entry.id === binding.id && entry.version === binding.version);
+    const completed = state.blockedEntries.filter((binding) => !isCurrentReassessmentBinding(binding));
+    await store.complete(state.fingerprint, completed);
+    traceDebug("runtime.passive_learning", "reassessment.receipt_reconciled", { batchId, completed: completed.length });
+    return store.read();
+}

package/dist/src/runtime/passive-learning/reassessment-state.d.ts

@@ -0,0 +1,25 @@
+import type { LearningKnowledgeContext, LearningKnowledgeEntry } from "../long-term-memory/maturation/contracts.js";
+import { type CoWorkerReviewProgress } from "./review-progress.js";
+type Binding = Pick<LearningKnowledgeEntry, "kind" | "id" | "version">;
+export declare const MAX_REASSESSMENT_BINDINGS = 500;
+type ReassessmentState = Readonly<{
+    schemaVersion: 1;
+    fingerprint: string | null;
+    attemptedAt: number;
+    reason: string | null;
+    blockedEntries: readonly Binding[];
+    reviewProgress?: CoWorkerReviewProgress;
+    reviewEntries?: readonly Binding[];
+}>;
+export declare function learningReassessmentFingerprint(context: LearningKnowledgeContext): string;
+/** Bounded exact-version receipts prevent repeated inference while other due entries advance. */
+export declare function createReassessmentStateStore(directory: string): Readonly<{
+    read: () => Promise<ReassessmentState>;
+    reserve(fingerprint: string, entries: readonly Binding[], now: number, assertCurrent: () => void): Promise<boolean>;
+    failed(fingerprint: string, entries: readonly Binding[], reason: string, retryable: boolean): Promise<void>;
+    complete(fingerprint: string, entries: readonly Binding[]): Promise<void>;
+    retryBlocked(): Promise<void>;
+    saveProgress(fingerprint: string, entries: readonly Binding[], progress: CoWorkerReviewProgress | undefined, assertCurrent?: () => void): Promise<void>;
+    resumeProgress(now: number): Promise<ReassessmentState>;
+}>;
+export {};