nedb-engine 3.0.0 → 3.2.1

package/README.md

@@ -26,86 +26,114 @@ One Rust core → ships to **PyPI** and **npm** from a single source.
 
 ---
 
-## ⚠️ New in 2.8.6 — Durability & Recovery (read this if you store anything you care about)
+## New in 3.2.0 — wrap the databases you already run
 
-Three defects found by killing a real engine at every persistence boundary and by filling a real
-filesystem to zero free blocks. All three are fixed. **If you are on 2.8.5 or earlier, upgrade.**
+NEDB adds **tamper-evident causal provenance to a database you already have**, in one line, without
+rip-and-replace. Five adapters, one surface:
 
-### 1. A failed flush silently discarded acknowledged writes
+```python
+from nedb import wrap_redis, wrap_sqlite, wrap_mysql, wrap_mongo, wrap_postgresql
 
-`IdIndex::flush_write_buf` cleared every buffered entry regardless of whether its disk write
-succeeded. So a flush that hit `ENOSPC` threw the entry away, and no later flush retried it.
+r = wrap_redis(redis.Redis())        # or wrap_sqlite(sqlite3.connect("app.db")), ...
+r.nedb.register("driver:*", "driver")   # teach NEDB the host's shape
+r.nedb.backfill()                       # import what is already there
+r.nedb.shadow_writes = True             # every future write is chained
 
-Reproduced on a full 22 MiB filesystem: **30 rows acknowledged by `put() -> Ok`, then `list()`
-returned 0 after reopen — while `verify()` reported all 30 objects healthy.** The content-addressed
-objects were durable; the id-index entries that make them findable were gone.
+r.set("driver:d1", json.dumps({"name": "Bob", "status": "active"}))
 
-```
-before:  try_flush_all() -> (no return value)      reopen -> 0 rows, verify() = 30 ok
-after:   try_flush_all() -> Err("id-index leaf rows/buf_25: No space left on device (os error 28)")
-         ...free space, retry -> Ok                reopen -> 30 rows
+r.nedb.query('FROM driver WHERE status = "active"')   # NQL over your Redis data
+r.nedb.query('FROM driver AS OF 41')                  # what it looked like at seq 41
+r.nedb.verify()                                       # True — BLAKE2b chain intact
 ```
 
-**Fixed:** an entry leaves the WAL only when its write actually landed. Failures stay buffered and
-retry on the next flush.
+| wrapper | host | shadowing |
+|---|---|---|
+| `wrap_redis` | `redis.Redis` / compatible | automatic — every write command intercepted |
+| `wrap_sqlite` | `sqlite3.Connection` | automatic — `execute()` intercepted post-write |
+| `wrap_mysql` | DB-API 2.0 (mysql-connector, PyMySQL) | explicit `shadow_row()` |
+| `wrap_mongo` | `pymongo.MongoClient` | explicit `shadow_row()` |
+| `wrap_postgresql` | DB-API 2.0 (psycopg2, psycopg 3) | explicit `shadow_row()` |
+
+**NEDB never writes into the host database's namespace.** Shadow data lives only in the NEDB engine.
+
+Three backends behind the same surface, selected by `backend="auto"`: **nedbd over HTTP** (`nedbd_url=`),
+**embedded v2/v3 DAG** (the Rust core, in-process, no server — `dag_path=` for a durable store,
+`dag_tmk=` for AES-256-GCM at rest), or the **v1 in-process AOF** engine as a universal fallback. On the
+DAG backend you also get `tip()`, `tip_collection()`, `since()` (changefeed) and `scan_status()`.
+
+### 🟢 MIT licensed since 3.0.0
+
+No production restriction, no copyleft, no Change Date. Use it in production, embed it commercially,
+ship it closed-source, fork it, sell it. License review is a wall, not a speed bump — that wall is gone.
+
+### Also in 3.2.0
+
+- **A durability defect that pinned every embedded database.** The background flush ticker held a
+  strong `Arc<Db>` in an unconditional loop, so the handle was never dropped: the exclusive data-dir
+  `LOCK` was never released (reopening the same path *in the same process* failed with "locked by
+  another process" naming your own pid), every `open()` leaked a thread and the whole `Db`, and
+  flush-on-close could never fire. The ticker now holds a `Weak<Db>` and exits when its owner does.
+  **Live in 2.8.5 through 3.1.0 — upgrade if you embed the engine.**
+- **`wrap_redis` crashed on any install without the native wheel** — the pure-Python fallback path
+  raised `AttributeError` from inside `wrap_redis()`. Fixed.
+- **Prebuilt binaries for `linux-arm64` and musl/Alpine**, on npm and PyPI. Graviton, Ampere, Linux
+  containers on Apple Silicon, and Alpine images previously installed cleanly and then failed at
+  import.
+- **CI actually runs the test suites.** Until now the only workflows fired on a version tag, so the
+  first automated opinion about a change arrived *after* it was published to three registries. All
+  26 suites now run on every push and pull request. It found four real defects in its first hour,
+  including two of the ones listed above.
 
-### 2. Flush errors were unobservable — new `try_flush_all()`
+---
 
-`flush_all()` returns `()` and logged fsync failures to stderr, so a caller could not tell a durable
-flush from a failed one. Anything that takes a destructive or externally-visible action on the
-strength of a persisted record needs to know.
+## Earlier — 2.8.6 durability & recovery
 
-```rust
-// Use this when the outcome matters:
-db.try_flush_all()?;      // Result<()> — id-index WAL + segment sync + MANIFEST
+Three defects found by killing a real engine at every persistence boundary and by filling a real
+filesystem to zero free blocks. **If you are on 2.8.5 or earlier, upgrade.**
 
