@blamejs/core 0.8.52 → 0.8.58

package/lib/db-query.js

@@ -484,6 +484,175 @@ class Query {
     return this._delete(false);
   }
 
+  // Atomic counter increment.
+  //
+  // `from(table).where(filter).increment("col", 1)` emits
+  // `UPDATE table SET col = col + ? WHERE ...` so concurrent writers
+  // can't collide on a fetch/mutate/store sequence (which would lose
+  // increments under racing transactions). Pass a negative delta to
+  // decrement.
+  //
+  // Returns the number of rows changed (matches updateMany shape).
+  increment(column, delta) {
+    if (typeof column !== "string" || column.length === 0) {
+      throw new Error("increment(column, delta): column must be a non-empty string");
+    }
+    _validateField(column);
+    if (delta === undefined) delta = 1;
+    if (typeof delta !== "number" || !Number.isFinite(delta) || !Number.isInteger(delta)) {
+      throw new Error("increment(column, delta): delta must be a finite integer (default 1)");
+    }
+    if (this._where.length === 0) {
+      throw new Error("refusing unconditional increment — call where(...) first");
+    }
+    var whereSql = this._where.join(" AND ");
+    var qt = this._quotedTable();
+    var qc = '"' + column + '"';
+    // Use COALESCE so a NULL counter starts at 0 instead of producing
+    // NULL + delta = NULL silently (which would silently drop the
+    // operation under SQLite's NULL-arithmetic rules).
+    var sql = "UPDATE " + qt + " SET " + qc + " = COALESCE(" + qc + ", 0) + ? WHERE " + whereSql;
+    var allParams = [delta].concat(this._whereParams);
+    var stmt = this._db.prepare(sql);
+    var info = stmt.run.apply(stmt, allParams);
+    return info.changes;
+  }
+
+  // `.where(closure)` for grouped expressions, including OR
+  // composition. Pass a function `(qb) => qb.eq(col, val).orEq(...)`;
+  // the inner closure builds an expression that becomes a single
+  // parenthesised AND-leaf in the outer where chain.
+  //
+  // The closure receives a `WhereBuilder` exposing `.eq` / `.neq` /
+  // `.gt` / `.gte` / `.lt` / `.lte` / `.in` / `.like` plus `.orEq`,
+  // `.orNeq`, `.orGt`, `.orGte`, `.orLt`, `.orLte`, `.orIn`,
+  // `.orLike`, and `.raw(sql, params)`. Each non-`or` call ANDs the
+  // expression; each `or*` call ORs it.
+  whereGroup(closure) {
+    if (typeof closure !== "function") {
+      throw new Error("whereGroup(closure): expected function (qb) => ...");
+    }
+    var sub = new WhereBuilder();
+    closure(sub);
+    var built = sub.build();
+    if (!built.sql) return this;
+    this._where.push("(" + built.sql + ")");
+    for (var i = 0; i < built.params.length; i++) this._whereParams.push(built.params[i]);
+    return this;
+  }
+
+  // Top-level OR — extends the existing where-chain so
+  // `.where(a).orWhere(b)` produces `WHERE (a) OR (b)` rather than
+  // `WHERE (a) AND (b)`. Accepts the same arg shapes as `.where`:
+  // object-literal map, `(field, value)`, `(field, op, value)`, or a
+  // `(qb) => ...` closure.
+  orWhere(fieldOrObjOrFn, op, value) {
+    if (this._where.length === 0) {
+      throw new Error("orWhere(...): no prior where(...) — start the chain with where(...)");
+    }
+    if (typeof fieldOrObjOrFn === "function") {
+      var sub = new WhereBuilder();
+      fieldOrObjOrFn(sub);
+      var built = sub.build();
+      if (!built.sql) return this;
+      var prev = this._where.pop();
+      this._where.push("(" + prev + " OR (" + built.sql + "))");
+      for (var i = 0; i < built.params.length; i++) this._whereParams.push(built.params[i]);
+      return this;
+    }
+    // For non-closure shapes, build a transient single-leaf Query and
+    // splice it. We compile to a `WhereBuilder` for symmetry.
+    var sub2 = new WhereBuilder();
+    if (fieldOrObjOrFn !== null && typeof fieldOrObjOrFn === "object" && !Array.isArray(fieldOrObjOrFn)) {
+      Object.keys(fieldOrObjOrFn).forEach(function (k) { sub2.eq(k, fieldOrObjOrFn[k]); });
+    } else if (op === undefined) {
+      sub2.eq(fieldOrObjOrFn, /* value */ arguments[1]);
+    } else {
+      sub2._push("AND", fieldOrObjOrFn, op, value);
+    }
+    var built2 = sub2.build();
+    if (!built2.sql) return this;
+    var prev2 = this._where.pop();
+    this._where.push("(" + prev2 + " OR (" + built2.sql + "))");
+    for (var j = 0; j < built2.params.length; j++) this._whereParams.push(built2.params[j]);
+    return this;
+  }
+
+  // `.search(fields, term)` — chainable LIKE-OR helper. Adds
+  // `(field1 LIKE ? OR field2 LIKE ? ...)` ANDed onto the existing
+  // where-chain. Empty term is a no-op (so `?search=` from a query-
+  // string flows through cleanly).
+  //
+  // `term` is wrapped with `%` on both sides for substring match by
+  // default; pass `{ match: "prefix" }` for `term%` only or
+  // `{ match: "exact" }` to LIKE the term verbatim (for operators
+  // who need to keep `%`/`_` in the user-supplied query).
+  search(fields, term, opts) {
+    if (!Array.isArray(fields) || fields.length === 0) {
+      throw new Error("search(fields, term): fields must be a non-empty array of column names");
+    }
+    fields.forEach(_validateField);
+    if (term === undefined || term === null) return this;
+    if (typeof term !== "string") {
+      throw new Error("search(fields, term): term must be a string");
+    }
+    if (term.length === 0) return this;
+    var match = (opts && opts.match) || "substring";
+    // Escape the operator's term so SQL LIKE wildcards in user input
+    // don't widen the match. Use `~` as the ESCAPE char (SQLite's
+    // ESCAPE clause requires a single character — picking `~` rather
+    // than `\` avoids JS-string-literal escaping headaches; `~` rarely
+    // appears in user-supplied search terms).
+    var escaped = String(term).replace(/[~%_]/g, function (c) { return "~" + c; });
+    var pattern;
+    if (match === "exact")        pattern = escaped;
+    else if (match === "prefix")  pattern = escaped + "%";
+    else if (match === "substring") pattern = "%" + escaped + "%";
+    else throw new Error("search: opts.match must be 'substring' | 'prefix' | 'exact'");
+    var clauses = fields.map(function (f) { return '"' + f + '" LIKE ? ESCAPE \'~\''; });
+    var sql = "(" + clauses.join(" OR ") + ")";
+    var params = fields.map(function () { return pattern; });
+    this._where.push(sql);
+    for (var i = 0; i < params.length; i++) this._whereParams.push(params[i]);
+    return this;
+  }
+
+  // `.paginate(opts)` — page envelope. Composes the existing
+  // `.orderBy().limit().offset().all()` + a separate `.count()` so
+  // operators get `{ items, total, limit, offset, page, totalPages }`
+  // in one call.
+  //
+  // Defaults: `limit = 25`, `offset = 0`. `orderBy` is required when
+  // the underlying query has no order — otherwise SQLite returns
+  // rows in storage order (not stable across page calls).
+  paginate(opts) {
+    opts = opts || {};
+    var limit = opts.limit === undefined ? 25 : opts.limit;
+    var offset = opts.offset === undefined ? 0 : opts.offset;
+    if (!Number.isInteger(limit) || limit <= 0 || limit > 1000) {                          // allow:raw-byte-literal — paginate page-size cap, not bytes
+      throw new Error("paginate: limit must be a positive integer ≤ 1000 (default 25)");
+    }
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw new Error("paginate: offset must be a non-negative integer");
+    }
+    if (opts.orderBy) {
+      var dir = opts.orderDir || (opts.orderDirection || "asc");
+      this.orderBy(opts.orderBy, dir);
+    }
+    var total = this.count();
+    var items = this.limit(limit).offset(offset).all();
+    var totalPages = Math.max(1, Math.ceil(total / limit));
+    var page = Math.floor(offset / limit) + 1;
+    return {
+      items:      items,
+      total:      total,
+      limit:      limit,
+      offset:     offset,
+      page:       page,
+      totalPages: totalPages,
+    };
+  }
+
   _delete(single) {
     if (this._where.length === 0) {
       throw new Error("refusing unconditional delete — call where(...) first");
@@ -503,6 +672,82 @@ class Query {
   }
 }
 
+// WhereBuilder — sub-expression builder used by Query.whereGroup() and
+// Query.orWhere((qb) => ...) to compose grouped AND/OR predicates that
+// the bare .where() chain (which only ANDs) can't express.
+//
+// Each `.eq` / `.neq` / `.gt` / `.gte` / `.lt` / `.lte` / `.in` /
+// `.like` call ANDs an expression; `.orEq` / `.orNeq` / `.orGt` /
+// `.orGte` / `.orLt` / `.orLte` / `.orIn` / `.orLike` ORs an
+// expression. `.raw(sql, params)` AND's an arbitrary fragment.
+//
+// `.build()` returns `{ sql, params }`. Empty builder → `{ sql: "",
+// params: [] }`.
+class WhereBuilder {
+  constructor() {
+    this._parts = [];   // [{ joiner: "AND"|"OR", sql: "...", params: [...] }]
+  }
+  _push(joiner, field, op, value) {
+    if (typeof field !== "string" || field.length === 0) {
+      throw new Error("WhereBuilder: field must be a non-empty string");
+    }
+    _validateField(field);
+    var qf = '"' + field + '"';
+    if (op === "IN" || op === "NOT IN") {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw new Error("WhereBuilder: " + op + " requires a non-empty array of values");
+      }
+      var placeholders = value.map(function () { return "?"; }).join(", ");
+      this._parts.push({ joiner: joiner, sql: qf + " " + op + " (" + placeholders + ")", params: value.slice() });
+      return this;
+    }
+    if (!ALLOWED_OPS.has(op)) {
+      throw new Error("WhereBuilder: invalid operator '" + op + "'");
+    }
+    this._parts.push({ joiner: joiner, sql: qf + " " + op + " ?", params: [value] });
+    return this;
+  }
+  eq(f, v)   { return this._push("AND", f, "=",  v); }
+  neq(f, v)  { return this._push("AND", f, "!=", v); }
+  gt(f, v)   { return this._push("AND", f, ">",  v); }
+  gte(f, v)  { return this._push("AND", f, ">=", v); }
+  lt(f, v)   { return this._push("AND", f, "<",  v); }
+  lte(f, v)  { return this._push("AND", f, "<=", v); }
+  in(f, vs)  { return this._push("AND", f, "IN", vs); }
+  like(f, v) { return this._push("AND", f, "LIKE", v); }
+  orEq(f, v)   { return this._push("OR", f, "=",  v); }
+  orNeq(f, v)  { return this._push("OR", f, "!=", v); }
+  orGt(f, v)   { return this._push("OR", f, ">",  v); }
+  orGte(f, v)  { return this._push("OR", f, ">=", v); }
+  orLt(f, v)   { return this._push("OR", f, "<",  v); }
+  orLte(f, v)  { return this._push("OR", f, "<=", v); }
+  orIn(f, vs)  { return this._push("OR", f, "IN", vs); }
+  orLike(f, v) { return this._push("OR", f, "LIKE", v); }
+  raw(sql, params) {
+    if (typeof sql !== "string" || sql.length === 0) {
+      throw new Error("WhereBuilder.raw: sql must be a non-empty string");
+    }
+    var p = Array.isArray(params) ? params : (params == null ? [] : [params]);
+    if (_countPlaceholders(sql) !== p.length) {
+      throw new Error("WhereBuilder.raw: placeholder count mismatch");
+    }
+    this._parts.push({ joiner: "AND", sql: "(" + sql + ")", params: p });
+    return this;
+  }
+  build() {
+    if (this._parts.length === 0) return { sql: "", params: [] };
+    var sql = this._parts[0].sql;
+    var params = this._parts[0].params.slice();
+    for (var i = 1; i < this._parts.length; i += 1) {
+      sql = sql + " " + this._parts[i].joiner + " " + this._parts[i].sql;
+      for (var j = 0; j < this._parts[i].params.length; j += 1) {
+        params.push(this._parts[i].params[j]);
+      }
+    }
+    return { sql: sql, params: params };
+  }
+}
+
 // Count `?` placeholders outside string literals + comments.
 // Tracks SQL single-quoted, double-quoted, line-comment, and block-
 // comment state to avoid counting `?` characters that are part of

