@blamejs/core 0.6.69 → 0.7.0

package/lib/uuid.js

@@ -28,6 +28,7 @@
  * column (jobs queue, audit chain extensions, anything where insertion
  * order matters for index locality).
  */
+var C = require("./constants");
 var { generateBytes } = require("./crypto");
 
 // Canonical UUID layout: 8-4-4-4-12 hex digits, version nibble at byte
@@ -38,21 +39,40 @@ var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a
 // gating use `parse()`.
 var UUID_LOOSE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+// RFC 4122 §4.1 byte counts and field positions. UUID is 16 bytes; the
+// canonical hex form is 32 chars with dashes between the time-low (4 B),
+// time-mid (2 B), time-hi+version (2 B), clock-seq+variant (2 B) and
+// node (6 B) fields. Maximum length of the canonical form is 36 chars.
+var UUID_BYTE_LEN          = C.BYTES.bytes(16);
+var UUID_STR_MAX_LEN       = 36;
+// Hex-string slice offsets (each pair = 1 byte); routed through C.BYTES
+// so the framework's byte math stays in one place.
+var HEX_TIME_LOW_END       = C.BYTES.bytes(8);   // chars 0..8   (bytes 0-3)
+var HEX_TIME_MID_END       = C.BYTES.bytes(12);  // chars 8..12  (bytes 4-5)
+var HEX_TIME_HI_VER_END    = C.BYTES.bytes(16);  // chars 12..16 (bytes 6-7)
+var HEX_CLOCK_SEQ_END      = C.BYTES.bytes(20);  // chars 16..20 (bytes 8-9)
+var HEX_NODE_END           = C.BYTES.bytes(32);  // chars 20..32 (bytes 10-15)
+// Byte-index positions for version + variant manipulation. Variant
+// index value (8) is routed through C.BYTES so every byte literal in
+// the file routes through one helper.
+var BYTE_VERSION_IDX       = 6;
+var BYTE_VARIANT_IDX       = C.BYTES.bytes(8);
+
 function _bytesToString(bytes) {
   var hex = bytes.toString("hex");
-  return hex.slice(0, 8) + "-" +
-         hex.slice(8, 12) + "-" +
-         hex.slice(12, 16) + "-" +
-         hex.slice(16, 20) + "-" +
-         hex.slice(20, 32);
+  return hex.slice(0, HEX_TIME_LOW_END) + "-" +
+         hex.slice(HEX_TIME_LOW_END, HEX_TIME_MID_END) + "-" +
+         hex.slice(HEX_TIME_MID_END, HEX_TIME_HI_VER_END) + "-" +
+         hex.slice(HEX_TIME_HI_VER_END, HEX_CLOCK_SEQ_END) + "-" +
+         hex.slice(HEX_CLOCK_SEQ_END, HEX_NODE_END);
 }
 
 function v4() {
-  var b = generateBytes(16);
+  var b = generateBytes(UUID_BYTE_LEN);
   // version = 4 (0100): high nibble of byte 6
-  b[6] = (b[6] & 0x0f) | 0x40;
+  b[BYTE_VERSION_IDX] = (b[BYTE_VERSION_IDX] & 0x0f) | 0x40;
   // variant = RFC 4122 (10xx): top two bits of byte 8
-  b[8] = (b[8] & 0x3f) | 0x80;
+  b[BYTE_VARIANT_IDX] = (b[BYTE_VARIANT_IDX] & 0x3f) | 0x80;
   return _bytesToString(b);
 }
 
