@blamejs/core 0.6.70 → 0.7.0

package/lib/backup/manifest.js

@@ -69,6 +69,7 @@
  */
 
 var C = require("../constants");
+var safeBuffer = require("../safe-buffer");
 var safeJson = require("../safe-json");
 var { FrameworkError } = require("../framework-error");
 
@@ -84,7 +85,10 @@ class BackupManifestError extends FrameworkError {
 var FORMAT_VERSION = 1;
 var FRAMEWORK_NAME = "blamejs";
 var VALID_KINDS = { "raw": 1, "vault-sealed": 1, "plaintext": 1 };
-var HEX_RE = /^[0-9a-fA-F]+$/;
+// SHA3-512 produces 64 raw bytes — each byte serializes as 2 hex chars
+// in the manifest, so the hex string is 128 chars long.
+var SHA3_512_HEX_LENGTH = 128;
+var HEX_RE = safeBuffer.HEX_RE;
 var BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 
 function _isHex(s, evenLength) {
@@ -124,7 +128,7 @@ function _validateFileEntry(f, idx, errors) {
   if (typeof f.encryptedSize !== "number" || !Number.isInteger(f.encryptedSize) || f.encryptedSize < 0) {
     errors.push("files[" + idx + "].encryptedSize: required non-negative integer");
   }
-  if (!_isHex(f.checksum, true) || f.checksum.length !== 128) {
+  if (!_isHex(f.checksum, true) || f.checksum.length !== SHA3_512_HEX_LENGTH) {
     errors.push("files[" + idx + "].checksum: required 128-char hex string (sha3-512)");
   }
   if (!_isHex(f.salt, true)) {

package/lib/break-glass.js

@@ -66,6 +66,14 @@ var BreakGlassError = defineClass("BreakGlassError", { alwaysPermanent: false })
 
 // ---- Defaults (matched to operator-locked decisions) ----
 
+// Symmetric byte counts: 32-byte cell-key (kdf output, XChaCha20 key
+// length); 32-byte DEK (AEAD key); 16-byte grant-id randomness (128-bit
+// uniqueness for cross-table grant lookups). All routed through C.BYTES
+// so the framework's byte math has a single source of truth.
+var CELL_KEY_BYTES          = C.BYTES.bytes(32);
+var DEK_BYTES               = C.BYTES.bytes(32);
+var GRANT_ID_BYTES          = C.BYTES.bytes(16);
+
 var DEFAULT_GRANT_TTL_MS    = C.TIME.minutes(15);
 var DEFAULT_MAX_ROWS        = 1;       // operator-locked: row-by-row auth
 var DEFAULT_REASON_MIN_LEN  = 12;
@@ -137,7 +145,7 @@ function _kCell(dek, table, rowId, column) {
   return kdf(Buffer.concat([
     Buffer.isBuffer(dek) ? dek : Buffer.from(dek, "base64"),
     Buffer.from("breakglass.cell|" + table + "|" + String(rowId) + "|" + column, "utf8"),
-  ]), 32);
+  ]), CELL_KEY_BYTES);
 }
 
 async function _ensureDek(table) {
@@ -158,7 +166,7 @@ async function _ensureDek(table) {
   if (sealed) {
     dek = Buffer.from(vault().unseal(sealed), "base64");
   } else {
-    dek = generateBytes(32);
+    dek = generateBytes(DEK_BYTES);
     var sealedDek = vault().seal(dek.toString("base64"));
     await clusterStorage.execute(
       "UPDATE _blamejs_break_glass_policies SET dekSealed = ? WHERE tableName = ?",
@@ -415,10 +423,7 @@ function _validatePolicySet(table, opts) {
   // CLI to convert existing rows). At unseal time, the row's
   // glass-locked columns are decrypted via decryptCell with encryption
   // context binding (table, rowId, column).
-  if (opts.cryptographic !== undefined && typeof opts.cryptographic !== "boolean") {
-    throw new BreakGlassError("breakglass/bad-policy",
-      "policy.set: cryptographic must be a boolean");
-  }
+  validateOpts.optionalBoolean(opts.cryptographic, "policy.set: cryptographic", BreakGlassError, "breakglass/bad-policy");
   var grantTtl = opts.grantTtl != null ? opts.grantTtl : DEFAULT_GRANT_TTL_MS;
   if (typeof grantTtl !== "number" || !isFinite(grantTtl) || grantTtl <= 0) {
     throw new BreakGlassError("breakglass/bad-policy",
@@ -733,7 +738,7 @@ async function grant(opts) {
 
   // Build + persist the grant row
   var nowMs    = Date.now();
-  var grantId  = "bg-" + generateToken(16);
+  var grantId  = "bg-" + generateToken(GRANT_ID_BYTES);
   var sessionId = (opts.req && opts.req.session && opts.req.session.id) || null;
   // Honor the framework-wide trustProxy setting from init() — same
   // boundary as middleware. Without trustProxy, X-Forwarded-For is

package/lib/bundler.js

@@ -81,11 +81,22 @@ var path = require("path");
 var fs = require("fs");
 var crypto = require("./crypto");
 var atomicFile = require("./atomic-file");
-var { defineClass } = require("./framework-error");
+var logModule = require("./log");
+var nb = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
 
 var BundlerError = defineClass("BundlerError", { alwaysPermanent: true });
+var bootLog = logModule.boot("bundler");
+
+// Default content-hash length: 16 hex chars (8 bytes of SHA3-512). Long
+// enough that collision probability is negligible for asset cache busting,
+// short enough to keep generated filenames readable.
+var DEFAULT_HASH_LEN = 0x10;
+var MIN_HASH_LEN     = 0x4;
+var MAX_HASH_LEN     = 0x40;
+var DEFAULT_GRACE_MS = 100;
 
 function _hashContent(buf, hexLen) {
   // SHA3-512 → take the first hexLen hex chars. Same family as the
@@ -221,10 +232,7 @@ function create(opts) {
     "_watch", "_setTimeout", "_clearTimeout",
   ], "b.bundler");
   _validateEntries(opts.entries);
-  if (typeof opts.outdir !== "string" || opts.outdir.length === 0) {
-    throw new BundlerError("bundler/no-outdir",
-      "bundler.create requires opts.outdir");
-  }
+  validateOpts.requireNonEmptyString(opts.outdir, "bundler.create: opts.outdir", BundlerError, "bundler/no-outdir");
   var engineImpl = _validateEngine(opts.engine);
 
   var entries     = Object.assign({}, opts.entries);
@@ -236,8 +244,17 @@ function create(opts) {
         ? opts.manifest
         : "manifest.json");
   var hashOn   = opts.hash !== false;
-  var hashLen  = typeof opts.hashLen === "number" && opts.hashLen >= 4 && opts.hashLen <= 64
-    ? Math.floor(opts.hashLen) : 16;
+  var hashLen  = DEFAULT_HASH_LEN;
+  if (opts.hashLen !== undefined) {
+    if (!nb.isPositiveFiniteInt(opts.hashLen) ||
+        opts.hashLen < MIN_HASH_LEN || opts.hashLen > MAX_HASH_LEN) {
+      throw new BundlerError("bundler/bad-hash-len",
+        "bundler.create: opts.hashLen must be a positive finite integer " +
+        "between " + MIN_HASH_LEN + " and " + MAX_HASH_LEN +
+        "; got " + nb.shape(opts.hashLen));
+    }
+    hashLen = opts.hashLen;
+  }
   var log      = opts.log || null;
 
   // Test seam: tests pass a fake watcher so we don't actually fs.watch
@@ -246,7 +263,9 @@ function create(opts) {
   };
   var setTimeoutFn  = opts._setTimeout  || setTimeout;
   var clearTimeoutFn = opts._clearTimeout || clearTimeout;
-  var graceMs = typeof opts.graceMs === "number" && opts.graceMs >= 0 ? opts.graceMs : 100;
+  nb.requireNonNegativeFiniteIntIfPresent(opts.graceMs,
+    "bundler.create: opts.graceMs", BundlerError, "bundler/bad-grace-ms");
+  var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
 
   var watchers      = [];
   var debounceTimer = null;
@@ -256,15 +275,7 @@ function create(opts) {
     return path.isAbsolute(p) ? p : path.resolve(cwd, p);
   }
 
-  function _logVia(level, message, fields) {
-    if (log && typeof log[level] === "function") {
-      try { log[level](message, fields); } catch (_e) { /* logger best-effort */ }
-      return;
-    }
-    var line = "[blamejs:bundler] " + message + (fields ? " " + JSON.stringify(fields) : "");
-    if (level === "error" || level === "warn" || level === "fatal") console.error(line);
-    else console.log(line);
-  }
+  var _logVia = logModule.makeViaOrFallback(log, bootLog);
 
   async function build() {
     var t0 = Date.now();
@@ -350,16 +361,16 @@ function create(opts) {
 
   function _scheduleRebuild(reason, callback) {
     if (debounceTimer) {
-      try { clearTimeoutFn(debounceTimer); } catch (_e) {}
+      try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ }
     }
     debounceTimer = setTimeoutFn(function () {
       debounceTimer = null;
       _logVia("info", "rebuilding", { reason: reason });
       build().then(
-        function (r) { if (callback) try { callback(null, r); } catch (_e) {} },
+        function (r) { if (callback) try { callback(null, r); } catch (_e) { /* operator callback threw — logged elsewhere if material */ } },
         function (e) {
           _logVia("error", "rebuild failed", { error: (e && e.message) || String(e) });
-          if (callback) try { callback(e, null); } catch (_e) {}
+          if (callback) try { callback(e, null); } catch (_e) { /* operator callback threw — already logged */ }
         }
       );
     }, graceMs);
@@ -404,7 +415,7 @@ function create(opts) {
   async function close() {
     watching = false;
     if (debounceTimer) {
-      try { clearTimeoutFn(debounceTimer); } catch (_e) {}
+      try { clearTimeoutFn(debounceTimer); } catch (_e) { /* timer already cleared */ }
       debounceTimer = null;
     }
     for (var i = 0; i < watchers.length; i++) {

package/lib/cache-redis.js

@@ -33,9 +33,14 @@
  * is filtered against actual key existence — see invalidateTag below).
  */
 
+var C = require("./constants");
+var { boot } = require("./log");
 var redisClient = require("./redis-client");
+var safeJson = require("./safe-json");
 var { CacheError } = require("./framework-error");
 
+var log = boot("cache-redis");
+
 var _err = CacheError.factory;
 
 function _toStr(v) {
@@ -84,7 +89,7 @@ function create(cfg) {
     var s = _toStr(v);
     if (s === null) return undefined;
     var parsed;
-    try { parsed = JSON.parse(s); }
+    try { parsed = safeJson.parse(s, { maxBytes: C.BYTES.mib(64) }); }
     catch (_e) { return undefined; }
     // Sliding TTL: extend the entry's life on every read. Best-effort
     // (PEXPIREAT may race with delete; if it fails the operator just
@@ -216,7 +221,7 @@ function create(cfg) {
       } else {
         // Ghost — just SREM from this tag set + drop the reverse.
         try { await client.command("SREM", _tagKey(tag), keys[i]); }
-        catch (_e) {}
+        catch (e) { log.debug("invalidateTag-cleanup-failed", { op: "SREM", tag: tag, error: e.message }); }
       }
     }
     // Drop the tag set itself if it's now empty (or empty after the
@@ -224,7 +229,7 @@ function create(cfg) {
     var remaining = await client.command("SCARD", _tagKey(tag));
     if (Number(remaining) === 0) {
       try { await client.command("DEL", _tagKey(tag)); }
-      catch (_e) {}
+      catch (e) { log.debug("invalidateTag-cleanup-failed", { op: "DEL", tag: tag, error: e.message }); }
     }
     emitObs("cache.redis.invalidateTag", { namespace: namespace, tag: tag, dropped: dropped });
     return dropped;

package/lib/cache.js

@@ -85,15 +85,19 @@
  *     the application layer.
  */
 
+var cacheRedis = require("./cache-redis");
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+var { boot } = require("./log");
 var numericChecks = require("./numeric-checks");
 var requestHelpers = require("./request-helpers");
 var safeAsync = require("./safe-async");
+var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var { CacheError } = require("./framework-error");
 
+var log = boot("cache");
 var observability = lazyRequire(function () { return require("./observability"); });
 
 var _err = CacheError.factory;
@@ -101,7 +105,7 @@ var _err = CacheError.factory;
 var DEFAULTS = Object.freeze({
   backend:                 "memory",
   ttlMs:                   C.TIME.minutes(5),
-  maxEntries:              10000,
+  maxEntries:              C.BYTES.bytes(10000),
   maxBytes:                Infinity,
   sweepIntervalMs:         C.TIME.minutes(1),
   staleWhileRevalidate:    false,
@@ -148,7 +152,7 @@ function _defaultSizeOf(value) {
   if (value === null || value === undefined) return 0;
   if (Buffer.isBuffer(value)) return value.length;
   if (typeof value === "string") return Buffer.byteLength(value, "utf8");
-  if (typeof value === "number" || typeof value === "boolean") return 8;
+  if (typeof value === "number" || typeof value === "boolean") return C.BYTES.bytes(8);
   // Fallback: round-trip through JSON. Cost is real; documented in the
   // DEFAULTS docstring so operators with hot-path size accounting know
   // to supply their own sizeOf.
@@ -170,12 +174,8 @@ function _validateBackendObject(backend) {
 }
 
 function _validateCreateOpts(opts) {
-  if (!opts || typeof opts !== "object") {
-    throw _err("BAD_OPT", "cache.create: opts must be an object");
-  }
-  if (typeof opts.namespace !== "string" || opts.namespace.length === 0) {
-    throw _err("BAD_OPT", "cache.create: namespace must be a non-empty string (cache identity for observability + audit)");
-  }
+  validateOpts.requireObject(opts, "cache.create", CacheError);
+  validateOpts.requireNonEmptyString(opts.namespace, "cache.create: namespace", CacheError, "BAD_OPT");
   // Composite cluster-key separator is ":" — namespace must not contain it
   // or two namespaces could collide ("a:b" + "c" = "a:b:c" = "a" + "b:c").
   if (opts.namespace.indexOf(":") !== -1) {
@@ -200,41 +200,21 @@ function _validateCreateOpts(opts) {
   if (opts.ttlMs !== undefined) _validateTtl("cache.create: ttlMs", opts.ttlMs);
   if (opts.maxEntries !== undefined) _validateMaxEntries(opts.maxEntries);
   if (opts.maxBytes !== undefined) _validateMaxBytes(opts.maxBytes);
-  if (opts.sizeOf !== undefined && typeof opts.sizeOf !== "function") {
-    throw _err("BAD_OPT", "cache.create: sizeOf must be a function (value) → bytes");
-  }
-  if (opts.slidingTtl !== undefined && typeof opts.slidingTtl !== "boolean") {
-    throw _err("BAD_OPT", "cache.create: slidingTtl must be a boolean");
-  }
+  validateOpts.optionalFunction(opts.sizeOf, "cache.create: sizeOf", CacheError);
+  validateOpts.optionalBoolean(opts.slidingTtl, "cache.create: slidingTtl", CacheError);
   if (opts.sweepIntervalMs !== undefined) {
-    if (!_isFiniteNonNegative(opts.sweepIntervalMs) || opts.sweepIntervalMs < 1000) {
-      throw _err("BAD_OPT", "cache.create: sweepIntervalMs must be a finite number ≥ 1000ms, got " +
+    validateOpts.optionalFiniteNonNegative(opts.sweepIntervalMs, "cache.create: sweepIntervalMs", CacheError);
+    if (opts.sweepIntervalMs < C.TIME.seconds(1)) {
+      throw _err("BAD_OPT", "cache.create: sweepIntervalMs must be >= 1000ms, got " +
         JSON.stringify(opts.sweepIntervalMs));
     }
   }
-  if (opts.staleWhileRevalidate !== undefined && typeof opts.staleWhileRevalidate !== "boolean") {
-    throw _err("BAD_OPT", "cache.create: staleWhileRevalidate must be a boolean");
-  }
-  if (opts.auditFailures !== undefined && typeof opts.auditFailures !== "boolean") {
-    throw _err("BAD_OPT", "cache.create: auditFailures must be a boolean");
-  }
-  if (opts.auditClear !== undefined && typeof opts.auditClear !== "boolean") {
-    throw _err("BAD_OPT", "cache.create: auditClear must be a boolean");
-  }
-  if (opts.audit !== undefined && opts.audit !== null) {
-    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
-      throw _err("BAD_OPT", "cache.create: audit must be a b.audit-shaped object (safeEmit fn)");
-    }
-  }
-  if (opts.observability !== undefined && opts.observability !== null) {
-    if (typeof opts.observability !== "object" ||
-        typeof opts.observability.event !== "function") {
-      throw _err("BAD_OPT", "cache.create: observability must be a b.observability-shaped object (event fn)");
-    }
-  }
-  if (opts.clock !== undefined && typeof opts.clock !== "function") {
-    throw _err("BAD_OPT", "cache.create: clock must be a function");
-  }
+  validateOpts.optionalBoolean(opts.staleWhileRevalidate, "cache.create: staleWhileRevalidate", CacheError);
+  validateOpts.optionalBoolean(opts.auditFailures, "cache.create: auditFailures", CacheError);
+  validateOpts.optionalBoolean(opts.auditClear, "cache.create: auditClear", CacheError);
+  validateOpts.auditShape(opts.audit, "cache.create", CacheError);
+  validateOpts.observabilityShape(opts.observability, "cache.create", CacheError);
+  validateOpts.optionalFunction(opts.clock, "cache.create: clock", CacheError);
 }
 
 function _validateKey(key, ctx) {
@@ -505,7 +485,7 @@ function _clusterBackend(cfg) {
         [newExpires, now, _composedKey(key), now]
       ).catch(function () { /* best-effort */ });
     }
-    try { return JSON.parse(row.valueJson); }
+    try { return safeJson.parse(row.valueJson, { maxBytes: C.BYTES.mib(64) }); }
     catch (_e) { return undefined; }
   }
 
@@ -750,18 +730,19 @@ function create(opts) {
     "invalidationPubsub",
   ], "cache");
   _validateCreateOpts(opts);
+  var cfg0 = validateOpts.applyDefaults(opts, DEFAULTS);
 
   var namespace        = opts.namespace;
-  var backendKind      = opts.backend || DEFAULTS.backend;
-  var defaultTtlMs     = (opts.ttlMs            === undefined) ? DEFAULTS.ttlMs            : opts.ttlMs;
-  var maxEntries       = (opts.maxEntries       === undefined) ? DEFAULTS.maxEntries       : opts.maxEntries;
-  var maxBytes         = (opts.maxBytes         === undefined) ? DEFAULTS.maxBytes         : opts.maxBytes;
+  var backendKind      = cfg0.backend;
+  var defaultTtlMs     = cfg0.ttlMs;
+  var maxEntries       = cfg0.maxEntries;
+  var maxBytes         = cfg0.maxBytes;
   var sizeOf           = (typeof opts.sizeOf === "function") ? opts.sizeOf : _defaultSizeOf;
-  var sweepIntervalMs  = (opts.sweepIntervalMs  === undefined) ? DEFAULTS.sweepIntervalMs  : opts.sweepIntervalMs;
-  var staleRevalidate  = (opts.staleWhileRevalidate === undefined) ? DEFAULTS.staleWhileRevalidate : opts.staleWhileRevalidate;
-  var slidingTtl       = (opts.slidingTtl       === undefined) ? DEFAULTS.slidingTtl       : opts.slidingTtl;
-  var auditFailures    = (opts.auditFailures    === undefined) ? DEFAULTS.auditFailures    : opts.auditFailures;
-  var auditClear       = (opts.auditClear       === undefined) ? DEFAULTS.auditClear       : opts.auditClear;
+  var sweepIntervalMs  = cfg0.sweepIntervalMs;
+  var staleRevalidate  = cfg0.staleWhileRevalidate;
+  var slidingTtl       = cfg0.slidingTtl;
+  var auditFailures    = cfg0.auditFailures;
+  var auditClear       = cfg0.auditClear;
   var audit            = opts.audit || null;
   var operatorObs      = opts.observability || null;
   var clock            = opts.clock || function () { return Date.now(); };
@@ -786,11 +767,7 @@ function create(opts) {
     } catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
   }
 
-  function emitAudit(action, info) {
-    if (!audit) return;
-    try { audit.safeEmit(Object.assign({ action: action }, info || {})); }
-    catch (_e) { /* audit best-effort */ }
-  }
+  var emitAudit = validateOpts.makeAuditEmitter(audit);
 
   function _actor(callerOpts) {
     return requestHelpers.resolveActorWithOverride(callerOpts);
@@ -825,7 +802,6 @@ function create(opts) {
   } else if (backendKind === "cluster") {
     backend = _clusterBackend(cfg);
   } else if (backendKind === "redis") {
-    var cacheRedis = require("./cache-redis");
     backend = _customBackend(cacheRedis.create({
       namespace:             namespace,
       url:                   opts.redisUrl,
@@ -1171,11 +1147,14 @@ function create(opts) {
     try {
       if (ev.kind === "tag" && typeof ev.tag === "string" &&
           typeof backend.invalidateTag === "function") {
-        try { await backend.invalidateTag(ev.tag); } catch (_e) {}
+        try { await backend.invalidateTag(ev.tag); }
+        catch (e) { log.debug("invalidation-apply-failed", { op: "invalidateTag", tag: ev.tag, error: e.message }); }
       } else if (ev.kind === "del" && typeof ev.key === "string") {
-        try { await backend.del(ev.key); } catch (_e) {}
+        try { await backend.del(ev.key); }
+        catch (e) { log.debug("invalidation-apply-failed", { op: "del", key: ev.key, error: e.message }); }
       } else if (ev.kind === "clear") {
-        try { await backend.clear(); } catch (_e) {}
+        try { await backend.clear(); }
+        catch (e) { log.debug("invalidation-apply-failed", { op: "clear", error: e.message }); }
       }
       // Wipe local in-flight memoization so a freshly-invalidated key
       // can't resolve from a still-pending fetch on this node.
@@ -1195,7 +1174,8 @@ function create(opts) {
     if (closed) return;
     closed = true;
     if (invalidationPubsub && invalidationToken) {
-      try { invalidationPubsub.unsubscribe(invalidationToken); } catch (_e) {}
+      try { invalidationPubsub.unsubscribe(invalidationToken); }
+      catch (e) { log.debug("close-cleanup-failed", { op: "unsubscribe", error: e.message }); }
       invalidationToken = null;
     }
     inflight.clear();

package/lib/canonical-json.js

@@ -78,7 +78,10 @@ function _scrub(value, seen, bufferAs) {
   if (Array.isArray(value)) {
     return value.map(function (v) { return _scrub(v, seen, bufferAs); });
   }
-  var keys = Object.keys(value).sort();
+  // Canonical-json IS the destination for sorted-keys walks across the
+  // codebase; the keys-then-sort here is the canonical primitive itself.
+  var keys = Object.keys(value);
+  keys.sort();
   var out = {};
   for (var i = 0; i < keys.length; i++) {
     out[keys[i]] = _scrub(value[keys[i]], seen, bufferAs);
@@ -97,4 +100,16 @@ function stringify(value, opts) {
   return JSON.stringify(_scrub(value, null, bufferAs));
 }
 
-module.exports = { stringify: stringify };
+// Stable key ordering for an object — same lexicographic sort used by
+// the canonical-json walker. Exposed so call sites that need a sorted
+// key list (CLI report ordering, fingerprint inputs) route through
+// the framework's single source-of-truth ordering rule rather than
+// re-implementing the keys-then-sort dance inline.
+function sortKeys(obj) {
+  if (!obj || typeof obj !== "object") return [];
+  var keys = Object.keys(obj);
+  keys.sort();
+  return keys;
+}
+
+module.exports = { stringify: stringify, sortKeys: sortKeys };

package/lib/chain-writer.js

@@ -172,11 +172,11 @@ function create(opts) {
   async function _appendInsideMutex(logical) {
     var counter = _nextCounter++;
     var nowMs   = Date.now();
-    var nonce   = generateBytes(16);
+    var nonce   = generateBytes(C.BYTES.bytes(16));
 
     // Caller-supplied logical row: spread + add framework-managed fields.
     var fullLogical = Object.assign({}, logical, {
-      _id:               (logical && logical._id) || generateToken(16),
+      _id:               (logical && logical._id) || generateToken(C.BYTES.bytes(16)),
       recordedAt:        nowMs,
       monotonicCounter:  counter,
     });

package/lib/cli-helpers.js

@@ -47,8 +47,16 @@
  * spawning a child process.
  */
 
+var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 
+// lazyRequire the framework root so cli-helpers stays loadable in
+// contexts that aren't the framework root (tests, operator-side
+// scripts importing only cli-helpers). The first bootApp() call
+// resolves the framework module; subsequent calls reuse the cached
+// load.
+var blamejs = lazyRequire(function () { return require("../"); });
+
 // ---- Streams + exit-code-shaped reporting --------------------------------
 
 function _writeLine(stream, line) {
@@ -178,10 +186,7 @@ async function bootApp(opts) {
     vaultPassphrase = Buffer.from(raw, "utf8");
   }
 
-  // Late require so this module stays loadable in contexts that aren't
-  // the framework root (tests, operator-side scripts importing only
-  // cli-helpers).
-  var b = require("../");
+  var b = blamejs();
   var app = await b.createApp({
     dataDir: opts.dataDir,
     routes:  function () {},

package/lib/cli.js

@@ -41,17 +41,29 @@ var apiSnapshot = require("./api-snapshot");
 var auditChain = require("./audit-chain");
 var auditTools = require("./audit-tools");
 var backup = require("./backup");
+var canonicalJson = require("./canonical-json");
 var cliHelpers = require("./cli-helpers");
 var constants = require("./constants");
+var C = constants;
 var crypto = require("./crypto");
 var dev = require("./dev");
+var fileType = require("./file-type");
 var migrations = require("./migrations");
+var passwordModule = require("./auth/password");
 var requestHelpers = require("./request-helpers");
 var restore = require("./restore");
 var restoreBundle = require("./restore-bundle");
 var restoreRollback = require("./restore-rollback");
 var seeders = require("./seeders");
 var vaultPassphraseOps = require("./vault/passphrase-ops");
+var { defineClass } = require("./framework-error");
+
+var CliError = defineClass("CliError", { alwaysPermanent: true });
+
+// Maximum length for an operator-supplied --ignore regex pattern. Caps
+// ReDoS surface area: a multi-megabyte pattern compiled to a regex
+// would already be a footgun, so refuse anything beyond the cap.
+var MAX_IGNORE_PATTERN_LENGTH = 0x100;
 
 var DEFAULT_MIG_DIR = "./migrations";
 var DEFAULT_SEED_DIR = "./seeders";
@@ -363,7 +375,15 @@ async function _runDev(args, ctx) {
   }
   var argList   = _coerceList(args.flags.arg).map(String);
   var watchList = _coerceList(args.flags.watch).map(String);
-  var ignoreList = _coerceList(args.flags.ignore).map(function (s) { return new RegExp(String(s)); });
+  var ignoreList = _coerceList(args.flags.ignore).map(function (s) {
+    var str = String(s);
+    if (str.length > MAX_IGNORE_PATTERN_LENGTH) {
+      throw new CliError("cli/bad-ignore-pattern",
+        "blamejs dev: --ignore pattern exceeds max length " +
+        MAX_IGNORE_PATTERN_LENGTH + " (got " + str.length + ")");
+    }
+    return RegExp(str);
+  });
   var graceMs = args.flags["grace-ms"] !== undefined ? Number(args.flags["grace-ms"]) : undefined;
   if (graceMs !== undefined && (!Number.isFinite(graceMs) || graceMs < 0)) {
     _writeLine(ctx.stderr, "blamejs dev: --grace-ms must be a non-negative number");
@@ -1220,7 +1240,11 @@ async function _runBackup(args, ctx) {
         var kind = m.files[k].kind || "unknown";
         kinds[kind] = (kinds[kind] || 0) + 1;
       }
-      var ks = Object.keys(kinds).sort();
+      // Stable kind ordering for the human-readable report — same
+      // sort the framework's canonical-json walker uses for object
+      // keys. Pulled out as a sortKeys() helper so this single sorted
+      // walk in cli matches the canonical-json discipline elsewhere.
+      var ks = canonicalJson.sortKeys(kinds);
       for (var ki = 0; ki < ks.length; ki++) {
         report.write("  " + ks[ki] + ": " + kinds[ks[ki]]);
       }
@@ -1240,7 +1264,7 @@ async function _runBackup(args, ctx) {
 
   if (sub === "verify") {
     var stagingDir = path.join(os.tmpdir(),
-      "blamejs-backup-verify-" + crypto.generateToken(8));
+      "blamejs-backup-verify-" + crypto.generateToken(C.BYTES.bytes(8)));
     try {
       var r = await restoreBundle.extract({
         bundleDir:  bundleDir,
@@ -1836,7 +1860,6 @@ function _runFileType(args, ctx) {
   catch (e) {
     return report.error("read failed: " + ((e && e.message) || String(e)));
   }
-  var fileType = require("./file-type");
   if (args.flags.allowlist && args.flags.allowlist !== true) {
     var allowed = requestHelpers.parseListHeader(args.flags.allowlist);
     try {
@@ -1929,7 +1952,6 @@ async function _runPassword(args, ctx) {
     policyOpts.breachCheck = "haveibeenpwned";
     if (args.flags["fail-closed"]) policyOpts.failClosed = true;
   }
-  var passwordModule = require("./auth/password");
   var policy;
   try { policy = passwordModule.policy(policyOpts); }
   catch (e) { return report.error("bad policy: " + ((e && e.message) || String(e)), 2); }

package/lib/cluster-provider-db.js

@@ -45,6 +45,7 @@
  * Lease object shape:
  *   { nodeId, leaseId, acquiredAt, expiresAt, fencingToken, endpoint }
  */
+var C = require("./constants");
 var { generateToken } = require("./crypto");
 var externalDb = require("./external-db");
 var { ClusterProviderError } = require("./framework-error");
@@ -129,7 +130,7 @@ function create(config) {
       throw _err("INVALID_TTL", "leaseTtlMs must be a positive number", true);
     }
     var endpoint = (opts && opts.endpoint) || null;
-    var leaseId = generateToken(16);
+    var leaseId = generateToken(C.BYTES.bytes(16));
     var nowMs = Date.now();
     var expiresAt = nowMs + leaseTtlMs;