@lostgradient/weft 0.2.1 → 0.4.0

package/dist/core/engine/lease-manager.js

@@ -0,0 +1,135 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import {
+  decodeEpoch,
+  decodeHolder,
+  encodeEpoch,
+  encodeHolder
+} from "./lease-codec.js";
+import { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError } from "./lease-errors.js";
+const DEFAULT_ACQUIRE_POLL_INTERVAL_MS = 1000;
+export function createLeaseManager(options) {
+  const { storage, holderId, getNow, ttlMs, renewIntervalMs, waitTimeoutMs } = options, acquirePollIntervalMs = options.acquirePollIntervalMs ?? DEFAULT_ACQUIRE_POLL_INTERVAL_MS, unconfirmableMarginMs = renewIntervalMs;
+  let stopped = !1, heldEpoch = null, heldEpochBytes = null, lastHolderBytes = null, renewalInterval = null, leaseLost = !1, inFlightRenewal = null;
+  const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  function reportLeaseLost(reason) {
+    if (leaseLost)
+      return;
+    leaseLost = !0;
+    options.onLeaseLost?.(reason);
+  }
+  async function readState() {
+    const holderRaw = await storage.get(KEYS.leaseHolder()), epochRaw = await storage.get(KEYS.leaseEpoch());
+    return {
+      epochRaw,
+      holderRaw,
+      epoch: epochRaw === null ? null : decodeEpoch(epochRaw),
+      holder: holderRaw === null ? null : decodeHolder(holderRaw)
+    };
+  }
+  async function takeOwnership(expectedEpochBytes, expectedHolderBytes, nextEpoch) {
+    const expiresAt = getNow() + ttlMs, holderBytes = encodeHolder({ holderId, expiresAt, epoch: nextEpoch }), committed = await storageConditionalBatch(storage, [
+      { key: KEYS.leaseEpoch(), expectedValue: expectedEpochBytes },
+      { key: KEYS.leaseHolder(), expectedValue: expectedHolderBytes }
+    ], [
+      { type: "put", key: KEYS.leaseEpoch(), value: encodeEpoch(nextEpoch) },
+      { type: "put", key: KEYS.leaseHolder(), value: holderBytes }
+    ]);
+    if (committed) {
+      heldEpoch = nextEpoch;
+      heldEpochBytes = encodeEpoch(nextEpoch);
+      lastHolderBytes = holderBytes;
+    }
+    return committed;
+  }
+  async function tryAcquireOnce() {
+    const { epochRaw, holderRaw, epoch, holder } = await readState();
+    if (epochRaw !== null && epoch === null)
+      throw new EngineLeaseCorruptedError('the "lease:epoch" high-water mark is present but does not decode to a valid epoch');
+    if (epochRaw === null && holderRaw !== null)
+      throw new EngineLeaseCorruptedError('a "lease:holder" record exists with no "lease:epoch" key (the lease protocol never deletes the epoch)');
+    if (holder !== null && getNow() < holder.expiresAt)
+      return !1;
+    const nextEpoch = (epoch ?? 0) + 1;
+    if (nextEpoch >= Number.MAX_SAFE_INTEGER)
+      throw new EngineLeaseCorruptedError(`the next ownership epoch (${nextEpoch}) is at or above the safe-integer ceiling and cannot be minted without bricking future boots`);
+    return takeOwnership(epochRaw, holderRaw, nextEpoch);
+  }
+  async function acquire() {
+    const startedAt = getNow(), deadline = startedAt + waitTimeoutMs;
+    let lastHolderId = null, firstAttempt = !0;
+    for (;; ) {
+      if (stopped)
+        return;
+      if (!firstAttempt && getNow() >= deadline)
+        throw new EngineLeaseAcquisitionTimeoutError(getNow() - startedAt, lastHolderId);
+      firstAttempt = !1;
+      if (await tryAcquireOnce())
+        return;
+      const holderRaw = await storage.get(KEYS.leaseHolder());
+      lastHolderId = holderRaw === null ? null : decodeHolder(holderRaw)?.holderId ?? null;
+      if (getNow() >= deadline)
+        throw new EngineLeaseAcquisitionTimeoutError(getNow() - startedAt, lastHolderId);
+      await delay(acquirePollIntervalMs);
+    }
+  }
+  async function renewOnce() {
+    if (stopped || leaseLost || heldEpoch === null || lastHolderBytes === null)
+      return;
+    const expiresAt = getNow() + ttlMs, holderBytes = encodeHolder({ holderId, expiresAt, epoch: heldEpoch });
+    let committed;
+    try {
+      committed = await storageConditionalBatch(storage, [{ key: KEYS.leaseHolder(), expectedValue: lastHolderBytes }], [{ type: "put", key: KEYS.leaseHolder(), value: holderBytes }]);
+    } catch {
+      const priorExpiry = decodeHolder(lastHolderBytes)?.expiresAt ?? 0;
+      if (getNow() >= priorExpiry - unconfirmableMarginMs)
+        reportLeaseLost("renewal-unconfirmable");
+      return;
+    }
+    if (committed) {
+      lastHolderBytes = holderBytes;
+      return;
+    }
+    reportLeaseLost("deposed");
+  }
+  function renewUnderGuard() {
+    if (inFlightRenewal !== null)
+      return;
+    inFlightRenewal = renewOnce().catch(() => {}).finally(() => {
+      inFlightRenewal = null;
+    });
+  }
+  function startRenewal() {
+    if (stopped || renewalInterval !== null)
+      return;
+    renewalInterval = setInterval(() => {
+      renewUnderGuard();
+    }, renewIntervalMs);
+    renewalInterval.unref?.();
+  }
+  function currentEpochBytes() {
+    return heldEpochBytes === null ? null : heldEpochBytes.slice();
+  }
+  function clearRenewal() {
+    if (renewalInterval !== null) {
+      clearInterval(renewalInterval);
+      renewalInterval = null;
+    }
+  }
+  async function release() {
+    stopped = !0;
+    clearRenewal();
+    if (inFlightRenewal !== null)
+      await inFlightRenewal;
+    if (lastHolderBytes === null)
+      return;
+    try {
+      if (await storageConditionalBatch(storage, [{ key: KEYS.leaseHolder(), expectedValue: lastHolderBytes }], [{ type: "delete", key: KEYS.leaseHolder() }]))
+        lastHolderBytes = null;
+    } catch {}
+  }
+  function stop() {
+    stopped = !0;
+    clearRenewal();
+  }
+  return { acquire, startRenewal, renewOnce, currentEpochBytes, release, stop };
+}

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

