@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/runtime/passive-learning/activity-permissions.js

@@ -0,0 +1,88 @@
+function readActivityPermissions(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isActivityPermissions(value))
+        throw new Error("invalid_learning_preferences");
+    return Object.freeze({ collection: value.collection, learning: value.learning, proactive: value.proactive });
+}
+function isActivityPermissions(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const permissions = value;
+    if (Object.keys(permissions).length !== 3)
+        return false;
+    return ["collection", "learning", "proactive"].every((key) => typeof permissions[key] === "boolean");
+}
+/** Old API clients retain their existing switches until authorization is explicitly saved. */
+export function normalizeLearningActivityControls(input, previous) {
+    const permissions = readActivityPermissions(input.activityPermissions === undefined
+        ? previous.activityPermissions : input.activityPermissions);
+    const controls = {
+        enabled: input.enabled ?? previous.enabled,
+        processingPaused: input.processingPaused ?? previous.processingPaused ?? false,
+        proactiveEnabled: input.proactiveEnabled ?? previous.proactiveEnabled ?? false,
+    };
+    if (!permissions)
+        return controls;
+    assertAuthorizedActivation(input, permissions);
+    return {
+        activityPermissions: permissions,
+        enabled: permissions.collection && controls.enabled,
+        processingPaused: !permissions.learning || resolveAuthorizedLearningPause(input, previous),
+        proactiveEnabled: permissions.proactive && controls.proactiveEnabled,
+    };
+}
+function resolveAuthorizedLearningPause(input, previous) {
+    if (input.processingPaused !== undefined)
+        return input.processingPaused;
+    if (!previous.modelProfileId)
+        return true;
+    return previous.processingPaused ?? false;
+}
+function assertAuthorizedActivation(input, permissions) {
+    if (input.enabled === true && !permissions.collection)
+        throw new Error("learning_activity_not_allowed");
+    if (input.processingPaused === false && !permissions.learning)
+        throw new Error("learning_activity_not_allowed");
+    if (input.proactiveEnabled === true && !permissions.proactive)
+        throw new Error("learning_activity_not_allowed");
+}
+function requiresPermissionModelValidation(allowed, previouslyAllowed, profile, previousProfile, starting) {
+    if (!allowed)
+        return false;
+    if (!previouslyAllowed)
+        return true;
+    if (profile !== previousProfile)
+        return true;
+    return starting;
+}
+/** Authorizing an activity validates its model without starting a review or invoking a model. */
+export function validateLearningActivityModels(previous, next, validateProfile) {
+    const permissions = next.activityPermissions;
+    if (!permissions)
+        return;
+    const old = previous.activityPermissions ?? {
+        collection: previous.enabled,
+        learning: Boolean(previous.modelProfileId && !previous.processingPaused),
+        proactive: Boolean(previous.proactiveEnabled),
+    };
+    const learningModel = next.modelProfileId;
+    const collectionNeedsModel = requiresPermissionModelValidation(permissions.collection, old.collection, learningModel, previous.modelProfileId, next.enabled && !previous.enabled);
+    const learningNeedsModel = requiresPermissionModelValidation(permissions.learning, old.learning, learningModel, previous.modelProfileId, !next.processingPaused && Boolean(previous.processingPaused));
+    const learningModelNeedsValidation = collectionNeedsModel || learningNeedsModel;
+    validateRequiredActivityModel(learningModelNeedsValidation, learningModel, "learning_model_required", validateProfile);
+    const proactiveModel = next.proactiveModelProfileId ?? learningModel;
+    const proactiveNeedsModel = requiresPermissionModelValidation(permissions.proactive, old.proactive, proactiveModel, previous.proactiveModelProfileId ?? previous.modelProfileId, Boolean(next.proactiveEnabled && !previous.proactiveEnabled));
+    if (!proactiveNeedsModel)
+        return;
+    if (proactiveModel === learningModel && learningModelNeedsValidation)
+        return;
+    validateRequiredActivityModel(true, proactiveModel, "proactive_model_required", validateProfile);
+}
+function validateRequiredActivityModel(required, profile, missingReason, validateProfile) {
+    if (!required)
+        return;
+    if (!profile)
+        throw new Error(missingReason);
+    validateProfile(profile);
+}

