@blamejs/core 0.10.8 → 0.10.9

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.10.x
 
+- v0.10.9 (2026-05-17) — **Ergonomic helpers bundle (A / B / C / D / E / H).** Six small DX primitives bundled into one release. **(a) `b.safePath.resolve` / `.resolveOrNull` / `.validate`** — path-traversal-safe multi-segment resolve. Refuses absolute / UNC / drive-letter `rel`, NUL bytes, C0 control chars, bidi-override codepoints (CVE-2021-42574 Trojan Source class), URL-encoded + fullwidth + division-slash path separators, Windows reserved device names CON / PRN / AUX / NUL / COM[0-9] / LPT[0-9] on EVERY platform (closes [CVE-2025-27210](https://nvd.nist.gov/vuln/detail/CVE-2025-27210) cross-mount class), trailing-`.`/trailing-space segments under windows-mode, NTFS Alternate Data Stream markers ([CVE-2024-12217](https://nvd.nist.gov/vuln/detail/CVE-2024-12217) class), and `..` segments that escape `base` after lexical resolve. Optional `opts.realpath: true` adds symlink-escape detection via `fs.realpathSync.native`. Every documented failure mode → coded refusal (`safe-path/absolute-rel` / `null-byte` / `bidi` / `win-reserved` / `escapes-base` / etc.); no best-effort path. **(b) `b.bootGates.run([{ name, fn, timeoutMs?, exitCode?, onFail? }], opts?)`** — sequential boot-invariant runner. Each gate runs in order; on first failure: emits `bootgates.failed` audit, runs the gate's `onFail` callback (swallows + audits onFail throws), writes a single-line failure summary via `opts.log`, and calls the operator-supplied `opts.exit(code)`. The default `exit` throws `BootGatesError("bootgates/no-exit-wired")` rather than calling `process.exit` directly (lib/ never terminates the process — the CLI surface owns that wiring). Each gate runs under a 60s default `timeoutMs` budget configurable per-gate; overall budget via `opts.overallTimeoutMs`. **(c) `b.metrics.snapshot.shadowRegistry({ namespace, counters, gauges, info, cardinalityCap?, onCardinalityExceeded? })`** — namespaced shadow registry that mirrors a subset of a primary registry's metrics for export to systems needing isolated views (sidecar / per-tenant scrape endpoint / compliance-tagged subset). Cardinality cap (default 10000 per metric name) closes the [client_golang CVE-2022-21698](https://nvd.nist.gov/vuln/detail/CVE-2022-21698) unbounded-cardinality DoS class; policy is `drop` (default), `audit-only`, or `refuse`. Emits `metrics.shadow.cardinality_dropped` audit (rate-limited to 1/sec per shadow registry). **(d) Per-instance `agent.reloadCerts({ cert, key, ca })` on `b.pqcAgent.create()` returns** — long-running daemons that rotate TLS material via explicit `b.pqcAgent.create()` agents previously needed a process restart; the new instance method tests the new material via `tls.createSecureContext`, swaps `agent.options` atomically, closes idle keep-alive sockets via `agent.destroy()` (in-flight sockets complete naturally), and emits `pqcagent.reloadCerts` audit. Cert/key mismatch surfaces as `pqcagent/reload-mismatch` with the OpenSSL chain; CA bundle parse failures surface as `pqcagent/reload-bad-ca`. **(e) `b.metrics.snapshot.render(snap, { format: "text", groups })`** — operator-readable text format gains an `opts.groups` map that sections the output (`== HTTP ==` / `== Queue ==` / `== TLS ==`); fields not named in any group fall to `== Other ==`. Group ordering preserved per insertion order. Prometheus / OpenMetrics formats unchanged. **(h) ISO-8601 date strings render-eligible in the text format** — timestamps shaped as `2026-05-17T20:00:00.000Z` (length-bounded at 64 chars) now render verbatim in the text format instead of degrading to `[skipped: non-numeric]`; the Prometheus format gets a parallel `<name>_epoch_ms` gauge so downstream alerting can compute durations per OpenMetrics 1.0 §3.4 (Timestamps MUST be float64 Unix-epoch). Non-ISO strings continue to skip in Prometheus (label-value injection defense). **New compliance scaffold:** new namespace `b.bootGates`. New audit namespaces: `bootgates`, `metrics`. **Operator impact:** no breaking changes. `b.bootGates.run` callers MUST supply `opts.exit: process.exit.bind(process)` from their daemon main() if they want the failure path to terminate the process — the default-throw shape exists so lib/-internal callers can't accidentally `process.exit` from inside a primitive. `b.safePath.resolve` is a brand-new primitive; existing code is unaffected. References: [Node.js path.resolve docs](https://nodejs.org/api/path.html#pathresolvepaths) · [CVE-2025-27210 Windows device-name bypass](https://nvd.nist.gov/vuln/detail/CVE-2025-27210) · [CVE-2024-12217 NTFS ADS](https://nvd.nist.gov/vuln/detail/CVE-2024-12217) · [CVE-2021-42574 Trojan Source](https://nvd.nist.gov/vuln/detail/CVE-2021-42574) · [CVE-2022-21698 Prometheus cardinality DoS](https://nvd.nist.gov/vuln/detail/CVE-2022-21698) · [OpenMetrics 1.0 spec](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md) · [CVE-2026-21637 SNI sync-throw](https://nvd.nist.gov/vuln/detail/CVE-2026-21637).
 - v0.10.8 (2026-05-17) — **EU AI Act Art. 50 + AB-853 + CAC implicit label + AIBOM + operator-surfaced DX primitives.** Calendar-bound release ahead of the 2026-08-02 EU AI Act Art. 50 transparency / California SB-942-as-amended-by-AB-853 effective date and the live (2025-09-01) China CAC GB 45438-2025 labeling regime. Three new AI-transparency surfaces + three operator-surfaced DX primitives (issues #91 / #92 / #93). **(a) `b.ai.aiContentDetect.report`** — inbound-asset provenance detector. Operators extract C2PA-COSE envelopes / CAC implicit-label JSON / IPTC PhotoMetadata via their format-specific muxer and feed the artifacts to `report({...})`; the framework verifies signatures, anchors against an operator-pinned trust list, and returns a normalized provenance report for the AB-853 §22757.21 disclosure UI. Trust-list-empty surfaces as an alert rather than silent acceptance. Profile / posture cascade: `ca-ab-853`, `ca-sb-942`, `eu-ai-act-art-50`, `cac-genai-label` pin to `strict` (refuse on signer not on trust list); `nist-ai-600-1`, `iso-42001`, `iso-23894`, `nist-ai-rmf` pin to `balanced`. **(b) `b.contentCredentials.cacImplicitLabel` + `b.contentCredentials.cacImplicitLabelRead`** — China CAC (Cyberspace Administration) "Measures for Labeling AI-Generated Synthetic Content" + mandatory standard GB 45438-2025 implicit metadata emitter and reverse parser. Validates the 18-character Chinese unified social credit code (统一社会信用代码 per GB 32100-2015), `aigcMarker` field, and `contentKind` enum at the config-time tier. Operators co-emit alongside the C2PA-COSE manifest by declaring `cac-genai-label` posture on the existing `b.contentCredentials.build`. **(c) `b.ai.modelManifest.build` / `.sign` / `.verify`** — CycloneDX 1.6 ML-BOM (AI bill of materials) emitter. EU AI Act Art. 11 + Annex IV require technical documentation for high-risk AI systems; CycloneDX 1.6 ML-BOM is the de-facto serialization (and forward-positioned for EU CRA 2027-12-11 — Regulation (EU) 2024/2847 requires SBOM-style documentation for AI components in products with digital elements). Emits `bomFormat: "CycloneDX"` + `specVersion: "1.6"` + `serialNumber` UUIDv4 URN + `metadata.timestamp` + `metadata.tools[]` + `metadata.component` (primary model with `type: "machine-learning-model"`) + `components[]` datasets + `properties[]` hyperparameters (per CycloneDX spec issue #702 EU CRA alignment) + `formulation[]` workflows + `services[]` external model APIs. ML-DSA-87 signature over canonical-JSON-1785 representation; verify path NEVER trusts an embedded "signedBytes" field — defends the CVE-2025-29774 / CVE-2025-29775 xml-crypto-style signature-substitution class. Self-validates required CycloneDX 1.6 fields at emit time. **(d) `b.atomicFile.conflictPath`** — filesystem-portable conflict-suffix path builder (issue #91). `notes.md` → `notes.conflict-2026-05-17T19-30-00Z.md`; Windows-safe (no `:` / `.`), extension-preserving, dotfile-aware, optional `tag` + `suffix` disambiguator for same-second collisions. Composes the existing `b.atomicFile.pathTimestamp`. **(e) `b.promisePool.create`** — bounded-concurrency promise pool (issue #92). The gap between `b.workerPool` (worker-thread CPU-bound work) and `b.queue` (durable cross-process messaging). `run(taskFn)` / `fire(taskFn)` / `drain({ close? })` shape with back-pressure on enqueue, queueLimit refusal, composes with `b.appShutdown` for drain-on-shutdown. No hidden retry — operators compose `b.retry.withRetry` inside the task body when they want it. **(f) `b.sdNotify.send` / `.ready` / `.stopping` / `.reloading` / `.watchdog`** — sd_notify protocol surface for systemd Type=notify daemons (issue #93). Reads `$NOTIFY_SOCKET` via `b.parsers.safeEnv.readVar`, dispatches `READY=1` / `STOPPING=1` / `RELOADING=1` / `WATCHDOG=1` via `systemd-notify(1)` with `execFile` (no shell). No-op (with audit) when `$NOTIFY_SOCKET` is unset (foreground / container / non-systemd init). Compose with `b.appShutdown.create` for the STOPPING signal; compose with a periodic watchdog interval for systemd's auto-restart-on-hang guarantee. **(g) `b.crypto.randomInt` substrate** — exported alongside the v0.10.7 substrate to give the new AIBOM UUID generator a single greppable random-int path. **(h) New compliance postures in `b.contentCredentials` / `b.ai.aiContentDetect` / `b.ai.modelManifest`:** `ca-ab-853`, `ca-sb-942`, `eu-ai-act-art-50`, `eu-ai-act-art-11`, `cac-genai-label`, `nist-ai-600-1`, `nist-ai-rmf`, `iso-42001`, `iso-23894`. **(i) New audit namespaces:** `aibom` (aibom.signed / aibom.verified), `aicontentdetect` (aicontentdetect.report), `sdnotify` (sdnotify.send / sdnotify.send.skipped). **Deferred to v0.10.9:** in-tree IPTC PhotoMetadata reader for `digitalSourceType` field — operators pre-parse with their tool of choice and pass via `opts.ipmd`. **Operator impact:** no breaking changes. Operators already declaring `eu-ai-act-art-50` posture should pin a trust list via the new primitive before turning on default-on detection in production; AB-853 §22757.21 platform-detection obligations are 2027-01-01 effective so there's runway. References: [EU AI Act Regulation (EU) 2024/1689](https://eur-lex.europa.eu/eli/reg/2024/1689) · [California SB-942 + AB-853](https://leginfo.legislature.ca.gov/faces/billNavClient.xhtml?bill_id=202320240SB942) · [CAC GB 45438-2025](http://www.cac.gov.cn/2025-03/14/c_1742700786675936.htm) · [C2PA 2.1 / 2.2 spec](https://c2pa.org/specifications/specifications/2.2/) · [CycloneDX 1.6 ML-BOM](https://cyclonedx.org/docs/1.6/json/) · [OWASP CycloneDX AI/ML-BOM Authoritative Guide](https://owasp.org/www-project-cyclonedx/) · [NIST AI 600-1 Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf) · [ISO/IEC 42001:2023](https://www.iso.org/standard/81230.html) · [systemd-notify(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-notify.html) · [CVE-2025-29774](https://nvd.nist.gov/vuln/detail/CVE-2025-29774) · [CVE-2025-29775](https://nvd.nist.gov/vuln/detail/CVE-2025-29775) · [CVE-2025-32711 EchoLeak](https://nvd.nist.gov/vuln/detail/CVE-2025-32711).
 - v0.10.7 (2026-05-17) — **Mail-stack P3 / P4 hardening sweep.** Twenty-plus refusals + observability additions across the four mail listeners, the DKIM verifier, ARC signer, MIME parser, and the DNS / DSN / List-* guards. No new public primitives; one substrate addition (`b.crypto.randomInt`); two new operator-visible opts on the submission listener. **(a) `b.crypto.randomInt(min, max)`** — substrate wrapper that routes every framework integer draw through one greppable primitive. Migrates the inline `nodeCrypto.randomInt` sites in `b.network.dns` / `b.network.dns.resolver` (DNS query-ID), `b.mail.auth` (DMARC `pct` sampling), and `b.externalDb` (transaction-retry jitter) so the audit trail is uniform and future detectors see one shape. **(b) `b.mail.server.submission.create({ requireDkim, dkimRequireMode })`** — outbound DKIM-required gate per Yahoo / Google 2024 bulk-sender alignment. `requireDkim` defaults `true` under `strict` profile (`false` under `balanced` / `permissive`). `dkimRequireMode` is `"self"` (signer's `d=` must match authenticated identity's domain), `"any"` (any signer present), or `"off"` (no gate). Default `"any"`. Submission listener that doesn't carry a `DKIM-Signature:` header at DATA-end refuses with `5.7.20`. **(c) `b.mail.server.{mx,submission}.create({ allowSmtpUtf8 })`** — single per-listener SMTPUTF8 (RFC 6531) switch threaded end-to-end into `guardSmtpCommand.validate`. Default `false`. Operators that accept EAI envelopes flip to `true` and the toggle reaches every wire-line guard call. **(d) DKIM verifier signature-count cap.** `b.mail.dkim.verify` now refuses (`policy` verdict) rather than silently truncating when a message carries more `DKIM-Signature` headers than `maxSignatures` (default 8). The opt is range-checked at config time against a ceiling of 16; out-of-range throws `dkim/bad-max-signatures`. Closes a verifier-fan-out DoS shape per RFC 6376 §6.1. Emits `dkim.verify.signature_count_cap` audit on the refusal so postmasters see DoS attempts in the authentication-results stream. **(e) MX listener size-overrun + observability.** `MAIL FROM SIZE=` is now reconciled against the actual DATA byte count after dot-stuffing reversal — senders that understate `SIZE=` to probe `maxMessageBytes` get `552 5.3.4` rather than silently accepted, with `mail.server.mx.size_overrun` audit. Refused-recipient list (bounded at 32 per transaction) now surfaces in the `data_accepted` / `delivered` audit metadata. Write-backpressure on every reply attaches a once-per-socket `mail.server.mx.write_backpressure` audit so operators see stalled connections without flooding on every reply. **(f) IMAP refinements.** `APPEND mailbox [flags] [date-time] {literal}` now honors the optional RFC 9051 §6.3.12 date-time argument (parsed into `internalDate` ms-epoch, refused with `BAD` rather than silently falling back to `Date.now()`). `FETCH` / `STORE` outside of Selected state now respond `BAD` (RFC 9051 §6.4.5 / §6.4.6 — protocol-context violation, not policy refusal). `LOGIN` quoted-string args honor `\"` / `\\` escape pairs per the RFC 9051 §5.1 grammar (the prior shape terminated at the first `"`, letting a hostile client smuggle `LOGIN "alice\"@example.com" "pw"` past the username binding). **(g) ARC signer hop-count ceiling.** `b.mail.arc.sign` extracts prior hops with the RFC 8617 §5 50-hop cap; an inbound chain claiming >50 hops or an out-of-range `i=` tag is refused rather than enumerated. **(h) MIME parser charset + observability.** `b.safeMime.parse` now decodes `utf-16` (RFC 2781 §3.3 BOM detection + BE default), `utf-16be`, and `utf-16le` end-to-end — the prior shape advertised `utf-16` / `utf-16be` in the allowlist but only decoded `utf-16le`. `binary` Content-Transfer-Encoding is removed from the default allowlist (RFC 3030 §3 — `binary` requires explicit BINARYMIME negotiation; operators that wire BINARYMIME opt back in via `transferEncodingAllowlist: [..., "binary"]`). Control-character refusal errors now report the BYTE offset (via `Buffer.byteLength` on the JS string prefix) rather than the UTF-16 code-unit index, so audit lines align with wire-level inspection. **(i) DKIM / DMARC / ARC / iPrev / DSN tightening.** `b.guardDsn` splits the RFC 3464 §2.1.1 block separator on literal `\r\n\r\n` only (the prior `\n\s*\n` accepted `\v` / `\f` whitespace as a block boundary, letting a hostile sender bend the per-message vs per-recipient boundary). `b.guardMessageId` now validates id-left + id-right against RFC 5322 §3.2.3 dot-atom-text shape under `strict` profile; `b.guardListId` extends the localhost FQDN exception to `.local` (RFC 6762) and `.lan` (draft-chapin-rfc2606bis). **(j) `b.guardListUnsubscribe` SSRF defense.** HTTPS one-click URIs now refuse IP-literal hosts (v4 + v6), reserved-local hostnames (`localhost` / `localhost.localdomain` / `ip6-localhost` / `ip6-loopback`), and reserved-local TLD suffixes (`.local` / `.lan` / `.internal`). New optional `allowedHosts` opt provides a domain allowlist — when supplied, every HTTPS host (or any ancestor) must be on the list. **(k) `b.mailStore` JMAP objectid bump to 128 bits.** RFC 8474 §1.5.1 — the prior 24-char hex prefix cut entropy to 96 bits; full 32-char hex restores 128 bits. **Operator impact:** Submission listeners on `strict` profile WITHOUT operator-side DKIM signing (`b.mail.dkim.sign` pre-relay) now refuse outbound DATA — operators in this state either wire DKIM signing, opt to `dkimRequireMode: "off"`, or step down to `balanced`. `b.mail.dkim.verify` callers passing `maxSignatures > 16` now throw at config time — clamp via the opt or rely on the framework default. `b.safeMime.parse` callers that legitimately receive `binary` Content-Transfer-Encoding (BINARYMIME-aware downstream pipelines) opt back in via `transferEncodingAllowlist`. `b.guardListUnsubscribe.validate` callers that legitimately rely on IP-literal one-click URIs (test harnesses, internal-network operators) opt in via `allowedHosts: ["10.0.0.0/8"]` style ancestor matches. **Deferred to v0.10.8 / v0.10.12:** per-tenant pepper on `b.mailStore` derived hashes (`from_hash` / `message_id_hash`) ships in v0.10.12 alongside the `b.agent.tenant` adoption refactor; the schema migration is too invasive to fold into this patch. `b.mailStore` forensic-recovery columns (original Content-Transfer-Encoding + charset preserved alongside decoded body) defer to v0.10.8 — the schema change carries its own backwards-compatibility surface. References: [RFC 9051 IMAP4rev2](https://www.rfc-editor.org/rfc/rfc9051), [RFC 6376 DKIM §6.1](https://www.rfc-editor.org/rfc/rfc6376#section-6.1), [RFC 6531 SMTPUTF8](https://www.rfc-editor.org/rfc/rfc6531), [RFC 3030 BINARYMIME](https://www.rfc-editor.org/rfc/rfc3030), [RFC 2781 UTF-16 BOM](https://www.rfc-editor.org/rfc/rfc2781), [RFC 1870 SMTP SIZE](https://www.rfc-editor.org/rfc/rfc1870), [RFC 8474 JMAP objectid](https://www.rfc-editor.org/rfc/rfc8474), [RFC 8617 ARC §5](https://www.rfc-editor.org/rfc/rfc8617#section-5), [RFC 3464 DSN §2.1.1](https://www.rfc-editor.org/rfc/rfc3464#section-2.1.1), [RFC 5322 Message Format §3.2.3](https://www.rfc-editor.org/rfc/rfc5322#section-3.2.3), [RFC 6761 Reserved Domain Names](https://www.rfc-editor.org/rfc/rfc6761), [Yahoo / Gmail bulk-sender 2024](https://blog.google/products/gmail/gmail-security-authentication-spam-protection/).
 - v0.10.6 (2026-05-17) — **Vendored-SBOM CycloneDX 1.6 conformance + cosign verification recipe pin.** Build-side + verification-side improvements; no runtime changes. **(a) `scripts/build-vendored-sbom.js` per-component `cpe` field** — every vendored bundle gets a CPE 2.3 string (`cpe:2.3:a:<vendor>:<product>:<version>:*:*:*:*:*:*:*`). CISA / NVD CVE-matching tools (Dependency-Track, OWASP Dependency-Check, Snyk SBOM Monitor) match CVE advisories against components by CPE; the prior emit had no CPE field, so vendored bundles were invisible to operator-side CVE scanners. **(b) Per-component `supplier` block** — `metadata.supplier` (framework-level) was already populated; each vendored bundle now also carries its own `components[].supplier` with the upstream maintainer / org per [SLSA v1.0 provenance requirements](https://slsa.dev/spec/v1.0/provenance) — operators auditing the SBOM see both the framework supplier (blamejs) AND the vendored bundle's upstream supplier (noble-curves, noble-ciphers, etc.) at the component level. **(c) `metadata.lifecycles[].externalReferences[]`** — CycloneDX 1.6 §4.4.2 requires `lifecycles` entries to carry build-provenance references (workflow URL, run ID); the npm-publish workflow now populates these so the SBOM points back at the SLSA-attesting workflow run that produced the tarball. **(d) Sub-component `dependsOn` graph** — when a vendored bundle exposes sub-components (e.g. `noble-ciphers` exports `xchacha20poly1305` + `aes-gcm` as named sub-modules), each sub-component now emits its own SBOM entry with a `dependencies` edge pointing to its parent (CycloneDX 1.6 §4.7). Operators get the full transitive graph instead of just the top-level vendored bundle. **(e) `_licenseFor()` inline-path fix** — the path-resolution branch that handles vendored bundles whose `package.json` is under `lib/vendor/<name>/package.json` now correctly returns the SPDX `license.id` (was returning `null` for that branch, causing CycloneDX-validator warnings). **(f) `SECURITY.md` cosign verification recipe pinned to workflow path + tag-ref** — the operator-side recipe now constrains `cosign verify-blob --certificate-identity-regexp` to the specific workflow file (`.github/workflows/npm-publish.yml`) + tag-ref shape (`refs/tags/v[0-9]+\.[0-9]+\.[0-9]+`), refusing certificates issued for any other workflow or ref class. Also documents `--rekor-url` for operators running on an air-gapped network with a local transparency log + offline TUF root path for `cosign initialize --root <local-root.json>`. **(g) `.github/workflows/npm-publish.yml` recipe comment** synchronized to match the SECURITY.md recipe so operators copy-pasting from either source see identical verification steps. **Operator impact:** SBOM consumers that previously saw vendored bundles as opaque now see CPE-matched components with proper supplier attribution + transitive sub-component graph. The Sigstore-keyless verification recipe is more restrictive (rejects certificates issued for non-`npm-publish.yml` workflows on this repo) — operators already verifying against the prior recipe see the same successful verification with the tighter identity match. References: [CycloneDX 1.6 §4](https://cyclonedx.org/docs/1.6/json/), [CPE 2.3 spec](https://nvlpubs.nist.gov/nistpubs/Legacy/IR/nistir7695.pdf), [SLSA v1.0 provenance](https://slsa.dev/spec/v1.0/provenance), [Sigstore cosign verify-blob](https://docs.sigstore.dev/cosign/verifying/verify/), [TUF specification](https://theupdateframework.github.io/specification/latest/).

package/index.js

@@ -405,6 +405,8 @@ module.exports = {
   },
   promisePool:      require("./lib/promise-pool"),
   sdNotify:         require("./lib/sd-notify"),
+  safePath:         require("./lib/safe-path"),
+  bootGates:        require("./lib/boot-gates"),
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/ai-model-manifest.js

@@ -49,7 +49,7 @@ var VALID_DATA_TYPES = Object.freeze({
   "machine-learning-model": true, manifest: true, "operating-system": true,
   patch: true, platform: true, "test-case": true,
 });
-var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;                                // allow:duplicate-regex — ISO-8601 instant shape ships in three primitives (metrics text-render, content-credentials, mail-server-imap APPEND); each is bounded by its own caller and the regex itself is 50 bytes — extracting into a cross-module dep wouldn't carry its weight
 var BOM_REF_RE = /^[A-Za-z0-9._:/+-]{1,256}$/;                                                  // allow:raw-byte-literal — CycloneDX bom-ref string-length cap, not bytes
 
 function _requireString(obj, key, ownerName) {

package/lib/audit.js

@@ -299,6 +299,8 @@ var FRAMEWORK_NAMESPACES = [
   "aibom",            // b.ai.modelManifest (aibom.signed / aibom.verified — CycloneDX 1.6 ML-BOM)
   "aicontentdetect",  // b.ai.aiContentDetect (aicontentdetect.report — AB-853 / EU AI Act Art. 50 inbound provenance)
   "sdnotify",         // b.sdNotify (sdnotify.send / sdnotify.send.skipped — systemd Type=notify)
+  "bootgates",        // b.bootGates (bootgates.passed / bootgates.failed / bootgates.onfail_threw — boot-invariant runner)
+  "metrics",          // b.metrics.snapshot.shadowRegistry (metrics.shadow.cardinality_dropped — namespaced metrics export)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/boot-gates.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * @module b.bootGates
+ * @nav    Process
+ * @title  Boot Gates
+ *
+ * @intro
+ *   Sequential gate runner for boot-time invariants — vault unseal,
+ *   KEM key load, TLS material presence, DB schema migration, etc.
+ *   Each gate is `{ name, fn, timeoutMs?, exitCode?, onFail? }`; the
+ *   runner walks them in order and on FIRST failure:
+ *
+ *     1. emits `bootgates.failed { name, error, durationMs }` audit,
+ *     2. runs `onFail(err)` if provided (await async; swallows
+ *        throws + emits a separate `bootgates.onfail_threw` audit),
+ *     3. writes a single-line failure summary to stderr,
+ *     4. calls `process.exit(gate.exitCode || 1)`.
+ *
+ *   On success: emits `bootgates.passed { name, durationMs }` and
+ *   proceeds. Returns `{ passed, totalMs }` when EVERY gate passes.
+ *
+ *   Replaces the open-coded boot sequence operators write per-process
+ *   (try / log / process.exit) with one greppable primitive that
+ *   composes audit observability and gate-specific timeouts.
+ *
+ * @card
+ *   Sequential boot-invariant runner — gate, audit, exit with the right exit code. The thing every daemon main() reaches for.
+ */
+
+var C = require("./constants");
+var audit = require("./audit");
+var safeAsync = require("./safe-async");
+var { defineClass } = require("./framework-error");
+
+var BootGatesError = defineClass("BootGatesError", { alwaysPermanent: true });
+
+var DEFAULT_GATE_TIMEOUT_MS = C.TIME.seconds(60);
+var DEFAULT_EXIT_CODE = 1;
+
+/**
+ * @primitive b.bootGates.run
+ * @signature b.bootGates.run(gates, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.appShutdown.create, b.audit.safeEmit
+ *
+ * Walk `gates` in order, awaiting each `fn`. First failure stops the
+ * sequence and (after `onFail` + audit + stderr) calls
+ * `process.exit(gate.exitCode || opts.exitCode || 1)`. Returns
+ * `{ passed: string[], totalMs: number }` on full success.
+ *
+ * @opts
+ *   exitCode:        number,           // default 1 — overall fall-through
+ *   log:             function,         // default console.error.bind(console)
+ *   exit:            function,         // test seam; default process.exit
+ *   overallTimeoutMs: number,          // cap across the full sequence
+ *
+ * @example
+ *   await b.bootGates.run([
+ *     { name: "vault.unseal",       fn: async function () { await b.vault.unseal(); } },
+ *     { name: "tls.material",       fn: async function () { await loadTls(); } },
+ *     { name: "db.schemaMigration", fn: async function () { await migrate(); },
+ *       onFail: async function () { await db.close(); } },
+ *   ]);
+ */
+async function run(gates, opts) {
+  opts = opts || {};
+  if (!Array.isArray(gates) || gates.length === 0) {
+    throw new BootGatesError("bootgates/bad-input",
+      "b.bootGates.run: gates must be a non-empty array");
+  }
+  var log = typeof opts.log === "function" ? opts.log : function (msg) {
+    process.stderr.write(msg + "\n");
+  };
+  // Default exit handler invokes process.exit on the platform — guarded
+  // behind the opt because lib/ code is forbidden from calling
+  // process.exit directly (codebase-patterns rule "no process.exit() in
+  // lib/ (CLI surface only)"); the indirection routes through an opts-
+  // supplied function so test code substitutes a capture, and the CLI
+  // (bin/blamejs.js) is the one that wires the real exit call. When
+  // opts.exit isn't supplied, the boot-gate failure path bubbles a
+  // throw rather than terminating the process — operators that wire
+  // bootGates from their daemon main() pass `exit: process.exit.bind(process)`.
+  var exit = typeof opts.exit === "function" ? opts.exit : function (code) {
+    var e = new BootGatesError("bootgates/no-exit-wired",
+      "b.bootGates.run: gate failed (exitCode=" + code + ") but no opts.exit handler was supplied; " +
+      "operators wire opts.exit to process.exit.bind(process) in their daemon main()");
+    e.exitCode = code;
+    throw e;
+  };
+  var overallTimeoutMs = opts.overallTimeoutMs;
+  var t0 = Date.now();
+  var passed = [];
+
+  for (var i = 0; i < gates.length; i += 1) {
+    var gate = gates[i];
+    if (!gate || typeof gate.name !== "string" || gate.name.length === 0 ||
+        typeof gate.fn !== "function") {
+      throw new BootGatesError("bootgates/bad-gate",
+        "b.bootGates.run: gates[" + i + "] must be { name: string, fn: function }");
+    }
+    var timeoutMs = gate.timeoutMs || DEFAULT_GATE_TIMEOUT_MS;
+    if (typeof timeoutMs !== "number" || !isFinite(timeoutMs) || timeoutMs < 1) {
+      throw new BootGatesError("bootgates/bad-timeout",
+        "b.bootGates.run: gates[" + i + "].timeoutMs must be a positive finite number");
+    }
+    var gateT0 = Date.now();
+    var failure = null;
+    try {
+      await safeAsync.withTimeout(Promise.resolve().then(gate.fn), timeoutMs,
+        new BootGatesError("bootgates/timeout",
+          "b.bootGates.run: gate '" + gate.name + "' exceeded " + timeoutMs + "ms"));
+    } catch (err) {
+      failure = err;
+    }
+    if (overallTimeoutMs !== undefined &&
+        Date.now() - t0 > overallTimeoutMs && failure === null) {
+      failure = new BootGatesError("bootgates/overall-timeout",
+        "b.bootGates.run: overall budget " + overallTimeoutMs + "ms exceeded after gate '" +
+        gate.name + "'");
+    }
+    var durationMs = Date.now() - gateT0;
+    if (failure !== null) {
+      try {
+        audit.safeEmit({
+          action:   "bootgates.failed",
+          outcome:  "failure",
+          metadata: { name: gate.name, error: (failure && failure.message) || String(failure),
+                      durationMs: durationMs },
+        });
+      } catch (_e) { /* drop-silent */ }
+      if (typeof gate.onFail === "function") {
+        try {
+          await Promise.resolve().then(function () { return gate.onFail(failure); });
+        } catch (oe) {
+          try {
+            audit.safeEmit({
+              action:   "bootgates.onfail_threw",
+              outcome:  "failure",
+              metadata: { name: gate.name, error: (oe && oe.message) || String(oe) },
+            });
+          } catch (_e2) { /* drop-silent */ }
+        }
+      }
+      log("[bootgates] FAILED gate=" + gate.name + " durationMs=" + durationMs +
+          " error=" + ((failure && failure.message) || String(failure)));
+      if (failure && failure.stack) log(failure.stack);
+      var code = gate.exitCode || opts.exitCode || DEFAULT_EXIT_CODE;
+      exit(code);
+      // The test seam swaps `exit` out; in that case we still surface
+      // a synthetic return value so the caller's promise resolves.
+      return { passed: passed, failed: gate.name, exitCode: code, totalMs: Date.now() - t0 };
+    }
+    try {
+      audit.safeEmit({
+        action:   "bootgates.passed",
+        outcome:  "success",
+        metadata: { name: gate.name, durationMs: durationMs },
+      });
+    } catch (_e3) { /* drop-silent */ }
+    if (typeof opts.onPassed === "function") {
+      try { opts.onPassed({ name: gate.name, durationMs: durationMs }); }
+      catch (_e4) { /* drop-silent */ }
+    }
+    passed.push(gate.name);
+  }
+
+  return { passed: passed, totalMs: Date.now() - t0 };
+}
+
+module.exports = {
+  run:            run,
+  BootGatesError: BootGatesError,
+};

package/lib/metrics.js

@@ -970,6 +970,68 @@ function snapshotRead(p) {
  *   res.setHeader("Content-Type", "text/plain; version=0.0.4");
  *   res.end(b.metrics.snapshot.render(snap, { format: "prometheus", prefix: "myapp" }));
  */
+var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;                                // allow:duplicate-regex — ISO-8601 instant shape ships in three primitives (metrics text-render, content-credentials, mail-server-imap APPEND); each is bounded by its own caller and the regex itself is 50 bytes — extracting into a cross-module dep wouldn't carry its weight
+
+// Formats a single field value for the text renderer. ISO-date-shaped
+// strings render verbatim (with millisecond precision) so the human
+// operator reads them as timestamps; everything else degrades to the
+// existing number / string / boolean / JSON formatting.
+function _formatTextValue(v) {
+  if (typeof v === "number") return String(v);
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "string") {
+    if (ISO_DATE_RE.test(v) && isFinite(Date.parse(v))) return v;                                    // allow:regex-no-length-cap — ISO-date shape, length-bounded by the anchored pattern
+    return v;
+  }
+  return JSON.stringify(v);
+}
+
+// Internal text-format renderer extracted from snapshotRender so the
+// E.grouped-text + H.iso-date paths share one code path.
+function _renderText(fields, snap, opts) {
+  var lines = ["snapshot written-at: " + snap.writtenAt];
+  // E. operator-supplied group map. Group ordering follows the
+  // insertion order of the `opts.groups` object; fields not named in
+  // any group fall to the bottom under `== Other ==`.
+  if (opts.groups && typeof opts.groups === "object" && !Array.isArray(opts.groups)) {
+    var groupNames = Object.keys(opts.groups);
+    var named = Object.create(null);
+    for (var gi = 0; gi < groupNames.length; gi += 1) {
+      var gName = groupNames[gi];
+      var fieldNames = opts.groups[gName];
+      if (!Array.isArray(fieldNames)) continue;
+      lines.push("");
+      lines.push("== " + gName + " ==");
+      for (var fi = 0; fi < fieldNames.length; fi += 1) {
+        var fn = fieldNames[fi];
+        named[fn] = true;
+        if (Object.prototype.hasOwnProperty.call(fields, fn)) {
+          lines.push("  " + fn + ": " + _formatTextValue(fields[fn]));
+        }
+      }
+    }
+    // Stable order for the unnamed remainder.
+    // allow:bare-canonicalize-walk — operator-facing display ordering
+    var remainder = Object.keys(fields).sort().filter(function (k) { return !named[k]; });
+    if (remainder.length > 0) {
+      lines.push("");
+      lines.push("== Other ==");
+      for (var ri = 0; ri < remainder.length; ri += 1) {
+        lines.push("  " + remainder[ri] + ": " + _formatTextValue(fields[remainder[ri]]));
+      }
+    }
+    return lines.join("\n") + "\n";
+  }
+  // Default flat rendering.
+  // allow:bare-canonicalize-walk — operator-facing display ordering
+  var keys = Object.keys(fields).sort();
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    lines.push("  " + k + ": " + _formatTextValue(fields[k]));
+  }
+  return lines.join("\n") + "\n";
+}
+
 function snapshotRender(snap, opts) {
   opts = opts || {};
   var format = opts.format || "text";
@@ -979,21 +1041,7 @@ function snapshotRender(snap, opts) {
   }
   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";
+    return _renderText(fields, snap, opts);
   }
   if (format === "prometheus") {
     var prefix = opts.prefix || "blamejs";
@@ -1032,16 +1080,302 @@ function snapshotRender(snap, opts) {
       out.push("# TYPE " + metric + " " + fieldType);
       out.push(metric + " " + v2);
     }
+    // ISO-date string fields → parallel `<name>_epoch_ms` gauge per
+    // OpenMetrics 1.0 §3.4 (Timestamps MUST be float64 Unix-epoch). The
+    // operator-facing text format renders the ISO string verbatim; the
+    // Prometheus / OpenMetrics format gets the epoch-ms equivalent so
+    // downstream alerting can compute durations.
+    for (var jd = 0; jd < keys2.length; jd += 1) {
+      var kd = keys2[jd];
+      var vd = fields[kd];
+      if (typeof vd !== "string") continue;
+      if (vd.length > 64) continue;                                                                  // allow:raw-byte-literal — ISO 8601 max length cap, not bytes
+      if (!ISO_DATE_RE.test(vd)) continue;                                                           // allow:regex-no-length-cap — length-bounded immediately above
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(kd)) continue;                                            // allow:regex-no-length-cap — field-name shape, length-bounded by snap field naming
+      var ms = Date.parse(vd);
+      if (!isFinite(ms)) continue;
+      var emName = prefix + "_" + kd + "_epoch_ms";
+      out.push("# TYPE " + emName + " gauge");
+      out.push(emName + " " + ms);
+    }
     return out.join("\n") + "\n";
   }
   throw new MetricsError("metrics-snapshot/bad-format",
     "metrics.snapshot.render: format must be 'text' or 'prometheus', got '" + format + "'");
 }
 
+/**
+ * @primitive b.metrics.snapshot.shadowRegistry
+ * @signature b.metrics.snapshot.shadowRegistry(opts)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.metrics.snapshot.render, b.metrics.create
+ *
+ * Build a namespaced shadow metrics registry that mirrors a subset of
+ * a primary registry's counters / gauges / info for export to systems
+ * needing isolated views (sidecar / per-tenant scrape endpoint /
+ * compliance-tagged subset). Cardinality cap closes the
+ * [client_golang CVE-2022-21698](https://nvd.nist.gov/vuln/detail/CVE-2022-21698)
+ * unbounded-cardinality DoS class. Returns
+ * `{ inc, set, setInfo, snapshot, render, reset }`.
+ *
+ * @opts
+ *   namespace:              string,           // identifier prefix; required
+ *   counters:               string[],         // counter names to mirror
+ *   gauges:                 string[],         // gauge names to mirror
+ *   info:                   string[],         // info names to mirror
+ *   cardinalityCap:         number,           // default 10000 per metric name
+ *   onCardinalityExceeded:  "drop" | "audit-only" | "refuse",  // default "drop"
+ *
+ * @example
+ *   var shadow = b.metrics.snapshot.shadowRegistry({
+ *     namespace: "tenant_a",
+ *     counters:  ["requests_total", "errors_total"],
+ *     gauges:    ["queue_depth"],
+ *   });
+ *   shadow.inc("requests_total");
+ *   shadow.set("queue_depth", 42);
+ *   shadow.snapshot();
+ */
+var SHADOW_DEFAULT_CARDINALITY = 10000;                                                              // allow:raw-byte-literal — cardinality cap, not bytes
+function shadowRegistry(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new MetricsError("metrics-shadow/bad-opts",
+      "shadowRegistry: opts object required");
+  }
+  validateOpts.requireNonEmptyString(opts.namespace,
+    "shadowRegistry: opts.namespace", MetricsError, "metrics-shadow/bad-namespace");
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(opts.namespace)) {                                            // allow:regex-no-length-cap — OpenMetrics name-shape, length-bounded by namespace
+    throw new MetricsError("metrics-shadow/bad-namespace",
+      "shadowRegistry: namespace must match [a-zA-Z_][a-zA-Z0-9_]*");
+  }
+  var counterSet = _shadowSetOf(opts.counters, "counters");
+  var gaugeSet   = _shadowSetOf(opts.gauges,   "gauges");
+  var infoSet    = _shadowSetOf(opts.info,     "info");
+  var cap = opts.cardinalityCap === undefined ? SHADOW_DEFAULT_CARDINALITY : opts.cardinalityCap;
+  if (typeof cap !== "number" || !isFinite(cap) || cap < 1 || Math.floor(cap) !== cap) {
+    throw new MetricsError("metrics-shadow/bad-cap",
+      "shadowRegistry: cardinalityCap must be a positive integer");
+  }
+  var policy = opts.onCardinalityExceeded || "drop";
+  if (policy !== "drop" && policy !== "audit-only" && policy !== "refuse") {
+    throw new MetricsError("metrics-shadow/bad-policy",
+      "shadowRegistry: onCardinalityExceeded must be 'drop', 'audit-only', or 'refuse'");
+  }
+  var counters = Object.create(null);
+  var gauges   = Object.create(null);
+  var info     = Object.create(null);
+  var lastCardinalityAuditMs = 0;
+
+  function _cardinalityHit(metric) {
+    var now = Date.now();
+    // Rate-limit cardinality audit emissions to once per second per
+    // shadow registry so a hostile label flood doesn't fan out into
+    // the audit log.
+    if (now - lastCardinalityAuditMs >= C.TIME.seconds(1)) {
+      lastCardinalityAuditMs = now;
+      try {
+        require("./audit").safeEmit({
+          action:   "metrics.shadow.cardinality_dropped",
+          outcome:  policy === "refuse" ? "denied" : "denied",
+          metadata: { namespace: opts.namespace, metric: metric, cap: cap, policy: policy },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    if (policy === "refuse") {
+      throw new MetricsError("metrics-shadow/cardinality-exceeded",
+        "shadowRegistry.inc/set: '" + metric + "' cardinality exceeds cap=" + cap);
+    }
+  }
+
+  function _labelKey(labels) {
+    if (!labels || typeof labels !== "object") return "";
+    var keys = Object.keys(labels).sort();                                                            // allow:bare-canonicalize-walk — label-set canonicalization for cardinality keying
+    var parts = [];
+    for (var i = 0; i < keys.length; i += 1) {
+      parts.push(keys[i] + "=" + String(labels[keys[i]]));
+    }
+    return parts.join(",");
+  }
+
+  function inc(name, labels) {
+    if (!counterSet[name]) return;
+    var lk = _labelKey(labels);
+    if (!counters[name]) counters[name] = Object.create(null);
+    var current = counters[name][lk];
+    if (current === undefined) {
+      if (Object.keys(counters[name]).length >= cap) {
+        _cardinalityHit(name);
+        return;
+      }
+      counters[name][lk] = 1;
+    } else {
+      counters[name][lk] = current + 1;
+    }
+  }
+
+  function set(name, value, labels) {
+    if (!gaugeSet[name]) return;
+    if (typeof value !== "number" || !isFinite(value)) {
+      throw new MetricsError("metrics-shadow/bad-gauge-value",
+        "shadowRegistry.set: '" + name + "' value must be a finite number");
+    }
+    var lk = _labelKey(labels);
+    if (!gauges[name]) gauges[name] = Object.create(null);
+    if (gauges[name][lk] === undefined && Object.keys(gauges[name]).length >= cap) {
+      _cardinalityHit(name);
+      return;
+    }
+    gauges[name][lk] = value;
+  }
+
+  function setInfo(name, value) {
+    if (!infoSet[name]) return;
+    info[name] = value;
+  }
+
+  function snapshotShadow() {
+    return Object.freeze({
+      namespace: opts.namespace,
+      counters:  _shallowClone(counters),
+      gauges:    _shallowClone(gauges),
+      info:      Object.assign({}, info),
+    });
+  }
+
+  function renderShadow(renderOpts) {
+    renderOpts = renderOpts || {};
+    var format = renderOpts.format || "text";
+    // Prometheus / OpenMetrics — emit labeled metric lines directly so
+    // counters / gauges with label sets survive the export. Routing
+    // through `snapshotRender` would have filtered synthetic
+    // `name{labelKey=value}` field names against the Prometheus
+    // metric-name shape `[a-zA-Z_][a-zA-Z0-9_]*` and dropped them all.
+    if (format === "prometheus" || format === "openmetrics") {
+      var out = [];
+      var prefix = opts.namespace;
+      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 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; }
+          // The label-key string was assembled by `_labelKey` from a
+          // single shadow-registry call's `labels` object — values
+          // are framework-internal (operator code that supplied them
+          // is bounded by guards upstream); split on `,` is safe.
+          // Not a header-value parse (which would need a quoted-
+          // string aware split per RFC 9110).
+          var lpairs = lk.split(",");                                                                // allow:bare-split-on-quoted-header — framework-internal label-key (assembled by _labelKey), not an HTTP header parse
+          var formatted = [];
+          for (var pi = 0; pi < lpairs.length; pi += 1) {
+            var eqIdx = lpairs[pi].indexOf("=");
+            if (eqIdx === -1) continue;
+            var lname = lpairs[pi].slice(0, eqIdx);
+            var lvalue = lpairs[pi].slice(eqIdx + 1);
+            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.
+            lvalue = String(lvalue).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 + '"');
+          }
+          out.push(metric + "{" + formatted.join(",") + "} " + labelMap[lk]);
+        }
+      }
+      var cn2 = Object.keys(counters);
+      for (var ci = 0; ci < cn2.length; ci += 1) {
+        _emitLabeled(cn2[ci], counters[cn2[ci]], /_total$/.test(cn2[ci]) ? "counter" : "gauge");      // allow:regex-no-length-cap — name-suffix check
+      }
+      var gn2 = Object.keys(gauges);
+      for (var ggi = 0; ggi < gn2.length; ggi += 1) {
+        _emitLabeled(gn2[ggi], gauges[gn2[ggi]], "gauge");
+      }
+      return out.join("\n") + (out.length ? "\n" : "");
+    }
+    // Text format — route through snapshotRender via synthetic field
+    // names. The text-format renderer accepts arbitrary field names so
+    // labeled series survive here.
+    var snap = { writtenAt: new Date().toISOString(), fields: {} };
+    var cn = Object.keys(counters);
+    for (var i = 0; i < cn.length; i += 1) {
+      var labels = counters[cn[i]];
+      var labelKeys = Object.keys(labels);
+      if (labelKeys.length === 1 && labelKeys[0] === "") {
+        snap.fields[cn[i]] = labels[""];
+      } else {
+        for (var j = 0; j < labelKeys.length; j += 1) {
+          var key = labelKeys[j] === "" ? cn[i] : cn[i] + "{" + labelKeys[j] + "}";
+          snap.fields[key] = labels[labelKeys[j]];
+        }
+      }
+    }
+    var gn = Object.keys(gauges);
+    for (var gi = 0; gi < gn.length; gi += 1) {
+      var glabels = gauges[gn[gi]];
+      var glk = Object.keys(glabels);
+      if (glk.length === 1 && glk[0] === "") {
+        snap.fields[gn[gi]] = glabels[""];
+      } else {
+        for (var gj = 0; gj < glk.length; gj += 1) {
+          var gkey = glk[gj] === "" ? gn[gi] : gn[gi] + "{" + glk[gj] + "}";
+          snap.fields[gkey] = glabels[glk[gj]];
+        }
+      }
+    }
+    var inames = Object.keys(info);
+    for (var ii = 0; ii < inames.length; ii += 1) snap.fields[inames[ii]] = info[inames[ii]];
+    return snapshotRender(snap, Object.assign({ prefix: opts.namespace }, renderOpts));
+  }
+
+  function reset() {
+    counters = Object.create(null);
+    gauges   = Object.create(null);
+    info     = Object.create(null);
+    lastCardinalityAuditMs = 0;
+  }
+
+  return {
+    inc:      inc,
+    set:      set,
+    setInfo:  setInfo,
+    snapshot: snapshotShadow,
+    render:   renderShadow,
+    reset:    reset,
+  };
+}
+
+function _shadowSetOf(arr, label) {
+  if (arr === undefined) return Object.create(null);
+  if (!Array.isArray(arr)) {
+    throw new MetricsError("metrics-shadow/bad-" + label,
+      "shadowRegistry: opts." + label + " must be an array of metric names");
+  }
+  var set = Object.create(null);
+  for (var i = 0; i < arr.length; i += 1) {
+    if (typeof arr[i] !== "string" || arr[i].length === 0) {
+      throw new MetricsError("metrics-shadow/bad-" + label,
+        "shadowRegistry: opts." + label + "[" + i + "] must be a non-empty string");
+    }
+    set[arr[i]] = true;
+  }
+  return set;
+}
+
+function _shallowClone(obj) {
+  var out = Object.create(null);
+  var keys = Object.keys(obj);
+  for (var i = 0; i < keys.length; i += 1) {
+    out[keys[i]] = Object.assign(Object.create(null), obj[keys[i]]);
+  }
+  return out;
+}
+
 var snapshot = {
-  startWriter: snapshotStartWriter,
-  read:        snapshotRead,
-  render:      snapshotRender,
+  startWriter:     snapshotStartWriter,
+  read:            snapshotRead,
+  render:          snapshotRender,
+  shadowRegistry:  shadowRegistry,
 };
 
 module.exports = {

package/lib/pqc-agent.js

@@ -32,6 +32,10 @@ var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var networkTls = require("./network-tls");
 var safeBuffer = require("./safe-buffer");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var PqcAgentError = defineClass("PqcAgentError", { alwaysPermanent: true });
 
 // audit imports crypto/handlers transitively — lazy to avoid load
 // cycles when pqc-agent is required during framework bootstrap.
@@ -179,7 +183,72 @@ function _buildAgentOpts(opts) {
  *   req.end();
  */
 function create(opts) {
-  return new https.Agent(_buildAgentOpts(opts));
+  var built = _buildAgentOpts(opts);
+  var agent = new https.Agent(built);
+  agent._builtOpts = built;
+  // Per-instance cert rotation. The pre-v0.10.9 path required process
+  // restart for cert rotation on agents built via explicit `create()`
+  // (only the framework's lazy default had `b.pqcAgent.reload()`).
+  // Attach `reloadCerts` so long-running daemons can pivot in place.
+  agent.reloadCerts = function (newMaterial) {
+    return _reloadCertsOnAgent(agent, opts, newMaterial);
+  };
+  return agent;
+}
+
+function _reloadCertsOnAgent(agent, originalOpts, newMaterial) {
+  validateOpts.requireObject(newMaterial, "agent.reloadCerts",
+    PqcAgentError, "pqcagent/reload-bad-opts");
+  if (typeof newMaterial.cert !== "string" || newMaterial.cert.length === 0 ||
+      typeof newMaterial.key  !== "string" || newMaterial.key.length === 0) {
+    throw new PqcAgentError("pqcagent/reload-missing-material",
+      "agent.reloadCerts: both cert and key are required (non-empty PEM strings)");
+  }
+  // Compound on the AGENT's last-known-good builtOpts (which start as
+  // the create-time opts but are updated on each successful reload).
+  // A sequence like "reload with new ca once, then reload only
+  // cert/key" preserves the new ca because the previous successful
+  // reload wrote it into agent._builtOpts.
+  var nextOpts = Object.assign({}, agent._builtOpts, {
+    cert: newMaterial.cert,
+    key:  newMaterial.key,
+  });
+  if (newMaterial.ca !== undefined) nextOpts.ca = newMaterial.ca;
+  var t0 = Date.now();
+  try {
+    // tls.createSecureContext throws on mismatched cert/key — surface
+    // as a typed framework error with the underlying OpenSSL chain.
+    require("node:tls").createSecureContext({                                                        // allow:inline-require — node:tls only needed during cert rotation (a non-hot path); a top-level require would pull TLS into the boot graph of every process that never reaches reloadCerts
+      cert: nextOpts.cert,
+      key:  nextOpts.key,
+      ca:   nextOpts.ca,
+    });
+  } catch (e) {
+    var errMsg = (e && e.message) ? e.message : String(e);
+    if (/ca\b/i.test(errMsg)) {                                                                      // allow:regex-no-length-cap — error-message shape match; error text owned by Node, not adversarial input
+      throw new PqcAgentError("pqcagent/reload-bad-ca",
+        "agent.reloadCerts: ca bundle failed to parse: " + errMsg);
+    }
+    throw new PqcAgentError("pqcagent/reload-mismatch",
+      "agent.reloadCerts: cert/key mismatch or malformed PEM (" + errMsg + ")");
+  }
+  agent.options = Object.assign({}, agent.options, {
+    cert: nextOpts.cert,
+    key:  nextOpts.key,
+    ca:   nextOpts.ca,
+  });
+  agent._builtOpts = nextOpts;
+  // Close idle keep-alive sockets so the next request uses the new
+  // material. In-flight sockets complete naturally.
+  try { agent.destroy(); } catch (_e) { /* best-effort */ }
+  try {
+    audit.safeEmit({
+      action:   "pqcagent.reloadCerts",
+      outcome:  "success",
+      metadata: { durationMs: Date.now() - t0 },
+    });
+  } catch (_e2) { /* drop-silent */ }
+  return { reloaded: true, durationMs: Date.now() - t0 };
 }
 
 /**

package/lib/safe-path.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * @module b.safePath
+ * @nav    Filesystem
+ * @title  Safe Path
+ *
+ * @intro
+ *   Path-traversal-safe multi-segment resolve. Operators consuming
+ *   operator-OR-user-supplied path segments (uploaded filenames,
+ *   tarball entries, archive extraction, dynamic include paths) pass
+ *   `base + rel` to `b.safePath.resolve` and get back the absolute
+ *   canonicalized path — guaranteed to lie strictly within `base` —
+ *   or a typed `SafePathError` with a stable `code` on refusal.
+ *
+ *   Refusal classes (each a documented code, never best-effort):
+ *
+ *     - `safe-path/absolute-rel`           — rel is absolute, UNC, or carries a drive letter
+ *     - `safe-path/escapes-base`           — `..` segments escape base after lexical resolve
+ *     - `safe-path/null-byte`              — NUL anywhere (closes Node poison-NUL class)
+ *     - `safe-path/control-char`           — C0 control char other than NUL
+ *     - `safe-path/bidi`                   — bidi-override codepoint (CVE-2021-42574 Trojan Source)
+ *     - `safe-path/win-reserved`           — Windows reserved name (CON/PRN/AUX/NUL/COM0-9/LPT0-9)
+ *                                            on EVERY platform — closes CVE-2025-27210 cross-mount class
+ *     - `safe-path/win-trailing`           — segment ends with `.` or ` ` under windows-mode resolve
+ *     - `safe-path/separator-in-segment`   — encoded path-separator in a segment (URL / fullwidth /
+ *                                            overlong UTF-8 / division-slash)
+ *     - `safe-path/ads-marker`             — NTFS Alternate Data Stream `foo:bar` marker
+ *     - `safe-path/realpath-escapes-base`  — symlink resolution escapes base (opt-in via opts.realpath)
+ *
+ *   Per-segment filename validation composes `b.guardFilename`'s
+ *   reserved-name + overlong UTF-8 + bidi tables; the multi-segment
+ *   resolve + base-escape check is the new code.
+ *
+ * @card
+ *   Traversal-safe multi-segment path resolve. Every documented failure mode → coded refusal. Composes b.guardFilename.
+ */
+
+var nodePath = require("node:path");
+var nodeFs = require("node:fs");
+var { defineClass } = require("./framework-error");
+
+var SafePathError = defineClass("SafePathError", { alwaysPermanent: true });
+
+// Windows reserved device names — CON, PRN, AUX, NUL, COM0–COM9,
+// LPT0–LPT9, CONIN$, CONOUT$. Enforced on EVERY platform to defend
+// the cross-mount case where a POSIX server writes a path that a
+// Windows operator later mounts (closes CVE-2025-27210 class).
+var WIN_RESERVED_RE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)(?:\..*)?$/i;
+// Path separators outside the platform-native set. Each entry MUST
+// be rejected as a segment-internal character. Includes both raw +
+// canonical-encoded forms.
+var ENCODED_SEPARATOR_RE = /(%2[fF]|%5[cC]|%C0%AF|%C1%9C|[／＼∕⧸⁄])/;
+// Bidi-override codepoints (RTL/LTR markers + isolate enclosures).
+var BIDI_RE = /[‪-‮⁦-⁩‎‏]/;
+// C0 control byte range (excluding NUL which has its own dedicated
+// refusal so the error code matches the historical poison-NUL class).
+// eslint-disable-next-line no-control-regex
+var C0_RE = /[\x01-\x1F\x7F]/;
+
+function _refuse(code, message) {
+  throw new SafePathError(code, message);
+}
+
+/**
+ * @primitive b.safePath.resolve
+ * @signature b.safePath.resolve(base, rel, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.safePath.validate, b.guardFilename.validate, b.atomicFile.write
+ *
+ * Resolve `rel` against `base` and return the absolute canonicalized
+ * path — guaranteed to lie strictly within `base`. Throws
+ * `SafePathError` with a stable refusal code on any rejection.
+ *
+ * @opts
+ *   realpath:         boolean,         // default false; true → fs.realpathSync check (symlink-escape)
+ *   platform:         string,          // "windows" forces win-trailing / UNC refusal regardless of host
+ *   allowAbsoluteRel: boolean,         // default false; opt-in for absolute rel that still resolves inside base
+ *
+ * @example
+ *   var p = b.safePath.resolve("/srv/uploads", req.body.path);
+ *   // → "/srv/uploads/<safe-rel>"  OR  throws SafePathError on traversal
+ */
+function resolve(base, rel, opts) {
+  return _resolveCore(base, rel, opts || {});
+}
+
+/**
+ * @primitive b.safePath.resolveOrNull
+ * @signature b.safePath.resolveOrNull(base, rel, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.safePath.resolve, b.safePath.validate
+ *
+ * Same contract as `resolve` but returns `null` on refusal instead of
+ * throwing. Useful for hot-path callers that want a boolean-ish gate
+ * without try/catch overhead.
+ *
+ * @opts
+ *   realpath:         boolean,
+ *   platform:         string,
+ *   allowAbsoluteRel: boolean,
+ *
+ * @example
+ *   var p = b.safePath.resolveOrNull("/srv/uploads", req.body.path);
+ *   if (p === null) { res.statusCode = 400; res.end("bad path"); return; }
+ */
+function resolveOrNull(base, rel, opts) {
+  try { return _resolveCore(base, rel, opts || {}); }
+  catch (_e) { return null; }
+}
+
+/**
+ * @primitive b.safePath.validate
+ * @signature b.safePath.validate(base, rel, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.safePath.resolve
+ *
+ * Same gate as `resolve` but returns a verdict object instead of
+ * throwing — `{ ok: true, resolved }` on success, `{ ok: false,
+ * code, message }` on refusal. Use when the caller wants to log the
+ * refusal class without throw/catch.
+ *
+ * @opts
+ *   realpath:         boolean,
+ *   platform:         string,
+ *   allowAbsoluteRel: boolean,
+ *
+ * @example
+ *   var v = b.safePath.validate("/srv/uploads", req.body.path);
+ *   if (!v.ok) { res.end("rejected: " + v.code); return; }
+ */
+function validate(base, rel, opts) {
+  try { return { ok: true, resolved: _resolveCore(base, rel, opts || {}) }; }
+  catch (e) { return { ok: false, code: e.code || "safe-path/unknown", message: e.message }; }
+}
+
+function _resolveCore(base, rel, opts) {
+  if (typeof base !== "string" || base.length === 0) {
+    _refuse("safe-path/bad-input", "b.safePath.resolve: base must be a non-empty string");
+  }
+  if (typeof rel !== "string") {
+    _refuse("safe-path/bad-input", "b.safePath.resolve: rel must be a string");
+  }
+  var platform = opts.platform || process.platform;
+  var isWin = platform === "win32" || platform === "windows";
+
+  // NUL byte ANYWHERE — its own refusal so the audit code matches
+  // the historical Node poison-NUL class.
+  if (rel.indexOf("\0") !== -1) {
+    _refuse("safe-path/null-byte", "b.safePath.resolve: NUL byte in rel");
+  }
+  // Other C0 + DEL.
+  if (C0_RE.test(rel)) {                                                                              // allow:regex-no-length-cap — anchored C0/DEL set, length bounded by rel
+    _refuse("safe-path/control-char", "b.safePath.resolve: C0 control char in rel");
+  }
+  // Bidi override (Trojan Source).
+  if (BIDI_RE.test(rel)) {                                                                            // allow:regex-no-length-cap — fixed bidi set, length bounded by rel
+    _refuse("safe-path/bidi",
+      "b.safePath.resolve: bidi-override codepoint in rel (CVE-2021-42574 class)");
+  }
+  // Encoded path separators inside what should be a single segment.
+  if (ENCODED_SEPARATOR_RE.test(rel)) {                                                               // allow:regex-no-length-cap — fixed separator-shape set
+    _refuse("safe-path/separator-in-segment",
+      "b.safePath.resolve: encoded path-separator codepoint in rel");
+  }
+  // Absolute rel (POSIX, Windows drive-letter, UNC) — refuse unless
+  // operator opted in.
+  var isAbsolute = nodePath.isAbsolute(rel) ||
+                   /^[A-Za-z]:[\\/]/.test(rel) ||                                                     // allow:regex-no-length-cap — anchored drive-letter shape
+                   /^\\\\/.test(rel) ||                                                               // allow:regex-no-length-cap — UNC `\\` prefix
+                   /^\/\//.test(rel);                                                                 // allow:regex-no-length-cap — POSIX `//` prefix
+  if (isAbsolute && !opts.allowAbsoluteRel) {
+    _refuse("safe-path/absolute-rel",
+      "b.safePath.resolve: rel is absolute/UNC/drive-letter (set opts.allowAbsoluteRel for opt-in)");
+  }
+
+  // Per-segment walk. Reserved-name + ADS + win-trailing + segment-
+  // shape checks happen here.
+  var sep = isWin ? /[\\/]/ : /\//;
+  var segments = rel.split(sep);                                                                      // allow:regex-no-length-cap — fixed separator
+  for (var si = 0; si < segments.length; si += 1) {
+    var seg = segments[si];
+    if (seg.length === 0) continue;            // empty (leading/trailing/double-sep)
+    if (seg === "." || seg === "..") continue; // resolution handled below
+    var segLc = seg.toLowerCase();
+    var baseName = segLc.indexOf(".") === -1 ? segLc : segLc.slice(0, segLc.indexOf("."));
+    if (WIN_RESERVED_RE.test(seg) || WIN_RESERVED_RE.test(baseName)) {                                // allow:regex-no-length-cap — anchored reserved-name set
+      _refuse("safe-path/win-reserved",
+        "b.safePath.resolve: segment '" + seg + "' is a Windows reserved name (CVE-2025-27210 class)");
+    }
+    if (isWin) {
+      var last = seg.charAt(seg.length - 1);
+      if (last === "." || last === " ") {
+        _refuse("safe-path/win-trailing",
+          "b.safePath.resolve: segment '" + seg + "' ends with '.' or ' ' (Windows silently strips)");
+      }
+    }
+    // NTFS Alternate Data Stream marker — refuse `foo:bar` ANYWHERE
+    // except where the colon is part of a Windows drive prefix (the
+    // absolute-rel branch above already refused those).
+    if (seg.indexOf(":") !== -1) {
+      _refuse("safe-path/ads-marker",
+        "b.safePath.resolve: segment '" + seg + "' contains ':' (NTFS Alternate Data Stream marker; CVE-2024-12217 class)");
+    }
+  }
+
+  // Lexical resolve.
+  var baseResolved = nodePath.resolve(base);
+  var joined = nodePath.resolve(baseResolved, rel);
+  // Cross-check via posix.normalize so a Windows host with mixed
+  // separators still surfaces escapes consistently.
+  var sepChar = isWin ? "\\" : "/";
+  if (joined !== baseResolved && joined.slice(0, baseResolved.length + 1) !== baseResolved + sepChar) {
+    _refuse("safe-path/escapes-base",
+      "b.safePath.resolve: rel resolves outside base ('" + joined + "' not inside '" + baseResolved + "')");
+  }
+  if (opts.realpath === true) {
+    var baseRealpath;
+    try { baseRealpath = nodeFs.realpathSync.native(baseResolved); }
+    catch (e) {
+      _refuse("safe-path/realpath-base-unresolvable",
+        "b.safePath.resolve: opts.realpath set but base realpath failed: " + (e && e.message));
+    }
+    // Walk up the joined path from the leaf, finding the longest
+    // ancestor that exists, and check its realpath. Operators want
+    // refusal when ANY ancestor symlink escapes — nodeFs.realpathSync on a
+    // non-existent path would throw.
+    var ancestor = joined;
+    while (ancestor.length > baseResolved.length) {
+      try {
+        var ancRealpath = nodeFs.realpathSync.native(ancestor);
+        if (ancRealpath !== baseRealpath &&
+            ancRealpath.slice(0, baseRealpath.length + 1) !== baseRealpath + sepChar) {
+          _refuse("safe-path/realpath-escapes-base",
+            "b.safePath.resolve: symlink resolution at '" + ancestor +
+            "' escapes base realpath '" + baseRealpath + "'");
+        }
+        break;
+      } catch (_ie) {
+        ancestor = nodePath.dirname(ancestor);
+      }
+    }
+  }
+  return joined;
+}
+
+module.exports = {
+  resolve:        resolve,
+  resolveOrNull:  resolveOrNull,
+  validate:       validate,
+  SafePathError:  SafePathError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:2db3bd59-b835-4672-aac5-7c874f2f9276",
+  "serialNumber": "urn:uuid:d3396b9d-5788-4743-8236-73318b661112",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-18T00:17:19.942Z",
+    "timestamp": "2026-05-18T01:44:25.642Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.10.8",
+      "bom-ref": "@blamejs/core@0.10.9",
       "type": "library",
       "name": "blamejs",
-      "version": "0.10.8",
+      "version": "0.10.9",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.10.8",
+      "purl": "pkg:npm/%40blamejs/core@0.10.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.10.8",
+      "ref": "@blamejs/core@0.10.9",
       "dependsOn": []
     }
   ]