@lostgradient/weft 0.2.0

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

@@ -0,0 +1,136 @@
+import { KEYS } from "../../../storage/interface.js";
+import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
+import { Context, setContextWorkflowInterceptor } from "../../context.js";
+import { EventLog } from "../../event-log.js";
+import { WorkflowResumedEvent } from "../../events.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 { prepareResumeState } from "./persist.js";
+import {
+  enforceHistoryPolicyBeforeReplay,
+  loadTerminalCleanupTrackedState,
+  loadWorkflowStartHeaders,
+  setWorkflowStartHeaders
+} from "./shared.js";
+function assertResumeNotTerminating(internals, workflowId) {
+  if (internals.terminalizingWorkflows.has(workflowId))
+    throw Error(`Cannot resume workflow "${workflowId}": termination is in progress`);
+}
+function commitSerializedResumeState(internals, args) {
+  const {
+    workflowId,
+    resumeCheckpoint,
+    serializedCheckpoint,
+    registeredVersionTuple,
+    restoredHead,
+    callbacks
+  } = args;
+  internals.checkpoints.set(workflowId, resumeCheckpoint);
+  rememberCommittedCheckpointBytes(internals, workflowId, serializedCheckpoint);
+  internals.workflowVersionTuples.set(workflowId, registeredVersionTuple);
+  internals.eventLogHeads.set(workflowId, restoredHead);
+  setWorkflowStartHeaders(internals, workflowId, args.workflowStartHeaders, callbacks);
+  internals.parkedInlineWorkflows.delete(workflowId);
+}
+function relaunchInlineWorkflowAfterResume(internals, latestState, args) {
+  const { workflowId, resumeCheckpoint, registration, callbacks } = args, accumulatedResults = new Map(resumeCheckpoint.accumulatedResults), workflowAbort = new AbortController;
+  resetCancelHandlers(internals, workflowId);
+  const context = new Context({
+    workflowId,
+    workflowType: latestState.type,
+    startedAt: getWorkflowExecutionStartedAt(latestState),
+    abortController: workflowAbort,
+    getNow: internals.options.getNow,
+    resolveWorkflowType: callbacks.resolveWorkflowTypeTarget,
+    executionStateOwnerId: latestState.executionStateOwnerId ?? workflowId,
+    accumulatedResults,
+    locals: resumeCheckpoint.locals,
+    searchAttributes: resumeCheckpoint.searchAttributes,
+    registerCancelHandler: createCancelHandlerRegistration(internals, workflowId),
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    sleepReferenceTime: resumeCheckpoint.createdAt,
+    ...latestState.executionDeadline !== void 0 && {
+      deadline: latestState.executionDeadline
+    }
+  });
+  setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
+  if (internals.options.development)
+    context.explain(!0);
+  const generator = registration.handler(context, latestState.input), inlineStrategy = internals.inlineStrategy;
+  inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
+  inlineStrategy.continueWorkflow(workflowId, void 0);
+}
+function relaunchWorkerWorkflowAfterResume(internals, latestState, args) {
+  const { workflowId, resumeCheckpoint, workflowStartHeaders } = args, serialized = serializeCheckpoint(resumeCheckpoint);
+  internals.strategy.startWorkflow({
+    workflowId,
+    workflowType: latestState.type,
+    input: latestState.input,
+    checkpoint: serialized,
+    nestingDepth: internals.workflowNestingDepths.get(workflowId) ?? 0,
+    executionStateOwnerId: latestState.executionStateOwnerId ?? workflowId,
+    ...latestState.executionDeadline !== void 0 && {
+      deadline: latestState.executionDeadline
+    },
+    ...workflowStartHeaders !== void 0 && workflowStartHeaders.size > 0 && {
+      headers: [...workflowStartHeaders]
+    }
+  });
+}
+async function performSerializedResume(internals, args) {
+  const { workflowId } = args;
+  assertResumeNotTerminating(internals, workflowId);
+  const latestState = await loadWorkflowState(internals, workflowId);
+  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"`);
+  commitSerializedResumeState(internals, args);
+  if (internals.inlineStrategy) {
+    relaunchInlineWorkflowAfterResume(internals, latestState, args);
+    return;
+  }
+  relaunchWorkerWorkflowAfterResume(internals, latestState, args);
+}
+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"`);
+  const checkpointBytes = await internals.storage.get(KEYS.checkpoint(workflowId));
+  if (!checkpointBytes)
+    throw Error(`Checkpoint not found for workflow "${workflowId}"`);
+  const checkpoint = deserializeCheckpoint(checkpointBytes), registration = internals.registrations.get(state.type);
+  if (!registration)
+    throw Error(`No workflow registered with name "${state.type}" (needed to resume "${workflowId}")`);
+  const preparedResumeState = await prepareResumeState(internals, workflowId, state, checkpoint, checkpointBytes, registration, callbacks), resumeCheckpoint = preparedResumeState.checkpoint, registeredVersionTuple = preparedResumeState.versionTuple, restoredHead = await new EventLog(internals.storage, workflowId).loadHead();
+  if (await enforceHistoryPolicyBeforeReplay(internals, workflowId, restoredHead, callbacks))
+    return callbacks.getHandle(workflowId);
+  const workflowStartHeaders = await loadWorkflowStartHeaders(internals, workflowId, callbacks);
+  await loadTerminalCleanupTrackedState(internals, workflowId, callbacks);
+  const handle = callbacks.getHandle(workflowId);
+  await callbacks.runSerializedWorkflowStateWrite(workflowId, () => performSerializedResume(internals, {
+    workflowId,
+    resumeCheckpoint,
+    serializedCheckpoint: preparedResumeState.serializedCheckpoint,
+    registeredVersionTuple,
+    restoredHead,
+    workflowStartHeaders,
+    registration,
+    callbacks
+  }));
+  if (dispatchResumedEvent)
+    callbacks.dispatchEvent(new WorkflowResumedEvent(workflowId, resumeCheckpoint.step));
+  if (internals.inlineStrategy)
+    callbacks.swallowPromiseRejection(callbacks.processPendingUpdatesAfterInlineAdvance(workflowId));
+  return handle;
+}

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