package/dist/src/runtime/passive-learning/analysis-clock.d.ts

@@ -0,0 +1,14 @@
+import type { LearningAnalysisWindow } from "./contracts.js";
+/** Cadence survives collection changes; pausing analysis only disarms its timer. */
+export declare class LearningAnalysisClock {
+    private readonly run;
+    private readonly now;
+    private timer;
+    private nextCycleAt;
+    scheduledAt: number | undefined;
+    constructor(run: () => void, now?: () => number);
+    dispatched(now: number, interval: number): void;
+    arm(now: number, interval: number, window?: LearningAnalysisWindow | null, earliest?: number): void;
+    private schedule;
+    clear(resetCycle?: boolean): void;
+}

package/dist/src/runtime/passive-learning/analysis-clock.js

@@ -0,0 +1,46 @@
+import { nextAnalysisInstant } from "./analysis-schedule.js";
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Cadence survives collection changes; pausing analysis only disarms its timer. */
+export class LearningAnalysisClock {
+    run;
+    now;
+    timer;
+    nextCycleAt;
+    scheduledAt;
+    constructor(run, now = Date.now) {
+        this.run = run;
+        this.now = now;
+    }
+    dispatched(now, interval) {
+        this.nextCycleAt = now + interval;
+    }
+    arm(now, interval, window, earliest) {
+        if (this.timer)
+            return;
+        if (earliest !== undefined && !Number.isFinite(earliest))
+            return;
+        this.nextCycleAt ??= now + interval;
+        this.scheduledAt = nextAnalysisInstant(Math.max(now, this.nextCycleAt, earliest ?? now), window);
+        this.schedule(now);
+    }
+    schedule(now) {
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            if (this.scheduledAt !== undefined && this.scheduledAt > this.now()) {
+                this.schedule(this.now());
+                return;
+            }
+            this.scheduledAt = undefined;
+            this.run();
+        }, Math.min(MAX_TIMER_DELAY_MS, Math.max(1, this.scheduledAt - now)));
+        this.timer.unref?.();
+    }
+    clear(resetCycle = false) {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.scheduledAt = undefined;
+        if (resetCycle)
+            this.nextCycleAt = undefined;
+    }
+}

package/dist/src/runtime/passive-learning/analysis-schedule.d.ts

@@ -0,0 +1,6 @@
+import type { LearningAnalysisWindow, PassiveLearningPreferences } from "./contracts.js";
+export declare function normalizeAnalysisSchedule(input: Partial<PassiveLearningPreferences>, previous: PassiveLearningPreferences): Pick<PassiveLearningPreferences, "analysisIntervalMinutes" | "analysisTrigger" | "analysisObservationCount" | "analysisWindow" | "maxConcurrentBatches">;
+export declare function isWithinAnalysisWindow(instant: number, window?: LearningAnalysisWindow | null): boolean;
+/** Missing local start times skip that day, matching the canonical scheduler. */
+export declare function nextAnalysisInstant(earliest: number, window?: LearningAnalysisWindow | null): number;
+export declare function validateWindow(window: LearningAnalysisWindow | null): void;

package/dist/src/runtime/passive-learning/analysis-schedule.js

