memorio 5.0.0 → 5.1.0

package/adr/002-observer-semantics.md

@@ -1,180 +1,179 @@
-# 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`
+# 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`

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

@@ -2,7 +2,6 @@
 
 > **Status:** Proposed
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 
 ## Context
 
@@ -11,7 +10,7 @@ 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
+repo v5.1.0, the semantics remain **undocumented** - they rely on
 accidental Proxy behavior rather than an explicit contract.
 
 This ADR makes the deep mutation semantics explicit.
@@ -20,7 +19,7 @@ This ADR makes the deep mutation semantics explicit.
 
 - `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
+- 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.
@@ -59,7 +58,7 @@ and a consumer writes `state.user.profile = { name: "Alice" }`:
 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**
+4. The event dispatched is `state.user.profile` - **not**
    `state.user.profile.name`.
 
 There is **no automatic intermediate object creation** during deep
@@ -113,15 +112,15 @@ When a nested object inside an array is mutated (`state.items[0].name = "X"`):
 
 ## Consequences
 
-- **Positive:** Deep mutations are deterministic — exactly one event
+- **Positive:** Deep mutations are deterministic - exactly one event
   per mutation, on the exact leaf path.
-- **Positive:** Reference identity is preserved — the same proxy wrapper
+- **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
+  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