@lostgradient/weft 0.24.0 → 0.24.2

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

@@ -1,211 +1,31 @@
 import { KEYS } from "../../../storage/interface.js";
-import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
-import { encode } from "../../codec.js";
-import { Context, setContextWorkflowInterceptor } from "../../context.js";
-import { EventLog } from "../../event-log.js";
-import { WorkflowResumedEvent } from "../../events.js";
-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 { commitFencedEngineWrite } from "../fenced-write.js";
-import { getWorkflowExecutionStartedAt } from "../handles.js";
-import { loadWorkflowState } from "../storage-io.js";
-import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
 import { decodeWorkflowState } from "../validation.js";
-import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
-import { prepareResumeState } from "./persist.js";
+import { performResumeAfterClaimAcquired } from "./resume-body.js";
 import {
-  reprovideRecoveredServices,
-  workflowServicesResolverInfoFromState
-} from "./recovered-services.js";
-import {
-  enforceHistoryPolicyBeforeReplay,
-  loadTerminalCleanupTrackedState,
-  loadWorkflowStartHeaders,
-  setWorkflowStartHeaders
-} from "./shared.js";
-import { acquireStandaloneClaimBeforeResume } from "./standalone-claim-acquire.js";
-async function prepareRecoveredServicesOrFail(internals, state, callbacks, resolverInfo) {
-  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError, callbacks.dispatchEvent, resolverInfo);
-}
-async function runRecoveredWorkflowHookOrFail(internals, state, handle, resolverInfo, onRecoveredWorkflow, callbacks) {
-  const info = {
-    ...resolverInfo,
-    handle,
-    launchOptions: resolverInfo.launchOptions ?? { id: state.id },
-    services: internals.workflowServices.get(state.id)
-  };
-  try {
-    await onRecoveredWorkflow(info);
-    return !1;
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error), hookError = Error(`Recovery hook failed for workflow "${state.id}": ${reason}`);
-    try {
-      await callbacks.failWorkflowForRecoveryHook(state.id, hookError);
-    } catch (commitError) {
-      callbacks.handleCleanupError("onRecoveredWorkflow", commitError, state.id);
-    }
-    return !0;
-  }
-}
-async function prepareRecoveredWorkflowOrFail(internals, state, callbacks, onRecoveredWorkflow) {
-  const resolverInfo = onRecoveredWorkflow === void 0 ? void 0 : await workflowServicesResolverInfoFromState(internals, state), handle = callbacks.getHandle(state.id);
-  if (await prepareRecoveredServicesOrFail(internals, state, callbacks, resolverInfo))
-    return { handle, shouldStop: !0 };
-  if (onRecoveredWorkflow === void 0 || resolverInfo === void 0)
-    return { handle, shouldStop: !1 };
-  const shouldStop = await runRecoveredWorkflowHookOrFail(internals, state, handle, resolverInfo, onRecoveredWorkflow, callbacks);
-  return { handle, shouldStop };
-}
-function assertResumeNotTerminating(internals, workflowId) {
-  if (internals.terminalizingWorkflows.has(workflowId))
-    throw Error(`Cannot resume workflow "${workflowId}": termination is in progress`);
-}
-function commitSerializedResumeState(internals, args) {
-  const {
-    workflowId,
-    resumeCheckpoint,
-    serializedCheckpoint,
-    registeredVersionTuple,
-    restoredHead,
-    callbacks
-  } = args;
-  internals.checkpoints.set(workflowId, resumeCheckpoint);
-  rememberCommittedCheckpointBytes(internals, workflowId, serializedCheckpoint);
-  internals.workflowVersionTuples.set(workflowId, registeredVersionTuple);
-  internals.eventLogHeads.set(workflowId, restoredHead);
-  setWorkflowStartHeaders(internals, workflowId, args.workflowStartHeaders, callbacks);
-  internals.parkedInlineWorkflows.delete(workflowId);
-}
-async function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
-  const { workflowId, resumeCheckpoint, registration, callbacks } = args, accumulatedResults = new Map(resumeCheckpoint.accumulatedResults), workflowAbort = new AbortController;
-  resetCancelHandlers(internals, workflowId);
-  await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
-  const context = new Context({
-    workflowId,
-    ...latestState.workflowExecutionToken !== void 0 && {
-      workflowExecutionToken: latestState.workflowExecutionToken
-    },
-    workflowType: latestState.type,
-    startedAt: getWorkflowExecutionStartedAt(latestState),
-    abortController: workflowAbort,
-    getNow: internals.options.getNow,
-    resolveWorkflowType: callbacks.resolveWorkflowTypeTarget,
-    executionStateOwnerId: latestState.executionStateOwnerId ?? workflowId,
-    accumulatedResults,
-    locals: resumeCheckpoint.locals,
-    searchAttributes: resumeCheckpoint.searchAttributes,
-    registerCancelHandler: createCancelHandlerRegistration(internals, workflowId),
-    ...registration.searchAttributes && {
-      searchAttributeSchema: registration.searchAttributes
-    },
-    sleepReferenceTime: resumeCheckpoint.createdAt,
-    ...latestState.executionDeadline !== void 0 && {
-      deadline: latestState.executionDeadline
-    },
-    services: internals.workflowServices.get(workflowId),
-    ...internals.options.onLog != null && { logSink: internals.options.onLog }
-  });
-  setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
-  if (internals.options.development)
-    context.explain(!0);
-  const generator = registration.handler(context, latestState.input), inlineStrategy = internals.inlineStrategy;
-  inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
-  inlineStrategy.continueWorkflow(workflowId, void 0);
-}
-async function relaunchWorkerWorkflowAfterResume(internals, latestState, args) {
-  const { workflowId, resumeCheckpoint, workflowStartHeaders, callbacks } = args;
-  resetCancelHandlers(internals, workflowId);
-  await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
-  const serialized = serializeCheckpoint(resumeCheckpoint);
-  internals.strategy.startWorkflow({
-    workflowId,
-    ...latestState.workflowExecutionToken !== void 0 && {
-      workflowExecutionToken: latestState.workflowExecutionToken
-    },
-    workflowType: latestState.type,
-    input: latestState.input,
-    checkpoint: serialized,
-    nestingDepth: internals.workflowNestingDepths.get(workflowId) ?? 0,
-    executionStateOwnerId: latestState.executionStateOwnerId ?? workflowId,
-    ...latestState.executionDeadline !== void 0 && {
-      deadline: latestState.executionDeadline
-    },
-    ...workflowStartHeaders !== void 0 && workflowStartHeaders.size > 0 && {
-      headers: [...workflowStartHeaders]
-    }
-  });
-}
-async function performSerializedResume(internals, args) {
-  const { workflowId } = args;
-  assertResumeNotTerminating(internals, workflowId);
-  const latestState = await loadWorkflowState(internals, workflowId);
-  assertResumeNotTerminating(internals, workflowId);
-  if (!latestState)
-    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"`);
-  await reactivateSuspendedWorkflowState(internals, latestState);
-  commitSerializedResumeState(internals, args);
-  if (internals.inlineStrategy) {
-    await relaunchInlineWorkflowAfterResume(internals, latestState, args);
-    return;
-  }
-  await relaunchWorkerWorkflowAfterResume(internals, latestState, args);
-}
-async function reactivateSuspendedWorkflowState(internals, state) {
-  if (state.status !== "suspended")
-    return;
-  const previousState = { ...state };
-  state.status = "running";
-  state.updatedAt = internals.options.getNow();
-  await commitFencedEngineWrite(internals, state.id, [
-    { type: "put", key: KEYS.workflow(state.id), value: encode(state) },
-    ...buildWorkflowVisibilityIndexTransition(state.id, previousState, state).batchOps,
-    ...state.executionDeadline !== void 0 ? buildTimerBatchOperations({
-      id: `deadline:${state.id}`,
-      workflowId: state.id,
-      fireAt: state.executionDeadline,
-      kind: "execution-deadline"
-    }) : []
-  ], [], () => Error(`Resume of workflow "${state.id}" lost its CAS race.`));
-}
-export async function resumeWorkflowFromStorage(internals, workflowId, dispatchResumedEvent, callbacks, onRecoveredWorkflow) {
+  acquireStandaloneClaimBeforeResume,
+  releaseFreshlyAcquiredResumeClaim
+} from "./standalone-claim-acquire.js";
+function recordFreshClaimEpoch(acquireResult, tracker) {
+  if (acquireResult.freshlyAcquired && tracker !== void 0)
+    tracker.epoch = acquireResult.epoch;
+}
+async function releaseFreshClaimOnRejectionUnlessDeferred(internals, workflowId, acquireResult, deferRelease) {
+  if (acquireResult.freshlyAcquired && deferRelease !== !0)
+    await releaseFreshlyAcquiredResumeClaim(internals, workflowId, acquireResult.epoch);
+}
+export async function resumeWorkflowFromStorage(internals, workflowId, dispatchResumedEvent, callbacks, onRecoveredWorkflow, options) {
   const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
   if (!stateBytes)
     throw Error(`Workflow "${workflowId}" not found in storage`);
   const state = decodeWorkflowState(stateBytes);
   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);