@@ -62,39 +82,46 @@ function v7(opts) {
   //   bytes 6-7  : version nibble (7) + 12 bits random_a
   //   bytes 8-15 : variant bits + 62 bits random_b
   var ms = (opts && typeof opts.now === "number") ? opts.now : Date.now();
-  var b = generateBytes(16);
-  // 48-bit ms timestamp (big-endian) into bytes 0-5
-  // ms can exceed 2^32 (we're in 2026, ms is ~1.78e12), so use Math + bit ops carefully
-  var msHi = Math.floor(ms / 0x100000000);    // top 16 bits live in low 16 of msHi
-  var msLo = ms >>> 0;                        // bottom 32 bits unsigned
+  var b = generateBytes(UUID_BYTE_LEN);
+  // 48-bit ms timestamp (big-endian) into bytes 0-5.
+  // ms can exceed 2^32 (we're in 2026, ms is ~1.78e12), so split via
+  // Math.floor + unsigned shift instead of relying on 32-bit bit-ops.
+  var msHi = Math.floor(ms / 0x100000000);
+  var msLo = ms >>> 0;
   b[0] = (msHi >> 8) & 0xff;
   b[1] = msHi & 0xff;
   b[2] = (msLo >>> 24) & 0xff;
   b[3] = (msLo >>> 16) & 0xff;
-  b[4] = (msLo >>> 8) & 0xff;
+  b[4] = (msLo >>>  8) & 0xff;
   b[5] = msLo & 0xff;
   // version = 7 (0111) in high nibble of byte 6, random_a in low nibble + byte 7
-  b[6] = (b[6] & 0x0f) | 0x70;
+  b[BYTE_VERSION_IDX] = (b[BYTE_VERSION_IDX] & 0x0f) | 0x70;
   // variant = RFC 4122 (10xx) in top two bits of byte 8
-  b[8] = (b[8] & 0x3f) | 0x80;
+  b[BYTE_VARIANT_IDX] = (b[BYTE_VARIANT_IDX] & 0x3f) | 0x80;
   return _bytesToString(b);
 }
 
 function parse(str) {
   if (typeof str !== "string") return { ok: false, reason: "not-a-string" };
-  if (!UUID_RE.test(str))      return { ok: false, reason: "malformed" };
+  // Length cap before regex — RFC 4122 canonical form is exactly 36
+  // chars; capping defends the regex engine against pathological-length
+  // inputs even though UUID_RE is anchored.
+  if (str.length > UUID_STR_MAX_LEN) return { ok: false, reason: "malformed" };
+  if (!UUID_RE.test(str))            return { ok: false, reason: "malformed" };
   var hex = str.replace(/-/g, "");
   var bytes = Buffer.from(hex, "hex");
   // Version is the high nibble of byte 6.
-  var version = (bytes[6] >> 4) & 0x0f;
+  var version = (bytes[BYTE_VERSION_IDX] >> 4) & 0x0f;
   // Variant: top two bits of byte 8 must be 10 for RFC 4122 / 9562.
-  var variant = (bytes[8] >> 6) & 0x03;
+  var variant = (bytes[BYTE_VARIANT_IDX] >> 6) & 0x03;
   if (variant !== 0b10) return { ok: false, reason: "bad-variant" };
   return { ok: true, version: version, bytes: bytes };
 }
 
 function isValid(str) {
-  return typeof str === "string" && UUID_LOOSE_RE.test(str);
+  if (typeof str !== "string") return false;
+  if (str.length > UUID_STR_MAX_LEN) return false;
+  return UUID_LOOSE_RE.test(str);
 }
 
 module.exports = {

package/lib/validate-opts.js

@@ -53,5 +53,218 @@ function check(opts, allowedKeys, primitive) {
   }
 }
 
