@lostgradient/weft 0.24.1 → 0.24.2

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

@@ -1,4 +1,47 @@
-import { type WorkflowHandle } from '../handles.ts';
+/**
+ * `engine.resume(id)` / `recoverAll()`'s standalone-replay-from-storage entry
+ * point. The actual work — load tracking/checkpoint/registration state,
+ * prepare the resume, and relaunch inline or in a worker — lives in
+ * `resume-body.ts`'s `performResumeAfterClaimAcquired` (split out to stay
+ * under this repository's 500-line implementation-file ceiling once the
+ * WFT-134 claim-release wrapping below was added). This file's own job is
+ * just: load and validate state, acquire a claim if this run doesn't already
+ * hold one, and release a claim it freshly acquired if the resume turns out
+ * not to succeed after all — UNLESS `options.deferClaimReleaseOnRejection`
+ * asks this call to leave that claim installed for its caller instead (see
+ * {@link ResumeFromStorageOptions}).
+ *
+ * @module core/engine/lifecycle/resume
+ */
+import type { WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
-import { type LifecycleCallbacks, type RecoverAllOptions } from './shared.ts';
-export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow']): Promise<WorkflowHandle>;
+import type { LifecycleCallbacks, RecoverAllOptions } from './shared.ts';
+/**
+ * An out-parameter this call populates with the epoch of a claim it freshly
+ * acquired, so a caller using `deferClaimReleaseOnRejection` can release that
+ * EXACT generation itself once it is done using it (WFT-134 review round 2,
+ * issue D). Left at `{ epoch: null }` when no fresh acquisition happened —
+ * folding disabled, no registry, the cached claim matched, or acquisition
+ * itself threw `WorkflowClaimUnavailableError` before returning.
+ */
+export type FreshResumeClaimTracker = {
+    epoch: number | null;
+};
+/** Options for {@link resumeWorkflowFromStorage}. */
+export type ResumeFromStorageOptions = {
+    /**
+     * `true` for `recoverAll()`'s per-entry recovery loop (WFT-134 issue D):
+     * its own `recoverEntryOrIsolateFailure` isolates several errors into a
+     * fenced `failWorkflowForXxx()` commit that needs a freshly-acquired claim
+     * to still be installed, so this call must NOT release on rejection —
+     * instead it records the acquired epoch in `freshClaimTracker` and lets the
+     * caller release once its own isolated-failure handling is done. Default
+     * (`false`/omitted) is correct for an explicit `engine.resume()` caller,
+     * which has nothing further to do with the claim and must release
+     * immediately on any rejection.
+     */
+    deferClaimReleaseOnRejection?: boolean;
+    /** Populated with the freshly-acquired epoch, if any — see {@link FreshResumeClaimTracker}. */
+    freshClaimTracker?: FreshResumeClaimTracker;
+};
+export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow'], options?: ResumeFromStorageOptions): Promise<WorkflowHandle>;

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

@@ -1,220 +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 { resolveExecutableRegistrationOrRenamedNotFound } from "../dynamic-source-execution.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 { assertSameGeneration, deriveResumeGeneration } from "./resume-generation-guard.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, 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({
-    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, resolvedRevision, callbacks } = args;
-  internals.workflowTypeByWorkflowId.set(workflowId, {
-    type: latestState.type,
-    revision: resolvedRevision
-  });
-  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"`);
-  assertSameGeneration(workflowId, latestState, args.expectedGeneration);
-  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);
-  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), { 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), { 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,
-    resolvedRevision,
-    expectedGeneration: deriveResumeGeneration(state),
-    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/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,10 +27,76 @@
  * 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

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

@@ -3,10 +3,10 @@ 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({
@@ -16,13 +16,23 @@ 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);

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

@@ -59,6 +59,8 @@ export type StartBatchContext = {
      * 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

@@ -49,9 +49,9 @@ 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 hasStartConditionConflict(internals, conditions, source) {
+async function hasStartConditionConflict(internals, conditions, sources) {
   for (const entry of conditions) {
-    if (entry.source !== source)
+    if (!sources.includes(entry.source))
       continue;
     const currentValue = await internals.storage.get(entry.condition.key);
     if (!storageValuesEqual(currentValue, entry.condition.expectedValue))
@@ -75,8 +75,13 @@ function tagStartPreconditions(conditions) {
     condition
   }));
 }
-function tagDuplicateIdCondition(condition) {
-  return condition === void 0 ? [] : [{ source: "duplicate-id", 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) => ({
@@ -97,21 +102,24 @@ export async function buildAndCommitStartBatch(context, buildIdempotentStartOper
     lastWorkflowConcurrencyStateKey = workflowConcurrency?.stateKey ?? lastWorkflowConcurrencyStateKey;
     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),
-      ...tagDuplicateIdCondition(context.duplicateIdCondition),
+      ...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 (outcome !== "claim-lost" && await hasStartConditionConflict(internals, conditions, "duplicate-id"))
+    if (outcome !== "claim-lost" && await hasStartConditionConflict(internals, conditions, [
+      "duplicate-id",
+      "duplicate-id-generation"
+    ]))
       throw new WorkflowAlreadyExistsError(workflowId);
-    if (await hasStartConditionConflict(internals, conditions, "start-precondition"))
+    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);
-    await attributeLostStartPreconditionOrRetry(workflowId, context.duplicateIdCondition !== void 0, workflowConcurrency !== void 0, () => hasStartConditionConflict(internals, conditions, "workflow-concurrency"));
+    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-or-signal-resolution.d.ts

@@ -41,11 +41,17 @@ export declare function resolveExistingRunOrThrowPurged(internals: EngineInterna
  * resolves it instead of racing it to a terminal-conflict). Only when the record is
  * absent do we wait for the reservation to clear and read once more to discriminate:
  *
- * - **record present** — the winner committed: signal it (or conflict if terminal)
- *   and return the handle.
+ * - **record present** — the winner committed: signal it (or conflict if terminal).
  * - **record absent after the reservation clears** — the winner aborted before
  *   committing (storage failure, oversized payload, throwing start interceptor): no
  *   run exists, so return `undefined` and let the caller retry its own create.
+ *
+ * Either terminal-conflict branch is checked against {@link wasSignalAcceptedByWinner}
+ * before throwing: a fast workflow can reach a terminal status between this
+ * loser's reads, entirely independent of how much slower or faster the winner's
+ * OWN commit path happens to be — so a same-`signalId` convergent caller (the
+ * documented "concurrent absent-target callers" contract) must not depend on
+ * catching the winner mid-flight to avoid a spurious conflict.
  */
 export declare function resolveCallerIdWinnerOrRetry(internals: EngineInternals, winnerId: string, signalSpec: StartOrSignalSignal, signalId: string, callbacks: StartOrSignalCallbacks, allowTerminalRestart?: boolean): Promise<WorkflowHandle | undefined>;
 /**

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

@@ -1,5 +1,5 @@
 import { sleep } from "../../../runtime/portable.js";
-import { KEYS } from "../../../storage/interface.js";
+import { KEYS, storageHas } from "../../../storage/interface.js";
 import { decode } from "../../codec.js";
 import { IdempotencyKeyPurgedError, StartOrSignalConflictError } from "../errors.js";
 import { loadWorkflowState } from "../storage-io.js";
@@ -23,6 +23,14 @@ async function awaitReservationCleared(internals, workflowId) {
     await sleep(RESERVATION_CLEAR_RETRY_DELAY_MS);
   }
 }
+async function wasSignalAcceptedByWinner(internals, workflowId, signalName, signalId) {
+  return storageHas(internals.storage, KEYS.signalAcceptedResponse(workflowId, signalName, signalId));
+}
+async function resolveTerminalConflictOrConvergence(internals, winnerId, status, signalSpec, signalId, callbacks) {
+  if (await wasSignalAcceptedByWinner(internals, winnerId, signalSpec.name, signalId))
+    return callbacks.getHandle(winnerId);
+  throw new StartOrSignalConflictError(winnerId, status);
+}
 export async function resolveCallerIdWinnerOrRetry(internals, winnerId, signalSpec, signalId, callbacks, allowTerminalRestart = !1) {
   const state = await loadWorkflowState(internals, winnerId);
   if (state !== null) {
@@ -31,7 +39,7 @@ export async function resolveCallerIdWinnerOrRetry(internals, winnerId, signalSp
       return callbacks.getHandle(winnerId);
     }
     if (!allowTerminalRestart)
-      throw new StartOrSignalConflictError(winnerId, state.status);
+      return resolveTerminalConflictOrConvergence(internals, winnerId, state.status, signalSpec, signalId, callbacks);
   }
   await awaitReservationCleared(internals, winnerId);
   const stateAfterReservation = await loadWorkflowState(internals, winnerId);
@@ -40,7 +48,7 @@ export async function resolveCallerIdWinnerOrRetry(internals, winnerId, signalSp
   if (isTerminalWorkflowStatus(stateAfterReservation.status)) {
     if (state !== null && isSameTerminalRun(state, stateAfterReservation))
       return;
-    throw new StartOrSignalConflictError(winnerId, stateAfterReservation.status);
+    return resolveTerminalConflictOrConvergence(internals, winnerId, stateAfterReservation.status, signalSpec, signalId, callbacks);
   }
   await callbacks.signalExistingWorkflow(winnerId, signalSpec.name, signalSpec.payload, signalId);
   return callbacks.getHandle(winnerId);

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

@@ -37,10 +37,16 @@
  * 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.
+ * The pre-compare-and-swap purge ABA — a winner purged between the read and the
+ * commit, making an absent record look never-used to a value-comparing condition
+ * alone — no longer reaches this function's elimination logic (WFT-153, closing
+ * the residual this comment used to describe as untracked). The caller now checks
+ * a SECOND, positive-evidence condition first (`'duplicate-id-generation'` in
+ * `buildAndCommitStartBatch`) on a durable per-id generation counter that a purge
+ * bumps but never resets, so that case throws `WorkflowAlreadyExistsError` before
+ * reaching here. This function still does not claim exclusive attribution for
+ * every conceivable cause — only that the two positively-detectable duplicate-id
+ * causes are ruled out ahead of it.
  *
  * With no concurrency evidence at all, fail closed: something missed, nothing
  * retryable explains it, and a spurious `WorkflowAlreadyExistsError` is public,

package/dist/core/engine/lifecycle/start-schedule-timing.d.ts

@@ -0,0 +1,11 @@
+import type { StartOptions } from '../../types.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+/**
+ * Resolve a start's effective delayed-start timestamp from
+ * `options.startAt`/`options.startAfter`, or `undefined` for an immediate
+ * start. Split out of `start.ts` to keep that file under the repository's
+ * line-count ceiling; this is a pure resolution step with no dependency on
+ * `startWorkflow`'s own reservation/commit state.
+ */
+export declare function resolveScheduledStartAt(internals: EngineInternals, options: StartOptions | undefined, submissionTime: number, callbacks: LifecycleCallbacks): number | undefined;

package/dist/core/engine/lifecycle/start-schedule-timing.js

@@ -0,0 +1,21 @@
+import { normalizeStorageTimestamp } from "../../scheduler.js";
+import {
+  assertExclusiveStartWorkflowOptions,
+  coerceStartWorkflowTimestamp,
+  StartWorkflowValidationError
+} from "../../start-workflow-validation.js";
+import { parseStartOptionDuration } from "./start-state.js";
+export function resolveScheduledStartAt(internals, options, submissionTime, callbacks) {
+  assertExclusiveStartWorkflowOptions(options?.startAt, options?.startAfter);
+  if (options?.startAt !== void 0)
+    return coerceStartWorkflowTimestamp(options.startAt, "options.startAt");
+  if (options?.startAfter !== void 0) {
+    const startAfterMilliseconds = parseStartOptionDuration(internals, options.startAfter, "options.startAfter", callbacks);
+    try {
+      return normalizeStorageTimestamp(submissionTime + startAfterMilliseconds, "options.startAfter");
+    } catch {
+      throw new StartWorkflowValidationError("options.startAfter must resolve to a finite, non-negative start time");
+    }
+  }
+  return;
+}