@abot-ai/runtime 1.2.0 → 1.3.0

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;

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

@@ -0,0 +1,81 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const SCHEDULER_MANIFEST = "scheduler-journal.json";
+export const MAX_JOURNAL_SUFFIX = 256;
+export const JOURNAL_GENERATION_NAME = /^generation-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export async function readJournalHead(directory) {
+    let text;
+    try {
+        text = await readFile(join(directory, SCHEDULER_MANIFEST), "utf8");
+    }
+    catch (error) {
+        if (isMissingJournalFile(error))
+            return undefined;
+        throw error;
+    }
+    return parseJournalHead(JSON.parse(text));
+}
+function parseJournalHead(value) {
+    if (!isJournalObject(value))
+        corruptJournalHead();
+    if (!isJournalGeneration(value.generation))
+        corruptJournalHead();
+    if (value.schemaVersion === 2)
+        return { schemaVersion: 2, generation: value.generation };
+    if (value.schemaVersion !== 3)
+        corruptJournalHead();
+    if (!isJournalSequence(value.sequence))
+        corruptJournalHead();
+    if (!isJournalObject(value.checkpoint))
+        corruptJournalHead();
+    const checkpoint = value.checkpoint;
+    if (!isJournalSequence(checkpoint.sequence))
+        corruptJournalHead();
+    if (checkpoint.file !== journalCheckpointName(checkpoint.sequence))
+        corruptJournalHead();
+    if (!hasBoundedJournalSuffix(value.sequence, checkpoint.sequence))
+        corruptJournalHead();
+    return {
+        schemaVersion: 3,
+        generation: value.generation,
+        sequence: value.sequence,
+        checkpoint: {
+            file: String(checkpoint.file),
+            sequence: checkpoint.sequence,
+        },
+    };
+}
+export function journalReadIdentity(head) {
+    if (!head)
+        return undefined;
+    if (head.schemaVersion === 2)
+        return head.generation;
+    return `${head.generation}/${head.checkpoint.file}`;
+}
+export function journalCheckpointName(sequence) {
+    if (!isJournalSequence(sequence))
+        corruptJournalHead();
+    return `checkpoint-${sequence}.json`;
+}
+export function isMissingJournalFile(error) {
+    return isJournalObject(error) && error.code === "ENOENT";
+}
+function isJournalObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return !Array.isArray(value);
+}
+function isJournalGeneration(value) {
+    return typeof value === "string" && JOURNAL_GENERATION_NAME.test(value);
+}
+function isJournalSequence(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1;
+}
+function hasBoundedJournalSuffix(sequence, covered) {
+    if (sequence < covered)
+        return false;
+    return sequence - covered <= MAX_JOURNAL_SUFFIX;
+}
+function corruptJournalHead() {
+    throw new Error("scheduler_store_corrupt");
+}

package/dist/src/runtime/scheduler/journal-index-state.d.ts

@@ -0,0 +1,31 @@
+import type { SchedulerJob, SchedulerRun } from "./contracts.js";
+export type JournalRunEntry = Pick<SchedulerRun, "id" | "jobId" | "sessionId" | "environmentId" | "jobRevision" | "scheduledAt" | "requestId" | "status"> & {
+    file: string;
+    offset: number;
+    active?: SchedulerRun;
+};
+export type JournalIndexState = {
+    jobs: SchedulerJob[];
+    runs: JournalRunEntry[];
+};
+export declare function encodeJournalIndexState(state: JournalIndexState, generation: string, sequence: number): {
+    version: number;
+    generation: string;
+    sequence: number;
+    jobs: SchedulerJob[];
+    runs: {
+        file: string;
+        id: string;
+        requestId: string;
+        sessionId: string;
+        status: import("./contracts.js").SchedulerRunStatus;
+        jobId: string;
+        scheduledAt: string;
+        environmentId: string;
+        jobRevision: number;
+        offset: number;
+        active?: SchedulerRun;
+    }[];
+};
+export declare function parseJournalIndexState(value: unknown, directory: string, generation: string, sequence: number): JournalIndexState;
+export declare function matchesIndexedJournalRun(run: SchedulerRun | undefined, entry: JournalRunEntry): run is SchedulerRun;

package/dist/src/runtime/scheduler/journal-index-state.js

