@lostgradient/weft 0.24.0 → 0.24.1

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

@@ -0,0 +1,16 @@
+/**
+ * Build the initial in-memory {@link WorkflowState} and {@link Checkpoint}
+ * for a fresh `start()` — split out of `start.ts`, which has no headroom
+ * under the repository's 500-line implementation-file ceiling for this
+ * logic inline.
+ *
+ * @module core/engine/lifecycle/start-state
+ */
+import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
+import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+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, revision: string, 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 applyRestartLineage(state: WorkflowState, displacedState: WorkflowState | null): void;

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

@@ -0,0 +1,60 @@
+import { createCheckpoint } from "../../checkpoint.js";
+import { normalizeStorageTimestamp } from "../../scheduler.js";
+import {
+  StartWorkflowValidationError,
+  parseStartWorkflowDuration
+} from "../../start-workflow-validation.js";
+export function parseStartOptionDuration(_internals, duration, fieldName, _callbacks) {
+  return parseStartWorkflowDuration(duration, fieldName);
+}
+function buildInitialIdentitySlice(workflowId, type, input, versionTuple, revision, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags) {
+  return {
+    id: workflowId,
+    type,
+    status: delayedStartTimer ? "pending" : "running",
+    input,
+    versionTuple,
+    revision,
+    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, revision, options, tags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks) {
+  const now = internals.options.getNow(), state = buildInitialIdentitySlice(workflowId, type, input, versionTuple, revision, 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;
+}
+export function applyRestartLineage(state, displacedState) {
+  if (displacedState === null)
+    return;
+  state.restartedFrom = {
+    workflowId: displacedState.id,
+    ...displacedState.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: displacedState.workflowExecutionToken
+    },
+    replacedAt: state.createdAt
+  };
+}

package/dist/core/engine/lifecycle/start-terminal-conflict-purge.d.ts

@@ -1,7 +1,65 @@
-import type { BatchOperation } from '../../../storage/interface.ts';
+import type { BatchOperation, ConditionalBatchCondition } from '../../../storage/interface.ts';
 import type { StartWorkflowOptions, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
+/**
+ * What the duplicate-id read decided about a caller-supplied workflow id.
+ */
+export type StartDuplicateIdDecision = {
+    /** A prior terminal run this start will displace, or `null` for a fresh id. */
+    terminalRunToPurge: WorkflowState | null;
+    /**
+     * Compare-and-swap precondition that makes the duplicate-id check atomic with
+     * the create commit (WFT-152).
+     *
+     * The check below reads `KEYS.workflow(workflowId)` and decides whether the id
+     * is free, but that read and the create batch are separated by every build step
+     * in between. Within ONE engine `pendingStarts` holds the id across that window;
+     * two engines sharing a store share no such memory, so both previously committed
+     * blind and the second silently overwrote the first — leaving the loser with a
+     * run whose terminal transition happens on the other engine and therefore never
+     * settles its `result()` waiter. Conditioning the batch on the exact value seen
+     * here collapses that window: the loser's batch does not commit, and
+     * `buildAndCommitStartBatch` surfaces {@link WorkflowAlreadyExistsError} — the
+     * same error the in-engine `pendingStarts` guard already throws for the same
+     * collision.
+     *
+     * `expectedValue` is the RAW observed bytes, deliberately not a re-encoding of
+     * the decoded state: re-encoding is not guaranteed to round-trip byte-identically,
+     * and a condition built from one would fail against a record nothing had touched.
+     * `null` (id absent) and a prior terminal run's bytes (an
+     * `onTerminalConflict: 'start-new'` restart) are both valid expected values, so a
+     * restart is equally protected against a concurrent engine displacing the same
+     * terminal run.
+     *
+     * No `conditionalBatch` capability gate is needed. Reaching this code means a
+     * workflow is registered, and registration drains through
+     * `WorkflowCatalog#activateRegistered`, which already hard-requires that
+     * capability at `Engine.create()`. A store that cannot honour this condition
+     * cannot host an engine that could start a workflow in the first place.
+     *
+     * KNOWN LIMITATION (PR #959 review). The condition compares a VALUE, so it cannot
+     * distinguish "this id was never used" from "a run existed here and was purged".
+     * If a racing winner commits, completes, and is purged or swept by retention
+     * before this batch commits, `wf:<id>` is absent again, `expectedValue: null`
+     * matches, and both starts execute. Closing that needs durable per-id generation
+     * or tombstone state a purge cannot restore — a new persisted mechanism, out of
+     * scope here. The window is narrow (a winner's whole lifecycle plus a purge inside
+     * one loser's read-to-commit gap) and the outcome is a duplicate run rather than
+     * the indefinite hang this fence exists to remove.
+     */
+    duplicateIdCondition: ConditionalBatchCondition;
+};
+/**
+ * The decision for a start whose id was GENERATED rather than caller-supplied. A
+ * v4 UUID is effectively unique, so the duplicate-id read is skipped entirely and
+ * there is no observed value to condition on — the start keeps the unconditioned
+ * single-write hot path.
+ */
+export declare const GENERATED_ID_START_DECISION: {
+    readonly terminalRunToPurge: null;
+    readonly duplicateIdCondition: undefined;
+};
 /**
  * Decide what a caller-supplied workflow id that already has a persisted record
  * means, WITHOUT performing any destructive action. Only invoked when the caller
@@ -23,9 +81,14 @@ import { type LifecycleCallbacks } from './shared.ts';
  *   delete the finalizer payload before the resource is torn down, leaking it, so
  *   the restart is refused until teardown settles (which clears the marker).
  *
- * Returns `null` when there is no existing record (the create proceeds normally).
+ * This read is only a point-in-time observation: another engine sharing the store
+ * can commit a create for the same id in the window between it and the create
+ * batch. The returned {@link StartDuplicateIdDecision} therefore carries a
+ * `duplicateIdCondition` holding the exact bytes seen here, so that batch can be
+ * conditioned on them — turning that window into a lost compare-and-swap rather
+ * than a blind overwrite (WFT-152).
  */
-export declare function resolveTerminalConflictForRestart(internals: EngineInternals, workflowId: string, options: StartWorkflowOptions | undefined): Promise<WorkflowState | null>;
+export declare function resolveTerminalConflictForRestart(internals: EngineInternals, workflowId: string, options: StartWorkflowOptions | undefined): Promise<StartDuplicateIdDecision>;
 /**
  * Prepare a prior terminal run for displacement by a `'start-new'` restart WITHOUT
  * committing the destructive delete. Returns the storage delete operations (for the

package/dist/core/engine/lifecycle/start-terminal-conflict-purge.js

@@ -6,10 +6,17 @@ import {
 import { WorkflowAlreadyExistsError, WorkflowTeardownPendingError } from "../errors.js";
 import { cleanupWaiters } from "../termination/cleanup.js";
 import { decodeWorkflowState, isTerminalWorkflowStatus } from "../validation.js";
+export const GENERATED_ID_START_DECISION = {
+  terminalRunToPurge: null,
+  duplicateIdCondition: void 0
+};
 export async function resolveTerminalConflictForRestart(internals, workflowId, options) {
-  const existingBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  const key = KEYS.workflow(workflowId), existingBytes = await internals.storage.get(key);
   if (existingBytes === null)
-    return null;
+    return {
+      terminalRunToPurge: null,
+      duplicateIdCondition: { key, expectedValue: null }
+    };
   if (options?.onTerminalConflict !== "start-new")
     throw new WorkflowAlreadyExistsError(workflowId);
   const existingState = decodeWorkflowState(existingBytes);
@@ -17,7 +24,10 @@ export async function resolveTerminalConflictForRestart(internals, workflowId, o
     throw new WorkflowAlreadyExistsError(workflowId);
   if (await storageHas(internals.storage, KEYS.teardownOwed(workflowId)))
     throw new WorkflowTeardownPendingError(workflowId);
-  return existingState;
+  return {
+    terminalRunToPurge: existingState,
+    duplicateIdCondition: { key, expectedValue: existingBytes }
+  };
 }
 export async function prepareTerminalRunPurge(internals, state, callbacks) {
   const cleanupWaitersForStart = (id) => cleanupWaiters(internals, id, {

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

@@ -1,13 +1,23 @@
 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 { StartOptions, 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 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): 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;

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

@@ -1,4 +1,3 @@
-import { createCheckpoint } from "../../checkpoint.js";
 import { assertPayloadWithinLimit } from "../../payload-size.js";
 import { normalizeStorageTimestamp } from "../../scheduler.js";
 import {
@@ -6,13 +5,16 @@ import {
   assertExclusiveStartWorkflowOptions,
   assertValidOnTerminalConflict,
   coerceStartWorkflowId,
-  coerceStartWorkflowTimestamp,
-  parseStartWorkflowDuration
+  coerceStartWorkflowTimestamp
 } 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,6 +30,17 @@ import {
   runWorkflowStartInterceptor
 } from "./start-exec.js";
 import {
+  resolveCachedStartRevision,
+  resolveStartRevisionUncached
+} from "./start-revision-resolution.js";
+import {
+  applyRestartLineage,
+  createInitialCheckpoint,
+  createInitialWorkflowState,
+  parseStartOptionDuration
+} from "./start-state.js";
+import {
+  GENERATED_ID_START_DECISION,
   prepareTerminalRunPurge,
   resolveTerminalConflictForRestart
 } from "./start-terminal-conflict-purge.js";
@@ -70,11 +83,16 @@ 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) {
   assertServicesSupportedForMode(internals, options);
   assertValidOnTerminalConflict(options);
   const preparation = prepareStartWorkflow(internals, options, callbacks), {
@@ -90,12 +108,16 @@ 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 } = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : GENERATED_ID_START_DECISION, 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;
     internals.checkpoints.set(workflowId, checkpoint);
@@ -113,7 +135,8 @@ 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
     }, buildIdempotentStartOperations);
     if (options?.services !== void 0) {
       internals.workflowServices.set(workflowId, options.services);
@@ -140,17 +163,6 @@ 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)
@@ -165,45 +177,3 @@ export function resolveScheduledStartAt(internals, options, submissionTime, call
   }
   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,7 @@
-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 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 = {
@@ -19,4 +19,3 @@ export type ResumeOptions = {
 };
 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,31 +1,35 @@
 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 { WorkflowRecoverySkippedEvent } from "../../events.js";
 import { VersionMismatchError } from "../../versioning.js";
-import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { hydrateCheckpointReplayState } from "../checkpoint-replay.js";
+import { DynamicWorkflowSourceUnavailableError } from "../dynamic-source-errors.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 { WorkflowRevisionUnavailableError } from "../revision-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 {
+  buildRecoveryRevisionGroups,
+  classifyRevisionGroups,
+  createRecoveryScopedRevisionCallbacks
+} from "./recovery-revision-groups.js";
 import { resumeWorkflowFromStorage } from "./resume.js";
 import {
-  createWorkflowHandle,
   enforceHistoryPolicyBeforeReplayById,
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
@@ -39,9 +43,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")
@@ -76,6 +80,14 @@ async function recoverEntryOrIsolateFailure(internals, workflowId, callbacks, op
     }
     if (error instanceof WorkflowClaimUnavailableError)
       return null;
+    if (error instanceof WorkflowRevisionUnavailableError) {
+      await callbacks.failWorkflowForRevisionUnavailable(workflowId, error);
+      return null;
+    }
+    if (error instanceof DynamicWorkflowSourceUnavailableError) {
+      await callbacks.failWorkflowForUnavailableDynamicSource(workflowId, error);
+      return null;
+    }
     throw error;
   }
 }
@@ -83,9 +95,13 @@ 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 +111,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);
   }
@@ -115,10 +131,7 @@ 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 +142,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 +162,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,11 @@
 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, 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,13 @@ export {
   workflowStateWithVersionTuple,
   workflowVersionTupleFromState
 } from "./lifecycle/persist.js";
+export { resolveScheduledStartAt, 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 +42,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";