@abot-ai/runtime 1.3.1 → 1.5.0

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

@@ -0,0 +1,156 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { withFileLock } from "../adapters/long-term-memory/file-lock.js";
+import { fileSystemErrorCode } from "../adapters/long-term-memory/file-lock/contracts.js";
+import { readCoWorkerReviewProgress } from "./review-progress.js";
+export const MAX_REASSESSMENT_BINDINGS = 500;
+const MAX_STATE_BYTES = 128 * 1024;
+const EMPTY = Object.freeze({ schemaVersion: 1, fingerprint: null, attemptedAt: 0, reason: null, blockedEntries: [] });
+export function learningReassessmentFingerprint(context) {
+    const entries = context.entries.map(({ kind, id, version, reconsiderAt }) => ({ kind, id, version, reconsiderAt }));
+    entries.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+    return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+}
+/** Bounded exact-version receipts prevent repeated inference while other due entries advance. */
+export function createReassessmentStateStore(directory) {
+    const file = join(directory, "knowledge-reassessment.json");
+    async function read() {
+        try {
+            const handle = await open(file, "r");
+            try {
+                const buffer = Buffer.alloc(MAX_STATE_BYTES + 1);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (bytesRead > MAX_STATE_BYTES)
+                    throw new Error("learning_reassessment_state_invalid");
+                const parsed = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
+                if (!parsed || typeof parsed !== "object")
+                    throw new Error("learning_reassessment_state_invalid");
+                const value = parsed;
+                if (value.schemaVersion !== 1 || !Number.isFinite(value.attemptedAt) || value.attemptedAt < 0)
+                    throw new Error("learning_reassessment_state_invalid");
+                if (value.fingerprint !== null && !/^[a-f0-9]{64}$/u.test(value.fingerprint))
+                    throw new Error("learning_reassessment_state_invalid");
+                if (value.reason !== null && (typeof value.reason !== "string" || !/^[a-z][a-z0-9_]{0,100}$/u.test(value.reason)))
+                    throw new Error("learning_reassessment_state_invalid");
+                if (!Array.isArray(value.blockedEntries) || value.blockedEntries.length > MAX_REASSESSMENT_BINDINGS || value.blockedEntries.some((entry) => !isBinding(entry)))
+                    throw new Error("learning_reassessment_state_invalid");
+                const reviewProgress = readCoWorkerReviewProgress(value.reviewProgress);
+                if (reviewProgress && (!value.fingerprint || !Array.isArray(value.reviewEntries) ||
+                    value.reviewEntries.length > MAX_REASSESSMENT_BINDINGS || value.reviewEntries.some((entry) => !isBinding(entry))))
+                    throw new Error("learning_reassessment_state_invalid");
+                return { schemaVersion: 1, fingerprint: value.fingerprint, attemptedAt: value.attemptedAt,
+                    reason: value.reason, blockedEntries: value.blockedEntries.map(({ kind, id, version }) => ({ kind, id, version })),
+                    ...(reviewProgress ? { reviewProgress, reviewEntries: value.reviewEntries } : {}) };
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (fileSystemErrorCode(error) === "ENOENT")
+                return EMPTY;
+            throw error;
+        }
+    }
+    async function update(change) {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        return withFileLock(`${file}.lock`, async () => {
+            const previous = await read();
+            const next = change(previous);
+            if (next === previous)
+                return previous;
+            const serialized = JSON.stringify(next);
+            if (Buffer.byteLength(serialized) > MAX_STATE_BYTES)
+                throw new Error("learning_reassessment_capacity");
+            const temporary = `${file}.${randomUUID()}.tmp`;
+            try {
+                const handle = await open(temporary, "wx", 0o600);
+                try {
+                    await handle.writeFile(serialized);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await rename(temporary, file);
+                return next;
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        });
+    }
+    return Object.freeze({
+        read,
+        async reserve(fingerprint, entries, now, assertCurrent) {
+            let reserved = false;
+            await update((state) => {
+                assertCurrent();
+                if (entries.some((entry) => state.blockedEntries.some((blocked) => sameBinding(entry, blocked))))
+                    return state;
+                const blockedEntries = [...state.blockedEntries, ...entries];
+                if (blockedEntries.length > MAX_REASSESSMENT_BINDINGS)
+                    throw new Error("learning_reassessment_capacity");
+                reserved = true;
+                const canResumeProgress = state.fingerprint === fingerprint && state.reviewProgress && now < Date.parse(state.reviewProgress.expiresAt);
+                return { schemaVersion: 1, fingerprint, attemptedAt: now, reason: null, blockedEntries,
+                    ...(canResumeProgress ? { reviewProgress: state.reviewProgress, reviewEntries: state.reviewEntries } : {}) };
+            });
+            return reserved;
+        },
+        async failed(fingerprint, entries, reason, retryable) {
+            await update((state) => state.fingerprint !== fingerprint ? state : {
+                ...state, fingerprint: retryable && !state.reviewProgress ? null : fingerprint, reason,
+                blockedEntries: retryable ? withoutBindings(state.blockedEntries, entries) : state.blockedEntries,
+                reviewProgress: retryable ? state.reviewProgress : undefined,
+                reviewEntries: retryable ? state.reviewEntries : undefined,
+            });
+        },
+        async complete(fingerprint, entries) {
+            await update((state) => state.fingerprint !== fingerprint ? state : {
+                ...state, fingerprint: null, reason: null, blockedEntries: withoutBindings(state.blockedEntries, entries),
+                reviewProgress: undefined, reviewEntries: undefined,
+            });
+        },
+        async retryBlocked() {
+            await update((state) => !state.blockedEntries.length ? state : {
+                ...state, fingerprint: state.reviewProgress ? state.fingerprint : null, reason: null, blockedEntries: [],
+            });
+        },
+        async saveProgress(fingerprint, entries, progress, assertCurrent = () => { }) {
+            await update((state) => {
+                assertCurrent();
+                if (state.fingerprint !== fingerprint)
+                    throw new Error("learning_generation_superseded");
+                return { ...state, reviewProgress: progress, reviewEntries: progress ? entries : undefined };
+            });
+        },
+        async resumeProgress(now) {
+            return update((state) => {
+                if (!state.reviewProgress)
+                    return state;
+                const unexpired = now < Date.parse(state.reviewProgress.expiresAt);
+                const blockedEntries = withoutBindings(state.blockedEntries, state.reviewEntries ?? []);
+                if (unexpired && blockedEntries.length === state.blockedEntries.length)
+                    return state;
+                return { ...state, blockedEntries,
+                    reviewProgress: unexpired ? state.reviewProgress : undefined,
+                    reviewEntries: unexpired ? state.reviewEntries : undefined };
+            });
+        },
+    });
+}
+function sameBinding(left, right) {
+    return left.kind === right.kind && left.id === right.id && left.version === right.version;
+}
+function withoutBindings(values, removed) {
+    return values.filter((value) => !removed.some((entry) => sameBinding(entry, value)));
+}
+function isBinding(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return (entry.kind === "candidate" || entry.kind === "memory") &&
+        [entry.id, entry.version].every((text) => typeof text === "string" && text.length > 0 && text.length <= 160);
+}

package/dist/src/runtime/passive-learning/resources/admission.d.ts

@@ -0,0 +1,23 @@
+import type { CoWorkerResourceActivity } from "./contracts.js";
+type AdmissionRequest = Readonly<{
+    activity?: CoWorkerResourceActivity;
+    supportsParallel: boolean;
+    signal: AbortSignal;
+    maximum(): number;
+    assertActivityAllowed(): void;
+}>;
+/** Only existing work waits here. Release/abort events drive admission; no timers or retries. */
+export declare class CoWorkerResourceAdmission {
+    private active;
+    private exclusive;
+    private lastActivity;
+    private readonly waiting;
+    get activeCalls(): number;
+    acquire(request: AdmissionRequest): Promise<() => void>;
+    private drain;
+    private nextWaiting;
+    private remove;
+    private hasCapacity;
+    private grant;
+}
+export {};

package/dist/src/runtime/passive-learning/resources/admission.js

@@ -0,0 +1,92 @@
+// At most eight processing owners, one proactive review and one reassessment.
+const MAX_WAITING_ADMISSIONS = 10;
+/** Only existing work waits here. Release/abort events drive admission; no timers or retries. */
+export class CoWorkerResourceAdmission {
+    active = 0;
+    exclusive = 0;
+    lastActivity;
+    waiting = [];
+    get activeCalls() {
+        return this.active;
+    }
+    acquire(request) {
+        request.signal.throwIfAborted();
+        request.assertActivityAllowed();
+        if (!request.activity) {
+            if (this.waiting.length || !this.hasCapacity(request))
+                throw new Error("co_worker_resources_busy");
+            return Promise.resolve(this.grant(request));
+        }
+        if (this.waiting.length >= MAX_WAITING_ADMISSIONS)
+            throw new Error("co_worker_resources_busy");
+        return new Promise((resolve, reject) => {
+            const waiting = {
+                request,
+                resolve,
+                reject,
+                removeAbortListener: () => request.signal.removeEventListener("abort", aborted),
+            };
+            const aborted = () => {
+                const index = this.waiting.indexOf(waiting);
+                if (index < 0)
+                    return;
+                this.waiting.splice(index, 1);
+                waiting.removeAbortListener();
+                reject(request.signal.reason ?? new Error("co_worker_resource_wait_aborted"));
+                this.drain();
+            };
+            request.signal.addEventListener("abort", aborted, { once: true });
+            this.waiting.push(waiting);
+            this.drain();
+        });
+    }
+    drain() {
+        while (this.waiting.length) {
+            const next = this.nextWaiting();
+            try {
+                next.request.signal.throwIfAborted();
+                next.request.assertActivityAllowed();
+                // A waiting exclusive call forms a barrier: cloud work cannot keep overtaking it.
+                if (!this.hasCapacity(next.request))
+                    return;
+                this.remove(next);
+                next.resolve(this.grant(next.request));
+            }
+            catch (error) {
+                this.remove(next);
+                next.reject(error);
+            }
+        }
+    }
+    nextWaiting() {
+        return (this.waiting.find(({ request }) => request.activity !== this.lastActivity) ?? this.waiting[0]);
+    }
+    remove(waiting) {
+        this.waiting.splice(this.waiting.indexOf(waiting), 1);
+        waiting.removeAbortListener();
+    }
+    hasCapacity(request) {
+        if (this.exclusive > 0)
+            return false;
+        if (!request.supportsParallel && this.active > 0)
+            return false;
+        return this.active < request.maximum();
+    }
+    grant(request) {
+        this.active += 1;
+        if (!request.supportsParallel)
+            this.exclusive += 1;
+        if (request.activity)
+            this.lastActivity = request.activity;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.active -= 1;
+            if (!request.supportsParallel)
+                this.exclusive -= 1;
+            this.drain();
+        };
+    }
+}

package/dist/src/runtime/passive-learning/resources/budget.d.ts

@@ -0,0 +1,21 @@
+import { type CoWorkerResourceLimits, type CoWorkerResourceReservation, type CoWorkerResourceUsage } from "./contracts.js";
+/** One shared instance per environment; persistent quota is serialized across processes. */
+export declare class CoWorkerResourceBudget {
+    private readonly options;
+    private readonly store;
+    private readonly admission;
+    constructor(options: Readonly<{
+        directory: string;
+        limits(): CoWorkerResourceLimits;
+        now?: () => number;
+    }>);
+    status(): Promise<CoWorkerResourceUsage & Readonly<{
+        activeCalls: number;
+    }>>;
+    /** Persist the day only for an actual effect, such as a proposal delivery. Status never writes. */
+    ensureCurrentWindow(): Promise<CoWorkerResourceUsage & Readonly<{
+        activeCalls: number;
+    }>>;
+    reserve(reservation: CoWorkerResourceReservation): Promise<() => void>;
+    private now;
+}

package/dist/src/runtime/passive-learning/resources/budget.js

@@ -0,0 +1,78 @@
+import { validateCoWorkerResourceLimits, } from "./contracts.js";
+import { resolveCoWorkerBudgetDay } from "./day-window.js";
+import { createCoWorkerResourceStore } from "./store.js";
+import { CoWorkerResourceAdmission } from "./admission.js";
+function reserveDailyCapacity(usage, limits, reservation) {
+    if (reservation.kind === "model") {
+        if (usage.modelCalls >= limits.modelCallsPerDay)
+            throw new Error("co_worker_model_daily_budget_exhausted");
+        return { ...usage, modelCalls: usage.modelCalls + 1 };
+    }
+    const characters = reservation.embeddingCharacters ?? 0;
+    if (!Number.isSafeInteger(characters) || characters < 0)
+        throw new Error("co_worker_embedding_characters_invalid");
+    if (usage.embeddingCalls >= limits.embeddingCallsPerDay)
+        throw new Error("co_worker_embedding_daily_budget_exhausted");
+    if (characters > limits.embeddingCharactersPerDay - usage.embeddingCharacters)
+        throw new Error("co_worker_embedding_character_budget_exhausted");
+    return {
+        ...usage,
+        embeddingCalls: usage.embeddingCalls + 1,
+        embeddingCharacters: usage.embeddingCharacters + characters,
+    };
+}
+/** One shared instance per environment; persistent quota is serialized across processes. */
+export class CoWorkerResourceBudget {
+    options;
+    store;
+    admission = new CoWorkerResourceAdmission();
+    constructor(options) {
+        this.options = options;
+        this.store = createCoWorkerResourceStore(options.directory);
+    }
+    async status() {
+        const limits = this.options.limits();
+        validateCoWorkerResourceLimits(limits);
+        const usage = resolveCoWorkerBudgetDay(await this.store.read(), this.now(), limits.timeZone);
+        return { ...usage, activeCalls: this.admission.activeCalls };
+    }
+    /** Persist the day only for an actual effect, such as a proposal delivery. Status never writes. */
+    async ensureCurrentWindow() {
+        const usage = await this.store.update((previous) => {
+            const limits = this.options.limits();
+            validateCoWorkerResourceLimits(limits);
+            return resolveCoWorkerBudgetDay(previous, this.now(), limits.timeZone);
+        });
+        return { ...usage, activeCalls: this.admission.activeCalls };
+    }
+    async reserve(reservation) {
+        reservation.signal.throwIfAborted();
+        const limits = this.options.limits();
+        validateCoWorkerResourceLimits(limits);
+        const release = await this.admission.acquire({
+            ...reservation,
+            maximum: () => {
+                const current = this.options.limits();
+                validateCoWorkerResourceLimits(current);
+                return current.maxConcurrentCalls;
+            },
+        });
+        try {
+            await this.store.update((previous) => {
+                reservation.signal.throwIfAborted();
+                reservation.assertActivityAllowed();
+                const currentLimits = this.options.limits();
+                validateCoWorkerResourceLimits(currentLimits);
+                return reserveDailyCapacity(resolveCoWorkerBudgetDay(previous, this.now(), currentLimits.timeZone), currentLimits, reservation);
+            });
+            return release;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+}

package/dist/src/runtime/passive-learning/resources/contracts.d.ts

@@ -0,0 +1,29 @@
+export type CoWorkerResourceLimits = Readonly<{
+    modelCallsPerDay: number;
+    embeddingCallsPerDay: number;
+    embeddingCharactersPerDay: number;
+    maxConcurrentCalls: number;
+    timeZone: string;
+}>;
+/** Embedding safety defaults are implementation limits, independently configurable. */
+export declare const DEFAULT_CO_WORKER_RESOURCE_LIMITS: CoWorkerResourceLimits;
+export type CoWorkerResourceUsage = Readonly<{
+    schemaVersion: 1;
+    timeZone: string;
+    startedAt: number;
+    resetsAt: number;
+    modelCalls: number;
+    embeddingCalls: number;
+    embeddingCharacters: number;
+}>;
+export type CoWorkerResourceActivity = "processing" | "proactive";
+export type CoWorkerResourceReservation = Readonly<{
+    kind: "model" | "embedding";
+    activity?: CoWorkerResourceActivity;
+    /** Only known cloud providers may opt into parallel execution. */
+    supportsParallel: boolean;
+    embeddingCharacters?: number;
+    signal: AbortSignal;
+    assertActivityAllowed(): void;
+}>;
+export declare function validateCoWorkerResourceLimits(limits: CoWorkerResourceLimits): void;

package/dist/src/runtime/passive-learning/resources/contracts.js

@@ -0,0 +1,26 @@
+/** Embedding safety defaults are implementation limits, independently configurable. */
+export const DEFAULT_CO_WORKER_RESOURCE_LIMITS = Object.freeze({
+    modelCallsPerDay: 24,
+    embeddingCallsPerDay: 96,
+    embeddingCharactersPerDay: 1_048_576,
+    maxConcurrentCalls: 1,
+    timeZone: "UTC",
+});
+export function validateCoWorkerResourceLimits(limits) {
+    const counts = [
+        limits.modelCallsPerDay,
+        limits.embeddingCallsPerDay,
+        limits.embeddingCharactersPerDay,
+        limits.maxConcurrentCalls,
+    ];
+    if (counts.some((value) => !Number.isSafeInteger(value) || value < 1))
+        throw new Error("co_worker_resource_limits_invalid");
+    if (limits.maxConcurrentCalls > 8)
+        throw new Error("co_worker_resource_limits_invalid");
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: limits.timeZone }).format(0);
+    }
+    catch {
+        throw new Error("co_worker_resource_time_zone_invalid");
+    }
+}

package/dist/src/runtime/passive-learning/resources/day-window.d.ts

@@ -0,0 +1,3 @@
+import type { CoWorkerResourceUsage } from "./contracts.js";
+/** A zone edit never advances an existing reset or creates a short transition day. */
+export declare function resolveCoWorkerBudgetDay(previous: CoWorkerResourceUsage | undefined, now: number, timeZone: string): CoWorkerResourceUsage;

package/dist/src/runtime/passive-learning/resources/day-window.js

@@ -0,0 +1,39 @@
+import { nextSchedulerOccurrence } from "../../scheduler/next-occurrence.js";
+import { addCalendarDays, calendarDateAt, resolveCalendarTime, } from "../../scheduler/calendar-time.js";
+function nextLocalMidnight(now, timeZone) {
+    const next = nextSchedulerOccurrence({ kind: "daily", at: "00:00" }, timeZone, now);
+    if (!next)
+        throw new Error("co_worker_budget_reset_unavailable");
+    return Date.parse(next);
+}
+function previousLocalMidnight(now, timeZone) {
+    const current = calendarDateAt(now, timeZone);
+    for (let offset = 0; offset < 370; offset += 1) {
+        const midnight = resolveCalendarTime(addCalendarDays(current, -offset), "00:00", timeZone);
+        if (midnight !== null && midnight <= now)
+            return midnight;
+    }
+    throw new Error("co_worker_budget_reset_unavailable");
+}
+/** A zone edit never advances an existing reset or creates a short transition day. */
+export function resolveCoWorkerBudgetDay(previous, now, timeZone) {
+    if (!Number.isFinite(now))
+        throw new Error("co_worker_budget_clock_invalid");
+    if (previous && now < previous.resetsAt)
+        return previous;
+    let resetsAt = nextLocalMidnight(now, timeZone);
+    if (previous && previous.timeZone !== timeZone) {
+        const oldZoneNextReset = nextLocalMidnight(now, previous.timeZone);
+        if (resetsAt < oldZoneNextReset)
+            resetsAt = nextLocalMidnight(oldZoneNextReset - 1, timeZone);
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        timeZone,
+        startedAt: Math.max(previous?.resetsAt ?? -Infinity, previousLocalMidnight(now, timeZone)),
+        resetsAt,
+        modelCalls: 0,
+        embeddingCalls: 0,
+        embeddingCharacters: 0,
+    });
+}

