@lostgradient/weft 0.24.0 → 0.24.2

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

@@ -1,13 +1,60 @@
 import type { BatchOperation } from '../../../storage/interface.ts';
-import type { Checkpoint, Duration, StartOptions, StartWorkflowOptions, TimerEntry, WorkflowState } from '../../types.ts';
-import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import type { StartWorkflowOptions } from '../../types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
 import { type BuildIdempotentStartOperations } from './start-commit.ts';
 export declare function start(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
-export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations): Promise<WorkflowHandle>;
-export declare function resolveScheduledStartAt(internals: EngineInternals, options: StartOptions | undefined, submissionTime: number, callbacks: LifecycleCallbacks): number | undefined;
-export declare function parseStartOptionDuration(_internals: EngineInternals, duration: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter', _callbacks: LifecycleCallbacks): number;
-export declare function createInitialWorkflowState(internals: EngineInternals, workflowId: string, type: string, input: unknown, versionTuple: WorkflowVersionTuple, options: StartOptions | undefined, tags: string[] | undefined, executionStateOwnerId: string | undefined, parentWorkflowId: string | undefined, parentWorkflowExecutionToken: string | undefined, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
-export declare function createInitialCheckpoint(internals: EngineInternals, workflowId: string, workflowVersion: string, options: StartOptions | undefined, _callbacks: LifecycleCallbacks): Checkpoint;
+export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations, 
+/**
+ * A pinned schedule's forward-looking revision commitment (WFT-20),
+ * threaded from `ScheduleCallbacks.startWorkflow`'s own `revisionOverride`
+ * parameter. When supplied, this call resolves and reserves EXACTLY this
+ * revision (via {@link resolveAndReservePinnedExecutableRegistration},
+ * which enforces an exact-match check for an eager type rather than
+ * silently falling back to whatever is active) instead of the ordinary
+ * "whatever `resolveExecutableRegistration` currently resolves"
+ * admission path, and the persisted `WorkflowState.revision` is this
+ * value verbatim — never re-derived from `registeredCatalogRevisions`.
+ * `undefined` (the default, every non-schedule start) is byte-for-byte
+ * the pre-WFT-20 admission path.
+ */
+revisionOverride?: string, 
+/**
+ * Internal-only, never part of the public `StartOptions` type (WFT-95).
+ * When truthy, `options.id` skips strict fresh-admission validation
+ * (`assertValidWorkflowId`'s `.`/`..` rejection) and is instead validated
+ * with the decode-compatible `assertDecodableWorkflowId`. This exists
+ * ONLY to replay an id that was already durably accepted before strict
+ * admission existed — never to let a genuinely fresh caller admit `.`/`..`.
+ *
+ * Set from exactly three internal call sites, all replaying an
+ * already-persisted id rather than admitting a new one:
+ *   - `drainQueuedScheduleRun()` (via `ScheduledRunStartOptions.skipAdmissionIdCheck`,
+ *     threaded through `startScheduledRun()`), which restarts a schedule's
+ *     persisted `queuedRuns[].workflowId` — safe unconditionally (`true`),
+ *     since a queued run created after this fix was already validated as
+ *     non-`.`/`..` at schedule-admission time, so relaxing the check here
+ *     is a no-op for it and only matters for a historical pre-WFT-95 queued run.
+ *   - `retryFailedWorkflow()`'s checkpoint-absent fallback (`bulk-operations-retry.ts`),
+ *     which rebuilds an already-persisted, already-validated-at-the-time
+ *     `workflowId` from its stored input via `onTerminalConflict: 'start-new'`.
+ *     Passes the literal `'bulk-retry-only'` rather than `true` — see
+ *     {@link enforceReplayOnlyIdFence}'s doc comment for the TOCTOU race that
+ *     value fences: the retry's own confirmation read and
+ *     `resolveTerminalConflictForRestart`'s atomic read are not the same
+ *     read, so a concurrent purge under `ownership: 'workflow-lease'` can
+ *     leave nothing to purge-and-replace by the time this runs.
+ *   - `dispatchChildWorkflowStart()`'s crash-reattach retry, which passes
+ *     the literal `'reattach-only'` rather than `true` — see
+ *     {@link enforceReplayOnlyIdFence}'s doc comment for the same TOCTOU
+ *     race (this one only *speculatively* matched an existing record
+ *     before this call, unlike the schedule-drain site above).
+ *
+ * Every other caller (REST, JSON-RPC, direct `engine.start()`,
+ * `engine.startOrSignal()`, a fresh `ctx.startChild()`) omits this
+ * parameter and gets the strict check, because it is not part of
+ * `StartOptions`/`StartWorkflowOptions` and therefore cannot be set from
+ * any public surface.
+ */
+skipAdmissionIdCheck?: boolean | 'reattach-only' | 'bulk-retry-only'): Promise<WorkflowHandle>;

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

@@ -1,18 +1,17 @@
-import { createCheckpoint } from "../../checkpoint.js";
 import { assertPayloadWithinLimit } from "../../payload-size.js";
-import { normalizeStorageTimestamp } from "../../scheduler.js";
 import {
-  StartWorkflowValidationError,
-  assertExclusiveStartWorkflowOptions,
   assertValidOnTerminalConflict,
-  coerceStartWorkflowId,
-  coerceStartWorkflowTimestamp,
-  parseStartWorkflowDuration
+  coerceReplayWorkflowId,
+  coerceStartWorkflowId
 } from "../../start-workflow-validation.js";
-import { releaseInFlightStart, reserveInFlightStart } from "../catalog-removal.js";
+import {
+  releaseInFlightStart,
+  resolveAndReserveExecutableRegistration
+} from "../catalog-removal.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
-import { WorkflowAlreadyExistsError, WorkflowNotRegisteredError } from "../errors.js";
+import { WorkflowAlreadyExistsError } from "../errors.js";
 import { createDelayedStartTimerEntry } from "../operations-time.js";
+import { resolveAndReservePinnedExecutableRegistration } from "../pinned-schedule-revision.js";
 import { selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
 import { buildWorkflowConcurrencyStartOperations } from "../workflow-concurrency.js";
 import { createWorkflowVersionTuple } from "./persist.js";
@@ -28,14 +27,27 @@ import {
   runWorkflowStartInterceptor
 } from "./start-exec.js";
 import {
+  resolveCachedStartRevision,
+  resolveStartRevisionUncached
+} from "./start-revision-resolution.js";
+import { resolveScheduledStartAt } from "./start-schedule-timing.js";
+import {
+  applyRestartLineage,
+  createInitialCheckpoint,
+  createInitialWorkflowState,
+  parseStartOptionDuration
+} from "./start-state.js";
+import {
+  enforceReplayOnlyIdFence,
+  GENERATED_ID_START_DECISION,
   prepareTerminalRunPurge,
   resolveTerminalConflictForRestart
 } from "./start-terminal-conflict-purge.js";
 export async function start(internals, type, input, options, callbacks) {
   return startWorkflow(internals, type, input, options, void 0, callbacks);
 }
-function prepareStartWorkflow(internals, options, callbacks) {
-  const callerProvidedId = options?.id !== void 0, workflowId = options?.id !== void 0 ? coerceStartWorkflowId(options.id, "options.id") : crypto.randomUUID(), parentHeaders = internals.pendingParentHeaders;
+function prepareStartWorkflow(internals, options, callbacks, skipAdmissionIdCheck) {
+  const callerProvidedId = options?.id !== void 0, workflowId = options?.id !== void 0 ? skipAdmissionIdCheck ? coerceReplayWorkflowId(options.id, "options.id") : coerceStartWorkflowId(options.id, "options.id") : crypto.randomUUID(), parentHeaders = internals.pendingParentHeaders;
   internals.pendingParentHeaders = void 0;
   const pendingExecutionStateOwnerId = internals.pendingExecutionStateOwnerId, executionStateOwnerId = pendingExecutionStateOwnerId === null ? void 0 : pendingExecutionStateOwnerId ?? workflowId;
   internals.pendingExecutionStateOwnerId = void 0;
@@ -70,14 +82,19 @@ function assertServicesSupportedForMode(internals, options) {
   if (options?.services !== void 0 && internals.inlineStrategy === null)
     throw Error('options.services is only supported in inline execution mode; it cannot be serialized to a Worker. Remove services or use workflowExecutionMode: "inline".');
 }
-export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks, buildIdempotentStartOperations) {
-  const registration = internals.registrations.get(type);
-  if (!registration)
-    throw new WorkflowNotRegisteredError(type);
-  const workflowConcurrency = registration.concurrency;
+function resolveAndReserveStartRegistration(internals, type, revisionOverride, callbacks) {
+  if (revisionOverride === void 0)
+    return resolveAndReserveExecutableRegistration(internals, type, callbacks.resolveExecutableRegistration);
+  return resolveAndReservePinnedExecutableRegistration(internals.engine, internals, type, revisionOverride).then(({ registration, inFlightRevision }) => ({
+    registration,
+    inFlightRevision,
+    resolvedRevision: revisionOverride
+  }));
+}
+export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks, buildIdempotentStartOperations, revisionOverride, skipAdmissionIdCheck) {
   assertServicesSupportedForMode(internals, options);
   assertValidOnTerminalConflict(options);
-  const preparation = prepareStartWorkflow(internals, options, callbacks), {
+  const preparation = prepareStartWorkflow(internals, options, callbacks, Boolean(skipAdmissionIdCheck)), {
     workflowId,
     callerProvidedId,
     parentHeaders,
@@ -90,14 +107,25 @@ export async function startWorkflow(internals, type, input, options, additionalS
   if (internals.pendingStarts.has(workflowId))
     throw new WorkflowAlreadyExistsError(workflowId);
   internals.pendingStarts.add(workflowId);
-  let startSucceeded = !1;
-  const inFlightRevision = reserveInFlightStart(internals, type);
+  let startSucceeded = !1, inFlightRevision;
   try {
-    const terminalRunToPurge = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : null;
     assertPayloadWithinLimit(input, internals.options.payloadSizePolicy.maxBytes, "workflow input");
-    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, preparation.normalizedTags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks);
+    const {
+      registration,
+      inFlightRevision: reservedRevision,
+      resolvedRevision
+    } = await resolveAndReserveStartRegistration(internals, type, revisionOverride, callbacks);
+    inFlightRevision = reservedRevision;
+    const workflowConcurrency = registration.concurrency, revision = resolveCachedStartRevision(internals, type, resolvedRevision) ?? await resolveStartRevisionUncached(internals, type), {
+      terminalRunToPurge,
+      duplicateIdCondition,
+      duplicateIdGenerationCondition,
+      observedGenerationBytes
+    } = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : GENERATED_ID_START_DECISION;
+    enforceReplayOnlyIdFence(skipAdmissionIdCheck, workflowId, terminalRunToPurge);
+    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, revision, options, preparation.normalizedTags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks);
     applyRestartLineage(state, terminalRunToPurge);
-    const checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks) : void 0;
+    const checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks, observedGenerationBytes) : void 0;
     internals.checkpoints.set(workflowId, checkpoint);
     setWorkflowStartHeaders(internals, workflowId, workflowStartHeaders, callbacks);
     internals.workflowVersionTuples.set(workflowId, versionTuple);
@@ -113,7 +141,9 @@ export async function startWorkflow(internals, type, input, options, additionalS
       additionalStartOperations,
       buildWorkflowConcurrencyStartOperations: workflowConcurrency === void 0 ? void 0 : () => buildWorkflowConcurrencyStartOperations(internals, type, workflowId, input, workflowConcurrency),
       callbacks,
-      purgeDeleteOperations
+      purgeDeleteOperations,
+      duplicateIdCondition,
+      duplicateIdGenerationCondition
     }, buildIdempotentStartOperations);
     if (options?.services !== void 0) {
       internals.workflowServices.set(workflowId, options.services);
@@ -140,70 +170,3 @@ export async function startWorkflow(internals, type, input, options, additionalS
       rollbackTransientStartState(internals, workflowId);
   }
 }
-function applyRestartLineage(state, displacedState) {
-  if (displacedState === null)
-    return;
-  state.restartedFrom = {
-    workflowId: displacedState.id,
-    ...displacedState.workflowExecutionToken !== void 0 && {
-      workflowExecutionToken: displacedState.workflowExecutionToken
-    },
-    replacedAt: state.createdAt
-  };
-}
-export function resolveScheduledStartAt(internals, options, submissionTime, callbacks) {
-  assertExclusiveStartWorkflowOptions(options?.startAt, options?.startAfter);
-  if (options?.startAt !== void 0)
-    return coerceStartWorkflowTimestamp(options.startAt, "options.startAt");
-  if (options?.startAfter !== void 0) {
-    const startAfterMilliseconds = parseStartOptionDuration(internals, options.startAfter, "options.startAfter", callbacks);
-    try {
-      return normalizeStorageTimestamp(submissionTime + startAfterMilliseconds, "options.startAfter");
-    } catch {
-      throw new StartWorkflowValidationError("options.startAfter must resolve to a finite, non-negative start time");
-    }
-  }
-  return;
-}
-export function parseStartOptionDuration(_internals, duration, fieldName, _callbacks) {
-  return parseStartWorkflowDuration(duration, fieldName);
-}
-function buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags) {
-  return {
-    id: workflowId,
-    type,
-    status: delayedStartTimer ? "pending" : "running",
-    input,
-    versionTuple,
-    workflowExecutionToken: crypto.randomUUID(),
-    ...executionStateOwnerId !== void 0 && { executionStateOwnerId },
-    ...parentWorkflowId !== void 0 && { parentWorkflowId },
-    ...parentWorkflowExecutionToken !== void 0 && { parentWorkflowExecutionToken },
-    createdAt: now,
-    ...!delayedStartTimer && { startedAt: now },
-    updatedAt: now,
-    ...tags !== void 0 && { tags }
-  };
-}
-function resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks) {
-  if (options?.executionTimeout === void 0 || delayedStartTimer)
-    return;
-  const executionTimeoutMilliseconds = parseStartOptionDuration(internals, options.executionTimeout, "options.executionTimeout", callbacks);
-  try {
-    return normalizeStorageTimestamp(now + executionTimeoutMilliseconds, "options.executionTimeout");
-  } catch {
-    throw new StartWorkflowValidationError("options.executionTimeout must resolve to a finite, non-negative deadline");
-  }
-}
-export function createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, tags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks) {
-  const now = internals.options.getNow(), state = buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags), executionDeadline = resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks);
-  if (executionDeadline !== void 0)
-    state.executionDeadline = executionDeadline;
-  return state;
-}
-export function createInitialCheckpoint(internals, workflowId, workflowVersion, options, _callbacks) {
-  const checkpoint = createCheckpoint(workflowId, workflowVersion, internals.options.getNow());
-  if (options?.searchAttributes)
-    checkpoint.searchAttributes = { ...options.searchAttributes };
-  return checkpoint;
-}

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

