@workflow/core 5.0.0-beta.42 → 5.0.0-beta.44

package/dist/private.d.ts

@@ -33,7 +33,7 @@ export interface WorkflowOrchestratorContext {
     /**
      * 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
+     * it moved (see step.ts), which 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
@@ -53,6 +53,14 @@ export interface WorkflowOrchestratorContext {
      * whole run and both replays of a run must draw in the same order.
      */
     generateUlid: () => string;
+    /**
+     * Monotone count of correlation-id draws this replay has made. Progress
+     * metric for {@link quiesceEarlierCascades}: a macrotask turn in which it
+     * does not move (and no hydration is in flight) means every woken branch has
+     * run as far as it can without another delivery. Optional so lightweight
+     * test contexts degrade to the single-yield behavior.
+     */
+    readonly mintCount?: number;
     generateNanoid: () => string;
     /**
      * Sequential promise queue that ensures all event-driven promise resolutions
@@ -66,12 +74,12 @@ export interface WorkflowOrchestratorContext {
      * Counter of in-flight async data delivery operations (step result
      * 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
+     * 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
+     * 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` /
@@ -84,7 +92,7 @@ export interface WorkflowOrchestratorContext {
      * 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,
+     * 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
@@ -127,64 +135,19 @@ interface DeliveryBarrierEntry {
      * 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 —
+     * 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;
+    /**
+     * Retire this entry: resolve `delivered` and remove it from the registry,
+     * exactly as `markDelivered` would. Called only by the context's safety-net
+     * dispenser ({@link ensureBarrierSafetyNet}), and only on the lowest-index
+     * entry at delivery idle. Idempotent.
+     */
+    retire: () => void;
 }
