memorio 5.1.2 → 5.1.4

package/llms.txt

@@ -21,8 +21,8 @@ Memorio provides 6 storage modules plus utilities:
 | `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) |
-| `sqlite` | SQLite via sql.js (WebAssembly) | Browser-only relational SQL |
-| `observer` | Object watcher | Legacy; string-based paths, not statically checked against `state`'s shape |
+| `sqlite` | SQLite via sql.js (WebAssembly) / `bun:sqlite` (native) | Browser-only relational SQL; optional journal + checkpoint persistence to `store` |
+| `observer` | Object watcher | String-based path observer; use `typed<T>()` + `registerSchema()` for statically checked alternatives |
 | `useObserver` | React hook | Auto-discovery of state paths |
 | `encryption` | AES-GCM + PBKDF2 | Encrypt/decrypt values, store/session integration |
 
@@ -51,6 +51,8 @@ To opt in to global access (state, store, session, cache, idb, sqlite, observer,
 import 'memorio/global'
 ```
 
+**Upgrading from 4.x:** in v5, `import 'memorio'` no longer installs globals on `globalThis`. If your code uses bare globals (e.g. `state.counter = 1` without importing `state`), change the import to `import 'memorio/global'`. Named imports (`import { state } from 'memorio'`) are unaffected. After upgrading, restart your dev server and clear `node_modules/.vite` / `.next/cache` to avoid stale pre-bundles masking the change.
+
 This is independent of bundler environment detection (no `import.meta.env.DEV`, no `process.env.NODE_ENV` checks).
 
 ## API Reference
@@ -89,6 +91,19 @@ These are materially different behaviors - confirm against the actual source whi
 - Automatic path tracking via `__path` property
 - Nested proxy support
 - Auto-dispatches events on changes
+- `state.persist(path)` mirrors state path to `store` and syncs writes (see "Getting Started" guide)
+
+#### `state.persist(path)`
+
+Creates a bidirectional mirror between `state` (live in-memory) and `store` (durable copy). Seeds the initial value from `store` if present, then every write to that path flows to `store` automatically.
+
+```javascript
+const stopPersisting = state.persist('state.user')
+state.user = { name: 'Sara' }
+// ... writes to state.user are mirrored to store
+
+stopPersisting() // stops mirroring; store value is preserved
+```
 
 ### `store` - localStorage Persistence
 

package/markdown/MEMORY.md

@@ -69,6 +69,33 @@ Permanently removes a memory.
 await memorio.memory.forget('user.temp')
 ```
 
+### `memorio.memory.patch(key, patches)`
+
+Apply a field-level JSON Patch to an existing memory entry's value. Supports `set` and `delete` operations.
+
+```ts
+await memorio.memory.remember('user', {
+  name: 'Mario',
+  profile: { theme: 'light', lang: 'en' }
+})
+
+// Set a nested value
+await memorio.memory.patch('user', [
+  { op: 'set', path: 'user.profile.theme', value: 'dark' }
+])
+
+// Delete a field
+await memorio.memory.patch('user', [
+  { op: 'delete', path: 'user.profile.lang' }
+])
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `op` | `'set' \| 'delete'` | The patch operation type |
+| `path` | `string` | Dot-notation path relative to the entry value (e.g. `'user.profile.theme'`) |
+| `value` | `any` | The value to set (only for `op: 'set'`) |
+
 ### `memorio.memory.context(opts?)`
 
 Returns ranked, relevant memories. Uses recency × confidence × type/scope boost algorithm.

package/markdown/SQLITE.md

@@ -1,10 +1,10 @@
-> **Status:** Published
-> **Date:** 2026-09-12
-> **Scope**: API Reference
-> **Standard**: Memorio API Specification v5
->
----
-# SQLite - Memorio
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# SQLite - Memorio
 
 > The `sql.js` package is **optional** - if it is not installed, Memorio loads `sql.js` on first use by injecting the `sql-wasm-browser.js` UMD build from the jsDelivr CDN as a classic `<script>` (which exposes the `initSqlJs` factory on `globalThis`). No bare `import('sql.js')` is ever emitted, so bundlers never resolve the optional dependency at build time. Not available in Node.js/Deno.
 