-// Still available, still logs, nowhere to propagate (ticker / Drop):
-db.flush_all();
-```
+**1. A failed flush silently discarded acknowledged writes.** `IdIndex::flush_write_buf` cleared every
+buffered entry regardless of whether its disk write succeeded, so a flush that hit `ENOSPC` threw the
+entry away and no later flush retried it. Reproduced on a full 22 MiB filesystem: 30 rows acknowledged
+by `put() -> Ok`, then `list()` returned 0 after reopen — while `verify()` reported all 30 objects
+healthy. The content-addressed objects were durable; the id-index entries that make them findable were
+gone. An entry now leaves the WAL only when its write actually landed.
+
+**2. Flush errors were unobservable.** `flush_all()` returns `()`, so a caller could not tell a durable
+flush from a failed one.
 
-Also new: `Db::try_flush_manifest()` and `IdIndex::try_flush_write_buf()`.
+```rust
+db.try_flush_all()?;      // Result<()> — use this when the outcome matters
+db.flush_all();           // still logs; for ticker / Drop, nowhere to propagate
+```
 
-### 3. `repair` could not repair, and `since()` claimed "caught up" while behind
+Also added: `Db::try_flush_manifest()` and `IdIndex::try_flush_write_buf()`.
 
-The cold scan rebuilt `seq_index`, per-collection tips, the Merkle head and `MANIFEST` — but **never
-the id index**. A database whose WAL never reached disk came back with every object verifying and
-`list()` empty, and `nedb-cli repair` printed success without fixing it, because
-`start_cold_scan()` is a deliberate no-op on a warm store.
+**3. `repair` could not repair, and `since()` claimed "caught up" while behind.** The cold scan rebuilt
+`seq_index`, per-collection tips, the Merkle head and `MANIFEST` — but never the id index, and
+`start_cold_scan()` is a deliberate no-op on a warm store, so `nedb-cli repair` printed success on
+exactly the database it exists to fix.
 
 ```bash
 nedb-cli repair ./data
 # repaired: 203 id-index entr(ies) rebuilt, 203 node(s) verified, flushed
 ```
 
-```rust
-let restored = db.repair()?;   // rebuild id index from objects; highest seq wins
-```
-
-Every object carries its own `coll`, `id` and `seq`, so the id index is fully derivable — a lost WAL
-is recoverable and nothing is invented. `repair()` also recomputes head and tips, so a repaired
-database reopens **warm** instead of coming back up cold with an empty head.
-
-Separately, `since()` set `has_more = hit_limit` alone. On a warm boot the seq index is empty **by
-design** (that is why warm start is O(1)), so every lookup missed and `since()` returned zero nodes
-with `has_more = false` — indistinguishable from genuinely up to date. A consumer following the
-documented drain loop stopped one call in, with every record unread.
-
-**Fixed:** `has_more` is true whenever the cursor is behind the log head. `ScanStatus` gains
-**`seq_index_ready`** — replication consumers should gate on that, not on `scan_complete`, which is
-true on a warm boot precisely because the scan was skipped.
+Every object carries its own `coll`, `id` and `seq`, so the index is fully derivable — nothing is
+invented. Separately, `since()` set `has_more = hit_limit` alone; on a warm boot the seq index is empty
+*by design*, so `since()` returned zero nodes with `has_more = false` — indistinguishable from
+genuinely up to date, and a consumer following the documented drain loop stopped one call in with every
+record unread. `has_more` is now true whenever the cursor is behind head, and `ScanStatus` gains
+**`seq_index_ready`** — gate replication on that, not on `scan_complete`.
 
-### Known sharp edge (documented, not changed)
-
-`since()`'s cursor is **exclusive** and seqs start at 0, so `since(0, _)` returns `(0, head]` and the
-very first write in a database (seq 0) is unreachable through any cursor value. Ten writes drain as
-nine records. Changing the convention would break existing consumers; a replica seeded from
-`since()` alone starts one record short.
+**Known sharp edge (documented, not changed):** `since()`'s cursor is **exclusive** and seqs start at 0,
+so `since(0, _)` returns `(0, head]` and the very first write (seq 0) is unreachable through any cursor
+value. Ten writes drain as nine records. Changing the convention would break existing consumers.
 
 ---
 
-## NEDB v2.8.0 — Production Stable
+## NEDB v3.2.0 — Production Stable
 
-**Current stable: 2.8.0** — NEDB ships as **three version-aligned distributions** on one tag — `nedb-engine` (flagship), `crypto-database` (verifiable v2/v3 DAG), and `aof-db` (fast append-only) — across npm / PyPI / crates.io with full mac + linux + windows native addons (see [**Releasing**](#releasing) below). All native wheels (Linux + Windows on GitHub Actions; macOS arm64 + x86_64 on Codemagic M2 Mac Minis) **plus** the universal pure-Python wheel ship from a single `v*` tag, with the `nedbd-v2` binary bundled inside `pip install nedb-engine`.
+**Current stable: 3.2.0** — NEDB ships as **three version-aligned distributions** on one tag — `nedb-engine` (flagship), `crypto-database` (verifiable v2/v3 DAG), and `aof-db` (fast append-only) — across npm / PyPI / crates.io with native addons for **macOS (arm64 + x86_64), Linux (x86_64 + aarch64, glibc + musl) and Windows x86_64** (see [**Releasing**](#releasing) below). All native wheels (Linux + Windows on GitHub Actions; macOS on Codemagic M2 Mac Minis) **plus** the universal pure-Python wheel ship from a single `v*` tag, with the `nedbd-v2` binary bundled inside `pip install nedb-engine`.
 
 ### New in 2.8.0 — Cast: the database understands English
 
@@ -150,7 +178,7 @@ nedbd --dag --data ./data
 NEDBD_DAG=1 NEDB_TMK=<32-byte-hex> nedbd --data ./data
 
 curl http://127.0.0.1:7070/health
-# {"ok":true,"version":"2.2.31","service":"nedbd","engine":"dag","startup_ready":true,"encrypted":true}
+# {"ok":true,"version":"3.2.0","service":"nedbd","engine":"dag","startup_ready":true,"encrypted":true}
 
 # Tail the live event stream (new in v2.2.31)
 curl http://127.0.0.1:7070/events
@@ -204,6 +232,24 @@ pip install nedb-engine      # Python ≥ 3.8 — pure-Python + optional Rust na
 npm install nedb-engine       # Node ≥ 16   — napi-rs prebuilt binaries
 ```
 