-  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();
-  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);
-  if (shouldStop)
-    return handle;
-  await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
-    workflowId,
-    resumeCheckpoint,
-    serializedCheckpoint: preparedResumeState.serializedCheckpoint,
-    registeredVersionTuple,
-    restoredHead,
-    workflowStartHeaders,
-    registration,
-    callbacks
-  }));
-  if (dispatchResumedEvent)
-    callbacks.dispatchEvent(new WorkflowResumedEvent(workflowId, resumeCheckpoint.step));
-  if (internals.inlineStrategy)
-    callbacks.swallowPromiseRejection(callbacks.processPendingUpdatesAfterInlineAdvance(workflowId));
-  return handle;
+  const acquireResult = await acquireStandaloneClaimBeforeResume(internals, workflowId);
+  recordFreshClaimEpoch(acquireResult, options?.freshClaimTracker);
+  try {
+    return await performResumeAfterClaimAcquired(internals, workflowId, state, dispatchResumedEvent, callbacks, onRecoveredWorkflow);
+  } catch (error) {
+    await releaseFreshClaimOnRejectionUnlessDeferred(internals, workflowId, acquireResult, options?.deferClaimReleaseOnRejection);
+    throw error;
+  }
 }

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

@@ -10,7 +10,7 @@
  *
  * Deliberately covers `running` and `suspended` the same way. The ADR
  * describes `suspended` as folding `acquire` into the status flip itself