package/dist/src/runtime/passive-learning/resources/gateway.d.ts

@@ -0,0 +1,13 @@
+import type { ModelGatewayClient } from "../../ports.js";
+import type { CoWorkerResourceBudget } from "./budget.js";
+import type { CoWorkerResourceActivity } from "./contracts.js";
+type CoWorkerGatewayCall = Parameters<ModelGatewayClient["invoke"]>[0] | Parameters<ModelGatewayClient["invokeRaw"]>[0] | Parameters<NonNullable<ModelGatewayClient["embed"]>>[0];
+/** Scope this client to Co-worker; ordinary chat and memory retain their own client. */
+export declare function createCoWorkerResourceGateway(options: Readonly<{
+    gateway: ModelGatewayClient;
+    budget: CoWorkerResourceBudget;
+    activity?: CoWorkerResourceActivity;
+    assertActivityAllowed(): void;
+    supportsParallel(params: CoWorkerGatewayCall): boolean;
+}>): ModelGatewayClient;
+export {};

package/dist/src/runtime/passive-learning/resources/gateway.js

@@ -0,0 +1,38 @@
+/** Scope this client to Co-worker; ordinary chat and memory retain their own client. */
+export function createCoWorkerResourceGateway(options) {
+    async function invoke(params, kind, operation, embeddingCharacters) {
+        const release = await options.budget.reserve({
+            kind,
+            ...(options.activity ? { activity: options.activity } : {}),
+            supportsParallel: options.supportsParallel(params),
+            signal: params.abortSignal,
+            assertActivityAllowed: options.assertActivityAllowed,
+            ...(embeddingCharacters === undefined ? {} : { embeddingCharacters }),
+        });
+        try {
+            // A pause or window end during the durable reservation must prevent dispatch.
+            params.abortSignal.throwIfAborted();
+            options.assertActivityAllowed();
+            return await operation();
+        }
+        finally {
+            // A failed, cancelled or interrupted admitted attempt never refunds quota.
+            release();
+        }
+    }
+    const { gateway } = options;
+    return Object.freeze({
+        invoke: (params) => invoke(params, "model", () => gateway.invoke(params)),
+        invokeRaw: (params) => invoke(params, "model", () => gateway.invokeRaw(params)),
+        ...(gateway.countInputTokens
+            ? {
+                countInputTokens: (params) => gateway.countInputTokens(params),
+            }
+            : {}),
+        ...(gateway.embed
+            ? {
+                embed: (params) => invoke(params, "embedding", () => gateway.embed(params), params.texts.reduce((total, text) => total + text.length, 0)),
+            }
+            : {}),
+    });
+}

