memorio 4.9.35 → 5.1.0

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

@@ -0,0 +1,128 @@
+# ADR-003: Deep Mutation Semantics
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+
+## 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 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.
+
+## 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,127 @@
+# 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

@@ -0,0 +1,148 @@
+# 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`

package/adr/006-context-isolation.md

@@ -0,0 +1,91 @@
+# ADR-006: Context Isolation Model
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+
+## Context
+
+Memorio must support multiple isolated state trees within a single
+process - for tests, micro-frontends, SSR, workers, and multi-tenant
+environments. The 4.7.3 baseline uses `createContext` /
+`memorio.isolate(name)` to create context-prefixed state, but the
+mechanics and guarantees are undocumented.
+
+This ADR defines how context isolation works, what the isolation
+boundary is, and how it interacts with the Mutation Engine (ADR-007).
+
+## Assumptions
+
+- The core `state`, `store`, `session`, `cache` singletons live on
+  `globalThis` and are shared across all import paths (ESM, CJS,
+  absolute-path imports).
+- A "context" is a string ID that prefixes internal store keys.
+- `memorio.setContext(id)` sets the active context ID at runtime.
+- Server-side code must create per-request contexts from trusted
+  server-side data (never client-controlled input).
+
+## Decision
+
+### Global singleton vs. isolated context
+
+- The global `state` / `store` / `session` / `cache` are **singletons**
+  on `globalThis`. Importing `memorio` in any module returns the same
+  instances. This is the default and is intended for single-instance
+  applications (e.g. one browser tab, one Next.js server instance).
+- `memorio.isolate(name)` creates a new context and returns
+  context-scoped proxies. These proxies share the same underlying
+  engine but read/write to context-prefixed keys in `store`.
+
+### Context ID
+
+- Context IDs are strings. They must be unique within a process.
+- Context IDs are **organizational**, not a security boundary. They
+  do not prevent unauthorized access to another context's data within
+  the same process. Server-side authorization must be enforced at the
+  application layer.
+- `internal.currentContext` is a module-level string on the singleton
+  `internal` object. Mutations record the active context ID.
+
+### Context-scoped state
+
+When `internal.currentContext` is set to `ctxId`:
+
+1. `state.set(key, value)` writes to `state` but records
+   `context: ctxId` in the MutationRecord.
+2. `store.set(key, value)` writes to storage with key
+   `ctxId:key` (key-prefix isolation).
+3. `session.set(key, value)` writes to storage with key
+   `ctxId:key`.
+4. Reads from `store.get(key)` and `session.get(key)` read from
+   `ctxId:key`.
+
+### Default context
+
+When `internal.currentContext` is `null` (the default), all state and
+store operations use the un-prefixed keys. This is the "default" or
+"global" context.
+
+### Multi-tenant caveat
+
+`state` (the Proxy) is always global - it is a single reactive tree.
+Context isolation applies to **persistence** (`store`, `session`) and
+**mutation records** (`context` field). To achieve true state-tree
+isolation, consumers should use `memorio.isolate(name)` which creates
+a new context, or instantiate isolated Memorio instances.
+
+## Consequences
+
+- **Positive:** Single global singleton simplifies the common case
+  (one app, one state tree).
+- **Positive:** Context-prefixed persistence enables multi-tenant
+  server-side usage without separate state trees.
+- **Positive:** Mutation records carry context, enabling causal-graph
+  partitioning (Phase 4).
+- **Negative:** `state` itself is not multi-tenant - consumers needing
+  isolated state trees must use `isolate()` or separate processes.
+- **Negative:** Context isolation is organizational, not a security
+  boundary - documented clearly in AGENTS.md.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-006-context.test.ts`

package/adr/007-mutation-records.md

@@ -0,0 +1,117 @@
+# ADR-007: Mutation Records
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+
+## Context
+
+Section 6 of the Memorio 5.x plan requires every state mutation to pass
+through a normalized internal `MutationRecord`. The 4.7.3 baseline has
+an informal `MutationRecord` interface in `core/internal.ts` with
+`path`, `action`, `newValue`, `previousValue`, `timestamp`. The 5.0
+codebase has extended this with `id`, `operation`, `hlc`, `context`,
+`source`, and `transactionId` (see `core/mutation/types.ts`).
+
+This ADR formalizes the canonical record structure and guarantees.
+
+## Assumptions
+
+- Every `set`/`delete` trap on the state Proxy calls the
+  `buildProxy` callback once.
+- The callback constructs a `Mutation` via `createMutation()` which:
+  - Generates an HLC-based ID (`m_<encoded>`).
+  - Captures `before` = previous value, `after` = new value.
+  - Tags the mutation with the active transaction ID (if any).
+  - Sets `context` from `internal.currentContext`.
+- `recordMutation()` is the single write point to the trace log and
+  undo/redo stacks (in `core/internal.ts`).
+- History tracking is opt-in via `enableHistory(true)`.
+
+## Decision
+
+### Canonical MutationRecord structure
+
+```ts
+interface MutationRecord {
+  // --- Canonical Memorio 5 fields ---
+  id: string           // HLC-based UUID: "m_<encoded-hlc>"
+  path: string         // Dotted path relative to state: "user.profile.name"
+  operation: 'set' | 'delete' | 'insert' | 'remove' | 'replace' | 'length'
+  before: any          // Value before mutation (deepRaw'd)
+  after: any           // Value after mutation (deepRaw'd)
+  timestamp: number    // Epoch ms
+  hlc: string           // Serialized HLC: "hlc:<physical>:<logical>:<node>"
+
+  // --- Metadata ---
+  context?: string      // Active context ID
+  source?: string       // Optional attribution (e.g. "profile.save")
+  transactionId?: string // Active transaction ID, if any
+  parentId?: string     // Parent mutation ID (for causal graph)
+
+  // --- Legacy fields (backward compatibility) ---
+  action: 'set' | 'delete'    // Mirrors operation (set/delete only)
+  newValue: any               // Alias for `after`
+  previousValue: any           // Alias for `before`
+}
+```
+
+### Guarantees
+
+1. **Every mutation gets a unique ID.** The ID is generated via
+   `generateMutationId()` which calls `hlc.tick()` - guaranteeing
+   causal ordering within a single node. The node suffix ensures
+   uniqueness across devices.
+
+2. **Before/after are deepRaw'd.** Proxy wrappers are never stored in
+   the record - only plain values. This ensures serializable,
+   comparison-safe records.
+
+3. **Single write point.** `internal.recordMutation()` is the only
+   function that pushes to `mutations`, `undoStack`, or `redoStack`.
+   No other code path mutates these arrays directly.
+
+4. **Redo stack clears on new mutation.** Any mutation (including
+   undo/redo inverse writes, since those temporarily disable history)
+   must NOT clear the redo stack - undo/redo use
+   `internal.historyEnabled = false` to bypass `recordMutation`.
+
+5. **Max history depth.** Both stacks are trimmed to
+   `internal.maxHistory` (default: 100). Trimming removes from the
+   front (shift), preserving recency.
+
+6. **No-op mutations.** If `before === after`, the record is still
+   created and stored (the mutation happened, even if the value
+   didn't change). `mutationToPatch()` returns `null` for no-ops, so
+   no patch is stored in a commit's patch list.
+
+### Reentrancy guard
+
+The `mutate()` function sets `internal._recording = false` before
+writing to the state Proxy, then calls `recordMutation()` itself. This
+prevents the Proxy callback from double-recording the same mutation.
+
+### Transaction tagging
+
+During an active transaction, `createMutation()` calls
+`tagForTransaction()` to attach the current transaction ID.
+`registerMutationInTransaction(id)` adds the mutation ID to the
+transaction's mutation list.
+
+## Consequences
+
+- **Positive:** A single, well-typed record structure serves undo,
+  redo, trace, diff, and future replay/revert.
+- **Positive:** HLC-based IDs provide causal ordering for the causal
+  graph and simulation engine.
+- **Positive:** Legacy fields maintain full backward compatibility
+  with 4.x consumers.
+- **Negative:** Storing both legacy and canonical fields doubles the
+  record size - acceptable for the opt-in history feature.
+- **Negative:** No-op mutations are stored - a future optimization
+  could skip them in the set trap, but the Mutation Engine must remain
+  the source of truth.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-007-mutation-records.test.ts`
+- `tests/vitest/tests/mutation-engine.test.ts` (existing)