bunqueue 2.8.49 → 2.8.50

package/dist/client/workflow/runnerTiming.js

@@ -0,0 +1,66 @@
+/**
+ * Timing primitives used while running a workflow step.
+ *
+ * Kept separate from runner.ts so the runner stays focused on state transitions.
+ */
+import { clock } from './clock';
+import { describeError } from './identity';
+/** Largest delay accepted by Bun/Node timers without wrapping to 1ms. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Exponential retry backoff with jitter. */
+export function retryBackoffDelay(attempt, baseMs = 500, maxMs = 30_000) {
+    const delay = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
+    return delay + delay * 0.5 * clock().random();
+}
+/**
+ * Bound a value or PromiseLike without passing an overflowing delay to the runtime.
+ *
+ * Long deadlines are re-armed in platform-sized chunks. Promise.resolve is
+ * intentional: it assimilates userland thenables as well as native promises.
+ */
+export function runWithTimeout(value, timeoutMs, controller) {
+    const operation = Promise.resolve(value);
+    if (!(timeoutMs > 0) || !Number.isFinite(timeoutMs))
+        return operation;
+    const scheduler = clock();
+    const deadline = scheduler.now() + timeoutMs;
+    if (!Number.isFinite(deadline))
+        return operation;
+    return new Promise((resolve, reject) => {
+        let timer;
+        let settled = false;
+        const clearTimer = () => {
+            if (timer)
+                scheduler.clearTimeout(timer);
+            timer = undefined;
+        };
+        const onTimeout = () => {
+            if (settled)
+                return;
+            const remaining = deadline - scheduler.now();
+            if (remaining > 0) {
+                timer = scheduler.setTimeout(onTimeout, Math.min(remaining, MAX_TIMER_DELAY_MS));
+                return;
+            }
+            settled = true;
+            timer = undefined;
+            const error = new Error(`Step timed out after ${timeoutMs}ms`);
+            controller?.abort(error);
+            reject(error);
+        };
+        timer = scheduler.setTimeout(onTimeout, Math.min(timeoutMs, MAX_TIMER_DELAY_MS));
+        operation.then((result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimer();
+            resolve(result);
+        }, (reason) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimer();
+            reject(reason instanceof Error ? reason : new Error(describeError(reason)));
+        });
+    });
+}

package/dist/client/workflow/stepTypes.d.ts

