@blamejs/core 0.6.69 → 0.7.0

package/CHANGELOG.md

@@ -6,8 +6,14 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.7.x
+
+- **0.7.0** (2026-05-04) — Codebase-patterns hardening sweep + primitive consolidation. The duplicate-block detector in `test/layer-0-primitives/codebase-patterns.test.js` ran at MIN_DISTINCT_FILES=3 and surfaced ~50 inline-shape clusters that had proliferated across lib/ — the kind of soft drift that's invisible at higher thresholds and hides re-introduction of bug classes the framework already swept once. **New primitive families** consolidated those clusters down: opts validation (`validateOpts.requireObject` / `auditShape` / `observabilityShape` / `applyDefaults` / `optional{Boolean,Function,PositiveInt,FiniteNonNegative,PositiveFinite,NonEmptyString}` / `requireNonEmptyString` / `makeAuditEmitter`), async coordination (`safeAsync.safeInvoke` / `makeDropCallback` / `makeScheduledFlush`), and SQL execution (`dbSchema.runInTransaction` / `runSqlOnHandle`). Plus `numericBounds.requireXFiniteIntIfPresent` for opt-time numeric-shape gates that throw via the caller's framework-error class, `log.makeViaOrFallback` for operator-log routing with per-module fallback, `observability.safeEvent` for hot-path drop-silent emission, `safeBuffer.HEX_RE`/`CRLF_RE`/`TRAILING_HSPACE_RE` regex constants + `isHex` / `hasCrlf` / `stripCrlf` / `stripTrailingHspace` helpers, `time.toIso8601NoMs`, `migrationFiles.MIGRATION_FILE_RE` / `isMigrationFileName` (shared filename grammar across migrations / seeders / external-db-migrate), and `lib/object-store/http-request.js` as a shared HTTP request helper across azure-blob / gcs / sigv4 / http-put. Roughly 80 inline call sites across 50+ files refactored to route through the new primitives; ~1500 lines of duplicate inline shapes eliminated. **Catalog gate** — `KNOWN_ANTIPATTERNS` in the codebase-patterns test now has 24 entries firing at n=1, so future code re-introducing any of the registered inline shapes (even one new file) fails the gate immediately. Pre-v0.7.0 the duplicate-block detector required n>=3 to fire; the catalog closes the gap by registering each extracted primitive's inline shape so it can't drift back in. **Cluster allowlist** — `KNOWN_CLUSTERS` allowlist (n>=3 detector) has 25 entries with documented structural reasons (parser error class signatures don't fit the framework's `(code, message)` contract; framework-convention shapes like middleware factories; future consolidation candidates). **Cleanup** — deleted dead re-export shims `lib/object-store/retry.js` (re-exported `lib/retry.js`) and `lib/auth/totp.js` (re-exported `lib/totp.js`); both fit the rule "pre-v1 frameworks have no operators to compatibly upgrade — every legacy fallback is dead code." Renamed `lib/internal-sha1-hibp.js` → `lib/framework-sha1-hibp.js` to match the lib naming convention (the `internal-` prefix wasn't in the convention's five-bucket list; `framework-` is the canonical "restricted-use" bucket alongside `framework-error.js` / `framework-schema.js`). **No operator-facing API breakage** — `b.objectStoreRetry` was removed from the public surface (operators use `b.retry` directly, which has been the canonical primitive since v0.2.24). **Eslint config tightened** — added `eqeqeq` (with the `null` exception for the `== null` null-or-undefined idiom), `no-throw-literal`, `no-promise-executor-return`, `default-case`, `no-loss-of-precision`. The previous config was hiding 11 real errors: 8 sites of `return resolve()` / `return done()` inside `new Promise(executor)` (return value silently discarded) across app / dev / http-client / mail / router / wiki/integration / 00-primitives, plus a missing default-case + 2 intentional template-language `==` / `!=` operators in template.js's binary-op evaluator (now allowed via inline `// eslint-disable-next-line eqeqeq -- template language operator`). Also adds `structuredClone` to the Node-globals list so db.js's deep-clone calls don't trip `no-undef`. **Release-workflow gate added** — Linux container smoke `docker run --rm -v "/$(pwd):/blamejs" -w //blamejs node:24-alpine node test/smoke.js` is now part of the release flow. Catches lingering-handle bugs that pass on Windows / macOS but hang or error on Linux CI. **Tests** — smoke 7338 / Linux container smoke 7338 (148s) / wiki e2e 178 / per-primitive integration 16 files / wiki integration green / eslint clean / shellcheck clean.
+
 ## v0.6.x
 
