@lostgradient/weft 0.2.0 → 0.3.0

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,45 @@
+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 StartOrSignalCallbacks } from './start-or-signal-resolution.ts';
+export type { StartOrSignalCallbacks };
+/**
+ * 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<WorkflowHandle>;

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

@@ -0,0 +1,141 @@
+import { KEYS, requireStorageCapability } from "../../../storage/interface.js";
+import { encode } from "../../codec.js";
+import {
+  assertValidIdempotencyKey,
+  StartWorkflowValidationError
+} from "../../start-workflow-validation.js";
+import { IdempotencyKeyPurgedError, WorkflowAlreadyExistsError } from "../errors.js";
+import { buildCreateBatchSignalOperations } from "../signals.js";
+import {
+  StartIdempotencyRaceLostError
+} from "./start-commit.js";
+import {
+  requireWinnerId,
+  resolveCallerIdWinnerOrRetry,
+  resolveExistingRunOrThrowPurged,
+  resolveIdempotencyKeyWorkflowId,
+  resolveWinnerWithSignal,
+  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.)");
+}
+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;
+  if (idempotencyKey === void 0)
+    throw new StartWorkflowValidationError("startWithIdempotency requires options.idempotencyKey");
+  assertValidIdempotencyKey(idempotencyKey, "options.idempotencyKey");
+  assertIdAndIdempotencyKeyExclusive(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 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)
+    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");
+  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;
+    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.d.ts

@@ -3,11 +3,11 @@ import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } fr
 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';
+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): 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 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 createInitialCheckpoint(internals: EngineInternals, workflowId: string, workflowVersion: string, options: StartOptions | undefined, _callbacks: LifecycleCallbacks): Checkpoint;

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

@@ -1,6 +1,5 @@
 import { KEYS } from "../../../storage/interface.js";
 import { createCheckpoint } from "../../checkpoint.js";
-import { WorkflowStartedEvent } from "../../events.js";
 import { assertPayloadWithinLimit } from "../../payload-size.js";
 import { normalizeStorageTimestamp } from "../../scheduler.js";
 import {
@@ -20,8 +19,12 @@ import {
   normalizeStartWorkflowTags,
   setWorkflowStartHeaders
 } from "./shared.js";
-import { buildStartBatchOperations } from "./start-batch.js";
-import { runWorkflowStartInterceptor, startWorkflowExecution } from "./start-exec.js";
+import { buildAndCommitStartBatch } from "./start-commit.js";
+import {
+  assertDeferSupported,
+  beginExecutionAwaitingLiveness,
+  runWorkflowStartInterceptor
+} from "./start-exec.js";
 export async function start(internals, type, input, options, callbacks) {
   return startWorkflow(internals, type, input, options, void 0, callbacks);
 }
@@ -43,20 +46,25 @@ function prepareStartWorkflow(internals, options, callbacks) {
     normalizedTags
   };
 }
-async function persistStartBatch(internals, startOperations) {
-  await internals.storage.batch(startOperations);
-}
 function rollbackTransientStartState(internals, workflowId) {
   forgetCommittedCheckpointBytes(internals, workflowId);
   internals.checkpoints.delete(workflowId);
   internals.workflowHeaders.delete(workflowId);
   internals.workflowVersionTuples.delete(workflowId);
+  internals.workflowServices.delete(workflowId);
+  internals.workflowsNeedingTerminalCleanup.delete(workflowId);
 }
-export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks) {
+function assertServicesSupportedForMode(internals, options) {
+  if (options?.services !== void 0 && internals.inlineStrategy === null)
+    throw Error('options.services is only supported in inline execution mode; it cannot be serialized to a Worker. Remove services or use workflowExecutionMode: "inline".');
+}
+export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks, buildIdempotentStartOperations) {
   const registration = internals.registrations.get(type);
   if (!registration)
     throw new WorkflowNotRegisteredError(type);
+  assertServicesSupportedForMode(internals, options);
   const preparation = prepareStartWorkflow(internals, options, callbacks), { workflowId, callerProvidedId, parentHeaders, executionStateOwnerId, delayedStartTimer } = preparation;
+  assertDeferSupported(internals, options, Boolean(delayedStartTimer));
   if (internals.pendingStarts.has(workflowId))
     throw new WorkflowAlreadyExistsError(workflowId);
   internals.pendingStarts.add(workflowId);
@@ -71,11 +79,32 @@ export async function startWorkflow(internals, type, input, options, additionalS
     internals.checkpoints.set(workflowId, checkpoint);
     setWorkflowStartHeaders(internals, workflowId, workflowStartHeaders, callbacks);
     internals.workflowVersionTuples.set(workflowId, versionTuple);
-    const startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, delayedStartTimer, persistedWorkflowStartHeaders, additionalStartOperations, callbacks);
-    await persistStartBatch(internals, startOperations);
+    await buildAndCommitStartBatch({
+      internals,
+      workflowId,
+      state,
+      checkpoint,
+      registration,
+      options,
+      delayedStartTimer,
+      persistedWorkflowStartHeaders,
+      additionalStartOperations,
+      callbacks
+    }, buildIdempotentStartOperations);
+    if (options?.services !== void 0) {
+      internals.workflowServices.set(workflowId, options.services);
+      internals.workflowsNeedingTerminalCleanup.add(workflowId);
+    }
     const handle = createWorkflowHandle(internals, workflowId, callbacks);
-    if (!delayedStartTimer)
-      beginWorkflowExecution(internals, workflowId, type, input, checkpoint, state.executionDeadline, state.executionStateOwnerId ?? workflowId, registration, callbacks);
+    await beginExecutionAwaitingLiveness(internals, {
+      type,
+      input,
+      checkpoint,
+      state,
+      registration,
+      options,
+      isDelayed: Boolean(delayedStartTimer)
+    }, workflowId, callbacks);
     startSucceeded = !0;
     return handle;
   } finally {
@@ -101,42 +130,18 @@ export function resolveScheduledStartAt(internals, options, submissionTime, call
 export function parseStartOptionDuration(_internals, duration, fieldName, _callbacks) {
   return parseStartWorkflowDuration(duration, fieldName);
 }
-export function beginWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, _registration, callbacks) {
-  const nestingDepth = internals.pendingNestingDepth ?? 0;
-  internals.pendingNestingDepth = void 0;
-  if (internals.inlineStrategy !== null) {
-    callbacks.queueInlineWorkflowExecutionStart({
-      workflowId,
-      workflowType,
-      input,
-      checkpoint,
-      nestingDepth,
-      executionDeadline,
-      executionStateOwnerId
-    });
-    return;
-  }
-  callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, workflowType, input));
-  startWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, callbacks);
-}
 function buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, delayedStartTimer, now, tags) {
   return {
     id: workflowId,
     type,
     status: delayedStartTimer ? "pending" : "running",
     input,
-    version: versionTuple.workflowVersion,
+    versionTuple,
     executionStateOwnerId,
     createdAt: now,
     ...!delayedStartTimer && { startedAt: now },
     updatedAt: now,
-    ...tags !== void 0 && { tags },
-    ...versionTuple.agentVersion !== void 0 && {
-      agentVersion: versionTuple.agentVersion
-    },
-    ...versionTuple.toolVersions !== void 0 && {
-      toolVersions: versionTuple.toolVersions
-    }
+    ...tags !== void 0 && { tags }
   };
 }
 function resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks) {

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

@@ -1,8 +1,9 @@
 export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, } from './lifecycle/shared.ts';
 export { createWorkflowVersionTuple, derivePreparedExecutionState, prepareResumeState, throwVersionMismatch, workflowStateWithVersionTuple, workflowVersionTupleFromState, } from './lifecycle/persist.ts';
-export { beginWorkflowExecution, createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
+export { createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
+export { startOrSignal, startWithIdempotency, type StartOrSignalCallbacks, } from './lifecycle/start-or-signal.ts';
 export { buildInitialSearchAttributeOperations, buildStartBatchOperations, validateSearchAttributes, } from './lifecycle/start-batch.ts';
-export { runWorkflowStartInterceptor, startWorkflowExecution } from './lifecycle/start-exec.ts';
+export { beginWorkflowExecution, runWorkflowStartInterceptor, startWorkflowExecution, } from './lifecycle/start-exec.ts';
 export { buildForkBatchOperations, buildForkSearchAttributes, createForkLineage, createForkedWorkflowState, } from './lifecycle/fork-helpers.ts';
 export { fork, launchWorkflowFromCheckpoint, recoverAll, resume } from './lifecycle/transition.ts';
 export { resumeWorkflowFromStorage } from './lifecycle/resume.ts';

package/dist/core/engine/lifecycle.js

@@ -16,7 +16,6 @@ export {
   workflowVersionTupleFromState
 } from "./lifecycle/persist.js";
 export {
-  beginWorkflowExecution,
   createInitialCheckpoint,
   createInitialWorkflowState,
   parseStartOptionDuration,
@@ -24,12 +23,20 @@ export {
   start,
   startWorkflow
 } from "./lifecycle/start.js";
+export {
+  startOrSignal,
+  startWithIdempotency
+} from "./lifecycle/start-or-signal.js";
 export {
   buildInitialSearchAttributeOperations,
   buildStartBatchOperations,
   validateSearchAttributes
 } from "./lifecycle/start-batch.js";
-export { runWorkflowStartInterceptor, startWorkflowExecution } from "./lifecycle/start-exec.js";
+export {
+  beginWorkflowExecution,
+  runWorkflowStartInterceptor,
+  startWorkflowExecution
+} from "./lifecycle/start-exec.js";
 export {
   buildForkBatchOperations,
   buildForkSearchAttributes,

package/dist/core/engine/listing.js

@@ -88,7 +88,7 @@ function summaryFromState(state, attributeFailureCategory) {
     type: state.type,
     status: state.status,
     ...state.tags !== void 0 && { tags: state.tags },
-    version: state.version,
+    version: state.versionTuple.workflowVersion,
     createdAt: state.createdAt,
     updatedAt: state.updatedAt,
     ...state.executionDeadline !== void 0 && { executionDeadline: state.executionDeadline },

package/dist/core/engine/operations-data.d.ts

@@ -19,5 +19,21 @@ export type DataOperationCallbacks = {
 export declare function processMemoOperation(_internals: EngineInternals, workflowId: string, operation: MemoOperation, callbacks: DataOperationCallbacks): Promise<void>;
 export declare function processOffloadOperation(internals: EngineInternals, workflowId: string, operation: OffloadOperation, callbacks: DataOperationCallbacks): Promise<void>;
 export declare function processLoadOperation(internals: EngineInternals, workflowId: string, operation: LoadOperation, callbacks: DataOperationCallbacks): Promise<void>;
+/**
+ * Read an offloaded value back out of storage by `workflowId` + `key`, decoding
+ * it with the same codec {@link processOffloadOperation} wrote it with.
+ *
+ * This is the post-completion sibling of the in-workflow `ctx.load()` read
+ * (see {@link processLoadOperation}): `ctx.load()` is restricted to the running
+ * workflow's own offloads and throws on a miss, whereas this external reader
+ * lets a consumer read a *terminal* workflow's offloaded output after
+ * `handle.result()` resolves — the artifact survives normal completion
+ * (`completeWorkflow`/`failWorkflow` preserve `offload:` keys) and is swept only
+ * when the workflow is terminated/cancelled.
+ *
+ * @returns The decoded offload value, or `null` when no value is stored under
+ *   that key (either the key was never written, or the artifact was swept).
+ */
+export declare function getOffloadFromInternals(internals: EngineInternals, workflowId: string, key: string): Promise<unknown>;
 export declare function processArchiveOperation(internals: EngineInternals, workflowId: string, operation: ArchiveOperation, callbacks: DataOperationCallbacks): Promise<void>;
 export {};

