@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/runtime/scheduler/journal-store.js

@@ -0,0 +1,184 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SchedulerJournalIndex, isActiveSchedulerRun, } from "./journal-index.js";
+import { cleanObsoleteJournalGenerations, createJournalGeneration, initialJournalTransaction, isMissingJournalFile, journalTransactionName, loadJournalIndex, SCHEDULER_MANIFEST, writeJournalJson, } from "./journal-files.js";
+import { hasSchedulerTransactionChanges, schedulerTransaction, } from "./journal-transaction.js";
+import { querySchedulerRuns } from "./run-list-query.js";
+import { parseSchedulerSnapshot } from "./snapshot-validation.js";
+import { MAX_JOURNAL_SUFFIX, readJournalHead, } from "./journal-head.js";
+import { cleanObsoleteJournalCheckpoints, loadCheckpointJournalIndex, writeJournalCheckpoint, } from "./journal-checkpoint.js";
+import { JournalPublicationSyncError, syncJournalDirectory, syncJournalDirectoryPath, } from "./journal-durability.js";
+export class SchedulerJournalStore {
+    directory;
+    index = new SchedulerJournalIndex();
+    sequence = 0;
+    generation;
+    head;
+    legacy;
+    publicationFailure;
+    ownedDirectoriesSynced = false;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async load() {
+        const head = await readJournalHead(this.directory);
+        this.generation = head?.generation;
+        if (head?.schemaVersion === 3) {
+            const loaded = await loadCheckpointJournalIndex(this.directory, head);
+            this.index = loaded.index;
+            this.sequence = loaded.sequence;
+            this.head = head;
+            return this;
+        }
+        if (this.generation) {
+            const loaded = await loadJournalIndex(this.directory, this.generation);
+            this.index = loaded.index;
+            this.sequence = loaded.sequence;
+            return this;
+        }
+        try {
+            this.legacy = parseSchedulerSnapshot(JSON.parse(await readFile(join(this.directory, "scheduler.json"), "utf8")));
+        }
+        catch (error) {
+            if (!isMissingJournalFile(error))
+                throw error;
+            this.legacy = { schemaVersion: 1, jobs: [], runs: [] };
+        }
+        return this;
+    }
+    async prepareOwned() {
+        this.requireDurablePublication();
+        await this.ensureOwnedDirectoriesSynced();
+        await cleanObsoleteJournalGenerations(this.directory, this.generation);
+        if (this.legacy)
+            await this.replaceGeneration(this.legacy);
+        if (requiresJournalCheckpoint(this.head, this.sequence)) {
+            const head = await writeJournalCheckpoint(this.directory, this.generation, this.sequence, this.index);
+            await this.publishHead(head);
+            this.head = head;
+        }
+        await cleanObsoleteJournalCheckpoints(this.directory, this.head);
+    }
+    async snapshot(view) {
+        this.requireDurablePublication();
+        if (!this.legacy)
+            return this.index.snapshot(view);
+        const runs = view === "active"
+            ? this.legacy.runs.filter(isActiveSchedulerRun)
+            : this.legacy.runs;
+        return structuredClone({ ...this.legacy, runs });
+    }
+    async readRuns(jobId, query) {
+        this.requireDurablePublication();
+        if (!this.legacy)
+            return this.index.readRuns(jobId, query);
+        return structuredClone(querySchedulerRuns(this.legacy.runs, jobId, query));
+    }
+    async update(mutate, view) {
+        // Retry storage cleanup before, never after committing an ordinary mutation.
+        await this.prepareOwned();
+        const before = await this.snapshot(view);
+        const candidate = structuredClone(before);
+        const result = structuredClone(mutate(candidate));
+        const after = parseSchedulerSnapshot(structuredClone(candidate));
+        const delta = schedulerTransaction(before, after, view);
+        if (!hasSchedulerTransactionChanges(delta))
+            return result;
+        this.index.validate(delta);
+        if (hasJournalRemovals(delta)) {
+            const complete = view === "active"
+                ? applyWorkingChanges(await this.snapshot(), delta)
+                : after;
+            await this.replaceGeneration(complete);
+            return result;
+        }
+        const file = join(this.directory, this.generation, journalTransactionName(this.sequence + 1));
+        await writeJournalJson(file, delta);
+        const head = { ...this.head, sequence: this.sequence + 1 };
+        await this.publishHead(head);
+        this.index.apply(delta, file);
+        this.sequence += 1;
+        this.head = head;
+        return result;
+    }
+    async replaceGeneration(snapshot) {
+        const generation = await createJournalGeneration(this.directory);
+        const index = new SchedulerJournalIndex();
+        let sequence = 0;
+        const append = async (delta) => {
+            const file = join(this.directory, generation, journalTransactionName(++sequence));
+            index.validate(delta);
+            await writeJournalJson(file, delta);
+            index.apply(delta, file);
+        };
+        await append({ ...initialJournalTransaction(), jobs: snapshot.jobs });
+        // Bound boot/import transaction payloads; ordinary commits contain only changes.
+        for (let offset = 0; offset < snapshot.runs.length; offset += 32) {
+            await append({
+                ...initialJournalTransaction(),
+                runs: snapshot.runs.slice(offset, offset + 32),
+            });
+        }
+        const head = await writeJournalCheckpoint(this.directory, generation, sequence, index);
+        await this.publishHead(head);
+        this.index = index;
+        this.sequence = sequence;
+        this.generation = generation;
+        this.head = head;
+        this.legacy = undefined;
+        // Failed physical removal remains discoverable on the next explicit operation.
+        await cleanObsoleteJournalGenerations(this.directory, generation);
+    }
+    async ensureOwnedDirectoriesSynced() {
+        if (this.ownedDirectoriesSynced)
+            return;
+        // Older writers synced files only; establish their selected entries before cleanup.
+        if (this.head)
+            await syncJournalDirectory(join(this.directory, this.head.generation, "checkpoints"));
+        if (this.generation)
+            await syncJournalDirectory(join(this.directory, this.generation));
+        await syncJournalDirectoryPath(this.directory);
+        this.ownedDirectoriesSynced = true;
+    }
+    async publishHead(head) {
+        try {
+            await writeJournalJson(join(this.directory, SCHEDULER_MANIFEST), head);
+        }
+        catch (error) {
+            if (error instanceof JournalPublicationSyncError)
+                this.publicationFailure = error;
+            throw error;
+        }
+    }
+    requireDurablePublication() {
+        // A visible head may differ from this cache; only a new owned load may accept it.
+        if (this.publicationFailure)
+            throw this.publicationFailure;
+    }
+}
+function requiresJournalCheckpoint(head, sequence) {
+    if (!head)
+        return true;
+    return sequence - head.checkpoint.sequence >= MAX_JOURNAL_SUFFIX;
+}
+function hasJournalRemovals(delta) {
+    return delta.deletedJobs.length > 0 || delta.deletedRuns.length > 0;
+}
+function applyWorkingChanges(snapshot, delta) {
+    const jobs = new Map(snapshot.jobs.map((job) => [job.id, job]));
+    const runs = new Map(snapshot.runs.map((run) => [run.id, run]));
+    for (const id of delta.deletedJobs)
+        jobs.delete(id);
+    for (const job of delta.jobs)
+        jobs.set(job.id, job);
+    for (const id of delta.deletedRuns)
+        runs.delete(id);
+    for (const run of delta.runs)
+        runs.set(run.id, run);
+    const jobOrder = delta.jobOrder ?? [...jobs.keys()];
+    return {
+        schemaVersion: 1,
+        jobs: jobOrder.map((id) => jobs.get(id)),
+        runs: [...runs.values()].filter((run) => jobs.has(run.jobId)),
+    };
+}

