@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -1,4 +1,6 @@
 import { serializeCheckpoint } from "../../checkpoint.js";
+import { WorkflowStartedEvent } from "../../events.js";
+import { StartWorkflowValidationError } from "../../start-workflow-validation.js";
 export function runWorkflowStartInterceptor(_internals, workflowId, workflowType, input, parentHeaders, callbacks) {
   const composedInterceptor = callbacks.getComposedWorkflowInterceptor();
   if (!composedInterceptor)
@@ -37,3 +39,39 @@ export function startWorkflowExecution(internals, workflowId, workflowType, inpu
     }
   });
 }
+export function beginWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, _registration, callbacks, onStarted) {
+  const nestingDepth = internals.pendingNestingDepth ?? 0;
+  internals.pendingNestingDepth = void 0;
+  if (internals.inlineStrategy !== null) {
+    callbacks.queueInlineWorkflowExecutionStart({
+      workflowId,
+      workflowType,
+      input,
+      checkpoint,
+      nestingDepth,
+      executionDeadline,
+      executionStateOwnerId,
+      ...onStarted !== void 0 && { onStarted }
+    });
+    return;
+  }
+  callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, workflowType, input));
+  startWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, callbacks);
+  onStarted?.();
+}
+export function assertDeferSupported(internals, options, isDelayedStart) {
+  if (options?.defer !== !1)
+    return;
+  if (internals.inlineStrategy === null)
+    throw new StartWorkflowValidationError('options.defer: false is only supported in inline execution mode; a worker-mode start cannot be awaited for inline liveness. Use workflowExecutionMode: "inline" or remove defer.');
+  if (isDelayedStart)
+    throw new StartWorkflowValidationError("options.defer: false is incompatible with a delayed start (startAt/startAfter): a scheduled run has not begun executing, so there is no liveness to await. Remove defer or the delayed-start option.");
+}
+export async function beginExecutionAwaitingLiveness(internals, params, workflowId, callbacks) {
+  if (params.isDelayed)
+    return;
+  const liveness = params.options?.defer === !1 ? Promise.withResolvers() : void 0;
+  beginWorkflowExecution(internals, workflowId, params.type, 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.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-resolution.d.ts

@@ -0,0 +1,79 @@
+import type { StartOrSignalSignal } from '../../types.ts';
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+/**
+ * Callbacks `startOrSignal` needs beyond the lifecycle set: a way to deliver a
+ * signal to an already-running workflow through the full engine signal path
+ * (interceptors, events, parked-run wakeups). Supplied by the engine so the
+ * "signal an existing non-terminal run" branch reuses `engine.signal` with the
+ * same `signalId` the create batch would have used.
+ */
+export type StartOrSignalCallbacks = LifecycleCallbacks & {
+    signalExistingWorkflow: (workflowId: string, signalName: string, payload: unknown, signalId: string) => Promise<void>;
+};
+/** The value stored at `KEYS.startIdempotency(key)`: the workflow the key created. */
+export type StartIdempotencyMapping = {
+    workflowId: string;
+};
+/** Resolve an existing workflow id for an idempotency key, if one was created. */
+export declare function resolveIdempotencyKeyWorkflowId(internals: EngineInternals, idempotencyKey: string): Promise<string | undefined>;
+/**
+ * Resolve a key-mapped workflow id to a handle id, asserting its record still
+ * exists. The `start-idem:` mapping is permanent — it survives BOTH terminal
+ * cleanup AND purge/retention (those reclaim the workflow record, never the
+ * `start-idem:` keyspace) — so a present mapping whose record is gone means the
+ * key is spent: a fresh create would fail the still-present mapping CAS and strand
+ * the caller. Surface {@link IdempotencyKeyPurgedError} instead of handing back a
+ * handle to a vanished run. Shared by the synchronous mapping hit and the
+ * post-race winner lookup so both reject a purged key identically.
+ */
+export declare function resolveExistingRunOrThrowPurged(internals: EngineInternals, workflowId: string): Promise<string>;
+/**
+ * Resolve a caller-`id` create-race loss without conflating an in-memory
+ * reservation with a durable record. A loser collides on the winner's
+ * `pendingStarts` reservation (start.ts) BEFORE the winner commits, so the bare
+ * collision proves nothing about whether a run will exist.
+ *
+ * Read the winner's record FIRST: this catches a winner that has already committed
+ * but is still non-terminal before it can complete (a fast workflow consumes its
+ * create-batch signal and finishes the moment it is driven — reading immediately
+ * 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 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.
+ */
+export declare function resolveCallerIdWinnerOrRetry(internals: EngineInternals, winnerId: string, signalSpec: StartOrSignalSignal, signalId: string, callbacks: StartOrSignalCallbacks): Promise<WorkflowHandle | undefined>;
+/**
+ * For a workflow that already exists: signal it if non-terminal, conflict if
+ * terminal. Returns the handle on a successful signal, or `undefined` when the
+ * workflow record is not present (so the caller falls through to create).
+ */
+export declare function signalOrConflictExistingWorkflow(internals: EngineInternals, workflowId: string, signalSpec: StartOrSignalSignal, signalId: string, callbacks: StartOrSignalCallbacks): Promise<WorkflowHandle | undefined>;
+/**
+ * Signal a KEYED race winner, bounded-retrying when its record is not yet readable.
+ * The keyed winner commits its record atomically with the `start-idem:` mapping, so
+ * the record is guaranteed to exist — but the loser may read before the commit
+ * settles, so a short delay between reads lets it land. (Caller-`id` winners can
+ * abort before committing and are handled by `resolveCallerIdWinnerOrRetry`, not
+ * here.)
+ *
+ * After {@link WINNER_RESOLUTION_MAX_ATTEMPTS} reads with no record, the record is
+ * absent for a committed-with-mapping winner only because it was purged: re-read
+ * the mapping, and if it still resolves to this exact `winnerId` the key is spent —
+ * throw {@link IdempotencyKeyPurgedError}. A mapping that now resolves to a
+ * DIFFERENT id (or vanished) cannot prove this winner was purged, so it falls
+ * through to the invariant throw rather than mislabelling external keyspace
+ * mutation as a spent key.
+ */
+export declare function resolveWinnerWithSignal(internals: EngineInternals, winnerId: string, signalSpec: StartOrSignalSignal, signalId: string, callbacks: StartOrSignalCallbacks, idempotencyKey: string): Promise<WorkflowHandle>;
+/**
+ * Read the winning workflow id from the idempotency mapping after a lost CAS. The
+ * mapping must exist once any caller's create commits; its absence means the
+ * `start-idem:` keyspace was mutated externally.
+ */
+export declare function requireWinnerId(internals: EngineInternals, idempotencyKey: string): Promise<string>;

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

@@ -0,0 +1,60 @@
+import { sleep } from "../../../runtime/portable.js";
+import { KEYS } from "../../../storage/interface.js";
+import { decode } from "../../codec.js";
+import { IdempotencyKeyPurgedError, StartOrSignalConflictError } from "../errors.js";
+import { loadWorkflowState } from "../storage-io.js";
+import { isTerminalWorkflowStatus } from "../validation.js";
+export async function resolveIdempotencyKeyWorkflowId(internals, idempotencyKey) {
+  const bytes = await internals.storage.get(KEYS.startIdempotency(idempotencyKey));
+  if (bytes === null)
+    return;
+  return decode(bytes).workflowId;
+}
+export async function resolveExistingRunOrThrowPurged(internals, workflowId) {
+  if (await loadWorkflowState(internals, workflowId) === null)
+    throw new IdempotencyKeyPurgedError(workflowId);
+  return workflowId;
+}
+const RESERVATION_CLEAR_MAX_ATTEMPTS = 5, RESERVATION_CLEAR_RETRY_DELAY_MS = 5;
+async function awaitReservationCleared(internals, workflowId) {
+  for (let attempt = 0;attempt < RESERVATION_CLEAR_MAX_ATTEMPTS; attempt += 1) {
+    if (!internals.pendingStarts.has(workflowId))
+      return;
+    await sleep(RESERVATION_CLEAR_RETRY_DELAY_MS);
+  }
+}
+export async function resolveCallerIdWinnerOrRetry(internals, winnerId, signalSpec, signalId, callbacks) {
+  const resolved = await signalOrConflictExistingWorkflow(internals, winnerId, signalSpec, signalId, callbacks);
+  if (resolved !== void 0)
+    return resolved;
+  await awaitReservationCleared(internals, winnerId);
+  return signalOrConflictExistingWorkflow(internals, winnerId, signalSpec, signalId, callbacks);
+}
+export async function signalOrConflictExistingWorkflow(internals, workflowId, signalSpec, signalId, callbacks) {
+  const state = await loadWorkflowState(internals, workflowId);
+  if (state === null)
+    return;
+  if (isTerminalWorkflowStatus(state.status))
+    throw new StartOrSignalConflictError(workflowId, state.status);
+  await callbacks.signalExistingWorkflow(workflowId, signalSpec.name, signalSpec.payload, signalId);
+  return callbacks.getHandle(workflowId);
+}
+const WINNER_RESOLUTION_MAX_ATTEMPTS = 5, WINNER_RESOLUTION_RETRY_DELAY_MS = 5;
+export async function resolveWinnerWithSignal(internals, winnerId, signalSpec, signalId, callbacks, idempotencyKey) {
+  for (let attempt = 0;attempt < WINNER_RESOLUTION_MAX_ATTEMPTS; attempt += 1) {
+    const resolved = await signalOrConflictExistingWorkflow(internals, winnerId, signalSpec, signalId, callbacks);
+    if (resolved !== void 0)
+      return resolved;
+    if (attempt < WINNER_RESOLUTION_MAX_ATTEMPTS - 1)
+      await sleep(WINNER_RESOLUTION_RETRY_DELAY_MS);
+  }
+  if (await resolveIdempotencyKeyWorkflowId(internals, idempotencyKey) === winnerId)
+    throw new IdempotencyKeyPurgedError(winnerId);
+  throw Error(`startOrSignal resolved winning workflow "${winnerId}" but its record never became readable after ${WINNER_RESOLUTION_MAX_ATTEMPTS} attempts.`);
+}
+export async function requireWinnerId(internals, idempotencyKey) {
+  const winnerId = await resolveIdempotencyKeyWorkflowId(internals, idempotencyKey);
+  if (winnerId === void 0)
+    throw Error(`start idempotency mapping for key "${idempotencyKey}" vanished after a lost compare-and-swap; the start-idem: keyspace may have been mutated externally.`);
+  return winnerId;
+}

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

@@ -0,0 +1,46 @@
+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, StartOrSignalResult };
+/**
+ * Enforce at-most-once start for a given `idempotencyKey`. On the first call,
+ * the workflow record and a `startIdempotency(key) → { workflowId }` mapping
+ * commit in one compare-and-swap gated on the mapping being absent. Every later
+ * call with the same key resolves the mapping and returns a handle to that run —
+ * even if it has since reached a terminal state (idempotent start is a pure
+ * dedup; it never restarts).
+ *
+ * Concurrent same-key callers race at the lookup→commit gap; the CAS lets exactly
+ * one win, and the loser (its create batch rejected) resolves to the winner's
+ * run. Requires the `conditionalBatch` capability and throws if it is absent —
+ * single-execution semantics cannot be honored without atomic compare-and-swap.
+ */
+export declare function startWithIdempotency(internals: EngineInternals, type: string, input: unknown, options: StartOptions, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+/**
+ * Atomic start-or-signal (signal-with-start). Resolves the target workflow, then:
+ *
+ * - **Absent** → create the workflow and deliver the signal in ONE conditional
+ *   batch (workflow record + `sig:`/`sigres:` pair + optional idempotency
+ *   mapping). The freshly-launched run consumes the signal on its first drive.
+ * - **Non-terminal** (running, pending, suspended) → deliver the signal through
+ *   the standard engine signal path with the same `signalId`, so it dedups
+ *   against a create-batch signal a concurrent winner may have written.
+ * - **Terminal** → throw {@link StartOrSignalConflictError}: a finished run
+ *   cannot be signalled and is not silently replaced.
+ *
+ * Convergence requires a SHARED workflow identity. Concurrent callers converge on
+ * one workflow and one signal only when they share an `options.idempotencyKey`
+ * (the durable mapping picks one creator and the signal id derives from the key)
+ * or an explicit `options.id` (the caller-id reservation picks one creator).
+ *
+ * A bare `signal.signalId` with NEITHER `options.id` nor `options.idempotencyKey`
+ * does NOT converge: each absent-target call generates its own workflow id, so
+ * concurrent callers create distinct runs and each delivers its own signal. In
+ * that mode `startOrSignal` is an atomic start-with-one-initial-signal, not a
+ * 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<StartOrSignalResult>;

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

@@ -0,0 +1,71 @@
+import { KEYS, requireStorageCapability } from "../../../storage/interface.js";
+import {
+  assertIdAndIdempotencyKeyExclusive,
+  assertOnTerminalConflictUnsupported,
+  assertValidIdempotencyKey,
+  assertValidOnTerminalConflict,
+  StartWorkflowValidationError
+} from "../../start-workflow-validation.js";
+import { IdempotencyKeyPurgedError } from "../errors.js";
+import { StartIdempotencyRaceLostError } from "./start-commit.js";
+import {
+  createWithSignalOrFallback,
+  idempotentStartOperationsFor
+} from "./start-or-signal-create.js";
+import {
+  requireWinnerId,
+  resolveExistingRunOrThrowPurged,
+  resolveIdempotencyKeyWorkflowId,
+  signalOrConflictExistingWorkflow
+} from "./start-or-signal-resolution.js";
+import { startWorkflow } from "./start.js";
+function resolveSignalId(signalSpec, idempotencyKey) {
+  if (idempotencyKey !== void 0)
+    return KEYS.startIdempotencySignalId(idempotencyKey);
+  if (signalSpec.signalId !== void 0)
+    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.)");
+}
+export async function startWithIdempotency(internals, type, input, options, callbacks) {
+  requireStorageCapability(internals.storage, "conditionalBatch", "start idempotency");
+  const { idempotencyKey } = options;
+  if (idempotencyKey === void 0)
+    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));
+  try {
+    return await startWorkflow(internals, type, input, options, void 0, callbacks, idempotentStartOperationsFor(internals, idempotencyKey, void 0));
+  } catch (error) {
+    if (!(error instanceof StartIdempotencyRaceLostError))
+      throw error;
+  }
+  return callbacks.getHandle(await resolveExistingRunOrThrowPurged(internals, await requireWinnerId(internals, idempotencyKey)));
+}
+function validateStartOrSignalConvergence(signalSpec, options) {
+  const idempotencyKey = options?.idempotencyKey;
+  if (idempotencyKey === void 0)
+    return;
+  assertValidIdempotencyKey(idempotencyKey, "options.idempotencyKey");
+  assertIdAndIdempotencyKeyExclusive(options ?? {});
+  if (signalSpec.signalId !== void 0)
+    throw new StartWorkflowValidationError("startOrSignal does not accept both signal.signalId and options.idempotencyKey: the signal id derives from the idempotency key for convergence. Provide exactly one.");
+}
+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 { handle: resolved, outcome: "signalled" };
+    if (mappedId !== void 0)
+      throw new IdempotencyKeyPurgedError(mappedId);
+  }
+  return createWithSignalOrFallback(internals, type, input, signalSpec, signalId, options, callbacks);
+}

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, type RegistrationEntry } from './shared.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): Promise<WorkflowHandle>;
+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 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 beginWorkflowExecution(internals: EngineInternals, workflowId: string, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, _registration: RegistrationEntry, callbacks: LifecycleCallbacks): void;
-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;