@abot-ai/runtime 1.1.0 → 1.3.0

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

@@ -0,0 +1,76 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { acquireFileLock } from "../adapters/long-term-memory/file-lock/acquisition.js";
+import { SchedulerJournalStore } from "./journal-store.js";
+import { journalReadIdentity, readJournalHead } from "./journal-head.js";
+export function createFileSchedulerStore(directory) {
+    let releaseOwner;
+    let journal;
+    let transactionTail = Promise.resolve();
+    const enqueue = (operation) => {
+        const transaction = transactionTail.then(operation);
+        transactionTail = transaction.catch(() => undefined);
+        return transaction;
+    };
+    const readJournal = async (read) => {
+        if (journal)
+            return read(journal);
+        // Unowned readers have no cached lease. A retired immutable generation is
+        // retried only when its authoritative pointer changed during this read.
+        for (;;) {
+            const before = journalReadIdentity(await readJournalHead(directory));
+            const [result] = await Promise.allSettled([
+                new SchedulerJournalStore(directory).load().then(read),
+            ]);
+            if (before !== journalReadIdentity(await readJournalHead(directory)))
+                continue;
+            if (result.status === "rejected")
+                throw result.reason;
+            return result.value;
+        }
+    };
+    return {
+        acquire: async () => {
+            if (releaseOwner)
+                throw new Error("scheduler_store_in_use");
+            await mkdir(directory, { recursive: true, mode: 0o700 });
+            try {
+                releaseOwner = await acquireFileLock(join(directory, "scheduler.owner"), { waitMs: 0 });
+            }
+            catch (error) {
+                if (isOwnerContention(error))
+                    throw new Error("scheduler_store_in_use");
+                throw error;
+            }
+            try {
+                journal = await new SchedulerJournalStore(directory).load();
+                await journal.prepareOwned();
+            }
+            catch (error) {
+                const release = releaseOwner;
+                releaseOwner = undefined;
+                journal = undefined;
+                await release();
+                throw error;
+            }
+            return async () => {
+                await transactionTail;
+                const release = releaseOwner;
+                releaseOwner = undefined;
+                journal = undefined;
+                await release?.();
+            };
+        },
+        read: (view) => enqueue(() => readJournal((store) => store.snapshot(view))),
+        readRuns: (jobId, query) => enqueue(() => readJournal((store) => store.readRuns(jobId, query))),
+        update: (mutate, view) => enqueue(async () => {
+            if (!releaseOwner || !journal)
+                throw new Error("scheduler_store_not_owned");
+            return journal.update(mutate, view);
+        }),
+    };
+}
+function isOwnerContention(error) {
+    return (error instanceof Error &&
+        error.message === "long_term_memory_store_lock_timeout");
+}

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

@@ -0,0 +1,4 @@
+export declare function parseSchedulerInstant(value: unknown, field: string): string;
+export declare function schedulerInstantFromMilliseconds(value: number): string;
+/** Canonical output must be accepted again by the four-digit ISO parser. */
+export declare function isSupportedSchedulerInstant(value: number): boolean;

package/dist/src/runtime/scheduler/instant-validation.js

