@workflow/core 5.0.0-beta.5 → 5.0.0-beta.51

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
@@ -22,6 +31,12 @@ export declare enum EventConsumerResult {
 }
 type EventConsumerCallback = (event: Event | null) => EventConsumerResult;
 export interface EventsConsumerOptions {
+    /**
+     * Callback invoked after an event has been consumed. Consumers such as the
+     * deterministic workflow clock must not observe events that are merely
+     * inspected while waiting for user code to subscribe to the next operation.
+     */
+    onConsumedEvent?: (event: Event) => void;
     /**
      * Callback invoked when a non-null event cannot be consumed by any registered
      * callback, indicating an orphaned or invalid event in the event log. The
@@ -30,6 +45,16 @@ export interface EventsConsumerOptions {
      * downstream subscribe() calls have a chance to cancel the check first.
      */
     onUnconsumedEvent: (event: Event) => void;
+    /**
+     * Callback invoked when an event is skipped because it repeats an event
+     * class the walk already consumed for the same entity. `firstEventType` is
+     * the type that recorded the class, which is the one the workflow observed.
+     * Diagnostics only: skipping is a normal outcome, not an error, though a
+     * `firstEventType` differing from `event.eventType` says the two writers
+     * decided the entity's outcome differently, which is worth more than an
+     * info log.
+     */
+    onDuplicateEvent?: (event: Event, firstEventType: Event['eventType']) => void;
     /**
      * Returns the current promise queue. The unconsumed event check is chained
      * onto this queue so it only fires after all pending async work (e.g.,
@@ -37,17 +62,108 @@ 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 behavior, 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;
+}
+/** See {@link EventsConsumer.describe}. */
+export interface EventsConsumerSnapshot {
+    index: number;
+    length: number;
+    parked: number;
+    lastConsumedEventId: string | undefined;
 }
 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;
+    /**
+     * `<class>:<correlationId>` for every event class the walk has already
+     * consumed, mapped to the event type that recorded it. The type is kept so a
+     * repeat that decided the same class *differently* (a `step_failed` behind a
+     * `step_completed`) can be reported as more than a re-commit. See
+     * {@link EventsConsumer.firstEventTypeOfClass}.
+     */
+    private readonly seenEventClasses;
+    private onConsumedEvent?;
     private onUnconsumedEvent;
+    private onDuplicateEvent?;
     private getPromiseQueue;
+    private isDeliveryIdle;
     private pendingUnconsumedCheck;
     private pendingUnconsumedTimeout;
     private unconsumedCheckVersion;
+    /**
+     * The event a callback most recently claimed, for {@link describe}. Tracked
+     * separately from {@link eventIndex} because the walk also steps over events
+     * (parked, sealed no-ops, duplicates) without anyone consuming them, so
+     * `events[eventIndex - 1]` does not say what replay last acted on.
+     */
+    private lastConsumed;
     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;
+    /**
+     * Where the walk stands, for a divergence message. Everything here is
+     * already known to the consumer; the point of the method is that the
+     * orchestrator can print it without reaching into private state.
+     *
+     * `index` is the ordered walk's position (the offset of the event it is
+     * stuck on, when it is stuck), `length` the log as this consumer holds it,
+     * `parked` how many events the walk stepped over and still holds, and
+     * `lastConsumedEventId` the id of the event a callback most recently
+     * claimed, `undefined` before the first claim.
+     */
+    describe(): EventsConsumerSnapshot;
+    append(events: Event[]): void;
     /**
      * Registers a callback function to be called after an event has been consumed
      * by a different callback. The callback can return:
@@ -58,7 +174,188 @@ export declare class EventsConsumer {
      * @param fn - The callback function to register.
      */
     subscribe(fn: EventConsumerCallback): void;
+    private notifyConsumedEvent;
     private consume;
+    /**
+     * Offer `currentEvent` to each registered callback in turn. Returns true
+     * 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;
+    /**
+     * Release anything parked whose class a consumption has since recorded for
+     * the same entity, on the same terms as {@link skipDuplicateEvent}.
+     *
+     * The ordered walk decides a straggler at the event, but only for one of the
+     * two orders the copies can arrive in. When neither copy has a consumer yet,
+     * both park — the walk steps over the first and re-enters immediately, so
+     * the second is offered in the same tick, with no class recorded because
+     * nothing has been *consumed*. The drain then claims the first and the
+     * second is left held by a consumer list that will never grow the callback
+     * it needs, which the workflow function returning reports through
+     * {@link strandedEvent} as a replay divergence.
+     *
+     * Run before each offer pass rather than once, because the consumption that
+     * records the class happens inside the drain itself.
+     *
+     * Not specific to `attr_set`: `wait_completed` reaches the same state, and
+     * {@link ONE_SHOT_EVENT_TYPES} only covers it in the order where the
+     * consumption came first.
+     */
+    private dropParkedDuplicates;
+    /**
+     * 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;
+    /**
+     * The key `event`'s class is tracked under, or `undefined` for the events
+     * that belong to no class and are therefore never skipped: the types with no
+     * entry at all (`hook_received`, `hook_conflict`, `run_created`), and a
+     * classed type carrying no entity to track it under.
+     *
+     * {@link classifyEntityEvent} owns that rule, because the observability UI
+     * decides the same question about the same log and the two must not drift.
+     */
+    private eventClassKey;
+    /**
+     * Remembers that `event`'s class is now decided for its entity, if the type
+     * belongs to a class. First writer wins: the recorded type is the one the
+     * workflow observed, and a later repeat is measured against it.
+     */
+    private recordEventClass;
+    /**
+     * The type that already decided `event`'s class for the same entity, or
+     * `undefined` when nothing has: a second `step_created` for one step, a
+     * second terminal outcome, a second `step_started` after the step's result is
+     * already in the log.
+     *
+     * Such an event is committed but inert. Concurrent replays write into one
+     * log without a currency guard, so a replay working from a prefix that
+     * predates another replay's write can commit its own copy of work the log
+     * already records. That copy cannot change what the workflow observed: the
+     * outcome was decided by the first event of the class and every later replay
+     * reads that same event at the same log position, so ignoring the straggler
+     * is deterministic across replays.
+     *
+     * Classes are tracked separately, so passing one does not suppress another.
+     * A step whose result is in the log still reaches its `step_created` and
+     * `step_started` consumers if it has yet to see those classes.
+     *
+     * Consulted only after every registered callback has declined the event, so
+     * it can never take an event a consumer wanted. A retry's `step_started` is
+     * claimed by the step's live consumer and counts as an attempt exactly as
+     * before, and a second `step_created` reaching a step that has not finished
+     * is likewise consumed rather than skipped; only the copies nobody claims are
+     * skipped.
+     *
+     * Unlike the divergence report, this does *not* wait out the deferred window
+     * first, and it does not need to. The window buys time for a consumer that
+     * has yet to register, and no such consumer can want this event: the class
+     * was recorded by a consumption in this same replay, which means the entity's
+     * consumer was registered and took an event of this class, and correlation
+     * ids are minted from a monotonic ULID per body position, so nothing later in
+     * the body registers a second consumer under this id. Waiting would cost
+     * `getDeferredCheckDelayMs()` per straggler per replay for information that
+     * cannot arrive: 0.75% of production runs carry at least one straggler, and
+     * the p99 among those carries 155.
+     *
+     * The invariant to preserve if hook identity ever becomes caller-supplied
+     * (an idempotency key rather than a minted id): two `createHook` calls in one
+     * body could then share a correlation id, and the second consumer's
+     * `hook_created` would be a repeat of a class this replay already recorded.
+     * That would make skipping wrong for `hook_created`, and is the reason the
+     * class map lives next to the event types rather than being inferred.
+     */
+    private firstEventTypeOfClass;
+    /**
+     * Steps the walk over a sealed-log `noop` (specVersion >= 7): the World's
+     * backend wrote it to occupy a slot whose writer allocated the position and
+     * died, so the log's density arithmetic holds. It is invisible to the
+     * workflow: no consumer is offered it, no event class is recorded, and the
+     * deterministic clock does not advance, exactly as with
+     * {@link skipDuplicateEvent}, so a log that happens to contain one produces the same
+     * timestamps as a log that does not. (Its `createdAt` is the seal time,
+     * which can even postdate later slots' events; letting it touch the clock
+     * would leak the sealer's wall clock into replay.)
+     */
+    private skipSealedNoop;
+    /** Steps the walk over a repeat of an already-consumed class. */
+    private skipDuplicateEvent;
+    private handleEndOfLog;
+    private scheduleUnconsumedCheck;
+    /**
+     * Decide what a still-unconsumed event is, now that the promise queue has
+     * drained and the delivery gate says the VM is not mid-reaction.
+     *
+     * `mayPark` is false only for the end-of-log recheck of an event {@link park}
+     * already holds. Nothing in the first branch applies to one of those: it is
+     * not the event at the cursor, so the identity guard is not meaningful, and
+     * it is parked already.
+     *
+     * A duplicate class never arrives here. {@link consume} steps over one in the
+     * pass that offered it, before this check is ever scheduled, and a class
+     * recorded while the check was in flight can only have been recorded by a
+     * consumption inside {@link consume}, whose next pass re-offers this event
+     * and steps over it there, leaving the identity guard above to drop the
+     * in-flight check. One that parks before any consumption records its class
+     * is released later by {@link dropParkedDuplicates} instead.
+     */
+    private resolveUnconsumedEvent;
+    /**
+     * 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 behavior 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 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,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAG7C;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,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;;;;;;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,CAAM;IAC9B,QAAQ,CAAC,SAAS,EAAE,qBAAqB,EAAE,CAAM;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;IAO3D;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,EAAE,qBAAqB;IAgBnC,OAAO,CAAC,OAAO,CA+Db;CACH"}
+{"version":3,"file":"events-consumer.d.ts","sourceRoot":"","sources":["../src/events-consumer.ts"],"names":[],"mappings":"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"}