@lostgradient/weft 0.3.0 → 0.5.0

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

@@ -1,6 +1,7 @@
 import type { BatchOperation, ConditionalBatchCondition } from '../../../storage/interface.ts';
 import type { Checkpoint, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
+import type { WorkflowConcurrencyStartOperations } from '../workflow-concurrency.ts';
 import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
 /**
  * Builds the id-dependent operations and compare-and-swap preconditions for an
@@ -34,7 +35,15 @@ export type StartBatchContext = {
     delayedStartTimer: TimerEntry | undefined;
     persistedWorkflowStartHeaders: Map<string, string> | undefined;
     additionalStartOperations: BatchOperation[] | undefined;
+    buildWorkflowConcurrencyStartOperations: (() => Promise<WorkflowConcurrencyStartOperations | undefined>) | undefined;
     callbacks: LifecycleCallbacks;
+    /**
+     * Storage deletes for a prior terminal run being displaced by an
+     * `onTerminalConflict: 'start-new'` restart. Prepended ahead of the create puts
+     * so purge-and-recreate commit as one atomic batch (see
+     * {@link buildStartBatchOperations}). Undefined for an ordinary start.
+     */
+    purgeDeleteOperations: BatchOperation[] | undefined;
 };
 /**
  * Assemble the start batch — folding in the id-dependent idempotency mapping and

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

@@ -1,4 +1,9 @@
-import { requireStorageCapability, storageConditionalBatch } from "../../../storage/interface.js";
+import { requireStorageCapability, storageValuesEqual } from "../../../storage/interface.js";
+import { AtomicStateConflictError } from "../../atomic-state.js";
+import {
+  commitFencedEngineWrite,
+  commitFencedEngineWriteAllowingPreconditionFailure
+} from "../fenced-write.js";
 import { buildStartBatchOperations } from "./start-batch.js";
 
 export class StartIdempotencyRaceLostError extends Error {
@@ -7,13 +12,36 @@ export class StartIdempotencyRaceLostError extends Error {
     this.name = "StartIdempotencyRaceLostError";
   }
 }
+const WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS = 5;
 async function persistStartBatch(internals, startOperations, conditions) {
-  if (conditions === void 0) {
-    await internals.storage.batch(startOperations);
+  if (conditions.length === 0) {
+    await commitFencedEngineWrite(internals, startOperations, [], () => Error("Workflow start lost its CAS race."));
     return !0;
   }
-  requireStorageCapability(internals.storage, "conditionalBatch", "start idempotency");
-  return storageConditionalBatch(internals.storage, conditions, startOperations);
+  requireStorageCapability(internals.storage, "conditionalBatch", "start preconditions");
+  return commitFencedEngineWriteAllowingPreconditionFailure(internals, startOperations, conditions.map((entry) => entry.condition));
+}
+async function hasStartPreconditionConflict(internals, conditions) {
+  for (const entry of conditions) {
+    if (entry.source !== "start-precondition")
+      continue;
+    const currentValue = await internals.storage.get(entry.condition.key);
+    if (!storageValuesEqual(currentValue, entry.condition.expectedValue))
+      return !0;
+  }
+  return !1;
+}
+function tagStartPreconditions(conditions) {
+  return (conditions ?? []).map((condition) => ({
+    source: "start-precondition",
+    condition
+  }));
+}
+function tagWorkflowConcurrencyConditions(conditions) {
+  return conditions.map((condition) => ({
+    source: "workflow-concurrency",
+    condition
+  }));
 }
 function mergeAdditionalStartOperations(additional, idempotent) {
   if (idempotent === void 0 || idempotent.length === 0)
@@ -21,7 +49,21 @@ function mergeAdditionalStartOperations(additional, idempotent) {
   return [...additional ?? [], ...idempotent];
 }
 export async function buildAndCommitStartBatch(context, buildIdempotentStartOperations) {
-  const { internals, workflowId, state, checkpoint, registration, options } = context, idempotent = buildIdempotentStartOperations?.(workflowId), startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, context.delayedStartTimer, context.persistedWorkflowStartHeaders, mergeAdditionalStartOperations(context.additionalStartOperations, idempotent?.operations), context.callbacks);
-  if (!await persistStartBatch(internals, startOperations, idempotent?.conditions))
-    throw new StartIdempotencyRaceLostError;
+  const { internals, workflowId, state, checkpoint, registration, options } = context, maxAttempts = context.buildWorkflowConcurrencyStartOperations === void 0 ? 1 : WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS;
+  let lastWorkflowConcurrencyStateKey;
+  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 = [
+      ...tagStartPreconditions(idempotent?.conditions),
+      ...tagWorkflowConcurrencyConditions(workflowConcurrency?.conditions ?? [])
+    ];
+    if (await persistStartBatch(internals, startOperations, conditions))
+      return;
+    if (await hasStartPreconditionConflict(internals, conditions))
+      throw new StartIdempotencyRaceLostError;
+    if (workflowConcurrency === void 0)
+      throw new StartIdempotencyRaceLostError;
+  }
+  throw new AtomicStateConflictError(lastWorkflowConcurrencyStateKey ?? "workflow concurrency admission", WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS);
 }

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

@@ -0,0 +1,58 @@
+/**
+ * Create-and-deliver machinery for {@link startOrSignal}: building the atomic
+ * start-with-signal batch, running it, and recovering from every way the create
+ * can lose its CAS (keyed-mapping loss, caller-`id` reservation collision, or a
+ * pre-buffered signal). Split from `start-or-signal.ts` to keep that module
+ * focused on the public `startOrSignal` / `startWithIdempotency` entry points.
+ *
+ * @module core/engine/lifecycle/start-or-signal-create
+ */
+import type { StartOptions, StartOrSignalSignal } from '../../types.ts';
+import { type StartOrSignalOutcome, type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type BuildIdempotentStartOperations } from './start-commit.ts';
+import { type StartOrSignalCallbacks } from './start-or-signal-resolution.ts';
+/**
+ * Build the `(workflowId) => { operations, conditions }` callback that folds the
+ * idempotency mapping and (optionally) the create-batch signal into the start
+ * batch, gated on the mapping key being absent. Every caller supplies at least
+ * one of `idempotencyKey` / `signal` (the plain start path skips this builder
+ * entirely), so the returned callback always contributes at least one operation.
+ */
+export declare function idempotentStartOperationsFor(internals: EngineInternals, idempotencyKey: string | undefined, signal: {
+    name: string;
+    payload: unknown;
+    signalId: string;
+} | undefined): BuildIdempotentStartOperations;
+/**
+ * A resolved start-or-signal handle paired with which atomic path produced it
+ * (#466), computed during the call at zero extra cost.
+ */
+export type StartOrSignalResult<TResult = unknown> = {
+    handle: WorkflowHandle<TResult>;
+    outcome: StartOrSignalOutcome;
+};
+/**
+ * Create the workflow and deliver the signal atomically, recovering from a lost
+ * create batch:
+ *
+ * - **Lost to a keyed winner** — idempotency-mapping CAS loss
+ *   ({@link StartIdempotencyRaceLostError} on the keyed path): the mapping commits
+ *   atomically with the record, so the winner is guaranteed committed — resolve it
+ *   and signal it (or conflict if terminal).
+ * - **Lost to a caller-`id` winner** — collision on the winner's in-memory
+ *   `pendingStarts` reservation ({@link WorkflowAlreadyExistsError}): the
+ *   reservation is held BEFORE the durable commit, so it may clear without a run
+ *   ever existing (the winner aborted: storage failure, oversized payload, a
+ *   throwing start interceptor). Wait for the reservation to clear, then signal a
+ *   committed winner or — if it aborted — retry the create. Bounded by
+ *   {@link CALLER_ID_CREATE_MAX_ATTEMPTS}.
+ * - **Signal already buffered** — `StartIdempotencyRaceLostError` on the
+ *   caller-`id` path: the only CAS condition there is the signal's `sigres:`
+ *   accepted-response marker, so the loss means a signal with this signalId was
+ *   pre-buffered and (the batch being atomic) the `wf:` record was NOT written.
+ *   Plain-create the workflow; the buffered signal is consumed on first drive
+ *   (scan-then-park), and the caller's payload loses to the pre-buffered one by
+ *   the same first-wins dedup.
+ */
+export declare function createWithSignalOrFallback(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, signalId: string, options: StartOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<StartOrSignalResult>;

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

@@ -0,0 +1,95 @@
+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 {
+  requireWinnerId,
+  resolveCallerIdWinnerOrRetry,
+  resolveWinnerWithSignal
+} from "./start-or-signal-resolution.js";
+import { startWorkflow } from "./start.js";
+export function idempotentStartOperationsFor(internals, idempotencyKey, signal) {
+  return (workflowId) => {
+    const operations = [], conditions = [];
+    if (idempotencyKey !== void 0) {
+      const key = KEYS.startIdempotency(idempotencyKey);
+      operations.push({
+        type: "put",
+        key,
+        value: encode({ workflowId })
+      });
+      conditions.push({ key, expectedValue: null });
+    }
+    if (signal !== void 0) {
+      const built = buildCreateBatchSignalOperations(internals, workflowId, signal.name, signal.payload, signal.signalId);
+      operations.push(...built.operations);
+      conditions.push(built.condition);
+    }
+    return { operations, conditions };
+  };
+}
+const CALLER_ID_CREATE_MAX_ATTEMPTS = 5;
+export async function createWithSignalOrFallback(internals, type, input, signalSpec, signalId, options, callbacks) {
+  const idempotencyKey = options?.idempotencyKey;
+  for (let attempt = 0;attempt < CALLER_ID_CREATE_MAX_ATTEMPTS; attempt += 1) {
+    const outcome = await resolveCreateRaceOutcome(internals, options, async () => {
+      return startWorkflow(internals, type, input, options, void 0, callbacks, idempotentStartOperationsFor(internals, idempotencyKey, {
+        name: signalSpec.name,
+        payload: signalSpec.payload,
+        signalId
+      }));
+    });
+    if (outcome.kind === "created")
+      return { handle: outcome.handle, outcome: "started" };
+    if (outcome.kind === "lost-keyed")
+      return {
+        handle: await resolveWinnerWithSignal(internals, outcome.id, signalSpec, signalId, callbacks, outcome.idempotencyKey),
+        outcome: "signalled"
+      };
+    if (outcome.kind === "lost-caller-id") {
+      const resolved = await resolveCallerIdWinnerOrRetry(internals, outcome.id, signalSpec, signalId, callbacks);
+      if (resolved !== void 0)
+        return { handle: resolved, outcome: "signalled" };
+    } else {
+      const resolved = await plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks);
+      if (resolved !== void 0)
+        return resolved;
+    }
+  }
+  throw Error(`startOrSignal could not create workflow "${options?.id ?? "<generated>"}" after ${CALLER_ID_CREATE_MAX_ATTEMPTS} attempts: each concurrent same-id winner aborted before its durable commit.`);
+}
+async function plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks) {
+  try {
+    return {
+      handle: await startWorkflow(internals, type, input, options, void 0, callbacks),
+      outcome: "started"
+    };
+  } catch (error) {
+    if (!(error instanceof WorkflowAlreadyExistsError))
+      throw error;
+    const resolved = await resolveCallerIdWinnerOrRetry(internals, error.workflowId, signalSpec, signalId, callbacks);
+    return resolved === void 0 ? void 0 : { handle: resolved, outcome: "signalled" };
+  }
+}
+async function resolveCreateRaceOutcome(internals, options, runCreate) {
+  try {
+    return { kind: "created", handle: await runCreate() };
+  } catch (error) {
+    if (error instanceof WorkflowAlreadyExistsError)
+      return { kind: "lost-caller-id", id: error.workflowId };
+    if (error instanceof StartIdempotencyRaceLostError) {
+      const idempotencyKey = options?.idempotencyKey;
+      if (idempotencyKey !== void 0)
+        return {
+          kind: "lost-keyed",
+          id: await requireWinnerId(internals, idempotencyKey),
+          idempotencyKey
+        };
+      return { kind: "signal-already-buffered" };
+    }
+    throw error;
+  }
+}