@@ -97,16 +97,16 @@ console.debug('SQLite version:', sqlite.db.version());
 ### Example 5: Persistence & dev download
 
 > **Important:** sql.js databases live in **WebAssembly memory** - they are
-> in-memory and **volatile** (lost on page refresh) unless you persist them.
+> in-memory and **volatile** (lost on page refresh) unless you opt into persistence.
 
 ```javascript
-// Opt into auto-persistence at create time (global config or per-create)
+// Opt into persistence at create time (global config or per-create)
 await sqlite.db.create('app', { persistence: true });
 
 await sqlite.query.run('app', 'CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)');
-// writes are snapshotted to localStorage automatically (debounced via updateHook)
+// writes are journaled incrementally; checkpoints are saved automatically
 
-await sqlite.db.persist('app');          // force an immediate snapshot
+await sqlite.db.persist('app');          // force an immediate checkpoint (full snapshot + clear journal)
 // After a refresh, reopening restores the data:
 await sqlite.db.create('app', { persistence: true });
 
@@ -117,10 +117,33 @@ await sqlite.db.download('app', 'app.sqlite');
 await sqlite.db.close('app');
 ```
 
+Persistence uses a **journal + checkpoint** strategy for incremental durability:
+
+1. **Journal**: every `db.run(sql, params)` write is recorded as a journal entry
+   (with an HLC timestamp for causal ordering) in `store` (localStorage). The
+   journal is append-only and incremental - only the changed statement is stored.
+2. **Checkpoint**: every 50 operations (configurable), or after 250 ms of write
+   idle, a full database snapshot is taken and written to `store`. The journal is
+   then cleared up to that point.
+3. **Recovery**: on `create(name, { persistence: true })`, the latest checkpoint
+   is loaded first, then any journal entries that were written after the
+   checkpoint are replayed on top - so no writes are lost even if the page closes
+   between checkpoints.
+
 Persistence is stored on `store` (localStorage, namespaced per
-`sqlite.config({ namespace })` / memorio context) as a base64 snapshot under
-`memorio:sqlite:db:<ns>:<name>`. It is best-effort: if `store` is unavailable
-the database simply behaves as in-memory.
+`sqlite.config({ namespace })` / memorio context) as:
+- Checkpoint: `memorio:sqlite:db:<ns>:<name>` (base64 binary snapshot)
+- Journal entries: `memorio:sqlite:journal:<ns>:<name>:<seq>` (individual SQL ops)
+
+It is best-effort: if `store` is unavailable the database simply behaves as
+in-memory. The journal is also available directly:
+
+```javascript
+sqlite.db.persist('app');              // force checkpoint (alias: flush)
+sqlite.db.flush('app');                // force checkpoint
+const entries = sqlite.db.journal.entries('app'); // inspect pending ops
+await sqlite.db.journal.checkpoint('app'); // manual checkpoint
+```
 
 ---
 
@@ -130,11 +153,13 @@ the database simply behaves as in-memory.
 
 | Method | Parameters | Returns | Description |
 |--------|------------|---------|-------------|
