memorio 4.9.35 → 5.1.0

package/SECURITY.md

@@ -1,48 +1,174 @@
-# Security
+# Security & Encryption
 
-Memorio follows NIST and NSA security standards at the enterprise level.
+This document covers Memorio's optional encryption layer, client-side multitenancy, and general security posture. For the short version, see the **Security** section in the main [README](./README.md).
 
-## Security Standards
+---
+
+## Nothing is encrypted by default
+
+This applies to every layer: `state`, `store`, `session`, `idb`, `memory`, `sqlite`. Treat browser storage as client-controlled unless you explicitly opt in.
+
+Core has zero production dependencies. No `eval`, no dynamic code execution, no bundled telemetry, sanitized keys, validated inputs, bounded journal entries, UUID-based session identifiers. Independently checkable via Socket.dev / Snyk.
+
+---
+
+## The encryption layer
+
+Memorio ships an optional encryption layer built on the **Web Crypto API** (`crypto.subtle`): AES-GCM for authenticated encryption, PBKDF2 for password-based key derivation. It is opt-in - no layer encrypts by default, so the common case stays transparent and fast.
+
+All `memorio.encryption` operations are **asynchronous by design** - the Web Crypto API runs cryptographic work on a separate internal thread managed by the browser/runtime, so `deriveKey()`, `encrypt()`, and `decrypt()` return Promises that never block the main thread. PBKDF2 derivation at the NIST SP 800-132-recommended 600,000 iterations typically completes in under 300ms on mid-range hardware. No explicit Web Worker offload is needed.
+
+### Encrypt a value
+
+```ts
+import { memorio } from 'memorio'
+
+// Derive a key from a password (PBKDF2, 600k iterations - NIST SP 800-132)
+const key = await memorio.encryption.deriveKey('my-password', 'per-tenant-salt')
+// or generate one directly, without a password:
+const freshKey = await memorio.encryption.generateKey()
+const freshSalt = memorio.encryption.generateSalt()
+
+// Encrypt → envelope object { __memorio_encrypted, alg, iv, data }
+const envelope = await memorio.encryption.encrypt({ token: 'abc123' }, key)
+
+// Decrypt - wrong key rejects rather than returning garbage
+const original = await memorio.encryption.decrypt(envelope, key)
+// → { token: 'abc123' }
 
-- **NIST Guidelines**: Follows NIST SP 800-53 security controls and NIST Cybersecurity Framework
-- **NSA Standards**: Defense-grade security practices; considers nation-state level threats in risk assessment
+// Check a value before trying to decrypt it
+memorio.encryption.isEncrypted(envelope)     // true - checks the __memorio_encrypted flag
+memorio.encryption.isAvailable()             // false in environments without Web Crypto (e.g. old runtimes)
+```
 
-## Supply Chain Security
+For the common "encrypt with a password, get a string back" case, skip manual key derivation:
 
-- **Socket.dev**: Minimum target score 90%; all alarms must be resolved before release
-- **Dependency Management**: Zero production dependencies (fully dependency-free); dev dependencies audited regularly
-- **Prohibited**: No `eval()` usage, no encrypted/obfuscated code in builds, no hardcoded secrets
+```ts
+const cipherText = await memorio.encryption.encryptWithPassword({ token: 'abc123' }, 'my-password')
+const plain = await memorio.encryption.decryptWithPassword(cipherText, 'my-password')
+```
 
-## Code Security
+Both accept/return an envelope object (not a JSON string when you already have a key):
 
-- No hardcoded credentials or API keys
-- Secure random session ID generation (`crypto.randomUUID` → `crypto.getRandomValues` → fallback)
-- Input validation on all public APIs
-- XSS prevention on DevTools data export
-- Property-based access control on global objects (`Object.defineProperty` with `enumerable: false`)
+```ts
+const envelope = await memorio.encryption.encrypt({ token: 'abc123' }, key)
+const plain = await memorio.encryption.decrypt(envelope, key) // returns the original value
+```
 
-## OWASP Compliance
+**Key import/export** for storing CryptoKey material securely (e.g. in an httpOnly cookie):
 
-Addresses OWASP Top 10 (2021):
-- A01:2021 - Broken Access Control (global object protection, property locks)
-- A02:2021 - Cryptographic Failures (crypto.randomUUID for session IDs)
-- A03:2021 - Injection (CSS sanitization in devtools)
-- A05:2021 - Security Misconfiguration (minimal surface area, no bundled secrets)
-- A06:2021 - Vulnerable and Outdated Components (regular npm audit, Socket.dev)
-- A07:2021 - Identification and Authentication Failures (N/A - library, no auth)
-- A08:2021 - Software and Data Integrity Failures (strict tsconfig, lock files)
-- A09:2021 - Security Logging and Monitoring Failures (DevTools inspect, Logger module)
-- A10:2021 - Server-Side Request Forgery (N/A - no network requests)
+```ts
+const key = await memorio.encryption.generateKey()
+const { key: b64, iv } = await memorio.encryption.exportKey(key)
+// Store b64 securely, then restore later:
+const restoredKey = await memorio.encryption.importKey(b64, iv)
+```
 
-## Reporting Security Issues
+### Store with at-rest encryption
 
-If you find a security vulnerability:
+```ts
+// Per-call encryption (opt-in)
+await store.set('api_token', secretValue, { encrypt: key })
+const token = await store.get('api_token', { decrypt: key })
 
-1. Email [Dario Passariello](mailto:dariopassarielloa@gmail.com)
-2. Or visit https://dario.passariello.ca/contact/
+// Or configure a default key for automatic encryption:
+store.config({ encryptionKey: key })
+await store.set('api_token', secretValue)  // encrypted transparently
+const token = await store.get('api_token') // decrypted transparently
+```
 