@@ -0,0 +1,69 @@
+import { nextSchedulerOccurrence } from "../scheduler/next-occurrence.js";
+import { normalizeLearningTrigger } from "./processing-trigger.js";
+const WALL_TIME = /^(?:[01]\d|2[0-3]):[0-5]\d$/u;
+export function normalizeAnalysisSchedule(input, previous) {
+    const analysisIntervalMinutes = input.analysisIntervalMinutes ?? previous.analysisIntervalMinutes ?? 15;
+    const maxConcurrentBatches = input.maxConcurrentBatches ?? previous.maxConcurrentBatches ?? 1;
+    if (!isIntegerInRange(analysisIntervalMinutes, 1, 1440) ||
+        !isIntegerInRange(maxConcurrentBatches, 1, 8))
+        throw new Error("invalid_learning_preferences");
+    const analysisWindow = input.analysisWindow === undefined
+        ? (previous.analysisWindow ?? null)
+        : input.analysisWindow;
+    validateWindow(analysisWindow);
+    return {
+        ...normalizeLearningTrigger(input, previous),
+        analysisIntervalMinutes,
+        maxConcurrentBatches,
+        analysisWindow: analysisWindow
+            ? Object.freeze({ ...analysisWindow })
+            : null,
+    };
+}
+export function isWithinAnalysisWindow(instant, window) {
+    if (!window || window.start === window.end)
+        return true;
+    const parts = new Intl.DateTimeFormat("en-GB", {
+        timeZone: window.timeZone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    }).formatToParts(instant);
+    const hour = parts.find(({ type }) => type === "hour").value;
+    const minute = parts.find(({ type }) => type === "minute").value;
+    const time = `${hour}:${minute}`;
+    return window.start < window.end
+        ? time >= window.start && time < window.end
+        : time >= window.start || time < window.end;
+}
+/** Missing local start times skip that day, matching the canonical scheduler. */
+export function nextAnalysisInstant(earliest, window) {
+    if (isWithinAnalysisWindow(earliest, window))
+        return earliest;
+    const next = nextSchedulerOccurrence({ kind: "daily", at: window.start }, window.timeZone, earliest);
+    if (!next)
+        throw new Error("invalid_learning_preferences");
+    return Date.parse(next);
+}
+function isIntegerInRange(value, minimum, maximum) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= minimum &&
+        value <= maximum);
+}
+export function validateWindow(window) {
+    if (window === null)
+        return;
+    if (!window ||
+        typeof window !== "object" ||
+        !WALL_TIME.test(window.start) ||
+        !WALL_TIME.test(window.end) ||
+        typeof window.timeZone !== "string")
+        throw new Error("invalid_learning_preferences");
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: window.timeZone }).format(0);
+    }
+    catch {
+        throw new Error("invalid_learning_preferences");
+    }
+}

package/dist/src/runtime/passive-learning/application-catalog.d.ts

@@ -0,0 +1,13 @@
+import type { LearningBatch, LearningObservation, PassiveLearningPreferences } from "./contracts.js";
+export type LearningApplicationSummary = Readonly<{
+    app: string;
+    observationCount: number;
+    lastObservedAt?: string;
+    collectionExcluded: boolean;
+    processingExcluded: boolean;
+}>;
+/** Derived metadata only; counts cover retained observations, never lifetime usage. */
+export declare function learningApplicationCatalog(queued: readonly LearningObservation[], history: readonly LearningBatch[], preferences: PassiveLearningPreferences): {
+    applications: readonly LearningApplicationSummary[];
+    applicationsOmitted: number;
+};

package/dist/src/runtime/passive-learning/application-catalog.js

