@lostgradient/weft 0.2.0 → 0.3.0

package/dist/core/engine/inline-launch-queue.d.ts

@@ -9,6 +9,20 @@ export declare function queueInlineWorkflowExecutionStart(internals: EngineInter
 export declare function flushQueuedInlineWorkflowStarts(internals: EngineInternals, callbacks: InlineLaunchQueueCallbacks): Promise<void>;
 /** Used by scheduler-driven direct backfill flushes. Clears the scheduled flag first. */
 export declare function flushQueuedInlineWorkflowStartsDirectly(internals: EngineInternals, callbacks: InlineLaunchQueueCallbacks): Promise<void>;
+/**
+ * Drain every pending inline launch before engine teardown. Called from
+ * `[Symbol.asyncDispose]` *before* `disposeEngine` aborts the signal, so the
+ * flush actually executes the queued starts (the abort check in
+ * {@link flushQueuedInlineWorkflowStarts} would otherwise discard them). This
+ * turns a deferred-launch macrotask into work that completes before
+ * `asyncDispose` returns, so a disposed engine leaves no dangling pending
+ * launch — the fix for the test-runner macrotask-starvation footgun.
+ *
+ * A queued start that was already aborted (signal set before this is reached)
+ * is left for the synchronous `disposeQueuedInlineWorkflowStarts` path, which
+ * discards it and settles its `defer: false` awaiter.
+ */
+export declare function drainQueuedInlineWorkflowStarts(internals: EngineInternals, callbacks: InlineLaunchQueueCallbacks): Promise<void>;
 export declare function dropQueuedInlineWorkflowStart(internals: EngineInternals, workflowId: string): boolean;
 export declare function disposeQueuedInlineWorkflowStarts(internals: EngineInternals): void;
 export declare function hasQueuedInlineWorkflowStart(internals: EngineInternals, workflowId: string): boolean;

package/dist/core/engine/inline-launch-queue.js

@@ -17,9 +17,18 @@ export function queueInlineWorkflowExecutionStart(internals, start, callbacks) {
     callbacks.swallowPromiseRejection(flushQueuedInlineWorkflowStarts(internals, callbacks));
   }, 0);
 }
