@blamejs/core 0.16.7 → 0.16.9

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.16.x
 
+- v0.16.9 (2026-07-10) — **`b.safeBuffer.quoteString` — one RFC quoted-string serializer behind eight header and protocol emitters — plus a consolidated per-primitive test suite and a static gate that refuses a documented primitive no test references.** Eight places in the framework serialized an RFC quoted-string by hand — escape backslash and DQUOTE, wrap in DQUOTEs — for Cache-Status and Signature-Input sf-strings, Link header parameters, Authentication-Results reason, IMAP quoted strings and METADATA values, ManageSieve responses, and Server-Timing descriptions. Those copies are consolidated into one primitive, b.safeBuffer.quoteString, so an unescaped quote can never terminate a string early and smuggle extra parameters into a protocol line, and the escaping cannot drift between emitters. Output is byte-identical to before. The test suite is reorganized so every primitive's tests live in a canonical per-primitive file (thirty-eight auxiliary files folded or renamed; every assertion preserved — the full suite passes with the exact same check count). On top of that reorganization, the comment-block validator gains a primitive-without-test check: a documented @primitive that no test references — neither the full dotted form nor its namespace plus a method invocation — now fails the static gate. One hundred six existing primitives currently lack any test reference; they are recorded in an explicit shrink-only register in the validator, each entry an open test-backfill item, and the gate refuses any new primitive shipping untested. **Added:** *b.safeBuffer.quoteString — RFC quoted-string serialization* — Coerces to string, escapes every backslash and DQUOTE with a leading backslash, and wraps the result in DQUOTEs — the quoted-string grammar shared by RFC 8941 §3.3.3 Structured Fields sf-string, RFC 8288 Link header parameters, RFC 8601 §2.2 Authentication-Results reason, RFC 3501 §4.3 IMAP quoted strings, and RFC 5804 §1.2 ManageSieve strings. Escaping only: a grammar with a restricted character range (sf-string is printable-ASCII; IMAP quoted strings cannot carry CR/LF) enforces its range check before calling it. · *Static gate: a documented primitive must be referenced by a test* — The comment-block validator now scans the test corpus for every @primitive: the full dotted form (b.namespace.method) anywhere under test/, or the namespace / owning module referenced together with the method invoked in the same test file — the same-file rule stops a ubiquitous method name like .create( in an unrelated test from counting as coverage. A primitive with no reference fails the pre-push static gate. One hundred six existing primitives currently have no reference; they are listed in a shrink-only register inside the validator — each entry an open test-backfill item that is deleted when its test lands — and a new primitive cannot ship untested. **Changed:** *Eight quoted-string emitters route through the one serializer* — Cache-Status key/detail, Signature-Input sf-strings, Link header parameter values, Authentication-Results reason, IMAP METADATA values and quoted strings, ManageSieve OK/NO/BYE/LISTSCRIPTS responses, and Server-Timing desc now compose b.safeBuffer.quoteString instead of hand-rolling the escape. Emitted bytes are unchanged. · *Per-primitive canonical test files* — Thirty-eight auxiliary test files are folded into (or renamed to) their primitive's canonical test file — one file per primitive domain, concern-named splits kept (e.g. http-client-cache / -stream / -throttle). No assertion was changed, added, or removed by the reorganization; the full suite passes with the exact same check count before and after. The b.*-surface reference gate that previously ran inside the smoke suite is superseded by the stronger validator check above. **Detectors:** *rfc-quoted-string-escape-owned-by-safeBuffer* — Flags an inline backslash-then-DQUOTE escape chain in lib/ outside the primitive's home — the quoted-string serializer re-implemented, whose escaping can drift from the canonical one. While being proven against the pre-consolidation tree it caught an eighth emitter the manual sweep had missed (an IMAP response-literal helper), which is consolidated in this release too.
+
+- v0.16.8 (2026-07-10) — **`b.metrics.snapshot.render` now emits the labeled registry — counters, gauges and histogram buckets with their label sets — matching the live exposition endpoint byte-for-byte, plus a Public Suffix List refresh and supply-chain pin maintenance.** A snapshot written with b.metrics.snapshot.startWriter's registry option always carried the full labeled registry in its metrics field, but b.metrics.snapshot.render ignored that field: the prometheus format emitted only the flat numeric fields, so a sidecar wanting a complete /metrics exposition of labeled series had to re-implement label-value escaping and bucketed line formatting itself. Both render formats now emit the labeled series. The prometheus output is produced by the same family encoder the live exposition() endpoint uses — one encoder now backs the live exposition, the shadow registry and snapshot rendering — so series names and escaping are identical whichever source a scraper reads. Snapshot files are parsed defensively: a malformed family, a non-Prometheus metric or label name, or a non-numeric sample in a hand-edited snapshot file is dropped rather than rendered, so a tampered file cannot forge exposition lines. Separately, twelve documentation examples opened with require("blamejs").create(), a factory the export does not have; the examples are corrected and the @example-execution test no longer supplies a substitute create(), so any future example calling a method the shipped export lacks fails the suite. The vendored Public Suffix List is refreshed to the 2026-07-09 upstream revision, and the CI toolchain pins (github/codeql-action, the ClusterFuzzLite base-builder digest) are brought current. **Changed:** *One shared Prometheus family encoder behind every exposition surface* — The live registry exposition(), the shadow registry's prometheus render and the new snapshot rendering now share a single labeled-sample encoder (label ordering, value escaping, histogram bucket lines). Output of the existing surfaces is unchanged, including the guarantee that a label literally named constructor / prototype / __proto__ survives rendering. · *Public Suffix List refreshed to the 2026-07-09 upstream revision* — The vendored, signature-verified Public Suffix List bundle is rebuilt from the current upstream publication (previously 2026-07-02). This keeps DMARC / BIMI organizational-domain alignment and cookie-scope decisions current with registry changes. · *CI toolchain pins brought current* — github/codeql-action is pinned to v4.37.0 across the CodeQL and Scorecard workflows in one change (its init / analyze / upload-sarif sub-actions must move together — mixed versions break the CodeQL analysis run), and Dependabot now groups codeql-action updates into a single pull request. The ClusterFuzzLite base-builder image digest is bumped to the current upstream publication, with the oss-fuzz submission mirror kept in sync. **Fixed:** *b.metrics.snapshot.render emits the labeled registry from snap.metrics (#430)* — Snapshots written with startWriter's registry option carry every registered counter / gauge / histogram — label sets and bucket counts — in a structured metrics field, but render() only emitted the flat numeric fields. The prometheus format now renders those families with the same labeled / bucketed sample lines (name{label="value"} n, name_bucket{le=…}, name_sum, name_count) the live exposition() endpoint serves, family names verbatim rather than prefix-qualified, so dashboards see one series name regardless of scrape source; the text format lists each labeled sample as a name{label="value"} row. Malformed families, non-Prometheus metric / label names, and non-numeric samples in a snapshot file are dropped rather than rendered, so a hand-edited file cannot forge exposition lines. · *Twelve documentation examples no longer call a nonexistent create() factory* — @example blocks in b.a2a, b.cloudEvents, b.pqcSoftware and b.tlsExporter opened with var b = require("blamejs").create(), but the top-level export has no create() — copying those examples threw a TypeError on the first line. The examples now open with var b = require("blamejs"). The @example-execution test previously supplied a substitute create() to the examples' require, which masked exactly this drift; the substitute is removed, so an example calling any method the shipped export lacks now fails the suite. **Detectors:** *prometheus-exposition-escape-owned-by-metrics* — Flags a hand-rolled Prometheus escape chain (backslash-doubling plus newline escaping) outside lib/metrics.js — the signature of a second exposition encoder growing whose escaping can drift from the canonical one. The two-step backslash+quote escapes used by RFC quoted-string wire formats (sf-string, IMAP, Sieve, Link header) are out of scope.
+
 - v0.16.7 (2026-07-06) — **Restore two APIs that silently didn't work — the Clear-Site-Data header helper and data-subject export — and correct five documentation examples, all surfaced by a new test that executes every JSDoc @example end-to-end.** The comment-block validator only ever PARSE-checked each documentation @example, so an example could compile and still be dead — calling a method that no longer exists, passing an option the API rejects, or misreading a return shape. A new test now EXECUTES every self-contained @example against the real framework, and on its first run it caught two genuine framework defects plus five stale examples. b.middleware.clearSiteData.headerValue (documented @status stable since 0.15.9) was unreachable: the middleware export was a bare factory that never carried the headerValue helper (nor KNOWN_TYPES / DEFAULT_TYPES), so calling it threw — it is now attached to the export, mirroring b.middleware.idempotencyKey. b.subject.export / b.subject.exportData returned undefined instead of the documented empty object when no data-subject tables are declared, so an operator running an export before tagging any subjectField column got undefined and crashed on the first property access — it now returns {}. Five @example blocks are corrected to runnable code (b.guardRegex.gate's return usage; the invalid title option on b.openapi.create / b.asyncapi.create, which belongs under info; b.retention.complianceFloor; b.safeSchema.object). No security surface changes. **Added:** *JSDoc @example execution validation* — A new test executes every self-contained JSDoc @example against the real framework — not just parse-checks it — so an example that references a renamed or removed method, passes an option the API rejects, or misreads a return shape now fails the suite instead of shipping as dead documentation. Examples with side effects (network, database, filesystem, long-lived work) or that abstract external setup are skipped; the executed set runs in a sandbox with a wall-clock ceiling. **Fixed:** *b.middleware.clearSiteData.headerValue is reachable again* — b.middleware.clearSiteData was exported as a bare factory function, so the advertised b.middleware.clearSiteData.headerValue(types, label?) — plus KNOWN_TYPES and DEFAULT_TYPES — were undefined off the export and threw a TypeError, even though the helper (documented stable since 0.15.9) existed on the module. Those members are now attached to the middleware export, so the documented call works. · *b.subject.export / exportData returns {} when no data-subject tables are declared* — On the no-subject-tables path, export returned the value of its internal audit-write helper — which has no return statement, i.e. undefined — instead of the documented empty dump. An operator running a data-subject export before tagging any subjectField column therefore received undefined and crashed on Object.keys(dump) / dump.<table>. It now returns {} as documented (export and exportData are the same function). · *Five documentation examples corrected to runnable code* — b.guardRegex.gate's example now uses the gate return value correctly; b.openapi.create and b.asyncapi.create examples move title/version under info (title is not a top-level option); and the b.retention.complianceFloor and b.safeSchema.object examples are made self-contained. These are documentation-only corrections.
 
 - v0.16.6 (2026-07-05) — **Repair the ClusterFuzzLite / OSS-Fuzz build script so its fuzz targets actually install the jazzer.js runtime and pair with their seed corpora.** This patch fixes the OSS-Fuzz / ClusterFuzzLite build script (.clusterfuzzlite/build.sh), which was latently broken: it compiled every fuzz/<name>.fuzz.js harness without first installing @jazzer.js/core, so the generated targets referenced a runtime that was never present and could not start, and it named each seed-corpus archive after the .fuzz.js-stripped base (guard-csv_seed_corpus.zip) rather than the compiled target (guard-csv.fuzz), so the fuzzing engine never associated a corpus with its target and bootstrapped from nothing. Both failures were silent because the compile step still exits 0 and the in-repo CI fuzz workflows invoke jazzer.js directly rather than through this script — the script is the OSS-Fuzz-upstream integration spec. The build script now installs the jazzer.js runtime into the project-root node_modules before compiling and names each corpus after its target, and a codebase-patterns check locks both invariants in. The build image's inline documentation is corrected (jazzer.js is not present in the base image; the CI workflows do not consume this image) and now records why the upstream path is still latent (the base image ships Node 20 / GLIBC 2.31, below the framework's Node 22+ and jazzer.js's GLIBC 2.38 needs). No shipped framework code changes; fuzz and build-image assets are dev-only and are not part of the published package. **Fixed:** *OSS-Fuzz / ClusterFuzzLite build script installs the jazzer.js runtime before compiling* — compile_javascript_fuzzer emits a runnable that executes <project>/node_modules/@jazzer.js/core at fuzz time from a wholesale copy of the source tree, so the runtime must exist in the project-root node_modules at compile time. The build script never ran an install, so @jazzer.js/core (declared in fuzz/package.json) was absent and every compiled target referenced a runtime that wasn't there. The script now installs it before the compile loop. · *Fuzz seed corpora are paired with their compiled target* — compile_javascript_fuzzer names each target after basename -s .js (keeping the .fuzz stem, e.g. guard-csv.fuzz), but the script zipped each seed corpus under the .fuzz.js-stripped base (guard-csv_seed_corpus.zip). The fuzzing engine pairs <target>_seed_corpus.zip, so no corpus was ever associated and targets started from an empty corpus. Each corpus is now named after its target. · *Build-image documentation corrected* — The build image's comments claimed jazzer.js was pre-installed in the base image and that the CI fuzz workflows consume this image; neither is true. The comments now state that build.sh installs jazzer.js and that the CI workflows invoke jazzer.js directly, and record that the OSS-Fuzz-upstream path remains latent until the base image advances to Node 24 / a newer GLIBC. **Detectors:** *Fuzz-build invariants checked in codebase-patterns* — A cross-artifact check asserts that .clusterfuzzlite/build.sh installs a jazzer.js runtime before compile_javascript_fuzzer and names each seed-corpus archive after the compiled target, so neither gap can silently reappear.