@@ -1,80 +1,43 @@
-import { serializeCheckpoint } from "../../checkpoint.js";
-import { encode } from "../../codec.js";
-import {
-  VersionMismatchError,
-  buildVersionUpdateOperations,
-  checkVersionCompatibility,
-  migrateCheckpoint
-} from "../../versioning.js";
+import { VersionMismatchError, checkVersionCompatibility } from "../../versioning.js";
 import {
   diffWorkflowVersionTuples
 } from "../../workflow-version-tuple.js";
-import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
+import { hydrateCheckpointReplayState } from "../checkpoint-replay.js";
 export function createWorkflowVersionTuple(_internals, registration, _callbacks) {
   return {
     workflowVersion: registration.version
   };
 }
 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) {
-  const compatibility = checkVersionCompatibility(checkpoint.version, registration.version, !!registration.migrate), registeredVersionTuple = createWorkflowVersionTuple(internals, registration, callbacks), versionDiff = diffWorkflowVersionTuples(workflowVersionTupleFromState(internals, state, callbacks), registeredVersionTuple), hasVersionTupleDrift = versionDiff.workflowVersion !== void 0 || versionDiff.agentVersion !== void 0 || versionDiff.toolVersions !== void 0;
-  if (compatibility === "incompatible" || hasVersionTupleDrift && !registration.migrate)
+  const compatibility = checkVersionCompatibility(checkpoint.version, registration.version), registeredVersionTuple = createWorkflowVersionTuple(internals, registration, callbacks), versionDiff = diffWorkflowVersionTuples(workflowVersionTupleFromState(internals, state, callbacks), registeredVersionTuple), hasVersionTupleDrift = versionDiff.workflowVersion !== void 0 || versionDiff.agentVersion !== void 0 || versionDiff.toolVersions !== void 0;
+  if (compatibility === "incompatible" || hasVersionTupleDrift)
     throwVersionMismatch(internals, workflowId, state, registration, versionDiff, callbacks);
-  let preparedState = state, preparedCheckpoint = checkpoint, shouldPersistPreparedState = !1;
-  if ((compatibility === "needs-migration" || hasVersionTupleDrift) && registration.migrate) {
-    const migrated = migrateCheckpoint(checkpoint, checkpoint.version, registration.version, registration.migrate);
-    migrated.version = registeredVersionTuple.workflowVersion;
-    preparedCheckpoint = migrated;
-    preparedState = workflowStateWithVersionTuple(internals, state, registeredVersionTuple, callbacks);
-    shouldPersistPreparedState = !0;
-  }
   return {
-    state: preparedState,
-    checkpoint: preparedCheckpoint,
+    state,
+    checkpoint,
     versionTuple: registeredVersionTuple,
-    shouldPersistPreparedState
+    shouldPersistPreparedState: !1
   };
 }
 export async function prepareResumeState(internals, workflowId, state, checkpoint, checkpointBytes, registration, callbacks) {
-  const preparedExecutionState = derivePreparedExecutionState(internals, workflowId, state, checkpoint, registration, callbacks);
-  if (preparedExecutionState.shouldPersistPreparedState) {
-    const versionVisibilityOperations = buildWorkflowVisibilityIndexTransition(workflowId, state, preparedExecutionState.state).batchOps;
-    await internals.storage.batch([
-      ...buildVersionUpdateOperations(workflowId, serializeCheckpoint(preparedExecutionState.checkpoint), preparedExecutionState.versionTuple.workflowVersion, encode(preparedExecutionState.state)),
-      ...versionVisibilityOperations
-    ]);
-  }
+  const preparedExecutionState = derivePreparedExecutionState(internals, workflowId, state, checkpoint, registration, callbacks), hydratedCheckpoint = await hydrateCheckpointReplayState(internals.storage, workflowId, preparedExecutionState.checkpoint);
   return {
     state: preparedExecutionState.state,
-    checkpoint: preparedExecutionState.checkpoint,
-    serializedCheckpoint: preparedExecutionState.shouldPersistPreparedState ? serializeCheckpoint(preparedExecutionState.checkpoint) : checkpointBytes,
+    checkpoint: hydratedCheckpoint,
+    serializedCheckpoint: checkpointBytes,
     versionTuple: preparedExecutionState.versionTuple
   };
 }
 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