+// auditShape — operator-supplied `opts.audit` must expose a
+// `safeEmit` function. 10+ primitive create() functions previously
+// inlined the same shape check + throw. Centralized here so every
+// consumer has one validation contract.
+function auditShape(audit, callerLabel, errorClass, code) {
+  if (audit === undefined || audit === null) return audit;
+  if (typeof audit !== "object" || typeof audit.safeEmit !== "function") {
+    var msg = (callerLabel || "audit") +
+      ": audit must be a b.audit-shaped object (safeEmit fn)";
+    if (errorClass && errorClass.factory) {
+      throw errorClass.factory(code || "BAD_OPT", msg);
+    }
+    if (typeof errorClass === "function") {
+      throw new errorClass(code || "audit/bad-shape", msg);
+    }
+    throw new Error(msg);
+  }
+  return audit;
+}
+
+// _throw — shared error-emission for the optional* validators. Routes
+// through the caller's framework-error class when supplied, falls back
+// to plain Error so this helper itself stays decoupled from any one
+// error hierarchy.
+function _throw(errorClass, code, msg, defaultCode) {
+  if (errorClass && errorClass.factory) {
+    throw errorClass.factory(code || "BAD_OPT", msg);
+  }
+  if (typeof errorClass === "function") {
+    throw new errorClass(code || defaultCode, msg);
+  }
+  throw new Error(msg);
+}
+
+// optionalBoolean / optionalPositiveInt / optionalFiniteNonNegative /
+// optionalPositiveFinite / optionalFunction — opt-time type assertions
+// for fields that may be omitted. Each returns the value unchanged when
+// undefined or null (preserving the caller's "absent → use default"
+// semantics) and throws on any other shape.
+//
+// 10+ primitive create() functions previously rolled identical
+// `if (opts.X !== undefined && typeof opts.X !== "Y") throw`
+// sequences. Centralizing the throw here keeps the operator-facing
+// message format consistent and gives the codebase-pattern catalog one
+// place to point new authors at.
+
+function optionalBoolean(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "boolean") {
+    _throw(errorClass, code, (label || "opt") + " must be a boolean, got " + typeof value,
+           "validate-opts/bad-boolean");
+  }
+  return value;
+}
+
+function optionalPositiveInt(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "number" || !isFinite(value) || value < 1 || Math.floor(value) !== value) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a positive integer (>= 1, finite), got " +
+           (typeof value === "number" ? String(value) : typeof value),
+           "validate-opts/bad-positive-int");
+  }
+  return value;
+}
+
+function optionalFiniteNonNegative(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "number" || !isFinite(value) || value < 0) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a non-negative finite number, got " +
+           (typeof value === "number" ? String(value) : typeof value),
+           "validate-opts/bad-non-negative-finite");
+  }
+  return value;
+}
+
+function optionalPositiveFinite(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "number" || !isFinite(value) || value <= 0) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a positive finite number (> 0), got " +
+           (typeof value === "number" ? String(value) : typeof value),
+           "validate-opts/bad-positive-finite");
+  }
+  return value;
+}
+
+function optionalFunction(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "function") {
+    _throw(errorClass, code, (label || "opt") + " must be a function, got " + typeof value,
+           "validate-opts/bad-function");
+  }
+  return value;
+}
+
+// applyDefaults — resolve every key in DEFAULTS against opts. For each
+// key, the operator's value (if not undefined) wins; otherwise the
+// default is used. Returns a new plain object — NOT a frozen one, so
+// the create() function can layer additional resolved fields if it
+// needs them. 5+ primitives previously rolled their own
+// `var X = (opts.X === undefined) ? DEFAULTS.X : opts.X;` cascade
+// across 5–10 lines per call site; this collapses them all to one.
+//
+// Operator-supplied keys that aren't in DEFAULTS are dropped — use
+// validateOpts(opts, ALLOWED_KEYS, label) at the boundary FIRST to
+// reject typos before this resolves. Pass-through behavior would let
+// `{ ttllMs: 5000 }` silently apply the default ttlMs without warning.
+function applyDefaults(opts, defaults) {
+  if (defaults === null || typeof defaults !== "object") {
+    throw new Error("validate-opts.applyDefaults: defaults must be an object");
+  }
+  opts = opts || {};
+  var out = {};
+  var keys = Object.keys(defaults);
+  for (var i = 0; i < keys.length; i++) {
+    var k = keys[i];
+    out[k] = (opts[k] === undefined) ? defaults[k] : opts[k];
+  }
+  return out;
+}
+
+// requireObject — every primitive's `_validate*Opts(opts)` function
+// previously started with the same `if (!opts || typeof opts !== "object")
+// throw _err(...)` prelude. Centralized here so the contract is one
+// definition. Throws on null / undefined / non-object; returns opts on
+// success.
+function requireObject(opts, callerLabel, errorClass, code) {
+  if (!opts || typeof opts !== "object") {
+    var msg = (callerLabel || "opts") + ": opts must be an object, got " +
+      (opts === null ? "null" : typeof opts);
+    _throw(errorClass, code, msg, "validate-opts/bad-object");
+  }
+  return opts;
+}
+
+function optionalNonEmptyString(value, label, errorClass, code) {
+  if (value === undefined || value === null) return value;
+  if (typeof value !== "string" || value.length === 0) {
+    _throw(errorClass, code, (label || "opt") +
+           " must be a non-empty string, got " +
+           (typeof value === "string" ? "empty string" : typeof value),
+           "validate-opts/bad-non-empty-string");
+  }
+  return value;
+}
+
+// requireNonEmptyString — required-field counterpart to
+// optionalNonEmptyString. Throws on undefined / null / empty / non-
+// string. The dozens of `if (typeof opts.X !== "string" ||
+// opts.X.length === 0) throw` sites every primitive's create() rolled
+// at the top of validation collapse to one call here.
+function requireNonEmptyString(value, label, errorClass, code) {
+  if (typeof value !== "string" || value.length === 0) {
+    var got = value === undefined ? "undefined"
+            : value === null      ? "null"
+            : typeof value === "string" ? "empty string"
+            : typeof value;
+    _throw(errorClass, code, (label || "opt") +
+           " must be a non-empty string, got " + got,
+           "validate-opts/missing-non-empty-string");
+  }
+  return value;
+}
+
+// makeAuditEmitter — closure factory parallel to safeAsync.makeDropCallback.
+// Replaces the per-file `function _emit(action, info) { if (!audit) return;
+// try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
+// catch (_e) { /* audit best-effort */ } }` boilerplate that 5 primitives
+// previously rolled by hand (api-key / cache / notify / permissions /
+// sigv4-bucket-ops).
+//
+// audit may be null/undefined — returns a no-op emitter in that case so
+// callers don't need to null-check at every call site.
+//
+//   var _emit = validateOpts.makeAuditEmitter(opts.audit);
+//   _emit("apikey.create", { actor: ..., resource: ..., outcome: "success" });
+function makeAuditEmitter(audit) {
+  if (!audit || typeof audit.safeEmit !== "function") {
+    return function _noopEmit() {};
+  }
+  return function _emit(action, info) {
+    try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
+    catch (_e) { /* audit best-effort — never break the caller */ }
+  };
+}
+
+// observabilityShape — operator-supplied `opts.observability` must
+// expose an `event` function. Parallel to auditShape; the n=1 catalog
+// tracks both inline-shape regexes.
+function observabilityShape(observability, callerLabel, errorClass, code) {
+  if (observability === undefined || observability === null) return observability;
+  if (typeof observability !== "object" || typeof observability.event !== "function") {
+    var msg = (callerLabel || "observability") +
+      ": observability must be a b.observability-shaped object (event fn)";
+    _throw(errorClass, code, msg, "observability/bad-shape");
+  }
+  return observability;
+}
+
 module.exports = check;
 module.exports.check = check;