@@ -0,0 +1,79 @@
+import type { ComposedWorkflowInterceptor } from '../../interceptor.ts';
+import type { QueuedInlineWorkflowExecutionStart } from '../engine-internal-types.ts';
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+export type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+export declare const FORK_LINEAGE_ATTRIBUTE = "weft:forkedFrom";
+export declare const EMPTY_STORAGE_VALUE: Uint8Array<ArrayBuffer>;
+/**
+ * Options for {@link Engine.recoverAll}. The acknowledgement flag is an
+ * explicit escape hatch for deployments that intentionally skip stored
+ * workflows whose type is not registered on this engine.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type RecoverAllOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const options: RecoverAllOptions = { acknowledgeUnknownWorkflowTypes: true };
+ * await engine.recoverAll(options);
+ * ```
+ */
+export type RecoverAllOptions = {
+    /**
+     * Skip stored running workflows whose type is not registered. Use only for
+     * rolling deploys or explicit storage migrations.
+     */
+    acknowledgeUnknownWorkflowTypes?: boolean;
+};
+export type LifecycleCallbacks = {
+    dispatchEvent: (event: Event) => void;
+    getHandle: (workflowId: string) => WorkflowHandle;
+    createWorkflowHandleWithResultPromise: (workflowId: string) => WorkflowHandle;
+    runSerializedWorkflowStateWrite: (workflowId: string, fn: () => Promise<void>) => Promise<void>;
+    getComposedWorkflowInterceptor: () => ComposedWorkflowInterceptor | null;
+    resolveWorkflowTypeTarget: (target: string | Function) => string;
+    processPendingUpdatesAfterReplay: (workflowId: string) => void;
+    processPendingUpdatesAfterInlineAdvance: (workflowId: string) => Promise<void>;
+    processPendingUpdatesForHandlers: (workflowId: string) => Promise<void>;
+    queueInlineWorkflowExecutionStart: (start: QueuedInlineWorkflowExecutionStart) => void;
+    isInlineWorkflowLocallyOwned: (workflowId: string, workflowStatus: string) => boolean;
+    hasLocalCheckpointOwnership: (workflowId: string, workflowStatus: string) => boolean;
+    handleCleanupError: (source: string, error: unknown, workflowId?: string) => void;
+    swallowPromiseRejection: (promise: Promise<unknown> | undefined) => Promise<void>;
+    /**
+     * Force the workflow to a terminal `timed-out` state because its persisted
+     * event-log record count breached the history circuit-breaker threshold.
+     * Invoked by {@link enforceHistoryPolicyBeforeReplay} so an already-oversized
+     * history is terminated without being replayed.
+     */
+    enforceHistoryCircuitBreaker: (workflowId: string) => Promise<void>;
+};
+/**
+ * Pre-replay history circuit breaker. Called at every restore-from-checkpoint
+ * entry point immediately after the persisted event-log head is loaded and
+ * before replay. When `maxEvents` is configured and the workflow's durable
+ * event-log record count (`head.sequence + 1`) exceeds it, force the workflow
+ * to a terminal `timed-out` state and return `true` so the caller skips replay.
+ * Returns `false` (and does nothing) when the circuit breaker is disabled or
+ * the limit is not breached.
+ */
+export declare function enforceHistoryPolicyBeforeReplay(internals: EngineInternals, workflowId: string, head: {
+    sequence: number;
+}, callbacks: Pick<LifecycleCallbacks, 'enforceHistoryCircuitBreaker'>): Promise<boolean>;
+/**
+ * {@link enforceHistoryPolicyBeforeReplay} for callers that have not already
+ * loaded the event-log head. Resolves the head from the engine's in-memory map
+ * (present for workflows this instance already tracks, e.g. locally-owned ones)
+ * and falls back to storage. Used by `resume` on its local-ownership paths,
+ * which return before reaching `resumeWorkflowFromStorage` (where the head is
+ * otherwise loaded for the guard) — without this the circuit breaker would be
+ * skipped for a locally-owned workflow left `running` with an oversized history.
+ */
+export declare function enforceHistoryPolicyBeforeReplayById(internals: EngineInternals, workflowId: string, callbacks: Pick<LifecycleCallbacks, 'enforceHistoryCircuitBreaker'>): Promise<boolean>;
+export declare function createWorkflowHandle(_internals: EngineInternals, workflowId: string, callbacks: Pick<LifecycleCallbacks, 'createWorkflowHandleWithResultPromise'>): WorkflowHandle;
+export declare function setWorkflowStartHeaders(internals: EngineInternals, workflowId: string, headers: Map<string, string> | undefined, _callbacks: LifecycleCallbacks): void;
+export declare function loadWorkflowStartHeaders(internals: EngineInternals, workflowId: string, _callbacks: LifecycleCallbacks): Promise<Map<string, string> | undefined>;
+export declare function loadTerminalCleanupTrackedState(internals: EngineInternals, workflowId: string, _callbacks: LifecycleCallbacks): Promise<void>;
+export declare function normalizeStartWorkflowTags(_internals: EngineInternals, tags: unknown, fieldName: string | undefined, _callbacks: LifecycleCallbacks): string[] | undefined;
+export declare function processPendingUpdatesAfterReplay(_internals: EngineInternals, workflowId: string, callbacks: Pick<LifecycleCallbacks, 'handleCleanupError' | 'processPendingUpdatesForHandlers'>): Promise<void>;

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

