@blamejs/core 0.6.69 → 0.7.0

package/lib/db.js

@@ -52,20 +52,45 @@ var consent = require("./consent");
 var C = require("./constants");
 var { generateToken, generateBytes, encryptPacked, decryptPacked } = require("./crypto");
 var cryptoField = require("./crypto-field");
+var dbDeclareRowPolicy = require("./db-declare-row-policy");
+var dbDeclareView = require("./db-declare-view");
 var { Query } = require("./db-query");
 var dbSchema = require("./db-schema");
+var { defineClass } = require("./framework-error");
 var { boot } = require("./log");
 var lazyRequire = require("./lazy-require");
+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 vault = require("./vault");
 
+var DbError = defineClass("DbError", { alwaysPermanent: true });
+var _dbErr = DbError.factory;
+
 // Lazy: cluster-storage's _localDb pulls db back in, so eager require
 // would deadlock the load order. cluster-storage is only used on the
 // purge-audit-chain external-db path, which always runs after init.
 var clusterStorage = lazyRequire(function () { return require("./cluster-storage"); });
 
+// Lazy refs for the test-reset cascade. Each module requires db.js
+// directly or transitively (audit/consent/subject/session/etc. all
+// own a sealed-column slice that depends on db.from), so eager
+// requires here would cycle on load. The cascade runs only when a
+// test explicitly resets db, so paying the resolve cost lazily is
+// the correct tradeoff.
+var _resetAudit       = lazyRequire(function () { return require("./audit"); });
+var _resetConsent     = lazyRequire(function () { return require("./consent"); });
+var _resetSubject     = lazyRequire(function () { return require("./subject"); });
+var _resetSession     = lazyRequire(function () { return require("./session"); });
+var _resetStorage     = lazyRequire(function () { return require("./storage"); });
+var _resetAuditSign   = lazyRequire(function () { return require("./audit-sign"); });
+var _resetQueue       = lazyRequire(function () { return require("./queue"); });
+var _resetBreakGlass  = lazyRequire(function () { return require("./break-glass"); });
+var _resetLogStream   = lazyRequire(function () { return require("./log-stream"); });
+var _resetRedact      = lazyRequire(function () { return require("./redact"); });
+var _resetExternalDb  = lazyRequire(function () { return require("./external-db"); });
+
 var AUDIT_TIP_SCHEMA = {
   type: "object",
   required: ["atMonotonicCounter"],
@@ -82,7 +107,7 @@ var runSql = dbSchema.runSql;
 var database  = null;       // the SQLite handle
 var dbPath    = null;       // plaintext DB file path (tmpfs in encrypted mode, dataDir/db in plain mode)
 var encPath   = null;       // encrypted-at-rest path (null in plain mode)
-var encKey    = null;       // 32-byte DB encryption key (null in plain mode)
+var encKey    = null;       // DB encryption key buffer (null in plain mode)
 var encTimer  = null;       // periodic encrypt interval handle
 var atRest    = null;       // 'encrypted' or 'plain'
 var dataDir   = null;
@@ -532,13 +557,13 @@ function loadOrCreateDbKey(dataDirPath) {
     var sealed = atomicFile.readSync(keyPath, { encoding: "utf8" }).trim();
     var b64 = vault.unseal(sealed);
     if (!b64) {
-      log.error("FATAL: db.key.enc unseal returned empty — vault may not be initialized or key file corrupted");
-      process.exit(1);
+      throw _dbErr("db/key-unseal-empty",
+        "FATAL: db.key.enc unseal returned empty — vault may not be initialized or key file corrupted");
     }
     return Buffer.from(b64, "base64");
   }
   // First run — generate, seal, persist (atomic)
-  var raw = generateBytes(32);
+  var raw = generateBytes(C.BYTES.bytes(32));
   var sealedKey = vault.seal(raw.toString("base64"));
   atomicFile.writeSync(keyPath, sealedKey, { fileMode: 0o600 });
   log("generated DB encryption key at " + keyPath);
@@ -601,15 +626,17 @@ function cleanStaleTmpDbs(tmpDir) {
 async function init(opts) {
   if (initialized) return;
   if (!opts || !opts.dataDir) {
-    throw new Error("db.init({ dataDir }) is required");
+    throw new DbError("db/bad-init", "db.init({ dataDir }) is required");
   }
   if (!Array.isArray(opts.schema)) {
-    throw new Error("db.init({ schema }) must be an array of table definitions");
+    throw new DbError("db/bad-init",
+      "db.init({ schema }) must be an array of table definitions");
   }
 
   atRest = (opts.atRest || "encrypted").toLowerCase();
   if (atRest !== "encrypted" && atRest !== "plain") {
-    throw new Error("db.init: atRest must be 'encrypted' or 'plain', got: " + opts.atRest);
+    throw new DbError("db/bad-at-rest",
+      "db.init: atRest must be 'encrypted' or 'plain', got: " + opts.atRest);
   }
   dataDir = opts.dataDir;
   if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
@@ -617,14 +644,14 @@ async function init(opts) {
   if (atRest === "encrypted") {
     var tmpDir = resolveTmpDir(opts.tmpDir);
     if (!tmpDir) {
-      log.error("FATAL: atRest: 'encrypted' (default) requires tmpfs but none was found.");
-      log.error("  Provide opts.tmpDir or set BLAMEJS_TMPDIR, or pass atRest: 'plain' (with warning).");
-      process.exit(1);
+      throw _dbErr("db/no-tmpfs",
+        "FATAL: atRest: 'encrypted' (default) requires tmpfs but none was found. " +
+        "Provide opts.tmpDir or set BLAMEJS_TMPDIR, or pass atRest: 'plain' (with warning).");
     }
     if (!fs.existsSync(tmpDir)) fs.mkdirSync(tmpDir, { recursive: true });
 
     encPath = path.join(dataDir, "db.enc");
-    dbPath  = path.join(tmpDir, "blamejs-" + generateToken(16) + ".db");
+    dbPath  = path.join(tmpDir, "blamejs-" + generateToken(C.BYTES.bytes(16)) + ".db");
     encKey  = loadOrCreateDbKey(dataDir);
 
     cleanStaleTmpDbs(tmpDir);
@@ -657,11 +684,10 @@ async function init(opts) {
   // Refuse app schema entries that collide with framework-reserved names
   for (var ri = 0; ri < opts.schema.length; ri++) {
     if (RESERVED_TABLE_NAMES.has(opts.schema[ri].name)) {
-      throw new Error(
+      throw new DbError("db/reserved-table-name",
         "table name '" + opts.schema[ri].name + "' is reserved by the framework. " +
         "Pick a different name (the framework provisions audit_log, consent_log, " +
-        "and _blamejs_* tables automatically)."
-      );
+        "and _blamejs_* tables automatically).");
     }
   }
 
@@ -743,25 +769,24 @@ async function init(opts) {
   // detects-and-fails.
   var auditResult = await audit.verify();
   if (!auditResult.ok) {
-    log.error("FATAL: audit_log chain integrity broken at row " + auditResult.breakAt + " (" + auditResult.reason + ")");
-    log.error("  break row _id: " + auditResult.breakRowId);
-    log.error("  expected: " + auditResult.expected);
-    log.error("  actual:   " + auditResult.actual);
-    log.error("Refusing to boot. Compliance requires that any tamper-detection signal halt service.");
-    log.error("Recovery is manual: restore from backup, or rebuild the audit chain from a verified earlier snapshot.");
-    // Fire the breach event BEFORE exit so operator listeners get one
-    // last chance at sync I/O (file flag, console alert) before the
-    // process is gone.
+    // 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 });
-    process.exit(1);
+    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) {
-    log.error("FATAL: consent_log chain integrity broken at row " + consentResult.breakAt + " (" + consentResult.reason + ")");
-    log.error("  break row _id: " + consentResult.breakRowId);
-    log.error("Refusing to boot.");
     events.emit(events.EVENTS.AUDIT_CHAIN_BREAK, { table: "consent_log", result: consentResult });
-    process.exit(1);
+    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)");
 
@@ -799,13 +824,12 @@ async function init(opts) {
   // forgery attempt + key-rotation gone wrong). Refuse to boot on failure.
   var ckptResult = await audit.verifyCheckpoints();
   if (!ckptResult.ok) {
-    log.error("FATAL: audit checkpoint verification failed at row " +
-      ckptResult.breakAt + " (" + ckptResult.reason + ")");
-    log.error("  checkpoint _id: " + ckptResult.checkpointId);
-    log.error("Refusing to boot. Either the audit-signing key was rotated " +
-      "without retaining the prior pubkey, or a forged checkpoint was inserted.");
     events.emit(events.EVENTS.AUDIT_CHECKPOINT_BREAK, { result: ckptResult });
-    process.exit(1);
+    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)");
 
@@ -915,7 +939,9 @@ function execRaw(sql) {
 
 function transaction(fn) {
   _requireInit();
-  if (typeof fn !== "function") throw new Error("transaction requires a function");
+  if (typeof fn !== "function") {
+    throw new DbError("db/bad-transaction-fn", "transaction requires a function");
+  }
   runSql(database, "BEGIN");
   try {
     var result = fn(module.exports);
@@ -965,7 +991,8 @@ function close() {
 
 function _requireInit() {
   if (!initialized) {
-    throw new Error("db.init() must be awaited before using db API");
+    throw new DbError("db/not-initialized",
+      "db.init() must be awaited before using db API");
   }
 }
 
@@ -1018,25 +1045,25 @@ function _checkRollback(dataDirPath) {
   try {
     tip = safeJson.parse(atomicFile.readSync(tipPath), { schema: AUDIT_TIP_SCHEMA });
   } catch (e) {
-    log.error("FATAL: audit.tip unreadable or schema-invalid at " + tipPath + " — " + e.message);
-    log.error("Either delete it (forfeits rollback protection until next checkpoint) " +
+    throw _dbErr("db/audit-tip-unreadable",
+      "FATAL: audit.tip unreadable or schema-invalid at " + tipPath + " — " + e.message +
+      ". Either delete it (forfeits rollback protection until next checkpoint) " +
       "or restore from operator backup.");
-    process.exit(1);
   }
   var current = database.prepare("SELECT MAX(monotonicCounter) AS m FROM audit_log").get();
   var currentMax = current && current.m ? current.m : 0;
   if (currentMax < tip.atMonotonicCounter) {
-    log.error("FATAL: audit-log rollback detected.");
-    log.error("  audit.tip recorded counter: " + tip.atMonotonicCounter);
-    log.error("  current DB max counter:     " + currentMax);
-    log.error("Either the DB was restored from an older snapshot, or audit_log " +
-      "rows have been deleted. Investigate before continuing.");
     events.emit(events.EVENTS.AUDIT_ROLLBACK_DETECTED, {
       tipCounter:    tip.atMonotonicCounter,
       currentMax:    currentMax,
       tipPath:       tipPath,
     });
-    process.exit(1);
+    throw _dbErr("db/audit-rollback-detected",
+      "FATAL: audit-log rollback detected. " +
+      "audit.tip recorded counter: " + tip.atMonotonicCounter +
+      "; current DB max counter: " + currentMax +
+      ". Either the DB was restored from an older snapshot, or audit_log rows " +
+      "have been deleted. Investigate before continuing.");
   }
   log("rollback check ok (tip counter " + tip.atMonotonicCounter +
     ", current " + currentMax + ")");
@@ -1049,9 +1076,12 @@ function _checkRollback(dataDirPath) {
 //   fatal    → log fatal, exit(1) — audit-log the attempt before exit
 async function _runNtpBootCheck(opts) {
   if (safeEnv.readVar("BLAMEJS_SKIP_NTP_CHECK", { default: "" }) === "1") return;
-  var ntpCheck;
-  try { ntpCheck = require("./ntp-check"); }
-  catch (_e) { return; /* module not present — skip silently */ }
+  var ntp;
+  try { ntp = ntpCheck(); }
+  catch (e) {
+    log.debug("ntp-check module unavailable", { error: e.message });
+    return;
+  }
 
   var envServersRaw = safeEnv.readVar("BLAMEJS_NTP_SERVERS",         { default: "" });
   var envTimeout    = safeEnv.readVar("BLAMEJS_NTP_TIMEOUT_MS",      { default: "" });
@@ -1065,12 +1095,13 @@ async function _runNtpBootCheck(opts) {
     var thr = {};
     if (envWarn)  thr.warnMs  = parseInt(envWarn, 10);
     if (envFatal) thr.fatalMs = parseInt(envFatal, 10);
-    try { ntpCheck.setThresholds(thr); } catch (_e) {}
+    try { ntp.setThresholds(thr); }
+    catch (e) { log.debug("ntp setThresholds failed", { error: e.message }); }
   }
 
   var result;
   try {
-    result = await ntpCheck.bootCheck({
+    result = await ntp.bootCheck({
       servers:   resolvedServers,
       timeoutMs: resolvedTimeout,
     });
@@ -1098,17 +1129,27 @@ async function _runNtpBootCheck(opts) {
       message:  result.message,
     });
     if (safeEnv.readVar("BLAMEJS_NTP_STRICT", { default: "1" }) !== "0") {
-      log.error("Refuse to boot. Investigate NTP / RTC / container time sync.");
-      log.error("Override: BLAMEJS_NTP_STRICT=0 to continue (NOT recommended for production).");
-      process.exit(1);
+      throw _dbErr("db/ntp-drift-fatal",
+        "FATAL: ntp clock drift exceeds threshold: " + result.message +
+        ". Refuse to boot. Investigate NTP / RTC / container time sync. " +
+        "Override: BLAMEJS_NTP_STRICT=0 to continue (NOT recommended for production).");
     }
   }
 }
 
+// _cascadeStep — invoke ._resetForTest on a single lazy-required module
+// ref, logging at debug on any failure. Used by _resetForTest's cascade
+// over the framework's stateful subsystems.
+function _cascadeStep(name, ref) {
+  try { ref()._resetForTest(); }
+  catch (e) { log.debug("cascade-reset failed", { module: name, error: e.message }); }
+}
+
 // Test helpers — not part of public contract
 function _resetForTest() {
   if (encTimer) { encTimer.stop(); encTimer = null; }
-  try { if (database) database.close(); } catch (_e) {}
+  try { if (database) database.close(); }
+  catch (e) { log.debug("test-reset close failed", { error: e.message }); }
   database = null;
   dbPath = null;
   encPath = null;
@@ -1119,6 +1160,7 @@ function _resetForTest() {
   cryptoField.clearForTest();
 }
 
+
 module.exports = {
   init:                init,
   from:                from,
@@ -1154,7 +1196,8 @@ module.exports = {
   purgeAuditChain:     async function (args) {
     var lastPurgedCounter = Number(args && args.lastPurgedCounter);
     if (!Number.isFinite(lastPurgedCounter) || lastPurgedCounter < 0) {
-      throw new Error("purgeAuditChain: lastPurgedCounter must be a non-negative number");
+      throw new DbError("db/bad-purge-counter",
+      "purgeAuditChain: lastPurgedCounter must be a non-negative number");
     }
     if (cluster.isClusterMode()) {
       // External-db has no append-only triggers; ordinary DELETE works.
@@ -1195,20 +1238,20 @@ module.exports = {
   // 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 JSON.parse(JSON.stringify(tableMetadata));
+    if (!name) return structuredClone(tableMetadata);
     var m = tableMetadata[name];
-    return m ? JSON.parse(JSON.stringify(m)) : null;
+    return m ? structuredClone(m) : null;
   },
   // 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
   // dialects. See lib/db-declare-view.js.
-  declareView:         require("./db-declare-view").declareView,
+  declareView:         dbDeclareView.declareView,
   // declareRowPolicy — declarative Postgres ROW LEVEL SECURITY migration
   // spec. Pairs with externalDb.transaction({ sessionGucs }) for the
   // per-request `SET LOCAL` plumbing. Postgres-only; fail-fast on other
   // dialects. See lib/db-declare-row-policy.js.
-  declareRowPolicy:    require("./db-declare-row-policy").declareRowPolicy,
+  declareRowPolicy:    dbDeclareRowPolicy.declareRowPolicy,
   // 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(); },
@@ -1221,17 +1264,20 @@ module.exports = {
     dataResidency = null;
     tableMetadata = {};
     // Cascade reset to stateful modules so a fresh init() works.
-    try { require("./audit")._resetForTest(); }      catch (_e) {}
-    try { require("./consent")._resetForTest(); }    catch (_e) {}
-    try { require("./subject")._resetForTest(); }    catch (_e) {}
-    try { require("./session")._resetForTest(); }    catch (_e) {}
-    try { require("./storage")._resetForTest(); }    catch (_e) {}
-    try { require("./audit-sign")._resetForTest(); } catch (_e) {}
-    try { require("./queue")._resetForTest(); } catch (_e) {}
-    try { require("./break-glass")._resetForTest(); } catch (_e) {}
-    try { require("./log-stream")._resetForTest(); } catch (_e) {}
-    try { require("./redact")._resetForTest(); } catch (_e) {}
-    try { require("./external-db")._resetForTest(); } catch (_e) {}
+    // Each ref is a lazyRequire (top-of-file) so module-load cycles
+    // don't trip; failures (missing optional dep, partial smoke
+    // suites that skip a module entirely) get logged at debug.
+    _cascadeStep("audit",       _resetAudit);
+    _cascadeStep("consent",     _resetConsent);
+    _cascadeStep("subject",     _resetSubject);
+    _cascadeStep("session",     _resetSession);
+    _cascadeStep("storage",     _resetStorage);
+    _cascadeStep("audit-sign",  _resetAuditSign);
+    _cascadeStep("queue",       _resetQueue);
+    _cascadeStep("break-glass", _resetBreakGlass);
+    _cascadeStep("log-stream",  _resetLogStream);
+    _cascadeStep("redact",      _resetRedact);
+    _cascadeStep("external-db", _resetExternalDb);
   },
   // Helper for audit.checkpoint to write the rollback-detection sidecar
   _writeAuditTip: function (tip) {

package/lib/deprecate.js

@@ -51,6 +51,7 @@
  */
 
 var safeEnv = require("./parsers/safe-env");
+var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
 class DeprecateError extends FrameworkError {
@@ -90,14 +91,8 @@ function _validateOpts(opts, fnName) {
     throw new DeprecateError("deprecate/bad-opts",
       fnName + ": opts is required (with at least 'since' and 'removeIn')");
   }
-  if (typeof opts.since !== "string" || opts.since.length === 0) {
-    throw new DeprecateError("deprecate/bad-opts",
-      fnName + ": opts.since (version string) is required");
-  }
-  if (typeof opts.removeIn !== "string" || opts.removeIn.length === 0) {
-    throw new DeprecateError("deprecate/bad-opts",
-      fnName + ": opts.removeIn (version string) is required");
-  }
+  validateOpts.requireNonEmptyString(opts.since, fnName + ": opts.since (version string)", DeprecateError, "deprecate/bad-opts");
+  validateOpts.requireNonEmptyString(opts.removeIn, fnName + ": opts.removeIn (version string)", DeprecateError, "deprecate/bad-opts");
 }
 
 function warn(name, opts) {

package/lib/dev.js

@@ -48,6 +48,11 @@
  */
 
 var path = require("path");
+var childProcess = require("child_process");
+var fs = require("fs");
+var logModule = require("./log");
+var nb = require("./numeric-bounds");
+var validateOpts = require("./validate-opts");
 var { FrameworkError } = require("./framework-error");
 
 class DevError extends FrameworkError {
@@ -59,8 +64,13 @@ class DevError extends FrameworkError {
   }
 }
 
+var bootLog = logModule.boot("dev");
+
 var DEFAULT_GRACE_MS         = 250;
-var DEFAULT_KILL_TIMEOUT_MS  = 4000;
+// Default SIGKILL escalation budget: 4s — long enough for graceful
+// shutdown handlers to flush, short enough that an ignored SIGTERM
+// doesn't keep the dev loop hanging.
+var DEFAULT_KILL_TIMEOUT_MS  = 0xFA0;
 var DEFAULT_KILL_SIGNAL      = "SIGTERM";
 var DEFAULT_IGNORE = [
   /node_modules/,
@@ -86,39 +96,39 @@ function _logVia(log, level, message, fields) {
     catch (_e) { /* logger best-effort */ }
     return;
   }
-  // Fallback: prefixed line on stdout/stderr
-  var line = "[blamejs:dev] " + message + (fields ? " " + JSON.stringify(fields) : "");
-  if (level === "error" || level === "warn" || level === "fatal") console.error(line);
-  else console.log(line);
+  // Fallback: framework boot channel (TTY-aware, structured-JSON when piped).
+  var line = message + (fields ? " " + JSON.stringify(fields) : "");
+  var emit = (level === "error" || level === "fatal") ? bootLog.error
+    : (level === "warn" ? bootLog.warn : bootLog.info);
+  emit(line);
 }
 
 function create(opts) {
   opts = opts || {};
-  if (typeof opts.command !== "string" || opts.command.length === 0) {
-    throw new DevError("dev/no-command",
-      "dev.create requires opts.command (the program to spawn)");
-  }
+  validateOpts.requireNonEmptyString(opts.command, "dev.create: opts.command (the program to spawn)", DevError, "dev/no-command");
   var args         = Array.isArray(opts.args) ? opts.args.slice() : [];
   var watch        = Array.isArray(opts.watch) && opts.watch.length > 0
     ? opts.watch.slice() : ["."];
   var ignore       = Array.isArray(opts.ignore)
     ? DEFAULT_IGNORE.concat(opts.ignore)
     : DEFAULT_IGNORE.slice();
-  var graceMs      = typeof opts.graceMs === "number" && opts.graceMs >= 0
-    ? opts.graceMs : DEFAULT_GRACE_MS;
+  nb.requireNonNegativeFiniteIntIfPresent(opts.graceMs,
+    "dev.create: opts.graceMs", DevError, "dev/bad-grace-ms");
+  var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
   var killSignal   = typeof opts.killSignal === "string" ? opts.killSignal : DEFAULT_KILL_SIGNAL;
-  var killTimeoutMs = typeof opts.killTimeoutMs === "number" && opts.killTimeoutMs >= 0
-    ? opts.killTimeoutMs : DEFAULT_KILL_TIMEOUT_MS;
+  nb.requireNonNegativeFiniteIntIfPresent(opts.killTimeoutMs,
+    "dev.create: opts.killTimeoutMs", DevError, "dev/bad-kill-timeout-ms");
+  var killTimeoutMs = opts.killTimeoutMs !== undefined ? opts.killTimeoutMs : DEFAULT_KILL_TIMEOUT_MS;
   var log          = opts.log || null;
   var env          = opts.env || process.env;
   var cwd          = opts.cwd || process.cwd();
 
   // Test seams
   var spawnFn = opts._spawn || function (cmd, sargs, sopts) {
-    return require("child_process").spawn(cmd, sargs, sopts);
+    return childProcess.spawn(cmd, sargs, sopts);
   };
   var watchFn = opts._watch || function (dir, wopts, listener) {
-    return require("fs").watch(dir, wopts, listener);
+    return fs.watch(dir, wopts, listener);
   };
   var setTimeoutFn  = opts._setTimeout  || setTimeout;
   var clearTimeoutFn = opts._clearTimeout || clearTimeout;
@@ -160,13 +170,13 @@ function create(opts) {
 
   function _killChild() {
     return new Promise(function (resolve) {
-      if (!child) return resolve();
+      if (!child) { resolve(); return; }
       var c = child;
       var settled = false;
       function done() {
         if (settled) return;
         settled = true;
-        if (killTimer) { try { clearTimeoutFn(killTimer); } catch (_e) {} killTimer = null; }
+        if (killTimer) { try { clearTimeoutFn(killTimer); } catch (_e) { /* timer already cleared */ } killTimer = null; }
         resolve();
       }
       c.once("exit", done);
@@ -174,7 +184,8 @@ function create(opts) {
       catch (e) {
         _logVia(log, "warn", "kill threw, child may already be gone",
           { error: (e && e.message) || String(e) });
-        return done();
+        done();
+        return;
       }
       // Hard-kill if the child ignores SIGTERM
       killTimer = setTimeoutFn(function () {
@@ -285,7 +296,7 @@ function create(opts) {
   async function stop() {
     if (!started) return;
     stopping = true;
-    if (debounceTimer) { try { clearTimeoutFn(debounceTimer); } catch (_e) {} debounceTimer = null; }
+    if (debounceTimer) { try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ } debounceTimer = null; }
     _disarmWatchers();
     await _killChild();
     child = null;

package/lib/dual-control.js

@@ -113,9 +113,7 @@ function create(opts) {
     "namespace", "cache", "audit", "ttlMs", "minApprovers", "forbidSelfApprove",
     "consumeLockMs", "minReasonLength", "approverRoles", "notify",
   ], "dualControl");
-  if (typeof opts.namespace !== "string" || opts.namespace.length === 0) {
-    throw _err("BAD_OPT", "create: opts.namespace is required");
-  }
+  validateOpts.requireNonEmptyString(opts.namespace, "create: opts.namespace", DualControlError, "BAD_OPT");
   if (!opts.cache || typeof opts.cache.get !== "function" || typeof opts.cache.set !== "function") {
     throw _err("BAD_OPT", "create: opts.cache is required (a b.cache instance)");
   }
@@ -210,7 +208,7 @@ function create(opts) {
     if (reasonProblem) {
       return Object.assign({ grantId: null }, reasonProblem);
     }
-    var grantId = "dc-" + crypto.generateToken(8);
+    var grantId = "dc-" + crypto.generateToken(C.BYTES.bytes(8));
     var nowMs = Date.now();
     var record = {
       grantId:        grantId,