@@ -0,0 +1,137 @@
+import { basename, join } from "node:path";
+import { parseStoredJob, parseStoredRun } from "./snapshot-validation.js";
+export function encodeJournalIndexState(state, generation, sequence) {
+    return {
+        version: 1,
+        generation,
+        sequence,
+        jobs: state.jobs,
+        runs: state.runs.map((entry) => ({ ...entry, file: basename(entry.file) })),
+    };
+}
+export function parseJournalIndexState(value, directory, generation, sequence) {
+    if (!isIndexObject(value))
+        corruptJournalIndex();
+    if (value.version !== 1)
+        corruptJournalIndex();
+    if (value.generation !== generation)
+        corruptJournalIndex();
+    if (value.sequence !== sequence)
+        corruptJournalIndex();
+    if (!Array.isArray(value.jobs))
+        corruptJournalIndex();
+    if (!Array.isArray(value.runs))
+        corruptJournalIndex();
+    const jobs = value.jobs.map(parseStoredJob);
+    const owners = new Map(jobs.map((job) => [job.id, job]));
+    if (owners.size !== jobs.length)
+        corruptJournalIndex();
+    const runs = value.runs.map((entry) => parseJournalRunEntry(entry, directory, sequence, owners));
+    if (new Set(runs.map((entry) => entry.id)).size !== runs.length)
+        corruptJournalIndex();
+    return { jobs, runs };
+}
+function parseJournalRunEntry(value, directory, sequence, jobs) {
+    if (!isIndexObject(value))
+        corruptJournalIndex();
+    for (const field of [
+        "id",
+        "jobId",
+        "sessionId",
+        "environmentId",
+        "requestId",
+        "scheduledAt",
+    ]) {
+        if (typeof value[field] !== "string")
+            corruptJournalIndex();
+    }
+    if (!Number.isFinite(Date.parse(String(value.scheduledAt))))
+        corruptJournalIndex();
+    if (!isPositiveIndexInteger(value.jobRevision))
+        corruptJournalIndex();
+    if (!isNonnegativeIndexInteger(value.offset))
+        corruptJournalIndex();
+    if (!isCoveredTransactionFile(value.file, sequence))
+        corruptJournalIndex();
+    if (!isIndexedRunStatus(value.status))
+        corruptJournalIndex();
+    const entry = {
+        ...value,
+        file: join(directory, value.file),
+    };
+    requireIndexedRunOwner(entry, jobs.get(entry.jobId));
+    if (requiresActiveRunPayload(entry.status)) {
+        entry.active = parseStoredRun(value.active);
+        if (!matchesIndexedJournalRun(entry.active, entry))
+            corruptJournalIndex();
+        return entry;
+    }
+    if (value.active !== undefined)
+        corruptJournalIndex();
+    return entry;
+}
+export function matchesIndexedJournalRun(run, entry) {
+    if (!run)
+        return false;
+    const fields = [
+        "id",
+        "jobId",
+        "sessionId",
+        "environmentId",
+        "jobRevision",
+        "scheduledAt",
+        "requestId",
+        "status",
+    ];
+    return fields.every((field) => run[field] === entry[field]);
+}
+function requireIndexedRunOwner(entry, job) {
+    if (!job)
+        corruptJournalIndex();
+    if (entry.sessionId !== job.sessionId)
+        corruptJournalIndex();
+    if (entry.environmentId !== job.environmentId)
+        corruptJournalIndex();
+    if (entry.jobRevision > job.revision)
+        corruptJournalIndex();
+}
+function isIndexObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return !Array.isArray(value);
+}
+function isPositiveIndexInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1;
+}
+function isNonnegativeIndexInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function isCoveredTransactionFile(value, sequence) {
+    if (typeof value !== "string")
+        return false;
+    if (!/^[0-9]{16}\.json$/.test(value))
+        return false;
+    const reference = Number(value.slice(0, -5));
+    if (!isPositiveIndexInteger(reference))
+        return false;
+    return reference <= sequence;
+}
+function isIndexedRunStatus(value) {
+    if (typeof value !== "string")
+        return false;
+    return [
+        "pending",
+        "running",
+        "succeeded",
+        "failed",
+        "cancelled",
+        "interrupted",
+        "missed",
+    ].includes(value);
+}
+function requiresActiveRunPayload(status) {
+    return status === "pending" || status === "running";
+}
+function corruptJournalIndex() {
+    throw new Error("scheduler_store_corrupt");
+}

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

