memorio 4.9.35 → 5.0.0

package/adr/005-scheduler-contract.md

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

package/adr/006-context-isolation.md

@@ -0,0 +1,92 @@
+# ADR-006: Context Isolation Model
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## 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,118 @@
+# ADR-007: Mutation Records
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## 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)

package/adr/008-transactions.md

@@ -0,0 +1,106 @@
+# ADR-008: Transactions
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+Section 11 of the Memorio 5.x plan requires transactions to group
+multiple mutations into one logical operation. The 5.0 codebase
+implements `beginTransaction`, `commitTransaction`,
+`abortTransaction`, `listTransactions`, `currentTransaction` in
+`core/mutation/transaction.ts`. This ADR formalizes the semantics.
+
+## Assumptions
+
+- Mutations inside a transaction are tagged with the transaction ID
+  via `createMutation()` → `tagForTransaction()`.
+- The transaction registry lives on `globalThis`
+  (`__memorio_transaction_registry__`) to survive module duplication.
+- `internal.currentTransactionId` tracks the active transaction.
+- `memorio.transaction(fn, opts)` is a convenience alias for
+  `beginTransaction`.
+
+## Decision
+
+### Transaction lifecycle
+
+```
+beginTransaction(source, message, metadata)
+  → creates TransactionContext { id, startedAt, active: true }
+  → sets internal.currentTransactionId = id
+  → mutations tagged with id
+
+commitTransaction()
+  → marks context active: false, sets committedAt
+  → clears internal.currentTransactionId
+  → returns { id, mutations[], startedAt, committedAt, source, message, metadata }
+
+abortTransaction()
+  → rolls back all tagged mutations (applies inverse)
+  → removes mutation IDs from undoStack (no redo push)
+  → deletes from registry, clears currentTransactionId
+  → returns the Transaction record
+```
+
+### Transaction ID generation
+
+- Generated via `generateTransactionId()` → `tx_<encoded-hlc>`.
+- Monotonically ordered within a node via HLC.
+
+### Nested transactions
+
+`beginTransaction` called while a transaction is already active
+creates a **new** transaction context (with a new ID). The previous
+transaction remains active in the registry — it is **not** suspended
+or paused. `commitTransaction()` only commits the **most recently
+started** active transaction.
+
+This is a **flat namespace** model: transactions are independent, not
+hierarchical. A mutation made after the inner `beginTransaction` is
+tagged with the inner transaction's ID, not the outer.
+
+> **Future:** A hierarchical model (with parentId) may be introduced.
+> This ADR documents the current flat behavior.
+
+### Rollback on abort
+
+`abortTransaction` finds each tagged mutation in `undoStack` by its
+record ID, removes it from the stack (without pushing to redo), and
+applies the inverse (`_applyInverse`). The inverse writes go through
+the Proxy with `historyEnabled = false` and `_recording = false`, so
+they are not recorded.
+
+### Transaction record immutability
+
+Once committed or aborted, a transaction's `mutations` list is frozen
+(immutable). The registry retains the context for
+`listTransactions()` inspection, but `active` is `false`.
+
+### Mutate inside a transaction
+
+`memorio.mutate(path, value, { source })` inside a transaction:
+1. Calls `createMutation(...)` which auto-tags with the active
+   transaction ID via `tagForTransaction()`.
+2. Writes to state with `_recording = false` (no double recording).
+3. Calls `recordMutation(mutation)` — the mutation is recorded in the
+   trace log AND tagged in the transaction.
+
+## Consequences
+
+- **Positive:** Mutations are grouped and attributable to a logical
+  operation — essential for explain() and impact() in Phase 4.
+- **Positive:** `abortTransaction` provides atomic rollback — all
+  mutations are undone.
+- **Positive:** Registry on `globalThis` survives module duplication.
+- **Negative:** Nested transactions are flat (not hierarchical) —
+  the outer transaction is not aborted if the inner is aborted.
+- **Negative:** Rollback via inverse application requires all
+  `before` values to be present in the MutationRecord — for
+  very large objects this is memory-intensive.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-008-transactions.test.ts`
+- `tests/vitest/tests/mutation-engine.test.ts` (existing, §06-07)

package/adr/009-history-model.md

@@ -0,0 +1,110 @@
+# ADR-009: History Model (Snapshot / Delta)
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+Section 12 and Section 13 of the Memorio 5.x plan require an immutable,
+Git-inspired history model with commits, snapshots, deltas, and undo/redo
+as distinct concepts. The 4.7.3 baseline implements undo/redo on a
+linear mutation stack (in `core/internal.ts` and
+`functions/history/index.ts`). This ADR defines the upgrade path to
+the full Commit → Snapshot → Delta model.
+
+## Assumptions
+
+- The current undo/redo stack stores flat `MutationRecord` entries.
+- `enableHistory(true)` activates recording.
+- `memorio.snapshot()` captures a deep clone of state.
+- `memorio.trace()` returns the flat mutation log.
+
+## Decision
+
+### Current state (4.7.3 baseline)
+
+- Mutations are stored as `MutationRecord[]` in `undoStack` and
+  `redoStack` on the singleton `internal` object.
+- `undo()` pops from `undoStack`, pushes to `redoStack`, applies the
+  inverse to state.
+- `redo()` pops from `redoStack`, pushes to `undoStack`, re-applies.
+- `trace()` returns the full `mutations` log (trimmed to
+  `maxHistory`).
+- No commit concept exists — every mutation is an individual entry.
+
+### Target state (Memorio 5.0)
+
+```
+Commit (immutable, append-only)
+  ├── parent: CommitId | null
+  ├── patches: Patch[]    (RFC 6902: add | remove | replace)
+  ├── metadata: { source?, message?, actor?, timestamp, hlc }
+  └── snapshot?: SnapshotRef  (materialized every N commits)
+```
+
+- **Commits** are the unit of history. `memorio.commit(message, fn)`
+  groups all mutations in `fn` into one commit.
+- **Snapshots** are deep clones of state, materialized every
+  `snapshotInterval` commits (default: 100) to bound replay cost.
+- **Deltas** are the `Patch[]` that transform a snapshot to the next
+  state. Only patches are stored between snapshots — never full
+  state copies.
+- **Undo/Redo** operate at the commit level, not the individual
+  mutation level. Undoing a commit applies the inverse of every patch
+  in the commit.
+
+### Migration path
+
+1. **Phase 1 (this sprint):** Keep the existing flat mutation stack.
+   Document that `undo()`/`redo()` operate per-mutation, not per-commit.
+   Add `memorio.commit()` as a grouping mechanism without changing the
+   underlying stack.
+2. **Phase 3:** Replace the flat stack with the Commit → Snapshot →
+   Delta model. `undo()`/`redo()` will operate per-commit.
+
+### Undo vs. Revert (explicit distinction)
+
+- **Undo** (`memorio.undo()`): Moves the current position backward in
+  the undo stack. The mutation is preserved on the redo stack.
+- **Revert** (`memorio.history.revert(commitId)`): Creates a **new**
+  mutation that reverses a historical commit. The original commit
+  remains in history (immutable). This is a future Phase 3 feature.
+
+### maxCommits and maxHistory
+
+- `maxCommits` (default: 10,000): Maximum number of commit entries
+  retained. Older commits are trimmed (FIFO).
+- `maxHistory` (default: 100): Maximum mutations per undo/redo stack
+  (legacy, applies to the current flat model).
+
+### Replay safety
+
+- Replay must be deterministic. Patches are pure (no closures, no
+  functions). `state.path = value` is the inverse of `delete
+  state.path` in a patch-based replay.
+- External dependencies (Date.now, Math.random, crypto) must be
+  injected via a replay context to maintain determinism.
+
+## Consequences
+
+- **Positive:** Commits group mutations logically — essential for
+  explain(), business history, and audit trails.
+- **Positive:** Snapshot/delta model bounds memory and replay cost.
+- **Positive:** Undo and Revert are distinct operations — no
+  conflation.
+- **Negative:** The current flat stack must be replaced in Phase 3,
+  which is a breaking change to `undo()`/`redo()` semantics
+  (per-mutation → per-commit).
+- **Negative:** Snapshot materialization at intervals is a trade-off
+  between memory and CPU — defaults must be benchmark-driven.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-009-history.test.ts`
+- `tests/vitest/tests/mutation-engine.test.ts` (existing, §04-07)
+
+## Benchmarks
+
+- `experimental/benchmarks/replay.bench.ts` — measures replay cost
+  with and without interval snapshots.

