@workflow/core 5.0.0-beta.4 → 5.0.0-beta.40

package/dist/private.d.ts

@@ -1,10 +1,13 @@
 /**
  * Utils used by the bundler when transforming code
  */
-import type { CryptoKey } from './encryption.js';
+import type { WorldCapabilities } from '@workflow/world';
+import type { CorrelationIdGenerator } from './correlation-id.js';
 import type { EventsConsumer } from './events-consumer.js';
 import type { QueueItem } from './global.js';
+import type { ReplayPayloadCache } from './replay-payload-cache.js';
 import type { Serializable } from './schemas.js';
+import type { PayloadKey } from './serialization/encryption.js';
 export type StepFunction<Args extends Serializable[] = any[], Result extends Serializable | unknown = unknown> = ((...args: Args) => Promise<Result>) & {
     maxRetries?: number;
     stepId?: string;
@@ -25,8 +28,19 @@ export declare function registerStepFunction(stepId: string, stepFn: StepFunctio
 export declare function getStepFunction(stepId: string): StepFunction | undefined;
 export interface WorkflowOrchestratorContext {
     runId: string;
-    encryptionKey: CryptoKey | undefined;
+    encryptionKey: PayloadKey | undefined;
+    worldCapabilities?: WorldCapabilities;
     globalThis: typeof globalThis;
+    /**
+     * Increments when a suspension is accepted and on every retained-session
+     * resume. STEP suspension signals capture it when scheduled and no-op if
+     * it moved (see step.ts) — this drops same-boundary sibling signals and
+     * timers queued at boundary N that would fire after the session resumed
+     * into boundary N+1. Sleep/hook/attribute signals are intentionally
+     * unguarded: their presence makes the boundary unretainable, so a late
+     * signal correctly demotes the session (workflow.ts `onWorkflowError`).
+     */
+    suspensionGeneration: number;
     eventsConsumer: EventsConsumer;
     /**
      * Map of pending invocations keyed by correlationId.
@@ -34,7 +48,12 @@ export interface WorkflowOrchestratorContext {
      */
     invocationsQueue: Map<string, QueueItem>;
     onWorkflowError: (error: Error) => void;
-    generateUlid: () => string;
+    /**
+     * Mints a correlation id body for one entity family. Every entity a replay
+     * creates draws from here, and the family is what keeps a disagreement about
+     * one family's count from renumbering another's.
+     */
+    generateCorrelationId: CorrelationIdGenerator;
     generateNanoid: () => string;
     /**
      * Sequential promise queue that ensures all event-driven promise resolutions
@@ -46,18 +65,168 @@ export interface WorkflowOrchestratorContext {
     promiseQueue: Promise<void>;
     /**
      * Counter of in-flight async data delivery operations (step result
-     * hydration, hook payload hydration). Suspensions must wait for this
-     * to reach 0 before firing, to avoid preempting data delivery.
+     * hydration, hook payload hydration, abort signal hydration). Suspensions
+     * must wait for this to reach 0 before firing, to avoid preempting data
+     * delivery — e.g. dehydrating a step's arguments while an abort that should
+     * be reflected in those arguments is still hydrating its reason.
      */
     pendingDeliveries: number;
+    /**
+     * Ordered registry of in-flight "branch-deciding" deliveries — the
+     * resolutions a workflow typically `Promise.race`s on, or awaits from
+     * independent concurrent branches: hook payloads (`hook_received`), wait
+     * completions (`wait_completed`), and step results (`step_completed` /
+     * `step_failed`). Keyed by the delivery's position (index) in the consumed
+     * event log.
+     *
+     * The problem: each of these resolutions reaches workflow code after a
+     * different, workload-dependent number of microtask hops. A buffered hook
+     * payload is observed via the async hook iterator (`yield await this`),
+     * costing extra hops; a `wait_completed` resolves with fewer, and a reused
+     * sleep can resolve in an entirely earlier loop iteration; a step result is
+     * gated on hydration whose cost varies between replays of the SAME
+     * invocation — the first replay pays the full decrypt/decompress/revive,
+     * while later replays sharing the invocation's `ReplayPayloadCache`
+     * memo-hit small primitive results and resolve in one or two hops. Either
+     * way, the resolution that the committed event log ordered first can lose a
+     * `Promise.race` (or a `useStep` ULID allocation) to a faster- or
+     * already-resolved competitor, diverging from the log and surfacing as
+     * `CorruptedEventLogError`.
+     *
+     * The fix is a strict, deterministic delivery order anchored on
+     * event-log position: a delivery does not resolve to the workflow until
+     * every relevant earlier-in-log delivery has been delivered. Because the
+     * gate is "the earlier delivery resolved", not "won a timing race", the
+     * outcome is independent of microtask hops, hydration/decryption time,
+     * and `Promise.race` argument order. Which earlier kinds a delivery defers
+     * behind is spelled out on {@link awaitEarlierDeliveries}.
+     *
+     * Index is used rather than the `eventId` string because `eventId` is an
+     * opaque, world-assigned value not guaranteed to sort in creation order
+     * (only the bundled ULID worlds happen to).
+     *
+     * Optional so older/out-of-tree contexts (and lightweight test harnesses)
+     * that do not initialize it degrade gracefully to the previous behavior.
+     */
+    pendingDeliveryBarriers?: Map<number, DeliveryBarrierEntry>;
+    /**
+     * Invocation-scoped cache of prepared serialized payloads and immutable final
+     * values. Prepared bytes survive fresh replay VMs; object graphs do not.
+     */
+    replayPayloadCache: ReplayPayloadCache;
+}
+/** The kind of branch-deciding delivery a barrier represents. */
+export type DeliveryKind = 'hook' | 'wait' | 'step';
+interface DeliveryBarrierEntry {
+    kind: DeliveryKind;
+    /** Resolves once this delivery has resolved to the workflow. */
+    delivered: Promise<void>;
+    /**
+     * Whether this delivery is committed to reaching the workflow without any
+     * further action by workflow code. True for wait completions and step
+     * results, which always resolve from their own chain, and for a hook payload
+     * that already had a waiting consumer when it was consumed.
+     *
+     * False for a BUFFERED hook payload no consumer has claimed yet: it is
+     * delivered by `claim()`, i.e. whenever the workflow next reads the hook —
+     * which may be causally *after* a later-in-log delivery. `arm()` flips it
+     * once a consumer takes the payload.
+     */
+    armed: boolean;
+}
+/**
+ * Awaits, in strict event-log order, every still-registered delivery that is
+ * earlier in the log than `eventIndex` and that a delivery of `kind` defers
+ * behind (see {@link DEFER_BEHIND}), so that this resolution is handed to the
+ * workflow only after all relevant earlier-in-log deliveries have been. This
+ * is what keeps a `Promise.race` — or the ULID a follow-up `useStep` draws on
+ * a concurrent branch — deterministic and aligned with the committed event
+ * log, independent of microtask-hop counts, hydration time, or race-argument
+ * order. When this delivery does have to wait, it also yields a macrotask
+ * afterwards so the earlier delivery's consumer can run to its own next
+ * suspension point first; see the comment at that `await` for why ordering the
+ * `resolve()` calls alone is not enough.
+ *
+ * One asymmetry: a STEP result additionally skips any earlier delivery that
+ * will not resolve on its own, i.e. one blocked (directly or transitively) on
+ * a buffered hook payload no consumer has claimed. Such a payload is delivered
+ * only when the workflow next reads the hook, and reaching that read very
+ * commonly requires the step result itself (`await stepX()` before the read).
+ * Gating the step on it would stall the workflow until the barrier's idle
+ * safety net fires, which then releases every delivery queued behind that
+ * payload at once — losing exactly the race this ordering exists to protect.
+ * Waits and hooks keep gating on unclaimed payloads: for them, waiting for the
+ * claim IS the ordering guarantee (a `wait_completed` must not preempt a
+ * payload the log ordered first).
+ */
+export declare function awaitEarlierDeliveries(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind): Promise<void>;
+/** Handle for a registered branch-deciding delivery barrier. */
+export interface DeliveryBarrier {
+    /**
+     * Mark this delivery as delivered to the workflow. Resolves its
+     * `delivered` promise so any later-in-log delivery gated on it (via
+     * {@link awaitEarlierDeliveries}) may proceed, and removes it from the
+     * registry. Idempotent.
+     */
+    markDelivered: () => void;
+    /**
+     * Mark this delivery as committed to happening, for a barrier registered
+     * unarmed (a buffered hook payload) once a consumer has claimed it. From
+     * then on a later step result may be ordered behind it. Idempotent.
+     */
+    arm: () => void;
 }
+/**
+ * Register a branch-deciding delivery at its event-log index so that later
+ * deliveries can be ordered strictly after it. Returns an inert handle when
+ * `pendingDeliveryBarriers` is not initialized.
+ *
+ * Pass `armed: false` for a delivery whose resolution waits on workflow code
+ * asking for it (a buffered hook payload); call `arm()` when it does.
+ *
+ * To guarantee a later delivery gated on this one can never hang when this
+ * delivery is abandoned (the workflow took a different branch or is
+ * suspending and never observes it), the barrier auto-resolves at idle.
+ *
+ * INVARIANT required of every call site: a barrier that is ever `armed` must
+ * be paired with a delivery chain that runs unconditionally — attached when
+ * the event is consumed (waits, step results, waiting-consumer hook payloads,
+ * aborts), or by the `claim()` whose invocation is what arms it (buffered
+ * hook payloads). The idle check ({@link scheduleWhenIdle}) refuses to
+ * observe idle while an armed, self-resolving barrier is undelivered, and the
+ * safety net below is itself idle-gated — so an armed barrier with no
+ * unconditional chain would livelock every idle check in the run, including
+ * its own retirement.
+ */
+export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind, options?: {
+    armed?: boolean;
+}): DeliveryBarrier;
 /**
  * Schedule a callback to fire only after all pending data deliveries
  * (step results, hook payloads) and async deserialization have completed.
- * Uses a polling loop: setTimeout(0) → check pendingDeliveries →
- * if > 0, wait for promiseQueue → repeat. This handles the multi-round
- * delivery pattern where each hook payload delivery cycle appends new
- * async work to the promiseQueue.
+ * Uses a polling loop: setTimeout(0) → check pendingDeliveries and the
+ * barrier registry → if anything is still in flight, wait for promiseQueue →
+ * repeat. This handles the multi-round delivery pattern where each hook
+ * payload delivery cycle appends new async work to the promiseQueue.
+ *
+ * "In flight" is two distinct windows, each with its own guard:
+ * `pendingDeliveries > 0` covers hydration inside the serial queue slots, and
+ * {@link hasParkedCommittedDelivery} covers the detached gap between a slot
+ * releasing that counter and the delivery's `resolve()` actually running —
+ * deliberately outside `pendingDeliveries` (see step.ts), and invisible to it.
+ *
+ * The initial `setTimeout(0)` macrotask is load-bearing and must NOT be
+ * downgraded to a microtask (`queueMicrotask`/`Promise.resolve().then`).
+ * `pendingDeliveries` only guards the host-side hydration window; between a
+ * delivery's `resolve()` and the workflow VM body running its continuation to
+ * register the next subscriber, `pendingDeliveries` is already 0 even though
+ * the VM is mid-reaction. Node does not guarantee a microtask scheduled in
+ * the host context settles after the cross-VM promise chain (resolve in host
+ * → workflow code in VM → subscribe back in host); the macrotask boundary
+ * gives that chain time to run, so the suspension does not preempt a sibling
+ * delivery still in flight. Empirically, replacing it with `queueMicrotask`
+ * breaks hook/sleep `Promise.race` ordering (CorruptedEventLogError).
  */
 export declare function scheduleWhenIdle(ctx: WorkflowOrchestratorContext, fn: () => void): void;
+export {};
 //# sourceMappingURL=private.d.ts.map

package/dist/private.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../src/private.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,YAAY,CACtB,IAAI,SAAS,YAAY,EAAE,GAAG,GAAG,EAAE,EACnC,MAAM,SAAS,YAAY,GAAG,OAAO,GAAG,OAAO,IAC7C,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAsEF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,QAGxE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAoBxE;AAOD,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,cAAc,EAAE,cAAc,CAAC;IAC/B;;;OAGG;IACH,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACxC,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,2BAA2B,EAChC,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAYN"}
+{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../src/private.ts"],"names":[],"mappings":"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"}