@blamejs/core 0.9.9 → 0.9.14

package/lib/metrics.js

@@ -39,6 +39,9 @@
 
 var C = require("./constants");
 var canonicalJson = require("./canonical-json");
+var nodeFs   = require("node:fs");
+var atomicFile = require("./atomic-file");
+var safeJson = require("./safe-json");
 var { defineClass } = require("./framework-error");
 var { boot } = require("./log");
 var nb = require("./numeric-bounds");
@@ -678,9 +681,253 @@ function _resetForTest() {
   _activeTap = null;
 }
 
+// ---- Snapshot writer/reader ----
+//
+// Out-of-process metrics export pattern for long-running daemons:
+// the daemon writes a JSON snapshot atomically every N seconds; a
+// separate CLI process reads + renders. Bypasses the HTTP-port +
+// Unix-socket coupling that the regular Prometheus exposition
+// handler requires. Useful for systemd daemons that don't want to
+// bind a stats port at all (operator runs `daemon stats` and the
+// CLI just reads the file).
+//
+// The writer is atomic — every write goes through atomic-file's
+// writeSync (temp-file + rename + fsync) so a reader that lands
+// between rename and fsync sees the previous complete snapshot
+// rather than a partially-written one.
+//
+// Surface:
+//
+//   var stop = b.metrics.snapshot.startWriter({
+//     path:       "/run/blamejs-daemon/metrics.json",
+//     intervalMs: 5000,
+//     fields:     function () { return { uptimeMs: ..., counters: {...} }; },
+//   });
+//   // ...later:
+//   stop();   // clears timer; runs one final fields() flush before returning
+//
+//   var snap = b.metrics.snapshot.read("/run/blamejs-daemon/metrics.json");
+//   process.stdout.write(b.metrics.snapshot.render(snap, { format: "text" }));
+
+/**
+ * @primitive b.metrics.snapshot.startWriter
+ * @signature b.metrics.snapshot.startWriter(opts)
+ * @since     0.9.13
+ * @status    stable
+ * @related   b.metrics.snapshot.read, b.metrics.snapshot.render
+ *
+ * Start a periodic writer that calls `opts.fields()` every
+ * `opts.intervalMs` and writes the returned object as JSON to
+ * `opts.path` atomically. Returns a `stop()` function that clears
+ * the timer + performs one final flush before resolving.
+ *
+ * @opts
+ *   path:        string,    // absolute path to write the snapshot
+ *   intervalMs:  number,    // milliseconds between flushes (>=100)
+ *   fields:      Function,  // returns an object — written as JSON
+ *
+ * @example
+ *   var stop = b.metrics.snapshot.startWriter({
+ *     path:       "/run/blamejs/metrics.json",
+ *     intervalMs: 5000,
+ *     fields:     function () {
+ *       return {
+ *         uptimeMs:    process.uptime() * 1000,
+ *         queueDepth:  myQueue.size,
+ *         lastSyncAt:  lastSyncAt,
+ *       };
+ *     },
+ *   });
+ *   // ... on SIGTERM:
+ *   stop();
+ */
+function snapshotStartWriter(opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(opts.path,
+    "metrics.snapshot.startWriter: opts.path",
+    MetricsError, "metrics-snapshot/bad-path");
+  if (typeof opts.intervalMs !== "number" || !isFinite(opts.intervalMs) || opts.intervalMs < 100) {
+    throw new MetricsError("metrics-snapshot/bad-interval",
+      "metrics.snapshot.startWriter: opts.intervalMs must be a finite number >= 100, got " + opts.intervalMs);
+  }
+  if (typeof opts.fields !== "function") {
+    throw new MetricsError("metrics-snapshot/bad-fields",
+      "metrics.snapshot.startWriter: opts.fields must be a function returning the snapshot object");
+  }
+  var p          = opts.path;
+  var fieldsFn   = opts.fields;
+  var intervalMs = opts.intervalMs;
+
+  var doFlush = function () {
+    var snap;
+    try {
+      snap = fieldsFn();
+    } catch (e) {
+      log("snapshot.fields() threw: " + (e && e.message ? e.message : String(e)));
+      return;
+    }
+    if (!snap || typeof snap !== "object") {
+      log("snapshot.fields() returned non-object; skipping flush");
+      return;
+    }
+    var payload = {
+      writtenAt: new Date().toISOString(),
+      fields:    snap,
+    };
+    try {
+      atomicFile.writeSync(p, JSON.stringify(payload) + "\n", { fileMode: 0o644 });
+    } catch (e) {
+      log("snapshot.writeSync failed: " + (e && e.message ? e.message : String(e)));
+    }
+  };
+
+  // First flush is synchronous so the file exists by the time
+  // startWriter returns. Subsequent flushes run on the interval.
+  doFlush();
+  var timer = setInterval(doFlush, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+
+  return function stop() {
+    clearInterval(timer);
+    doFlush();   // final flush captures last state before the daemon exits
+  };
+}
+
+/**
+ * @primitive b.metrics.snapshot.read
+ * @signature b.metrics.snapshot.read(path)
+ * @since     0.9.13
+ * @status    stable
+ * @related   b.metrics.snapshot.startWriter, b.metrics.snapshot.render
+ *
+ * Read + parse a snapshot file written by `startWriter`. Returns
+ * `{ writtenAt, fields }`. Throws `MetricsError` with code
+ * `metrics-snapshot/...` on missing file, parse failure, or
+ * shape mismatch.
+ *
+ * @example
+ *   var snap = b.metrics.snapshot.read("/run/blamejs/metrics.json");
+ *   console.log("uptime:", snap.fields.uptimeMs);
+ *   console.log("written at:", snap.writtenAt);
+ */
+function snapshotRead(p) {
+  validateOpts.requireNonEmptyString(p,
+    "metrics.snapshot.read: path",
+    MetricsError, "metrics-snapshot/bad-path");
+  var raw;
+  try {
+    raw = nodeFs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new MetricsError("metrics-snapshot/not-found",
+      "metrics.snapshot.read: " + p + " — " + (e && e.message ? e.message : String(e)));
+  }
+  var parsed;
+  // safeJson.parse with bounded maxBytes — the snapshot file is read
+  // by a separate CLI / sidecar process from where it's written, and a
+  // hostile actor with write access to the snapshot path could replace
+  // it with a multi-GB file that would OOM the reader. 4 MiB ceiling
+  // is well above the framework's expected snapshot size (~5-50 KiB)
+  // and the safeJson absolute cap stays within reach.
+  try {
+    parsed = safeJson.parse(raw, { maxBytes: 4 * 1024 * 1024 });   // allow:raw-byte-literal — 4 MiB snapshot-file ceiling
+  } catch (e) {
+    throw new MetricsError("metrics-snapshot/bad-json",
+      "metrics.snapshot.read: " + p + " contains invalid JSON: " + (e && e.message ? e.message : String(e)));
+  }
+  if (!parsed || typeof parsed !== "object" ||
+      typeof parsed.writtenAt !== "string" || !parsed.fields ||
+      typeof parsed.fields !== "object") {
+    throw new MetricsError("metrics-snapshot/bad-shape",
+      "metrics.snapshot.read: " + p + " is not a startWriter-produced snapshot (missing writtenAt or fields)");
+  }
+  return parsed;
+}
+
+/**
+ * @primitive b.metrics.snapshot.render
+ * @signature b.metrics.snapshot.render(snap, opts)
+ * @since     0.9.13
+ * @status    stable
+ * @related   b.metrics.snapshot.read
+ *
+ * Format a snapshot object for human or machine consumption.
+ *
+ *   format: "text"       — operator-readable lines, one field per row (default)
+ *   format: "prometheus" — Prometheus 0.0.4 text format, gauge metrics
+ *                          named with a configurable prefix; only top-level
+ *                          numeric fields under `snap.fields` are emitted
+ *
+ * @opts
+ *   format:  "text" | "prometheus",   // default: "text"
+ *   prefix:  string,                   // prometheus-only; default: "blamejs"
+ *
+ * @example
+ *   var snap = b.metrics.snapshot.read("/run/blamejs/metrics.json");
+ *   process.stdout.write(b.metrics.snapshot.render(snap));
+ *   // or for Prometheus scraping:
+ *   res.setHeader("Content-Type", "text/plain; version=0.0.4");
+ *   res.end(b.metrics.snapshot.render(snap, { format: "prometheus", prefix: "myapp" }));
+ */
+function snapshotRender(snap, opts) {
+  opts = opts || {};
+  var format = opts.format || "text";
+  if (!snap || typeof snap !== "object" || !snap.fields) {
+    throw new MetricsError("metrics-snapshot/bad-snap",
+      "metrics.snapshot.render: snap must be a startWriter-produced object (got " + typeof snap + ")");
+  }
+  var fields = snap.fields;
+  if (format === "text") {
+    var lines = ["snapshot written-at: " + snap.writtenAt];
+    // allow:bare-canonicalize-walk — sort is for stable human-readable
+    // output ordering, not canonicalize-for-hashing
+    var keys = Object.keys(fields).sort();
+    for (var i = 0; i < keys.length; i++) {
+      var k = keys[i];
+      var v = fields[k];
+      var s;
+      if (typeof v === "number") s = String(v);
+      else if (typeof v === "string") s = v;
+      else if (typeof v === "boolean") s = v ? "true" : "false";
+      else s = JSON.stringify(v);
+      lines.push("  " + k + ": " + s);
+    }
+    return lines.join("\n") + "\n";
+  }
+  if (format === "prometheus") {
+    var prefix = opts.prefix || "blamejs";
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(prefix)) {
+      throw new MetricsError("metrics-snapshot/bad-prefix",
+        "metrics.snapshot.render: prometheus prefix must match [a-zA-Z_][a-zA-Z0-9_]*, got '" + prefix + "'");
+    }
+    var out = [];
+    // allow:bare-canonicalize-walk — sort is for stable Prometheus
+    // exposition output ordering, not canonicalize-for-hashing
+    var keys2 = Object.keys(fields).sort();
+    for (var j = 0; j < keys2.length; j++) {
+      var k2 = keys2[j];
+      var v2 = fields[k2];
+      if (typeof v2 !== "number" || !isFinite(v2)) continue;   // only numeric scalars
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k2)) continue;       // skip prom-incompatible names
+      var metric = prefix + "_" + k2;
+      out.push("# TYPE " + metric + " gauge");
+      out.push(metric + " " + v2);
+    }
+    return out.join("\n") + "\n";
+  }
+  throw new MetricsError("metrics-snapshot/bad-format",
+    "metrics.snapshot.render: format must be 'text' or 'prometheus', got '" + format + "'");
+}
+
+var snapshot = {
+  startWriter: snapshotStartWriter,
+  read:        snapshotRead,
+  render:      snapshotRender,
+};
+
 module.exports = {
   create:                    create,
   tap:                       tap,
+  snapshot:                  snapshot,
   MetricsError:              MetricsError,
   DEFAULT_HTTP_BUCKETS:      DEFAULT_HTTP_BUCKETS,
   DEFAULT_CARDINALITY_CAP:   DEFAULT_CARDINALITY_CAP,

package/lib/middleware/idempotency-key.js

@@ -44,6 +44,8 @@ var nodeCrypto    = require("node:crypto");
 var lazyRequire   = require("../lazy-require");
 var numericBounds = require("../numeric-bounds");
 var safeBuffer    = require("../safe-buffer");
+var safeJson      = require("../safe-json");
+var safeSql       = require("../safe-sql");
 var { defineClass } = require("../framework-error");
 
 var audit          = lazyRequire(function () { return require("../audit"); });
@@ -124,6 +126,153 @@ function memoryStore(opts) {
   };
 }
 
