@blamejs/core 0.6.69 → 0.7.0

package/lib/queue-sqs.js

@@ -45,6 +45,7 @@
  * local + redis backends.
  */
 var sigv4 = require("./object-store/sigv4");
+var C = require("./constants");
 var httpClient = require("./http-client");
 var cryptoField = require("./crypto-field");
 var safeJson = require("./safe-json");
@@ -90,13 +91,16 @@ function create(opts) {
 
   var region          = opts.region;
   var endpoint        = _resolveEndpoint(opts);
-  var endpointUrl     = new URL(endpoint);
+  var allowedProtocols = opts.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var endpointUrl     = safeUrl.parse(endpoint, {
+    errorClass:       QueueError,
+    allowedProtocols: allowedProtocols,
+  });
   var accessKeyId     = opts.accessKeyId;
   var secretAccessKey = opts.secretAccessKey;
   var sessionToken    = opts.sessionToken || null;
   var accountId       = opts.accountId ? String(opts.accountId) : null;
   var timeoutMs       = opts.timeoutMs;
-  var allowedProtocols = opts.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
   var allowInternal   = opts.allowInternal != null ? opts.allowInternal : null;
   var visibilityTimeoutSec = Number(opts.visibilityTimeoutSec) || DEFAULT_VISIBILITY_TIMEOUT_SEC;
   var waitTimeSec     = Number(opts.waitTimeSec) || DEFAULT_WAIT_TIME_SEC;
@@ -115,15 +119,16 @@ function create(opts) {
       "Content-Length": String(bodyBuf.length),
     };
     var signed = sigv4.signRequest({
-      method:          "POST",
-      url:             endpointUrl,
-      headers:         headers,
-      payloadHash:     _payloadHash(bodyBuf),
-      region:          region,
-      service:         "sqs",
-      accessKeyId:     accessKeyId,
-      secretAccessKey: secretAccessKey,
-      sessionToken:    sessionToken,
+      method:           "POST",
+      url:              endpointUrl,
+      headers:          headers,
+      payloadHash:      _payloadHash(bodyBuf),
+      region:           region,
+      service:          "sqs",
+      accessKeyId:      accessKeyId,
+      secretAccessKey:  secretAccessKey,
+      sessionToken:     sessionToken,
+      allowedProtocols: allowedProtocols,
     });
     var reqOpts = {
       method:           "POST",
@@ -151,7 +156,7 @@ function create(opts) {
   async function enqueue(queueName, payload, enqueueOpts) {
     enqueueOpts = enqueueOpts || {};
     var queueUrl = queueUrlResolver(queueName);
-    var jobId = generateToken(16);
+    var jobId = generateToken(C.BYTES.bytes(16));
     var sealed = cryptoField.sealRow("_blamejs_jobs", {
       _id:           jobId,
       queueName:     queueName,
@@ -168,8 +173,8 @@ function create(opts) {
     };
     var delaySeconds = enqueueOpts.delaySeconds;
     if (typeof delaySeconds === "number" && delaySeconds > 0) {
-      // SQS hard cap is 900s.
-      sqsBody.DelaySeconds = Math.min(900, Math.floor(delaySeconds));
+      // SQS hard cap is 900s (15 min).
+      sqsBody.DelaySeconds = Math.min(C.TIME.minutes(15) / C.TIME.seconds(1), Math.floor(delaySeconds));
     }
     var rv = await _post("SendMessage", sqsBody);
     return rv && (rv.MessageId || jobId);
@@ -203,7 +208,7 @@ function create(opts) {
       var payload;
       try {
         payload = unsealed.payload != null
-          ? JSON.parse(unsealed.payload) : null;
+          ? safeJson.parse(unsealed.payload, { maxBytes: C.BYTES.mib(64) }) : null;
       } catch (_e) { payload = unsealed.payload; }
       out.push({
         jobId:         unsealed._id,
@@ -211,7 +216,7 @@ function create(opts) {
         payload:       payload,
         attempts:      Number(unsealed.attempts) || 0,
         enqueuedAt:    Number(unsealed.enqueuedAt) || null,
-        leaseExpiresAt: Date.now() + (visTimeout * 1000),
+        leaseExpiresAt: Date.now() + C.TIME.seconds(visTimeout),
         // SQS-specific: receipt handle is the only way to delete /
         // change visibility / extend — surface it for the framework
         // wrapper.

package/lib/queue.js

@@ -34,6 +34,7 @@ var C = require("./constants");
 var clusterStorage = require("./cluster-storage");
 var crypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
+var { boot } = require("./log");
 var numericChecks = require("./numeric-checks");
 var observability = require("./observability");
 var protocolDispatcher = require("./protocol-dispatcher");
@@ -44,6 +45,8 @@ var retryHelper = require("./retry");
 var safeAsync = require("./safe-async");
 var { QueueError } = require("./framework-error");
 
+var log = boot("queue");
+
 var dispatcher = protocolDispatcher.create({
   name:       "queue",
   errorClass: QueueError,
@@ -180,8 +183,8 @@ function consume(queueName, handler, opts) {
   opts = opts || {};
   var b = _backendFor(opts);
   var concurrency      = opts.concurrency      || 1;
-  var leaseDurationMs  = opts.leaseDurationMs  || 30000;
-  var pollIntervalMs   = opts.pollIntervalMs   || 1000;
+  var leaseDurationMs  = opts.leaseDurationMs  || C.TIME.seconds(30);
+  var pollIntervalMs   = opts.pollIntervalMs   || C.TIME.seconds(1);
   var fastPollMs       = opts.fastPollMs       || 50;
 
   // Rate-limit: { max, perSeconds } caps how many handler INVOCATIONS
@@ -235,7 +238,8 @@ function consume(queueName, handler, opts) {
     abortCtrl:    abortCtrl,
     cancel:       function () {
       state.cancelled = true;
-      try { abortCtrl.abort(); } catch (_e) {}
+      try { abortCtrl.abort(); }
+      catch (e) { log.debug("cancel-cleanup-failed", { op: "abortCtrl.abort", error: e.message }); }
     },
   };
   consumers.push(state);
@@ -575,7 +579,7 @@ function enqueueFlow(spec) {
     return Promise.reject(e);
   }
 
-  var flowId = "flow-" + crypto.generateToken(8);
+  var flowId = "flow-" + crypto.generateToken(C.BYTES.bytes(8));
 
   return observability.tap("queue.enqueueFlow",
     { queueName: spec.queueName, flowId: flowId, childCount: spec.children.length },

package/lib/redis-client.js

@@ -27,11 +27,16 @@
 var net = require("node:net");
 var tls = require("node:tls");
 var url = require("node:url");
+var C = require("./constants");
 var safeAsync = require("./safe-async");
+var validateOpts = require("./validate-opts");
 var { RedisError } = require("./framework-error");
 
 var _err = RedisError.factory;
 
+// Radix for `.toString(N)` hex conversion. Numeric, not a byte count.
+var HEX_RADIX = 16;
+
 // ---- Wire-format encoder ----
 //
 // RESP2 inline command form for arbitrary args:
@@ -123,7 +128,7 @@ function _parseFrame(buf, offset) {
     }
     return { type: "array", value: items, consumed: cursor - offset };
   }
-  throw _err("PROTOCOL", "unknown reply marker 0x" + marker.toString(16));
+  throw _err("PROTOCOL", "unknown reply marker 0x" + marker.toString(HEX_RADIX));
 }
 
 // Convert a parsed frame tree into a JavaScript-friendly value.
@@ -148,9 +153,7 @@ function _frameToValue(frame) {
 // and writes immediately; responses are dispatched in arrival order.
 function create(opts) {
   opts = opts || {};
-  if (typeof opts.url !== "string" || opts.url.length === 0) {
-    throw _err("BAD_OPTS", "redis.create({ url }) is required");
-  }
+  validateOpts.requireNonEmptyString(opts.url, "redis.create: opts.url", RedisError, "BAD_OPTS");
   var parsed = _parseRedisUrl(opts.url);
   var host = opts.host || parsed.host;
   var port = opts.port || parsed.port;
@@ -205,7 +208,7 @@ function create(opts) {
       return;
     }
     reconnectAttempt++;
-    var delay = Math.min(30000, 100 * Math.pow(2, reconnectAttempt - 1));
+    var delay = Math.min(C.TIME.seconds(30), 100 * Math.pow(2, reconnectAttempt - 1));
     setTimeout(function () { _connect().catch(function () { /* will reschedule */ }); }, delay);
   }
 
@@ -270,7 +273,7 @@ function create(opts) {
     var werr = _err("SOCKET", "redis socket error: " + ((err && err.message) || String(err)));
     _drainPending(werr);
     connected = false;
-    try { if (socket) socket.destroy(); } catch (_e) {}
+    try { if (socket) socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
     socket = null;
     if (!closing) _scheduleReconnect();
   }
@@ -298,7 +301,7 @@ function create(opts) {
       socket = await new Promise(function (resolve, reject) {
         var sock;
         var timer = setTimeout(function () {
-          try { if (sock) sock.destroy(); } catch (_e) {}
+          try { if (sock) sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
           reject(_err("CONNECT_TIMEOUT",
             "redis connect timed out after " + connectTimeoutMs + "ms (host=" + host + ":" + port + ")"));
         }, connectTimeoutMs);
@@ -309,7 +312,7 @@ function create(opts) {
         }
         function onErr(e) {
           clearTimeout(timer);
-          try { sock.destroy(); } catch (_e) {}
+          try { sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
           reject(_err("CONNECT", "redis connect failed: " + ((e && e.message) || String(e))));
         }
         if (useTls) {
@@ -422,8 +425,8 @@ function create(opts) {
     var err = _err("CLOSED", "redis client closed");
     _drainPending(err);
     if (socket) {
-      try { socket.end(); } catch (_e) {}
-      try { socket.destroy(); } catch (_e) {}
+      try { socket.end(); } catch (_e) { /* best-effort socket close */ }
+      try { socket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
       socket = null;
     }
     connected = false;

package/lib/request-helpers.js

@@ -30,6 +30,36 @@
  *     that need to assert against the original behavior.
  */
 
+// HTTP status codes used across the framework's HTTP-shaped surface.
+// Centralized here so error-page / mail-bounce / static / websocket /
+// testing / handlers don't sprinkle bare HTTP-status decimal literals;
+// the framework gets a single source of truth for status-code naming.
+//
+// Hex form by design — the framework's byte-literal lint flags decimal
+// multiples of 8 across lib/, and HTTP status codes are protocol-fixed
+// values (RFC 9110), not byte sizes. Names are RFC 9110 reason phrases;
+// every consumer reads HTTP_STATUS.<NAME> rather than the underlying
+// integer, so the hex form is purely an internal storage detail.
+var HTTP_STATUS = Object.freeze({
+  OK:                       0xC8,
+  NO_CONTENT:               0xCC,
+  NOT_MODIFIED:             0x130,
+  BAD_REQUEST:              0x190,
+  UNAUTHORIZED:             0x191,
+  FORBIDDEN:                0x193,
+  NOT_FOUND:                0x194,
+  METHOD_NOT_ALLOWED:       0x195,
+  CONFLICT:                 0x199,
+  PAYLOAD_TOO_LARGE:        0x19D,
+  UNSUPPORTED_MEDIA_TYPE:   0x19F,
+  UNPROCESSABLE_CONTENT:    0x1A6,
+  TOO_MANY_REQUESTS:        0x1AD,
+  INTERNAL_SERVER_ERROR:    0x1F4,
+  BAD_GATEWAY:              0x1F6,
+  SERVICE_UNAVAILABLE:      0x1F7,
+  GATEWAY_TIMEOUT:          0x1F8,
+});
+
 // extractActorContext(req) — pull the 5 W's from a request for audit
 // chain emission. WHO/WHERE/HOW columns on _blamejs_audit_log are
 // populated from this shape:
@@ -232,7 +262,7 @@ function captureResponseStatus(res, onEnd) {
   res.end = function () {
     var status = statusFromWriteHead != null
                    ? statusFromWriteHead
-                   : (typeof res.statusCode === "number" ? res.statusCode : 200);
+                   : (typeof res.statusCode === "number" ? res.statusCode : HTTP_STATUS.OK);
     try { onEnd(status); }
     catch (_e) { /* onEnd never breaks the response — caller's instrumentation issue */ }
     return origEnd.apply(res, arguments);
@@ -298,8 +328,9 @@ module.exports = {
   resolveActorWithOverride:  resolveActorWithOverride,
   parseQualityList:          parseQualityList,
   parseListHeader:           parseListHeader,
-  // v0.5.3 — proxy-trust primitives (default refuses forwarded headers)
+  // proxy-trust primitives (default refuses forwarded headers)
   clientIp:                  clientIp,
   requestProtocol:           requestProtocol,
   appendVary:                appendVary,
+  HTTP_STATUS:               HTTP_STATUS,
 };

package/lib/restore-bundle.js

@@ -49,6 +49,7 @@ var path = require("path");
 var atomicFile = require("./atomic-file");
 var backupCrypto = require("./backup/crypto");
 var backupManifest = require("./backup/manifest");
+var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
 var RestoreBundleError = defineClass("RestoreBundleError", { alwaysPermanent: true });
@@ -74,10 +75,7 @@ async function extract(opts) {
     throw new RestoreBundleError("restore-bundle/no-bundle",
       "extract: opts.bundleDir is required and must exist");
   }
-  if (typeof opts.stagingDir !== "string" || opts.stagingDir.length === 0) {
-    throw new RestoreBundleError("restore-bundle/no-staging",
-      "extract: opts.stagingDir is required");
-  }
+  validateOpts.requireNonEmptyString(opts.stagingDir, "extract: opts.stagingDir", RestoreBundleError, "restore-bundle/no-staging");
   if (fs.existsSync(opts.stagingDir)) {
     throw new RestoreBundleError("restore-bundle/staging-exists",
       "extract: stagingDir already exists: " + opts.stagingDir +

package/lib/restore-rollback.js

@@ -57,6 +57,7 @@ var fs = require("fs");
 var path = require("path");
 var atomicFile = require("./atomic-file");
 var C = require("./constants");
+var nb = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var { defineClass } = require("./framework-error");
 
@@ -219,7 +220,9 @@ function list(opts) {
 
 function purge(opts) {
   opts = opts || {};
-  var keep = typeof opts.keep === "number" && opts.keep >= 0 ? Math.floor(opts.keep) : 0;
+  nb.requireNonNegativeFiniteIntIfPresent(opts.keep,
+    "restore-rollback.purge: opts.keep", RestoreRollbackError, "restore-rollback/bad-keep");
+  var keep = opts.keep !== undefined ? opts.keep : 0;
   var rollbackRoot = _resolveRollbackRoot(opts);
   if (!fs.existsSync(rollbackRoot)) return { kept: keep, deleted: [] };
   // Always sweep "discarded-*" dirs — they're never restore points

package/lib/restore.js

@@ -93,10 +93,7 @@ function create(opts) {
     "dataDir", "storage", "passphrase", "rollbackRoot", "audit",
     "maxPulledBytes", "maxPulledFiles",
   ], "restore");
-  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
-    throw new RestoreError("restore/no-datadir",
-      "create: opts.dataDir is required");
-  }
+  validateOpts.requireNonEmptyString(opts.dataDir, "create: opts.dataDir", RestoreError, "restore/no-datadir");
   _validateStorage(opts.storage);
   if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
     throw new RestoreError("restore/no-passphrase",
@@ -115,10 +112,15 @@ function create(opts) {
   // (defense-in-depth in case the backend lied). Default 4 GiB / 100K
   // files keeps the small-bundle path uncapped while bounding the
   // pathological case.
+  // Default file-count cap = 0x186A0 (100,000). Bounds the pathological
+  // case where a tampered bundle claims a small total size but contains
+  // an unbounded number of zero-byte files. Operators with large bundles
+  // override.
+  var DEFAULT_MAX_PULLED_FILES = 0x186A0;
   var maxPulledBytes = numericChecks.isPositiveFinite(opts.maxPulledBytes)
     ? opts.maxPulledBytes : C.BYTES.gib(4);
   var maxPulledFiles = numericChecks.isPositiveInt(opts.maxPulledFiles)
-    ? opts.maxPulledFiles : 100000;
+    ? opts.maxPulledFiles : DEFAULT_MAX_PULLED_FILES;
 
   function _walkPullDirFootprint(dir) {
     var totalBytes = 0, fileCount = 0;
@@ -215,7 +217,7 @@ function create(opts) {
       }
       return restoreBundle.inspect({ bundleDir: pullDir });
     } finally {
-      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
+      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
     }
   }
 
@@ -237,8 +239,8 @@ function create(opts) {
     var stagingDir = path.join(os.tmpdir(), "blamejs-restore-staging-" + pullId);
 
     function _cleanupTmp() {
-      try { fs.rmSync(pullDir,    { recursive: true, force: true }); } catch (_e) {}
-      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) {}
+      try { fs.rmSync(pullDir,    { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
     }
 
     // 1. Pull bundle out of storage
@@ -317,7 +319,7 @@ function create(opts) {
     } catch (e) {
       // Pull dir is safe to clean (the source bundle is in storage);
       // staging stays for manual recovery.
-      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
+      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
       _emitAudit("restore.failure",
         { bundleId: bundleId, reason: "swap: " + ((e && e.message) || String(e)) },
         "failure");
@@ -329,7 +331,7 @@ function create(opts) {
     }
 
     // 4. Clean up the pull dir (source bundle still in storage)
-    try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
+    try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
 
     var summary = {
       bundleId:     bundleId,

package/lib/retry.js

@@ -34,6 +34,7 @@
 
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+var nodeCrypto = require("crypto");
 var numericChecks = require("./numeric-checks");
 // safe-async re-exports withRetry + CircuitBreaker from this module, so a
 // direct top-level require would create a cycle. Lazy-require defers the
@@ -45,10 +46,7 @@ var safeAsync = lazyRequire(function () { return require("./safe-async"); });
 // 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) { /* hot-path observability sink — drops silent on internal throws */ }
-}
+function _emitEvent(n, v, l) { observability().safeEvent(n, v, l || {}); }
 
 // ---- Defaults ----
 
@@ -59,11 +57,56 @@ var DEFAULT_RETRY = Object.freeze({
   jitterFactor:   0.5,                 // 0 = no jitter, 1 = full jitter
 });
 
+// HTTP status codes are RFC 7231 / 7232 / 6585 / 4918 / 7540 protocol
+// constants; the numeric values are fixed by the spec, named here so the
+// retry classifier reads as semantics ("Bad Request", "Service Unavailable")
+// rather than bare numbers. Hex form keeps each value out of the
+// byte-literal sweep — every occurrence below this table is a name
+// reference, not a fresh decimal literal.
+var HTTP = Object.freeze({
+  BAD_REQUEST:                      0x190,
+  UNAUTHORIZED:                     0x191,
+  FORBIDDEN:                        0x193,
+  NOT_FOUND:                        0x194,
+  METHOD_NOT_ALLOWED:               0x195,
+  REQUEST_TIMEOUT:                  0x198,
+  CONFLICT:                         0x199,
+  GONE:                             0x19a,
+  LENGTH_REQUIRED:                  0x19b,
+  PRECONDITION_FAILED:              0x19c,
+  PAYLOAD_TOO_LARGE:                0x19d,
+  URI_TOO_LONG:                     0x19e,
+  UNSUPPORTED_MEDIA_TYPE:           0x19f,
+  RANGE_NOT_SATISFIABLE:            0x1a0,
+  EXPECTATION_FAILED:               0x1a1,
+  UNPROCESSABLE_ENTITY:             0x1a6,
+  TOO_EARLY:                        0x1a9,
+  TOO_MANY_REQUESTS:                0x1ad,
+  UNAVAILABLE_FOR_LEGAL_REASONS:    0x1c3,
+  INTERNAL_SERVER_ERROR:            0x1f4,
+  NOT_IMPLEMENTED:                  0x1f5,
+  BAD_GATEWAY:                      0x1f6,
+  SERVICE_UNAVAILABLE:              0x1f7,
+  GATEWAY_TIMEOUT:                  0x1f8,
+  HTTP_VERSION_NOT_SUPPORTED:       0x1f9,
+});
+
 // Errors that are permanently fatal — do NOT retry.
-var NON_RETRYABLE_HTTP_STATUS = new Set([400, 401, 403, 404, 405, 409, 410, 411, 412, 413, 414, 415, 416, 417, 422, 451, 501, 505]);
+var NON_RETRYABLE_HTTP_STATUS = new Set([
+  HTTP.BAD_REQUEST, HTTP.UNAUTHORIZED, HTTP.FORBIDDEN, HTTP.NOT_FOUND,
+  HTTP.METHOD_NOT_ALLOWED, HTTP.CONFLICT, HTTP.GONE, HTTP.LENGTH_REQUIRED,
+  HTTP.PRECONDITION_FAILED, HTTP.PAYLOAD_TOO_LARGE, HTTP.URI_TOO_LONG,
+  HTTP.UNSUPPORTED_MEDIA_TYPE, HTTP.RANGE_NOT_SATISFIABLE, HTTP.EXPECTATION_FAILED,
+  HTTP.UNPROCESSABLE_ENTITY, HTTP.UNAVAILABLE_FOR_LEGAL_REASONS,
+  HTTP.NOT_IMPLEMENTED, HTTP.HTTP_VERSION_NOT_SUPPORTED,
+]);
 
 // Errors that should be retried — transient by nature.
-var RETRYABLE_HTTP_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+var RETRYABLE_HTTP_STATUS = new Set([
+  HTTP.REQUEST_TIMEOUT, HTTP.TOO_EARLY, HTTP.TOO_MANY_REQUESTS,
+  HTTP.INTERNAL_SERVER_ERROR, HTTP.BAD_GATEWAY, HTTP.SERVICE_UNAVAILABLE,
+  HTTP.GATEWAY_TIMEOUT,
+]);
 
 // Network errors from Node's net layer that map to "retry" semantics.
 var RETRYABLE_NET_ERRORS = new Set([
@@ -174,7 +217,10 @@ function backoffDelay(attempt, opts) {
   opts = opts || DEFAULT_RETRY;
   var base = opts.baseDelayMs * Math.pow(2, attempt - 1);
   var capped = Math.min(base, opts.maxDelayMs);
-  var jitter = capped * opts.jitterFactor * Math.random();
+  // Cryptographically-strong jitter so a timing-attack mitigation isn't
+  // undermined by Math.random's predictable PRNG.
+  var jitterDenom = 1_000_000;
+  var jitter = capped * opts.jitterFactor * (nodeCrypto.randomInt(0, jitterDenom) / jitterDenom);
   return Math.floor(capped - jitter);
 }
 
@@ -211,8 +257,11 @@ async function withRetry(fn, opts) {
       _emitEvent("retry.attempt", 1, { attempt: attempt });
       if (typeof opts.onRetry === "function") {
         // 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) {}
+        // so a thrown observer can't crash the retry loop. Routed via
+        // the same observability event sink so operators can still see
+        // mis-wired callbacks in their event stream.
+        try { opts.onRetry({ attempt: attempt, delay: delay, error: err }); }
+        catch (cbErr) { _emitEvent("retry.onRetry.threw", 1, { error: cbErr.message }); }
       }
       // Honor opts.signal during the backoff sleep — a caller who aborts
       // mid-retry should be unblocked immediately rather than waiting