package/adr/README.md

@@ -0,0 +1,46 @@
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records (ADRs) for the
+**Memorio 5.x** "Application State Intelligence Runtime" initiative.
+
+## Format
+
+ADRs follow the [MADR](https://adr.github.io/) (Markdown Architectural
+Decision Records) format. Each decision record answers four questions:
+
+1. **Context** — What is the issue that we were dealing with when we
+   started thinking about it?
+2. **Decision** — What is the change that we will make (that resolves
+   the issue)?
+3. **Consequences** — What becomes easier or more difficult to do
+   because of this change?
+
+## Numbering
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| [001](001-state-proxy-model.md) | State Proxy Model | Accepted |
+| [002](002-observer-semantics.md) | Observer Semantics | Proposed |
+| [003](003-deep-mutation-semantics.md) | Deep Mutation Semantics | Proposed |
+| [004](004-array-mutation-semantics.md) | Array Mutation Semantics | Proposed |
+| [005](005-scheduler-contract.md) | Scheduler Contract | Proposed |
+| [006](006-context-isolation.md) | Context Isolation Model | Accepted |
+| [007](007-mutation-records.md) | Mutation Records | Accepted |
+| [008](008-transactions.md) | Transactions | Accepted |
+| [009](009-history-model.md) | History Model (Snapshot/Delta) | Proposed |
+
+## Lifecycle
+
+New ADRs start as **Proposed**, move to **Accepted** when the decision
+is implemented and tests pass, and become **Superseded** when a later
+ADR supersedes them. A **Deprecated** status marks decisions that are no
+longer relevant but kept for historical context.
+
+## Compliance
+
+Every ADR that defines a behavioral contract must have a corresponding
+compliance test suite under `tests/vitest/tests/contracts/`. The test
+file name mirrors the ADR number (e.g. `adr-004-arrays.test.ts`).
+
+A release must not be published if any **Accepted** ADR has failing
+compliance tests.

