@yoltra/core 0.5.0 → 0.6.0

package/dist/types/store/Store.d.ts

@@ -1,4 +1,6 @@
-import { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, EventMeta, MiddlewareInput, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EmitOptions, InstrumentationObserver, EventPhase, NarrowedEventHandler, When } from '../types.js';
+import { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, EventMeta, MiddlewareInput, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EmitOptions, EmitResult, ConnectOptions, InstrumentationObserver, CascadeInfo, EventPhase, NarrowedEventHandler, When } from '../types.js';
+import { CallHandle, CallOptions } from './call.js';
+import { Rejection } from './rejection.js';
 export declare class Store<EM extends EventMapBase, R extends string, S extends Record<R, any>> implements StoreInstance<R, S, EM> {
     /**
      * Store name (used by DevTools & diagnostics).
@@ -80,6 +82,18 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @internal
      */
+    /**
+     * Subscribers to events that actually changed state, notified after the commit.
+     *
+     * @remarks
+     * Separate from `committedEventSubscribers` rather than a filter over it, because the two
+     * answer different questions and one of them is load bearing: `committed` means "not vetoed"
+     * and fires for every event a store accepts, including every event in a store with no
+     * reducers. Narrowing it would have silently stopped toasts and analytics firing.
+     *
+     * @internal
+     */
+    private readonly writtenEventSubscribers;
     private readonly allEventSubscribers;
     /**
      * Track reducerBus unsubs per slice for HMR/register/unregister.
@@ -142,6 +156,36 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private isReducing;
+    /**
+     * The event currently being reduced, or `null` outside the drain.
+     *
+     * @remarks
+     * This is what makes causality exact rather than best-effort. The drain is synchronous — no
+     * `await` can interleave — so any `emit` that arrives while it is set is, without ambiguity, a
+     * consequence of this event. That catches the case a scoped `emit` closure cannot: a
+     * middleware or subscriber that captured the store and calls `store.emit` directly instead of
+     * using the injected one. Attribution should not depend on which reference a consumer reached
+     * for.
+     *
+     * @internal
+     */
+    private currentEvent;
+    /**
+     * Events processed by the drain currently in progress. Compared against
+     * `maxTransitionsPerDrain`, which is off unless configured.
+     *
+     * @internal
+     */
+    private transitionsThisDrain;
+    /**
+     * Ceilings that stop a cascade from becoming a hung process. See {@link StoreSpec.maxReduceDepth}.
+     *
+     * @internal
+     */
+    private readonly maxReduceDepth;
+    private readonly maxTransitionsPerDrain;
+    private readonly onCascade?;
+    private readonly onRejected?;
     /**
      * Registered instrumentation observers (DevTools seam). See {@link instrument}.
      *
@@ -151,11 +195,24 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     /**
      * Scratch array collecting slice-prefixed changed leaf paths during an
      * instrumented reduce. Set by {@link drainReduce} while observers are active;
-     * appended to by {@link forwardEvent}. `null` when not instrumenting.
+     * appended to by {@link commitStaged}. `null` when not instrumenting.
      *
      * @internal
      */
     private changedPathSink;
+    /**
+     * Where keyed reducers put their pending writes during a reduce, and the refusal one of them
+     * returned.
+     *
+     * @remarks
+     * Keyed reducers are invoked through `reducerBus`, which delivers to handlers and has no way
+     * to hand a value back — the same reason `changedPathSink` exists. `null` outside a reduce.
+     *
+     * @internal
+     */
+    private stagingSink;
+    private stagedRejection;
+    private stagedRejectedBy;
     /**
      * Count of effect tasks currently in flight; surfaced as queue depth by
      * {@link __devtoolsIntrospect}.
@@ -268,6 +325,18 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private pruneProcessedEvents;
+    /**
+     * Reports a breached ceiling and refuses the emit.
+     *
+     * @remarks
+     * Console *and* hook, matching how reducer and effect errors are reported: a cascade is a
+     * wiring bug, and the console line is what a developer who has not registered a hook will
+     * actually see. Without one, refusing the emit would look exactly like the event never having
+     * been emitted at all — which is the invisibility this whole guard exists to end.
+     *
+     * @internal
+     */
+    private reportCascade;
     /**
      * Checks if an event matches a `When` matcher.
      *
@@ -313,6 +382,17 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private notifyEffects;
+    /**
+     * An `emit` that attributes whatever it sends to `cause`.
+     *
+     * @remarks
+     * Built per event rather than per effect: every effect reacting to one event shares a cause,
+     * and one closure is cheaper than one per handler on a path that runs for every committed
+     * event.
+     *
+     * @internal
+     */
+    private scopedEmit;
     /**
      * Notifies event subscribers for a specific phase.
      *
@@ -367,17 +447,60 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * pattern reducer's throw aborted the commit and notified nobody, not even the uncommitted
      * subscribers a veto would have reached.
      *
-     * The semantics are now the same either way: **the failing slice is isolated.** Its state is
+     * The semantics are the same either way: **the failing slice is isolated.** Its state is
      * unchanged, every other slice still reduces, and the event still commits if anything else
-     * changed. Rolling the whole event back would be tidier in principle, but fine-grained
-     * subscribers are notified inside `forwardEvent` as each slice commits, so an event that
-     * reverted afterwards would have already told components about a value that no longer exists.
-     * Isolation keeps every notification truthful.
+     * changed.
+     *
+     * That is deliberately *not* what a {@link Rejected} refusal does, which discards the whole
+     * event. A crash and a refusal are different acts: a reducer that throws has a bug and should
+     * not be able to veto its neighbours' work, while a reducer that refuses has made a decision
+     * and must be able to.
+     *
+     * This once argued that rolling back was untenable, because subscribers were notified as each
+     * slice committed and a later revert would have told them about a value that no longer
+     * existed. Staging removed that obstacle — nothing is notified until every slice is written —
+     * which is what made refusal possible at all.
      *
      * @internal
      */
-    private forwardEventGuarded;
-    private forwardEvent;
+    private stageSliceGuarded;
+    /**
+     * Runs one slice's reducer and records what it *would* write. Writes nothing.
+     *
+     * @returns The reducer's {@link Rejection} if it refused, otherwise `null`.
+     *
+     * @remarks
+     * The staging half of the write path. Nothing here touches `this.state` or notifies anybody,
+     * which is what lets the event be refused after every reducer has had its say — a decision
+     * that has to see the whole diff cannot be made one slice at a time.
+     *
+     * Freezing happens here rather than at commit because it is where the new value is built, and
+     * the freeze is a no-op on anything already frozen; a staged slice that never commits is
+     * discarded frozen, which costs nothing and keeps the committed path free of a second walk.
+     *
+     * @internal
+     */
+    private stageSlice;
+    /**
+     * Writes every staged slice, then tells the world — in that order.
+     *
+     * @remarks
+     * The commit half. Assigning all slices under a single new root before any notification goes
+     * out is what closes the window this used to leave open: notifications fired per slice as each
+     * committed, so a subscriber to slice A that read `getState()` could observe slice B of the
+     * *same event* not yet applied. In React that window is real, because the atomic hooks use a
+     * change as a bare signal and then re-read the whole store.
+     *
+     * It is also what makes refusal possible at all. The previous code documented rollback as
+     * untenable precisely because "an event that reverted afterwards would have already told
+     * components about a value that no longer exists" — true when notification and commit were the
+     * same step, and no longer true now that they are not.
+     *
+     * @returns `true` if anything was written.
+     *
+     * @internal
+     */
+    private commitStaged;
     /**
      * Returns a structured introspection snapshot for DevTools UIs.
      *
@@ -422,7 +545,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * fine-grained path changes for each slice.
      *
      * **State Immutability**: If any slices change, a new state object is created via
-     * shallow spread. This ensures consistent immutability with {@link forwardEvent}.
+     * shallow spread. This ensures consistent immutability with {@link commitStaged}.
      *
      * **Missing slices**: the snapshot should contain every slice. A slice absent
      * from `nextPlain` is **retained at its current value** (not blanked to
@@ -461,13 +584,13 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * phase* (step 5) runs afterwards, asynchronously.
      * 1. **Deduplication** (opt-in) - Skip when content-dedup is enabled (`dedupWindowMs > 0`) or a matching `dedupKey` recurs; off by default
      * 2. **Middleware** (sync) - Pre-reducer hooks; may cancel by returning `false`
-     * 3. **Reducers** (sync) - state updates + fine-grained path notifications
-     * 4. **Subscribers + coarse** (sync) - event subscribers (fire-and-forget) then coarse listeners (only if state changed)
+     * 3. **Reducers** (sync) - every matching slice is *staged*; nothing is written yet, so a refusal from the last reducer still stops the first one's write
+     * 4. **Commit + subscribers** (sync) - all staged slices are assigned under one new root, then event subscribers (`committed`, then `written` when state actually changed), then coarse listeners
      * 5. **Effects** (async) - side-effects keyed by `(channel, type)`; the returned promise resolves once they complete
      *
      * **Change Detection**: Uses reference equality (`===`) on `this.state` to determine
-     * if any slice changed. Works because {@link forwardEvent} creates a new state reference
-     * via shallow spread when any slice changes.
+     * if any slice changed. Works because the commit builds a new state reference via
+     * shallow spread when any slice changes.
      *
      * @typeParam C - Channel key in `EM`.
      * @typeParam T - Type key within channel `C`.
@@ -495,7 +618,20 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    emit<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T], opts?: EmitOptions): Promise<void>;
+    emit<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T], opts?: EmitOptions): Promise<EmitResult>;
+    /**
+     * The real emit, with an explicitly supplied cause.
+     *
+     * @remarks
+     * Exists so the parent can be passed without a pseudo-private field on the public
+     * {@link EmitOptions}. Two callers supply one: the public {@link emit} passes `null` and lets
+     * `currentEvent` speak for the synchronous case, and the scoped `emit` handed to effects passes
+     * the event that triggered them — effects resume after the drain has ended, so nothing else
+     * could still know what caused them.
+     *
+     * @internal
+     */
+    private emitCaused;
     /**
      * Drains the reduce queue **synchronously**. For each event it runs middleware,
      * reducers, event subscribers, and coarse listeners in the same tick, so
@@ -536,7 +672,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     /**
      * Builds an {@link InstrumentedEvent} from the reduce result and notifies
      * observers. `changedPaths` are the exact slice-prefixed leaf paths recorded
-     * by {@link forwardEvent} during this reduce, so DevTools patches need no
+     * by {@link commitStaged} during this reduce, so DevTools patches need no
      * re-diff.
      *
      * @internal
@@ -573,7 +709,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     connect(spec: {
         reducer: R;
         property: string;
-    }, h: (chg: Change) => void): () => void;
+    }, h: (chg: Change) => void, options?: ConnectOptions): () => void;
     /**
      * Subscribe to events by channel and type.
      *
@@ -743,6 +879,92 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
+    /**
+     * Sends a request and waits for the reply, correlating the two automatically.
+     *
+     * @typeParam C  - Request channel.
+     * @typeParam T  - Request type within `C`.
+     * @param channel - Channel to send on.
+     * @param type - Event type to send.
+     * @param payload - The **request** payload. This is what you are sending; what comes back is
+     * described by {@link CallOptions.reply}, not by this.
+     * @param opts - Which replies end the call, and how long to wait. See {@link CallOptions}.
+     * @returns A {@link CallHandle}: `await` it for the terminal reply, or `for await` it for
+     * progress events as they arrive.
+     *
+     * @remarks
+     * Every consumer of an event bus eventually writes request/reply by hand — mint an id,
+     * subscribe, match, time out, unsubscribe — and every one of them writes the same eighty lines
+     * with the same two bugs: the subscription outlives the call, and a responder that forgets to
+     * echo the id produces a timeout with nothing to point at. This is that, once.
+     *
+     * **Correlation is causal.** The store stamps `parentId` on anything emitted while an event is
+     * being handled, so a responder that replies through the `emit` it was handed is already
+     * correlated. There is no id to mint, echo, or forget:
+     *
+     * ```ts
+     * store.registerEffect({
+     *   when: { keys: [["rpc", "ask"]] },
+     *   effect: async (event, _get, emit) => {
+     *     await emit("rpc", "answer", await lookup(event.payload.q));
+     *   },
+     * });
+     * ```
+     *
+     * **The reply carries its own discriminant.** A call resolves to the *event*, not the payload,
+     * because a caller often cannot know which kind of reply it will get:
+     *
+     * ```ts
+     * const res = await store.call("rpc", "ask", { q }, { reply: ["rpc", ["answer", "error"]] });
+     * switch (res.type) {
+     *   case "answer": return res.payload;
+     *   case "error":  throw new Error(res.payload.reason);
+     * }
+     * ```
+     *
+     * **Progress streams, with backpressure.** Any correlated event that is not terminal is
+     * progress, and iterating the call consumes it. The producer genuinely waits: `emit` resolves
+     * only once its effects have run, and the collector is an effect that does not return until the
+     * consumer has taken the item. A responder writing `await emit("rpc", "progress", chunk)` is
+     * therefore paced by the reader, with nothing buffering without bound.
+     *
+     * ```ts
+     * const call = store.call("job", "start", { id }, {
+     *   reply: ["job", "done"],
+     *   highWaterMark: 4,
+     * });
+     * for await (const step of call) await render(step.payload); // producer waits on this
+     * const { payload } = await call;
+     * ```
+     *
+     * Backpressure engages **once you begin iterating**. A call that is only awaited never pulls,
+     * so blocking its producer would deadlock the call itself — progress nobody reads would stop
+     * the terminal event from ever being sent. Un-iterated progress therefore buffers to
+     * `highWaterMark` and is then counted on {@link CallHandle.dropped} rather than blocking.
+     *
+     * **This is a local primitive.** A reply cannot reach it from a federated peer: the federation
+     * envelope carries neither `meta` nor `parentId`, and ingress namespaces the channel, so
+     * neither correlation nor the reply route survives the hop. That is not an oversight to route
+     * around — federation answers cross-node request/reply with typed peer *queries*, which are
+     * gated by a responder policy that may concede or deny. A call that federated silently would
+     * turn that access decision into an accident of which channel someone named. Ask a peer with a
+     * query; use `call` within a process.
+     *
+     * @example Timeout is idle, not total
+     * ```ts
+     * // Survives a job that streams for minutes; fails a responder that goes quiet for 5s.
+     * await store.call("job", "start", { id }, { reply: ["job", "done"], timeoutMs: 5_000 });
+     * ```
+     *
+     * @example Cancelling
+     * ```ts
+     * const call = store.call("rpc", "ask", { q }, { reply: ["rpc", "answer"] });
+     * useEffect(() => () => call.cancel("unmounted"), [call]);
+     * ```
+     *
+     * @public
+     */
+    call<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T], opts: CallOptions<EM>): CallHandle<EventUnion<EM>, EventUnion<EM>>;
     registerEffect(spec: EffectSpec<DeepReadonly<S>, EM>): () => void;
     /**
      * Convenience helper to register an **effect** filtered by a single `(channel, type)` pair.
@@ -955,6 +1177,10 @@ export declare function createStore<S extends Record<string, any>, EM extends Ev
     };
     onEffectError?: (error: unknown, event: EventUnion<EM>) => void;
     onReducerError?: (error: unknown, event: EventUnion<EM>, slice: string) => void;
+    maxReduceDepth?: number;
+    maxTransitionsPerDrain?: number;
+    onCascade?: (info: CascadeInfo<EM>) => void;
+    onRejected?: (rejection: Rejection, event: EventUnion<EM>, slice: string) => void;
 }): StoreInstance<keyof S & string, S, EM>;
 /**
  * Creates a store with types inferred from the reducers map.
@@ -996,6 +1222,10 @@ export declare function createStore<RM extends ReducersMapAny>(cfg: {
     };
     onEffectError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>) => void;
     onReducerError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>, slice: string) => void;
+    maxReduceDepth?: number;
+    maxTransitionsPerDrain?: number;
+    onCascade?: (info: CascadeInfo<EMFromReducersStrict<RM>>) => void;
+    onRejected?: (rejection: Rejection, event: EventUnion<EMFromReducersStrict<RM>>, slice: string) => void;
 }): StoreInstance<keyof RM & string, StateFromReducers<RM>, EMFromReducersStrict<RM>>;
 /**
  * Utility to define **typed** `(channel, events[])` definitions for reducer specs.

package/dist/types/store/call.d.ts

@@ -0,0 +1,149 @@
+import { EventMapBase, EventUnion } from '../types.js';
+/**
+ * Which reply events end a {@link StoreInstance.call | call}, and therefore what it resolves to.
+ *
+ * @remarks
+ * Given as `[channel]` or `[channel, type]` or `[channel, [type, type]]`. The named types are
+ * **terminal**: the first one to arrive settles the call. Every other correlated event on that
+ * channel is progress.
+ *
+ * Naming a channel alone makes every event on it terminal, which suits a responder with a single
+ * kind of answer. Naming types is what lets a responder stream: `["rpc", ["answer", "error"]]`
+ * ends on either, and anything else — `progress`, `partial`, `log` — flows to the consumer.
+ *
+ * @public
+ */
+export type ReplySpec<EM extends EventMapBase> = readonly [channel: keyof EM & string] | readonly [channel: keyof EM & string, type: string] | readonly [channel: keyof EM & string, types: readonly string[]];
+/**
+ * Options for {@link StoreInstance.call}.
+ *
+ * @public
+ */
+export interface CallOptions<EM extends EventMapBase> {
+    /** Which reply events end the call. See {@link ReplySpec}. */
+    readonly reply: ReplySpec<EM>;
+    /**
+     * How long the call may sit **idle** before it gives up, in milliseconds.
+     *
+     * @remarks
+     * Idle, not total: every correlated event resets it, progress included. A job that streams for
+     * two minutes must not fail a thirty-second call, and a total deadline would make the timeout a
+     * function of how much work the responder had to do rather than whether it is still alive.
+     *
+     * For a genuine deadline — "this must be finished by then, however lively" — use
+     * {@link CallOptions.signal} with an `AbortSignal.timeout()`.
+     *
+     * @default 30000
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Aborts the call. The returned promise rejects and the iterator ends.
+     *
+     * @remarks
+     * Unlike `timeoutMs` this is absolute, so it is the right tool for a request deadline, a
+     * user-cancelled action, or a component unmounting.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * How many progress events may buffer before the producer is made to wait.
+     *
+     * @remarks
+     * Only meaningful once the caller is iterating. See {@link StoreInstance.call} for what
+     * backpressure means here and when it engages.
+     *
+     * @default 16
+     */
+    readonly highWaterMark?: number;
+    /**
+     * Correlate on this id instead of on causality.
+     *
+     * @remarks
+     * Causal matching — a reply is correlated because the store stamped it as *caused by* the
+     * request — is free and cannot be forged, but only holds in one process. A reply arriving from
+     * another node, a worker, or any transport carries no causal link, so for those the responder
+     * echoes an id and both sides agree on it here.
+     *
+     * When set, the id is sent as `meta.correlationId` and a reply matches if it echoes the same
+     * value **or** is causally descended. Causality still wins where it applies, so a local
+     * responder needs no changes to be compatible with a remote one.
+     */
+    readonly correlationId?: string;
+}
+/**
+ * The result of {@link StoreInstance.call}: awaitable for the terminal reply, async-iterable for
+ * progress.
+ *
+ * @typeParam TReply - The terminal reply event.
+ * @typeParam TProgress - Non-terminal correlated events.
+ *
+ * @remarks
+ * One object serving both shapes, rather than two functions, because the caller's intent is not
+ * known at the call site — the same request may be awaited in one place and streamed in another,
+ * and the responder should not have to care which.
+ *
+ * ```ts
+ * // Await the answer, ignore the running commentary.
+ * const done = await store.call("rpc", "ask", { q }, { reply: ["rpc", "answer"] });
+ *
+ * // Or consume the commentary, then take the answer.
+ * const call = store.call("rpc", "ask", { q }, { reply: ["rpc", "answer"] });
+ * for await (const step of call) render(step.payload);
+ * const answer = await call;
+ * ```
+ *
+ * Awaiting the same call twice is safe and yields the same reply; the terminal event is retained.
+ *
+ * @public
+ */
+export interface CallHandle<TReply, TProgress> extends Promise<TReply>, AsyncIterable<TProgress> {
+    /**
+     * Progress events discarded because nothing was iterating.
+     *
+     * @remarks
+     * Zero unless the call was awaited without being iterated *and* the responder streamed more
+     * than `highWaterMark` events. Non-zero is not an error — it is the honest count of what a
+     * caller chose not to read, and is worth logging rather than guessing at.
+     */
+    readonly dropped: number;
+    /** Stops listening and settles the call. Safe to call more than once. */
+    cancel(reason?: string): void;
+}
+/**
+ * Raised when a call goes {@link CallOptions.timeoutMs} without a correlated event.
+ *
+ * @public
+ */
+export declare class CallTimeoutError extends Error {
+    readonly channel: string;
+    readonly type: string;
+    readonly idleMs: number;
+    constructor(channel: string, type: string, idleMs: number);
+}
+/**
+ * Raised when a call is cancelled, or its {@link CallOptions.signal} aborts.
+ *
+ * @public
+ */
+export declare class CallAbortedError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Normalises a {@link ReplySpec} into a channel and a terminal-type test.
+ *
+ * @internal
+ */
+export declare function parseReply<EM extends EventMapBase>(reply: ReplySpec<EM>): {
+    channel: string;
+    isTerminal: (type: string) => boolean;
+};
+/**
+ * Whether `event` is a reply to the request identified by `requestId` / `correlationId`.
+ *
+ * @remarks
+ * Causality first: the store stamps `parentId` on anything emitted while handling an event, so a
+ * responder that answers through the `emit` it was given is correlated without doing anything.
+ * The explicit id is the fallback for replies that crossed a boundary causality cannot.
+ *
+ * @internal
+ */
+export declare function isReplyTo<EM extends EventMapBase>(event: EventUnion<EM>, requestId: string, correlationId: string | undefined): boolean;