package/dist/src/runtime/scheduler/journal-transaction.d.ts

@@ -0,0 +1,14 @@
+import type { SchedulerJob, SchedulerRun, SchedulerSnapshot } from "./contracts.js";
+export interface SchedulerTransaction {
+    version: 1;
+    jobs: SchedulerJob[];
+    runs: SchedulerRun[];
+    deletedJobs: string[];
+    deletedRuns: string[];
+    jobOrder?: string[];
+    runOrder?: string[];
+}
+export declare function parseSchedulerTransaction(value: unknown): SchedulerTransaction;
+export declare function assertJournalTransactionIds(transaction: SchedulerTransaction): void;
+export declare function schedulerTransaction(before: SchedulerSnapshot, after: SchedulerSnapshot, view?: "active"): SchedulerTransaction;
+export declare function hasSchedulerTransactionChanges(value: SchedulerTransaction): boolean;

package/dist/src/runtime/scheduler/journal-transaction.js

@@ -0,0 +1,104 @@
+import { parseStoredJob, parseStoredRun } from "./snapshot-validation.js";
+export function parseSchedulerTransaction(value) {
+    if (!isSchedulerTransactionRecord(value))
+        throw new Error("scheduler_store_corrupt");
+    const raw = value;
+    if (!hasSchedulerTransactionCollections(raw))
+        throw new Error("scheduler_store_corrupt");
+    const transaction = {
+        version: 1,
+        jobs: raw.jobs.map(parseStoredJob),
+        runs: raw.runs.map(parseStoredRun),
+        deletedJobs: requireJournalIds(raw.deletedJobs),
+        deletedRuns: requireJournalIds(raw.deletedRuns),
+        ...(raw.jobOrder === undefined
+            ? {}
+            : { jobOrder: requireJournalIds(raw.jobOrder) }),
+        ...(raw.runOrder === undefined
+            ? {}
+            : { runOrder: requireJournalIds(raw.runOrder) }),
+    };
+    assertJournalTransactionIds(transaction);
+    return transaction;
+}
+function isSchedulerTransactionRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    return !Array.isArray(value);
+}
+function hasSchedulerTransactionCollections(value) {
+    if (value.version !== 1)
+        return false;
+    if (!Array.isArray(value.jobs))
+        return false;
+    return Array.isArray(value.runs);
+}
+export function assertJournalTransactionIds(transaction) {
+    assertDisjointJournalRecords(transaction.jobs, transaction.deletedJobs);
+    assertDisjointJournalRecords(transaction.runs, transaction.deletedRuns);
+    if (transaction.jobOrder)
+        requireJournalIds(transaction.jobOrder);
+    if (transaction.runOrder)
+        requireJournalIds(transaction.runOrder);
+}
+function assertDisjointJournalRecords(records, deleted) {
+    const ids = new Set(requireJournalIds(records.map((record) => record.id)));
+    if (hasOverlappingJournalIds(ids, requireJournalIds(deleted)))
+        throw new Error("scheduler_store_corrupt");
+}
+function hasOverlappingJournalIds(upserted, deleted) {
+    return deleted.some((id) => upserted.has(id));
+}
+function requireJournalIds(value) {
+    if (!Array.isArray(value))
+        throw new Error("scheduler_store_corrupt");
+    if (!hasOnlyJournalIdStrings(value))
+        throw new Error("scheduler_store_corrupt");
+    if (hasDuplicateJournalIds(value))
+        throw new Error("scheduler_store_corrupt");
+    return [...value];
+}
+function hasOnlyJournalIdStrings(value) {
+    return value.every((id) => typeof id === "string");
+}
+function hasDuplicateJournalIds(value) {
+    return new Set(value).size !== value.length;
+}
+function changedRecords(before, after) {
+    const originals = new Map(before.map((item) => [item.id, item]));
+    return after.filter((item) => JSON.stringify(originals.get(item.id)) !== JSON.stringify(item));
+}
+function removedRecords(before, after) {
+    const retained = new Set(after.map((item) => item.id));
+    return before.filter((item) => !retained.has(item.id)).map((item) => item.id);
+}
+export function schedulerTransaction(before, after, view) {
+    const jobOrder = after.jobs.map((item) => item.id);
+    const runOrder = after.runs.map((item) => item.id);
+    return {
+        version: 1,
+        jobs: changedRecords(before.jobs, after.jobs),
+        runs: changedRecords(before.runs, after.runs),
+        deletedJobs: removedRecords(before.jobs, after.jobs),
+        deletedRuns: removedRecords(before.runs, after.runs),
+        ...(hasJournalOrderChanged(before.jobs, jobOrder) ? { jobOrder } : {}),
+        ...(shouldPersistRunOrder(view, before.runs, runOrder) ? { runOrder } : {}),
+    };
+}
+function hasJournalOrderChanged(before, order) {
+    if (before.length !== order.length)
+        return true;
+    return before.some((record, index) => record.id !== order[index]);
+}
+function shouldPersistRunOrder(view, before, order) {
+    if (view === "active")
+        return false;
+    return hasJournalOrderChanged(before, order);
+}
+export function hasSchedulerTransactionChanges(value) {
+    if (value.jobs.length || value.runs.length)
+        return true;
+    if (value.deletedJobs.length || value.deletedRuns.length)
+        return true;
+    return value.jobOrder !== undefined || value.runOrder !== undefined;
+}

