adispatchd 0.0.0-stage → 0.1.0

package/dist/persistence/actions.js

@@ -0,0 +1,196 @@
+import { InvalidTransitionError, NotFoundError } from './errors.js';
+import { all, fromJson, get, run, str, toJson, transaction } from './sqlite.js';
+/** Allowed action status changes. */
+export const ACTION_STATUS_TRANSITIONS = {
+    pending: ['running', 'succeeded', 'failed', 'skipped'],
+    // `running → pending`: recovery resets an interrupted attempt before retrying.
+    running: ['succeeded', 'failed', 'pending'],
+    // `failed → running|pending`: (manual) retry; `failed → skipped`: operator skips it.
+    failed: ['running', 'pending', 'skipped'],
+    succeeded: [],
+    skipped: [],
+};
+/** Repository for the action journal. */
+export class ActionRepository {
+    db;
+    clock;
+    constructor(db, clock) {
+        this.db = db;
+        this.clock = clock;
+    }
+    /**
+     * Create the journal for all actions of a hook (`pending`, ordinal 0..n-1).
+     * Idempotent: if a journal for `(runId, hook)` already exists it is returned
+     * unchanged (resume after restart).
+     */
+    createJournal(runId, hook, actions) {
+        return transaction(this.db, () => {
+            const existing = this.listForHook(runId, hook);
+            if (existing.length > 0)
+                return existing;
+            if (!get(this.db, 'SELECT 1 FROM runs WHERE id = ?', [runId]))
+                throw new NotFoundError('run', runId);
+            const now = this.clock.now().toISOString();
+            actions.forEach((action, ordinal) => {
+                run(this.db, `INSERT INTO run_actions (run_id, hook, ordinal, action_type, action_name, action_config_json, status, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, 'pending', ?, ?)`, [runId, hook, ordinal, action.type, action.name ?? null, JSON.stringify(action.config ?? null), now, now]);
+            });
+            return this.listForHook(runId, hook);
+        });
+    }
+    /** Action by ID or `null`. */
+    get(id) {
+        const row = get(this.db, 'SELECT * FROM run_actions WHERE id = ?', [id]);
+        return row ? toAction(row) : null;
+    }
+    /** Action by ID; throws {@link NotFoundError}. */
+    require(id) {
+        const a = this.get(id);
+        if (!a)
+            throw new NotFoundError('action', id);
+        return a;
+    }
+    /** All actions of a run, by hook creation then ordinal. */
+    listForRun(runId) {
+        return all(this.db, 'SELECT * FROM run_actions WHERE run_id = ? ORDER BY id ASC', [runId]).map(toAction);
+    }
+    /** Actions of one hook in ordinal order. */
+    listForHook(runId, hook) {
+        return all(this.db, 'SELECT * FROM run_actions WHERE run_id = ? AND hook = ? ORDER BY ordinal ASC', [runId, hook]).map(toAction);
+    }
+    /**
+     * Change an action's status (validated against {@link ACTION_STATUS_TRANSITIONS}).
+     * `externalKey`/`error` are stored when given.
+     */
+    setStatus(id, status, options = {}) {
+        return transaction(this.db, () => {
+            const current = this.require(id);
+            if (options.expectedFrom !== undefined && current.status !== options.expectedFrom) {
+                throw new InvalidTransitionError(`Action ${id} is '${current.status}', expected '${options.expectedFrom}'`, {
+                    actionId: id,
+                    from: current.status,
+                    to: status,
+                });
+            }
+            if (current.status !== status && !ACTION_STATUS_TRANSITIONS[current.status].includes(status)) {
+                throw new InvalidTransitionError(`Invalid action transition '${current.status}' → '${status}'`, {
+                    actionId: id,
+                    from: current.status,
+                    to: status,
+                });
+            }
+            const sets = ['status = ?', 'updated_at = ?'];
+            const params = [status, this.clock.now().toISOString()];
+            if (options.externalKey !== undefined) {
+                sets.push('external_key = ?');
+                params.push(options.externalKey);
+            }
+            if (options.error !== undefined) {
+                sets.push('last_error_json = ?');
+                params.push(toJson(options.error ?? undefined));
+            }
+            run(this.db, `UPDATE run_actions SET ${sets.join(', ')} WHERE id = ?`, [...params, id]);
+            return this.require(id);
+        });
+    }
+    /**
+     * Start a new attempt: inserts `action_attempts` row (attempt = previous + 1),
+     * increments `attempts` and sets the action `running`.
+     */
+    startAttempt(actionId) {
+        return transaction(this.db, () => {
+            const action = this.require(actionId);
+            if (action.status !== 'running')
+                this.setStatus(actionId, 'running');
+            const next = Number(get(this.db, 'SELECT COALESCE(MAX(attempt), 0) + 1 AS n FROM action_attempts WHERE run_action_id = ?', [actionId])?.n ?? 1);
+            const now = this.clock.now().toISOString();
+            const res = run(this.db, 'INSERT INTO action_attempts (run_action_id, attempt, started_at) VALUES (?, ?, ?)', [
+                actionId,
+                next,
+                now,
+            ]);
+            run(this.db, 'UPDATE run_actions SET attempts = ?, updated_at = ? WHERE id = ?', [next, now, actionId]);
+            return this.requireAttempt(res.lastInsertRowid);
+        });
+    }
+    /**
+     * Record the end of an attempt. Does not change the action status – the
+     * lifecycle engine decides (retry → stays `running`/`pending`, give up → `failed`).
+     */
+    finishAttempt(attemptId, outcome, options = {}) {
+        return transaction(this.db, () => {
+            const attempt = this.requireAttempt(attemptId);
+            const now = this.clock.now().toISOString();
+            run(this.db, 'UPDATE action_attempts SET finished_at = ?, outcome = ?, error_json = ?, external_key = ? WHERE id = ?', [
+                now,
+                outcome,
+                toJson(options.error ?? undefined),
+                options.externalKey ?? null,
+                attemptId,
+            ]);
+            if (options.error !== undefined) {
+                run(this.db, 'UPDATE run_actions SET last_error_json = ?, updated_at = ? WHERE id = ?', [
+                    toJson(options.error),
+                    now,
+                    attempt.actionId,
+                ]);
+            }
+            return this.requireAttempt(attemptId);
+        });
+    }
+    /** Attempts of an action in order. */
+    listAttempts(actionId) {
+        return all(this.db, 'SELECT * FROM action_attempts WHERE run_action_id = ? ORDER BY attempt ASC', [actionId]).map(toAttempt);
+    }
+    /** All `failed` actions with run context, newest first (GUI / retry). */
+    listFailed() {
+        return all(this.db, `SELECT a.*, r.workflow_id AS r_workflow_id, r.source_item_key AS r_item, r.source_url AS r_url
+       FROM run_actions a JOIN runs r ON r.id = a.run_id
+       WHERE a.status = 'failed' ORDER BY a.updated_at DESC, a.id DESC`).map((row) => ({
+            ...toAction(row),
+            workflowId: String(row.r_workflow_id),
+            sourceItemKey: str(row.r_item),
+            sourceUrl: str(row.r_url),
+        }));
+    }
+    /** IDs of runs with `pending` or `running` actions (recovery: resume chains). */
+    runIdsWithIncompleteActions() {
+        return all(this.db, `SELECT DISTINCT run_id FROM run_actions WHERE status IN ('pending', 'running') ORDER BY run_id ASC`).map((r) => String(r.run_id));
+    }
+    requireAttempt(id) {
+        const row = get(this.db, 'SELECT * FROM action_attempts WHERE id = ?', [id]);
+        if (!row)
+            throw new NotFoundError('action_attempt', id);
+        return toAttempt(row);
+    }
+}
+function toAction(row) {
+    return {
+        id: Number(row.id),
+        runId: String(row.run_id),
+        hook: row.hook,
+        ordinal: Number(row.ordinal),
+        type: String(row.action_type),
+        name: str(row.action_name),
+        config: fromJson(row.action_config_json),
+        status: row.status,
+        externalKey: str(row.external_key),
+        attempts: Number(row.attempts),
+        lastError: fromJson(row.last_error_json),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
+function toAttempt(row) {
+    return {
+        id: Number(row.id),
+        actionId: Number(row.run_action_id),
+        attempt: Number(row.attempt),
+        startedAt: String(row.started_at),
+        finishedAt: str(row.finished_at),
+        outcome: str(row.outcome) ?? null,
+        error: fromJson(row.error_json),
+        externalKey: str(row.external_key),
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/persistence/actions.js.map

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

package/dist/persistence/blocks.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Retry blocks and technical-failure counters (Spec §11).
+ *
+ * Counter design: an explicit `failure_counters` row per
+ * `(workflow_id, scope_key)` (scope = source item key, `''` = workflow scope
+ * for sourceless runs) holding `consecutive` and the counting-period
+ * `generation`. It is updated exclusively in the same transaction as a run's
+ * transition into `finalizing` (see `RunRepository.beginFinalization`), which
+ * happens at most once per run – so counting is exactly-once also across
+ * crashes/recovery. Technical failures (`crashed|start_error|timed_out`)
+ * increment; `completed`+`success` resets to 0 and starts a new counting
+ * period (`generation + 1`); business `failure` and `cancelled` leave it
+ * unchanged. Clearing a block likewise resets to 0 and increments
+ * `generation`; old runs and blocks stay untouched.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Clock } from '../core/index.js';
+/** A persisted retry block. `itemKey === null` = workflow-scoped block. */
+export interface BlockRecord {
+    id: number;
+    workflowId: string;
+    itemKey: string | null;
+    reason: string;
+    /** Run whose failure created the block, if any. */
+    runId: string | null;
+    /** Consecutive technical failures when the block was created. */
+    failureCount: number;
+    /** Counting period the block belongs to. */
+    generation: number;
+    createdAt: string;
+    clearedAt: string | null;
+    clearedBy: string | null;
+}
+/** Input for {@link BlockRepository.create}. */
+export interface CreateBlockInput {
+    workflowId: string;
+    itemKey: string | null;
+    reason: string;
+    runId?: string | null;
+    failureCount?: number;
+}
+/** Current counter state of one workflow/scope. */
+export interface FailureCounterState {
+    consecutive: number;
+    generation: number;
+}
+/** Repository for `blocks` and `failure_counters`. */
+export declare class BlockRepository {
+    private readonly db;
+    private readonly clock;
+    constructor(db: DatabaseSync, clock: Clock);
+    /** Create an active block. Throws if an active block already exists for the key. */
+    create(input: CreateBlockInput): BlockRecord;
+    /**
+     * Clear (remove) a block: sets `cleared_at`, resets the counter and starts
+     * a new counting period (`generation + 1`). Idempotent for already cleared blocks.
+     */
+    clear(id: number, clearedBy?: string | null): BlockRecord;
+    /** Block by ID or `null`. */
+    get(id: number): BlockRecord | null;
+    /** Active block for `(workflowId, itemKey)` (`itemKey = null` → workflow scope), or `null`. */
+    activeFor(workflowId: string, itemKey: string | null): BlockRecord | null;
+    /** True if an active block exists for `(workflowId, itemKey)`. */
+    isBlocked(workflowId: string, itemKey: string | null): boolean;
+    /** All active blocks, newest first. */
+    listActive(): BlockRecord[];
+    /** Block history of a workflow (optionally one scope), newest first. */
+    listForWorkflow(workflowId: string, options?: {
+        itemKey?: string | null;
+        limit?: number;
+    }): BlockRecord[];
+    /** IDs of runs whose technical failures were counted in the block's period (for the GUI). */
+    affectedRunIds(blockId: number): string[];
+    /** Consecutive technical failures in the current counting period. */
+    consecutiveTechnicalFailures(workflowId: string, itemKey: string | null): number;
+    /** Counter state (`{0, 0}` if never touched). */
+    counter(workflowId: string, itemKey: string | null): FailureCounterState;
+    /**
+     * Internal: apply a run outcome to the counter. Must be called inside the
+     * transaction that moves the run into `finalizing`.
+     */
+    applyOutcome(workflowId: string, itemKey: string | null, effect: 'increment' | 'reset' | 'none'): FailureCounterState;
+    private ensureCounter;
+    private require;
+}

package/dist/persistence/blocks.js

@@ -0,0 +1,140 @@
+import { BlockExistsError, NotFoundError } from './errors.js';
+import { blockScopeKey } from './lock-keys.js';
+import { all, get, run, str, transaction } from './sqlite.js';
+/** Repository for `blocks` and `failure_counters`. */
+export class BlockRepository {
+    db;
+    clock;
+    constructor(db, clock) {
+        this.db = db;
+        this.clock = clock;
+    }
+    /** Create an active block. Throws if an active block already exists for the key. */
+    create(input) {
+        return transaction(this.db, () => {
+            const existing = this.activeFor(input.workflowId, input.itemKey);
+            if (existing) {
+                throw new BlockExistsError(existing.id);
+            }
+            const { generation } = this.counter(input.workflowId, input.itemKey);
+            const res = run(this.db, `INSERT INTO blocks (workflow_id, source_item_key, reason, run_id, failure_count, generation, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+                input.workflowId,
+                input.itemKey,
+                input.reason,
+                input.runId ?? null,
+                input.failureCount ?? 0,
+                generation,
+                this.clock.now().toISOString(),
+            ]);
+            return this.require(res.lastInsertRowid);
+        });
+    }
+    /**
+     * Clear (remove) a block: sets `cleared_at`, resets the counter and starts
+     * a new counting period (`generation + 1`). Idempotent for already cleared blocks.
+     */
+    clear(id, clearedBy = null) {
+        return transaction(this.db, () => {
+            const block = this.require(id);
+            if (block.clearedAt !== null)
+                return block;
+            const now = this.clock.now().toISOString();
+            run(this.db, 'UPDATE blocks SET cleared_at = ?, cleared_by = ? WHERE id = ?', [now, clearedBy, id]);
+            this.ensureCounter(block.workflowId, block.itemKey);
+            run(this.db, `UPDATE failure_counters SET consecutive = 0, generation = generation + 1, updated_at = ?
+         WHERE workflow_id = ? AND scope_key = ?`, [now, block.workflowId, blockScopeKey(block.itemKey)]);
+            return this.require(id);
+        });
+    }
+    /** Block by ID or `null`. */
+    get(id) {
+        const row = get(this.db, 'SELECT * FROM blocks WHERE id = ?', [id]);
+        return row ? toBlock(row) : null;
+    }
+    /** Active block for `(workflowId, itemKey)` (`itemKey = null` → workflow scope), or `null`. */
+    activeFor(workflowId, itemKey) {
+        const row = get(this.db, `SELECT * FROM blocks WHERE workflow_id = ? AND COALESCE(source_item_key, '') = ? AND cleared_at IS NULL`, [workflowId, blockScopeKey(itemKey)]);
+        return row ? toBlock(row) : null;
+    }
+    /** True if an active block exists for `(workflowId, itemKey)`. */
+    isBlocked(workflowId, itemKey) {
+        return this.activeFor(workflowId, itemKey) !== null;
+    }
+    /** All active blocks, newest first. */
+    listActive() {
+        return all(this.db, 'SELECT * FROM blocks WHERE cleared_at IS NULL ORDER BY created_at DESC, id DESC').map(toBlock);
+    }
+    /** Block history of a workflow (optionally one scope), newest first. */
+    listForWorkflow(workflowId, options = {}) {
+        if (options.itemKey !== undefined) {
+            return all(this.db, `SELECT * FROM blocks WHERE workflow_id = ? AND COALESCE(source_item_key, '') = ?
+         ORDER BY created_at DESC, id DESC LIMIT ?`, [workflowId, blockScopeKey(options.itemKey), options.limit ?? 100]).map(toBlock);
+        }
+        return all(this.db, 'SELECT * FROM blocks WHERE workflow_id = ? ORDER BY created_at DESC, id DESC LIMIT ?', [
+            workflowId,
+            options.limit ?? 100,
+        ]).map(toBlock);
+    }
+    /** IDs of runs whose technical failures were counted in the block's period (for the GUI). */
+    affectedRunIds(blockId) {
+        const block = this.require(blockId);
+        return all(this.db, `SELECT id FROM runs WHERE workflow_id = ? AND COALESCE(source_item_key, '') = ?
+         AND block_generation = ? AND counted_technical_failure = 1
+       ORDER BY created_at ASC, id ASC`, [block.workflowId, blockScopeKey(block.itemKey), block.generation]).map((r) => String(r.id));
+    }
+    /** Consecutive technical failures in the current counting period. */
+    consecutiveTechnicalFailures(workflowId, itemKey) {
+        return this.counter(workflowId, itemKey).consecutive;
+    }
+    /** Counter state (`{0, 0}` if never touched). */
+    counter(workflowId, itemKey) {
+        const row = get(this.db, 'SELECT consecutive, generation FROM failure_counters WHERE workflow_id = ? AND scope_key = ?', [
+            workflowId,
+            blockScopeKey(itemKey),
+        ]);
+        return { consecutive: Number(row?.consecutive ?? 0), generation: Number(row?.generation ?? 0) };
+    }
+    /**
+     * Internal: apply a run outcome to the counter. Must be called inside the
+     * transaction that moves the run into `finalizing`.
+     */
+    applyOutcome(workflowId, itemKey, effect) {
+        this.ensureCounter(workflowId, itemKey);
+        const now = this.clock.now().toISOString();
+        if (effect === 'increment') {
+            run(this.db, 'UPDATE failure_counters SET consecutive = consecutive + 1, updated_at = ? WHERE workflow_id = ? AND scope_key = ?', [now, workflowId, blockScopeKey(itemKey)]);
+        }
+        else if (effect === 'reset') {
+            // A success ends the counting period: next failures belong to a new generation,
+            // so `affectedRunIds` of a later block never includes failures before the success.
+            run(this.db, 'UPDATE failure_counters SET consecutive = 0, generation = generation + 1, updated_at = ? WHERE workflow_id = ? AND scope_key = ?', [now, workflowId, blockScopeKey(itemKey)]);
+        }
+        return this.counter(workflowId, itemKey);
+    }
+    ensureCounter(workflowId, itemKey) {
+        run(this.db, `INSERT INTO failure_counters (workflow_id, scope_key, consecutive, generation, updated_at)
+       VALUES (?, ?, 0, 0, ?) ON CONFLICT (workflow_id, scope_key) DO NOTHING`, [workflowId, blockScopeKey(itemKey), this.clock.now().toISOString()]);
+    }
+    require(id) {
+        const block = this.get(id);
+        if (!block)
+            throw new NotFoundError('block', id);
+        return block;
+    }
+}
+function toBlock(row) {
+    return {
+        id: Number(row.id),
+        workflowId: String(row.workflow_id),
+        itemKey: str(row.source_item_key),
+        reason: String(row.reason),
+        runId: str(row.run_id),
+        failureCount: Number(row.failure_count),
+        generation: Number(row.generation),
+        createdAt: String(row.created_at),
+        clearedAt: str(row.cleared_at),
+        clearedBy: str(row.cleared_by),
+    };
+}
+//# sourceMappingURL=blocks.js.map

package/dist/persistence/blocks.js.map

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

package/dist/persistence/cron-firings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cron idempotency and diagnostics (Spec §5.5, §7): at most one firing
+ * record per `(workflow_id, scheduled_for)`.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Clock } from '../core/index.js';
+/**
+ * Decision for a cron slot, e.g. `started`, `skipped_missed`, `skipped_limit`,
+ * `skipped_condition`, `skipped_blocked`, `skipped_lock` (WI-09 owns the vocabulary).
+ */
+export type CronDecision = string;
+/** A persisted cron firing. */
+export interface CronFiringRecord {
+    workflowId: string;
+    /** Cron slot, ISO-8601 UTC. */
+    scheduledFor: string;
+    runId: string | null;
+    decision: CronDecision;
+    reason: string | null;
+    recordedAt: string;
+}
+/** Input for {@link CronFiringRepository.record}. */
+export interface RecordCronFiringInput {
+    workflowId: string;
+    scheduledFor: Date | string;
+    decision: CronDecision;
+    runId?: string | null;
+    reason?: string | null;
+}
+/** Repository for `cron_firings`. */
+export declare class CronFiringRepository {
+    private readonly db;
+    private readonly clock;
+    constructor(db: DatabaseSync, clock: Clock);
+    /**
+     * Record a firing if none exists for the slot. Returns `inserted: false`
+     * and the existing record if the slot was already handled (no duplicate run).
+     */
+    record(input: RecordCronFiringInput): {
+        inserted: boolean;
+        firing: CronFiringRecord;
+    };
+    /** Update decision/run of an existing slot (e.g. `started` + run ID after reservation). */
+    update(workflowId: string, scheduledFor: Date | string, change: {
+        decision?: CronDecision;
+        runId?: string | null;
+        reason?: string | null;
+    }): CronFiringRecord;
+    /** Firing for a slot or `null`. */
+    get(workflowId: string, scheduledFor: Date | string): CronFiringRecord | null;
+    /** Latest firing (by slot) of a workflow or `null`. */
+    latest(workflowId: string): CronFiringRecord | null;
+    /** Firings of a workflow, newest slot first. */
+    listForWorkflow(workflowId: string, limit?: number): CronFiringRecord[];
+}

package/dist/persistence/cron-firings.js

@@ -0,0 +1,70 @@
+import { NotFoundError } from './errors.js';
+import { all, get, iso, run, str } from './sqlite.js';
+/** Repository for `cron_firings`. */
+export class CronFiringRepository {
+    db;
+    clock;
+    constructor(db, clock) {
+        this.db = db;
+        this.clock = clock;
+    }
+    /**
+     * Record a firing if none exists for the slot. Returns `inserted: false`
+     * and the existing record if the slot was already handled (no duplicate run).
+     */
+    record(input) {
+        const slot = iso(input.scheduledFor);
+        const res = run(this.db, `INSERT INTO cron_firings (workflow_id, scheduled_for, run_id, decision, reason, recorded_at)
+       VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (workflow_id, scheduled_for) DO NOTHING`, [input.workflowId, slot, input.runId ?? null, input.decision, input.reason ?? null, this.clock.now().toISOString()]);
+        const firing = this.get(input.workflowId, slot);
+        if (!firing)
+            throw new NotFoundError('cron_firing', `${input.workflowId}@${slot}`);
+        return { inserted: res.changes === 1, firing };
+    }
+    /** Update decision/run of an existing slot (e.g. `started` + run ID after reservation). */
+    update(workflowId, scheduledFor, change) {
+        const slot = iso(scheduledFor);
+        const current = this.get(workflowId, slot);
+        if (!current)
+            throw new NotFoundError('cron_firing', `${workflowId}@${slot}`);
+        run(this.db, 'UPDATE cron_firings SET decision = ?, run_id = ?, reason = ? WHERE workflow_id = ? AND scheduled_for = ?', [
+            change.decision ?? current.decision,
+            change.runId !== undefined ? change.runId : current.runId,
+            change.reason !== undefined ? change.reason : current.reason,
+            workflowId,
+            slot,
+        ]);
+        return this.get(workflowId, slot);
+    }
+    /** Firing for a slot or `null`. */
+    get(workflowId, scheduledFor) {
+        const row = get(this.db, 'SELECT * FROM cron_firings WHERE workflow_id = ? AND scheduled_for = ?', [
+            workflowId,
+            iso(scheduledFor),
+        ]);
+        return row ? toFiring(row) : null;
+    }
+    /** Latest firing (by slot) of a workflow or `null`. */
+    latest(workflowId) {
+        const row = get(this.db, 'SELECT * FROM cron_firings WHERE workflow_id = ? ORDER BY scheduled_for DESC LIMIT 1', [workflowId]);
+        return row ? toFiring(row) : null;
+    }
+    /** Firings of a workflow, newest slot first. */
+    listForWorkflow(workflowId, limit = 100) {
+        return all(this.db, 'SELECT * FROM cron_firings WHERE workflow_id = ? ORDER BY scheduled_for DESC LIMIT ?', [
+            workflowId,
+            limit,
+        ]).map(toFiring);
+    }
+}
+function toFiring(row) {
+    return {
+        workflowId: String(row.workflow_id),
+        scheduledFor: String(row.scheduled_for),
+        runId: str(row.run_id),
+        decision: String(row.decision),
+        reason: str(row.reason),
+        recordedAt: String(row.recorded_at),
+    };
+}
+//# sourceMappingURL=cron-firings.js.map

package/dist/persistence/cron-firings.js.map

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

package/dist/persistence/database.d.ts

@@ -0,0 +1,60 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type Clock, type Logger } from '../core/index.js';
+import { type Migration } from './schema.js';
+/** Default SQLite busy timeout (ms). */
+export declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+/** Options for {@link openDatabase}. */
+export interface OpenDatabaseOptions {
+    clock?: Clock;
+    logger?: Logger;
+    /** Migrations to apply (default: built-in {@link MIGRATIONS}; tests may append artificial ones). */
+    migrations?: readonly Migration[];
+    busyTimeoutMs?: number;
+}
+/** Outcome of applying migrations. */
+export interface MigrationResult {
+    /** Schema version before opening (0 = empty database). */
+    fromVersion: number;
+    /** Schema version after migrating. */
+    toVersion: number;
+    /** Versions applied during this open. */
+    applied: number[];
+    /** Backup written before migrating, if any. */
+    backupPath: string | null;
+}
+/** An opened, migrated database. */
+export interface OpenedDatabase {
+    db: DatabaseSync;
+    /** Absolute path of the database file. */
+    path: string;
+    migration: MigrationResult;
+    close(): void;
+}
+/**
+ * Open (creating if needed) `<dataDir>/adispatchd.sqlite`, configure it
+ * (foreign keys, WAL, busy timeout) and apply pending migrations. If the
+ * database already existed and migrations are pending, it is first backed up
+ * to `<dataDir>/backups/adispatchd-<version>-<ts>.sqlite`.
+ *
+ * The caller should hold the data-dir instance lock ({@link acquireInstanceLock}) first.
+ */
+export declare function openDatabase(dataDir: string, options?: OpenDatabaseOptions): OpenedDatabase;
+/** Apply connection pragmas. */
+export declare function configureConnection(db: DatabaseSync, busyTimeoutMs?: number): void;
+/** Options for {@link migrate}. */
+export interface MigrateOptions {
+    migrations: readonly Migration[];
+    /** Directory for the pre-migration backup; `null` = no backup (fresh database). */
+    backupDir: string | null;
+    clock: Clock;
+    logger: Logger;
+}
+/** Current schema version (0 if `schema_migrations` does not exist yet). */
+export declare function schemaVersion(db: DatabaseSync): number;
+/** Apply all pending migrations, each in its own transaction. Idempotent. */
+export declare function migrate(db: DatabaseSync, options: MigrateOptions): MigrationResult;
+/**
+ * Write a consistent copy of the database (`VACUUM INTO`, safe in WAL mode)
+ * to `<backupDir>/adispatchd-<version>-<ts>.sqlite`. Returns its path.
+ */
+export declare function backupDatabase(db: DatabaseSync, backupDir: string, version: number, clock: Clock): string;