nedb-engine 2.8.4 → 2.8.6

package/README.md

@@ -20,6 +20,83 @@ 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)
+
+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.**
+
+### 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.
+
+```
+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
+```
+
+**Fixed:** an entry leaves the WAL only when its write actually landed. Failures stay buffered and
+retry on the next flush.
+
+### 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.
+
+```rust
+// Use this when the outcome matters:
+db.try_flush_all()?;      // Result<()> — id-index WAL + segment sync + MANIFEST
+
+// Still available, still logs, nowhere to propagate (ticker / Drop):
+db.flush_all();
+```
+
+Also new: `Db::try_flush_manifest()` and `IdIndex::try_flush_write_buf()`.
+
+### 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**. 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.
+
+```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.
+
+### 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.
+
+---
+
 ## NEDB v2.8.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`.
@@ -47,6 +124,7 @@ Off by default — feature-gated at compile time, flag-gated at runtime, and `ex
 **New in 2.5.x:**
 
 - **Durable-mode auto-flush-on-exit** — a durable store flushes buffered writes on `Ctrl+C` / `SIGTERM`, not just on a clean `Drop`. Automatic in the Node and Python bindings; `Db::install_exit_flush(Arc<Db>)` for standalone Rust binaries. See [**docs/DURABILITY.md**](docs/DURABILITY.md).
+- **2.8.5 — embedded bindings flush on a cadence.** `NedbCore.open()` (Node + Python) now runs the 1 s manifest ticker exactly as `nedbd` does, so a `SIGKILL` / OOM / power cut loses at most one tick of acknowledged writes instead of everything since open. `NEDB_FLUSH_MS` tunes or disables it. See [docs/DURABILITY.md](docs/DURABILITY.md).
 - **`nedb-cli`** — operate on a store directory offline (`head` · `status` · `verify` · `get` · `scan` · `flush` · `repair` · `export`), and **`nedb-inspector`** — a deterministic (no-regex, no-LLM) checker that warns when a durable open lacks flush-on-exit wiring. See [**docs/CLI.md**](docs/CLI.md).
 - **Replication contract** — `tip()` (the latest write), a bounded `since()` changefeed, and a `scan_status()` readiness gate. See [**docs/REPLICATION.md**](docs/REPLICATION.md).
 

package/index.d.ts

@@ -1,64 +1,5 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/* auto-generated by NAPI-RS */
-
-export declare class NedbCore {
-  /** Create an in-memory v2 DAG database — zero disk I/O. */
-  constructor()
-  /**
-   * Open a durable v2 DAG database at `path`.
-   * Automatically migrates v1 AOF → v2 DAG on first open.
-   *
-   * Durable-mode auto-flush-on-exit is wired in the JS wrapper via
-   * `process.on('SIGTERM'|'SIGINT'|'beforeExit', () => db.flush())` — the
-   * libuv-cooperative hook — NOT a C-level signal handler here, which would
-   * clobber libuv's own signal machinery.
-   */
-  static open(path: string): NedbCore
-  createIndex(coll: string, field: string, kind: string): void
-  /** Put a document. Returns the stored doc as a JSON string. */
-  put(coll: string, id: string, docJson: string): string
-  /** Full put with optional client / nonce — API compat, v2 ignores these. */
-  putEx(coll: string, id: string, docJson: string, client?: string | undefined | null, nonce?: bigint | undefined | null, idem?: string | undefined | null): string
-  delete(coll: string, id: string): void
-  deleteEx(coll: string, id: string, client?: string | undefined | null, nonce?: bigint | undefined | null, idem?: string | undefined | null): void
-  /** Link: stored as a doc in __links__ collection for NQL traversal. */
-  link(frm: string, rel: string, to: string): void
-  unlink(frm: string, rel: string, to: string): void
-  get(coll: string, id: string): string | null
-  getAsOf(coll: string, id: string, asOf: bigint): string | null
-  query(nqlStr: string): Array<string>
-  neighbors(frm: string, rel: string): Array<string>
-  neighborsAsOf(frm: string, rel: string, asOf: bigint): Array<string>
-  inbound(to: string, rel: string): Array<string>
-  inboundAsOf(to: string, rel: string, asOf: bigint): Array<string>
-  verify(): boolean
-  head(): string
-  seq(): bigint
-  /** Flush WAL and MANIFEST — v2 equivalent of v1 flush(). */
-  flush(): void
-  /**
-   * The tip — the most recent write (latest node) as a JSON string, or null if
-   * the database is empty. The cheap "give me the latest write" primitive.
-   */
-  tip(): string | null
-  /**
-   * Collection-local tip — the most recent write into `coll` as a JSON string,
-   * or null if the collection has no writes. Resume one chain without filtering.
-   */
-  tipCollection(coll: string): string | null
-  /**
-   * Changefeed page after `after_seq` (exclusive), up to `limit` nodes (0 = the
-   * engine default cap), as a JSON envelope string:
-   * `{nodes, from_seq, to_seq, head_seq, has_more}`. Page while `has_more`,
-   * advancing your cursor to `to_seq`, then attach to the live subscribe edge.
-   */
-  since(afterSeq: bigint, limit: number): string
-  /**
-   * Replication readiness as a JSON string: `{scan_complete, tip_seq,
-   * indexed_seq_min, indexed_seq_max, indexed_count}`. Wait for
-   * `scan_complete == true` before trusting historical `since()` catch-up.
-   */
-  scanStatus(): string
-}
+// nedb-engine — public type surface.
+//
+// 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';

package/index.js

@@ -1,315 +1,81 @@
-/* tslint:disable */
-/* eslint-disable */
-/* prettier-ignore */
+'use strict';
+// nedb-engine — durable-mode auto-flush-on-exit wrapper.
+//
+// The native addon (generated napi binding in ./native.js) exposes `NedbCore`.
+// A durable `NedbCore.open(path)` buffers writes in the engine's id-index WAL and
+// only makes them durable on `flush()`; a hard exit (Ctrl+C, `SIGTERM` from an
+// orchestrator, `pm2 stop`) that never runs an explicit flush would lose writes
+// staged since the last flush.
+//
+// We close that gap the libuv-cooperative way — `process.on('SIGINT'|'SIGTERM'
+// |'exit', () => db.flush())` — NOT a C-level signal handler inside the addon,
+// which would clobber libuv's own signal machinery. In-memory databases
+// (`new NedbCore()`) are never armed; there is nothing to flush.
+//
+// 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
 
-/* auto-generated by NAPI-RS */
+const native = require('./native.js');
 
-const { existsSync, readFileSync } = require('fs')
-const { join } = require('path')
+const Native = native.NedbCore;
 
-const { platform, arch } = process
+// The napi class defines `open` as a NON-writable, NON-configurable static, so the
+// 2.5.x wrapper's `NedbCore.open = …` threw ("Cannot assign to read only property")
+// — and CI's `napi build` was overwriting this file with the generated loader
+// anyway, so the published package never carried the wrapper at all. Both fixed
+// in 2.8.5: wrap by SUBCLASS (an own static on the subclass shadows the parent's),
+// build with `--js native.js` so this file survives, and gate the publish on
+// `NedbCore.__exitFlushWrapped` (see test/durability.test.mjs).
+let NedbCore = Native;
+if (Native && typeof Native.open === 'function' && !Native.__exitFlushWrapped) {
+  // Durable handles opened in this process. Strong refs: a durable DB is meant to
+  // live for the process, and we must be able to flush it on the way out.
+  const live = new Set();
+  let armed = false;
 
-let nativeBinding = null
-let localFileExisted = false
-let loadError = null
-
-function isMusl() {
-  // For Node 10
-  if (!process.report || typeof process.report.getReport !== 'function') {
-    try {
-      const lddPath = require('child_process').execSync('which ldd').toString().trim()
-      return readFileSync(lddPath, 'utf8').includes('musl')
-    } catch (e) {
-      return true
-    }
-  } else {
-    const { glibcVersionRuntime } = process.report.getReport().header
-    return !glibcVersionRuntime
-  }
-}
-
-switch (platform) {
-  case 'android':
-    switch (arch) {
-      case 'arm64':
-        localFileExisted = existsSync(join(__dirname, 'nedb.android-arm64.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.android-arm64.node')
-          } else {
-            nativeBinding = require('nedb-engine-android-arm64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm':
-        localFileExisted = existsSync(join(__dirname, 'nedb.android-arm-eabi.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.android-arm-eabi.node')
-          } else {
-            nativeBinding = require('nedb-engine-android-arm-eabi')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Android ${arch}`)
-    }
-    break
-  case 'win32':
-    switch (arch) {
-      case 'x64':
-        localFileExisted = existsSync(
-          join(__dirname, 'nedb.win32-x64-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.win32-x64-msvc.node')
-          } else {
-            nativeBinding = require('nedb-engine-win32-x64-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'ia32':
-        localFileExisted = existsSync(
-          join(__dirname, 'nedb.win32-ia32-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.win32-ia32-msvc.node')
-          } else {
-            nativeBinding = require('nedb-engine-win32-ia32-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm64':
-        localFileExisted = existsSync(
-          join(__dirname, 'nedb.win32-arm64-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.win32-arm64-msvc.node')
-          } else {
-            nativeBinding = require('nedb-engine-win32-arm64-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Windows: ${arch}`)
-    }
-    break
-  case 'darwin':
-    localFileExisted = existsSync(join(__dirname, 'nedb.darwin-universal.node'))
-    try {
-      if (localFileExisted) {
-        nativeBinding = require('./nedb.darwin-universal.node')
-      } else {
-        nativeBinding = require('nedb-engine-darwin-universal')
-      }
-      break
-    } catch {}
-    switch (arch) {
-      case 'x64':
-        localFileExisted = existsSync(join(__dirname, 'nedb.darwin-x64.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.darwin-x64.node')
-          } else {
-            nativeBinding = require('nedb-engine-darwin-x64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm64':
-        localFileExisted = existsSync(
-          join(__dirname, 'nedb.darwin-arm64.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.darwin-arm64.node')
-          } else {
-            nativeBinding = require('nedb-engine-darwin-arm64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on macOS: ${arch}`)
-    }
-    break
-  case 'freebsd':
-    if (arch !== 'x64') {
-      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
-    }
-    localFileExisted = existsSync(join(__dirname, 'nedb.freebsd-x64.node'))
-    try {
-      if (localFileExisted) {
-        nativeBinding = require('./nedb.freebsd-x64.node')
-      } else {
-        nativeBinding = require('nedb-engine-freebsd-x64')
+  const flushAll = () => {
+    for (const db of live) {
+      try {
+        db.flush();
+      } catch (_) {
+        // Best-effort on shutdown — never throw out of an exit handler.
       }
-    } catch (e) {
-      loadError = e
     }
-    break
-  case 'linux':
-    switch (arch) {
-      case 'x64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-x64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-x64-musl.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-x64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-x64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-x64-gnu.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-x64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'arm64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-arm64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-arm64-musl.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-arm64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-arm64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-arm64-gnu.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-arm64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'arm':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-arm-musleabihf.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-arm-musleabihf.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-arm-musleabihf')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-arm-gnueabihf.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-arm-gnueabihf.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-arm-gnueabihf')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'riscv64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-riscv64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-riscv64-musl.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-riscv64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'nedb.linux-riscv64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./nedb.linux-riscv64-gnu.node')
-            } else {
-              nativeBinding = require('nedb-engine-linux-riscv64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 's390x':
-        localFileExisted = existsSync(
-          join(__dirname, 'nedb.linux-s390x-gnu.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./nedb.linux-s390x-gnu.node')
-          } else {
-            nativeBinding = require('nedb-engine-linux-s390x-gnu')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Linux: ${arch}`)
-    }
-    break
-  default:
-    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
-}
+  };
 
-if (!nativeBinding) {
-  if (loadError) {
-    throw loadError
-  }
-  throw new Error(`Failed to load native binding`)
-}
+  const arm = () => {
+    if (armed || process.env.NEDB_NO_EXIT_FLUSH) return;
+    armed = true;
+    // 'exit' fires on normal termination; handlers must be synchronous, and
+    // db.flush() is a synchronous native call — so this is safe and sufficient
+    // for clean exits and uncaught-exception exits.
+    process.on('exit', flushAll);
+    // Registering a SIGINT/SIGTERM listener SUPPRESSES Node's default
+    // termination, so once we listen we own the exit: flush, then terminate with
+    // the conventional 128+signum status.
+    const onSignal = (signum) => () => {
+      flushAll();
+      process.exit(128 + signum);
+    };
+    process.on('SIGINT', onSignal(2));
+    process.on('SIGTERM', onSignal(15));
+  };
 
-const { NedbCore } = nativeBinding
+  NedbCore = class NedbCore extends Native {
+    static open(path) {
+      const db = Native.open(path);
+      live.add(db);
+      arm();
+      return db;
+    }
+  };
+  // Mark so a re-require (or a wrapped re-export) never double-wraps.
+  Object.defineProperty(NedbCore, '__exitFlushWrapped', { value: true, enumerable: false });
+}
 
-module.exports.NedbCore = NedbCore
+module.exports = { ...native, NedbCore };
+// Explicit named re-export so ESM `import { NedbCore } from 'nedb-engine'` (used
+// by the test suite) resolves the class through cjs-module-lexer.
+module.exports.NedbCore = NedbCore;

package/native.d.ts

@@ -0,0 +1,64 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare class NedbCore {
+  /** Create an in-memory v2 DAG database — zero disk I/O. */
+  constructor()
+  /**
+   * Open a durable v2 DAG database at `path`.
+   * Automatically migrates v1 AOF → v2 DAG on first open.
+   *
+   * Durable-mode auto-flush-on-exit is wired in the JS wrapper via
+   * `process.on('SIGTERM'|'SIGINT'|'beforeExit', () => db.flush())` — the
+   * libuv-cooperative hook — NOT a C-level signal handler here, which would
+   * clobber libuv's own signal machinery.
+   */
+  static open(path: string): NedbCore
+  createIndex(coll: string, field: string, kind: string): void
+  /** Put a document. Returns the stored doc as a JSON string. */
+  put(coll: string, id: string, docJson: string): string
+  /** Full put with optional client / nonce — API compat, v2 ignores these. */
+  putEx(coll: string, id: string, docJson: string, client?: string | undefined | null, nonce?: bigint | undefined | null, idem?: string | undefined | null): string
+  delete(coll: string, id: string): void
+  deleteEx(coll: string, id: string, client?: string | undefined | null, nonce?: bigint | undefined | null, idem?: string | undefined | null): void
+  /** Link: stored as a doc in __links__ collection for NQL traversal. */
+  link(frm: string, rel: string, to: string): void
+  unlink(frm: string, rel: string, to: string): void
+  get(coll: string, id: string): string | null
+  getAsOf(coll: string, id: string, asOf: bigint): string | null
+  query(nqlStr: string): Array<string>
+  neighbors(frm: string, rel: string): Array<string>
+  neighborsAsOf(frm: string, rel: string, asOf: bigint): Array<string>
+  inbound(to: string, rel: string): Array<string>
+  inboundAsOf(to: string, rel: string, asOf: bigint): Array<string>
+  verify(): boolean
+  head(): string
+  seq(): bigint
+  /** Flush WAL and MANIFEST — v2 equivalent of v1 flush(). */
+  flush(): void
+  /**
+   * The tip — the most recent write (latest node) as a JSON string, or null if
+   * the database is empty. The cheap "give me the latest write" primitive.
+   */
+  tip(): string | null
+  /**
+   * Collection-local tip — the most recent write into `coll` as a JSON string,
+   * or null if the collection has no writes. Resume one chain without filtering.
+   */
+  tipCollection(coll: string): string | null
+  /**
+   * Changefeed page after `after_seq` (exclusive), up to `limit` nodes (0 = the
+   * engine default cap), as a JSON envelope string:
+   * `{nodes, from_seq, to_seq, head_seq, has_more}`. Page while `has_more`,
+   * advancing your cursor to `to_seq`, then attach to the live subscribe edge.
+   */
+  since(afterSeq: bigint, limit: number): string
+  /**
+   * Replication readiness as a JSON string: `{scan_complete, tip_seq,
+   * indexed_seq_min, indexed_seq_max, indexed_count}`. Wait for
+   * `scan_complete == true` before trusting historical `since()` catch-up.
+   */
+  scanStatus(): string
+}

package/native.js

@@ -0,0 +1,315 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'nedb.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.android-arm64.node')
+          } else {
+            nativeBinding = require('nedb-engine-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'nedb.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('nedb-engine-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'nedb.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('nedb-engine-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'nedb.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('nedb-engine-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'nedb.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('nedb-engine-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'nedb.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./nedb.darwin-universal.node')
+      } else {
+        nativeBinding = require('nedb-engine-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'nedb.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.darwin-x64.node')
+          } else {
+            nativeBinding = require('nedb-engine-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'nedb.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.darwin-arm64.node')
+          } else {
+            nativeBinding = require('nedb-engine-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'nedb.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./nedb.freebsd-x64.node')
+      } else {
+        nativeBinding = require('nedb-engine-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'nedb.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./nedb.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('nedb-engine-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'nedb.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./nedb.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('nedb-engine-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { NedbCore } = nativeBinding
+
+module.exports.NedbCore = NedbCore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nedb-engine",
-  "version": "2.8.4",
+  "version": "2.8.6",
   "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",
   "types": "index.d.ts",
@@ -19,6 +19,7 @@
     "*.node",
     "nedbd-v2*",
     "test/smoke.mjs",
+    "test/durability.test.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -59,7 +60,7 @@
   "scripts": {
     "build": "napi build --release --platform --cargo-cwd rust/crates/nedb-node --js native.js --dts native.d.ts",
     "build:debug": "napi build --platform --cargo-cwd rust/crates/nedb-node --js native.js --dts native.d.ts",
-    "test": "node test/smoke.mjs"
+    "test": "node test/smoke.mjs && node test/durability.test.mjs"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0"

package/test/durability.test.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// nedb-engine — embedded durability under SIGKILL (2.8.5)
+// ---------------------------------------------------------------------------
+// The contract: an acknowledged write is on disk within one manifest tick (default 1 s) or at
+// exit, whichever comes first. This test proves the tick half the only way that means anything:
+// a child process opens a durable db, puts a document, gets the hash back, waits past one tick,
+// and is killed with SIGKILL — no exit hook can run. The parent then opens the same directory
+// and must find the document.
+//
+// Negative control: the same sequence with NEDB_FLUSH_MS=0 (ticker disabled) must LOSE the
+// document — otherwise this test would pass for reasons unrelated to the ticker.
+// Wrapper case: ticker off + graceful SIGTERM must KEEP the document — the exit-flush wrapper's job.
+//
+// © INTERCHAINED LLC
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+let NedbCore, addonSpecifier;
+try { ({ NedbCore } = await import('nedb-engine')); addonSpecifier = 'nedb-engine'; }
+catch { addonSpecifier = new URL('../index.js', import.meta.url).href; ({ NedbCore } = await import(addonSpecifier)); }
+
+const CHILD = `
+  const { NedbCore } = await import(process.argv[1]); // node -e: argv[1] is the first user arg
+  const db = NedbCore.open(process.argv[2]);
+  const out = db.put('durability', 'doc-1', JSON.stringify({ written_at: Date.now(), note: 'must survive SIGKILL' }));
+  process.stdout.write('PUT ' + JSON.parse(out)._hash + '\\n');
+  setInterval(() => {}, 1 << 30); // stay alive until killed
+`;
+
+function runChild(dir, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['--input-type=module', '-e', CHILD, addonSpecifier, dir], { env: { ...process.env, ...env }, stdio: ['ignore', 'pipe', 'inherit'] });
+    let buf = '';
+    child.stdout.on('data', (d) => { buf += d; const m = buf.match(/PUT ([0-9a-f]+)/); if (m) resolve({ child, hash: m[1] }); });
+    child.on('exit', (code, sig) => reject(new Error(`child exited early (${code ?? sig}) — ${buf}`)));
+    setTimeout(() => reject(new Error('child never acknowledged the put')), 15000).unref();
+  });
+}
+
+const tmp = (l) => fs.mkdtempSync(path.join(os.tmpdir(), `nedb-dur-${l}-`));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const readBack = (dir) => { const db = NedbCore.open(dir); const raw = db.get('durability', 'doc-1'); return raw ? JSON.parse(raw) : null; };
+let failed = 0;
+const check = (ok, msg) => { console.log(`  ${ok ? '✓' : '✗'} ${msg}`); if (!ok) failed++; };
+
+console.log('\n  N E D B  ·  embedded durability under SIGKILL');
+
+// ── positive: default ticker (1000 ms) ─────────────────────────────────────
+{
+  const dir = tmp('tick');
+  const { child, hash } = await runChild(dir, { NEDB_FLUSH_MS: '1000' });
+  console.log(`  → child acknowledged put ${hash.slice(0, 12)}…; waiting 2.5 s (two ticks) then SIGKILL`);
+  await sleep(2500);
+  child.kill('SIGKILL'); await new Promise((r) => child.on('exit', r));
+  const doc = readBack(dir);
+  check(doc !== null && doc._hash === hash, `after SIGKILL + reopen the document is present with the acknowledged hash (${doc ? doc._hash.slice(0, 12) + '…' : 'GONE'})`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ── negative control: ticker disabled → the write must be lost ─────────────
+{
+  const dir = tmp('notick');
+  const { child, hash } = await runChild(dir, { NEDB_FLUSH_MS: '0' });
+  console.log(`  → control: NEDB_FLUSH_MS=0, put ${hash.slice(0, 12)}…, 2.5 s, SIGKILL`);
+  await sleep(2500);
+  child.kill('SIGKILL'); await new Promise((r) => child.on('exit', r));
+  const doc = readBack(dir);
+  check(doc === null, `with the ticker disabled the same sequence loses the write (${doc ? 'unexpectedly present' : 'gone, as the control requires'})`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ── wrapper: graceful SIGTERM with the ticker OFF → the exit flush must save it ──
+{
+  check(NedbCore.__exitFlushWrapped === true, 'index.js is the durable-mode wrapper (not the generated loader)');
+  const dir = tmp('term');
+  const { child, hash } = await runChild(dir, { NEDB_FLUSH_MS: '0' });
+  console.log(`  → wrapper: NEDB_FLUSH_MS=0, put ${hash.slice(0, 12)}…, SIGTERM (graceful)`);
+  child.kill('SIGTERM'); await new Promise((r) => child.on('exit', r));
+  const doc = readBack(dir);
+  check(doc !== null && doc._hash === hash, `after SIGTERM the exit-flush wrapper made the write durable (${doc ? 'present' : 'GONE'})`);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+if (failed) { console.log(`\n  ${failed} check(s) failed`); process.exit(1); }
+console.log('\n  durability contract holds: on disk within one tick, or at exit.\n');