@adonis-agora/durable 0.41.0 → 0.43.0

package/dist/src/schedules.d.ts

@@ -0,0 +1,172 @@
+import type { ConcurrencyQuota } from './concurrency.js';
+import type { StartOptions } from './engine.js';
+import type { RunResult, ScheduleQuery, SearchAttributes, StateStore, WorkflowRun } from './interfaces.js';
+import { type WorkflowRef } from './workflow-ref.js';
+/**
+ * A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
+ * runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
+ * poll (safe with many workers: each window's run id is deterministic, `start` is idempotent, and
+ * advancing the schedule is a compare-and-set).
+ */
+export interface ScheduleOptions {
+    /** Stable id, unique per store (e.g. `digest:user-42`). Part of every run id it starts. */
+    id: string;
+    /** The workflow to start — a registered name or `@Workflow` class. */
+    workflow: WorkflowRef;
+    /** The input every run starts with. */
+    input?: unknown;
+    /** Cron expression (5 fields, or 6 with leading seconds). Needs the `cron-parser` peer. */
+    cron?: string | undefined;
+    /** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
+    every?: string | number | undefined;
+    /** IANA timezone the cron is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
+    timezone?: string | undefined;
+    /**
+     * Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
+     * thousands of schedules on the same cron don't all start in the same second.
+     */
+    jitter?: string | number | undefined;
+    /**
+     * The previous run of this schedule is still in flight when the next window comes due:
+     * `'allow'` (default) starts the new one anyway; `'skip'` skips that window.
+     */
+    overlap?: 'allow' | 'skip' | undefined;
+    /**
+     * Windows missed while nothing polled (all schedulers down): `'latest'` (default) fires the most
+     * recent missed window once; `'skip'` drops them and waits for the next window. Never more than one
+     * catch-up run per schedule.
+     */
+    catchup?: 'latest' | 'skip' | undefined;
+    /** Create paused (never due until `resume`). On `upsert`, omit to keep the current paused state. */
+    paused?: boolean | undefined;
+    /** Free-form note shown with the schedule (why it exists / why it's paused). */
+    note?: string | undefined;
+    /** Namespace of the schedule and of the runs it starts. Defaults to the engine's own namespace. */
+    namespace?: string | undefined;
+    /** Labels to find the schedule by — also stamped on every run it starts (plus `schedule:<id>`). */
+    tags?: string[] | undefined;
+    /** Search attributes stamped on every run it starts. */
+    searchAttributes?: SearchAttributes | undefined;
+    /** Dispatch priority for the runs it starts. */
+    priority?: number | undefined;
+    /**
+     * A start-time concurrency quota applied to every run it starts (see `StartOptions.concurrency`):
+     * a window whose start would exceed it is recorded as the schedule's `lastError` and skipped, and
+     * the schedule moves on to its next window.
+     */
+    concurrency?: ConcurrencyQuota | undefined;
+}
+/** A schedule as `engine.schedules.get/list` describe it. */
+export interface ScheduleDescription {
+    id: string;
+    workflow: string;
+    input: unknown;
+    namespace: string;
+    cron?: string | undefined;
+    everyMs?: number | undefined;
+    timezone?: string | undefined;
+    jitterMs?: number | undefined;
+    overlap: 'allow' | 'skip';
+    catchup: 'latest' | 'skip';
+    paused: boolean;
+    note?: string | undefined;
+    tags?: string[] | undefined;
+    searchAttributes?: SearchAttributes | undefined;
+    priority?: number | undefined;
+    concurrency?: ConcurrencyQuota | undefined;
+    /** When it is next due (jitter included), or null if it never fires again / paused. */
+    nextFireAt: Date | null;
+    /** The last window it fired for, and the run that window started. */
+    lastFireAt?: Date | undefined;
+    lastRunId?: string | undefined;
+    /** How many windows it has fired (manual triggers excluded). */
+    fires: number;
+    /** The last start failure (e.g. a concurrency limit), cleared by the next successful start. */
+    lastError?: string | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Filter for `engine.schedules.list`. */
+export type ScheduleListQuery = Omit<ScheduleQuery, 'dueBy'>;
+/** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
+export declare class ScheduleAlreadyExistsError extends Error {
+    readonly scheduleId: string;
+    constructor(scheduleId: string);
+}
+/** Thrown by `engine.schedules.*` on an id that doesn't exist. */
+export declare class ScheduleNotFoundError extends Error {
+    readonly scheduleId: string;
+    constructor(scheduleId: string);
+}
+/** The engine surface the schedule client drives. */
+export interface ScheduleHost {
+    start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+}
+/** Engine-level knobs for the client. */
+export interface ScheduleClientOptions {
+    /** The engine's namespace: the default for new schedules, and which ones `tick` fires. */
+    namespace?: string | undefined;
+    clock?: (() => number) | undefined;
+}
+/**
+ * Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
+ * `schedules` config / `static schedule`, these live in the store: create/update/pause/delete them at runtime
+ * (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
+ * ones via {@link tick}.
+ *
+ * Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
+ * (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
+ * schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
+ * A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
+ */
+export declare class ScheduleClient {
+    private readonly store;
+    private readonly host;
+    private readonly options;
+    constructor(store: StateStore, host: ScheduleHost, options?: ScheduleClientOptions);
+    private now;
+    /** Whether the store persists schedules (implements the schedule methods). */
+    get supported(): boolean;
+    private requireStore;
+    /** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
+    create(opts: ScheduleOptions): Promise<ScheduleDescription>;
+    /**
+     * Create the schedule, or replace the definition of an existing one (its history — last fire, last
+     * run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
+     * window that already fired is never fired again by an upsert.
+     */
+    upsert(opts: ScheduleOptions): Promise<ScheduleDescription>;
+    /** The schedule `id`, or null. */
+    get(id: string): Promise<ScheduleDescription | null>;
+    /** Schedules matching `query`, soonest-due first. */
+    list(query?: ScheduleListQuery): Promise<ScheduleDescription[]>;
+    /** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
+    delete(id: string): Promise<boolean>;
+    /** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
+    pause(id: string, note?: string): Promise<ScheduleDescription>;
+    /**
+     * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
+     */
+    resume(id: string): Promise<ScheduleDescription>;
+    /**
+     * Start one run of the schedule right now, outside its cadence (paused or not). The run id is
+     * `sched:<id>:manual:<nowMs>`; it doesn't move the schedule's next fire.
+     */
+    trigger(id: string): Promise<RunResult>;
+    /**
+     * Fire every due schedule (in this engine's namespace; all namespaces for an operator engine):
+     * start its window's run and advance it to the next window. Called by the worker tick (`durable:work`
+     * / the embedded worker) when `persistedSchedules` is on; call it yourself from any other driver.
+     * Returns the
+     * run ids started (or re-found, for an idempotent re-fire).
+     */
+    tick(nowMs?: number): Promise<string[]>;
+    /** Fire one due schedule and advance it. Returns the run id started, if any. */
+    private fire;
+    /** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
+    private overlapping;
+    private mustGet;
+    private write;
+}
+//# sourceMappingURL=schedules.d.ts.map

package/dist/src/schedules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedules.d.ts","sourceRoot":"","sources":["../../src/schedules.ts"],"names":[],"mappings":"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"}

package/dist/src/schedules.js

@@ -0,0 +1,362 @@
+import { parseDuration } from './duration.js';
+import { nextCronFireMs, prevCronFireMs } from './scheduler.js';
+import { workflowName } from './workflow-ref.js';
+/** Statuses a run never leaves on its own — an `overlap: 'skip'` schedule may fire again. */
+const TERMINAL_RUN_STATUSES = ['completed', 'failed', 'cancelled', 'dead'];
+/** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
+export class ScheduleAlreadyExistsError extends Error {
+    scheduleId;
+    constructor(scheduleId) {
+        super(`schedule "${scheduleId}" already exists`);
+        this.scheduleId = scheduleId;
+        this.name = 'ScheduleAlreadyExistsError';
+    }
+}
+/** Thrown by `engine.schedules.*` on an id that doesn't exist. */
+export class ScheduleNotFoundError extends Error {
+    scheduleId;
+    constructor(scheduleId) {
+        super(`schedule "${scheduleId}" not found`);
+        this.scheduleId = scheduleId;
+        this.name = 'ScheduleNotFoundError';
+    }
+}
+const DEFAULT_NAMESPACE = 'default';
+/** How late a window may fire under `catchup: 'skip'` and still count as on time (plus jitter). */
+const ON_TIME_GRACE_MS = 60_000;
+const TICK_BATCH = 100;
+/**
+ * Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
+ * `schedules` config / `static schedule`, these live in the store: create/update/pause/delete them at runtime
+ * (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
+ * ones via {@link tick}.
+ *
+ * Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
+ * (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
+ * schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
+ * A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
+ */
+export class ScheduleClient {
+    store;
+    host;
+    options;
+    constructor(store, host, options = {}) {
+        this.store = store;
+        this.host = host;
+        this.options = options;
+    }
+    now() {
+        return (this.options.clock ?? Date.now)();
+    }
+    /** Whether the store persists schedules (implements the schedule methods). */
+    get supported() {
+        const s = this.store;
+        return !!(s.saveSchedule &&
+            s.getSchedule &&
+            s.updateSchedule &&
+            s.deleteSchedule &&
+            s.listSchedules);
+    }
+    requireStore() {
+        if (!this.supported) {
+            throw new Error('persisted schedules need a store that implements saveSchedule/getSchedule/updateSchedule/deleteSchedule/listSchedules — every bundled store adapter does; this one does not');
+        }
+        const s = this.store;
+        return {
+            saveSchedule: (r) => s.saveSchedule.call(s, r),
+            getSchedule: (id) => s.getSchedule.call(s, id),
+            updateSchedule: (id, patch, expected) => s.updateSchedule.call(s, id, patch, expected),
+            deleteSchedule: (id) => s.deleteSchedule.call(s, id),
+            listSchedules: (q) => s.listSchedules.call(s, q),
+        };
+    }
+    /** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
+    async create(opts) {
+        const store = this.requireStore();
+        if (await store.getSchedule(opts.id))
+            throw new ScheduleAlreadyExistsError(opts.id);
+        return this.write(opts, null);
+    }
+    /**
+     * Create the schedule, or replace the definition of an existing one (its history — last fire, last
+     * run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
+     * window that already fired is never fired again by an upsert.
+     */
+    async upsert(opts) {
+        const store = this.requireStore();
+        return this.write(opts, await store.getSchedule(opts.id));
+    }
+    /** The schedule `id`, or null. */
+    async get(id) {
+        const record = await this.requireStore().getSchedule(id);
+        return record ? describe(record) : null;
+    }
+    /** Schedules matching `query`, soonest-due first. */
+    async list(query = {}) {
+        return (await this.requireStore().listSchedules(query)).map(describe);
+    }
+    /** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
+    delete(id) {
+        return this.requireStore().deleteSchedule(id);
+    }
+    /** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
+    async pause(id, note) {
+        const store = this.requireStore();
+        const record = await this.mustGet(id);
+        const spec = { ...record.spec };
+        if (note !== undefined)
+            spec.note = note;
+        await store.updateSchedule(id, {
+            paused: true,
+            spec: spec,
+            updatedAt: new Date(this.now()),
+        });
+        return describe(await this.mustGet(id));
+    }
+    /**
+     * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
+     */
+    async resume(id) {
+        const store = this.requireStore();
+        const record = await this.mustGet(id);
+        const spec = record.spec;
+        const window = nextWindowAfter(spec, this.now());
+        await store.updateSchedule(id, {
+            paused: false,
+            nextFireAt: window === null ? null : window + jitterFor(record.id, window, spec),
+            state: { ...record.state, window },
+            updatedAt: new Date(this.now()),
+        });
+        return describe(await this.mustGet(id));
+    }
+    /**
+     * Start one run of the schedule right now, outside its cadence (paused or not). The run id is
+     * `sched:<id>:manual:<nowMs>`; it doesn't move the schedule's next fire.
+     */
+    async trigger(id) {
+        const record = await this.mustGet(id);
+        const runId = `sched:${id}:manual:${this.now()}`;
+        return this.host.start(record.workflow, specOf(record).input, runId, startOptions(record));
+    }
+    /**
+     * Fire every due schedule (in this engine's namespace; all namespaces for an operator engine):
+     * start its window's run and advance it to the next window. Called by the worker tick (`durable:work`
+     * / the embedded worker) when `persistedSchedules` is on; call it yourself from any other driver.
+     * Returns the
+     * run ids started (or re-found, for an idempotent re-fire).
+     */
+    async tick(nowMs = this.now()) {
+        const store = this.requireStore();
+        const started = [];
+        for (let round = 0; round < 50; round++) {
+            const due = await store.listSchedules({
+                dueBy: nowMs,
+                namespace: this.options.namespace,
+                limit: TICK_BATCH,
+            });
+            for (const record of due) {
+                const runId = await this.fire(record, nowMs);
+                if (runId)
+                    started.push(runId);
+            }
+            if (due.length < TICK_BATCH)
+                break;
+        }
+        return started;
+    }
+    /** Fire one due schedule and advance it. Returns the run id started, if any. */
+    async fire(record, nowMs) {
+        const store = this.requireStore();
+        const spec = specOf(record);
+        const state = record.state;
+        let latest;
+        let next;
+        try {
+            // The most recent window at or before now — the one (and only one) a late poll fires.
+            latest = latestWindowAtOrBefore(spec, nowMs);
+            next = nextWindowAfter(spec, latest);
+        }
+        catch (error) {
+            // A definition that no longer evaluates (bad cron/timezone): stop it, loudly, instead of
+            // failing on every tick forever.
+            await store.updateSchedule(record.id, {
+                paused: true,
+                nextFireAt: null,
+                state: { ...state, lastError: `invalid schedule: ${errorMessage(error)}` },
+                updatedAt: new Date(nowMs),
+            }, record.nextFireAt);
+            return undefined;
+        }
+        const window = state.window ?? latest;
+        const jitter = spec.jitterMs ?? 0;
+        const onTime = nowMs - latest <= ON_TIME_GRACE_MS + jitter;
+        let runId;
+        let lastError;
+        let fired = false;
+        const skipMissed = spec.catchup === 'skip' && !onTime;
+        const beforeWindow = latest < window; // clock skew: not actually due yet
+        if (!skipMissed && !beforeWindow && !(await this.overlapping(spec, state))) {
+            runId = `sched:${record.id}:${latest}`;
+            try {
+                await this.host.start(record.workflow, spec.input, runId, startOptions(record));
+                fired = true;
+            }
+            catch (error) {
+                // A racing poller may have created the same (deterministic) run first: that's a success.
+                if (await this.host.getRun(runId))
+                    fired = true;
+                else
+                    lastError = errorMessage(error);
+            }
+        }
+        const nextState = {
+            ...state,
+            window: next,
+            ...(fired ? { lastFireAt: latest, lastRunId: runId, fires: (state.fires ?? 0) + 1 } : {}),
+            lastError: fired ? undefined : (lastError ?? state.lastError),
+        };
+        await store.updateSchedule(record.id, {
+            nextFireAt: next === null ? null : next + jitterFor(record.id, next, spec),
+            state: stripUndefined(nextState),
+            updatedAt: new Date(nowMs),
+        }, record.nextFireAt);
+        return fired ? runId : undefined;
+    }
+    /** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
+    async overlapping(spec, state) {
+        if (spec.overlap !== 'skip' || !state.lastRunId)
+            return false;
+        const prev = await this.host.getRun(state.lastRunId);
+        return !!prev && !TERMINAL_RUN_STATUSES.includes(prev.status);
+    }
+    async mustGet(id) {
+        const record = await this.requireStore().getSchedule(id);
+        if (!record)
+            throw new ScheduleNotFoundError(id);
+        return record;
+    }
+    async write(opts, existing) {
+        const store = this.requireStore();
+        const spec = toSpec(opts);
+        const now = this.now();
+        // An upsert that doesn't say otherwise keeps a paused schedule paused.
+        const paused = opts.paused ?? existing?.paused ?? false;
+        const window = nextWindowAfter(spec, now); // also validates the cron/timezone up front
+        const record = {
+            id: opts.id,
+            namespace: opts.namespace ?? this.options.namespace ?? DEFAULT_NAMESPACE,
+            workflow: workflowName(opts.workflow),
+            paused,
+            nextFireAt: window === null ? null : window + jitterFor(opts.id, window, spec),
+            tags: opts.tags,
+            spec: spec,
+            state: stripUndefined({
+                ...(existing?.state ?? {}),
+                window,
+            }),
+            createdAt: existing?.createdAt ?? new Date(now),
+            updatedAt: new Date(now),
+        };
+        await store.saveSchedule(record);
+        return describe(record);
+    }
+}
+function toSpec(opts) {
+    if ((opts.cron == null) === (opts.every == null)) {
+        throw new Error(`schedule "${opts.id}" needs exactly one of "cron" or "every"`);
+    }
+    const everyMs = opts.every != null ? parseDuration(opts.every) : undefined;
+    if (everyMs !== undefined && !(everyMs > 0)) {
+        throw new Error(`schedule "${opts.id}": "every" must be a positive duration`);
+    }
+    const jitterMs = opts.jitter != null ? parseDuration(opts.jitter) : undefined;
+    return stripUndefined({
+        v: 1,
+        input: opts.input,
+        cron: opts.cron,
+        everyMs,
+        timezone: opts.timezone,
+        jitterMs: jitterMs && jitterMs > 0 ? jitterMs : undefined,
+        overlap: opts.overlap ?? 'allow',
+        catchup: opts.catchup ?? 'latest',
+        note: opts.note,
+        searchAttributes: opts.searchAttributes,
+        priority: opts.priority,
+        concurrency: opts.concurrency,
+    });
+}
+function specOf(record) {
+    return record.spec;
+}
+/** The latest window at or before `atMs`. */
+function latestWindowAtOrBefore(spec, atMs) {
+    if (spec.cron != null)
+        return prevCronFireMs(spec.cron, atMs, spec.timezone);
+    const every = spec.everyMs;
+    return Math.floor(atMs / every) * every;
+}
+/** The first window strictly after `afterMs`. */
+function nextWindowAfter(spec, afterMs) {
+    if (spec.cron != null)
+        return nextCronFireMs(spec.cron, afterMs, spec.timezone);
+    const every = spec.everyMs;
+    return (Math.floor(afterMs / every) + 1) * every;
+}
+/** A stable offset in `[0, jitterMs)` per (schedule, window): FNV-1a over the pair. */
+function jitterFor(id, window, spec) {
+    const max = spec.jitterMs ?? 0;
+    if (max <= 0)
+        return 0;
+    let h = 0x811c9dc5;
+    for (const ch of `${id}@${window}`) {
+        h ^= ch.charCodeAt(0);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h % max;
+}
+function startOptions(record) {
+    const spec = specOf(record);
+    return stripUndefined({
+        tags: [...(record.tags ?? []), `schedule:${record.id}`],
+        namespace: record.namespace,
+        searchAttributes: spec.searchAttributes,
+        priority: spec.priority,
+        concurrency: spec.concurrency,
+    });
+}
+function describe(record) {
+    const spec = specOf(record);
+    const state = record.state;
+    return stripUndefined({
+        id: record.id,
+        workflow: record.workflow,
+        input: spec.input,
+        namespace: record.namespace,
+        cron: spec.cron,
+        everyMs: spec.everyMs,
+        timezone: spec.timezone,
+        jitterMs: spec.jitterMs,
+        overlap: spec.overlap ?? 'allow',
+        catchup: spec.catchup ?? 'latest',
+        paused: record.paused,
+        note: spec.note,
+        tags: record.tags,
+        searchAttributes: spec.searchAttributes,
+        priority: spec.priority,
+        concurrency: spec.concurrency,
+        nextFireAt: record.paused || record.nextFireAt == null ? null : new Date(record.nextFireAt),
+        lastFireAt: state.lastFireAt != null ? new Date(state.lastFireAt) : undefined,
+        lastRunId: state.lastRunId,
+        fires: state.fires ?? 0,
+        lastError: state.lastError,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    });
+}
+function stripUndefined(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=schedules.js.map

package/dist/src/schedules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedules.js","sourceRoot":"","sources":["../../src/schedules.ts"],"names":[],"mappings":"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"}

package/dist/src/stores/lucid-schema.d.ts

@@ -11,6 +11,7 @@ export declare const DURABLE_TABLES: {
     readonly signalWaiters: 'durable_signal_waiters';
     readonly bufferedSignals: 'durable_buffered_signals';
     readonly bufferedEvents: 'durable_buffered_events';
+    readonly schedules: 'durable_schedules';
 };
 /**
  * Where {@link createDurableTables} reports an APPLIED repair. Structurally satisfied by `console`

package/dist/src/stores/lucid-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lucid-schema.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,cAAc;aACzB,IAAI,EAAE,uBAAuB;aAC7B,WAAW,EAAE,0BAA0B;aACvC,UAAU,EAAE,wBAAwB;aACpC,aAAa,EAAE,wBAAwB;aACvC,eAAe,EAAE,0BAA0B;aAC3C,cAAc,EAAE,yBAAyB;CACjC,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AA8ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,QAAQ,EACZ,cAAc,CAAC,EAAE,MAAM,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAyNf;AAED,uFAAuF;AACvF,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5F"}
+{"version":3,"file":"lucid-schema.d.ts","sourceRoot":"","sources":["../../../src/stores/lucid-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,cAAc;aACzB,IAAI,EAAE,uBAAuB;aAC7B,WAAW,EAAE,0BAA0B;aACvC,UAAU,EAAE,wBAAwB;aACpC,aAAa,EAAE,wBAAwB;aACvC,eAAe,EAAE,0BAA0B;aAC3C,cAAc,EAAE,yBAAyB;aACzC,SAAS,EAAE,mBAAmB;CACtB,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AA8ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,QAAQ,EACZ,cAAc,CAAC,EAAE,MAAM,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA6Of;AAED,uFAAuF;AACvF,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS5F"}

package/dist/src/stores/lucid-schema.js

@@ -10,6 +10,7 @@ export const DURABLE_TABLES = {
     signalWaiters: 'durable_signal_waiters',
     bufferedSignals: 'durable_buffered_signals',
     bufferedEvents: 'durable_buffered_events',
+    schedules: 'durable_schedules',
 };
 /**
  * The warning {@link createDurableTables} emits when it actually `ALTER`ed something.
@@ -301,6 +302,25 @@ export async function createDurableTables(db, connectionName, options = {}) {
             table.index(['name', 'published_at'], 'durable_buffered_events_name_idx');
         });
     }
+    // Persisted schedules (`engine.schedules`): the store filters on the columns; `spec`/`state` are
+    // engine-owned JSON documents it keeps verbatim. `next_fire_at` is epoch ms (NULL = never fires
+    // again), exact, so `updateSchedule`'s compare-and-set on it is reliable on every dialect.
+    if (!(await conn().hasTable(DURABLE_TABLES.schedules))) {
+        await conn().createTable(DURABLE_TABLES.schedules, (table) => {
+            table.string('id').primary();
+            table.string('namespace').notNullable().defaultTo('default');
+            table.string('workflow').notNullable();
+            table.boolean('paused').notNullable().defaultTo(false);
+            table.bigInteger('next_fire_at');
+            table.text('tags');
+            table.text('spec').notNullable();
+            table.text('state').notNullable();
+            table.bigInteger('created_at').notNullable();
+            table.bigInteger('updated_at').notNullable();
+            // The worker tick's "due by T" scan: `paused = false AND next_fire_at <= T`.
+            table.index(['paused', 'next_fire_at'], 'durable_schedules_due_idx');
+        });
+    }
     // ONE warning for the whole call, listing every column added, or none at all. Not one per ALTER:
     // an operator needs to know their schema was behind and by what, and a burst of lines is easier to
     // lose than a single one.
@@ -311,6 +331,7 @@ export async function createDurableTables(db, connectionName, options = {}) {
 /** Drop every durable table (reverse FK order). Used by tests and migration `down`. */
 export async function dropDurableTables(db, connectionName) {
     const conn = () => db.connection(connectionName).schema;
+    await conn().dropTableIfExists(DURABLE_TABLES.schedules);
     await conn().dropTableIfExists(DURABLE_TABLES.bufferedEvents);
     await conn().dropTableIfExists(DURABLE_TABLES.bufferedSignals);
     await conn().dropTableIfExists(DURABLE_TABLES.signalWaiters);