-| `sqlite.config(opts)` | `opts: { loader?, locateFile?, wasmUrl?, persistence?, namespace? }` | `sqlite` | Configure the engine. `loader` fully replaces the initializer (default = CDN `<script>`); `locateFile` customizes wasm resolution; `wasmUrl` sets the wasm base directory; `persistence` toggles automatic db snapshots; `namespace` partitions persisted snapshots. Chainable. |
-| `sqlite.db.create(name, opts)` | `name: string, opts?: { data?, persistence? }` | `Database` | Opens/creates a named in-memory db. With `persistence: true` (or global config), a snapshot is restored if present and writes are auto-saved. |
-| `sqlite.db.persist(name)` | `name: string` | `Promise<boolean>` | Force an immediate snapshot of a persisted database to `store`. |
+| `sqlite.config(opts)` | `opts: { loader?, locateFile?, wasmUrl?, persistence?, namespace? }` | `sqlite` | Configure the engine. `loader` fully replaces the initializer (default = CDN `<script>`); `locateFile` customizes wasm resolution; `wasmUrl` sets the wasm base directory; `persistence` toggles journal + checkpoint persistence; `namespace` partitions persisted data. Chainable. |
+| `sqlite.db.create(name, opts)` | `name: string, opts?: { data?, persistence? }` | `Database` | Opens/creates a named in-memory db. With `persistence: true` (or global config), the latest checkpoint is restored and pending journal entries are replayed for full crash recovery. |
+| `sqlite.db.persist(name)` | `name: string` | `Promise<boolean>` | Force an immediate checkpoint (full snapshot + journal clear) of a persisted database to `store`. Alias of `flush`. |
+| `sqlite.db.flush(name)` | `name: string` | `Promise<boolean>` | Force an immediate checkpoint (alias of `persist`). |
 | `sqlite.db.download(name, filename?)` | `name: string, filename?: string` | `Promise<boolean>` | Dev-only: trigger a browser download of the db as a `.sqlite` file. |
-| `sqlite.db.close(name)` | `name: string` | `Promise<void>` | Persist (if enabled), close, and release the handle. |
+| `sqlite.db.close(name)` | `name: string` | `Promise<void>` | Checkpoint (if enabled), close, and release the handle. |
+| `sqlite.db.journal` | `name: string` | Object | Journal namespace: `append`, `entries`, `count`, `clear`, `replay`, `checkpoint`. |
 | `sqlite.ready` | none | `Promise<void>` | Resolves once `sql.js` has been initialized. Rejects (and sets `_disabled`) if the engine can't load. |
 | `sqlite.db.version()` | none | `string \| null` | Engine version, available after initialization. |
 | `sqlite._disabled` | none | `boolean` | `true` when the module is disabled (non-browser env / load failure). |
@@ -147,7 +172,7 @@ the database simply behaves as in-memory.
 | `sqlite.db.support()` | none | `boolean` | Check whether SQLite can run in this environment. |
 | `sqlite.db.create(name, opts?)` | `name: string`, `opts?: { data }` | `Promise<Database>` | Create an in-memory database (or reopen one from a binary dump). |
 | `sqlite.db.get(name)` | `name: string` | `Database` | Retrieve an open database handle. |
-| `sqlite.db.delete(name)` | `name: string` | `boolean` | Close and remove a database handle. |
+| `sqlite.db.delete(name)` | `name: string` | `Promise<boolean>` | Checkpoint (if enabled), close, and remove a database handle. |
 | `sqlite.db.list()` | none | `string[]` | List open database names. |
 | `sqlite.db.size(name?)` | `name?: string` | `Promise<number>` | Size in bytes of one or all databases. |
 | `sqlite.db.export(name)` | `name: string` | `Promise<Uint8Array>` | Export a database to a binary dump. |
@@ -184,6 +209,7 @@ the database simply behaves as in-memory.
 
 1. Configure the wasm path for production: `sqlite.config({ wasmUrl })` or `sqlite.config({ loader })`.
 2. Create one named database per feature and reuse the handle: `const db = await sqlite.db.create('app')`.
-3. Always release databases you no longer need: `sqlite.db.delete('temp')`.
-4. Use `await sqlite.ready` before running statements to ensure the engine is loaded.
-5. Use `?` placeholders and `params` to avoid SQL injection.
+3. Use `await sqlite.ready` before running statements to ensure the engine is loaded.
+4. Use `?` placeholders and `params` to avoid SQL injection.
+5. Batch writes and call `sqlite.db.persist()` / `sqlite.db.flush()` once after the batch, not inside a loop. The journal captures each write incrementally, but the checkpoint (full snapshot) is the expensive operation.
+6. Always release databases you no longer need: `await sqlite.db.delete('temp')`.

package/markdown/STORE.md

@@ -1,10 +1,10 @@
-> **Status:** Published
-> **Date:** 2026-09-12
-> **Scope**: API Reference
-> **Standard**: Memorio API Specification v5
->
----
-# Store - Memorio
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Store - Memorio
 
 > 🖥️ **Browser & Edge**: Uses localStorage for persistence
 > ⚙️ **Node.js/Deno**: Falls back to in-memory storage (not persistent)
