memorio 4.9.35 → 5.0.0

package/SECURITY.md

@@ -34,7 +34,23 @@ Addresses OWASP Top 10 (2021):
 - A09:2021 - Security Logging and Monitoring Failures (DevTools inspect, Logger module)
 - A10:2021 - Server-Side Request Forgery (N/A - no network requests)
 
-## Reporting Security Issues
+## Global API Security
+
+Memorio does **not** expose its APIs on `globalThis` by default. The opt-in
+entrypoint `import 'memorio/global'` installs `state`, `store`, `session`,
+`cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis`.
+This is an explicit consumer choice - not inferred from `NODE_ENV` or
+bundler environment variables.
+
+For application code, prefer explicit named imports:
+
+```js
+import { state } from 'memorio'
+```
+
+See [SECURITY-HARDENING.md](./SECURITY-HARDENING.md) for a full hardening
+guide covering storage encryption, context isolation, logger data capture,
+and platform capability assumptions.
 
 If you find a security vulnerability:
 

package/SUMMARY.md

@@ -1,45 +1,59 @@
-# Table of contents
-
-* [README](README.md)
-
-## Core Modules
-
-* [State](markdown/STATE.md) - Reactive global state management
-* [Observer](markdown/OBSERVER.md) - Object observation pattern
-* [useObserver](markdown/USEOBSERVER.md) - React hook for state observation
-* [Dispatch](markdown/DISPATCH.md) - Event system for vanilla JS applications
-* [Cache](markdown/CACHE.md) - In-memory caching (lost on refresh)
-* [Store](markdown/STORE.md) - Persistent localStorage management
-* [Session](markdown/SESSION.md) - Temporary sessionStorage management
-* [IDB](markdown/IDB.md) - IndexedDB for large data storage
-* [SQLite](markdown/SQLITE.md) - SQLite in the browser via sql.js (WASM)
-
-## Typed & Validated
-
-* [Typed Stores](markdown/TYPED.md) - Compile-time type safety for state access
-* [Schema Validation](markdown/SCHEMA.md) - Runtime validation of state mutations
-
-## History & Introspection
-
-* [History](markdown/HISTORY.md) - Snapshot, diff, undo/redo, trace
-* [Introspection](markdown/INSPECT.md) - stateKeys, pathExists, stateType, stateSchema
-
-## Memory System
-
-* [Memory](markdown/MEMORY.md) - Semantic memory layer with TTL, confidence, scopes
-* [Node Attachment](markdown/MEMORY-ATTACHMENT.md) - Dynamic node attachment system
-* [Synchronization](markdown/SYNC.md) - Local-first sync, journal, conflict resolution, multi-device evolution
-
-## Platform & Compatibility
-
-* [Platform & Context Isolation](markdown/PLATFORM.md) - Cross-platform support, session isolation
-* [Security](markdown/SECURITY.md) - Security measures, vulnerability prevention
-* [Changelog](markdown/CHANGELOG.md) - Version history and migration guide
-* [Classic Import](markdown/IMPORT.md) - Named export guide for `import { state } from 'memorio'`
-
-## Additional Resources
-
-* [License](../LICENSE.md)
-* [Contributing](../CONTRIBUTING.md)
-* [Code of Conduct](../CODE_OF_CONDUCT.md)
-* [Security](../SECURITY.md)
+# Riepilogo dei file - memorio examples & markdown
+
+## 📁 examples/ (20 file)
+
+| File | Cosa mostra |
+|---|---|
+| `basic.ts` | Tour introduttivo: platform detection, `state`, `store`, `session` in un unico script. |
+| `cache.ts` | Uso base della cache in-memory: set/get, oggetti complessi, cleanup. |
+| `cross-platform-guards.ts` | Come usare `getCapabilities()` invece di `isBrowser()`/`isNode()` per gestire in modo esplicito gli ambienti dove `store`/`session`/`idb` non sono durevoli. |
+| `history.ts` *(nuovo)* | State Intelligence: `snapshot()`/`diff()`/`rollback()` per il pattern "prova → ispeziona → conferma o annulla", undo/redo passo-passo, trace log con export/replay. |
+| `idb.ts` | CRUD completo su IndexedDB: database, tabelle, record, info (size/version/exist). |
+| `multi-tenant-context.ts` | Isolamento dati per richiesta/tenant con `memorio.createContext()` in un handler server-side, incluso cleanup. |
+| `node-server.ts` | Memorio lato server: cache in-memory, fallback di `store`/`session`, contesti multi-tenant, più snippet commentati (Express, WebSocket, job queue, CLI). |
+| `observer.ts` | Pattern observer: singolo valore, oggetti interi, più observer sullo stesso path, cleanup. |
+| `platform.ts` | Platform detection dettagliata + isolamento contesti per server multi-tenant, con verifica esplicita dell'isolamento tra due utenti. |
+| `react-app.tsx` | App React completa (header, profilo, cart, notifiche, settings, login/logout) costruita solo su `state`/`store`/`useObserver`. |
+| `react-observer.tsx` | `useObserver` in due modalità (auto-discovery vs deps espliciti) combinato con `typed<T>()` e `registerSchema()`. |
+| `semantic-memory.ts` | Memoria applicativa per un'app LLM-backed: remember/update con confidence e source, retrieval con `memory.context()` - con nota esplicita che non è ricerca semantica per embedding. |
+| `session-advanced.ts` | Uso avanzato di `session`: auth token, bozza di form, carrello, dimensione dello storage. |
+| `sqlite-batched-writes.ts` | Come evitare di serializzare l'intero DB SQLite ad ogni riga: batch di insert seguito da un solo flush. |
+| `state-advanced.ts` | Stato annidato, array, locking di un valore (`.lock()`), path tracking, rimozione stato. |
+| `store-advanced.ts` | `store` avanzato: persistenza, quota, alias dei metodi, gestione errori, serializzazione di vari tipi. |
+| `sync.ts` *(nuovo)* | Local-first sync: configurazione di un `SyncProvider` (push/pull/resolve), scope `device`/`user`/`shared`, ispezione e replay del journal. |
+| `typed-and-schema.ts` | Tutti gli snippet di `TYPED.md` e `SCHEMA.md` in un unico file TypeScript funzionante: typed state + validazione runtime combinati. |
+| `useObserver.tsx` | Guida step-by-step all'hook `useObserver`: dipendenza singola, multiple, auto-discovery, sync con `useState`, mini to-do app. |
+| `browser-vanilla.html` | Demo HTML/JS pura (nessun bundler) con UI per state, store, session, cache, observer e platform info. |
+
+## 📁 markdown/ (24 file)
+
+| File | Cosa documenta |
+|---|---|
+| `AUDIT-REPORT.md` | Audit di sicurezza/performance/affidabilità/qualità del codice per la v4.9.5 (datato 2026-09-06), con azioni correttive già applicate. |
+| `CACHE.md` | Reference della cache in-memory: API, quando usarla, limiti. |
+| `CHANGELOG.md` | Storico versioni dalla v2.5.0 alla `Unreleased`, con bugfix, refactoring e note di sicurezza per ogni release. |
+| `DEVTOOLS.md` | Strumenti di debug da console del browser per ispezionare/gestire lo stato di Memorio. |
+| `DISPATCH.md` | Sistema di eventi pub/sub per app vanilla JS (alternativa a `useObserver` fuori da React). |
+| `HISTORY.md` | Reference completa di time-travel: enable/snapshot/diff/undo/redo/rollback/trace, con "how it works" e best practice. |
+| `IDB.md` | Reference IndexedDB: creazione DB/tabelle, CRUD, info sul database. |
+| `IMPORT.md` | I due stili di import (named vs `memorio/global`) e perché condividono la stessa istanza. |
+| `INSPECT.md` | Utility di introspezione per scoprire/verificare la forma dello `state` a runtime - utile per agenti AI. |
+| `LOGGER.md` | Middleware di logging automatico per tracciare le modifiche di stato in console. |
+| `MEMORY-ATTACHMENT.md` | Sistema di "attachment" tra elementi di memoria - estensione opzionale della memoria semantica. |
+| `MEMORY.md` | Reference del layer di memoria semantica: remember/update/context, TTL, confidence, tag, scope. |
+| `OBSERVER.md` | Reference del pattern observer per reagire ai cambi di stato. |
+| `PLATFORM.md` | Platform detection + sistema di context isolation per applicazioni multi-tenant server-side. |
+| `PROJECT.md` | Scheda di progetto interna: versione, team, moduli inclusi, stack tecnologico, target. |
+| `SCHEMA.md` | Validazione runtime dei percorsi di stato: schema oggetto/array/enum/funzione custom. |
+| `SECURITY.md` | Postura di sicurezza del progetto (minacce coperte, cosa NON fa Memorio, come viene gestito l'accesso ai dati). |
+| `SESSION.md` | Reference di `session` (sessionStorage) con fallback in-memory fuori dal browser. |
+| `SQLITE.md` | Reference del layer SQLite via `sql.js`: caricamento lazy, persistenza, query. |
+| `STATE.md` | Reference dello stato reattivo basato su Proxy - il layer centrale di Memorio. |
+| `STORE.md` | Reference di `store` (localStorage) con fallback in-memory fuori dal browser. |
+| `SYNC.md` | Sincronizzazione local-first opzionale: scope, journal, conflict resolution, strategie avanzate per multi-device (HLC, tombstones, fractional indexing). |
+| `TYPED.md` | `memorio.typed<T>()` per la sicurezza dei tipi a compile-time sullo stesso proxy di `state`. |
+| `USEOBSERVER.md` | Reference dell'hook React `useObserver`: modalità auto-discovery vs deps espliciti, tutte le forme di `deps` supportate. |
+
+---
+
+**Nota di copertura:** ogni doc in `markdown/` ha ora almeno un esempio corrispondente in `examples/`, **tranne** `DEVTOOLS.md`, `DISPATCH.md`, `INSPECT.md`, `LOGGER.md` e `MEMORY-ATTACHMENT.md` - utile saperlo se in futuro vuoi completare anche quelli.

package/adr/001-state-proxy-model.md

@@ -0,0 +1,96 @@
+# ADR-001: State Proxy Model
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+Memorio's reactive state is built on a JavaScript `Proxy`. Every read of
+a nested object re-wraps the child in a Proxy so that deep
+`set`/`delete` traps fire and dispatch events. The design must answer:
+
+- How are proxy wrappers cached to avoid exponential allocation on
+  repeated reads?
+- What is the reference-identity contract between the proxy and the
+  raw target?
+- Which property names are reserved and cannot be used as state keys?
+- How are non-plain objects (Date, Set, Map, functions) handled?
+
+## Assumptions
+
+- The Proxy target is always a plain `Object` or `Array`.
+- A single `buildProxy` invocation creates one Proxy per raw object.
+- The Proxy is shared across all import paths via `globalThis`
+  singletons (see ADR-006).
+- `__DEV__` is a build-time constant (replaced to `false` in
+  production, `true` in dev/test).
+
+## Decision
+
+### Wrapper caching
+
+`buildProxy` caches the wrapper in a `WeakMap<rawTarget, proxyWrapper>`.
+On every `get` trap, after unwrapping with `TARGET`, the result is looked
+up in the cache; if present, the existing wrapper is returned instead of
+allocating a new one. This keeps repeated nested reads at O(1) in
+allocation and O(1) in proxy depth.
+
+### Reference identity
+
+- `TARGET` is a `Symbol` accessor on the proxy that returns the raw
+  underlying target. `state[TARGET]` === raw root.
+- `state.a[TARGET]` === raw target's `a` property.
+- `JSON.stringify(proxy)` works because `ownKeys` and
+  `getOwnPropertyDescriptor` delegate to `Reflect`.
+- `deepRaw(value)` unwraps all Memorio proxies recursively using
+  `TARGET` and a `WeakSet` for cycle safety, returning a plain clone
+  with no wrapper references.
+
+### Reserved property names
+
+`protect` array in `core/internal.ts` reserves these keys on the root
+`state` proxy:
+
+```
+list, state, store, idb, cache, sqlite, observer, useObserver,
+remove, removeAll, _platform, _capabilities, _sessionId
+```
+
+Setting any of these keys as state data is rejected by the `set` trap
+with a console error. Attempting to set any `_`-prefixed key that
+collides with internal bookkeeping is also guarded.
+
+### Non-plain objects
+
+- `Date`, `Set`, `Map`, `RegExp`, functions, and other non-plain
+  instances are returned by reference — they are **not** re-wrapped in a
+  Proxy.
+- `deepRaw` only traverses `Object` and `Array` constructors; all other
+  types are returned by reference.
+
+### Path tracking
+
+Every `get` trap for a string property sets `internal.lastAccessedPath`
+to the full dotted path (`state.foo.bar`). When
+`internal.tracking` is true, the path is also added to
+`internal.trackedPaths`.
+
+## Consequences
+
+- **Positive:** O(1) wrapper allocation on repeated nested reads; no
+  proxy-depth accumulation on spread updates (regression tested).
+- **Positive:** `TARGET` symbol prevents prototype-pollution attacks
+  via `__proto__`/`constructor`/`prototype` because those are string
+  keys that are simply treated as data keys on the raw target.
+- **Positive:** `deepRaw` produces clean data for persistence and
+  snapshots without leaking proxy wrappers.
+- **Negative:** The `WeakMap` cache is per-module-instance, but since
+  the proxy target is a singleton on `globalThis`, the cache is
+  effectively shared across import paths.
+- **Negative:** Non-plain objects cannot be deeply observed for inner
+  mutations — this is an accepted limitation documented in the API.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-001-state.test.ts`

package/adr/002-observer-semantics.md

@@ -0,0 +1,180 @@
+# ADR-002: Observer Semantics
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+Memorio must freeze observer behavior so that developers can reason
+about *when* and *why* their callbacks fire. The observer system is the
+bridge between state mutations and UI updates, between the Mutation
+Engine and the reactive system. Before adding advanced features (impact
+analysis, simulation, causal graph), the observer contract must be
+explicit and deterministic.
+
+The following questions must have explicit answers:
+
+1. Does a deep mutation notify the leaf observer?
+2. Does a deep mutation notify parent observers?
+3. What happens for array mutations?
+4. What is the reference identity contract for observer callbacks?
+5. Are notifications synchronous or asynchronous?
+6. Are multiple mutations batched into a single notification?
+7. What is the ordering guarantee when multiple observers listen to
+   overlapping paths?
+8. Can an observer mutate state synchronously?
+9. What happens when an observer throws?
+10. What happens when an observer is removed during dispatch?
+11. How are nested transactions handled with respect to observer
+    notification?
+
+## Assumptions
+
+- The state Proxy fires exactly one callback per `set` or `delete`
+  trap (no double-firing for the same logical mutation).
+- The dispatch layer (`core/dispatch.ts`) is the sole event bus.
+- `useObserver` is a thin wrapper over `observer` + `dispatch.listen`.
+- History tracking is opt-in (`enableHistory(true)`).
+
+## Decision
+
+### 1. Leaf notification
+
+A mutation at path `state.user.profile.name` dispatches an event on
+exactly the path `state.user.profile.name`. Only observers registered
+on that exact path receive the notification. Observers on ancestor
+paths (`state.user.profile`, `state.user`, `state`) do **not** fire for
+a leaf mutation unless the mutation replaces the ancestor itself.
+
+```js
+observer('state.user.profile.name', cb)   // fires
+observer('state.user.profile', cb)       // does NOT fire
+observer('state.user', cb)               // does NOT fire
+```
+
+This is the **exact-path observer** model. It is intentional:
+coarse-grained ancestor notification is handled by `useObserver`'s
+auto-discovery mode (which explicitly registers on each accessed path),
+not by event bubbling.
+
+### 2. Deep mutation notification
+
+When `state.user.profile.name = "Alice"` executes, the set trap fires
+on the `name` property of the `profile` proxy. The callback receives
+`{ path: 'user.profile.name', ... }`. The event dispatched is
+`state.user.profile.name`. Only the leaf observer fires.
+
+### 3. Array mutations
+
+Array mutations at index `i` dispatch on the **array path**
+(`state.items`), not the index path. This is because array identity
+matters for UI reconciliation (React list rendering).
+
+```js
+state.items.push(3)  // dispatches 'state.items'
+state.items[0] = 99  // dispatches 'state.items'
+state.items.sort()   // dispatches 'state.items'
+```
+
+### 4. Reference identity
+
+Observer callbacks receive the event object. The callback function
+itself is stored by reference in the dispatch layer. Re-registering the
+same function on the same path replaces the old listener (single-slot
+behavior in `observer`, multi-subscriber in `dispatch.listen`).
+
+`useObserver` deduplicates identical path registrations.
+
+### 5. Synchronous vs asynchronous
+
+- **Event dispatch** (`dispatch.set`) is **synchronous** —
+  `globalThis.dispatchEvent` runs listeners inline.
+- **Callback notification** via `dispatch.listen` is **asynchronous**
+  — wrapped in `queueMicrotask(cb)` (or `Promise.resolve().then(cb)`
+  as fallback). This ensures that by the time the callback fires, the
+  state Proxy has already committed the mutation.
+
+This means:
+
+```js
+state.counter = 1
+// state.counter === 1 is TRUE here (mutation already committed)
+// observer callback hasn't run yet (next microtask)
+```
+
+### 6. Batching
+
+There is **no automatic batching** of observer callbacks. Each mutation
+dispatches its own microtask. Multiple synchronous mutations in a
+transaction produce multiple notifications — one per mutation.
+
+A future scheduler (ADR-005) may introduce microtask/raf batching for
+UI frameworks, but the core engine does not coalesce notifications.
+
+### 7. Ordering guarantee
+
+When multiple observers listen to the same path, they fire in
+**registration order** (FIFO). The dispatch layer maintains a list of
+handlers per event name.
+
+When multiple mutations occur synchronously (without history), they
+dispatch in mutation order. When history is enabled, the undo/redo
+stack preserves mutation order via array index.
+
+### 8. Observer mutating state
+
+An observer callback **may** mutate state. Because notifications are
+asynchronous (microtask), the mutation triggers a new dispatch cycle
+with its own microtask. There is no immediate re-entrancy. However,
+deeply recursive state mutations from observers are considered a
+application-level bug and are **not** guarded at the engine level.
+
+### 9. Observer throwing
+
+If an observer callback throws, the error propagates as an unhandled
+rejection (since the callback runs inside a microtask). The dispatch
+layer does **not** catch or swallow errors. A throwing observer does
+not prevent other observers on the same path from firing (each
+callback is wrapped in its own microtask boundary via
+`Promise.resolve().then`).
+
+### 10. Observer removed during dispatch
+
+Since dispatch is asynchronous (microtask), calling
+`dispatch.remove(path)` or `observer.remove(path)` during a callback
+removes the listener from subsequent dispatches. The current dispatch
+cycle is unaffected — all handlers registered at dispatch time fire.
+
+### 11. Transactions and observer notification
+
+During a transaction, each mutation inside the transaction dispatches
+normally. The transaction grouping does not suppress notifications.
+However, `undo()` and `redo()` temporarily disable history recording
+(via `internal.historyEnabled = false`), and the inverse/forward
+operations fire the proxy callback — which will dispatch to observers.
+
+A future enhancement may batch observer notifications for all mutations
+within a transaction into a single synthetic notification. This ADR
+does **not** define that behavior yet.
+
+## Consequences
+
+- **Positive:** Deterministic, FIFO-ordered, asynchronous notification
+  gives observers a consistent view of state on every call.
+- **Positive:** Microtask scheduling avoids "state not yet committed"
+  bugs that plague synchronous observer models.
+- **Positive:** Exact-path matching means observers fire only when the
+  specific watched path changes — no spurious re-renders.
+- **Positive:** No batching in the core engine keeps it simple and
+  framework-agnostic. Batching is a scheduler-layer concern.
+- **Negative:** Multiple synchronous mutations produce multiple
+  microtask notifications — consumers that need coalescing must
+  implement it (or use the future scheduler).
+- **Negative:** Throwing observers produce unhandled rejections rather
+  than being caught — this is intentional (fail fast) but may surprise
+  consumers expecting error isolation.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-002-observer.test.ts`

package/adr/003-deep-mutation-semantics.md

@@ -0,0 +1,129 @@
+# ADR-003: Deep Mutation Semantics
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+Deep mutations (e.g. `state.user.profile.name = "Alice"`) are the most
+common source of subtle bugs in proxy-based state libraries. The
+4.7.3 baseline had forensic defects around deep mutation notifications:
+observers not firing, paths not resolved correctly, payloads missing
+arguments. While these defects were reported as not reproducible in
+repo v4.9.10, the semantics remain **undocumented** — they rely on
+accidental Proxy behavior rather than an explicit contract.
+
+This ADR makes the deep mutation semantics explicit.
+
+## Assumptions
+
+- `buildProxy` recursively wraps nested plain objects and arrays.
+- Each Proxy tracks its dotted path via the `tree` array.
+- The set trap computes `path = objPath(key, tree)` — a dotted path
+  relative to `state` (e.g. `user.profile.name`).
+- The callback receives `{ action, path, newValue, previousValue }`.
+- The proxy stores **raw** values (via `deepRaw`) on the raw target.
+
+## Decision
+
+### Deep mutation notification scope
+
+When `state.user.profile.name = "Alice"` executes:
+
+1. The set trap on the deepest proxy (the `profile` object) fires.
+2. `path` is computed as `user.profile.name` (relative to `state`).
+3. The callback receives `{ path: "user.profile.name", ... }`.
+4. `dispatch.set("state.user.profile.name", ...)` is called.
+5. **Only** observers on `state.user.profile.name` fire.
+6. `state.user.profile.name` is updated on the raw target to `"Alice"`.
+
+Observers on `state.user.profile`, `state.user`, or `state` do **not**
+receive a notification for this mutation. This is the exact-path
+contract (see ADR-002, §1).
+
+### Reference identity after deep mutation
+
+After `state.user.profile.name = "Alice"`:
+- `state.user` returns the **same** proxy wrapper (cached via WeakMap).
+- `state.user.profile` returns the **same** proxy wrapper.
+- `state.user.profile.name` returns `"Alice"` (the new primitive).
+- `state.user.profile[TARGET]` returns the same raw object as before
+  (the object was mutated in place, not replaced).
+
+### Intermediate object creation
+
+If a deep path does not exist yet (`state.user.profile` is undefined),
+and a consumer writes `state.user.profile = { name: "Alice" }`:
+1. The set trap on `user` fires with `path = "user.profile"`.
+2. The full object `{ name: "Alice" }` is stored as the raw value.
+3. A new proxy wrapper is created for `{ name: "Alice" }` on the next
+   read.
+4. The event dispatched is `state.user.profile` — **not**
+   `state.user.profile.name`.
+
+There is **no automatic intermediate object creation** during deep
+assignment to nested proxies. If `state.user` is undefined and the
+consumer writes `state.user.profile.name = "Alice"`, this throws a
+TypeError (cannot set property 'profile' of undefined).
+
+To set deeply nested values that don't exist yet, use
+`memorio.mutate("state.user.profile.name", "Alice")` which creates
+intermediate objects programmatically.
+
+### No-op mutations
+
+If a set trap assigns the same value (`state.x = state.x`), the set
+trap still fires. The callback still dispatches the event. However,
+the `mutationToPatch` function returns `null` for `before === after`,
+so no patch is stored in the commit log. The undo/redo stack records
+the mutation (with `before === after`), but undo is a no-op for such
+entries.
+
+A future enhancement may add value-comparison in the set trap to skip
+no-op dispatches. This ADR does **not** implement that.
+
+### Delete semantics
+
+`delete state.user.profile.name`:
+1. The `deleteProperty` trap on the `profile` proxy fires.
+2. `path` is computed as `user.profile.name`.
+3. The callback receives `{ action: "delete", path, previousValue }`.
+4. The event dispatched is `state.user.profile.name`.
+5. The property is removed from the raw target.
+
+### Array deep mutation
+
+When a nested object inside an array is mutated (`state.items[0].name = "X"`):
+1. The set trap fires on the proxy wrapping `items[0]`.
+2. `path` is computed as `items.0.name` (array index joined by dots).
+3. The event dispatched is `state.items.0.name`.
+4. **Additionally**, because arrays use identity-based reconciliation,
+   the observer contract (ADR-002 §3) states that array observers fire
+   on the **array path** (`state.items`), not the element path. However,
+   the dispatch only fires `state.items.0.name`. Array observers
+   registered via `observer('state.items', ...)` will **not** fire for
+   `items[0].name` mutations.
+
+> **Note:** This is a known limitation. Array element mutations that
+> change object properties do not notify the array-path observer.
+> A future scheduler or mutation engine enhancement may address this
+> by dispatching on both `state.items.0.name` and `state.items`.
+> This ADR documents the current behavior.
+
+## Consequences
+
+- **Positive:** Deep mutations are deterministic — exactly one event
+  per mutation, on the exact leaf path.
+- **Positive:** Reference identity is preserved — the same proxy wrapper
+  is reused, preventing proxy-depth accumulation (regression tested).
+- **Positive:** `memorio.mutate()` provides a safe path-based API for
+  setting deeply nested values that don't exist yet.
+- **Negative:** Array element object mutations don't notify array-path
+  observers — consumers must observe the specific element path.
+- **Negative:** No-op set traps still dispatch events — this is
+  intentional for consistency but may cause unnecessary re-renders.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-003-deep-mutation.test.ts`

package/adr/004-array-mutation-semantics.md

@@ -0,0 +1,128 @@
+# ADR-004: Array Mutation Semantics
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+Arrays are the most error-prone data structure in proxy-based state
+libraries. The 4.7.3 baseline handled `push` and `pop` but had no
+explicit contract for `sort`, `splice`, `shift`, `unshift`, `fill`,
+`reverse`, `length` changes, or whole-array replacement. Section 9 of
+the Memorio 5.x plan demands explicit, regression-tested behavior for
+every array operation.
+
+A mutation that persists but does not notify, or notifies but does not
+persist, is considered a **semantic defect** unless explicitly
+documented.
+
+## Assumptions
+
+- Arrays are plain JS arrays stored on the Proxy raw target.
+- Array methods (`push`, `pop`, `splice`, etc.) mutate the array in
+  place and trigger the set trap on the Proxy wrapping the array.
+- The set trap's `key` for array mutations is the array index or
+  `length`.
+- The callback receives `{ action, path, newValue, previousValue }`.
+- The state Proxy dispatches via `dispatch.set("state." + path)`.
+
+## Decision
+
+### Mutation → Persistence mapping
+
+Every array operation below **must** persist to the underlying raw
+array and **must** dispatch an event on the **array path**
+(`state.<arrayPath>`), not on the individual index path. The event
+path is computed from the Proxy `tree` (e.g. for `state.items`, the
+tree is `["items"]`, so the path is `items` and the event is
+`state.items`).
+
+| Operation | Persists? | Dispatches on | Patch op |
+|-----------|-----------|---------------|----------|
+| `state.arr[i] = val` | Yes | `state.arr` | `replace` (index i) |
+| `state.arr.push(val)` | Yes | `state.arr` | `add` (at index `arr.length`) |
+| `state.arr.pop()` | Yes | `state.arr` | `remove` (last index) |
+| `state.arr.shift()` | Yes | `state.arr` | `remove` (index 0) |
+| `state.arr.unshift(val)` | Yes | `state.arr` | `add` (at index 0) |
+| `state.arr.splice(i, n, ...items)` | Yes | `state.arr` | `remove` + `add` |
+| `state.arr.sort()` | Yes | `state.arr` | `replace` (whole array) |
+| `state.arr.reverse()` | Yes | `state.arr` | `replace` (whole array) |
+| `state.arr.fill(val, start, end)` | Yes | `state.arr` | `replace` (whole array) |
+| `state.arr.length = n` (truncate) | Yes | `state.arr` | `remove` (removed indices) |
+| `state.arr.length = n` (extend) | Yes | `state.arr` | `add` (new indices) |
+| `state.arr = newArray` | Yes | `state.arr` | `replace` (whole array) |
+| `state.arr[i].prop = val` | Yes | `state.arr.i.prop` | `replace` (leaf) |
+
+### sort() persistence
+
+`sort()` mutates the array in place and returns a reference to the same
+(sorted) array. The Proxy set trap fires because `length` changes and
+indices are reassigned. The event dispatched is `state.arr`. The
+mutation is **persisted** to the raw target.
+
+**Known constraint:** `sort()` with a custom comparator must also
+persist correctly. The comparator function is applied by V8's native
+`Array.prototype.sort`; the Proxy only sees the resulting index
+reassignments.
+
+### splice() semantics
+
+`splice()` can add, remove, or replace elements at an index. The Proxy
+sees multiple set/delete traps. The event dispatched is `state.arr`
+(the first trap fires, and subsequent traps on the same array path
+are de-duplicated by the dispatch layer's microtask scheduling).
+
+### length changes
+
+Setting `arr.length = n` where `n < arr.length` truncates the array.
+The deleteProperty trap fires for each removed index. Setting
+`arr.length = n` where `n > arr.length` extends the array with
+`undefined` holes; the set trap fires for `length`.
+
+### Whole-array replacement
+
+`state.arr = [1, 2, 3]` replaces the entire array. The set trap fires
+once with `path = "arr"`, `newValue = [1, 2, 3]` (deepRaw'd). The
+event dispatched is `state.arr`. Observers on `state.arr` fire.
+Previous array observers (on the old array instance) are orphaned —
+the consumer must re-register if they observe specific indices.
+
+### Array element object mutation
+
+`state.arr[0].name = "X"` mutates an object inside the array. This
+fires the set trap on the Proxy wrapping `arr[0]` with
+`path = "arr.0.name"`. The event dispatched is `state.arr.0.name`.
+
+Per ADR-003, this does **not** notify observers on `state.arr`. This
+is a known limitation. Consumers who need to observe changes to
+objects within arrays must observe the specific element path
+(`state.arr.0.name`) or use `useObserver` auto-discovery.
+
+### Event deduplication
+
+Because a single array operation (e.g. `splice`) can produce multiple
+set/delete traps, the dispatch layer may fire `state.arr` multiple
+times within the same synchronous block. Each dispatch schedules a
+separate microtask. Observers on `state.arr` will fire **multiple
+times** — once per trap. A future scheduler enhancement may coalesce
+these. This ADR documents the current behavior.
+
+## Consequences
+
+- **Positive:** Every array operation persists and notifies — no
+  silent failures.
+- **Positive:** Array observers fire on the array path, not individual
+  indices — this matches React list-reconciliation mental model.
+- **Positive:** `sort()`, `splice()`, and other complex operations are
+  explicitly tested for persistence + notification.
+- **Negative:** Multiple traps from a single array operation may
+  produce multiple observer notifications — consumers must
+  de-duplicate if needed.
+- **Negative:** Array element object mutations do not notify the
+  array-path observer — this is a fundamental limitation of the
+  exact-path observer model.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-004-arrays.test.ts`