@blamejs/core 0.16.6 → 0.16.8

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.16.x
 
+- 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.
 
 - v0.16.5 (2026-07-03) — **Correctness fixes across the ReDoS guard, Base32 codec, HTTP multipart builder, SAML encrypted-assertion decryption, and the OAuth device grant — several restore advertised functionality that was silently non-working, plus a multipart header-injection fix.** This patch fixes a batch of correctness and security defects, several of which restore advertised behaviour that never actually worked. The ReDoS guard (b.guardRegex) no longer false-rejects LINEAR patterns that use a quantified non-capturing group (`(?:…)?`, `(?:…)*`) or an optional quantified group (`(X+)?`, `(?:X+)?`) — those repeat the group at most once and are not catastrophic; the detector now correctly requires the OUTER quantifier to be unbounded, so operator regex screening and b.selfUpdate asset patterns that use an optional SemVer suffix work again while genuine `(a+)+` shapes are still refused. The Base32 decoder now rejects NON-CANONICAL input (a final symbol whose unused low bits are non-zero — previously two distinct strings decoded to the same bytes, a malleability problem for the TOTP secrets and identifiers Base32 backs) and impossible symbol counts (1/3/6 mod 8 that silently produced a truncated buffer). The HTTP multipart/form-data builder now refuses CR/LF/NUL in a field name, filename, or content-type, closing a part-header-injection / form-part-forgery path. Two SAML EncryptedAssertion decryption paths that were completely dead — ML-KEM-1024 key transport and XChaCha20-Poly1305 content — are fixed (they referenced crypto entry points that were never exported, so the framework's advertised PQC-first / AEAD SAML encryption always failed and misreported the cause as a wrong-key or tag-mismatch error). The OAuth device grant now works against spec-compliant identity providers (its poll aborted on the first `authorization_pending`, which RFC 8628 delivers as an HTTP 400 the client was rejecting before reading), and a static (non-discovery) OAuth client can now use introspection, dynamic registration, and device authorization by configuring those endpoints. Smaller fixes round it out: the HTTP client's default error carries statusCode/permanent; the CLI dev server's repeatable flags accumulate; DANE and MTA-STS failures are scoped correctly per RFC; and typed errors replace raw TypeErrors on a couple of malformed-input paths. **Fixed:** *HTTP client default error carries statusCode and permanent* — request() fell back to the base FrameworkError when no explicit opts.errorClass was passed, so error.statusCode and error.permanent were undefined on the default path despite the documented default of HttpClientError. The default is now HttpClientError, so those fields are populated for every consumer. · *Static OAuth clients can configure introspection / registration / device-authorization endpoints* — create() never read opts.introspectionEndpoint / registrationEndpoint / deviceAuthorizationEndpoint into its static-endpoint set, so introspectToken / registerClient / deviceAuthorization resolved those endpoints only via OIDC discovery — a static (non-discovery) client could not use them, even though introspectToken's own error told operators to set the endpoint on create(). Those three endpoints are now honored from static config. · *CLI dev server repeatable flags accumulate* — `blamejs dev --arg / --watch / --ignore` are documented repeatable, but the argument parser overwrote each on repeat, so only the last occurrence survived — only the last --watch directory was monitored, only the last --ignore applied, and the child received only the last --arg. Repeated occurrences of these flags now accumulate as documented. · *DANE per-recipient failure isolation and MTA-STS testing-mode handling* — A DANE-enforce TLSA-lookup failure threw out of the entire deliver() batch instead of failing just the one recipient; it now fails that recipient and lets the rest proceed. And an MTA-STS policy published in `testing` mode was hard-bounced under the default enforce posture, violating RFC 8461 §5.2 (testing mode is report-only); a testing-mode policy no longer blocks delivery. · *external-db validates defaultBackend and enforces the pool min floor* — init() did not validate that opts.defaultBackend named a registered backend, so a typo surfaced as an opaque TypeError at the first query instead of a typed config-time error; it is now validated at init. The pool `min` (documented as a floor on idle clients) was never enforced; the reaper now respects it. · *mail-bounce returns a typed error for a null SES SNS message* — An SES SNS notification whose Message field is JSON literal `null` dereferenced null and threw a raw TypeError (also risking an internal-message leak); it now throws the typed MailBounceError like the other malformed-input paths. **Security:** *b.guardRegex no longer false-rejects linear quantified-group patterns (#432, #429)* — The nested-quantifier ReDoS detector treated the `?` in a `(?:` group prefix as an inner quantifier and treated a bounded outer `?` / `{0,1}` as a dangerous outer quantifier, so it wrongly refused LINEAR patterns like `^(?:/page/\d+)?$`, `^foo(?:bar)*$`, `^(a+)?$`, and `(?:[-+][0-9A-Za-z.-]+)?`. The catastrophic class requires the OUTER quantifier to be unbounded (`*`/`+`/`{n,}`). The detector now relies solely on the paren-aware structural scanner, which requires an unbounded outer quantifier and does not miscount a group prefix — so genuine `(a+)+` / `((a)+)+` shapes stay refused while these linear ones are accepted. Consumers screening operator-supplied regexes (route rules, and b.selfUpdate asset patterns using an optional SemVer prerelease/build group) are no longer forced to rewrite valid input. · *Base32 decoder rejects non-canonical encodings and impossible lengths* — b.base32.decode discarded the final symbol's unused low bits without checking they were zero (RFC 4648 §3.5), so two distinct strings — e.g. `MY======` and `MZ======` — decoded to the same bytes (decoder malleability), and it silently accepted impossible symbol counts (1/3/6 mod 8) that can't represent whole bytes, returning a truncated buffer. Both are now refused (`base32/non-canonical`, `base32/bad-length`), giving a one-to-one mapping between a byte sequence and its Base32 string — important where the string is a key / secret / dedup handle (TOTP, identifiers). Valid input, including unpadded and loose-mode input, is unaffected. · *HTTP multipart/form-data builder refuses CR/LF/NUL in part-header values* — The multipart body builder interpolated the field name, file field, filename, and content-type onto `Content-Disposition:` / `Content-Type:` part-header lines without a control-character check, so an attacker controlling one of those values could smuggle a CRLF and inject additional part headers or forge form parts. CR, LF, and NUL in any of those values are now refused, matching the header-safety the mail-header sweep already applies to RFC 822 lines. · *SAML EncryptedAssertion ML-KEM-1024 and XChaCha20-Poly1305 decryption now work* — verifyResponse's post-quantum key-transport branch and its XChaCha20-Poly1305 content branch called crypto entry points that the crypto module never exported, so every ML-KEM-1024-wrapped or XChaCha20-Poly1305-encrypted SAML assertion failed with an internal TypeError that was re-reported as a key-unwrap or tag-mismatch error — the advertised PQC-first / AEAD SAML encryption was dead. Both paths now route through the exported envelope-open and packed-AEAD primitives, verified with a full encrypt→decrypt round trip. Fails closed (no auth bypass) either way. · *OAuth device grant polls correctly against spec-compliant providers* — pollDeviceCode issued its token request in the default buffering mode, so the HTTP client rejected the HTTP 400 that RFC 8628 §3.5 / RFC 6749 §5.2 use to carry `authorization_pending` / `slow_down` before the poll loop could read the OAuth error body — the grant aborted on the first poll (which is almost always `authorization_pending`, since the user hasn't approved yet). The request now resolves 4xx OAuth error responses so the pending / slow-down / terminal handling runs and the device grant completes.

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/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/guard-regex.js

@@ -484,12 +484,12 @@ function _sanitizeTransform(input) {
  * @example
  *   var gate = b.guardRegex.gate({ profile: "strict" });
  *
- *   gate({ identifier: "(a+)+b" }).then(function (rv) {
+ *   gate.check({ identifier: "(a+)+b" }).then(function (rv) {
  *     rv.ok;                                           // → false
  *     rv.action;                                       // → "refuse"
  *   });
  *
- *   gate({ identifier: "^[a-z]+$" }).then(function (rv) {
+ *   gate.check({ identifier: "^[a-z]+$" }).then(function (rv) {
  *     rv.action;                                       // → "serve"
  *   });
  */

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/middleware/asyncapi-serve.js

@@ -94,7 +94,7 @@ var audit         = lazyRequire(function () { return require("../audit"); });
  * @example
  *   var b = require("@blamejs/core");
  *   var app = b.router.create();
- *   var aapi = b.asyncapi.create({ title: "events", version: "1.0.0" });
+ *   var aapi = b.asyncapi.create({ info: { title: "events", version: "1.0.0" } });
  *   app.use(b.middleware.asyncapiServe({
  *     document:      aapi,
  *     pathJson:      "/asyncapi.json",

package/lib/middleware/index.js

@@ -120,7 +120,11 @@ module.exports = {
   tracePropagate:        tracePropagate.create,
   tusUpload:        tusUpload.create,
   webAppManifest:   webAppManifest.create,
-  clearSiteData:    clearSiteData.create,
+  clearSiteData:    Object.assign(clearSiteData.create, {
+    headerValue:   clearSiteData.headerValue,
+    KNOWN_TYPES:   clearSiteData.KNOWN_TYPES,
+    DEFAULT_TYPES: clearSiteData.DEFAULT_TYPES,
+  }),
   nel:              nel.create,
   speculationRules: speculationRules.create,
   protectedResourceMetadata: protectedResourceMetadata.create,

package/lib/middleware/openapi-serve.js

@@ -100,7 +100,7 @@ var audit         = lazyRequire(function () { return require("../audit"); });
  * @example
  *   var b = require("@blamejs/core");
  *   var app = b.router.create();
- *   var doc = b.openapi.create({ title: "api", version: "1.0.0" });
+ *   var doc = b.openapi.create({ info: { title: "api", version: "1.0.0" } });
  *   app.use(b.middleware.openapiServe({
  *     document:     doc,
  *     pretty:       true,

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)

package/lib/retention.js

@@ -623,7 +623,7 @@ var COMPLIANCE_RETENTION_FLOOR_MS = Object.freeze({
  * matched). Throws on an unknown posture so config-time typos surface.
  *
  * @example
- *   var ttl = b.retention.complianceFloor("hipaa", b.C.TIME.days(180));
+ *   var ttl = b.retention.complianceFloor("hipaa", b.constants.TIME.days(180));
  *   // → 189216000000 (HIPAA's 6-year floor wins over the 180-day candidate)
  *
  *   var sox = b.retention.complianceFloor("sox", 0);

package/lib/safe-schema.js

@@ -996,8 +996,11 @@ function unknown() { return any(); }
  *   // → "object/unknown-key"
  *
  *   // Prototype-pollution attempt rejected even with passthrough.
+ *   // A hostile __proto__ only becomes an own key through JSON input;
+ *   // object-literal `__proto__:` sets the prototype instead.
  *   var loose = user.passthrough();
- *   var report = loose.safeParse({ email: "a@b.com", age: 30, __proto__: { admin: true } });
+ *   var hostile = JSON.parse('{ "email": "a@b.com", "age": 30, "__proto__": { "admin": true } }');
+ *   var report = loose.safeParse(hostile);
  *   report.ok;
  *   // → false
  *   report.errors[0].code;

package/lib/subject.js

@@ -133,7 +133,12 @@ function exportData(subjectId, opts) {
 
   var tables = db()._getSubjectTables();
   if (tables.length === 0) {
-    return _writeAudit("subject.export", subjectId, "success", { reason: opts.reason || null }, {});
+    // No subjectField-tagged tables: still audit, but return the documented
+    // empty dump ({}) — _writeAudit returns undefined, so returning its value
+    // (with a vestigial 5th arg) silently handed callers `undefined`, crashing
+    // `Object.keys(dump)` / `dump.<table>` before any table is even declared.
+    _writeAudit("subject.export", subjectId, "success", { reason: opts.reason || null });
+    return {};
   }
 
   var dump = {};

package/lib/tls-exporter.js

@@ -106,7 +106,7 @@ function _resolveTlsSocket(socketOrReq) {
  *   }
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   var server = b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
  *     var exporter = b.tlsExporter.fromSocket(req, { length: 32 });
  *     res.end("exporter bytes: " + exporter.length);
@@ -175,7 +175,7 @@ function fromSocket(socketOrReq, opts) {
  * compare via `verifyTokenBinding` on the next request.
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
  *     var binding = b.tlsExporter.bindToken(req, "session-token-abc123");
  *     binding.length;
@@ -214,7 +214,7 @@ function bindToken(socketOrReq, token) {
  * the input shape is wrong.
  *
  * @example
- *   var b = require("blamejs").create();
+ *   var b = require("blamejs");
  *   b.https.createServer({ key: KEY, cert: CERT }, function (req, res) {
  *     var stored = b.tlsExporter.bindToken(req, "session-token-abc123");
  *     var ok = b.tlsExporter.verifyTokenBinding(req, "session-token-abc123", stored);