package/adr/template.md

@@ -0,0 +1,49 @@
+# ADR Template — MADR format
+
+> **Status:** `{Proposed | Accepted | Superseded by [ADR-XXX](adr-XXX.md) | Deprecated}`
+> **Date:** YYYY-MM-DD
+> **Deciders:** Memorio 5.x Core Team
+
+## Context
+
+> What is the issue that we were dealing with when we started thinking
+> about it? What are the forces at play? Consider the unique constraints
+> of this project — the need for deterministic, explainable state that
+> remembers, understands, replays, and simulates application state.
+
+## Assumptions
+
+> List any assumptions the decision relies on (e.g. “state mutations are
+> synchronous,” “the Proxy target is always a plain object or array”).
+
+## Decision
+
+> What is the change that we will make? Describe the chosen approach in
+> detail. This section must be precise enough to serve as an implementation
+> contract. Include:
+>
+> - The precise semantics (what happens, what does not happen)
+> - Edge cases and error behavior
+> - Performance characteristics
+> - Backward-compatibility implications
+
+## Consequences
+
+> What becomes easier or more difficult to do because of this change?
+> Consider:
+>
+> - **Positive** — benefits gained (e.g. improved developer experience,
+>   better performance, deterministic behavior)
+> - **Negative** — trade-offs and drawbacks (e.g. loss of flexibility,
+>   migration complexity, runtime overhead)
+> - **Testability** — how this decision is covered by compliance tests
+
+## Compliance tests
+
+> Reference the test file(s) that verify this contract. Every Accepted
+> ADR must list at least one compliance test file path relative to the
+> repository root.
+
+```
+
+File: _ADR_TITLE_PLACEHOLDER.md