@blamejs/core 0.8.43 → 0.8.49

package/lib/legal-hold.js

@@ -0,0 +1,374 @@
+"use strict";
+/**
+ * legal-hold — subject-level litigation/regulatory hold registry.
+ *
+ * A legal hold (a.k.a. litigation hold, preservation order, regulatory
+ * hold) freezes a named subject's data so retention sweeps, RTBF
+ * erasures, and routine purges cannot remove records pending the
+ * resolution of an investigation, lawsuit, audit, or regulatory
+ * inquiry. Per FRCP Rule 26 / Rule 37(e) (US Federal Rules of Civil
+ * Procedure), GDPR Art. 17(3)(e) (right-to-erasure exception for
+ * legal claims), SEC Rule 17a-4 (broker-dealer record preservation),
+ * and HIPAA §164.530(j)(2) (six-year retention of HIPAA records),
+ * once an organization knows or should reasonably know that records
+ * are relevant to anticipated litigation or regulatory action, it
+ * must suspend routine destruction.
+ *
+ * Per-rule `legalHoldField` in b.retention already lets an operator
+ * gate retention skips on a column value. This module is the central
+ * registry that:
+ *
+ *   1. Records each placement / release as a hash-chained audit row
+ *      (`legalhold.placed` / `legalhold.released` events).
+ *   2. Persists subject-id-keyed entries in `_blamejs_legal_hold` so
+ *      the framework can answer `isHeld(subjectId)` in O(1) without
+ *      the operator having to plumb a flag column into every table.
+ *   3. Wires into b.subject.erase + b.retention so a placed hold
+ *      refuses erasure even when the operator-supplied
+ *      acknowledgements would otherwise pass.
+ *
+ *   var holds = b.legalHold.create({
+ *     db:       b.db,
+ *     audit:    b.audit,
+ *     signWith: b.auditSign,             // optional — sign every event
+ *   });
+ *
+ *   await holds.place("user-42", {
+ *     reason:      "SEC subpoena 2026-03-12 case 24-cv-01933",
+ *     custodian:   "legal@example.com",
+ *     citation:    "FRCP-26",
+ *     retainUntil: Date.now() + C.TIME.days(365),  // optional sunset
+ *   });
+ *
+ *   await holds.release("user-42", {
+ *     reason:   "case dismissed; preservation duty ended",
+ *     approver: "legal@example.com",
+ *   });
+ *
+ *   holds.isHeld("user-42");              // → boolean (sync read)
+ *   holds.list();                         // → [{ subjectId, ... }]
+ *   holds.history("user-42");             // → [{ at, action, ... }]
+ *
+ * Storage shape: `_blamejs_legal_hold` is the active registry (one
+ * row per held subject); placement + release history is preserved in
+ * the framework audit_log via `legalhold.placed` / `.released`
+ * events. Operators wanting a flat history table re-derive it from
+ * the audit chain.
+ *
+ * Validation tier: throw at config-time on bad opts; throw on
+ * missing/garbage subjectId at the API; emit + return shaped error
+ * on policy denials (already-held / not-held / invalid-citation).
+ */
+var crypto = require("./crypto");
+var lazyRequire = require("./lazy-require");
+var safeJson = require("./safe-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var LegalHoldError = defineClass("LegalHoldError", { alwaysPermanent: true });
+var _err = LegalHoldError.factory;
+
+// Per FRCP Rule 26(f) / 37(e), GDPR Art. 17(3)(e), SEC Rule 17a-4(b),
+// HIPAA §164.530(j)(2), 21 CFR Part 11 §11.10(c). Operator-supplied
+// citation should match one of these or be a free-form reference; the
+// framework only sanity-checks shape, not value.
+var KNOWN_CITATIONS = Object.freeze([
+  "FRCP-26", "FRCP-37(e)",
+  "GDPR-Art-17-3-e",
+  "SEC-Rule-17a-4", "SEC-Rule-17a-4(f)",
+  "FINRA-4511",
+  "HIPAA-164.530(j)(2)",
+  "21-CFR-Part-11", "21-CFR-Part-11-11.10(c)",
+  "operator-defined",
+]);
+
+function _subjectIdString(subjectId) {
+  if (subjectId === null || subjectId === undefined) {
+    throw _err("BAD_ARG", "subjectId must be a non-empty string");
+  }
+  var s = String(subjectId);
+  if (s.length === 0) {
+    throw _err("BAD_ARG", "subjectId must be a non-empty string");
+  }
+  return s;
+}
+
+function _hashSubject(subjectId) {
+  return crypto.sha3Hash("bj-legal-hold:" + subjectId);
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["db", "audit", "signWith"], "legalHold");
+  if (!opts.db || typeof opts.db.prepare !== "function") {
+    throw _err("BAD_OPT", "create: opts.db is required (a b.db handle)");
+  }
+  var db = opts.db;
+  var auditOn = opts.audit !== false && opts.audit != null;
+  var auditInstance = (opts.audit && opts.audit !== true) ? opts.audit : null;
+  // signWith is reserved for future per-event detached signatures;
+  // currently the audit chain itself is hash-linked + the sidecar
+  // signing on audit_checkpoints covers tamper detection. Validate
+  // shape so a caller passing it gets a typo-surfacing throw, but
+  // don't require it.
+  validateOpts.optionalObjectWithMethod(opts.signWith, "sign",
+    "create: opts.signWith", LegalHoldError, "BAD_OPT", "b.auditSign-shaped object");
+
+  function _emit(action, info, outcome) {
+    if (!auditOn) return;
+    var sink = auditInstance || audit();
+    try {
+      sink.safeEmit({
+        action:   action,
+        outcome:  outcome,
+        resource: { kind: "legal-hold", id: info && info.subjectId },
+        reason:   (info && info.reason) || null,
+        metadata: info || {},
+      });
+    } catch (_e) { /* best-effort */ }
+  }
+
+  function _ensureSchema() {
+    // Idempotent migration. The framework SQLite path installs the
+    // table via FRAMEWORK_SCHEMA at boot; this guard is for the
+    // external-db / cluster path where schema migrations are operator-
+    // driven. Either way the IF NOT EXISTS shape is safe to re-run.
+    var fn = db.runSql || db.execRaw;
+    if (typeof fn === "function") {
+      fn(
+        'CREATE TABLE IF NOT EXISTS "_blamejs_legal_hold" (' +
+        '"subjectIdHash" TEXT PRIMARY KEY,' +
+        '"placedAt" INTEGER NOT NULL,' +
+        '"placedBy" TEXT,' +
+        '"reason" TEXT NOT NULL,' +
+        '"custodian" TEXT,' +
+        '"citation" TEXT,' +
+        '"retainUntil" INTEGER' +
+        ')'
+      );
+    }
+  }
+
+  function place(subjectId, args) {
+    var sid = _subjectIdString(subjectId);
+    args = args || {};
+    if (typeof args.reason !== "string" || args.reason.length === 0) {
+      throw _err("BAD_ARG", "place: args.reason is required (non-empty string)");
+    }
+    if (args.citation !== undefined && args.citation !== null) {
+      if (typeof args.citation !== "string" || args.citation.length === 0) {
+        throw _err("BAD_ARG", "place: args.citation must be a non-empty string");
+      }
+    }
+    if (args.retainUntil !== undefined && args.retainUntil !== null) {
+      if (typeof args.retainUntil !== "number" ||
+          !isFinite(args.retainUntil) ||
+          args.retainUntil <= 0) {
+        throw _err("BAD_ARG", "place: args.retainUntil must be a positive finite ms-epoch");
+      }
+    }
+    _ensureSchema();
+    var hash = _hashSubject(sid);
+    var existing = db.prepare(
+      'SELECT placedAt FROM "_blamejs_legal_hold" WHERE subjectIdHash = ?'
+    ).get(hash);
+    if (existing) {
+      _emit("legalhold.place_rejected",
+        { subjectId: sid, reason: "already-held",
+          existingSince: existing.placedAt },
+        "denied");
+      return { error: "already-held", placedAt: existing.placedAt };
+    }
+    var nowMs = Date.now();
+    db.prepare(
+      'INSERT INTO "_blamejs_legal_hold" ' +
+      '(subjectIdHash, placedAt, placedBy, reason, custodian, citation, retainUntil) ' +
+      'VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(
+      hash, nowMs,
+      args.placedBy || null,
+      args.reason,
+      args.custodian || null,
+      args.citation || null,
+      args.retainUntil || null
+    );
+    _emit("legalhold.placed",
+      { subjectId: sid, reason: args.reason,
+        custodian: args.custodian || null,
+        citation:  args.citation  || null,
+        retainUntil: args.retainUntil || null,
+        placedBy: args.placedBy || null,
+        knownCitation: args.citation && KNOWN_CITATIONS.indexOf(args.citation) !== -1 },
+      "success");
+    return { placed: true, placedAt: nowMs };
+  }
+
+  function release(subjectId, args) {
+    var sid = _subjectIdString(subjectId);
+    args = args || {};
+    if (typeof args.reason !== "string" || args.reason.length === 0) {
+      throw _err("BAD_ARG", "release: args.reason is required (non-empty string)");
+    }
+    if (typeof args.approver !== "string" || args.approver.length === 0) {
+      throw _err("BAD_ARG", "release: args.approver is required (non-empty string)");
+    }
+    _ensureSchema();
+    var hash = _hashSubject(sid);
+    var existing = db.prepare(
+      'SELECT placedAt, reason FROM "_blamejs_legal_hold" WHERE subjectIdHash = ?'
+    ).get(hash);
+    if (!existing) {
+      _emit("legalhold.release_rejected",
+        { subjectId: sid, reason: "not-held" },
+        "denied");
+      return { error: "not-held" };
+    }
+    db.prepare(
+      'DELETE FROM "_blamejs_legal_hold" WHERE subjectIdHash = ?'
+    ).run(hash);
+    _emit("legalhold.released",
+      { subjectId: sid, reason: args.reason,
+        approver: args.approver,
+        originalReason: existing.reason,
+        heldSince: existing.placedAt },
+      "success");
+    return { released: true, heldSince: existing.placedAt };
+  }
+
+  function isHeld(subjectId) {
+    var sid = _subjectIdString(subjectId);
+    _ensureSchema();
+    var hash = _hashSubject(sid);
+    var row = db.prepare(
+      'SELECT retainUntil FROM "_blamejs_legal_hold" WHERE subjectIdHash = ?'
+    ).get(hash);
+    if (!row) return false;
+    // retainUntil expiry — when the operator pinned a sunset and it
+    // has passed, the hold has lapsed and isHeld returns false. The
+    // row stays so audit/history reads can see when the sunset hit;
+    // operators wanting the row gone call release() explicitly.
+    if (row.retainUntil && row.retainUntil < Date.now()) return false;
+    return true;
+  }
+
+  function get(subjectId) {
+    var sid = _subjectIdString(subjectId);
+    _ensureSchema();
+    var hash = _hashSubject(sid);
+    var row = db.prepare(
+      'SELECT subjectIdHash, placedAt, placedBy, reason, custodian, citation, retainUntil ' +
+      'FROM "_blamejs_legal_hold" WHERE subjectIdHash = ?'
+    ).get(hash);
+    if (!row) return null;
+    return {
+      subjectId:   sid,
+      placedAt:    row.placedAt,
+      placedBy:    row.placedBy,
+      reason:      row.reason,
+      custodian:   row.custodian,
+      citation:    row.citation,
+      retainUntil: row.retainUntil,
+      lapsed:      !!(row.retainUntil && row.retainUntil < Date.now()),
+    };
+  }
+
+  function list() {
+    _ensureSchema();
+    var rows = db.prepare(
+      'SELECT subjectIdHash, placedAt, placedBy, reason, custodian, citation, retainUntil ' +
+      'FROM "_blamejs_legal_hold" ORDER BY placedAt'
+    ).all();
+    var nowMs = Date.now();
+    return rows.map(function (r) {
+      return {
+        subjectIdHash: r.subjectIdHash,
+        placedAt:      r.placedAt,
+        placedBy:      r.placedBy,
+        reason:        r.reason,
+        custodian:     r.custodian,
+        citation:      r.citation,
+        retainUntil:   r.retainUntil,
+        lapsed:        !!(r.retainUntil && r.retainUntil < nowMs),
+      };
+    });
+  }
+
+  function history(subjectId) {
+    // Re-derive the placement/release history from the audit chain.
+    // We don't store a separate history table — the audit_log is
+    // already tamper-evident and chain-verified.
+    var sid = _subjectIdString(subjectId);
+    var rows = [];
+    try {
+      var auditQuery = db.prepare(
+        'SELECT recordedAt, action, metadata, outcome ' +
+        'FROM audit_log ' +
+        'WHERE action LIKE ? AND resourceKind = ? ' +
+        'ORDER BY recordedAt'
+      );
+      // resourceId is sealed, so match on resourceKind + post-filter
+      // by parsed metadata.
+      var raw = auditQuery.all("legalhold.%", "legal-hold");
+      for (var i = 0; i < raw.length; i++) {
+        var meta = null;
+        try { meta = safeJson.parse(raw[i].metadata || "{}"); } catch (_e) { meta = null; }
+        if (meta && meta.subjectId === sid) {
+          rows.push({
+            at:       raw[i].recordedAt,
+            action:   raw[i].action,
+            outcome:  raw[i].outcome,
+            metadata: meta,
+          });
+        }
+      }
+    } catch (_e) { /* drop-silent: audit_log may be sealed-metadata in cluster mode */ }
+    return rows;
+  }
+
+  var instance = {
+    place:           place,
+    release:         release,
+    isHeld:          isHeld,
+    get:             get,
+    list:            list,
+    history:         history,
+    KNOWN_CITATIONS: KNOWN_CITATIONS,
+  };
+  // Auto-register the most recent instance as the framework singleton
+  // so b.subject.erase / b.retention can consult b.legalHold.isHeld
+  // without each operator threading the instance through. Operators
+  // building multiple registries (multi-tenant, test isolation) call
+  // create() once per tenant; the last create() wins for the global
+  // gate, and per-tenant code holds its own instance reference.
+  _registerSingleton(instance);
+  return instance;
+}
+
+// Singleton convenience — many primitives (b.subject.erase,
+// b.retention) need to consult the registry without each operator
+// passing a holds instance through. The first create() under a
+// db handle wins; subsequent calls return the active singleton.
+var _singleton = null;
+
+function _registerSingleton(instance) {
+  _singleton = instance;
+}
+
+function _getSingleton() {
+  return _singleton;
+}
+
+function _resetForTest() {
+  _singleton = null;
+}
+
+module.exports = {
+  create:            create,
+  KNOWN_CITATIONS:   KNOWN_CITATIONS,
+  LegalHoldError:    LegalHoldError,
+  _registerSingleton: _registerSingleton,
+  _getSingleton:     _getSingleton,
+  _resetForTest:     _resetForTest,
+};

