bunqueue 2.8.46 → 2.8.47

package/dist/client/workflow/runner.js

@@ -1,10 +1,12 @@
 /**
  * WorkflowRunner - Step execution with retry, parallel execution, sub-workflow dispatch
  */
+import { idempotencyKey, isIterationOf, describeError } from './identity';
+import { clock } from './clock';
 /** Exponential backoff with jitter */
 function backoffDelay(attempt, baseMs = 500, maxMs = 30_000) {
     const delay = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
-    const jitter = delay * 0.5 * Math.random();
+    const jitter = delay * 0.5 * clock().random();
     return delay + jitter;
 }
 /** Run a promise with a timeout */
@@ -14,28 +16,39 @@ export function runWithTimeout(promise, timeoutMs) {
     if (timeoutMs <= 0)
         return promise;
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
+        const timer = clock().setTimeout(() => {
             reject(new Error(`Step timed out after ${timeoutMs}ms`));
         }, timeoutMs);
         promise.then((v) => {
-            clearTimeout(timer);
+            clock().clearTimeout(timer);
             resolve(v);
         }, (e) => {
-            clearTimeout(timer);
-            reject(e instanceof Error ? e : new Error(String(e)));
+            clock().clearTimeout(timer);
+            // `describeError`, not `String`: this wrapper runs BEFORE the compensator's own
+            // catch, so converting here with `String` is what destroyed a structured throw
+            // into `[object Object]` no matter how carefully the catch handled it.
+            reject(e instanceof Error ? e : new Error(describeError(e)));
         });
     });
 }
 /** Execute a step with retry logic and exponential backoff */