@@ -0,0 +1,22 @@
+import type { SchedulerRun, SchedulerRunListQuery, SchedulerSnapshot } from "./contracts.js";
+import { type SchedulerTransaction } from "./journal-transaction.js";
+import { type JournalIndexState } from "./journal-index-state.js";
+export declare class SchedulerJournalIndex {
+    private jobs;
+    private runs;
+    private active;
+    constructor(state?: JournalIndexState);
+    exportState(): JournalIndexState;
+    validate(transaction: SchedulerTransaction): void;
+    private validateChangedJobHistory;
+    private prospectiveRunIds;
+    apply(transaction: SchedulerTransaction, file: string): void;
+    private applyRun;
+    private updateActiveRun;
+    private applyRunOrder;
+    snapshot(view?: "active"): Promise<SchedulerSnapshot>;
+    readRuns(jobId?: string, query?: SchedulerRunListQuery): Promise<SchedulerRun[]>;
+    private removeRun;
+    private removeJob;
+}
+export declare function isActiveSchedulerRun(run: SchedulerRun): boolean;

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

@@ -0,0 +1,195 @@
+import { readFile } from "node:fs/promises";
+import { assertJournalTransactionIds, parseSchedulerTransaction, } from "./journal-transaction.js";
+import { querySchedulerRuns } from "./run-list-query.js";
+import { matchesIndexedJournalRun, } from "./journal-index-state.js";
+export class SchedulerJournalIndex {
+    jobs = new Map();
+    runs = new Map();
+    active = new Map();
+    constructor(state) {
+        if (!state)
+            return;
+        const detached = structuredClone(state);
+        this.jobs = new Map(detached.jobs.map((job) => [job.id, job]));
+        this.runs = new Map(detached.runs.map((run) => [run.id, run]));
+        for (const entry of this.runs.values()) {
+            if (entry.active)
+                this.active.set(entry.id, entry.active);
+        }
+    }
+    exportState() {
+        return structuredClone({
+            jobs: [...this.jobs.values()],
+            runs: [...this.runs.values()],
+        });
+    }
+    validate(transaction) {
+        assertJournalTransactionIds(transaction);
+        const jobs = new Map(this.jobs);
+        for (const job of transaction.jobs)
+            jobs.set(job.id, job);
+        for (const id of transaction.deletedJobs)
+            jobs.delete(id);
+        for (const run of transaction.runs)
+            assertJournalRunOwner(run, jobs.get(run.jobId));
+        this.validateChangedJobHistory(transaction);
+        if (transaction.jobOrder)
+            assertJournalOrder(jobs, transaction.jobOrder);
+        if (transaction.runOrder)
+            assertJournalOrder(this.prospectiveRunIds(transaction), transaction.runOrder);
+    }
+    validateChangedJobHistory(transaction) {
+        const changed = new Map(transaction.jobs
+            .filter((job) => requiresJournalHistoryValidation(this.jobs.get(job.id), job))
+            .map((job) => [job.id, job]));
+        if (changed.size === 0)
+            return;
+        const replaced = new Set([
+            ...transaction.deletedRuns,
+            ...transaction.runs.map((run) => run.id),
+        ]);
+        for (const entry of this.runs.values()) {
+            if (replaced.has(entry.id))
+                continue;
+            const job = changed.get(entry.jobId);
+            if (!job)
+                continue;
+            assertJournalRunOwner(entry, job);
+        }
+    }
+    prospectiveRunIds(transaction) {
+        const deletedJobs = new Set(transaction.deletedJobs);
+        const ids = new Set([...this.runs.values()]
+            .filter((run) => !deletedJobs.has(run.jobId))
+            .map((run) => run.id));
+        for (const id of transaction.deletedRuns)
+            ids.delete(id);
+        for (const run of transaction.runs)
+            ids.add(run.id);
+        return ids;
+    }
+    apply(transaction, file) {
+        this.validate(transaction);
+        for (const job of transaction.jobs)
+            this.jobs.set(job.id, job);
+        for (const id of transaction.deletedJobs)
+            this.removeJob(id);
+        for (const id of transaction.deletedRuns)
+            this.removeRun(id);
+        transaction.runs.forEach((run, offset) => this.applyRun(run, file, offset));
+        if (transaction.jobOrder)
+            this.jobs = orderedJournalRecords(this.jobs, transaction.jobOrder);
+        this.applyRunOrder(transaction.runOrder);
+    }
+    applyRun(run, file, offset) {
+        const entry = {
+            id: run.id,
+            jobId: run.jobId,
+            sessionId: run.sessionId,
+            environmentId: run.environmentId,
+            jobRevision: run.jobRevision,
+            scheduledAt: run.scheduledAt,
+            requestId: run.requestId,
+            status: run.status,
+            file,
+            offset,
+        };
+        this.updateActiveRun(run, entry);
+        this.runs.set(run.id, entry);
+    }
+    updateActiveRun(run, entry) {
+        if (!isActiveSchedulerRun(run)) {
+            this.active.delete(run.id);
+            return;
+        }
+        entry.active = run;
+        this.active.set(run.id, run);
+    }
+    applyRunOrder(order) {
+        if (!order)
+            return;
+        this.runs = orderedJournalRecords(this.runs, order);
+        this.active = orderedJournalRecords(this.active, order.filter((id) => this.active.has(id)));
+    }
+    async snapshot(view) {
+        return {
+            schemaVersion: 1,
+            jobs: structuredClone([...this.jobs.values()]),
+            runs: view === "active"
+                ? structuredClone([...this.active.values()])
+                : await this.readRuns(),
+        };
+    }
+    async readRuns(jobId, query) {
+        const selected = querySchedulerRuns([...this.runs.values()], jobId, query);
+        const files = new Map();
+        const result = [];
+        for (const entry of selected) {
+            if (entry.active) {
+                result.push(structuredClone(entry.active));
+                continue;
+            }
+            let loading = files.get(entry.file);
+            if (!loading) {
+                loading = readFile(entry.file, "utf8").then((text) => parseSchedulerTransaction(JSON.parse(text)));
+                files.set(entry.file, loading);
+            }
+            const run = (await loading).runs[entry.offset];
+            if (!matchesIndexedJournalRun(run, entry))
+                throw new Error("scheduler_store_corrupt");
+            result.push(structuredClone(run));
+        }
+        return result;
+    }
+    removeRun(id) {
+        this.runs.delete(id);
+        this.active.delete(id);
+    }
+    removeJob(id) {
+        this.jobs.delete(id);
+        for (const entry of this.runs.values()) {
+            if (entry.jobId === id)
+                this.removeRun(entry.id);
+        }
+    }
+}
+export function isActiveSchedulerRun(run) {
+    return run.status === "pending" || run.status === "running";
+}
+function orderedJournalRecords(records, order) {
+    assertJournalOrder(records, order);
+    return new Map(order.map((id) => [id, records.get(id)]));
+}
+function assertJournalOrder(records, order) {
+    if (!containsEveryJournalRecord(records, order))
+        throw new Error("scheduler_store_corrupt");
+}
+function containsEveryJournalRecord(records, order) {
+    if (order.length !== records.size)
+        return false;
+    if (new Set(order).size !== order.length)
+        return false;
+    return order.every((id) => records.has(id));
+}
+function requiresJournalHistoryValidation(previous, next) {
+    if (!previous)
+        return false;
+    if (previous.sessionId !== next.sessionId)
+        return true;
+    if (previous.environmentId !== next.environmentId)
+        return true;
+    return next.revision < previous.revision;
+}
+function assertJournalRunOwner(run, job) {
+    if (!hasConsistentJournalRunOwner(run, job))
+        throw new Error("scheduler_store_corrupt");
+}
+function hasConsistentJournalRunOwner(run, job) {
+    if (!job)
+        return false;
+    if (run.sessionId !== job.sessionId)
+        return false;
+    if (run.environmentId !== job.environmentId)
+        return false;
+    return run.jobRevision <= job.revision;
+}

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

@@ -0,0 +1,21 @@
+import type { SchedulerRunListQuery, SchedulerSnapshot } from "./contracts.js";
+export declare class SchedulerJournalStore {
+    private readonly directory;
+    private index;
+    private sequence;
+    private generation?;
+    private head?;
+    private legacy?;
+    private publicationFailure?;
+    private ownedDirectoriesSynced;
+    constructor(directory: string);
+    load(): Promise<this>;
+    prepareOwned(): Promise<void>;
+    snapshot(view?: "active"): Promise<SchedulerSnapshot>;
+    readRuns(jobId?: string, query?: SchedulerRunListQuery): Promise<import("./contracts.js").SchedulerRun[]>;
+    update<T>(mutate: (state: SchedulerSnapshot) => T, view?: "active"): Promise<T>;
+    private replaceGeneration;
+    private ensureOwnedDirectoriesSynced;
+    private publishHead;
+    private requireDurablePublication;
+}