@@ -0,0 +1,69 @@
+import { SchedulerValidationError } from "./validation-error.js";
+const MIN_SCHEDULER_INSTANT = Date.parse("0000-01-01T00:00:00.000Z");
+const MAX_SCHEDULER_INSTANT = Date.parse("9999-12-31T23:59:59.999Z");
+export function parseSchedulerInstant(value, field) {
+    if (typeof value !== "string") {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", `${field} requires an ISO instant`);
+    }
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/i.exec(value);
+    if (!match) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", `${field} requires an ISO instant with an explicit UTC offset`);
+    }
+    const [, year, month, day, hour, minute, second = "0"] = match;
+    if (!isExistingCalendarDate(Number(year), Number(month), Number(day))) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", `${field} contains an invalid date`);
+    }
+    if (!isExistingClockTime(Number(hour), Number(minute), Number(second))) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", `${field} contains an invalid time`);
+    }
+    return schedulerInstantFromMilliseconds(Date.parse(value));
+}
+function isExistingCalendarDate(year, month, day) {
+    if (month < 1 || month > 12)
+        return false;
+    if (day < 1)
+        return false;
+    const monthDays = [
+        31,
+        isLeapYear(year) ? 29 : 28,
+        31,
+        30,
+        31,
+        30,
+        31,
+        31,
+        30,
+        31,
+        30,
+        31,
+    ];
+    return day <= monthDays[month - 1];
+}
+function isLeapYear(year) {
+    if (year % 400 === 0)
+        return true;
+    if (year % 100 === 0)
+        return false;
+    return year % 4 === 0;
+}
+function isExistingClockTime(hour, minute, second) {
+    if (hour > 23)
+        return false;
+    if (minute > 59)
+        return false;
+    return second <= 59;
+}
+export function schedulerInstantFromMilliseconds(value) {
+    if (!isSupportedSchedulerInstant(value)) {
+        throw new SchedulerValidationError("scheduler_invalid_schedule", "Instant is outside the supported date range");
+    }
+    return new Date(value).toISOString();
+}
+/** Canonical output must be accepted again by the four-digit ISO parser. */
+export function isSupportedSchedulerInstant(value) {
+    if (!Number.isSafeInteger(value))
+        return false;
+    if (value < MIN_SCHEDULER_INSTANT)
+        return false;
+    return value <= MAX_SCHEDULER_INSTANT;
+}

package/dist/src/runtime/scheduler/interval-range.d.ts

@@ -0,0 +1,8 @@
+import type { SchedulerSchedule } from "./contracts.js";
+type IntervalSchedule = Extract<SchedulerSchedule, {
+    kind: "interval";
+}>;
+export declare function nextIntervalOccurrence(schedule: IntervalSchedule, after: number): string | null;
+/** Admission only: legacy stored intervals remain readable until exhaustion. */
+export declare function requireRepresentableIntervalRecurrence(schedule: SchedulerSchedule, after: number): void;
+export {};

package/dist/src/runtime/scheduler/interval-range.js

@@ -0,0 +1,24 @@
+import { isSupportedSchedulerInstant, schedulerInstantFromMilliseconds, } from "./instant-validation.js";
+import { SchedulerValidationError } from "./validation-error.js";
+export function nextIntervalOccurrence(schedule, after) {
+    const anchor = Date.parse(schedule.anchorAt);
+    const steps = Math.max(0, Math.floor((after - anchor) / schedule.everyMs) + 1);
+    const next = anchor + steps * schedule.everyMs;
+    if (!isSupportedSchedulerInstant(next))
+        return null;
+    return schedulerInstantFromMilliseconds(next);
+}
+/** Admission only: legacy stored intervals remain readable until exhaustion. */
+export function requireRepresentableIntervalRecurrence(schedule, after) {
+    if (schedule.kind !== "interval")
+        return;
+    const first = nextIntervalOccurrence(schedule, after);
+    if (first === null)
+        throwUnsupportedRecurrence();
+    const second = nextIntervalOccurrence(schedule, Date.parse(first));
+    if (second === null)
+        throwUnsupportedRecurrence();
+}
+function throwUnsupportedRecurrence() {
+    throw new SchedulerValidationError("scheduler_invalid_schedule", "Interval recurrence is outside the supported date range");
+}

package/dist/src/runtime/scheduler/job-management.d.ts

@@ -0,0 +1,8 @@
+import type { CreateSchedulerJobInput, SchedulerJob, SchedulerJobState, SchedulerListFilter, SchedulerRun, UpdateSchedulerJobInput } from "./contracts.js";
+import { type SchedulerContext } from "./service-context.js";
+export declare function createSchedulerJob(context: SchedulerContext, input: CreateSchedulerJobInput): Promise<SchedulerJob>;
+export declare function updateSchedulerJob(context: SchedulerContext, jobId: string, patch: UpdateSchedulerJobInput): Promise<SchedulerJob>;
+export declare function changeSchedulerJobState(context: SchedulerContext, jobId: string, target: SchedulerJobState): Promise<SchedulerJob>;
+export declare function requestSchedulerRunNow(context: SchedulerContext, jobId: string): Promise<SchedulerRun>;
+export declare function deleteSchedulerSession(context: SchedulerContext, sessionId: string): Promise<void>;
+export declare function matchesSchedulerFilter(job: SchedulerJob, filter: SchedulerListFilter): boolean;

package/dist/src/runtime/scheduler/job-management.js

