@lostgradient/weft 0.2.1 → 0.3.0

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

@@ -1,14 +1,17 @@
 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 {
@@ -95,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);
@@ -104,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}"`);

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

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

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

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

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

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

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

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

@@ -0,0 +1,141 @@
+import { KEYS, requireStorageCapability } from "../../../storage/interface.js";
+import { encode } from "../../codec.js";
+import {
+  assertValidIdempotencyKey,
+  StartWorkflowValidationError
+} from "../../start-workflow-validation.js";
+import { IdempotencyKeyPurgedError, WorkflowAlreadyExistsError } from "../errors.js";
+import { buildCreateBatchSignalOperations } from "../signals.js";
+import {
+  StartIdempotencyRaceLostError
+} from "./start-commit.js";
+import {
+  requireWinnerId,
+  resolveCallerIdWinnerOrRetry,
+  resolveExistingRunOrThrowPurged,
+  resolveIdempotencyKeyWorkflowId,
+  resolveWinnerWithSignal,
+  signalOrConflictExistingWorkflow
+} from "./start-or-signal-resolution.js";
+import { startWorkflow } from "./start.js";
+function resolveSignalId(signalSpec, idempotencyKey) {
+  if (idempotencyKey !== void 0)
+    return KEYS.startIdempotencySignalId(idempotencyKey);
+  if (signalSpec.signalId !== void 0)
+    return signalSpec.signalId;
+  throw new StartWorkflowValidationError("startOrSignal requires either signal.signalId or options.idempotencyKey to identify the signal to deliver. (Concurrent callers converge on one workflow and one signal only with a shared idempotencyKey, or a shared id plus signalId; a bare signalId starts a fresh run per caller.)");
+}
+function idempotentStartOperationsFor(internals, idempotencyKey, signal) {
+  return (workflowId) => {
+    const operations = [], conditions = [];
+    if (idempotencyKey !== void 0) {
+      const key = KEYS.startIdempotency(idempotencyKey);
+      operations.push({
+        type: "put",
+        key,
+        value: encode({ workflowId })
+      });
+      conditions.push({ key, expectedValue: null });
+    }
+    if (signal !== void 0) {
+      const built = buildCreateBatchSignalOperations(internals, workflowId, signal.name, signal.payload, signal.signalId);
+      operations.push(...built.operations);
+      conditions.push(built.condition);
+    }
+    return { operations, conditions };
+  };
+}
+export async function startWithIdempotency(internals, type, input, options, callbacks) {
+  requireStorageCapability(internals.storage, "conditionalBatch", "start idempotency");
+  const { idempotencyKey } = options;
+  if (idempotencyKey === void 0)
+    throw new StartWorkflowValidationError("startWithIdempotency requires options.idempotencyKey");
+  assertValidIdempotencyKey(idempotencyKey, "options.idempotencyKey");
+  assertIdAndIdempotencyKeyExclusive(options);
+  const existingId = await resolveIdempotencyKeyWorkflowId(internals, idempotencyKey);
+  if (existingId !== void 0)
+    return callbacks.getHandle(await resolveExistingRunOrThrowPurged(internals, existingId));
+  try {
+    return await startWorkflow(internals, type, input, options, void 0, callbacks, idempotentStartOperationsFor(internals, idempotencyKey, void 0));
+  } catch (error) {
+    if (!(error instanceof StartIdempotencyRaceLostError))
+      throw error;
+  }
+  return callbacks.getHandle(await resolveExistingRunOrThrowPurged(internals, await requireWinnerId(internals, idempotencyKey)));
+}
+function assertIdAndIdempotencyKeyExclusive(options) {
+  if (options.id !== void 0 && options.idempotencyKey !== void 0)
+    throw new StartWorkflowValidationError("options.id and options.idempotencyKey are mutually exclusive: idempotency assigns its own workflow id and dedups through the idempotency key. Provide one or the other.");
+}
+function validateStartOrSignalConvergence(signalSpec, options) {
+  const idempotencyKey = options?.idempotencyKey;
+  if (idempotencyKey === void 0)
+    return;
+  assertValidIdempotencyKey(idempotencyKey, "options.idempotencyKey");
+  assertIdAndIdempotencyKeyExclusive(options ?? {});
+  if (signalSpec.signalId !== void 0)
+    throw new StartWorkflowValidationError("startOrSignal does not accept both signal.signalId and options.idempotencyKey: the signal id derives from the idempotency key for convergence. Provide exactly one.");
+}
+export async function startOrSignal(internals, type, input, signalSpec, options, callbacks) {
+  requireStorageCapability(internals.storage, "conditionalBatch", "startOrSignal");
+  const idempotencyKey = options?.idempotencyKey;
+  validateStartOrSignalConvergence(signalSpec, options);
+  const signalId = resolveSignalId(signalSpec, idempotencyKey), mappedId = idempotencyKey !== void 0 ? await resolveIdempotencyKeyWorkflowId(internals, idempotencyKey) : void 0, existingId = mappedId ?? options?.id;
+  if (existingId !== void 0) {
+    const resolved = await signalOrConflictExistingWorkflow(internals, existingId, signalSpec, signalId, callbacks);
+    if (resolved !== void 0)
+      return resolved;
+    if (mappedId !== void 0)
+      throw new IdempotencyKeyPurgedError(mappedId);
+  }
+  return createWithSignalOrFallback(internals, type, input, signalSpec, signalId, options, callbacks);
+}
+const CALLER_ID_CREATE_MAX_ATTEMPTS = 5;
+async function createWithSignalOrFallback(internals, type, input, signalSpec, signalId, options, callbacks) {
+  const idempotencyKey = options?.idempotencyKey;
+  for (let attempt = 0;attempt < CALLER_ID_CREATE_MAX_ATTEMPTS; attempt += 1) {
+    const outcome = await resolveCreateRaceOutcome(internals, options, async () => {
+      return startWorkflow(internals, type, input, options, void 0, callbacks, idempotentStartOperationsFor(internals, idempotencyKey, {
+        name: signalSpec.name,
+        payload: signalSpec.payload,
+        signalId
+      }));
+    });
+    if (outcome.kind === "created")
+      return outcome.handle;
+    if (outcome.kind === "lost-keyed")
+      return resolveWinnerWithSignal(internals, outcome.id, signalSpec, signalId, callbacks, outcome.idempotencyKey);
+    const resolved = outcome.kind === "lost-caller-id" ? await resolveCallerIdWinnerOrRetry(internals, outcome.id, signalSpec, signalId, callbacks) : await plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks);
+    if (resolved !== void 0)
+      return resolved;
+  }
+  throw Error(`startOrSignal could not create workflow "${options?.id ?? "<generated>"}" after ${CALLER_ID_CREATE_MAX_ATTEMPTS} attempts: each concurrent same-id winner aborted before its durable commit.`);
+}
+async function plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks) {
+  try {
+    return await startWorkflow(internals, type, input, options, void 0, callbacks);
+  } catch (error) {
+    if (!(error instanceof WorkflowAlreadyExistsError))
+      throw error;
+    return resolveCallerIdWinnerOrRetry(internals, error.workflowId, signalSpec, signalId, callbacks);
+  }
+}
+async function resolveCreateRaceOutcome(internals, options, runCreate) {
+  try {
+    return { kind: "created", handle: await runCreate() };
+  } catch (error) {
+    if (error instanceof WorkflowAlreadyExistsError)
+      return { kind: "lost-caller-id", id: error.workflowId };
+    if (error instanceof StartIdempotencyRaceLostError) {
+      const idempotencyKey = options?.idempotencyKey;
+      if (idempotencyKey !== void 0)
+        return {
+          kind: "lost-keyed",
+          id: await requireWinnerId(internals, idempotencyKey),
+          idempotencyKey
+        };
+      return { kind: "signal-already-buffered" };
+    }
+    throw error;
+  }
+}

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

@@ -3,11 +3,11 @@ import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } fr
 import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
-import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+import { type BuildIdempotentStartOperations } from './start-commit.ts';
 export declare function start(internals: EngineInternals, type: string, input: unknown, options: StartOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
-export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;
+export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations): Promise<WorkflowHandle>;
 export declare function resolveScheduledStartAt(internals: EngineInternals, options: StartOptions | undefined, submissionTime: number, callbacks: LifecycleCallbacks): number | undefined;
 export declare function parseStartOptionDuration(_internals: EngineInternals, duration: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter', _callbacks: LifecycleCallbacks): number;
-export declare function beginWorkflowExecution(internals: EngineInternals, workflowId: string, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, _registration: RegistrationEntry, callbacks: LifecycleCallbacks): void;
 export declare function createInitialWorkflowState(internals: EngineInternals, workflowId: string, type: string, input: unknown, versionTuple: WorkflowVersionTuple, options: StartOptions | undefined, tags: string[] | undefined, executionStateOwnerId: string, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
 export declare function createInitialCheckpoint(internals: EngineInternals, workflowId: string, workflowVersion: string, options: StartOptions | undefined, _callbacks: LifecycleCallbacks): Checkpoint;