+function settleDiscardedInlineStarts(internals, discarded) {
+  for (const start of discarded) {
+    internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
+    internals.queuedOrLaunchingInlineWorkflowStartIds.delete(start.workflowId);
+    start.onStarted?.();
+  }
+}
 export async function flushQueuedInlineWorkflowStarts(internals, callbacks) {
   if (internals.abortController.signal.aborted) {
+    const discarded = internals.queuedInlineWorkflowStarts;
     internals.queuedInlineWorkflowStarts = [];
+    settleDiscardedInlineStarts(internals, discarded);
     return;
   }
   if (internals.queuedInlineWorkflowStarts.length === 0)
@@ -27,12 +36,21 @@ export async function flushQueuedInlineWorkflowStarts(internals, callbacks) {
   const pendingStarts = internals.queuedInlineWorkflowStarts;
   internals.queuedInlineWorkflowStarts = [];
   for (const start of pendingStarts)
-    await startQueuedInlineWorkflowExecution(internals, start, callbacks);
+    await callbacks.swallowPromiseRejection(startQueuedInlineWorkflowExecution(internals, start, callbacks));
 }
 export async function flushQueuedInlineWorkflowStartsDirectly(internals, callbacks) {
   internals.queuedInlineWorkflowStartFlushScheduled = !1;
   await flushQueuedInlineWorkflowStarts(internals, callbacks);
 }
+export async function drainQueuedInlineWorkflowStarts(internals, callbacks) {
+  internals.queuedInlineWorkflowStartFlushScheduled = !1;
+  let passes = 0;
+  const maxPasses = 1000;
+  while (internals.queuedInlineWorkflowStarts.length > 0 && !internals.abortController.signal.aborted && passes < maxPasses) {
+    passes += 1;
+    await callbacks.swallowPromiseRejection(flushQueuedInlineWorkflowStarts(internals, callbacks));
+  }
+}
 async function startQueuedInlineWorkflowExecution(internals, start, callbacks) {
   try {
     const state = await loadWorkflowState(internals, start.workflowId);
@@ -45,22 +63,29 @@ async function startQueuedInlineWorkflowExecution(internals, start, callbacks) {
   } finally {
     internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
     internals.queuedOrLaunchingInlineWorkflowStartIds.delete(start.workflowId);
+    start.onStarted?.();
   }
 }
 export function dropQueuedInlineWorkflowStart(internals, workflowId) {
   if (internals.queuedInlineWorkflowStarts.length === 0)
     return !1;
-  const initialLength = internals.queuedInlineWorkflowStarts.length;
-  internals.queuedInlineWorkflowStarts = internals.queuedInlineWorkflowStarts.filter((start) => start.workflowId !== workflowId);
-  if (internals.queuedInlineWorkflowStarts.length !== initialLength) {
-    internals.queuedInlineWorkflowStartIds.delete(workflowId);
-    internals.queuedOrLaunchingInlineWorkflowStartIds.delete(workflowId);
-  }
+  const initialLength = internals.queuedInlineWorkflowStarts.length, dropped = [];
+  internals.queuedInlineWorkflowStarts = internals.queuedInlineWorkflowStarts.filter((start) => {
+    if (start.workflowId === workflowId) {
+      dropped.push(start);
+      return !1;
+    }
+    return !0;
+  });
+  if (internals.queuedInlineWorkflowStarts.length !== initialLength)
+    settleDiscardedInlineStarts(internals, dropped);
   return internals.queuedInlineWorkflowStarts.length !== initialLength;
 }
 export function disposeQueuedInlineWorkflowStarts(internals) {
   internals.queuedInlineWorkflowStartFlushScheduled = !1;
+  const discarded = internals.queuedInlineWorkflowStarts;
   internals.queuedInlineWorkflowStarts = [];
+  settleDiscardedInlineStarts(internals, discarded);
   internals.queuedInlineWorkflowStartIds.clear();
   internals.queuedOrLaunchingInlineWorkflowStartIds.clear();
   const channel = internals.queuedInlineWorkflowStartChannel;

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

@@ -32,8 +32,11 @@ import type { Checkpoint } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
 import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
-import type { ScheduleHandleEngine, WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
+import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
+import type { WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
 import type { WorkflowFeedListener } from './index.ts';
+import type { ScheduleHandleEngine } from './schedule-handle.ts';
+import type { SecondInstanceDetector } from './second-instance-detector.ts';
 type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine;
 export interface EngineInternals {
     engine: EngineRuntime;
@@ -75,11 +78,15 @@ export interface EngineInternals {
     activityRegistry: ActivityRegistry;
     /**
      * Per-workflow activity registries built from
-     * `workflow({ name }).activities({ ... }).execute(...)`. Indexed by workflow
-     * type. Phase 3 wires lookups via `activityRegistriesByWorkflow.get(type)`
-     * first, falling back to {@link EngineInternals.activityRegistry} so the
-     * legacy global path keeps working until Phase 6 removes it. Each registry
-     * is constructed from a defensive deep clone+freeze of the workflow's
+     * `workflow({ name }).activities({ ... }).execute(...)`, indexed by workflow
+     * type. Activity lookup is per-activity: it consults the workflow's
+     * `activityRegistriesByWorkflow.get(type)` registry first and, for any activity
+     * that registry does not contain, falls back to the engine-wide
+     * {@link EngineInternals.activityRegistry}. Both sources are first-class — a
+     * workflow can resolve some activities from its own `activities(...)` map and
+     * others (shared/globally-registered) from the global registry, and a workflow
+     * with no per-workflow map resolves entirely from the global one. Each
+     * per-workflow registry is a defensive deep clone+freeze of the workflow's
      * `activities` map so post-registration mutation cannot reach the engine.
      */
     activityRegistriesByWorkflow: Map<string, ActivityRegistry>;
@@ -108,6 +115,14 @@ export interface EngineInternals {
     workflowHeaders: Map<string, Map<string, string>>;
     workflowStateWriteChains: Map<string, Promise<void>>;
     heartbeatDetails: Map<string, unknown>;
+    /**
+     * Per-run, non-serialized `services` value exposed to the workflow body as
+     * `ctx.services`. Set at `engine.start({ services })` and re-provided on
+     * recovery by `resolveWorkflowServices`. Never checkpointed — held only in
+     * engine memory, keyed by workflowId, and cleared on terminal cleanup (the
+     * same lifecycle as {@link heartbeatDetails}).
+     */
+    workflowServices: Map<string, unknown>;
     /**
      * Activities that called `ctx.completeAsync()` and are awaiting out-of-band
      * completion via `engine.completeAsyncActivity` / `failAsyncActivity`, keyed
@@ -119,13 +134,14 @@ export interface EngineInternals {
     pendingScheduleCreations: Set<string>;
     workflowsNeedingTerminalCleanup: Set<string>;
     cleanupInterval: ReturnType<typeof setInterval> | null;
-    cleanupIntervalDisposalTracker: {
-        disposed: boolean;
-        cleanupInterval: ReturnType<typeof setInterval> | null;
-    } | null;
+    cleanupIntervalDisposalTracker: EngineCleanupIntervalDisposalTracker | null;
     retentionSweepInterval: ReturnType<typeof setInterval> | null;
     retentionSweepInFlight: Promise<void> | null;
     nextRetentionSweepAt: number | null;
+    /** Interval driving the best-effort second-instance detector; `null` when off. */
+    secondInstanceDetectionInterval: ReturnType<typeof setInterval> | null;
+    /** The active second-instance detector; `null` when detection is disabled. */
+    secondInstanceDetector: SecondInstanceDetector | null;
     reviewCoordinator: ReviewCoordinator;
     reviewWaiters: Map<string, (decision: HumanReviewResult) => void>;
     reviewWaitersByWorkflow: Map<string, TrackedWaiterKeys>;

package/dist/core/engine/lifecycle/fork-helpers.js

@@ -22,17 +22,11 @@ export function createForkedWorkflowState(_internals, workflowId, sourceState, v
     type: sourceState.type,
     status: "running",
     input: sourceState.input,
-    version: versionTuple.workflowVersion,
+    versionTuple,
     executionStateOwnerId: workflowId,
     createdAt: forkedAt,
     startedAt: forkedAt,
     updatedAt: forkedAt,
-    ...versionTuple.agentVersion !== void 0 && {
-      agentVersion: versionTuple.agentVersion
-    },
-    ...versionTuple.toolVersions !== void 0 && {
-      toolVersions: versionTuple.toolVersions
-    },
     forkedFrom: lineage
   };
 }

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

@@ -16,28 +16,13 @@ export function createWorkflowVersionTuple(_internals, registration, _callbacks)
   };
 }
 export function workflowVersionTupleFromState(_internals, state, _callbacks) {
-  return {
-    workflowVersion: state.version,
-    ...state.agentVersion !== void 0 && { agentVersion: state.agentVersion },
-    ...state.toolVersions !== void 0 && { toolVersions: state.toolVersions }
-  };
+  return state.versionTuple;
 }
 export function workflowStateWithVersionTuple(internals, state, versionTuple, _callbacks) {
-  const {
-    agentVersion: _existingAgentVersion,
-    toolVersions: _existingToolVersions,
-    ...rest
-  } = state;
   return {
-    ...rest,
-    version: versionTuple.workflowVersion,
-    updatedAt: internals.options.getNow(),
-    ...versionTuple.agentVersion !== void 0 && {
-      agentVersion: versionTuple.agentVersion
-    },
-    ...versionTuple.toolVersions !== void 0 && {
-      toolVersions: versionTuple.toolVersions
-    }
+    ...state,
+    versionTuple,
+    updatedAt: internals.options.getNow()
   };
 }
 export function derivePreparedExecutionState(internals, workflowId, state, checkpoint, registration, callbacks) {
@@ -76,5 +61,5 @@ export async function prepareResumeState(internals, workflowId, state, checkpoin
   };
 }
 export function throwVersionMismatch(_internals, workflowId, state, registration, versionDiff, _callbacks) {
-  throw new VersionMismatchError(workflowId, state.type, state.version, registration.version, void 0, versionDiff);
+  throw new VersionMismatchError(workflowId, state.type, state.versionTuple.workflowVersion, registration.version, void 0, versionDiff);
 }

package/dist/core/engine/lifecycle/recovered-services.d.ts

@@ -0,0 +1,45 @@
+import type { WorkflowState } from '../../types.ts';
+import type { EngineInternals } from '../internals.ts';
+/**
+ * Re-provide a recovered inline workflow's non-serialized `services` before its
+ * generator is driven forward, and decide whether execution should proceed.
+ *
+ * Both recovery entry points use this: `resumeWorkflowFromStorage` (for a run
+ * left `running`) and the delayed-start timer handler (for a `startAfter`/
+ * `startAt` run that crashed `pending` before its timer fired). On a fresh
+ * process the in-memory `workflowServices` map is empty, so without this a
+ * recovered run that originally had services would silently execute with
+ * `ctx.services === undefined`.
+ *
+ * The resolver is only consulted for runs launched WITH services, detected by
+ * the durable `KEYS.workflowHasServices` marker. A run that never had services
+ * has no marker and proceeds without touching the resolver — so a fail-closed
+ * resolver does not fail healthy no-services runs.
+ *
+ * Returns `false` to proceed (services available, none expected, or no resolver
+ * is configured). Returns `true` to STOP — the run was terminally
+ * failed (services unavailable), or the terminal commit faulted and the run was
+ * left for a later boot to retry. Either way the generator must not advance:
+ * driving it without services would crash the body and that throw would escape
+ * into the recovery loop, aborting sibling runs.
+ *
+ * Worker mode skips this (services are inline-only, rejected at `engine.start()`).
+ * A resolver throw is treated as `unavailable` with the error as the reason,
+ * for the same sibling-isolation reason.
+ *
+ * @param failRun - Terminally fails just this run with `reason`. Supplied by the
+ *   caller because the two entry points reach the termination machinery through
+ *   different callback bundles. It receives the canonical terminal error built
+ *   by {@link unavailableServicesError}, so both recovery paths fail the run
+ *   with an identical message and (via `failWorkflow`'s default) the `system`
+ *   failure category.
+ * @param onCommitError - Records a fail-warn when `failRun` itself throws, so the
+ *   swallowed terminal-commit fault is still observable.
+ */
+export declare function reprovideRecoveredServices(internals: EngineInternals, state: WorkflowState, failRun: (workflowId: string, error: Error) => Promise<void>, onCommitError: (source: string, error: unknown, workflowId: string) => void): Promise<boolean>;
+/**
+ * The canonical terminal error for a recovered run whose services could not be
+ * re-provided. Shared by both recovery paths so they fail with an identical
+ * message (the failure category is `system`, the default for `failWorkflow`).
+ */
+export declare function unavailableServicesError(workflowId: string, reason: string): Error;

package/dist/core/engine/lifecycle/recovered-services.js

@@ -0,0 +1,34 @@
+import { KEYS } from "../../../storage/interface.js";
+export async function reprovideRecoveredServices(internals, state, failRun, onCommitError) {
+  const resolver = internals.options.resolveWorkflowServices;
+  if (internals.inlineStrategy === null || !resolver)
+    return !1;
+  if (internals.workflowServices.has(state.id))
+    return !1;
+  if (await internals.storage.get(KEYS.workflowHasServices(state.id)) === null)
+    return !1;
+  let reason;
+  try {
+    const resolution = await resolver({
+      workflowId: state.id,
+      workflowType: state.type,
+      input: state.input
+    });
+    if (resolution.status === "available") {
+      internals.workflowServices.set(state.id, resolution.services);
+      return !1;
+    }
+    reason = resolution.reason;
+  } catch (error) {
+    reason = error instanceof Error ? error.message : String(error);
+  }
+  try {
+    await failRun(state.id, unavailableServicesError(state.id, reason));
+  } catch (error) {
+    onCommitError("reprovideRecoveredServices", error, state.id);
+  }
+  return !0;
+}
+export function unavailableServicesError(workflowId, reason) {
+  return Error(`Recovered workflow "${workflowId}" services unavailable: ${reason}`);
+}

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

@@ -1,21 +1,28 @@
 import { KEYS } from "../../../storage/interface.js";
 import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
+import { encode } from "../../codec.js";
 import { Context, setContextWorkflowInterceptor } from "../../context.js";
 import { EventLog } from "../../event-log.js";
 import { WorkflowResumedEvent } from "../../events.js";
+import { buildTimerBatchOperations } from "../../scheduler.js";
 import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
 import { rememberCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { getWorkflowExecutionStartedAt } from "../handles.js";
 import { loadWorkflowState } from "../storage-io.js";
 import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
 import { decodeWorkflowState } from "../validation.js";
+import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
 import { prepareResumeState } from "./persist.js";
+import { reprovideRecoveredServices } from "./recovered-services.js";
 import {
   enforceHistoryPolicyBeforeReplay,
   loadTerminalCleanupTrackedState,
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
 } from "./shared.js";
+async function prepareRecoveredServicesOrFail(internals, state, callbacks) {
+  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError);
+}
 function assertResumeNotTerminating(internals, workflowId) {
   if (internals.terminalizingWorkflows.has(workflowId))
     throw Error(`Cannot resume workflow "${workflowId}": termination is in progress`);
@@ -57,7 +64,8 @@ function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
     sleepReferenceTime: resumeCheckpoint.createdAt,
     ...latestState.executionDeadline !== void 0 && {
       deadline: latestState.executionDeadline
-    }
+    },
+    services: internals.workflowServices.get(workflowId)
   });
   setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
   if (internals.options.development)
@@ -90,8 +98,9 @@ async function performSerializedResume(internals, args) {
   assertResumeNotTerminating(internals, workflowId);
   if (!latestState)
     throw Error(`Workflow "${workflowId}" not found in storage`);
-  if (latestState.status !== "running")
-    throw Error(`Cannot resume workflow "${workflowId}": status is "${latestState.status}", expected "running"`);
+  if (latestState.status !== "running" && latestState.status !== "suspended")
+    throw Error(`Cannot resume workflow "${workflowId}": status is "${latestState.status}", expected "running" or "suspended"`);
+  await reactivateSuspendedWorkflowState(internals, latestState);
   commitSerializedResumeState(internals, args);
   if (internals.inlineStrategy) {
     relaunchInlineWorkflowAfterResume(internals, latestState, args);
@@ -99,13 +108,30 @@ async function performSerializedResume(internals, args) {
   }
   relaunchWorkerWorkflowAfterResume(internals, latestState, args);
 }
+async function reactivateSuspendedWorkflowState(internals, state) {
+  if (state.status !== "suspended")
+    return;
+  const previousState = { ...state };
+  state.status = "running";
+  state.updatedAt = internals.options.getNow();
+  await internals.storage.batch([
+    { type: "put", key: KEYS.workflow(state.id), value: encode(state) },
+    ...buildWorkflowVisibilityIndexTransition(state.id, previousState, state).batchOps,
+    ...state.executionDeadline !== void 0 ? buildTimerBatchOperations({
+      id: `deadline:${state.id}`,
+      workflowId: state.id,
+      fireAt: state.executionDeadline,
+      kind: "execution-deadline"
+    }) : []
+  ]);
+}
 export async function resumeWorkflowFromStorage(internals, workflowId, dispatchResumedEvent, callbacks) {
   const stateBytes = await internals.storage.get(KEYS.workflow(workflowId));
   if (!stateBytes)
     throw Error(`Workflow "${workflowId}" not found in storage`);
   const state = decodeWorkflowState(stateBytes);
-  if (state.status !== "running")
-    throw Error(`Cannot resume workflow "${workflowId}": status is "${state.status}", expected "running"`);
+  if (state.status !== "running" && state.status !== "suspended")
+    throw Error(`Cannot resume workflow "${workflowId}": status is "${state.status}", expected "running" or "suspended"`);
   const checkpointBytes = await internals.storage.get(KEYS.checkpoint(workflowId));
   if (!checkpointBytes)
     throw Error(`Checkpoint not found for workflow "${workflowId}"`);
@@ -117,6 +143,8 @@ export async function resumeWorkflowFromStorage(internals, workflowId, dispatchR
     return callbacks.getHandle(workflowId);
   const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks);
   await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
+  if (await prepareRecoveredServicesOrFail(internals, state, callbacks))
+    return callbacks.getHandle(workflowId);
   const handle = callbacks.getHandle(workflowId);
   await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
     workflowId,

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

@@ -48,6 +48,14 @@ export type LifecycleCallbacks = {
      * history is terminated without being replayed.
      */
     enforceHistoryCircuitBreaker: (workflowId: string) => Promise<void>;
+    /**
+     * Force a recovered workflow to a terminal `failed` state because its
+     * non-serialized `services` could not be re-provided (the engine's
+     * `resolveWorkflowServices` reported `unavailable`). Fails just this run with
+     * a `system` failure category; the engine and other recovered runs continue.
+     * `error` is the canonical {@link unavailableServicesError}.
+     */
+    failWorkflowForUnavailableServices: (workflowId: string, error: Error) => Promise<void>;
 };
 /**
  * Pre-replay history circuit breaker. Called at every restore-from-checkpoint

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

@@ -19,18 +19,7 @@ export function buildStartBatchOperations(_internals, workflowId, state, checkpo
     ...visibilityIndexOperations,
     ...buildWorkflowTagIndexOperations(workflowId, void 0, state.tags),
     ...buildInitialSearchAttributeOperations(_internals, workflowId, registration, options?.searchAttributes, callbacks),
-    ...workflowStartHeaders && workflowStartHeaders.size > 0 ? [
-      {
-        type: "put",
-        key: KEYS.workflowHeaders(workflowId),
-        value: encodeWorkflowStartHeaders(workflowStartHeaders)
-      },
-      {
-        type: "put",
-        key: KEYS.terminalCleanupNeeded(workflowId),
-        value: EMPTY_STORAGE_VALUE
-      }
-    ] : [],
+    ...buildPerRunScratchOperations(workflowId, options, workflowStartHeaders),
     ...additionalOperations ?? []
   ];
   if (executionDeadline !== void 0)
@@ -44,6 +33,28 @@ export function buildStartBatchOperations(_internals, workflowId, state, checkpo
     operations.push(...buildTimerBatchOperations(delayedStartTimer));
   return operations;
 }
+function buildPerRunScratchOperations(workflowId, options, workflowStartHeaders) {
+  const hasHeaders = workflowStartHeaders !== void 0 && workflowStartHeaders.size > 0, hasServices = options?.services !== void 0, operations = [];
+  if (hasHeaders)
+    operations.push({
+      type: "put",
+      key: KEYS.workflowHeaders(workflowId),
+      value: encodeWorkflowStartHeaders(workflowStartHeaders)
+    });
+  if (hasServices)
+    operations.push({
+      type: "put",
+      key: KEYS.workflowHasServices(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
+  if (hasHeaders || hasServices)
+    operations.push({
+      type: "put",
+      key: KEYS.terminalCleanupNeeded(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
+  return operations;
+}
 export function buildInitialSearchAttributeOperations(_internals, workflowId, registration, searchAttributes, callbacks) {
   if (!searchAttributes || Object.keys(searchAttributes).length === 0)
     return [];

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

@@ -0,0 +1,47 @@
+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 LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
+/**
+ * Builds the id-dependent operations and compare-and-swap preconditions for an
+ * idempotent start or `startOrSignal`. Invoked by `startWorkflow` with the real
+ * `workflowId` once it has been generated, so the idempotency mapping put (and
+ * any create-batch signal) can carry that id. The whole start batch then commits
+ * through a single `storageConditionalBatch` gated on the returned conditions; a
+ * lost CAS rolls back the start and throws {@link StartIdempotencyRaceLostError}
+ * so the caller resolves to the winner.
+ */
+export type BuildIdempotentStartOperations = (workflowId: string) => {
+    operations: BatchOperation[];
+    conditions: ConditionalBatchCondition[];
+};
+/**
+ * Internal sentinel: the idempotent create batch lost its compare-and-swap to a
+ * concurrent caller holding the same idempotency key. Never surfaced to users —
+ * `start` / `startOrSignal` catch it and resolve to the winning run's handle.
+ */
+export declare class StartIdempotencyRaceLostError extends Error {
+    constructor();
+}
+/** Everything {@link buildAndCommitStartBatch} needs to assemble the start batch. */
+export type StartBatchContext = {
+    internals: EngineInternals;
+    workflowId: string;
+    state: WorkflowState;
+    checkpoint: Checkpoint;
+    registration: RegistrationEntry;
+    options: StartOptions | undefined;
+    delayedStartTimer: TimerEntry | undefined;
+    persistedWorkflowStartHeaders: Map<string, string> | undefined;
+    additionalStartOperations: BatchOperation[] | undefined;
+    callbacks: LifecycleCallbacks;
+};
+/**
+ * Assemble the start batch — folding in the id-dependent idempotency mapping and
+ * create-batch signal once the real workflow id exists — and commit it, gated on
+ * any idempotency preconditions. Throws {@link StartIdempotencyRaceLostError}
+ * when a concurrent same-key caller won the compare-and-swap, so the calling
+ * `startWorkflow` rolls back its transient state and the wrapper resolves to the
+ * winning run.
+ */
+export declare function buildAndCommitStartBatch(context: StartBatchContext, buildIdempotentStartOperations: BuildIdempotentStartOperations | undefined): Promise<void>;

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

@@ -0,0 +1,27 @@
+import { requireStorageCapability, storageConditionalBatch } from "../../../storage/interface.js";
+import { buildStartBatchOperations } from "./start-batch.js";
+
+export class StartIdempotencyRaceLostError extends Error {
+  constructor() {
+    super("start idempotency compare-and-swap lost to a concurrent caller");
+    this.name = "StartIdempotencyRaceLostError";
+  }
+}
+async function persistStartBatch(internals, startOperations, conditions) {
+  if (conditions === void 0) {
+    await internals.storage.batch(startOperations);
+    return !0;
+  }
+  requireStorageCapability(internals.storage, "conditionalBatch", "start idempotency");
+  return storageConditionalBatch(internals.storage, conditions, startOperations);
+}
+function mergeAdditionalStartOperations(additional, idempotent) {
+  if (idempotent === void 0 || idempotent.length === 0)
+    return additional;
+  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;
+}

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

@@ -1,5 +1,33 @@
-import type { Checkpoint } from '../../types.ts';
+import type { Checkpoint, StartOptions, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
-import { type LifecycleCallbacks } from './shared.ts';
+import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
 export declare function runWorkflowStartInterceptor(_internals: EngineInternals, workflowId: string, workflowType: string, input: unknown, parentHeaders: Map<string, string> | undefined, callbacks: LifecycleCallbacks): Map<string, string> | undefined;
 export declare function startWorkflowExecution(internals: EngineInternals, workflowId: string, workflowType: string, input: unknown, checkpoint: Checkpoint, nestingDepth: number, executionDeadline: number | undefined, executionStateOwnerId: string, _callbacks?: LifecycleCallbacks): void;
+export declare function beginWorkflowExecution(internals: EngineInternals, workflowId: string, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, _registration: RegistrationEntry, callbacks: LifecycleCallbacks, onStarted?: () => void): void;
+/**
+ * `defer: false` is an inline-only liveness gate: it awaits the moment the
+ * generator is first driven. A worker-mode start queues to the Worker transport
+ * (no inline liveness to await), and a delayed start has not begun executing at
+ * all — so both reject rather than silently behaving like `defer: true`.
+ */
+export declare function assertDeferSupported(internals: EngineInternals, options: StartOptions | undefined, isDelayedStart: boolean): void;
+type BeginExecutionParams = {
+    type: string;
+    input: unknown;
+    checkpoint: Checkpoint;
+    state: WorkflowState;
+    registration: RegistrationEntry;
+    options: StartOptions | undefined;
+    isDelayed: boolean;
+};
+/**
+ * Drive the initial execution for a freshly-started workflow and, when
+ * `defer: false`, await the run actually beginning before resolving. A delayed
+ * start does not begin executing now, so it neither begins execution here nor
+ * awaits liveness. The liveness promise is settled by the inline-launch queue
+ * once the generator is driven (or by dispose if the queued start is discarded),
+ * so a `defer: false` caller can rely on the run being live without a macrotask
+ * round-trip the moment `engine.start()` resolves.
+ */
+export declare function beginExecutionAwaitingLiveness(internals: EngineInternals, params: BeginExecutionParams, workflowId: string, callbacks: LifecycleCallbacks): Promise<void>;
+export {};

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