@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import { nextSchedulerOccurrence } from "./next-occurrence.js";
+import { normalizeSchedulerScheduleUpdate } from "./schedule-update.js";
+import { requireRepresentableIntervalRecurrence } from "./interval-range.js";
+import { cancelPendingRuns, findPendingRun, makeSchedulerRun, requireSchedulerJob, } from "./run-records.js";
+import { normalizeSchedulerSchedule, validateSchedulerJobInput, } from "./schedule-validation.js";
+import { invalidateJob, requireRunningScheduler, } from "./service-context.js";
+export function createSchedulerJob(context, input) {
+    return context.enqueue(async () => {
+        requireRunningScheduler(context);
+        validateSchedulerJobInput(input);
+        await requireExistingSession(context, input.sessionId);
+        const now = context.now();
+        const schedule = normalizeSchedulerSchedule(input.schedule, now);
+        requireRepresentableIntervalRecurrence(schedule, now);
+        const nextRunAt = nextSchedulerOccurrence(schedule, input.timeZone, now);
+        if (!nextRunAt)
+            throw new Error("scheduler_schedule_in_past");
+        const job = {
+            id: randomUUID(),
+            environmentId: context.environmentId,
+            sessionId: input.sessionId,
+            title: input.title.trim(),
+            prompt: input.prompt,
+            modelProfileId: input.modelProfileId,
+            agentMode: input.agentMode,
+            toolPermissionMode: "full_access",
+            timeZone: input.timeZone,
+            schedule,
+            state: "active",
+            createdAt: new Date(now).toISOString(),
+            updatedAt: new Date(now).toISOString(),
+            nextRunAt,
+            revision: 1,
+        };
+        return context.store.update((state) => {
+            if (context.deletedSessions.has(job.sessionId))
+                throw new Error("scheduler_session_deleted");
+            state.jobs.push(job);
+            return job;
+        });
+    });
+}
+export function updateSchedulerJob(context, jobId, patch) {
+    const settleInvalidation = invalidateJob(context, jobId);
+    return context
+        .enqueue(async () => {
+        requireRunningScheduler(context);
+        return context.store.update((state) => {
+            const job = requireSchedulerJob(state, jobId);
+            if (job.state === "cancelled")
+                throw new Error("scheduler_job_cancelled");
+            const editable = pickEditableFields(patch);
+            const input = { ...job, ...editable };
+            validateSchedulerJobInput(input);
+            const now = context.now();
+            const schedule = normalizeSchedulerScheduleUpdate(job.schedule, editable.schedule, now);
+            const candidate = { ...input, schedule };
+            if (!hasSchedulerJobChanges(job, candidate))
+                return job;
+            const changedTiming = hasSchedulerTimingChanges(job, candidate);
+            if (changedTiming)
+                requireRepresentableIntervalRecurrence(schedule, now);
+            const nextRunAt = changedTiming
+                ? nextSchedulerOccurrence(schedule, input.timeZone, now)
+                : job.nextRunAt;
+            if (changedTiming && !nextRunAt)
+                throw new Error("scheduler_schedule_in_past");
+            const pending = findPendingRun(state, jobId);
+            cancelPendingRuns(state, jobId, new Date(now).toISOString());
+            Object.assign(job, editable, {
+                schedule,
+                nextRunAt,
+                toolPermissionMode: "full_access",
+                updatedAt: new Date(now).toISOString(),
+                revision: job.revision + 1,
+            });
+            if (changedTiming && job.state === "completed")
+                job.state = "active";
+            if (pending && !changedTiming) {
+                state.runs.push(makeSchedulerRun(job, pending.scheduledAt, pending.trigger));
+            }
+            return job;
+        });
+    })
+        .finally(settleInvalidation);
+}
+function hasSchedulerTimingChanges(job, candidate) {
+    if (JSON.stringify(job.schedule) !== JSON.stringify(candidate.schedule))
+        return true;
+    if (job.timeZone === candidate.timeZone)
+        return false;
+    switch (candidate.schedule.kind) {
+        case "daily":
+        case "weekly":
+        case "monthly":
+            return true;
+        default:
+            return false;
+    }
+}
+function hasSchedulerJobChanges(job, candidate) {
+    if (hasSchedulerTimingChanges(job, candidate))
+        return true;
+    return [
+        "title",
+        "prompt",
+        "modelProfileId",
+        "agentMode",
+        "timeZone",
+    ].some((field) => job[field] !== candidate[field]);
+}
+function pickEditableFields(patch) {
+    const result = {};
+    for (const key of [
+        "title",
+        "prompt",
+        "modelProfileId",
+        "agentMode",
+        "timeZone",
+        "schedule",
+    ]) {
+        if (patch[key] === undefined)
+            continue;
+        Object.assign(result, { [key]: patch[key] });
+    }
+    return result;
+}
+export function changeSchedulerJobState(context, jobId, target) {
+    const settleInvalidation = invalidateJob(context, jobId);
+    return context
+        .enqueue(async () => {
+        requireRunningScheduler(context);
+        return context.store.update((state) => {
+            const job = requireSchedulerJob(state, jobId);
+            if (job.state === "cancelled" && target !== "cancelled") {
+                throw new Error("scheduler_job_cancelled");
+            }
+            const now = context.now();
+            if (target !== "active") {
+                cancelPendingRuns(state, jobId, new Date(now).toISOString());
+            }
+            if (job.state === target)
+                return job;
+            job.state = target;
+            job.updatedAt = new Date(now).toISOString();
+            job.revision += 1;
+            if (target === "cancelled")
+                job.nextRunAt = null;
+            if (target !== "active")
+                return job;
+            job.nextRunAt = nextSchedulerOccurrence(job.schedule, job.timeZone, now);
+            if (!job.nextRunAt)
+                job.state = "completed";
+            return job;
+        });
+    })
+        .finally(settleInvalidation);
+}
+export function requestSchedulerRunNow(context, jobId) {
+    return context.enqueue(async () => {
+        requireRunningScheduler(context);
+        const existing = await context.store.read();
+        const owner = requireSchedulerJob(existing, jobId);
+        await requireExistingSession(context, owner.sessionId);
+        return context.store.update((state) => {
+            const job = requireSchedulerJob(state, jobId);
+            if (job.state === "cancelled")
+                throw new Error("scheduler_job_cancelled");
+            if (context.deletedSessions.has(job.sessionId))
+                throw new Error("scheduler_session_deleted");
+            const pending = findPendingRun(state, jobId);
+            if (pending)
+                return pending;
+            const run = makeSchedulerRun(job, new Date(context.now()).toISOString(), "manual");
+            state.runs.push(run);
+            return run;
+        });
+    });
+}
+export function deleteSchedulerSession(context, sessionId) {
+    // Invalidation is synchronous: no awaited preparation may dispatch after this call.
+    const releaseIntent = context.deletedSessions.reserveIntent(sessionId);
+    return context
+        .enqueue(async () => {
+        requireRunningScheduler(context);
+        context.deletedSessions.add(sessionId);
+        await context.store.update((state) => {
+            state.jobs = state.jobs.filter((job) => job.sessionId !== sessionId);
+            state.runs = state.runs.filter((run) => run.sessionId !== sessionId);
+        });
+    })
+        .finally(releaseIntent);
+}
+export function matchesSchedulerFilter(job, filter) {
+    if (filter.sessionId !== undefined && job.sessionId !== filter.sessionId)
+        return false;
+    if (filter.state !== undefined && job.state !== filter.state)
+        return false;
+    if (!filter.search?.trim())
+        return true;
+    const searchable = [job.title, job.prompt, job.sessionId, job.modelProfileId]
+        .join(" ")
+        .toLowerCase();
+    return searchable.includes(filter.search.trim().toLowerCase());
+}
+async function requireExistingSession(context, sessionId) {
+    if (context.deletedSessions.has(sessionId))
+        throw new Error("scheduler_session_deleted");
+    if (!(await context.executor.sessionExists(sessionId)))
+        throw new Error("scheduler_session_not_found");
+}

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