package/dist/src/runtime/scheduler/next-occurrence.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerSchedule } from "./contracts.js";
+/** Strictly after the supplied instant. Never shifts missing calendar dates or times. */
+export declare function nextSchedulerOccurrence(schedule: SchedulerSchedule, timeZone: string, after: number): string | null;

package/dist/src/runtime/scheduler/next-occurrence.js

@@ -0,0 +1,39 @@
+import { isSupportedSchedulerInstant, schedulerInstantFromMilliseconds, } from "./instant-validation.js";
+import { nextIntervalOccurrence } from "./interval-range.js";
+import { addCalendarDays, calendarDateAt, calendarWeekday, resolveCalendarTime, } from "./calendar-time.js";
+/** Strictly after the supplied instant. Never shifts missing calendar dates or times. */
+export function nextSchedulerOccurrence(schedule, timeZone, after) {
+    switch (schedule.kind) {
+        case "timer":
+        case "once":
+            return Date.parse(schedule.at) > after ? schedule.at : null;
+        case "interval":
+            return nextIntervalOccurrence(schedule, after);
+        default:
+            return nextCalendarOccurrence(schedule, timeZone, after);
+    }
+}
+function nextCalendarOccurrence(schedule, timeZone, after) {
+    const start = calendarDateAt(after, timeZone);
+    for (let offset = 0; offset < 370; offset += 1) {
+        const date = addCalendarDays(start, offset);
+        if (!matchesCalendarDay(schedule, date))
+            continue;
+        const instant = resolveCalendarTime(date, schedule.at, timeZone);
+        if (instant === null)
+            continue;
+        if (instant <= after)
+            continue;
+        if (!isSupportedSchedulerInstant(instant))
+            return null;
+        return schedulerInstantFromMilliseconds(instant);
+    }
+    throw new Error("scheduler_next_occurrence_unavailable");
+}
+function matchesCalendarDay(schedule, date) {
+    if (schedule.kind === "daily")
+        return true;
+    if (schedule.kind === "monthly")
+        return date.day === schedule.dayOfMonth;
+    return schedule.weekdays.includes(calendarWeekday(date));
+}