@@ -0,0 +1,49 @@
+import { KEYS, storageHas } from "../../../storage/interface.js";
+import { EventLog } from "../../event-log.js";
+import { coerceStartWorkflowTags } from "../../start-workflow-validation.js";
+import { normalizeWorkflowTags } from "../../workflow-tags.js";
+import { loadWorkflowStartHeaders as loadWorkflowStartHeadersFromStorage } from "../storage-io.js";
+export const FORK_LINEAGE_ATTRIBUTE = "weft:forkedFrom", EMPTY_STORAGE_VALUE = new Uint8Array(0);
+export async function enforceHistoryPolicyBeforeReplay(internals, workflowId, head, callbacks) {
+  const maxEvents = internals.options.historyPolicy.maxEvents;
+  if (maxEvents === null || head.sequence + 1 <= maxEvents)
+    return !1;
+  await callbacks.enforceHistoryCircuitBreaker(workflowId);
+  return !0;
+}
+export async function enforceHistoryPolicyBeforeReplayById(internals, workflowId, callbacks) {
+  if (internals.options.historyPolicy.maxEvents === null)
+    return !1;
+  const head = internals.eventLogHeads.get(workflowId) ?? await new EventLog(internals.storage, workflowId).loadHead();
+  return enforceHistoryPolicyBeforeReplay(internals, workflowId, head, callbacks);
+}
+export function createWorkflowHandle(_internals, workflowId, callbacks) {
+  return callbacks.createWorkflowHandleWithResultPromise(workflowId);
+}
+export function setWorkflowStartHeaders(internals, workflowId, headers, _callbacks) {
+  if (!headers || headers.size === 0) {
+    internals.workflowHeaders.delete(workflowId);
+    return;
+  }
+  internals.workflowHeaders.set(workflowId, new Map(headers));
+  internals.workflowsNeedingTerminalCleanup.add(workflowId);
+}
+export async function loadWorkflowStartHeaders(internals, workflowId, _callbacks) {
+  return loadWorkflowStartHeadersFromStorage(internals, workflowId);
+}
+export async function loadTerminalCleanupTrackedState(internals, workflowId, _callbacks) {
+  if (await storageHas(internals.storage, KEYS.terminalCleanupNeeded(workflowId)))
+    internals.workflowsNeedingTerminalCleanup.add(workflowId);
+}
+export function normalizeStartWorkflowTags(_internals, tags, fieldName, _callbacks) {
+  if (tags === void 0)
+    return;
+  return normalizeWorkflowTags(coerceStartWorkflowTags(tags, fieldName ?? "options.tags"));
+}
+export async function processPendingUpdatesAfterReplay(_internals, workflowId, callbacks) {
+  try {
+    await callbacks.processPendingUpdatesForHandlers(workflowId);
+  } catch (error) {
+    callbacks.handleCleanupError("processPendingUpdates", error, workflowId);
+  }
+}

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

