memorio 4.7.1 → 4.8.0

package/llms.txt

@@ -8,7 +8,7 @@
 npm i memorio
 ```
 
-> **For AI agents generating code against this library:** default `state` is a shared, global namespace unless a context is explicitly created with `memorio.createContext(id)`. Do not assume per-request or per-tab isolation is automatic — see [Session & Context Isolation](#session--context-isolation) before generating server-side code that handles more than one user/request.
+> **For AI agents generating code against this library:** default `state` is a shared, global namespace unless a context is explicitly created with `memorio.createContext(id)`. Do not assume per-request or per-tab isolation is automatic - see [Session & Context Isolation](#session--context-isolation) before generating server-side code that handles more than one user/request.
 
 ## Core Concepts
 
@@ -20,7 +20,7 @@ Memorio provides 6 storage modules plus utilities:
 | `store` | localStorage persistence | Survives browser refresh; falls back to non-durable in-memory `Map` in Node.js/Deno |
 | `session` | sessionStorage | Dies with browser tab; falls back to non-durable in-memory `Map` in Node.js/Deno |
 | `cache` | In-memory cache | Fastest read, no persistence |
-| `idb` | IndexedDB | Structured, async, persistent (browser-only — disabled in Node.js/Deno) |
+| `idb` | IndexedDB | Structured, async, persistent (browser-only - disabled in Node.js/Deno) |
 | `observer` | Object watcher | Legacy; string-based paths, not statically checked against `state`'s shape |
 | `useObserver` | React hook | Auto-discovery of state paths |
 
@@ -42,7 +42,7 @@ useObserver(
 
 ## API Reference
 
-### `state` — Reactive State
+### `state` - Reactive State
 
 Global, Proxy-based, reactive state management.
 
@@ -65,21 +65,21 @@ state.remove('items')
 state.removeAll()
 ```
 
-**Locking — VERIFY BEFORE PUBLISHING:** this library's own documents currently disagree on scope.
+**Locking - VERIFY BEFORE PUBLISHING:** this library's own documents currently disagree on scope.
 
 - One source describes **per-key** locking: `state.config.lock()` freezes only the `config` key; other keys remain writable.
 - Another source describes **global** locking: `state.lock()` / `state.unlock()` freezing the entire `state` object at once.
 
-These are materially different behaviors — confirm against the actual source which one (or both, with distinct method names) is implemented, then replace this note with the real signature(s). Do not ship a docs update, or generate code against this section, until this is resolved.
+These are materially different behaviors - confirm against the actual source which one (or both, with distinct method names) is implemented, then replace this note with the real signature(s). Do not ship a docs update, or generate code against this section, until this is resolved.
 
 **Features:**
 - Automatic path tracking via `__path` property
 - Nested proxy support
 - Auto-dispatches events on changes
 
-### `store` — localStorage Persistence
+### `store` - localStorage Persistence
 
-Persistent storage that survives browser refresh. On Node.js/Deno this falls back to an in-memory `Map` that does **not** survive a process restart — treat it as a same-shape cache there, not durable storage.
+Persistent storage that survives browser refresh. On Node.js/Deno this falls back to an in-memory `Map` that does **not** survive a process restart - treat it as a same-shape cache there, not durable storage.
 
 ```javascript
 // Set
@@ -109,9 +109,9 @@ console.debug(store.isPersistent)  // true → real localStorage
 await store.quota()  // [usage, quota] in KB
 ```
 
-> **`store.quota()` currently returns `[0, 0]` for the `localStorage` backend** — it is not a real usage reading for that backend, it's a placeholder. Don't use it to make capacity decisions until it's implemented for `localStorage`; it may be meaningful for other backends (e.g. `idb`), but confirm before relying on it there too.
+> **`store.quota()` currently returns `[0, 0]` for the `localStorage` backend** - it is not a real usage reading for that backend, it's a placeholder. Don't use it to make capacity decisions until it's implemented for `localStorage`; it may be meaningful for other backends (e.g. `idb`), but confirm before relying on it there too.
 
-### `session` — sessionStorage
+### `session` - sessionStorage
 
 Storage that dies when browser tab closes. Same Node.js/Deno `Map` fallback caveat as `store` applies here.
 
@@ -140,7 +140,7 @@ console.debug(session.size(), 'chars stored')
 console.debug(session.isPersistent)
 ```
 
-### `cache` — In-Memory Cache
+### `cache` - In-Memory Cache
 
 Fastest possible read, data lost on refresh.
 
@@ -167,9 +167,9 @@ const value = cache['myKey']
 delete cache['myKey']
 ```
 
