@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/engine/lifecycle/delayed-start-registration.d.ts

@@ -0,0 +1,30 @@
+import type { TimerEntry } from '../../types.ts';
+import type { ExecutableRegistration } from '../dynamic-source-execution.ts';
+import type { EngineInternals } from '../internals.ts';
+import type { TimeOperationCallbacks } from '../operations-time.ts';
+/**
+ * Resolve `type`'s registration for a delayed-start fire, failing the
+ * workflow (via `callbacks.failWorkflow`) and returning `null` on any
+ * resolution error instead of throwing. ADR 0002: acquires this workflow's
+ * claim standalone + hydrates cleanup tracking BEFORE failing — the
+ * happy-path pending→running fold later in `startDelayedWorkflow` would
+ * otherwise establish both.
+ *
+ * Resolved against `revision` — the pending run's own persisted
+ * `WorkflowState.revision` (WFT-17), `undefined` for a legacy record —
+ * never the catalog's active pointer, so a delayed-start fire honors the
+ * exact revision this run was created against, matching
+ * `resumeWorkflowFromStorage()`'s use of the same resolver.
+ *
+ * Returns the FULL `{ entry, revision }` pair, not just `entry` — mirroring
+ * `resolveExecutableRegistrationOrRenamedNotFound()`'s shape used by
+ * `resume.ts`/`transition.ts`. For a legacy, pre-revision-pinning pending
+ * record with exactly one registered `registerSource()` candidate, the
+ * resolver can unambiguously resolve that candidate even though the input
+ * `revision` was `undefined` — the caller MUST thread this returned
+ * `revision` (not the input `revision` or the persisted state's own,
+ * still-`undefined` `revision`) through the pending→running transition and
+ * into `beginWorkflowExecution`, or the per-instance identity cache ends up
+ * stamped with the wrong (missing) revision (WFT-19 review round 7).
+ */
+export declare function resolveDelayedStartRegistrationOrFail(internals: EngineInternals, entry: TimerEntry, type: string, revision: string | undefined, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'resolveExecutableRegistrationForRevision'>): Promise<ExecutableRegistration | null>;

package/dist/core/engine/lifecycle/delayed-start-registration.js

@@ -0,0 +1,11 @@
+import { ensureDelayedStartClaimAndCleanupBeforeFailure } from "./standalone-claim-acquire.js";
+export async function resolveDelayedStartRegistrationOrFail(internals, entry, type, revision, callbacks) {
+  try {
+    return await callbacks.resolveExecutableRegistrationForRevision(type, revision);
+  } catch (error) {
+    await ensureDelayedStartClaimAndCleanupBeforeFailure(internals, entry.workflowId);
+    const asError = error instanceof Error ? error : Error(String(error));
+    await callbacks.failWorkflow(entry.workflowId, asError);
+    return null;
+  }
+}

package/dist/core/engine/lifecycle/fork-helpers.d.ts

@@ -5,5 +5,37 @@ import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
 export declare function createForkLineage(_internals: EngineInternals, sourceWorkflowId: string, checkpoint: Checkpoint, _callbacks: LifecycleCallbacks): ForkLineage;
 export declare function buildForkSearchAttributes(_internals: EngineInternals, checkpoint: Checkpoint, lineage: ForkLineage, _callbacks: LifecycleCallbacks): Record<string, SearchAttributeValue>;