@@ -0,0 +1,7 @@
+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 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

@@ -0,0 +1,70 @@
+import { KEYS } from "../../../storage/interface.js";
+import { serializeCheckpoint } from "../../checkpoint.js";
+import { encode } from "../../codec.js";
+import { buildTimerBatchOperations } from "../../scheduler.js";
+import { buildIndexOperations, validateAttributeType } from "../../search-attributes.js";
+import { buildWorkflowTagIndexOperations } from "../../workflow-tags.js";
+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) {
+  const visibilityIndexOperations = buildWorkflowVisibilityIndexOperations(workflowId, null, state).batchOps, operations = [
+    { type: "put", key: KEYS.workflow(workflowId), value: encode(state) },
+    {
+      type: "put",
+      key: KEYS.checkpoint(workflowId),
+      value: serializeCheckpoint(checkpoint)
+    },
+    ...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
+      }
+    ] : [],
+    ...additionalOperations ?? []
+  ];
+  if (executionDeadline !== void 0)
+    operations.push(...buildTimerBatchOperations({
+      id: `deadline:${workflowId}`,
+      workflowId,
+      fireAt: executionDeadline,
+      kind: "execution-deadline"
+    }));
+  if (delayedStartTimer)
+    operations.push(...buildTimerBatchOperations(delayedStartTimer));
+  return operations;
+}
+export function buildInitialSearchAttributeOperations(_internals, workflowId, registration, searchAttributes, callbacks) {
+  if (!searchAttributes || Object.keys(searchAttributes).length === 0)
+    return [];
+  validateSearchAttributes(_internals, registration, searchAttributes, callbacks);
+  validateAttributeValueSizes(searchAttributes);
+  return [
+    {
+      type: "put",
+      key: KEYS.attribute(workflowId),
+      value: encode(searchAttributes)
+    },
+    ...buildIndexOperations(workflowId, {}, searchAttributes)
+  ];
+}
+export function validateSearchAttributes(_internals, registration, searchAttributes, _callbacks) {
+  if (!registration.searchAttributes)
+    return;
+  const schema = registration.searchAttributes;
+  for (const [key, value] of Object.entries(searchAttributes)) {
+    if (!(key in schema))
+      throw Error(`Unknown search attribute "${key}". Registered attributes: ${Object.keys(schema).join(", ")}`);
+    validateAttributeType(key, value, schema[key]);
+  }
+}

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