@@ -0,0 +1,171 @@
+/** Workflow handler, definition, and graph types. */
+/** Context passed to step handlers */
+export interface StepContext<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
+    /** Original workflow input */
+    readonly input: TInput;
+    /** Results from completed steps (step name → result) */
+    readonly steps: Readonly<TSteps>;
+    /** Signals received via engine.signal() */
+    readonly signals: Readonly<Record<string, unknown>>;
+    /** Current execution ID */
+    readonly executionId: string;
+    /**
+     * Aborted when this handler attempt reaches its timeout.
+     *
+     * Handlers that support cooperative cancellation should pass this signal to
+     * downstream I/O so timed-out work does not continue after the workflow moves on.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Idempotency key for THIS execution of the step. Stable across automatic retries
+     * and across crash-resume; different for a different run. Pass it straight to the
+     * provider so a repeat lands on the same operation instead of a new one.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * Compensation only: the key the FORWARD step used. When the forward outcome is
+     * in doubt, this is what lets a rollback ask the provider "did this actually
+     * happen?" instead of depending on an output that may never have been persisted.
+     */
+    readonly forwardIdempotencyKey?: string;
+}
+/** Step handler function (type-erased for internal storage) */
+export type StepHandler<TInput = unknown, TResult = unknown> = (ctx: StepContext<TInput, any>) => Promise<TResult> | TResult;
+/** Typed step handler — preserves accumulated step types */
+export type TypedStepHandler<TInput, TSteps extends Record<string, unknown>, TResult> = (ctx: StepContext<TInput, TSteps>) => Promise<TResult> | TResult;
+/** Compensate handler (type-erased for internal storage) */
+export type CompensateHandler<TInput = unknown> = (ctx: StepContext<TInput, any>) => Promise<void> | void;
+/** Typed compensate handler — preserves accumulated step types */
+export type TypedCompensateHandler<TInput, TSteps extends Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => Promise<void> | void;
+/** Schema-like object — any object with a .parse() method (Zod, ArkType, Valibot, etc.) */
+export interface SchemaLike {
+    parse(data: unknown): unknown;
+}
+/**
+ * Options for a single step.
+ *
+ * `TSteps` is part of the signature for source compatibility and for symmetry with
+ * `TypedStepHandler`, even though `compensate` no longer narrows on it (see below).
+ * Removing the parameter would break every explicit `StepOptions<In, Steps>` in
+ * user code.
+ */
+export interface StepOptions<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> {
+    retry?: number;
+    timeout?: number;
+    /**
+     * A METHOD taking a permissively-typed context, and every part of that is load
+     * bearing. Three forms were measured against real handler shapes:
+     *
+     *   shape                                     union   method<TSteps>   method<any>
+     *   compensate: async (ctx) => ...            TS7006  ok               ok
+     *   annotated with steps it reads             ok      ok               ok
+     *   annotated with a step that does not exist ok      TS2322           ok
+     *   CompensateHandler<TInput> alias           ok      ok               ok
+     *
+     * Not a union (`TypedCompensateHandler | CompensateHandler`): TypeScript cannot
+     * contextually type a parameter against a union of signatures, so the inline arrow
+     * every documented example uses was an implicit `any` and failed `noImplicitAny`.
+     *
+     * A method rather than a property so parameters stay bivariant under
+     * `strictFunctionTypes`, which is what lets an explicitly annotated handler through.
+     *
+     * `any` rather than `TSteps` for the step map, deliberately: with `TSteps` an
+     * annotation naming a step this workflow does not declare is rejected, and the
+     * published union accepted it. Keeping the looser map costs typed access to
+     * `ctx.steps` inside a rollback, which handlers already narrow with a cast in
+     * practice, and buys source compatibility with every handler written before.
+     */
+    compensate?(ctx: StepContext<TInput, TSteps extends never ? never : any>): Promise<void> | void;
+    /** Validate step input before execution */
+    inputSchema?: SchemaLike;
+    /** Validate step output after execution */
+    outputSchema?: SchemaLike;
+}
+/** Internal step definition */
+export interface StepDefinition {
+    name: string;
+    handler: StepHandler;
+    compensate?: CompensateHandler;
+    retry: number;
+    timeout: number;
+    inputSchema?: SchemaLike;
+    outputSchema?: SchemaLike;
+}
+/** Branch condition function */
+export type BranchCondition<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => string;
+/** Internal branch definition (type-erased) */
+export interface BranchDefinition {
+    condition: BranchCondition<any, any>;
+    paths: Map<string, StepDefinition[]>;
+}
+/** Definition of a parallel step group */
+export interface ParallelDefinition {
+    steps: StepDefinition[];
+}
+/** Input mapper for sub-workflows */
+export type SubWorkflowInputMapper<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown;
+/** Bounds for polling a child workflow. */
+export interface SubWorkflowOptions {
+    /** Maximum time to wait for the child. Defaults to five minutes. */
+    timeout?: number;
+    /** Delay between durable child-state reads. Defaults to 100ms. */
+    pollInterval?: number;
+}
+/** Loop condition: receives context + iteration count, returns boolean */
+export type LoopCondition<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>, iteration: number) => boolean | Promise<boolean>;
+/** Definition of a doUntil/doWhile loop (type-erased) */
+export interface LoopDefinition {
+    condition: LoopCondition<any, any>;
+    steps: StepDefinition[];
+    maxIterations: number;
+}
+/** Item extractor for forEach */
+export type ForEachItemsExtractor<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown[];
+/** Definition of a forEach loop (type-erased) */
+export interface ForEachDefinition {
+    items: ForEachItemsExtractor<any, any>;
+    step: StepDefinition;
+    maxIterations: number;
+}
+/** Transform function for map */
+export type MapTransformFn<TInput = unknown, TSteps extends Record<string, unknown> = Record<string, unknown>> = (ctx: StepContext<TInput, TSteps>) => unknown;
+/** Definition of a map node (type-erased) */
+export interface MapDefinition {
+    name: string;
+    transform: MapTransformFn<any, any>;
+}
+/** Workflow node (discriminated union) */
+export type WorkflowNode = {
+    type: 'step';
+    def: StepDefinition;
+} | {
+    type: 'branch';
+    def: BranchDefinition;
+} | {
+    type: 'waitFor';
+    event: string;
+    timeout?: number;
+} | {
+    type: 'parallel';
+    def: ParallelDefinition;
+} | {
+    type: 'subWorkflow';
+    name: string;
+    inputMapper: SubWorkflowInputMapper<any, any>;
+    timeout: number;
+    pollInterval: number;
+} | {
+    type: 'doUntil';
+    def: LoopDefinition;
+} | {
+    type: 'doWhile';
+    def: LoopDefinition;
+} | {
+    type: 'forEach';
+    def: ForEachDefinition;
+} | {
+    type: 'map';
+    def: MapDefinition;
+} | {
+    type: 'pivot';
+};