-### `idb` — IndexedDB
+### `idb` - IndexedDB
 
-Structured, persistent, async database (browser-only). **Disabled in Node.js/Deno** — calls will warn and no-op; use `store` or `session` there instead.
+Structured, persistent, async database (browser-only). **Disabled in Node.js/Deno** - calls will warn and no-op; use `store` or `session` there instead.
 
 ```javascript
 // Create database
@@ -206,9 +206,9 @@ if (idb.db.support()) {
 }
 ```
 
-Always guard `idb` calls with `idb.db.support()` (or `memorio.getCapabilities().hasIndexedDB`) in code that might run outside a browser — don't rely on the no-op warning alone.
+Always guard `idb` calls with `idb.db.support()` (or `memorio.getCapabilities().hasIndexedDB`) in code that might run outside a browser - don't rely on the no-op warning alone.
 
-### `observer` — Object Watcher
+### `observer` - Object Watcher
 
 Legacy observer API. Prefer `useObserver` in React code.
 
@@ -231,9 +231,9 @@ console.debug(observer.list)
 observer.removeAll()
 ```
 
-> Paths are plain strings and are not checked against `state`'s actual shape at compile time or at registration time. A typo or a later rename of the corresponding `state` key will fail silently — the observer simply never fires again.
+> Paths are plain strings and are not checked against `state`'s actual shape at compile time or at registration time. A typo or a later rename of the corresponding `state` key will fail silently - the observer simply never fires again.
 
-### `useObserver` — React Hook
+### `useObserver` - React Hook
 
 Primary way to observe state changes in React components.
 
@@ -264,7 +264,7 @@ function Counter() {
 - Returns a cleanup function to stop monitoring
 - Supports both Proxy objects and string paths
 
-### `devtools` — Inspection Tools
+### `devtools` - Inspection Tools
 
 Browser-only (see [Cross-Platform Support](#cross-platform-support)); no-ops or unavailable in Node.js/Deno.
 
@@ -284,9 +284,9 @@ $session  // globalThis.session
 $cache    // globalThis.cache
 ```
 
-### `logger` — Change Tracking
+### `logger` - Change Tracking
 
-Records every write it's configured to track, with timestamps — including whatever values you pass in.
+Records every write it's configured to track, with timestamps - including whatever values you pass in.
 
 ```javascript
 memorio.logger.configure({
@@ -301,7 +301,7 @@ memorio.logger.clearHistory()
 memorio.logger.exportLogs()   // JSON string of all history
 ```
 
-> The `value` field in each history entry is whatever was written — tokens, PII, anything. Don't enable `logger` unconditionally in production paths that handle sensitive data, and don't wire `exportLogs()` output anywhere it could leak (analytics, error reporters, support tooling) without redaction.
+> The `value` field in each history entry is whatever was written - tokens, PII, anything. Don't enable `logger` unconditionally in production paths that handle sensitive data, and don't wire `exportLogs()` output anywhere it could leak (analytics, error reporters, support tooling) without redaction.
 
 ## Platform Detection
 