@@ -0,0 +1,9 @@
+import { SchedulerJournalIndex } from "./journal-index.js";
+import { type CommittedJournalHead } from "./journal-head.js";
+export declare function loadCheckpointJournalIndex(directory: string, head: CommittedJournalHead): Promise<{
+    index: SchedulerJournalIndex;
+    sequence: number;
+}>;
+export declare function writeJournalCheckpoint(directory: string, generation: string, sequence: number, index: SchedulerJournalIndex): Promise<CommittedJournalHead>;
+/** Only checkpoint artifacts are retired here; archived transaction payloads remain immutable. */
+export declare function cleanObsoleteJournalCheckpoints(directory: string, head: CommittedJournalHead): Promise<void>;

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

@@ -0,0 +1,45 @@
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { SchedulerJournalIndex } from "./journal-index.js";
+import { encodeJournalIndexState, parseJournalIndexState, } from "./journal-index-state.js";
+import { journalCheckpointName, } from "./journal-head.js";
+import { journalTransactionName, writeJournalJson } from "./journal-files.js";
+import { parseSchedulerTransaction } from "./journal-transaction.js";
+import { syncJournalDirectory } from "./journal-durability.js";
+export async function loadCheckpointJournalIndex(directory, head) {
+    const generationDirectory = join(directory, head.generation);
+    const checkpointPath = join(generationDirectory, "checkpoints", head.checkpoint.file);
+    const state = parseJournalIndexState(JSON.parse(await readFile(checkpointPath, "utf8")), generationDirectory, head.generation, head.checkpoint.sequence);
+    const index = new SchedulerJournalIndex(state);
+    for (let sequence = head.checkpoint.sequence + 1; sequence <= head.sequence; sequence++) {
+        const file = join(generationDirectory, journalTransactionName(sequence));
+        index.apply(parseSchedulerTransaction(JSON.parse(await readFile(file, "utf8"))), file);
+    }
+    return { index, sequence: head.sequence };
+}
+export async function writeJournalCheckpoint(directory, generation, sequence, index) {
+    const checkpointDirectory = join(directory, generation, "checkpoints");
+    await mkdir(checkpointDirectory, { recursive: true, mode: 0o700 });
+    await syncJournalDirectory(join(directory, generation));
+    const file = journalCheckpointName(sequence);
+    const state = encodeJournalIndexState(index.exportState(), generation, sequence);
+    parseJournalIndexState(state, join(directory, generation), generation, sequence);
+    await writeJournalJson(join(checkpointDirectory, file), state);
+    return {
+        schemaVersion: 3,
+        generation,
+        sequence,
+        checkpoint: { file, sequence },
+    };
+}
+/** Only checkpoint artifacts are retired here; archived transaction payloads remain immutable. */
+export async function cleanObsoleteJournalCheckpoints(directory, head) {
+    const path = join(directory, head.generation, "checkpoints");
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (entry.name === head.checkpoint.file)
+            continue;
+        await rm(join(path, entry.name), { force: true });
+    }
+}

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