package/dist/src/runtime/passive-learning/resources/store.d.ts

@@ -0,0 +1,13 @@
+import type { CoWorkerResourceUsage } from "./contracts.js";
+export declare function createCoWorkerResourceStore(directory: string): Readonly<{
+    read: () => Promise<CoWorkerResourceUsage | undefined>;
+    update(change: (previous: CoWorkerResourceUsage | undefined) => CoWorkerResourceUsage): Promise<Readonly<{
+        schemaVersion: 1;
+        timeZone: string;
+        startedAt: number;
+        resetsAt: number;
+        modelCalls: number;
+        embeddingCalls: number;
+        embeddingCharacters: number;
+    }>>;
+}>;

package/dist/src/runtime/passive-learning/resources/store.js

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { withFileLock } from "../../adapters/long-term-memory/file-lock.js";
+import { fileSystemErrorCode } from "../../adapters/long-term-memory/file-lock/contracts.js";
+const MAX_BUDGET_STATE_BYTES = 2_048;
+function parseResourceUsage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("co_worker_budget_state_invalid");
+    const state = value;
+    if (state.schemaVersion !== 1)
+        throw new Error("co_worker_budget_state_invalid");
+    if (!Number.isFinite(state.startedAt) || !Number.isFinite(state.resetsAt))
+        throw new Error("co_worker_budget_state_invalid");
+    if (state.resetsAt <= state.startedAt)
+        throw new Error("co_worker_budget_state_invalid");
+    const counters = [
+        state.modelCalls,
+        state.embeddingCalls,
+        state.embeddingCharacters,
+    ];
+    if (counters.some((count) => !Number.isSafeInteger(count) || count < 0))
+        throw new Error("co_worker_budget_state_invalid");
+    if (typeof state.timeZone !== "string")
+        throw new Error("co_worker_budget_state_invalid");
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: state.timeZone }).format(0);
+    }
+    catch {
+        throw new Error("co_worker_budget_state_invalid");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        timeZone: state.timeZone,
+        startedAt: state.startedAt,
+        resetsAt: state.resetsAt,
+        modelCalls: state.modelCalls,
+        embeddingCalls: state.embeddingCalls,
+        embeddingCharacters: state.embeddingCharacters,
+    });
+}
+export function createCoWorkerResourceStore(directory) {
+    const file = join(directory, "resource-budget.json");
+    async function read() {
+        try {
+            const handle = await open(file, "r");
+            try {
+                const buffer = Buffer.alloc(MAX_BUDGET_STATE_BYTES + 1);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (bytesRead > MAX_BUDGET_STATE_BYTES)
+                    throw new Error("co_worker_budget_state_too_large");
+                return parseResourceUsage(JSON.parse(buffer.subarray(0, bytesRead).toString("utf8")));
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (fileSystemErrorCode(error) === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async function write(state) {
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            const handle = await open(temporary, "wx", 0o600);
+            try {
+                await handle.writeFile(JSON.stringify(state));
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, file);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    return Object.freeze({
+        read,
+        async update(change) {
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            return withFileLock(`${file}.lock`, async () => {
+                const previous = await read();
+                const changed = change(previous);
+                if (changed === previous)
+                    return changed;
+                const next = parseResourceUsage(changed);
+                await write(next);
+                return next;
+            });
+        },
+    });
+}

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

@@ -0,0 +1,20 @@
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+import type { LearningBatch, PassiveLearningModel } from "./contracts.js";
+import type { ReviewProgressPort } from "./review-progress.js";
+/** Model choice and memory commit are separate; only a durable receipt is success. */
+export declare function reviewLearningBatch(options: {
+    batch: LearningBatch;
+    model: PassiveLearningModel;
+    memory: LongTermMemoryService;
+    modelProfileId: string;
+    signal: AbortSignal;
+    ownerId: string;
+    isCurrent(): boolean;
+    progress?: ReviewProgressPort;
+}): Promise<Readonly<{
+    batchId: string;
+    recordIds: readonly string[];
+    candidateIds?: readonly string[];
+    createdAt: string;
+    expiresAt?: string;
+}>>;