@blamejs/core 0.6.6 → 0.6.11

package/lib/i18n.js

@@ -38,16 +38,16 @@
  *   - {var} interpolation; missing vars render as literal {var} unless
  *     `interpolation.strict: true`.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - create() opts                           → Tier A (throw at boot)
- *   - bad locale tag at any boundary          → Tier A (throw)
- *   - t(missingKey)                           → Tier C (return key + obs)
- *   - t() with bad locale override            → Tier A (programming bug)
- *   - plural shape missing 'other'            → Tier A (throw at load)
- *   - interpolation missing var               → Tier C (literal {var})
- *   - format* bad input                       → Tier A
- *   - middleware Accept-Language parse error  → Tier C (defaultLocale)
+ *   - create() opts                           → throw at boot
+ *   - bad locale tag at any boundary          → throw at call site
+ *   - t(missingKey)                           → return key + observability event
+ *   - t() with bad locale override            → throw at call site (programming bug)
+ *   - plural shape missing 'other'            → throw at load time
+ *   - interpolation missing var               → render literal {var}
+ *   - format* bad input                       → throw at call site
+ *   - middleware Accept-Language parse error  → fall back to defaultLocale
  *
  * Security stance: translation values come from operator-controlled
  * files, not user input. {var} interpolation does NOT html-escape;
@@ -97,7 +97,7 @@ var DEFAULTS = Object.freeze({
   RTL_LANGUAGES:    RTL_LANGUAGES,
 });
 
-// ---- Tier-A validation ----
+// ---- Call-site validation (throw on bad input) ----
 
 function _isValidBcp47(tag) {
   if (typeof tag !== "string" || tag.length === 0) return false;
@@ -476,7 +476,7 @@ function create(opts) {
     try {
       if (operatorObs) operatorObs.event(name, 1, labels || {});
       else observability().event(name, 1, labels || {});
-    } catch (_e) { /* Tier B */ }
+    } catch (_e) { /* drop-silent — observability sink must not crash i18n calls */ }
   }
 
   // Cardinal plural-rules instances per locale. `Intl.PluralRules` is
@@ -721,7 +721,7 @@ function create(opts) {
       // Permit setting a non-configured locale (operators may want to
       // experiment), but fall the chain through to the configured ones.
       // Don't throw — i18n.locale is set/observed in many flows; making
-      // it Tier-A would force operators into try/catch around UI setters.
+      // this throw would force operators into try/catch around UI setters.
       _emitObs("i18n.miss.locale", { requested: newLocale, resolved: defaultLocale });
     }
     currentLocale = newLocale;

package/lib/middleware/body-parser.js

@@ -1041,8 +1041,40 @@ async function _parseJsonFromBuf(buf, opts) {
   return parsed;
 }
 
+// raw — convenience wrapper that returns a middleware which buffers
+// the request body as a Buffer regardless of Content-Type. Webhook
+// signature-verification routes use this — the HMAC is computed over
+// the literal body bytes, so JSON-parsing first would change them.
+//
+//   router.post("/hooks/in", b.middleware.bodyParser.raw(), function (req, res) {
+//     verifier.verify(req.headers["x-signature"], req.body);  // req.body is a Buffer
+//   });
+//
+// Accepts the same `raw`-section opts as create() (limit, contentTypes).
+// contentTypes default expands to `["*/*"]` so any Content-Type lands
+// as raw bytes.
+function raw(opts) {
+  opts = opts || {};
+  return create({
+    json:        false,
+    urlencoded:  false,
+    text:        false,
+    multipart:   false,
+    raw: {
+      limit:        opts.limit != null ? opts.limit : DEFAULTS.raw.limit,
+      contentTypes: opts.contentTypes || ["*/*"],
+    },
+  });
+}
+
+// Attach raw onto create so b.middleware.bodyParser.raw() works
+// (middleware/index.js exports the create function as the namespace
+// itself, so static helpers hang off it).
+create.raw = raw;
+
 module.exports = {
   create:           create,
+  raw:              raw,
   BodyParserError:  BodyParserError,
   // Internal helpers exposed for tests + the csrf-protect refactor.
   _contentType:     _contentType,

package/lib/middleware/cors.js

@@ -191,7 +191,7 @@ function create(opts) {
     }
   }
 