package/dist/core/engine/operations-data.js

@@ -30,6 +30,12 @@ export async function processLoadOperation(internals, workflowId, operation, cal
     return decode(raw);
   });
 }
+export async function getOffloadFromInternals(internals, workflowId, key) {
+  const raw = await internals.storage.get(KEYS.offload(workflowId, key));
+  if (raw === null)
+    return null;
+  return decode(raw);
+}
 export async function processArchiveOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     await internals.storage.put(KEYS.archive(workflowId, operation.key), encode(operation.data));

package/dist/core/engine/operations-time.d.ts

@@ -19,10 +19,11 @@ export type TimeOperationCallbacks = {
     runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
     handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
     timeout: (workflowId: string) => Promise<void>;
+    handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
 };
 export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
 export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
 export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void): void;
-export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'failWorkflow' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
-export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'workflowVersionTupleFromState'>): Promise<void>;
 export {};

package/dist/core/engine/operations-time.js

@@ -1,7 +1,8 @@
-import { KEYS } from "../../storage/interface.js";
+import { KEYS, storageHas } from "../../storage/interface.js";
 import { deserializeCheckpoint } from "../checkpoint.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
+import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
   return {
@@ -85,6 +86,10 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   });
   if (!runningState)
     return;
+  if (await reprovideRecoveredServices(internals, runningState, (workflowId, error) => callbacks.failWorkflow(workflowId, error), callbacks.handleCleanupError))
+    return;
+  if (await storageHas(internals.storage, KEYS.terminalCleanupNeeded(entry.workflowId)))
+    internals.workflowsNeedingTerminalCleanup.add(entry.workflowId);
   internals.checkpoints.set(entry.workflowId, checkpoint);
   internals.workflowVersionTuples.set(entry.workflowId, callbacks.workflowVersionTupleFromState(runningState));
   callbacks.setWorkflowStartHeaders(entry.workflowId, await callbacks.loadWorkflowStartHeaders(entry.workflowId));

package/dist/core/engine/persisted-data-version.d.ts

@@ -12,13 +12,9 @@ import type { Storage as WeftStorage } from '../../storage/interface.ts';
  * 3. Sentinel is absent. Only stamp the storage when it carries no user
  *    workflow data. Stamping a database that already holds workflow records,
  *    schedules, checkpoints, or any other `wf:` / `op:` / `schedule:` / `ev:`
- *    prefixed key would silently classify pre-versioned data (written by an
- *    older Weft binary or by the `new Engine({ storage })` constructor path
- *    before the sentinel was introduced) as schema-current and risk replaying
- *    incompatible records. When user data is already present without a
- *    sentinel, fail with `PersistedDataIncompatibleError(null, …)` so the
- *    operator can choose explicitly whether to wipe and start fresh.
+ *    prefixed key would silently classify unversioned data as schema-current
+ *    and risk replaying incompatible records. When user data is already present
+ *    without a sentinel, fail with `PersistedDataIncompatibleError(null, …)` so
+ *    the operator can choose explicitly whether to wipe and start fresh.
  */
-export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage, options?: {
-    allowLegacyData?: boolean;
-}): Promise<void>;
+export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage): Promise<void>;