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

package/dist/events-consumer.d.ts

@@ -6,6 +6,15 @@ import { type Event } from '@workflow/world';
  * in host). Any subscribe() arriving during this window cancels the check.
  */
 export declare const DEFERRED_CHECK_DELAY_MS = 100;
+/**
+ * Floor for the deferred-check delay, so a too-low override can't manufacture
+ * spurious divergence (each false positive burns a divergence-recovery retry
+ * and can escalate to a terminal `CorruptedEventLogError`).
+ *
+ * Exported so tests needing the shortest legal delay can ask for it instead of
+ * hardcoding a number this floor would silently clamp up.
+ */
+export declare const MIN_DEFERRED_CHECK_DELAY_MS = 10;
 export declare enum EventConsumerResult {
     /**
      * Callback consumed the event, but should not be removed from the callbacks list
@@ -43,18 +52,72 @@ export interface EventsConsumerOptions {
      * deserialization delays the resolve() that triggers the next subscribe().
      */
     getPromiseQueue: () => Promise<void>;
+    /**
+     * Whether no data delivery is in flight (`isDeliveryIdle` in private.ts).
+     * The unconsumed-event check waits for this before it fires: a delivery in
+     * flight means the workflow VM is mid-reaction, and an event it has not
+     * claimed yet is an event it has not reached yet.
+     *
+     * Required rather than defaulting to always-idle: always-idle is exactly the
+     * pre-gate behaviour, so a defaulted option would let a construction site opt
+     * a whole replay path back out without saying so. Tests that drive a consumer
+     * with no orchestrator context pass `() => true` to keep the pre-existing
+     * timing, and say so at the call site.
+     */
+    isDeliveryIdle: () => boolean;
 }
 export declare class EventsConsumer {
     eventIndex: number;
     readonly events: Event[];
     readonly callbacks: EventConsumerCallback[];
+    /**
+     * Events the ordered walk stepped over because nobody claimed them and their
+     * type carries no ordering claim. Each keeps the index it held in the log:
+     * consumers read {@link eventIndex} at consumption time to order their
+     * delivery against the rest of the log, and a late delivery must still make
+     * the claim its position gave it.
+     *
+     * Held in log order, drained in log order, and drained before every offer so
+     * a consumer registered after the walk passed the event still receives it.
+     */
+    private readonly parked;
+    /**
+     * Correlation ids of the {@link ONE_SHOT_EVENT_TYPES} events consumed so
+     * far, so a second resolution for one of them is recognized as unclaimable
+     * rather than parked for a consumer that cannot exist.
+     */
+    private readonly resolved;
     private onConsumedEvent?;
     private onUnconsumedEvent;
     private getPromiseQueue;
+    private isDeliveryIdle;
     private pendingUnconsumedCheck;
     private pendingUnconsumedTimeout;
     private unconsumedCheckVersion;
     constructor(events: Event[], options: EventsConsumerOptions);
+    /**
+     * The oldest event the walk stepped over that no consumer has claimed yet,
+     * if any. Parking is a bet that a consumer will be registered later, so at
+     * any point where no consumer ever will be again — the replay finishing is
+     * the definitive one — this answers which event the bet lost on.
+     */
+    get strandedEvent(): Event | undefined;
+    /**
+     * What the walk is still holding, or `undefined` when it holds nothing.
+     *
+     * Read at every point a replay stops, including the suspensions that are not
+     * settling points, so the held state reaches telemetry. A replay cannot tell
+     * a delivery awaiting a later consumer from one no consumer will ever
+     * register, so it reports rather than decides: the same `eventId` reported on
+     * suspension after suspension of one run is the shape that says the bet
+     * parking made is not going to pay off, and that shape is only visible across
+     * replays.
+     */
+    get parkedSummary(): {
+        count: number;
+        eventId: string;
+        eventType: Event['eventType'];
+    } | undefined;
     append(events: Event[]): void;
     /**
      * Registers a callback function to be called after an event has been consumed
@@ -70,13 +133,71 @@ export declare class EventsConsumer {
     private consume;
     /**
      * Offer `currentEvent` to each registered callback in turn. Returns true
-     * when a callback consumed a real (non-null) event and the drain should
-     * advance to the next event in the same synchronous pass; false otherwise
-     * (nothing consumed it, or the consumed event was the end-of-events
-     * sentinel).
+     * when a callback consumed it. Does not move {@link eventIndex}: the ordered
+     * walk and the parked drain advance differently, so each does its own.
+     */
+    private offer;
+    /**
+     * Offer everything parked, oldest first, until a pass claims nothing.
+     *
+     * Each offer runs with {@link eventIndex} moved back to the position the
+     * parked event held in the log, because that is the position its consumer
+     * will register a delivery barrier under. Restoring the walk pointer
+     * afterwards is what keeps the two pointers from interfering.
+     */
+    private drainParked;
+    /**
+     * Step the ordered walk over an event nobody claimed, holding on to it for a
+     * later consumer. Returns false when the event's type makes its position a
+     * decision record, which is the one case where nobody claiming it means the
+     * replay diverged.
+     */
+    private park;
+    private handleEndOfLog;
+    private scheduleUnconsumedCheck;
+    /**
+     * Run `fn` once no data delivery is in flight, polling the way
+     * `scheduleWhenIdle` does: let the promise queue drain, re-check a timer
+     * tick later, repeat.
+     *
+     * Without this the check is a bet that every delivery the walk is running
+     * ahead of lands inside a fixed window. Consumption is synchronous while the
+     * resolution it triggers is not: a step result hydrates in the host, resolves
+     * from a detached continuation behind `awaitEarlierDeliveries`, and only then
+     * does VM code run far enough to subscribe the next consumer. Replaying a
+     * batch of N parallel step results leaves N-1 of them on that detached path
+     * with the queue already drained, so the walk sits on the ordered event the
+     * VM is about to draw and the window is the only thing standing between a
+     * healthy run and `ReplayDivergenceError`.
+     *
+     * Shortening the window shows that mechanism directly: on identical event logs
+     * the local race repro corrupts 34 of 42 runs at a 10ms window and 0 of 114 at
+     * the 100ms default. That measures how the bet loses, not that the default
+     * loses it, and no measurement of a delivery outrunning 100ms exists either
+     * way. So read this as retiring the bet rather than as repairing an observed
+     * failure of that number: the delay is a user-settable env override, which
+     * leaves the old behaviour one configuration away from losing on any backend.
+     *
+     * Termination is `hasParkedCommittedDelivery`'s: it counts only deliveries
+     * that resolve on their own, so nothing here can gate its own retirement. A
+     * genuinely orphaned event has no delivery to wait on and reaches `fn` on the
+     * first poll.
+     *
+     * What the gate gives up: for the ordered events that still reach
+     * `onUnconsumedEvent` rather than {@link park}, this stops being the thing
+     * that catches a diverged log while a delivery is in flight. The suspension
+     * and this check now wake from the same `isDeliveryIdle` edge, and
+     * `scheduleWhenIdle` fires on the first timer tick after idle while this waits
+     * a further `getDeferredCheckDelayMs()`. So a run with a pending `sleep()`
+     * suspends first, and `onWorkflowError` drops the divergence arriving second
+     * (its `'suspended'` branch demotes to `'replay'` and surfaces nothing),
+     * leaving a later `resume()` to decline into a cold replay. Pre-gate the
+     * suspension already won that race whenever the delivery landed inside the
+     * fixed window, so what changed is that the outcome stopped depending on
+     * timing. Nothing should treat this check as the mechanism that reports
+     * divergence on a log the run is still delivering into.
      */
-    private consumeOne;
-    private handleUnconsumed;
+    private whenDeliveryIdle;
 }
 export {};
 //# sourceMappingURL=events-consumer.d.ts.map