+### Prebuilt platforms
+
+Both registries ship prebuilt binaries for:
+
+| Platform | libc | Python wheel | Node addon |
+|---|---|---|---|
+| Linux x86_64 | glibc | ✅ manylinux | ✅ |
+| Linux x86_64 | musl (Alpine) | ✅ musllinux | ✅ |
+| Linux aarch64 (Graviton, Ampere, Apple-Silicon containers) | glibc | ✅ manylinux | ✅ |
+| Linux aarch64 | musl (Alpine) | ✅ musllinux | ✅ |
+| macOS arm64 + x86_64 | — | ✅ | ✅ |
+| Windows x86_64 | MSVC | ✅ | ✅ |
+
+On Python, any platform without a prebuilt wheel still installs: pip falls back
+to the universal `py3-none-any` wheel and you get the pure-Python v1 AOF engine
+(correct, slower, no embedded DAG). On Node there is no such fallback — an
+unlisted platform has no addon.
+
 ---
 
 ## Python — 5-minute tour
@@ -913,7 +959,8 @@ Requires `GITHUB_TOKEN` (`repo` + `workflow` scope) in the environment. It never
 ## Authors
 
 Built by **[Mark Allen Evans Jr.](https://interchained.org)** (INTERCHAINED, LLC)
-with **Claude Sonnet 4.6** on [Hyperagent](https://hyperagent.com/refer/J2G6TCD7).
+with the **Interchained AI fleet** on [Hyperagent](https://hyperagent.com/refer/J2G6TCD7) —
+Vex (GLM · Claude Sonnet · Opus · Fable · GPT-6 Astra/Sol), across hundreds of sessions.
 
 > *"Take one idea, turn it into an LP, then an app, then a system, then a platform, then infrastructure that is irreplaceable."*
 

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/index.js

@@ -15,8 +15,7 @@
 // Escape hatch: set NEDB_NO_EXIT_FLUSH=1 to leave signal handling entirely to
 // the host app (it can still call `db.flush()` itself).
 //
-// © INTERCHAINED LLC × Claude Opus 4.8
-
+// © INTERCHAINED LLC × Vex (Interchained AI fleet: GLM · Claude · Opus · Fable · GPT-6)
 const native = require('./native.js');
 
 const Native = native.NedbCore;

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "nedb-engine",
-  "version": "3.0.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.",
+  "version": "3.2.1",
+  "description": "NEDB \u2014 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",
@@ -53,7 +61,10 @@
       "additional": [
         "aarch64-apple-darwin",
         "x86_64-unknown-linux-gnu",
-        "x86_64-pc-windows-msvc"
+        "x86_64-pc-windows-msvc",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-unknown-linux-musl",
+        "aarch64-unknown-linux-musl"
       ]
     }
   },

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