@@ -317,7 +317,7 @@ const caps = memorio.getCapabilities()
 // { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, sessionId: 'uuid', ... }
 ```
 
-Prefer checking `getCapabilities()` over assuming a platform from context — especially before calling `idb` or relying on `store`/`session` durability.
+Prefer checking `getCapabilities()` over assuming a platform from context - especially before calling `idb` or relying on `store`/`session` durability.
 
 ## Cross-Platform Support
 
@@ -333,7 +333,7 @@ Prefer checking `getCapabilities()` over assuming a platform from context — es
 
 ## Session & Context Isolation
 
-By default, `state` is a **shared global namespace** — a value set in one place is visible everywhere else that reads `state` in the same process. There is no automatic per-tab or per-request isolation of `state` itself.
+By default, `state` is a **shared global namespace** - a value set in one place is visible everywhere else that reads `state` in the same process. There is no automatic per-tab or per-request isolation of `state` itself.
 
 To isolate a slice of state (e.g. per tenant, per request), create an explicit context:
 
@@ -341,7 +341,7 @@ To isolate a slice of state (e.g. per tenant, per request), create an explicit c
 const ctx = memorio.createContext('tenant-name')
 ctx.state.user = { name: 'Isolated' }
 
-console.debug(state.user) // undefined — separate namespace from ctx.state
+console.debug(state.user) // undefined - separate namespace from ctx.state
 
 memorio.listContexts()
 memorio.deleteContext('context-id')
@@ -351,9 +351,100 @@ memorio.isolate('tenant-name')  // alias for createContext
 Isolation is implemented as a **key-prefix convention** inside the same underlying storage, not a hard memory or process boundary. In a shared Node.js process or an edge isolate that may be reused across requests:
 
 - generate context IDs from trusted server-side data, never directly from client-controlled input, to prevent collisions or spoofing;
-- don't treat this as your only isolation layer for data that must not cross tenants — enforce that at the process/request level as well.
+- don't treat this as your only isolation layer for data that must not cross tenants - enforce that at the process/request level as well.
 
-`getCapabilities().sessionId` provides a per-session identifier for browser contexts but is not itself an isolation mechanism — use `createContext` for that.
+`getCapabilities().sessionId` provides a per-session identifier for browser contexts but is not itself an isolation mechanism - use `createContext` for that.
+
+### `memorio.typed<T>()` - Typed Store (compile-time safety)
+
+Returns the global `state` proxy cast to type `T`. The same Proxy instance — no overhead. Use for TypeScript autocomplete and static type checking.
+
+```javascript
+const app = memorio.typed<AppState>()
+app.user = { name: 'Sara', age: 30 }  // type-checked
+app.user = { name: 42 }               // ❌ compile error
+```
+
+### `memorio.registerSchema()` - Schema Validation (runtime safety)
+
+Register validators for state paths. Writes that violate a schema are rejected before being stored.
+
+```javascript
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
+  }
+})
+
+state.user = { name: 'Sara' }  // rejected: missing 'email'
+state.user = { name: 'Sara', email: 'sara@test.com' }  // accepted
+```
+
+Custom validators:
+
+```javascript
+memorio.registerSchema('theme', (val) =>
+  val === 'light' || val === 'dark' ? true : 'must be light or dark'
+)
+```
+
+Manual validation and management:
+
+```javascript
+memorio.validate('user', value)     // { valid: true } or { valid: false, errors: [...] }
+memorio.listSchemas()               // ['user', 'theme']
+memorio.unregisterSchema('theme')   // removes validator
+```
+
+Combine `typed<T>()` + `registerSchema()` for both compile-time and runtime safety.
+
+### `memorio.snapshot()` / `memorio.diff()` - Time Travel
+
+```javascript
+memorio.enableHistory()
+
+const snap = memorio.snapshot()
+state.user.name = 'Luigi'
+state.counter = 100
+
+const changes = memorio.diff(snap)
+// [{ path: 'user.name', oldValue: 'Sara', newValue: 'Luigi' }, ...]
+
+memorio.rollback(snap)  // restore to snapshot
+```
+
+### `memorio.undo()` / `memorio.redo()` - Undo/Redo
+
+```javascript
+state.a = 1; state.b = 2; state.c = 3
+memorio.undo()   // removes state.c
+memorio.undo()   // removes state.b
+memorio.redo()   // restores state.b
+memorio.canUndo() // true
+memorio.canRedo() // true
+```
+
+### `memorio.trace()` - Mutation Log
+
+```javascript
+memorio.trace()
+// [{ path, action, newValue, previousValue, timestamp }, ...]
+memorio.clearHistory()
+```
+
+### `memorio.stateKeys()` / `memorio.pathExists()` / `memorio.stateSchema()` - Introspection
+
+```javascript
+memorio.stateKeys()      // ['user', 'counter']
+memorio.pathExists('user.name')  // true or false
+memorio.stateType('user.name')   // 'string'
+memorio.stateSchema()    // [{ path, type, defined }, ...] - full tree report
+```
+
+---
 
 ## Security
 
@@ -361,9 +452,9 @@ Isolation is implemented as a **key-prefix convention** inside the same underlyi
 - No `eval`, no dynamic code execution, no obfuscation, no hardcoded secrets.
 - Inputs validated, keys sanitized before use.
 - Secure random session IDs via `crypto.randomUUID`.
-- Data in `store`, `session`, and `idb` is **not encrypted** — these are thin wrappers over browser storage APIs that persist data in the clear on the user's device. Add your own encryption layer before storing tokens, secrets, or regulated personal data there.
+- Data in `store`, `session`, and `idb` is **not encrypted** - these are thin wrappers over browser storage APIs that persist data in the clear on the user's device. Add your own encryption layer before storing tokens, secrets, or regulated personal data there.
 
-Engineering practices are informed by recognized guidance (e.g. NIST SP 800-53 practices) as a design input — this is a statement about how the library is built, not a compliance certification, and no third-party audit has been performed. Report security issues privately (see `SECURITY.md`) rather than in a public issue.
+Engineering practices are informed by recognized guidance (e.g. NIST SP 800-53 practices) as a design input - this is a statement about how the library is built, not a compliance certification, and no third-party audit has been performed. Report security issues privately (see `SECURITY.md`) rather than in a public issue.
 
 ## License
 
@@ -371,7 +462,7 @@ MIT © Dario Passariello (BigLogic Inc Canada)
 
 ## Utilities
 
-### `memorio.dispatch` — Event Dispatch System
+### `memorio.dispatch` - Event Dispatch System
 
 Internal event system used by state changes; also usable directly for custom events.
 

package/markdown/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ---
 
-## v4.6.1 (Security Patch) - 2026-08-14 — CRITICAL Security Fix
+## v4.6.1 (Security Patch) - 2026-08-14 - CRITICAL Security Fix
 
 ### 🔐 Security NOTICE (v4.6.0)
 
@@ -32,7 +32,7 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 — Refactoring & Documentation
+## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 - Refactoring & Documentation
 
 **⚠️ WARNING**: This version had a hardcoded PAT token that was later remediated in v4.6.1**
 
@@ -75,7 +75,7 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v3.0.2 (Current) - 2026-05-19 — Bug Fix, Security & API Expansion
+## v3.0.2 (Current) - 2026-05-19 - Bug Fix, Security & API Expansion
 
 ### 🐛 Bug Fixes
 
@@ -98,9 +98,9 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 - Added JSDoc to `observerFunction` in `functions/observer/index.ts`
 - Added JSDoc to `cache` global in `functions/cache/index.ts`
-- `lint` and `tsc` pass clean — 0 vulnerabilities from `npm audit`
+- `lint` and `tsc` pass clean - 0 vulnerabilities from `npm audit`
 
-### 🆕 API — New in 3.0.2
+### 🆕 API - New in 3.0.2
 
 | Function | Description |
 |----------|-------------|
@@ -136,10 +136,10 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v2.9.0 — 2026-05-13
+## v2.9.0 - 2026-05-13
 
 ### Added
-- DevTools — `memorio.devtools.inspect()`, `stats()`, `exportData()`
+- DevTools - `memorio.devtools.inspect()`, `stats()`, `exportData()`
 - Logger with full history, stats and export
 - Platform detection (`isBrowser`, `isNode`, `isDeno`, `isEdge`, `getCapabilities`)
 - Session isolation via `crypto.randomUUID()`
@@ -154,7 +154,7 @@ The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed
 
 ---
 
-## v2.5.0 — 2026-02-17
+## v2.5.0 - 2026-02-17
 
 - Initial release of memorio (state, store, session, cache, idb)
 - Observer pattern (`observer`)

package/markdown/HISTORY.md

@@ -0,0 +1,192 @@
+# History, Undo / Redo, Snapshot, Diff, Trace - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Memorio provides a lightweight time-travel system for `state` mutations: snapshots, diffs, undo/redo, and a full mutation trace log.
+
+History tracking is **opt-in** — it is disabled by default to avoid overhead. Enable it when you need undo/redo or trace capabilities.
+
+---
+
+## Enable History
+
+```javascript
+import 'memorio'
+
+memorio.enableHistory()    // enable tracking
+// ... mutate state ...
+memorio.state.user = { name: 'Sara' }
+memorio.state.counter = 42
+```
+
+> Without `enableHistory()`, mutations are not recorded and `undo()`/`redo()`/`trace()` return empty results.
+
+---
+
+## Snapshot & Diff
+
+Snapshot captures the entire `state` tree at a point in time. Diff compares a snapshot against current state to see what changed.
+
+```javascript
+// Enable history (snapshots work regardless, but trace/undo need it)
+memorio.enableHistory()
+
+// Take a snapshot
+state.user = { name: 'Sara', age: 30 }
+const snap = memorio.snapshot()
+
+// Make changes
+state.user.name = 'Luigi'
+state.counter = 100
+state.items = ['a', 'b']
+
+// Diff against the snapshot
+const changes = memorio.diff(snap)
+console.debug(changes)
+// [
+//   { path: 'user.name', oldValue: 'Sara', newValue: 'Luigi' },
+//   { path: 'counter',   oldValue: undefined, newValue: 100 },
+//   { path: 'items',     oldValue: undefined, newValue: ['a', 'b'] }
+// ]
+```
+
+This is essential for AI agents: take a snapshot, make changes, inspect the diff, and decide whether to commit or rollback.
+
+---
+
+## Undo / Redo
+
+```javascript
+state.user = { name: 'Sara' }
+state.counter = 100
+state.items = ['a', 'b']
+
+memorio.undo()   // removes state.items
+memorio.undo()   // counter → undefined
+memorio.redo()   // counter → 100 again
+
+memorio.canUndo()  // true
+memorio.canRedo()  // true (after above undo + redo cycle)
+```
+
+- `undo()`: Restores the previous state by inverting the most recent mutation.
+- `redo()`: Re-applies the most recently undone mutation.
+- `canUndo()` / `canRedo()`: Check availability before calling.
+
+### Max history depth
+
+```javascript
+memorio.setMaxHistory(50)   // keep at most 50 mutations per stack (default: 100)
+```
+
+---
+
+## Rollback (full state restore)
+
+Unlike undo (which works one step at a time), `rollback` replaces the entire state from a snapshot:
+
+```javascript
+const snap = memorio.snapshot()
+
+state.experiment = { result: 'failed' }
+state.counter = 999
+
+// Discard everything and restore to snapshot
+memorio.rollback(snap)
+// state.experiment is now gone
+// state.counter is back to its snapshot value
+```
+
+---
+
+## Trace (mutation log)
+
+The trace log records every mutation with timestamp, path, action, and before/after values:
+
+```javascript
+memorio.enableHistory()
+
+state.user.name = 'Sara'
+state.counter = 1
+state.counter = 2
+
+const log = memorio.trace()
+console.debug(log)
+// [
+//   { path: 'user.name', action: 'set', newValue: 'Sara', previousValue: undefined, timestamp: 1725... },
+//   { path: 'counter',   action: 'set', newValue: 1,      previousValue: undefined, timestamp: 1725... },
+//   { path: 'counter',   action: 'set', newValue: 2,      previousValue: 1,         timestamp: 1725... }
+// ]
+```
+
+This is useful for:
+- **AI debugging**: inspect what changed and when
+- **Event sourcing**: export the log and replay state from scratch
+- **Audit trails**: log all mutations for compliance
+
+### Export / import trace
+
+```javascript
+const log = memorio.trace()
+localStorage.setItem('memorio-trace', JSON.stringify(log))
+
+// Later, replay:
+const saved = JSON.parse(localStorage.getItem('memorio-trace'))
+for (const record of saved) {
+  if (record.action === 'set') {
+    state[record.path] = record.newValue
+  }
+}
+```
+
+---
+
+## Clear History
+
+```javascript
+memorio.clearHistory()   // wipe undo/redo stacks + trace log
+memorio.clearRedo()      // clear only the redo stack (undo stack preserved)
+```
+
+> `clearHistory()` does NOT reset the current `state` — only the history tracking data.
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.snapshot()` | none | `Record<string, any>` | Deep clone of current state |
+| `memorio.diff(snap)` | `snap` | `DiffEntry[]` | Changed paths with old/new values |
+| `memorio.undo()` | none | `MutationRecord \| undefined` | Undo last mutation |
+| `memorio.redo()` | none | `MutationRecord \| undefined` | Redo last undone mutation |
+| `memorio.canUndo()` | none | `boolean` | Whether undo is available |
+| `memorio.canRedo()` | none | `boolean` | Whether redo is available |
+| `memorio.rollback(snap)` | `snap` | `void` | Restore full state from snapshot |
+| `memorio.trace()` | none | `MutationRecord[]` | List of all recorded mutations |
+| `memorio.enableHistory(enabled?)` | `boolean` | `void` | Enable/disable tracking |
+| `memorio.clearHistory()` | none | `void` | Clear all history stacks |
+| `memorio.clearRedo()` | none | `void` | Clear only redo stack |
+| `memorio.setMaxHistory(max)` | `number` | `void` | Set max stack depth |
+| `memorio.getMaxHistory()` | none | `number` | Get current max depth |
+
+---
+
+## How It Works
+
+1. When `historyEnabled` is true, the state proxy's callback (`buildProxy` callback) fires on every `set`/`delete` trap, recording a `MutationRecord` with path, action, oldValue, newValue, and timestamp.
+2. Records are pushed to both a trace log (`mutations`) and an undo stack.
+3. Any new mutation clears the redo stack.
+4. `undo()` pops from the undo stack, pushes to the redo stack, and applies the inverse operation (restoring the previous value, or deleting if it was new).
+5. `redo()` pops from the redo stack, pushes back to the undo stack, and re-applies the original mutation.
+6. During undo/redo, history tracking is temporarily disabled to prevent recursive recording.
+7. `diff()` does a recursive key-by-key comparison between the snapshot and current `deepRaw(state)`.
+
+---
+
+## Best Practices
+
+1. **Always snapshot before AI experimentation** — `const snap = memorio.snapshot()` gives you a safe rollback point.
+2. **Call `diff()` before `rollback()`** — inspect what changed first; sometimes you only need to revert one key.
+3. **Keep `maxHistory` reasonable** — the default (100) is fine for most apps. Lower it for memory-constrained environments.
+4. **Don't rely on trace for sensitive data** — the trace log records *all* values written, including tokens/PII. Clear it or disable tracing in production paths.

