@yoltra/core 0.7.0 → 0.8.0

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

@@ -1,4 +1,4 @@
-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 { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, EventMeta, MiddlewareInput, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EmitOptions, EmitResult, ConnectOptions, InstrumentationObserver, CascadeInfo, EventPhase, Origin, RegistrationObserver, ReplaceScope, NotifiedPhase, 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> {
@@ -11,7 +11,9 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     /**
      * Registered middleware pipeline (run **before** reducers).
      * Stores either raw functions (legacy) or MiddlewareSpec objects.
-     * Return `false` from the middleware function to stop propagation.
+     *
+     * Only an explicit `false` stops propagation. Returning nothing allows the event, so
+     * middleware that only logs or measures needs no `return` at all.
      *
      * @internal
      */
@@ -95,6 +97,17 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     private readonly writtenEventSubscribers;
     private readonly allEventSubscribers;
+    /**
+     * True while a devtools time-travel is applying a snapshot or replaying events.
+     *
+     * @remarks
+     * Saved and restored rather than set and cleared to `false`: `__replayEvents` calls
+     * `__applyExternalState` as its first step, so clearing on the inner call's way out would
+     * unset the flag for the entire event loop that follows it.
+     *
+     * @internal
+     */
+    private replaying;
     /**
      * Track reducerBus unsubs per slice for HMR/register/unregister.
      *
@@ -109,6 +122,70 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private readonly patternReducers;
+    /**
+     * Where each mounted slice came from. See {@link Origin}.
+     *
+     * @remarks
+     * This is what makes `replace*` mean "replace mine" rather than "replace everything". It
+     * is written by `mountSlice` and never by a caller.
+     *
+     * @internal
+     */
+    private readonly sliceOrigin;
+    /**
+     * Who claims each dynamically mounted slice, for introspection only.
+     *
+     * @remarks
+     * Surfaced in `__devtoolsIntrospect()` and named in the collision error. **Never read by
+     * `replace*`.** Correctness comes from {@link Origin}, which nobody has to remember to
+     * pass; if preservation depended on this string, forgetting it would silently delete a
+     * library's state.
+     *
+     * @internal
+     */
+    private readonly sliceOwner;
+    /**
+     * Slices unmounted by their owner, for a development-time diagnostic.
+     *
+     * @remarks
+     * Decoration re-types the store, and after a disposer runs the widened type still claims
+     * a slice that is gone. Reading it would hand a component `undefined` from a type that
+     * promised a value, which is the silent failure this whole feature exists to remove.
+     * Populated only for `dynamic` and `internal` slices: a `spec` slice removed by a
+     * `replace*` was not promised by anyone's widened type.
+     *
+     * Bounded, because a long development session that mounts and disposes repeatedly would
+     * otherwise accumulate an entry per cycle forever. The oldest is dropped: the diagnostic
+     * exists for a slice someone has just stopped using, and a name disposed hundreds of
+     * mounts ago is not the one being read by mistake. Maps to the owner, or `undefined`
+     * when the library did not name itself.
+     *
+     * @internal
+     */
+    private readonly disposedSlices;
+    /** @internal */
+    private readonly registrationObservers;
+    /**
+     * Changes accumulated inside the current public call, flushed once at its end.
+     *
+     * @internal
+     */
+    private pendingRegistrationChanges;
+    /**
+     * Depth of nested registration transactions.
+     *
+     * @remarks
+     * `hotReplace` calls three `replace*` methods, and each of those registers repeatedly.
+     * Only the outermost public entry point flushes, so one `hotReplace` produces one batch
+     * spanning all three kinds rather than three batches of intermediate topology.
+     *
+     * @internal
+     */
+    private registrationDepth;
+    /** True while observers are being notified, so a re-entrant change is queued. @internal */
+    private notifyingRegistrations;
+    /** Batches produced by an observer's own registrations, drained after the current one. @internal */
+    private readonly queuedRegistrationBatches;
     /**
      * Whether `__replayEvents()` is allowed.
      * Set from `spec.devtools.allowReplay`.
@@ -135,6 +212,8 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * signal that a reducer misbehaved.
      */
     private readonly onReducerError?;
+    /** @internal */
+    private readonly onSubscriberError?;
     /**
      * `slice:channel:type` combinations already warned about for payload aliasing.
      *
@@ -224,13 +303,15 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * Tracks processed events by fingerprint with timestamps for TTL-based deduplication.
      *
      * **Deduplication Behavior:**
-     * - Events are fingerprinted using `channel::type::JSON(payload)`
+     * - Events are fingerprinted through the codec, so `Map`, `Set`, `Date`, `BigInt`, binary
+     *   and cyclic payloads all compare by content rather than collapsing to `{}`
+     * - Plain-object keys are sorted, so key order is not content; array and `Map` order is
      * - If an identical fingerprint is seen within the dedup window, it's skipped
-     * - The window is 50ms in development, 100ms in production
+     * - The window is `dedupWindowMs`, which defaults to `0` (dedup off)
      *
      * **Limitations:**
-     * - Non-serializable payloads (functions, symbols, circular refs) get unique
-     *   fingerprints and won't be deduplicated
+     * - A payload larger than the fingerprint node budget is never deduplicated, which is the
+     *   safe direction: a missed dedup costs a duplicate, a false one drops a real event
      * - Legitimate rapid-fire identical events may be incorrectly deduplicated
      * - The cache is bounded to 1000 entries with lazy pruning
      *
@@ -479,17 +560,21 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
         reducers: {
             name: string;
             when: When<EM> | undefined;
+            origin: Origin;
+            owner: string | undefined;
         }[];
         effects: {
             channel: string;
             type: string;
             name?: string;
             description?: string;
+            origin: Origin;
         }[];
         middleware: {
             name?: string;
             description?: string;
             when?: unknown;
+            origin: Origin;
         }[];
         atomic: {
             reducer: string;
@@ -499,6 +584,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
             channel: string;
             type: string;
             phase: string;
+            duringReplay: boolean;
         }[];
         coarse: number;
         dedupHits: number;
@@ -520,6 +606,12 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     __applyExternalState(nextPlain: any): void;
+    /**
+     * The body of {@link __applyExternalState}, with the replay flag already set.
+     *
+     * @internal
+     */
+    private applyExternalStateInner;
     /**
      * Replays a sequence of events from a snapshot through reducers and event
      * subscribers ONLY. Skips dedup, middleware, and effects.
@@ -539,6 +631,12 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
         id: string;
         meta?: EventMeta;
     }>): void;
+    /**
+     * The body of {@link __replayEvents}, with the replay flag already set.
+     *
+     * @internal
+     */
+    private replayEventsInner;
     /**
      * Emits a typed event `(channel, type, payload)`.
      * Events are queued and processed **sequentially** (FIFO).
@@ -674,6 +772,80 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
         reducer: R;
         property: string;
     }, h: (chg: Change) => void, options?: ConnectOptions): () => void;
+    /**
+     * Subscribe to reducer, middleware and effect registrations.
+     *
+     * Delivered as an array, one batch per public call: `replaceReducers` unmounts and then
+     * remounts, and a per-change observer would see a spurious unmount of a slice that is only
+     * being updated. Observers run after the state broadcast, and a registration made by an
+     * observer is queued rather than delivered re-entrantly.
+     *
+     * Replay never produces a change, so there is no `duringReplay` option here. `dispose()`
+     * fires nothing.
+     *
+     * @param observer - Receives one batch per registration change.
+     * @param options - `emitCurrent` synthesizes a `'mounted'` batch for everything already
+     * installed, delivered synchronously before this call returns, carrying each registration's
+     * real origin rather than a synthetic marker.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const off = store.onRegistrationChange((changes) => {
+     *   for (const c of changes) {
+     *     console.log(c.op, c.kind, c.name, c.origin);
+     *   }
+     * }, { emitCurrent: true });
+     * off();
+     * ```
+     *
+     * @public
+     */
+    onRegistrationChange(observer: RegistrationObserver<EM>, options?: {
+        emitCurrent?: boolean;
+    }): Unsubscribe;
+    /**
+     * Everything currently installed, as `"mounted"` changes.
+     *
+     * @internal
+     */
+    private describeCurrentRegistrations;
+    /**
+     * Runs `fn` as one registration transaction, flushing a single batch at the outermost end.
+     *
+     * @internal
+     */
+    private inRegistrationTransaction;
+    /**
+     * Records a change, to be delivered when the current transaction ends.
+     *
+     * @remarks
+     * Guarded on observer count **before** anything is allocated. These call sites run inside
+     * `createStore`, so a twenty-slice store with nobody listening must build no objects and
+     * no arrays at all - the same discipline `emitInstrumentation` already follows.
+     *
+     * @internal
+     */
+    private recordRegistrationChange;
+    /** @internal */
+    private flushRegistrationChanges;
+    /**
+     * Delivers batches an observer produced while being notified.
+     *
+     * @remarks
+     * Bounded like the reduce depth, and for the same reason: two observers registering in
+     * response to each other would otherwise loop forever. Logged rather than thrown - the
+     * topology is correct at that point, and throwing would truncate the stream *and* unwind a
+     * caller that did nothing wrong.
+     *
+     * @internal
+     */
+    private drainQueuedRegistrationBatches;
+    /** @internal */
+    private deliverRegistrationBatch;
+    /** @internal */
+    private invokeRegistrationObserver;
+    get isReplaying(): boolean;
     /**
      * Subscribe to events by channel and type.
      *
@@ -685,8 +857,15 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * - `'committed'` (default): Events that passed middleware and reached reducers.
      *   Notified after reducers, before effects.
      * - `'uncommitted'`: Events rejected by middleware. Notified immediately after rejection.
+     * - `'written'`: Events that actually changed state. Stricter than `committed`, which
+     *   fires for every event a store accepts including one with no reducers at all.
      * - `'all'`: Both committed and uncommitted events. Handler receives the phase parameter
-     *   to distinguish between the two.
+     *   to distinguish between the two. Deliberately not `written` as well: an event that
+     *   writes is also committed, so folding it in would notify every existing `all`
+     *   subscriber twice for one event.
+     *
+     * **Replay:** a handler is not called while devtools is replaying, unless it opted in with
+     * `{ duringReplay: true }`.
      *
      * @typeParam C - Channel key within `EM`.
      * @typeParam T - Event type key within channel `C`.
@@ -720,7 +899,9 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    onEvent<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: NarrowedEventHandler<DeepReadonly<S>, EM, C, T>, phase?: EventPhase): Unsubscribe;
+    onEvent<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: NarrowedEventHandler<DeepReadonly<S>, EM, C, T>, phase?: EventPhase, options?: {
+        duringReplay?: boolean;
+    }): Unsubscribe;
     /**
      * Subscribes to **coarse-grained** commits (called once per successful event, only if state changed).
      *
@@ -787,7 +968,50 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    registerMiddleware(mw: MiddlewareInput<DeepReadonly<S>, EM>): Unsubscribe;
+    registerMiddleware(mw: MiddlewareInput<DeepReadonly<S>, EM>): any;
+    /**
+     * Turns a disposer into the callable object `register*` returns.
+     *
+     * @remarks
+     * `Object.assign` onto the function rather than a new object, so every existing call site
+     * keeps working verbatim: `const off = store.registerEffect(spec); off();` compiles and
+     * runs exactly as before, while `.store` and `.dispose` become available to a library that
+     * wants the widened type.
+     *
+     * A callable object rather than an overload or a second method: an overload cannot change
+     * the return shape based on nothing, and a parallel `registerSliceX` family would leave
+     * the originals permanently second class and force libraries to branch on the core version.
+     *
+     * @internal
+     */
+    private recordMiddlewareChange;
+    /**
+     * Drops an effect's metadata only once nothing is still registered with it.
+     *
+     * @remarks
+     * `effectMeta` is keyed by the effect *function*, and the same function can legitimately
+     * back several registrations. Deleting on the first disposal stripped the name and
+     * description of the ones still live, which a devtools panel then showed as unnamed.
+     *
+     * @internal
+     */
+    private releaseEffectMeta;
+    /** @internal */
+    private recordEffectChange;
+    /** @internal */
+    private asRegistration;
+    /**
+     * The one place the widening cast lives.
+     *
+     * @remarks
+     * Decoration is type-level only. This returns the **same runtime object**: subscriptions,
+     * effects, middleware, the dedup cache, both buses and any in-flight `call()` are
+     * untouched, and nothing re-subscribes. Keeping the cast here means no call site needs one,
+     * which is the entire point of the feature.
+     *
+     * @internal
+     */
+    private widened;
     /**
      * Dynamically **adds** a named slice reducer at runtime.
      *
@@ -810,7 +1034,50 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    registerReducer(name: string, spec: ReducerSpec<any, EM>): () => void;
+    registerReducer(name: string, spec: ReducerSpec<any, EM>, options?: {
+        owner?: string;
+    }): any;
+    /**
+     * Mounts a slice and hands back the widened store alongside a disposer.
+     *
+     * @remarks
+     * The name `registerSlice` is what the guide uses; `registerReducer` keeps its broader
+     * `name: string` signature and delegates here, so existing call sites are untouched.
+     *
+     * @public
+     */
+    registerSlice(name: string, spec: ReducerSpec<any, EM>, options?: {
+        owner?: string;
+    }): any;
+    /** @internal */
+    private registerSliceInner;
+    /**
+     * Mounts a slice and returns the widened store, for chaining.
+     *
+     * @remarks
+     * No disposer, deliberately. After a disposer runs, the widened type still promises a
+     * slice that is gone, and TypeScript cannot express "valid until that call". The chaining
+     * API therefore does not hand one out, so the footgun does not exist on the path most
+     * people take; {@link registerSlice} carries one for the library that owns the slice, and
+     * the documented rule is that a disposer stays library-private.
+     *
+     * @public
+     */
+    withSlice(name: string, spec: ReducerSpec<any, EM>, options?: {
+        owner?: string;
+    }): any;
+    /**
+     * Registers middleware and returns the widened store, for chaining.
+     *
+     * @public
+     */
+    withMiddleware(mw: MiddlewareInput<DeepReadonly<S>, EM>): any;
+    /**
+     * Registers an effect and returns the widened store, for chaining.
+     *
+     * @public
+     */
+    withEffect(spec: EffectSpec<DeepReadonly<S>, EM>): any;
     /**
      * Registers an **effect** (stateless async event consumer) that runs after reducers.
      *
@@ -923,7 +1190,17 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @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;
+    registerEffect(spec: EffectSpec<DeepReadonly<S>, EM>): any;
+    /**
+     * {@link registerEffect}, with the provenance the caller cannot set.
+     *
+     * @remarks
+     * Kept private so no origin parameter leaks into `StoreInstance`. Three callers: the
+     * constructor (`spec`), the public method (`dynamic`), and `store.call()` (`internal`).
+     *
+     * @internal
+     */
+    private registerEffectWithOrigin;
     /**
      * Convenience helper to register an **effect** filtered by a single `(channel, type)` pair.
      *
@@ -962,7 +1239,11 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    replaceMiddleware(next: MiddlewareInput<DeepReadonly<S>, EM>[]): void;
+    replaceMiddleware(next: MiddlewareInput<DeepReadonly<S>, EM>[], opts?: {
+        scope?: ReplaceScope;
+    }): void;
+    /** @internal */
+    private replaceMiddlewareInner;
     /**
      * Replaces all registered **effects** (HMR-friendly).
      *
@@ -979,12 +1260,24 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    replaceEffects(next: Array<EffectSpec<DeepReadonly<S>, EM>>): void;
+    replaceEffects(next: Array<EffectSpec<DeepReadonly<S>, EM>>, opts?: {
+        scope?: ReplaceScope;
+    }): void;
+    /** @internal */
+    private replaceEffectsInner;
     /**
      * Replaces the entire **reducer set** (HMR-friendly).
      *
      * @param next - Map of slice specs keyed by slice name.
-     * @param opts - `{ preserveState?: boolean }` (default `true`).
+     * @param opts - `{ preserveState?: boolean }` (default `true`) and
+     * `{ scope?: "spec" | "all" }` (default `"spec"`).
+     *
+     * @remarks
+     * Replaces **spec-provenance slices only**. A slice mounted after construction with
+     * `registerSlice` survives, along with its state: it was never part of the set this call
+     * is replacing. Pass `{ scope: "all" }` for the pre-0.8.0 wholesale behaviour.
+     *
+     * Throws, before mutating anything, if `next` names a slice a library mounted at runtime.
      *
      * @example Hot module replacement
      * ```ts
@@ -999,7 +1292,34 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     replaceReducers(next: Record<R, ReducerSpec<S[R], EM>>, opts?: {
         preserveState?: boolean;
+        scope?: ReplaceScope;
     }): void;
+    /** @internal */
+    private replaceReducersInner;
+    /**
+     * Refuses, before anything is mutated, to take over a slice mounted at runtime.
+     *
+     * @remarks
+     * An application authoring a slice a library owns is a real mistake, and a silent takeover
+     * is the worst available outcome: the library keeps a disposer for a slice that is no
+     * longer its own. Throwing part-way through would be worse still, which is why this runs
+     * as a pre-flight and why `hotReplace` calls it before swapping anything at all.
+     *
+     * @internal
+     */
+    private assertNoSliceCollision;
+    /**
+     * Says what a `replace*` call left alone, when it left anything alone.
+     *
+     * @remarks
+     * Development only, and silent unless something was actually preserved, so the normal HMR
+     * path stays quiet. `console.debug` rather than `warn`: this is correct operation, and
+     * every existing `warn` in this file marks a genuine problem. It exists so "why is that
+     * effect still firing after a reload" has an answer that does not require reading core.
+     *
+     * @internal
+     */
+    private reportPreserved;
     /**
      * Convenience API to replace **any subset** of store parts (HMR patterns).
      *
@@ -1022,6 +1342,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
         middleware?: MiddlewareInput<DeepReadonly<S>, EM>[];
         effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
         preserveState?: boolean;
+        scope?: ReplaceScope;
     }): void;
     /**
      * Mounts a slice: installs reducer, initializes state (unless preserved),
@@ -1034,6 +1355,37 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private mountSlice;
+    /** @internal */
+    private mountSliceInner;
+    /**
+     * Records a slice mount or unmount for {@link onRegistrationChange}.
+     *
+     * @internal
+     */
+    private recordSliceChange;
+    /**
+     * Announces a newly mounted slice on the connector bus.
+     *
+     * @remarks
+     * `registerReducer` has always broadcast to `listeners`, which wakes `subscribe` and so
+     * `useSelector`. It emitted **nothing** on `connectorBus`, which is what `connect` rides,
+     * so `useAtomicProp`, `useAtomicProps` and the Suspense hooks never woke for a slice
+     * mounted after creation: a component subscribed to a path inside it simply never
+     * re-rendered. That makes the decoration story ship a documented-as-working path that does
+     * not work, which is why this is here rather than filed as a follow-up.
+     *
+     * Scope, stated precisely because it is narrower than it looks: this emits the slice root
+     * and its **top-level** keys, which is exactly what an ordinary commit emits when a
+     * subtree first appears - `detectChangedProps` reports a newly-appearing branch at its
+     * root, not leaf by leaf. So a `connect` on `"deep.n"` does not fire here, and does not
+     * fire on a normal commit that first creates `deep` either. Consistent, not complete.
+     *
+     * Skipped when nothing is subscribed, and skipped entirely during construction, where no
+     * subscriber can exist yet.
+     *
+     * @internal
+     */
+    private announceMountedSlice;
     /**
      * Unmounts a slice: disposes reducer-bus listeners, removes reducer,
      * and optionally deletes the slice state.
@@ -1130,6 +1482,7 @@ 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;
+    onSubscriberError?: (error: unknown, event: EventUnion<EM>, phase: NotifiedPhase) => void;
     maxReduceDepth?: number;
     maxTransitionsPerDrain?: number;
     onCascade?: (info: CascadeInfo<EM>) => void;
@@ -1175,6 +1528,7 @@ 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;
+    onSubscriberError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>, phase: NotifiedPhase) => void;
     maxReduceDepth?: number;
     maxTransitionsPerDrain?: number;
     onCascade?: (info: CascadeInfo<EMFromReducersStrict<RM>>) => void;

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

@@ -0,0 +1,62 @@
+/**
+ * Content fingerprints for event deduplication.
+ *
+ * @remarks
+ * Extracted from `Store.ts` following the `matching.ts` / `paths.ts` precedent: nothing here
+ * touches an instance field.
+ *
+ * The old fingerprint was `channel::type::JSON.stringify(payload)`, which produced two
+ * inconsistent failures on the one path whose entire job is deciding whether two payloads are
+ * the same. A `Map`, `Set` or typed array stringifies to `{}`, so **distinct payloads
+ * collided and the second event was silently swallowed** - precisely the behaviour the README
+ * says Yoltra refuses to do by default. A `BigInt` or a cycle threw, hit a timestamp fallback,
+ * and was never deduped at all.
+ *
+ * `encodeState` already produces a faithful, JSON-stringifiable representation of all of
+ * those, so fingerprinting through it makes content dedup mean what it says.
+ *
+ * @module
+ */
+/**
+ * JSON with plain-object keys sorted, for a stable content fingerprint.
+ *
+ * @remarks
+ * Insertion order is not content: `{a:1,b:2}` and `{b:2,a:1}` are the same payload and must
+ * fingerprint alike, which `JSON.stringify` alone does not deliver.
+ *
+ * **Arrays and `Map` entries are never sorted.** Their order is semantic - `[1,2]` is not
+ * `[2,1]`, and a `Map` preserves insertion order by specification. Sorting them would make
+ * genuinely different payloads share a fingerprint, which is worse than the bug this module
+ * exists to fix: it would silently drop real events rather than merely failing to dedup.
+ *
+ * Runs over the **already-encoded** value, so `Map`, `Set`, `Date` and binary have already
+ * become plain JSON shapes and there is nothing exotic left to handle.
+ *
+ * `JSON.stringify(v, keyArray)` cannot do this: the replacer-array form applies one global
+ * key list at every depth.
+ *
+ * @internal
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * A content fingerprint for one event.
+ *
+ * @param channel - Event channel.
+ * @param type - Event type.
+ * @param payload - Event payload.
+ * @returns A string that is equal for two events with equal content.
+ *
+ * @remarks
+ * Primitives keep a fast path, but a typed one: `String(payload)` alone made the number `1`
+ * and the string `"1"` the same event, as it did `true` and `"true"`. `null` and `undefined`
+ * are likewise distinguished, having previously shared `::null`.
+ *
+ * When the payload exceeds the node budget the fingerprint degrades to **never dedupe**
+ * rather than maybe-wrongly-dedupe. Two large payloads differing only past the cutoff would
+ * otherwise collide and the second would be dropped; refusing to dedup merely costs a
+ * duplicate, which is the safe direction and matches what already happened to payloads the
+ * old implementation could not serialize.
+ *
+ * @internal
+ */
+export declare function fingerprint(channel: string, type: string, payload: unknown): string;