package/dist/src/runtime/scheduler/run-completion.d.ts

@@ -0,0 +1,12 @@
+import type { SchedulerRun, SchedulerRunOutcome } from "./contracts.js";
+import type { SchedulerContext } from "./service-context.js";
+export interface SchedulerRunCompletion {
+    runId: string;
+    sessionId: string;
+    requestId: string;
+    generation: number;
+    outcome: SchedulerRunOutcome;
+    finishedAt: string;
+}
+export declare function settleSchedulerRun(context: SchedulerContext, run: SchedulerRun, generation: number, execution: Promise<SchedulerRunOutcome>, release: () => void): Promise<void>;
+export declare function reconcileSchedulerCompletions(context: SchedulerContext): Promise<void>;

package/dist/src/runtime/scheduler/run-completion.js

@@ -0,0 +1,77 @@
+export async function settleSchedulerRun(context, run, generation, execution, release) {
+    const identity = {
+        runId: run.id,
+        sessionId: run.sessionId,
+        requestId: run.requestId,
+    };
+    try {
+        const outcome = await execution.catch((error) => ({
+            status: "failed",
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        const completion = {
+            ...identity,
+            generation,
+            outcome: { ...outcome },
+            finishedAt: new Date(context.now()).toISOString(),
+        };
+        await context.enqueue(async () => {
+            if (!canPersistCompletion(context, completion))
+                return;
+            context.pendingCompletions.set(completion.runId, completion);
+            await persistCompletion(context, completion);
+        });
+    }
+    catch (error) {
+        context.onError(error);
+    }
+    finally {
+        release();
+    }
+}
+export async function reconcileSchedulerCompletions(context) {
+    // Each ordinary tick attempts retained writes once, without executing work.
+    for (const completion of context.pendingCompletions.values()) {
+        await persistCompletion(context, completion);
+    }
+}
+async function persistCompletion(context, completion) {
+    if (!canPersistCompletion(context, completion)) {
+        context.pendingCompletions.delete(completion.runId);
+        return;
+    }
+    try {
+        await context.store.update((state) => {
+            // Stop and session deletion can arrive while the store awaits its read.
+            if (!canPersistCompletion(context, completion))
+                return;
+            const run = state.runs.find((candidate) => candidate.id === completion.runId);
+            if (!isUnsettledCapturedRun(run, completion))
+                return;
+            Object.assign(run, completion.outcome, {
+                finishedAt: completion.finishedAt,
+            });
+        });
+        context.pendingCompletions.delete(completion.runId);
+    }
+    catch (error) {
+        // Keep the captured outcome for a later clock tick, not an execution retry.
+        context.onError(error);
+    }
+}
+function canPersistCompletion(context, completion) {
+    if (!context.running)
+        return false;
+    if (context.generation !== completion.generation)
+        return false;
+    return !context.deletedSessions.has(completion.sessionId);
+}
+function isUnsettledCapturedRun(run, completion) {
+    if (!run)
+        return false;
+    if (run.status !== "running")
+        return false;
+    if (run.sessionId !== completion.sessionId)
+        return false;
+    return run.requestId === completion.requestId;
+}

package/dist/src/runtime/scheduler/run-list-query.d.ts

@@ -0,0 +1,5 @@
+import type { SchedulerRun, SchedulerRunListQuery } from "./contracts.js";
+/** Omitted queries retain the public service's complete, chronological result. */
+type RunListIdentity = Pick<SchedulerRun, "id" | "jobId" | "scheduledAt">;
+export declare function querySchedulerRuns<T extends RunListIdentity>(runs: readonly T[], jobId: string | undefined, query: SchedulerRunListQuery | undefined): T[];
+export {};

package/dist/src/runtime/scheduler/run-list-query.js

@@ -0,0 +1,38 @@
+export function querySchedulerRuns(runs, jobId, query) {
+    const scoped = runs.filter((run) => jobId === undefined || run.jobId === jobId);
+    if (query === undefined)
+        return scoped;
+    const limit = requireRunPageLimit(query?.limit);
+    const ordered = scoped.sort(compareNewestRuns);
+    const offset = runCursorOffset(ordered, query.cursor);
+    return ordered.slice(offset, offset + limit);
+}
+function requireRunPageLimit(limit) {
+    if (!Number.isSafeInteger(limit))
+        throw new Error("scheduler_run_page_limit_invalid");
+    if (Number(limit) < 1)
+        throw new Error("scheduler_run_page_limit_invalid");
+    if (Number(limit) > 101)
+        throw new Error("scheduler_run_page_limit_invalid");
+    return Number(limit);
+}
+function runCursorOffset(runs, cursor) {
+    if (cursor === undefined)
+        return 0;
+    if (typeof cursor !== "string")
+        throw new Error("scheduler_run_cursor_invalid");
+    if (!cursor)
+        throw new Error("scheduler_run_cursor_invalid");
+    const index = runs.findIndex((run) => run.id === cursor);
+    if (index < 0)
+        throw new Error("scheduler_run_cursor_not_found");
+    return index + 1;
+}
+function compareNewestRuns(left, right) {
+    const scheduled = Date.parse(right.scheduledAt) - Date.parse(left.scheduledAt);
+    if (scheduled !== 0)
+        return scheduled;
+    if (left.id === right.id)
+        return 0;
+    return left.id < right.id ? 1 : -1;
+}

package/dist/src/runtime/scheduler/run-records.d.ts

@@ -0,0 +1,6 @@
+import type { SchedulerJob, SchedulerRun, SchedulerSnapshot } from "./contracts.js";
+export declare function makeSchedulerRun(job: SchedulerJob, scheduledAt: string, trigger: SchedulerRun["trigger"]): SchedulerRun;
+export declare function findPendingRun(state: SchedulerSnapshot, jobId: string): SchedulerRun | undefined;
+export declare function cancelPendingRuns(state: SchedulerSnapshot, jobId: string, at: string): void;
+export declare function requireSchedulerJob(state: SchedulerSnapshot, jobId: string): SchedulerJob;
+export declare function hasRunningSession(state: SchedulerSnapshot, sessionId: string): boolean;

package/dist/src/runtime/scheduler/run-records.js

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+export function makeSchedulerRun(job, scheduledAt, trigger) {
+    return {
+        id: randomUUID(),
+        requestId: randomUUID(),
+        jobId: job.id,
+        environmentId: job.environmentId,
+        sessionId: job.sessionId,
+        title: job.title,
+        prompt: job.prompt,
+        modelProfileId: job.modelProfileId,
+        agentMode: job.agentMode,
+        timeZone: job.timeZone,
+        jobRevision: job.revision,
+        scheduledAt,
+        trigger,
+        status: "pending",
+    };
+}
+export function findPendingRun(state, jobId) {
+    return state.runs.find((run) => run.jobId === jobId && run.status === "pending");
+}
+export function cancelPendingRuns(state, jobId, at) {
+    for (const run of state.runs) {
+        if (run.jobId !== jobId)
+            continue;
+        if (run.status !== "pending")
+            continue;
+        run.status = "cancelled";
+        run.finishedAt = at;
+    }
+}
+export function requireSchedulerJob(state, jobId) {
+    const job = state.jobs.find((candidate) => candidate.id === jobId);
+    if (!job)
+        throw new Error("scheduler_job_not_found");
+    return job;
+}
+export function hasRunningSession(state, sessionId) {
+    return state.runs.some((run) => run.sessionId === sessionId && run.status === "running");
+}

package/dist/src/runtime/scheduler/schedule-update.d.ts

@@ -0,0 +1,3 @@
+import type { SchedulerSchedule, SchedulerScheduleInput } from "./contracts.js";
+/** PATCH preserves omitted or exact stored timing; actual edits are new input. */
+export declare function normalizeSchedulerScheduleUpdate(stored: SchedulerSchedule, input: SchedulerScheduleInput | undefined, now: number): SchedulerSchedule;

package/dist/src/runtime/scheduler/schedule-update.js

@@ -0,0 +1,22 @@
+import { normalizeSchedulerSchedule } from "./schedule-validation.js";
+/** PATCH preserves omitted or exact stored timing; actual edits are new input. */
+export function normalizeSchedulerScheduleUpdate(stored, input, now) {
+    if (input === undefined)
+        return stored;
+    if (isExactStoredTimerSchedule(stored, input))
+        return stored;
+    return normalizeSchedulerSchedule(input, now);
+}
+function isExactStoredTimerSchedule(stored, input) {
+    if (!input || typeof input !== "object")
+        return false;
+    if (stored.kind !== "timer")
+        return false;
+    if (input.kind !== "timer")
+        return false;
+    if (input.delayMs !== stored.delayMs)
+        return false;
+    if (!("at" in input))
+        return false;
+    return input.at === stored.at;
+}

package/dist/src/runtime/scheduler/schedule-validation.d.ts

@@ -0,0 +1,10 @@
+import type { CreateSchedulerJobInput, SchedulerSchedule, SchedulerScheduleInput } from "./contracts.js";
+export { SchedulerValidationError } from "./validation-error.js";
+export { parseSchedulerInstant } from "./instant-validation.js";
+export declare function requireSchedulerText(value: unknown, field: string): string;
+export declare function validateSchedulerJobInput(input: CreateSchedulerJobInput): void;
+export declare function validateTimeZone(timeZone: string): void;
+export declare function requireCalendarHour(value: unknown): string;
+export declare function normalizeSchedulerSchedule(input: SchedulerScheduleInput, now: number): SchedulerSchedule;
+/** Stored timer deadlines are canonical state, not new relative timer input. */
+export declare function normalizeStoredSchedulerSchedule(schedule: SchedulerSchedule): SchedulerSchedule;