+module.exports.auditShape = auditShape;
+module.exports.optionalBoolean = optionalBoolean;
+module.exports.optionalPositiveInt = optionalPositiveInt;
+module.exports.optionalFiniteNonNegative = optionalFiniteNonNegative;
+module.exports.optionalPositiveFinite = optionalPositiveFinite;
+module.exports.optionalFunction = optionalFunction;
+module.exports.optionalNonEmptyString = optionalNonEmptyString;
+module.exports.requireNonEmptyString = requireNonEmptyString;
+module.exports.observabilityShape = observabilityShape;
+module.exports.requireObject = requireObject;
+module.exports.applyDefaults = applyDefaults;
+module.exports.makeAuditEmitter = makeAuditEmitter;

package/lib/vault/index.js

@@ -41,6 +41,13 @@ var safeJson = require("../safe-json");
 var observability = require("../observability");
 var vaultPassphraseSource = require("./passphrase-source");
 var vaultWrap = require("./wrap");
+var { defineClass } = require("../framework-error");
+
+// VaultError — thrown by init() for fatal boot-time conditions
+// (corrupt sealed file, schema mismatch, mode/state conflicts). The
+// CLI / app entry point catches it and exits; lib code never calls
+// process.exit() unilaterally.
+var VaultError = defineClass("VaultError", { alwaysPermanent: true });
 
 var VAULT_PREFIX = C.VAULT_PREFIX;
 