@@ -0,0 +1,8 @@
+/** The replacement is visible, but its directory entry is not confirmed durable. */
+export declare class JournalPublicationSyncError extends Error {
+    constructor(cause: unknown);
+}
+export declare function syncJournalDirectory(directory: string): Promise<void>;
+/** Establish the owned root, including directories left by an interrupted mkdir. */
+export declare function syncJournalDirectoryPath(directory: string): Promise<void>;
+export declare function writeJournalJson(path: string, value: unknown): Promise<void>;

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

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { open, rename, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+/** The replacement is visible, but its directory entry is not confirmed durable. */
+export class JournalPublicationSyncError extends Error {
+    constructor(cause) {
+        super("scheduler_store_directory_sync_failed", { cause });
+    }
+}
+function supportsJournalDirectorySync() {
+    // Node does not support opening Windows directories for FileHandle.sync().
+    return process.platform !== "win32";
+}
+export async function syncJournalDirectory(directory) {
+    if (!supportsJournalDirectorySync())
+        return;
+    const handle = await open(directory, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Establish the owned root, including directories left by an interrupted mkdir. */
+export async function syncJournalDirectoryPath(directory) {
+    if (!supportsJournalDirectorySync())
+        return;
+    let current = resolve(directory);
+    for (;;) {
+        await syncJournalDirectory(current);
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+export async function writeJournalJson(path, value) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(value), "utf8");
+        await handle.sync();
+        await handle.close();
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    try {
+        await syncJournalDirectory(dirname(path));
+    }
+    catch (error) {
+        // Do not unlink or roll back a replacement that readers can already see.
+        throw new JournalPublicationSyncError(error);
+    }
+}

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

@@ -0,0 +1,14 @@
+import { SchedulerJournalIndex } from "./journal-index.js";
+import { type SchedulerTransaction } from "./journal-transaction.js";
+export { SCHEDULER_MANIFEST, isMissingJournalFile } from "./journal-head.js";
+export { writeJournalJson } from "./journal-durability.js";
+export declare function readJournalGeneration(directory: string): Promise<string | undefined>;
+export declare function loadJournalIndex(directory: string, generation: string): Promise<{
+    index: SchedulerJournalIndex;
+    sequence: number;
+}>;
+export declare function journalTransactionName(sequence: number): string;
+export declare function createJournalGeneration(directory: string): Promise<string>;
+/** Only under the owner lock. The committed pointer is the sole keep rule. */
+export declare function cleanObsoleteJournalGenerations(directory: string, active?: string): Promise<void>;
+export declare function initialJournalTransaction(): SchedulerTransaction;

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

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { SchedulerJournalIndex } from "./journal-index.js";
+import { parseSchedulerTransaction, } from "./journal-transaction.js";
+import { JOURNAL_GENERATION_NAME, readJournalHead } from "./journal-head.js";
+import { syncJournalDirectory } from "./journal-durability.js";
+export { SCHEDULER_MANIFEST, isMissingJournalFile } from "./journal-head.js";
+export { writeJournalJson } from "./journal-durability.js";
+export async function readJournalGeneration(directory) {
+    return (await readJournalHead(directory))?.generation;
+}
+export async function loadJournalIndex(directory, generation) {
+    const path = join(directory, generation);
+    const entries = (await readdir(path))
+        .filter((name) => name.endsWith(".json"))
+        .sort();
+    if (!entries.length)
+        throw new Error("scheduler_store_corrupt");
+    const index = new SchedulerJournalIndex();
+    for (const [position, name] of entries.entries()) {
+        if (name !== journalTransactionName(position + 1))
+            throw new Error("scheduler_store_corrupt");
+        const file = join(path, name);
+        index.apply(parseSchedulerTransaction(JSON.parse(await readFile(file, "utf8"))), file);
+    }
+    return { index, sequence: entries.length };
+}
+export function journalTransactionName(sequence) {
+    if (!Number.isSafeInteger(sequence) || sequence < 1)
+        throw new Error("scheduler_store_sequence_invalid");
+    return `${String(sequence).padStart(16, "0")}.json`;
+}
+export async function createJournalGeneration(directory) {
+    const generation = `generation-${randomUUID()}`;
+    await mkdir(join(directory, generation), { mode: 0o700 });
+    await syncJournalDirectory(directory);
+    return generation;
+}
+/** Only under the owner lock. The committed pointer is the sole keep rule. */
+export async function cleanObsoleteJournalGenerations(directory, active) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (!isJournalGenerationDirectory(entry))
+            continue;
+        if (entry.name === active)
+            continue;
+        await rm(join(directory, entry.name), { recursive: true, force: true });
+    }
+    if (active)
+        await rm(join(directory, "scheduler.json"), { force: true });
+}
+function isJournalGenerationDirectory(entry) {
+    if (!entry.isDirectory())
+        return false;
+    return JOURNAL_GENERATION_NAME.test(entry.name);
+}
+export function initialJournalTransaction() {
+    return { version: 1, jobs: [], runs: [], deletedJobs: [], deletedRuns: [] };
+}

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

@@ -0,0 +1,21 @@
+export declare const SCHEDULER_MANIFEST = "scheduler-journal.json";
+export declare const MAX_JOURNAL_SUFFIX = 256;
+export declare const JOURNAL_GENERATION_NAME: RegExp;
+export type JournalCheckpointReference = {
+    file: string;
+    sequence: number;
+};
+export type JournalHead = {
+    schemaVersion: 2;
+    generation: string;
+} | CommittedJournalHead;
+export type CommittedJournalHead = {
+    schemaVersion: 3;
+    generation: string;
+    sequence: number;
+    checkpoint: JournalCheckpointReference;
+};
+export declare function readJournalHead(directory: string): Promise<JournalHead | undefined>;
+export declare function journalReadIdentity(head: JournalHead | undefined): string | undefined;
+export declare function journalCheckpointName(sequence: number): string;
+export declare function isMissingJournalFile(error: unknown): boolean;