package/dist/client/workflow/stepTypes.js

@@ -0,0 +1,3 @@
+/* biome-ignore-all lint/suspicious/noExplicitAny: runtime definitions intentionally erase accumulated generics */
+/** Workflow handler, definition, and graph types. */
+export {};

package/dist/client/workflow/store.d.ts

@@ -1,31 +1,24 @@
 /**
  * WorkflowStore - SQLite persistence for workflow executions
  */
-import type { Execution, ExecutionState, ParkOutcome, SignalOutcome } from './types';
+import type { Execution, ExecutionListOptions, ExecutionState, ParkOutcome, SignalOutcome } from './types';
 export declare class WorkflowStore {
     private readonly db;
     private readonly stmts;
     /** Sole owner of the `signals` column — see storeSignals.ts */
     private readonly signals;
+    private readonly listing;
     constructor(dbPath?: string);
     /**
-     * INSERT a brand-new execution. Not an upsert in spirit, despite the statement.
-     *
-     * A plain INSERT, not an upsert: the statement used to be `INSERT OR REPLACE`, so a
-     * duplicate execution id silently OVERWROTE a live run instead of failing. Ids carry
-     * a random component, which makes that vanishingly rare in production and reachable
-     * in a simulation, where a seeded generator draws from a far smaller space. A lost
-     * execution is the worst possible presentation of a collision; a constraint error is
-     * the best.
-     *
-     * This is the ONLY writer of `signals` outside SignalCoordinator, and it is safe
-     * only because its single caller passes a fresh execution whose signals are `{}`.
-     * Calling it on a live run would write a stale snapshot over signals delivered
-     * since it was read, which is exactly the lost-update SignalCoordinator exists to
-     * prevent. Use `update()` for anything that already exists.
+     * Insert a fresh execution. A plain INSERT exposes id collisions instead of
+     * replacing live runs. This is the only signal writer outside SignalCoordinator and
+     * is safe because callers pass a new execution with no signals.
      */
     save(exec: Execution): void;
     get(id: string): Execution | null;
+    findChild(parentExecutionId: string, workflowName: string): Execution | null;
+    /** Remove an execution whose initial queue publication failed. */
+    remove(id: string): boolean;
     /**
      * Persist the step-level columns of an execution.
      *
@@ -43,12 +36,20 @@ export declare class WorkflowStore {
      * claim the single resume for this caller.
      */
     recordSignal(id: string, event: string, payload: unknown): SignalOutcome;
+    /**
+     * Restore the wait claim if publishing its resume job failed.
+     *
+     * The signal remains durable, so recover() can publish the resume again.
+     */
+    restoreSignalWait(id: string, event: string, nodeIndex: number): boolean;
     /**
      * Park a running execution at a `waitFor`, unless the awaited signal has already
      * been recorded (in which case the caller must advance instead).
      */
     parkForSignal(id: string, event: string): ParkOutcome;
-    list(workflowName?: string, state?: ExecutionState): Execution[];
+    list(workflowName?: string, state?: ExecutionState, options?: ExecutionListOptions): Execution[];
+    /** Runs whose registered definition must remain available and structurally stable. */
+    listActive(workflowName: string): Execution[];
     /**
      * Executions in a recoverable state that recovery may drive ON ITS OWN.
      *
@@ -79,5 +80,4 @@ export declare class WorkflowStore {
     /** Get archived execution count */
     getArchivedCount(): number;
     close(): void;
-    private rowToExecution;
 }