-  // Tier A validation on opts.siteOrigin — must parse as http(s) URL.
+  // Throw at create() on bad opts.siteOrigin — must parse as http(s) URL.
   // Accept string OR array of strings.
   var siteOrigins = [];
   if (opts.siteOrigin !== undefined && opts.siteOrigin !== null) {

package/lib/middleware/csrf-protect.js

@@ -34,7 +34,7 @@
  *      (e.g. req.session.data.csrfToken). Issuance + req.csrfToken
  *      exposure are the operator's responsibility in this mode.
  *
- * If neither is supplied, the middleware throws at create() — Tier A
+ * If neither is supplied, the middleware throws at create() —
  * config-time validation, no silent passthrough.
  *
  * Submitted-token sources tried in order on state-changing requests:
@@ -177,7 +177,7 @@ function create(opts) {
     ? opts.trustProxy : false;
   var _isHttps = _isHttpsFor(trustProxy);
 
-  // Tier A — exactly one issuance source.
+  // Throw at create() — exactly one issuance source allowed.
   var hasCookie = opts.cookie != null && opts.cookie !== false;
   var hasLookup = typeof opts.tokenLookup === "function";
   if (hasCookie && hasLookup) {

package/lib/middleware/db-role-for.js

@@ -62,15 +62,23 @@
  * Observability event: db.role.bound { value: 1, labels: { role, source } }
  *   source ∈ "resolver" | "permissions" | "default"
  *
- * Audit emission of `db.role.switched` (the cross-request transition
- * record) lands in v0.6.7 — this middleware focuses on binding the role.
+ * Audit emission: db.role.switched is recorded once per request when a
+ * role binds. The audit row carries the actor 5 W's via
+ * requestHelpers.extractActorContext and metadata { previousRole,
+ * newRole, source }. Defaults align with the framework's "the
+ * authorization decision IS the audit-worthy event" stance — both
+ * auditFailures and auditSuccess default true. The audit sink can be
+ * pinned via opts.audit (any object exposing safeEmit), defaults to
+ * the framework's b.audit.
  */
 var dbRoleContext = require("../db-role-context");
 var lazyRequire = require("../lazy-require");
+var requestHelpers = require("../request-helpers");
 var safeSql = require("../safe-sql");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 
+var audit        = lazyRequire(function () { return require("../audit"); });
 var observability = lazyRequire(function () { return require("../observability"); });
 
 var DbRoleForError = defineClass("DbRoleForError", { alwaysPermanent: true });
@@ -79,6 +87,7 @@ var _err = function (code, message) { return new DbRoleForError(code, message);
 var ALLOWED_OPTS = [
   "resolve", "permissions", "defaultRole",
   "requireRole", "missingRoleStatus", "responder",
+  "audit", "auditFailures", "auditSuccess",
 ];
 
 function _emitEvent(name, value, labels) {
@@ -140,6 +149,20 @@ function create(opts) {
         "middleware.dbRoleFor: missingRoleStatus must be an HTTP status code (100-599)");
     }
   }
+  if (opts.audit !== undefined && opts.audit !== null) {
+    if (typeof opts.audit !== "object" || typeof opts.audit.safeEmit !== "function") {
+      throw _err("db-role-for/bad-opt",
+        "middleware.dbRoleFor: audit must be a b.audit-shaped object (safeEmit fn)");
+    }
+  }
+  if (opts.auditFailures !== undefined && typeof opts.auditFailures !== "boolean") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: auditFailures must be a boolean");
+  }
+  if (opts.auditSuccess !== undefined && typeof opts.auditSuccess !== "boolean") {
+    throw _err("db-role-for/bad-opt",
+      "middleware.dbRoleFor: auditSuccess must be a boolean");
+  }
 
   var resolveFn         = opts.resolve || null;
   var perms             = opts.permissions || null;
@@ -147,6 +170,14 @@ function create(opts) {
   var requireRole       = !!opts.requireRole;
   var missingRoleStatus = opts.missingRoleStatus || 401;
   var responder         = opts.responder || _defaultResponder;
+  // Audit defaults match permissions: the role-binding decision IS the
+  // audit-worthy act. Operators with extreme volume opt out via
+  // auditSuccess: false; failures stay on regardless. The audit sink
+  // defaults to the framework's b.audit; operators with multiple audit
+  // chains pass their own (matches captureAudit's shape).
+  var auditSink         = opts.audit || null;
+  var auditFailures     = (opts.auditFailures === undefined) ? true : opts.auditFailures;
+  var auditSuccess      = (opts.auditSuccess  === undefined) ? true : opts.auditSuccess;
 
   return function dbRoleForMiddleware(req, res, next) {
     var role = null;
@@ -182,6 +213,15 @@ function create(opts) {
     if (!role) {
       if (requireRole) {
         _emitEvent("db.role.missing", 1, {});
+        if (auditFailures) {
+          _auditSwitch(auditSink, req, {
+            previousRole: dbRoleContext.getRole(),
+            newRole:      null,
+            source:       "middleware",
+            outcome:      "failure",
+            reason:       "no-role",
+          });
+        }
         return responder(req, res, missingRoleStatus, {
           error:  "missing_db_role",
           status: missingRoleStatus,
@@ -206,12 +246,46 @@ function create(opts) {
       return next(e);
     }
 
+    var previousRole = dbRoleContext.getRole();
     req.dbRole = role;
     _emitEvent("db.role.bound", 1, { role: role, source: source });
+    if (auditSuccess) {
+      _auditSwitch(auditSink, req, {
+        previousRole: previousRole,
+        newRole:      role,
+        source:       "middleware",
+        outcome:      "success",
+      });
+    }
     dbRoleContext.runWithRole(role, function () { next(); });
   };
 }
 
+// Emit the db.role.switched audit row. Fire-and-forget — the audit
+// handler's own try/catch keeps a momentary outage from breaking the
+// request. The actor 5 W's come from extractActorContext (req-driven);
+// metadata carries the previous + new role + binding source so a
+// forensic walker can reconstruct "which role read which row when."
+// The sink defaults to the framework's b.audit when the operator
+// didn't pass an explicit instance.
+function _auditSwitch(sink, req, info) {
+  try {
+    var emitter = sink || audit();
+    emitter.safeEmit({
+      action:   "db.role.switched",
+      actor:    requestHelpers.extractActorContext(req),
+      resource: { kind: "db.role", id: info.newRole || "(none)" },
+      outcome:  info.outcome || "success",
+      reason:   info.reason || null,
+      metadata: {
+        previousRole: info.previousRole || null,
+        newRole:      info.newRole || null,
+        source:       info.source,
+      },
+    });
+  } catch (_e) { /* audit best-effort */ }
+}
+
 module.exports = {
   create:           create,
   DbRoleForError:   DbRoleForError,

package/lib/middleware/rate-limit.js

@@ -256,8 +256,8 @@ function create(opts) {
   var bodyOnLimit = opts.bodyOnLimit !== undefined ? opts.bodyOnLimit : "Too Many Requests";
   var emitHeaders = opts.header !== false;
   var skipPaths = opts.skipPaths || [];
-  // Tier-A: each entry must be a string prefix or a RegExp. Anything
-  // else would crash _shouldSkip with TypeError on the first request.
+  // Throw at create(): each entry must be a string prefix or a RegExp.
+  // Anything else would crash _shouldSkip with TypeError on the first request.
   for (var sp = 0; sp < skipPaths.length; sp++) {
     if (typeof skipPaths[sp] !== "string" && !(skipPaths[sp] instanceof RegExp)) {
       throw new Error("middleware.rateLimit: skipPaths[" + sp +

package/lib/notify.js

@@ -74,7 +74,7 @@ var DEFAULTS = Object.freeze({
   // we get the framework's policy without forking the constants.
 });
 
-// ---- Tier-A validation ----
+// ---- Call-site validation (throw on bad input) ----
 
 function _isFiniteNonNegative(n) {
   return typeof n === "number" && isFinite(n) && n >= 0;
@@ -360,7 +360,7 @@ function create(opts) {
 
   function _emitObs(name, labels) {
     try { observability().event(name, 1, labels || {}); }
-    catch (_e) { /* Tier B */ }
+    catch (_e) { /* drop-silent — observability sink must not crash send() */ }
   }
 
   function _emitAudit(action, info) {

package/lib/object-store/sigv4-bucket-ops.js

@@ -44,13 +44,14 @@
  *     maxAgeSeconds:  3600,
  *   }]);
  *
- * Validation is Tier-A: every input shape is rejected at the call
- * site rather than producing a server-side 400. Errors surface as
- * ObjectStoreError with codes (BUCKET_INVALID_NAME, INVALID_LIFECYCLE,
- * INVALID_CORS_RULE, BUCKET_ALREADY_OWNED, BUCKET_NOT_EMPTY, etc.).
+ * Validation rejects every bad input shape at the call site rather
+ * than producing a server-side 400. Errors surface as ObjectStoreError
+ * with codes (BUCKET_INVALID_NAME, INVALID_LIFECYCLE, INVALID_CORS_RULE,
+ * BUCKET_ALREADY_OWNED, BUCKET_NOT_EMPTY, etc.).
  */
 var { URL } = require("url");
 var nodeCrypto = require("crypto");
+var C = require("../constants");
 var sigv4 = require("./sigv4");
 var safeXml = require("../parsers/safe-xml");
 var safeUrl = require("../safe-url");
@@ -261,7 +262,7 @@ function _buildCorsXml(rules) {
     body += "</CORSRule>";
   }
   body += "</CORSConfiguration>";
-  if (Buffer.byteLength(body, "utf8") > 64 * 1024) {
+  if (Buffer.byteLength(body, "utf8") > C.BYTES.kib(64)) {
     throw _err("INVALID_CORS_RULE",
       "CORS configuration exceeds 64 KB (S3 spec)", true);
   }

package/lib/object-store/sigv4.js

@@ -214,17 +214,17 @@ function _request(method, url, headers, body, opts) {
 // CompleteMultipartUpload with EntityTooSmall. The framework refuses
 // configurations below this floor at create() time so operators don't
 // see surprising failures only on large uploads.
-var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
+var MIN_PART_SIZE_BYTES = C.BYTES.mib(5);
 // S3 spec ceiling on part count. CompleteMultipartUpload rejects
 // uploads with more than 10000 parts.
 var MAX_PARTS = 10000;
 // Auto-multipart trigger: buffered bodies under this stay single-PUT.
 // Streams always go multipart since size isn't known up-front.
-var DEFAULT_MULTIPART_THRESHOLD_BYTES = 64 * 1024 * 1024;
+var DEFAULT_MULTIPART_THRESHOLD_BYTES = C.BYTES.mib(64);
 // Conservative default part size — large enough to keep round-trip
 // overhead small relative to payload, small enough to fit comfortably
 // in a 4-way-concurrent upload's memory footprint.
-var DEFAULT_PART_SIZE_BYTES = 16 * 1024 * 1024;
+var DEFAULT_PART_SIZE_BYTES = C.BYTES.mib(16);
 var DEFAULT_PART_CONCURRENCY = 4;
 
 // ---- SSE option handling ----

package/lib/observability.js

@@ -59,18 +59,43 @@ var lazyRequire = require("./lazy-require");
 var tracing = lazyRequire(function () { return require("./tracing"); });
 var metrics = lazyRequire(function () { return require("./metrics"); });
 
+// Operator-installed tap handler — wired via setTap(). When non-null,
+// every observability event/tap dispatch routes here in addition to
+// the framework's metrics module. Used by b.otelExport.create() so an
+// OTLP/HTTP exporter receives the same hot-path counters the framework
+// emits internally.
+var _externalTap = null;
+
 function _safeMetricsTap(name, value, labels) {
   try { metrics().tap(name, value, labels); }
   catch (_e) { /* boot-order tolerance — metrics may not be loaded */ }
+  if (_externalTap !== null) {
+    try { _externalTap(name, value, labels); }
+    catch (_e) { /* operator-installed handler — drop-silent on its throws */ }
+  }
+}
+
+// setTap — install an external tap handler. Operators wire this from
+// `b.otelExport.create({...}).tapHandler` so every framework counter
+// also lands in the operator's metrics pipeline.
+//
+// The handler signature mirrors metrics.tap: (name, value, labels).
+// Pass null to remove the previously-installed handler.
+function setTap(handler) {
+  if (handler !== null && typeof handler !== "function") {
+    throw new TypeError("observability.setTap: handler must be a function or null, got " +
+      typeof handler);
+  }
+  _externalTap = handler;
 }
 
 function tap(name, attrs, fn) {
   if (typeof attrs === "function") { fn = attrs; attrs = null; }
-  // Tier A validation: tap is called from many call sites and a typo
-  // in the name (e.g. variable holding undefined) silently corrupts both
-  // the span tree AND the metrics counter route, with no obvious symptom
-  // until somebody opens a dashboard. Throw at first call so the
-  // operator catches it.
+  // Throw on bad input: tap is called from many call sites and a typo
+  // in the name (e.g. variable holding undefined) silently corrupts
+  // both the span tree AND the metrics counter route, with no obvious
+  // symptom until somebody opens a dashboard. Throw at first call so
+  // the operator catches it.
   if (typeof name !== "string" || name.length === 0) {
     throw new TypeError("observability.tap: name must be a non-empty string, got " +
       (typeof name) + " " + JSON.stringify(name));
@@ -97,18 +122,19 @@ function tap(name, attrs, fn) {
   });
 }
 
-// Tier B (drop-silent): event is the fire-and-forget shape called from
-// hot paths where throwing would crash the request that triggered it.
-// Bad input is silently dropped — operators with a misnamed event see
-// the missing counter, not a 500. metrics.tap performs its own label-
-// name regex validation; an invalid call surfaces in the metrics module
-// log, not via a thrown exception.
+// Drop-silent on bad input by design: event is the fire-and-forget
+// shape called from hot paths where throwing would crash the request
+// that triggered it. Operators with a misnamed event see the missing
+// counter, not a 500. metrics.tap performs its own label-name regex
+// validation; an invalid call surfaces in the metrics module log, not
+// via a thrown exception.
 function event(name, value, labels) {
   if (typeof name !== "string" || name.length === 0) return;
   _safeMetricsTap(name, value, labels);
 }
 
 module.exports = {
-  tap:   tap,
-  event: event,
+  tap:    tap,
+  event:  event,
+  setTap: setTap,
 };

package/lib/otel-export.js

@@ -27,8 +27,8 @@
  *
  * Wiring with `b.observability`:
  *
- *   // Option A: replace the metrics tap entirely
- *   b.observability._setTap(otel.tapHandler);
+ *   // Option A: install as an external tap on b.observability
+ *   b.observability.setTap(otel.tapHandler);
  *
  *   // Option B: alongside b.metrics — operators write their own
  *   // multi-tap fan-out (or pick one or the other for v1).

package/lib/pagination.js

@@ -215,10 +215,10 @@ async function cursor(query, opts) {
   }
   var limit     = _resolveLimit(opts);
   var orderBy   = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Tier-A on orderBy — the value is interpolated into a raw SQL fragment
-  // for the keyset where-clause. Restrict to identifier-safe characters
-  // so a careless caller piping `req.query.orderBy` through doesn't
-  // create an SQL-injection vector.
+  // Throw at call site on bad orderBy — the value is interpolated into
+  // a raw SQL fragment for the keyset where-clause. Restrict to
+  // identifier-safe characters so a careless caller piping
+  // `req.query.orderBy` through doesn't create an SQL-injection vector.
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
     throw new PaginationError("pagination/bad-orderby",
       "cursor: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
@@ -342,8 +342,8 @@ async function offset(query, opts) {
   var page = parseInt(opts.page, 10);
   if (isNaN(page) || page < 1) page = 1;
   var orderBy = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Same Tier-A on offset() as cursor() — orderBy passes through to the
-  // db Query; identifier-safe-only to prevent SQL injection.
+  // Same identifier-only check on offset() as cursor() — orderBy passes
+  // through to the db Query; throw at call site to prevent SQL injection.
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
     throw new PaginationError("pagination/bad-orderby",
       "offset: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +

package/lib/permissions.js

@@ -31,14 +31,14 @@
  *   "users:*:read"  matches "users:foo:read" (per-segment *)
  *   "users:read"    matches "users:read" only — no implicit sub-resource grant
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - create() role table / scope formats → Tier A (throw at app init)
- *   - require(scope) registration arg     → Tier A (throw at route declaration)
- *   - check(actor, scope) bad actor       → Tier C (return false)
+ *   - create() role table / scope formats → throw at app init
+ *   - require(scope) registration arg     → throw at route declaration
+ *   - check(actor, scope) bad actor       → return false (tolerant read)
  *   - resolver returns null in middleware → 401 (missingActorStatus)
  *   - actor lacks scope in middleware     → 403 (denyStatus)
- *   - audit/observability emit failures   → Tier B (drop silent)
+ *   - audit/observability emit failures   → drop silent (hot-path sink)
  *
  * Audit defaults follow the framework's security-defaults stance
  * default: `auditFailures: true`
@@ -57,7 +57,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 // Lowercase tokens, digits, dash, underscore, and `*` allowed per
@@ -331,7 +331,7 @@ function create(opts) {
   }
 
   // Middleware factory. `mode` is "single" | "all" | "any"; `requested`
-  // is the scope or scope list. Tier A on registration arg.
+  // is the scope or scope list. Throw at registration time on bad shape.
   function _middleware(mode, requested) {
     if (mode === "single") {
       _validateScopePattern(requested, "permissions.require");

package/lib/protocol-dispatcher.js

@@ -51,8 +51,8 @@ var { defineClass } = require("./framework-error");
 // supply their own get this generic shape with the same code namespace.
 var ProtocolDispatcherError = defineClass("ProtocolDispatcherError", { withStatusCode: true });
 
-// Tier A validation — called at create-time, throw on bad input so
-// operators catch typos at app boot, not first request.
+// Throw at create-time on bad input so operators catch typos at app
+// boot, not first request.
 function _validateConfig(opts) {
   if (!opts || typeof opts !== "object") {
     throw new Error("protocolDispatcher.create: opts is required");

package/lib/queue.js

@@ -505,7 +505,7 @@ function _resetForTest() {
 //     ],
 //   });
 //
-// Cycle detection runs at registration (Tier-A throw). Each child enters
+// Cycle detection runs at registration (throws at call site). Each child enters
 // the queue with availableAt = MAX_SAFE_INTEGER until parent completion
 // bumps it. Returns { flowId, jobs: [{ name, jobId }, ...] }.
 function enqueueFlow(spec) {

package/lib/request-helpers.js

@@ -175,9 +175,9 @@ function requestProtocol(req, opts) {
 //   parseListHeader(undefined)             → []
 //   parseListHeader("")                    → []
 //
-// Tier-C: tolerant of non-string input (returns []) — these are read
-// from request headers that the network might omit. Callers needing
-// stricter checks layer their own validation on the result.
+// Tolerant read: non-string input returns [] — these are read from
+// request headers that the network might omit. Callers needing stricter
+// checks layer their own validation on the result.
 function parseListHeader(value, opts) {
   if (value == null) return [];
   opts = opts || {};

package/lib/retry.js

@@ -18,14 +18,14 @@
  * compose freely with `safeAsync.withTimeout`, AbortSignals, and any
  * caller-side instrumentation.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - withRetry opts at first call            → Tier A (throw)
- *   - CircuitBreaker constructor opts         → Tier A (throw)
- *   - backoffDelay(attempt) attempt argument  → Tier A (throw)
- *   - isRetryable(err) defensive read         → Tier C (return defaults)
- *   - onRetry callback throw                  → Tier B (drop silent)
- *   - breaker internal _onSuccess/_onFailure  → Tier B (drop silent)
+ *   - withRetry opts at first call            → throw at call site
+ *   - CircuitBreaker constructor opts         → throw at call site
+ *   - backoffDelay(attempt) attempt argument  → throw at call site
+ *   - isRetryable(err) defensive read         → tolerant (return defaults)
+ *   - onRetry callback throw                  → drop silent (hot-path sink)
+ *   - breaker internal _onSuccess/_onFailure  → drop silent (hot-path sink)
  *
  * HTTP-client auto-retry is intentionally NOT provided here. Callers
  * wrap their own outbound calls in `b.retry.withRetry(...)` to keep
@@ -40,13 +40,13 @@ var lazyRequire = require("./lazy-require");
 // are fully loaded.
 var safeAsync = lazyRequire(function () { return require("./safe-async"); });
 // observability is also lazy-required because the metrics + tracing
-// registry boots after this file loads. event() is Tier B — any
-// throw inside the metrics sink is swallowed by observability itself.
+// registry boots after this file loads. event() is fire-and-forget —
+// any throw inside the metrics sink is swallowed by observability itself.
 var observability = lazyRequire(function () { return require("./observability"); });
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 // ---- Defaults ----
@@ -80,7 +80,7 @@ var DEFAULT_BREAKER = Object.freeze({
   successThreshold:  2,                   // consecutive HALF probes that close it
 });
 
-// ---- Tier-A validation helpers ----
+// ---- Call-site validation helpers (throw on bad input) ----
 
 function _isPositiveInt(n) {
   return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;
@@ -147,7 +147,7 @@ function _validateBreakerOpts(name, opts) {
 
 // ---- Public surface ----
 
-// Tier C: defensive read of err shape; missing fields → false.
+// Tolerant read of err shape; missing fields → false.
 function isRetryable(err) {
   if (!err) return false;
   if (err.isObjectStoreError && err.permanent) return false;
@@ -162,11 +162,12 @@ function isRetryable(err) {
   return false;                                   // default: not retryable (avoid masking bugs)
 }
 
-// Tier A: attempt must be a positive int; opts (when supplied) must
-// have non-neg-finite baseDelayMs/maxDelayMs and finite jitterFactor in [0,1].
-// We don't full-validate opts here every call (hot path) — defaults are
-// frozen, so the only way a bad opts reaches here is via withRetry which
-// already validated, OR a caller using backoffDelay directly. For that
+// Throw on bad input: attempt must be a positive int; opts (when supplied)
+// must have non-neg-finite baseDelayMs/maxDelayMs and finite jitterFactor
+// in [0,1]. We don't full-validate opts here every call (hot path) —
+// defaults are frozen, so the only way a bad opts reaches here is via
+// withRetry which already validated, OR a caller using backoffDelay
+// directly. For that
 // direct case we still validate the attempt arg loudly.
 function backoffDelay(attempt, opts) {
   if (!_isPositiveInt(attempt)) {
@@ -212,8 +213,8 @@ async function withRetry(fn, opts) {
       var delay = backoffDelay(attempt, opts);
       _emitEvent("retry.attempt", 1, { attempt: attempt });
       if (typeof opts.onRetry === "function") {
-        // Tier B: hot-path observability sink. A thrown observer must
-        // not crash the retry loop — by design.
+        // Hot-path observability sink — drops silent on observer throw
+        // so a thrown observer can't crash the retry loop.
         try { opts.onRetry({ attempt: attempt, delay: delay, error: err }); } catch (_e) {}
       }
       // Honor opts.signal during the backoff sleep — a caller who aborts