memorio 5.0.0 → 5.1.0

package/markdown/PLATFORM.md

@@ -1,271 +1,277 @@
-# Platform & Context Isolation - Memorio
-
-> ℹ️ **New in v2.7.0, expanded in v3.0.2**: Context isolation system for multi-tenant server-side applications
-
-Memorio automatically detects the runtime environment and adapts its behavior accordingly. This document explains platform compatibility, session isolation, and the new context system.
-
----
-
-## Quick Reference: Client vs Server
-
-### Which Module to Use?
-
-| Scenario | Recommended Module | Persistence |
-|----------|-------------------|-------------|
-| UI State (React/components) | `state` | Memory |
-| Temporary computed data | `cache` | Memory |
-| User preferences | `store` | Browser localStorage |
-| Auth tokens | `session` | Browser sessionStorage |
-| Large offline data | `idb` | IndexedDB |
-| Server request isolation | `memorio.createContext()` | Memory |
-
-### Module Availability
-
-| Module | Browser | Node.js | Deno | Edge |
-|--------|--------|---------|------|------|
-| `state` | ✅ | ✅ | ✅ | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
-| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
-| `idb` | ✅ | ❌ | ❌ | ⚠️ |
-| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
-| `devtools` | ✅ | ❌ | ❌ | ❌ |
-
----
-
-## Platform Detection
-
-Memorio automatically detects the environment on import:
-
-```javascript
-import { memorio, store } from 'memorio';
-
-// Check current platform
-console.debug(memorio.getCapabilities().platform); // 'browser' | 'node' | 'deno' | 'edge'
-console.debug(store.isPersistent); // true if using real localStorage
-```
-
-### Available Platform APIs
-
-```javascript
-// Check platform
-memorio.isBrowser()    // true in browser
-memorio.isNode()      // true in Node.js
-memorio.isDeno()      // true in Deno
-memorio.isEdge()      // true in Edge Workers
-
-// Get capabilities
-const caps = memorio.getCapabilities();
-// caps.platform, caps.hasSessionStorage, caps.hasLocalStorage, etc.
-```
-
----
-
-## Platform Compatibility Matrix
-
-| Feature | Browser | Node.js | Deno | Edge Workers |
-|---------|---------|---------|------|--------------|
-| `state` | ✅ | ✅ | ✅ | ✅ |
-| `observer` | ✅ | ✅ | ✅ | ✅ |
-| `useObserver` | ✅ | ⚠️ React only | ⚠️ React only | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
-| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
-| `idb` | ✅ | ❌ | ❌ | ⚠️ |
-
-- ✅ Full support
-- ⚠️ Partial support (fallback to in-memory)
-- ❌ Not available
-
----
-
-## Client vs Server Usage
-
-### 🖥️ Client-Side (Browser)
-
-All features work with real browser storage:
-
-```javascript
-import { store, session, idb } from 'memorio'
-
-// Store - persistent localStorage
-store.set('preferences', { theme: 'dark' });
-store.isPersistent; // true
-
-// Session - temporary sessionStorage
-session.set('token', 'jwt-token');
-session.isPersistent; // true (survives refresh)
-
-// IDB - large data storage
-idb.db.create('myApp');
-```
-
-### 🖥️ Server-Side (Node.js/Deno)
-
-Use `state` and `cache` for in-memory data. Store/session fall back to memory:
-
-```javascript
-import { state, store, session, cache } from 'memorio'
-
-// State - in-memory global state
-state.user = { name: 'Server User' };
-
-// Cache - in-memory temporary cache
-cache.set('apiResponse', data);
-
-// Store - in-memory fallback (not persistent)
-store.set('temp', data);
-store.isPersistent; // false - data lost on restart
-
-// Session - in-memory fallback
-session.set('requestData', data);
-session.isPersistent; // false - data lost on restart
-```
-
----
-
-## Session Isolation
-
-Each instance/session gets unique storage keys to prevent conflicts:
-
-```javascript
-// Without context: "memorio_store_[sessionId]_key"
-// With context: "[contextName]-key"
-```
-
-This ensures:
-- Multiple browser tabs don't share session data
-- Server-side requests are isolated
-
----
-
-## Context Isolation (Server-Side Multi-Tenancy)
-
-> ⚠️ **Server-Side Only**: This feature is designed for multi-tenant server environments (Node.js, Deno). Not needed for client-side applications.
-
-For server-side applications handling multiple tenants (e.g., different users/requests), use **contexts** to isolate data:
-
-### Creating a Context
-
-```javascript
-import { memorio, state } from 'memorio'
-
-// Create isolated context for a user/session
-const ctx = memorio.isolate('user-123');
-
-// Keys in store/session are prefixed with context name
-// store: "user-123-key"
-// session: "user-123-key"
-
-// Use context's isolated storage
-ctx.state.user = { name: 'Isolated User' };
-ctx.store.set('settings', { theme: 'dark' });
-ctx.session.set('token', 'abc123');
-ctx.cache.set('temp', data);
-
-// Context is completely isolated from global state
-console.debug(state.user); // undefined - global state is separate
-```
-
-### Managing Contexts
-
-```javascript
-// List all contexts
-const contexts = memorio.listContexts();
-console.debug(contexts); // ['user-123', 'user-456', ...]
-
-// Delete a context (cleanup)
-memorio.deleteContext('user-123');
-```
-
-> **Note**: `memorio.isolate('name')` is a shorthand alias for creating isolated contexts.
-
-### Context Use Cases
-
-#### 1. Per-Request Isolation (Express/Fastify)
-
-```javascript
-// Middleware to isolate each request
-app.use((req, res, next) => {
-  const ctx = memorio.createContext(`req-${req.id}`);
-  req.memorioContext = ctx;
-  next();
-});
-
-// In route handler
-app.get('/user', (req, res) => {
-  const ctx = req.memorioContext;
-  ctx.state.user = getUserData();
-  // Each request has isolated state
-});
-```
-
-#### 2. Multi-Tenant SaaS
-
-```javascript
-// Each tenant gets isolated storage
-function handleTenant(tenantId) {
-  const ctx = memorio.createContext(tenantId);
-
-  ctx.state.config = getTenantConfig(tenantId);
-  ctx.store.set('data', tenantData);
-
-  return ctx;
-}
-```
-
----
-
-## Best Practices
-
-### Client-Side (Browser)
-
-1. Use `store` for persistent data (preferences, user settings)
-2. Use `session` for temporary data (auth tokens)
-3. Use `cache` for computed values
-4. Use `state` for reactive UI state
-
-### Server-Side (Node.js/Deno)
-
-1. Use `memorio.createContext()` for each request/tenant
-2. Don't use global `state`/`store`/`session` across requests
-3. Use `cache` for request-scoped caching
-4. Check `store.isPersistent` / `session.isPersistent` if persistence matters
-
-### Edge Workers
-
-Same as browser - localStorage and sessionStorage are available.
-
----
-
-## API Reference
-
-### Global Functions
-
-| Function | Returns | Description |
-|----------|---------|-------------|
-| `memorio.isBrowser()` | `boolean` | Check if running in browser |
-| `memorio.isNode()` | `boolean` | Check if running in Node.js |
-| `memorio.isDeno()` | `boolean` | Check if running in Deno |
-| `memorio.isEdge()` | `boolean` | Check if running in Edge |
-| `memorio.getCapabilities()` | `object` | Get platform capabilities |
-
-### Context Management
-
-| Function | Returns | Description |
-|----------|---------|-------------|
-| `memorio.isolate(name?)` | `Context` | Create isolated context |
-| `memorio.listContexts()` | `string[]` | List all context IDs |
-| `memorio.deleteContext(id)` | `boolean` | Delete a context |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `memorio.version` | `string` | Memorio version |
-| `memorio.getCapabilities().platform` | `string` | Current platform |
-| `memorio.isBrowser()` / `isNode()` / `isDeno()` / `isEdge()` | `boolean` | Platform checks |
-| `memorio._sessionId` | `string` | Unique session identifier |
-
-> **Classic `import`**: context APIs are also named exports.
-> `import { createContext, listContexts, deleteContext, isolate } from 'memorio'`.
+# Platform & Context Isolation - Memorio
+
+> ℹ️ **New in v2.7.0, expanded in v3.0.2**: Context isolation system for multi-tenant server-side applications
+
+Memorio automatically detects the runtime environment and adapts its behavior accordingly. This document explains platform compatibility, session isolation, and the new context system.
+
+---
+
+## Quick Reference: Client vs Server
+
+### Which Module to Use?
+
+| Scenario | Recommended Module | Persistence |
+|----------|-------------------|-------------|
+| UI State (React/components) | `state` | Memory |
+| Temporary computed data | `cache` | Memory |
+| User preferences | `store` | Browser localStorage |
+| Auth tokens | `session` | Browser sessionStorage |
+| Large offline data | `idb` | IndexedDB |
+| Server request isolation | `memorio.createContext()` | Memory |
+
+### Module Availability
+
+| Module | Browser | Node.js | Bun | Deno | Edge |
+|--------|--------|---------|-----|------|------|
+| `state` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ✅* | ⚠️ (memory) | ✅ |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
+| `idb` | ✅ | ❌ | ❌ | ❌ | ⚠️ |
+| `sqlite` | ✅ (sql.js) | ❌ | ✅ (native `bun:sqlite`) | ❌ | ⚠️ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ⚠️ | ✅ |
+| `devtools` | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+*Bun: `store` uses `localStorage` when available (Bun 1.x+), falls back to memory otherwise.
+
+> ⚠️ **Bun row added from project notes, not verified against source for this document.** Confirm against `core/platform.ts` before publishing.
+
+---
+
+## Platform Detection
+
+Memorio automatically detects the environment on import:
+
+```javascript
+import { memorio, store } from 'memorio';
+
+// Check current platform
+console.debug(memorio.getCapabilities().platform); // 'browser' | 'node' | 'bun' | 'deno' | 'edge'
+console.debug(store.isPersistent); // true if using real localStorage
+```
+
+### Available Platform APIs
+
+```javascript
+// Check platform
+memorio.isBrowser()    // true in browser
+memorio.isNode()      // true in Node.js
+memorio.isBun()       // true in Bun
+memorio.isDeno()      // true in Deno
+memorio.isEdge()      // true in Edge Workers
+
+// Get capabilities
+const caps = memorio.getCapabilities();
+// caps.platform, caps.hasSessionStorage, caps.hasLocalStorage, caps.hasBunSqlite, etc.
+```
+
+---
+
+## Platform Compatibility Matrix
+
+| Feature | Browser | Node.js | Deno | Edge Workers |
+|---------|---------|---------|------|--------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` | ✅ | ✅ | ✅ | ✅ |
+| `useObserver` | ✅ | ⚠️ React only | ⚠️ React only | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+
+- ✅ Full support
+- ⚠️ Partial support (fallback to in-memory)
+- ❌ Not available
+
+---
+
+## Client vs Server Usage
+
+### 🖥️ Client-Side (Browser)
+
+All features work with real browser storage:
+
+```javascript
+import { store, session, idb } from 'memorio'
+
+// Store - persistent localStorage
+store.set('preferences', { theme: 'dark' });
+store.isPersistent; // true
+
+// Session - temporary sessionStorage
+session.set('token', 'jwt-token');
+session.isPersistent; // true (survives refresh)
+
+// IDB - large data storage
+idb.db.create('myApp');
+```
+
+### 🖥️ Server-Side (Node.js/Deno)
+
+Use `state` and `cache` for in-memory data. Store/session fall back to memory:
+
+```javascript
+import { state, store, session, cache } from 'memorio'
+
+// State - in-memory global state
+state.user = { name: 'Server User' };
+
+// Cache - in-memory temporary cache
+cache.set('apiResponse', data);
+
+// Store - in-memory fallback (not persistent)
+store.set('temp', data);
+store.isPersistent; // false - data lost on restart
+
+// Session - in-memory fallback
+session.set('requestData', data);
+session.isPersistent; // false - data lost on restart
+```
+
+---
+
+## Session Isolation
+
+Each instance/session gets unique storage keys to prevent conflicts:
+
+```javascript
+// Without context: "memorio_store_[sessionId]_key"
+// With context: "[contextName]-key"
+```
+
+This ensures:
+- Multiple browser tabs don't share session data
+- Server-side requests are isolated
+
+---
+
+## Context Isolation (Server-Side Multi-Tenancy)
+
+> ⚠️ **Server-Side Only**: This feature is designed for multi-tenant server environments (Node.js, Deno). Not needed for client-side applications.
+
+For server-side applications handling multiple tenants (e.g., different users/requests), use **contexts** to isolate data:
+
+### Creating a Context
+
+```javascript
+import { memorio, state } from 'memorio'
+
+// Create isolated context for a user/session
+const ctx = memorio.isolate('user-123');
+
+// Keys in store/session are prefixed with context name
+// store: "user-123-key"
+// session: "user-123-key"
+
+// Use context's isolated storage
+ctx.state.user = { name: 'Isolated User' };
+ctx.store.set('settings', { theme: 'dark' });
+ctx.session.set('token', 'abc123');
+ctx.cache.set('temp', data);
+
+// Context is completely isolated from global state
+console.debug(state.user); // undefined - global state is separate
+```
+
+### Managing Contexts
+
+```javascript
+// List all contexts
+const contexts = memorio.listContexts();
+console.debug(contexts); // ['user-123', 'user-456', ...]
+
+// Delete a context (cleanup)
+memorio.deleteContext('user-123');
+```
+
+> **Note**: `memorio.isolate('name')` is a shorthand alias for creating isolated contexts.
+
+### Context Use Cases
+
+#### 1. Per-Request Isolation (Express/Fastify)
+
+```javascript
+// Middleware to isolate each request
+app.use((req, res, next) => {
+  const ctx = memorio.createContext(`req-${req.id}`);
+  req.memorioContext = ctx;
+  next();
+});
+
+// In route handler
+app.get('/user', (req, res) => {
+  const ctx = req.memorioContext;
+  ctx.state.user = getUserData();
+  // Each request has isolated state
+});
+```
+
+#### 2. Multi-Tenant SaaS
+
+```javascript
+// Each tenant gets isolated storage
+function handleTenant(tenantId) {
+  const ctx = memorio.createContext(tenantId);
+
+  ctx.state.config = getTenantConfig(tenantId);
+  ctx.store.set('data', tenantData);
+
+  return ctx;
+}
+```
+
+---
+
+## Best Practices
+
+### Client-Side (Browser)
+
+1. Use `store` for persistent data (preferences, user settings)
+2. Use `session` for temporary data (auth tokens)
+3. Use `cache` for computed values
+4. Use `state` for reactive UI state
+
+### Server-Side (Node.js/Deno)
+
+1. Use `memorio.createContext()` for each request/tenant
+2. Don't use global `state`/`store`/`session` across requests
+3. Use `cache` for request-scoped caching
+4. Check `store.isPersistent` / `session.isPersistent` if persistence matters
+
+### Edge Workers
+
+Same as browser - localStorage and sessionStorage are available.
+
+---
+
+## API Reference
+
+### Global Functions
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `memorio.isBrowser()` | `boolean` | Check if running in browser |
+| `memorio.isNode()` | `boolean` | Check if running in Node.js |
+| `memorio.isDeno()` | `boolean` | Check if running in Deno |
+| `memorio.isEdge()` | `boolean` | Check if running in Edge |
+| `memorio.getCapabilities()` | `object` | Get platform capabilities |
+
+### Context Management
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `memorio.isolate(name?)` | `Context` | Create isolated context |
+| `memorio.listContexts()` | `string[]` | List all context IDs |
+| `memorio.deleteContext(id)` | `boolean` | Delete a context |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `memorio.version` | `string` | Memorio version |
+| `memorio.getCapabilities().platform` | `string` | Current platform |
+| `memorio.isBrowser()` / `isNode()` / `isDeno()` / `isEdge()` | `boolean` | Platform checks |
+| `memorio._sessionId` | `string` | Unique session identifier |
+
+> **Classic `import`**: context APIs are also named exports.
+> `import { createContext, listContexts, deleteContext, isolate } from 'memorio'`.

package/markdown/REDUX.md

@@ -0,0 +1,54 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Redux and other state managers - Memorio
+
+> Skip this unless you already use Redux.
+
+> **Your state manager owns application state. Memorio owns memory.**
+
+```ts
+import { createMemorioReduxBridge } from 'memorio/redux'
+
+const memorioRedux = createMemorioReduxBridge<AppState>({
+  mappings: {
+    'user.preferences': {
+      selector: state => state.user.preferences,
+      type: 'preference',
+      scope: 'local',
+      tags: ['app', 'user']
+    },
+    'user.name': state => state.user.name
+  },
+  whitelist: ['user/preferencesChanged', 'user/nameChanged'],
+  debug: true
+})
+
+const store = createStore(reducer, applyMiddleware(memorioRedux.middleware))
+
+await memorioRedux.hydrate(store, {
+  onHydration(values) { store.dispatch(restorePreferences(values)) }
+})
+```
+
+```text
+Redux ─────────────→ memorio        memorio ───────────→ Redux
+application state    durable memory                     bootstrap hydration (one-shot)
+```
+
+The bridge persists only mapped selectors, never mirrors the full tree, coalesces bursts, and never breaks Redux dispatch if Memorio fails.
+
+| | Redux | Memorio |
+|---|---|---|
+| Core model | single store | independent runtime layers |
+| State changes | actions + reducers | direct reactive mutation |
+| Persistence | external integration | built in |
+| Structured memory | - | native |
+| Offline memory sync | - | supported |
+| Time-travel debugging | mature | State Intelligence (in progress) |
+| Production dependencies | ecosystem-dependent | zero in core |
+
+Use Redux when you need its action-pipeline discipline and ecosystem. Use Memorio when you want state, persistence, and structured memory under one runtime. You can use both.

package/markdown/SCHEMA.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/SESSION.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/SQLITE.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/STATE.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/STORE.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/SYNC.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >