memorio 4.9.35 → 5.1.0

package/adr/008-transactions.md

@@ -0,0 +1,105 @@
+# ADR-008: Transactions
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+
+## 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,109 @@
+# ADR-009: History Model (Snapshot / Delta)
+
+> **Status:** Proposed
+> **Date:** 2026-09-12
+
+## 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,48 @@
+# ADR Template - MADR format
+
+> **Status:** `{Proposed | Accepted | Superseded by [ADR-XXX](adr-XXX.md) | Deprecated}`
+> **Date:** YYYY-MM-DD
+
+## 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

package/bin/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'install-extension') {
+  installExtension();
+} else {
+  console.log('Usage: npx memorio install-extension');
+  process.exit(command ? 1 : 0);
+}
+
+function installExtension() {
+  const vsixPath = path.join(__dirname, '..', 'vsix', 'memorio.vsix');
+
+  if (!fs.existsSync(vsixPath)) {
+    console.error(`VSIX file not found at ${vsixPath}.`);
+    console.error('The npm package may be corrupted, or the build did not copy the .vsix into vsix/.');
+    process.exit(1);
+  }
+
+  const candidates = candidateBinaries();
+  const found = candidates.find((bin) => isAvailable(bin));
+
+  if (!found) {
+    console.error('No compatible editor found in PATH (tried: ' + candidates.join(', ') + ').');
+    console.error('Manual installation:');
+    console.error('  1. Open your editor (VSCodium/VSCode)');
+    console.error('  2. Command Palette -> "Extensions: Install from VSIX..."');
+    console.error(`  3. Select: ${vsixPath}`);
+    process.exit(1);
+  }
+
+  console.log(`Editor detected: ${found}. Installing memorio extension...`);
+  const result = spawnSync(found, ['--install-extension', vsixPath], {
+    stdio: 'inherit',
+    shell: os.platform() === 'win32',
+  });
+
+  if (result.status !== 0) {
+    console.error('Installation failed. Try manually:');
+    console.error(`  ${found} --install-extension "${vsixPath}"`);
+    process.exit(result.status || 1);
+  }
+
+  console.log('Memorio extension installed successfully.');
+}
+
+function candidateBinaries() {
+  const names = ['codium', 'vscodium', 'code', 'code-insiders'];
+  if (os.platform() === 'win32') {
+    return names.map((n) => `${n}.cmd`);
+  }
+  return names;
+}
+
+function isAvailable(bin) {
+  const checkCmd = os.platform() === 'win32' ? 'where' : 'which';
+  const result = spawnSync(checkCmd, [bin], { stdio: 'ignore', shell: true });
+  return result.status === 0;
+}

package/examples/basic.ts