package/dist/types/store/callQueue.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @module @yoltra/core
+ */
+/**
+ * A bounded hand-off queue between one producer and one consumer, where **the producer waits**.
+ *
+ * @remarks
+ * This is what makes {@link StoreInstance.call}'s backpressure real rather than decorative. A
+ * plain buffer accepts everything and grows; this one hands the producer a promise that does not
+ * resolve until the consumer has taken an item. Because the store awaits effects, and `emit`
+ * resolves only once its effects have finished, a producer writing
+ *
+ * ```ts
+ * await emit("rpc", "progress", chunk);
+ * ```
+ *
+ * genuinely blocks until the consumer catches up — end to end, through machinery that already
+ * existed, with nothing polling and nothing dropped.
+ *
+ * **Backpressure only engages once the consumer has begun iterating.** Before that, items buffer
+ * up to `highWaterMark` and further ones are counted and discarded. That asymmetry is deliberate:
+ * a caller that only awaits the terminal reply never pulls, so blocking the producer would
+ * deadlock the very call it is feeding — the producer would be waiting to deliver progress
+ * nobody will read, and would therefore never emit the terminal event that ends the wait.
+ *
+ * @internal
+ */
+export declare class CallQueue<T> {
+    private readonly highWaterMark;
+    private readonly buffer;
+    /** Consumers parked in `take`, oldest first. */
+    private readonly takers;
+    /** Producers parked in `put`, each with the item they are waiting to hand over. */
+    private readonly putters;
+    private consuming;
+    /** No more items will be accepted, but what is already here is still owed to the consumer. */
+    private ended;
+    /** Abandoned: nothing further is owed to anybody. */
+    private closed;
+    /** Items discarded because nobody was iterating and the buffer was full. */
+    private dropped;
+    constructor(highWaterMark: number);
+    /** How many items were discarded for want of a consumer. */
+    get droppedCount(): number;
+    /**
+     * Marks that a consumer has started pulling. From here on, a full buffer parks the producer
+     * rather than dropping.
+     */
+    beginConsuming(): void;
+    /**
+     * Offers an item. The returned promise settles when the item has been taken — or immediately,
+     * if it fit in the buffer or was dropped.
+     */
+    put(item: T): Promise<void>;
+    /** Takes the next item, waiting if none is available. Resolves `done` once closed and drained. */
+    take(): Promise<IteratorResult<T>>;
+    /**
+     * Stops accepting items, but keeps owing the consumer everything already queued.
+     *
+     * @remarks
+     * What the terminal reply does. Closing outright at that moment would throw away progress the
+     * responder had already handed over and the consumer had not yet read — which is exactly what
+     * happened before this existed: a six-step job delivered five steps, because the sixth was in
+     * the buffer when `done` arrived and the buffer was cleared. The terminal event says "no more
+     * is coming", not "forget what you were given".
+     */
+    end(): void;
+    /**
+     * Closes the queue: waiting consumers are told `done`, and **every parked producer is
+     * released**.
+     *
+     * @remarks
+     * Releasing producers is not tidying up. A producer parked on `put` is a pending `await emit`
+     * somewhere; leaving it parked when the call has already settled would hang the responder for
+     * good — turning a timed-out call into a wedged process, which is worse than the problem
+     * backpressure was added to solve.
+     */
+    close(): void;
+}