-export declare function createForkedWorkflowState(_internals: EngineInternals, workflowId: string, sourceState: WorkflowState, versionTuple: WorkflowVersionTuple, lineage: ForkLineage, forkedAt: number, _callbacks: LifecycleCallbacks): WorkflowState;
+export declare function createForkedWorkflowState(_internals: EngineInternals, workflowId: string, sourceState: WorkflowState, versionTuple: WorkflowVersionTuple, lineage: ForkLineage, forkedAt: number, _callbacks: LifecycleCallbacks, 
+/**
+ * `fork()`'s own resolver-returned revision — used to fill in the fork's
+ * persisted `revision` ONLY when `sourceState.revision` is itself
+ * `undefined` (WFT-19 review round 6, Codex, P1). Never overrides an
+ * already-defined `sourceState.revision`: `resolveExecutableRegistrationForRevision()`
+ * ALWAYS returns `revision: undefined` for an eager registration (eager
+ * has no ambiguity to resolve against — see `canResolveRevisionLocally`'s
+ * doc), even though the eager source run's own `sourceState.revision` is
+ * a real, independently-meaningful value (`resolveCachedStartRevision()`'s
+ * `registeredCatalogRevisions` fallback stamps it at ordinary start time,
+ * for every registration kind). Blindly preferring `resolvedRevision`
+ * here would have dropped that real value for every eager-type fork —
+ * caught by `tests/replay-fixtures/fork-from-checkpoint.json`'s golden
+ * byte comparison. For a legacy (pre-revision-pinning) source run on a
+ * dynamic-source type with exactly one registered candidate,
+ * `sourceState.revision` genuinely IS `undefined` even though the
+ * resolver resolved — and the fork launches against — that sole
+ * candidate's code; `sourceState.revision ?? resolvedRevision` falls
+ * through to the resolver's answer only in that case. Stamping the fork's
+ * persisted `revision` with the raw `undefined` legacy pin (as this
+ * function did before this fix existed) left the fork durably unpinned:
+ * it would run correctly until the next restart, but a fresh-process
+ * `recoverAll()` after a second candidate is later registered would
+ * classify the fork `legacy-ambiguous` and refuse to resume it, even
+ * though the fork's own resolver already knew exactly which revision it
+ * belonged to at creation time. Mirrors the identical fix already applied
+ * to the process-local identity cache in `checkpoint-launch.ts`'s
+ * `launchWorkflowFromCheckpoint()` (WFT-19 review round 5) — that fix
+ * closed the in-memory gap; this one closes the matching durable-state
+ * gap the same bug left behind, for the one case it actually applies to.
+ */
+resolvedRevision: string | undefined): WorkflowState;
 export declare function buildForkBatchOperations(_internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, serializedCheckpoint: Uint8Array, workflowStartHeaders: Map<string, string> | undefined, _callbacks: LifecycleCallbacks): BatchOperation[];

package/dist/core/engine/lifecycle/fork-helpers.js

@@ -16,7 +16,8 @@ export function buildForkSearchAttributes(_internals, checkpoint, lineage, _call
     [FORK_LINEAGE_ATTRIBUTE]: lineage.workflowId
   };
 }