@@ -0,0 +1,5 @@
+import type { Checkpoint } from '../../types.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } 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;

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

@@ -0,0 +1,39 @@
+import { serializeCheckpoint } from "../../checkpoint.js";
+export function runWorkflowStartInterceptor(_internals, workflowId, workflowType, input, parentHeaders, callbacks) {
+  const composedInterceptor = callbacks.getComposedWorkflowInterceptor();
+  if (!composedInterceptor)
+    return;
+  const headers = new Map;
+  if (parentHeaders)
+    for (const [key, value] of parentHeaders)
+      headers.set(key, value);
+  let capturedHeaders;
+  composedInterceptor.workflowStart({
+    workflowId,
+    workflowType,
+    input,
+    headers
+  }, (interception) => {
+    capturedHeaders = new Map(interception.headers);
+  });
+  return capturedHeaders;
+}
+export function startWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, _callbacks) {
+  if (nestingDepth !== 0)
+    internals.workflowNestingDepths.set(workflowId, nestingDepth);
+  internals.workflowTypeByWorkflowId.set(workflowId, workflowType);
+  internals.strategy.startWorkflow({
+    workflowId,
+    workflowType,
+    input,
+    checkpoint: serializeCheckpoint(checkpoint),
+    nestingDepth,
+    executionStateOwnerId,
+    startedAt: checkpoint.createdAt,
+    sleepReferenceTime: checkpoint.createdAt,
+    ...executionDeadline !== void 0 && { deadline: executionDeadline },
+    ...internals.workflowHeaders.has(workflowId) && {
+      headers: [...internals.workflowHeaders.get(workflowId)]
+    }
+  });
+}

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