package/dist/client/workflow/store.js

@@ -2,9 +2,12 @@
  * WorkflowStore - SQLite persistence for workflow executions
  */
 import { Database } from 'bun:sqlite';
-import { pack, unpack } from './storeCodec';
+import { pack } from './storeCodec';
 import { SignalCoordinator } from './storeSignals';
 import { clock } from './clock';
+import { decodeExecution, packExecutionMeta } from './storeExecutionCodec';
+import { archivedExecutionCount, archiveExecutions, cleanupExecutions } from './storeMaintenance';
+import { ExecutionListing } from './storeListing';
 const CREATE_TABLE = `
 CREATE TABLE IF NOT EXISTS workflow_executions (
   id TEXT PRIMARY KEY,
@@ -34,23 +37,19 @@ CREATE TABLE IF NOT EXISTS workflow_executions_archive (
 )`;
 const CREATE_IDX_NAME = `CREATE INDEX IF NOT EXISTS idx_wf_name ON workflow_executions(workflow_name)`;
 const CREATE_IDX_STATE = `CREATE INDEX IF NOT EXISTS idx_wf_state ON workflow_executions(state)`;
-function packMeta(exec) {
-    const meta = {};
-    if (exec.rollbackStatus !== undefined)
-        meta.rollbackStatus = exec.rollbackStatus;
-    if (exec.failureReason !== undefined)
-        meta.failureReason = exec.failureReason;
-    if (exec.committedAt !== undefined)
-        meta.committedAt = exec.committedAt;
-    if (exec.parentExecutionId !== undefined)
-        meta.parentExecutionId = exec.parentExecutionId;
-    return Object.keys(meta).length > 0 ? pack(meta) : null;
-}
+const CREATE_LIST_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_wf_created ON workflow_executions(created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_wf_name_created ON workflow_executions(workflow_name, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_wf_state_created ON workflow_executions(state, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_wf_name_state_created ON workflow_executions(workflow_name, state, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_wf_state_updated ON workflow_executions(state, updated_at ASC, id ASC)`,
+];
 export class WorkflowStore {
     db;
     stmts;
     /** Sole owner of the `signals` column — see storeSignals.ts */
     signals;
+    listing;
     constructor(dbPath) {
         this.db = new Database(dbPath ?? ':memory:', { create: true });
         this.db.run('PRAGMA journal_mode = WAL');
@@ -64,6 +63,8 @@ export class WorkflowStore {
         this.db.run(CREATE_ARCHIVE_TABLE);
         this.db.run(CREATE_IDX_NAME);
         this.db.run(CREATE_IDX_STATE);
+        for (const statement of CREATE_LIST_INDEXES)
+            this.db.run(statement);
         // Rollback bookkeeping arrived after the original schema. One nullable blob
         // rather than three columns keeps the migration to a single guarded statement
         // per table; SQLite has no ADD COLUMN IF NOT EXISTS, so the throw IS the check.
@@ -89,39 +90,42 @@ export class WorkflowStore {
         SET state = ?, steps = ?, current_node_index = ?, resolved_steps = ?, updated_at = ?, meta = ?
         WHERE id = ?
       `),
-            list: this.db.prepare(`SELECT * FROM workflow_executions ORDER BY created_at DESC LIMIT 100`),
-            listByName: this.db.prepare(`SELECT * FROM workflow_executions WHERE workflow_name = ? ORDER BY created_at DESC LIMIT 100`),
-            listByState: this.db.prepare(`SELECT * FROM workflow_executions WHERE state = ? ORDER BY created_at DESC LIMIT 100`),
-            listByBoth: this.db.prepare(`SELECT * FROM workflow_executions WHERE workflow_name = ? AND state = ? ORDER BY created_at DESC LIMIT 100`),
-            listRecoverable: this.db.prepare(`SELECT * FROM workflow_executions WHERE state IN ('running', 'waiting', 'compensating') ORDER BY updated_at ASC`),
+            childrenByName: this.db.prepare(`SELECT * FROM workflow_executions WHERE workflow_name = ? ORDER BY created_at ASC, id ASC`),
+            listActiveByName: this.db.prepare(`SELECT * FROM workflow_executions
+         WHERE workflow_name = ?
+           AND state IN ('running', 'waiting', 'compensating', 'compensation-stuck', 'failed')`),
+            listRecoverable: this.db.prepare(`SELECT * FROM workflow_executions
+         WHERE state IN ('running', 'waiting', 'compensating', 'failed')
+         ORDER BY updated_at ASC, id ASC`),
+            remove: this.db.prepare(`DELETE FROM workflow_executions WHERE id = ?`),
         };
         this.signals = new SignalCoordinator(this.db);
+        this.listing = new ExecutionListing(this.db);
     }
     /**
-     * INSERT a brand-new execution. Not an upsert in spirit, despite the statement.
-     *
-     * A plain INSERT, not an upsert: the statement used to be `INSERT OR REPLACE`, so a
-     * duplicate execution id silently OVERWROTE a live run instead of failing. Ids carry
-     * a random component, which makes that vanishingly rare in production and reachable
-     * in a simulation, where a seeded generator draws from a far smaller space. A lost
-     * execution is the worst possible presentation of a collision; a constraint error is
-     * the best.
-     *
-     * This is the ONLY writer of `signals` outside SignalCoordinator, and it is safe
-     * only because its single caller passes a fresh execution whose signals are `{}`.
-     * Calling it on a live run would write a stale snapshot over signals delivered
-     * since it was read, which is exactly the lost-update SignalCoordinator exists to
-     * prevent. Use `update()` for anything that already exists.
+     * Insert a fresh execution. A plain INSERT exposes id collisions instead of
+     * replacing live runs. This is the only signal writer outside SignalCoordinator and
+     * is safe because callers pass a new execution with no signals.
      */
     save(exec) {
         if (Object.keys(exec.signals).length > 0) {
             throw new Error('WorkflowStore.save() is for new executions only; it would overwrite delivered signals. Use update().');
         }
-        this.stmts.upsert.run(exec.id, exec.workflowName, exec.state, pack(exec.input), pack(exec.steps), exec.currentNodeIndex, exec.resolvedSteps ? pack(exec.resolvedSteps) : null, pack(exec.signals), exec.createdAt, exec.updatedAt, packMeta(exec));
+        this.stmts.upsert.run(exec.id, exec.workflowName, exec.state, pack(exec.input), pack(exec.steps), exec.currentNodeIndex, exec.resolvedSteps ? pack(exec.resolvedSteps) : null, pack(exec.signals), exec.createdAt, exec.updatedAt, packExecutionMeta(exec));
     }
     get(id) {
         const row = this.stmts.get.get(id);
-        return row ? this.rowToExecution(row) : null;
+        return row ? decodeExecution(row) : null;
+    }
+    findChild(parentExecutionId, workflowName) {
+        const rows = this.stmts.childrenByName.all(workflowName);
+        return (rows.map(decodeExecution).find((child) => child.parentExecutionId === parentExecutionId) ??
+            null);
+    }
+    /** Remove an execution whose initial queue publication failed. */
+    remove(id) {
+        const result = this.stmts.remove.run(id);
+        return result.changes === 1;
     }
     /**
      * Persist the step-level columns of an execution.
@@ -136,7 +140,7 @@ export class WorkflowStore {
      */
     update(exec) {
         exec.updatedAt = clock().now();
-        this.stmts.updateState.run(exec.state, pack(exec.steps), exec.currentNodeIndex, exec.resolvedSteps ? pack(exec.resolvedSteps) : null, exec.updatedAt, packMeta(exec), exec.id);
+        this.stmts.updateState.run(exec.state, pack(exec.steps), exec.currentNodeIndex, exec.resolvedSteps ? pack(exec.resolvedSteps) : null, exec.updatedAt, packExecutionMeta(exec), exec.id);
     }
     /**
      * Record a signal payload and, if the run is parked at a `waitFor`, atomically
@@ -145,6 +149,14 @@ export class WorkflowStore {
     recordSignal(id, event, payload) {
         return this.signals.record(id, event, payload);
     }
+    /**
+     * Restore the wait claim if publishing its resume job failed.
+     *
+     * The signal remains durable, so recover() can publish the resume again.
+     */
+    restoreSignalWait(id, event, nodeIndex) {
+        return this.signals.restoreWaiting(id, event, nodeIndex);
+    }
     /**
      * Park a running execution at a `waitFor`, unless the awaited signal has already
      * been recorded (in which case the caller must advance instead).
@@ -152,21 +164,15 @@ export class WorkflowStore {
     parkForSignal(id, event) {
         return this.signals.park(id, event);
     }
-    list(workflowName, state) {
-        let rows;
-        if (workflowName && state) {
-            rows = this.stmts.listByBoth.all(workflowName, state);
-        }
-        else if (workflowName) {
-            rows = this.stmts.listByName.all(workflowName);
-        }
-        else if (state) {
-            rows = this.stmts.listByState.all(state);
-        }
-        else {
-            rows = this.stmts.list.all();
-        }
-        return rows.map((r) => this.rowToExecution(r));
+    list(workflowName, state, options) {
+        return this.listing.list(workflowName, state, options);
+    }
+    /** Runs whose registered definition must remain available and structurally stable. */
+    listActive(workflowName) {
+        const rows = this.stmts.listActiveByName.all(workflowName);
+        return rows
+            .map(decodeExecution)
+            .filter((exec) => exec.state !== 'failed' || exec.rollbackStatus === undefined);
     }
     /**
      * Executions in a recoverable state that recovery may drive ON ITS OWN.
@@ -185,8 +191,12 @@ export class WorkflowStore {
      */
     listRecoverable() {
         const rows = this.stmts.listRecoverable.all();
-        const all = rows.map((r) => this.rowToExecution(r));
-        return all.filter((e) => !e.parentExecutionId || this.get(e.parentExecutionId) === null);
+        const all = rows.map(decodeExecution);
+        return all.filter((execution) => {
+            if (execution.state === 'failed' && execution.rollbackStatus !== undefined)
+                return false;
+            return !execution.parentExecutionId || this.get(execution.parentExecutionId) === null;
+        });
     }
     /**
      * Delete executions at least `maxAgeMs` old in terminal states.
@@ -197,62 +207,17 @@ export class WorkflowStore {
      * (`test/repro-workflow-archive-boundary.test.ts`).
      */
     cleanup(maxAgeMs, states = ['completed', 'failed']) {
-        const cutoff = clock().now() - maxAgeMs;
-        const placeholders = states.map(() => '?').join(',');
-        const stmt = this.db.prepare(`DELETE FROM workflow_executions WHERE updated_at <= ? AND state IN (${placeholders})`);
-        const result = stmt.run(cutoff, ...states);
-        return result.changes;
+        return cleanupExecutions(this.db, maxAgeMs, states);
     }
     /** Archive executions at least `maxAgeMs` old to the archive table. Cutoff inclusive, as in `cleanup`. */
     archive(maxAgeMs, states = ['completed', 'failed']) {
-        const cutoff = clock().now() - maxAgeMs;
-        const now = clock().now();
-        const placeholders = states.map(() => '?').join(',');
-        const rows = this.db
-            .prepare(`SELECT * FROM workflow_executions WHERE updated_at <= ? AND state IN (${placeholders}) LIMIT 1000`)
-            .all(cutoff, ...states);
-        if (rows.length === 0)
-            return 0;
-        const insertArchive = this.db.prepare(`
-      INSERT OR REPLACE INTO workflow_executions_archive
-      (id, workflow_name, state, input, steps, current_node_index, resolved_steps, signals, created_at, updated_at, archived_at, meta)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `);
-        const deleteOriginal = this.db.prepare(`DELETE FROM workflow_executions WHERE id = ?`);
-        const tx = this.db.transaction(() => {
-            for (const row of rows) {
-                insertArchive.run(row.id, row.workflow_name, row.state, row.input, row.steps, row.current_node_index, row.resolved_steps, row.signals, row.created_at, row.updated_at, now, row.meta ?? null);
-                deleteOriginal.run(row.id);
-            }
-        });
-        tx();
-        return rows.length;
+        return archiveExecutions(this.db, maxAgeMs, states);
     }
     /** Get archived execution count */
     getArchivedCount() {
-        const row = this.db
-            .prepare(`SELECT COUNT(*) as cnt FROM workflow_executions_archive`)
-            .get();
-        return row.cnt;
+        return archivedExecutionCount(this.db);
     }
     close() {
         this.db.close();
     }
-    rowToExecution(row) {
-        return {
-            id: row.id,
-            workflowName: row.workflow_name,
-            state: row.state,
-            input: unpack(row.input),
-            steps: unpack(row.steps) ?? {},
-            currentNodeIndex: row.current_node_index,
-            resolvedSteps: row.resolved_steps
-                ? unpack(row.resolved_steps)
-                : undefined,
-            signals: unpack(row.signals) ?? {},
-            createdAt: row.created_at,
-            updatedAt: row.updated_at,
-            ...(unpack(row.meta) ?? {}),
-        };
-    }
 }

