@yoltra/core 0.3.0 → 0.4.0

package/dist/types/serialize/codec.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Lossless encoding of store state for the wire.
+ *
+ * @remarks
+ * The wire is JSON, and `JSON.stringify` is not a safe way to put arbitrary state on it. It does
+ * not fail on the values it cannot represent — it quietly destroys them. A `Map` becomes `{}`, a
+ * `Set` becomes `{}`, a `Date` becomes a string, `undefined` disappears from objects entirely,
+ * and a `BigInt` or a cycle throws from inside a handler nobody awaits.
+ *
+ * Silent destruction is the dangerous half. The panel showed `{}` where a `Map` lived, which is
+ * merely wrong; but time-travel then sent that `{}` back and applied it to the running store,
+ * replacing a live `Map` with an empty object in the user's own application. A debugging tool
+ * corrupting the program it is inspecting is the worst failure available to it.
+ *
+ * Values are therefore tagged rather than coerced. Anything JSON can carry travels unchanged;
+ * anything it cannot is wrapped in a marker object that {@link decodeState} reverses exactly.
+ *
+ * @module
+ */
+/** Options for {@link encodeState}. */
+export interface EncodeOptions {
+    /**
+     * Redacts a value before it leaves the process.
+     *
+     * @remarks
+     * State frequently holds tokens, session material and personal data, and devtools traffic
+     * crosses a socket to another process. Return the replacement value, or the value itself to
+     * keep it. Applied before encoding, so a redacted value is encoded like any other.
+     */
+    readonly sanitize?: (path: string, value: unknown) => unknown;
+    /**
+     * Maximum number of nodes to encode. Beyond it, subtrees are replaced by a truncation marker.
+     *
+     * @remarks
+     * A snapshot larger than the hub's frame cap is rejected outright, which reads to the user as
+     * a panel that hangs. Truncating visibly is a better failure: the panel renders, and says
+     * where it stopped. Defaults to 100000.
+     */
+    readonly maxNodes?: number;
+}
+/** Reports what an encode had to compromise. Empty when nothing was lost. */
+export interface EncodeReport {
+    /** Node budget was exhausted and some subtrees were replaced by markers. */
+    readonly truncated: boolean;
+    /** Values no JSON representation exists for, by path — functions, symbols, DOM nodes. */
+    readonly unsupported: readonly string[];
+}
+/** Result of {@link encodeState}. */
+export interface EncodeResult {
+    readonly value: unknown;
+    readonly report: EncodeReport;
+}
+/**
+ * Encodes a value into something `JSON.stringify` can carry losslessly.
+ *
+ * @param input - Any value, including one holding `Map`, `Set`, `Date`, `BigInt` or cycles.
+ * @param options - Redaction and size limits.
+ * @returns The encoded value plus a report of anything that could not be represented.
+ *
+ * @example
+ * ```ts
+ * const { value } = encodeState({ index: new Map([['a', 1]]) });
+ * JSON.stringify(value); // safe, and decodeState restores the Map
+ * ```
+ *
+ * @public
+ */
+export declare function encodeState(input: unknown, options?: EncodeOptions): EncodeResult;
+/**
+ * Reverses {@link encodeState}.
+ *
+ * @param input - A value produced by `encodeState` (typically after a JSON round trip).
+ * @returns The original structure, with `Map`, `Set`, `Date` and friends restored.
+ *
+ * @remarks
+ * Unsupported markers decode to `undefined`: a function cannot be reconstructed, and inventing a
+ * placeholder would be worse than an absent value. Cycles are restored by resolving references
+ * after the tree is built, so a decoded structure is cyclic exactly where the original was.
+ *
+ * @public
+ */
+export declare function decodeState(input: unknown): unknown;
+/** Outcome of {@link encodeStateBounded}. */
+export interface BoundedEncodeResult {
+    /** The encoded value, small enough to send. */
+    readonly value: unknown;
+    /** `true` when the state did not fit and parts were replaced by markers. */
+    readonly truncated: boolean;
+    /** Explains what was dropped, for display beside a partial tree. */
+    readonly note?: string;
+}
+/**
+ * Encodes a value, shrinking it until its serialized form fits within `maxBytes`.
+ *
+ * @param input - Any value.
+ * @param maxBytes - Byte budget for the serialized form.
+ * @param options - Passed through to {@link encodeState}.
+ *
+ * @returns The encoded value and whether anything had to be dropped.
+ *
+ * @remarks
+ * A frame larger than the hub's cap is not merely slow — it is rejected, and the connection with
+ * it, so the client reconnects, asks again, is refused again, and the panel sits waiting through
+ * a loop with nothing on screen to explain it. The size therefore has to be bounded before the
+ * frame is sent rather than discovered afterwards.
+ *
+ * Node count is a poor proxy for bytes: a hundred nodes holding base64 blobs outweigh a hundred
+ * thousand holding integers. So this measures the encoded output and, when it is too large,
+ * scales the node budget by how far over it went and measures again. Scaling by the overshoot
+ * rather than halving matters: from a default of a hundred thousand nodes, repeated halving
+ * needs a dozen rounds to reach the hundreds, so a state that could have been shown in part
+ * would have been abandoned instead.
+ *
+ * Truncation is reported rather than performed silently. A partial tree presented as the state is
+ * worse than no tree at all: a debugger that quietly lies about state is not a debugger.
+ *
+ * @public
+ */
+export declare function encodeStateBounded(input: unknown, maxBytes: number, options?: EncodeOptions): BoundedEncodeResult;

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

