memorio 5.0.0 → 5.1.1

package/adr/006-context-isolation.md

@@ -1,92 +1,91 @@
-# 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`
+# 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

@@ -2,7 +2,6 @@
 
 > **Status:** Accepted
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 
 ## Context
 
@@ -59,12 +58,12 @@ interface MutationRecord {
 ### Guarantees
 
 1. **Every mutation gets a unique ID.** The ID is generated via
-   `generateMutationId()` which calls `hlc.tick()` — guaranteeing
+   `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,
+   the record - only plain values. This ensures serializable,
    comparison-safe records.
 
 3. **Single write point.** `internal.recordMutation()` is the only
@@ -73,7 +72,7 @@ interface MutationRecord {
 
 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
+   must NOT clear the redo stack - undo/redo use
    `internal.historyEnabled = false` to bypass `recordMutation`.
 
 5. **Max history depth.** Both stacks are trimmed to
@@ -107,8 +106,8 @@ transaction's mutation list.
 - **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
+  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.
 

package/adr/008-transactions.md

@@ -2,7 +2,6 @@
 
 > **Status:** Accepted
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 
 ## Context
 
@@ -53,7 +52,7 @@ abortTransaction()
 
 `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
+transaction remains active in the registry - it is **not** suspended
 or paused. `commitTransaction()` only commits the **most recently
 started** active transaction.
 
@@ -84,20 +83,20 @@ Once committed or aborted, a transaction's `mutations` list is frozen
 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
+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
+  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) —
+- **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
+  `before` values to be present in the MutationRecord - for
   very large objects this is memory-intensive.
 
 ## Compliance tests

package/adr/009-history-model.md

@@ -2,7 +2,6 @@
 
 > **Status:** Proposed
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 
 ## Context
 
@@ -31,7 +30,7 @@ the full Commit → Snapshot → Delta model.
 - `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.
+- No commit concept exists - every mutation is an individual entry.
 
 ### Target state (Memorio 5.0)
 
@@ -48,7 +47,7 @@ Commit (immutable, append-only)
 - **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. 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
@@ -88,16 +87,16 @@ Commit (immutable, append-only)
 
 ## Consequences
 
-- **Positive:** Commits group mutations logically — essential for
+- **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
+- **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.
+  between memory and CPU - defaults must be benchmark-driven.
 
 ## Compliance tests
 
@@ -106,5 +105,5 @@ Commit (immutable, append-only)
 
 ## Benchmarks
 
-- `experimental/benchmarks/replay.bench.ts` — measures replay cost
+- `experimental/benchmarks/replay.bench.ts` - measures replay cost
   with and without interval snapshots.

package/adr/README.md

@@ -1,46 +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.
+# 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

@@ -1,49 +1,48 @@
-# 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
+# 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;
+}