@@ -1,7 +1,8 @@
-import type { Checkpoint, ForkOptions, WorkflowState } from '../../types.ts';
-import { type WorkflowHandle } from '../handles.ts';
+import type { ForkOptions } from '../../types.ts';
+import type { WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
-import { type LifecycleCallbacks, type RecoverAllOptions, type RegistrationEntry } from './shared.ts';
+import { type FreshResumeClaimTracker } from './resume.ts';
+import { type LifecycleCallbacks, type RecoverAllOptions } from './shared.ts';
 export declare function recoverAll(internals: EngineInternals, callbacks: LifecycleCallbacks, options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
 /** Options for {@link resume}. */
 export type ResumeOptions = {
@@ -16,7 +17,14 @@ export type ResumeOptions = {
      * `engine.resume()` leaves it `false` — nothing was deposed there.
      */
     readonly forceReplayFromStorage?: boolean;
+    /**
+     * Forwarded to `resumeWorkflowFromStorage()`'s matching options — see
+     * `ResumeFromStorageOptions` (WFT-134 issue D). Set by
+     * `recoverEntryOrIsolateFailure` only; unset for the local-ownership fast
+     * path above, which never reaches that function.
+     */
+    readonly deferClaimReleaseOnRejection?: boolean;
+    readonly freshClaimTracker?: FreshResumeClaimTracker;
 };
 export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow'], options?: ResumeOptions): Promise<WorkflowHandle>;
 export declare function fork(internals: EngineInternals, sourceWorkflowId: string, options: ForkOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
-export declare function launchWorkflowFromCheckpoint(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, callbacks: LifecycleCallbacks): WorkflowHandle;

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

@@ -1,35 +1,36 @@
 import { KEYS } from "../../../storage/interface.js";
 import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
-import { RegExpExtensionDecodeError } from "../../codec/extension-codec.js";
-import { Context, setContextWorkflowInterceptor } from "../../context.js";
 import { EMPTY_EVENT_HEAD } from "../../event-log.js";
-import { WorkflowRecoverySkippedEvent, WorkflowStartedEvent } from "../../events.js";
-import { VersionMismatchError } from "../../versioning.js";
-import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
+import { WorkflowRecoverySkippedEvent } from "../../events.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { hydrateCheckpointReplayState } from "../checkpoint-replay.js";
+import { resolveExecutableRegistrationOrRenamedNotFound } from "../dynamic-source-execution.js";
 import { WorkflowTypeNotRegisteredForRecoveryError } from "../errors.js";
 import { commitFencedEngineWrite } from "../fenced-write.js";
-import { getWorkflowExecutionStartedAt } from "../handles.js";
-import { WorkflowClaimUnavailableError } from "../lease-errors.js";
 import { normalizeForkStep, selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
 import { loadWorkflowState } from "../storage-io.js";
-import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
 import { decodeWorkflowState } from "../validation.js";
+import { launchWorkflowFromCheckpoint } from "./checkpoint-launch.js";
 import {
   buildForkBatchOperations,
   buildForkSearchAttributes,
   createForkLineage,
   createForkedWorkflowState
 } from "./fork-helpers.js";
-import { createWorkflowVersionTuple, derivePreparedExecutionState } from "./persist.js";
+import { derivePreparedExecutionState } from "./persist.js";
+import { isolateRecoveryFailure } from "./recovery-isolation.js";
+import {
+  buildRecoveryRevisionGroups,
+  classifyRevisionGroups,
+  createRecoveryScopedRevisionCallbacks
+} from "./recovery-revision-groups.js";
 import { resumeWorkflowFromStorage } from "./resume.js";
 import {
-  createWorkflowHandle,
   enforceHistoryPolicyBeforeReplayById,
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
 } from "./shared.js";
+import { releaseFreshlyAcquiredResumeClaim } from "./standalone-claim-acquire.js";
 function isWorkflowSideRecordKey(key) {
   return key.includes(":ckpt") || key.includes(":offload") || key.includes(":archive") || key.includes(":timeline:");
 }
@@ -39,9 +40,9 @@ function classifyRecoveryState(internals, callbacks, state) {
     return { kind: "local", workflowId: state.id };
   if (state.status !== "running")
     return { kind: "ignored" };
-  if (!internals.registrations.has(state.type))
+  if (!internals.registrations.has(state.type) && !internals.sources.byName.has(state.type))
     return { kind: "missing", workflow: { type: state.type, workflowId: state.id } };
-  return { kind: "recoverable", workflowId: state.id };
+  return { kind: "recoverable", workflowId: state.id, type: state.type, revision: state.revision };
 }
 function appendRecoveryClassification(result, classification) {
   if (classification.kind === "ignored")
@@ -63,29 +64,32 @@ async function preflightRecoverAll(internals, callbacks) {
   return result;
 }
 async function recoverEntryOrIsolateFailure(internals, workflowId, callbacks, options) {
+  const freshClaimTracker = { epoch: null };
   try {
-    return await resume(internals, workflowId, callbacks, options?.onRecoveredWorkflow);
+    return await resume(internals, workflowId, callbacks, options?.onRecoveredWorkflow, {
+      deferClaimReleaseOnRejection: !0,
+      freshClaimTracker
+    });
   } catch (error) {
-    if (error instanceof RegExpExtensionDecodeError) {
-      await callbacks.failWorkflowForCheckpointDecodeError(workflowId, error);
-      return null;
-    }
-    if (error instanceof VersionMismatchError && options?.versionMismatchPolicy !== "throw") {
-      await callbacks.failWorkflowForVersionMismatch(workflowId, error);
-      return null;
+    try {
+      return await isolateRecoveryFailure(workflowId, callbacks, options, error);
+    } finally {
+      if (freshClaimTracker.epoch !== null)
+        await releaseFreshlyAcquiredResumeClaim(internals, workflowId, freshClaimTracker.epoch);
     }
-    if (error instanceof WorkflowClaimUnavailableError)
-      return null;
-    throw error;
   }
 }
 export async function recoverAll(internals, callbacks, options) {
   const preflight = await preflightRecoverAll(internals, callbacks), handles = [];
   if (preflight.missingWorkflows.length > 0 && options?.acknowledgeUnknownWorkflowTypes !== !0)
     throw new WorkflowTypeNotRegisteredForRecoveryError({
-      registeredTypes: internals.registrations.keys(),
+      registeredTypes: new Set([
+        ...internals.registrations.keys(),
+        ...internals.sources.byName.keys()
+      ]),
       missingWorkflows: preflight.missingWorkflows
     });
+  const recoverableEntries = preflight.entries.filter((entry) => entry.kind === "recoverable"), revisionGroups = buildRecoveryRevisionGroups(recoverableEntries), revisionClassifications = await classifyRevisionGroups(internals, callbacks, revisionGroups), recoveryScopedCallbacks = createRecoveryScopedRevisionCallbacks(callbacks, revisionClassifications);
   for (const entry of preflight.entries) {
     if (entry.kind === "local") {
       handles.push(callbacks.getHandle(entry.workflowId));
@@ -95,7 +99,7 @@ export async function recoverAll(internals, callbacks, options) {
       callbacks.dispatchEvent(new WorkflowRecoverySkippedEvent(entry.workflow.workflowId, entry.workflow.type, "type-not-registered"));
       continue;
     }
-    const handle = await recoverEntryOrIsolateFailure(internals, entry.workflowId, callbacks, options);
+    const handle = await recoverEntryOrIsolateFailure(internals, entry.workflowId, recoveryScopedCallbacks, options);
     if (handle !== null)
       handles.push(handle);
   }
@@ -109,16 +113,20 @@ export async function resume(internals, workflowId, callbacks, onRecoveredWorkfl
       return callbacks.getHandle(workflowId);
     }
   }
-  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks, onRecoveredWorkflow);
+  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks, onRecoveredWorkflow, {
+    ...options?.deferClaimReleaseOnRejection !== void 0 && {
+      deferClaimReleaseOnRejection: options.deferClaimReleaseOnRejection
+    },
+    ...options?.freshClaimTracker !== void 0 && {
+      freshClaimTracker: options.freshClaimTracker
+    }
+  });
 }
 export async function fork(internals, sourceWorkflowId, options, callbacks) {
   const sourceState = await loadWorkflowState(internals, sourceWorkflowId);
   if (!sourceState)
     throw Error(`Workflow "${sourceWorkflowId}" not found`);
-  const registration = internals.registrations.get(sourceState.type);
-  if (!registration)
-    throw Error(`No workflow registered with name "${sourceState.type}" (needed to fork "${sourceWorkflowId}")`);
-  const fromStep = options?.fromStep !== void 0 ? normalizeForkStep(options.fromStep) : void 0, checkpointKey = fromStep !== void 0 ? KEYS.checkpointHistory(sourceWorkflowId, fromStep) : KEYS.checkpoint(sourceWorkflowId), checkpointBytes = await internals.storage.get(checkpointKey);
+  const { entry: registration, revision: resolvedRevision } = await resolveExecutableRegistrationOrRenamedNotFound((type) => callbacks.resolveExecutableRegistrationForRevision(type, sourceState.revision), sourceState.type, () => Error(`No workflow registered with name "${sourceState.type}" (needed to fork "${sourceWorkflowId}")`)), fromStep = options?.fromStep !== void 0 ? normalizeForkStep(options.fromStep) : void 0, checkpointKey = fromStep !== void 0 ? KEYS.checkpointHistory(sourceWorkflowId, fromStep) : KEYS.checkpoint(sourceWorkflowId), checkpointBytes = await internals.storage.get(checkpointKey);
   if (!checkpointBytes) {
     if (fromStep !== void 0)
       throw Error(`Checkpoint not found at step ${String(fromStep)} for workflow "${sourceWorkflowId}"`);
@@ -129,14 +137,14 @@ export async function fork(internals, sourceWorkflowId, options, callbacks) {
     createdAt: forkedAt,
     workflowId,
     searchAttributes: buildForkSearchAttributes(internals, preparedExecutionState.checkpoint, lineage, callbacks)
-  }, forkState = createForkedWorkflowState(internals, workflowId, preparedExecutionState.state, preparedExecutionState.versionTuple, lineage, forkedAt, callbacks);
+  }, forkState = createForkedWorkflowState(internals, workflowId, preparedExecutionState.state, preparedExecutionState.versionTuple, lineage, forkedAt, callbacks, resolvedRevision);
   let forkStarted = !1;
   try {
     const forkCheckpointBytes = serializeCheckpoint(forkCheckpoint);
     await commitFencedEngineWrite(internals, workflowId, buildForkBatchOperations(internals, workflowId, forkState, forkCheckpoint, forkCheckpointBytes, persistedWorkflowStartHeaders, callbacks), [], () => Error(`Fork of workflow "${workflowId}" lost its CAS race.`));
     internals.eventLogHeads.set(workflowId, EMPTY_EVENT_HEAD);
     setWorkflowStartHeaders(internals, workflowId, persistedWorkflowStartHeaders, callbacks);
-    const handle = launchWorkflowFromCheckpoint(internals, workflowId, forkState, forkCheckpoint, registration, callbacks);
+    const handle = launchWorkflowFromCheckpoint(internals, workflowId, forkState, forkCheckpoint, registration, resolvedRevision, callbacks);
     forkStarted = !0;
     return handle;
   } finally {
@@ -149,66 +157,3 @@ export async function fork(internals, sourceWorkflowId, options, callbacks) {
     }
   }
 }
-function launchInlineWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks) {
-  const inlineStrategy = internals.inlineStrategy;
-  if (!inlineStrategy)
-    throw Error("Inline workflow launch requested without an inline strategy.");
-  const accumulatedResults = new Map(checkpoint.accumulatedResults), workflowAbort = new AbortController;
-  resetCancelHandlers(internals, workflowId);
-  const context = new Context({
-    workflowId,
-    ...state.workflowExecutionToken !== void 0 && {
-      workflowExecutionToken: state.workflowExecutionToken
-    },
-    workflowType: state.type,
-    startedAt: getWorkflowExecutionStartedAt(state),
-    abortController: workflowAbort,
-    getNow: internals.options.getNow,
-    resolveWorkflowType: callbacks.resolveWorkflowTypeTarget,
-    executionStateOwnerId: state.executionStateOwnerId ?? workflowId,
-    accumulatedResults,
-    searchAttributes: checkpoint.searchAttributes,
-    registerCancelHandler: createCancelHandlerRegistration(internals, workflowId),
-    ...registration.searchAttributes && {
-      searchAttributeSchema: registration.searchAttributes
-    },
-    sleepReferenceTime: checkpoint.createdAt,
-    ...state.executionDeadline !== void 0 && { deadline: state.executionDeadline },
-    ...internals.options.onLog != null && { logSink: internals.options.onLog }
-  });
-  setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
-  if (internals.options.development)
-    context.explain(!0);
-  const generator = registration.handler(context, state.input);
-  inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
-  inlineStrategy.continueWorkflow(workflowId, void 0);
-  callbacks.swallowPromiseRejection(callbacks.processPendingUpdatesAfterInlineAdvance(workflowId));
-}
-function launchWorkerWorkflowFromCheckpoint(internals, workflowId, state, checkpoint) {
-  const serialized = serializeCheckpoint(checkpoint);
-  internals.strategy.startWorkflow({
-    workflowId,
-    ...state.workflowExecutionToken !== void 0 && {
-      workflowExecutionToken: state.workflowExecutionToken
-    },
-    workflowType: state.type,
-    input: state.input,
-    checkpoint: serialized,
-    executionStateOwnerId: state.executionStateOwnerId ?? workflowId,
-    ...state.executionDeadline !== void 0 && { deadline: state.executionDeadline },
-    ...internals.workflowHeaders.has(workflowId) && {
-      headers: [...internals.workflowHeaders.get(workflowId)]
-    }
-  });
-}
-export function launchWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks) {
-  internals.checkpoints.set(workflowId, checkpoint);
-  internals.workflowVersionTuples.set(workflowId, createWorkflowVersionTuple(internals, registration, callbacks));
-  const handle = createWorkflowHandle(internals, workflowId, callbacks);
-  callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, state.type, state.input));
-  if (internals.inlineStrategy)
-    launchInlineWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks);
-  else
-    launchWorkerWorkflowFromCheckpoint(internals, workflowId, state, checkpoint);
-  return handle;
-}

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