package/lib/a2a.js

@@ -117,7 +117,7 @@ function _validateCardShape(card, errorClass) {
  * `verifyCard` use the same canonicalizer internally.
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var bytes = b.a2a.canonicalize({
  *     issuer:       "agent.example.com",
  *     agentId:      "ops-bot-1",
@@ -159,7 +159,7 @@ function canonicalize(card) {
  *   }
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var card = b.a2a.createCard({
  *     issuer:       "agent.example.com",
  *     agentId:      "ops-bot-1",
@@ -209,7 +209,7 @@ function createCard(opts) {
  *   }
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var card = b.a2a.createCard({
  *     issuer:       "agent.example.com",
  *     agentId:      "ops-bot-1",
@@ -292,7 +292,7 @@ function signCard(card, privateKeyPem, opts) {
  *   }
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var result = b.a2a.verifyCard(envelope, peerPublicKeyPem, {
  *     expectedIssuer: "agent.example.com"
  *   });

package/lib/cache-status.js

@@ -34,6 +34,7 @@
  *   RFC 9211 Cache-Status header — documents which intermediate caches handled a request with structured `hit` / `fwd` / `ttl` parameters so operators diagnose cache-decision chains.
  */
 
+var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
 
@@ -58,11 +59,6 @@ var BOOLEAN_PARAMS = Object.freeze(["hit", "stored", "collapsed"]);
 // passing other keys get passed-through verbatim as token=value.
 var KNOWN_PARAMS = Object.freeze(["hit", "fwd", "fwd-status", "ttl", "stored", "collapsed", "key", "detail"]);
 
-function _sfStringQuote(s) {
-  // RFC 8941 sf-string — quoted-string with escaping for " and \.
-  // Operator-supplied detail/key strings get the full quote-escape.
-  return "\"" + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
-}
 
 /**
  * @primitive b.cacheStatus.append
@@ -178,14 +174,14 @@ function entryString(entry) {
       throw new CacheStatusError("cache-status/bad-key",
         "entry.key must be a string when provided");
     }
-    parts.push("key=" + _sfStringQuote(entry.key));
+    parts.push("key=" + safeBuffer.quoteString(entry.key));
   }
   if (entry.detail !== undefined && entry.detail !== null) {
     if (typeof entry.detail !== "string") {
       throw new CacheStatusError("cache-status/bad-detail",
         "entry.detail must be a string when provided");
     }
-    parts.push("detail=" + _sfStringQuote(entry.detail));
+    parts.push("detail=" + safeBuffer.quoteString(entry.detail));
   }
   return parts.join("; ");
 }

package/lib/cloud-events.js

@@ -110,7 +110,7 @@ function _genId() {
  *   }
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var ce = b.cloudEvents.wrap({
  *     source:  "/services/orders",
  *     type:    "com.example.order.created",
@@ -214,7 +214,7 @@ function wrap(opts) {
  * envelope.
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var record = b.cloudEvents.parse({
  *     specversion: "1.0",
  *     id:          "evt-1",

package/lib/http-message-signature.js

@@ -104,7 +104,7 @@ function _sfQuotedString(s) {
         "httpSig: parameter string contains non-printable byte at offset " + i);
     }
   }
-  return "\"" + s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
+  return safeBuffer.quoteString(s);
 }
 
 // _serializeCovered — RFC 9421 §2.5 covered-components list.

package/lib/link-header.js

@@ -29,6 +29,7 @@
  *   parameter never splits the list.
  */
 
+var safeBuffer = require("./safe-buffer");
 var structuredFields = require("./structured-fields");
 var { defineClass } = require("./framework-error");
 
@@ -114,7 +115,7 @@ function parse(headerValue) {
 // common convention (RFC 8288 examples, REST pagination) quotes too.
 function _serParam(name, value) {
   if (value === "" || value === true) return name;            // valueless parameter
-  return name + "=\"" + String(value).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + "\"";
+  return name + "=" + safeBuffer.quoteString(value);
 }
 
 /**

package/lib/mail-auth.js

@@ -2158,7 +2158,7 @@ function authResultsEmit(opts) {
       // (`\"`). Pre-v0.8.32 the framework collapsed `"` to `'` which
       // is lossy. Use the spec-correct escape so the receiver can
       // round-trip the original reason.
-      clause += ' reason="' + r.reason.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+      clause += " reason=" + safeBuffer.quoteString(r.reason);
     }
     // Method-specific properties (ptype.property=value triples per
     // RFC 8601 §2.3). Operators pass them as flat object keys.

package/lib/mail-server-imap.js

@@ -789,7 +789,7 @@ function create(opts) {
       .then(function (rows) {
         if (Array.isArray(rows) && rows.length > 0) {
           var pairs = rows.map(function (r) {
-            var v = r.value === null || r.value === undefined ? "NIL" : '"' + String(r.value).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + '"';
+            var v = r.value === null || r.value === undefined ? "NIL" : safeBuffer.quoteString(r.value);
             return r.entry + " " + v;
           }).join(" ");
           _writeUntagged(socket, "METADATA " + (mailbox === "" ? '""' : mailbox) + " (" + pairs + ")");
@@ -1247,7 +1247,7 @@ function create(opts) {
         for (var i = 0; i < folders.length; i += 1) {
           var f = folders[i];
           var attrs = (f.attributes || []).map(function (a) { return "\\" + a; }).join(" ");
-          _writeUntagged(socket, "LIST (" + attrs + ") \"/\" " + _quote(f.name));
+          _writeUntagged(socket, "LIST (" + attrs + ") \"/\" " + safeBuffer.quoteString(f.name));
         }
         _writeTagged(socket, tag, "OK LIST completed");
       })
@@ -1282,7 +1282,7 @@ function create(opts) {
           var key = items[k].toUpperCase();
           if (info[key] !== undefined) parts.push(key + " " + info[key]);
         }
-        _writeUntagged(socket, "STATUS " + _quote(name) + " (" + parts.join(" ") + ")");
+        _writeUntagged(socket, "STATUS " + safeBuffer.quoteString(name) + " (" + parts.join(" ") + ")");
         _writeTagged(socket, tag, "OK STATUS completed");
       })
       .catch(function (err) {
@@ -1780,7 +1780,6 @@ function create(opts) {
     try { socket.destroy(); } catch (_e2) { /* idempotent */ }
     connections.delete(socket);
   }
-  function _quote(s) { return '"' + String(s).replace(/\\/g, "\\\\").replace(/"/g, "\\\"") + '"'; }
   function _unquote(s) {
     if (typeof s !== "string") return "";
     if (s[0] === "\"" && s[s.length - 1] === "\"") return s.slice(1, -1);

package/lib/mail-server-managesieve.js

@@ -730,7 +730,7 @@ function create(opts) {
           var s = list[i];
           var nm = String(s.name || "");
           var active = s.active === true ? " ACTIVE" : "";
-          socket.write('"' + _quoteEscape(nm) + '"' + active + "\r\n");
+          socket.write(safeBuffer.quoteString(nm) + active + "\r\n");
         }
         _emit("mail.server.managesieve.listscripts",
           { connectionId: state.id, count: list.length });
@@ -813,24 +813,20 @@ function create(opts) {
       });
   }
 
-  // RFC 5804 §1.2 quoted-string escaping: backslash + DQUOTE inside
-  // the value get escaped with a leading backslash.
-  function _quoteEscape(s) {
-    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');                                               // allow:regex-no-length-cap — backslash + DQUOTE escape on bounded-input
-  }
-
+  // RFC 5804 §1.2 quoted strings — serialization routes through
+  // safeBuffer.quoteString (one quoted-string escaper framework-wide).
   function _writeOk(socket, msg) {
-    try { socket.write('OK "' + _quoteEscape(msg) + '"\r\n'); } catch (_e) { /* socket down */ }
+    try { socket.write("OK " + safeBuffer.quoteString(msg) + "\r\n"); } catch (_e) { /* socket down */ }
   }
   function _writeOkWithTag(socket, tag, msg) {
-    try { socket.write('OK (TAG "' + _quoteEscape(tag) + '") "' + _quoteEscape(msg) + '"\r\n'); }
+    try { socket.write("OK (TAG " + safeBuffer.quoteString(tag) + ") " + safeBuffer.quoteString(msg) + "\r\n"); }
     catch (_e) { /* socket down */ }
   }
   function _writeNo(socket, msg) {
-    try { socket.write('NO "' + _quoteEscape(msg) + '"\r\n'); } catch (_e) { /* socket down */ }
+    try { socket.write("NO " + safeBuffer.quoteString(msg) + "\r\n"); } catch (_e) { /* socket down */ }
   }
   function _writeBye(socket, msg) {
-    try { socket.write('BYE "' + _quoteEscape(msg) + '"\r\n'); } catch (_e) { /* socket down */ }
+    try { socket.write("BYE " + safeBuffer.quoteString(msg) + "\r\n"); } catch (_e) { /* socket down */ }
   }
   function _close(socket) {
     try { socket.end(); } catch (_e) { /* idempotent */ }

package/lib/metrics.js

@@ -256,6 +256,84 @@ function _sortedLabelKeys(labelObj) {
   return keys;
 }
 
+// Shared metric-family encoder for the Prometheus / OpenMetrics text
+// formats. The live registry's exposition(), the shadow registry's
+// prometheus render, and snapshot.render's labeled-registry path all
+// route through here, so there is exactly one encoder for labeled /
+// bucketed sample lines.
+//
+//   family: { name, type, help, unit, buckets, entries }
+//     counter / gauge entries: [{ labels, value }]
+//     histogram entries:       [{ labels, counts, sum, count, exemplars }]
+function _renderFamilyLines(family, openMetrics, lines) {
+  // OpenMetrics §5.1.2 — counter sample lines MUST suffix with
+  // `_total`. The metadata `# HELP / # TYPE / # UNIT` lines MUST
+  // name the SAME family identifier the samples use, otherwise
+  // strict OpenMetrics parsers reject the family. Derive the
+  // exposition name once so metadata and sample lines agree.
+  var exposedName = family.name;
+  if (openMetrics && family.type === "counter" && !/_total$/.test(family.name)) {                    // allow:regex-no-length-cap — name-suffix check
+    exposedName = family.name + "_total";
+  }
+  if (family.help) lines.push("# HELP " + exposedName + " " + family.help);
+  lines.push("# TYPE " + exposedName + " " + family.type);
+  if (openMetrics && family.unit) lines.push("# UNIT " + exposedName + " " + family.unit);
+  var entries = family.entries;
+  if (family.type === "histogram") {
+    for (var k = 0; k < entries.length; k++) {
+      var entry = entries[k];
+      for (var bi = 0; bi < family.buckets.length; bi++) {
+        var bLabels = Object.assign(Object.create(null), entry.labels, { le: String(family.buckets[bi]) });
+        var bucketLine = family.name + "_bucket" + _renderLabels(bLabels) + " " + entry.counts[bi];
+        // OpenMetrics 1.0 §6.2 — exemplar trace + span IDs appended
+        // as `# {trace_id="...",span_id="..."} <value> <timestamp>`.
+        if (openMetrics && entry.exemplars && entry.exemplars[bi]) {
+          var ex = entry.exemplars[bi];
+          bucketLine += " # " + _renderLabels(ex.labels || {}) + " " + ex.value;
+          if (ex.timestamp) bucketLine += " " + ex.timestamp;
+        }
+        lines.push(bucketLine);
+      }
+      var infLabels = Object.assign(Object.create(null), entry.labels, { le: "+Inf" });
+      lines.push(family.name + "_bucket" + _renderLabels(infLabels) + " " + entry.counts[family.buckets.length]);
+      lines.push(family.name + "_sum"   + _renderLabels(entry.labels) + " " + entry.sum);
+      lines.push(family.name + "_count" + _renderLabels(entry.labels) + " " + entry.count);
+    }
+  } else {
+    // exposedName only diverges from family.name for OpenMetrics
+    // counters (the `_total` suffix rule above), so using it
+    // unconditionally keeps Prometheus output byte-identical.
+    for (var v = 0; v < entries.length; v++) {
+      lines.push(exposedName + _renderLabels(entries[v].labels) + " " + entries[v].value);
+    }
+  }
+}
+
+// Flatten one family into `{ key → value }` sample pairs (key = sample
+// name + rendered labels). The text-format snapshot renderer consumes
+// these as synthetic field rows; _renderFamilyLines renders the same
+// samples as wire-format lines (plus metadata + exemplars, which have
+// no key/value representation).
+function _familySamples(family) {
+  var out = Object.create(null);
+  for (var i = 0; i < family.entries.length; i++) {
+    var entry = family.entries[i];
+    if (family.type === "histogram") {
+      for (var bi = 0; bi < family.buckets.length; bi++) {
+        var bLabels = Object.assign(Object.create(null), entry.labels, { le: String(family.buckets[bi]) });
+        out[family.name + "_bucket" + _renderLabels(bLabels)] = entry.counts[bi];
+      }
+      var infLabels = Object.assign(Object.create(null), entry.labels, { le: "+Inf" });
+      out[family.name + "_bucket" + _renderLabels(infLabels)] = entry.counts[family.buckets.length];
+      out[family.name + "_sum" + _renderLabels(entry.labels)] = entry.sum;
+      out[family.name + "_count" + _renderLabels(entry.labels)] = entry.count;
+    } else {
+      out[family.name + _renderLabels(entry.labels)] = entry.value;
+    }
+  }
+  return out;
+}
+
 // Combine default + per-call labels, validating against the metric's
 // declared labelNames. Throws if a label name isn't declared.
 function _resolveLabels(defaultLabels, declaredNames, callLabels) {
@@ -596,53 +674,17 @@ function create(opts) {
     var sortedNames = Array.from(metrics.keys()).sort();
     for (var i = 0; i < sortedNames.length; i++) {
       var m = metrics.get(sortedNames[i]);
-      // OpenMetrics §5.1.2 — counter sample lines MUST suffix with
-      // `_total`. The metadata `# HELP / # TYPE / # UNIT` lines MUST
-      // name the SAME family identifier the samples use, otherwise
-      // strict OpenMetrics parsers reject the family. Derive the
-      // exposition name once at the top of the loop so both the
-      // metadata lines and the sample lines agree.
-      var exposedName = m.name;
-      if (openMetrics && m.type === "counter" && !/_total$/.test(m.name)) {
-        exposedName = m.name + "_total";
-      }
-      if (m.help) lines.push("# HELP " + exposedName + " " + m.help);
-      lines.push("# TYPE " + exposedName + " " + m.type);
-      if (openMetrics && m.unit) lines.push("# UNIT " + exposedName + " " + m.unit);
       var keys = Array.from(m.values.keys()).sort();
-      if (m.type === "histogram") {
-        for (var k = 0; k < keys.length; k++) {
-          var entry = m.values.get(keys[k]);
-          for (var bi = 0; bi < m.buckets.length; bi++) {
-            var bLabels = Object.assign({}, entry.labels, { le: String(m.buckets[bi]) });
-            var bucketLine = m.name + "_bucket" + _renderLabels(bLabels) + " " + entry.counts[bi];
-            // OpenMetrics 1.0 §6.2 — exemplar trace + span IDs appended
-            // as `# {trace_id="...",span_id="..."} <value> <timestamp>`.
-            if (openMetrics && entry.exemplars && entry.exemplars[bi]) {
-              var ex = entry.exemplars[bi];
-              bucketLine += " # " + _renderLabels(ex.labels || {}) + " " + ex.value;
-              if (ex.timestamp) bucketLine += " " + ex.timestamp;
-            }
-            lines.push(bucketLine);
-          }
-          var infLabels = Object.assign({}, entry.labels, { le: "+Inf" });
-          lines.push(m.name + "_bucket" + _renderLabels(infLabels) + " " + entry.counts[m.buckets.length]);
-          lines.push(m.name + "_sum"   + _renderLabels(entry.labels) + " " + entry.sum);
-          lines.push(m.name + "_count" + _renderLabels(entry.labels) + " " + entry.count);
-        }
-      } else if (m.type === "counter" && openMetrics) {
-        // exposedName already carries the `_total` suffix when needed
-        // (derived at the top of the loop so metadata + samples agree).
-        for (var v = 0; v < keys.length; v++) {
-          var ent = m.values.get(keys[v]);
-          lines.push(exposedName + _renderLabels(ent.labels) + " " + ent.value);
-        }
-      } else {
-        for (var v2 = 0; v2 < keys.length; v2++) {
-          var ent2 = m.values.get(keys[v2]);
-          lines.push(m.name + _renderLabels(ent2.labels) + " " + ent2.value);
-        }
-      }
+      var entries = [];
+      for (var k = 0; k < keys.length; k++) entries.push(m.values.get(keys[k]));
+      _renderFamilyLines({
+        name:    m.name,
+        type:    m.type,
+        help:    m.help,
+        unit:    m.unit,
+        buckets: m.buckets,
+        entries: entries,
+      }, openMetrics, lines);
       lines.push("");
     }
     if (openMetrics) lines.push("# EOF");
@@ -1157,6 +1199,19 @@ function snapshotRead(p) {
  * queries start returning the right answer once the new types reach
  * the scrape target.
  *
+ * ## Labeled registry series
+ *
+ * A snapshot written with `startWriter`'s `registry` option carries the
+ * registry's counters / gauges / histograms — label sets and histogram
+ * bucket counts — in a structured `metrics` field. Both formats render
+ * them: `prometheus` emits the same labeled / bucketed sample lines the
+ * live `exposition()` endpoint serves, family names verbatim (NOT
+ * `prefix`-qualified) so dashboards see one series name regardless of
+ * scrape source; `text` lists each labeled sample as a
+ * `name{label="value"}` row. A malformed family, metric / label name,
+ * or non-numeric sample in a hand-edited snapshot file is dropped,
+ * never rendered.
+ *
  * @opts
  *   format:      "text" | "prometheus",   // default: "text"
  *   prefix:      string,                   // prometheus-only; default: "blamejs"
@@ -1233,6 +1288,84 @@ function _renderText(fields, snap, opts) {
   return lines.join("\n") + "\n";
 }
 
+// Validate + normalize one serialized registry family from a snapshot's
+// `metrics` field (written by startWriter's `registry` option) into the
+// _renderFamilyLines shape. Snapshot files are read back from disk, so
+// this is a defensive reader: a malformed family, a non-Prometheus
+// metric / label name, or a non-numeric sample is dropped rather than
+// rendered — a hand-edited snapshot file must not be able to forge
+// exposition lines. Returns null when the whole family is unusable.
+function _normalizeSnapshotFamily(name, fam) {
+  if (!fam || typeof fam !== "object" || Array.isArray(fam)) return null;
+  // Same name contracts as the live registry (METRIC_NAME_RE allows the
+  // colon forms _validateMetricName accepts, LABEL_NAME_RE does not) —
+  // a family the live exposition emits must never be dropped here. The
+  // length cap bounds the anchored test on untrusted snapshot-file bytes.
+  if (name.length > 1024 || !METRIC_NAME_RE.test(name)) return null;
+  var type = fam.type;
+  if (type !== "counter" && type !== "gauge" && type !== "histogram") return null;
+  var buckets = null;
+  if (type === "histogram") {
+    if (!Array.isArray(fam.buckets)) return null;
+    buckets = [];
+    for (var bi = 0; bi < fam.buckets.length; bi += 1) {
+      if (typeof fam.buckets[bi] !== "number" || !isFinite(fam.buckets[bi])) return null;
+      buckets.push(fam.buckets[bi]);
+    }
+  }
+  var observations = Array.isArray(fam.observations) ? fam.observations : [];
+  var entries = [];
+  for (var i = 0; i < observations.length; i += 1) {
+    var obs = observations[i];
+    if (!obs || typeof obs !== "object") continue;
+    // null-proto so a label literally named `__proto__` / `constructor`
+    // lands as an own property instead of being swallowed by the
+    // plain-object prototype setter.
+    var labels = Object.create(null);
+    var rawLabels = obs.labels && typeof obs.labels === "object" ? obs.labels : {};
+    var lnames = Object.keys(rawLabels);
+    for (var li = 0; li < lnames.length; li += 1) {
+      if (lnames[li].length > 1024 || !LABEL_NAME_RE.test(lnames[li])) continue;   // drop forged / oversized label names
+      labels[lnames[li]] = String(rawLabels[lnames[li]]);
+    }
+    if (type === "histogram") {
+      if (!Array.isArray(obs.counts) || obs.counts.length !== buckets.length + 1) continue;
+      var countsOk = true;
+      for (var ci = 0; ci < obs.counts.length; ci += 1) {
+        if (typeof obs.counts[ci] !== "number" || !isFinite(obs.counts[ci])) { countsOk = false; break; }
+      }
+      if (!countsOk) continue;
+      if (typeof obs.sum !== "number" || !isFinite(obs.sum)) continue;
+      if (typeof obs.count !== "number" || !isFinite(obs.count)) continue;
+      entries.push({ labels: labels, counts: obs.counts, sum: obs.sum, count: obs.count });
+    } else {
+      if (typeof obs.value !== "number" || !isFinite(obs.value)) continue;   // numeric samples only
+      entries.push({ labels: labels, value: obs.value });
+    }
+  }
+  // Escape HELP text per the exposition format so a forged help string
+  // can't inject metric lines (live registries carry operator-authored
+  // help; snapshot files are untrusted bytes).
+  var help = typeof fam.help === "string"
+    ? fam.help.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, "")                       // allow:regex-no-length-cap — fixed-char-set escape // allow:duplicate-regex — Prometheus help-text escape shape
+    : "";
+  return { name: name, type: type, help: help, buckets: buckets, entries: entries };
+}
+
+// Walk a snapshot's serialized `metrics` object into validated families,
+// sorted by name for stable exposition output.
+function _normalizeSnapshotFamilies(metricsObj) {
+  if (!metricsObj || typeof metricsObj !== "object" || Array.isArray(metricsObj)) return [];
+  var families = [];
+  // allow:bare-canonicalize-walk — stable exposition output ordering
+  var names = Object.keys(metricsObj).sort();
+  for (var i = 0; i < names.length; i += 1) {
+    var family = _normalizeSnapshotFamily(names[i], metricsObj[names[i]]);
+    if (family) families.push(family);
+  }
+  return families;
+}
+
 function snapshotRender(snap, opts) {
   opts = opts || {};
   var format = opts.format || "text";
@@ -1241,8 +1374,25 @@ function snapshotRender(snap, opts) {
       "metrics.snapshot.render: snap must be a startWriter-produced object (got " + typeof snap + ")");
   }
   var fields = snap.fields;
+  // Labeled registry families (issue #430) — a snapshot written with
+  // startWriter's `registry` option carries every registered counter /
+  // gauge / histogram under `metrics`. Both formats render them so a
+  // sidecar consuming a snapshot written by another process gets the
+  // full labeled series, not just the flat numeric fields.
+  var families = _normalizeSnapshotFamilies(snap.metrics);
   if (format === "text") {
-    return _renderText(fields, snap, opts);
+    var textFields = fields;
+    if (families.length > 0) {
+      // Labeled series become synthetic `name{label="value"}` rows; an
+      // operator-supplied flat field wins on a (pathological) name
+      // collision.
+      var synth = Object.create(null);
+      for (var tf = 0; tf < families.length; tf += 1) {
+        Object.assign(synth, _familySamples(families[tf]));
+      }
+      textFields = Object.assign(synth, fields);
+    }
+    return _renderText(textFields, snap, opts);
   }
   if (format === "prometheus") {
     var prefix = opts.prefix || "blamejs";
@@ -1299,6 +1449,14 @@ function snapshotRender(snap, opts) {
       out.push("# TYPE " + emName + " gauge");
       out.push(emName + " " + ms);
     }
+    // Registry families render through the same encoder the live
+    // exposition() endpoint uses, names verbatim (NOT prefix-qualified),
+    // so a scraper switching between the live /metrics route and the
+    // snapshot sidecar sees identical series names.
+    for (var fj = 0; fj < families.length; fj += 1) {
+      if (out.length > 0) out.push("");   // blank-line family separator, mirrors exposition()
+      _renderFamilyLines(families[fj], false, out);
+    }
     return out.join("\n") + "\n";
   }
   throw new MetricsError("metrics-snapshot/bad-format",
@@ -1477,30 +1635,31 @@ function shadowRegistry(opts) {
       function _emitLabeled(name, labelMap, kind) {
         var metric = prefix + "_" + name;
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(metric)) return;                                        // allow:regex-no-length-cap — Prometheus name-shape; metric length bounded by namespace + name caps
-        out.push("# TYPE " + metric + " " + kind);
+        var entries = [];
         var lks = Object.keys(labelMap);
         for (var li = 0; li < lks.length; li += 1) {
           var lk = lks[li];
-          if (lk === "") { out.push(metric + " " + labelMap[lk]); continue; }
           // Read the structured label set kept alongside the canonical key (see
           // _coerceLabels) rather than re-parsing the key. No serialize-then-
           // split round-trip, so a `,` or `=` in a label value stays inside the
           // value and can never forge extra label pairs; and a label NAMED
           // `constructor` / `prototype` / `__proto__` survives instead of being
           // stripped by a prototype-pollution-hardened parse.
-          var labelObj = labelSets[lk];
-          if (!labelObj || typeof labelObj !== "object") { out.push(metric + " " + labelMap[lk]); continue; }
-          var lnames = Object.keys(labelObj).sort();                                                 // allow:bare-canonicalize-walk — deterministic label ordering in the exposition line
-          var formatted = [];
-          for (var pi = 0; pi < lnames.length; pi += 1) {
-            var lname = lnames[pi];
-            if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(lname)) continue;                                   // allow:regex-no-length-cap — Prometheus label-name shape
-            // Prometheus exposition: escape `\`, `"`, `\n` in label values.
-            var lvalue = String(labelObj[lname]).replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n"); // allow:regex-no-length-cap — fixed-char-set escape // allow:duplicate-regex — Prometheus value escape shape
-            formatted.push(lname + '="' + lvalue + '"');
+          var labelObj = lk === "" ? null : labelSets[lk];
+          // null-proto so a label literally named `__proto__` /
+          // `constructor` lands as an own property instead of being
+          // swallowed by the plain-object prototype setter.
+          var labels = Object.create(null);
+          if (labelObj && typeof labelObj === "object") {
+            var lnames = Object.keys(labelObj);
+            for (var pi = 0; pi < lnames.length; pi += 1) {
+              if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(lnames[pi])) continue;                            // allow:regex-no-length-cap — Prometheus label-name shape
+              labels[lnames[pi]] = labelObj[lnames[pi]];
+            }
           }
-          out.push(metric + "{" + formatted.join(",") + "} " + labelMap[lk]);
+          entries.push({ labels: labels, value: labelMap[lk] });
         }
+        _renderFamilyLines({ name: metric, type: kind, help: "", entries: entries }, false, out);
       }
       var cn2 = Object.keys(counters);
       for (var ci = 0; ci < cn2.length; ci += 1) {

package/lib/pqc-software.js

@@ -103,7 +103,7 @@ function _accessor(name) {
  * posture returns a stub whose primitive calls throw `PqcError`.
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   if (b.pqcSoftware.isAvailable()) {
  *     var ss = b.pqcSoftware.DEFAULT_KEM.keygen();
  *     ss.publicKey.length;
@@ -128,7 +128,7 @@ function isAvailable() {
  * bundle is unavailable.
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var names = b.pqcSoftware.listAlgorithms();
  *   names.indexOf("ml_kem_1024") >= 0;
  *   // → true (when the vendored bundle is present)
@@ -235,7 +235,7 @@ Object.defineProperty(pqc, "DEFAULT_HASH_SIG", {
  * shared secrets are byte-identical (32 bytes per FIPS 203 §1).
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var result = b.pqcSoftware.runKnownAnswerTest();
  *   result.ok;
  *   // → true (or { ok: false, reason: "<diagnostic>" } when broken)