memorio 4.7.1 → 4.8.0

package/README.md

@@ -13,7 +13,7 @@
 ![Tests](https://img.shields.io/badge/tests-101%20passed-green)
 ![License](https://img.shields.io/badge/License-MIT-gray)
 
-### One import. Global state, persistence, and a IndexedDB layer — done.
+### One import. Global state, persistence, and a IndexedDB layer - done.
 
 ```javascript
 import 'memorio'
@@ -21,7 +21,7 @@ import 'memorio'
 state.user = { name: 'Sara' }   // reactive, everywhere, instantly
 ```
 
-No provider tree. No reducers. No actions to dispatch before you can change a number. If you've ever set up a global store for an app that just needed *"a value, shared, that updates the UI when it changes,"* memorio is the toolkit for that thirty-second job — and it keeps growing with you: session storage, a cache, typed IndexedDB tables, an observer system, a React hook, devtools, and a change logger, all sharing one mental model.
+No provider tree. No reducers. No actions to dispatch before you can change a number. If you've ever set up a global store for an app that just needed *"a value, shared, that updates the UI when it changes,"* memorio is the toolkit for that thirty-second job - and it keeps growing with you: session storage, a cache, typed IndexedDB tables, an observer system, a React hook, devtools, and a change logger, all sharing one mental model.
 
 ---
 
@@ -31,26 +31,28 @@ No provider tree. No reducers. No actions to dispatch before you can change a nu
 2. [Installation](#installation)
 3. [Quick Start](#quick-start)
 4. [API Reference](#api-reference)
-5. [Cross-Platform Behavior](#cross-platform-behavior)
-6. [Context Isolation (multi-tenant)](#context-isolation-multi-tenant)
-7. [Security](#security)
-8. [License](#license)
+5. [Typed Stores](#typed-stores)
+6. [Schema Validation](#schema-validation)
+7. [Cross-Platform Behavior](#cross-platform-behavior)
+8. [Context Isolation (multi-tenant)](#context-isolation-multi-tenant)
+9. [Security](#security)
+10. [License](#license)
 
 ---
 
 ## Is this for you?
 
-memorio is built for speed of thought: you think "I need this value everywhere," you write one line, it works. That's the entire pitch — and it's a real one, not a rewritten complaint about how much Redux boilerplate you've had to write.
+memorio is built for speed of thought: you think "I need this value everywhere," you write one line, it works. That's the entire pitch - and it's a real one, not a rewritten complaint about how much Redux boilerplate you've had to write.
 
 **Reach for memorio when:**
-- You want state that's simply *there* — no store setup, no provider wrapping your app.
+- You want state that's simply *there* - no store setup, no provider wrapping your app.
 - You want `localStorage`, `sessionStorage`, and `IndexedDB` behind one consistent API instead of learning three.
 - You're prototyping, building an internal tool, or shipping something small-to-medium where iteration speed matters more than architectural ceremony.
 
 **Reach for something else when:**
-- You need every state path statically type-checked against every observer — memorio's `state.foo.bar` and `observer('state.foo.bar', ...)` are connected by a string, not by the compiler, so a rename won't be caught for you.
-- You need Redux-style middleware, action logs, or time-travel debugging as a hard requirement for a large team — those tools exist because that discipline solves real problems at scale, not because their authors enjoy boilerplate.
-- Your isolation requirements are a security boundary, not a convenience — see [Context Isolation](#context-isolation-multi-tenant) before you rely on it for that.
+- You need every state path statically type-checked against every observer - memorio's `state.foo.bar` and `observer('state.foo.bar', ...)` are connected by a string, not by the compiler, so a rename won't be caught for you. However, if you want compiler-checked state access, use `memorio.typed<T>()` (see [Typed Stores](#typed-stores)) which gives you full static types on the global `state` proxy. For runtime validation as well, combine with `memorio.registerSchema()` (see [Schema Validation](#schema-validation)).
+- You need Redux-style middleware, action logs, or time-travel debugging as a hard requirement for a large team - those tools exist because that discipline solves real problems at scale, not because their authors enjoy boilerplate. Memorio logs through `memorio.logger` and inspects via `memorio.devtools`, but doesn't have Redux DevTools time-travel.
+- Your isolation requirements are a security boundary, not a convenience - see [Context Isolation](#context-isolation-multi-tenant) before you rely on it for that.
 
 Pick the right tool. memorio is at its best when the answer to "how much state architecture do I need here?" is genuinely "not much."
 
@@ -63,15 +65,18 @@ npm i memorio
 # pnpm add memorio
 # yarn add memorio
 
-# Optional — only if you use the React hook
+# Optional - only if you use the React hook
 npm i react react-dom
+
+# Optional - only if you want a local sql.js for `sqlite` (default uses CDN)
+npm i sql.js
 ```
 
 ---
 
 ## Quick Start
 
-### Global style — the whole point of memorio
+### Global style - the whole point of memorio
 
 ```typescript
 import 'memorio' // once, at your entry point
@@ -85,7 +90,7 @@ useObserver(
 )
 ```
 
-### Named imports — same instances, explicit about it
+### Named imports - same instances, explicit about it
 
 ```typescript
 import { state, store, session, cache, idb, observer, useObserver, dispatch, memorio } from 'memorio'
@@ -102,13 +107,13 @@ function Counter() {
 }
 ```
 
-Two styles, one engine underneath — use whichever reads better in your codebase.
+Two styles, one engine underneath - use whichever reads better in your codebase.
 
 ---
 
 ## API Reference
 
-### `state` — reactive, volatile, Proxy-based
+### `state` - reactive, volatile, Proxy-based
 
 ```javascript
 state.user = { name: 'Sara', role: 'admin' }
@@ -125,7 +130,7 @@ state.config.maxUsers = 200   // throws: state 'config' is locked
 state.config.unlock()
 ```
 
-### `store` — the value that survives a refresh
+### `store` - the value that survives a refresh
 
 ```javascript
 store.set('preferences', { theme: 'dark' })
@@ -133,21 +138,21 @@ store.get('preferences')      // { theme: 'dark' } or null
 store.isPersistent            // true when backed by real localStorage
 ```
 
-### `session` — lives as long as the tab does
+### `session` - lives as long as the tab does
 
 ```javascript
 session.set('token', 'user-abc-123')
 session.get('token')
 ```
 
-### `cache` — the fastest thing you own, gone on refresh
+### `cache` - the fastest thing you own, gone on refresh
 
 ```javascript
 cache.set('temp', computeExpensiveResult())
 cache.get('temp')
 ```
 
-### `idb` — typed, async, structured tables without the ceremony
+### `idb` - typed, async, structured tables without the ceremony
 
 ```javascript
 await idb.db.create('my-db')
@@ -156,9 +161,91 @@ await idb.data.set('my-db', 'users', { id: 1, name: 'Sara' })
 const user = await idb.data.get('my-db', 'users', 1)
 ```
 
-> IndexedDB is a browser-only primitive — see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
+> IndexedDB is a browser-only primitive - see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
+
+### `sqlite` - in-memory SQLite, zero config
+
+`memorio.sqlite` is an optional, lazily-loaded SQLite engine backed by [`sql.js`](https://sql.js.org) (the optional `sql.js` npm package is **not** a build-time dependency). It runs entirely in memory — ideal for ad-hoc SQL, structured queryable data, and local relational lookups. The engine is fetched on first use and never loaded when you don't touch `sqlite`.
+
+```javascript
+import 'memorio' // or: import { sqlite } from 'memorio'
+
+await sqlite.ready                          // waits until the sql.js engine is loaded (or rejected)
+sqlite.db.support()                         // true when the current platform can run sql.js
+```
+
+Bases (databases) are addressed by name, like `idb`:
+const SQL = await sqlite.db.getSQL()        // the underlying sql.js engine (loaded once, cached)
+sqlite.db.version()                         // engine version string, or null before load
+```
+
+Bases (databases) are addressed by name, like `idb`. `sqlite.db.create('app')` opens (or creates) an in-memory database, while `sqlite.db.get('app')` retrieves an already-open handle (`sqlite.db.list/delete/size` round out the lifecycle):
+
+```javascript
+await sqlite.db.create('app')    // in-memory database handle
+await sqlite.query.run('app', 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)')
+``` `sqlite.data` gives a small shortcut layer, and `sqlite.query` runs SQL:
+
+```javascript
+// Write (shortcut over raw prepare/bind)
+await sqlite.data.set('app', 'users', { id: 1, name: 'Sara' })
+await sqlite.data.get('app', 'users', 1)    // { id: 1, name: 'Sara' }
+
+// SQL
+await sqlite.query.run('app', 'CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT)')
+const rows = await sqlite.query.select('app', 'SELECT * FROM items', [1])
+
+// Portability: export / import a whole base as a binary blob
+const blob = await sqlite.db.export('app')
+await sqlite.db.import('app', blob)
+
+// Clean up
+await sqlite.db.delete('app')
+```
+
+#### Loading the engine
+
+The default loader injects the sql.js UMD build (`sql-wasm-browser.js`) from the
+jsDelivr CDN as a classic `<script>`; on load it exposes the `initSqlJs` factory
+on `globalThis`, which memorio then calls with your `locateFile`. This avoids a
+bare `import('sql.js')` so bundlers never resolve the optional `sql.js`
+dependency at build time:
+
+```javascript
+// Zero config: CDN <script> loader (default)
+await sqlite.ready
+```
+
+If you prefer a local/bundled `sql.js` (offline, private network, or to pin a
+version), install it and supply your own loader:
+
+```bash
+npm i sql.js    # optional peer
+```
+
+```javascript
+import { sqlite } from 'memorio'
+
+sqlite.config({ loader: () => import('sql.js') })   // local/npm build of sql.js
+await sqlite.ready
+```
+
+You can also point the WASM `locateFile` step at your own CDN/base via
+`sqliteWasmBase` on `globalThis`, or pass a custom `locateFile` through
+`sqlite.config({ locateFile })`:
+
+```javascript
+globalThis.sqliteWasmBase = 'https://your-cdn.example.com/sql.js/dist/'
+sqlite.config({ locateFile: (file) => `https://your-cdn.example.com/sql.js/dist/${file}` })
+```
+
+When the engine can't load (e.g. no WASM support), `sqlite.ready` rejects, `sqlite._disabled` becomes `true`, and `sqlite._warning` explains why — `db.support()` simply returns `false` so you can degrade gracefully.
+
+- `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })` snapshot a database to `store` (localStorage, namespaced) and restore it on reopen — sql.js databases are in-memory by default; see [SQLite docs – Persistence & dev download](markdown/SQLITE.md#example-5-persistence--dev-download).
 
-### `observer` / `useObserver` — watch a path, react to it
+See [SQLite docs](markdown/SQLITE.md) for the full reference.
+
+### `observer` / `useObserver` - watch a path, react to it
 
 ```javascript
 observer('state.user', (newVal, oldVal) => {
@@ -168,14 +255,14 @@ observer('state.user', (newVal, oldVal) => {
 
 > Keys here are plain strings, not statically checked against `state`'s shape. Keep the observer near the code that shapes that state, and grep before you rename.
 
-### `dispatch` — the event bus underneath it all
+### `dispatch` - the event bus underneath it all
 
 ```javascript
 memorio.dispatch.listen('state.user', (event) => console.debug(event.detail))
 memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
 ```
 
-### `devtools` — see everything, instantly
+### `devtools` - see everything, instantly
 
 ```javascript
 memorio.devtools.inspect()
@@ -185,32 +272,358 @@ memorio.devtools.exportData()
 
 Pairs with [dphelper-manager](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk) for visual, time-travel inspection of your global state straight from devtools.
 
-### `logger` — a black box for every change
+### `logger` - a black box for every change
 
 ```javascript
 memorio.logger.configure({ enabled: true, logToConsole: true })
 memorio.logger.getHistory()
 ```
 
-> It logs *everything* written to `state`/`store`/`session` — including anything sensitive you put there. Great for debugging, but don't leave it on unconditionally in production if secrets or PII pass through your state. See [Security](#security).
+> It logs *everything* written to `state`/`store`/`session` - including anything sensitive you put there. Great for debugging, but don't leave it on unconditionally in production if secrets or PII pass through your state. See [Security](#security).
+
+---
+
+## Typed Stores
+
+`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation. The returned object is the *exact same* Proxy as `globalThis.state` — no duplication, no overhead.
+
+```typescript
+import 'memorio'
+
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+  items: string[]
+}
+
+const app = memorio.typed<AppState>()
+
+// Type-checked at compile time:
+app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.theme = 'dark'
+
+// TypeScript errors:
+// app.user = { name: 42 }            // age missing, name wrong type
+// app.theme = 'purple'               // not a valid literal
+```
+
+The same data is accessible via the global `state` proxy — `app` and `state` are identical instances:
+
+```typescript
+state.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.user.name   // 'Sara' — same Proxy
+```
+
+For runtime safety (rejecting invalid values even when TypeScript isn't checking), combine with [Schema Validation](#schema-validation) below.
+
+See [Typed Stores docs](markdown/TYPED.md) for full examples.
+
+---
+
+## Schema Validation
+
+`memorio.registerSchema(path, schema)` lets you register runtime validators for state paths. When a write to `state.somePath = value` violates a registered schema, the write is **rejected** before the value is stored.
+
+```typescript
+import 'memorio'
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }  // accepted
+state.user = { name: 'Sara' }                                    // rejected: missing 'email'
+state.user = { name: 42 }                                        // rejected: wrong type
+```
+
+Custom validator functions are also supported:
+
+```typescript
+memorio.registerSchema('theme', (val) => {
+  return val === 'light' || val === 'dark'
+    ? true
+    : 'theme must be "light" or "dark"'
+})
+
+state.theme = 'purple'  // rejected: "theme must be light or dark"
+state.theme = 'dark'    // accepted
+```
+
+Manual validation without writing:
+
+```typescript
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+// { valid: true }
+
+memorio.validate('user', { name: 'Sara' })
+// { valid: false, errors: ["user: missing required property 'email'"] }
+```
+
+Manage registered schemas:
+
+```typescript
+memorio.listSchemas()           // ['user', 'theme']
+memorio.unregisterSchema('theme')  // removes the validator
+```
+
+**Typed + Schema** — combine both for full safety:
+
+```typescript
+interface AppState {
+  user: { name: string; email: string }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
+  }
+})
+
+app.user = { names: 'Sara' }        // ❌ TS: wrong shape
+app.user = { name: '', email: '' }  // ❌ TS passes, ❌ runtime: name too short
+app.user = { name: 'Sara', email: 'sara@test.com' } // ✅ both pass
+```
+
+See [Schema Validation docs](markdown/SCHEMA.md) for the full schema definition reference.
+
+---
+
+## Memory System
+
+`memorio.memory` provides a semantic memory layer — a key/value store with **type safety**, **TTL**, **confidence scoring**, **tagging**, and **scope-based persistence**. It's designed for AI agents and applications that need structured, queryable memory with lifecycle management.
+
+### Core API
+
+```ts
+// remember(key, value, options)
+await memorio.memory.remember('user.language', 'Italian', {
+  type: 'preference',
+  confidence: 0.92,
+  scope: 'local',
+  ttl: null,           // never expires
+  tags: ['ui', 'user'],
+  source: 'conversation'
+})
+
+// recall(key, options)
+const lang = await memorio.memory.recall('user.language')
+// → 'Italian'
+
+// update(key, value, options) — creates a superseded version of the old entry
+await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
+
+// forget(key) — permanently deletes
+await memorio.memory.forget('user.language')
+```
+
+### Scopes
+
+| Scope | Storage | TTL | Cross-session | Size limit |
+|---|---|---|---|---|
+| `hot` | `state` proxy | ✅ | ❌ | ~5MB (RAM) |
+| `session` | `sessionStorage` | ✅ | Tab only | ~5MB |
+| `local` | `localStorage` | ✅ | ✅ | ~10MB |
+| `durable` | `IndexedDB` | ✅ | ✅ | ~1GB+ |
+
+Default scope is `local` for values ≤100KB, `durable` for larger values.
+
+### Context API
+
+```ts
+// context() — returns ranked, relevant memories
+const context = await memorio.memory.context({
+  tags: 'user',
+  types: ['preference', 'decision'],
+  minConfidence: 0.7,
+  maxEntries: 10
+})
+// → [{ key, value, relevance, age, confidence, ... }]
+```
+
+### Memory Entry Model
+
+Each memory is stored as a structured entry:
+
+```ts
+{
+  id: string          // unique identifier
+  key: string         // path-like key (e.g. "user.preference.theme")
+  value: any          // the stored data
+  type: MemoryType    // 'fact' | 'preference' | 'decision' | 'task' | 'context'
+  confidence: number  // 0.0–1.0
+  scope: MemoryScope  // 'hot' | 'session' | 'local' | 'durable'
+  ttl?: number | null // milliseconds (null = never expires)
+  tags: string[]      // for filtering
+  source?: string     // where this memory came from
+  status: MemoryStatus // 'active' | 'obsolete' | 'superseded'
+  createdAt: number   // timestamp
+  lastConfirmedAt: number
+  supersededId?: string | null
+}
+```
+
+### Memory Lifecycle
+
+| Operation | Behavior |
+|---|---|
+| `remember(key, newValue)` when entry exists | Old entry → `superseded` status, new entry → `active` |
+| `recall(key)` | Returns active value; expired entries return `null` unless `includeObsolete: true` |
+| `update(key, value)` | Creates superseded copy + updated active entry |
+| Entry with `ttl` expires | Status → `obsolete` (via `forgetExpired()`) |
+| `clear()` | Wipes all memories + index |
+
+See [Memory docs](markdown/MEMORY.md) for full reference.
+
+---
+
+## Synchronization & Cloud (optional)
+
+`memorio.memory` is **local-first**. The data is created and served from the
+device; the cloud is only ever a **transport/persistence provider**, never the
+source of truth. Enabling sync does not replace local storage — it *mirrors* it.
+
+```
+                    memorio
+                       │
+              ┌────────┴────────┐
+              │   Memory Engine │
+              └────────┬────────┘
+          ┌────────────┼────────────┐
+          ▼            ▼            ▼
+        local      SQLite         cloud
+        memory     durable        sync
+```
+
+### Configuring a backend
+
+Sync is **opt-in**. You supply an application-owned `provider` that knows how to
+talk to your backend (REST, WebSocket, Supabase, a custom agent server, a PostgreSQL
+database, etc.). **Memorio never handles credentials** — authentication and
+authorization live in your backend/provider (OWASP A01: Broken Access Control):
+
+```ts
+memorio.memory.configure({
+  namespace: 'user:123:device:abc',   // tenant/user/device — partitions the journal
+  provider: {                          // application-owned transport
+    push(ops) { return fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops), headers: auth }) }
+    pull(since) { return fetch(`/api/sync?since=${since}`).then(r => r.json()) }
+  },
+  auto: true                           // auto-replay pending ops on focus/online (default true)
+})
+
+await memorio.memory.ready   // waits until the local journal substrate is chosen
+```
+
+Once configured, `memorio.memory` records every operation locally and keeps it
+until the provider acknowledges it.
+
+### The local journal
+
+Every mutation (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`)
+is written to a local, **namespaced** operation journal:
+
+```ts
+await memory.remember('user.language', 'Italian', { scope: 'local' })
+
+memory.journal.pending()      // -> [{ id, key:'user.language', value:'Italian', operation:'remember', sync:'pending', version: 1, updatedAt: ... }]
+memory.journal.markSynced([id])
+memory.journal.replay()       // pushes pending() to provider.provider, marks synced, optional pull+apply
+memory.journal.status()       // 'sqlite' | 'store'  (substrate in use)
+```
+
+The journal stores the full entry plus `operation`, `version`, `updatedAt` and
+`sync` status, so conflicts can be resolved when connectivity returns.
+
+### Substrates
+
+The journal is persisted on `store` (localStorage / in-memory Map fallback) — **not** on a sql.js database, because sql.js databases are volatile (in-memory) and would lose pending operations on reload:
+
+| Substrate | Used for | Notes |
+|---|---|---|
+| `store` (localStorage) | sync journal | persistent across reloads; namespaced; Map fallback in Node |
+| `sqlite` (sql.js) | ad-hoc SQL / value storage | in-memory by default — use `persistence: true` to snapshot to `store` |
+| `idb` (IndexedDB) | `memorio.memory` durable scope values | persistent; persistent across reloads |
+
+The `sqlite.db.download(name)` dev helper also triggers a browser `.sqlite` download of an in-memory database on demand.
+
+### Sync = operations, not database dumps
+
+Memorio syncronizza **operazioni di memoria**, never a raw database dump. When
+two devices diverge, conflict resolution is based on `confidence`,
+`lastConfirmedAt`, `source`, `version` and `scope` — not just "last write wins":
+
+```ts
+// Device A: user.language = Italian, confidence 0.92
+// Device B: user.language = English, confidence 0.61
+// → the higher-confidence entry wins locally; the provider decides for shared.
+```
+
+The `namespace` (tenant / user / device) is the single partition key: local
+journal reads and writes are scoped to it, and they can never cross namespaces —
+a client holding a fake/forged namespace simply sees its own empty journal.
+
+### Scopes (isolation, not a security boundary)
+
+```
+scope: 'device'   // only this browser/device
+scope: 'user'      // follows the user across devices (via sync)
+scope: 'shared'   // shared across users/tenant
+```
+
+`scope: 'user'`/`'shared'` require a provider + namespace. `scope: 'device'`
+is local only. As with `memorio.createContext`, **scoping is a naming convention,
+not a security boundary** — enforce real isolation in your backend.
+
+### Security posture
+
+- **NIST SP 800-53 / OWASP**: no credentials, tokens, or secrets are read from or
+  stored by `memorio`; sensitive state you place in `state`/`store`/`session`/`idb`
+  is not encrypted by memorio (see [Security](#security)).
+- **Namespace isolation**: journal reads/writes are keyed by
+  `namespace:id` at the storage layer; there is no API to enumerate or open
+  another namespace's journal (defense-in-depth).
+- **No dynamic code**: journal entries are strictly JSON-round-tripped and
+  size-capped (10 MB/entry); no `eval`/template-injection of provider data.
+- **Trust boundary**: the provider/backend owns authentication, authorization,
+  and remote-side conflict resolution. Memorio owns the local durable copy and
+  the operation log; it surfaces `conflict`/`error` rows via `journal.pending()`.
+- **NSA/CISA advice (data-at-rest/secrets)**: if you persist `state`/`store`
+  server-side or ship user data through your backend, encrypt it server-side with
+  keys you manage; memorio treats the local journal as untrusted-from-the-browser
+  and does not attest its own integrity.
+
+See [SQLite docs](markdown/SQLITE.md), [Memory docs](markdown/MEMORY.md), and the [Synchronization & Cloud guide](markdown/SYNC.md).
 
 ---
 
 ## Cross-Platform Behavior
 
-memorio runs everywhere JavaScript does — but "everywhere" means different guarantees in different places, and we'd rather tell you now than have you find out at 2am:
+memorio runs everywhere JavaScript does - but "everywhere" means different guarantees in different places, and we'd rather tell you now than have you find out at 2am:
 
 | API | Browser | Node.js | Deno | Edge / Workers |
 |---|---|---|---|---|
 | `state` | Proxy in memory | Proxy in memory | Proxy in memory | Proxy in memory |
 | `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
 | `cache` | ✅ in memory | ✅ in memory | ✅ in memory | ✅ in memory |
-| `store` | `localStorage` | `Map` fallback — **not durable across restarts** | `Map` fallback — not durable | `localStorage` where available, else `Map` |
-| `session` | `sessionStorage` | `Map` fallback — not durable | `Map` fallback — not durable | `sessionStorage` where available, else `Map` |
+| `store` | `localStorage` | `Map` fallback - **not durable across restarts** | `Map` fallback - not durable | `localStorage` where available, else `Map` |
+| `session` | `sessionStorage` | `Map` fallback - not durable | `Map` fallback - not durable | `sessionStorage` where available, else `Map` |
 | `idb` | ✅ `IndexedDB` | ❌ not available | ❌ not available | ⚠️ check `getCapabilities()` |
+| `sqlite` | ✅ `sql.js` (lazy, CDN by default) | ❌ not available | ❌ not available | ⚠️ check `sqlite.db.support()` |
 | `devtools` | ✅ | ❌ | ❌ | ⚠️ |
 
-Same API top to bottom — that's the promise. But if your server code leans on `store.get(...)` surviving a redeploy, know that on Node/Deno it won't; the fallback is an in-memory cache with the same shape, not durable storage.
+Same API top to bottom - that's the promise. But if your server code leans on `store.get(...)` surviving a redeploy, know that on Node/Deno it won't; the fallback is an in-memory cache with the same shape, not durable storage.
 
 ```javascript
 memorio.isBrowser()
@@ -234,10 +647,10 @@ const ctx = memorio.createContext('tenant-123')
 ctx.state.user = { name: 'Isolated' }
 ctx.store.set('settings', { theme: 'dark' })
 
-console.debug(state.user) // undefined — separate namespace
+console.debug(state.user) // undefined - separate namespace
 ```
 
-Handy for keeping per-tenant or per-request state from colliding in the same process. Under the hood it's a key prefix (`tenant-123-key`) inside the same storage — a naming convention, not a hard memory boundary. Great for a browser tab; if you're running this in a shared Node.js process or an edge isolate that might be reused across requests, make sure tenant IDs can't collide or be forged, and don't treat this as your only isolation layer if the stakes are real.
+Handy for keeping per-tenant or per-request state from colliding in the same process. Under the hood it's a key prefix (`tenant-123-key`) inside the same storage - a naming convention, not a hard memory boundary. Great for a browser tab; if you're running this in a shared Node.js process or an edge isolate that might be reused across requests, make sure tenant IDs can't collide or be forged, and don't treat this as your only isolation layer if the stakes are real.
 
 ---
 
@@ -248,9 +661,9 @@ Handy for keeping per-tenant or per-request state from colliding in the same pro
 - Session IDs generated via `crypto.randomUUID`.
 - Inputs validated, keys sanitized, errors caught at module boundaries.
 
-memorio does **not** encrypt what you put into `store`, `session`, or `idb` — they're thin, fast wrappers over `localStorage`/`sessionStorage`/`IndexedDB`, which store data in the clear on the user's device. Bring your own encryption layer for tokens, secrets, or regulated personal data.
+memorio does **not** encrypt what you put into `store`, `session`, or `idb` - they're thin, fast wrappers over `localStorage`/`sessionStorage`/`IndexedDB`, which store data in the clear on the user's device. Bring your own encryption layer for tokens, secrets, or regulated personal data.
 
-We build with recognized engineering guidance (NIST SP 800-53 practices) as an input to how we write code — that's a design discipline, not a compliance certificate, and no third-party audit has been performed. Found an issue? Report it privately — see `SECURITY.md` — rather than opening a public issue.
+We build with recognized engineering guidance (NIST SP 800-53 practices) as an input to how we write code - that's a design discipline, not a compliance certificate, and no third-party audit has been performed. Found an issue? Report it privately - see `SECURITY.md` - rather than opening a public issue.
 
 ---
 

package/SECURITY.md

@@ -24,15 +24,15 @@ Memorio follows NIST and NSA security standards at the enterprise level.
 ## OWASP Compliance
 
 Addresses OWASP Top 10 (2021):
-- A01:2021 — Broken Access Control (global object protection, property locks)
-- A02:2021 — Cryptographic Failures (crypto.randomUUID for session IDs)
-- A03:2021 — Injection (CSS sanitization in devtools)
-- A05:2021 — Security Misconfiguration (minimal surface area, no bundled secrets)
-- A06:2021 — Vulnerable and Outdated Components (regular npm audit, Socket.dev)
-- A07:2021 — Identification and Authentication Failures (N/A — library, no auth)
-- A08:2021 — Software and Data Integrity Failures (strict tsconfig, lock files)
-- A09:2021 — Security Logging and Monitoring Failures (DevTools inspect, Logger module)
-- A10:2021 — Server-Side Request Forgery (N/A — no network requests)
+- A01:2021 - Broken Access Control (global object protection, property locks)
+- A02:2021 - Cryptographic Failures (crypto.randomUUID for session IDs)
+- A03:2021 - Injection (CSS sanitization in devtools)
+- A05:2021 - Security Misconfiguration (minimal surface area, no bundled secrets)
+- A06:2021 - Vulnerable and Outdated Components (regular npm audit, Socket.dev)
+- A07:2021 - Identification and Authentication Failures (N/A - library, no auth)
+- A08:2021 - Software and Data Integrity Failures (strict tsconfig, lock files)
+- A09:2021 - Security Logging and Monitoring Failures (DevTools inspect, Logger module)
+- A10:2021 - Server-Side Request Forgery (N/A - no network requests)
 
 ## Reporting Security Issues
 
@@ -44,5 +44,5 @@ If you find a security vulnerability:
 Do not open public issues for security vulnerabilities.
 
 ---
-*Document version: 2.0 — Last updated: 2026-05-19*
+*Document version: 2.0 - Last updated: 2026-05-19*
 *Owner: BigLogic Security Team*