@@ -1,4 +1,4 @@
-import { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, MiddlewareFunction, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EmitOptions, InstrumentationObserver, EventPhase, NarrowedEventHandler, When } from '../types';
+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';
 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).
@@ -47,7 +47,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     private readonly listeners;
     /**
      * Registered effect handlers keyed by `"channel::type"` for O(1) lookup.
-     * Used for effects with explicit `keys` or legacy `events` targeting.
+     * Used for effects with explicit `keys` targeting.
      *
      * @internal
      */
@@ -102,12 +102,33 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private readonly replayEnabled;
+    /**
+     * Produces the `id` for each emitted event. Defaults to `crypto.randomUUID()`; overridable
+     * via {@link StoreSpec.idFactory} for runtimes lacking it or for deterministic tests.
+     *
+     * @internal
+     */
+    private readonly idFactory;
     /**
      * Optional hook invoked when an effect throws/rejects. See
      * {@link StoreSpec.onEffectError}. `await emit()` never rejects on effect
      * failure — this is how callers observe effect errors.
      */
     private readonly onEffectError?;
+    /**
+     * Optional hook invoked when a reducer throws. See {@link StoreSpec.onReducerError}. The
+     * failing slice is isolated rather than the event being rolled back, so this is the only
+     * signal that a reducer misbehaved.
+     */
+    private readonly onReducerError?;
+    /**
+     * `slice:channel:type` combinations already warned about for payload aliasing.
+     *
+     * @remarks
+     * Development-only diagnostics have to stay quiet enough to be read. One warning names the
+     * pattern; repeating it once per event would bury it.
+     */
+    private readonly warnedPayloadAliases;
     /**
      * Pending events awaiting the **synchronous** reduce phase (middleware +
      * reducers + subscribers + coarse listeners). Drained by {@link drainReduce}.
@@ -327,6 +348,30 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @internal
      */