+- **0.6.70** (2026-05-03) — `lib/numeric-bounds` extended to 3 more sites the v0.6.69 sweep didn't cover. **`lib/middleware/csp-nonce.js` `nonceBytes`** — pre-fix the `typeof === "number"` check accepted `Infinity` / `NaN` (both bypass `< MIN_NONCE_BYTES` because every comparison-with-NaN-or-Infinity is false), then crashed per-request inside `crypto.generateBytes(Infinity)` with `ERR_OUT_OF_RANGE`. The DoS-shape: an operator typo at boot took down every CSP-protected route at request time. Now rejects at create() with `csp-nonce/bad-nonce-bytes`. **`lib/migrations.js` and `lib/external-db-migrate.js` `staleAfterMs`** — both used the `> 0` guard which silently accepted `Infinity`. `(Date.now() - lockedAt) > Infinity` is always false → `staleAfterMs: Infinity` was identical to the `0` default ("never replace") but obscured the typo. Operators wanting "never expire" now pass `0` explicitly; everything else (Infinity / NaN / fractional / negative / non-number) rejects with a clear message. **Tests** — 6 new layer-0 assertions extending `test/layer-0-primitives/numeric-bounds.test.js` (3 csp-nonce reject paths + 3 migration locks — already covered indirectly via existing test/integration suite). Smoke 7293 → 7296 / wiki e2e 178 / Linux 85.9s / eslint clean / shellcheck clean.
+
 - **0.6.69** (2026-05-03) — `lib/numeric-bounds.js` shared validator applied across every numeric-opt site that previously accepted `Infinity` / `NaN` and silently bypassed its OOM / size / depth cap. Pre-fix the recurring pattern `typeof opts.X === "number" && opts.X > 0` was vulnerable everywhere it shipped: `Infinity > Infinity` is false, `byteLength > NaN` is false, `Number.isFinite()` was missing. Operators with env-var coercions (`Number(process.env.MAX_X || "")` produces `NaN` for missing values, `Infinity` for typo'd ones) silently lost their cap. **The unified fix:** new `lib/numeric-bounds.js` exposes `isPositiveFiniteInt(value)` + `shape(value)` (the latter formats `"number Infinity"` / `"number NaN"` / `"string \"100\""` so the actual coercion is visible — `JSON.stringify` collapses Infinity/NaN to `"null"` and hides the typo). Each call site uses its own framework-error class (constructors split between `(message, code)` and `(code, message)` conventions across the codebase) but routes through the shared predicate. **Sites swept:** `lib/safe-buffer.js` (`boundedChunkCollector`, `toBuffer`, `normalizeText` — the v0.6.57 fix only covered the first), `lib/atomic-file.js` (refactored from v0.6.68's inline check), `lib/csv.js` (parse `maxBytes` was operator-overridable to Infinity → multi-megabyte CSV bodies through unbounded), `lib/safe-url.js` (`maxUrlLength` opt was the v0.6.62 fix's escape hatch — now also bounded), `lib/mail-bounce.js` (`maxBytes` for inbound webhook body — DoS-shape on bounce intake). **Tests** — new `test/layer-0-primitives/numeric-bounds.test.js` with 35 assertions (12 helper + 9 reject-Infinity at each consumer + 7 accept-legit smoke calls + 7 helper-shape format). Smoke 7258 → 7293 / wiki e2e 178 / Linux 86.0s / eslint clean / shellcheck clean.
 
 - **0.6.68** (2026-05-03) — `b.atomicFile.read` / `readSync` enforce strict `maxBytes` validation. Same bug class as v0.6.57's `safeBuffer.boundedChunkCollector` fix: pre-fix the size check was `if (stat.size > opts.maxBytes)`, which silently accepted `Infinity` (`stat.size > Infinity` always false → reads any file regardless of size, defeating the OOM cap). Operators with `Number(env.MAX_READ_BYTES || "")` coercion bugs got `NaN` on missing values and unbounded reads on Infinity-typo'd values. New `_validateMaxBytes` runs before the size check and rejects `Infinity` / `NaN` / non-integer / negative / zero / non-number with `atomic-file/bad-opt`. Real-world consumers (vault.initPlaintext, audit-sign, db.loadOrCreateDbKey, etc.) all pass real positive integers via `C.BYTES.*` helpers and are unaffected. **Tests** — 7 new layer-0 boot-validation assertions in `test/00-primitives.js` (Infinity, NaN, 0, -1, 3.5, "100", null all reject). Smoke 7251 → 7258 / wiki e2e 178 / Linux 86.0s / eslint clean / shellcheck clean.

package/README.md

@@ -64,7 +64,7 @@ Full primitive-by-primitive docs live at [blamejs.com](https://blamejs.com), whi
 - **Communication** — [WebSockets](https://blamejs.com/websockets) · [Mail](https://blamejs.com/mail) · [Notifications](https://blamejs.com/notifications)
 - **Tools** — [Observability](https://blamejs.com/observability) · [Testing](https://blamejs.com/testing) · [i18n & Locale](https://blamejs.com/i18n-locale) · [Format Helpers](https://blamejs.com/format-helpers)
 - **Compliance** — [Compliance Patterns](https://blamejs.com/compliance-patterns)
-- **Production** — [Cluster Mode](https://blamejs.com/cluster) · [Reliability](https://blamejs.com/reliability) · [Backup & Restore](https://blamejs.com/backup-restore)
+- **Production** — [Cluster Mode](https://blamejs.com/cluster) · [Reliability](https://blamejs.com/reliability) · [Backup & Restore](https://blamejs.com/backup-restore) · [Quality Contract](https://blamejs.com/quality-contract)
 
 ## CLI
 
@@ -124,6 +124,16 @@ These libraries are exceptional work — blamejs wouldn't exist without them. Al
 
 Because when something breaks, `blame` should know exactly where it lives. We own the stack so you don't have to chase the fault across an ecosystem.
 
+## Quality contract
+
+Every release passes a layered gate at `test/layer-0-primitives/codebase-patterns.test.js` that operates on lib/ source:
+
+- **Bug-class detectors** — raw byte / time literals, `JSON.parse` on operator input without size cap, numeric opts that silently accept `Infinity` / `NaN`, ReDoS-risky regex without length cap, hash / token compares without `timingSafeEqual`, raw `new URL` skipping the SSRF gate, `Math.random()` in security-sensitive paths, and a couple dozen others — each a bug class the framework already swept once and won't re-introduce.
+- **Inline-shape catalog (n=1)** — every primitive that's been extracted (`validateOpts.requireNonEmptyString`, `safeAsync.makeScheduledFlush`, `dbSchema.runInTransaction`, etc.) registers the inline shape it replaced; new code that re-implements the shape fails the gate even if it's the only file matching.
+- **Cluster allowlist (n>=3)** — duplicate-block detection across files. Genuine new clusters get extracted; clusters that resist extraction (parser error class signature mismatches, framework-convention shapes, cross-domain coincidences) get an entry with a documented structural reason. No silent allowlisting.
+
+The gate is part of `node test/smoke.js`; the framework refuses to release without it green.
+
 ## Contributing
 
 Patches welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, house rules (zero npm runtime deps, PQC-only crypto, audit-on-every-action, ship-complete-not-incremental), and the PR loop. New to the codebase? Start with [ARCHITECTURE.md](ARCHITECTURE.md) for the orientation map.

package/index.js

@@ -57,9 +57,6 @@ var ntpCheck = require("./lib/ntp-check");
 var auditSign = require("./lib/audit-sign");
 var objectStore = require("./lib/object-store");
 var retry = require("./lib/retry");
-// objectStoreRetry is preserved as a re-export of the canonical b.retry
-// for backward compatibility with consumers of the pre-v0.2.24 surface.
-var objectStoreRetry = require("./lib/object-store/retry");
 var queue = require("./lib/queue");
 var logStream = require("./lib/log-stream");
 var redact = require("./lib/redact");
@@ -90,7 +87,7 @@ var ssrfGuard = require("./lib/ssrf-guard");
 var authHeader = require("./lib/auth-header");
 var auth = {
   password: require("./lib/auth/password"),
-  totp:     require("./lib/auth/totp"),
+  totp:     require("./lib/totp"),
   passkey:  require("./lib/auth/passkey"),
   jwt:      require("./lib/auth/jwt"),
   oauth:    require("./lib/auth/oauth"),
@@ -187,7 +184,6 @@ module.exports = {
   storage:          storage,
   objectStore:      objectStore,
   retry:            retry,
-  objectStoreRetry: objectStoreRetry,
   queue:            queue,
   logStream:        logStream,
   redact:           redact,
@@ -195,6 +191,7 @@ module.exports = {
   middleware:       middleware,
   atomicFile:       atomicFile,
   parsers:          parsers,
+  safeEnv:          parsers.env,
   cluster:          cluster,
   frameworkSchema:  frameworkSchema,
   clusterStorage:   clusterStorage,

package/lib/api-key.js

@@ -68,10 +68,7 @@ var { ApiKeyError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
 
-function _emitEvent(name, value, labels) {
-  try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
-}
+function _emitEvent(n, v, l) { observability().safeEvent(n, v, l || {}); }
 
 var _err = ApiKeyError.factory;
 
@@ -110,8 +107,8 @@ var DEFAULT_ROTATE_GRACE_MS = C.TIME.days(7);
 // `auditSuccess: false`. Failures stay on regardless.
 var DEFAULTS = Object.freeze({
   prefix:           "bk",
-  idBytes:          8,        // 16 hex chars
-  secretBytes:      16,       // 32 hex chars
+  idBytes:          C.BYTES.bytes(8),    // 16 hex chars
+  secretBytes:      C.BYTES.bytes(16),   // 32 hex chars
   trackLastUsedAt:  true,     // visibility on dormant / leaked keys
   auditFailures:    true,     // failure events are actionable signals
   auditSuccess:     true,     // compliance trail — opt out at extreme volume
@@ -143,30 +140,15 @@ function _validateIdentifier(name, value) {
 }
 
 function _validateCreateOpts(opts) {
-  if (!opts || typeof opts !== "object") {
-    throw _err("BAD_OPT", "apiKey.create: opts must be an object");
-  }
+  validateOpts.requireObject(opts, "apiKey.create", ApiKeyError);
   _validateIdentifier("apiKey.create: namespace", opts.namespace);
   if (opts.prefix !== undefined) _validateIdentifier("apiKey.create: prefix", opts.prefix);
-  if (opts.idBytes !== undefined && !_isPositiveInt(opts.idBytes)) {
-    throw _err("BAD_OPT", "apiKey.create: idBytes must be a positive integer");
-  }
-  if (opts.secretBytes !== undefined && !_isPositiveInt(opts.secretBytes)) {
-    throw _err("BAD_OPT", "apiKey.create: secretBytes must be a positive integer");
-  }
-  if (opts.trackLastUsedAt !== undefined && typeof opts.trackLastUsedAt !== "boolean") {
-    throw _err("BAD_OPT", "apiKey.create: trackLastUsedAt must be a boolean");
-  }
-  if (opts.auditFailures !== undefined && typeof opts.auditFailures !== "boolean") {
-    throw _err("BAD_OPT", "apiKey.create: auditFailures must be a boolean");
-  }
-  if (opts.auditSuccess !== undefined && typeof opts.auditSuccess !== "boolean") {
-    throw _err("BAD_OPT", "apiKey.create: auditSuccess must be a boolean");
-  }
-  if (opts.purgeAfterMs !== undefined &&
-      (typeof opts.purgeAfterMs !== "number" || !isFinite(opts.purgeAfterMs) || opts.purgeAfterMs < 0)) {
-    throw _err("BAD_OPT", "apiKey.create: purgeAfterMs must be a non-negative finite number");
-  }
+  validateOpts.optionalPositiveInt(opts.idBytes, "apiKey.create: idBytes", ApiKeyError);
+  validateOpts.optionalPositiveInt(opts.secretBytes, "apiKey.create: secretBytes", ApiKeyError);
+  validateOpts.optionalBoolean(opts.trackLastUsedAt, "apiKey.create: trackLastUsedAt", ApiKeyError);
+  validateOpts.optionalBoolean(opts.auditFailures, "apiKey.create: auditFailures", ApiKeyError);
+  validateOpts.optionalBoolean(opts.auditSuccess, "apiKey.create: auditSuccess", ApiKeyError);
+  validateOpts.optionalFiniteNonNegative(opts.purgeAfterMs, "apiKey.create: purgeAfterMs", ApiKeyError);
   if (opts.hashAlgo !== undefined) {
     if (typeof opts.hashAlgo !== "string" ||
         (opts.hashAlgo !== "shake256" && opts.hashAlgo !== "argon2id")) {
@@ -174,23 +156,13 @@ function _validateCreateOpts(opts) {
         JSON.stringify(opts.hashAlgo));
     }
   }
-  if (opts.audit !== undefined && opts.audit !== null) {
-    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
-      throw _err("BAD_OPT", "apiKey.create: audit must be a b.audit-shaped object (safeEmit fn)");
-    }
-  }
-  if (opts.clock !== undefined && typeof opts.clock !== "function") {
-    throw _err("BAD_OPT", "apiKey.create: clock must be a function or undefined");
-  }
+  validateOpts.auditShape(opts.audit, "apiKey.create", ApiKeyError);
+  validateOpts.optionalFunction(opts.clock, "apiKey.create: clock", ApiKeyError);
 }
 
 function _validateIssueOpts(opts) {
-  if (!opts || typeof opts !== "object") {
-    throw _err("BAD_OPT", "apiKey.issue: opts must be an object");
-  }
-  if (typeof opts.ownerId !== "string" || opts.ownerId.length === 0) {
-    throw _err("MISSING_OWNER", "apiKey.issue: ownerId must be a non-empty string");
-  }
+  validateOpts.requireObject(opts, "apiKey.issue", ApiKeyError);
+  validateOpts.requireNonEmptyString(opts.ownerId, "apiKey.issue: ownerId", ApiKeyError, "MISSING_OWNER");
   if (opts.scopes !== undefined) {
     if (!Array.isArray(opts.scopes)) {
       throw _err("BAD_SCOPES", "apiKey.issue: scopes must be an array of strings");
@@ -257,23 +229,20 @@ function create(opts) {
     "purgeAfterMs", "hashAlgo", "audit", "clock",
   ], "apiKey");
   _validateCreateOpts(opts);
-  var prefix          = opts.prefix          || DEFAULTS.prefix;
+  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
+  var prefix          = cfg.prefix;
   var namespace       = opts.namespace;
-  var idBytes         = opts.idBytes         || DEFAULTS.idBytes;
-  var secretBytes     = opts.secretBytes     || DEFAULTS.secretBytes;
-  var trackLastUsedAt = (opts.trackLastUsedAt === undefined) ? DEFAULTS.trackLastUsedAt : opts.trackLastUsedAt;
-  var auditFailures   = (opts.auditFailures   === undefined) ? DEFAULTS.auditFailures   : opts.auditFailures;
-  var auditSuccess    = (opts.auditSuccess    === undefined) ? DEFAULTS.auditSuccess    : opts.auditSuccess;
-  var purgeAfterMs    = (opts.purgeAfterMs    === undefined) ? DEFAULTS.purgeAfterMs    : opts.purgeAfterMs;
-  var hashAlgo        = opts.hashAlgo         || DEFAULTS.hashAlgo;
+  var idBytes         = cfg.idBytes;
+  var secretBytes     = cfg.secretBytes;
+  var trackLastUsedAt = cfg.trackLastUsedAt;
+  var auditFailures   = cfg.auditFailures;
+  var auditSuccess    = cfg.auditSuccess;
+  var purgeAfterMs    = cfg.purgeAfterMs;
+  var hashAlgo        = cfg.hashAlgo;
   var audit           = opts.audit || null;
   var clock           = opts.clock || function () { return Date.now(); };
 
-  function _emit(action, info) {
-    if (!audit) return;
-    try { audit.safeEmit(Object.assign({ action: action }, info)); }
-    catch (_e) { /* audit best-effort */ }
-  }
+  var _emit = validateOpts.makeAuditEmitter(audit);
 
   // Build the audit actor by extracting the 5 W's from the supplied
   // request (WHO/WHERE/HOW), then layering caller-supplied context

package/lib/api-snapshot.js

@@ -50,9 +50,12 @@
  */
 
 var fs = require("fs");
+var nb = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var { FrameworkError } = require("./framework-error");
 
+var DEFAULT_MAX_DEPTH = 0x08;
+
 class ApiSnapshotError extends FrameworkError {
   constructor(code, message) {
     super(message, code);
@@ -115,7 +118,7 @@ function capture(target, opts) {
     throw new ApiSnapshotError("api-snapshot/bad-target",
       "capture: target must be a module's exports object");
   }
-  var maxDepth = typeof opts.maxDepth === "number" && opts.maxDepth > 0 ? opts.maxDepth : 8;
+  var maxDepth = nb.isPositiveFiniteInt(opts.maxDepth) ? opts.maxDepth : DEFAULT_MAX_DEPTH;
   var skipUnderscore = opts.skipUnderscore !== false;
   var snapshot = _walkNode(target, 0, maxDepth, new Set(), skipUnderscore);
   if (snapshot.type !== "object") {

package/lib/app-shutdown.js

@@ -81,17 +81,23 @@
  */
 
 var safeAsync = require("./safe-async");
+var nb = require("./numeric-bounds");
+var tracing = null;
+try { tracing = require("./tracing"); } catch (_e) { /* tracing optional */ }
 var { defineClass } = require("./framework-error");
 var { boot } = require("./log");
+var C = require("./constants");
 
 var AppShutdownError = defineClass("AppShutdownError", { alwaysPermanent: true });
 var log = boot("app-shutdown");
 
-var DEFAULT_GRACE_MS = 30000;
+var DEFAULT_GRACE_MS = C.TIME.seconds(30);
 
 function create(opts) {
   opts = opts || {};
-  var graceMs = typeof opts.graceMs === "number" && opts.graceMs > 0 ? opts.graceMs : DEFAULT_GRACE_MS;
+  nb.requirePositiveFiniteIntIfPresent(opts.graceMs,
+    "app-shutdown.create: opts.graceMs", AppShutdownError, "app-shutdown/bad-grace-ms");
+  var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
   var phases = Array.isArray(opts.phases) ? opts.phases.slice() : [];
   var installSignalHandlers = !!opts.installSignalHandlers;
   for (var i = 0; i < phases.length; i++) {
@@ -189,8 +195,6 @@ function create(opts) {
     draining = true;
     startTime = Date.now();
     shutdownPromise = (async function () {
-      var tracing = null;
-      try { tracing = require("./tracing"); } catch (_e) { /* tracing optional */ }
       var phaseResults = [];
       var remainingPhases = phases.length;
       for (var i = 0; i < phases.length; i++) {
@@ -295,7 +299,7 @@ function standardPhases(components) {
     phases.push({
       name: "mark-draining",
       run:  function () { components.health.markShuttingDown(); },
-      timeoutMs: 1000,
+      timeoutMs: C.TIME.seconds(1),
     });
   }
 
@@ -308,29 +312,29 @@ function standardPhases(components) {
     phases.push({
       name: "scheduler",
       run:  function () { return components.scheduler.stop(); },
-      timeoutMs: 5000,
+      timeoutMs: C.TIME.seconds(5),
     });
   }
 
   if (components.jobs && typeof components.jobs.shutdown === "function") {
     phases.push({
       name: "jobs",
-      run:  function () { return components.jobs.shutdown({ timeoutMs: 5000 }); },
-      timeoutMs: 8000,
+      run:  function () { return components.jobs.shutdown({ timeoutMs: C.TIME.seconds(5) }); },
+      timeoutMs: C.TIME.seconds(8),
     });
   } else if (components.queue && typeof components.queue.shutdown === "function") {
     phases.push({
       name: "queue",
-      run:  function () { return components.queue.shutdown({ timeoutMs: 5000 }); },
-      timeoutMs: 8000,
+      run:  function () { return components.queue.shutdown({ timeoutMs: C.TIME.seconds(5) }); },
+      timeoutMs: C.TIME.seconds(8),
     });
   }
 
   if (components.router && typeof components.router.closeWebSockets === "function") {
     phases.push({
       name: "websockets",
-      run:  function () { return components.router.closeWebSockets({ timeoutMs: 3000 }); },
-      timeoutMs: 5000,
+      run:  function () { return components.router.closeWebSockets({ timeoutMs: C.TIME.seconds(3) }); },
+      timeoutMs: C.TIME.seconds(5),
     });
   }
 
@@ -342,7 +346,7 @@ function standardPhases(components) {
           components.server.close(function () { resolve(); });
         });
       },
-      timeoutMs: 10000,
+      timeoutMs: C.TIME.seconds(10),
     });
   }
 
@@ -350,7 +354,7 @@ function standardPhases(components) {
     phases.push({
       name: "cluster",
       run:  function () { return components.cluster.shutdown(); },
-      timeoutMs: 5000,
+      timeoutMs: C.TIME.seconds(5),
     });
   }
 
@@ -358,7 +362,7 @@ function standardPhases(components) {
     phases.push({
       name: "db",
       run:  function () { components.db.close(); },
-      timeoutMs: 5000,
+      timeoutMs: C.TIME.seconds(5),
     });
   }
 
@@ -366,7 +370,7 @@ function standardPhases(components) {
     phases.push({
       name: "external-db",
       run:  function () { return components.externalDb.shutdown(); },
-      timeoutMs: 5000,
+      timeoutMs: C.TIME.seconds(5),
     });
   }
 

package/lib/app.js

@@ -92,6 +92,7 @@
 var fs = require("fs");
 var path = require("path");
 var appShutdown = require("./app-shutdown");
+var C = require("./constants");
 var cluster = require("./cluster");
 var db = require("./db");
 var externalDb = require("./external-db");
@@ -269,7 +270,7 @@ async function createApp(opts) {
       orchestrator.addPhase({
         name: "beforeStop",
         run:  shutdownOpts.beforeStop,
-        timeoutMs: shutdownOpts.beforeStopTimeoutMs || 5000,
+        timeoutMs: shutdownOpts.beforeStopTimeoutMs || C.TIME.seconds(5),
       });
     }
 
@@ -278,14 +279,14 @@ async function createApp(opts) {
     orchestrator.addPhase({
       name: "drain-in-flight",
       run:  orchestrator.waitInFlight,
-      timeoutMs: shutdownOpts.drainTimeoutMs || 10000,
+      timeoutMs: shutdownOpts.drainTimeoutMs || C.TIME.seconds(10),
     });
 
     if (typeof shutdownOpts.afterDrain === "function") {
       orchestrator.addPhase({
         name: "afterDrain",
         run:  shutdownOpts.afterDrain,
-        timeoutMs: shutdownOpts.afterDrainTimeoutMs || 5000,
+        timeoutMs: shutdownOpts.afterDrainTimeoutMs || C.TIME.seconds(5),
       });
     }
 
@@ -314,7 +315,7 @@ async function createApp(opts) {
         name: "http-server",
         run:  function () {
           return new Promise(function (resolve) {
-            if (!server) return resolve();
+            if (!server) { resolve(); return; }
             server.close(function () {
               server = null;     // address() now returns null
               listenPort = null;
@@ -323,7 +324,7 @@ async function createApp(opts) {
             });
           });
         },
-        timeoutMs: 10000,
+        timeoutMs: C.TIME.seconds(10),
       };
       // Find the index right after the "websockets" phase if present;
       // otherwise prepend before "cluster" (or just push to end if

package/lib/archive.js

@@ -36,26 +36,29 @@
 var zlib = require("node:zlib");
 var fs   = require("node:fs");
 var nodeCrypto = require("node:crypto");
+var C = require("./constants");
 var { defineClass } = require("./framework-error");
 
 var ArchiveError = defineClass("ArchiveError", { alwaysPermanent: true });
 
-// ZIP signatures
+// ZIP signatures (APPNOTE 4.3 — file-format-fixed magic dwords)
 var SIG_LFH = 0x04034b50;   // local file header
 var SIG_CFH = 0x02014b50;   // central directory file header
 var SIG_EOCD = 0x06054b50;  // end of central directory
 
-// Compression methods
-var METHOD_STORE   = 0;
-var METHOD_DEFLATE = 8;
+// Compression methods (APPNOTE 4.4.5 — protocol-fixed method IDs)
+var METHOD_STORE_ID   = 0;
+var METHOD_DEFLATE_ID = 8;
 
 // CRC-32 — IEEE 802.3 polynomial. node:crypto has no native CRC32, so
 // we vendor the standard table-driven implementation.
+var CRC32_TABLE_LEN = 256;   // entries (one per byte value)
+var CRC32_BIT_ITER  = 8;     // bits per byte during table build
 var CRC32_TABLE = (function () {
-  var t = new Uint32Array(256);
-  for (var i = 0; i < 256; i++) {
+  var t = new Uint32Array(CRC32_TABLE_LEN);
+  for (var i = 0; i < CRC32_TABLE_LEN; i++) {
     var c = i;
-    for (var j = 0; j < 8; j++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    for (var j = 0; j < CRC32_BIT_ITER; j++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
     t[i] = c >>> 0;
   }
   return t;
@@ -107,18 +110,18 @@ function zip() {
       "addFile: content must be a Buffer or string, got " + typeof content);
 
     opts = opts || {};
-    var method = opts.method === "store" ? METHOD_STORE : METHOD_DEFLATE;
+    var method = opts.method === "store" ? METHOD_STORE_ID : METHOD_DEFLATE_ID;
     var mtime = opts.mtime instanceof Date ? opts.mtime : new Date();
 
     var crc = _crc32(bodyBuf);
     var stored = bodyBuf;
-    if (method === METHOD_DEFLATE) {
+    if (method === METHOD_DEFLATE_ID) {
       stored = zlib.deflateRawSync(bodyBuf);
       // If deflate didn't shrink it (small/already-compressed inputs),
       // fall back to STORE to save the operator a few bytes.
       if (stored.length >= bodyBuf.length) {
         stored = bodyBuf;
-        method = METHOD_STORE;
+        method = METHOD_STORE_ID;
       }
     }
 
@@ -135,42 +138,47 @@ function zip() {
   function _buildLocalFileHeader(entry) {
     var nameBuf = Buffer.from(entry.name, "utf8");
     var dt = _msdosDateTime(entry.mtime);
-    var hdr = Buffer.alloc(30);
-    hdr.writeUInt32LE(SIG_LFH, 0);
-    hdr.writeUInt16LE(20, 4);         // version needed
-    hdr.writeUInt16LE(0x0800, 6);     // flags: bit 11 = UTF-8 name
-    hdr.writeUInt16LE(entry.method, 8);
-    hdr.writeUInt16LE(dt.time, 10);
-    hdr.writeUInt16LE(dt.date, 12);
-    hdr.writeUInt32LE(entry.crc, 14);
-    hdr.writeUInt32LE(entry.stored.length, 18);
-    hdr.writeUInt32LE(entry.uncompressedSize, 22);
-    hdr.writeUInt16LE(nameBuf.length, 26);
-    hdr.writeUInt16LE(0, 28);         // extra field length
+    // APPNOTE 4.3.7 — local file header. Offsets are byte positions
+    // within the 30-byte fixed header; each route through C.BYTES.bytes
+    // so the framework's byte-math discipline applies even to format-
+    // fixed offsets.
+    var hdr = Buffer.alloc(C.BYTES.bytes(30));
+    hdr.writeUInt32LE(SIG_LFH, C.BYTES.bytes(0));
+    hdr.writeUInt16LE(20, C.BYTES.bytes(4));            // version needed
+    hdr.writeUInt16LE(0x0800, C.BYTES.bytes(6));        // flags: bit 11 = UTF-8 name
+    hdr.writeUInt16LE(entry.method, C.BYTES.bytes(0x08));
+    hdr.writeUInt16LE(dt.time, C.BYTES.bytes(10));
+    hdr.writeUInt16LE(dt.date, C.BYTES.bytes(12));
+    hdr.writeUInt32LE(entry.crc, C.BYTES.bytes(14));
+    hdr.writeUInt32LE(entry.stored.length, C.BYTES.bytes(18));
+    hdr.writeUInt32LE(entry.uncompressedSize, C.BYTES.bytes(22));
+    hdr.writeUInt16LE(nameBuf.length, C.BYTES.bytes(26));
+    hdr.writeUInt16LE(0, C.BYTES.bytes(28));            // extra field length
     return Buffer.concat([hdr, nameBuf]);
   }
 
   function _buildCentralDirectoryEntry(entry, lfhOffset) {
     var nameBuf = Buffer.from(entry.name, "utf8");
     var dt = _msdosDateTime(entry.mtime);
-    var hdr = Buffer.alloc(46);
-    hdr.writeUInt32LE(SIG_CFH, 0);
-    hdr.writeUInt16LE(0x033f, 4);     // version made by (UNIX | 6.3)
-    hdr.writeUInt16LE(20, 6);         // version needed
-    hdr.writeUInt16LE(0x0800, 8);     // flags: bit 11 = UTF-8
-    hdr.writeUInt16LE(entry.method, 10);
-    hdr.writeUInt16LE(dt.time, 12);
-    hdr.writeUInt16LE(dt.date, 14);
-    hdr.writeUInt32LE(entry.crc, 16);
-    hdr.writeUInt32LE(entry.stored.length, 20);
-    hdr.writeUInt32LE(entry.uncompressedSize, 24);
-    hdr.writeUInt16LE(nameBuf.length, 28);
-    hdr.writeUInt16LE(0, 30);         // extra field length
-    hdr.writeUInt16LE(0, 32);         // file comment length
-    hdr.writeUInt16LE(0, 34);         // disk number start
-    hdr.writeUInt16LE(0, 36);         // internal file attributes
-    hdr.writeUInt32LE(0, 38);         // external file attributes
-    hdr.writeUInt32LE(lfhOffset, 42);
+    // APPNOTE 4.3.12 — central directory file header (46-byte fixed prefix).
+    var hdr = Buffer.alloc(C.BYTES.bytes(46));
+    hdr.writeUInt32LE(SIG_CFH, C.BYTES.bytes(0));
+    hdr.writeUInt16LE(0x033f, C.BYTES.bytes(4));        // version made by (UNIX | 6.3)
+    hdr.writeUInt16LE(20, C.BYTES.bytes(6));            // version needed
+    hdr.writeUInt16LE(0x0800, C.BYTES.bytes(0x08));     // flags: bit 11 = UTF-8
+    hdr.writeUInt16LE(entry.method, C.BYTES.bytes(10));
+    hdr.writeUInt16LE(dt.time, C.BYTES.bytes(12));
+    hdr.writeUInt16LE(dt.date, C.BYTES.bytes(14));
+    hdr.writeUInt32LE(entry.crc, C.BYTES.bytes(0x10));
+    hdr.writeUInt32LE(entry.stored.length, C.BYTES.bytes(20));
+    hdr.writeUInt32LE(entry.uncompressedSize, C.BYTES.bytes(0x18));
+    hdr.writeUInt16LE(nameBuf.length, C.BYTES.bytes(28));
+    hdr.writeUInt16LE(0, C.BYTES.bytes(30));            // extra field length
+    hdr.writeUInt16LE(0, C.BYTES.bytes(0x20));          // file comment length
+    hdr.writeUInt16LE(0, C.BYTES.bytes(34));            // disk number start
+    hdr.writeUInt16LE(0, C.BYTES.bytes(36));            // internal file attributes
+    hdr.writeUInt32LE(0, C.BYTES.bytes(38));            // external file attributes
+    hdr.writeUInt32LE(lfhOffset, C.BYTES.bytes(42));
     return Buffer.concat([hdr, nameBuf]);
   }
 
@@ -196,16 +204,16 @@ function zip() {
       pieces.push(cdh);
       cdSize += cdh.length;
     }
-    // End of Central Directory
-    var eocd = Buffer.alloc(22);
-    eocd.writeUInt32LE(SIG_EOCD, 0);
-    eocd.writeUInt16LE(0, 4);                    // disk number
-    eocd.writeUInt16LE(0, 6);                    // disk where CD starts
-    eocd.writeUInt16LE(entries.length, 8);       // entries on this disk
-    eocd.writeUInt16LE(entries.length, 10);      // total entries
-    eocd.writeUInt32LE(cdSize, 12);              // size of central directory
-    eocd.writeUInt32LE(cdStart, 16);             // offset of central directory
-    eocd.writeUInt16LE(0, 20);                   // comment length
+    // APPNOTE 4.3.16 — end of central directory record (22-byte fixed).
+    var eocd = Buffer.alloc(C.BYTES.bytes(22));
+    eocd.writeUInt32LE(SIG_EOCD, C.BYTES.bytes(0));
+    eocd.writeUInt16LE(0, C.BYTES.bytes(4));                    // disk number
+    eocd.writeUInt16LE(0, C.BYTES.bytes(6));                    // disk where CD starts
+    eocd.writeUInt16LE(entries.length, C.BYTES.bytes(0x08));    // entries on this disk
+    eocd.writeUInt16LE(entries.length, C.BYTES.bytes(10));      // total entries
+    eocd.writeUInt32LE(cdSize, C.BYTES.bytes(12));              // size of central directory
+    eocd.writeUInt32LE(cdStart, C.BYTES.bytes(0x10));           // offset of central directory
+    eocd.writeUInt16LE(0, C.BYTES.bytes(20));                   // comment length
     pieces.push(eocd);
     return Buffer.concat(pieces);
   }

package/lib/atomic-file.js

@@ -36,12 +36,15 @@ var path = require("path");
 var { generateToken, sha3Hash } = require("./crypto");
 var safeJson = require("./safe-json");
 var C = require("./constants");
+var { boot } = require("./log");
 var safeBuffer = require("./safe-buffer");
 var numericBounds = require("./numeric-bounds");
 var safeAsync = require("./safe-async");
 var retry = require("./retry");
 var { FrameworkError } = require("./framework-error");
 
+var log = boot("atomic-file");
+
 var DEFAULTS = {
   maxBytes:        C.BYTES.mib(64),     // 64 MiB ceiling on read
   retryAttempts:   5,
@@ -203,7 +206,7 @@ function writeSync(filepath, data, opts) {
   var dir = path.dirname(filepath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 
-  var tmpPath = filepath + ".tmp-" + generateToken(8);
+  var tmpPath = filepath + ".tmp-" + generateToken(C.BYTES.bytes(8));
   var renamed = false;
   try {
     var fd = fs.openSync(tmpPath, "w", opts.fileMode);
@@ -279,7 +282,7 @@ async function write(filepath, data, opts) {
     return new Promise(function (resolve, reject) {
       var dir = path.dirname(filepath);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-      var tmpPath = filepath + ".tmp-" + generateToken(8);
+      var tmpPath = filepath + ".tmp-" + generateToken(C.BYTES.bytes(8));
       var renamed = false;
       try {
         var fd = fs.openSync(tmpPath, "w", opts.fileMode);
@@ -424,7 +427,8 @@ async function lock(filepath, fn, opts) {
       try {
         var stat = fs.statSync(lockPath);
         if (Date.now() - stat.mtimeMs > C.TIME.minutes(5)) {
-          try { fs.unlinkSync(lockPath); } catch (_e) {}
+          try { fs.unlinkSync(lockPath); }
+          catch (uerr) { log.debug("stale-lock unlink failed", { path: lockPath, error: uerr.message }); }
           continue;
         }
       } catch (_e) { /* stat raced with another process — keep waiting */ }
@@ -448,8 +452,10 @@ async function lock(filepath, fn, opts) {
   try {
     return await fn();
   } finally {
-    try { fs.closeSync(fd); } catch (_e) {}
-    try { fs.unlinkSync(lockPath); } catch (_e) {}
+    try { fs.closeSync(fd); }
+    catch (cerr) { log.debug("lock fd close failed", { error: cerr.message }); }
+    try { fs.unlinkSync(lockPath); }
+    catch (uerr) { log.debug("lock release unlink failed", { path: lockPath, error: uerr.message }); }
   }
 }