package/dist/types/store/rejection.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module @yoltra/core
+ */
+/**
+ * Brand identifying a {@link Rejection}.
+ *
+ * @remarks
+ * `Symbol.for` rather than `Symbol()`, so the brand survives two copies of this package meeting
+ * at runtime — a duplicated dependency, a federated bundle, a consumer that pinned an older
+ * minor. With a unique symbol the check would silently answer `false` across that boundary and a
+ * refusal would read as ordinary state, which is the failure this whole feature exists to end.
+ *
+ * @internal
+ */
+declare const REJECTED: unique symbol;
+/**
+ * A reducer's refusal to apply a write, carrying the reason.
+ *
+ * @remarks
+ * Distinct from a reducer returning its state unchanged, which is indistinguishable from "the
+ * event did not concern me". A `Rejection` says *this write was considered and declined*, and it
+ * says why — which is what a contended store needs and what a lost update otherwise costs.
+ *
+ * @public
+ */
+export interface Rejection {
+    readonly [REJECTED]: true;
+    /** Why the write was refused. Surfaced to the caller and to `onRejected`. */
+    readonly reason: string;
+}
+/**
+ * Builds a {@link Rejection} for a reducer to return instead of state.
+ *
+ * @param reason - Why the write is refused; surfaced verbatim to the caller.
+ *
+ * @remarks
+ * Rejecting is a whole-event act: no slice commits, no change notifications fire, and the
+ * caller's `emit` resolves reporting the refusal. A reducer that merely has nothing to do should
+ * return its state, not this.
+ *
+ * @example Compare-and-swap on a contended slice
+ * ```ts
+ * reducer: (state, event) =>
+ *   event.payload.expectedVersion === state.version
+ *     ? { ...state, ...event.payload.patch, version: state.version + 1 }
+ *     : Rejected(`stale write: expected v${event.payload.expectedVersion}, have v${state.version}`)
+ * ```
+ *
+ * @public
+ */
+export declare function Rejected(reason: string): Rejection;
+/**
+ * Whether a reducer returned a {@link Rejection} rather than state.
+ *
+ * @public
+ */
+export declare function isRejected(value: unknown): value is Rejection;
+export {};