nedb-engine 2.8.6 → 3.1.0

package/LICENSE

@@ -1,65 +1,21 @@
-Business Source License 1.1
-
-Licensor: Interchained LLC, VibeCode 101, and/or the applicable copyright holders of NEDB
-
-Licensed Work: NEDB, including all source code, documentation, examples, tests, build scripts, specifications, APIs, SDKs, packages, binaries, and derivative works distributed from or based on the NEDB repository.
-
-Copyright: Copyright (c) 2026 Interchained LLC, VibeCode 101, and contributors. All rights reserved.
-
-Change Date: Four years after the first publicly available distribution of each specific version of the Licensed Work under this License.
-
-Change License: GNU Affero General Public License v3.0 or later.
-
-Additional Use Grant:
-
-You may use the Licensed Work only for non-production purposes, including evaluation, development, testing, research, local experimentation, security review, benchmarking, and personal learning.
-
-No production use is granted automatically.
-
-For clarity, the following uses are not permitted unless you have prior written permission from the Licensor:
-
-1. Using the Licensed Work in production.
-2. Using the Licensed Work to store, process, serve, index, replicate, query, or manage production data.
-3. Offering the Licensed Work, or any derivative work, as a hosted, managed, embedded, bundled, white-labeled, commercial, paid, revenue-generating, or customer-facing product or service.
-4. Offering database-as-a-service, storage-as-a-service, cache-as-a-service, search-as-a-service, analytics-as-a-service, AI-memory-as-a-service, agent-memory-as-a-service, blockchain-indexing-as-a-service, or any substantially similar service using the Licensed Work.
-5. Using the Licensed Work to compete with NEDB, Interchained LLC, VibeCode 101, AiAssist Secure, or any affiliated product, service, infrastructure platform, database engine, AI runtime, agent platform, or hosted developer infrastructure.
-6. Embedding the Licensed Work into commercial software, SaaS products, internal business systems, enterprise systems, hosted infrastructure, blockchain infrastructure, AI-agent infrastructure, or customer deliverables.
-7. Removing, hiding, modifying, or misrepresenting this License, copyright notices, attribution notices, authorship notices, repository references, or licensing notices.
-8. Circumventing license checks, access controls, paid licensing requirements, commercial-use restrictions, attribution requirements, or technical protections included with the Licensed Work.
-9. Using the Licensed Work in a way that implies endorsement, partnership, sponsorship, certification, or approval by the Licensor without written permission.
-10. Reselling, relicensing, sublicensing, renting, leasing, or otherwise commercially exploiting the Licensed Work except as expressly authorized in writing.
-
-Additional production, commercial, hosted, enterprise, embedded, OEM, resale, white-label, managed-service, competitive, or otherwise restricted use grants are available only by separate written permission from the Licensor.
-
-Written permission must be obtained from at least one of the following authorized licensing contacts:
-
-[founders@vibecode-101.com](mailto:founders@vibecode-101.com)
-[dev@interchained.org](mailto:dev@interchained.org)
-
-Permission is valid only if it is expressly granted in writing by an authorized representative of the Licensor and specifically identifies the permitted use, scope, duration, parties, and any applicable commercial terms.
-
-A general email conversation, informal message, pull request, issue comment, social media message, verbal discussion, repository access, package download, or contribution acceptance does not create a production, commercial, hosted, enterprise, resale, or competitive use license.
-
-Terms:
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and the rights granted in the paragraph above terminate.
-
-If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase or obtain a separate commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work, and the Change Date may vary for each version of the Licensed Work released by Licensor.
-
-You must conspicuously display this License on each original or modified copy of the Licensed Work. If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
-
-Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
-
-This License does not grant you any right in any trademark, service mark, trade name, logo, domain name, brand identity, product name, project name, or other identifier of Licensor or its affiliates, except as expressly required to preserve legally required notices.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, TITLE, SECURITY, ACCURACY, AVAILABILITY, DATA INTEGRITY, PERFORMANCE, AND FITNESS FOR PRODUCTION USE.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, LOSSES, COSTS, EXPENSES, BUSINESS INTERRUPTION, LOST PROFITS, LOST REVENUE, LOST DATA, SECURITY INCIDENTS, SERVICE OUTAGES, OR OTHER LIABILITY ARISING FROM OR RELATED TO THE LICENSED WORK OR YOUR USE OF THE LICENSED WORK.
-
-Notice:
-
-The Business Source License is not an Open Source license. However, each version of the Licensed Work will become available under the Change License on the applicable Change Date, or on the fourth anniversary of the first publicly available distribution of that version under this License, whichever comes first.
+MIT License
+
+Copyright (c) 2026 Interchained LLC and VibeCode 101
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,9 +13,15 @@ One Rust core → ships to **PyPI** and **npm** from a single source.
 [![CI](https://img.shields.io/github/actions/workflow/status/Eth-Interchained/nedb/release.yml?label=CI&color=34d399)](https://github.com/Eth-Interchained/nedb/actions)
 [![nedb-engine-client PyPI](https://img.shields.io/pypi/v/nedb-engine-client?label=nedb-engine-client&color=34d399)](https://pypi.org/project/nedb-engine-client/)
 [![nedb-engine-client npm](https://img.shields.io/npm/v/nedb-engine-client?label=nedb-engine-client&color=34d399)](https://www.npmjs.com/package/nedb-engine-client)
+[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e?logo=opensourceinitiative&logoColor=white)](https://github.com/Eth-Interchained/nedb/blob/master/LICENSE)
 
 **[Studio → studio.interchained.org](https://studio.interchained.org)**  ·  **[nedb.aiassist.net](https://nedb.aiassist.net)**
 
+> ## 🟢 MIT Licensed — free for any use, including commercial & production
+> NEDB is licensed under the **MIT License** — use it in production, embed it in commercial
+> products, ship it in closed-source software, fork it, sell it. No restrictions, no royalties,
+> no copyleft. See [`LICENSE`](LICENSE). The database is free; the moat is what you build on it.
+
 </div>
 
 ---
@@ -297,7 +303,58 @@ Typed errors throughout: `NedbAuthError`, `NedbNotFound`, `NedbBadRequest`,
 
 ---
 
-## Redis layer-2 — wrap_redis()
+## The wrap adapter family — provenance for the databases you already run
+
+**One line. Any stack.** Wrap your existing connection and gain tamper-evident, causally-provable, bi-temporal storage *alongside* your app — no migration, no rip-and-replace. NEDB never touches your namespace; shadow data lives only in the embedded DAG engine.
+
+| Language | Package | Redis | SQLite | MySQL | MongoDB | PostgreSQL |
+|---|---|:---:|:---:|:---:|:---:|:---:|
+| Python | `pip install nedb-engine` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Node.js | `npm install nedb-engine` → `require('nedb-engine/wrap')` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Rust | `nedb-wrap` (crates.io) | ✅ (`redis` feature) | 📋 engine-direct | 📋 engine-direct | 📋 engine-direct | 📋 engine-direct |
+
+✅ adapter shipped · 📋 embed the DAG core directly (`Surface` trait, same contract)
+
+The same contract everywhere — register → backfill → shadow → full NEDB API:
+
+```python
+# Python — every write auto-chained
+import redis, json
+from nedb import wrap_redis
+
+r = wrap_redis(redis.Redis("localhost", 6379), db_name="rideshare",
+               dag_path="./nedb-data")          # embedded v2/v3 DAG — no server
+r.nedb.register("driver:*", "driver", value_parser=json.loads)
+r.nedb.backfill()
+r.nedb.shadow_writes = True
+r.set("driver:d1", json.dumps({"name": "Bob", "status": "active"}))
+r.nedb.query('FROM driver WHERE status = "active"')
+r.nedb.verify()   # → True — BLAKE2b chain intact
+```
+
+```js
+// Node.js — same shape, real Rust DAG core via napi-rs
+const { wrapRedis } = require('nedb-engine/wrap');
+const r = wrapRedis(redisClient, { dbName: 'rideshare', dagPath: './nedb-data' });
+r.nedb.register('driver:*', 'driver');
+r.nedb.shadowWrites = true;
+await r.set('driver:d1', JSON.stringify({ name: 'Bob' }));
+r.nedb.query('FROM driver');
+```
+
+```rust
+// Rust — embed the engine directly (nedb-wrap crate)
+use nedb_wrap::Surface;
+let s = Surface::in_memory();               // or Surface::open(path)?
+s.register("driver:*", "driver");
+s.shadow_writes.store(true, std::sync::atomic::Ordering::Relaxed);
+s.shadow("driver:d1", serde_json::json!({"name": "Bob"}), true)?;
+assert!(s.verify());
+```
+
+Engine selection (all languages): `nedbd` HTTP server if you point at one (v1 AOF, `--dag` v2, `--dag-v3` v3) → **embedded DAG** if the native wheel is installed → v1 in-process fallback. Pass `dag_path=` for a durable store, `dag_tmk=` for AES-256-GCM encryption.
+
+## Redis layer-2 — wrap_redis() in depth
 
 Already running on Redis? Wrap your connection in one line and gain NEDB features *alongside* your existing Redis app — no migration required.
 
@@ -899,7 +956,8 @@ Requires `GITHUB_TOKEN` (`repo` + `workflow` scope) in the environment. It never
 
 ## License
 
-See `LICENSE` file. · © INTERCHAINED, LLC — [interchained.org](https://interchained.org)
+**MIT License** — free for any use, including commercial and production. See [`LICENSE`](LICENSE).
+© 2026 INTERCHAINED LLC — [interchained.org](https://interchained.org)
 
 ---
 

package/index.d.ts

@@ -3,3 +3,62 @@
 // Runtime behavior (durable-mode auto-flush-on-exit) is added by the wrapper in
 // index.js; the type surface is exactly the generated native binding's.
 export * from './native';
+
+// ── wrap adapter family (wrap/*.js) ─────────────────────────────────────────
+
+/** Options accepted by every wrap_* constructor. */
+export interface WrapOptions {
+  /** Logical database name (default "default"). */
+  dbName?: string;
+  /** HTTP nedbd server (v1 AOF, `--dag` v2, `--dag-v3` v3). Overrides embedded DAG. */
+  nedbdUrl?: string;
+  /** Bearer token for nedbd (NEDBD_TOKEN on the server). */
+  nedbdToken?: string;
+  /** Durable DAG store directory (embedded mode). */
+  dagPath?: string;
+  /** 64-hex TMK → AES-256-GCM at-rest encryption (embedded DAG mode). */
+  dagTmk?: string;
+  /** Explicit NedbCore class (testing / custom builds). */
+  native?: unknown;
+}
+
+/** The `.nedb` attribute — full NEDB layer-2 API. */
+export interface NedbSurface {
+  register(pattern: string, collection: string, opts?: {
+    idExtractor?: (key: string) => string;
+    valueParser?: (raw: unknown) => Record<string, unknown>;
+    valueType?: 'string' | 'hash' | 'json';
+  }): NedbSurface;
+  backfill(opts?: { pattern?: string; collection?: string; batchSize?: number }): number;
+  shadowWrites: boolean;
+  readonly engineKind: 'dag-embedded' | 'nedbd-http' | 'aof-embedded';
+
+  put(coll: string, id: string, doc: Record<string, unknown>): Record<string, unknown>;
+  get(coll: string, id: string, asOf?: number): Record<string, unknown> | null;
+  query(nql: string): Array<Record<string, unknown>>;
+  createIndex(coll: string, field: string, kind?: string): void;
+  delete(coll: string, id: string): void;
+  link(frm: string, rel: string, to: string): void;
+  unlink(frm: string, rel: string, to: string): void;
+  neighbors(frm: string, rel: string, asOf?: number): string[];
+  inbound(to: string, rel: string, asOf?: number): string[];
+  verify(): boolean;
+  readonly head: string;
+  readonly seq: number;
+  checkpoint(): string;
+  /** DAG-native: latest node (null on non-DAG backends). */
+  tip(): Record<string, unknown> | null;
+  /** DAG-native: changefeed page, after_seq exclusive. */
+  since(afterSeq: number | bigint, limit?: number): {
+    nodes: Array<Record<string, unknown>>; from_seq: number; to_seq: number;
+    head_seq: number; has_more: boolean;
+  };
+  /** DAG-native: replication readiness. */
+  scanStatus(): { scan_complete: boolean; tip_seq: number; indexed_count: number; [k: string]: unknown };
+}
+
+export declare function wrapRedis<T extends object = object>(client: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapSqlite<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapMysql<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapPg<T extends object = object>(conn: T, opts?: WrapOptions): T & { nedb: NedbSurface };
+export declare function wrapMongo<T extends object = object>(client: T, opts?: WrapOptions): T & { nedb: NedbSurface };

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "nedb-engine",
-  "version": "2.8.6",
+  "version": "3.1.0",
   "description": "NEDB — hash-chained, time-traveling, bi-temporal embedded database with Rust native core. SQL, Redis, MongoDB adapters. Causal Write Provenance. RESP2 wire protocol.",
   "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.js"
+    },
+    "./wrap": "./wrap/index.js"
+  },
   "types": "index.d.ts",
   "bin": {
     "nedbd-v2": "./nedbd-v2.js",
@@ -14,6 +21,7 @@
     "index.d.ts",
     "native.js",
     "native.d.ts",
+    "wrap/",
     "nedbd-v2.js",
     "nedb-inspector.mjs",
     "*.node",
@@ -23,7 +31,7 @@
     "README.md",
     "LICENSE"
   ],
-  "license": "GPL-3.0-or-later",
+  "license": "MIT",
   "homepage": "https://github.com/aiassistsecure/nedb#readme",
   "repository": {
     "type": "git",

package/wrap/index.js

@@ -0,0 +1,24 @@
+'use strict';
+// nedb/wrap/index.js — the JS wrap adapter family.
+//
+//   const { wrapRedis, wrapSqlite, wrapMysql, wrapPg, wrapMongo } =
+//     require('nedb-engine/wrap');
+//
+// Every wrapper: register → backfill → shadowWrites=true → full NEDB API on
+// `.nedb`, with the embedded v2/v3 DAG (Rust napi core) as the default engine.
+//
+// © INTERCHAINED LLC × Claude Sonnet 4.6
+'use strict';
+
+const { WrapSurface, openEngine, CollectionMapping, NedbdProxy, NativeEngine } = require('./surface');
+const { wrapRedis, WRITE_CMDS } = require('./redis');
+const { wrapSqlite, wrapMysql, wrapPg, SqlSurface } = require('./sql');
+const { wrapMongo, MongoSurface } = require('./mongo');
+
+module.exports = {
+  // adapters
+  wrapRedis, wrapSqlite, wrapMysql, wrapPg, wrapMongo,
+  // surface primitives (for custom adapters)
+  WrapSurface, openEngine, CollectionMapping, NedbdProxy, NativeEngine,
+  SqlSurface, MongoSurface, WRITE_CMDS,
+};

package/wrap/mongo.js

@@ -0,0 +1,91 @@
+'use strict';
+// nedb/wrap/mongo.js — wrapMongo: causal provenance for MongoDB (JS).
+//
+//   const { wrapMongo } = require('nedb-engine/wrap');
+//   const client = wrapMongo(mongoClient, { dbName: 'app' });
+//
+//   client.nedb.register('app.drivers', 'driver');   // "db.collection" ns
+//   client.nedb.backfill();
+//   client.nedb.shadowWrites = true;
+//
+//   // your code unchanged; after each write, chain it:
+//   await client.db().collection('drivers').insertOne({ name: 'Bob' });
+//   client.nedb.shadowRow('app.drivers', { _id: r.insertedId, name: 'Bob' });
+//
+// © INTERCHAINED LLC × Claude Sonnet 4.6
+'use strict';
+
+const { WrapSurface, openEngine } = require('./surface');
+
+class MongoSurface extends WrapSurface {
+  constructor(client, dbName, engine) {
+    super(dbName, engine);
+    this.client = client;
+  }
+
+  /** hostScan: iterate docs of a "db.collection" namespace (sync only —
+   *  pymongo-style cursor.toArray is async, so JS backfill for the native
+   *  driver is async; provide scanAsync). */
+  hostScan(mapping) { return []; }
+
+  async hostScanAsync(mapping, batchSize) {
+    const [dbName, collName] = mapping.pattern.split('.');
+    const out = [];
+    try {
+      const coll = this.client.db(dbName).collection(collName);
+      const cursor = coll.find({});
+      while (await cursor.hasNext()) {
+        const doc = await cursor.next();
+        const { _id, ...rest } = doc;
+        out.push([String(_id), rest]);
+        if (out.length >= (batchSize || 200)) break;
+      }
+    } catch (_) { /* skip */ }
+    return out;
+  }
+
+  shadowDoc() { return null; }
+
+  /** Explicit row shadow: routes into the registered collection. */
+  shadowRow(ns, doc, op = 'UPSERT') {
+    if (!this.shadowWrites) return;
+    try {
+      const m = this.mappings.find((x) => x.pattern === ns);
+      const coll = m ? m.collection : ns.split('.').pop();
+      if (doc === null || doc === undefined) {
+        this.engine.put('__mongo_shadow__', `${ns}:del:${op}`,
+          { ns, _op: 'DELETE' });
+        return;
+      }
+      const { _id, ...rest } = doc;
+      this.engine.put(coll, String(_id ?? op), { ...rest, _ns: ns, _op: op });
+    } catch (_) { /* never break the host */ }
+  }
+}
+
+class WrappedMongoClient {
+  constructor(client, opts = {}) {
+    const dbName = opts.dbName || 'default';
+    const engine = openEngine({
+      dbName, nedbdUrl: opts.nedbdUrl, nedbdToken: opts.nedbdToken,
+      dagPath: opts.dagPath, dagTmk: opts.dagTmk, native: opts.native,
+    });
+    this._client = client;
+    this.nedb = new MongoSurface(client, dbName, engine);
+  }
+  _raw() { return this._client; }
+}
+
+function wrapMongo(client, opts) {
+  const w = new WrappedMongoClient(client, opts);
+  return new Proxy(w, {
+    get(target, prop, receiver) {
+      if (prop in target || prop === 'nedb') return Reflect.get(target, prop, receiver);
+      const v = Reflect.get(target._client, prop);
+      return typeof v === 'function' ? v.bind(target._client) : v;
+    },
+    set(target, prop, value) { target._client[prop] = value; return true; },
+  });
+}
+
+module.exports = { wrapMongo, WrappedMongoClient, MongoSurface };

package/wrap/redis.js

@@ -0,0 +1,134 @@
+'use strict';
+// nedb/wrap/redis.js — wrapRedis: one-line causal provenance for Redis (JS).
+//
+//   const { wrapRedis } = require('nedb-engine/wrap');
+//   const redis = require('redis');
+//
+//   const r = wrapRedis(redis.createClient(), { dbName: 'rideshare' });
+//
+//   r.nedb.register('driver:*', 'driver');
+//   r.nedb.backfill();
+//   r.nedb.shadowWrites = true;
+//
+//   await r.set('driver:d1', JSON.stringify({ name: 'Bob' }));  // shadowed
+//   r.nedb.query('FROM driver');                                 // NQL on top
+//   r.nedb.verify();                                             // → true
+//
+// Works with any client whose write methods are functions on the connection
+// (node-redis v4, ioredis, redis-mock). Write commands are intercepted by
+// wrapping the method — the surface-1 behavior is unchanged.
+//
+// © INTERCHAINED LLC × Claude Sonnet 4.6
+'use strict';
+
+const { WrapSurface, openEngine } = require('./surface');
+
+// Redis write commands we shadow (mirrors the Python _WRITE_CMDS set).
+const WRITE_CMDS = new Set([
+  'set', 'setnx', 'setex', 'psetex', 'getset', 'getdel', 'getex',
+  'mset', 'msetnx', 'hset', 'hmset', 'hsetnx', 'hincrby', 'hincrbyfloat', 'hdel',
+  'lpush', 'rpush', 'lset', 'linsert', 'ltrim', 'lpop', 'rpop',
+  'sadd', 'srem', 'smove', 'zadd', 'zincrby', 'zrem',
+  'del', 'unlink', 'rename', 'renamenx', 'append', 'incr', 'incrby', 'decr', 'decrby',
+]);
+
+class RedisSurface extends WrapSurface {
+  constructor(client, dbName, engine) {
+    super(dbName, engine);
+    this.client = client;
+  }
+
+  // ── host scan: iterate keys matching the pattern, read their values ──────
+  hostScan(mapping, batchSize) {
+    // node-redis v4 / ioredis both expose scan + get/hgetall; a sync-scan
+    // fallback covers in-memory fakes.
+    const out = [];
+    const scanSync = typeof this.client.scanKeys === 'function'
+      ? this.client.scanKeys(mapping.pattern)
+      : (this.client.keys ? this.client.keys(mapping.pattern) : []);
+    for (const key of scanSync || []) {
+      try {
+        const raw = mapping.valueType === 'hash'
+          ? this.client.hgetall(key)
+          : this.client.get(key);
+        if (raw !== null && raw !== undefined) out.push([key, raw]);
+      } catch (_) { /* skip unreadable */ }
+      if (out.length >= (batchSize || 200)) break;
+    }
+    return out;
+  }
+
+  // ── host write → NEDB doc ──────────────────────────────────────────────────
+  // args = the host call's arguments AFTER the key.
+  // __replace: true → surface puts doc as-is (full replace); default merges.
+  shadowDoc(mapping, cmd, args) {
+    if (cmd === 'hset') {
+      // hset key field value | hset key {obj}
+      if (typeof args[0] === 'object' && args[0] !== null) return mapping.parseValue(args[0]);
+      return { [args[0]]: args[1] };   // merged over existing by the surface
+    }
+    if (cmd === 'set' || cmd === 'setex' || cmd === 'psetex' || cmd === 'setnx' || cmd === 'getset') {
+      return { ...mapping.parseValue(args[0]), __replace: true };
+    }
+    if (cmd === 'incr' || cmd === 'incrby' || cmd === 'decr' || cmd === 'decrby') {
+      return { _v: String(args[0] === undefined ? '' : args[0]) };
+    }
+    if (cmd === 'del' || cmd === 'unlink') {
+      return { _deleted: true, __replace: true };
+    }
+    // other write types: store the command as metadata (merged)
+    return { [`_redis_${cmd}`]: String(args[0] === undefined ? '' : args[0]) };
+  }
+}
+
+class WrappedRedis {
+  constructor(client, opts = {}) {
+    const dbName = opts.dbName || 'default';
+    const engine = openEngine({
+      dbName, nedbdUrl: opts.nedbdUrl, nedbdToken: opts.nedbdToken,
+      dagPath: opts.dagPath, dagTmk: opts.dagTmk, native: opts.native,
+    });
+    this._client = client;
+    this.nedb = new RedisSurface(client, dbName, engine);
+    this._installInterception();
+  }
+
+  _installInterception() {
+    const surface = this.nedb;
+    const client = this._client;
+    for (const cmd of WRITE_CMDS) {
+      const orig = client[cmd];
+      if (typeof orig !== 'function' || orig.__nedbWrapped) continue;
+      const wrapped = function (...args) {
+        const result = orig.apply(client, args);
+        try {
+          const key = args[0];
+          if (typeof key === 'string' && surface.shadowWrites) surface.shadow(cmd, key, ...args.slice(1));
+        } catch (_) { /* never break the host call */ }
+        return result;
+      };
+      wrapped.__nedbWrapped = true;
+      try { client[cmd] = wrapped; } catch (_) { /* frozen client — skip */ }
+    }
+  }
+
+  // passthrough for everything else
+  __getattrPrivate(name) { return this._client[name]; }
+  get _raw() { return this._client; }
+}
+
+function wrapRedis(client, opts) {
+  const w = new WrappedRedis(client, opts);
+  // Proxy property access to the underlying client so `await r.get(...)`
+  // works naturally, while `.nedb` stays on the wrapper.
+  return new Proxy(w, {
+    get(target, prop, receiver) {
+      if (prop in target || prop === 'nedb' || prop === '_client') return Reflect.get(target, prop, receiver);
+      const v = target._client[prop];
+      return typeof v === 'function' ? v.bind(target._client) : v;
+    },
+    set(target, prop, value) { target._client[prop] = value; return true; },
+  });
+}
+
+module.exports = { wrapRedis, WrappedRedis, RedisSurface, WRITE_CMDS };

package/wrap/sql.js

@@ -0,0 +1,151 @@
+'use strict';
+// nedb/wrap/sql.js — wrapSqlite / wrapMysql / wrapPg: causal provenance for
+// SQL databases (JS).
+//
+//   const { wrapSqlite } = require('nedb-engine/wrap');
+//   const db = wrapSqlite(mySqliteConnection, { dbName: 'app' });
+//
+//   db.nedb.register('drivers', 'driver');
+//   db.nedb.backfill();
+//   db.nedb.shadowWrites = true;
+//
+// SQLite: execute() is intercepted — INSERT/UPDATE/DELETE on registered
+// tables are shadowed automatically after they succeed.
+// MySQL/Postgres (DB-API style or promise clients): shadowing is explicit —
+// after your INSERT/UPDATE call db.nedb.shadowRow(table, pk, rowObj);
+// row=null chains a DELETE tombstone.
+//
+// © INTERCHAINED LLC × Claude Sonnet 4.6
+'use strict';
+
+const { WrapSurface, openEngine } = require('./surface');
+
+class SqlSurface extends WrapSurface {
+  constructor(conn, dbName, engine, kind) {
+    super(dbName, engine);
+    this.conn = conn;
+    this.kind = kind;
+  }
+
+  /** Default host scan: SELECT * FROM <table> — works on sync sqlite3 and
+   *  promise clients that expose .all/.query. Override for exotic drivers. */
+  hostScan(mapping, batchSize) {
+    const table = mapping.pattern;
+    const out = [];
+    const push = (cols, rows) => {
+      for (const row of rows || []) {
+        if (Array.isArray(row)) out.push([String(out.length + 1), Object.fromEntries(cols.map((c, i) => [c, row[i]]))]);
+        else out.push([String(row[cols[0]] ?? out.length + 1), row]);
+      }
+    };
+    if (typeof this.conn.all === 'function') {           // node-sqlite3 style
+      // sync reads aren't available; caller should backfill via callback mode.
+      return out;
+    }
+    if (typeof this.conn.prepare === 'function') {        // better-sqlite3
+      const stmt = this.conn.prepare(`SELECT rowid AS __nedb_rowid, * FROM "${table}"`);
+      for (const row of stmt.iterate()) {
+        const { __nedb_rowid, ...rest } = row;
+        out.push([String(__nedb_rowid), rest]);
+      }
+      return out;
+    }
+    if (typeof this.conn.exec === 'function' && this.conn.prepare === undefined) {
+      // node:sqlite (built-in) — similar to better-sqlite3
+      try {
+        const stmt = this.conn.prepare(`SELECT rowid AS __nedb_rowid, * FROM "${table}"`);
+        for (const row of stmt.iterate ? stmt.iterate() : []) {
+          const { __nedb_rowid, ...rest } = row;
+          out.push([String(__nedb_rowid), rest]);
+        }
+        return out;
+      } catch (_) { /* fall through */ }
+    }
+    if (typeof this.conn.query === 'function') {          // mysql2 / pg promise
+      // handled by host adapters with async backfill — sync scan unsupported
+      return out;
+    }
+    return out;
+  }
+
+  shadowDoc() { return null; }
+
+  /** Explicit row shadow (mysql/pg): routes into the registered collection. */
+  shadowRow(table, pk, row, op = 'UPSERT') {
+    if (!this.shadowWrites) return;
+    try {
+      if (row === null || row === undefined) {
+        this.engine.put('__sql_shadow__', `${table}:del:${pk}`,
+          { table, pk: String(pk), _op: 'DELETE' });
+        return;
+      }
+      const m = this.mappings.find((x) => x.pattern === table);
+      const coll = m ? m.collection : '__sql_shadow__';
+      this.engine.put(coll, String(pk), { ...row, _table: table, _op: op });
+    } catch (_) { /* never break the host */ }
+  }
+}
+
+class WrappedSqlConn {
+  constructor(conn, opts, kind) {
+    const dbName = opts.dbName || 'default';
+    const engine = openEngine({
+      dbName, nedbdUrl: opts.nedbdUrl, nedbdToken: opts.nedbdToken,
+      dagPath: opts.dagPath, dagTmk: opts.dagTmk, native: opts.native,
+    });
+    this._conn = conn;
+    this.nedb = new SqlSurface(conn, dbName, engine, kind);
+    if (kind === 'sqlite') this._installSqliteInterception();
+  }
+
+  /** sqlite3/better-sqlite/node:sqlite — wrap exec/run/execute for shadowing. */
+  _installSqliteInterception() {
+    const surface = this.nedb;
+    const conn = this._conn;
+    const methodNames = ['execute', 'run', 'exec'].filter((m) => typeof conn[m] === 'function');
+    for (const name of methodNames) {
+      const orig = conn[name];
+      if (orig.__nedbWrapped) continue;
+      const wrapped = function (sql, ...rest) {
+        const result = orig.call(conn, sql, ...rest);
+        try {
+          if (surface.shadowWrites && /^\s*(INSERT|UPDATE|DELETE|REPLACE)/i.test(String(sql))) {
+            surface.shadow('sql', sql, 'sql', sql, result);
+          }
+        } catch (_) {}
+        return result;
+      };
+      wrapped.__nedbWrapped = true;
+      try { conn[name] = wrapped; } catch (_) {}
+    }
+    // transactional helpers pass through
+  }
+
+  _raw() { return this._conn; }
+}
+
+function _wrapWithProxy(wrapper, conn) {
+  return new Proxy(wrapper, {
+    get(target, prop, receiver) {
+      if (prop in target || prop === 'nedb') return Reflect.get(target, prop, receiver);
+      const v = Reflect.get(conn, prop);
+      return typeof v === 'function' ? v.bind(conn) : v;
+    },
+    set(target, prop, value) { conn[prop] = value; return true; },
+  });
+}
+
+function wrapSqlite(conn, opts) {
+  return _wrapWithProxy(new WrappedSqlConn(conn, opts || {}, 'sqlite'), conn);
+}
+function wrapMysql(conn, opts) {
+  return _wrapWithProxy(new WrappedSqlConn(conn, opts || {}, 'mysql'), conn);
+}
+function wrapPg(conn, opts) {
+  const w = new WrappedSqlConn(conn, opts || {}, 'pg');
+  const p = _wrapWithProxy(w, conn);
+  // pg uses .query — shadowRow is explicit on the surface
+  return p;
+}
+
+module.exports = { wrapSqlite, wrapMysql, wrapPg, WrappedSqlConn, SqlSurface };

package/wrap/surface.js

@@ -0,0 +1,330 @@
+'use strict';
+// nedb/wrap/surface.js — the engine-agnostic NEDB layer-2 surface (JS).
+//
+// One contract, three engines:
+//   dag      — embedded Rust core (NedbCore from the napi-rs addon)
+//   nedbd    — HTTP nedbd server (v1 AOF, v2 DAG, v3 --dag-v3)
+//   memory   — a caller-supplied engine object (tests, custom backends)
+//
+// Host adapters (wrapRedis/wrapSqlite/wrapMysql/wrapMongo/wrapPg) supply:
+//   hostScan(mapping)          → iterate existing host records
+//   shadowDoc(mapping, args)   → host write → NEDB doc (or null)
+//
+// © INTERCHAINED LLC × Claude Sonnet 4.6
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ── engine resolution ────────────────────────────────────────────────────────
+
+/** Acquire the NedbCore class: caller-supplied, native addon, or throw. */
+function resolveNative(provided) {
+  if (provided) return provided;
+  try {
+    return require('../index.js').NedbCore;
+  } catch (_) {
+    throw new Error(
+      'nedb-engine native addon not found — rebuild with `npm run build` ' +
+      'or pass an engine explicitly (wrap(x, { engine }) / { nedbdUrl })');
+  }
+}
+
+/**
+ * Open an engine handle for a wrap_* surface.
+ *   openEngine({ nedbdUrl, nedbdToken, dagPath, engine }) → handle
+ * The handle exposes: put/get/query/createIndex/delete/link/unlink/
+ * neighbors/inbound/verify()/head/seq + engineKind.
+ */
+function openEngine(opts = {}) {
+  if (opts.engine) return normalizeEngine(opts.engine, 'supplied');
+
+  if (opts.nedbdUrl) return new NedbdProxy(opts.nedbdUrl, opts.dbName, opts.nedbdToken);
+
+  const NedbCore = resolveNative(opts.native);
+  const core = opts.dagPath
+    ? NedbCore.open(opts.dagPath, opts.dagTmk || null)
+    : new NedbCore();
+  return normalizeEngine(core, 'dag-embedded');
+}
+
+/** Normalize any engine-ish object into the canonical duck-typed contract. */
+function normalizeEngine(core, kind) {
+  // HTTP proxy shape → pass through as-is
+  if (core instanceof NedbdProxy) return core;
+  return new NativeEngine(core, kind);
+}
+
+// ── Native engine handle (embedded Rust DAG) ────────────────────────────────
+
+class NativeEngine {
+  constructor(core, kind) {
+    this.core = core;
+    this.kind = kind || 'dag-embedded';
+  }
+  put(coll, id, doc) {
+    const body = { ...doc };
+    for (const k of ['caused_by', 'valid_from', 'valid_to']) {
+      if (body[k] === undefined) delete body[k];
+    }
+    const node = this.core.put(coll, id, JSON.stringify(body));
+    return typeof node === 'string' ? JSON.parse(node) : node;
+  }
+  get(coll, id, asOf) {
+    const node = asOf === undefined || asOf === null
+      ? this.core.get(coll, id)
+      : this.core.get(coll, id, asOf);
+    return node ? (typeof node === 'string' ? JSON.parse(node) : node) : null;
+  }
+  query(nql) {
+    const rows = this.core.query(nql);
+    return rows.map((r) => (typeof r === 'string' ? JSON.parse(r) : r));
+  }
+  createIndex(coll, field, kind) { this.core.createIndex(coll, field, kind || 'eq'); }
+  delete(coll, id) { this.core.delete(coll, id); }
+  link(frm, rel, to) { this.core.link(frm, rel, to); }
+  unlink(frm, rel, to) { this.core.unlink(frm, rel, to); }
+  neighbors(frm, rel, asOf) {
+    return asOf === undefined ? this.core.neighbors(frm, rel)
+                              : this.core.neighbors(frm, rel, asOf);
+  }
+  inbound(to, rel, asOf) {
+    return asOf === undefined ? this.core.inbound(to, rel)
+                              : this.core.inbound(to, rel, asOf);
+  }
+  verify() { return this.core.verify() === true; }
+  get head() { return this.core.head(); }
+  get seq() { return this.core.seq(); }
+  checkpoint() { this.core.flush(); return this.head; }
+  tip() { const t = this.core.tip ? this.core.tip() : null; return t ? JSON.parse(t) : null; }
+  since(afterSeq, limit) {
+    if (!this.core.since) throw new Error('changefeed requires the DAG backend');
+    // napi binding: after_seq is u64 (BigInt), limit is usize (Number)
+    const after = typeof afterSeq === 'bigint' ? afterSeq : BigInt(afterSeq);
+    const lim = limit === undefined ? 0 : Number(limit);
+    return JSON.parse(this.core.since(after, lim));
+  }
+  scanStatus() {
+    if (!this.core.scanStatus) throw new Error('scanStatus requires the DAG backend');
+    return JSON.parse(this.core.scanStatus());
+  }
+  flush() { if (this.core.flush) this.core.flush(); }
+  get engineKind() { return this.kind; }
+}
+
+// ── HTTP nedbd handle ────────────────────────────────────────────────────────
+
+class NedbdProxy {
+  constructor(baseUrl, dbName, token) {
+    this.base = baseUrl.replace(/\/$/, '');
+    this.name = dbName;
+    this.token = token || null;
+    this._ensureDb();
+  }
+  _headers() {
+    const h = { 'Content-Type': 'application/json', Accept: 'application/json' };
+    if (this.token) h.Authorization = `Bearer ${this.token}`;
+    return h;
+  }
+  _req(method, p, body) {
+    const http = require('http');
+    const url = new URL(this.base + p);
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const res = http.request({
+      hostname: url.hostname, port: url.port || 80, path: url.pathname + url.search,
+      method, headers: { ...this._headers(), ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}) },
+    });
+    // synchronous-feeling via Atomics.wait on a SharedArrayBuffer flag
+    const flag = new Int32Array(new SharedArrayBuffer(4));
+    let out = { status: 0, text: '' };
+    const r2 = res;
+    r2.on('response', (r) => {
+      let t = '';
+      r.on('data', (c) => { t += c; });
+      r.on('end', () => { out = { status: r.statusCode, text: t }; Atomics.store(flag, 0, 1); Atomics.notify(flag, 0); });
+    });
+    r2.on('error', (e) => { out = { status: 0, text: String(e) }; Atomics.store(flag, 0, 1); Atomics.notify(flag, 0); });
+    if (payload) r2.write(payload);
+    r2.end();
+    Atomics.wait(flag, 0, 0);
+    if (out.status === 0) throw new Error(`nedbd ${method} ${p} failed: ${out.text}`);
+    let parsed;
+    try { parsed = JSON.parse(out.text); } catch { parsed = { raw: out.text }; }
+    if (out.status >= 400) throw new Error(`nedbd ${method} ${p} → HTTP ${out.status}: ${out.text.slice(0, 200)}`);
+    return parsed;
+  }
+  _db(suffix) { return `/v1/databases/${this.name}${suffix || ''}`; }
+  _ensureDb() {
+    try { this._req('GET', this._db()); } catch (e) {
+      if (String(e).includes('404')) this._req('POST', '/v1/databases', { name: this.name });
+      else throw e;
+    }
+  }
+  put(coll, id, doc, kw = {}) {
+    const payload = { coll, id, doc };
+    for (const k of ['client', 'nonce', 'idem', 'evidence', 'confidence', 'valid_from', 'valid_to', 'caused_by']) {
+      if (kw[k] !== undefined && kw[k] !== null) payload[k] = kw[k];
+    }
+    const r = this._req('POST', this._db('/put'), payload);
+    return r.doc !== undefined ? r.doc : doc;
+  }
+  get(coll, id, asOf) {
+    const clause = asOf !== undefined && asOf !== null ? ` AS OF ${asOf}` : '';
+    const rows = this.query(`FROM ${coll}${clause} WHERE _id = "${id}"`);
+    return rows.length ? rows[0] : null;
+  }
+  query(nql) { return this._req('POST', this._db('/query'), { nql }).rows || []; }
+  createIndex(coll, field, kind) { this._req('POST', this._db('/index'), { coll, field, kind: kind || 'eq' }); }
+  delete(coll, id) { this._req('DELETE', `/v1/databases/${this.name}/rows/${coll}/${id}`); }
+  link(frm, rel, to) {
+    try { this._req('POST', this._db('/link'), { frm, rel, to }); }
+    catch (e) {
+      if (String(e).includes('404') || String(e).toLowerCase().includes('not found')) {
+        this.put('__links__', `${frm}|${rel}|${to}`, { _from: frm, _rel: rel, _to: to });
+      } else throw e;
+    }
+  }
+  unlink(frm, rel, to) {
+    try { this._req('DELETE', `/v1/databases/${this.name}/links/${frm}/${rel}/${to}`); }
+    catch (_) { try { this._req('DELETE', `/v1/databases/${this.name}/rows/__links__/${frm}|${rel}|${to}`); } catch (_) {} }
+  }
+  neighbors(frm, rel, asOf) {
+    const clause = asOf !== undefined && asOf !== null ? ` AS OF ${asOf}` : '';
+    const [c] = frm.split(':');
+    const rows = this.query(`FROM ${c}${clause} WHERE _id = "${frm.split(':')[1] || ''}" TRAVERSE ${rel}`);
+    return rows.filter((r) => r._id).map((r) => `${r._coll || c}:${r._id}`);
+  }
+  inbound(to, rel, asOf) {
+    const clause = asOf !== undefined && asOf !== null ? ` AS OF ${asOf}` : '';
+    const [c] = to.split(':');
+    try {
+      const rows = this.query(`FROM ${c} WHERE _id = "${to.split(':')[1] || ''}" TRAVERSE ${rel} REVERSE`);
+      return rows.filter((r) => r._id).map((r) => `${r._coll || c}:${r._id}`);
+    } catch (_) { return []; }
+  }
+  verify() { return this._req('GET', this._db('/verify')).ok === true; }
+  get head() { return this._req('GET', this._db()).head || '0'.repeat(64); }
+  get seq() { return this._req('GET', this._db()).seq || 0; }
+  checkpoint() { return this._req('POST', this._db('/checkpoint')).head || this.head; }
+  get engineKind() { return 'nedbd-http'; }
+}
+
+// ── collection mapping (key/table glob → NEDB collection) ───────────────────
+
+class CollectionMapping {
+  constructor(pattern, collection, opts = {}) {
+    this.pattern = pattern;
+    this.collection = collection;
+    this.idExtractor = opts.idExtractor || ((k) => k.split(':').pop());
+    this.valueParser = opts.valueParser || CollectionMapping.defaultParse;
+    this.valueType = opts.valueType || 'string';
+  }
+  static defaultParse(v) {
+    if (v === null || v === undefined) return { _v: null };
+    if (typeof v === 'object') return v;
+    const s = String(v);
+    try {
+      const p = JSON.parse(s);
+      return (p && typeof p === 'object') ? p : { _v: p };
+    } catch { return { _v: s }; }
+  }
+  matches(key) {
+    // translate a glob to a RegExp (tiny, no deps)
+    const rx = new RegExp('^' + this.pattern
+      .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+    return rx.test(key);
+  }
+  extractId(key) { return this.idExtractor(key); }
+  parseValue(v) { return this.valueParser(v); }
+}
+
+// ── the shared surface (the `.nedb` attribute) ──────────────────────────────
+
+class WrapSurface {
+  constructor(dbName, engine) {
+    this.dbName = dbName;
+    this.engine = engine;
+    this.mappings = [];
+    this.shadowWrites = false;
+    this.backfilled = false;
+  }
+
+  // host hooks — override in host adapters
+  hostScan(/* mapping, batchSize */) { return []; }
+  shadowDoc(/* mapping, cmd, args */) { return null; }
+
+  register(pattern, collection, opts) {
+    this.mappings.push(new CollectionMapping(pattern, collection, opts));
+    return this;
+  }
+  mappingFor(key) { return this.mappings.find((m) => m.matches(key)) || null; }
+
+  backfill(opts = {}) {
+    const mappings = opts.pattern
+      ? [new CollectionMapping(opts.pattern, opts.collection || opts.pattern.split(':')[0], opts)]
+      : this.mappings;
+    let total = 0;
+    for (const m of mappings) {
+      for (const [key, raw] of this.hostScan(m, opts.batchSize || 200)) {
+        try {
+          const doc = m.parseValue(raw);
+          doc._source = 'backfill';
+          this.engine.put(m.collection, m.extractId(key), doc);
+          total += 1;
+        } catch (_) { /* skip unreadable */ }
+      }
+    }
+    this.backfilled = true;
+    return total;
+  }
+
+  shadow(cmd, key, ...rest) {
+    if (!this.shadowWrites) return;
+    try {
+      const m = this.mappingFor(key);
+      if (!m) {
+        this.engine.put('__shadow_raw__', key, { cmd, key, _source: 'shadow_raw' });
+        return;
+      }
+      // rest = the host call's arguments AFTER the key (value(s) / fields)
+      const doc = this.shadowDoc(m, cmd, rest);
+      if (!doc) return;
+      doc._source = 'shadow';
+      const id = m.extractId(key);
+      // merge over the existing doc (hset/incr are incremental by nature;
+      // set replaces — the adapter marks replacement with doc.__replace)
+      const prev = this.engine.get(m.collection, id);
+      const merged = doc.__replace || !prev ? doc : { ...prev, ...doc };
+      delete merged.__replace;
+      this.engine.put(m.collection, id, merged);
+    } catch (e) { if (process.env.NEDB_WRAP_DEBUG) console.error('[nedb shadow]', e); }
+  }
+
+  // ── full NEDB API ──────────────────────────────────────────────────────────
+  put(coll, id, doc, kw) { return this.engine.put(coll, id, doc, kw); }
+  get(coll, id, asOf) { return this.engine.get(coll, id, asOf); }
+  query(nql) { return this.engine.query(nql); }
+  createIndex(coll, field, kind) { this.engine.createIndex(coll, field, kind); }
+  delete(coll, id) { return this.engine.delete(coll, id); }
+  link(frm, rel, to) { return this.engine.link(frm, rel, to); }
+  unlink(frm, rel, to) { return this.engine.unlink(frm, rel, to); }
+  neighbors(frm, rel, asOf) { return this.engine.neighbors(frm, rel, asOf); }
+  inbound(to, rel, asOf) { return this.engine.inbound(to, rel, asOf); }
+  verify() { return this.engine.verify(); }
+  get head() { return this.engine.head; }
+  get seq() { return this.engine.seq; }
+  checkpoint() { return this.engine.checkpoint(); }
+  tip() { return this.engine.tip ? this.engine.tip() : null; }
+  since(afterSeq, limit) { return this.engine.since(afterSeq, limit); }
+  scanStatus() { return this.engine.scanStatus(); }
+  get engineKind() { return this.engine.engineKind; }
+
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    return `<WrapSurface db=${JSON.stringify(this.dbName)} engine=${this.engineKind} mappings=${this.mappings.length}>`;
+  }
+}
+
+module.exports = {
+  openEngine, NativeEngine, NedbdProxy, CollectionMapping, WrapSurface, resolveNative,
+};