@blamejs/core 0.8.42 → 0.8.49

package/lib/db.js

@@ -1,43 +1,45 @@
 "use strict";
 /**
- * Database orchestrator — encrypted-at-rest SQLite backed by node:sqlite.
- *
- * At-rest modes (default 'encrypted' per modernity stance; 'plain' is opt-out
- * only and emits a console warning at boot):
- *
- *   encrypted (default):
- *     - DB file lives in tmpfs (/dev/shm by default; configurable via
- *       db.init({ tmpDir }) or BLAMEJS_TMPDIR env var) at runtime.
- *     - On boot: <dataDir>/db.enc → decrypt → tmpDir/blamejs-<token>.db
- *     - Periodic re-encrypt every 5 minutes back to <dataDir>/db.enc.
- *     - On shutdown: final encrypt + remove plaintext from tmpfs.
- *     - DB encryption key sealed by vault, persisted at <dataDir>/db.key.enc.
- *     - Refuses to boot if neither a tmpDir nor /dev/shm is available.
- *
- *   plain (opt-out):
- *     - DB file lives directly at <dataDir>/db (plain SQLite on disk).
- *     - No periodic encryption. Field-level encryption (field-crypto.js)
- *       still protects sealed columns, but schema and row counts are visible.
- *     - Boot warning printed.
- *
- * Public API:
- *
- *   await db.init({
- *     dataDir,                         // required — where db.enc + db.key.enc live
- *     tmpDir,                          // optional — override (default /dev/shm)
- *     atRest: 'encrypted' | 'plain',   // default 'encrypted'
- *     schema: [ { name, columns, indexes, sealedFields, derivedHashes }, ... ],
- *     migrationDir,                    // optional — path to ./migrations/ (run-once)
- *   });
+ * @module b.db
+ * @featured true
+ * @nav    Data
+ * @title  Db
+ *
+ * @intro
+ *   Database core — SQLite (node:sqlite) wrapped in encrypted-at-rest
+ *   storage, sealed-column field-level crypto, append-only audit-chain
+ *   integration, declarative schema reconcile, and run-once
+ *   migrations. Default at-rest posture is `encrypted`: the live `.db`
+ *   lives in tmpfs (/dev/shm), is decrypted from `<dataDir>/db.enc` at
+ *   boot, periodically re-encrypted every five minutes, and re-
+ *   encrypted again at shutdown. The DB encryption key is sealed by
+ *   `b.vault` at `<dataDir>/db.key.enc`. Operators who want a plain
+ *   on-disk SQLite file pass `atRest: "plain"` and accept a boot
+ *   warning — sealed columns still protect PII, but schema and row
+ *   counts are visible to a forensic disk image.
+ *
+ *   Beyond the storage shell, the module owns the framework's data
+ *   contract: `audit_log` / `consent_log` / `audit_checkpoints` and
+ *   the `_blamejs_*` reserved tables are provisioned before any
+ *   operator schema reconciles, append-only triggers refuse
+ *   UPDATE/DELETE on the chain tables, and boot refuses to continue
+ *   on chain breakage, checkpoint signature failure, audit-log
+ *   rollback, or PRAGMA integrity_check corruption. WORM
+ *   declarations (`declareWorm`) and dual-control gates
+ *   (`declareRequireDualControl`) layer SEC 17a-4(f) / FINRA 4511 /
+ *   21 CFR Part 11 §11.10(c) record-preservation invariants on
+ *   operator tables.
  *
- *   db.from(tableName)                 → Query (chainable)
- *   db.prepare(sql)                    → SQLite Statement (raw escape hatch)
- *   db.stream(sql, ...params, opts?)   → Readable (object-mode rows;
- *                                       opts.table enables auto-unseal)
- *   db.runSql(sql)                     → raw SQL execution (DDL, BEGIN/COMMIT)
- *   db.transaction(function (db) {…})  → wraps in BEGIN/COMMIT/ROLLBACK
- *   db.hashFor(table, field, value)    → derived-hash lookup helper
- *   db.close()                         → final encrypt + close (idempotent)
+ *   The query surface is `db.from(table)` (chainable), `db.prepare`
+ *   (LRU-cached node:sqlite Statement), `db.stream` (object-mode
+ *   Readable for million-row exports with auto-unseal), and
+ *   `db.transaction` (BEGIN/COMMIT/ROLLBACK around a callback).
+ *   Postgres-only declarative migrations (`declareView` /
+ *   `declareRowPolicy`) emit migration-shape objects consumed by
+ *   `b.externalDb.migrate`.
+ *
+ * @card
+ *   Database core — SQLite (node:sqlite) wrapped in encrypted-at-rest storage, sealed-column field-level crypto, append-only audit-chain integration, declarative schema reconcile, and run-once migrations.
  */
 var fs = require("fs");
 var path = require("path");
@@ -47,10 +49,11 @@ var atomicFile = require("./atomic-file");
 var audit = require("./audit");
 var auditSign = require("./audit-sign");
 var cluster = require("./cluster");
+var csv = require("./csv");
 var events = require("./events");
 var consent = require("./consent");
 var C = require("./constants");
-var { generateToken, generateBytes, encryptPacked, decryptPacked } = require("./crypto");
+var { generateToken, generateBytes, encryptPacked, decryptPacked, sha3Hash } = require("./crypto");
 var cryptoField = require("./crypto-field");
 var dbDeclareRowPolicy = require("./db-declare-row-policy");
 var dbDeclareView = require("./db-declare-view");
@@ -64,9 +67,27 @@ var ntpCheck = lazyRequire(function () { return require("./ntp-check"); });
 var safeAsync = require("./safe-async");
 var safeEnv = require("./parsers/safe-env");
 var safeJson = require("./safe-json");
+var safeSql = require("./safe-sql");
+var validateOpts = require("./validate-opts");
 var vault = require("./vault");
 
 var DbError = defineClass("DbError", { alwaysPermanent: true });
+var WormViolationError = require("./framework-error").WormViolationError;
+var _wormErr = WormViolationError.factory;
+
+// Lazy: compliance and dual-control read state at runtime; both are
+// non-load-time deps so a top-of-file require would not cycle, but
+// they're only needed on declareWorm / declareRequireDualControl /
+// eraseHard. Lazy keeps the load graph minimal.
+var compliance = lazyRequire(function () { return require("./compliance"); });
+
+// Postures that REQUIRE row-level WORM on operator-named business-
+// record tables. Audit_log / consent_log / audit_checkpoints are
+// already WORM-by-default; this set covers operator tables.
+//   sec-17a-4   — SEC Rule 17a-4(f) broker-dealer record preservation
+//   finra-4511  — FINRA Rule 4511 books-and-records
+//   fda-21cfr11 — 21 CFR Part 11 §11.10(c) protect record integrity
+var WORM_POSTURES = Object.freeze(["sec-17a-4", "finra-4511", "fda-21cfr11"]);
 var _dbErr = DbError.factory;
 
 // Lazy: cluster-storage's _localDb pulls db back in, so eager require
@@ -116,6 +137,12 @@ var initialized = false;
 var dataResidency = null;   // operator's declared region config (validated by storage backends)
 var subjectTables = [];     // [{ name, subjectField, personalDataCategories }] — for subject.export/erase
 var tableMetadata = {};     // table name → metadata snapshot (PK/FK/sealed/derived) for getTableMetadata
+// D-M5 — streamLimit ceiling. db.stream() / Query.stream() consult this
+// (overridden per-call via opts.streamLimit). Default cap matches a
+// generous-but-bounded 1M rows so an accidentally-unbounded export
+// surfaces a thrown error instead of OOM. v0.7.67's maxRowsPerQuery
+// bounds .all() / .first() — this is its streaming counterpart.
+var streamLimit = C.BYTES.bytes(1000000);                                                              // allow:raw-byte-literal — row-count ceiling, not bytes
 
 // ---- Framework-baked tables ----
 //
@@ -225,6 +252,67 @@ var FRAMEWORK_SCHEMA = [
       erasedAt:      "INTEGER NOT NULL",
     },
   },