-/**
- * 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.
- *
- * What counts as "defers behind" is {@link gatesOn}, shared with
- * {@link computeResolvesOnItsOwn} so the two cannot drift.
- *
- * One asymmetry: a STEP result skips any earlier delivery that is UNARMED,
- * i.e. 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).
- *
- * The skip is direct, never transitive. A step still gates on an earlier ARMED
- * wait or hook, including one that is itself parked behind an unclaimed
- * payload. Skipping those too would invert log order for the commonest shape
- * there is: a workflow that creates a hook it does not read on this branch,
- * races `step` against `sleep`, and has the log say the sleep won. The step
- * would then overtake the wait, both branches would swap the correlation ids
- * they draw next, and replay would diverge — see
- * `step-delivery-ordering.test.ts`. Waiting instead is safe because the
- * payload's own idle safety net retires it and the whole chain then delivers
- * in log order; {@link hasParkedCommittedDelivery} deliberately reports such a
- * step as not self-resolving so that idle stays reachable.
- *
- * "The whole chain then delivers in log order" rests on the PAYLOAD's safety
- * net observing idle before the net of the wait parked behind it. If the
- * wait's net fired first, the step's gate would open while the wait was still
- * parked on the payload barrier and the inversion above would reappear. Within
- * one drain window that order is structural, and carried by FIFO of the
- * safety-net polls: nets arm via `setTimeout` in log order during synchronous
- * consumption, each polling round re-arms through `promiseQueue.then(...)` in
- * the order the checks ran, and each net that fires flips
- * {@link hasParkedCommittedDelivery} back to true, re-blocking the rest until
- * the released delivery completes. Replay — where divergence manifests —
- * always consumes the log in one window. Do not "optimize" the net scheduling
- * in a way that breaks that per-window FIFO.
- */
 export declare function awaitEarlierDeliveries(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind): Promise<void>;
 /** Handle for a registered branch-deciding delivery barrier. */
 export interface DeliveryBarrier {
@@ -215,12 +178,12 @@ export interface DeliveryBarrier {
  * 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
+ * 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
+ * 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.
  */
@@ -230,19 +193,19 @@ export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext
 /**
  * Whether some registered branch-deciding delivery is going to reach the
  * workflow without any further help (it is armed and not transitively parked
- * behind an unclaimed buffered payload — see {@link resolvesOnItsOwn}) but
+ * behind an unclaimed buffered payload, see {@link resolvesOnItsOwn}) but
  * has not been handed over yet.
  *
  * This is the delivery state `pendingDeliveries` cannot see. That counter
  * covers the hydration window inside a serial `promiseQueue` slot and is
  * released there, while the delivery's `resolve()` runs later, from a
- * detached continuation behind {@link awaitEarlierDeliveries} — including its
+ * detached continuation behind {@link awaitEarlierDeliveries}, including its
  * macrotask yield whenever the delivery had to defer. Replaying a batch of N
  * parallel step results consumed in one drain window leaves N-1 of them
  * parked on that yield with `pendingDeliveries` already at 0. An idle check
  * armed during the same window (a pending `sleep()` arms one on every replay)
  * could then observe "idle" mid-deferral and raise a `WorkflowSuspension`
- * BEFORE the workflow's own continuations ran — a suspension carrying none of
+ * BEFORE the workflow's own continuations ran: a suspension carrying none of
  * the follow-up work the batch was about to create, which the runtime
  * dutifully schedules as nothing, leaving the run dormant until an unrelated
  * timer fires (vercel/workflow#3183).
@@ -251,7 +214,7 @@ export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext
  * accuracy but for termination: an unclaimed buffered hook payload is retired
  * BY the idle safety net in {@link registerDeliveryBarrier}, so counting it
  * here would gate its own retirement. That reasoning extends to whatever is
- * parked behind such a payload — a wait, and a step gating on that wait — for
+ * parked behind such a payload (a wait, and a step gating on that wait) for
  * the same reason: the whole chain moves only once the net fires, and it
  * cannot fire while the chain is counted. Self-resolving deliveries always
  * deliver from their own chains (see the INVARIANT on
@@ -265,7 +228,7 @@ export declare function hasParkedCommittedDelivery(ctx: WorkflowOrchestratorCont
  * "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 —
+ * releasing that counter and the delivery's `resolve()` actually running,
  * deliberately outside `pendingDeliveries` (see step.ts), and invisible to it.
  *
  * Anything that decides a replay is over, or that a replay went wrong, has to
@@ -273,6 +236,18 @@ export declare function hasParkedCommittedDelivery(ctx: WorkflowOrchestratorCont
  * what it has and has not done yet says nothing about the run. Two callers
  * read it, for the two such decisions: {@link scheduleWhenIdle} for the
  * suspension, and the events consumer's unconsumed-event check for divergence.
+ *
+ * A non-empty barrier registry counts as in flight, even when every remaining
+ * entry is parked behind an unclaimed buffered payload. Those entries only
+ * move when the safety-net dispenser retires them (lowest-first, see
+ * {@link ensureBarrierSafetyNet}), and the deliveries they release are real
+ * workflow reactions: a suspension raised before they run would be computed
+ * from a VM that has not seen them, scheduling none of their follow-up work
+ * and leaving the run dormant (the vercel/workflow#3183 shape). The dispenser
+ * itself is gated on {@link canRetireAbandonedBarriers}, the weaker predicate
+ * without the registry term, precisely so it can do the draining that this
+ * predicate waits for; registry size strictly decreases at each retirement,
+ * so idle is always reached.
  */
 export declare function isDeliveryIdle(ctx: WorkflowOrchestratorContext): boolean;
 /**

package/dist/private.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../src/private.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../src/private.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,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,UAAU,GAAG,SAAS,CAAC;IACtC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B;;;;;;;;OAQG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,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;;;;OAIG;IACH,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC5D;;;OAGG;IACH,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpD,UAAU,oBAAoB;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;;;;;;;OAUG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAgTD,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,2BAA2B,EAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,2BAA2B,EAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,eAAe,CA4CjB;AAmHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,2BAA2B,GAC/B,OAAO,CAaT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,2BAA2B,GAAG,OAAO,CAKxE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,2BAA2B,EAChC,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAcN"}