package/markdown/INSPECT.md

@@ -0,0 +1,116 @@
+# Introspection & Inspection - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Introspection utilities let you programmatically discover, verify, and read the shape of the global `state` proxy. Essential for AI agents that need to check whether a path exists before writing, or enumerate available keys before reading.
+
+---
+
+## stateKeys()
+
+Returns all top-level keys currently on the `state` proxy. Excludes internal properties.
+
+```javascript
+import 'memorio'
+
+state.user = { name: 'Sara' }
+state.counter = 42
+
+memorio.stateKeys()   // ['user', 'counter']
+```
+
+---
+
+## pathExists(path)
+
+Checks whether a dotted path exists in state. Returns `true` if the path resolves to a non-undefined value.
+
+```javascript
+state.user = { name: 'Sara', profile: { age: 30 } }
+
+memorio.pathExists('user')           // true
+memorio.pathExists('user.name')      // true
+memorio.pathExists('user.profile')   // true
+memorio.pathExists('user.profile.age') // true
+memorio.pathExists('user.age')       // false
+memorio.pathExists('nonexistent')    // false
+```
+
+This is critical for AI agents: always check `pathExists` before writing to a nested path to avoid creating unintended intermediate objects.
+
+---
+
+## stateType(path)
+
+Returns the runtime type of the value at a given state path.
+
+```javascript
+state.count = 42
+state.name = 'Sara'
+state.items = [1, 2, 3]
+
+memorio.stateType('count')    // 'number'
+memorio.stateType('name')     // 'string'
+memorio.stateType('items')    // 'array'
+memorio.stateType('missing')  // 'undefined'
+```
+
+---
+
+## stateGet(path)
+
+Returns the value at a dotted path, deep-cloned to prevent accidental mutation of state.
+
+```javascript
+state.user = { name: 'Sara', tags: ['admin'] }
+
+const user = memorio.stateGet('user')   // { name: 'Sara', tags: ['admin'] }
+user.name = 'Luigi'                      // mutates the clone, not state
+state.user.name                         // still 'Sara'
+```
+
+---
+
+## stateSchema()
+
+Generates a full schema report of the current state tree — every path with its type and whether it's defined.
+
+```javascript
+state.user = { name: 'Sara', age: 30 }
+state.theme = 'dark'
+
+memorio.stateSchema()
+// [
+//   { path: 'user',      type: 'object', defined: true },
+//   { path: 'user.name', type: 'string', defined: true },
+//   { path: 'user.age',  type: 'number', defined: true },
+//   { path: 'theme',     type: 'string', defined: true }
+// ]
+```
+
+This is the **most useful for AI agents** — it gives a complete picture of what's in state and what types the values are, in a single call. Perfect for:
+- Discovering available state before generating code
+- Validating that expected paths exist
+- Understanding the shape of nested objects
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.stateKeys()` | none | `string[]` | Top-level state keys |
+| `memorio.pathExists(path)` | `string` | `boolean` | Whether a path resolves to a value |
+| `memorio.stateType(path)` | `string` | `string` | Runtime type at path |
+| `memorio.stateGet(path)` | `string` | `any` | Deep-cloned value at path |
+| `memorio.stateSchema()` | none | `SchemaEntry[]` | Full state tree report |
+
+---
+
+## How It Works
+
+All introspection functions read from the global `state` proxy via `deepRaw()` — the same function used internally by the state proxy to unwrap itself before storing. This ensures consistent, non-proxied values are returned.
+
+- `pathExists` and `stateGet` split the path on `.` and traverse the state tree.
+- `stateSchema` recursively walks the state object, collecting every path and its type.
+- All returned values from `stateGet` and `snapshot` are deep clones (via JSON round-trip) to prevent accidental mutation.