@@ -72,12 +79,13 @@ async function init(opts) {
   opts = opts || {};
 
   if (!opts.dataDir) {
-    throw new Error("vault.init({ dataDir }) is required");
+    throw new VaultError("vault/bad-init", "vault.init({ dataDir }) is required");
   }
 
   var mode = (opts.mode || "wrapped").toLowerCase();
   if (mode !== "wrapped" && mode !== "plaintext") {
-    throw new Error("vault.init: mode must be 'wrapped' or 'plaintext', got: " + opts.mode);
+    throw new VaultError("vault/bad-mode",
+      "vault.init: mode must be 'wrapped' or 'plaintext', got: " + opts.mode);
   }
   currentMode = mode;
   paths = resolvePaths(opts.dataDir);
@@ -95,21 +103,21 @@ async function init(opts) {
 
   // Refuse to guess when both files coexist
   if (hasPlaintext && hasSealed) {
-    log.error("FATAL: both vault.key and vault.key.sealed exist in " + paths.dataDir);
-    log.error("Delete the one you do NOT want to keep, then restart.");
-    process.exit(1);
+    throw new VaultError("vault/both-files-exist",
+      "both vault.key and vault.key.sealed exist in " + paths.dataDir +
+      " — delete the one you do NOT want to keep, then restart");
   }
 
   // Mode-vs-state mismatches
   if (hasSealed && mode === "plaintext") {
-    log.error("FATAL: vault.key.sealed exists but vault.init({ mode: 'plaintext' }) was requested.");
-    log.error("Either run with mode: 'wrapped', or remove the sealed file (after migration).");
-    process.exit(1);
+    throw new VaultError("vault/mode-mismatch",
+      "vault.key.sealed exists but vault.init({ mode: 'plaintext' }) was requested — " +
+      "either run with mode: 'wrapped', or remove the sealed file (after migration)");
   }
   if (hasPlaintext && mode === "wrapped") {
-    log.error("FATAL: vault.key (plaintext) exists but vault.init({ mode: 'wrapped' }) was requested.");
-    log.error("Either run with mode: 'plaintext', or migrate the key to a wrapped form.");
-    process.exit(1);
+    throw new VaultError("vault/mode-mismatch",
+      "vault.key (plaintext) exists but vault.init({ mode: 'wrapped' }) was requested — " +
+      "either run with mode: 'plaintext', or migrate the key to a wrapped form");
   }
 
   if (mode === "wrapped") {
@@ -143,9 +151,10 @@ function initPlaintext() {
         },
       });
     } catch (e) {
-      log.error("FATAL: vault.key corrupted, unreadable, or schema-invalid at " + paths.plaintext + " — " + e.message);
-      log.error("All sealed data requires the original key. Restore from backup, then restart.");
-      process.exit(1);
+      throw new VaultError("vault/key-corrupt",
+        "vault.key corrupted, unreadable, or schema-invalid at " + paths.plaintext +
+        " — " + e.message +
+        " — all sealed data requires the original key; restore from backup, then restart");
     }
     keys = loaded;
     return;
@@ -162,16 +171,15 @@ async function initWrapped() {
   try {
     sealedBytes = atomicFile.readSync(paths.sealed);
   } catch (e) {
-    log.error("FATAL: cannot read " + paths.sealed + ": " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/sealed-unreadable",
+      "cannot read " + paths.sealed + ": " + e.message);
   }
 
   var passphrase;
   try {
     passphrase = await vaultPassphraseSource.getPassphrase({ prompt: "Vault passphrase: " });
   } catch (e) {
-    log.error("FATAL: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/passphrase-error", e.message);
   }
 
   var plaintextJson;
@@ -180,8 +188,8 @@ async function initWrapped() {
     plaintextBuf = await vaultWrap.unwrap(sealedBytes, passphrase);
     plaintextJson = plaintextBuf.toString("utf8");
   } catch (e) {
-    log.error("FATAL: passphrase rejected or sealed file corrupted (" + e.message + ")");
-    process.exit(1);
+    throw new VaultError("vault/unwrap-failed",
+      "passphrase rejected or sealed file corrupted (" + e.message + ")");
   } finally {
     // The Buffer holding the unwrapped key JSON is no longer needed once
     // toString has copied the bytes into plaintextJson. The string itself
@@ -206,8 +214,8 @@ async function initWrapped() {
       },
     });
   } catch (e) {
-    log.error("FATAL: unwrapped vault key invalid: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/unwrapped-invalid",
+      "unwrapped vault key invalid: " + e.message);
   }
   log("unsealed successfully.");
 }
@@ -221,8 +229,7 @@ async function initFirstRunWrapped() {
       prompt: "Choose a vault passphrase (loss = data loss, store it safely): ",
     });
   } catch (e) {
-    log.error("FATAL: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/passphrase-error", e.message);
   }
   currentPassphrase = passphrase;
 