@@ -1,9 +1,12 @@
 export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, type RecoveredWorkflowInfo, } from './lifecycle/shared.ts';
 export { createWorkflowVersionTuple, derivePreparedExecutionState, prepareResumeState, throwVersionMismatch, workflowStateWithVersionTuple, workflowVersionTupleFromState, } from './lifecycle/persist.ts';
-export { createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
+export { resolveScheduledStartAt } from './lifecycle/start-schedule-timing.ts';
+export { start, startWorkflow } from './lifecycle/start.ts';
+export { applyRestartLineage, createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, } from './lifecycle/start-state.ts';
 export { startOrSignal, startWithIdempotency, type StartOrSignalCallbacks, type StartOrSignalResult, } from './lifecycle/start-or-signal.ts';
 export { buildInitialSearchAttributeOperations, buildStartBatchOperations, validateSearchAttributes, } from './lifecycle/start-batch.ts';
 export { beginWorkflowExecution, runWorkflowStartInterceptor, startWorkflowExecution, } from './lifecycle/start-exec.ts';
 export { buildForkBatchOperations, buildForkSearchAttributes, createForkLineage, createForkedWorkflowState, } from './lifecycle/fork-helpers.ts';
-export { fork, launchWorkflowFromCheckpoint, recoverAll, resume } from './lifecycle/transition.ts';
+export { launchWorkflowFromCheckpoint } from './lifecycle/checkpoint-launch.ts';
+export { fork, recoverAll, resume } from './lifecycle/transition.ts';
 export { resumeWorkflowFromStorage } from './lifecycle/resume.ts';

package/dist/core/engine/lifecycle.js

@@ -15,14 +15,14 @@ export {
   workflowStateWithVersionTuple,
   workflowVersionTupleFromState
 } from "./lifecycle/persist.js";
+export { resolveScheduledStartAt } from "./lifecycle/start-schedule-timing.js";
+export { start, startWorkflow } from "./lifecycle/start.js";
 export {
+  applyRestartLineage,
   createInitialCheckpoint,
   createInitialWorkflowState,
-  parseStartOptionDuration,
-  resolveScheduledStartAt,
-  start,
-  startWorkflow
-} from "./lifecycle/start.js";
+  parseStartOptionDuration
+} from "./lifecycle/start-state.js";
 export {
   startOrSignal,
   startWithIdempotency
@@ -43,5 +43,6 @@ export {
   createForkLineage,
   createForkedWorkflowState
 } from "./lifecycle/fork-helpers.js";
-export { fork, launchWorkflowFromCheckpoint, recoverAll, resume } from "./lifecycle/transition.js";
+export { launchWorkflowFromCheckpoint } from "./lifecycle/checkpoint-launch.js";
+export { fork, recoverAll, resume } from "./lifecycle/transition.js";
 export { resumeWorkflowFromStorage } from "./lifecycle/resume.js";

package/dist/core/engine/listing.js

@@ -6,6 +6,10 @@ import { buildIndexOperations, validateAttributeType } from "../search-attribute
 import { normalizeWorkflowTags } from "../workflow-tags.js";
 import { mutateWorkflowTags, validateAttributeValueSizes } from "./attributes-tags.js";
 import { CONSTRAINED_ID_CHUNK_SIZE } from "./candidate-read-batching.js";
+import {
+  getResolvedDynamicRegistration,
+  resolveExecutableRegistrationForRevision
+} from "./dynamic-source-execution.js";
 import { resolveListCandidateIds } from "./list-candidate-resolution.js";
 import {
   readSearchAttributesForFilter,
@@ -95,6 +99,7 @@ function summaryFromState(state, attributeFailureCategory) {
     status: state.status,
     ...state.tags !== void 0 && { tags: state.tags },
     version: state.versionTuple.workflowVersion,
+    ...state.revision !== void 0 && { revision: state.revision },
     createdAt: state.createdAt,
     updatedAt: state.updatedAt,
     ...state.executionDeadline !== void 0 && { executionDeadline: state.executionDeadline },
@@ -164,10 +169,19 @@ export async function getAttributes(internals, workflowId) {
     return null;
   return decoded;
 }
+async function resolveAttributeSchemaRegistration(internals, state) {
+  const eagerOrAlreadyResolved = getResolvedDynamicRegistration(internals, state.type, state.revision);
+  if (eagerOrAlreadyResolved !== void 0)
+    return eagerOrAlreadyResolved;
+  if (!internals.sources.byName.has(state.type))
+    return;
+  const { entry } = await resolveExecutableRegistrationForRevision(internals.engine, internals, state.type, state.revision);
+  return entry;
+}
 export async function setAttributes(internals, workflowId, attributes) {
   const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
   if (stateBytes) {
-    const state = decodeWorkflowState(stateBytes), registration = internals.registrations.get(state.type);
+    const state = decodeWorkflowState(stateBytes), registration = await resolveAttributeSchemaRegistration(internals, state);
     if (registration?.searchAttributes) {
       const schema = registration.searchAttributes;
       for (const [key, value] of Object.entries(attributes)) {

package/dist/core/engine/memo-durable-activity.js

@@ -45,7 +45,10 @@ class MemoDurableActivityScope {
     this.#activityCallbacks = activityCallbacks;
     this.#persistCheckpoint = persistCheckpoint;
     this.#identityPrefix = `memo:${operation.step}:${hashString(operation.key)}`;
-    this.#internals.workflowTypeByWorkflowId.set(workflowId, context.workflowType);
+    this.#internals.workflowTypeByWorkflowId.set(workflowId, {
+      type: context.workflowType,
+      revision: this.#internals.workflowTypeByWorkflowId.get(workflowId)?.revision
+    });
   }
   async run(execute) {
     const cleanupAbortForwarding = this.#forwardAbortSignals();

package/dist/core/engine/nonterminal-revision-count.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Count non-terminal (`running`, `pending`, or `suspended`) workflow runs
+ * pinned to an exact `(type, revision)` (WFT-17). Wired into
+ * `catalog-removal.ts`'s `countWorkflowRevisionReferences()`, replacing the
+ * `nonTerminalRuns: 0` stub WFT-12 left in place pending this batch (see
+ * that changelog entry: "stays 0 until run-level revision pinning (WFT-17)
+ * exists to count against").
+ *
+ * Mirrors `diagnostics/version-check.ts`'s `groupActiveWorkflowsByType()`
+ * bounded-scan shape: only top-level `wf:{id}` records are workflow states
+ * (`wf:{id}:ckpt`, `:offload`, `:archive`, `:timeline:`, and index keys all
+ * share the `wf:` prefix but are not).
+ *
+ * @module core/engine/nonterminal-revision-count
+ */
+import type { Storage } from '../../storage/interface.ts';
+/**
+ * Scan `storage` for non-terminal workflow states whose `type` and
+ * `revision` match exactly, returning the count. A legacy record with no
+ * persisted `revision` never matches (a defined `revision` argument cannot
+ * equal `undefined`), consistent with recovery's own "a legacy record is a
+ * distinct, unresolved pin" treatment — it is not silently folded into
+ * whichever revision happens to be active.
+ */
+export declare function countNonTerminalRunsForRevision(storage: Storage, type: string, revision: string): Promise<number>;