@yoltra/core 0.6.0 → 0.8.0

package/README.md

@@ -5,8 +5,10 @@
 > [ 🇲🇽 Versión en Español](./README.es.md) 
 > |   👉 🇺🇸 English Version
 
-![npm downloads](https://badgen.net/npm/dm/@yoltra/core)
-![License](https://badgen.net/npm/license/@yoltra/core)
+[![npm version](https://img.shields.io/npm/v/@yoltra/core)](https://www.npmjs.com/package/@yoltra/core)
+[![npm downloads](https://img.shields.io/npm/dm/@yoltra/core)](https://www.npmjs.com/package/@yoltra/core)
+[![types](https://img.shields.io/npm/types/@yoltra/core)](https://www.npmjs.com/package/@yoltra/core)
+[![License](https://img.shields.io/npm/l/@yoltra/core)](https://github.com/yoltra/yoltra/blob/main/LICENSE)
 
 **Framework-agnostic event-driven state container with fine-grained path subscriptions.**
 
@@ -34,7 +36,7 @@ emit(channel, type, payload)
   │
   ├─ 0. Dedup (opt-in) ─── Skip a duplicate only when dedupWindowMs > 0 or a dedupKey is given
   │
-  │  ══ SYNCHRONOUS reduce phase — runs before emit() returns ══
+  │  ══ SYNCHRONOUS reduce phase: runs before emit() returns ══
   ├─ 1. Middleware ─── Synchronous pre-reducer hooks (return false to reject → "uncommitted" event)
   ├─ 2. Reducers ─── Every matching slice staged, then all committed under one root
   ├─ 3. Event subscribers ─── Committed/uncommitted event notifications
@@ -43,11 +45,11 @@ emit(channel, type, payload)
   └─ 5. Effects ─── ASYNC side-effects, one independent task per event (keyed for O(1) lookup)
 ```
 
-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
+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
+`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.
 
 ---
@@ -71,17 +73,17 @@ Subscribe to exact state paths using dotted notation. Supports `*` (one segment)
 or more segments) wildcards:
 
 ```typescript
-// Exact path — fires when items[0].title changes
+// Exact path: fires when items[0].title changes
 store.connect({ reducer: "todos", property: "items.0.title" }, (change) =>
   console.log("title:", change.oldValue, "→", change.newValue),
 );
 
-// Single-segment wildcard — fires when ANY item's title changes
+// Single-segment wildcard: fires when ANY item's title changes
 store.connect({ reducer: "todos", property: "items.*.title" }, (change) =>
   console.log("some title changed at", change.path),
 );
 
-// Deep wildcard — fires when anything under items changes
+// Deep wildcard: fires when anything under items changes
 store.connect({ reducer: "todos", property: "items.**" }, (change) =>
   console.log("items tree changed at", change.path),
 );
@@ -108,7 +110,7 @@ await store.emit("auth", "login", { token: "abc123" });
 store.getState().token; // "abc123"
 ```
 
-Such a slice has no property beneath it, so its changes are reported at the **slice root** —
+Such a slice has no property beneath it, so its changes are reported at the **slice root**,
 the empty path. Subscribe to it with `property: ""`:
 
 ```typescript
@@ -117,20 +119,20 @@ store.connect({ reducer: "token", property: "" }, (change) =>
 );
 ```
 
-The types know the difference. `property` on a root-value slice accepts `""` and nothing else —
-there is no key to address — and the value comes back correctly typed:
+The types know the difference. `property` on a root-value slice accepts `""` and nothing else,
+because there is no key to address, and the value comes back correctly typed:
 
 ```typescript
 const token = useAtomicProp({ reducer: "token", property: "" }); // string | null
 ```
 
-### `""` versus `"**"` — watching a whole slice
+### `""` versus `"**"`: watching a whole slice
 
 Two subscriptions sound alike and are not:
 
 | Pattern | Fires when |
 |---|---|
-| `""` | the slice's **whole value** is replaced — a primitive changes, a `Map` is rebuilt, an object slice becomes `null` |
+| `""` | the slice's **whole value** is replaced: a primitive changes, a `Map` is rebuilt, an object slice becomes `null` |
 | `"**"` | **anything** in the slice changes, at any depth. Matches the root too, since `**` matches zero segments |
 | `"*"` | one level down, exactly. Never matches the root |
 
@@ -140,7 +142,7 @@ because such a slice reports its changes at their leaves.
 
 `Map` and `Set` are compared by reference, not by entry: a reducer returning a new `Map` is a
 change, mutating one in place is not. That follows from the immutability contract rather than
-being a special case — build a new collection instead of mutating the stored one. It is also why
+being a special case. Build a new collection instead of mutating the stored one. It is also why
 they have no paths beneath them: `"byId"` is subscribable, `"byId.get"` is not, and the types
 say so.
 
@@ -169,7 +171,7 @@ type AppEM = {
   system: { init: void; shutdown: void };
 };
 
-// Match specific event keys (recommended — preserves type correlation)
+// Match specific event keys (recommended: preserves type correlation)
 const counterReducer = {
   state: { value: 0 },
   when: {
@@ -212,13 +214,16 @@ const globalLogger = {
 ## Middleware
 
 Middleware runs **synchronously, before** reducers and can cancel event propagation (return
-`false` to reject → "uncommitted" event). Async work belongs in effects, not middleware. Supports
+`false` to reject → "uncommitted" event; returning nothing allows it). Async work belongs in
+effects, not middleware. When an event does not commit, `emit` says why: `reason` is
+`"vetoed"`, `"deduped"` or `"cascade"`, and a veto names the middleware in `vetoedBy`, so a
+guard refusing an action is distinguishable from a double-click being collapsed. Supports
 both raw functions (legacy) and `MiddlewareSpec` objects with targeting:
 
 ```typescript
 import type { MiddlewareSpec } from "@yoltra/core";
 
-// Targeted middleware — only runs for admin channel events
+// Targeted middleware: only runs for admin channel events
 const adminGuard: MiddlewareSpec<AppState, AppEM> = {
   when: { channel: "admin" },
   middleware: (state, event) => {
@@ -228,7 +233,8 @@ const adminGuard: MiddlewareSpec<AppState, AppEM> = {
   meta: { type: "middleware", name: "adminGuard" },
 };
 
-// Global middleware — runs for all events (synchronous: return a boolean, never a Promise)
+// Global middleware: runs for all events. Synchronous, never a Promise: only an explicit
+// `false` vetoes, so middleware that just observes can return nothing at all.
 const logger = (state, event) => {
   console.log("Event:", event.channel, event.type);
   return true;
@@ -301,12 +307,12 @@ Subscribe to events (not state) from the view layer. Useful for notifications, a
 responding to rejected events:
 
 ```typescript
-// Committed events (default) — events that passed middleware
+// Committed events (default): events that passed middleware
 const off = store.onEvent("ui", "save", (event, getState, emit, phase) => {
   console.log("Save committed:", event.payload);
 });
 
-// Uncommitted events — events rejected by middleware
+// Uncommitted events: events rejected by middleware
 store.onEvent(
   "ui",
   "delete",
@@ -316,7 +322,7 @@ store.onEvent(
   "uncommitted",
 );
 
-// Written events — state actually changed. Fires after the commit, so getState() is current.
+// Written events: state actually changed. Fires after the commit, so getState() is current.
 store.onEvent(
   "plan",
   "patch",
@@ -326,7 +332,7 @@ store.onEvent(
   "written",
 );
 
-// All events — both committed and uncommitted (not written; see below)
+// All events: both committed and uncommitted (not written; see below)
 store.onEvent(
   "ui",
   "action",
@@ -338,17 +344,35 @@ store.onEvent(
 ```
 
 `committed` means **not vetoed**, and always has: it fires for every event middleware let through,
-whether or not a reducer wrote anything — including every event in a store with no reducers at
+whether or not a reducer wrote anything, including every event in a store with no reducers at
 all. `written` is the stricter fact, added rather than substituted, so toasts and analytics keep
 working unchanged. `all` stays `committed | uncommitted`; folding `written` in would hand existing
 subscribers a second notification per event.
 
+### Event subscribers and time-travel
+
+**Replay does not call your handlers.** Scrubbing a DevTools timeline reduces the events again,
+so state follows the scrub, but `onEvent` handlers stay silent. They used to run exactly as they
+do for a live event, which meant dragging a timeline re-published to peers, re-wrote to sockets
+and re-fired analytics for events that were not happening again, with nothing available inside a
+handler to tell the difference.
+
+A handler that derives view state purely from the event stream, and performs no I/O, can opt in:
+
+```ts
+store.onEvent("ui", "save", handler, "committed", { duringReplay: true });
+```
+
+`store.isReplaying` is there for anything that has to branch rather than simply skip. Coarse
+`subscribe` listeners and `connect` subscriptions keep firing throughout, because the state
+genuinely did change and the UI has to follow the scrub.
+
 ---
 
 ## Commits are atomic across slices
 
 An event that touches several slices writes all of them, then notifies. Nothing observes a
-half-applied event — a subscriber to one slice reading `getState()` sees every other slice of the
+half-applied event. A subscriber to one slice reading `getState()` sees every other slice of the
 same event already applied.
 
 That matters most where a change is used as a signal to re-read, which is what the React hooks do.
@@ -380,8 +404,8 @@ const store = createStore({
 
 const result = await store.emit("plan", "patch", { steps, expectedVersion: 1 });
 
-result.committed; // true — middleware allowed it
-result.written; // false — but nothing was written
+result.committed; // true: middleware allowed it
+result.written; // false: nothing was written
 result.rejected?.reason; // "stale write: expected v1, have v3"
 ```
 
@@ -400,10 +424,10 @@ has made a decision and the whole event yields to it.
 
 ---
 
-## Request and reply — `store.call()`
+## Request and reply: `store.call()`
 
 Every event-bus consumer eventually writes request/reply by hand: mint an id, subscribe, match,
-time out, unsubscribe. It is about eighty lines and it has the same two bugs every time — the
+time out, unsubscribe. It is about eighty lines and it has the same two bugs every time: the
 subscription outlives the call, and a responder that forgets to echo the id produces a timeout
 with nothing to point at.
 
@@ -413,7 +437,7 @@ res.payload.text;
 ```
 
 The responder does nothing special. It replies through the `emit` it was handed, and the store's
-causal stamp correlates the two — **there is no id to mint, echo, or forget**:
+causal stamp correlates the two, and **there is no id to mint, echo, or forget**:
 
 ```typescript
 store.registerEffect({
@@ -453,7 +477,7 @@ const { payload } = await call;
 ```
 
 The backpressure is real, not a buffer with a limit. `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 —
+run, and the collector is an effect that does not return until the consumer has taken the item,
 so a responder writing `await emit("job", "tick", chunk)` is **paced by the reader**:
 
 ```typescript
@@ -466,7 +490,7 @@ effect: async (_event, _get, emit) => {
 ```
 
 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
+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 `call.dropped` rather than blocking.
 
@@ -474,17 +498,17 @@ and is then counted on `call.dropped` rather than blocking.
 
 | | |
 |---|---|
-| `timeoutMs` | **Idle**, not total — every correlated event resets it, progress included. A job that streams for two minutes will not fail a thirty-second call. Default 30s. |
+| `timeoutMs` | **Idle**, not total: every correlated event resets it, progress included. A job that streams for two minutes will not fail a thirty-second call. Default 30s. |
 | `signal` | An `AbortSignal`, for a real deadline or a cancelled action. |
 | `call.cancel(reason)` | Stops listening and settles. Safe to call twice. |
 
-However a call ends — resolved, timed out, aborted — the subscription is removed and any producer
+However a call ends, whether resolved, timed out or aborted, the subscription is removed and any producer
 parked on backpressure is released. A wedged responder is worse than the unbounded buffer this
 replaced.
 
 ## Reading a value as you subscribe
 
-`connect` starts at "from now on", so a subscriber's first read had to repeat the path elsewhere —
+`connect` starts at "from now on", so a subscriber's first read had to repeat the path elsewhere:
 the same path in two places, free to drift:
 
 ```typescript
@@ -513,14 +537,14 @@ store.connect({ reducer: "orders", property: "status" }, (change) => {
 });
 ```
 
-Provenance is **absent** when no event caused the change — a DevTools time-travel jump, or the
+Provenance is **absent** when no event caused the change: a DevTools time-travel jump, or the
 `immediate` delivery above. Absence is the signal, rather than a fabricated id.
 
 ---
 
 ## Event Deduplication (opt-in)
 
-Deduplication is **off by default** — Yoltra never silently drops legitimate rapid-fire identical
+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
@@ -533,7 +557,7 @@ const store = createStore({
   dedupWindowMs: 100, // default: 0 (disabled)
 });
 
-// Identity-based: dedupe by an explicit key — e.g. a React Strict Mode double-invoke in an effect.
+// 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}` });
 ```
 
@@ -541,8 +565,8 @@ await store.emit("analytics", "pageView", { page }, { dedupKey: `pageView:${page
 
 ## Cascade protection (on by default)
 
-Two consumers wired into each other — a subscriber that emits what its own reducer answers, or
-two slices that answer each other's events — produce an event chain with no end. The reduce queue
+Two consumers wired into each other, whether a subscriber that emits what its own reducer answers or
+two slices that answer each other's events, produce an event chain with no end. The reduce queue
 drains **synchronously**, so that is not a slow program: it is a frozen tab, or a pinned core,
 with no error and no stack to point at.
 
@@ -554,7 +578,7 @@ const store = createStore({
   name: "app",
   reducer: { ... },
 
-  // Defaults to 64. Bounded whether or not you configure it — a failure mode this bad
+  // Defaults to 64. Bounded whether or not you configure it. A failure mode this bad
   // should not require configuration to avoid. Set Infinity to opt out and own it.
   maxReduceDepth: 64,
 
@@ -578,13 +602,13 @@ Both fields are **absent** on a root event rather than present as `0`/`undefined
 application emits stay byte-identical to before this existed.
 
 Breaching does not throw. The offending emit is refused, everything already committed stands, and
-`onCascade` (plus a console error) names it — a throw would surface in whichever subscriber or
+`onCascade` (plus a console error) names it. A throw would surface in whichever subscriber or
 effect happened to be emitting, which is the same unattributable failure the ceiling exists to
 prevent.
 
 **A wide burst is not a cascade.** One event whose subscriber fans out to five hundred siblings
 is a legitimate shape; depth is what separates it from a cycle, and a plain loop of `store.emit`
-never accumulates depth at all — each call drains to completion before the next, so every one is
+never accumulates depth at all, because each call drains to completion before the next, so every one is
 a root. `maxTransitionsPerDrain` bounds burst *width* and is off by default for that reason; the
 event that starts a drain is never refused by it.
 
@@ -605,6 +629,63 @@ const dispose = store.registerReducer("filters", {
 dispose();
 ```
 
+### Decorating a store, with its types
+
+A slice added at runtime used to be invisible to the type system: `registerReducer` took a
+plain `string` and returned a bare disposer, so nothing downstream knew the slice existed or
+what shape it had. `withSlice` returns **the same store, re-typed**:
+
+```typescript
+type TransferEM = { transfer: { granted: { id: string } } };
+
+const transfers = defineSlice<TransferEM>()({
+  state: { granted: [] as string[] },
+  when: { keys: [["transfer", "granted"]] },
+  reducer: (s, e) => (e.type === "granted" ? { granted: [...s.granted, e.payload.id] } : s),
+});
+
+const app = store.withSlice("transfers", transfers, { owner: "@scope/transfers" });
+
+app.getState().transfers.granted; // string[]
+app.emit("transfer", "granted", { id: "a1" }); // the new channel is emittable
+```
+
+`withMiddleware` and `withEffect` do the same for the event map. Calls chain, and a library
+publishes a decorator by taking a store and returning one:
+
+```typescript
+export function withTransfers<R extends string, S extends Record<R, any>, EM extends EventMapBase>(
+  store: StoreInstance<R, S, EM>,
+  config: TransfersConfig,
+) {
+  return store.withSlice("transfers", transfers, { owner: "@scope/transfers" });
+}
+
+// Decorators nest, in any order.
+const decorated = withTransfers(withDevtools(store, dtConfig), config);
+```
+
+**Why the builders.** A spec's `when` carries channel and type strings and no payload types,
+so the event map a decoration contributes cannot be inferred from it, and TypeScript has no
+partial type-argument inference. `defineSlice<EM>()` puts it in a value position, where
+inference works, so no registration site needs a type argument or a cast. One consequence
+worth knowing: **a bare middleware function can never widen the event map**, because
+`MiddlewareFunction`'s event parameter is a mapped type nothing can be inferred back out of.
+Only the spec form from `defineMiddleware` can.
+
+**It is the same object.** Nothing re-subscribes, no state moves, and any in-flight
+`store.call()` is unaffected. Only the type changes.
+
+**Ordering.** Decorate at module scope, once, before the first render. Between `createStore`
+and the decoration the slice genuinely does not exist, and a component reading it sees
+`undefined` until it does.
+
+**Disposal.** `withSlice` hands back no disposer on purpose: after one runs, the widened type
+still promises a slice that is gone, and no type system can express "valid until that call".
+Use `registerSlice` when you own the slice and need teardown, and keep that disposer private
+to the library. Reading a disposed slice throws a named error in development rather than
+returning `undefined` from a type that promised a value.
+
 ---
 
 ## Hot Module Replacement
@@ -633,19 +714,43 @@ if (import.meta.hot) {
 }
 ```
 
+### `replace*` replaces what you authored, not what a library added
+
+A reducer, middleware or effect registered **after** construction, with `registerReducer`,
+`registerMiddleware` or `registerEffect`, survives a `replace*` call. Those registrations were
+never part of the set you are replacing: nobody writing `replaceReducers(myReducers)` means "and
+also delete the slice devtools mounted, along with its state".
+
+This used to go the other way, which made the HMR line above delete a library's slice and its
+state on the first file save, with no error and no warning. It is also why an in-flight
+`store.call()` no longer dies mid-reload: its reply listener belongs to the store itself.
+
+Pass `{ scope: "all" }` for the old wholesale behaviour, which a test harness resetting a store
+between cases may genuinely want:
+
+```typescript
+store.replaceReducers(nextReducers, { scope: "all" });
+store.hotReplace({ reducer: nextReducers, scope: "all" }); // forwards to all three
+```
+
+An application that authors a slice a library already mounted gets an error naming the slice,
+rather than a silent takeover that leaves the library holding a disposer for something no longer
+its own. In development, `replace*` logs at debug level when it preserved anything, so "why is
+that effect still firing after a reload" has an answer.
+
 ---
 
 ## Best Practices
 
 ### State is synchronous; `await` only for effects
 
-The reduce phase is synchronous, so state reflects your event the moment `emit()` returns — no
+The reduce phase is synchronous, so state reflects your event the moment `emit()` returns, with no
 `await` needed to read it back. Await `emit()` when you also want _this event's_ effects to have
 finished:
 
 ```typescript
 emit("todo", "add", todo);
-store.getState(); // Already reflects the new todo — no await required
+store.getState(); // Already reflects the new todo. No await required
 
 await emit("todo", "save", todo); // resolves once save's effects complete
 ```
@@ -694,7 +799,8 @@ store.registerEffect({
 | `store.getState()`                              | Get current readonly state snapshot            |
 | `store.subscribe(listener)`                     | Coarse subscription (any state change)         |
 | `store.connect(spec, handler)`                  | Fine-grained path subscription with wildcards  |
-| `store.onEvent(channel, type, handler, phase?)` | Event subscription (committed/uncommitted/all) |
+| `store.onEvent(channel, type, handler, phase?, options?)` | Event subscription (committed/uncommitted/written/all). Silent during replay unless `{ duringReplay: true }` |
+| `store.onRegistrationChange(observer, opts?)` | Fires when the store gains or loses a reducer, middleware or effect |
 | `store.onEffect(channel, type, handler)`        | Single-event effect shorthand                  |
 | `store.dispose()`                               | Cleanup timers and resources                   |
 
@@ -702,6 +808,10 @@ store.registerEffect({
 
 | API                                 | Description               |
 | ----------------------------------- | ------------------------- |
+| `store.registerSlice(name, spec, opts?)` | Add a slice at runtime; returns the widened store plus a disposer |
+| `store.withSlice(name, spec, opts?)` | Same, returning the widened store for chaining |
+| `store.withMiddleware(mw)`, `store.withEffect(spec)` | Register and widen the event map |
+| `defineSlice<EM>()`, `defineMiddleware<EM>()`, `defineEffect<EM>()` | Declare the event map a spec contributes |
 | `store.registerReducer(name, spec)` | Add a slice at runtime    |
 | `store.registerMiddleware(fn)`      | Add middleware at runtime |
 | `store.registerEffect(spec)`        | Add an effect at runtime  |
@@ -710,10 +820,10 @@ store.registerEffect({
 
 | API                                     | Description                |
 | --------------------------------------- | -------------------------- |
-| `store.replaceReducers(reducers, opts)` | Replace all reducers       |
-| `store.replaceMiddleware(middleware)`   | Replace all middleware     |
-| `store.replaceEffects(effects)`         | Replace all effects        |
-| `store.hotReplace(partial)`             | Replace any subset at once |
+| `store.replaceReducers(reducers, opts)`   | Replace spec reducers; runtime ones survive unless `{ scope: "all" }` |
+| `store.replaceMiddleware(middleware, opts)` | Replace spec middleware; same rule |
+| `store.replaceEffects(effects, opts)`       | Replace spec effects; same rule    |
+| `store.hotReplace(partial)`                 | Replace any subset at once; forwards `scope` |
 
 ### Helpers
 
@@ -749,7 +859,7 @@ that never happened.
 
 **Nothing throws on boot.** A missing, unparseable or unmigratable payload falls back to your
 declared defaults and reports through `onError`. A store that will not start because storage
-holds stale JSON is worse than one that starts fresh — and a full disk should not take down a
+holds stale JSON is worse than one that starts fresh, and a full disk should not take down a
 page, so write failures are reported the same way rather than raised.
 
 **Version mismatches are refused, not trusted.** Reducers change, and a snapshot written
@@ -767,7 +877,7 @@ For a server render, `dehydrate(store, { version })` produces the payload and
 ## Lists that reorder
 
 Path notification is positional for arrays. `items.0.title` names a *slot*, not a thing, so
-`unshift`, `splice(0, 1)` and `sort` move nearly every element into a different slot — and the
+`unshift`, `splice(0, 1)` and `sort` move nearly every element into a different slot, and the
 diff correctly reports that nearly every leaf changed. Inserting one row at the front of a
 thousand wakes a thousand subscribers.
 
@@ -790,7 +900,7 @@ todos.idsPath;                 // "ids"
 `entities.abc.title` survives insert, remove and reorder. A list container subscribes to `ids`
 and reorders its children; rows subscribe to their own entity and stay asleep through a sort.
 
-`ids` is still an array, so a reorder still reports `ids.0`, `ids.1` and so on — that cost is
+`ids` is still an array, so a reorder still reports `ids.0`, `ids.1` and so on. That cost is
 confined, not removed. What you get is cost proportional to what actually changed.
 
 For a small list that only ever grows at the end, `items.0.title` is fine and simpler. The
@@ -803,8 +913,8 @@ normalised, and the array reports roughly a thousand changed paths against two.
 case the adapter is for.
 
 A single-field update runs the other way: 20 µs for the array against 470 µs normalised.
-`detectChangedProps` indexes an array but enumerates an object's keys — building two key
-arrays and a `Set` per comparison — so a wide entity map is more expensive to walk even when
+`detectChangedProps` indexes an array but enumerates an object's keys, building two key
+arrays and a `Set` per comparison, so a wide entity map is more expensive to walk even when
 almost nothing in it moved. The numbers are in `benchmarks/`, and closing that gap is tracked
 work rather than a property of normalising as such.
 
@@ -813,24 +923,33 @@ individual fields edited is better off as an array today.
 
 ## Performance
 
-| Metric             | Value                                     |
-| ------------------ | ----------------------------------------- |
-| **Bundle size**    | 9.2 KB for the store (minified + gzipped) |
-| **Tree-shakeable** | Yes (ES modules)                          |
-| **Dependencies**   | Zero                                      |
-| **TypeScript**     | Full type definitions included            |
+| Metric             | Value                                  |
+| ------------------ | -------------------------------------- |
+| **Bundle size**    | Measured every build, see table below |
+| **Tree-shakeable** | Yes (ES modules)                       |
+| **Dependencies**   | Zero                                   |
+| **TypeScript**     | Full type definitions included         |
 
 Bundle size is checked, not asserted: `rush size` bundles the package the way a consumer
-would — tree-shaken, minified, gzipped — and fails when it exceeds the budget declared in
-`package.json`.
+would (tree-shaken, minified, gzipped) and fails when it exceeds the budget declared in
+`package.json`. The table below is written by that same check, so it cannot drift from what
+was measured; editing it by hand fails CI.
 
 The number that matters is what you import, not what the package exports:
 
-| Import                              | Size    | Budget |
-| ----------------------------------- | ------- | ------ |
-| `{ createStore }`                   | 9.2 KB  | 14 KB  |
-| `{ createStore, hydrate, persist }` | 10.7 KB | 16 KB  |
-| everything                          | 12.1 KB | 18 KB  |
+<!-- size-table:start -->
+| Import | Size | Budget |
+| --- | --- | --- |
+| `{ createStore }` | 11.5 KB | 14 KB |
+| `{ createStore, hydrate, persist }` | 12.8 KB | 16 KB |
+| everything | 14.2 KB | 18 KB |
+<!-- size-table:end -->
+
+These are **production** figures: what you ship once your bundler defines
+`NODE_ENV=production` and the development-only guards drop out. The budget column is the
+ceiling `rush size` enforces, and it is checked against a development build instead, which is
+the larger of the two: dev-only code cannot grow unnoticed just because it never reaches a
+user. So the headroom implied here is deliberately conservative.
 
 The **gap between rows** is the tree-shaking claim, and it is what to watch: persistence adds
 1.5 KB to the people who import it and nothing to anyone else, and the whole barrel is 2.9 KB
@@ -846,27 +965,31 @@ stops a runaway from hanging the tab.
 
 ## Documentation
 
-- **[yoltra Root README](../../README.md)** — Overview and
+- **[yoltra Root README](../../README.md)**: Overview and
   quick start
-- **[@yoltra/react](../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
-- **[Event Queue Architecture](https://github.com/yoltra/yoltra/blob/main/docs/en/design/event-queue-architecture.md)**
-  — Technical deep-dive
-- **[Library Comparison](https://github.com/yoltra/yoltra/blob/main/docs/en/design/state-management-library-comparison.md)**
-  — Architectural comparison
+- **[Quick Start Guide](https://github.com/yoltra/yoltra/blob/main/docs/en/QUICK_START_GUIDE.md)**:
+  Five steps to a working app
+- **[Upgrading to 0.8.0](https://github.com/yoltra/yoltra/blob/main/docs/en/UPGRADE_0.8.md)**:
+  Five behaviour changes, and one hazard if you roll back
+- **[Decoration Guide](https://github.com/yoltra/yoltra/blob/main/docs/en/DECORATION_GUIDE.md)**:
+  Adding a slice, middleware or effect to somebody else's store, with the types
+- **[Event Queue Architecture](https://github.com/yoltra/yoltra/blob/main/docs/en/design/event-queue-architecture.md)**:
+  Technical deep-dive
+- **[Library Comparison](https://github.com/yoltra/yoltra/blob/main/docs/en/design/state-management-library-comparison.md)**:
+  Architectural comparison
 
 ---
 
 ## Examples
 
-- **[Todo App](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-react)** — Full
+- **[Todo App](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-react)**: Full
   CRUD with performance profiling · [▶ Open the live demo](https://yoltra.dev/en/demos/in-react)
-- **[Kinetic Logo](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-kinetic-logo)**
-  — 3000 circles with physics simulation · [▶ Open the live demo](https://yoltra.dev/en/demos/kinetic-logo)
-- **[Next.js Integration](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-nextjs)**
-  — Pages Router, client-side state + theme switcher · [▶ Open the live demo](https://yoltra.dev/en/demos/in-nextjs)
+- **[Kinetic Logo](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-kinetic-logo)**:
+  3000 circles with physics simulation · [▶ Open the live demo](https://yoltra.dev/en/demos/kinetic-logo)
+- **[Next.js Integration](https://github.com/yoltra/yoltra/blob/main/examples/v0/yoltra-in-nextjs)**:
+  Pages Router, client-side state + theme switcher · [▶ Open the live demo](https://yoltra.dev/en/demos/in-nextjs)
 
 ---
 
@@ -879,10 +1002,10 @@ stops a runaway from hanging the tab.
 
 ## Status
 
-**Release Candidate** — APIs are stable, used in production, minor changes possible before v1.0.
+**Release Candidate**. APIs are stable, used in production, minor changes possible before v1.0.
 
 ---
 
 ## License
 
-**MIT** — Free to use in commercial and open-source projects.
+**MIT**. Free to use in commercial and open-source projects.

package/dist/types/index.d.ts

@@ -17,7 +17,8 @@ export { detectChangedProps } from './utils/detectChangedProps.js';
 export { freezeState } from './utils/immutability.js';
 export type { AliasWatch } from './utils/immutability.js';
 export { eventKeys } from './types.js';
-export type { EventMapBase, EventKey, Event, EventUnion, Change, Emit, EmitOptions, EmitResult, ConnectOptions, EventMeta, InstrumentedEvent, CascadeInfo, InstrumentationObserver, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, ReducersMapAny, StateFromReducers, EMFromReducersStrict, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, RootValue, Path, PathValue, WithGlob, Dotted, EventPhase, NotifiedPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types.js';
+export { defineSlice, defineMiddleware, defineEffect } from './types.js';
+export type { Prettify, Merge, WidenNames, WidenState, EventMapCarrier, EMAddOf, Decoration, Decorated, StoreDecorator, Origin, RegistrationChange, RegistrationObserver, ReplaceScope, EmptyEventMap, NotCommittedReason, StateOfSpec, SatisfiesSlices, DecoratableStore, WidenedSlice, StoreDecoration, EventMapBase, EventKey, Event, EventUnion, Change, Emit, EmitOptions, EmitResult, ConnectOptions, EventMeta, InstrumentedEvent, CascadeInfo, InstrumentationObserver, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, ReducersMapAny, StateFromReducers, EMFromReducersStrict, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, RootValue, Path, PathValue, WithGlob, Dotted, EventPhase, NotifiedPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types.js';
 export { createEntityAdapter } from './entity/entityAdapter.js';
 export type { EntityAdapter, EntityAdapterOptions, EntityId, EntityState, EntityUpdate, } from './entity/entityAdapter.js';
 export { decodeState, encodeState, encodeStateBounded } from './serialize/codec.js';

package/dist/types/persistence/persist.d.ts

@@ -20,7 +20,7 @@ export interface PersistenceAdapter {
     remove(key: string): void | Promise<void>;
 }
 /** Where a failure happened, so a handler can tell a bad write from a bad payload. */
-export type PersistencePhase = "read" | "write" | "decode" | "migrate";
+export type PersistencePhase = "read" | "write" | "decode" | "migrate" | "encode";
 /** Shared configuration. */
 export interface PersistOptions {
     /** Storage key. */
@@ -120,4 +120,4 @@ export declare function persist(store: PersistableStore, options: PersistOptions
  *
  * @public
  */
-export declare function dehydrate(store: Pick<PersistableStore, "getState">, options: Pick<PersistOptions, "version" | "slices">): string;
+export declare function dehydrate(store: Pick<PersistableStore, "getState">, options: Pick<PersistOptions, "version" | "slices" | "onError">): string;