@lostgradient/weft 0.23.1 → 0.24.1

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,12 +5,16 @@ import {
   assertExclusiveStartWorkflowOptions,
   assertValidOnTerminalConflict,
   coerceStartWorkflowId,
-  coerceStartWorkflowTimestamp,
-  parseStartWorkflowDuration
+  coerceStartWorkflowTimestamp
 } from "../../start-workflow-validation.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";
@@ -27,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";
@@ -69,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), {
@@ -89,11 +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;
+  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);
@@ -111,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);
@@ -133,21 +158,11 @@ export async function startWorkflow(internals, type, input, options, additionalS
     return handle;
   } finally {
     internals.pendingStarts.delete(workflowId);
+    releaseInFlightStart(internals, type, inFlightRevision);
     if (!startSucceeded)
       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)
@@ -162,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";

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>;

package/dist/core/engine/nonterminal-revision-count.js

@@ -0,0 +1,16 @@
+import { decodeWorkflowState, isTerminalWorkflowStatus } from "./validation.js";
+import { isTopLevelWorkflowStateKey } from "./workflow-state-stream.js";
+export async function countNonTerminalRunsForRevision(storage, type, revision) {
+  let count = 0;
+  for await (const [key, bytes] of storage.scan("wf:")) {
+    if (!isTopLevelWorkflowStateKey(key))
+      continue;
+    const state = decodeWorkflowState(bytes);
+    if (state.type !== type || state.revision !== revision)
+      continue;
+    if (isTerminalWorkflowStatus(state.status))
+      continue;
+    count += 1;
+  }
+  return count;
+}

package/dist/core/engine/operations-time.d.ts

@@ -1,31 +1,13 @@
 import type { ContextOperationRequest } from '../context.ts';
-import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../types.ts';
-import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { StartOptions, TimerEntry } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
-type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+import { type TimeOperationCallbacks } from './time-operation-callbacks.ts';
 type SleepOperation = Extract<ContextOperationRequest, {
     type: 'sleep';
 }>;
-export type TimeOperationCallbacks = {
-    completeOperation: (workflowId: string, value: unknown) => void;
-    dispatchEvent: (event: Event) => void;
-    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
-    failWorkflow: (workflowId: string, error: Error) => Promise<void>;
-    runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
-    beginWorkflowExecution: (workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, registration: RegistrationEntry) => void;
-    workflowVersionTupleFromState: (state: WorkflowState) => WorkflowVersionTuple;
-    setWorkflowStartHeaders: (workflowId: string, headers: Map<string, string> | undefined) => void;
-    loadWorkflowStartHeaders: (workflowId: string) => Promise<Map<string, string> | undefined>;
-    parseStartOptionDuration: (value: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter') => number;
-    runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
-    runWorkflowFinalizer: (workflowId: string, timerId: string) => Promise<void>;
-    handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
-    timeout: (workflowId: string) => Promise<void>;
-    handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
-};
+export type { TimeOperationCallbacks };
 export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
 export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
 export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void, scheduledFireAt: number): void;
-export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'dispatchEvent' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
-export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runWorkflowFinalizer' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'dispatchEvent' | 'workflowVersionTupleFromState'>): Promise<void>;
-export {};
+export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'dispatchEvent' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'resolveExecutableRegistrationForRevision' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runWorkflowFinalizer' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'dispatchEvent' | 'resolveExecutableRegistrationForRevision' | 'workflowVersionTupleFromState'>): Promise<void>;

package/dist/core/engine/operations-time.js

@@ -4,7 +4,9 @@ import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
 import { notifyConditionWaiters, notifyConditionWaitersForTimerFire } from "./condition-waiters.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
+import { resolveDelayedStartRegistrationOrFail } from "./lifecycle/delayed-start-registration.js";
 import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