@@ -0,0 +1,13 @@
+import type { BatchOperation } from '../../../storage/interface.ts';
+import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../../types.ts';
+import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
+export declare function start(internals: EngineInternals, type: string, input: unknown, options: StartOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+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

@@ -0,0 +1,163 @@
+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 {
+  StartWorkflowValidationError,
+  assertExclusiveStartWorkflowOptions,
+  coerceStartWorkflowId,
+  coerceStartWorkflowTimestamp,
+  parseStartWorkflowDuration
+} from "../../start-workflow-validation.js";
+import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
+import { WorkflowAlreadyExistsError, WorkflowNotRegisteredError } from "../errors.js";
+import { createDelayedStartTimerEntry } from "../operations-time.js";
+import { selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
+import { createWorkflowVersionTuple } from "./persist.js";
+import {
+  createWorkflowHandle,
+  normalizeStartWorkflowTags,
+  setWorkflowStartHeaders
+} from "./shared.js";
+import { buildStartBatchOperations } from "./start-batch.js";
+import { runWorkflowStartInterceptor, startWorkflowExecution } from "./start-exec.js";
+export async function start(internals, type, input, options, callbacks) {
+  return startWorkflow(internals, type, input, options, void 0, callbacks);
+}
+function prepareStartWorkflow(internals, options, callbacks) {
+  const callerProvidedId = options?.id !== void 0, workflowId = options?.id !== void 0 ? coerceStartWorkflowId(options.id, "options.id") : crypto.randomUUID(), parentHeaders = internals.pendingParentHeaders;
+  internals.pendingParentHeaders = void 0;
+  const executionStateOwnerId = internals.pendingExecutionStateOwnerId ?? workflowId;
+  internals.pendingExecutionStateOwnerId = void 0;
+  const submissionTime = internals.options.getNow(), scheduledStartAt = resolveScheduledStartAt(internals, options, submissionTime, callbacks), normalizedTags = normalizeStartWorkflowTags(internals, options?.tags, void 0, callbacks), delayedStartTimer = scheduledStartAt !== void 0 && scheduledStartAt > submissionTime ? createDelayedStartTimerEntry(internals, workflowId, scheduledStartAt, options, {
+    parseStartOptionDuration: (value, fieldName) => parseStartOptionDuration(internals, value, fieldName, callbacks)
+  }) : void 0;
+  return {
+    workflowId,
+    callerProvidedId,
+    parentHeaders,
+    executionStateOwnerId,
+    submissionTime,
+    delayedStartTimer,
+    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);
+}
+export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks) {
+  const registration = internals.registrations.get(type);
+  if (!registration)
+    throw new WorkflowNotRegisteredError(type);
+  const preparation = prepareStartWorkflow(internals, options, callbacks), { workflowId, callerProvidedId, parentHeaders, executionStateOwnerId, delayedStartTimer } = preparation;
+  if (internals.pendingStarts.has(workflowId))
+    throw new WorkflowAlreadyExistsError(workflowId);
+  internals.pendingStarts.add(workflowId);
+  let startSucceeded = !1;
+  try {
+    if (callerProvidedId) {
+      if (await internals.storage.get(KEYS.workflow(workflowId)) !== null)
+        throw new WorkflowAlreadyExistsError(workflowId);
+    }
+    assertPayloadWithinLimit(input, internals.options.payloadSizePolicy.maxBytes, "workflow input");
+    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, preparation.normalizedTags, executionStateOwnerId, delayedStartTimer, callbacks), checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders);
+    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);
+    const handle = createWorkflowHandle(internals, workflowId, callbacks);
+    if (!delayedStartTimer)
+      beginWorkflowExecution(internals, workflowId, type, input, checkpoint, state.executionDeadline, state.executionStateOwnerId ?? workflowId, registration, callbacks);
+    startSucceeded = !0;
+    return handle;
+  } finally {
+    internals.pendingStarts.delete(workflowId);
+    if (!startSucceeded)
+      rollbackTransientStartState(internals, workflowId);
+  }
+}
+export function resolveScheduledStartAt(internals, options, submissionTime, callbacks) {
+  assertExclusiveStartWorkflowOptions(options?.startAt, options?.startAfter);
+  if (options?.startAt !== void 0)
+    return coerceStartWorkflowTimestamp(options.startAt, "options.startAt");
+  if (options?.startAfter !== void 0) {
+    const startAfterMilliseconds = parseStartOptionDuration(internals, options.startAfter, "options.startAfter", callbacks);
+    try {
+      return normalizeStorageTimestamp(submissionTime + startAfterMilliseconds, "options.startAfter");
+    } catch {
+      throw new StartWorkflowValidationError("options.startAfter must resolve to a finite, non-negative start time");
+    }
+  }
+  return;
+}
+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,
+    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
+    }
+  };
+}
+function resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks) {
+  if (options?.executionTimeout === void 0 || delayedStartTimer)
+    return;
+  const executionTimeoutMilliseconds = parseStartOptionDuration(internals, options.executionTimeout, "options.executionTimeout", callbacks);
+  try {
+    return normalizeStorageTimestamp(now + executionTimeoutMilliseconds, "options.executionTimeout");
+  } catch {
+    throw new StartWorkflowValidationError("options.executionTimeout must resolve to a finite, non-negative deadline");
+  }
+}
+export function createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, tags, executionStateOwnerId, delayedStartTimer, callbacks) {
+  const now = internals.options.getNow(), state = buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, delayedStartTimer, now, tags), executionDeadline = resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks);
+  if (executionDeadline !== void 0)
+    state.executionDeadline = executionDeadline;
+  return state;
+}
+export function createInitialCheckpoint(internals, workflowId, workflowVersion, options, _callbacks) {
+  const checkpoint = createCheckpoint(workflowId, workflowVersion, internals.options.getNow());
+  if (options?.searchAttributes)
+    checkpoint.searchAttributes = { ...options.searchAttributes };
+  return checkpoint;
+}

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

@@ -0,0 +1,8 @@
+import type { Checkpoint, ForkOptions, WorkflowState } from '../../types.ts';
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks, type RecoverAllOptions, type RegistrationEntry } from './shared.ts';
+export declare function recoverAll(internals: EngineInternals, callbacks: LifecycleCallbacks, options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
+export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+export declare function fork(internals: EngineInternals, sourceWorkflowId: string, options: ForkOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+export declare function launchWorkflowFromCheckpoint(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, callbacks: LifecycleCallbacks): WorkflowHandle;