+    /**
+     * Reduces one slice and contains any error it raises.
+     *
+     * @returns `true` when the slice changed.
+     *
+     * @remarks
+     * The single funnel both dispatch paths go through, which is the point. Keyed reducers run
+     * through `reducerBus`, whose handler loop caught and logged; pattern reducers were called
+     * straight from the drain, so their errors escaped to the caller instead. The same bug in the
+     * same reducer therefore produced two different outcomes depending on how the slice happened
+     * to be targeted — a keyed reducer's throw let the event commit and its effects run, while a
+     * 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
+     * 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.
+     *
+     * @internal
+     */
+    private forwardEventGuarded;
     private forwardEvent;
     /**
      * Returns a structured introspection snapshot for DevTools UIs.
@@ -400,6 +445,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
         type: string;
         payload: any;
         id: string;
+        meta?: EventMeta;
     }>): void;
     /**
      * Emits a typed event `(channel, type, payload)`.
@@ -605,13 +651,21 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
     /**
      * Registers a middleware (runs **before** reducers).
      *
-     * @param mw - Middleware `(state, event, emit) => boolean|Promise<boolean>`.
-     *        Return `false` to cancel event propagation.
+     * @param mw - Middleware `(state, event, emit) => boolean`. Return `false` to cancel event
+     *        propagation.
      * @returns Unsubscribe function that removes this middleware.
      *
+     * @remarks
+     * **Synchronous, and that is the contract.** The reduce phase completes before `emit()`
+     * returns, so the commit decision has to be available in the same tick. An `async` middleware
+     * returns a Promise, every Promise is truthy, and the veto would therefore never fire — the
+     * event would commit while the middleware was still deciding. The type rejects it; this note
+     * exists because the examples here used to teach it. Do authorization and validation here, and
+     * anything that needs to await in an effect.
+     *
      * @example Logging middleware
      * ```ts
-     * const off = store.registerMiddleware(async (state, event) => {
+     * const off = store.registerMiddleware((state, event) => {
      *   console.log('Event:', event.channel, event.type, event.payload);
      *   return true; // allow
      * });
@@ -628,12 +682,12 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    registerMiddleware(mw: MiddlewareFunction<DeepReadonly<S>, EM>): Unsubscribe;
+    registerMiddleware(mw: MiddlewareInput<DeepReadonly<S>, EM>): Unsubscribe;
     /**
      * Dynamically **adds** a named slice reducer at runtime.
      *
      * @param name - New slice name (must not already exist).
-     * @param spec - Reducer spec (state, events, reducer).
+     * @param spec - Reducer spec (state, when, reducer).
      * @returns Disposer function that **removes** the slice (and its state).
      *
      * @example
@@ -657,7 +711,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * Effects are **keyed** by `(channel, type)` for O(1) lookup (no scanning all effects).
      *
-     * @param spec - Effect specification with `events` (EventKeys) and `effect` (handler).
+     * @param spec - Effect specification with `when` targeting and `effect` (handler).
      * @returns Unsubscribe function.
      *
      * @example Logging effect
@@ -723,7 +777,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      *
      * @public
      */
-    replaceMiddleware(next: MiddlewareFunction<DeepReadonly<S>, EM>[]): void;
+    replaceMiddleware(next: MiddlewareInput<DeepReadonly<S>, EM>[]): void;
     /**
      * Replaces all registered **effects** (HMR-friendly).
      *
@@ -780,7 +834,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     hotReplace(partial: {
         reducer?: Record<R, ReducerSpec<S[R], EM>>;
-        middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+        middleware?: MiddlewareInput<DeepReadonly<S>, EM>[];
         effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
         preserveState?: boolean;
     }): void;
@@ -789,7 +843,7 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * and wires `(channel, type)` listeners on the reducer bus.
      *
      * @param name - Slice name.
-     * @param rSpec - Reducer spec (state, events, reducer).
+     * @param rSpec - Reducer spec (state, when, reducer).
      * @param opts - `{ preserveState: boolean }` whether to keep existing state.
      *
      * @internal
@@ -806,9 +860,9 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     private unmountSlice;
     /**
-     * Normalizes event targeting from `when` or legacy `events` to an array of EventKeys.
+     * Normalizes event targeting from `when` to an array of EventKeys.
      *
-     * @param spec - Object with optional `when` and/or `events` properties.
+     * @param spec - Object with an optional `when` matcher.
      * @returns Array of `[channel, type]` pairs.
      *
      * @internal
@@ -887,13 +941,15 @@ export declare function createStore<S extends Record<string, any>, EM extends Ev
     reducer?: {
         [K in keyof S]?: ReducerSpec<S[K], EM>;
     };
-    middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+    middleware?: MiddlewareInput<DeepReadonly<S>, EM>[];
     effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
     dedupWindowMs?: number;
+    idFactory?: () => string;
     devtools?: {
         allowReplay?: boolean;
     };
     onEffectError?: (error: unknown, event: EventUnion<EM>) => void;
+    onReducerError?: (error: unknown, event: EventUnion<EM>, slice: string) => void;
 }): StoreInstance<keyof S & string, S, EM>;
 /**
  * Creates a store with types inferred from the reducers map.
@@ -926,13 +982,15 @@ export declare function createStore<S extends Record<string, any>, EM extends Ev
 export declare function createStore<RM extends ReducersMapAny>(cfg: {
     name: string;
     reducer: RM;
-    middleware?: MiddlewareFunction<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>[];
+    middleware?: MiddlewareInput<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>[];
     effects?: Array<EffectSpec<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>>;
     dedupWindowMs?: number;
+    idFactory?: () => string;
     devtools?: {
         allowReplay?: boolean;
     };
     onEffectError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>) => void;
+    onReducerError?: (error: unknown, 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/types.d.ts

@@ -48,7 +48,30 @@ export type EventKey<EM extends EventMapBase> = {
     [C in keyof EM & string]: [C, keyof EM[C] & string];
 }[keyof EM & string];
 /**
- * A single event object: `{ channel, type, payload, id }`.
+ * Opaque, optional envelope metadata carried alongside an {@link Event}.
+ *
+ * @remarks
+ * The store never reads, validates or acts on this — it only carries it end to end, so
+ * reducers, middleware, effects, event subscribers and instrumentation all observe the same
+ * value. It is deliberately untyped at this level: consumers namespace their own keys (for
+ * example a tracing integration keeping provenance under `meta.trace`) rather than
+ * extending core with domain concepts.
+ *
+ * It is **not** part of the deduplication fingerprint, which is computed from
+ * `(channel, type, payload)` only. Two events differing solely in `meta` still dedupe.
+ *
+ * @example
+ * ```ts
+ * await store.emit('orders', 'created', payload, {
+ *   meta: { trace: { origin: 'checkout-service', hop: 1 } },
+ * });
+ * ```
+ *
+ * @public
+ */
+export type EventMeta = Readonly<Record<string, unknown>>;
+/**
+ * A single event object: `{ channel, type, payload, id }`, plus optional `meta`.
  *
  * @typeParam EM - Event map.
  * @typeParam C  - Channel key.
@@ -56,14 +79,16 @@ export type EventKey<EM extends EventMapBase> = {
  * @typeParam P  - Payload type (defaults to `EM[C][T]`).
  *
  * @remarks
- * - The `id` field is automatically added by the store to enable deduplication.
+ * - The `id` field is automatically added by the store to enable deduplication, unless the
+ *   emitter supplies one via {@link EmitOptions.id}.
  * - Used for preventing duplicate event processing (e.g., React Strict Mode).
+ * - `meta` is present only when {@link EmitOptions.meta} was supplied. See {@link EventMeta}.
  *
  * @example
  * ```ts
  * type EM = { ui: { toggle: boolean } };
  * type Evt = Event<EM, 'ui', 'toggle'>;
- * // { channel: 'ui'; type: 'toggle'; payload: boolean; id: string }
+ * // { channel: 'ui'; type: 'toggle'; payload: boolean; id: string; meta?: EventMeta }
  * ```
  *
  * @public
@@ -74,6 +99,11 @@ export interface Event<EM extends EventMapBase = EventMapBase, C extends keyof E
     payload: P;
     /** Unique identifier for deduplication and devtools tracking (automatically added by store) */
     id: string;