+// Operator-supplied table name is validated via b.safeSql.validateIdentifier
+// — single source of truth for the framework's SQL-identifier shape
+// (ASCII identifier chars only, 63-char cap, no reserved words). Direct
+// interpolation is safe once the validator throws on bad input.
+
+/**
+ * @primitive b.middleware.idempotencyKey.dbStore
+ * @signature b.middleware.idempotencyKey.dbStore(opts)
+ * @since     0.9.14
+ * @status    stable
+ * @related   b.middleware.idempotencyKey, b.middleware.idempotencyKey.memoryStore, b.db
+ *
+ * Persistent-backed store for `idempotencyKey` middleware. Implements
+ * the same three-method interface as `memoryStore` (`get` / `set` /
+ * `delete`) but stores records in a SQLite-shaped database — the
+ * framework's internal `b.db`, an operator-supplied better-sqlite3
+ * instance, or any object exposing `prepare(sql) → { run, get, all }`.
+ *
+ * Use `dbStore` instead of `memoryStore` when:
+ *
+ *   - multiple processes share the request-handling fleet (forks
+ *     behind a load balancer, multi-instance K8s deployment) and a
+ *     retry can land on a different process than the original
+ *     request — only a shared store satisfies the §2 replay
+ *     semantics across the fleet;
+ *   - the daemon may restart between the original request and the
+ *     retry (graceful rolling deploy, OOM kill, planned reboot) —
+ *     `memoryStore` is volatile, `dbStore` survives the restart;
+ *   - audit / compliance review needs to walk historic
+ *     idempotency cache decisions — `dbStore` is queryable with
+ *     `SELECT * FROM <tableName>`, `memoryStore` is opaque.
+ *
+ * Lazily-expired: `get(key)` returns `null` for any row whose
+ * `expires_at` has passed (the row is deleted on the same call).
+ * `set(key, value, ttlMs)` upserts on conflict so a concurrent retry
+ * landing on a different process doesn't error out. `delete(key)` is
+ * idempotent (no-op when absent).
+ *
+ * @opts
+ *   db:         object,   // required — sqlite-shaped: { prepare(sql) → { run, get, all } }
+ *   tableName?: string,   // default "blamejs_idempotency_keys"; validated via b.safeSql.validateIdentifier
+ *   init?:      boolean,  // default true — run CREATE TABLE IF NOT EXISTS at construction
+ *
+ * @example
+ *   // single-process daemon, framework's internal sqlite:
+ *   var b = require("blamejs");
+ *   await b.db.init({ dataDir: "/var/lib/myapp", schema: [] });
+ *   var store = b.middleware.idempotencyKey.dbStore({ db: b.db });
+ *   var mw = b.middleware.idempotencyKey({
+ *     store: store,
+ *     ttlMs: b.constants.TIME.hours(24),
+ *   });
+ *   app.use(mw);
+ *
+ * @example
+ *   // multi-process fleet, shared better-sqlite3 instance over WAL:
+ *   var Database = require("better-sqlite3");
+ *   var db = new Database("/var/lib/myapp/idempotency.db", { fileMustExist: false });
+ *   db.pragma("journal_mode = WAL");
+ *   var store = b.middleware.idempotencyKey.dbStore({
+ *     db:        db,
+ *     tableName: "request_idempotency",
+ *   });
+ */
+function dbStore(opts) {
+  opts = opts || {};
+  if (!opts.db || typeof opts.db !== "object" || typeof opts.db.prepare !== "function") {
+    throw new IdempotencyError("idempotency/bad-db",
+      "dbStore: opts.db must be a sqlite-shaped database with a `prepare(sql)` method", true);
+  }
+  var tableNameRaw = opts.tableName !== undefined ? opts.tableName : "blamejs_idempotency_keys";
+  // Quote-and-validate in one step. safeSql.quoteIdentifier runs
+  // validateIdentifier internally (rejects bad shape / reserved
+  // words / sqlite_-prefixed names) and emits the dialect-correct
+  // double-quoted form. Identifier ALWAYS reaches SQL through the
+  // quoted form — defense-in-depth so a future shape-regex bypass
+  // can't reach raw concatenation. Per PR #44 review.
+  var qTable;
+  try { qTable = safeSql.quoteIdentifier(tableNameRaw, "sqlite"); }
+  catch (sqlErr) {
+    throw new IdempotencyError("idempotency/bad-table-name",
+      "dbStore: opts.tableName is not a valid SQL identifier: " +
+      (sqlErr && sqlErr.message ? sqlErr.message : String(sqlErr)), true);
+  }
+  var qIndex = safeSql.quoteIdentifier(tableNameRaw + "_expires_idx", "sqlite");
+  var doInit = opts.init !== false;
+  var db = opts.db;
+
+  if (doInit) {
+    db.prepare("CREATE TABLE IF NOT EXISTS " + qTable + " (" +
+      "k TEXT PRIMARY KEY, " +
+      "v TEXT NOT NULL, " +
+      "expires_at INTEGER NOT NULL)").run();
+    db.prepare("CREATE INDEX IF NOT EXISTS " + qIndex + " ON " +
+      qTable + "(expires_at)").run();
+  }
+
+  // Prepare once; reused on every store call. Statements cache to the
+  // framework's bounded prepare-cache automatically when db = b.db.
+  var stmtGet         = db.prepare("SELECT v, expires_at FROM " + qTable + " WHERE k = ?");
+  var stmtUpsert      = db.prepare("INSERT INTO " + qTable + "(k, v, expires_at) VALUES (?, ?, ?) " +
+    "ON CONFLICT(k) DO UPDATE SET v = excluded.v, expires_at = excluded.expires_at");
+  var stmtDelete      = db.prepare("DELETE FROM " + qTable + " WHERE k = ?");
+  // Conditional delete — only removes the row when expires_at still
+  // matches the version we observed. In a multi-process deployment
+  // another process can upsert the same key between our SELECT and
+  // DELETE; an unconditional `DELETE WHERE k = ?` would erase the
+  // FRESH replacement and turn a valid cached response into a miss
+  // (idempotency replay broken under concurrent retries). Per Codex
+  // P1 on PR #44.
+  var stmtDeleteStale = db.prepare("DELETE FROM " + qTable +
+    " WHERE k = ? AND expires_at <= ?");
+
+  return {
+    get: function (key) {
+      var row = stmtGet.get(key);
+      if (!row) return null;
+      if (row.expires_at < Date.now()) {
+        // Scoped delete by the observed expires_at so a concurrent
+        // upsert that wrote a fresher row isn't clobbered.
+        stmtDeleteStale.run(key, row.expires_at);
+        return null;
+      }
+      // safeJson.parse with bounded maxBytes — even though row.v is
+      // written by our own .set() below, a multi-process deployment
+      // shares the table across processes; a misbehaving sibling
+      // could write a huge value that OOMs the reader. The default
+      // maxBodyBytes (1 MiB) bounds what the middleware captures, so
+      // a 4 MiB ceiling here gives headroom for JSON-envelope overhead.
+      try { return safeJson.parse(row.v, { maxBytes: 4 * 1024 * 1024 }); }                           // allow:raw-byte-literal — 4 MiB row-value ceiling
+      catch (_e) {
+        // Corrupt row — scope the delete by the observed expires_at so
+        // a concurrent upsert of valid bytes survives.
+        stmtDeleteStale.run(key, row.expires_at);
+        return null;
+      }
+    },
+    set: function (key, value, ttlMs) {
+      stmtUpsert.run(key, JSON.stringify(value), Date.now() + ttlMs);
+    },
+    delete: function (key) {
+      stmtDelete.run(key);
+    },
+    _tableName: tableNameRaw,
+  };
+}
+
 function _validateStore(store, where) {
   if (!store || typeof store !== "object") {
     throw new IdempotencyError("idempotency/bad-store",
@@ -420,5 +569,6 @@ function _redactKey(key) {
 module.exports = create;
 module.exports.create     = create;
 module.exports.memoryStore = memoryStore;
+module.exports.dbStore     = dbStore;
 module.exports.DEFAULT_METHODS = DEFAULT_METHODS;
 module.exports.IdempotencyError = IdempotencyError;

package/lib/pqc-agent.js

@@ -1,31 +1,29 @@
 "use strict";
 /**
- * pqc-agent — outbound HTTPS agent locked to PQC group preference.
+ * @module     b.pqcAgent
+ * @nav        Production
+ * @title      PQC Agent
+ * @order      630
  *
- * The framework's posture is "all outbound TLS is PQC-only". This is
- * the single primitive that defines what that means at the agent
- * level: TLSv1.3 minimum, ecdhCurve set to the framework's PQC hybrid
- * preference (constants.TLS_GROUP_CURVE_STR), keep-alive on.
+ * @intro
+ *   Outbound HTTPS agent locked to the framework's PQC group preference.
+ *   The framework's posture is "all outbound TLS is PQC-only"; this
+ *   primitive defines what that means at the agent level — TLSv1.3
+ *   minimum, `ecdhCurve` set to the framework's PQC hybrid preference
+ *   (`constants.TLS_GROUP_CURVE_STR`), keep-alive on.
  *
- * Two surfaces:
+ *   `b.pqcAgent.agent` is a process-wide default agent, lazy-built on
+ *   first access; `b.pqcAgent.create(opts)` builds a fresh agent with
+ *   custom pool / timeout opts (ecdhCurve and minVersion cannot be
+ *   weakened); `b.pqcAgent.reload()` tears down the default agent so
+ *   the next access rebuilds against current TLS posture.
  *
- *   1. b.pqcAgent.agent — a process-wide default agent, lazy-built on
- *      first access. Use this for one-off outbound calls that go
- *      through node:https directly:
+ *   `lib/http-client.js`'s transport cache uses `pqcAgent.create()` under
+ *   the hood, so the framework's bundled HTTP client and any operator-
+ *   direct `https.request` calls converge on the same agent posture.
  *
- *        https.request(url, { agent: b.pqcAgent.agent }, ...);
- *
- *   2. b.pqcAgent.create(opts) — build a fresh agent with custom
- *      pool / timeout opts. ecdhCurve and minVersion CANNOT be
- *      weakened via opts; operator-supplied values for those are
- *      ignored and the framework's defaults win. Operators who need
- *      a non-PQC agent for a deliberate one-off integration with a
- *      non-PQC server construct their own new https.Agent() directly,
- *      outside this primitive.
- *
- * lib/http-client.js's transport cache uses pqcAgent.create() under
- * the hood, so the framework's bundled HTTP client and any operator-
- * direct https.request calls converge on the same agent posture.
+ * @card
+ *   Outbound HTTPS agent locked to TLSv1.3 + framework PQC hybrid group preference.
  */
 
 var https = require("node:https");
@@ -152,14 +150,63 @@ function _buildAgentOpts(opts) {
   return merged;
 }
 
+/**
+ * @primitive b.pqcAgent.create
+ * @signature b.pqcAgent.create(opts?)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.pqcAgent.reload
+ *
+ * Build a fresh https.Agent locked to the framework PQC hybrid group
+ * preference (TLSv1.3 minimum, ecdhCurve set to
+ * `C.TLS_GROUP_CURVE_STR`). Operator-supplied values for ecdhCurve
+ * may NARROW the framework default (drop a group) but cannot widen it
+ * unless `opts.allowOperatorGroups: true` is set; minVersion is fixed
+ * at TLSv1.3 and cannot be weakened.
+ *
+ * @opts
+ *   keepAlive?:           boolean,
+ *   keepAliveMsecs?:      number,
+ *   maxSockets?:          number,
+ *   maxFreeSockets?:      number,
+ *   scheduling?:          string,
+ *   ecdhCurve?:           string,   // colon-separated group names; must subset C.TLS_GROUP_PREFERENCE
+ *   allowOperatorGroups?: boolean,  // default false; opt in to operator-supplied groups outside the framework PQC preference
+ *
+ * @example
+ *   var agent = b.pqcAgent.create({ maxSockets: 200 });
+ *   var req = https.request("https://api.example.com/v1/x", { agent: agent });
+ *   req.end();
+ */
 function create(opts) {
   return new https.Agent(_buildAgentOpts(opts));
 }
 
-// http (cleartext) variant — same pool defaults but obviously no TLS
-// posture to enforce. Operator-side, almost no caller wants this; it
-// exists so http-client's h1 transport for cleartext origins (h2c
-// fixtures, internal services) shares the pool tuning.
+/**
+ * @primitive b.pqcAgent.createHttp
+ * @signature b.pqcAgent.createHttp(opts?)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.pqcAgent.create
+ *
+ * Build a cleartext `http.Agent` with the same pool defaults as
+ * `b.pqcAgent.create` — no TLS posture to enforce. Exists so the
+ * framework's HTTP client's h1 transport for cleartext origins (h2c
+ * fixtures, internal services on a private network) shares the same
+ * pool tuning as the encrypted path.
+ *
+ * @opts
+ *   keepAlive?:      boolean,
+ *   keepAliveMsecs?: number,
+ *   maxSockets?:     number,
+ *   maxFreeSockets?: number,
+ *   scheduling?:     string,
+ *
+ * @example
+ *   var agent = b.pqcAgent.createHttp({ maxSockets: 100 });
+ *   var req = http.request("http://internal.svc/health", { agent: agent });
+ *   req.end();
+ */
 function createHttp(opts) {
   return new http.Agent(Object.assign({}, DEFAULT_OPTS, opts || {}));
 }
@@ -173,11 +220,54 @@ function _getDefaultAgent() {
   return _defaultAgent;
 }
 
+/**
+ * @primitive b.pqcAgent.reload
+ * @signature b.pqcAgent.reload()
+ * @since     0.9.14
+ * @status    stable
+ * @related   b.pqcAgent.create
+ *
+ * Tear down the lazily-built default agent and reset to null so the
+ * next `b.pqcAgent.agent` access rebuilds against current TLS posture
+ * + network-tls applyToContext output.
+ *
+ * Long-running daemons that rotate the framework's TLS posture (via
+ * `b.network.tls` config refresh, certificate-pinset reload, or a
+ * `C.TLS_GROUP_PREFERENCE` update behind a feature flag) need a way
+ * to re-source the outbound https.Agent without forking a new
+ * process. `reload()` calls `.destroy()` on the existing default
+ * agent — Node closes idle keep-alive sockets and lets in-flight
+ * sockets complete naturally — then nulls the cache so the next
+ * `agent` access builds fresh. Agents handed out via explicit
+ * `b.pqcAgent.create()` are unaffected; only the framework's lazy
+ * default is recycled.
+ *
+ * Returns `{ destroyed: boolean }` — `destroyed: true` when an agent
+ * was actually torn down, `false` when no default had been built
+ * (no callers yet asked for it).
+ *
+ * @example
+ *   // operator's daemon picked up a refreshed TLS-pinset config:
+ *   b.network.tls.reload();
+ *   var res = b.pqcAgent.reload();
+ *   logger.info("pqc-agent reloaded", res);
+ */
+function reload() {
+  var hadAgent = _defaultAgent !== null;
+  if (hadAgent) {
+    try { _defaultAgent.destroy(); }
+    catch (_e) { /* destroy is best-effort */ }
+    _defaultAgent = null;
+  }
+  return { destroyed: hadAgent };
+}
+
 module.exports = {
   // Read property — getter so the agent is built on first access.
   get agent()  { return _getDefaultAgent(); },
   create:      create,
   createHttp:  createHttp,
+  reload:      reload,
   DEFAULT_OPTS: DEFAULT_OPTS,
   KNOWN_TLS_GROUPS: KNOWN_TLS_GROUPS,
   enforced:    true,

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,