nedb-engine 3.0.0 → 3.1.0

package/README.md

@@ -303,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.
 

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": "3.0.0",
+  "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",

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,
+};