package/dist/client/workflow/storeExecutionCodec.d.ts

@@ -0,0 +1,11 @@
+import type { Execution } from './types';
+export interface ExecutionMeta {
+    rollbackStatus?: Execution['rollbackStatus'];
+    failureReason?: string;
+    committedAt?: number;
+    parentExecutionId?: string;
+    decisions?: Record<string, unknown>;
+    definitionHash?: string;
+}
+export declare function packExecutionMeta(exec: Execution): Uint8Array | null;
+export declare function decodeExecution(row: Record<string, unknown>): Execution;

package/dist/client/workflow/storeExecutionCodec.js

@@ -0,0 +1,34 @@
+import { pack, unpack } from './storeCodec';
+export function packExecutionMeta(exec) {
+    const meta = {};
+    if (exec.rollbackStatus !== undefined)
+        meta.rollbackStatus = exec.rollbackStatus;
+    if (exec.failureReason !== undefined)
+        meta.failureReason = exec.failureReason;
+    if (exec.committedAt !== undefined)
+        meta.committedAt = exec.committedAt;
+    if (exec.parentExecutionId !== undefined)
+        meta.parentExecutionId = exec.parentExecutionId;
+    if (exec.decisions !== undefined)
+        meta.decisions = exec.decisions;
+    if (exec.definitionHash !== undefined)
+        meta.definitionHash = exec.definitionHash;
+    return Object.keys(meta).length > 0 ? pack(meta) : null;
+}
+export function decodeExecution(row) {
+    return {
+        id: row.id,
+        workflowName: row.workflow_name,
+        state: row.state,
+        input: unpack(row.input),
+        steps: unpack(row.steps) ?? {},
+        currentNodeIndex: row.current_node_index,
+        resolvedSteps: row.resolved_steps
+            ? unpack(row.resolved_steps)
+            : undefined,
+        signals: unpack(row.signals) ?? {},
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        ...(unpack(row.meta) ?? {}),
+    };
+}

package/dist/client/workflow/storeListing.d.ts

@@ -0,0 +1,11 @@
+import type { Database } from 'bun:sqlite';
+import type { Execution, ExecutionListOptions, ExecutionState } from './types';
+/** Prepared, consistently ordered execution-list queries. */
+export declare class ExecutionListing {
+    private readonly all;
+    private readonly byName;
+    private readonly byState;
+    private readonly byBoth;
+    constructor(db: Database);
+    list(workflowName?: string, state?: ExecutionState, options?: ExecutionListOptions): Execution[];
+}