@@ -0,0 +1,29 @@
+import { isLearningApplicationExcluded, learningApplicationKey } from "./application-policy.js";
+/** Derived metadata only; counts cover retained observations, never lifetime usage. */
+export function learningApplicationCatalog(queued, history, preferences) {
+    const rows = new Map();
+    const rules = [...preferences.excludedApplications, ...preferences.processingExcludedApplications ?? []];
+    for (const app of rules)
+        rows.set(learningApplicationKey(app), { app, observationCount: 0 });
+    const seen = new Set();
+    for (const observation of [...queued, ...history.flatMap((batch) => batch.observations)]) {
+        const identity = JSON.stringify([observation.deviceId, observation.id]);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        const key = learningApplicationKey(observation.source.app);
+        const row = rows.get(key) ?? { app: observation.source.app, observationCount: 0 };
+        row.observationCount += 1;
+        if (!row.lastObservedAt || Date.parse(observation.timestamp) > Date.parse(row.lastObservedAt))
+            row.lastObservedAt = observation.timestamp;
+        rows.set(key, row);
+    }
+    const summaries = [...rows.values()].map((row) => ({ ...row,
+        collectionExcluded: isLearningApplicationExcluded(row.app, preferences.excludedApplications),
+        processingExcluded: isLearningApplicationExcluded(row.app, preferences.processingExcludedApplications),
+    }));
+    const excluded = summaries.filter((row) => row.collectionExcluded || row.processingExcluded);
+    const recent = summaries.filter((row) => !row.collectionExcluded && !row.processingExcluded)
+        .sort((a, b) => Date.parse(b.lastObservedAt) - Date.parse(a.lastObservedAt));
+    return { applications: [...excluded, ...recent.slice(0, 100)], applicationsOmitted: Math.max(0, recent.length - 100) };
+}

package/dist/src/runtime/passive-learning/application-controls.d.ts

@@ -0,0 +1,10 @@
+import type { LearningActiveBatches } from "./active-batches.js";
+import type { PassiveLearningPreferences } from "./contracts.js";
+/** Exclusion changes settle affected work before publishing the saved policy. */
+export declare function commitLearningApplicationPreferences(options: {
+    previous: PassiveLearningPreferences;
+    next: PassiveLearningPreferences;
+    active: LearningActiveBatches;
+    suspend(): () => void;
+    commit(): Promise<void>;
+}): Promise<void>;

package/dist/src/runtime/passive-learning/application-controls.js

@@ -0,0 +1,14 @@
+import { hasProcessingApplicationsChanged } from "./application-policy.js";
+/** Exclusion changes settle affected work before publishing the saved policy. */
+export async function commitLearningApplicationPreferences(options) {
+    if (!hasProcessingApplicationsChanged(options.previous, options.next))
+        return options.commit();
+    const resume = options.suspend();
+    try {
+        await options.active.excludeApplications(options.next.processingExcludedApplications ?? []);
+        await options.commit();
+    }
+    finally {
+        resume();
+    }
+}

package/dist/src/runtime/passive-learning/application-pending.d.ts

@@ -0,0 +1,15 @@
+import type { LearningActiveBatches } from "./active-batches.js";
+import type { LearningBatch, LearningObservation, PassiveLearningPreferences } from "./contracts.js";
+import type { LearningJournal } from "./journal.js";
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+export declare function hasProcessablePendingBatch(batch: LearningBatch, generation: string, active: LearningActiveBatches, preferences: PassiveLearningPreferences, eligible?: (item: LearningObservation) => boolean): boolean;
+/** Split only uncommitted mixed batches; held evidence keeps its original expiry. */
+export declare function prepareApplicationPendingBatch(options: {
+    journal: LearningJournal;
+    active: LearningActiveBatches;
+    memory: LongTermMemoryService;
+    generation(): string;
+    preferences(): PassiveLearningPreferences;
+    canProcess(): boolean;
+    eligible?(item: LearningObservation): boolean;
+}): Promise<LearningBatch | undefined>;

package/dist/src/runtime/passive-learning/application-pending.js