package/lib/db.js

@@ -645,8 +645,12 @@ function resolveTmpDir(optsTmpDir) {
 
 // ---- DB encryption key management ----
 
-function loadOrCreateDbKey(dataDirPath) {
-  var keyPath = path.join(dataDirPath, "db.key.enc");
+function loadOrCreateDbKey(dataDirPath, keyPathOverride) {
+  // Operator opt: `opts.dbKeyPath` — useful when the encryption key
+  // needs to live outside `dataDir` (e.g. a separate volume mounted
+  // from a KMS-fronted secret store). Default places it next to the
+  // encrypted DB so backup capture is one-tarball.
+  var keyPath = keyPathOverride || path.join(dataDirPath, "db.key.enc");
   if (fs.existsSync(keyPath)) {
     var sealed = atomicFile.readSync(keyPath, { encoding: "utf8" }).trim();
     var b64 = vault.unseal(sealed);
@@ -703,6 +707,50 @@ function encryptToDisk() {
   atomicFile.writeSync(encPath, encryptPacked(fs.readFileSync(dbPath), encKey, _dbEncAad(dataDir)));
 }
 
+/**
+ * @primitive b.db.snapshot
+ * @signature b.db.snapshot()
+ * @since     0.8.58
+ * @status    stable
+ * @related   b.db.flushToDisk, b.backup
+ *
+ * In-memory encrypted snapshot — same envelope shape that
+ * `flushToDisk` writes, just held in memory. Operators capturing a
+ * backup mid-flight (`b.backup` wrapping a hot DB) get a Buffer they
+ * can stream onward to object storage without touching the on-disk
+ * encPath. Forces a WAL checkpoint first so the snapshot reflects
+ * committed state, not pre-WAL pages.
+ *
+ * Under `atRest: 'plain'` returns the raw plaintext SQLite file as a
+ * Buffer (no envelope), since there's no encryption key to apply —
+ * operators wanting an encrypted snapshot under plain mode wrap with
+ * their own `b.crypto.encryptPacked` at the call site.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var snap = b.db.snapshot();
+ *   await b.objectStore.put("backups/" + Date.now() + ".enc", snap);
+ */
+function snapshot() {
+  _requireInit();
+  // WAL checkpoint flushes committed transactions into the main DB file
+  // so the snapshot reflects the current logical state, not just the
+  // pre-WAL pages.
+  try { runSql(database, "PRAGMA wal_checkpoint(TRUNCATE)"); } catch (_e) { /* best effort */ }
+  if (!fs.existsSync(dbPath)) {
+    throw _dbErr("db/snapshot-no-source",
+      "snapshot: plaintext DB at " + dbPath + " is missing — did init complete?");
+  }
+  var plain = fs.readFileSync(dbPath);
+  if (!encPath || !encKey) {
+    // atRest: 'plain' — return the raw bytes. Operators wanting an
+    // encrypted snapshot under plain mode wrap with their own
+    // b.crypto.encryptPacked at the call site.
+    return plain;
+  }
+  return encryptPacked(plain, encKey, _dbEncAad(dataDir));
+}
+
 // Remove the plaintext DB + WAL/SHM sidecar files. On Windows these can't be
 // unlinked while the SQLite handle is open, so this MUST be called after
 // database.close().
@@ -846,9 +894,14 @@ async function init(opts) {
       }
     }
 
-    encPath = path.join(dataDir, "db.enc");
+    // Operator overrides for the encrypted-DB on-disk path. `opts.encryptedDbPath`
+    // takes a fully-qualified path; `opts.encryptedDbName` overrides
+    // just the basename under `dataDir` (default "db.enc"). Helps when
+    // multiple framework-shaped instances share a dataDir.
+    encPath = opts.encryptedDbPath ||
+              path.join(dataDir, opts.encryptedDbName || "db.enc");
     dbPath  = path.join(tmpDir, "blamejs-" + generateToken(C.BYTES.bytes(16)) + ".db");
-    encKey  = loadOrCreateDbKey(dataDir);
+    encKey  = loadOrCreateDbKey(dataDir, opts.dbKeyPath);
 
     cleanStaleTmpDbs(tmpDir);
     decryptToTmp();
@@ -945,14 +998,27 @@ async function init(opts) {
   // framework would silently provision it next to the reserved
   // namespace, allowing a row-by-row look-alike attack against audit
   // archive tooling.
+  // Under `frameworkTables: false` the framework's own audit_log /
+  // consent_log are NOT provisioned, so an operator naming a table
+  // `audit_log` (or `consent_log`) doesn't collide. The `_blamejs_*`
+  // prefix stays reserved unconditionally — those names are
+  // hard-claimed by other framework primitives (sessions, jobs,
+  // migrations, rate-limit-counters, …) which still get provisioned
+  // by their respective subsystems.
+  var frameworkTablesEarly = opts.frameworkTables !== false;
+  var FRAMEWORK_NAMED_RESERVED = frameworkTablesEarly
+    ? RESERVED_TABLE_NAMES
+    : new Set();   // empty — fall back to the prefix check only
   for (var ri = 0; ri < opts.schema.length; ri++) {
     var appName = opts.schema[ri].name;
-    if (RESERVED_TABLE_NAMES.has(appName) ||
+    if (FRAMEWORK_NAMED_RESERVED.has(appName) ||
         (typeof appName === "string" && appName.indexOf("_blamejs_") === 0)) {
       throw new DbError("db/reserved-table-name",
         "table name '" + appName + "' is reserved by the framework. " +
         "Pick a different name (the framework provisions audit_log, consent_log, " +
-        "and any '_blamejs_*'-prefixed tables automatically).");
+        "and any '_blamejs_*'-prefixed tables automatically). " +
+        "Pass opts.frameworkTables: false to skip provisioning audit_log/consent_log " +
+        "when the host application owns its own audit chain.");
     }
   }
 
@@ -1019,10 +1085,31 @@ async function init(opts) {
     }
   }
 
+  // Operator opt-out for the framework's own tables + audit/consent
+  // chain machinery + WORM assertion + audit-signing bootstrap. Set
+  // `frameworkTables: false` when the host application maintains its
+  // own audit/consent semantics and just wants the framework's
+  // primitives (vault / db / cryptoField / etc.) without the bundled
+  // chain tables. When OFF, every framework-table-dependent step
+  // below is a no-op. Append-only triggers are scoped to the
+  // framework tables only, so they're skipped too.
+  //
+  // `auditSigning: false` is a finer-grained gate — keep the
+  // framework tables but skip the audit-signing-key bootstrap (HS-
+  // shape deployments that already manage their own signing key).
+  //
+  // Defaults match v0.8.57 behavior: both ON.
+  var frameworkTablesEnabled = opts.frameworkTables !== false;
+  var auditSigningEnabled    = opts.auditSigning    !== false;
+
   // Build the full schema = framework-baked tables + app tables.
   // Framework tables come FIRST so audit_log/consent_log exist before any
-  // app migration can reference them.
-  var fullSchema = FRAMEWORK_SCHEMA.concat(opts.schema);
+  // app migration can reference them. When `frameworkTables: false`,
+  // skip the concat so the operator's own `audit_log` (or whatever
+  // shape) doesn't collide with the framework's.
+  var fullSchema = frameworkTablesEnabled
+    ? FRAMEWORK_SCHEMA.concat(opts.schema)
+    : opts.schema.slice();
 
   // Register schema with field-crypto + capture table metadata snapshot
   // (framework tables included so getTableMetadata covers everything).
@@ -1055,8 +1142,8 @@ async function init(opts) {
   // or malicious tampering — independent of the API surface's discipline.
   // Operator-driven retention purge (when implemented) must drop these
   // triggers explicitly inside a transaction, perform the purge, and
-  // recreate them.
-  _installAppendOnlyTriggers(database);
+  // recreate them. Skipped under `frameworkTables: false`.
+  if (frameworkTablesEnabled) _installAppendOnlyTriggers(database);
 
   // Imperative migrations (run once each, in order)
   if (opts.migrationDir) {
@@ -1081,29 +1168,33 @@ async function init(opts) {
   // means tamper-evidence has been compromised — the framework refuses
   // to continue under any circumstances. Recovery is operator-driven
   // (restore from backup or manual chain rebuild); the framework only
-  // detects-and-fails.
-  var auditResult = await audit.verify();
-  if (!auditResult.ok) {
-    // Fire the breach event BEFORE throwing so operator listeners get
-    // a chance at sync I/O (file flag, console alert) before init
-    // unwinds.
-    events.emit(events.EVENTS.AUDIT_CHAIN_BREAK, { table: "audit_log", result: auditResult });
-    throw _dbErr("db/audit-chain-break",
-      "FATAL: audit_log chain integrity broken at row " + auditResult.breakAt +
-      " (" + auditResult.reason + "); break row _id: " + auditResult.breakRowId +
-      "; expected: " + auditResult.expected + "; actual: " + auditResult.actual +
-      ". Refusing to boot. Compliance requires that any tamper-detection signal halt service. " +
-      "Recovery is manual: restore from backup, or rebuild the audit chain from a verified earlier snapshot.");
-  }
-  var consentResult = await consent.verify();
-  if (!consentResult.ok) {
-    events.emit(events.EVENTS.AUDIT_CHAIN_BREAK, { table: "consent_log", result: consentResult });
-    throw _dbErr("db/consent-chain-break",
-      "FATAL: consent_log chain integrity broken at row " + consentResult.breakAt +
-      " (" + consentResult.reason + "); break row _id: " + consentResult.breakRowId +
-      ". Refusing to boot.");
-  }
-  log("audit chain ok (" + auditResult.rowsVerified + " rows), consent chain ok (" + consentResult.rowsVerified + " rows)");
+  // detects-and-fails. Skipped under `frameworkTables: false` (the
+  // framework's audit_log / consent_log don't exist for an operator
+  // running their own audit subsystem).
+  if (frameworkTablesEnabled) {
+    var auditResult = await audit.verify();
+    if (!auditResult.ok) {
+      // Fire the breach event BEFORE throwing so operator listeners
+      // get a chance at sync I/O (file flag, console alert) before
+      // init unwinds.
+      events.emit(events.EVENTS.AUDIT_CHAIN_BREAK, { table: "audit_log", result: auditResult });
+      throw _dbErr("db/audit-chain-break",
+        "FATAL: audit_log chain integrity broken at row " + auditResult.breakAt +
+        " (" + auditResult.reason + "); break row _id: " + auditResult.breakRowId +
+        "; expected: " + auditResult.expected + "; actual: " + auditResult.actual +
+        ". Refusing to boot. Compliance requires that any tamper-detection signal halt service. " +
+        "Recovery is manual: restore from backup, or rebuild the audit chain from a verified earlier snapshot.");
+    }
+    var consentResult = await consent.verify();
+    if (!consentResult.ok) {
+      events.emit(events.EVENTS.AUDIT_CHAIN_BREAK, { table: "consent_log", result: consentResult });
+      throw _dbErr("db/consent-chain-break",
+        "FATAL: consent_log chain integrity broken at row " + consentResult.breakAt +
+        " (" + consentResult.reason + "); break row _id: " + consentResult.breakRowId +
+        ". Refusing to boot.");
+    }
+    log("audit chain ok (" + auditResult.rowsVerified + " rows), consent chain ok (" + consentResult.rowsVerified + " rows)");
+  }
 
   // ---- Rollback detection (audit.tip sidecar) ----
   // The framework writes <dataDir>/audit.tip on each checkpoint. At boot we
@@ -1116,11 +1207,15 @@ async function init(opts) {
   // MUST have declared row-level WORM on at least one business-record
   // table. Refuse boot otherwise so missing-declaration drift is
   // surfaced at start-up, not on the first delete.
-  try { _assertWormUnderPosture(); }
-  catch (e) {
-    // The assertion throws under regulated postures; let it
-    // propagate. Outside regulated postures it's a no-op.
-    throw e;
+  // Skipped under `frameworkTables: false` — WORM declarations are
+  // an operator-side concern when the framework isn't owning audit.
+  if (frameworkTablesEnabled) {
+    try { _assertWormUnderPosture(); }
+    catch (e) {
+      // The assertion throws under regulated postures; let it
+      // propagate. Outside regulated postures it's a no-op.
+      throw e;
+    }
   }
 
   // ---- Audit-signing key + checkpoint subsystem ----
@@ -1132,37 +1227,46 @@ async function init(opts) {
   // SHAKE-family hash posture); ML-DSA-87 is the throughput-focused
   // opt-in. Existing key files take their algorithm from disk; this
   // option only matters on first generation.
-  var auditSigningMode = (opts.auditSigning && opts.auditSigning.mode)
-    ? opts.auditSigning.mode
-    : safeEnv.readVar("BLAMEJS_AUDIT_SIGNING_MODE", {
-        default: "wrapped",
-        enum:    ["wrapped", "plaintext"],
-      });
-  var auditSigningAlg = opts.auditSigning && opts.auditSigning.algorithm
-    ? opts.auditSigning.algorithm
-    : null;
-  await auditSign.init({
-    dataDir:   dataDir,
-    mode:      auditSigningMode,
-    algorithm: auditSigningAlg || undefined,
-  });
-
-  // Verify all existing checkpoint signatures (defense against signature
-  // forgery attempt + key-rotation gone wrong). Refuse to boot on failure.
-  var ckptResult = await audit.verifyCheckpoints();
-  if (!ckptResult.ok) {
-    events.emit(events.EVENTS.AUDIT_CHECKPOINT_BREAK, { result: ckptResult });
-    throw _dbErr("db/audit-checkpoint-break",
-      "FATAL: audit checkpoint verification failed at row " +
-      ckptResult.breakAt + " (" + ckptResult.reason + "); checkpoint _id: " +
-      ckptResult.checkpointId + ". Refusing to boot. Either the audit-signing key " +
-      "was rotated without retaining the prior pubkey, or a forged checkpoint was inserted.");
+  // Operator opt-out via `auditSigning: false` skips the signing
+  // bootstrap entirely. Also implicitly skipped when frameworkTables
+  // are off (no audit_log to sign checkpoints over).
+  if (auditSigningEnabled && frameworkTablesEnabled) {
+    var auditSigningMode = (opts.auditSigning && opts.auditSigning.mode)
+      ? opts.auditSigning.mode
+      : safeEnv.readVar("BLAMEJS_AUDIT_SIGNING_MODE", {
+          default: "wrapped",
+          enum:    ["wrapped", "plaintext"],
+        });
+    var auditSigningAlg = opts.auditSigning && opts.auditSigning.algorithm
+      ? opts.auditSigning.algorithm
+      : null;
+    await auditSign.init({
+      dataDir:   dataDir,
+      mode:      auditSigningMode,
+      algorithm: auditSigningAlg || undefined,
+    });
   }
-  log("audit checkpoints ok (" + ckptResult.checkpointsVerified + " signed)");
 
-  // Anchor a fresh checkpoint at boot if there's any new audit activity
-  // since the last checkpoint (else no-op).
-  await audit.checkpoint({ skipIfUnchanged: true });
+  // Verify all existing checkpoint signatures (defense against
+  // signature forgery attempt + key-rotation gone wrong). Refuse to
+  // boot on failure. Skipped under `frameworkTables: false` /
+  // `auditSigning: false`.
+  if (frameworkTablesEnabled && auditSigningEnabled) {
+    var ckptResult = await audit.verifyCheckpoints();
+    if (!ckptResult.ok) {
+      events.emit(events.EVENTS.AUDIT_CHECKPOINT_BREAK, { result: ckptResult });
+      throw _dbErr("db/audit-checkpoint-break",
+        "FATAL: audit checkpoint verification failed at row " +
+        ckptResult.breakAt + " (" + ckptResult.reason + "); checkpoint _id: " +
+        ckptResult.checkpointId + ". Refusing to boot. Either the audit-signing key " +
+        "was rotated without retaining the prior pubkey, or a forged checkpoint was inserted.");
+    }
+    log("audit checkpoints ok (" + ckptResult.checkpointsVerified + " signed)");
+
+    // Anchor a fresh checkpoint at boot if there's any new audit
+    // activity since the last checkpoint (else no-op).
+    await audit.checkpoint({ skipIfUnchanged: true });
+  }
 
   // ---- NTP drift check ----
   // Best-effort; unreachable NTP doesn't fail boot, but >= 1hr drift does
@@ -2761,6 +2865,7 @@ module.exports = {
   getActivePosture:    getActivePosture,
   vacuumAfterErase:    vacuumAfterErase,
   from:                from,
+  collection:          require("./db-collection").collection,                              // allow:inline-require — db-collection lazy-requires db.js back; the inline require here breaks the cycle without needing a stub
   prepare:             prepare,
   stream:              stream,
   // D-M5 — runtime read-only accessor so Query.stream picks up the
@@ -2782,6 +2887,7 @@ module.exports = {
   // the snapshot source. Safe to call any time; no-op when no encPath
   // (plain mode) or when the plaintext DB doesn't exist.
   flushToDisk:         encryptToDisk,
+  snapshot:            snapshot,
   // integrityCheck — runs PRAGMA integrity_check against the live db
   // and returns "ok" on success, an array of corruption lines
   // otherwise. Operators wire this into a periodic monitor or a