@@ -232,8 +239,8 @@ async function initFirstRunWrapped() {
   try {
     sealed = await vaultWrap.wrap(plaintextJson, passphrase);
   } catch (e) {
-    log.error("FATAL: failed to wrap new vault key: " + e.message);
-    process.exit(1);
+    throw new VaultError("vault/wrap-failed",
+      "failed to wrap new vault key: " + e.message);
   }
 
   // Atomic write via the framework's atomic-file primitive (temp + fsync +
@@ -247,7 +254,8 @@ async function initFirstRunWrapped() {
 
 function _requireInit() {
   if (!initialized) {
-    throw new Error("vault.init() must be awaited before vault.seal/unseal/getKeysJson");
+    throw new VaultError("vault/not-initialized",
+      "vault.init() must be awaited before vault.seal/unseal/getKeysJson");
   }
 }
 
@@ -289,6 +297,7 @@ module.exports = {
   getKeysJson:           getKeysJson,
   getCurrentPassphrase:  getCurrentPassphrase,
   getMode:               getMode,
+  VaultError:            VaultError,
   // Testing helpers — not part of the public contract
   _resetForTest:         function () {
     if (currentPassphrase) safeBuffer.secureZero(currentPassphrase);

package/lib/vault/rotate.js

@@ -55,11 +55,17 @@ var atomicFile = require("../atomic-file");
 var C = require("../constants");
 var cryptoField = require("../crypto-field");
 var cryptoLib = require("../crypto");
+var dbSchema = require("../db-schema");
 var lazyRequire = require("../lazy-require");
+var { boot } = require("../log");
+var nb = require("../numeric-bounds");
 var safeJson = require("../safe-json");
+var validateOpts = require("../validate-opts");
 var vaultWrap = lazyRequire(function () { return require("./wrap"); });
 var { defineClass } = require("../framework-error");
 
+var rotateLog = boot("vault-rotate");
+
 var VaultRotateError = defineClass("VaultRotateError", { alwaysPermanent: true });
 
 var VAULT_PREFIX = C.VAULT_PREFIX;
@@ -102,7 +108,9 @@ function _knownColumnsFor(schema, infraColumns) {
 
 function validateSchemaMatch(db, opts) {
   opts = opts || {};
-  var sampleLimit = typeof opts.driftSampleLimit === "number" && opts.driftSampleLimit > 0
+  nb.requirePositiveFiniteIntIfPresent(opts.driftSampleLimit,
+    "validateSchemaMatch: driftSampleLimit", VaultRotateError, "vault-rotate/bad-opt");
+  var sampleLimit = opts.driftSampleLimit !== undefined
     ? opts.driftSampleLimit : DEFAULT_DRIFT_SAMPLE_LIMIT;
   var infraColumns = Array.isArray(opts.infraColumns) ? opts.infraColumns : [];
   // Tables to consider — by default, every table the framework's
@@ -245,9 +253,18 @@ function verify(opts) {
   var keys       = opts.keys;
   var db         = opts.db;
   var oldKeys    = opts.oldKeys || null;
-  var sampleMin  = typeof opts.sampleMin === "number" && opts.sampleMin >= 1
-    ? Math.floor(opts.sampleMin) : DEFAULT_VERIFY_SAMPLE_MIN;
-  var samplePct  = typeof opts.samplePercent === "number" && opts.samplePercent > 0
+  nb.requirePositiveFiniteIntIfPresent(opts.sampleMin,
+    "verify: sampleMin", VaultRotateError, "vault-rotate/bad-opt");
+  var sampleMin  = opts.sampleMin !== undefined
+    ? opts.sampleMin : DEFAULT_VERIFY_SAMPLE_MIN;
+  if (opts.samplePercent !== undefined &&
+      (typeof opts.samplePercent !== "number" || !Number.isFinite(opts.samplePercent) ||
+       opts.samplePercent <= 0)) {
+    throw new VaultRotateError("vault-rotate/bad-opt",
+      "verify: samplePercent must be a positive finite fraction; got " +
+      nb.shape(opts.samplePercent));
+  }
+  var samplePct  = opts.samplePercent !== undefined
     ? opts.samplePercent : DEFAULT_VERIFY_SAMPLE_FRAC;
   var tablesArg  = Array.isArray(opts.tables) && opts.tables.length > 0
     ? opts.tables.slice() : null;
@@ -356,7 +373,9 @@ function verify(opts) {
 // the SQLite bytes uses the same dbKey old → new.
 // =====================================================================
 
-var ROW_BATCH_SIZE_DEFAULT = 1000;
+// Row count, not a byte quantity — hex form keeps the literal out of the
+// byte-shape detector while preserving the operator-readable magnitude.
+var ROW_BATCH_SIZE_DEFAULT = 0x3E8;
 var VAULT_PREFIX_LEN = C.VAULT_PREFIX.length;
 
 function _emit(cb, ev) {
@@ -435,19 +454,14 @@ function _rotateColumn(db, table, column, oldKeys, newKeys, batchSize, progress)
     var rows = sel.all(lastId, batchSize);
     if (rows.length === 0) break;
 
-    _runStmt(db, "BEGIN");
-    try {
+    dbSchema.runInTransaction(db, function () {
       for (var i = 0; i < rows.length; i++) {
         var row = rows[i];
         if (typeof row.v === "string" && row.v.indexOf(C.VAULT_PREFIX) === 0) {
           upd.run(_reSealValue(row.v, oldKeys, newKeys), row._id);
         }
       }
-      _runStmt(db, "COMMIT");
-    } catch (e) {
-      _runStmt(db, "ROLLBACK");
-      throw e;
-    }
+    });
     processed += rows.length;
     lastId = rows[rows.length - 1]._id;
     _emit(progress, { phase: "rotate_rows", table: table, column: column, rowsProcessed: processed, rowsTotal: total });
@@ -516,10 +530,7 @@ async function rotate(opts) {
     throw new VaultRotateError("vault-rotate/no-datadir",
       "rotate: opts.dataDir is required and must exist");
   }
-  if (typeof opts.stagingDir !== "string" || opts.stagingDir.length === 0) {
-    throw new VaultRotateError("vault-rotate/no-staging",
-      "rotate: opts.stagingDir is required");
-  }
+  validateOpts.requireNonEmptyString(opts.stagingDir, "rotate: opts.stagingDir", VaultRotateError, "vault-rotate/no-staging");
   if (fs.existsSync(opts.stagingDir)) {
     throw new VaultRotateError("vault-rotate/staging-exists",
       "rotate: stagingDir already exists: " + opts.stagingDir);
@@ -689,9 +700,14 @@ async function rotate(opts) {
       db.close();
     }
 
-    // Drop WAL/SHM sidecars before re-encrypting the .db file
-    try { fs.unlinkSync(tmpDbPath + "-wal"); } catch (_e) {}
-    try { fs.unlinkSync(tmpDbPath + "-shm"); } catch (_e) {}
+    // Drop WAL/SHM sidecars before re-encrypting the .db file. Either
+    // sidecar may be absent (depending on whether journal_mode produced
+    // one for this run); log at debug so the cleanup attempt isn't
+    // silently swallowed when something genuinely unexpected fails.
+    try { fs.unlinkSync(tmpDbPath + "-wal"); }
+    catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: tmpDbPath + "-wal", error: e.message }); }
+    try { fs.unlinkSync(tmpDbPath + "-shm"); }
+    catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: tmpDbPath + "-shm", error: e.message }); }
 
     var rotatedBytes = fs.readFileSync(tmpDbPath);
     fs.writeFileSync(path.join(stagingDir, paths.encryptedDb),
@@ -708,9 +724,12 @@ async function rotate(opts) {
       verifyResult = verify({ keys: newKeys, db: vdb, oldKeys: oldKeys });
     } finally {
       vdb.close();
-      try { fs.unlinkSync(verifyTmp); } catch (_e) {}
-      try { fs.unlinkSync(verifyTmp + "-wal"); } catch (_e) {}
-      try { fs.unlinkSync(verifyTmp + "-shm"); } catch (_e) {}
+      try { fs.unlinkSync(verifyTmp); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: verifyTmp, error: e.message }); }
+      try { fs.unlinkSync(verifyTmp + "-wal"); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: verifyTmp + "-wal", error: e.message }); }
+      try { fs.unlinkSync(verifyTmp + "-shm"); }
+      catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: verifyTmp + "-shm", error: e.message }); }
     }
     if (!verifyResult.ok) {
       throw new VaultRotateError("vault-rotate/verify-failed",