@lostgradient/weft 0.24.0 → 0.24.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,23 +1,39 @@
-import { requireStorageCapability, storageValuesEqual } from "../../../storage/interface.js";
+import {
+  KEYS,
+  requireStorageCapability,
+  storageValuesEqual
+} from "../../../storage/interface.js";
 import { AtomicStateConflictError } from "../../atomic-state.js";
+import { WorkflowAlreadyExistsError } from "../errors.js";
 import {
   commitFencedEngineWrite,
   commitFencedEngineWriteAllowingPreconditionFailure
 } from "../fenced-write.js";
+import { WorkflowRevisionUnavailableError } from "../revision-errors.js";
 import {
   commitWithWorkflowClaimFold,
   prepareWorkflowClaimFold,
   throwWorkflowClaimUnavailable
 } from "../workflow-claim-fold.js";
 import { buildStartBatchOperations } from "./start-batch.js";
-
-export class StartIdempotencyRaceLostError extends Error {
-  constructor() {
-    super("start idempotency compare-and-swap lost to a concurrent caller");
-    this.name = "StartIdempotencyRaceLostError";
-  }
-}
+import { StartIdempotencyRaceLostError } from "./start-commit-errors.js";
+import { attributeLostStartPreconditionOrRetry } from "./start-precondition-attribution.js";
 const WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS = 5;
