memorio 4.7.1 → 4.7.3

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.

package/markdown/MEMORY.md

@@ -0,0 +1,155 @@
+# Memory System
+
+`memorio.memory` provides a semantic memory layer — a key/value store with type safety, TTL, confidence scoring, tagging, and scope-based persistence.
+
+## Core API
+
+### `memorio.memory.remember(key, value, opts?)`
+
+Stores a memory entry.
+
+```ts
+await memorio.memory.remember('user.name', 'Dario', {
+  type: 'preference',
+  confidence: 0.92,
+  scope: 'local',
+  ttl: null,
+  tags: ['user', 'profile'],
+  source: 'conversation'
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | `key` | Custom entry ID |
+| `type` | `'fact' \| 'preference' \| 'decision' \| 'task' \| 'context'` | `'fact'` | Semantic classification |
+| `confidence` | `number` | `1.0` | Trust score 0.0–1.0 |
+| `scope` | `'hot' \| 'session' \| 'local' \| 'durable'` | auto | Storage backend (see below) |
+| `ttl` | `number \| null` | `null` | Milliseconds before expiry (`null` = never) |
+| `tags` | `string \| string[]` | `[]` | Metadata for filtering |
+| `source` | `string` | `undefined` | Origin of the memory |
+
+### `memorio.memory.recall(query, opts?)`
+
+Retrieves a memory by key.
+
+```ts
+const name = await memorio.memory.recall('user.name')
+const highConfidence = await memorio.memory.recall('project', {
+  minConfidence: 0.8
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `type` | `MemoryType \| MemoryType[]` | `*` | Filter by type |
+| `tags` | `string \| string[]` | `*` | Filter by tags |
+| `minConfidence` | `number` | `0` | Minimum confidence threshold |
+| `includeObsolete` | `boolean` | `false` | Include expired/superseded entries |
+
+### `memorio.memory.update(key, value, opts?)`
+
+Updates an existing memory. Creates a **superseded copy** of the old entry (preserving history).
+
+```ts
+await memorio.memory.update('user.name', 'Alice', { confidence: 0.95 })
+```
+
+### `memorio.memory.forget(key)`
+
+Permanently removes a memory.
+
+```ts
+await memorio.memory.forget('user.temp')
+```
+
+### `memorio.memory.context(opts?)`
+
+Returns ranked, relevant memories. Uses recency × confidence × type/scope boost algorithm.
+
+```ts
+const ctx = await memorio.memory.context({
+  tags: 'project',
+  types: ['decision', 'preference'],
+  minConfidence: 0.7,
+  maxEntries: 10,
+  scopes: ['local', 'durable']
+})
+```
+
+Returns:
+```ts
+Array<{
+  key: string
+  value: any
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  tags: string[]
+  age: number          // milliseconds since createdAt
+  accessCount: number
+  lastAccessedAt: number
+}>
+```
+
+### `memorio.memory.stats()`
+
+Returns usage statistics:
+
+```ts
+{
+  total: number
+  byScope: Record<MemoryScope, number>
+  byType: Partial<Record<MemoryType, number>>
+  expired: number
+}
+```
+
+### `memorio.memory.forgetExpired()`
+
+Cleans all expired entries. Returns count removed.
+
+### `memorio.memory.clear()`
+
+Wipes all memories and the index.
+
+## Memory Entry Model
+
+```ts
+interface MemoryEntry<T = any> {
+  id: string
+  key: string
+  value: T
+  type: 'fact' | 'preference' | 'decision' | 'task' | 'context'
+  confidence: number
+  scope: 'hot' | 'session' | 'local' | 'durable'
+  ttl?: number | null
+  tags: string[]
+  source?: string
+  status: 'active' | 'obsolete' | 'superseded'
+  createdAt: number
+  lastConfirmedAt: number
+  supersededId?: string | null
+}
+```
+
+## 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.
+
+## Memory Lifecycle
+
+| Event | Behavior |
+|-------|----------|
+| `remember()` on existing key | Old entry → `superseded`, new entry → `active` |
+| Entry with TTL expires | Status → `obsolete` (cleaned by `forgetExpired()`) |
+| `recall()` expired entry | Returns `null` unless `includeObsolete: true` |
+| `update()` | Creates superseded copy + updated active entry |
+| `clear()` | Wipes all memories + index |

package/markdown/SCHEMA.md

@@ -0,0 +1,169 @@
+# Schema Validation - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Schema validation guards your `state` against invalid writes. It runs inside the state proxy's `set` trap, so any `state.somePath = value` that violates a registered schema is rejected at runtime — before the value is ever stored.
+
+Schema validation is **opt-in** and **zero-dependency**.
+
+---
+
+## Quick Start
+
+```javascript
+import 'memorio'
+
+// Register a validator for a top-level state key
+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 }
+  }
+})
+
+// Valid write — accepted
+state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }
+
+// Invalid write — rejected, returns false
+state.user = { name: 'Sara' }           // missing 'email'
+state.user = { name: 42, email: 'x' }   // wrong type for 'name'
+state.user = { age: -5 }                // out of range
+```
+
+---
+
+## Schema Definition
+
+A `Schema` object supports the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'string' \| 'number' \| 'boolean' \| 'object' \| 'array' \| 'any'` | Runtime type check |
+| `required` | `string[]` | Property names that must exist (objects only) |
+| `properties` | `Record<string, Schema>` | Nested property schemas (validated recursively) |
+| `min` | `number` | Number: minimum value. String: minimum length |
+| `max` | `number` | Number: maximum value. String: maximum length |
+| `pattern` | `RegExp` | Regex the string value must match |
+| `enum` | `any[]` | Whitelist of allowed values |
+| `validator` | `(value) => boolean \| string` | Custom validator function |
+
+### Custom validator functions
+
+For logic that's hard to express declaratively, pass a function instead of a schema object:
+
+```javascript
+memorio.registerSchema('counter', (value) => {
+  if (typeof value !== 'number') return 'counter must be a number'
+  if (value < 0) return 'counter must be >= 0'
+  return true
+})
+```
+
+A custom validator receives the raw value. Return `true` to accept, or a **string** describing the error to reject.
+
+---
+
+## Path-based registration
+
+Schemas are keyed by their **state path**, relative to `state`:
+
+| API call | Catches |
+|----------|---------|
+| `registerSchema('user', schema)` | `state.user = value` |
+| `registerSchema('user.age', schema)` | `state.user.age = value` |
+| `registerSchema('items', schema)` | `state.items = value` |
+
+The full dotted path is constructed from the proxy's tree depth. Nested sets propagate the full path automatically.
+
+---
+
+## Manual validation
+
+You can validate a value without writing it to state:
+
+```javascript
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+// { valid: true }
+
+memorio.validate('user', { name: 'Sara' })
+// { valid: false, errors: ["user: missing required property 'email'"] }
+```
+
+When no schema is registered for a path, `validate` returns `{ valid: true }`.
+
+---
+
+## Schema management
+
+```javascript
+memorio.listSchemas()           // ['user', 'theme', 'items', 'counter']
+memorio.unregisterSchema('counter')  // removes the schema
+```
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.registerSchema(path, schema)` | `string`, `Schema \| fn` | `void` | Register a validator |
+| `memorio.validate(path, value)` | `string`, `any` | `{ valid, errors? }` | Manually validate a value |
+| `memorio.unregisterSchema(path)` | `string` | `boolean` | Remove a registered schema |
+| `memorio.listSchemas()` | none | `string[]` | List all registered paths |
+| `memorio.registerSchema()` is also importable | `registerSchema` | named export | same function |
+
+---
+
+## Combine with Typed Stores
+
+Schema validation gives you **runtime** safety; typed stores give you **compile-time** safety. Use both for full coverage:
+
+```typescript
+import 'memorio'
+
+interface AppState {
+  user: { name: string; email: string; age: number }
+  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: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+app.user = { name: '', email: 'bad' }   // ❌ TypeScript: age missing
+                                         // ❌ Runtime: missing required fields
+app.user = { name: 'Sara', email: 'ok', age: 30 } // ✅ both checks pass
+```
+
+See [Typed Stores](TYPED.md) for compile-time type safety.
+
+---
+
+## How it works
+
+1. When you call `registerSchema(path, schema)`, the schema is stored in an internal `Map`.
+2. On every `state.set` operation, the proxy's `set` trap computes the full path (e.g. `'user.name'`).
+3. If a schema is registered for that path, the value is validated.
+4. If validation fails, the write is rejected (`return false`), and an error is logged via `console.error` (when `memorio.debug = true`) or `console.debug` (via the internal `message` helper).
+5. If no schema is registered, the write proceeds normally.
+
+The validation adds negligible overhead when no schemas are registered (a single `Map` lookup that returns `undefined`).
+
+---
+
+## Limitations
+
+- Schema validation hooks into the `state` proxy only. `store`, `session`, and `cache` are not validated (they use separate storage). Use `validate()` before writing to other modules.
+- Path matching is **exact**: `registerSchema('user')` guards `state.user = ...`, but does **not** recursively validate `state.user.name = 'new'`. Register schemas at each path you need to guard.
+- The schema system is not a replacement for server-side validation. It protects against accidental misuse and provides defense-in-depth in the browser.

package/markdown/SECURITY.md

@@ -310,7 +310,7 @@ If you discover a security vulnerability in Memorio:
 
 ---
 
-### v2.7.0 — Previous
+### v2.7.0 - Previous
 
 - ✅ Added `crypto.getRandomValues()` fallback
 - ✅ Added key length validation (512 chars)