@@ -0,0 +1,44 @@
+import { canProcessLearningBatch, canProcessLearningObservation } from "./application-policy.js";
+import { createPendingLearningBatch } from "./batch-lifecycle.js";
+import { readLearningBatchReceipt, resolveReviewedBatchStatus } from "./batch-receipt.js";
+export function hasProcessablePendingBatch(batch, generation, active, preferences, eligible = () => true) {
+    if (batch.status !== "pending" || batch.generation !== generation || active.has(batch.id))
+        return false;
+    return batch.observations.some((item) => canProcessLearningObservation(item, preferences) && eligible(item));
+}
+/** Split only uncommitted mixed batches; held evidence keeps its original expiry. */
+export async function prepareApplicationPendingBatch(options) {
+    const eligible = (item) => {
+        if (!canProcessLearningObservation(item, options.preferences()))
+            return false;
+        return options.eligible?.(item) ?? true;
+    };
+    for (const batch of options.journal.items) {
+        if (!hasProcessablePendingBatch(batch, options.generation(), options.active, options.preferences(), eligible))
+            continue;
+        if (batch.observations.every(eligible))
+            return batch;
+        const receipt = await readLearningBatchReceipt(options.memory, batch.id);
+        if (!options.canProcess() || batch.generation !== options.generation())
+            return undefined;
+        if (receipt) {
+            await options.journal.replace({ ...batch, status: resolveReviewedBatchStatus(receipt.recordIds, receipt.candidateIds ?? []),
+                recordIds: receipt.recordIds, candidateIds: receipt.candidateIds ?? [], reason: undefined, completedAt: receipt.createdAt });
+            continue;
+        }
+        const preferences = options.preferences();
+        const allowed = batch.observations.filter(eligible);
+        if (!allowed.length)
+            continue;
+        if (allowed.length === batch.observations.length)
+            return batch;
+        const held = batch.observations.filter((item) => !eligible(item));
+        const ready = { ...batch, observations: allowed, reason: undefined, reviewProgress: undefined };
+        const blocked = { ...createPendingLearningBatch(held, batch.generation, Date.parse(batch.createdAt)),
+            reason: canProcessLearningBatch(batch, preferences) ? undefined : "learning_application_processing_excluded" };
+        if (!await options.journal.partition([ready, blocked]))
+            throw new Error("learning_partition_capacity");
+        return ready;
+    }
+    return undefined;
+}

package/dist/src/runtime/passive-learning/application-policy.d.ts

@@ -0,0 +1,7 @@
+import type { LearningBatch, LearningObservation, PassiveLearningPreferences } from "./contracts.js";
+export declare function learningApplicationKey(app: string): string;
+export declare function isLearningApplicationExcluded(app: string, exclusions?: readonly string[]): boolean;
+export declare function normalizeLearningApplications(apps: readonly string[]): readonly string[];
+export declare function canProcessLearningObservation(observation: LearningObservation, preferences: PassiveLearningPreferences): boolean;
+export declare function canProcessLearningBatch(batch: LearningBatch, preferences: PassiveLearningPreferences): boolean;
+export declare function hasProcessingApplicationsChanged(previous: PassiveLearningPreferences, next: PassiveLearningPreferences): boolean;

package/dist/src/runtime/passive-learning/application-policy.js

@@ -0,0 +1,26 @@
+export function learningApplicationKey(app) { return app.trim().toLowerCase(); }
+export function isLearningApplicationExcluded(app, exclusions = []) {
+    const key = learningApplicationKey(app);
+    return exclusions.some((excluded) => learningApplicationKey(excluded) === key);
+}
+export function normalizeLearningApplications(apps) {
+    if (!Array.isArray(apps) || apps.length > 100)
+        throw new Error("invalid_learning_exclusions");
+    const unique = new Map();
+    for (const app of apps) {
+        if (typeof app !== "string" || app.length > 128 || !app.trim() || /[\u0000-\u001f\u007f]/u.test(app))
+            throw new Error("invalid_learning_exclusions");
+        unique.set(learningApplicationKey(app), app.trim());
+    }
+    return Object.freeze([...unique.values()]);
+}
+export function canProcessLearningObservation(observation, preferences) {
+    return !isLearningApplicationExcluded(observation.source.app, preferences.processingExcludedApplications);
+}
+export function canProcessLearningBatch(batch, preferences) {
+    return batch.observations.every((observation) => canProcessLearningObservation(observation, preferences));
+}
+export function hasProcessingApplicationsChanged(previous, next) {
+    const keys = (value) => (value.processingExcludedApplications ?? []).map(learningApplicationKey).sort();
+    return JSON.stringify(keys(previous)) !== JSON.stringify(keys(next));
+}

