@lostgradient/weft 0.24.0 → 0.24.2

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-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-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,55 @@
+/**
+ * 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 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,
+ * 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.`);
+}

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

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

@@ -0,0 +1,16 @@
+/**
+ * Build the initial in-memory {@link WorkflowState} and {@link Checkpoint}
+ * for a fresh `start()` — split out of `start.ts`, which has no headroom
+ * under the repository's 500-line implementation-file ceiling for this
+ * logic inline.
+ *
+ * @module core/engine/lifecycle/start-state
+ */
+import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
+import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+export declare function parseStartOptionDuration(_internals: EngineInternals, duration: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter', _callbacks: LifecycleCallbacks): number;
+export declare function createInitialWorkflowState(internals: EngineInternals, workflowId: string, type: string, input: unknown, versionTuple: WorkflowVersionTuple, revision: string, options: StartOptions | undefined, tags: string[] | undefined, executionStateOwnerId: string | undefined, parentWorkflowId: string | undefined, parentWorkflowExecutionToken: string | undefined, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
+export declare function createInitialCheckpoint(internals: EngineInternals, workflowId: string, workflowVersion: string, options: StartOptions | undefined, _callbacks: LifecycleCallbacks): Checkpoint;
+export declare function applyRestartLineage(state: WorkflowState, displacedState: WorkflowState | null): void;

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

@@ -0,0 +1,60 @@
+import { createCheckpoint } from "../../checkpoint.js";
+import { normalizeStorageTimestamp } from "../../scheduler.js";
+import {
+  StartWorkflowValidationError,
+  parseStartWorkflowDuration
+} from "../../start-workflow-validation.js";
+export function parseStartOptionDuration(_internals, duration, fieldName, _callbacks) {
+  return parseStartWorkflowDuration(duration, fieldName);
+}
+function buildInitialIdentitySlice(workflowId, type, input, versionTuple, revision, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags) {
+  return {
+    id: workflowId,
+    type,
+    status: delayedStartTimer ? "pending" : "running",
+    input,
+    versionTuple,
+    revision,
+    workflowExecutionToken: crypto.randomUUID(),
+    ...executionStateOwnerId !== void 0 && { executionStateOwnerId },
+    ...parentWorkflowId !== void 0 && { parentWorkflowId },
+    ...parentWorkflowExecutionToken !== void 0 && { parentWorkflowExecutionToken },
+    createdAt: now,
+    ...!delayedStartTimer && { startedAt: now },
+    updatedAt: now,
+    ...tags !== void 0 && { tags }
+  };
+}
+function resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks) {
+  if (options?.executionTimeout === void 0 || delayedStartTimer)
+    return;
+  const executionTimeoutMilliseconds = parseStartOptionDuration(internals, options.executionTimeout, "options.executionTimeout", callbacks);
+  try {
+    return normalizeStorageTimestamp(now + executionTimeoutMilliseconds, "options.executionTimeout");
+  } catch {
+    throw new StartWorkflowValidationError("options.executionTimeout must resolve to a finite, non-negative deadline");
+  }
+}
+export function createInitialWorkflowState(internals, workflowId, type, input, versionTuple, revision, options, tags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks) {
+  const now = internals.options.getNow(), state = buildInitialIdentitySlice(workflowId, type, input, versionTuple, revision, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags), executionDeadline = resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks);
+  if (executionDeadline !== void 0)
+    state.executionDeadline = executionDeadline;
+  return state;
+}
+export function createInitialCheckpoint(internals, workflowId, workflowVersion, options, _callbacks) {
+  const checkpoint = createCheckpoint(workflowId, workflowVersion, internals.options.getNow());
+  if (options?.searchAttributes)
+    checkpoint.searchAttributes = { ...options.searchAttributes };
+  return checkpoint;
+}
+export function applyRestartLineage(state, displacedState) {
+  if (displacedState === null)
+    return;
+  state.restartedFrom = {
+    workflowId: displacedState.id,
+    ...displacedState.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: displacedState.workflowExecutionToken
+    },
+    replacedAt: state.createdAt
+  };
+}

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

