@abot-ai/runtime 1.1.0 → 1.3.0

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;
+}

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;