package/dist/core/engine/lifecycle/start-or-signal.d.ts

@@ -2,8 +2,9 @@ import type { StartOptions, StartOrSignalSignal } from '../../types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
+import { type StartOrSignalResult } from './start-or-signal-create.ts';
 import { type StartOrSignalCallbacks } from './start-or-signal-resolution.ts';
-export type { StartOrSignalCallbacks };
+export type { StartOrSignalCallbacks, StartOrSignalResult };
 /**
  * Enforce at-most-once start for a given `idempotencyKey`. On the first call,
  * the workflow record and a `startIdempotency(key) → { workflowId }` mapping
@@ -42,4 +43,4 @@ export declare function startWithIdempotency(internals: EngineInternals, type: s
  * convergence primitive. Use `idempotencyKey` (id-free convergence) or
  * `id` + `signalId` when concurrent callers must converge.
  */
-export declare function startOrSignal(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, options: StartOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<WorkflowHandle>;
+export declare function startOrSignal(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, options: StartOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<StartOrSignalResult>;

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

@@ -1,20 +1,21 @@
 import { KEYS, requireStorageCapability } from "../../../storage/interface.js";
-import { encode } from "../../codec.js";
 import {
+  assertIdAndIdempotencyKeyExclusive,
+  assertOnTerminalConflictUnsupported,
   assertValidIdempotencyKey,
+  assertValidOnTerminalConflict,
   StartWorkflowValidationError
 } from "../../start-workflow-validation.js";
-import { IdempotencyKeyPurgedError, WorkflowAlreadyExistsError } from "../errors.js";
-import { buildCreateBatchSignalOperations } from "../signals.js";
+import { IdempotencyKeyPurgedError } from "../errors.js";
+import { StartIdempotencyRaceLostError } from "./start-commit.js";
 import {
-  StartIdempotencyRaceLostError
-} from "./start-commit.js";
+  createWithSignalOrFallback,
+  idempotentStartOperationsFor
+} from "./start-or-signal-create.js";
 import {
   requireWinnerId,
-  resolveCallerIdWinnerOrRetry,
   resolveExistingRunOrThrowPurged,
   resolveIdempotencyKeyWorkflowId,
-  resolveWinnerWithSignal,
   signalOrConflictExistingWorkflow
 } from "./start-or-signal-resolution.js";
 import { startWorkflow } from "./start.js";
@@ -25,26 +26,6 @@ function resolveSignalId(signalSpec, idempotencyKey) {
     return signalSpec.signalId;
   throw new StartWorkflowValidationError("startOrSignal requires either signal.signalId or options.idempotencyKey to identify the signal to deliver. (Concurrent callers converge on one workflow and one signal only with a shared idempotencyKey, or a shared id plus signalId; a bare signalId starts a fresh run per caller.)");
 }
-function idempotentStartOperationsFor(internals, idempotencyKey, signal) {
-  return (workflowId) => {
-    const operations = [], conditions = [];
-    if (idempotencyKey !== void 0) {
-      const key = KEYS.startIdempotency(idempotencyKey);
-      operations.push({
-        type: "put",
-        key,
-        value: encode({ workflowId })
-      });
-      conditions.push({ key, expectedValue: null });
-    }
-    if (signal !== void 0) {
-      const built = buildCreateBatchSignalOperations(internals, workflowId, signal.name, signal.payload, signal.signalId);
-      operations.push(...built.operations);
-      conditions.push(built.condition);
-    }
-    return { operations, conditions };
-  };
-}
 export async function startWithIdempotency(internals, type, input, options, callbacks) {
   requireStorageCapability(internals.storage, "conditionalBatch", "start idempotency");
   const { idempotencyKey } = options;
@@ -52,6 +33,7 @@ export async function startWithIdempotency(internals, type, input, options, call
     throw new StartWorkflowValidationError("startWithIdempotency requires options.idempotencyKey");
   assertValidIdempotencyKey(idempotencyKey, "options.idempotencyKey");
   assertIdAndIdempotencyKeyExclusive(options);
+  assertValidOnTerminalConflict(options);
   const existingId = await resolveIdempotencyKeyWorkflowId(internals, idempotencyKey);
   if (existingId !== void 0)
     return callbacks.getHandle(await resolveExistingRunOrThrowPurged(internals, existingId));
@@ -63,10 +45,6 @@ export async function startWithIdempotency(internals, type, input, options, call
   }
   return callbacks.getHandle(await resolveExistingRunOrThrowPurged(internals, await requireWinnerId(internals, idempotencyKey)));
 }
-function assertIdAndIdempotencyKeyExclusive(options) {
-  if (options.id !== void 0 && options.idempotencyKey !== void 0)
-    throw new StartWorkflowValidationError("options.id and options.idempotencyKey are mutually exclusive: idempotency assigns its own workflow id and dedups through the idempotency key. Provide one or the other.");
-}
 function validateStartOrSignalConvergence(signalSpec, options) {
   const idempotencyKey = options?.idempotencyKey;
   if (idempotencyKey === void 0)
@@ -78,64 +56,16 @@ function validateStartOrSignalConvergence(signalSpec, options) {
 }
 export async function startOrSignal(internals, type, input, signalSpec, options, callbacks) {
   requireStorageCapability(internals.storage, "conditionalBatch", "startOrSignal");
+  assertOnTerminalConflictUnsupported(options, "startOrSignal");
   const idempotencyKey = options?.idempotencyKey;
   validateStartOrSignalConvergence(signalSpec, options);
   const signalId = resolveSignalId(signalSpec, idempotencyKey), mappedId = idempotencyKey !== void 0 ? await resolveIdempotencyKeyWorkflowId(internals, idempotencyKey) : void 0, existingId = mappedId ?? options?.id;
   if (existingId !== void 0) {
     const resolved = await signalOrConflictExistingWorkflow(internals, existingId, signalSpec, signalId, callbacks);
     if (resolved !== void 0)
-      return resolved;
+      return { handle: resolved, outcome: "signalled" };
     if (mappedId !== void 0)
       throw new IdempotencyKeyPurgedError(mappedId);
   }
   return createWithSignalOrFallback(internals, type, input, signalSpec, signalId, options, callbacks);
 }
-const CALLER_ID_CREATE_MAX_ATTEMPTS = 5;
-async function createWithSignalOrFallback(internals, type, input, signalSpec, signalId, options, callbacks) {
-  const idempotencyKey = options?.idempotencyKey;
-  for (let attempt = 0;attempt < CALLER_ID_CREATE_MAX_ATTEMPTS; attempt += 1) {
-    const outcome = await resolveCreateRaceOutcome(internals, options, async () => {
-      return startWorkflow(internals, type, input, options, void 0, callbacks, idempotentStartOperationsFor(internals, idempotencyKey, {
-        name: signalSpec.name,
-        payload: signalSpec.payload,
-        signalId
-      }));
-    });
-    if (outcome.kind === "created")
-      return outcome.handle;
-    if (outcome.kind === "lost-keyed")
-      return resolveWinnerWithSignal(internals, outcome.id, signalSpec, signalId, callbacks, outcome.idempotencyKey);
-    const resolved = outcome.kind === "lost-caller-id" ? await resolveCallerIdWinnerOrRetry(internals, outcome.id, signalSpec, signalId, callbacks) : await plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks);
-    if (resolved !== void 0)
-      return resolved;
-  }
-  throw Error(`startOrSignal could not create workflow "${options?.id ?? "<generated>"}" after ${CALLER_ID_CREATE_MAX_ATTEMPTS} attempts: each concurrent same-id winner aborted before its durable commit.`);
-}
-async function plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks) {
-  try {
-    return await startWorkflow(internals, type, input, options, void 0, callbacks);
-  } catch (error) {
-    if (!(error instanceof WorkflowAlreadyExistsError))
-      throw error;
-    return resolveCallerIdWinnerOrRetry(internals, error.workflowId, signalSpec, signalId, callbacks);
-  }
-}
-async function resolveCreateRaceOutcome(internals, options, runCreate) {
-  try {
-    return { kind: "created", handle: await runCreate() };
-  } catch (error) {
-    if (error instanceof WorkflowAlreadyExistsError)
-      return { kind: "lost-caller-id", id: error.workflowId };
-    if (error instanceof StartIdempotencyRaceLostError) {
-      const idempotencyKey = options?.idempotencyKey;
-      if (idempotencyKey !== void 0)
-        return {
-          kind: "lost-keyed",
-          id: await requireWinnerId(internals, idempotencyKey),
-          idempotencyKey
-        };
-      return { kind: "signal-already-buffered" };
-    }
-    throw error;
-  }
-}

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

@@ -0,0 +1,39 @@
+import type { BatchOperation } from '../../../storage/interface.ts';
+import type { StartWorkflowOptions, WorkflowState } from '../../types.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+/**
+ * Decide what a caller-supplied workflow id that already has a persisted record
+ * means, WITHOUT performing any destructive action. Only invoked when the caller
+ * supplied the id — a generated v4 UUID is effectively unique, so skipping this
+ * read keeps generated-id starts on the single-write hot path.
+ *
+ * - default (`'error'`): throw {@link WorkflowAlreadyExistsError} (the existing
+ *   contract — a duplicate id is always a conflict).
+ * - `'start-new'` on a **terminal** run: return that run's {@link WorkflowState}
+ *   so the caller can purge it *after* all deterministic new-run validation has
+ *   succeeded. This keeps the destructive purge as the last possible step before
+ *   the atomic create commit, so a restart that is rejected by any later
+ *   validation (payload size, execution-timeout overflow, a start interceptor
+ *   throwing) leaves the prior terminal run intact.
+ * - `'start-new'` on a **non-terminal** run: throw
+ *   {@link WorkflowAlreadyExistsError} — `'start-new'` never displaces a live run.
+ * - `'start-new'` on a **terminal** run that still owes a finalizer (#446): throw
+ *   {@link WorkflowTeardownPendingError} (transient). The displacing purge would
+ *   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).
+ */
+export declare function resolveTerminalConflictForRestart(internals: EngineInternals, workflowId: string, options: StartWorkflowOptions | undefined): Promise<WorkflowState | null>;
+/**
+ * Prepare a prior terminal run for displacement by a `'start-new'` restart WITHOUT
+ * committing the destructive delete. Returns the storage delete operations (for the
+ * caller to fold into the atomic create batch so purge-and-recreate land as one
+ * unit) and clears the OLD run's in-memory caches up front — before the new run
+ * writes its own caches under the reused id, so the clear cannot wipe fresh
+ * entries. `clearPurgedWorkflowInMemoryState` runs `cleanupWaiters` to settle the
+ * old run's pending signal/update/sleep waiters; it only needs
+ * `swallowPromiseRejection`, which `LifecycleCallbacks` already exposes.
+ */
+export declare function prepareTerminalRunPurge(internals: EngineInternals, state: WorkflowState, callbacks: LifecycleCallbacks): Promise<BatchOperation[]>;

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

@@ -0,0 +1,28 @@
+import { KEYS, storageHas } from "../../../storage/interface.js";
+import {
+  clearPurgedWorkflowInMemoryState,
+  collectWorkflowPurgeDeleteOperations
+} from "../bulk-operations-purge.js";
+import { WorkflowAlreadyExistsError, WorkflowTeardownPendingError } from "../errors.js";
+import { cleanupWaiters } from "../termination/cleanup.js";
+import { decodeWorkflowState, isTerminalWorkflowStatus } from "../validation.js";
+export async function resolveTerminalConflictForRestart(internals, workflowId, options) {
+  const existingBytes = await internals.storage.get(KEYS.workflow(workflowId));
+  if (existingBytes === null)
+    return null;
+  if (options?.onTerminalConflict !== "start-new")
+    throw new WorkflowAlreadyExistsError(workflowId);
+  const existingState = decodeWorkflowState(existingBytes);
+  if (!isTerminalWorkflowStatus(existingState.status))
+    throw new WorkflowAlreadyExistsError(workflowId);
+  if (await storageHas(internals.storage, KEYS.teardownOwed(workflowId)))
+    throw new WorkflowTeardownPendingError(workflowId);
+  return existingState;
+}
+export async function prepareTerminalRunPurge(internals, state, callbacks) {
+  const cleanupWaitersForStart = (id) => cleanupWaiters(internals, id, {
+    swallowPromiseRejection: callbacks.swallowPromiseRejection
+  }), deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state);
+  clearPurgedWorkflowInMemoryState(internals, state.id, cleanupWaitersForStart);
+  return deleteOperations;
+}

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

