@plumbus/core 0.8.0-beta.1 → 0.8.0-beta.4

package/dist/flows/dead-letter.d.ts

@@ -8,6 +8,23 @@ export interface OperatorRetryResult {
     flowName: string;
     retriedBy: string;
     retriedAt: string;
+    /**
+     * Under spine dispatch: whether a fresh dispatch hint was published for the reopened
+     * execution. False when the plane holds no durable state for it (a row started before
+     * tenant placement, or a control-plane flow the worker claims from its own table).
+     */
+    republished?: boolean;
+}
+/**
+ * Where a tenant-placed execution's hints go (#137). A row on a tenant plane is only ever
+ * run when the spine holds a ready hint for it; a terminal execution has none, so an operator
+ * retry must publish a fresh one or the reset row sits `created` forever.
+ */
+export interface OperatorRetryPlacement {
+    /** The spine's connection, where `opaque_dispatch` lives. */
+    spineDb: PostgresJsDatabase;
+    /** The plane's framework schema (`core_plumbus` by default). */
+    coreSchema?: string;
 }
 /**
  * Moves failed flow executions to the dead-letter table.
@@ -24,5 +41,5 @@ export declare function sweepFailedFlows(db: PostgresJsDatabase, limit?: number)
  * Attribution is recorded on the dead-letter row and execution state.
  * Failed → Created is an operator exception (not a normal state-machine edge).
  */
-export declare function retryDeadLetteredFlow(db: PostgresJsDatabase, executionId: string, opts: OperatorRetryOptions): Promise<OperatorRetryResult>;
+export declare function retryDeadLetteredFlow(db: PostgresJsDatabase, executionId: string, opts: OperatorRetryOptions, placement?: OperatorRetryPlacement): Promise<OperatorRetryResult>;
 //# sourceMappingURL=dead-letter.d.ts.map