@@ -16,8 +16,8 @@ import type { EngineInternals } from '../internals.ts';
  * 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
+ * Returns `false` to proceed (services available or none expected). 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
@@ -36,10 +36,12 @@ import type { EngineInternals } from '../internals.ts';
  * @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>;
+export declare function reprovideRecoveredServices(internals: EngineInternals, state: WorkflowState, failRun: (workflowId: string, error: Error) => Promise<void>, onCommitError: (source: string, error: unknown, workflowId: string) => void, dispatchDiagnostic?: (event: Event) => 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`).
+ * The canonical terminal error for any run whose services could not be provided —
+ * both recovery re-provision paths and a scheduled-occurrence launch. Shared so
+ * every caller fails with an identical message (the failure category is `system`,
+ * the default for `failWorkflow`). The message is recovery-agnostic because a
+ * freshly launched scheduled occurrence has never been recovered.
  */
 export declare function unavailableServicesError(workflowId: string, reason: string): Error;

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

@@ -1,12 +1,24 @@
 import { KEYS } from "../../../storage/interface.js";
-export async function reprovideRecoveredServices(internals, state, failRun, onCommitError) {
+import { DevelopmentWarningEvent } from "../../events.js";
+const RESOLVE_WORKFLOW_SERVICES_OPTION_PATH = "EngineOptions.resolveWorkflowServices";
+export async function reprovideRecoveredServices(internals, state, failRun, onCommitError, dispatchDiagnostic = () => {}) {
   const resolver = internals.options.resolveWorkflowServices;
-  if (internals.inlineStrategy === null || !resolver)
+  if (internals.inlineStrategy === null)
     return !1;
   if (internals.workflowServices.has(state.id))
     return !1;
   if (await internals.storage.get(KEYS.workflowHasServices(state.id)) === null)
     return !1;
+  if (!resolver) {
+    const reason = missingServicesResolverReason(state.id);
+    dispatchDiagnostic(new DevelopmentWarningEvent(state.id, reason, [RESOLVE_WORKFLOW_SERVICES_OPTION_PATH]));
+    try {
+      await failRun(state.id, unavailableServicesError(state.id, reason));
+    } catch (error) {
+      onCommitError("reprovideRecoveredServices", error, state.id);
+    }
+    return !0;
+  }
   let reason;
   try {
     const resolution = await resolver({
@@ -30,5 +42,8 @@ export async function reprovideRecoveredServices(internals, state, failRun, onCo
   return !0;
 }
 export function unavailableServicesError(workflowId, reason) {
-  return Error(`Recovered workflow "${workflowId}" services unavailable: ${reason}`);
+  return Error(`Workflow "${workflowId}" services unavailable: ${reason}`);
+}
+function missingServicesResolverReason(workflowId) {
+  return `Workflow "${workflowId}" was started with services, but this engine has no resolveWorkflowServices option. Configure EngineOptions.resolveWorkflowServices before recovery so ctx.services can be re-provided.`;
 }

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

@@ -1,14 +1,19 @@
 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 { rehydrateChildCancellationHandlers } from "../child-workflow-cancellation.js";
+import { commitFencedEngineWrite } from "../fenced-write.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 {
@@ -18,7 +23,7 @@ import {
   setWorkflowStartHeaders
 } from "./shared.js";
 async function prepareRecoveredServicesOrFail(internals, state, callbacks) {
-  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError);
+  return reprovideRecoveredServices(internals, state, callbacks.failWorkflowForUnavailableServices, callbacks.handleCleanupError, callbacks.dispatchEvent);
 }
 function assertResumeNotTerminating(internals, workflowId) {
   if (internals.terminalizingWorkflows.has(workflowId))
@@ -40,9 +45,10 @@ function commitSerializedResumeState(internals, args) {
   setWorkflowStartHeaders(internals, workflowId, args.workflowStartHeaders, callbacks);
   internals.parkedInlineWorkflows.delete(workflowId);
 }
-function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
+async function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
   const { workflowId, resumeCheckpoint, registration, callbacks } = args, accumulatedResults = new Map(resumeCheckpoint.accumulatedResults), workflowAbort = new AbortController;
   resetCancelHandlers(internals, workflowId);
+  await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
   const context = new Context({
     workflowId,
     workflowType: latestState.type,
@@ -62,7 +68,8 @@ function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
     ...latestState.executionDeadline !== void 0 && {
       deadline: latestState.executionDeadline
     },
-    services: internals.workflowServices.get(workflowId)
+    services: internals.workflowServices.get(workflowId),
+    ...internals.options.onLog != null && { logSink: internals.options.onLog }
   });
   setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
   if (internals.options.development)
@@ -71,8 +78,11 @@ function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
   inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
   inlineStrategy.continueWorkflow(workflowId, void 0);
 }
-function relaunchWorkerWorkflowAfterResume(internals, latestState, args) {
-  const { workflowId, resumeCheckpoint, workflowStartHeaders } = args, serialized = serializeCheckpoint(resumeCheckpoint);
+async function relaunchWorkerWorkflowAfterResume(internals, latestState, args) {
+  const { workflowId, resumeCheckpoint, workflowStartHeaders, callbacks } = args;
+  resetCancelHandlers(internals, workflowId);
+  await rehydrateChildCancellationHandlers(internals, workflowId, callbacks);
+  const serialized = serializeCheckpoint(resumeCheckpoint);
   internals.strategy.startWorkflow({
     workflowId,
     workflowType: latestState.type,
@@ -95,22 +105,40 @@ 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);
+    await relaunchInlineWorkflowAfterResume(internals, latestState, args);
     return;
   }
-  relaunchWorkerWorkflowAfterResume(internals, latestState, args);
+  await 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 commitFencedEngineWrite(internals, [
+    { 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"
+    }) : []
+  ], [], () => Error(`Resume of workflow "${state.id}" lost its CAS race.`));
 }
 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}"`);

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

