@yoltra/core 0.1.0 → 0.2.0

package/README.es.md

@@ -3,7 +3,7 @@
 # @yoltra/core
 
 > 👉 🇲🇽 Versión en Español  |
->  [ 🇺🇸 English Version](https://github.com/yoltra/yoltra/blob/main/packages/core/README.md) 
+>  [ 🇺🇸 English Version](./README.md) 
 
 ![npm downloads](https://badgen.net/npm/dm/@yoltra/core)
 ![License](https://badgen.net/npm/license/@yoltra/core)
@@ -11,7 +11,7 @@
 **Contenedor de estado orientado a eventos, agnostico de framework, con suscripciones de grano
 fino por ruta.**
 
-`@yoltra/core` es la base de [yoltra](https://github.com/yoltra/yoltra/blob/main/README.md).
+`@yoltra/core` es la base de [yoltra](../../README.md).
 Proporciona el store, el pipeline de eventos, middleware, efectos y el sistema de suscripciones
 `connect()`. Cero dependencias de framework.
 
@@ -32,22 +32,24 @@ Cada llamada a `emit()` fluye a traves de un pipeline determinista:
 ```
 emit(channel, type, payload)
   │
-  ├─ 1. Dedup ─── Omitir si la huella es identica dentro de la ventana de tiempo
+  ├─ 0. Dedup (opt-in) ─── Omite un duplicado solo si dedupWindowMs > 0 o se pasa un dedupKey
   │
-  ├─ 2. Middleware ─── Hooks pre-reducer (pueden rechazar → evento "no confirmado")
+  │  ══ fase de reduccion SINCRONA — corre antes de que emit() retorne ══
+  ├─ 1. Middleware ─── Hooks pre-reducer sincronos (devolver false para rechazar → evento "no confirmado")
+  ├─ 2. Reducers ─── Actualizaciones de estado sincronas, deteccion de cambios de grano fino por ruta
+  ├─ 3. Suscriptores de eventos ─── Notificaciones de eventos confirmados/no confirmados
+  ├─ 4. Suscriptores gruesos ─── Listeners externos del store (useSyncExternalStore, etc.), si el estado cambio
   │
-  ├─ 3. Reducers ─── Actualizaciones de estado sincronas, deteccion de cambios de grano fino por ruta
-  │
-  ├─ 4. Suscriptores de eventos ─── Notificaciones de eventos confirmados/no confirmados
-  │
-  ├─ 5. Efectos ─── Efectos secundarios async (post-reducer, indexados para busqueda O(1))
-  │
-  └─ 6. Suscriptores gruesos ─── Listeners externos del store (useSyncExternalStore, etc.)
+  └─ 5. Efectos ─── Efectos secundarios ASYNC, una tarea independiente por evento (indexados para busqueda O(1))
 ```
 
-Cada etapa es interceptable. El middleware puede cancelar eventos, creando eventos "no
-confirmados" a los que la UI aun puede reaccionar. Los efectos se ejecutan despues de los
-reducers y ven el estado final.
+La fase de reduccion (1–4) es **sincrona**, asi que `getState()` es correcto en el instante en que
+`emit()` retorna — incluso con middleware. Los efectos (5) corren despues como una tarea async
+independiente; la promesa de `emit()` se resuelve cuando terminan los efectos de ese evento. Cada
+etapa es interceptable, y `store.instrument()` expone todo el flujo — rutas hoja cambiadas, tiempos
+de reduccion, fase confirmado/rechazado — a las DevTools sin ningun `as any`. Ver la
+[Arquitectura del Pipeline de Eventos](../../docs/es/design/event-queue-architecture.md) para el
+modelo completo.
 
 ---
 
@@ -98,7 +100,7 @@ state.counter.value = 999; // TypeError: Cannot assign to read-only property
 
 ---
 
-## Targeting de Eventos con Matchers `When`
+## Consumo de Eventos con Matchers `When`
 
 Los reducers, efectos y middleware usan un matcher `When` unificado para declarar a cuales
 eventos responden:
@@ -154,8 +156,10 @@ const globalLogger = {
 
 ## Middleware
 
-El middleware se ejecuta **antes** de los reducers y puede cancelar la propagacion de eventos.
-Soporta tanto funciones directas (legacy) como objetos `MiddlewareSpec` con targeting:
+El middleware se ejecuta **sincronamente, antes** de los reducers y puede cancelar la propagacion
+de eventos (devolver `false` para rechazar → evento "no confirmado"). El trabajo async va en los
+efectos, no en el middleware. Soporta tanto funciones directas (legacy) como objetos
+`MiddlewareSpec` con targeting:
 
 ```typescript
 import type { MiddlewareSpec } from "@yoltra/core";
@@ -170,8 +174,8 @@ const adminGuard: MiddlewareSpec<AppState, AppEM> = {
   meta: { type: "middleware", name: "adminGuard" },
 };
 
-// Middleware global — se ejecuta para todos los eventos
-const logger = async (state, event, emit) => {
+// Middleware global — se ejecuta para todos los eventos (sincrono: devuelve un boolean, nunca una Promise)
+const logger = (state, event) => {
   console.log("Event:", event.channel, event.type);
   return true;
 };
@@ -188,7 +192,7 @@ const store = createStore({
 ### Middleware dinamico
 
 ```typescript
-const off = store.registerMiddleware(async (state, event) => {
+const off = store.registerMiddleware((state, event) => {
   return event.type !== "forbidden";
 });
 off(); // Remover despues
@@ -272,19 +276,24 @@ store.onEvent(
 
 ---
 
-## Deduplicacion de Eventos
+## Deduplicacion de Eventos (opt-in)
 
-yoltra deduplica automaticamente eventos identicos dentro de una ventana de tiempo configurable.
-Esto previene el doble procesamiento en React Strict Mode:
+La deduplicacion esta **desactivada por defecto** — yoltra nunca descarta en silencio eventos
+identicos legitimos y rapidos (doble-clics, `+1` repetidos). Actívala solo cuando de verdad quieras
+coalescer:
 
 ```typescript
+// Por contenido: coalescer (channel, type, payload) identicos dentro de una ventana.
 const store = createStore({
   name: "App",
   reducer: {
     /* ... */
   },
-  dedupWindowMs: 100, // default: 50ms dev, 100ms prod
+  dedupWindowMs: 100, // default: 0 (desactivado)
 });
+
+// Por identidad: dedup por una clave explicita — p. ej. un doble-invoke de React Strict Mode en un efecto.
+await store.emit("analytics", "pageView", { page }, { dedupKey: `pageView:${page}` });
 ```
 
 ---
@@ -336,16 +345,22 @@ if (import.meta.hot) {
 
 ## Mejores Practicas
 
-### Siempre hacer await de `emit()`
+### El estado es sincrono; haz `await` solo por los efectos
+
+La fase de reduccion es sincrona, asi que el estado refleja tu evento en el instante en que `emit()`
+retorna — sin `await` para leerlo. Haz `await` de `emit()` cuando ademas quieras que los efectos de
+_ese evento_ hayan terminado:
 
 ```typescript
-await emit("todo", "add", todo);
-const state = store.getState(); // Garantiza que refleja la nueva tarea
+emit("todo", "add", todo);
+store.getState(); // Ya refleja la nueva tarea — sin await
+
+await emit("todo", "save", todo); // se resuelve cuando terminan los efectos de save
 ```
 
 ### Mantener los reducers rapidos
 
-Los reducers son sincronos y bloquean la cola de eventos. Mueve el trabajo costoso a los
+Los reducers son sincronos y corren en el mismo tick que `emit()`. Mueve el trabajo costoso a los
 efectos:
 
 ```typescript
@@ -430,9 +445,9 @@ store.registerEffect({
 
 ## Documentacion
 
-- **[README raiz de yoltra](https://github.com/yoltra/yoltra/blob/main/README.md)** --
+- **[README raiz de yoltra](../../README.md)** --
   Descripcion general y configuracion rapida
-- **[@yoltra/react](https://github.com/yoltra/yoltra/blob/main/packages/react/README.md)** --
+- **[@yoltra/react](../react/README.md)** --
   Hooks de React y Suspense
 - **[Guia de Inicio Rapido](https://github.com/yoltra/yoltra/blob/main/docs/en/QUICK_START_GUIDE.md)**
   -- Cinco pasos hacia una app funcional
@@ -450,13 +465,13 @@ store.registerEffect({
 - **[Logo Cinetico](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-kinetic-logo)**
   -- 3000 círculos con simulación física.
 - **[Integracion con Next.js](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-nextjs)**
-  -- SSR + App Router + cambio de tema
+  -- Pages Router, estado de cliente + cambio de tema
 
 ---
 
 ## Contribuir
 
-- [Raiz del Monorepo](https://github.com/yoltra/yoltra/blob/main/README.md)
+- [Raiz del Monorepo](../../README.md)
 - [Guia de Contribucion](https://github.com/yoltra/yoltra/blob/main/CONTRIBUTING.md)
 
 ---

package/README.md

@@ -2,7 +2,7 @@
 
 # @yoltra/core
 
-> [ 🇲🇽 Versión en Español](https://github.com/yoltra/yoltra/blob/main/packages/core/README.es.md) 
+> [ 🇲🇽 Versión en Español](./README.es.md) 
 > |   👉 🇺🇸 English Version
 
 ![npm downloads](https://badgen.net/npm/dm/@yoltra/core)
@@ -11,7 +11,7 @@
 **Framework-agnostic event-driven state container with fine-grained path subscriptions.**
 
 `@yoltra/core` is the foundation of
-[yoltra](https://github.com/yoltra/yoltra/blob/main/README.md). It provides the store, event
+[yoltra](../../README.md). It provides the store, event
 pipeline, middleware, effects, and the `connect()` subscription system. Zero framework
 dependencies.
 
@@ -32,21 +32,23 @@ Every `emit()` call flows through a deterministic pipeline:
 ```
 emit(channel, type, payload)
   │
-  ├─ 1. Dedup ─── Skip if identical fingerprint within time window
+  ├─ 0. Dedup (opt-in) ─── Skip a duplicate only when dedupWindowMs > 0 or a dedupKey is given
   │
-  ├─ 2. Middleware ─── Pre-reducer hooks (can reject → "uncommitted" event)
+  │  ══ SYNCHRONOUS reduce phase — runs before emit() returns ══
+  ├─ 1. Middleware ─── Synchronous pre-reducer hooks (return false to reject → "uncommitted" event)
+  ├─ 2. Reducers ─── Synchronous state updates, fine-grained path change detection
+  ├─ 3. Event subscribers ─── Committed/uncommitted event notifications
+  ├─ 4. Coarse subscribers ─── External store listeners (useSyncExternalStore, etc.), if state changed
   │
-  ├─ 3. Reducers ─── Synchronous state updates, fine-grained path change detection
-  │
-  ├─ 4. Event subscribers ─── Committed/uncommitted event notifications
-  │
-  ├─ 5. Effects ─── Async side-effects (post-reducer, keyed for O(1) lookup)
-  │
-  └─ 6. Coarse subscribers ─── External store listeners (useSyncExternalStore, etc.)
+  └─ 5. Effects ─── ASYNC side-effects, one independent task per event (keyed for O(1) lookup)
 ```
 
-Every stage is hook-able. Middleware can cancel events, creating "uncommitted" events that the
-UI can still react to. Effects run after reducers and see the final state.
+The reduce phase (1–4) is **synchronous**, so `getState()` is correct the instant `emit()` returns
+— even with middleware. Effects (5) run afterward as an independent async task; the promise from
+`emit()` resolves when that event's effects finish. Every stage is hook-able, and
+`store.instrument()` exposes the whole flow — changed leaf paths, reduce timing, committed/rejected
+phase — to the DevTools with no `as any`. See the
+[Event Pipeline Architecture](../../docs/en/design/event-queue-architecture.md) for the full model.
 
 ---
 
@@ -152,8 +154,9 @@ const globalLogger = {
 
 ## Middleware
 
-Middleware runs **before** reducers and can cancel event propagation. Supports both raw
-functions (legacy) and `MiddlewareSpec` objects with targeting:
+Middleware runs **synchronously, before** reducers and can cancel event propagation (return
+`false` to reject → "uncommitted" event). Async work belongs in effects, not middleware. Supports
+both raw functions (legacy) and `MiddlewareSpec` objects with targeting:
 
 ```typescript
 import type { MiddlewareSpec } from "@yoltra/core";
@@ -168,8 +171,8 @@ const adminGuard: MiddlewareSpec<AppState, AppEM> = {
   meta: { type: "middleware", name: "adminGuard" },
 };
 
-// Global middleware — runs for all events
-const logger = async (state, event, emit) => {
+// Global middleware — runs for all events (synchronous: return a boolean, never a Promise)
+const logger = (state, event) => {
   console.log("Event:", event.channel, event.type);
   return true;
 };
@@ -186,7 +189,7 @@ const store = createStore({
 ### Dynamic middleware
 
 ```typescript
-const off = store.registerMiddleware(async (state, event) => {
+const off = store.registerMiddleware((state, event) => {
   return event.type !== "forbidden";
 });
 off(); // Remove later
@@ -269,19 +272,23 @@ store.onEvent(
 
 ---
 
-## Event Deduplication
+## Event Deduplication (opt-in)
 
-Yoltra automatically deduplicates identical events within a configurable time window. This
-prevents double-processing in React Strict Mode:
+Deduplication is **off by default** — Yoltra never silently drops legitimate rapid-fire identical
+events (double-clicks, repeated `+1`). Opt in only when you actually want coalescing:
 
 ```typescript
+// Content-based: coalesce identical (channel, type, payload) within a window.
 const store = createStore({
   name: "Yoltra_Rocks",
   reducer: {
     /* ... */
   },
-  dedupWindowMs: 100, // default: 50ms dev, 100ms prod
+  dedupWindowMs: 100, // default: 0 (disabled)
 });
+
+// Identity-based: dedupe by an explicit key — e.g. a React Strict Mode double-invoke in an effect.
+await store.emit("analytics", "pageView", { page }, { dedupKey: `pageView:${page}` });
 ```
 
 ---
@@ -333,16 +340,22 @@ if (import.meta.hot) {
 
 ## Best Practices
 
-### Always await `emit()`
+### State is synchronous; `await` only for effects
+
+The reduce phase is synchronous, so state reflects your event the moment `emit()` returns — no
+`await` needed to read it back. Await `emit()` when you also want _this event's_ effects to have
+finished:
 
 ```typescript
-await emit("todo", "add", todo);
-const state = store.getState(); // Guaranteed to reflect the new todo
+emit("todo", "add", todo);
+store.getState(); // Already reflects the new todo — no await required
+
+await emit("todo", "save", todo); // resolves once save's effects complete
 ```
 
 ### Keep reducers fast
 
-Reducers are synchronous and block the event queue. Move expensive work to effects:
+Reducers are synchronous and run in the same tick as `emit()`. Move expensive work to effects:
 
 ```typescript
 // Reducer: just set a loading flag
@@ -426,9 +439,9 @@ store.registerEffect({
 
 ## Documentation
 
-- **[yoltra Root README](https://github.com/yoltra/yoltra/blob/main/README.md)** — Overview and
+- **[yoltra Root README](../../README.md)** — Overview and
   quick start
-- **[@yoltra/react](https://github.com/yoltra/yoltra/blob/main/packages/react/README.md)** —
+- **[@yoltra/react](../react/README.md)** —
   React hooks and Suspense
 - **[Quick Start Guide](https://github.com/yoltra/yoltra/blob/main/docs/en/QUICK_START_GUIDE.md)**
   — Five steps to a working app
@@ -446,13 +459,13 @@ store.registerEffect({
 - **[Kinetic Logo](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-kinetic-logo)**
   — 3000 circles with physics simulation
 - **[Next.js Integration](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-nextjs)**
-  — SSR + App Router + theme switcher
+  — Pages Router, client-side state + theme switcher
 
 ---
 
 ## Contributing
 
-- [Monorepo Root](https://github.com/yoltra/yoltra/blob/main/README.md)
+- [Monorepo Root](../../README.md)
 - [Contributing Guide](https://github.com/yoltra/yoltra/blob/main/CONTRIBUTING.md)
 
 ---

package/dist/types/index.d.ts

@@ -12,4 +12,4 @@ export { Store, createStore, typedEvents } from './store/Store';
 export { detectChangedProps } from './utils/detectChangedProps';
 export { freezeState } from './utils/immutability';
 export { eventKeys } from './types';
-export type { EventMapBase, EventKey, Event, EventUnion, Change, Emit, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, Path, PathValue, WithGlob, Dotted, EventPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types';
+export type { EventMapBase, EventKey, Event, EventUnion, Change, Emit, EmitOptions, InstrumentedEvent, InstrumentationObserver, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, ReducersMapAny, StateFromReducers, EMFromReducersStrict, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, Path, PathValue, WithGlob, Dotted, EventPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types';

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

@@ -1,4 +1,4 @@
-import { Event, EventMapBase, EventKey, Change, DeepReadonly, EffectSpec, MiddlewareFunction, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EventPhase, NarrowedEventHandler, When } from '../types';
+import { Event, EventMapBase, EventKey, EventUnion, Change, DeepReadonly, EffectSpec, MiddlewareFunction, 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).
@@ -103,17 +103,45 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      */
     private readonly replayEnabled;
     /**
-     * FIFO event queue for serialized emission.
+     * 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?;
+    /**
+     * Pending events awaiting the **synchronous** reduce phase (middleware +
+     * reducers + subscribers + coarse listeners). Drained by {@link drainReduce}.
+     *
+     * @internal
+     */
+    private readonly reduceQueue;
+    /**
+     * Re-entrancy guard for the synchronous reduce phase.
+     *
+     * @internal
+     */
+    private isReducing;
+    /**
+     * Registered instrumentation observers (DevTools seam). See {@link instrument}.
+     *
+     * @internal
+     */
+    private readonly instrumentObservers;
+    /**
+     * 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.
      *
      * @internal
      */
-    private readonly eventQueue;
+    private changedPathSink;
     /**
-     * Re-entrancy guard while draining the queue.
+     * Count of effect tasks currently in flight; surfaced as queue depth by
+     * {@link __devtoolsIntrospect}.
      *
      * @internal
      */
-    private isProcessingQueue;
+    private inFlightEffects;
     /**
      * Tracks processed events by fingerprint with timestamps for TTL-based deduplication.
      *
@@ -131,6 +159,23 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private readonly processedEvents;
+    /**
+     * Lifetime count of events suppressed by the deduplication cache.
+     * Exposed via {@link __devtoolsIntrospect} so the DevTools agent can
+     * surface it in the STORE_METRICS response without further core changes.
+     *
+     * @internal
+     */
+    private dedupCount;
+    /**
+     * Store-owned metadata for registered effects, keyed by the effect function.
+     * Kept **off** the caller's function object: mutating a user-owned function
+     * (the old `fn.__quoMeta`) bled metadata across stores that share a handler
+     * and left it attached after unregister. Cleared on {@link dispose}.
+     *
+     * @internal
+     */
+    private effectMeta;
     /**
      * Configuration for event deduplication.
      * @internal
@@ -186,6 +231,14 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private shouldDedupe;
+    /**
+     * Starts the periodic prune interval if it isn't already running. Called when
+     * the first entry is cached so the timer's lifetime tracks actual dedup use
+     * (content window or identity `dedupKey`), independent of `dedupWindowMs`.
+     *
+     * @internal
+     */
+    private ensureCleanupTimer;
     /**
      * Removes expired entries from the processed events cache.
      *
@@ -250,6 +303,14 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @internal
      */
     private notifyEventSubscribers;
+    /**
+     * Invokes a single event-subscription handler **fire-and-forget**: synchronous
+     * throws and async rejections are logged but never block the emit pipeline.
+     * Event subscribers are notifications, not part of the committed reduce result.
+     *
+     * @internal
+     */
+    private invokeEventSubscriber;
     /**
      * Applies a reduced event to a slice and emits **precise** connector events.
      *
@@ -303,6 +364,8 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
             phase: string;
         }[];
         coarse: number;
+        dedupHits: number;
+        queueDepth: number;
     };
     /**
      * Applies an externally provided **whole-state** (e.g., DevTools time travel) and emits
@@ -311,11 +374,15 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * **State Immutability**: If any slices change, a new state object is created via
      * shallow spread. This ensures consistent immutability with {@link forwardEvent}.
      *
+     * **Missing slices**: the snapshot should contain every slice. A slice absent
+     * from `nextPlain` is **retained at its current value** (not blanked to
+     * `undefined`, which would make `getState().<slice>` throw on next access).
+     *
      * @param nextPlain - Plain JS object to become the new state.
      *
      * @internal
      */
-    private __applyExternalState;
+    __applyExternalState(nextPlain: any): void;
     /**
      * Replays a sequence of events from a snapshot through reducers and event
      * subscribers ONLY. Skips dedup, middleware, and effects.
@@ -338,12 +405,14 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * Emits a typed event `(channel, type, payload)`.
      * Events are queued and processed **sequentially** (FIFO).
      *
-     * **Pipeline per event:**
-     * 1. **Deduplication check** - Skip if event ID already processed (React Strict Mode safety)
-     * 2. **Middleware** - Pre-reducer hooks; may cancel by returning `false`
-     * 3. **Reducers** - Synchronous state updates via internal event bus
-     * 4. **Effects** - Async side-effects keyed by `(channel, type)` for O(1) lookup
-     * 5. **Coarse subscribers** - External store subscribers (only if state changed)
+     * **Pipeline per event:** the *reduce phase* (steps 1-4) runs **synchronously**,
+     * so `getState()` reflects the change as soon as `emit()` returns; the *effect
+     * 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)
+     * 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
@@ -354,7 +423,9 @@ export declare class Store<EM extends EventMapBase, R extends string, S extends
      * @param channel - Channel name.
      * @param type - Event type name.
      * @param payload - Payload typed as `EM[C][T]`.
-     * @returns A promise that resolves when the event has finished processing.
+     * @param opts - Optional per-emit options (e.g. `dedupKey` for identity-based dedup).
+     * @returns A promise that resolves once this event's effects have finished.
+     * State is already updated synchronously before `emit()` returns.
      *
      * @example Basic usage
      * ```ts
@@ -373,7 +444,53 @@ 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]): 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<void>;
+    /**
+     * Drains the reduce queue **synchronously**. For each event it runs middleware,
+     * reducers, event subscribers, and coarse listeners in the same tick, so
+     * `getState()` reflects the change the moment {@link emit} returns. Re-entrant
+     * emits (from middleware or subscribers) are appended and drained in the same
+     * pass — preserving FIFO order without interleaving reducers. Each committed
+     * event's effects then run in an independent task (see {@link runEventEffects}).
+     *
+     * @internal
+     */
+    private drainReduce;
+    /**
+     * Runs the **synchronous** part of the pipeline for a single event: middleware
+     * (may veto), key- and pattern-based reducers, committed/uncommitted event
+     * subscribers (fire-and-forget), and coarse listeners.
+     *
+     * @returns `true` if the event was committed (passed middleware), `false` if a
+     * middleware vetoed it.
+     *
+     * @internal
+     */
+    private applyEventSync;
+    /**
+     * Runs a single committed event's effects as an **independent async task**,
+     * then resolves that event's completion deferred so `await emit(...)` settles
+     * once its effects finish. Per-event tasks (rather than one shared serialized
+     * loop) let an effect `await` a re-entrant emit without deadlocking.
+     *
+     * @internal
+     */
+    private runEventEffects;
+    /**
+     * Registers an instrumentation observer. See {@link StoreInstance.instrument}.
+     *
+     * @public
+     */
+    instrument(observer: InstrumentationObserver<EM>): Unsubscribe;
+    /**
+     * 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
+     * re-diff.
+     *
+     * @internal
+     */
+    private emitInstrumentation;
     /**
      * Connects a **fine-grained** listener to a dotted path under a slice.
      *
@@ -776,6 +893,7 @@ export declare function createStore<S extends Record<string, any>, EM extends Ev
     devtools?: {
         allowReplay?: boolean;
     };
+    onEffectError?: (error: unknown, event: EventUnion<EM>) => void;
 }): StoreInstance<keyof S & string, S, EM>;
 /**
  * Creates a store with types inferred from the reducers map.
@@ -814,6 +932,7 @@ export declare function createStore<RM extends ReducersMapAny>(cfg: {
     devtools?: {
         allowReplay?: boolean;
     };
+    onEffectError?: (error: unknown, event: EventUnion<EMFromReducersStrict<RM>>) => void;
 }): StoreInstance<keyof RM & string, StateFromReducers<RM>, EMFromReducersStrict<RM>>;
 /**
  * Utility to define **typed** `(channel, events[])` definitions for reducer specs.