+function needsCatalogEntryStartPrecondition(internals, state) {
+  return internals.options.ownershipMode !== "none" && state.revision !== void 0;
+}
+async function buildCatalogEntryStartPrecondition(internals, state) {
+  return {
+    source: "catalog-entry",
+    condition: await buildCatalogEntryRevisionCondition(internals, state.type, state.revision)
+  };
+}
+export async function buildCatalogEntryRevisionCondition(internals, type, revision) {
+  const key = KEYS.catalogEntry(type, revision), entryBytes = await internals.storage.get(key);
+  if (entryBytes === null)
+    throw new WorkflowRevisionUnavailableError(type, revision, "not-installed");
+  return { key, expectedValue: entryBytes };
+}
 async function persistStartBatch(internals, workflowId, startOperations, conditions, claimFold, isDelayedStart) {
   if (claimFold) {
     const result = await commitWithWorkflowClaimFold(internals, claimFold, startOperations, conditions.map((entry) => entry.condition), "workflow claim acquisition");
@@ -33,9 +49,19 @@ async function persistStartBatch(internals, workflowId, startOperations, conditi
   requireStorageCapability(internals.storage, "conditionalBatch", "start preconditions");
   return await commitFencedEngineWriteAllowingPreconditionFailure(internals, fenceWorkflowId, startOperations, conditions.map((entry) => entry.condition)) ? "committed" : "precondition-lost";
 }
-async function hasStartPreconditionConflict(internals, conditions) {
+async function hasStartConditionConflict(internals, conditions, source) {
+  for (const entry of conditions) {
+    if (entry.source !== source)
+      continue;
+    const currentValue = await internals.storage.get(entry.condition.key);
+    if (!storageValuesEqual(currentValue, entry.condition.expectedValue))
+      return !0;
+  }
+  return !1;
+}
+async function hasCatalogEntryConflict(internals, conditions) {
   for (const entry of conditions) {
-    if (entry.source !== "start-precondition")
+    if (entry.source !== "catalog-entry")
       continue;
     const currentValue = await internals.storage.get(entry.condition.key);
     if (!storageValuesEqual(currentValue, entry.condition.expectedValue))
@@ -49,6 +75,9 @@ function tagStartPreconditions(conditions) {
     condition
   }));
 }
+function tagDuplicateIdCondition(condition) {
+  return condition === void 0 ? [] : [{ source: "duplicate-id", condition }];
+}
 function tagWorkflowConcurrencyConditions(conditions) {
   return conditions.map((condition) => ({
     source: "workflow-concurrency",
@@ -66,18 +95,23 @@ export async function buildAndCommitStartBatch(context, buildIdempotentStartOper
   for (let attempt = 0;attempt < maxAttempts; attempt += 1) {
     const idempotent = buildIdempotentStartOperations?.(workflowId), workflowConcurrency = await context.buildWorkflowConcurrencyStartOperations?.();
     lastWorkflowConcurrencyStateKey = workflowConcurrency?.stateKey ?? lastWorkflowConcurrencyStateKey;
-    const startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, context.delayedStartTimer, context.persistedWorkflowStartHeaders, mergeAdditionalStartOperations(context.additionalStartOperations, mergeAdditionalStartOperations(idempotent?.operations, workflowConcurrency?.operations)), context.callbacks, context.purgeDeleteOperations), conditions = [
+    const catalogEntryPrecondition = needsCatalogEntryStartPrecondition(internals, state) ? await buildCatalogEntryStartPrecondition(internals, state) : void 0, startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, context.delayedStartTimer, context.persistedWorkflowStartHeaders, mergeAdditionalStartOperations(context.additionalStartOperations, mergeAdditionalStartOperations(idempotent?.operations, workflowConcurrency?.operations)), context.callbacks, context.purgeDeleteOperations), conditions = [
       ...tagStartPreconditions(idempotent?.conditions),
-      ...tagWorkflowConcurrencyConditions(workflowConcurrency?.conditions ?? [])
+      ...tagDuplicateIdCondition(context.duplicateIdCondition),
+      ...tagWorkflowConcurrencyConditions(workflowConcurrency?.conditions ?? []),
+      ...catalogEntryPrecondition === void 0 ? [] : [catalogEntryPrecondition]
     ], isDelayedStart = context.delayedStartTimer !== void 0, claimFold = isDelayedStart ? void 0 : await prepareWorkflowClaimFold(internals, workflowId), outcome = await persistStartBatch(internals, workflowId, startOperations, conditions, claimFold, isDelayedStart);
     if (outcome === "committed")
       return;
-    if (await hasStartPreconditionConflict(internals, conditions))
+    if (outcome !== "claim-lost" && await hasStartConditionConflict(internals, conditions, "duplicate-id"))
+      throw new WorkflowAlreadyExistsError(workflowId);
+    if (await hasStartConditionConflict(internals, conditions, "start-precondition"))
       throw new StartIdempotencyRaceLostError;
+    if (await hasCatalogEntryConflict(internals, conditions))
+      throw new WorkflowRevisionUnavailableError(state.type, state.revision, "not-installed");
     if (outcome === "claim-lost")
       return throwWorkflowClaimUnavailable(internals, workflowId);
-    if (workflowConcurrency === void 0)
-      throw new StartIdempotencyRaceLostError;
+    await attributeLostStartPreconditionOrRetry(workflowId, context.duplicateIdCondition !== void 0, workflowConcurrency !== void 0, () => hasStartConditionConflict(internals, conditions, "workflow-concurrency"));
   }
   throw new AtomicStateConflictError(lastWorkflowConcurrencyStateKey ?? "workflow concurrency admission", WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS);
 }

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

@@ -2,8 +2,24 @@ import type { Checkpoint, StartOptions, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
 export declare function runWorkflowStartInterceptor(_internals: EngineInternals, workflowId: string, workflowType: string, input: unknown, parentHeaders: Map<string, string> | undefined, callbacks: LifecycleCallbacks): Map<string, string> | undefined;
-export declare function startWorkflowExecution(internals: EngineInternals, workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, input: unknown, checkpoint: Checkpoint, nestingDepth: number, executionDeadline: number | undefined, executionStateOwnerId: string, _callbacks?: LifecycleCallbacks): void;
-export declare function beginWorkflowExecution(internals: EngineInternals, workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, _registration: RegistrationEntry, callbacks: LifecycleCallbacks, onStarted?: () => void): void;
+export declare function startWorkflowExecution(internals: EngineInternals, workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, 
+/**
+ * The starting run's persisted `WorkflowState.revision` (WFT-19/WFT-20):
+ * populates the per-instance identity cache readers use for revision-scoped
+ * routing, and is echoed to the strategy's `startWorkflow` for worker-protocol
+ * revision validation.
+ */
+revision: string | undefined, input: unknown, checkpoint: Checkpoint, nestingDepth: number, executionDeadline: number | undefined, executionStateOwnerId: string, _callbacks?: LifecycleCallbacks): void;
+export declare function beginWorkflowExecution(internals: EngineInternals, workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, 
+/**
+ * The starting run's persisted `WorkflowState.revision` (WFT-19/WFT-20).
+ * Threaded into both the queued-inline path below (which also re-reads
+ * `revision` off the RELOADED `WorkflowState` at flush time —
+ * `inline-launch-queue.ts` — exactly like it already does for
+ * `workflowExecutionToken`) and the non-inline `startWorkflowExecution`
+ * branch, which populates the per-instance identity cache with it directly.
+ */
+revision: string | undefined, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, _registration: RegistrationEntry, callbacks: LifecycleCallbacks, onStarted?: () => void): void;
 /**
  * `defer: false` is an inline-only liveness gate: it awaits the moment the
  * generator is first driven. A worker-mode start queues to the Worker transport

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

@@ -20,13 +20,14 @@ export function runWorkflowStartInterceptor(_internals, workflowId, workflowType
   });
   return capturedHeaders;
 }
-export function startWorkflowExecution(internals, workflowId, workflowExecutionToken, workflowType, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, _callbacks) {
+export function startWorkflowExecution(internals, workflowId, workflowExecutionToken, workflowType, revision, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, _callbacks) {
   if (nestingDepth !== 0)
     internals.workflowNestingDepths.set(workflowId, nestingDepth);
-  internals.workflowTypeByWorkflowId.set(workflowId, workflowType);
+  internals.workflowTypeByWorkflowId.set(workflowId, { type: workflowType, revision });
   internals.strategy.startWorkflow({
     workflowId,
     ...workflowExecutionToken !== void 0 && { workflowExecutionToken },
+    ...revision !== void 0 && { revision },
     workflowType,
     input,
     checkpoint: serializeCheckpoint(checkpoint),
@@ -40,7 +41,7 @@ export function startWorkflowExecution(internals, workflowId, workflowExecutionT
     }
   });
 }
-export function beginWorkflowExecution(internals, workflowId, workflowExecutionToken, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, _registration, callbacks, onStarted) {
+export function beginWorkflowExecution(internals, workflowId, workflowExecutionToken, workflowType, revision, input, checkpoint, executionDeadline, executionStateOwnerId, _registration, callbacks, onStarted) {
   const nestingDepth = internals.pendingNestingDepth ?? 0;
   internals.pendingNestingDepth = void 0;
   if (internals.inlineStrategy !== null) {
@@ -48,6 +49,7 @@ export function beginWorkflowExecution(internals, workflowId, workflowExecutionT
       workflowId,
       ...workflowExecutionToken !== void 0 && { workflowExecutionToken },
       workflowType,
+      revision,
       input,
       checkpoint,
       nestingDepth,
@@ -58,7 +60,7 @@ export function beginWorkflowExecution(internals, workflowId, workflowExecutionT
     return;
   }
   callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, workflowType, input));
-  startWorkflowExecution(internals, workflowId, workflowExecutionToken, workflowType, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, callbacks);
+  startWorkflowExecution(internals, workflowId, workflowExecutionToken, workflowType, revision, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, callbacks);
   onStarted?.();
 }
 export function assertDeferSupported(internals, options, isDelayedStart) {
@@ -73,7 +75,7 @@ export async function beginExecutionAwaitingLiveness(internals, params, workflow
   if (params.isDelayed)
     return;
   const liveness = params.options?.defer === !1 ? Promise.withResolvers() : void 0;
-  beginWorkflowExecution(internals, workflowId, params.state.workflowExecutionToken, params.type, params.input, params.checkpoint, params.state.executionDeadline, params.state.executionStateOwnerId ?? workflowId, params.registration, callbacks, liveness ? () => liveness.resolve() : void 0);
+  beginWorkflowExecution(internals, workflowId, params.state.workflowExecutionToken, params.type, params.state.revision, params.input, params.checkpoint, params.state.executionDeadline, params.state.executionStateOwnerId ?? workflowId, params.registration, callbacks, liveness ? () => liveness.resolve() : void 0);
   if (liveness)
     await liveness.promise;
 }

package/dist/core/engine/lifecycle/start-or-signal-create.js

@@ -2,9 +2,7 @@ import { KEYS } from "../../../storage/interface.js";
 import { encode } from "../../codec.js";
 import { WorkflowAlreadyExistsError } from "../errors.js";
 import { buildCreateBatchSignalOperations } from "../signals.js";
-import {
-  StartIdempotencyRaceLostError
-} from "./start-commit.js";
+import { StartIdempotencyRaceLostError } from "./start-commit-errors.js";
 import {
   requireWinnerId,
   resolveCallerIdWinnerOrRetry,

package/dist/core/engine/lifecycle/start-or-signal.js

@@ -6,7 +6,7 @@ import {
   StartWorkflowValidationError
 } from "../../start-workflow-validation.js";
 import { IdempotencyKeyPurgedError, StartOrSignalConflictError } from "../errors.js";
-import { StartIdempotencyRaceLostError } from "./start-commit.js";
+import { StartIdempotencyRaceLostError } from "./start-commit-errors.js";
 import {
   createWithSignalOrFallback,
   idempotentStartOperationsFor

package/dist/core/engine/lifecycle/start-precondition-attribution.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Decide what a lost start compare-and-swap MEANS, once every positively-detectable
+ * cause has already been ruled out by the caller — an idempotency precondition, a
+ * catalog-entry removal, and a lost workflow claim are each re-checked and raise
+ * their own error before this runs.
+ *
+ * Throws when the loss is terminal; returns normally when the caller should retry
+ * workflow-concurrency admission.
+ *
+ * WFT-152: a caller-supplied id that lost its duplicate-id condition means another
+ * engine sharing this store committed a create for the same id after this start's
+ * duplicate-id read. It raises the SAME {@link WorkflowAlreadyExistsError} the
+ * in-engine `pendingStarts` guard raises for the identical collision, so a
+ * cross-engine duplicate id is indistinguishable from an in-engine one at the call
+ * site.
+ *
+ * Attribution is by ELIMINATION, never by re-reading the duplicate-id key. A
+ * re-read is unsound: the winning run can complete and be purged (or swept by
+ * retention) between the failed compare-and-swap and the check, restoring the
+ * workflow record to the very value the condition expected, so the conflict reads
+ * back as "no conflict". With no workflow-concurrency conditions in the batch,
+ * nothing else is left for the lost outcome to mean.
+ *
+ * When concurrency conditions ARE present, retry only on positive evidence that the
+ * retryable one is what missed — hence `hasWorkflowConcurrencyConflict`, invoked
+ * lazily so the extra storage read happens only on that path.
+ *
+ * That evidence is NOT proof the duplicate id was fine, and deliberately is not
+ * treated as such. The concurrency precondition is a monotonic atomic-state VERSION
+ * key (`buildWorkflowConcurrencyStartOperations` conditions on `snapshot.version`
+ * and writes `version + 1`; releasing the slot increments again rather than
+ * restoring), so once a same-id winner acquires and releases, that condition stays
+ * mismatched forever and reports a conflict regardless of what else missed. What
+ * makes retrying safe here is the caller's own earlier check: it re-reads the
+ * duplicate-id key positively and raises `WorkflowAlreadyExistsError` before this
+ * runs, so reaching this point means the workflow record currently matches the
+ * expectation — the id is free right now, and a retry re-conditions on that same
+ * still-matching value.
+ *
+ * The residual is the pre-compare-and-swap purge ABA (WFT-153): a winner purged
+ * between the read and the commit makes an absent record look never-used, which no
+ * value-comparing condition can detect. That is tracked separately and is the reason
+ * this function does not claim exclusive attribution.
+ *
+ * With no concurrency evidence at all, fail closed: something missed, nothing
+ * retryable explains it, and a spurious `WorkflowAlreadyExistsError` is public,
+ * non-destructive, and retryable by the caller.
+ */
+export declare function attributeLostStartPreconditionOrRetry(workflowId: string, hasDuplicateIdCondition: boolean, hasWorkflowConcurrency: boolean, hasWorkflowConcurrencyConflict: () => Promise<boolean>): Promise<void>;

package/dist/core/engine/lifecycle/start-precondition-attribution.js

@@ -0,0 +1,13 @@
+import { WorkflowAlreadyExistsError } from "../errors.js";
+import { StartIdempotencyRaceLostError } from "./start-commit-errors.js";
+export async function attributeLostStartPreconditionOrRetry(workflowId, hasDuplicateIdCondition, hasWorkflowConcurrency, hasWorkflowConcurrencyConflict) {
+  if (!hasDuplicateIdCondition) {
+    if (!hasWorkflowConcurrency)
+      throw new StartIdempotencyRaceLostError;
+    return;
+  }
+  if (!hasWorkflowConcurrency)
+    throw new WorkflowAlreadyExistsError(workflowId);
+  if (!await hasWorkflowConcurrencyConflict())
+    throw new WorkflowAlreadyExistsError(workflowId);
+}

package/dist/core/engine/lifecycle/start-revision-resolution.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve the exact revision a fresh `startWorkflow()` call — or a schedule's
+ * pin capture (WFT-20, `pinned-schedule-revision.ts`) — is about to commit
+ * to. Extracted out of `lifecycle/start.ts` so both that module and the
+ * schedule pin-capture path import the SAME logic instead of duplicating the
+ * `registeredCatalogRevisions`-fallback + `ensureWorkflowCatalogReady()`
+ * recheck rule; `start.ts` imports these back unchanged.
+ *
+ * @module core/engine/lifecycle/start-revision-resolution
+ */
+import type { EngineInternals } from '../internals.ts';
+/**
+ * The exact executable artifact a start is about to run: the resolved
+ * dynamic-source candidate revision, or — for an eager registration, which
+ * never populates `resolvedRevision` — this process's own
+ * `registeredCatalogRevisions` entry for `type` (the revision of the code
+ * actually loaded here, NOT `inFlightRevision`, which for an eager type
+ * falls back to the catalog's cached ACTIVE pointer and can name a revision
+ * this process never loaded under a multi-engine deployment). Synchronous,
+ * on purpose: every top-level engine.* method already awaits
+ * `ensureWorkflowCatalogReady()` before reaching a call site that needs this,
+ * so this map is populated by the time the overwhelmingly common case gets
+ * here. `undefined` means "genuinely not cached yet"; the caller falls back
+ * to {@link resolveStartRevisionUncached}.
+ */
+export declare function resolveCachedStartRevision(internals: EngineInternals, type: string, resolvedRevision: string | undefined): string | undefined;
+/**
+ * The rare fallback {@link resolveCachedStartRevision} defers to: a fired
+ * schedule occurrence or a delayed-start timer calls `startWorkflow`
+ * directly from background scheduler code, with no top-level
+ * `ensureWorkflowCatalogReady()` gate already awaited. Re-checks catalog
+ * readiness once, then re-reads the cache.
+ */
+export declare function resolveStartRevisionUncached(internals: EngineInternals, type: string): Promise<string>;

package/dist/core/engine/lifecycle/start-revision-resolution.js

@@ -0,0 +1,11 @@
+import { ensureWorkflowCatalogReady } from "../catalog-readiness.js";
+export function resolveCachedStartRevision(internals, type, resolvedRevision) {
+  return resolvedRevision ?? internals.registeredCatalogRevisions.get(type);
+}
+export async function resolveStartRevisionUncached(internals, type) {
+  await ensureWorkflowCatalogReady(internals.engine);
+  const afterReadiness = internals.registeredCatalogRevisions.get(type);
+  if (afterReadiness !== void 0)
+    return afterReadiness;
+  throw Error(`Cannot start workflow "${type}": no catalog revision is registered for this eagerly-registered type, even after re-checking catalog readiness. This should be unreachable.`);
+}