+import { ensureDelayedStartClaimAndCleanupBeforeFailure } from "./lifecycle/standalone-claim-acquire.js";
 import {
   acknowledgeSupersededSleepTimers,
   handleSleepTimerWithAcknowledgement,
@@ -88,23 +90,22 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   const checkpoint = await loadDelayedWorkflowCheckpoint(internals, entry, callbacks);
   if (!checkpoint)
     return;
-  const registration = internals.registrations.get(state.type);
-  if (!registration) {
-    await callbacks.failWorkflow(entry.workflowId, Error(`No workflow registered with name "${state.type}"`));
+  const resolvedRegistration = await resolveDelayedStartRegistrationOrFail(internals, entry, state.type, state.revision, callbacks);
+  if (resolvedRegistration === null)
     return;
-  }
-  const now = internals.options.getNow(), executionDeadline = await resolveDelayedExecutionDeadline(entry, now, callbacks);
+  const { entry: registration, revision: resolvedRevision } = resolvedRegistration, now = internals.options.getNow(), executionDeadline = await resolveDelayedExecutionDeadline(internals, entry, now, callbacks);
   if (executionDeadline === "invalid")
     return;
   const runningState = await callbacks.runSerializedWorkflowStateWrite(entry.workflowId, async () => {
     const latestState = await callbacks.loadWorkflowState(entry.workflowId);
     if (!latestState || latestState.status !== "pending")
       return null;
-    const nextRunningState = {
+    const effectiveRevision = latestState.revision ?? resolvedRevision, nextRunningState = {
       ...latestState,
       status: "running",
       startedAt: now,
       updatedAt: now,
+      ...effectiveRevision !== void 0 && { revision: effectiveRevision },
       ...executionDeadline !== void 0 && { executionDeadline }
     }, operations = [
       {
@@ -136,7 +137,7 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   internals.checkpoints.set(entry.workflowId, checkpoint);
   internals.workflowVersionTuples.set(entry.workflowId, callbacks.workflowVersionTupleFromState(runningState));
   callbacks.setWorkflowStartHeaders(entry.workflowId, await callbacks.loadWorkflowStartHeaders(entry.workflowId));
-  callbacks.beginWorkflowExecution(entry.workflowId, runningState.workflowExecutionToken, runningState.type, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
+  callbacks.beginWorkflowExecution(entry.workflowId, runningState.workflowExecutionToken, runningState.type, runningState.revision, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
 }
 async function loadDelayedWorkflowCheckpoint(internals, entry, callbacks) {
   const checkpointBytes = await internals.storage.get(KEYS.checkpoint(entry.workflowId));
@@ -146,21 +147,22 @@ async function loadDelayedWorkflowCheckpoint(internals, entry, callbacks) {
   }
   return deserializeCheckpoint(checkpointBytes);
 }
-async function resolveDelayedExecutionDeadline(entry, now, callbacks) {
+async function resolveDelayedExecutionDeadline(internals, entry, now, callbacks) {
   if (entry.executionTimeoutMs === void 0)
     return;
   if (!Number.isFinite(entry.executionTimeoutMs) || entry.executionTimeoutMs < 0) {
-    await failInvalidDelayedExecutionTimeout(entry, callbacks);
+    await failInvalidDelayedExecutionTimeout(internals, entry, callbacks);
     return "invalid";
   }
   try {
     return normalizeStorageTimestamp(now + entry.executionTimeoutMs, `Delayed execution timeout for workflow "${entry.workflowId}"`);
   } catch {
-    await failInvalidDelayedExecutionTimeout(entry, callbacks);
+    await failInvalidDelayedExecutionTimeout(internals, entry, callbacks);
     return "invalid";
   }
 }
-async function failInvalidDelayedExecutionTimeout(entry, callbacks) {
+async function failInvalidDelayedExecutionTimeout(internals, entry, callbacks) {
+  await ensureDelayedStartClaimAndCleanupBeforeFailure(internals, entry.workflowId);
   await callbacks.failWorkflow(entry.workflowId, Error(`Invalid delayed execution timeout for workflow "${entry.workflowId}"`));
 }
 export async function handleTimerFired(internals, entry, callbacks) {

package/dist/core/engine/ownership-bootstrap.d.ts

@@ -85,7 +85,7 @@ export type WorkflowLeaseOwnershipBootstrapOptions = {
      * doc for why an engine that cannot execute a candidate's registered type
      * must never win its claim in the first place.
      */
-    isWorkflowTypeRegistered?: (workflowType: string) => boolean;
+    isWorkflowTypeRegistered?: (workflowType: string, revision: string | undefined) => boolean;
 };
 /**
  * Everything `Engine` needs to hold on `EngineInternals` once bootstrap