package/lib/local-db-thin.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * b.localDb.thin — lightweight node:sqlite wrapper for desktop-daemon-
+ * shaped local state.
+ *
+ * The framework's full b.db is the right tool when the workload needs
+ * vault-sealed columns, the audit chain, sealed-by-default schema
+ * governance, framework-schema bootstrap, derived-hash lookup, sealed-
+ * fields rotation, and the cross-cutting "encrypted at rest" envelope.
+ * That stack costs vault keys, a tmpfs sealed-file dance, schema
+ * declarations, and a startup audit chain — overkill for a daemon
+ * keeping a hundred-row local registry on the operator's laptop.
+ *
+ * b.localDb.thin keeps the parts a daemon does need:
+ *
+ *   - A node:sqlite handle opened in WAL mode with sane busy-timeout.
+ *   - Boot-time `PRAGMA integrity_check` (cheap + closes the partial-
+ *     write data-loss class).
+ *   - Optional corrupt-rename-and-recreate recovery: if the file fails
+ *     integrity_check or open() raises SQLITE_CORRUPT, rename it to
+ *     `<file>.corrupt-<unix-ms>` and start fresh against the operator-
+ *     supplied schema.
+ *   - LRU-bounded prepared-statement cache (matches b.db's shape so
+ *     long-running daemons with diverse query shapes don't leak
+ *     statement handles).
+ *   - Audit hooks on open / recover / close so operators can wire
+ *     the same incident review pipeline they already have for b.db.
+ *
+ * What it deliberately does NOT do:
+ *
+ *   - No vault, no field encryption, no per-row keys, no SHA3 derived
+ *     hashes — operators with PHI / PCI go straight to b.db.
+ *   - No audit chain — there is no server-side compliance posture for
+ *     a desktop daemon's sqlite cache.
+ *   - No schema governance — `schemaSql` is the operator's `CREATE
+ *     TABLE IF NOT EXISTS ...` script, run verbatim at open.
+ *   - No background flush / no encrypted-at-rest tmpfs — the file is
+ *     opened in place. Operators wanting at-rest encryption use full
+ *     b.db.
+ *
+ * Public surface:
+ *   localDbThin.thin({
+ *     file:       string,                // required absolute path
+ *     schemaSql:  string,                // required CREATE TABLE / INDEX script
+ *     recovery:   "refuse" | "rename-and-recreate",  // default: "refuse"
+ *     pragmas:    object,                // optional extra PRAGMA overrides
+ *     audit:      boolean,               // default: true
+ *   }) -> { db, prepare, run, query, close, file }
+ *
+ * Audit emits:
+ *   localdb.thin.opened     { file }
+ *   localdb.thin.recovered  { file, renamedTo }
+ *   localdb.thin.closed     { file }
+ */
+
+var fs   = require("fs");
+var path = require("path");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var safeSql = require("./safe-sql");
+var { LocalDbThinError } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// LRU prepared-statement cache cap — same magnitude as lib/db.js's full
+// variant. Daemons issuing more than this many distinct SQL strings
+// likely have a string-concat bug rather than a legitimate need.
+var PREPARE_CACHE_MAX = 256;                                                       // allow:raw-byte-literal — distinct-statement cache cap
+
+var ALLOWED_RECOVERY = ["refuse", "rename-and-recreate"];
+
+// Bare NUL byte, expressed via String.fromCharCode so the source file
+// itself stays pure ASCII (the codebase-patterns gate also guarantees
+// this won't be confused with a literal embedded NUL during diffs).
+var NUL_BYTE = String.fromCharCode(0);
+
+function _validateOpts(opts) {
+  validateOpts.requireObject(opts, "localDb.thin", LocalDbThinError, "localdb-thin/bad-opts");
+  validateOpts.requireNonEmptyString(opts.file, "file", LocalDbThinError, "localdb-thin/bad-file");
+  // `file` is operator-supplied (daemon's chosen storage path), not
+  // request-driven input. Reject NUL bytes defensively — Node's path
+  // routines silently truncate at the first NUL, which would let a
+  // typo open a different file than the operator intended.
+  if (opts.file.indexOf(NUL_BYTE) !== -1) {
+    throw new LocalDbThinError("localdb-thin/bad-file",
+      "localDb.thin: file path must not contain NUL bytes");
+  }
+  validateOpts.requireNonEmptyString(opts.schemaSql, "schemaSql",
+    LocalDbThinError, "localdb-thin/bad-schema-sql");
+  var recovery = opts.recovery || "refuse";
+  if (ALLOWED_RECOVERY.indexOf(recovery) === -1) {
+    throw new LocalDbThinError("localdb-thin/bad-recovery",
+      "localDb.thin: recovery must be one of " + ALLOWED_RECOVERY.join(", ") +
+      " (got '" + recovery + "')");
+  }
+  if (opts.pragmas !== undefined &&
+      (typeof opts.pragmas !== "object" || Array.isArray(opts.pragmas))) {
+    throw new LocalDbThinError("localdb-thin/bad-pragmas",
+      "localDb.thin: pragmas must be an object mapping pragma name -> value");
+  }
+}
+
+function _runPragmas(database, extra) {
+  database.exec("PRAGMA journal_mode=WAL");
+  database.exec("PRAGMA synchronous=NORMAL");
+  database.exec("PRAGMA busy_timeout=5000");
+  database.exec("PRAGMA foreign_keys=ON");
+  database.exec("PRAGMA secure_delete=ON");
+  try { database.exec("PRAGMA trusted_schema=OFF"); } catch (_e) { /* sqlite < 3.31 */ }
+  try { database.exec("PRAGMA cell_size_check=ON"); } catch (_e) { /* sqlite < 3.26 */ }
+  if (extra && typeof extra === "object") {
+    var keys = Object.keys(extra);
+    for (var i = 0; i < keys.length; i += 1) {
+      var name = keys[i];
+      // PRAGMA names are operator-supplied keys; reject anything that
+      // isn't a bare SQL identifier so this never becomes a SQL-injection
+      // vector even at config time. Composes the same identifier shape
+      // safeSql.validateIdentifier enforces elsewhere.
+      if (!safeSql.DEFAULT_IDENTIFIER_RE.test(name) ||
+          name.length > safeSql.MAX_IDENTIFIER_LENGTH) {
+        throw new LocalDbThinError("localdb-thin/bad-pragma-name",
+          "localDb.thin: pragma name '" + name + "' must be a bare identifier");
+      }
+      var value = extra[name];
+      if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+        throw new LocalDbThinError("localdb-thin/bad-pragma-value",
+          "localDb.thin: pragma '" + name + "' value must be string|number|boolean");
+      }
+      database.exec("PRAGMA " + name + "=" + String(value));
+    }
+  }
+}
+
+function _integrityOk(database) {
+  try {
+    var rows = database.prepare("PRAGMA integrity_check").all();
+    return rows.length === 1 && rows[0] && rows[0].integrity_check === "ok";
+  } catch (_e) {
+    return false;
+  }
+}
+
+function thin(opts) {
+  _validateOpts(opts);
+
+  var auditOn  = opts.audit !== false;
+  // opts.file is operator-config (daemon-author chosen storage path),
+  // not request-driven input. Validation above already rejected non-
+  // strings and NUL bytes. The operator picks the file location; the
+  // wrapper opens it as-is.
+  var file = opts.file;
+  var recovery = opts.recovery || "refuse";
+
+  function _safeEmitAudit(action, metadata) {
+    if (!auditOn) return;
+    try { audit().safeEmit({ action: action, outcome: "success", metadata: metadata || {} }); }
+    catch (_e) { /* drop-silent — audit best-effort */ }
+  }
+
+  // node:sqlite is required lazily so a process never importing localDb
+  // doesn't pay the cost of resolving it at module load.
+  var nodeSqlite = require("node:sqlite");
+  var DatabaseSync = nodeSqlite.DatabaseSync;
+  if (typeof DatabaseSync !== "function") {
+    throw new LocalDbThinError("localdb-thin/sqlite-missing",
+      "localDb.thin: node:sqlite is unavailable on this Node build (requires Node 24.14+)");
+  }
+
+  // Ensure parent directory exists — operators commonly point this at
+  // an OS app-data path that may not exist on first daemon launch.
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); } catch (_e) { /* best-effort */ }
+
+  var database = null;
+  var renamedTo = null;
+
+  function _attemptOpen() {
+    var db = new DatabaseSync(file);
+    _runPragmas(db, opts.pragmas);
+    if (!_integrityOk(db)) {
+      try { db.close(); } catch (_e) { /* best-effort */ }
+      throw new LocalDbThinError("localdb-thin/corrupt",
+        "localDb.thin: PRAGMA integrity_check failed for '" + file + "'");
+    }
+    db.exec(opts.schemaSql);
+    return db;
+  }
+
+  try {
+    database = _attemptOpen();
+  } catch (e) {
+    var corrupt = (e && e.code === "localdb-thin/corrupt") ||
+                  (e && typeof e.message === "string" &&
+                   /SQLITE_CORRUPT|malformed|not a database/i.test(e.message));
+    if (corrupt && recovery === "rename-and-recreate") {
+      var stamp = String(Date.now());
+      renamedTo = file + ".corrupt-" + stamp;
+      // Bounded rename retry — Windows holds a file lock briefly after
+      // DatabaseSync.close() returns. Linux/macOS land on the first
+      // attempt. Capped at ~250ms total so a genuinely-stuck handle
+      // still surfaces as recovery-failed rather than hanging.
+      var renamed = false;
+      var lastRenameErr = null;
+      for (var attempt = 0; attempt < 5 && !renamed; attempt += 1) {
+        try {
+          if (fs.existsSync(file)) fs.renameSync(file, renamedTo);
+          renamed = true;
+        } catch (re) {
+          lastRenameErr = re;
+          if (re && (re.code === "EBUSY" || re.code === "EPERM")) {
+            // Synchronous spin — don't reach for setTimeout in a
+            // boot-time path. 50ms × 5 = 250ms upper bound.
+            var until = Date.now() + 50;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+          }
+          throw new LocalDbThinError("localdb-thin/recovery-failed",
+            "localDb.thin: rename of corrupt file failed: " + ((re && re.message) || String(re)));
+        }
+      }
+      if (!renamed) {
+        throw new LocalDbThinError("localdb-thin/recovery-failed",
+          "localDb.thin: rename of corrupt file failed: " +
+          ((lastRenameErr && lastRenameErr.message) || "unknown"));
+      }
+      // Also move WAL/SHM siblings if present so the fresh DB doesn't
+      // re-attach a half-open journal.
+      ["-wal", "-shm"].forEach(function (suffix) {
+        var sibling = file + suffix;
+        if (fs.existsSync(sibling)) {
+          try { fs.renameSync(sibling, sibling + ".corrupt-" + stamp); }
+          catch (_se) { /* best-effort */ }
+        }
+      });
+      database = _attemptOpen();
+      _safeEmitAudit("localdb.thin.recovered", { file: file, renamedTo: renamedTo });
+    } else if (corrupt) {
+      throw new LocalDbThinError("localdb-thin/corrupt",
+        "localDb.thin: file '" + file + "' is corrupt; pass recovery: 'rename-and-recreate' to auto-recover");
+    } else if (e && e.isLocalDbThinError) {
+      // Bad-pragma / bad-shape errors bubble up from _runPragmas with
+      // their own typed code already attached — re-throw verbatim
+      // rather than re-wrapping behind open-failed.
+      throw e;
+    } else {
+      throw new LocalDbThinError("localdb-thin/open-failed",
+        "localDb.thin: open of '" + file + "' failed: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  _safeEmitAudit("localdb.thin.opened", { file: file });
+
+  // ---- Prepared-statement cache ----
+  var prepareCache = new Map();
+  var closed = false;
+
+  function _ensureOpen() {
+    if (closed) {
+      throw new LocalDbThinError("localdb-thin/closed",
+        "localDb.thin: handle is closed");
+    }
+  }
+
+  function prepare(sql) {
+    _ensureOpen();
+    validateOpts.requireNonEmptyString(sql, "sql",
+      LocalDbThinError, "localdb-thin/bad-sql");
+    if (prepareCache.has(sql)) {
+      // Touch for LRU
+      var hit = prepareCache.get(sql);
+      prepareCache.delete(sql);
+      prepareCache.set(sql, hit);
+      return hit;
+    }
+    var stmt = database.prepare(sql);
+    prepareCache.set(sql, stmt);
+    if (prepareCache.size > PREPARE_CACHE_MAX) {
+      var oldest = prepareCache.keys().next().value;
+      prepareCache.delete(oldest);
+    }
+    return stmt;
+  }
+
+  function run(sql /* , ...params */) {
+    _ensureOpen();
+    var params = Array.prototype.slice.call(arguments, 1);
+    var stmt = prepare(sql);
+    return stmt.run.apply(stmt, params);
+  }
+
+  function query(sql /* , ...params */) {
+    _ensureOpen();
+    var params = Array.prototype.slice.call(arguments, 1);
+    var stmt = prepare(sql);
+    return stmt.all.apply(stmt, params);
+  }
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    prepareCache.clear();
+    try { database.close(); } catch (_e) { /* best-effort */ }
+    _safeEmitAudit("localdb.thin.closed", { file: file });
+  }
+
+  return {
+    db:           database,
+    prepare:      prepare,
+    run:          run,
+    query:        query,
+    close:        close,
+    file:         file,
+    recovered:    !!renamedTo,
+    recoveredTo:  renamedTo,
+  };
+}
+
+module.exports = {
+  thin:               thin,
+  LocalDbThinError:   LocalDbThinError,
+};