+  {
+    // Subject-level legal hold registry. Operators register a hold
+    // via b.legalHold.place(subjectId, ...) — b.subject.erase and
+    // b.retention consult b.legalHold.isHeld(subjectId) before
+    // accepting any deletion. Per FRCP Rule 26/37(e), GDPR Art
+    // 17(3)(e), SEC Rule 17a-4, HIPAA §164.530(j)(2).
+    name: "_blamejs_legal_hold",
+    columns: {
+      subjectIdHash: "TEXT PRIMARY KEY",
+      placedAt:      "INTEGER NOT NULL",
+      placedBy:      "TEXT",
+      reason:        "TEXT NOT NULL",
+      custodian:     "TEXT",
+      citation:      "TEXT",
+      retainUntil:   "INTEGER",
+    },
+    indexes: ["placedAt"],
+  },
+  {
+    // Per-row crypto-erasure key registry — F-RTBF-3 per-row keys.
+    // Each entry holds a sealed wrapped K_row keyed by (table,
+    // rowId). b.subject.eraseHard deletes the entry, leaving WAL /
+    // replica residuals undecryptable.
+    name: "_blamejs_per_row_keys",
+    columns: {
+      tableName:  "TEXT NOT NULL",
+      rowId:      "TEXT NOT NULL",
+      wrappedKey: "BLOB NOT NULL",
+      createdAt:  "INTEGER NOT NULL",
+    },
+    primaryKey: ["tableName", "rowId"],
+    indexes: [],
+  },
+  {
+    // Operator-declared WORM (write-once-read-many) registry. Each
+    // entry pairs an operator-named table with the posture that
+    // demanded the WORM declaration; boot-time assertions iterate
+    // this registry to verify triggers are installed under the
+    // current b.compliance.current() posture.
+    name: "_blamejs_worm_tables",
+    columns: {
+      tableName: "TEXT PRIMARY KEY",
+      posture:   "TEXT",
+      declaredAt: "INTEGER NOT NULL",
+    },
+  },
+  {
+    // Operator-declared dual-control gate registry. b.db.delete /
+    // b.subject.erase / b.audit.purge consult this table on
+    // destructive ops; under the named posture the framework refuses
+    // execution unless the caller passes a consumed dual-control
+    // grant.
+    name: "_blamejs_dual_control_gates",
+    columns: {
+      tableName: "TEXT PRIMARY KEY",
+      posture:   "TEXT",
+      m:         "INTEGER NOT NULL",
+      n:         "INTEGER NOT NULL",
+      declaredAt:"INTEGER NOT NULL",
+    },
+  },
   {
     name: "audit_checkpoints",
     columns: {
@@ -643,6 +731,61 @@ function cleanStaleTmpDbs(tmpDir) {
 
 // ---- Init dispatch ----
 
+/**
+ * @primitive b.db.init
+ * @signature b.db.init(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.close, b.db.from, b.db.declareWorm
+ *
+ * Boot the database. Provisions the framework-baked tables
+ * (`audit_log` / `consent_log` / `audit_checkpoints` /
+ * `_blamejs_*`), reconciles the operator schema, installs append-
+ * only triggers on chain tables, runs any pending file-based
+ * migrations, verifies the audit + consent chains end-to-end,
+ * verifies every audit checkpoint signature, runs PRAGMA
+ * integrity_check, performs a rollback-detection check against
+ * `audit.tip`, and runs a best-effort SNTP boot drift check. Refuses
+ * to boot on any chain breakage, signature mismatch, or rollback —
+ * compliance posture demands fail-closed at the earliest signal.
+ *
+ * @opts
+ *   dataDir:                 string,            // required — where db.enc + db.key.enc live
+ *   schema:                  Array,             // required — [{ name, columns, indexes, sealedFields, derivedHashes, foreignKeys, primaryKey, subjectField, personalDataCategories }, ...]
+ *   atRest:                  "encrypted"|"plain", // default "encrypted"
+ *   tmpDir:                  string,            // override the encrypted-mode tmpfs path (default /dev/shm or BLAMEJS_TMPDIR)
+ *   migrationDir:            string,            // optional — path to ./migrations/ (run-once each)
+ *   streamLimit:             number,            // default 1_000_000 — db.stream row ceiling
+ *   skipBootIntegrityCheck:  boolean,           // default false — skip PRAGMA integrity_check
+ *   skipIntegrityCheck:      boolean,           // default false — alias
+ *   auditSigning:            { mode, algorithm }, // default { mode: "wrapped" }
+ *   ntpServers:              string[],          // override NTP server list
+ *   ntpTimeoutMs:            number,            // override NTP timeout
+ *   dataResidency:           object,            // operator's region declaration
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({
+ *     dataDir: "/var/lib/myapp",
+ *     atRest:  "encrypted",
+ *     schema: [
+ *       {
+ *         name: "orders",
+ *         columns: {
+ *           _id:        "TEXT PRIMARY KEY",
+ *           customerId: "TEXT NOT NULL",
+ *           totalCents: "INTEGER NOT NULL",
+ *           note:       "TEXT",
+ *           createdAt:  "INTEGER NOT NULL",
+ *         },
+ *         indexes:       ["customerId"],
+ *         sealedFields:  ["note"],
+ *         derivedHashes: { customerIdHash: { from: "customerId" } },
+ *         subjectField:  "customerId",
+ *       },
+ *     ],
+ *   });
+ */
 async function init(opts) {
   if (initialized) return;
   // Drop any prepared-statement cache leftover from a prior init/close
@@ -661,6 +804,18 @@ async function init(opts) {
     throw new DbError("db/bad-at-rest",
       "db.init: atRest must be 'encrypted' or 'plain', got: " + opts.atRest);
   }
+  // D-M5 — operator-tunable streamLimit ceiling. Throw at config-time
+  // on bad shape so a typo surfaces at boot rather than as an
+  // unbounded stream at first export.
+  if (opts.streamLimit !== undefined) {
+    if (typeof opts.streamLimit !== "number" || !isFinite(opts.streamLimit) ||
+        opts.streamLimit <= 0 || Math.floor(opts.streamLimit) !== opts.streamLimit) {
+      throw new DbError("db/bad-init",
+        "db.init: streamLimit must be a positive finite integer; got " +
+        JSON.stringify(opts.streamLimit));
+    }
+    streamLimit = opts.streamLimit;
+  }
   dataDir = opts.dataDir;
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
 
@@ -956,6 +1111,18 @@ async function init(opts) {
   // is BELOW tip — the DB was rolled back to an older snapshot. Refuse boot.
   _checkRollback(dataDir);
 
+  // ---- F-RET-2 — WORM posture assertion ----
+  // Under sec-17a-4 / finra-4511 / fda-21cfr11 postures the operator
+  // 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;
+  }
+
   // ---- Audit-signing key + checkpoint subsystem ----
   // Default mode 'wrapped' (passphrase-required, separate from vault). Apps
   // that want a quick-start dev path can pass auditSigning: { mode: 'plaintext' }
@@ -1023,6 +1190,36 @@ async function init(opts) {
 
 // ---- Public API ----
 
+/**
+ * @primitive b.db.from
+ * @signature b.db.from(tableName)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.prepare, b.db.transaction, b.db.stream
+ *
+ * Open a chainable Query against a registered table. Sealed columns
+ * auto-encrypt on insert/update and auto-decrypt on read; derived-
+ * hash columns auto-populate from their source field on insert.
+ * Identifier safety, parameter binding, row-policy gates, and
+ * audit-emission are wired into the chain so operator code never
+ * concatenates SQL by hand.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "orders",
+ *       columns: { _id: "TEXT PRIMARY KEY", customerId: "TEXT NOT NULL", totalCents: "INTEGER NOT NULL" },
+ *       sealedFields: ["customerId"] },
+ *   ] });
+ *
+ *   b.db.from("orders").insert({
+ *     _id: b.uuid.v7(), customerId: "cust_123", totalCents: 4999,
+ *   });
+ *
+ *   var rows = b.db.from("orders").where({ customerId: "cust_123" }).all();
+ *   rows.length;
+ *   // → 1
+ */
 function from(tableName) {
   _requireInit();
   return new Query(database, tableName);
@@ -1038,6 +1235,33 @@ function from(tableName) {
 var PREPARE_CACHE_MAX = 256;                                                       // allow:raw-byte-literal — distinct-statement cache cap
 var _prepareCache = new Map();                                                     // sql → Statement (insertion order = LRU)
 
+/**
+ * @primitive b.db.prepare
+ * @signature b.db.prepare(sql)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.from, b.db.runSql, b.db.stream
+ *
+ * Raw-escape-hatch wrapper around `node:sqlite`'s `Statement`
+ * preparation, with an LRU cache keyed by SQL string (cap 256
+ * distinct shapes). Reuse of the same SQL returns the cached
+ * Statement so a hot path doesn't churn file descriptors. Use
+ * `b.db.from(table)` for the typical chainable surface; `prepare` is
+ * for the rare cases where the chainable Query doesn't cover the
+ * shape.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "orders",
+ *       columns: { _id: "TEXT PRIMARY KEY", totalCents: "INTEGER NOT NULL" } },
+ *   ] });
+ *
+ *   var stmt = b.db.prepare("SELECT SUM(totalCents) AS total FROM orders");
+ *   var row = stmt.get();
+ *   typeof row.total;
+ *   // → "object"
+ */
 function prepare(sql) {
   _requireInit();
   if (_prepareCache.has(sql)) {
@@ -1056,15 +1280,43 @@ function prepare(sql) {
   return stmt;
 }
 
-// stream — Readable in object mode that yields rows as node:sqlite's
-// iterate() produces them. Unlike all(), the engine doesn't materialize
-// the result set in memory before the first row arrives, so audit
-// exports / backup table dumps / large reports can process millions of
-// rows without OOM pressure.
-//
-// Optional opts.table enables auto-unseal of sealed columns via the
-// table's registered cryptoField schema. Raw / aggregate queries omit
-// it. Mid-iteration prepare()-bound errors propagate as 'error' events.
+/**
+ * @primitive b.db.stream
+ * @signature b.db.stream(sql)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.db.from, b.db.prepare, b.db.exportCsv
+ *
+ * Object-mode `Readable` that yields rows as `node:sqlite`'s
+ * `iterate()` produces them. Unlike `.all()`, the engine never
+ * materializes the full result set, so audit exports, backup table
+ * dumps, and million-row reports finish without OOM pressure.
+ * Variadic: positional parameter bindings come after `sql`; an
+ * optional final plain-object argument carries `opts.table` (enables
+ * sealed-column auto-unseal) and `opts.streamLimit` (per-call row
+ * ceiling override). Default ceiling is the module-level
+ * `streamLimit` (1_000_000); the stream destroys with a
+ * `db/stream-limit-exceeded` error past the cap rather than
+ * accumulating unboundedly.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "events",
+ *       columns: { _id: "TEXT PRIMARY KEY", payload: "TEXT" },
+ *       sealedFields: ["payload"] },
+ *   ] });
+ *
+ *   var count = 0;
+ *   var s = b.db.stream("SELECT * FROM events", { table: "events" });
+ *   await new Promise(function (resolve, reject) {
+ *     s.on("data", function (_row) { count += 1; });
+ *     s.on("end",   resolve);
+ *     s.on("error", reject);
+ *   });
+ *   count >= 0;
+ *   // → true
+ */
 function stream(sql) {
   _requireInit();
   var opts = null;
@@ -1090,6 +1342,20 @@ function stream(sql) {
   var table = opts && typeof opts.table === "string" ? opts.table : null;
   var unseal = table ? cryptoField : null;
 
+  // D-M5 — streamLimit ceiling. Per-call opts.streamLimit overrides
+  // the module-level default; bad shape throws at call time so the
+  // typo surfaces instead of an unbounded stream.
+  var perCallLimit = streamLimit;
+  if (opts && opts.streamLimit !== undefined) {
+    if (typeof opts.streamLimit !== "number" || !isFinite(opts.streamLimit) ||
+        opts.streamLimit <= 0 || Math.floor(opts.streamLimit) !== opts.streamLimit) {
+      throw new DbError("db/bad-stream-limit",
+        "db.stream: opts.streamLimit must be a positive finite integer; got " +
+        JSON.stringify(opts.streamLimit));
+    }
+    perCallLimit = opts.streamLimit;
+  }
+
   var stmt;
   var iter;
   try {
@@ -1100,12 +1366,21 @@ function stream(sql) {
     setImmediate(function () { r.destroy(e); });
     return r;
   }
+  var emitted = 0;
   return new Readable({
     objectMode: true,
     read: function () {
       try {
+        if (emitted >= perCallLimit) {
+          this.destroy(new DbError("db/stream-limit-exceeded",
+            "db.stream: emitted " + emitted + " rows, exceeding streamLimit " +
+            perCallLimit + ". Pass opts.streamLimit higher OR raise via " +
+            "db.init({ streamLimit }) after auditing the export path."));
+          return;
+        }
         var step = iter.next();
         if (step.done) { this.push(null); return; }
+        emitted += 1;
         var row = step.value;
         this.push(unseal ? unseal.unsealRow(table, row) : row);
       } catch (e) {
@@ -1120,6 +1395,38 @@ function stream(sql) {
 // review can reconstruct schema evolution from the chain alone (D-M1).
 var DDL_RE = /^\s*(CREATE|DROP|ALTER|TRUNCATE|RENAME|ATTACH|DETACH|REINDEX)\b/i;
 
+// D-L7 — slow-query observability buckets for the local SQLite path.
+// Highest matched bucket wins so the per-query emit is single-shot;
+// operators dashboard on the `bucket` label.
+var _SLOW_QUERY_BUCKETS_LOCAL = Object.freeze([
+  { ms: C.TIME.seconds(30), label: "30s" },
+  { ms: C.TIME.seconds(5),  label: "5s" },
+  { ms: C.TIME.seconds(1),  label: "1s" },
+]);
+var _STATEMENT_CLASS_RE_LOCAL = /^\s*(?:\/\*[\s\S]*?\*\/\s*|--[^\n]*\n\s*)*([A-Za-z]+)/;
+function _classifyStatementLocal(sql) {
+  if (typeof sql !== "string" || sql.length === 0) return "UNKNOWN";
+  var m = _STATEMENT_CLASS_RE_LOCAL.exec(sql);
+  return m ? m[1].toUpperCase() : "UNKNOWN";
+}
+function _reportSlowSqlite(durationMs, statement) {
+  if (typeof durationMs !== "number" || !isFinite(durationMs)) return;
+  for (var i = 0; i < _SLOW_QUERY_BUCKETS_LOCAL.length; i++) {
+    var bucket = _SLOW_QUERY_BUCKETS_LOCAL[i];
+    if (durationMs >= bucket.ms) {
+      try {
+        observability.event("db.query.slow", durationMs, {
+          backend:        "sqlite",
+          bucket:         bucket.label,
+          statementClass: _classifyStatementLocal(statement),
+          "db.statement": String(statement || "").slice(0, 256),                                       // allow:raw-byte-literal — log-truncation length, not bytes
+        });
+      } catch (_e) { /* hot-path observability sink — drop-silent by design */ }
+      return;
+    }
+  }
+}
+
 function execRaw(sql) {
   _requireInit();
   var startedAt = Date.now();
@@ -1129,6 +1436,8 @@ function execRaw(sql) {
   var isDdl = typeof sql === "string" && DDL_RE.test(sql);                                    // allow:regex-no-length-cap — leading-keyword anchor; constant-time test
   try {
     var result = runSql(database, sql);
+    var durationMs = Date.now() - startedAt;
+    _reportSlowSqlite(durationMs, sql);
     if (isDdl && auditMod) {
       auditMod.safeEmit({
         action:   "db.ddl.executed",
@@ -1140,12 +1449,14 @@ function execRaw(sql) {
           "db.system":     "sqlite",
           "db.operation":  String(sql).match(DDL_RE)[1].toUpperCase(),
           "db.statement":  String(sql).slice(0, 256),                                          // allow:raw-byte-literal — log-truncation length, not bytes
-          durationMs:      Date.now() - startedAt,
+          durationMs:      durationMs,
         },
       });
     }
     return result;
   } catch (e) {
+    var failureMs = Date.now() - startedAt;
+    _reportSlowSqlite(failureMs, sql);
     if (isDdl && auditMod) {
       auditMod.safeEmit({
         action:   "db.ddl.executed",
@@ -1155,7 +1466,7 @@ function execRaw(sql) {
           "db.system":     "sqlite",
           "db.operation":  String(sql).match(DDL_RE)[1].toUpperCase(),
           "db.statement":  String(sql).slice(0, 256),                                          // allow:raw-byte-literal — log-truncation length, not bytes
-          durationMs:      Date.now() - startedAt,
+          durationMs:      failureMs,
         },
       });
     }
@@ -1163,6 +1474,39 @@ function execRaw(sql) {
   }
 }
 
+/**
+ * @primitive b.db.transaction
+ * @signature b.db.transaction(fn)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.from, b.db.eraseHard
+ *
+ * Run `fn(db)` inside a `BEGIN ... COMMIT` block; any throw inside
+ * `fn` triggers `ROLLBACK` and re-propagates the error. Returns the
+ * value `fn` returned. Transactions compose with the chainable
+ * Query surface and with audit-chain emissions inside the body — the
+ * audit row's chain hash is computed from the value at COMMIT time,
+ * so a rolled-back transaction never leaves a phantom row in
+ * `audit_log`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "ledger",
+ *       columns: { _id: "TEXT PRIMARY KEY", balanceCents: "INTEGER NOT NULL" } },
+ *   ] });
+ *
+ *   b.db.from("ledger").insert({ _id: "acct_1", balanceCents: 100 });
+ *   b.db.from("ledger").insert({ _id: "acct_2", balanceCents: 0 });
+ *
+ *   b.db.transaction(function (db) {
+ *     db.from("ledger").where({ _id: "acct_1" }).update({ balanceCents: 50 });
+ *     db.from("ledger").where({ _id: "acct_2" }).update({ balanceCents: 50 });
+ *   });
+ *
+ *   b.db.from("ledger").where({ _id: "acct_2" }).first().balanceCents;
+ *   // → 50
+ */
 function transaction(fn) {
   _requireInit();
   if (typeof fn !== "function") {
@@ -1179,12 +1523,296 @@ function transaction(fn) {
   }
 }
 
+/**
+ * @primitive b.db.hashFor
+ * @signature b.db.hashFor(table, field, value)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.from
+ *
+ * Look up the deterministic SHA3 hash a sealed-source field maps to
+ * via the table's registered `derivedHashes`. Used to query a sealed
+ * column without unsealing every row — operator code passes the
+ * cleartext, the framework hashes it through the same namespaced
+ * derivation, and a `WHERE <hashColumn> = ?` lookup returns the
+ * matching rows. Returns `null` when the field has no derived-hash
+ * declaration on the table.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "users",
+ *       columns: { _id: "TEXT PRIMARY KEY", email: "TEXT", emailHash: "TEXT" },
+ *       sealedFields:  ["email"],
+ *       derivedHashes: { emailHash: { from: "email" } } },
+ *   ] });
+ *
+ *   b.db.from("users").insert({ _id: "u1", email: "alice@example.com" });
+ *
+ *   var h = b.db.hashFor("users", "email", "alice@example.com");
+ *   typeof h;
+ *   // → "string"
+ */
 function hashFor(table, field, value) {
   _requireInit();
   var lookup = cryptoField.lookupHash(table, field, value);
   return lookup ? lookup.value : null;
 }
 
+// _ddlToJsonSchemaType — best-effort SQL→JSON Schema type mapping.
+// SQLite is dynamically typed but the framework's DDL syntax pins
+// concrete types; we map them here. Operator-supplied custom types
+// (rare) fall back to "string" so the schema remains usable.
+function _ddlToJsonSchemaType(ddl) {
+  if (typeof ddl !== "string" || ddl.length === 0) return { type: "string" };
+  var head = ddl.split(/\s+/)[0].toUpperCase();
+  if (head === "INTEGER" || head === "INT" || head === "BIGINT") return { type: "integer" };
+  if (head === "REAL" || head === "FLOAT" || head === "DOUBLE" || head === "NUMERIC") return { type: "number" };
+  if (head === "BOOLEAN" || head === "BOOL") return { type: "boolean" };
+  if (head === "BLOB") return { type: "string", contentEncoding: "base64" };
+  if (head === "TEXT" || head === "VARCHAR" || head === "CHAR") return { type: "string" };
+  return { type: "string" };
+}
+
+// _tableToJsonSchema2020 — emit a JSON Schema 2020-12 description of
+// the named table. Sealed columns get an `x-blamejs-sealed: true`
+// annotation so consumers know the value is encrypted at rest;
+// derived-hash columns gain `x-blamejs-derived-from`. The schema's
+// `$schema` URI explicitly names the 2020-12 dialect so generated
+// validators round-trip.
+function _tableToJsonSchema2020(tableName, meta) {
+  var properties = {};
+  var required = [];
+  var cols = (meta && meta.columns) || {};
+  var colKeys = Object.keys(cols);
+  for (var i = 0; i < colKeys.length; i++) {
+    var col = colKeys[i];
+    var ddl = cols[col];
+    var schema = _ddlToJsonSchemaType(ddl);
+    if (typeof ddl === "string" && /\bNOT\s+NULL\b/i.test(ddl)) {
+      required.push(col);
+    } else {
+      // Nullable column — JSON Schema 2020-12 expresses this as a
+      // type union with "null".
+      schema = { anyOf: [schema, { type: "null" }] };
+    }
+    if (meta.sealedFields && meta.sealedFields.indexOf(col) !== -1) {
+      schema["x-blamejs-sealed"] = true;
+    }
+    if (meta.derivedHashes &&
+        Object.prototype.hasOwnProperty.call(meta.derivedHashes, col)) {
+      schema["x-blamejs-derived-from"] = meta.derivedHashes[col].from;
+    }
+    properties[col] = schema;
+  }
+  return {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id":     "blamejs:table:" + tableName,
+    title:     tableName,
+    type:      "object",
+    properties: properties,
+    required:   required,
+    additionalProperties: false,
+  };
+}
+
+/**
+ * @primitive b.db.exportCsv
+ * @signature b.db.exportCsv(opts)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.db.from, b.auditSign.getPublicKey
+ *
+ * RFC 4180 strict CSV export of a single registered table, with
+ * sealed-column auto-unseal (rides the chainable Query), optional
+ * WHERE filter, optional column projection, optional UTF-8 BOM,
+ * ISO-8601 cast for declared timestamp fields, SHA3-512 manifest of
+ * the byte stream, and an optional detached signature via any
+ * `b.auditSign`-shaped signer. Refuses unknown table names, refuses
+ * arbitrary column strings (every column must belong to the table),
+ * and emits a `db.export.csv` audit row.
+ *
+ * @opts
+ *   table:           string,      // required — registered table name
+ *   columns:         string[],    // optional column projection (default: all)
+ *   where:           object,      // optional Query.where(...) filter
+ *   bom:             boolean,     // default false; emit U+FEFF prefix
+ *   format:          "rfc4180",   // default "rfc4180" (only supported value)
+ *   timestampFields: string[],    // ms-int columns to cast to ISO-8601
+ *   signWith:        object,      // signer with sign / getPublicKey / getAlgorithm / getPublicKeyFingerprint
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "orders",
+ *       columns: { _id: "TEXT PRIMARY KEY", totalCents: "INTEGER NOT NULL", createdAt: "INTEGER NOT NULL" } },
+ *   ] });
+ *   b.db.from("orders").insert({ _id: "o1", totalCents: 4999, createdAt: Date.now() });
+ *
+ *   var out = b.db.exportCsv({
+ *     table:           "orders",
+ *     columns:         ["_id", "totalCents", "createdAt"],
+ *     bom:             true,
+ *     timestampFields: ["createdAt"],
+ *   });
+ *   typeof out.sha3_512;
+ *   // → "string"
+ *   out.rowCount >= 1;
+ *   // → true
+ */
+function exportCsv(opts) {
+  _requireInit();
+  if (!opts || typeof opts !== "object") {
+    throw new DbError("db/bad-export-opts", "exportCsv: opts object is required");
+  }
+  validateOpts.requireNonEmptyString(opts.table, "exportCsv: opts.table", DbError, "db/bad-export-table");
+  // Quote-validate the table identifier — refuses anything with embedded
+  // quotes, schema-qualified names valid via dot-separated parts.
+  safeSql.quoteIdentifier(opts.table);
+  var meta = tableMetadata[opts.table];
+  if (!meta) {
+    throw new DbError("db/unknown-table",
+      "exportCsv: '" + opts.table + "' is not a registered table");
+  }
+  var allCols = Object.keys(meta.columns || {});
+  var columns = Array.isArray(opts.columns) && opts.columns.length > 0
+    ? opts.columns.slice()
+    : allCols;
+  // Validate every column belongs to the table (refuses arbitrary
+  // operator strings becoming SQL identifiers).
+  for (var ci = 0; ci < columns.length; ci++) {
+    if (allCols.indexOf(columns[ci]) === -1) {
+      throw new DbError("db/bad-export-column",
+        "exportCsv: column '" + columns[ci] + "' is not in '" + opts.table + "'");
+    }
+  }
+  var bom = opts.bom === true;
+  var format = opts.format || "rfc4180";
+  if (format !== "rfc4180") {
+    throw new DbError("db/bad-export-format",
+      "exportCsv: format must be 'rfc4180', got " + JSON.stringify(format));
+  }
+  var timestampFields = Array.isArray(opts.timestampFields) ? opts.timestampFields : [];
+
+  // Build the query through Query so sealed columns auto-unseal.
+  var q = from(opts.table).select(columns);
+  if (opts.where && typeof opts.where === "object") {
+    q = q.where(opts.where);
+  }
+  var rows = q.all();
+
+  // Project rows into an array-of-arrays in the declared column order,
+  // casting timestamp fields from ms-int → ISO-8601 string.
+  var headerRow = columns.slice();
+  var bodyRows = new Array(rows.length);
+  for (var ri = 0; ri < rows.length; ri++) {
+    var src = rows[ri];
+    var out = new Array(columns.length);
+    for (var cj = 0; cj < columns.length; cj++) {
+      var col = columns[cj];
+      var v = src[col];
+      if (timestampFields.indexOf(col) !== -1 && typeof v === "number" && isFinite(v)) {
+        out[cj] = new Date(v).toISOString();
+      } else if (Buffer.isBuffer(v)) {
+        out[cj] = v.toString("base64");
+      } else if (v === null || v === undefined) {
+        out[cj] = "";
+      } else {
+        out[cj] = String(v);
+      }
+    }
+    bodyRows[ri] = out;
+  }
+
+  var csvBody = csv.stringify([headerRow].concat(bodyRows), { eol: "\r\n" });
+  var fullText = bom ? ("" + csvBody) : csvBody;
+  var bytes = Buffer.from(fullText, "utf8");
+
+  var sha3hex = sha3Hash(bytes).toString("hex");
+
+  var manifest = {
+    version:        1,
+    framework:      "blamejs",
+    table:          opts.table,
+    columns:        columns,
+    rowCount:       rows.length,
+    bom:            bom,
+    format:         format,
+    bytesWritten:   bytes.length,
+    sha3_512:       sha3hex,
+    exportedAt:     new Date().toISOString(),
+  };
+
+  var signature = null;
+  if (opts.signWith) {
+    if (typeof opts.signWith.sign !== "function" ||
+        typeof opts.signWith.getPublicKey !== "function" ||
+        typeof opts.signWith.getAlgorithm !== "function" ||
+        typeof opts.signWith.getPublicKeyFingerprint !== "function") {
+      throw new DbError("db/bad-signer",
+        "exportCsv: signWith must expose sign / getPublicKey / getAlgorithm / getPublicKeyFingerprint");
+    }
+    var sigBuf;
+    try { sigBuf = opts.signWith.sign(bytes); }
+    catch (e) {
+      throw new DbError("db/sign-failed",
+        "exportCsv: sign threw: " + ((e && e.message) || String(e)));
+    }
+    signature = {
+      algorithm:   opts.signWith.getAlgorithm(),
+      publicKey:   opts.signWith.getPublicKey(),
+      fingerprint: opts.signWith.getPublicKeyFingerprint(),
+      value:       sigBuf.toString("base64"),
+      signedAt:    new Date().toISOString(),
+    };
+    manifest.signature = signature;
+  }
+
+  audit.safeEmit({
+    action:   "db.export.csv",
+    outcome:  "success",
+    metadata: {
+      table:      opts.table,
+      rowCount:   rows.length,
+      sha3_512:   sha3hex,
+      bytes:      bytes.length,
+      signed:     !!signature,
+    },
+  });
+
+  return {
+    csv:          fullText,
+    bytes:        bytes,
+    bytesWritten: bytes.length,
+    sha3_512:     sha3hex,
+    signature:    signature,
+    manifest:     manifest,
+    rowCount:     rows.length,
+  };
+}
+
+/**
+ * @primitive b.db.close
+ * @signature b.db.close()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.init, b.db.flushToDisk
+ *
+ * Idempotent shutdown. Stops the periodic encrypt timer, fires a
+ * best-effort final audit checkpoint when the local node is the
+ * cluster leader, re-encrypts the live tmpfs database back to
+ * `<dataDir>/db.enc`, closes the SQLite handle (releasing the file
+ * lock on Windows), then unlinks the plaintext sidecar files in
+ * tmpfs. Safe to call multiple times — no-ops after the first
+ * successful close.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   b.db.close();
+ *   b.db.close();
+ *   // → undefined
+ */
 function close() {
   if (!initialized) return;
   if (encTimer) {
@@ -1262,6 +1890,336 @@ function _installAppendOnlyTriggers(database) {
   }
 }
 
+// Install row-level WORM (write-once-read-many) triggers on
+// operator-named tables. Per SEC Rule 17a-4(f), FINRA Rule 4511,
+// and 21 CFR Part 11 §11.10(c). Idempotent (CREATE TRIGGER IF
+// NOT EXISTS); registers the entry in _blamejs_worm_tables so the
+// boot-time assertion under WORM_POSTURES catches operators who
+// set the posture without declaring tables.
+function _installWormTriggers(database, tableName) {
+  safeSql.validateIdentifier(tableName);
+  runSql(database,
+    'CREATE TRIGGER IF NOT EXISTS "worm_no_delete_' + tableName + '" ' +
+    'BEFORE DELETE ON "' + tableName + '" ' +
+    'BEGIN ' +
+    "  SELECT RAISE(ABORT, '" + tableName + " is WORM (write-once-read-many) - DELETE prohibited'); " +
+    'END'
+  );
+  runSql(database,
+    'CREATE TRIGGER IF NOT EXISTS "worm_no_update_' + tableName + '" ' +
+    'BEFORE UPDATE ON "' + tableName + '" ' +
+    'BEGIN ' +
+    "  SELECT RAISE(ABORT, '" + tableName + " is WORM (write-once-read-many) - UPDATE prohibited'); " +
+    'END'
+  );
+}
+
+/**
+ * @primitive b.db.declareWorm
+ * @signature b.db.declareWorm(args)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance 21-cfr-11
+ * @related   b.db.declareRequireDualControl, b.db.eraseHard
+ *
+ * Install row-level WORM (write-once-read-many) triggers on
+ * operator-named business-record tables. Per SEC Rule 17a-4(f),
+ * FINRA Rule 4511, and 21 CFR Part 11 §11.10(c). UPDATE and DELETE
+ * are refused at the SQLite-trigger level, independent of the
+ * application's discipline. Each declared table is registered in
+ * `_blamejs_worm_tables`; under `sec-17a-4` / `finra-4511` /
+ * `fda-21cfr11` postures the boot-time assertion refuses to start
+ * if the registry is empty. Cluster mode (external-db) refuses the
+ * call — operators install WORM via `b.externalDb.migrate` instead.
+ *
+ * @opts
+ *   tables:  string[],  // required — non-empty array of operator table names
+ *   posture: string,    // optional — posture label recorded on each row
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "trade_blotter",
+ *       columns: { _id: "TEXT PRIMARY KEY", symbol: "TEXT NOT NULL", qty: "INTEGER NOT NULL" } },
+ *   ] });
+ *
+ *   var declared = b.db.declareWorm({
+ *     tables:  ["trade_blotter"],
+ *     posture: "sec-17a-4",
+ *   });
+ *   declared.tables;
+ *   // → ["trade_blotter"]
+ */
+function declareWorm(args) {
+  _requireInit();
+  args = args || {};
+  if (args.tables === undefined || args.tables === null) {
+    throw _wormErr("BAD_OPT",
+      "declareWorm: args.tables is required (array of table names)");
+  }
+  validateOpts.optionalNonEmptyStringArray(args.tables,
+    "declareWorm: args.tables", WormViolationError, "BAD_OPT");
+  if (args.tables.length === 0) {
+    throw _wormErr("BAD_OPT", "declareWorm: args.tables must be non-empty");
+  }
+  for (var i = 0; i < args.tables.length; i++) {
+    safeSql.validateIdentifier(args.tables[i]);
+  }
+  if (args.posture !== undefined && args.posture !== null &&
+      (typeof args.posture !== "string" || args.posture.length === 0)) {
+    throw _wormErr("BAD_OPT", "declareWorm: args.posture must be a non-empty string or null");
+  }
+  if (cluster.isClusterMode()) {
+    throw _wormErr("UNSUPPORTED",
+      "declareWorm: cluster mode (external-db) installs WORM via b.externalDb.migrate; " +
+      "the SQLite trigger primitive is single-node only");
+  }
+  var nowMs = Date.now();
+  var ins = database.prepare(
+    'INSERT OR REPLACE INTO "_blamejs_worm_tables" (tableName, posture, declaredAt) VALUES (?, ?, ?)'
+  );
+  for (var j = 0; j < args.tables.length; j++) {
+    var t = args.tables[j];
+    if (t === "audit_log" || t === "consent_log" || t === "audit_checkpoints") {
+      throw _wormErr("RESERVED",
+        "declareWorm: '" + t + "' is a framework-managed append-only table; " +
+        "use audit-tools.purge for sanctioned deletions");
+    }
+    _installWormTriggers(database, t);
+    ins.run(t, args.posture || null, nowMs);
+    audit.safeEmit({
+      action:   "db.worm.declared",
+      outcome:  "success",
+      metadata: { tableName: t, posture: args.posture || null, declaredAt: nowMs },
+    });
+  }
+  return { tables: args.tables.slice(), posture: args.posture || null };
+}
+
+function _assertWormUnderPosture() {
+  var posture;
+  try { posture = compliance().current(); } catch (_e) { posture = null; }
+  if (!posture || WORM_POSTURES.indexOf(posture) === -1) return;
+  if (cluster.isClusterMode()) return;
+  var rows;
+  try {
+    rows = database.prepare(
+      'SELECT tableName FROM "_blamejs_worm_tables"'
+    ).all();
+  } catch (_e) { rows = []; }
+  if (!rows || rows.length === 0) {
+    throw _wormErr("POSTURE_VIOLATION",
+      "FATAL: compliance posture '" + posture + "' requires row-level WORM " +
+      "on business-record tables (per SEC 17a-4(f) / FINRA 4511 / 21 CFR Part 11). " +
+      "Call b.db.declareWorm({ tables: [...], posture: '" + posture + "' }) at boot.");
+  }
+}
+
+/**
+ * @primitive b.db.declareRequireDualControl
+ * @signature b.db.declareRequireDualControl(args)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.db.declareWorm, b.db.eraseHard
+ *
+ * Gate destructive operations (`b.db.eraseHard`, retention sweeps,
+ * audit purges) on operator-named tables behind an m-of-n dual-
+ * control grant. Each declared table is registered in
+ * `_blamejs_dual_control_gates` with its quorum tuple `(m, n)`; the
+ * gate consult on `eraseHard` refuses execution unless the caller
+ * passes `opts.dualControlGrant` returned by `b.dualControl.consume()`.
+ *
+ * @opts
+ *   tables:  string[],  // required — non-empty array of table names
+ *   m:       number,    // default 2 — minimum approvals
+ *   n:       number,    // default max(2, m) — total approver pool
+ *   posture: string,    // optional — posture label recorded with the gate
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "patient_records",
+ *       columns: { _id: "TEXT PRIMARY KEY", chartJson: "TEXT" } },
+ *   ] });
+ *
+ *   var gate = b.db.declareRequireDualControl({
+ *     tables:  ["patient_records"],
+ *     m:       2,
+ *     n:       3,
+ *     posture: "hipaa",
+ *   });
+ *   gate.m;
+ *   // → 2
+ */
+function declareRequireDualControl(args) {
+  _requireInit();
+  args = args || {};
+  validateOpts.optionalNonEmptyStringArray(args.tables,
+    "declareRequireDualControl: args.tables", DbError, "db/dual-control-bad-tables");
+  if (!Array.isArray(args.tables) || args.tables.length === 0) {
+    throw new DbError("db/dual-control-bad-tables",
+      "declareRequireDualControl: args.tables must be a non-empty array of table names");
+  }
+  for (var i = 0; i < args.tables.length; i++) {
+    safeSql.validateIdentifier(args.tables[i]);
+  }
+  var m = args.m === undefined ? 2 : args.m;
+  var n = args.n === undefined ? Math.max(2, m) : args.n;
+  if (typeof m !== "number" || !isFinite(m) || m < 2 || Math.floor(m) !== m) {
+    throw new DbError("db/dual-control-bad-quorum",
+      "declareRequireDualControl: m must be an integer >= 2");
+  }
+  if (typeof n !== "number" || !isFinite(n) || n < m || Math.floor(n) !== n) {
+    throw new DbError("db/dual-control-bad-quorum",
+      "declareRequireDualControl: n must be an integer >= m");
+  }
+  if (args.posture !== undefined && args.posture !== null &&
+      (typeof args.posture !== "string" || args.posture.length === 0)) {
+    throw new DbError("db/dual-control-bad-posture",
+      "declareRequireDualControl: args.posture must be a non-empty string or null");
+  }
+  var nowMs = Date.now();
+  var ins = database.prepare(
+    'INSERT OR REPLACE INTO "_blamejs_dual_control_gates" ' +
+    '(tableName, posture, m, n, declaredAt) VALUES (?, ?, ?, ?, ?)'
+  );
+  for (var j = 0; j < args.tables.length; j++) {
+    ins.run(args.tables[j], args.posture || null, m, n, nowMs);
+    audit.safeEmit({
+      action:   "db.dual_control.declared",
+      outcome:  "success",
+      metadata: { tableName: args.tables[j], posture: args.posture || null, m: m, n: n },
+    });
+  }
+  return { tables: args.tables.slice(), m: m, n: n, posture: args.posture || null };
+}
+
+function _checkDualControlGate(tableName) {
+  if (!initialized) return null;
+  if (cluster.isClusterMode()) return null;
+  var row;
+  try {
+    row = database.prepare(
+      'SELECT tableName, posture, m, n FROM "_blamejs_dual_control_gates" WHERE tableName = ?'
+    ).get(tableName);
+  } catch (_e) { return null; }
+  return row || null;
+}
+
+/**
+ * @primitive b.db.eraseHard
+ * @signature b.db.eraseHard(tableName, rowId, opts)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance gdpr, hipaa
+ * @related   b.db.declareRequireDualControl, b.subject.erase, b.legalHold
+ *
+ * Crypto-erase one row plus a `REINDEX` on the table so freed B-tree
+ * pages can't reconstruct the deleted row's index entries. Closes
+ * the F-RTBF B-tree-residual class on a per-row basis. Consults the
+ * legal-hold registry (refuses on `subjectId` held) and the dual-
+ * control gate registry (refuses unless `opts.dualControlGrant` is a
+ * consumed grant); emits a `db.erase_hard` audit row on success or a
+ * `db.erase_hard.denied` audit row on either gate refusal.
+ *
+ * @opts
+ *   reason:            string,   // required — non-empty rationale recorded in audit
+ *   subjectId:         string,   // optional — consults legal-hold registry
+ *   dualControlGrant:  object,   // required when the table is gated; from b.dualControl.consume()
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "stale_pii",
+ *       columns: { _id: "TEXT PRIMARY KEY", ssn: "TEXT" },
+ *       sealedFields: ["ssn"] },
+ *   ] });
+ *   b.db.from("stale_pii").insert({ _id: "row1", ssn: "123-45-6789" });
+ *
+ *   var result = b.db.eraseHard("stale_pii", "row1", {
+ *     reason: "subject erasure under GDPR Art 17",
+ *   });
+ *   result.rowsDeleted;
+ *   // → 1
+ */
+function eraseHard(tableName, rowId, opts) {
+  _requireInit();
+  opts = opts || {};
+  safeSql.validateIdentifier(tableName);
+  validateOpts.requireNonEmptyString(rowId, "eraseHard: rowId", DbError, "db/erase-hard-bad-row-id");
+  validateOpts.requireNonEmptyString(opts.reason, "eraseHard: opts.reason", DbError, "db/erase-hard-no-reason");
+  if (opts.subjectId) {
+    var legalHoldMod;
+    try { legalHoldMod = require("./legal-hold"); }                                              // allow:inline-require — circular-load defense (legal-hold transitively requires db)
+    catch (_e) { legalHoldMod = null; }
+    var holds = legalHoldMod && legalHoldMod._getSingleton();
+    if (holds && holds.isHeld(opts.subjectId)) {
+      audit.safeEmit({
+        action:  "db.erase_hard.denied",
+        outcome: "denied",
+        metadata: { tableName: tableName, rowId: rowId,
+          reason: "legal-hold-active", subjectId: opts.subjectId },
+      });
+      throw new DbError("db/erase-hard-legal-hold",
+        "eraseHard: subject '" + opts.subjectId + "' is on legal hold; " +
+        "release the hold before erasure");
+    }
+  }
+  var gate = _checkDualControlGate(tableName);
+  if (gate && !opts.dualControlGrant) {
+    audit.safeEmit({
+      action:  "db.erase_hard.denied",
+      outcome: "denied",
+      metadata: { tableName: tableName, rowId: rowId,
+        reason: "dual-control-required", gate: gate },
+    });
+    throw new DbError("db/erase-hard-dual-control-required",
+      "eraseHard: '" + tableName + "' is gated by dual-control (m=" +
+      gate.m + ", n=" + gate.n + "). Pass opts.dualControlGrant from " +
+      "b.dualControl.consume() to proceed.");
+  }
+  if (gate && opts.dualControlGrant) {
+    var grant = opts.dualControlGrant;
+    if (!grant || grant.ready !== true) {
+      throw new DbError("db/erase-hard-grant-not-ready",
+        "eraseHard: opts.dualControlGrant.ready must be true (consumed grant)");
+    }
+  }
+  var t0 = Date.now();
+  var deleted = 0;
+  transaction(function () {
+    var row = database.prepare(
+      'SELECT * FROM "' + tableName + '" WHERE _id = ?'
+    ).get(rowId);
+    if (row) {
+      try { cryptoField.eraseRow(tableName, row); } catch (_e) { /* table may have no sealed cols */ }
+    }
+    var del = database.prepare(
+      'DELETE FROM "' + tableName + '" WHERE _id = ?'
+    );
+    var result = del.run(rowId);
+    deleted = (result && result.changes) || 0;
+    // REINDEX rebuilds every index on the table from scratch,
+    // dropping the B-tree pages that held the deleted row's index
+    // entries.
+    runSql(database, 'REINDEX "' + tableName + '"');
+  });
+  audit.safeEmit({
+    action:   "db.erase_hard",
+    outcome:  "success",
+    reason:   opts.reason,
+    metadata: {
+      tableName:    tableName,
+      rowId:        rowId,
+      rowsDeleted:  deleted,
+      durationMs:   Date.now() - t0,
+      subjectId:    opts.subjectId || null,
+      dualControlConsumed: !!(gate && opts.dualControlGrant),
+    },
+  });
+  return { rowsDeleted: deleted, durationMs: Date.now() - t0 };
+}
+
 // Read the audit.tip sidecar file in dataDir and compare to the current
 // audit_log MAX(monotonicCounter). Refuse boot on rollback (current < tip).
 function _checkRollback(dataDirPath) {
@@ -1390,13 +2348,32 @@ function _resetForTest() {
 }
 
 
-// F-RTBF-1 — operator-callable vacuum. Run after a large-scale erase
-// (b.subject.erase batch, b.retention sweep) so freed pages don't
-// linger with sealed-column ciphertext readable from a forensic
-// disk image.
-//
-//   await b.db.vacuumAfterErase({ mode: "incremental", pages: 1000 });
-//   await b.db.vacuumAfterErase({ mode: "full" });
+/**
+ * @primitive b.db.vacuumAfterErase
+ * @signature b.db.vacuumAfterErase(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance gdpr, hipaa
+ * @related   b.db.eraseHard, b.subject.erase
+ *
+ * Run after a large-scale erase (`b.subject.erase` batch,
+ * `b.retention` sweep) so SQLite's freed pages don't linger with
+ * sealed-column ciphertext that a forensic disk image could
+ * recover. `incremental` mode runs `PRAGMA incremental_vacuum(N)`
+ * (default 1000 pages) — fast, doesn't rewrite the whole file.
+ * `full` mode runs `VACUUM` — rewrites every page; the database is
+ * locked for the duration.
+ *
+ * @opts
+ *   mode:  "incremental"|"full",  // default "incremental"
+ *   pages: number,                // incremental only; default 1000
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   b.db.vacuumAfterErase({ mode: "incremental", pages: 500 });
+ *   // → undefined
+ */
 function vacuumAfterErase(opts) {
   opts = opts || {};
   var mode = opts.mode || "incremental";
@@ -1431,12 +2408,364 @@ function vacuumAfterErase(opts) {
   } catch (_e) { /* audit best-effort */ }
 }
 
+// F-POSTURE-1 — cascade-installed posture name. b.compliance.set(p)
+// calls applyPosture(p) which records the posture; the downstream
+// cryptoField.eraseRow path consults this via getActivePosture() to
+// auto-vacuum under postures whose POSTURE_DEFAULTS sets
+// requireVacuumAfterErase: true.
+var _activePosture = null;
+
+/**
+ * @primitive b.db.applyPosture
+ * @signature b.db.applyPosture(posture)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.compliance.set, b.db.getActivePosture
+ *
+ * Record the active compliance posture for the database subsystem.
+ * Called by `b.compliance.set(p)` during posture cascade so the
+ * downstream `cryptoField.eraseRow` path can consult
+ * `getActivePosture()` and auto-vacuum under postures whose defaults
+ * set `requireVacuumAfterErase: true`. Returns `null` for empty
+ * input; otherwise `{ posture, dbInitialized }`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var result = b.db.applyPosture("hipaa");
+ *   result.posture;
+ *   // → "hipaa"
+ */
+function applyPosture(posture) {
+  if (typeof posture !== "string" || posture.length === 0) return null;
+  _activePosture = posture;
+  return { posture: posture, dbInitialized: !!database };
+}
+/**
+ * @primitive b.db.getActivePosture
+ * @signature b.db.getActivePosture()
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.db.applyPosture, b.compliance.set
+ *
+ * Read the posture last installed via `applyPosture`. Used by
+ * downstream subsystems (`cryptoField.eraseRow`, retention sweeps)
+ * to branch on posture-driven defaults. Returns `null` before any
+ * posture has been set.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.db.applyPosture("pci-dss");
+ *   b.db.getActivePosture();
+ *   // → "pci-dss"
+ */
+function getActivePosture() { return _activePosture; }
+
+/**
+ * @primitive b.db.runSql
+ * @signature b.db.runSql(sql)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.prepare, b.db.transaction
+ *
+ * Execute a raw SQL string with no result-set return — DDL
+ * (`CREATE TABLE` / `DROP TABLE` / `ALTER` / etc.), DML where the
+ * caller doesn't need rows back, and `BEGIN` / `COMMIT` / `ROLLBACK`
+ * outside of `transaction()`. Slow-query observability buckets fire
+ * on every call. DDL statements emit a `db.ddl.executed` audit row
+ * with the leading keyword extracted so a forensic review can
+ * reconstruct schema evolution from the audit chain alone.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   b.db.runSql("CREATE TABLE IF NOT EXISTS scratch (id INTEGER PRIMARY KEY)");
+ *   // → undefined
+ */
+
+/**
+ * @primitive b.db.flushToDisk
+ * @signature b.db.flushToDisk()
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.db.close, b.db.init
+ *
+ * Force the live tmpfs SQLite to be re-encrypted to
+ * `<dataDir>/db.enc` immediately. The framework already does this
+ * every five minutes and at clean shutdown; operators running a
+ * backup workflow call `flushToDisk()` first so the snapshot source
+ * reflects the most recent committed state. No-op in `atRest:
+ * "plain"` mode (no `db.enc` exists).
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", atRest: "encrypted", schema: [] });
+ *   b.db.flushToDisk();
+ *   // → undefined
+ */
+
+/**
+ * @primitive b.db.getStreamLimit
+ * @signature b.db.getStreamLimit()
+ * @since     0.7.67
+ * @status    stable
+ * @related   b.db.stream, b.db.init
+ *
+ * Read the module-level `streamLimit` ceiling (default
+ * `1_000_000`). Per-call `opts.streamLimit` on `db.stream` overrides
+ * this; `db.init({ streamLimit })` raises or lowers it for the
+ * process.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   b.db.getStreamLimit() > 0;
+ *   // → true
+ */
+
+/**
+ * @primitive b.db.integrityCheck
+ * @signature b.db.integrityCheck()
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.db.integrityMonitor, b.db.init
+ *
+ * Run `PRAGMA integrity_check` on the live database. Returns the
+ * string `"ok"` on a clean check or an array of corruption
+ * descriptions otherwise. Operators wire this into a `/healthz`
+ * handler or a periodic monitor.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   b.db.integrityCheck();
+ *   // → "ok"
+ */
+
+/**
+ * @primitive b.db.integrityMonitor
+ * @signature b.db.integrityMonitor(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.db.integrityCheck
+ *
+ * Periodic `PRAGMA integrity_check` runner. Returns a handle with
+ * `.stop()` for graceful shutdown. Emits `system.db.integrity_ok` /
+ * `system.db.integrity_corrupt` audit rows and matching
+ * observability counters on every check. Operators pass
+ * `onCorruption` to receive the issues array on detection (alerts,
+ * page outs, kill-switches).
+ *
+ * @opts
+ *   intervalMs:   number,        // default C.TIME.hours(24)
+ *   audit:        boolean,       // default true; emit audit rows on every check
+ *   onCorruption: Function,      // (issues) => void; fires on corruption
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   var mon = b.db.integrityMonitor({
+ *     intervalMs:   60000,
+ *     onCorruption: function (_issues) { },
+ *   });
+ *   mon.stop();
+ */
+
+/**
+ * @primitive b.db.purgeAuditChain
+ * @signature b.db.purgeAuditChain(args)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.audit, b.db.eraseHard
+ *
+ * Narrow-purpose `DELETE` against `audit_log` + `audit_checkpoints`
+ * for use by `audit-tools.purge`. Drops the BEFORE-DELETE append-
+ * only triggers inside a transaction, executes the deletion against
+ * rows with `monotonicCounter <= lastPurgedCounter`, then re-
+ * installs the triggers so the append-only invariant resumes.
+ * Cluster mode delegates to `cluster-storage` (no triggers in
+ * external-db). The caller is responsible for verifying purge
+ * legitimacy via `audit-tools.verifyBundle` before invoking.
+ *
+ * @opts
+ *   lastPurgedCounter: number,   // required — non-negative; rows at or below this counter are deleted
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [] });
+ *   var result = await b.db.purgeAuditChain({ lastPurgedCounter: 0 });
+ *   typeof result.rowsDeleted;
+ *   // → "number"
+ */
+
+/**
+ * @primitive b.db.getMode
+ * @signature b.db.getMode()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.init, b.db.getDbPath
+ *
+ * Diagnostic accessor — returns the active at-rest posture
+ * (`"encrypted"` or `"plain"`) chosen at `init` time.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", atRest: "plain", schema: [] });
+ *   b.db.getMode();
+ *   // → "plain"
+ */
+
+/**
+ * @primitive b.db.getDbPath
+ * @signature b.db.getDbPath()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.db.getMode
+ *
+ * Diagnostic accessor — returns the absolute path of the live
+ * SQLite file. In encrypted mode this is a tmpfs path
+ * (e.g. `/dev/shm/blamejs-<token>.db`); in plain mode it's
+ * `<dataDir>/blamejs.db`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", atRest: "plain", schema: [] });
+ *   typeof b.db.getDbPath();
+ *   // → "string"
+ */
+
+/**
+ * @primitive b.db.getDataResidency
+ * @signature b.db.getDataResidency()
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.db.init
+ *
+ * Read the operator's declared data-residency configuration (passed
+ * via `db.init({ dataResidency })`). Storage / mail / log
+ * destinations consult this to refuse cross-region writes.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({
+ *     dataDir:       "/tmp/data",
+ *     dataResidency: { region: "eu-west-1" },
+ *     schema:        [],
+ *   });
+ *   b.db.getDataResidency().region;
+ *   // → "eu-west-1"
+ */
+
+/**
+ * @primitive b.db.getTableMetadata
+ * @signature b.db.getTableMetadata(nameOrOpts)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.db.from, b.db.init
+ *
+ * Reflective metadata for one or every registered table — primary-
+ * key columns, foreign keys, sealed-field list, derived-hash
+ * declarations, subject mapping, personal-data categories. Returns
+ * a deep-copied snapshot; mutations don't affect framework state.
+ * Two-arg form supports format dispatch:
+ * `getTableMetadata({ table, format: "json-schema-2020-12" })`
+ * emits a JSON Schema 2020-12 document with sealed columns
+ * annotated `x-blamejs-sealed: true` and derived-hash columns
+ * annotated `x-blamejs-derived-from: "<source>"`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/tmp/data", schema: [
+ *     { name: "users",
+ *       columns: { _id: "TEXT PRIMARY KEY", email: "TEXT" },
+ *       sealedFields: ["email"] },
+ *   ] });
+ *
+ *   var meta = b.db.getTableMetadata("users");
+ *   meta.sealedFields;
+ *   // → ["email"]
+ *
+ *   var schema = b.db.getTableMetadata({
+ *     table:  "users",
+ *     format: "json-schema-2020-12",
+ *   });
+ *   schema.properties.email["x-blamejs-sealed"];
+ *   // → true
+ */
+
+/**
+ * @primitive b.db.declareView
+ * @signature b.db.declareView(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.db.declareRowPolicy, b.externalDb.init
+ *
+ * Declarative `CREATE VIEW` + `GRANT` migration spec for a
+ * Postgres-backed `b.externalDb` deployment. Returns a migration-
+ * shape object consumed by `b.externalDb.migrate`. Postgres-only;
+ * fail-fast at apply time on other dialects.
+ *
+ * @opts
+ *   name:    string,    // required — view identifier
+ *   select:  string,    // required — view body
+ *   grants:  object,    // optional — { role: ["SELECT", ...] }
+ *   schema:  string,    // optional — schema-qualified namespace
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var spec = b.db.declareView({
+ *     name:   "active_users",
+ *     select: "SELECT id, email FROM users WHERE deleted_at IS NULL",
+ *     grants: { app_reader: ["SELECT"] },
+ *   });
+ *   spec.kind;
+ *   // → "view"
+ */
+
+/**
+ * @primitive b.db.declareRowPolicy
+ * @signature b.db.declareRowPolicy(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.db.declareView, b.externalDb.init
+ *
+ * Declarative Postgres ROW LEVEL SECURITY migration spec. Pairs
+ * with `b.externalDb.transaction({ sessionGucs })` for the per-
+ * request `SET LOCAL` plumbing that scopes the policy. Returns a
+ * migration-shape object consumed by `b.externalDb.migrate`.
+ * Postgres-only; fail-fast on other dialects.
+ *
+ * @opts
+ *   table:    string,    // required — target table
+ *   name:     string,    // required — policy identifier
+ *   command:  string,    // optional — "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL"
+ *   using:    string,    // optional — USING expression
+ *   withCheck:string,    // optional — WITH CHECK expression
+ *   roles:    string[],  // optional — TO role list
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var spec = b.db.declareRowPolicy({
+ *     table:   "orders",
+ *     name:    "tenant_isolation",
+ *     command: "ALL",
+ *     using:   "tenant_id = current_setting('app.tenant_id')::uuid",
+ *     roles:   ["app_user"],
+ *   });
+ *   spec.kind;
+ *   // → "row-policy"
+ */
+
 module.exports = {
   init:                init,
+  applyPosture:        applyPosture,
+  getActivePosture:    getActivePosture,
   vacuumAfterErase:    vacuumAfterErase,
   from:                from,
   prepare:             prepare,
   stream:              stream,
+  // D-M5 — runtime read-only accessor so Query.stream picks up the
+  // configured ceiling without re-importing module state.
+  getStreamLimit:      function () { return streamLimit; },
   runSql:              execRaw,
   // SQLite multi-statement helper alias matching the node:sqlite
   // module's shape. Operator migration / seeder files that received
@@ -1582,11 +2911,37 @@ module.exports = {
   // Reflective metadata: PK columns, FK relationships, sealed/derived fields,
   // subject mapping. Useful for tooling, RoPA generation, and admin dashboards.
   // Returns a deep-copied snapshot; mutations don't affect framework state.
-  getTableMetadata:    function (name) {
-    if (!name) return structuredClone(tableMetadata);
-    var m = tableMetadata[name];
-    return m ? structuredClone(m) : null;
+  //
+  // Two-arg form supports format dispatch:
+  //   getTableMetadata({ table: "orders", format: "json-schema-2020-12" })
+  // emits a JSON Schema 2020-12 representation of the table — every
+  // column types out per its DDL, sealed fields gain an "x-blamejs-
+  // sealed" annotation, derived-hash columns gain "x-blamejs-derived-
+  // from", and the schema's $schema URI points at JSON Schema 2020-12.
+  getTableMetadata:    function (nameOrOpts) {
+    if (!nameOrOpts) return structuredClone(tableMetadata);
+    if (typeof nameOrOpts === "string") {
+      var m = tableMetadata[nameOrOpts];
+      return m ? structuredClone(m) : null;
+    }
+    if (typeof nameOrOpts !== "object") return null;
+    var tableName = nameOrOpts.table;
+    if (typeof tableName !== "string" || tableName.length === 0) {
+      throw new DbError("db/bad-table-arg",
+        "getTableMetadata: opts.table must be a non-empty string");
+    }
+    var meta = tableMetadata[tableName];
+    if (!meta) return null;
+    var format = nameOrOpts.format || "blamejs";
+    if (format === "blamejs") return structuredClone(meta);
+    if (format === "json-schema-2020-12") {
+      return _tableToJsonSchema2020(tableName, meta);
+    }
+    throw new DbError("db/bad-format",
+      "getTableMetadata: format must be 'blamejs' or 'json-schema-2020-12', got " +
+      JSON.stringify(format));
   },
+  exportCsv:           exportCsv,
   // declareView — declarative CREATE VIEW + GRANT migration spec for an
   // externalDb backend. Returns a migration-shape object for use with
   // b.externalDb.migrate. Postgres-only; fail-fast at apply time on other
@@ -1597,6 +2952,22 @@ module.exports = {
   // per-request `SET LOCAL` plumbing. Postgres-only; fail-fast on other
   // dialects. See lib/db-declare-row-policy.js.
   declareRowPolicy:    dbDeclareRowPolicy.declareRowPolicy,
+  // declareWorm — install row-level WORM (write-once-read-many) on
+  // operator-named business-record tables. Per SEC Rule 17a-4(f),
+  // FINRA Rule 4511, 21 CFR Part 11 §11.10(c). Boot-time assertion
+  // refuses to continue under sec-17a-4 / finra-4511 / fda-21cfr11
+  // postures unless at least one table is declared.
+  declareWorm:         declareWorm,
+  // declareRequireDualControl — gate destructive ops (erase / purge /
+  // physical delete) on operator-named tables behind an m-of-n
+  // dual-control grant from b.dualControl.consume(). Caller passes
+  // the consumed grant via opts.dualControlGrant on b.db.eraseHard.
+  declareRequireDualControl: declareRequireDualControl,
+  // eraseHard — full crypto-erase + REINDEX for one row, with
+  // legal-hold + dual-control gate consult. Closes the F-RTBF
+  // B-tree residual class on a per-row basis.
+  eraseHard:           eraseHard,
+  _assertWormUnderPosture: _assertWormUnderPosture,
   // Internal accessors used by audit / subject / consent modules.
   // Not part of the public contract — apps should not depend on them.
   _getSubjectTables:   function () { return subjectTables.slice(); },