package/dist/src/runtime/passive-learning/background-dependencies.d.ts

@@ -0,0 +1,38 @@
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+import type { LearningChangedEvent, PassiveLearningModel, PassiveLearningPreferences, ProactiveStatus, LearningReassessmentStatus } from "./contracts.js";
+import type { CoWorkerResourceUsage } from "./resources/contracts.js";
+export type LearningBackgroundContext = Readonly<{
+    preferences(): PassiveLearningPreferences;
+    assertProcessingAllowed(): void;
+    changed(event?: LearningChangedEvent): void;
+    isInteractiveBusy(): boolean;
+    isStarted(): boolean;
+    isProcessingBusy?(): boolean;
+}>;
+export type LearningProactiveLifecycle = Readonly<{
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    preferencesChanged(): Promise<void>;
+    knowledgeChanged(): void;
+    beginInteractive(): () => void;
+    status(): Promise<ProactiveStatus>;
+    dismiss(id: string): Promise<void>;
+    sessionDeleted?(sessionId: string): Promise<void>;
+}>;
+export type LearningReassessmentLifecycle = Readonly<{
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    preferencesChanged(): Promise<void>;
+    knowledgeChanged(): void;
+    beginInteractive(): () => void;
+    status(): LearningReassessmentStatus;
+}>;
+export type LearningBackgroundDependencies = Readonly<{
+    model: PassiveLearningModel;
+    memory: LongTermMemoryService;
+    resourceUsage?(): Promise<CoWorkerResourceUsage & {
+        activeCalls: number;
+    }>;
+    proactive?: LearningProactiveLifecycle;
+    reassessment?: LearningReassessmentLifecycle;
+}>;

package/dist/src/runtime/passive-learning/background-dependencies.js

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

package/dist/src/runtime/passive-learning/background-lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { LearningBackgroundDependencies } from "./background-dependencies.js";
+import type { PassiveLearningPreferences } from "./contracts.js";
+/** Feature lifecycle coordination; no timers or model work beyond each owning activity. */
+export declare class LearningBackgroundLifecycle {
+    private readonly options;
+    private unsubscribeMaintenance;
+    private unsubscribeKnowledge;
+    get maintenanceReason(): string | undefined;
+    proactiveStartupReason: string | undefined;
+    reassessmentStartupReason: string | undefined;
+    constructor(options: {
+        background: LearningBackgroundDependencies;
+        changed(): void;
+    });
+    validatePreferences(previous: PassiveLearningPreferences, next: PassiveLearningPreferences): Promise<void>;
+    start(): Promise<void>;
+    private startIndependentActivity;
+    stop(): Promise<void>;
+    preferencesChanged(): Promise<void>;
+    knowledgeChanged(): void;
+    beginInteractive(): () => void;
+}

package/dist/src/runtime/passive-learning/background-lifecycle.js