-export function createForkedWorkflowState(_internals, workflowId, sourceState, versionTuple, lineage, forkedAt, _callbacks) {
+export function createForkedWorkflowState(_internals, workflowId, sourceState, versionTuple, lineage, forkedAt, _callbacks, resolvedRevision) {
+  const forkRevision = sourceState.revision ?? resolvedRevision;
   return {
     id: workflowId,
     type: sourceState.type,
@@ -24,6 +25,7 @@ export function createForkedWorkflowState(_internals, workflowId, sourceState, v
     input: sourceState.input,
     workflowExecutionToken: crypto.randomUUID(),
     versionTuple,
+    ...forkRevision !== void 0 && { revision: forkRevision },
     executionStateOwnerId: workflowId,
     createdAt: forkedAt,
     startedAt: forkedAt,

package/dist/core/engine/lifecycle/recovery-revision-groups.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `recoverAll()`'s per-`(type, revision)` preload barrier (WFT-17/WFT-18),
+ * replacing the per-`type`-only barrier `recovery-dynamic-sources.ts` used
+ * to own. Split out of `transition.ts`, which has no headroom under the
+ * repository's 500-line implementation-file ceiling for this logic inline
+ * — the same reason `recovery-dynamic-sources.ts` was split out for
+ * WFT-15/16.
+ *
+ * Recovery scans non-terminal workflow states, groups them by their exact
+ * `(type, revision)` pin (a legacy record with no persisted `revision`
+ * groups under `undefined` for its type), and preloads/classifies every
+ * group BEFORE any group's runs advance — ready, or unavailable with the
+ * error every run in that group fails with. Grouping and classification use
+ * nested `Map<type, Map<revision, …>>` structures rather than a
+ * delimiter-joined composite key, so an arbitrary workflow `type` or
+ * `revision` string can never collide with a delimiter.
+ *
+ * @module core/engine/lifecycle/recovery-revision-groups
+ */
+import { DynamicWorkflowSourceUnavailableError } from '../dynamic-source-errors.ts';
+import type { EngineInternals } from '../internals.ts';
+import { WorkflowRevisionUnavailableError } from '../revision-errors.ts';
+import type { LifecycleCallbacks } from './shared.ts';
+/** One preflight-recoverable entry's identity, as `transition.ts`'s preflight scan produces it. */
+export type RecoverableRevisionEntry = {
+    readonly workflowId: string;
+    readonly type: string;
+    readonly revision: string | undefined;
+};
+/** One `(type, revision)` group: every non-terminal run pinned to that exact revision. */
+export type RecoveryRevisionGroup = {
+    readonly type: string;
+    readonly revision: string | undefined;
+    readonly workflowIds: readonly string[];
+};
+/** `type -> revision -> group`. A legacy entry (no persisted `revision`) groups under the `undefined` key. */
+export type RecoveryRevisionGroups = ReadonlyMap<string, ReadonlyMap<string | undefined, RecoveryRevisionGroup>>;
+/**
+ * Group preflight-recoverable entries by their exact `(type, revision)` pin.
+ * Every non-terminal run pinned to the same revision of the same type lands
+ * in one group, regardless of scan order.
+ */
+export declare function buildRecoveryRevisionGroups(entries: readonly RecoverableRevisionEntry[]): RecoveryRevisionGroups;
+/** Outcome of classifying one `(type, revision)` group. */
+export type RevisionGroupClassification = {
+    readonly status: 'ready';
+} | {
+    readonly status: 'unavailable';
+    readonly error: WorkflowRevisionUnavailableError | DynamicWorkflowSourceUnavailableError;
+};
+/** `type -> revision -> classification`, mirroring {@link RecoveryRevisionGroups}'s shape. */
+export type RevisionGroupClassifications = ReadonlyMap<string, ReadonlyMap<string | undefined, RevisionGroupClassification>>;
+/**
+ * Resolve every `(type, revision)` group to `'ready'` or `'unavailable'`,
+ * concurrently, one `resolveExecutableRegistrationForRevision()` call per
+ * group — even when many non-terminal runs share the same pin. An eager
+ * type's groups are omitted from the result entirely (eager is always
+ * ready and needs no preload call); only dynamic-source groups are
+ * classified. A disposal mid-preload aborts the whole barrier by
+ * rethrowing, matching `recoverEntryOrIsolateFailure`'s own un-isolated
+ * treatment of {@link EngineDisposedError}.
+ */
+export declare function classifyRevisionGroups(internals: EngineInternals, callbacks: LifecycleCallbacks, groups: RecoveryRevisionGroups): Promise<RevisionGroupClassifications>;
+/**
+ * Wrap `callbacks` so `recoverAll()`'s own per-entry `resume()` calls below
+ * see a batch's cached `classifyRevisionGroups()` failure for the entry's
+ * `(type, revision)` group, WITHOUT touching any state shared with other
+ * callers. `classifications` is a plain, closure-local `Map` structure —
+ * nothing outside `recoverAll()` ever sees it, so a concurrent, unrelated
+ * `engine.start()`, `engine.resume()`, or a second concurrent `recoverAll()`
+ * batch for the SAME `(type, revision)` keeps using the real, un-wrapped
+ * `callbacks.resolveExecutableRegistrationForRevision` and can never observe
+ * (or race the reset of) this batch's classification.
+ */
+export declare function createRecoveryScopedRevisionCallbacks(callbacks: LifecycleCallbacks, classifications: RevisionGroupClassifications): LifecycleCallbacks;

package/dist/core/engine/lifecycle/recovery-revision-groups.js

@@ -0,0 +1,64 @@
+import { DynamicWorkflowSourceUnavailableError } from "../dynamic-source-errors.js";
+import { EngineDisposedError } from "../errors.js";
+import { WorkflowRevisionUnavailableError } from "../revision-errors.js";
+export function buildRecoveryRevisionGroups(entries) {
+  const groups = new Map;
+  for (const entry of entries) {
+    let byRevision = groups.get(entry.type);
+    if (byRevision === void 0) {
+      byRevision = new Map;
+      groups.set(entry.type, byRevision);
+    }
+    const existing = byRevision.get(entry.revision);
+    if (existing === void 0)
+      byRevision.set(entry.revision, {
+        type: entry.type,
+        revision: entry.revision,
+        workflowIds: [entry.workflowId]
+      });
+    else
+      existing.workflowIds.push(entry.workflowId);
+  }
+  return groups;
+}
+export async function classifyRevisionGroups(internals, callbacks, groups) {
+  const dynamicGroups = [];
+  for (const [type, byRevision] of groups) {
+    if (internals.registrations.has(type))
+      continue;
+    dynamicGroups.push(...byRevision.values());
+  }
+  const results = new Map;
+  if (dynamicGroups.length === 0)
+    return results;
+  const settled = await Promise.allSettled(dynamicGroups.map((group) => callbacks.resolveExecutableRegistrationForRevision(group.type, group.revision)));
+  for (const [index, outcome] of settled.entries()) {
+    const group = dynamicGroups[index];
+    let byRevision = results.get(group.type);
+    if (byRevision === void 0) {
+      byRevision = new Map;
+      results.set(group.type, byRevision);
+    }
+    if (outcome.status === "fulfilled") {
+      byRevision.set(group.revision, { status: "ready" });
+      continue;
+    }
+    const reason = outcome.reason;
+    if (reason instanceof EngineDisposedError)
+      throw reason;
+    const error = reason instanceof WorkflowRevisionUnavailableError || reason instanceof DynamicWorkflowSourceUnavailableError ? reason : new DynamicWorkflowSourceUnavailableError(group.type, group.revision, "load-failed", reason);
+    byRevision.set(group.revision, { status: "unavailable", error });
+  }
+  return results;
+}
+export function createRecoveryScopedRevisionCallbacks(callbacks, classifications) {
+  return {
+    ...callbacks,
+    resolveExecutableRegistrationForRevision: (type, revision) => {
+      const classification = classifications.get(type)?.get(revision);
+      if (classification?.status === "unavailable")
+        return Promise.reject(classification.error);
+      return callbacks.resolveExecutableRegistrationForRevision(type, revision);
+    }
+  };
+}

package/dist/core/engine/lifecycle/resume-generation-guard.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `resumeWorkflowFromStorage()`'s generation-identity re-check (WFT-19
+ * review round 7, chatgpt-codex-connector + stevekinney) — split out of
+ * `resume.ts`, which has no headroom under the repository's 500-line
+ * implementation-file ceiling for this doc-heavy addition.
+ *
+ * @module core/engine/lifecycle/resume-generation-guard
+ */
+import type { WorkflowState } from '../../types.ts';
+/**
+ * The generation a resume's `registration`/`resumeCheckpoint`/`resolvedRevision`
+ * were all resolved against — captured from the SAME `WorkflowState` decoded
+ * at the very top of `resumeWorkflowFromStorage()`, before
+ * `acquireStandaloneClaimBeforeResume`, the checkpoint load, and registration
+ * resolution all ran.
+ *
+ * `performSerializedResume()` re-reads workflow state fresh inside its
+ * serialized section but (before this guard existed) only re-checked
+ * `status` — never identity. An `onTerminalConflict: 'start-new'`
+ * replacement landing on this SAME `workflowId` between the top-of-function
+ * read and the serialized section's fresh read (e.g. a concurrent
+ * cancel/timeout terminalizes this run, then a fresh `start()` call replaces
+ * it) purges the old record and writes a brand-new one — new
+ * `type`/`revision` possibly, and ALWAYS a fresh `workflowExecutionToken`
+ * (`crypto.randomUUID()`, minted by every `start()` — see
+ * `start-state.ts`'s `buildInitialIdentitySlice`). Without
+ * {@link assertSameGeneration}, the stale `registration`/
+ * `resumeCheckpoint` a resume closure already built would replay against the
+ * replacement's fresh state: `commitSerializedResumeState` populates
+ * `internals.checkpoints` from the OLD checkpoint, and
+ * `relaunchInlineWorkflowAfterResume` drives the OLD handler — silently
+ * corrupting the replacement's run.
+ *
+ * A DIFFERENT engine's replacement is additionally caught earlier, by
+ * `acquireStandaloneClaimBeforeResume`'s durable `wakeOwnershipCheck`
+ * (workflow-lease mode only) — but that check compares only holder
+ * identity/epoch, never workflow identity, so a SAME-engine replacement
+ * (whose fold-acquire updates this engine's own already-held claim in
+ * place, leaving the epoch check trivially satisfied) is not caught there.
+ * This guard closes that gap for every ownership mode, not just
+ * workflow-lease.
+ */
+export type ResumeGeneration = {
+    type: string;
+    revision: string | undefined;
+    workflowExecutionToken: string | undefined;
+};
+/** Captures {@link ResumeGeneration} off the `WorkflowState` a resume decoded at its top, before any `await`. */
+export declare function deriveResumeGeneration(state: WorkflowState): ResumeGeneration;
+/**
+ * Throws when `latestState` — freshly re-read inside `performSerializedResume()`'s
+ * serialized section — no longer belongs to the same generation `expected`
+ * names. See {@link ResumeGeneration}'s doc for the exact race this
+ * closes. All three fields are compared — `workflowExecutionToken` alone
+ * would miss a legacy record that carries `undefined` on both sides of the
+ * race.
+ */
+export declare function assertSameGeneration(workflowId: string, latestState: WorkflowState, expected: ResumeGeneration): void;

package/dist/core/engine/lifecycle/resume-generation-guard.js

@@ -0,0 +1,11 @@
+export function deriveResumeGeneration(state) {
+  return {
+    type: state.type,
+    revision: state.revision,
+    workflowExecutionToken: state.workflowExecutionToken
+  };
+}
+export function assertSameGeneration(workflowId, latestState, expected) {
+  if (latestState.workflowExecutionToken !== expected.workflowExecutionToken || latestState.type !== expected.type || latestState.revision !== expected.revision)
+    throw Error(`Cannot resume workflow "${workflowId}": its persisted state changed generation (a replacement run landed at this same id) between resume's registration lookup ` + "and its serialized commit \u2014 retry against the new generation instead of replaying " + "stale state.");
+}

package/dist/core/engine/lifecycle/resume.js

@@ -8,6 +8,7 @@ import { buildTimerBatchOperations } from "../../scheduler.js";
 import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
 import { rememberCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { rehydrateChildCancellationHandlers } from "../child-workflow-cancellation.js";
+import { resolveExecutableRegistrationOrRenamedNotFound } from "../dynamic-source-execution.js";
 import { commitFencedEngineWrite } from "../fenced-write.js";
 import { getWorkflowExecutionStartedAt } from "../handles.js";
 import { loadWorkflowState } from "../storage-io.js";
@@ -19,6 +20,7 @@ import {
   reprovideRecoveredServices,
   workflowServicesResolverInfoFromState
 } from "./recovered-services.js";
+import { assertSameGeneration, deriveResumeGeneration } from "./resume-generation-guard.js";
 import {
   enforceHistoryPolicyBeforeReplay,
   loadTerminalCleanupTrackedState,
@@ -79,7 +81,11 @@ function commitSerializedResumeState(internals, args) {
   internals.parkedInlineWorkflows.delete(workflowId);
 }
 async function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
-  const { workflowId, resumeCheckpoint, registration, callbacks } = args, accumulatedResults = new Map(resumeCheckpoint.accumulatedResults), workflowAbort = new AbortController;
+  const { workflowId, resumeCheckpoint, registration, resolvedRevision, callbacks } = args, accumulatedResults = new Map(resumeCheckpoint.accumulatedResults), workflowAbort = new AbortController;
+  internals.workflowTypeByWorkflowId.set(workflowId, {
+    type: latestState.type,
+    revision: resolvedRevision
+  });
   resetCancelHandlers(internals, workflowId);
   await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
   const context = new Context({
@@ -115,7 +121,11 @@ async function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
   inlineStrategy.continueWorkflow(workflowId, void 0);
 }
 async function relaunchWorkerWorkflowAfterResume(internals, latestState, args) {
-  const { workflowId, resumeCheckpoint, workflowStartHeaders, callbacks } = args;
+  const { workflowId, resumeCheckpoint, workflowStartHeaders, resolvedRevision, callbacks } = args;
+  internals.workflowTypeByWorkflowId.set(workflowId, {
+    type: latestState.type,
+    revision: resolvedRevision
+  });
   resetCancelHandlers(internals, workflowId);
   await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
   const serialized = serializeCheckpoint(resumeCheckpoint);
@@ -146,6 +156,7 @@ async function performSerializedResume(internals, args) {
     throw Error(`Workflow "${workflowId}" not found in storage`);
   if (latestState.status !== "running" && latestState.status !== "suspended")
     throw Error(`Cannot resume workflow "${workflowId}": status is "${latestState.status}", expected "running" or "suspended"`);
+  assertSameGeneration(workflowId, latestState, args.expectedGeneration);
   await reactivateSuspendedWorkflowState(internals, latestState);
   commitSerializedResumeState(internals, args);
   if (internals.inlineStrategy) {
@@ -179,18 +190,14 @@ export async function resumeWorkflowFromStorage(internals, workflowId, dispatchR
   if (state.status !== "running" && state.status !== "suspended")
     throw Error(`Cannot resume workflow "${workflowId}": status is "${state.status}", expected "running" or "suspended"`);
   await acquireStandaloneClaimBeforeResume(internals, workflowId);
+  await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
   const checkpointBytes = await internals.storage.get(KEYS.checkpoint(workflowId));
   if (!checkpointBytes)
     throw Error(`Checkpoint not found for workflow "${workflowId}"`);
-  const checkpoint = deserializeCheckpoint(checkpointBytes), registration = internals.registrations.get(state.type);
-  if (!registration)
-    throw Error(`No workflow registered with name "${state.type}" (needed to resume "${workflowId}")`);
-  const preparedResumeState = await prepareResumeState(internals, workflowId, state, checkpoint, checkpointBytes, registration, callbacks), resumeCheckpoint = preparedResumeState.checkpoint, registeredVersionTuple = preparedResumeState.versionTuple, restoredHead = await new EventLog(internals.storage, workflowId).loadHead();
+  const checkpoint = deserializeCheckpoint(checkpointBytes), { entry: registration, revision: resolvedRevision } = await resolveExecutableRegistrationOrRenamedNotFound((type) => callbacks.resolveExecutableRegistrationForRevision(type, state.revision), state.type, () => Error(`No workflow registered with name "${state.type}" (needed to resume "${workflowId}")`)), preparedResumeState = await prepareResumeState(internals, workflowId, state, checkpoint, checkpointBytes, registration, callbacks), resumeCheckpoint = preparedResumeState.checkpoint, registeredVersionTuple = preparedResumeState.versionTuple, restoredHead = await new EventLog(internals.storage, workflowId).loadHead();
   if (await enforceHistoryPolicyBeforeReplay(internals, workflowId, restoredHead, callbacks))
     return callbacks.getHandle(workflowId);
-  const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks);
-  await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
-  const { handle, shouldStop } = await prepareRecoveredWorkflowOrFail(internals, state, callbacks, onRecoveredWorkflow);
+  const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks), { handle, shouldStop } = await prepareRecoveredWorkflowOrFail(internals, state, callbacks, onRecoveredWorkflow);
   if (shouldStop)
     return handle;
   await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
@@ -201,6 +208,8 @@ export async function resumeWorkflowFromStorage(internals, workflowId, dispatchR
     restoredHead,
     workflowStartHeaders,
     registration,
+    resolvedRevision,
+    expectedGeneration: deriveResumeGeneration(state),
     callbacks
   }));
   if (dispatchResumedEvent)

package/dist/core/engine/lifecycle/shared.d.ts

@@ -1,5 +1,6 @@
 import type { ComposedWorkflowInterceptor } from '../../interceptor.ts';
 import type { WorkflowServicesResolverLaunchOptions, WorkflowServicesResolverScheduleInfo } from '../../types.ts';
+import type { ExecutableRegistration } from '../dynamic-source-execution.ts';
 import type { QueuedInlineWorkflowExecutionStart } from '../engine-internal-types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
@@ -125,6 +126,48 @@ export type LifecycleCallbacks = {
      * {@link RecoverAllOptions.versionMismatchPolicy}.
      */
     failWorkflowForVersionMismatch: (workflowId: string, error: Error) => Promise<void>;
+    /**
+     * Turn a workflow `type` into an executable registration, awaiting
+     * dynamic-source resolution when `type` is not eagerly registered
+     * (WFT-15/16). See `dynamic-source-execution.ts`'s own doc for the full
+     * contract.
+     *
+     * `onRevisionChosen`, when given, fires synchronously the moment a lazy
+     * `type`'s target revision is picked — BEFORE the (potentially slow)
+     * loader is awaited — so a caller like `startWorkflow` can reserve an
+     * `inFlightStarts` slot for that exact revision immediately, closing the
+     * window where a concurrent `removeWorkflowRevision()` could observe zero
+     * references against a revision this call's own source load is about to
+     * durably (re)install. Never fires for an eager type (no revision to
+     * choose) or when resolution fails before a revision is picked (the
+     * ambiguous-revision case).
+     */
+    resolveExecutableRegistration: (type: string, onRevisionChosen?: (revision: string) => void) => Promise<ExecutableRegistration>;
+    /**
+     * Force a recovered workflow to a terminal `failed` state because its
+     * dynamic workflow source could not be resolved during the recovery
+     * preload barrier — only this run fails; `recoverAll()` continues
+     * recovering sibling types.
+     */
+    failWorkflowForUnavailableDynamicSource: (workflowId: string, error: Error) => Promise<void>;
+    /**
+     * Resolve workflow `type` against its EXACT pinned revision (WFT-17's
+     * `WorkflowState.revision`, `undefined` for a legacy pre-pinning record)
+     * instead of whichever revision the catalog currently considers active.
+     * Used by every resume path (`resumeWorkflowFromStorage`) so a pinned run
+     * never falls back to the active pointer. See
+     * `dynamic-source-execution.ts`'s `resolveExecutableRegistrationForRevision()`
+     * for the full classification contract.
+     */
+    resolveExecutableRegistrationForRevision: (type: string, revision: string | undefined) => Promise<ExecutableRegistration>;
+    /**
+     * Force a recovered workflow to a terminal `failed` state because its
+     * pinned revision could not be resolved during the recovery preload
+     * barrier (WFT-18) — a {@link import('../revision-errors.ts').WorkflowRevisionUnavailableError}.
+     * Only this run fails; `recoverAll()` continues recovering sibling
+     * `(type, revision)` groups, including other revisions of the same type.
+     */
+    failWorkflowForRevisionUnavailable: (workflowId: string, error: Error) => Promise<void>;
 };
 /**
  * Pre-replay history circuit breaker. Called at every restore-from-checkpoint

package/dist/core/engine/lifecycle/standalone-claim-acquire.d.ts

@@ -31,3 +31,15 @@
  */
 import type { EngineInternals } from '../internals.ts';
 export declare function acquireStandaloneClaimBeforeResume(internals: EngineInternals, workflowId: string): Promise<void>;
+/**
+ * Standalone-acquire `workflowId`'s claim (see {@link acquireStandaloneClaimBeforeResume},
+ * a no-op once already held) and hydrate its terminal-cleanup tracking from
+ * the durable marker — the two preconditions a `'self'`-fenced `failWorkflow()`
+ * write needs. Used by `operations-time.ts`'s `startDelayedWorkflow` on every
+ * failure exit (dynamic-source resolve, invalid execution-timeout) BEFORE
+ * failing: a delayed-start's pending→running write is the only other place
+ * this claim would otherwise get acquired (folded atomically, per ADR 0002),
+ * so a failure committed ahead of that write needs this standalone path
+ * instead, exactly like a recovered `running`/`suspended` workflow does.
+ */
+export declare function ensureDelayedStartClaimAndCleanupBeforeFailure(internals: EngineInternals, workflowId: string): Promise<void>;

package/dist/core/engine/lifecycle/standalone-claim-acquire.js

@@ -1,3 +1,4 @@
+import { KEYS, storageHas } from "../../../storage/interface.js";
 import { WorkflowClaimUnavailableError } from "../lease-errors.js";
 import { wakeOwnershipCheck } from "../wake-ownership-check.js";
 export async function acquireStandaloneClaimBeforeResume(internals, workflowId) {
@@ -23,3 +24,8 @@ export async function acquireStandaloneClaimBeforeResume(internals, workflowId)
   if (result.status === "lost-race")
     throw new WorkflowClaimUnavailableError(workflowId, result.heldBy);
 }
+export async function ensureDelayedStartClaimAndCleanupBeforeFailure(internals, workflowId) {
+  await acquireStandaloneClaimBeforeResume(internals, workflowId);
+  if (await storageHas(internals.storage, KEYS.terminalCleanupNeeded(workflowId)))
+    internals.workflowsNeedingTerminalCleanup.add(workflowId);
+}

package/dist/core/engine/lifecycle/start-commit-errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal sentinel: the idempotent create batch lost its compare-and-swap to a
+ * concurrent caller holding the same idempotency key. Never surfaced to users —
+ * `start` / `startOrSignal` catch it and resolve to the winning run's handle.
+ *
+ * Lives in its own module so both `start-commit.ts` and the attribution helper it
+ * delegates to (`start-precondition-attribution.ts`) can raise it without an import
+ * cycle between them.
+ */
+export declare class StartIdempotencyRaceLostError extends Error {
+    constructor();
+}

package/dist/core/engine/lifecycle/start-commit-errors.js

@@ -0,0 +1,6 @@
+export class StartIdempotencyRaceLostError extends Error {
+  constructor() {
+    super("start idempotency compare-and-swap lost to a concurrent caller");
+    this.name = "StartIdempotencyRaceLostError";
+  }
+}

package/dist/core/engine/lifecycle/start-commit.d.ts

@@ -1,4 +1,4 @@
-import type { BatchOperation, ConditionalBatchCondition } from '../../../storage/interface.ts';
+import { type BatchOperation, type ConditionalBatchCondition } from '../../../storage/interface.ts';
 import type { Checkpoint, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
 import type { WorkflowConcurrencyStartOperations } from '../workflow-concurrency.ts';
@@ -17,13 +17,19 @@ export type BuildIdempotentStartOperations = (workflowId: string) => {
     conditions: ConditionalBatchCondition[];
 };
 /**
- * Internal sentinel: the idempotent create batch lost its compare-and-swap to a
- * concurrent caller holding the same idempotency key. Never surfaced to users —
- * `start` / `startOrSignal` catch it and resolve to the winning run's handle.
+ * The `conditionalBatch` precondition half of {@link buildCatalogEntryStartPrecondition}
+ * — a bare `type`/`revision` pair rather than a full `WorkflowState`, so it
+ * is also reusable by a checkpoint-backed failed-run retry's reactivation
+ * commit (`bulk-operations-retry.ts`, WFT-17/18 Codex review on PR #958),
+ * which has no `WorkflowState & { revision: string }` narrowing of its own
+ * and — unlike a fresh start — carries no `inFlightStartsByRevision`
+ * reservation to close the SAME-process half of this race, so it needs this
+ * fence unconditionally rather than only under `ownershipMode !== 'none'`.
+ * Exported (rather than kept local to this module) specifically for that
+ * reuse; returns the bare {@link ConditionalBatchCondition} so callers never
+ * need this module's own non-exported {@link TaggedStartCondition} shape.
  */
-export declare class StartIdempotencyRaceLostError extends Error {
-    constructor();
-}
+export declare function buildCatalogEntryRevisionCondition(internals: EngineInternals, type: string, revision: string): Promise<ConditionalBatchCondition>;
 /** Everything {@link buildAndCommitStartBatch} needs to assemble the start batch. */
 export type StartBatchContext = {
     internals: EngineInternals;
@@ -44,6 +50,15 @@ export type StartBatchContext = {
      * {@link buildStartBatchOperations}). Undefined for an ordinary start.
      */
     purgeDeleteOperations: BatchOperation[] | undefined;
+    /**
+     * Compare-and-swap precondition making the caller-supplied-id duplicate check
+     * atomic with this commit (WFT-152). Built by `resolveTerminalConflictForRestart`
+     * from the exact bytes its duplicate-id read observed, and carried here as the
+     * `duplicateIdCondition` of the `StartDuplicateIdDecision` it returns. Undefined
+     * for a generated id, which cannot collide and so keeps the unconditioned hot
+     * path.
+     */
+    duplicateIdCondition: ConditionalBatchCondition | undefined;
 };
 /**
  * Assemble the start batch — folding in the id-dependent idempotency mapping and