+    /**
+     * Optional caller-supplied metadata, carried through the pipeline untouched.
+     * Absent entirely unless {@link EmitOptions.meta} was supplied. See {@link EventMeta}.
+     */
+    readonly meta?: EventMeta;
 }
 /**
  * Generic "old → new" wrapper for fine-grained change notifications.
@@ -129,6 +159,41 @@ export interface EmitOptions {
      * is 0, using a short default window.
      */
     dedupKey?: string;
+    /**
+     * Use this exact id for the event instead of generating one.
+     *
+     * @remarks
+     * Intended for **idempotent re-emission**: a caller replaying an event from elsewhere (a
+     * peer store, a durable log) can preserve the original id so the same logical event keeps
+     * one identity everywhere, which makes it traceable across systems and in DevTools.
+     *
+     * The store does **not** enforce uniqueness — supplying a duplicate id does not dedupe the
+     * event. Deduplication is a separate, opt-in concern; see {@link EmitOptions.dedupKey}.
+     */
+    id?: string;
+    /**
+     * Metadata to attach to this event, carried through the pipeline untouched and visible to
+     * reducers, middleware, effects, subscribers and instrumentation. See {@link EventMeta}.
+     *
+     * @remarks
+     * Omitting this leaves `event.meta` genuinely absent rather than `undefined`, so event
+     * objects are byte-identical to those produced before this option existed.
+     */
+    meta?: EventMeta;
+    /**
+     * Bypass deduplication for this emit entirely, even when the store was created with
+     * {@link StoreSpec.dedupWindowMs} greater than 0.
+     *
+     * @remarks
+     * Content-based dedup fingerprints `(channel, type, payload)`, so a store with a dedup
+     * window silently collapses genuinely distinct events that happen to share a payload —
+     * repeated ticks with an empty payload, or the same event legitimately arriving twice from
+     * two different sources. Set this when the caller already guarantees distinctness by other
+     * means and needs every emit to land.
+     *
+     * Takes precedence over both {@link EmitOptions.dedupKey} and the store-level window.
+     */
+    skipDedup?: boolean;
 }
 export type Emit<EM extends EventMapBase> = <C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T], opts?: EmitOptions) => Promise<void>;
 /**
@@ -145,12 +210,16 @@ export type Unsubscribe = () => void;
  * @public
  */
 export interface InstrumentedEvent<EM extends EventMapBase = EventMapBase> {
-    /** The processed event, including its generated `id`. */
+    /**
+     * The processed event, including its `id` and any {@link EventMeta} the emitter attached.
+     * `meta` is absent unless it was supplied.
+     */
     event: {
         id: string;
         channel: string;
         type: string;
         payload: unknown;
+        meta?: EventMeta;
     };
     /** `true` if the event passed middleware and ran reducers; `false` if vetoed. */
     committed: boolean;
@@ -295,6 +364,26 @@ export type StoreSpec<R extends string, S extends Record<R, any>, EM extends Eve
      * @default 0 (disabled)
      */
     dedupWindowMs?: number;
+    /**
+     * Generates the `id` for each emitted event. Defaults to `crypto.randomUUID()`.
+     *
+     * @remarks
+     * Two reasons to override it. First, portability: `crypto.randomUUID` requires a **secure
+     * context** in browsers and is absent on some runtimes (React Native / Hermes), where the
+     * default would throw on every emit. Second, determinism: injecting a counter makes event
+     * ids stable across runs, which is what allows byte-exact assertions in tests.
+     *
+     * The factory must return a string. Uniqueness is the caller's responsibility.
+     *
+     * @default () => crypto.randomUUID()
+     *
+     * @example
+     * ```ts
+     * let n = 0;
+     * const store = createStore({ name: 'Test', reducer, idFactory: () => `evt-${++n}` });
+     * ```
+     */
+    idFactory?: () => string;
     /**
      * DevTools configuration options.
      *
@@ -324,6 +413,25 @@ export type StoreSpec<R extends string, S extends Record<R, any>, EM extends Eve
      * @param event - The event whose effect failed.
      */
     onEffectError?: (error: unknown, event: EventUnion<EM>) => void;
+    /**
+     * Invoked when a reducer throws.
+     *
+     * @remarks
+     * A reducer is meant to be pure and total, so a throw is a bug in application code — and it
+     * used to be almost invisible. Keyed reducers ran through a bus that logged and moved on,
+     * letting the event commit and its effects run; pattern reducers threw straight out of the
+     * drain, aborting the commit and notifying nobody. Both paths now isolate the failing slice
+     * and report here.
+     *
+     * The failing slice keeps its previous state; every other slice still reduces, and the event
+     * still commits if anything else changed. `emit()` never rejects because of a reducer error,
+     * so this hook is how a caller observes one.
+     *
+     * @param error - The thrown value.
+     * @param event - The event being reduced when it threw.
+     * @param slice - Name of the slice whose reducer threw.
+     */
+    onReducerError?: (error: unknown, event: EventUnion<EM>, slice: string) => void;
 };
 /**
  * Public Store surface.
@@ -384,9 +492,9 @@ export interface StoreInstance<R extends string = string, S extends Record<R, an
      */
     registerEffect(spec: EffectSpec<DeepReadonly<S>, EM>): Unsubscribe;
     /**
-     * Dynamically add middleware.
+     * Dynamically add middleware, in either the function or the spec form.
      */