@@ -0,0 +1,75 @@
+/** Feature lifecycle coordination; no timers or model work beyond each owning activity. */
+export class LearningBackgroundLifecycle {
+    options;
+    unsubscribeMaintenance;
+    unsubscribeKnowledge;
+    get maintenanceReason() { return this.options.background.memory.retention?.reason(); }
+    proactiveStartupReason;
+    reassessmentStartupReason;
+    constructor(options) {
+        this.options = options;
+    }
+    async validatePreferences(previous, next) {
+        if (!next.proactiveEnabled)
+            return;
+        const profile = next.proactiveModelProfileId ?? next.modelProfileId;
+        if (previous.proactiveEnabled && profile === (previous.proactiveModelProfileId ?? previous.modelProfileId))
+            return;
+        if (!profile)
+            throw new Error("proactive_model_required");
+        this.options.background.model.validateProfile(profile);
+        const memory = await this.options.background.memory.status();
+        if (!memory.enabled || !memory.available || !this.options.background.memory.learning)
+            throw new Error("learning_memory_unavailable");
+        if (!this.options.background.proactive)
+            throw new Error("proactive_unavailable");
+    }
+    async start() {
+        this.proactiveStartupReason = undefined;
+        this.reassessmentStartupReason = undefined;
+        this.unsubscribeMaintenance ??= this.options.background.memory.retention?.subscribeChanges(this.options.changed);
+        this.unsubscribeKnowledge ??= this.options.background.memory.subscribeChanges?.(() => {
+            this.knowledgeChanged();
+            this.options.changed();
+        });
+        await this.startIndependentActivity(this.options.background.proactive, () => {
+            this.proactiveStartupReason = "proactive_start_failed";
+        });
+        await this.startIndependentActivity(this.options.background.reassessment, () => {
+            this.reassessmentStartupReason = "learning_reassessment_start_failed";
+        });
+    }
+    async startIndependentActivity(activity, failed) {
+        if (!activity)
+            return;
+        try {
+            await activity.start();
+        }
+        catch {
+            failed();
+            // A failed startup can leave an activity partially armed; settle it once.
+            await activity.stop().catch(() => { });
+            this.options.changed();
+        }
+    }
+    async stop() {
+        this.unsubscribeMaintenance?.();
+        this.unsubscribeMaintenance = undefined;
+        this.unsubscribeKnowledge?.();
+        this.unsubscribeKnowledge = undefined;
+        await Promise.all([this.options.background.proactive?.stop(), this.options.background.reassessment?.stop()]);
+    }
+    async preferencesChanged() {
+        await this.options.background.proactive?.preferencesChanged();
+        await this.options.background.reassessment?.preferencesChanged();
+    }
+    knowledgeChanged() {
+        this.options.background.proactive?.knowledgeChanged();
+        this.options.background.reassessment?.knowledgeChanged();
+    }
+    beginInteractive() {
+        const releases = [this.options.background.proactive?.beginInteractive(), this.options.background.reassessment?.beginInteractive()];
+        return () => { for (const release of releases)
+            release?.(); };
+    }
+}

package/dist/src/runtime/passive-learning/batch-lifecycle.d.ts

@@ -0,0 +1,7 @@
+import type { LearningBatch, LearningObservation } from "./contracts.js";
+export declare function learningBatchExpiresAt(batch: LearningBatch): number;
+export declare function createPendingLearningBatch(observations: readonly LearningObservation[], generation: string, now: number): LearningBatch;
+export declare function isPendingLearningBatch(batch: LearningBatch): boolean;
+export declare function isDeferredLearningFailure(error: unknown): error is Error;
+export declare function canResumeInterruptedLearning(signal: AbortSignal, current: boolean): boolean;
+export declare function resolveLearningBatchFailureStatus(signal: AbortSignal, current: boolean, processingPersisted: boolean): LearningBatch["status"];

package/dist/src/runtime/passive-learning/batch-lifecycle.js