@@ -1,115 +1,115 @@
-/**
- * Memorio Basic Example
- *
- * This example shows the fundamental features of Memorio:
- * - State management
- * - Store (localStorage)
- * - Session storage
- * - Platform detection
- *
- * Run: npx ts-node examples/basic.ts
- */
-
-import 'memorio'
-
-// ============================================
-// PLATFORM DETECTION
-// ============================================
-
-console.debug('=== Platform Detection ===')
-console.debug('Memorio version:', memorio.version)
-
-// Check platform
-if (memorio.isBrowser()) {
-  console.debug('Platform: Browser')
-} else if (memorio.isNode()) {
-  console.debug('Platform: Node.js')
-} else if (memorio.isDeno()) {
-  console.debug('Platform: Deno')
-} else if (memorio.isEdge()) {
-  console.debug('Platform: Edge Worker')
-}
-
-// Get capabilities
-const caps = memorio.getCapabilities()
-console.debug('Capabilities:', {
-  platform: caps.platform,
-  hasLocalStorage: caps.hasLocalStorage,
-  hasSessionStorage: caps.hasSessionStorage,
-  hasIndexedDB: caps.hasIndexedDB
-})
-
-// ============================================
-// STATE - In-memory reactive state
-// ============================================
-
-console.debug('\n=== State Management ===')
-
-// Set some state values
-state.name = 'Mario'
-state.age = 30
-state.isActive = true
-state.profile = {
-  email: 'mario@example.com',
-  avatar: 'https://example.com/mario.png'
-}
-
-// Get state values
-console.debug('Name:', state.name)
-console.debug('Age:', state.age)
-console.debug('Profile:', state.profile)
-
-// List all states
-console.debug('All states:', state.list)
-
-// ============================================
-// STORE - Persistent localStorage
-// ============================================
-
-console.debug('\n=== Store (Persistent Storage) ===')
-
-// Check persistence
-console.debug('Is persistent:', store.isPersistent) // true in browser, false in Node.js/Deno
-
-// Save to localStorage
-store.set('username', 'mario')
-store.set('preferences', { theme: 'dark', language: 'en' })
-store.set('lastLogin', Date.now())
-
-// Read from localStorage
-console.debug('Username:', store.get('username'))
-console.debug('Preferences:', store.get('preferences'))
-
-// Get storage size
-console.debug('Storage size:', store.size(), 'kilobytes')
-
-// ============================================
-// SESSION - Temporary session storage
-// ============================================
-
-console.debug('\n=== Session (Temporary Storage) ===')
-
-// Check persistence
-console.debug('Is persistent:', session.isPersistent) // true in browser, false in Node.js/Deno
-
-// Save session data (cleared when tab closes)
-session.set('token', 'abc123xyz')
-session.set('userId', 42)
-
-// Read session data
-console.debug('Token:', session.get('token'))
-console.debug('User ID:', session.get('userId'))
-
-// ============================================
-// CLEANUP
-// ============================================
-
-// Clear specific items
-store.remove('username')
-session.remove('token')
-
-// Clear all
-store.removeAll()
-session.removeAll()
-
-console.debug('\nExample complete!')
+/**
+ * Memorio Basic Example
+ *
+ * This example shows the fundamental features of Memorio:
+ * - State management
+ * - Store (localStorage)
+ * - Session storage
+ * - Platform detection
+ *
+ * Run: npx ts-node examples/basic.ts
+ */
+
+import { memorio, state, store, session } from 'memorio'
+
+// ============================================
+// PLATFORM DETECTION
+// ============================================
+
+console.debug('=== Platform Detection ===')
+console.debug('Memorio version:', memorio.version)
+
+// Check platform
+if (memorio.isBrowser()) {
+  console.debug('Platform: Browser')
+} else if (memorio.isNode()) {
+  console.debug('Platform: Node.js')
+} else if (memorio.isDeno()) {
+  console.debug('Platform: Deno')
+} else if (memorio.isEdge()) {
+  console.debug('Platform: Edge Worker')
+}
+
+// Get capabilities
+const caps = memorio.getCapabilities()
+console.debug('Capabilities:', {
+  platform: caps.platform,
+  hasLocalStorage: caps.hasLocalStorage,
+  hasSessionStorage: caps.hasSessionStorage,
+  hasIndexedDB: caps.hasIndexedDB
+})
+
+// ============================================
+// STATE - In-memory reactive state
+// ============================================
+
+console.debug('\n=== State Management ===')
+
+// Set some state values
+state.name = 'Mario'
+state.age = 30
+state.isActive = true
+state.profile = {
+  email: 'mario@example.com',
+  avatar: 'https://example.com/mario.png'
+}
+
+// Get state values
+console.debug('Name:', state.name)
+console.debug('Age:', state.age)
+console.debug('Profile:', state.profile)
+
+// List all states
+console.debug('All states:', state.list)
+
+// ============================================
+// STORE - Persistent localStorage
+// ============================================
+
+console.debug('\n=== Store (Persistent Storage) ===')
+
+// Check persistence
+console.debug('Is persistent:', store.isPersistent) // true in browser, false in Node.js/Deno
+
+// Save to localStorage
+store.set('username', 'mario')
+store.set('preferences', { theme: 'dark', language: 'en' })
+store.set('lastLogin', Date.now())
+
+// Read from localStorage
+console.debug('Username:', store.get('username'))
+console.debug('Preferences:', store.get('preferences'))
+
+// Get storage size
+console.debug('Storage size:', store.size(), 'kilobytes')
+
+// ============================================
+// SESSION - Temporary session storage
+// ============================================
+
+console.debug('\n=== Session (Temporary Storage) ===')
+
+// Check persistence
+console.debug('Is persistent:', session.isPersistent) // true in browser, false in Node.js/Deno
+
+// Save session data (cleared when tab closes)
+session.set('token', 'abc123xyz')
+session.set('userId', 42)
+
+// Read session data
+console.debug('Token:', session.get('token'))
+console.debug('User ID:', session.get('userId'))
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Clear specific items
+store.remove('username')
+session.remove('token')
+
+// Clear all
+store.removeAll()
+session.removeAll()
+
+console.debug('\nExample complete!')