@@ -22,7 +22,7 @@ export declare const EMPTY_STORAGE_VALUE: Uint8Array<ArrayBuffer>;
 export type RecoverAllOptions = {
     /**
      * Skip stored running workflows whose type is not registered. Use only for
-     * rolling deploys or explicit storage migrations.
+     * rolling deploys or explicit operator storage repair.
      */
     acknowledgeUnknownWorkflowTypes?: boolean;
 };
@@ -56,6 +56,13 @@ export type LifecycleCallbacks = {
      * `error` is the canonical {@link unavailableServicesError}.
      */
     failWorkflowForUnavailableServices: (workflowId: string, error: Error) => Promise<void>;
+    /**
+     * Force a recovered workflow to a terminal `failed` state because its
+     * persisted checkpoint cannot be decoded on this runtime. The failure is
+     * isolated to the affected run so `recoverAll()` can continue recovering
+     * other workflows from the same storage backend.
+     */
+    failWorkflowForCheckpointDecodeError: (workflowId: string, error: Error) => Promise<void>;
 };
 /**
  * Pre-replay history circuit breaker. Called at every restore-from-checkpoint

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

@@ -2,6 +2,6 @@ import type { BatchOperation } from '../../../storage/interface.ts';
 import type { Checkpoint, SearchAttributeValue, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
-export declare function buildStartBatchOperations(_internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, options: StartOptions | undefined, executionDeadline: number | undefined, delayedStartTimer: TimerEntry | undefined, workflowStartHeaders: Map<string, string> | undefined, additionalOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks): BatchOperation[];
+export declare function buildStartBatchOperations(_internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, options: StartOptions | undefined, executionDeadline: number | undefined, delayedStartTimer: TimerEntry | undefined, workflowStartHeaders: Map<string, string> | undefined, additionalOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, purgeDeleteOperations: BatchOperation[] | undefined): BatchOperation[];
 export declare function buildInitialSearchAttributeOperations(_internals: EngineInternals, workflowId: string, registration: RegistrationEntry, searchAttributes: StartOptions['searchAttributes'], callbacks: LifecycleCallbacks): BatchOperation[];
 export declare function validateSearchAttributes(_internals: EngineInternals, registration: RegistrationEntry, searchAttributes: Record<string, SearchAttributeValue>, _callbacks: LifecycleCallbacks): void;

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

@@ -8,8 +8,9 @@ import { validateAttributeValueSizes } from "../attributes-tags.js";
 import { encodeWorkflowStartHeaders } from "../state-utilities.js";
 import { buildWorkflowVisibilityIndexOperations } from "../workflow-indexes.js";
 import { EMPTY_STORAGE_VALUE } from "./shared.js";
-export function buildStartBatchOperations(_internals, workflowId, state, checkpoint, registration, options, executionDeadline, delayedStartTimer, workflowStartHeaders, additionalOperations, callbacks) {
+export function buildStartBatchOperations(_internals, workflowId, state, checkpoint, registration, options, executionDeadline, delayedStartTimer, workflowStartHeaders, additionalOperations, callbacks, purgeDeleteOperations) {
   const visibilityIndexOperations = buildWorkflowVisibilityIndexOperations(workflowId, null, state).batchOps, operations = [
+    ...purgeDeleteOperations ?? [],
     { type: "put", key: KEYS.workflow(workflowId), value: encode(state) },
     {
       type: "put",

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

@@ -0,0 +1,56 @@
+import type { BatchOperation, ConditionalBatchCondition } from '../../../storage/interface.ts';
+import type { Checkpoint, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
+import type { EngineInternals } from '../internals.ts';
+import type { WorkflowConcurrencyStartOperations } from '../workflow-concurrency.ts';
+import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
+/**
+ * Builds the id-dependent operations and compare-and-swap preconditions for an
+ * 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;
+    buildWorkflowConcurrencyStartOperations: (() => Promise<WorkflowConcurrencyStartOperations | undefined>) | undefined;
+    callbacks: LifecycleCallbacks;
+    /**
+     * Storage deletes for a prior terminal run being displaced by an
+     * `onTerminalConflict: 'start-new'` restart. Prepended ahead of the create puts
+     * so purge-and-recreate commit as one atomic batch (see
+     * {@link buildStartBatchOperations}). Undefined for an ordinary start.
+     */
+    purgeDeleteOperations: BatchOperation[] | undefined;
+};
+/**
+ * Assemble the start batch — folding in the id-dependent idempotency mapping and
+ * 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,69 @@
+import { requireStorageCapability, storageValuesEqual } from "../../../storage/interface.js";
+import { AtomicStateConflictError } from "../../atomic-state.js";
+import {
+  commitFencedEngineWrite,
+  commitFencedEngineWriteAllowingPreconditionFailure
+} from "../fenced-write.js";
+import { buildStartBatchOperations } from "./start-batch.js";
+
+export class StartIdempotencyRaceLostError extends Error {
+  constructor() {
+    super("start idempotency compare-and-swap lost to a concurrent caller");
+    this.name = "StartIdempotencyRaceLostError";
+  }
+}
+const WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS = 5;
+async function persistStartBatch(internals, startOperations, conditions) {
+  if (conditions.length === 0) {
+    await commitFencedEngineWrite(internals, startOperations, [], () => Error("Workflow start lost its CAS race."));
+    return !0;
+  }
+  requireStorageCapability(internals.storage, "conditionalBatch", "start preconditions");
+  return commitFencedEngineWriteAllowingPreconditionFailure(internals, startOperations, conditions.map((entry) => entry.condition));
+}
+async function hasStartPreconditionConflict(internals, conditions) {
+  for (const entry of conditions) {
+    if (entry.source !== "start-precondition")
+      continue;
+    const currentValue = await internals.storage.get(entry.condition.key);
+    if (!storageValuesEqual(currentValue, entry.condition.expectedValue))
+      return !0;
+  }
+  return !1;
+}
+function tagStartPreconditions(conditions) {
+  return (conditions ?? []).map((condition) => ({
+    source: "start-precondition",
+    condition
+  }));
+}
+function tagWorkflowConcurrencyConditions(conditions) {
+  return conditions.map((condition) => ({
+    source: "workflow-concurrency",
+    condition
+  }));
+}
+function mergeAdditionalStartOperations(additional, idempotent) {
+  if (idempotent === void 0 || idempotent.length === 0)
+    return additional;
+  return [...additional ?? [], ...idempotent];
+}
+export async function buildAndCommitStartBatch(context, buildIdempotentStartOperations) {
+  const { internals, workflowId, state, checkpoint, registration, options } = context, maxAttempts = context.buildWorkflowConcurrencyStartOperations === void 0 ? 1 : WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS;
+  let lastWorkflowConcurrencyStateKey;
+  for (let attempt = 0;attempt < maxAttempts; attempt += 1) {
+    const idempotent = buildIdempotentStartOperations?.(workflowId), workflowConcurrency = await context.buildWorkflowConcurrencyStartOperations?.();
+    lastWorkflowConcurrencyStateKey = workflowConcurrency?.stateKey ?? lastWorkflowConcurrencyStateKey;
+    const startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, context.delayedStartTimer, context.persistedWorkflowStartHeaders, mergeAdditionalStartOperations(context.additionalStartOperations, mergeAdditionalStartOperations(idempotent?.operations, workflowConcurrency?.operations)), context.callbacks, context.purgeDeleteOperations), conditions = [
+      ...tagStartPreconditions(idempotent?.conditions),
+      ...tagWorkflowConcurrencyConditions(workflowConcurrency?.conditions ?? [])
+    ];
+    if (await persistStartBatch(internals, startOperations, conditions))
+      return;
+    if (await hasStartPreconditionConflict(internals, conditions))
+      throw new StartIdempotencyRaceLostError;
+    if (workflowConcurrency === void 0)
+      throw new StartIdempotencyRaceLostError;
+  }
+  throw new AtomicStateConflictError(lastWorkflowConcurrencyStateKey ?? "workflow concurrency admission", WORKFLOW_CONCURRENCY_ADMISSION_MAX_ATTEMPTS);
+}

package/dist/core/engine/lifecycle/start-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 {};