@@ -1,13 +1,13 @@
 import type { BatchOperation } from '../../../storage/interface.ts';
-import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
+import type { Checkpoint, Duration, StartOptions, StartWorkflowOptions, TimerEntry, WorkflowState } from '../../types.ts';
 import { type WorkflowVersionTuple } from '../../workflow-version-tuple.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: StartOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
-export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations): Promise<WorkflowHandle>;
+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 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, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
+export declare function createInitialWorkflowState(internals: EngineInternals, workflowId: string, type: string, input: unknown, versionTuple: WorkflowVersionTuple, options: StartOptions | undefined, tags: string[] | undefined, executionStateOwnerId: string | undefined, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
 export declare function createInitialCheckpoint(internals: EngineInternals, workflowId: string, workflowVersion: string, options: StartOptions | undefined, _callbacks: LifecycleCallbacks): Checkpoint;

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

@@ -1,10 +1,10 @@
-import { KEYS } from "../../../storage/interface.js";
 import { createCheckpoint } from "../../checkpoint.js";
 import { assertPayloadWithinLimit } from "../../payload-size.js";
 import { normalizeStorageTimestamp } from "../../scheduler.js";
 import {
   StartWorkflowValidationError,
   assertExclusiveStartWorkflowOptions,
+  assertValidOnTerminalConflict,
   coerceStartWorkflowId,
   coerceStartWorkflowTimestamp,
   parseStartWorkflowDuration
@@ -13,6 +13,7 @@ import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.j
 import { WorkflowAlreadyExistsError, WorkflowNotRegisteredError } from "../errors.js";
 import { createDelayedStartTimerEntry } from "../operations-time.js";
 import { selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
+import { buildWorkflowConcurrencyStartOperations } from "../workflow-concurrency.js";
 import { createWorkflowVersionTuple } from "./persist.js";
 import {
   createWorkflowHandle,
@@ -25,13 +26,17 @@ import {
   beginExecutionAwaitingLiveness,
   runWorkflowStartInterceptor
 } from "./start-exec.js";
+import {
+  prepareTerminalRunPurge,
+  resolveTerminalConflictForRestart
+} from "./start-terminal-conflict-purge.js";
 export async function start(internals, type, input, options, callbacks) {
   return startWorkflow(internals, type, input, options, void 0, callbacks);
 }
 function prepareStartWorkflow(internals, options, callbacks) {
   const callerProvidedId = options?.id !== void 0, workflowId = options?.id !== void 0 ? coerceStartWorkflowId(options.id, "options.id") : crypto.randomUUID(), parentHeaders = internals.pendingParentHeaders;
   internals.pendingParentHeaders = void 0;
-  const executionStateOwnerId = internals.pendingExecutionStateOwnerId ?? workflowId;
+  const pendingExecutionStateOwnerId = internals.pendingExecutionStateOwnerId, executionStateOwnerId = pendingExecutionStateOwnerId === null ? void 0 : pendingExecutionStateOwnerId ?? workflowId;
   internals.pendingExecutionStateOwnerId = void 0;
   const submissionTime = internals.options.getNow(), scheduledStartAt = resolveScheduledStartAt(internals, options, submissionTime, callbacks), normalizedTags = normalizeStartWorkflowTags(internals, options?.tags, void 0, callbacks), delayedStartTimer = scheduledStartAt !== void 0 && scheduledStartAt > submissionTime ? createDelayedStartTimerEntry(internals, workflowId, scheduledStartAt, options, {
     parseStartOptionDuration: (value, fieldName) => parseStartOptionDuration(internals, value, fieldName, callbacks)
@@ -62,7 +67,9 @@ export async function startWorkflow(internals, type, input, options, additionalS
   const registration = internals.registrations.get(type);
   if (!registration)
     throw new WorkflowNotRegisteredError(type);
+  const workflowConcurrency = registration.concurrency;
   assertServicesSupportedForMode(internals, options);
+  assertValidOnTerminalConflict(options);
   const preparation = prepareStartWorkflow(internals, options, callbacks), { workflowId, callerProvidedId, parentHeaders, executionStateOwnerId, delayedStartTimer } = preparation;
   assertDeferSupported(internals, options, Boolean(delayedStartTimer));
   if (internals.pendingStarts.has(workflowId))
@@ -70,12 +77,9 @@ export async function startWorkflow(internals, type, input, options, additionalS
   internals.pendingStarts.add(workflowId);
   let startSucceeded = !1;
   try {
-    if (callerProvidedId) {
-      if (await internals.storage.get(KEYS.workflow(workflowId)) !== null)
-        throw new WorkflowAlreadyExistsError(workflowId);
-    }
+    const terminalRunToPurge = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : null;
     assertPayloadWithinLimit(input, internals.options.payloadSizePolicy.maxBytes, "workflow input");
-    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, preparation.normalizedTags, executionStateOwnerId, delayedStartTimer, callbacks), checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders);
+    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, preparation.normalizedTags, executionStateOwnerId, delayedStartTimer, callbacks), checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks) : void 0;
     internals.checkpoints.set(workflowId, checkpoint);
     setWorkflowStartHeaders(internals, workflowId, workflowStartHeaders, callbacks);
     internals.workflowVersionTuples.set(workflowId, versionTuple);
@@ -89,12 +93,16 @@ export async function startWorkflow(internals, type, input, options, additionalS
       delayedStartTimer,
       persistedWorkflowStartHeaders,
       additionalStartOperations,
-      callbacks
+      buildWorkflowConcurrencyStartOperations: workflowConcurrency === void 0 ? void 0 : () => buildWorkflowConcurrencyStartOperations(internals, type, workflowId, input, workflowConcurrency),
+      callbacks,
+      purgeDeleteOperations
     }, buildIdempotentStartOperations);
     if (options?.services !== void 0) {
       internals.workflowServices.set(workflowId, options.services);
       internals.workflowsNeedingTerminalCleanup.add(workflowId);
     }
+    if (workflowConcurrency !== void 0)
+      internals.workflowsNeedingTerminalCleanup.add(workflowId);
     const handle = createWorkflowHandle(internals, workflowId, callbacks);
     await beginExecutionAwaitingLiveness(internals, {
       type,
@@ -137,7 +145,7 @@ function buildInitialIdentitySlice(workflowId, type, input, versionTuple, execut
     status: delayedStartTimer ? "pending" : "running",
     input,
     versionTuple,
-    executionStateOwnerId,
+    ...executionStateOwnerId !== void 0 && { executionStateOwnerId },
     createdAt: now,
     ...!delayedStartTimer && { startedAt: now },
     updatedAt: now,