@lostgradient/weft 0.23.1 → 0.24.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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,65 @@
-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.
+     *
+     * KNOWN LIMITATION (PR #959 review). The condition compares a VALUE, so it cannot
+     * distinguish "this id was never used" from "a run existed here and was purged".
+     * If a racing winner commits, completes, and is purged or swept by retention
+     * before this batch commits, `wf:<id>` is absent again, `expectedValue: null`
+     * matches, and both starts execute. Closing that needs durable per-id generation
+     * or tombstone state a purge cannot restore — a new persisted mechanism, out of
+     * scope here. The window is narrow (a winner's whole lifecycle plus a purge inside
+     * one loser's read-to-commit gap) and the outcome is a duplicate run rather than
+     * the indefinite hang this fence exists to remove.
+     */
+    duplicateIdCondition: ConditionalBatchCondition;
+};
+/**
+ * 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;
+};
 /**
  * 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 +81,14 @@ 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).
  */
-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>;
 /**
  * Prepare a prior terminal run for displacement by a `'start-new'` restart WITHOUT
  * committing the destructive delete. Returns the storage delete operations (for the

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

@@ -6,10 +6,17 @@ import {
 import { WorkflowAlreadyExistsError, WorkflowTeardownPendingError } from "../errors.js";
 import { cleanupWaiters } from "../termination/cleanup.js";
 import { decodeWorkflowState, isTerminalWorkflowStatus } from "../validation.js";
+export const GENERATED_ID_START_DECISION = {
+  terminalRunToPurge: null,
+  duplicateIdCondition: void 0
+};
 export async function resolveTerminalConflictForRestart(internals, workflowId, options) {
-  const existingBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  const key = KEYS.workflow(workflowId), existingBytes = await internals.storage.get(key);
   if (existingBytes === null)
-    return null;
+    return {
+      terminalRunToPurge: null,
+      duplicateIdCondition: { key, expectedValue: null }
+    };
   if (options?.onTerminalConflict !== "start-new")
     throw new WorkflowAlreadyExistsError(workflowId);
   const existingState = decodeWorkflowState(existingBytes);
@@ -17,7 +24,10 @@ 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 }
+  };
 }
 export async function prepareTerminalRunPurge(internals, state, callbacks) {
   const cleanupWaitersForStart = (id) => cleanupWaiters(internals, id, {

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

@@ -1,13 +1,23 @@
 import type { BatchOperation } from '../../../storage/interface.ts';
-import type { Checkpoint, Duration, StartOptions, StartWorkflowOptions, TimerEntry, WorkflowState } from '../../types.ts';
-import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import type { StartOptions, StartWorkflowOptions } from '../../types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
 import { type BuildIdempotentStartOperations } from './start-commit.ts';
 export declare function start(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
-export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations): Promise<WorkflowHandle>;
+export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations, 
+/**
+ * A pinned schedule's forward-looking revision commitment (WFT-20),
+ * threaded from `ScheduleCallbacks.startWorkflow`'s own `revisionOverride`
+ * parameter. When supplied, this call resolves and reserves EXACTLY this
+ * revision (via {@link resolveAndReservePinnedExecutableRegistration},
+ * which enforces an exact-match check for an eager type rather than
+ * silently falling back to whatever is active) instead of the ordinary
+ * "whatever `resolveExecutableRegistration` currently resolves"
+ * admission path, and the persisted `WorkflowState.revision` is this
+ * value verbatim — never re-derived from `registeredCatalogRevisions`.
+ * `undefined` (the default, every non-schedule start) is byte-for-byte
+ * the pre-WFT-20 admission path.
+ */
+revisionOverride?: string): Promise<WorkflowHandle>;
 export declare function resolveScheduledStartAt(internals: EngineInternals, options: StartOptions | undefined, submissionTime: number, callbacks: LifecycleCallbacks): number | undefined;
-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, 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;