-export async function executeStepWithRetry(def, ctx, exec, emitter, updateFn) {
+export async function executeStepWithRetry(def, ctx, exec, hooks, occurrence = 0) {
+    const { emitter, updateFn } = hooks;
     const maxAttempts = def.retry;
     let lastError;
+    // Derived once, outside the retry loop, and persisted with the START record: a
+    // rollback for a step whose outcome is unknown needs this key to reconcile, and by
+    // then the body may never have reached the point of writing anything.
+    const forwardKey = idempotencyKey(exec.id, def.name, occurrence, 'forward');
+    const stepCtx = { ...ctx, idempotencyKey: forwardKey };
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         const prev = exec.steps[def.name];
         exec.steps[def.name] = {
             status: 'running',
-            startedAt: prev?.startedAt ?? Date.now(),
+            startedAt: prev?.startedAt ?? clock().now(),
             attempts: attempt,
+            idempotencyKey: forwardKey,
+            occurrence,
         };
         updateFn(exec);
         emitter?.emitStep('step:started', exec.id, exec.workflowName, def.name, {
@@ -43,29 +56,50 @@ export async function executeStepWithRetry(def, ctx, exec, emitter, updateFn) {
             maxAttempts,
         });
         try {
+            let input = stepCtx.input;
             if (def.inputSchema) {
                 try {
-                    def.inputSchema.parse(ctx.input);
+                    // The RETURN VALUE matters. `parse()` is the coercing entry point of every
+                    // schema library the docs point at: `.default()` fills gaps, `.transform()`
+                    // rewrites, `z.coerce.date()` builds a Date from a string. Calling it purely
+                    // for its throw validated the shape and silently dropped every coercion, so
+                    // a step declaring `.default('EUR')` ran with no currency at all
+                    // (`test/repro-workflow-gate-and-schema.test.ts`). A validator that returns
+                    // nothing is still supported: `undefined` means "I only assert", so the
+                    // original value is kept rather than blanked.
+                    const parsed = def.inputSchema.parse(stepCtx.input);
+                    if (parsed !== undefined)
+                        input = parsed;
                 }
                 catch (e) {
-                    throw new Error(`Input validation failed for "${def.name}": ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+                    throw new Error(`Input validation failed for "${def.name}": ${describeError(e)}`, {
+                        cause: e,
+                    });
                 }
             }
-            const result = await runWithTimeout(def.handler(ctx), def.timeout);
+            const handlerCtx = input === stepCtx.input ? stepCtx : { ...stepCtx, input };
+            let result = await runWithTimeout(def.handler(handlerCtx), def.timeout);
             if (def.outputSchema) {
                 try {
-                    def.outputSchema.parse(result);
+                    const parsed = def.outputSchema.parse(result);
+                    if (parsed !== undefined)
+                        result = parsed;
                 }
                 catch (e) {
-                    throw new Error(`Output validation failed for "${def.name}": ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+                    throw new Error(`Output validation failed for "${def.name}": ${describeError(e)}`, {
+                        cause: e,
+                    });
                 }
             }
             exec.steps[def.name] = {
                 status: 'completed',
+                compensatable: def.compensate !== undefined,
                 result,
                 startedAt: exec.steps[def.name].startedAt,
-                completedAt: Date.now(),
+                completedAt: clock().now(),
                 attempts: attempt,
+                idempotencyKey: forwardKey,
+                occurrence,
             };
             updateFn(exec);
             emitter?.emitStep('step:completed', exec.id, exec.workflowName, def.name, {
@@ -76,14 +110,14 @@ export async function executeStepWithRetry(def, ctx, exec, emitter, updateFn) {
             return;
         }
         catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
+            lastError = err instanceof Error ? err : new Error(describeError(err));
             if (attempt < maxAttempts) {
                 emitter?.emitStep('step:retry', exec.id, exec.workflowName, def.name, {
                     error: lastError.message,
                     attempt,
                     maxAttempts,
                 });
-                await new Promise((r) => setTimeout(r, backoffDelay(attempt)));
+                await new Promise((r) => clock().setTimeout(() => r(), backoffDelay(attempt)));
                 continue;
             }
         }
@@ -91,12 +125,33 @@ export async function executeStepWithRetry(def, ctx, exec, emitter, updateFn) {
     const finalError = lastError ?? new Error('Step failed');
     exec.steps[def.name] = {
         status: 'failed',
+        compensatable: def.compensate !== undefined,
         error: String(finalError),
         startedAt: exec.steps[def.name].startedAt,
-        completedAt: Date.now(),
+        completedAt: clock().now(),
         attempts: maxAttempts,
+        idempotencyKey: forwardKey,
+        occurrence,
     };
-    updateFn(exec);
+    // The step's own error is the cause; a write that fails while RECORDING it is
+    // downstream, and letting it propagate instead replaced "warehouse rejected the
+    // reservation" with "SQLITE_BUSY". `executor.ts` writes whatever surfaces into
+    // `failureReason`, so the operator got the name of the database's problem and no trace
+    // of the real one (`test/repro-workflow-step-error-masking.test.ts`).
+    //
+    // The same masking was fixed in `loops.ts` one frame above this, at the call sites.
+    // That was not a fix of the behaviour: this writer is what every step goes through,
+    // loop or not, so the property only holds once it is enforced here.
+    //
+    // On the success path above there is no step error to protect, so that write stays
+    // unguarded and a store that cannot persist a completed step still fails loudly: a
+    // record that never reached disk is one whose work runs again.
+    try {
+        updateFn(exec);
+    }
+    catch {
+        // Deliberately swallowed: `finalError` is thrown below and carries the real cause.
+    }
     emitter?.emitStep('step:failed', exec.id, exec.workflowName, def.name, {
         error: String(finalError),
         attempt: maxAttempts,
@@ -106,19 +161,39 @@ export async function executeStepWithRetry(def, ctx, exec, emitter, updateFn) {
 }
 /** Execute multiple steps in parallel via Promise.allSettled */
 export async function executeParallelSteps(steps, ctx, exec, emitter, updateFn) {
-    const results = await Promise.allSettled(steps.map((def) => executeStepWithRetry(def, ctx, exec, emitter, updateFn)));
+    const results = await Promise.allSettled(steps.map((def) => executeStepWithRetry(def, ctx, exec, { emitter, updateFn })));
     const failed = results.filter((r) => r.status === 'rejected');
     if (failed.length > 0) {
-        const errors = failed.map((r) => r.reason instanceof Error ? r.reason : new Error(String(r.reason)));
+        const errors = failed.map((r) => r.reason instanceof Error ? r.reason : new Error(describeError(r.reason)));
         throw new AggregateError(errors, errors[0].message);
     }
 }
 /** Execute a sub-workflow by starting it and polling for completion */
-export async function executeSubWorkflow(workflowName, input, startFn, getFn, pollIntervalMs = 100) {
-    const handle = await startFn(workflowName, input);
+// 6 params, one over the limit. `existingChildId` is what makes re-entering this node resume
+// the child a restart already started, instead of abandoning it and provisioning a second
+// one, so it belongs in the signature where a caller cannot forget it rather than in an
+// options bag where omitting it looks deliberate.
+// biome-ignore lint/complexity/useMaxParams: see above
+export async function executeSubWorkflow(workflowName, input, startFn, getFn, pollIntervalMs = 100, 
+/**
+ * A child this node already started, from an earlier entry into the same node.
+ *
+ * Without it the node started a BRAND NEW child every time it was re-entered, and
+ * re-entry is routine: a restart followed by `recover()` re-enqueues the parent's
+ * current node. Measured across one restart, the child ran twice and both rows were
+ * left `running` forever, since a child is excluded from recovery while its parent
+ * exists and `cleanup`/`archive` only reap terminal states. Duplicated work, not just
+ * a leaked row: a child that provisions a resource provisioned it twice
+ * (`test/repro-workflow-orphan-child.test.ts`).
+ */
+existingChildId) {
+    // Resume the existing child when it is still there. A row that has been cleaned away
+    // cannot be resumed, so that case starts fresh.
+    const existing = existingChildId ? getFn(existingChildId) : null;
+    const handle = existing ? { id: existing.id } : await startFn(workflowName, input);
     const maxWait = 300_000;
-    const start = Date.now();
-    while (Date.now() - start < maxWait) {
+    const start = clock().now();
+    while (clock().now() - start < maxWait) {
         const subExec = getFn(handle.id);
         if (subExec?.state === 'completed') {
             const results = {};
@@ -126,12 +201,21 @@ export async function executeSubWorkflow(workflowName, input, startFn, getFn, po
                 if (record.status === 'completed')
                     results[name] = record.result;
             }
-            return results;
+            return { results, executionId: handle.id };
         }
         if (subExec?.state === 'failed') {
             throw new Error(`Sub-workflow "${workflowName}" (${handle.id}) failed`);
         }
-        await new Promise((r) => setTimeout(r, pollIntervalMs));
+        // A child that parks mid-rollback is terminal FOR THIS POLL: nothing it does next
+        // happens without an operator. Waiting for it was measured at the full 300 s, after
+        // which the parent reported a timeout, which is the wrong diagnostic for precisely
+        // the scenario this module exists to handle, and it held a worker slot for five
+        // minutes to say it. The parent parks too, with the real reason.
+        if (subExec?.state === 'compensation-stuck') {
+            throw new Error(`Sub-workflow "${workflowName}" (${handle.id}) is parked mid-rollback ` +
+                `(compensation-stuck); resolve it with resumeCompensation or abandonCompensation`);
+        }
+        await new Promise((r) => clock().setTimeout(() => r(), pollIntervalMs));
     }
     throw new Error(`Sub-workflow "${workflowName}" (${handle.id}) timed out`);
 }
@@ -158,9 +242,23 @@ export function findStepDef(wf, name) {
                 return found;
         }
         if (node.type === 'forEach') {
-            if (node.def.step.name === name || name.startsWith(node.def.step.name + ':')) {
+            if (node.def.step.name === name)
                 return node.def.step;
-            }
+        }
+    }
+    // Only now consider iteration records. Two passes, not one: a loop body named
+    // `charge` and a separate step named `charge:extra` both "start with charge:", so a
+    // single prefix pass resolved `charge:extra` to the LOOP's definition. Its own
+    // rollback never ran and the loop's ran twice. Exact names win outright, and an
+    // iteration suffix must be numeric — the only suffix this engine generates.
+    for (const node of wf.nodes) {
+        if (node.type === 'doUntil' || node.type === 'doWhile') {
+            const found = node.def.steps.find((s) => isIterationOf(name, s.name));
+            if (found)
+                return found;
+        }
+        if (node.type === 'forEach' && isIterationOf(name, node.def.step.name)) {
+            return node.def.step;
         }
     }
     return null;

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

@@ -1,20 +1,80 @@
 /**
  * WorkflowStore - SQLite persistence for workflow executions
  */
-import type { Execution, ExecutionState } from './types';
+import type { Execution, 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;
     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.
+     */
     save(exec: Execution): void;
     get(id: string): Execution | null;
+    /**
+     * Persist the step-level columns of an execution.
+     *
+     * Deliberately does NOT write `signals`. A worker holds one in-memory `Execution`
+     * for the whole duration of a node, so its `signals` snapshot goes stale as soon as
+     * `recordSignal()` writes to the row. Rewriting the column from that stale snapshot
+     * silently destroyed signals delivered mid-step and parked the run forever
+     * (`test/repro-workflow-signal-lost-update.test.ts`). Signal payloads are owned
+     * exclusively by `recordSignal()`/`parkForSignal()`, which read-modify-write the
+     * column inside a transaction.
+     */
     update(exec: Execution): void;
+    /**
+     * Record a signal payload and, if the run is parked at a `waitFor`, atomically
+     * claim the single resume for this caller.
+     */
+    recordSignal(id: string, event: string, payload: unknown): SignalOutcome;
+    /**
+     * 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 all executions in recoverable states (running, waiting, compensating) */
+    /**
+     * Executions in a recoverable state that recovery may drive ON ITS OWN.
+     *
+     * A `subWorkflow` child is a row like any other, so the state filter alone offered
+     * it to `recover()` as if it were a top-level run. Driving it independently re-ran
+     * its steps and produced fresh records with no `compensation`, which defeats the
+     * "a step that already carries an outcome is not re-run" guard: the parent's later
+     * unwind dispatched the child's reversal a SECOND time, against a provider that had
+     * already been refunded (`test/repro-model-child-recovered-alone.test.ts`; found by
+     * the state-machine model, seed 1267197984).
+     *
+     * A child's lifecycle belongs to its parent, which unwinds it through `unwindChild`.
+     * One exception: if the parent row is gone, nothing owns the child any more, so it
+     * is returned rather than stranded forever in a non-terminal state.
+     */
     listRecoverable(): Execution[];
-    /** Delete executions older than maxAge in terminal states */
+    /**
+     * Delete executions at least `maxAgeMs` old in terminal states.
+     *
+     * The cutoff is INCLUSIVE. A strict `<` makes `cleanup(0)`, the documented way to
+     * flush everything terminal right now, skip every row whose `updated_at` lands on
+     * the current millisecond, which is precisely where a run that just finished lands
+     * (`test/repro-workflow-archive-boundary.test.ts`).
+     */
     cleanup(maxAgeMs: number, states?: string[]): number;
-    /** Archive executions older than maxAge to the archive table */
+    /** Archive executions at least `maxAgeMs` old to the archive table. Cutoff inclusive, as in `cleanup`. */
     archive(maxAgeMs: number, states?: string[]): number;
     /** Get archived execution count */
     getArchivedCount(): number;

package/dist/client/workflow/store.js

@@ -2,17 +2,9 @@
  * WorkflowStore - SQLite persistence for workflow executions
  */
 import { Database } from 'bun:sqlite';
-import { Packr, Unpackr } from 'msgpackr';
-const packr = new Packr({ structuredClone: true });
-const unpackr = new Unpackr({ structuredClone: true });
-function pack(data) {
-    return packr.pack(data);
-}
-function unpack(buf) {
-    if (!buf)
-        return null;
-    return unpackr.unpack(buf);
-}
+import { pack, unpack } from './storeCodec';
+import { SignalCoordinator } from './storeSignals';
+import { clock } from './clock';
 const CREATE_TABLE = `
 CREATE TABLE IF NOT EXISTS workflow_executions (
   id TEXT PRIMARY KEY,
@@ -42,26 +34,59 @@ 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;
+}
 export class WorkflowStore {
     db;
     stmts;
+    /** Sole owner of the `signals` column — see storeSignals.ts */
+    signals;
     constructor(dbPath) {
         this.db = new Database(dbPath ?? ':memory:', { create: true });
         this.db.run('PRAGMA journal_mode = WAL');
+        // The Engine hands the SAME dataPath to this store and to its embedded
+        // Queue/Worker, so two connections share one file. Without a busy timeout a
+        // read-then-upgrade inside signal()/parkForSignal() can surface SQLITE_BUSY
+        // straight to the caller, with no retry, the moment the queue happens to be
+        // writing. Five seconds matches the server's own persistence layer.
+        this.db.run('PRAGMA busy_timeout = 5000');
         this.db.run(CREATE_TABLE);
         this.db.run(CREATE_ARCHIVE_TABLE);
         this.db.run(CREATE_IDX_NAME);
         this.db.run(CREATE_IDX_STATE);
+        // 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.
+        for (const table of ['workflow_executions', 'workflow_executions_archive']) {
+            try {
+                this.db.run(`ALTER TABLE ${table} ADD COLUMN meta BLOB`);
+            }
+            catch {
+                /* already migrated */
+            }
+        }
         this.stmts = {
             upsert: this.db.prepare(`
-        INSERT OR REPLACE INTO workflow_executions
-        (id, workflow_name, state, input, steps, current_node_index, resolved_steps, signals, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO workflow_executions
+        (id, workflow_name, state, input, steps, current_node_index, resolved_steps, signals, created_at, updated_at, meta)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `),
             get: this.db.prepare(`SELECT * FROM workflow_executions WHERE id = ?`),
+            // NOTE: `signals` is deliberately absent. That column is owned exclusively by
+            // recordSignal()/parkForSignal() — see the comment on `update()`.
             updateState: this.db.prepare(`
         UPDATE workflow_executions
-        SET state = ?, steps = ?, current_node_index = ?, resolved_steps = ?, signals = ?, updated_at = ?
+        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`),
@@ -70,17 +95,62 @@ export class WorkflowStore {
             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`),
         };
+        this.signals = new SignalCoordinator(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.
+     */
     save(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);
+        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));
     }
     get(id) {
         const row = this.stmts.get.get(id);
         return row ? this.rowToExecution(row) : null;
     }
+    /**
+     * Persist the step-level columns of an execution.
+     *
+     * Deliberately does NOT write `signals`. A worker holds one in-memory `Execution`
+     * for the whole duration of a node, so its `signals` snapshot goes stale as soon as
+     * `recordSignal()` writes to the row. Rewriting the column from that stale snapshot
+     * silently destroyed signals delivered mid-step and parked the run forever
+     * (`test/repro-workflow-signal-lost-update.test.ts`). Signal payloads are owned
+     * exclusively by `recordSignal()`/`parkForSignal()`, which read-modify-write the
+     * column inside a transaction.
+     */
     update(exec) {
-        exec.updatedAt = Date.now();
-        this.stmts.updateState.run(exec.state, pack(exec.steps), exec.currentNodeIndex, exec.resolvedSteps ? pack(exec.resolvedSteps) : null, pack(exec.signals), exec.updatedAt, exec.id);
+        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);
+    }
+    /**
+     * Record a signal payload and, if the run is parked at a `waitFor`, atomically
+     * claim the single resume for this caller.
+     */
+    recordSignal(id, event, payload) {
+        return this.signals.record(id, event, payload);
+    }
+    /**
+     * 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, event) {
+        return this.signals.park(id, event);
     }
     list(workflowName, state) {
         let rows;
@@ -98,38 +168,60 @@ export class WorkflowStore {
         }
         return rows.map((r) => this.rowToExecution(r));
     }
-    /** List all executions in recoverable states (running, waiting, compensating) */
+    /**
+     * Executions in a recoverable state that recovery may drive ON ITS OWN.
+     *
+     * A `subWorkflow` child is a row like any other, so the state filter alone offered
+     * it to `recover()` as if it were a top-level run. Driving it independently re-ran
+     * its steps and produced fresh records with no `compensation`, which defeats the
+     * "a step that already carries an outcome is not re-run" guard: the parent's later
+     * unwind dispatched the child's reversal a SECOND time, against a provider that had
+     * already been refunded (`test/repro-model-child-recovered-alone.test.ts`; found by
+     * the state-machine model, seed 1267197984).
+     *
+     * A child's lifecycle belongs to its parent, which unwinds it through `unwindChild`.
+     * One exception: if the parent row is gone, nothing owns the child any more, so it
+     * is returned rather than stranded forever in a non-terminal state.
+     */
     listRecoverable() {
         const rows = this.stmts.listRecoverable.all();
-        return rows.map((r) => this.rowToExecution(r));
+        const all = rows.map((r) => this.rowToExecution(r));
+        return all.filter((e) => !e.parentExecutionId || this.get(e.parentExecutionId) === null);
     }
-    /** Delete executions older than maxAge in terminal states */
+    /**
+     * Delete executions at least `maxAgeMs` old in terminal states.
+     *
+     * The cutoff is INCLUSIVE. A strict `<` makes `cleanup(0)`, the documented way to
+     * flush everything terminal right now, skip every row whose `updated_at` lands on
+     * the current millisecond, which is precisely where a run that just finished lands
+     * (`test/repro-workflow-archive-boundary.test.ts`).
+     */
     cleanup(maxAgeMs, states = ['completed', 'failed']) {
-        const cutoff = Date.now() - maxAgeMs;
+        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 stmt = this.db.prepare(`DELETE FROM workflow_executions WHERE updated_at <= ? AND state IN (${placeholders})`);
         const result = stmt.run(cutoff, ...states);
         return result.changes;
     }
-    /** Archive executions older than maxAge to the archive table */
+    /** Archive executions at least `maxAgeMs` old to the archive table. Cutoff inclusive, as in `cleanup`. */
     archive(maxAgeMs, states = ['completed', 'failed']) {
-        const cutoff = Date.now() - maxAgeMs;
-        const now = Date.now();
+        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`)
+            .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)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      (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);
+                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);
             }
         });
@@ -160,6 +252,7 @@ export class WorkflowStore {
             signals: unpack(row.signals) ?? {},
             createdAt: row.created_at,
             updatedAt: row.updated_at,
+            ...(unpack(row.meta) ?? {}),
         };
     }
 }

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

@@ -0,0 +1,7 @@
+/**
+ * msgpack codec shared by the workflow store and its signal coordinator.
+ * Kept in its own module so both can encode blobs identically without either
+ * owning the packer.
+ */
+export declare function pack(data: unknown): Uint8Array;
+export declare function unpack(buf: Uint8Array | null | undefined): unknown;

package/dist/client/workflow/storeCodec.js

@@ -0,0 +1,16 @@
+/**
+ * msgpack codec shared by the workflow store and its signal coordinator.
+ * Kept in its own module so both can encode blobs identically without either
+ * owning the packer.
+ */
+import { Packr, Unpackr } from 'msgpackr';
+const packr = new Packr({ structuredClone: true });
+const unpackr = new Unpackr({ structuredClone: true });
+export function pack(data) {
+    return packr.pack(data);
+}
+export function unpack(buf) {
+    if (!buf)
+        return null;
+    return unpackr.unpack(buf);
+}