@@ -1,7 +1,91 @@
-import type { BatchOperation } from '../../../storage/interface.ts';
+import type { BatchOperation, ConditionalBatchCondition } from '../../../storage/interface.ts';
 import type { StartWorkflowOptions, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
+/**
+ * What the duplicate-id read decided about a caller-supplied workflow id.
+ */
+export type StartDuplicateIdDecision = {
+    /** A prior terminal run this start will displace, or `null` for a fresh id. */
+    terminalRunToPurge: WorkflowState | null;
+    /**
+     * Compare-and-swap precondition that makes the duplicate-id check atomic with
+     * the create commit (WFT-152).
+     *
+     * The check below reads `KEYS.workflow(workflowId)` and decides whether the id
+     * is free, but that read and the create batch are separated by every build step
+     * in between. Within ONE engine `pendingStarts` holds the id across that window;
+     * two engines sharing a store share no such memory, so both previously committed
+     * blind and the second silently overwrote the first — leaving the loser with a
+     * run whose terminal transition happens on the other engine and therefore never
+     * settles its `result()` waiter. Conditioning the batch on the exact value seen
+     * here collapses that window: the loser's batch does not commit, and
+     * `buildAndCommitStartBatch` surfaces {@link WorkflowAlreadyExistsError} — the
+     * same error the in-engine `pendingStarts` guard already throws for the same
+     * collision.
+     *
+     * `expectedValue` is the RAW observed bytes, deliberately not a re-encoding of
+     * the decoded state: re-encoding is not guaranteed to round-trip byte-identically,
+     * and a condition built from one would fail against a record nothing had touched.
+     * `null` (id absent) and a prior terminal run's bytes (an
+     * `onTerminalConflict: 'start-new'` restart) are both valid expected values, so a
+     * restart is equally protected against a concurrent engine displacing the same
+     * terminal run.
+     *
+     * No `conditionalBatch` capability gate is needed. Reaching this code means a
+     * workflow is registered, and registration drains through
+     * `WorkflowCatalog#activateRegistered`, which already hard-requires that
+     * capability at `Engine.create()`. A store that cannot honour this condition
+     * cannot host an engine that could start a workflow in the first place.
+     *
+     * RESOLVED (PR #959 review; closed by WFT-153). This condition alone compares
+     * only a VALUE, so on its own it cannot distinguish "this id was never used"
+     * from "a run existed here and was purged" — a racing winner that commits,
+     * completes, and is purged (or swept by retention) before this batch commits
+     * would make `wf:<id>` absent again, matching `expectedValue: null`. That gap
+     * is now closed by {@link duplicateIdGenerationCondition} below, an ADDITIONAL
+     * condition on a durable per-id generation counter a purge bumps but never
+     * resets — see its own doc for the mechanism.
+     */
+    duplicateIdCondition: ConditionalBatchCondition;
+    /**
+     * ADDITIONAL compare-and-swap precondition on the observed `wf-gen:<id>`
+     * bytes, closing the residual ABA hole {@link duplicateIdCondition} cannot
+     * detect (WFT-153, following WFT-152). `duplicateIdCondition` compares a
+     * VALUE, so it cannot tell "this id was never used" from "a run existed
+     * here and was purged" — if a racing winner completes and is purged before
+     * this batch commits, `wf:<id>` looks absent again and `duplicateIdCondition`
+     * alone would match. `wf-gen:<id>` is bumped in the SAME atomic batch that
+     * deletes `wf:<id>` on purge (`workflow-generation-fence.ts`) and is never
+     * otherwise touched, so a purge landing in the read-to-commit gap changes
+     * this key even though `wf:<id>` reads the same — the stale loser's
+     * condition on the pre-purge generation bytes fails where the value-only
+     * comparison could not detect it. See `storage/generation-keys.ts`.
+     */
+    duplicateIdGenerationCondition: ConditionalBatchCondition;
+    /**
+     * The exact `wf-gen:<id>` bytes {@link duplicateIdGenerationCondition} was
+     * built from, threaded through to {@link prepareTerminalRunPurge} so a
+     * `'start-new'` restart's own displacing purge bumps the generation from
+     * this SAME observed value rather than a second, independent read. This is
+     * what makes the restart's own CAS trivially self-consistent — it can never
+     * fence itself out on its own legitimate restart, because the value it
+     * bumps from is exactly the value its own precondition checks.
+     */
+    observedGenerationBytes: Uint8Array | null;
+};
+/**
+ * The decision for a start whose id was GENERATED rather than caller-supplied. A
+ * v4 UUID is effectively unique, so the duplicate-id read is skipped entirely and
+ * there is no observed value to condition on — the start keeps the unconditioned
+ * single-write hot path.
+ */
+export declare const GENERATED_ID_START_DECISION: {
+    readonly terminalRunToPurge: null;
+    readonly duplicateIdCondition: undefined;
+    readonly duplicateIdGenerationCondition: undefined;
+    readonly observedGenerationBytes: null;
+};
 /**
  * Decide what a caller-supplied workflow id that already has a persisted record
  * means, WITHOUT performing any destructive action. Only invoked when the caller
@@ -23,9 +107,58 @@ import { type LifecycleCallbacks } from './shared.ts';
  *   delete the finalizer payload before the resource is torn down, leaking it, so
  *   the restart is refused until teardown settles (which clears the marker).
  *
- * Returns `null` when there is no existing record (the create proceeds normally).
+ * This read is only a point-in-time observation: another engine sharing the store
+ * can commit a create for the same id in the window between it and the create
+ * batch. The returned {@link StartDuplicateIdDecision} therefore carries a
+ * `duplicateIdCondition` holding the exact bytes seen here, so that batch can be
+ * conditioned on them — turning that window into a lost compare-and-swap rather
+ * than a blind overwrite (WFT-152). It also reads `wf-gen:<id>` in the SAME pass
+ * and carries `duplicateIdGenerationCondition`/`observedGenerationBytes` (WFT-153),
+ * closing the residual ABA window a value-only condition cannot detect — see that
+ * field's own doc.
  */
-export declare function resolveTerminalConflictForRestart(internals: EngineInternals, workflowId: string, options: StartWorkflowOptions | undefined): Promise<WorkflowState | null>;
+export declare function resolveTerminalConflictForRestart(internals: EngineInternals, workflowId: string, options: StartWorkflowOptions | undefined): Promise<StartDuplicateIdDecision>;
+/**
+ * The `'reattach-only'`/`'bulk-retry-only'` fence for `startWorkflow`'s
+ * `skipAdmissionIdCheck` parameter (WFT-95 TOCTOU fix). Call immediately
+ * after {@link resolveTerminalConflictForRestart} resolves.
+ *
+ * Both call sites reach `startWorkflow` after a separate, non-atomic read
+ * confirmed an already-persisted record they mean to replay or replace — but
+ * that confirmation and `resolveTerminalConflictForRestart`'s own atomic read
+ * are not the same read:
+ *
+ * - `dispatchChildWorkflowStart()`'s crash-reattach retry confirms a matching
+ *   persisted child via `loadWorkflowState()`, then leaves
+ *   `options.onTerminalConflict` unset — so `resolveTerminalConflictForRestart`
+ *   either finds the record still there (throws {@link WorkflowAlreadyExistsError},
+ *   this function is never reached: the expected, unraced reattach) or gone
+ *   (`terminalRunToPurge: null`, the ordinary fresh-create branch).
+ * - `retryFailedWorkflow()`'s checkpoint-absent fallback (`bulk-operations-retry.ts`)
+ *   confirms a `failed` record via its own `loadWorkflowState()`, then always
+ *   sets `options.onTerminalConflict: 'start-new'` — so
+ *   `resolveTerminalConflictForRestart` either finds the SAME terminal record
+ *   still there (returns its bytes as `terminalRunToPurge`, the expected,
+ *   unraced purge-and-replace) or finds it gone (`terminalRunToPurge: null`,
+ *   the same ordinary fresh-create branch).
+ *
+ * Under `ownership: 'workflow-lease'`, another engine can purge the matched
+ * record in the window between either call site's own confirmation read and
+ * `resolveTerminalConflictForRestart`'s. Being called with a `'reattach-only'`
+ * or `'bulk-retry-only'` `skipAdmissionIdCheck` and a `null` `terminalRunToPurge`
+ * therefore means the race happened: there is nothing left to reattach to or
+ * replace, so this re-runs strict admission rather than let a bypassed
+ * `.`/`..` id fall through into a genuinely fresh create. `coerceStartWorkflowId`
+ * throws the same `StartWorkflowValidationError` strict admission would have
+ * thrown on the caller's very first (non-retry) attempt — a clean,
+ * deterministic rejection instead of a silently created reserved-id run.
+ *
+ * A no-op for every other `skipAdmissionIdCheck` value: `true` (schedule
+ * drain) applies unconditionally and never calls this, and `undefined`
+ * (every public start surface) already went through strict admission in
+ * `prepareStartWorkflow`.
+ */
+export declare function enforceReplayOnlyIdFence(skipAdmissionIdCheck: boolean | 'reattach-only' | 'bulk-retry-only' | undefined, workflowId: string, terminalRunToPurge: WorkflowState | null): void;
 /**
  * Prepare a prior terminal run for displacement by a `'start-new'` restart WITHOUT
  * committing the destructive delete. Returns the storage delete operations (for the
@@ -35,5 +168,14 @@ export declare function resolveTerminalConflictForRestart(internals: EngineInter
  * entries. `clearPurgedWorkflowInMemoryState` runs `cleanupWaiters` to settle the
  * old run's pending signal/update/sleep waiters; it only needs
  * `swallowPromiseRejection`, which `LifecycleCallbacks` already exposes.
+ *
+ * Also appends the `wf-gen:<id>` bump PUT operation (WFT-153), built from
+ * `observedGenerationBytes` — the SAME bytes `resolveTerminalConflictForRestart`
+ * already read for `duplicateIdGenerationCondition` — rather than a second,
+ * independent read. Reusing that one observed value for both the outer CAS
+ * condition and the bump amount is what makes this restart's own commit
+ * trivially self-consistent: it can never fence itself out on its own
+ * legitimate restart, because the value it bumps from is exactly the value its
+ * own precondition checks (see `duplicateIdGenerationCondition`'s doc).
  */
-export declare function prepareTerminalRunPurge(internals: EngineInternals, state: WorkflowState, callbacks: LifecycleCallbacks): Promise<BatchOperation[]>;
+export declare function prepareTerminalRunPurge(internals: EngineInternals, state: WorkflowState, callbacks: LifecycleCallbacks, observedGenerationBytes: Uint8Array | null): Promise<BatchOperation[]>;

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

@@ -1,4 +1,5 @@
 import { KEYS, storageHas } from "../../../storage/interface.js";
+import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
 import {
   clearPurgedWorkflowInMemoryState,
   collectWorkflowPurgeDeleteOperations
@@ -6,10 +7,28 @@ import {
 import { WorkflowAlreadyExistsError, WorkflowTeardownPendingError } from "../errors.js";
 import { cleanupWaiters } from "../termination/cleanup.js";
 import { decodeWorkflowState, isTerminalWorkflowStatus } from "../validation.js";
+import { buildWorkflowGenerationBumpOperation } from "../workflow-generation-fence.js";
+export const GENERATED_ID_START_DECISION = {
+  terminalRunToPurge: null,
+  duplicateIdCondition: void 0,
+  duplicateIdGenerationCondition: void 0,
+  observedGenerationBytes: null
+};
 export async function resolveTerminalConflictForRestart(internals, workflowId, options) {
-  const existingBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  const key = KEYS.workflow(workflowId), generationKey = KEYS.workflowGeneration(workflowId), [existingBytes, observedGenerationBytes] = await Promise.all([
+    internals.storage.get(key),
+    internals.storage.get(generationKey)
+  ]), duplicateIdGenerationCondition = {
+    key: generationKey,
+    expectedValue: observedGenerationBytes
+  };
   if (existingBytes === null)
-    return null;
+    return {
+      terminalRunToPurge: null,
+      duplicateIdCondition: { key, expectedValue: null },
+      duplicateIdGenerationCondition,
+      observedGenerationBytes
+    };
   if (options?.onTerminalConflict !== "start-new")
     throw new WorkflowAlreadyExistsError(workflowId);
   const existingState = decodeWorkflowState(existingBytes);
@@ -17,12 +36,22 @@ export async function resolveTerminalConflictForRestart(internals, workflowId, o
     throw new WorkflowAlreadyExistsError(workflowId);
   if (await storageHas(internals.storage, KEYS.teardownOwed(workflowId)))
     throw new WorkflowTeardownPendingError(workflowId);
-  return existingState;
+  return {
+    terminalRunToPurge: existingState,
+    duplicateIdCondition: { key, expectedValue: existingBytes },
+    duplicateIdGenerationCondition,
+    observedGenerationBytes
+  };
 }
-export async function prepareTerminalRunPurge(internals, state, callbacks) {
+export function enforceReplayOnlyIdFence(skipAdmissionIdCheck, workflowId, terminalRunToPurge) {
+  if ((skipAdmissionIdCheck === "reattach-only" || skipAdmissionIdCheck === "bulk-retry-only") && terminalRunToPurge === null)
+    coerceStartWorkflowId(workflowId, "options.id");
+}
+export async function prepareTerminalRunPurge(internals, state, callbacks, observedGenerationBytes) {
   const cleanupWaitersForStart = (id) => cleanupWaiters(internals, id, {
     swallowPromiseRejection: callbacks.swallowPromiseRejection
   }), deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state);
+  deleteOperations.push(buildWorkflowGenerationBumpOperation(state.id, observedGenerationBytes));
   clearPurgedWorkflowInMemoryState(internals, state.id, cleanupWaitersForStart);
   return deleteOperations;
 }