@@ -56,7 +56,7 @@ store.remove('username');
 
 // Check size
 const totalSize = store.size();
-console.debug(`${totalSize} bytes`);
+console.debug(`${totalSize} KB`);
 ```
 
 ### Example 3: Advanced
@@ -66,9 +66,9 @@ console.debug(`${totalSize} bytes`);
 const [used, total] = await store.quota();
 console.debug(`Using ${used} out of ${total} KB`);
 
-// Get total size in characters
+// Get total size in kilobytes
 const size = store.size();
-console.debug(`${size} bytes`);
+console.debug(`${size} KB`);
 
 // Clear all data
 store.removeAll();
@@ -97,7 +97,7 @@ try {
 | `store.delete(name)` | `name: string` | `boolean` | Alias for remove |
 | `store.removeAll()` | none | `boolean` | Clear all storage |
 | `store.clearAll()` | none | `boolean` | Alias for removeAll |
-| `store.size()` | none | `number` | Get total size in characters |
+| `store.size()` | none | `number` | Get total size in kilobytes (KB) |
 | `store.quota()` | none | `Promise<[number, number]>` | Get storage usage/quota in KB |
 
 ### Properties
@@ -167,4 +167,4 @@ Use `store.quota()` to monitor usage.
 1. Prefix keys: `store.set('app_username', '...')`
 2. Check before set: `if (store.get('key')) { ... }`
 3. Handle quota: Try/catch around large data
-4. Clean up: `store.removeAll()` on logout
+4. Clean up: `store.removeAll()` on logout

package/markdown/SYNC.md

@@ -1,10 +1,10 @@
-> **Status:** Published
-> **Date:** 2026-09-12
-> **Scope**: API Reference
-> **Standard**: Memorio API Specification v5
->
----
-# Synchronization & Cloud (optional)
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Synchronization & Cloud (optional)
 
 `memorio.memory` is **local-first**. Data is created and served from the device;
 the cloud is only ever a **transport/persistence provider**, never the source of
@@ -67,12 +67,15 @@ memorio.memory.configure({ sync: { provider: myCloudProvider, namespace: '…' }
 SQLite (`sql.js`) is **in-memory by default** (volatie per page load). It becomes
 the durable journal/value store when you opt in:
 
-- `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })`
-  snapshot the database to `store` (localStorage) and restore it on reopen.
-- Writes are snapshotted via sql.js `updateHook` (debounced).
-- `sqlite.db.persist(name)` forces an immediate save; `sqlite.db.close(name)`
-  flushes + closes; `sqlite.db.download(name, file?)` triggers a browser
-  `.sqlite` download (dev convenience).
+ - `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })`
+   snapshot the database to `store` (localStorage) and restore it on reopen.
+ - Writes are journaled incrementally (append-only, HLC-timestamped) and
+   checkpointed periodically (every 50 ops or 250 ms of idle). On reopen, the
+   last checkpoint is loaded and the journal is replayed - no writes are lost.
+ - `sqlite.db.persist(name)` / `sqlite.db.flush(name)` forces an immediate
+   checkpoint; `sqlite.db.close(name)` checkpoints + closes;
+   `sqlite.db.download(name, file?)` triggers a browser `.sqlite` download
+   (dev convenience).
 
 See `docs/markdown/SQLITE.md` for the full SQLite reference.
 
@@ -172,7 +175,7 @@ interface SyncProvider {
 | `localStorage` / Map | `store` | no | yes (browser) |
 | `sessionStorage` / Map | `session` | no | per-tab (browser) |
 | IndexedDB | `idb`, `memory` durable | no | yes |
-| sql.js (WASM heap) | `sqlite` | **yes** | only with `persistence: true` (snapshot → `store`) |
+| sql.js (WASM heap) | `sqlite` | **yes** | with `persistence: true` (journal + checkpoint → `store`) |
 | sync journal | `memory.journal` | no | yes (`store`) |
 
 ---
@@ -315,4 +318,4 @@ entity-level entries. Mitigate with:
 Applying granular path-level patches, HLC for causality, fractional indexing
 for ordered collections, explicit tombstones for deletions, and a convergence
 test suite lets memorio handle high-frequency concurrent offline edits across
-devices without the overhead of a full CRDT stack.
+devices without the overhead of a full CRDT stack.

package/modules/redux.cjs

@@ -471,8 +471,6 @@ var CONTEXTS_KEY, _contexts;
 var init_platform = __esm({
   "core/platform.ts"() {
     init_cjs_shims();
-    init_internal();
-    init_encryption();
     __name(getSessionStorage, "getSessionStorage");
     __name(getLocalStorage, "getLocalStorage");
     __name(hasIndexedDB, "hasIndexedDB");
@@ -1675,12 +1673,8 @@ function encodeHLC(hlcValue) {
 }
 __name(encodeHLC, "encodeHLC");
 
-// core/mutation/patch.ts
-init_cjs_shims();
-
 // core/mutation/transaction.ts
 init_cjs_shims();
-init_internal();
 var TX_REGISTRY_KEY = "__memorio_transaction_registry__";
 var registry = globalThis[TX_REGISTRY_KEY] || /* @__PURE__ */ new Map();
 if (!globalThis[TX_REGISTRY_KEY]) {
@@ -2035,19 +2029,39 @@ if (globalThis[STATE_INSTANCE_KEY]) {
         const initial = store.get(key);
         if (initial !== void 0 && initial !== null) {
           let acc = state2;
+          let seedOk = true;
           for (let i = 0; i < segments.length - 1; i++) {
             const seg = segments[i];
-            if (acc[seg] === void 0 || acc[seg] === null) acc[seg] = {};
-            acc = acc[seg];
+            const existing = acc[seg];
+            if (existing === void 0 || existing === null) {
+              acc[seg] = {};
+              acc = acc[seg];
+            } else if (typeof existing === "object") {
+              acc = existing;
+            } else {
+              if (DEV) {
+                console.warn(
+                  `[memorio state] state.persist('${normalized}') aborted seeding: '${seg}' already holds a primitive value (${typeof existing}), cannot nest '${segments.slice(i + 1).join(".")}' under it.`
+                );
+              }
+              seedOk = false;
+              break;
+            }
+          }
+          if (seedOk && acc) {
+            acc[segments[segments.length - 1]] = deepRaw(initial);
           }
-          if (acc) acc[segments[segments.length - 1]] = deepRaw(initial);
         }
         const handler = /* @__PURE__ */ __name(() => {
           let current = state2;
           for (const seg of segments) {
             current = current === void 0 || current === null ? void 0 : current[seg];
           }
-          store.set(key, deepRaw(current));
+          if (current === void 0) {
+            store.remove(key);
+          } else {
+            store.set(key, deepRaw(current));
+          }
         }, "handler");
         const off = dispatch.listen(normalized, handler);
         return typeof off === "function" ? off : () => {
@@ -3037,19 +3051,22 @@ var memory = {
   async patch(key, patches) {
     const entry = await this._getEntry(key);
     if (!entry) return;
+    const patchedValue = JSON.parse(JSON.stringify(entry.value ?? {}));
     let patched = false;
     for (const p of patches) {
+      const relativePath = p.path.replace(/^[^.]+\./, "");
       if (p.op === "set") {
-        setNestedPath({ [entry.key]: entry.value }, p.path.replace(/^[^.]+\./, ""), p.value);
+        setNestedPath(patchedValue, relativePath, p.value);
         patched = true;
       } else if (p.op === "delete") {
-        deleteNestedPath({ [entry.key]: entry.value }, p.path.replace(/^[^.]+\./, ""));
+        deleteNestedPath(patchedValue, relativePath);
         patched = true;
       }
     }
     if (!patched) return;
     const updated = {
       ...entry,
+      value: patchedValue,
       updatedAt: now(),
       lastConfirmedAt: now(),
       version: (entry.version ? entry.version : 0) + 1,