-Do not open public issues for security vulnerabilities.
+`session` supports the same `config` and per-call opts.
+
+> ⚠️ **Sync vs async changes once encryption is on.** Without encryption, `store.get`/`store.set` (and `session`'s equivalents) are synchronous - they return the value directly. As soon as either call touches `encrypt`/`decrypt` (per-call, or because a default `encryptionKey` is configured), both become asynchronous and return a `Promise`. Code written against the plain synchronous API will silently receive a `Promise` instead of a value if encryption is turned on later - always `await` `store.get`/`store.set` defensively if there's any chance encryption gets enabled down the line.
 
 ---
-*Document version: 2.0 - Last updated: 2026-05-19*
-*Owner: BigLogic Security Team*
+
+## Contexts are not authorization
+
+```ts
+memorio.createContext('tenant-123')
+```
+
+Contexts organize and isolate application concerns by namespace-prefixing keys - they are **not** a security boundary. Any script running in the same JS runtime can attempt operations against another context. Real tenant isolation belongs at the auth/backend layer.
+
+---
+
+## Encrypted multitenancy
+
+Pass an `encryptionKey` to `createContext()` and the tenant's isolated `store`/`session` automatically encrypt on write and decrypt on read:
+
+```ts
+const tenantKey = await memorio.encryption.deriveKey(tenantPassword, tenantSalt)
+
+const ctx = memorio.createContext('tenant-123', { encryptionKey: tenantKey })
+
+// Values are encrypted at rest within this context's namespace
+await ctx.store.set('secrets', { apiKey: '…' })
+const secrets = await ctx.store.get('secrets')  // decrypted transparently
+
+// Another tenant with a different key can't read this data
+const otherCtx = memorio.createContext('tenant-456', { encryptionKey: otherKey })
+const leaked = await otherCtx.store.get('memorio_store_secrets')  // fails to decrypt
+```
+
+This adds a cryptographic wall on top of the namespace prefix: even if a tenant's key prefix is guessed, the ciphertext is unreadable without the key. It still doesn't replace backend authorization - see above.
+
+> ⚠️ **`cache` is never encrypted, even inside an encrypted context.** `createContext(name, { encryptionKey })` only encrypts that context's `store` and `session` - its `cache` stays volatile, in-memory, and in plaintext regardless. Don't put anything in `ctx.cache` you wouldn't put in unencrypted `cache`.
+
+`memorio.isolate()` is a thin alias for `createContext()` and accepts the same `{ encryptionKey }` option.
+
+> **Key management is yours.** Derive keys from authenticated session material or generate them with `memorio.encryption.generateKey()`. Never hardcode keys in client bundles.
+
+---
+
+## 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, never inferred from `NODE_ENV` or bundler environment variables.
+
+For application code, prefer explicit named imports:
+
+```ts
+import { state } from 'memorio'
+```
+
+---
+
+## Code-level hardening
+
+- No hardcoded credentials, API keys, or secrets anywhere in the codebase or build output.
+- Session IDs use a secure random source with graceful fallback: `crypto.randomUUID` → `crypto.getRandomValues` → a documented fallback if neither is available.
+- Public APIs validate their inputs rather than trusting caller-supplied shapes.
+- Global objects installed via `memorio/global` use `Object.defineProperty` with `enumerable: false` where applicable, rather than plain assignment.
+- No obfuscated or minified-beyond-readability code shipped in a way that would hide behavior from review.
+
+---
+
+## Supply chain
+
+- Zero production dependencies in core - nothing to audit transitively for the parts you actually ship.
+- Dev dependencies are audited periodically (`npm audit` and equivalent).
+- Package integrity is checkable independently via Socket.dev / Snyk before you adopt a given version.
+
+> If you require a specific minimum Socket.dev/Snyk score or a documented audit trail as part of a procurement process, verify the current score yourself at adoption time - this document doesn't pin a number that could go stale.
+
+---
+
+## Reporting a vulnerability
+
+Please don't open a public issue for a security vulnerability. Instead:
+
+1. Email [Dario Passariello](mailto:dariopassarielloa@gmail.com), or
+2. Use the contact form at https://dario.passariello.ca/contact/
+
+---
+
+## Enterprise compliance notes
+
+| Concern | What you get | Impact |
+| --- | --- | --- |
+| **Opt-in encryption** | `memorio.encryption` provides AES-GCM + PBKDF2. `store`/`session` and encrypted contexts support automatic encrypt-on-write/decrypt-on-read. | Not encrypted by default - you must opt in via `store.config({ encryptionKey })` or `createContext(id, { encryptionKey })`. Without it, PII, tokens, and regulated data (GDPR/HIPAA) are at rest in plaintext. Enabling it also changes the calling convention - see the sync/async warning above. |
+| **Client-side multitenancy** | `createContext(id, { encryptionKey })` provides namespace + cryptographic isolation between tenants. | Still **not** a security boundary - any script in the same JS runtime can attempt context operations. Encryption makes cross-tenant reads cryptographically hard, but real authorization must live on the backend. |
+| **DevTools** | Expose data for development only. | Only active when you opt into `memorio/global`; never ship enabled in production. |
+| **Formal compliance frameworks (NIST, OWASP, etc.)** | No formal third-party audit or certification has been published for this project. | If your procurement process requires a certified compliance framework, commission an independent audit rather than relying on self-declared conformance - see [When to use something else](./README.md#when-to-use-something-else) in the README. |
+
+If any of these gaps block adoption, keep Memorio for memory/state lifecycle and pair it with a dedicated secrets manager or backend-enforced authorization for the pieces it explicitly doesn't cover.

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 v5.1.0 (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,95 @@
+# ADR-001: State Proxy Model
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+
+## 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,179 @@
+# ADR-002: Observer Semantics
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+
+## 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`