@@ -0,0 +1,48 @@
+import { randomUUID } from "node:crypto";
+import { PASSIVE_OBSERVATION_RETENTION_MS } from "../../shared/passive-observation.js";
+export function learningBatchExpiresAt(batch) {
+    const collectedAt = batch.observations.map((item) => Date.parse(item.timestamp));
+    return (Math.min(Date.parse(batch.createdAt), ...collectedAt) +
+        PASSIVE_OBSERVATION_RETENTION_MS);
+}
+export function createPendingLearningBatch(observations, generation, now) {
+    return {
+        id: randomUUID(),
+        createdAt: new Date(now).toISOString(),
+        generation,
+        status: "pending",
+        observations,
+        recordIds: [],
+    };
+}
+export function isPendingLearningBatch(batch) {
+    return batch.status === "pending" || batch.status === "processing";
+}
+export function isDeferredLearningFailure(error) {
+    if (!(error instanceof Error))
+        return false;
+    return ["learning_knowledge_conflict", "learning_outside_processing_window",
+        "learning_receipt_capacity", "learning_memory_unavailable",
+        "learning_review_progress_capacity", "learning_review_progress_storage_unavailable",
+        "co_worker_model_daily_budget_exhausted", "co_worker_embedding_daily_budget_exhausted",
+        "co_worker_embedding_character_budget_exhausted", "co_worker_resources_busy"].includes(error.message);
+}
+export function canResumeInterruptedLearning(signal, current) {
+    if (!current || !signal.aborted || !(signal.reason instanceof Error))
+        return false;
+    return [
+        "learning_interactive_preempted",
+        "learning_processing_paused",
+        "learning_stopped",
+        "learning_application_processing_excluded",
+    ].includes(signal.reason.message);
+}
+export function resolveLearningBatchFailureStatus(signal, current, processingPersisted) {
+    if (canResumeInterruptedLearning(signal, current))
+        return "pending";
+    if (signal.aborted)
+        return "cancelled";
+    if (!processingPersisted && current)
+        return "pending";
+    return "failed";
+}

package/dist/src/runtime/passive-learning/batch-partition.d.ts

@@ -0,0 +1,10 @@
+import type { LearningBatch } from "./contracts.js";
+/** Keep whole observations durable; each part gets a fresh bound knowledge review. */
+export declare function partitionOversizedLearningBatch(error: unknown, options: {
+    batch: LearningBatch;
+    signal: AbortSignal;
+    isCurrent(): boolean;
+    partition?(batches: readonly LearningBatch[]): Promise<boolean>;
+    replace(batch: LearningBatch): Promise<void>;
+    failed(error: unknown): void;
+}): Promise<boolean>;

package/dist/src/runtime/passive-learning/batch-partition.js

@@ -0,0 +1,46 @@
+import { traceDebug } from "../observability/debug-logger.js";
+import { createPendingLearningBatch } from "./batch-lifecycle.js";
+import { LearningReviewCapacityError } from "./review-capacity.js";
+import { learningFailureReason } from "./status-projection.js";
+/** Keep whole observations durable; each part gets a fresh bound knowledge review. */
+export async function partitionOversizedLearningBatch(error, options) {
+    if (!(error instanceof LearningReviewCapacityError))
+        return false;
+    if (options.batch.observations.length < 2 || !options.partition)
+        return false;
+    if (options.signal.aborted || !options.isCurrent())
+        return false;
+    const parts = partitionLearningObservations(options.batch);
+    try {
+        if (!await options.partition(parts)) {
+            await options.replace({ ...options.batch, status: "pending", reason: undefined, completedAt: undefined });
+            options.failed(new Error("learning_partition_capacity"));
+            traceDebug("runtime.passive_learning", "batch.partition_deferred", { batchId: options.batch.id });
+            return true;
+        }
+    }
+    catch (storageError) {
+        // Do not overwrite a partially staged journal partition with the original batch.
+        options.failed(storageError);
+        traceDebug("runtime.passive_learning", "batch.partition_failed", {
+            batchId: options.batch.id, reason: learningFailureReason(storageError),
+        });
+        return true;
+    }
+    traceDebug("runtime.passive_learning", "batch.partitioned", {
+        batchId: options.batch.id,
+        parts: parts.map(({ id, observations }) => ({ batchId: id, observations: observations.length })),
+        reason: "learning_review_context_exceeds_budget",
+    });
+    return true;
+}
+function partitionLearningObservations(batch) {
+    const middle = Math.ceil(batch.observations.length / 2);
+    const createdAt = Date.parse(batch.createdAt);
+    const first = createPendingLearningBatch(batch.observations.slice(0, middle), batch.generation, createdAt);
+    const second = createPendingLearningBatch(batch.observations.slice(middle), batch.generation, createdAt);
+    return [
+        { ...first, id: batch.id, reason: "learning_batch_partitioned" },
+        { ...second, reason: "learning_batch_partitioned" },
+    ];
+}