@blamejs/core 0.9.12 → 0.9.15

package/lib/queue-local.js

@@ -35,7 +35,7 @@ var C = require("./constants");
 var { generateToken } = require("./crypto");
 var cryptoField = require("./crypto-field");
 var lazyRequire = require("./lazy-require");
-var nb = require("./numeric-bounds");
+var numericBounds = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var scheduler = require("./scheduler");
 var { QueueError } = require("./framework-error");
@@ -388,10 +388,10 @@ function create(_config) {
     opts = opts || {};
     var limit = 100;
     if (opts.limit !== undefined) {
-      if (!nb.isPositiveFiniteInt(opts.limit)) {
+      if (!numericBounds.isPositiveFiniteInt(opts.limit)) {
         throw new QueueError("queue/bad-opt",
           "queue.dlqList: limit must be a positive finite integer; got " +
-            nb.shape(opts.limit), true);
+            numericBounds.shape(opts.limit), true);
       }
       limit = opts.limit;
     }

package/lib/queue.js

@@ -43,7 +43,7 @@
  */
 var C = require("./constants");
 var clusterStorage = require("./cluster-storage");
-var crypto = require("./crypto");
+var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var { boot } = require("./log");
 var numericChecks = require("./numeric-checks");
@@ -877,7 +877,7 @@ function enqueueFlow(spec) {
     return Promise.reject(e);
   }
 
-  var flowId = "flow-" + crypto.generateToken(C.BYTES.bytes(8));
+  var flowId = "flow-" + bCrypto.generateToken(C.BYTES.bytes(8));
 
   return observability.tap("queue.enqueueFlow",
     { queueName: spec.queueName, flowId: flowId, childCount: spec.children.length },

package/lib/redis-client.js

@@ -25,8 +25,8 @@
  * callers can branch on transport vs server-side errors.
  */
 var net = require("node:net");
-var tls = require("node:tls");
-var url = require("node:url");
+var nodeTls = require("node:tls");
+var nodeUrl = require("node:url");
 var C = require("./constants");
 var safeAsync = require("./safe-async");
 var validateOpts = require("./validate-opts");
@@ -319,7 +319,7 @@ function create(opts) {
           var tlsConnectOpts = { host: host, port: port };
           if (servername) tlsConnectOpts.servername = servername;
           if (caBundle)   tlsConnectOpts.ca = caBundle;
-          sock = tls.connect(tlsConnectOpts, onOk);
+          sock = nodeTls.connect(tlsConnectOpts, onOk);
         } else {
           sock = net.connect({ host: host, port: port }, onOk);
         }
@@ -457,7 +457,7 @@ function create(opts) {
 // Empty-username + non-empty password is the legacy single-arg AUTH form.
 function _parseRedisUrl(s) {
   var u;
-  try { u = new url.URL(s); }
+  try { u = new nodeUrl.URL(s); }
   catch (e) {
     throw _err("BAD_URL", "redis url parse failed: " + ((e && e.message) || String(e)));
   }

package/lib/restore-bundle.js

@@ -45,8 +45,8 @@
  *   Backup-bundle reader — verify the manifest signature, list bundle contents without decrypting, and cherry-pick a restore subset to a staging directory the caller atomically swaps into place.
  */
 
-var fs = require("fs");
-var path = require("path");
+var nodeFs = require("fs");
+var nodePath = require("path");
 var atomicFile = require("./atomic-file");
 var backupCrypto = require("./backup/crypto");
 var backupManifest = require("./backup/manifest");
@@ -65,7 +65,7 @@ function _cleanupStaging(stagingDir) {
   // Best-effort recursive remove — if cleanup fails, surface that to
   // the caller via stderr but never override the original error
   // we're already throwing.
-  try { fs.rmSync(stagingDir, { recursive: true, force: true }); }
+  try { nodeFs.rmSync(stagingDir, { recursive: true, force: true }); }
   catch (_e) { /* best-effort */ }
 }
 
@@ -123,15 +123,15 @@ function _cleanupStaging(stagingDir) {
 async function extract(opts) {
   var t0 = Date.now();
   opts = opts || {};
-  if (typeof opts.bundleDir !== "string" || !fs.existsSync(opts.bundleDir)) {
+  if (typeof opts.bundleDir !== "string" || !nodeFs.existsSync(opts.bundleDir)) {
     throw new RestoreBundleError("restore-bundle/no-bundle",
       "extract: opts.bundleDir is required and must exist");
   }
   validateOpts.requireNonEmptyString(opts.stagingDir, "extract: opts.stagingDir", RestoreBundleError, "restore-bundle/no-staging");
-  if (fs.existsSync(opts.stagingDir)) {
+  if (nodeFs.existsSync(opts.stagingDir)) {
     throw new RestoreBundleError("restore-bundle/staging-exists",
       "extract: stagingDir already exists: " + opts.stagingDir +
-      " (refusing to merge into existing directory — pick a fresh path)");
+      " (refusing to merge into existing directory — pick a fresh nodePath)");
   }
   if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
     throw new RestoreBundleError("restore-bundle/no-passphrase",
@@ -145,14 +145,14 @@ async function extract(opts) {
 
   // 1. Read + parse + validate manifest
   _emit(progress, { phase: "read_manifest" });
-  var manifestPath = path.join(bundleDir, "manifest.json");
-  if (!fs.existsSync(manifestPath)) {
+  var manifestPath = nodePath.join(bundleDir, "manifest.json");
+  if (!nodeFs.existsSync(manifestPath)) {
     throw new RestoreBundleError("restore-bundle/missing-manifest",
       "extract: bundleDir has no manifest.json — bundle is incomplete or not a blamejs backup");
   }
   var manifest;
   try {
-    manifest = backupManifest.parse(fs.readFileSync(manifestPath, "utf8"));
+    manifest = backupManifest.parse(nodeFs.readFileSync(manifestPath, "utf8"));
   } catch (e) {
     if (e && e.isBackupManifestError) throw e;
     throw new RestoreBundleError("restore-bundle/bad-manifest",
@@ -215,13 +215,13 @@ async function extract(opts) {
         continue;
       }
 
-      var blobPath = path.join(bundleDir, entry.encryptedPath);
-      if (!fs.existsSync(blobPath)) {
+      var blobPath = nodePath.join(bundleDir, entry.encryptedPath);
+      if (!nodeFs.existsSync(blobPath)) {
         throw new RestoreBundleError("restore-bundle/missing-blob",
           "extract: manifest references '" + entry.encryptedPath +
           "' but the bundle has no such file");
       }
-      var blob = fs.readFileSync(blobPath);
+      var blob = nodeFs.readFileSync(blobPath);
       if (blob.length !== entry.encryptedSize) {
         throw new RestoreBundleError("restore-bundle/size-mismatch",
           "extract: blob '" + entry.encryptedPath + "' has size " + blob.length +
@@ -257,8 +257,8 @@ async function extract(opts) {
           " — bundle is corrupted or manifest tampered");
       }
 
-      var destPath = path.join(stagingDir, entry.relativePath);
-      atomicFile.ensureDir(path.dirname(destPath));
+      var destPath = nodePath.join(stagingDir, entry.relativePath);
+      atomicFile.ensureDir(nodePath.dirname(destPath));
       atomicFile.writeSync(destPath, plaintext, { fileMode: 0o600 });
 
       fileCount++;
@@ -321,16 +321,16 @@ async function extract(opts) {
  */
 function inspect(opts) {
   opts = opts || {};
-  if (typeof opts.bundleDir !== "string" || !fs.existsSync(opts.bundleDir)) {
+  if (typeof opts.bundleDir !== "string" || !nodeFs.existsSync(opts.bundleDir)) {
     throw new RestoreBundleError("restore-bundle/no-bundle",
       "inspect: opts.bundleDir is required and must exist");
   }
-  var manifestPath = path.join(opts.bundleDir, "manifest.json");
-  if (!fs.existsSync(manifestPath)) {
+  var manifestPath = nodePath.join(opts.bundleDir, "manifest.json");
+  if (!nodeFs.existsSync(manifestPath)) {
     throw new RestoreBundleError("restore-bundle/missing-manifest",
       "inspect: bundleDir has no manifest.json");
   }
-  return backupManifest.parse(fs.readFileSync(manifestPath, "utf8"));
+  return backupManifest.parse(nodeFs.readFileSync(manifestPath, "utf8"));
 }
 
 module.exports = {

package/lib/restore-rollback.js

@@ -6,7 +6,7 @@
  *
  * @intro
  *   Backup-restore safety net — atomic dataDir swap with a versioned
- *   rollback path. The primitive `b.restore` calls to put a
+ *   rollback nodePath. The primitive `b.restore` calls to put a
  *   freshly-decrypted bundle into place: filesystem rename is atomic
  *   on POSIX (and on Windows when nothing has the dir open), so the
  *   swap either fully completes or the previous `dataDir` is
@@ -39,14 +39,14 @@
  *   corrupting state.
  *
  * @card
- *   Backup-restore safety net — atomic dataDir swap with a versioned rollback path.
+ *   Backup-restore safety net — atomic dataDir swap with a versioned rollback nodePath.
  */
 
-var fs = require("fs");
-var path = require("path");
+var nodeFs = require("fs");
+var nodePath = require("path");
 var atomicFile = require("./atomic-file");
 var C = require("./constants");
-var nb = require("./numeric-bounds");
+var numericBounds = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var { defineClass } = require("./framework-error");
 
@@ -94,7 +94,7 @@ function _resolveRollbackRoot(opts) {
  */
 function swap(opts) {
   opts = opts || {};
-  if (typeof opts.stagingDir !== "string" || !fs.existsSync(opts.stagingDir)) {
+  if (typeof opts.stagingDir !== "string" || !nodeFs.existsSync(opts.stagingDir)) {
     throw new RestoreRollbackError("restore-rollback/no-staging",
       "swap: opts.stagingDir is required and must exist");
   }
@@ -106,20 +106,20 @@ function swap(opts) {
   atomicFile.ensureDir(rollbackRoot);
 
   var swappedAt = atomicFile.pathTimestamp();
-  var rollbackPath = path.join(rollbackRoot, swappedAt);
-  var markerPath = path.join(rollbackRoot, swappedAt + ".marker.json");
+  var rollbackPath = nodePath.join(rollbackRoot, swappedAt);
+  var markerPath = nodePath.join(rollbackRoot, swappedAt + ".marker.json");
 
-  if (fs.existsSync(rollbackPath) || fs.existsSync(markerPath)) {
+  if (nodeFs.existsSync(rollbackPath) || nodeFs.existsSync(markerPath)) {
     throw new RestoreRollbackError("restore-rollback/collision",
       "swap: a rollback at " + rollbackPath + " already exists — refusing to overwrite");
   }
 
-  var hadDataDir = fs.existsSync(opts.dataDir);
+  var hadDataDir = nodeFs.existsSync(opts.dataDir);
 
-  // Step 1: rename current dataDir → rollback path. Skipped on first
+  // Step 1: rename current dataDir → rollback nodePath. Skipped on first
   // restore (no existing dataDir).
   if (hadDataDir) {
-    try { fs.renameSync(opts.dataDir, rollbackPath); }
+    try { nodeFs.renameSync(opts.dataDir, rollbackPath); }
     catch (e) {
       throw new RestoreRollbackError("restore-rollback/rename-existing-failed",
         "swap: could not move existing dataDir to rollback: " + ((e && e.message) || String(e)));
@@ -127,11 +127,11 @@ function swap(opts) {
   }
 
   // Step 2: rename staging → dataDir
-  try { fs.renameSync(opts.stagingDir, opts.dataDir); }
+  try { nodeFs.renameSync(opts.stagingDir, opts.dataDir); }
   catch (e) {
     // Step 2 failed — try to undo step 1 so the operator's dataDir is back
     if (hadDataDir) {
-      try { fs.renameSync(rollbackPath, opts.dataDir); }
+      try { nodeFs.renameSync(rollbackPath, opts.dataDir); }
       catch (_e) { /* dataDir is now in rollbackPath; operator must recover manually */ }
     }
     throw new RestoreRollbackError("restore-rollback/rename-staging-failed",
@@ -148,7 +148,7 @@ function swap(opts) {
     operator:     opts.marker || null,
   };
   try {
-    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
+    nodeFs.writeFileSync(markerPath, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
   } catch (_e) { /* marker write is best-effort */ }
 
   return {
@@ -193,19 +193,19 @@ async function rollback(opts) {
     throw new RestoreRollbackError("restore-rollback/no-datadir",
       "rollback: opts.dataDir is required");
   }
-  if (typeof opts.rollbackPath !== "string" || !fs.existsSync(opts.rollbackPath)) {
+  if (typeof opts.rollbackPath !== "string" || !nodeFs.existsSync(opts.rollbackPath)) {
     throw new RestoreRollbackError("restore-rollback/no-rollback",
       "rollback: opts.rollbackPath is required and must exist");
   }
 
   // Move the current dataDir aside (so the rollback's rename target is empty)
   var discardedAt = null;
-  if (fs.existsSync(opts.dataDir)) {
+  if (nodeFs.existsSync(opts.dataDir)) {
     var rollbackRoot = _resolveRollbackRoot(opts);
     atomicFile.ensureDir(rollbackRoot);
     discardedAt = atomicFile.pathTimestamp();
-    var discardedPath = path.join(rollbackRoot, "discarded-" + discardedAt);
-    try { fs.renameSync(opts.dataDir, discardedPath); }
+    var discardedPath = nodePath.join(rollbackRoot, "discarded-" + discardedAt);
+    try { nodeFs.renameSync(opts.dataDir, discardedPath); }
     catch (e) {
       throw new RestoreRollbackError("restore-rollback/rename-existing-failed",
         "rollback: could not move current dataDir aside: " + ((e && e.message) || String(e)));
@@ -214,7 +214,7 @@ async function rollback(opts) {
   }
 
   // Rename the rollback dir back into dataDir's place
-  try { fs.renameSync(opts.rollbackPath, opts.dataDir); }
+  try { nodeFs.renameSync(opts.rollbackPath, opts.dataDir); }
   catch (e) {
     throw new RestoreRollbackError("restore-rollback/rollback-rename-failed",
       "rollback: could not move rollback into dataDir: " + ((e && e.message) || String(e)) +
@@ -223,7 +223,7 @@ async function rollback(opts) {
 
   // Best-effort: clean up the marker file alongside the rollback path
   var markerPath = opts.rollbackPath + ".marker.json";
-  try { if (fs.existsSync(markerPath)) fs.unlinkSync(markerPath); }
+  try { if (nodeFs.existsSync(markerPath)) nodeFs.unlinkSync(markerPath); }
   catch (_e) { /* marker cleanup is best-effort */ }
 
   return {
@@ -258,22 +258,22 @@ async function rollback(opts) {
 function list(opts) {
   opts = opts || {};
   var rollbackRoot = _resolveRollbackRoot(opts);
-  if (!fs.existsSync(rollbackRoot)) return [];
-  var entries = fs.readdirSync(rollbackRoot, { withFileTypes: true });
+  if (!nodeFs.existsSync(rollbackRoot)) return [];
+  var entries = nodeFs.readdirSync(rollbackRoot, { withFileTypes: true });
   var out = [];
   for (var i = 0; i < entries.length; i++) {
     if (!entries[i].isDirectory()) continue;
     var name = entries[i].name;
     if (name.indexOf("discarded-") === 0) continue; // discarded dirs aren't restore points
-    var p = path.join(rollbackRoot, name);
+    var p = nodePath.join(rollbackRoot, name);
     var markerPath = p + ".marker.json";
     var marker = null;
-    if (fs.existsSync(markerPath)) {
-      try { marker = safeJson.parse(fs.readFileSync(markerPath, "utf8"), { maxBytes: C.BYTES.kib(64) }); }
+    if (nodeFs.existsSync(markerPath)) {
+      try { marker = safeJson.parse(nodeFs.readFileSync(markerPath, "utf8"), { maxBytes: C.BYTES.kib(64) }); }
       catch (_e) { marker = null; }
     }
     var stat;
-    try { stat = fs.statSync(p); } catch (_e) { continue; }
+    try { stat = nodeFs.statSync(p); } catch (_e) { continue; }
     out.push({
       rollbackPath: p,
       swappedAt:    (marker && marker.swappedAt) || stat.mtime.toISOString(),
@@ -311,18 +311,18 @@ function list(opts) {
  */
 function purge(opts) {
   opts = opts || {};
-  nb.requireNonNegativeFiniteIntIfPresent(opts.keep,
+  numericBounds.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: [] };
+  if (!nodeFs.existsSync(rollbackRoot)) return { kept: keep, deleted: [] };
   // Always sweep "discarded-*" dirs — they're never restore points
-  var entries = fs.readdirSync(rollbackRoot, { withFileTypes: true });
+  var entries = nodeFs.readdirSync(rollbackRoot, { withFileTypes: true });
   var deleted = [];
   for (var i = 0; i < entries.length; i++) {
     if (entries[i].isDirectory() && entries[i].name.indexOf("discarded-") === 0) {
-      var p = path.join(rollbackRoot, entries[i].name);
-      try { fs.rmSync(p, { recursive: true, force: true }); deleted.push(p); }
+      var p = nodePath.join(rollbackRoot, entries[i].name);
+      try { nodeFs.rmSync(p, { recursive: true, force: true }); deleted.push(p); }
       catch (_e) { /* best-effort */ }
     }
   }
@@ -333,9 +333,9 @@ function purge(opts) {
   for (var j = 0; j < toDelete.length; j++) {
     var rbPath = toDelete[j].rollbackPath;
     var mkPath = rbPath + ".marker.json";
-    try { fs.rmSync(rbPath, { recursive: true, force: true }); deleted.push(rbPath); }
+    try { nodeFs.rmSync(rbPath, { recursive: true, force: true }); deleted.push(rbPath); }
     catch (_e) { /* best-effort */ }
-    try { if (fs.existsSync(mkPath)) fs.unlinkSync(mkPath); }
+    try { if (nodeFs.existsSync(mkPath)) nodeFs.unlinkSync(mkPath); }
     catch (_e) { /* best-effort */ }
   }
   return { kept: keep, deleted: deleted };

package/lib/restore.js

@@ -51,11 +51,11 @@
  *     manual recovery)
  */
 
-var fs = require("fs");
+var nodeFs = require("fs");
 var os = require("os");
-var path = require("path");
+var nodePath = require("path");
 var C = require("./constants");
-var crypto = require("./crypto");
+var bCrypto = require("./crypto");
 var numericChecks = require("./numeric-checks");
 var restoreBundle = require("./restore-bundle");
 var restoreRollback = require("./restore-rollback");
@@ -128,11 +128,11 @@ function create(opts) {
     while (stack.length > 0) {
       var current = stack.pop();
       var entries;
-      try { entries = fs.readdirSync(current, { withFileTypes: true }); }
+      try { entries = nodeFs.readdirSync(current, { withFileTypes: true }); }
       catch (_e) { continue; }
       for (var i = 0; i < entries.length; i++) {
         var entry = entries[i];
-        var full = path.join(current, entry.name);
+        var full = nodePath.join(current, entry.name);
         if (entry.isDirectory()) {
           stack.push(full);
         } else if (entry.isFile()) {
@@ -141,7 +141,7 @@ function create(opts) {
             return { tooManyFiles: true, fileCount: fileCount };
           }
           try {
-            totalBytes += fs.statSync(full).size;
+            totalBytes += nodeFs.statSync(full).size;
             if (totalBytes > maxPulledBytes) {
               return { tooManyBytes: true, totalBytes: totalBytes };
             }
@@ -200,8 +200,8 @@ function create(opts) {
         "inspect: bundle '" + bundleId + "' not in storage");
     }
     await _preflightBundleSize(bundleId);
-    var pullDir = path.join(os.tmpdir(),
-      "blamejs-restore-inspect-" + crypto.generateToken(4));
+    var pullDir = nodePath.join(os.tmpdir(),
+      "blamejs-restore-inspect-" + bCrypto.generateToken(4));
     try {
       await storage.readBundle(bundleId, pullDir);
       var pulled = _walkPullDirFootprint(pullDir);
@@ -217,7 +217,7 @@ function create(opts) {
       }
       return restoreBundle.inspect({ bundleDir: pullDir });
     } finally {
-      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
+      try { nodeFs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
     }
   }
 
@@ -234,13 +234,13 @@ function create(opts) {
         "run: bundle '" + bundleId + "' not in storage");
     }
 
-    var pullId = crypto.generateToken(4);
-    var pullDir    = path.join(os.tmpdir(), "blamejs-restore-pull-"    + pullId);
-    var stagingDir = path.join(os.tmpdir(), "blamejs-restore-staging-" + pullId);
+    var pullId = bCrypto.generateToken(4);
+    var pullDir    = nodePath.join(os.tmpdir(), "blamejs-restore-pull-"    + pullId);
+    var stagingDir = nodePath.join(os.tmpdir(), "blamejs-restore-staging-" + pullId);
 
     function _cleanupTmp() {
-      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 */ }
+      try { nodeFs.rmSync(pullDir,    { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
+      try { nodeFs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
     }
 
     // 1. Pull bundle out of storage
@@ -319,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) { /* best-effort tmpdir cleanup */ }
+      try { nodeFs.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");
@@ -331,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) { /* best-effort tmpdir cleanup */ }
+    try { nodeFs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) { /* best-effort tmpdir cleanup */ }
 
     var summary = {
       bundleId:     bundleId,

package/lib/retry.js

@@ -445,8 +445,58 @@ class CircuitBreaker {
   }
 }
 
+/**
+ * @primitive b.retry.withBreaker
+ * @signature b.retry.withBreaker(fn, opts)
+ * @since     0.9.13
+ * @status    stable
+ * @related   b.retry.withRetry, b.circuitBreaker.create
+ *
+ * Compose `withRetry` + a CircuitBreaker so one retry-loop invocation
+ * counts as exactly one breaker call. The breaker observes the
+ * eventual outcome of the retry loop (success or final failure), not
+ * each intermediate retry attempt — otherwise every retried call
+ * inflates the breaker's failure counter and the breaker opens far
+ * sooner than intended.
+ *
+ * Every downstream consumer that wants this composition writes
+ * `breaker.wrap(() => b.retry.withRetry(fn, retryOpts))` by hand;
+ * this primitive captures the pattern so the convention is uniform.
+ *
+ * @opts
+ *   retry:    Object,                // forwarded to withRetry — same options
+ *   breaker:  CircuitBreaker,        // existing breaker instance (required)
+ *
+ * @example
+ *   var cb = b.circuitBreaker.create({ name: "upstream-billing", failureThreshold: 5 });
+ *   var result = await b.retry.withBreaker(async function () {
+ *     return await fetch("https://billing.example.com/v1/charges");
+ *   }, {
+ *     retry:   { maxAttempts: 3, baseDelayMs: 500 },
+ *     breaker: cb,
+ *   });
+ */
+function withBreaker(fn, opts) {
+  opts = opts || {};
+  if (typeof fn !== "function") {
+    throw new TypeError("retry.withBreaker: fn must be a function, got " + typeof fn);
+  }
+  if (!opts.breaker || typeof opts.breaker.wrap !== "function") {
+    throw new TypeError("retry.withBreaker: opts.breaker must be a CircuitBreaker instance (with .wrap(fn))");
+  }
+  // breaker.wrap counts ONE breaker call regardless of how many retry
+  // attempts withRetry makes internally. The breaker only sees the
+  // final outcome — success closes it (after enough probes in
+  // half-open), or final failure opens it after `failureThreshold`
+  // exhausted-retry-loop calls.
+  return opts.breaker.wrap(function () {
+    return withRetry(fn, opts.retry || {});
+  });
+}
+
 module.exports = {
   withRetry:                 withRetry,
+  withBreaker:               withBreaker,
   isRetryable:               isRetryable,
   backoffDelay:              backoffDelay,
   CircuitBreaker:            CircuitBreaker,

package/lib/router.js

@@ -34,8 +34,8 @@
  */
 var http  = require("http");
 var http2 = require("http2");
-var fs = require("fs");
-var path = require("path");
+var nodeFs = require("fs");
+var nodePath = require("path");
 var C = require("./constants");
 var requestHelpers = require("./request-helpers");
 var lazyRequire = require("./lazy-require");
@@ -296,8 +296,8 @@ class Router {
     this.routes = [];
     this.middleware = [];
     // WebSocket routes are kept separate from HTTP routes — they're
-    // matched on the upgrade / Extended CONNECT path, not on a method
-    // verb. Map<path, { handler, opts }>.
+    // matched on the upgrade / Extended CONNECT nodePath, not on a method
+    // verb. Map<nodePath, { handler, opts }>.
     this._wsRoutes = new Map();
     // Active WebSocket connections opened through router.ws(). Tracked
     // so router.closeWebSockets() can do a clean rolling-shutdown.
@@ -407,7 +407,7 @@ class Router {
   //   process.exit(0);
   //
   // Tests use the same primitive in teardown — no parallel cleanup
-  // path, no h1-upgrade detached-socket workaround.
+  // nodePath, no h1-upgrade detached-socket workaround.
   async closeWebSockets(opts) {
     opts = opts || {};
     var timeoutMs = typeof opts.timeoutMs === "number" ? opts.timeoutMs : C.TIME.seconds(5);
@@ -603,7 +603,7 @@ class Router {
 
   // ---- WebSocket route registration ----
   //
-  // ws(path, handler, opts?)
+  // ws(nodePath, handler, opts?)
   //   path     — exact match. Path-param patterns aren't supported on
   //              upgrade requests; operators that need dynamic paths
   //              register one ws route per stable shape.
@@ -1089,7 +1089,7 @@ class Router {
     // server's emitter list clean for HTTP-only deployments.
     if (self._wsRoutes.size > 0) {
       // h1 upgrade event — fires for "Upgrade: websocket" from h1
-      // clients. Routes by path; refuses with 426 in h2-only mode.
+      // clients. Routes by nodePath; refuses with 426 in h2-only mode.
       server.on("upgrade", function (req, socket, head) {
         var pathname = String(req.url || "/").split("?")[0];
         var route = self._wsRoutes.get(pathname);
@@ -1201,18 +1201,18 @@ class Router {
  */
 // Static file serving middleware
 function serveStatic(dir) {
-  var root = path.resolve(dir);
+  var root = nodePath.resolve(dir);
   return (req, res, next) => {
     if (req.method !== "GET") return next();
     var rel = req.pathname;
     if (rel.includes("\0")) return next();
-    var filePath = path.resolve(path.join(root, rel));
+    var filePath = nodePath.resolve(nodePath.join(root, rel));
     if (!filePath.startsWith(root)) return next();
-    if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) return next();
+    if (!nodeFs.existsSync(filePath) || nodeFs.statSync(filePath).isDirectory()) return next();
 
-    var ext = path.extname(filePath).toLowerCase();
+    var ext = nodePath.extname(filePath).toLowerCase();
     var mime = MIME_TYPES[ext] || "application/octet-stream";
-    var stat = fs.statSync(filePath);
+    var stat = nodeFs.statSync(filePath);
     var hasVersion = req.url && req.url.includes("?v=");
     var cacheControl = hasVersion
       ? "public, max-age=31536000, immutable"
@@ -1222,7 +1222,7 @@ function serveStatic(dir) {
       "Content-Length": stat.size,
       "Cache-Control":  cacheControl,
     });
-    fs.createReadStream(filePath).pipe(res);
+    nodeFs.createReadStream(filePath).pipe(res);
   };
 }
 

package/lib/sandbox.js

@@ -78,11 +78,11 @@
  * arbitrary source from the public internet.
  */
 
-var path = require("path");
+var nodePath = require("path");
 var lazyRequire = require("./lazy-require");
 var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
-var constants = require("./constants");
+var C = require("./constants");
 var { SandboxError } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
@@ -110,14 +110,14 @@ var ALWAYS_AVAILABLE = Object.freeze([
   "Promise", "Error", "TypeError", "RangeError", "RegExp",
 ]);
 
-var WORKER_PATH = path.resolve(__dirname, "sandbox-worker.js");
+var WORKER_PATH = nodePath.resolve(__dirname, "sandbox-worker.js");
 
 // Default caps. Sourced from C.* helpers so the unit lives at the call site.
 var DEFAULT_TIMEOUT_MS = 250;
-var MAX_TIMEOUT_MS = constants.TIME.seconds(10);
-var DEFAULT_MAX_BYTES = constants.BYTES.mib(64);
-var MAX_MAX_BYTES = constants.BYTES.gib(1);
-var MIN_MAX_BYTES = constants.BYTES.mib(4);
+var MAX_TIMEOUT_MS = C.TIME.seconds(10);
+var DEFAULT_MAX_BYTES = C.BYTES.mib(64);
+var MAX_MAX_BYTES = C.BYTES.gib(1);
+var MIN_MAX_BYTES = C.BYTES.mib(4);
 
 function _validateAllowed(allowed) {
   if (allowed === undefined || allowed === null) return [];
@@ -217,7 +217,7 @@ function run(opts) {
   // floor so the worker can boot. Round each cap down to a MiB integer.
   // Floors / caps are quanta of MiB chosen to fit a small embedded
   // worker; passed straight to v8's resourceLimits.
-  var oneMib = constants.BYTES.mib(1);
+  var oneMib = C.BYTES.mib(1);
   // The MiB-unit caps below are integers passed directly to v8's
   // resourceLimits (already typed in MiB by the v8 API), not byte
   // counts - the constants helpers don't apply.