memorio 5.0.0 → 5.1.0

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

@@ -1,128 +1,127 @@
-# 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`
+# ADR-004: Array Mutation Semantics
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+
+## 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`

package/adr/005-scheduler-contract.md

@@ -1,149 +1,148 @@
-# ADR-005: Scheduler Contract
-
-> **Status:** Proposed
-> **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
-
-## Context
-
-The Memorio 5.x plan (Section 10) requires an explicit, configurable
-scheduler. The 4.7.3 baseline dispatches observer callbacks via
-`queueMicrotask` (in `core/dispatch.ts`). There is no configuration
-point, no batching, and no flush control. This must be formalized into
-a contract that supports future UI-framework integration (React
-batched mode, requestAnimationFrame, manual flush for tests).
-
-The scheduler contract must define: ordering, batching, reentrancy,
-error isolation, nested mutations, transaction interaction, and flush
-behavior.
-
-## Assumptions
-
-- The core engine dispatches events via `dispatch.set(name, value)`.
-- `dispatch.listen(name, cb)` wraps `cb` in a microtask boundary.
-- The scheduler is orthogonal to the Mutation Engine (ADR-007) and
-  Transactions (ADR-008) — it only affects *when* observer callbacks
-  fire, not *what* is recorded.
-- `__DEV__` is a build-time constant.
-
-## Decision
-
-### Current default: microtask
-
-The current dispatch layer uses `queueMicrotask` (or
-`Promise.resolve().then(cb)` fallback). This means:
-
-1. **Ordering:** Observer callbacks fire in registration order (FIFO),
-   within the microtask queue, after the current synchronous block
-   completes.
-2. **Asynchronous:** Callbacks fire after the mutation is committed
-   to the raw Proxy target.
-3. **No batching:** Each `dispatch.set` schedules its own microtask.
-
-### Proposed scheduler configuration
-
-A future `createMemorio({ scheduler: ... })` or
-`memorio.configureScheduler({ mode, batching })` API would allow:
-
-```ts
-type SchedulerMode = "sync" | "microtask" | "macrotask" | "raf" | "manual"
-```
-
-| Mode | Behavior |
-|------|----------|
-| `sync` | Callbacks fire synchronously during `dispatch.set`. |
-| `microtask` | Callbacks fire in the microtask queue (default). |
-| `macrotask` | Callbacks fire via `setTimeout(cb, 0)` (macro task). |
-| `raf` | Callbacks fire via `requestAnimationFrame`. |
-| `manual` | Callbacks only fire when `flush()` is called. |
-
-### Batching semantics (proposed)
-
-When `batching: true` (only meaningful with `microtask` or `macrotask`
-mode):
-
-1. All `dispatch.set` calls within a single synchronous block are
-   collected.
-2. Each unique event name is invoked once, after the synchronous
-   block completes, in the scheduled task.
-3. The order of batched callbacks follows the order of first
-   `dispatch.set` for each unique event name.
-
-When `batching: false` (default):
-
-1. Each `dispatch.set` schedules its own callback independently.
-
-### Reentrancy
-
-- Reentrant `dispatch.set` calls (observer callbacks that dispatch new
-  events) are queued after the current callback completes.
-- `sync` mode has no reentrancy boundary — recursive
-  `dispatch.set` calls fire immediately, risking stack overflow.
-- No built-in guard against infinite dispatch loops. Consumers must
-  break the cycle.
-
-### Error isolation
-
-- A throwing callback in `microtask`/`macrotask`/`raf` mode produces
-  an unhandled rejection / error. Other callbacks scheduled in the same
-  tick are unaffected (each runs in its own closure).
-- In `sync` mode, a throwing callback propagates to the caller of
-  `dispatch.set`.
-- A future enhancement may wrap each callback in `try/catch` with an
-  optional error reporter. This ADR does **not** implement that.
-
-### Nested mutations
-
-Mutations inside observer callbacks create a new dispatch cycle. They
-are **not** coalesced with the current cycle. This means:
-
-```js
-state.counter = 1
-// microtask fires:
-observer('state.counter', () => {
-  state.counter = 2  // → schedules a NEW microtask
-})
-```
-
-### Transaction interaction
-
-- During a transaction, each mutation dispatches normally (no
-  suppression).
-- `undo()` / `redo()` set `internal.historyEnabled = false` to prevent
-  re-recording, but the Proxy set trap still dispatches events to
-  observers.
-- A future "transaction-level notification" may suppress individual
-  mutation dispatches during a transaction and fire a single
-  "transaction-end" event. This ADR does **not** define that.
-
-### Flush behavior
-
-- In `manual` mode, `memorio.flush()` (or equivalent) processes all
-  queued callbacks. This is primarily for testing.
-- In other modes, "flush" is implicit (microtask queue drains
-  naturally).
-
-## Current status
-
-The scheduler is currently **not configurable**. The default
-`microtask` behavior is in effect. This ADR is **Proposed** — the
-configuration API is a Phase 2/3 enhancement. The compliance tests
-for the default behavior lock in the current semantics so that future
-scheduler changes do not break existing code.
-
-## Consequences
-
-- **Positive:** Documenting the microtask default gives consumers a
-  deterministic mental model.
-- **Positive:** The proposed API is framework-agnostic — all modes are
-  expressible as platform primitives.
-- **Positive:** `manual` mode enables deterministic testing.
-- **Negative:** No batching means multiple synchronous mutations each
-  produce a microtask — this is a known performance limitation for
-  bulk updates.
-- **Negative:** No error isolation means a buggy observer can crash
-  the app via unhandled rejection.
-
-## Compliance tests
-
-- `tests/vitest/tests/contracts/adr-005-scheduler.test.ts`
+# ADR-005: Scheduler Contract
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+
+## Context
+
+The Memorio 5.x plan (Section 10) requires an explicit, configurable
+scheduler. The 4.7.3 baseline dispatches observer callbacks via
+`queueMicrotask` (in `core/dispatch.ts`). There is no configuration
+point, no batching, and no flush control. This must be formalized into
+a contract that supports future UI-framework integration (React
+batched mode, requestAnimationFrame, manual flush for tests).
+
+The scheduler contract must define: ordering, batching, reentrancy,
+error isolation, nested mutations, transaction interaction, and flush
+behavior.
+
+## Assumptions
+
+- The core engine dispatches events via `dispatch.set(name, value)`.
+- `dispatch.listen(name, cb)` wraps `cb` in a microtask boundary.
+- The scheduler is orthogonal to the Mutation Engine (ADR-007) and
+  Transactions (ADR-008) - it only affects *when* observer callbacks
+  fire, not *what* is recorded.
+- `__DEV__` is a build-time constant.
+
+## Decision
+
+### Current default: microtask
+
+The current dispatch layer uses `queueMicrotask` (or
+`Promise.resolve().then(cb)` fallback). This means:
+
+1. **Ordering:** Observer callbacks fire in registration order (FIFO),
+   within the microtask queue, after the current synchronous block
+   completes.
+2. **Asynchronous:** Callbacks fire after the mutation is committed
+   to the raw Proxy target.
+3. **No batching:** Each `dispatch.set` schedules its own microtask.
+
+### Proposed scheduler configuration
+
+A future `createMemorio({ scheduler: ... })` or
+`memorio.configureScheduler({ mode, batching })` API would allow:
+
+```ts
+type SchedulerMode = "sync" | "microtask" | "macrotask" | "raf" | "manual"
+```
+
+| Mode | Behavior |
+|------|----------|
+| `sync` | Callbacks fire synchronously during `dispatch.set`. |
+| `microtask` | Callbacks fire in the microtask queue (default). |
+| `macrotask` | Callbacks fire via `setTimeout(cb, 0)` (macro task). |
+| `raf` | Callbacks fire via `requestAnimationFrame`. |
+| `manual` | Callbacks only fire when `flush()` is called. |
+
+### Batching semantics (proposed)
+
+When `batching: true` (only meaningful with `microtask` or `macrotask`
+mode):
+
+1. All `dispatch.set` calls within a single synchronous block are
+   collected.
+2. Each unique event name is invoked once, after the synchronous
+   block completes, in the scheduled task.
+3. The order of batched callbacks follows the order of first
+   `dispatch.set` for each unique event name.
+
+When `batching: false` (default):
+
+1. Each `dispatch.set` schedules its own callback independently.
+
+### Reentrancy
+
+- Reentrant `dispatch.set` calls (observer callbacks that dispatch new
+  events) are queued after the current callback completes.
+- `sync` mode has no reentrancy boundary - recursive
+  `dispatch.set` calls fire immediately, risking stack overflow.
+- No built-in guard against infinite dispatch loops. Consumers must
+  break the cycle.
+
+### Error isolation
+
+- A throwing callback in `microtask`/`macrotask`/`raf` mode produces
+  an unhandled rejection / error. Other callbacks scheduled in the same
+  tick are unaffected (each runs in its own closure).
+- In `sync` mode, a throwing callback propagates to the caller of
+  `dispatch.set`.
+- A future enhancement may wrap each callback in `try/catch` with an
+  optional error reporter. This ADR does **not** implement that.
+
+### Nested mutations
+
+Mutations inside observer callbacks create a new dispatch cycle. They
+are **not** coalesced with the current cycle. This means:
+
+```js
+state.counter = 1
+// microtask fires:
+observer('state.counter', () => {
+  state.counter = 2  // → schedules a NEW microtask
+})
+```
+
+### Transaction interaction
+
+- During a transaction, each mutation dispatches normally (no
+  suppression).
+- `undo()` / `redo()` set `internal.historyEnabled = false` to prevent
+  re-recording, but the Proxy set trap still dispatches events to
+  observers.
+- A future "transaction-level notification" may suppress individual
+  mutation dispatches during a transaction and fire a single
+  "transaction-end" event. This ADR does **not** define that.
+
+### Flush behavior
+
+- In `manual` mode, `memorio.flush()` (or equivalent) processes all
+  queued callbacks. This is primarily for testing.
+- In other modes, "flush" is implicit (microtask queue drains
+  naturally).
+
+## Current status
+
+The scheduler is currently **not configurable**. The default
+`microtask` behavior is in effect. This ADR is **Proposed** - the
+configuration API is a Phase 2/3 enhancement. The compliance tests
+for the default behavior lock in the current semantics so that future
+scheduler changes do not break existing code.
+
+## Consequences
+
+- **Positive:** Documenting the microtask default gives consumers a
+  deterministic mental model.
+- **Positive:** The proposed API is framework-agnostic - all modes are
+  expressible as platform primitives.
+- **Positive:** `manual` mode enables deterministic testing.
+- **Negative:** No batching means multiple synchronous mutations each
+  produce a microtask - this is a known performance limitation for
+  bulk updates.
+- **Negative:** No error isolation means a buggy observer can crash
+  the app via unhandled rejection.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-005-scheduler.test.ts`