- * (`reactivateSuspendedWorkflowState`'s commit in `resume.ts`), but the
+ * (`reactivateSuspendedWorkflowState`'s commit in `resume-body.ts`), but the
  * EARLIER fenced writes above need a held claim regardless of final status,
  * so one early standalone acquire is the pragmatic shape for both — a
  * documented deviation from that row, not an oversight.
@@ -27,7 +27,85 @@
  * re-check (it can win the CAS against a still-valid claim), so only the
  * durable holder is re-read (no write) and compared.
  *
+ * **`'holder-absent'` falls through to a fresh `acquire()` instead of hard-
+ * failing (WFT-134).** `suspendWorkflow`'s external terminal rotation
+ * durably deletes `wf-owner-holder:<id>` as part of its suspend commit, which
+ * can outpace this engine's own local cache correction
+ * (`WorkflowClaimRegistry.forgetLocalClaim`). A same-engine `resume()`
+ * landing in that gap must not be treated as a real conflict — it is
+ * exactly the "no other holder to lose to" case a fresh `acquire()` handles
+ * safely. `'holder-undecodable'` and `'generation-mismatch'` remain hard
+ * failures: both mean a holder record IS present and either corrupt or
+ * naming a different generation, a real conflict this function must not
+ * paper over.
+ *
  * @module core/engine/lifecycle/standalone-claim-acquire
  */
 import type { EngineInternals } from '../internals.ts';
-export declare function acquireStandaloneClaimBeforeResume(internals: EngineInternals, workflowId: string): Promise<void>;
+/**
+ * Result of {@link acquireStandaloneClaimBeforeResume}. `freshlyAcquired:
+ * true` means this call itself performed a fresh `registry.acquire()`
+ * (whether because no claim was cached yet, or because the `'holder-absent'`
+ * fallback below ran), and carries the exact `epoch` that acquire minted —
+ * `freshlyAcquired: false` means no acquisition happened at all (folding
+ * disabled, no registry, or the cached claim matched). Callers use this to
+ * know whether, and under which exact generation, THEY are now responsible
+ * for releasing a claim this call just installed if the resume they were
+ * preparing turns out not to be resumable after all — see `resume.ts`'s
+ * `resumeWorkflowFromStorage` (WFT-134).
+ */
+export type StandaloneClaimAcquireResult = {
+    freshlyAcquired: true;
+    epoch: number;
+} | {
+    freshlyAcquired: false;
+};
+export declare function acquireStandaloneClaimBeforeResume(internals: EngineInternals, workflowId: string): Promise<StandaloneClaimAcquireResult>;
+/**
+ * Best-effort durable release of a claim {@link acquireStandaloneClaimBeforeResume}
+ * freshly acquired for THIS resume attempt, called when a later, status-aware
+ * check (`performSerializedResume`'s status/generation re-validation in
+ * `resume-body.ts`) rejects the resume after all (WFT-134). Without this, a claim
+ * acquired for a workflow that turned out to be non-resumable — already
+ * terminal, or replaced by an `onTerminalConflict: 'start-new'` run — stays
+ * installed: the renewal task keeps refreshing it indefinitely, and a
+ * legitimate `start-new` (or the replacement run's own fold-acquire) loses
+ * its CAS against a claim nothing is actually driving.
+ *
+ * `acquiredEpoch` MUST be the exact epoch {@link acquireStandaloneClaimBeforeResume}
+ * returned to this same caller — passed straight through to
+ * `WorkflowClaimRegistry.release()`'s own `expectedEpoch` guard (WFT-134
+ * review round 2). Between this resume's acquire and its rejection, a
+ * DIFFERENT `start-new` or resume can legitimately replace the registry's
+ * entry for `workflowId`; releasing "whatever is current" instead of this
+ * exact generation would drop that replacement's live claim and strand it
+ * without local epoch bytes. `release()` no-ops (`'not-held'`) when the
+ * registry has moved past `acquiredEpoch`, so this call is always safe to
+ * make regardless of what has happened to the entry since.
+ *
+ * A full durable `release()`, not a local-only `forgetLocalClaim()`: the
+ * acquire this undoes durably wrote BOTH `wf-owner-epoch:<id>` and
+ * `wf-owner-holder:<id>`, and it is specifically the durable holder record
+ * that would otherwise block a legitimate replacement's own acquire — merely
+ * clearing this engine's local cache would leave that durable block in place.
+ * Swallows a lost-race/thrown release the same way every other best-effort
+ * claim release in this codebase does (see `complete.ts`'s
+ * `releaseWorkflowClaimAfterTerminalSettlement`): a failed release here just
+ * leaves the claim for TTL/grace expiry, never worse than not attempting it.
+ * `release()` itself already forgets its LOCAL entry on a thrown durable
+ * error (identity/epoch-guarded), so this call needs no matching cleanup of
+ * its own to stop the renewal task from renewing a claim nothing drives.
+ */
+export declare function releaseFreshlyAcquiredResumeClaim(internals: EngineInternals, workflowId: string, acquiredEpoch: number): 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,11 +1,12 @@
+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) {
   if (internals.options.ownershipMode !== "workflow-lease")
-    return;
+    return { freshlyAcquired: !1 };
   const registry = internals.workflowClaimRegistry;
   if (registry === null)
-    return;
+    return { freshlyAcquired: !1 };
   const cachedEpoch = registry.currentEpoch(workflowId);
   if (cachedEpoch !== null) {
     const check = await wakeOwnershipCheck({
@@ -15,11 +16,26 @@ export async function acquireStandaloneClaimBeforeResume(internals, workflowId)
       expectedEngineId: registry.engineId,
       expectedEpoch: cachedEpoch
     });
-    if (check.status === "discarded")
+    if (check.status === "match")
+      return { freshlyAcquired: !1 };
+    if (check.reason !== "holder-absent")
       throw new WorkflowClaimUnavailableError(workflowId, check.observedEngineId);
-    return;
   }
   const result = await registry.acquire(workflowId);
   if (result.status === "lost-race")
     throw new WorkflowClaimUnavailableError(workflowId, result.heldBy);
+  return { freshlyAcquired: !0, epoch: result.epoch };
+}
+export async function releaseFreshlyAcquiredResumeClaim(internals, workflowId, acquiredEpoch) {
+  const registry = internals.workflowClaimRegistry;
+  if (registry === null)
+    return;
+  try {
+    await registry.release(workflowId, acquiredEpoch);
+  } catch {}
+}
+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,17 @@ 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;
+    /** ADDITIONAL WFT-153 precondition on observed `wf-gen:<id>` bytes; see `StartDuplicateIdDecision.duplicateIdGenerationCondition` in `start-terminal-conflict-purge.ts`. Undefined exactly when `duplicateIdCondition` is. */
+    duplicateIdGenerationCondition: 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, sources) {
+  for (const entry of conditions) {
+    if (!sources.includes(entry.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,14 @@ function tagStartPreconditions(conditions) {
     condition
   }));
 }
+function tagDuplicateIdConditions(condition, generationCondition) {
+  const tagged = [];
+  if (condition !== void 0)
+    tagged.push({ source: "duplicate-id", condition });
+  if (generationCondition !== void 0)
+    tagged.push({ source: "duplicate-id-generation", condition: generationCondition });
+  return tagged;
+}
 function tagWorkflowConcurrencyConditions(conditions) {
   return conditions.map((condition) => ({
     source: "workflow-concurrency",
@@ -66,18 +100,26 @@ 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 ?? [])
+      ...tagDuplicateIdConditions(context.duplicateIdCondition, context.duplicateIdGenerationCondition),
+      ...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",
+      "duplicate-id-generation"
+    ]))
+      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