-    registerMiddleware(mw: MiddlewareFunction<DeepReadonly<S>, EM>): Unsubscribe;
+    registerMiddleware(mw: MiddlewareInput<DeepReadonly<S>, EM>): Unsubscribe;
     /**
      * Dynamically add/remove a namespaced reducer slice at runtime.
      */
@@ -466,7 +574,7 @@ export interface StoreInstance<R extends string = string, S extends Record<R, an
      */
     hotReplace(partial: {
         reducer?: Record<R, ReducerSpec<S[R], EM>>;
-        middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+        middleware?: MiddlewareInput<DeepReadonly<S>, EM>[];
         effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
         preserveState?: boolean;
     }): void;
@@ -487,6 +595,7 @@ export interface StoreInstance<R extends string = string, S extends Record<R, an
         type: string;
         payload: any;
         id: string;
+        meta?: EventMeta;
     }>): void;
     /**
      * Returns a structured introspection snapshot for DevTools UIs.
@@ -569,15 +678,6 @@ export interface StoreInstance<R extends string = string, S extends Record<R, an
  * };
  * ```
  *
- * @example Using `events` (legacy)
- * ```ts
- * const counterSpec: ReducerSpec<{ value: number }, MyEM> = {
- *   state: { value: 0 },
- *   events: [['ui', 'increment'], ['ui', 'decrement']],
- *   reducer(s, evt) { ... },
- * };
- * ```
- *
  * @public
  */
 export interface ReducerSpec<S = any, EM extends EventMapBase = EventMapBase> {
@@ -587,14 +687,8 @@ export interface ReducerSpec<S = any, EM extends EventMapBase = EventMapBase> {
     state: S;
     /**
      * Event targeting using the unified `When` matcher.
-     * Preferred over `events` for new code.
      */
     when?: When<EM>;
-    /**
-     * List of EventKeys `[channel, type]` that this reducer responds to.
-     * @deprecated Use `when: { keys: [...] }` instead for better type inference.
-     */
-    events?: ReadonlyArray<EventKey<EM>>;
     /**
      * Pure reducer function: `(state, event) => nextState`.
      */
@@ -651,14 +745,8 @@ export type ReducerFunction<S = any, EM extends EventMapBase = EventMapBase> = (
 export interface EffectSpec<S = any, EM extends EventMapBase = EventMapBase> {
     /**
      * Event targeting using the unified `When` matcher.
-     * Preferred over `events` for new code.
      */
     when?: When<EM>;
-    /**
-     * List of EventKeys `[channel, type]` that this effect responds to.
-     * @deprecated Use `when: { keys: [...] }` instead for better type inference.
-     */
-    events?: ReadonlyArray<EventKey<EM>>;
     /**
      * Async effect handler: `(event, getState, emit) => void | Promise<void>`.
      */
@@ -986,11 +1074,23 @@ export type Dotted<Slice> = (keyof Slice & string) | Path<Slice>;
 /**
  * Deep readonly type: recursively makes all properties readonly.
  *
+ * @remarks
+ * The built-in object types are handled before the general mapped-object case, because
+ * mapping over one destroys it. `{ readonly [K in keyof Map<K, V>]: ... }` produces an object
+ * carrying the *names* of a Map's methods with their signatures rewritten, so reading a Map
+ * out of state and calling `.get()` on it was a type error even though the value at runtime
+ * is an ordinary Map. The same applied to `Set`, `Date`, `RegExp` and any function stored in
+ * state.
+ *
+ * Collections become their `Readonly*` counterparts, which is the same treatment arrays
+ * already had. Functions are returned untouched: a function's properties are not state, and
+ * mapping over them makes it uncallable.
+ *
  * @typeParam T - Type to make readonly.
  *
  * @public
  */
-export type DeepReadonly<T> = T extends (infer A)[] ? ReadonlyArray<DeepReadonly<A>> : T extends object ? {
+export type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends (infer A)[] ? ReadonlyArray<DeepReadonly<A>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends Date | RegExp | Promise<unknown> | Error ? T : T extends object ? {
     readonly [K in keyof T]: DeepReadonly<T[K]>;
 } : T;
 /**

package/dist/types/utils/immutability.d.ts

@@ -44,4 +44,27 @@ import { DeepReadonly } from '../types';
  *
  * @public
  */
-export declare function freezeState<T>(obj: T, seen?: WeakSet<object>): DeepReadonly<T>;
+export declare function freezeState<T>(obj: T, seen?: WeakSet<object>, alias?: AliasWatch): DeepReadonly<T>;
+/**
+ * Watches the freeze walk for one specific reference.
+ *
+ * @remarks
+ * Exists to turn a dev-only heisenbug into a named warning. Because the freeze is deep and
+ * in place, anything a reducer stores **by reference** is frozen too — the event payload, a
+ * module-level default, a cached response. Mutating that object afterwards then throws, only in
+ * development, from a stack that has nothing to do with the store, and the same code works in
+ * production because the freeze is compiled out.
+ *
+ * Freezing it is not the mistake: an object reachable from state genuinely must not be mutated,
+ * or state changes behind the store's back. Keeping the reference is. The walk already visits
+ * every node, so recognising one of them costs an identity comparison and lets the store say so
+ * at the moment it happens.
+ *
+ * @public
+ */
+export interface AliasWatch {
+    /** The reference to look for while freezing. */
+    readonly watch: object;
+    /** Called if `watch` is reachable from the value being frozen. */
+    readonly onFound: () => void;
+}