package/dist/events-consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events-consumer.d.ts","sourceRoot":"","sources":["../src/events-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,iBAAiB,CAAC;AAGxD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAmB3C,oBAAY,mBAAmB;IAC7B;;OAEG;IACH,QAAQ,IAAA;IACR;;OAEG;IACH,WAAW,IAAA;IACX;;OAEG;IACH,QAAQ,IAAA;CACT;AAED,KAAK,qBAAqB,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,mBAAmB,CAAC;AAE1E,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzC;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,qBAAa,cAAc;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,qBAAqB,EAAE,CAAM;IACjD,OAAO,CAAC,eAAe,CAAC,CAAyB;IACjD,OAAO,CAAC,iBAAiB,CAAyB;IAClD,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,sBAAsB,CAA8B;IAC5D,OAAO,CAAC,wBAAwB,CAA8C;IAC9E,OAAO,CAAC,sBAAsB,CAAK;gBAEvB,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,qBAAqB;IAW3D,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAK7B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,qBAAqB;IAgBnC,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,OAAO,CA0Bb;IAEF;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAgClB,OAAO,CAAC,gBAAgB;CAqCzB"}
+{"version":3,"file":"events-consumer.d.ts","sourceRoot":"","sources":["../src/events-consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,iBAAiB,CAAC;AAGxD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAgG9C,oBAAY,mBAAmB;IAC7B;;OAEG;IACH,QAAQ,IAAA;IACR;;OAEG;IACH,WAAW,IAAA;IACX;;OAEG;IACH,QAAQ,IAAA;CACT;AAED,KAAK,qBAAqB,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,mBAAmB,CAAC;AAE1E,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzC;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC1C;;;;;OAKG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC;CAC/B;AAED,qBAAa,cAAc;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,qBAAqB,EAAE,CAAM;IACjD;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,eAAe,CAAC,CAAyB;IACjD,OAAO,CAAC,iBAAiB,CAAyB;IAClD,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,sBAAsB,CAA8B;IAC5D,OAAO,CAAC,wBAAwB,CAA8C;IAC9E,OAAO,CAAC,sBAAsB,CAAK;gBAEvB,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,qBAAqB;IAY3D;;;;;OAKG;IACH,IAAI,aAAa,IAAI,KAAK,GAAG,SAAS,CAErC;IAED;;;;;;;;;;OAUG;IACH,IAAI,aAAa,IACb;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;KAAE,GACjE,SAAS,CAUZ;IAED,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAK7B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,qBAAqB;IAgBnC,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,OAAO,CA4Cb;IAEF;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAmCb;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAyBnB;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAqBZ,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,uBAAuB;IAqD/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,OAAO,CAAC,gBAAgB;CA2BzB"}