package/dist/flows/dead-letter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../../src/flows/dead-letter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAIlE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC/F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3F;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,kBAAkB,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAuE9B"}
+{"version":3,"file":"dead-letter.d.ts","sourceRoot":"","sources":["../../src/flows/dead-letter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAUlE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6DAA6D;IAC7D,OAAO,EAAE,kBAAkB,CAAC;IAC5B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC/F;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB3F;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,kBAAkB,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,oBAAoB,EAC1B,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAuG9B"}

package/dist/flows/dead-letter.js

@@ -1,4 +1,6 @@
 import { eq } from 'drizzle-orm';
+import { FRAMEWORK_SCHEMA } from '../data/schema-generator.js';
+import { insertDispatchOutbox, publishOutboxToSpine, reopenExecutionState, } from '../durable/index.js';
 import { flowDeadLetterTable, flowExecutionsTable } from './schema.js';
 import { FlowStatus } from './state-machine.js';
 /**
@@ -65,7 +67,7 @@ export async function sweepFailedFlows(db, limit = 100) {
  * Attribution is recorded on the dead-letter row and execution state.
  * Failed → Created is an operator exception (not a normal state-machine edge).
  */
-export async function retryDeadLetteredFlow(db, executionId, opts) {
+export async function retryDeadLetteredFlow(db, executionId, opts, placement) {
     if (!opts.actor?.trim()) {
         throw new Error('Operator retry requires an actor');
     }
@@ -120,11 +122,25 @@ export async function retryDeadLetteredFlow(db, executionId, opts) {
         metadata: { ...existingMeta, ...attribution },
     })
         .where(eq(flowDeadLetterTable.executionId, executionId));
+    let republished = false;
+    if (placement) {
+        // Reopen the durable state and hand the spine a fresh hint, so a worker claims the
+        // reset row again. A plane without state for this execution has nothing to reopen: the
+        // row is claimed from its own table as before.
+        const schemaName = placement.coreSchema ?? FRAMEWORK_SCHEMA;
+        const reopened = await reopenExecutionState(db, { executionId, stepId: row.currentStep ?? '', nowIso: retriedAt }, schemaName);
+        if (reopened) {
+            const outbox = await insertDispatchOutbox(db, reopened, reopened.currentStepId, retriedAt, schemaName);
+            await publishOutboxToSpine(db, placement.spineDb, outbox, `disp:${executionId}:${reopened.revision}`, retriedAt, schemaName);
+            republished = true;
+        }
+    }
     return {
         executionId,
         flowName: row.flowName,
         retriedBy: opts.actor,
         retriedAt,
+        republished,
     };
 }
 //# sourceMappingURL=dead-letter.js.map

package/dist/flows/dead-letter.js.map

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

package/dist/flows/engine.d.ts

@@ -1,10 +1,10 @@
 import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import type { ApprovalService } from '../approvals/types.js';
 import type { EventQueue } from '../events/queue.js';
+import type { DataPlaneResolver } from '../tenancy/types.js';
 import type { AuditService } from '../types/audit.js';
 import type { DataService, EventService, ExecutionContext, FlowExecution, LoggerService } from '../types/context.js';
 import type { AuthContext } from '../types/security.js';
-import type { DataPlaneResolver } from '../tenancy/types.js';
 import type { CompiledFlowRegistry } from './compiled-registry.js';
 import { type DefinitionInFlightStrategy as DefinitionInFlightStrategyName } from './definition-strategy.js';
 import type { FlowRegistry } from './registry.js';
@@ -69,6 +69,21 @@ export interface FlowSpineDispatchConfig {
     resolver: DataPlaneResolver;
     /** Schema holding tenant durable tables. Default `core_plumbus`. */
     coreSchema?: string;
+    /**
+     * What a flow started with no tenant reference does. `'refuse'` (the default) is the
+     * fail-closed choice a single-tenant-per-plane deployment wants. `'control-plane'` places
+     * such a flow on `db` — the spine — exactly as an engine without spine dispatch would, and
+     * claims it from there beside the tenant hints: control-plane work (a fleet sweep, a
+     * platform procedure an operator started) has no tenant plane to live on and no private
+     * state to keep off the spine.
+     */
+    untenanted?: 'refuse' | 'control-plane';
+    /**
+     * How many claims a hint survives without its tenant plane resolving before it is parked
+     * as dead-lettered instead of being re-leased on every poll — a tenant whose plane is gone
+     * (closed, dropped) leaves hints behind. Default 10.
+     */
+    maxClaimAttempts?: number;
 }
 interface FlowExecutionRow {
     id: string;

package/dist/flows/engine.d.ts.map

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

package/dist/flows/engine.js

@@ -1,13 +1,14 @@
-import { z } from 'zod';
-import { and, eq, inArray, isNull, lte, or, sql } from 'drizzle-orm';
 import { randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
+import { and, eq, inArray, isNull, lte, or, sql } from 'drizzle-orm';
+import { z } from 'zod';
 import { parseDurationToMs } from '../config/duration.js';
+import { FRAMEWORK_SCHEMA } from '../data/schema-generator.js';
+import { ackSpineDispatch, casAdvanceExecution, claimSpineDispatch, deadLetterSpineDispatch, extendSpineDispatchLease, findSpineDispatchTenantRoute, insertDispatchOutbox, loadExecutionState, markExecutionStateTerminal, markOutboxAckedBySpineRow, persistAcceptanceOnDb, persistRetryScheduleOnDb, publishOutboxToSpine, } from '../durable/index.js';
+import { SpineDeliveryState } from '../durable/types.js';
 import { FlowCancelledError, LeaseLostError, PlumbusError } from '../errors/index.js';
-import { BUDGET_EXHAUSTED, consumeExecutionBudget, createExecutionBudgetLedger, writeExecutionBudget, } from './budget.js';
 import { BackoffStrategy, ErrorCode, FlowStepType } from '../types/enums.js';
-import { FRAMEWORK_SCHEMA } from '../data/schema-generator.js';
-import { ackSpineDispatch, casAdvanceExecution, claimSpineDispatch, insertDispatchOutbox, loadExecutionState, persistAcceptanceOnDb, publishOutboxToSpine, } from '../durable/index.js';
+import { BUDGET_EXHAUSTED, consumeExecutionBudget, createExecutionBudgetLedger, writeExecutionBudget, } from './budget.js';
 import { flowDefinitionId, hydrateCompiledFlow } from './compile-flow.js';
 import { assertSupportedDefinitionStrategy, DefinitionInFlightStrategy, } from './definition-strategy.js';
 import { flowExecutionsTable } from './schema.js';
@@ -89,8 +90,11 @@ export function createFlowEngine(config) {
     const onFlowStepEnqueue = config.onFlowStepEnqueue;
     const spineDispatch = config.spineDispatch;
     const durableSchema = spineDispatch?.coreSchema ?? FRAMEWORK_SCHEMA;
+    const maxClaimAttempts = spineDispatch?.maxClaimAttempts ?? 10;
+    const untenantedOnControlPlane = spineDispatch?.untenanted === 'control-plane';
     const executionStores = new Map();
     const claimedHints = new Map();
+    const scheduledRetries = new Map();
     const executionPins = new Map();
     function restorePinFromRow(row) {
         if (executionPins.has(row.id))
@@ -138,6 +142,35 @@ export function createFlowEngine(config) {
     function storeFor(executionId) {
         return executionStores.get(executionId) ?? db;
     }
+    /**
+     * Finds the plane an execution's row lives on when this engine did not start or claim it —
+     * a request-side engine reading, cancelling or resuming a flow another process placed on a
+     * tenant plane. The spine's dispatch hint names the tenant route; the resolver names the
+     * plane. Without a hint the execution is the engine's own (control-plane) row, or unknown,
+     * and `db` answers as before.
+     */
+    async function locateStore(executionId) {
+        const cached = executionStores.get(executionId);
+        if (cached)
+            return cached;
+        if (!spineDispatch)
+            return db;
+        try {
+            const tenantRouteId = await findSpineDispatchTenantRoute(spineDispatch.db, executionId);
+            if (!tenantRouteId)
+                return db;
+            const handle = await spineDispatch.resolver.resolve(tenantRouteId);
+            executionStores.set(executionId, handle.db);
+            return handle.db;
+        }
+        catch (error) {
+            logger?.warn('could not locate the plane of a dispatched execution; using the engine database', {
+                executionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return db;
+        }
+    }
     const onFlowDelayedSchedule = config.onFlowDelayedSchedule;
     async function maybeEnqueueFlowStep(executionId, correlationId) {
         if (onFlowStepEnqueue) {
@@ -194,11 +227,18 @@ export function createFlowEngine(config) {
         let writeDb = db;
         if (spineDispatch) {
             if (!auth.tenantId) {
-                throw new PlumbusError(ErrorCode.Forbidden, 'spine dispatch requires a tenant reference on flow start', { reason: 'untenanted-flow-start' });
+                if (!untenantedOnControlPlane) {
+                    throw new PlumbusError(ErrorCode.Forbidden, 'spine dispatch requires a tenant reference on flow start', { reason: 'untenanted-flow-start' });
+                }
+                // A control-plane flow: the classic row on the spine, claimed from there.
+                writeDb = spineDispatch.db;
+                executionStores.set(executionId, writeDb);
+            }
+            else {
+                const handle = await spineDispatch.resolver.resolve(auth.tenantId);
+                writeDb = handle.db;
+                executionStores.set(executionId, writeDb);
             }
-            const handle = await spineDispatch.resolver.resolve(auth.tenantId);
-            writeDb = handle.db;
-            executionStores.set(executionId, writeDb);
         }
         await writeDb.insert(flowExecutionsTable).values({
             id: executionId,
@@ -269,7 +309,7 @@ export function createFlowEngine(config) {
                     tenantState.terminal ||
                     tenantState.revision !== hint.expectedRevision ||
                     tenantState.tenantEpoch !== hint.tenantEpoch) {
-                    await ackSpineDispatch(spineDispatch.db, hint.dispatchId);
+                    await dropSpineHint(handle.db, hint.dispatchId);
                     continue;
                 }
                 const execRows = await handle.db
@@ -278,8 +318,16 @@ export function createFlowEngine(config) {
                     .where(eq(flowExecutionsTable.id, hint.executionId))
                     .limit(1);
                 const row = execRows[0];
-                if (!row) {
-                    await ackSpineDispatch(spineDispatch.db, hint.dispatchId);
+                // A row cancelled or otherwise closed outside the run loop keeps no claim on the
+                // hint that was published for it: drop the hint rather than revive the row.
+                if (!row || isTerminal(row.status)) {
+                    await dropSpineHint(handle.db, hint.dispatchId);
+                    continue;
+                }
+                // A row waiting for an event, or for a wake time that has not come, is not runnable
+                // whatever the hint says; leave the hint to lapse rather than run the wait step again.
+                if (row.status === FlowStatus.Waiting &&
+                    (row.waitingForEvent !== null || (row.wakeAt !== null && row.wakeAt > new Date()))) {
                     continue;
                 }
                 executionStores.set(hint.executionId, handle.db);
@@ -303,16 +351,40 @@ export function createFlowEngine(config) {
                 logger?.error('spine claim failed closed for one dispatch', {
                     dispatchId: hint.dispatchId,
                     executionId: hint.executionId,
+                    attempt: hint.attempt,
                     error: error instanceof Error ? error.message : String(error),
                 });
+                if (hint.attempt >= maxClaimAttempts) {
+                    await deadLetterSpineDispatch(spineDispatch.db, hint.dispatchId, 'plane-unresolved');
+                    logger?.warn('spine hint dead-lettered after repeated claim failures', {
+                        dispatchId: hint.dispatchId,
+                        executionId: hint.executionId,
+                        tenantRouteId: hint.tenantRouteId,
+                        attempt: hint.attempt,
+                    });
+                }
             }
         }
         return rows;
     }
     async function claimNext(batchSize) {
         if (spineDispatch) {
-            return claimNextFromSpine(batchSize);
+            const fromSpine = await claimNextFromSpine(batchSize);
+            if (!untenantedOnControlPlane)
+                return fromSpine;
+            // Control-plane flows live on the spine's own `flow_executions`; claim what budget is
+            // left there, after the tenant hints.
+            const remaining = (batchSize ?? claimBatchSize) - fromSpine.length;
+            if (remaining <= 0)
+                return fromSpine;
+            const fromControlPlane = await claimNextFromOwnDb(remaining);
+            for (const row of fromControlPlane)
+                executionStores.set(row.id, spineDispatch.db);
+            return [...fromSpine, ...fromControlPlane];
         }
+        return claimNextFromOwnDb(batchSize);
+    }
+    async function claimNextFromOwnDb(batchSize) {
         const limit = batchSize ?? claimBatchSize;
         const leaseDurationInterval = `${leaseDurationMs} milliseconds`;
         const result = await db.execute(sql `
@@ -401,6 +473,22 @@ export function createFlowEngine(config) {
      * capability can cooperatively stop its in-flight AI / HTTP work.
      */
     async function extendLease(executionId) {
+        const hint = claimedHints.get(executionId);
+        if (spineDispatch && hint) {
+            const spineExtended = await extendSpineDispatchLease(spineDispatch.db, {
+                dispatchId: hint.dispatchId,
+                workerId,
+                leaseDurationMs,
+            });
+            if (!spineExtended) {
+                logger?.warn('extendSpineDispatchLease matched 0 rows', {
+                    executionId,
+                    dispatchId: hint.dispatchId,
+                    expectedWorkerId: workerId,
+                });
+                return false;
+            }
+        }
         const leaseDurationInterval = `${leaseDurationMs} milliseconds`;
         const result = await storeFor(executionId)
             .update(flowExecutionsTable)
@@ -548,7 +636,11 @@ export function createFlowEngine(config) {
         // Auto-thread `signal` into AI calls so capability authors don't have to
         // pass it explicitly. An explicit `signal` in the call overrides the
         // step default. See AIService type for the per-method signal parameter.
-        const scopedAi = ctx.ai.withContext?.({ tenantId: flowAuth.tenantId, actor: flowAuth.userId }) ?? ctx.ai;
+        const scopedAi = ctx.ai.withContext?.({
+            tenantId: flowAuth.tenantId,
+            actor: flowAuth.userId,
+            correlationId: row.correlationId ?? undefined,
+        }) ?? ctx.ai;
         const flowAi = wrapAiWithDefaultSignal(scopedAi, stepAc.signal);
         const flowCtx = {
             ...ctx,
@@ -824,7 +916,7 @@ export function createFlowEngine(config) {
      * Resume a waiting flow (e.g., after an event arrives or approval granted).
      */
     async function resume(executionId, signal) {
-        const rows = await storeFor(executionId)
+        const rows = await (await locateStore(executionId))
             .select()
             .from(flowExecutionsTable)
             .where(eq(flowExecutionsTable.id, executionId))
@@ -902,7 +994,7 @@ export function createFlowEngine(config) {
      * run their compensation capability first (recovery CompensationState v1).
      */
     async function cancel(executionId, opts) {
-        const rows = await storeFor(executionId)
+        const rows = await (await locateStore(executionId))
             .select()
             .from(flowExecutionsTable)
             .where(eq(flowExecutionsTable.id, executionId))
@@ -932,6 +1024,7 @@ export function createFlowEngine(config) {
             stepHistory: history,
             completedAt: new Date(),
         });
+        await closeSpineState(executionId, 'cancelled');
         if (audit) {
             await audit.record(`flow.cancelled.${row.flowName}`, {
                 executionId,
@@ -1030,7 +1123,7 @@ export function createFlowEngine(config) {
      * Get the current status of a flow execution.
      */
     async function status(executionId) {
-        const rows = await storeFor(executionId)
+        const rows = await (await locateStore(executionId))
             .select()
             .from(flowExecutionsTable)
             .where(eq(flowExecutionsTable.id, executionId))
@@ -1045,13 +1138,31 @@ export function createFlowEngine(config) {
         const retryCount = row.retryCount + 1;
         const maxRetries = flow.retry?.attempts ?? 0;
         if (retryCount <= maxRetries) {
-            // Retry: keep current step, increment counter
-            await guardedUpdate(executionId, {
+            const delayMs = computeRetryDelay(retryCount, flow.retry?.backoff ?? BackoffStrategy.Fixed);
+            const wakeAt = new Date(Date.now() + delayMs);
+            const updated = await guardedUpdate(executionId, {
+                status: FlowStatus.Waiting,
                 stepHistory: history,
                 retryCount,
                 lastError: error ?? null,
+                waitingForEvent: null,
+                wakeAt,
+                leaseOwner: null,
+                leaseExpiresAt: null,
             });
-            return { id: executionId, flowName: row.flowName, status: FlowStatus.Running };
+            if (!updated) {
+                throw new LeaseLostError(`Lease lost scheduling retry for flow execution "${executionId}"`, { executionId, workerId, step: row.currentStep });
+            }
+            if (spineDispatch && row.currentStep) {
+                scheduledRetries.set(executionId, {
+                    stepId: row.currentStep,
+                    notBefore: wakeAt.toISOString(),
+                });
+            }
+            if (onFlowDelayedSchedule) {
+                await onFlowDelayedSchedule(executionId, wakeAt, row.correlationId ?? executionId);
+            }
+            return { id: executionId, flowName: row.flowName, status: FlowStatus.Waiting };
         }
         // Exhausted retries — fail the flow
         await failFlow(executionId, row.flowName, error, row);
@@ -1146,12 +1257,22 @@ export function createFlowEngine(config) {
             FlowStatus.Waiting,
         ])));
         const rowsAffected = getRowsAffected(result);
-        if (rowsAffected > 0 && audit) {
-            await audit.record('flow.runner.finalized', {
-                executionId,
-                workerId,
-                error: message,
-            });
+        if (rowsAffected > 0) {
+            await closeSpineState(executionId, 'failed');
+            // The run never reached its sync: the hint this worker holds is dropped here.
+            const hint = claimedHints.get(executionId);
+            const tenantDb = executionStores.get(executionId);
+            if (hint && tenantDb) {
+                await dropSpineHint(tenantDb, hint.dispatchId);
+                claimedHints.delete(executionId);
+            }
+            if (audit) {
+                await audit.record('flow.runner.finalized', {
+                    executionId,
+                    workerId,
+                    error: message,
+                });
+            }
         }
         return rowsAffected > 0;
     }
@@ -1168,6 +1289,47 @@ export function createFlowEngine(config) {
         const rowsAffected = getRowsAffected(result);
         return rowsAffected > 0;
     }
+    /** Acknowledges a hint on the spine and closes the outbox row behind it on the plane. */
+    async function dropSpineHint(tenantDb, dispatchId) {
+        if (!spineDispatch)
+            return false;
+        const acknowledged = await ackSpineDispatch(spineDispatch.db, dispatchId, workerId);
+        if (!acknowledged)
+            return false;
+        try {
+            await markOutboxAckedBySpineRow(tenantDb, dispatchId, new Date().toISOString(), durableSchema);
+        }
+        catch (error) {
+            logger?.warn('acknowledged spine hint left its outbox row open', {
+                dispatchId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return true;
+    }
+    /**
+     * A terminal transition taken outside the run loop — an operator cancel, the runner
+     * finalising a run that threw — leaves the tenant's durable state open and, possibly, a
+     * hint on the spine. Close the state so the next claim drops the hint. Rows on the engine's
+     * own database (classic placement, control-plane flows) carry no durable state.
+     */
+    async function closeSpineState(executionId, status) {
+        if (!spineDispatch)
+            return;
+        const store = await locateStore(executionId);
+        if (store === spineDispatch.db)
+            return;
+        try {
+            await markExecutionStateTerminal(store, { executionId, status, nowIso: new Date().toISOString() }, durableSchema);
+        }
+        catch (error) {
+            logger?.warn('could not close the durable state of a finished execution', {
+                executionId,
+                status,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     async function syncSpineAfterRun(executionId, result) {
         if (!spineDispatch)
             return;
@@ -1176,6 +1338,27 @@ export function createFlowEngine(config) {
         if (!hint || !tenantDb)
             return;
         const nowIso = new Date().toISOString();
+        const retry = scheduledRetries.get(executionId);
+        if (retry) {
+            try {
+                const scheduled = await persistRetryScheduleOnDb(tenantDb, {
+                    executionId,
+                    expectedRevision: hint.expectedRevision,
+                    tenantEpoch: hint.tenantEpoch,
+                    stepId: retry.stepId,
+                    notBefore: retry.notBefore,
+                }, nowIso, durableSchema);
+                await dropSpineHint(tenantDb, hint.dispatchId);
+                claimedHints.delete(executionId);
+                if (scheduled.kind !== 'committed' || !scheduled.outbox)
+                    return;
+                await publishOutboxToSpine(tenantDb, spineDispatch.db, scheduled.outbox, `disp:${executionId}:${scheduled.execution.revision}`, nowIso, durableSchema, { deliveryState: SpineDeliveryState.RetryScheduled });
+                return;
+            }
+            finally {
+                scheduledRetries.delete(executionId);
+            }
+        }
         const flowRow = (await tenantDb
             .select({ currentStep: flowExecutionsTable.currentStep })
             .from(flowExecutionsTable)
@@ -1201,7 +1384,7 @@ export function createFlowEngine(config) {
             sideEffectKey: `${executionId}:${hint.stepId}:${hint.expectedRevision}`,
             sideEffectLabel: `${executionId}:${hint.stepId}`,
         }, durableSchema);
-        await ackSpineDispatch(spineDispatch.db, hint.dispatchId);
+        await dropSpineHint(tenantDb, hint.dispatchId);
         claimedHints.delete(executionId);
         if (cas !== 'ok' || terminal)
             return;
@@ -1210,11 +1393,15 @@ export function createFlowEngine(config) {
             return;
         const nextStep = flowRow.currentStep;
         const outbox = await insertDispatchOutbox(tenantDb, advanced, nextStep, nowIso, durableSchema);
-        await publishOutboxToSpine(tenantDb, spineDispatch.db, outbox, `disp:${executionId}:${advanced.revision}`, nowIso, durableSchema);
+        // The worker that ran this step drains the next one without claiming again, so the hint
+        // for it is born under this worker's lease; a worker that dies mid-drain lets it lapse
+        // and another claims it. Keeping the hint lets the next sync advance the durable state.
+        const next = await publishOutboxToSpine(tenantDb, spineDispatch.db, outbox, `disp:${executionId}:${advanced.revision}`, nowIso, durableSchema, { workerId, leaseExpiresAt: new Date(Date.now() + leaseDurationMs).toISOString() });
+        claimedHints.set(executionId, next);
     }
     async function applyDefinitionStrategy(executionId, strategy) {
         assertSupportedDefinitionStrategy(strategy);
-        const rows = await storeFor(executionId)
+        const rows = await (await locateStore(executionId))
             .select()
             .from(flowExecutionsTable)
             .where(eq(flowExecutionsTable.id, executionId))