@blamejs/core 0.18.48 → 0.18.49

package/CHANGELOG.md

@@ -8,6 +8,14 @@ upgrading across more than a few patches at a time.
 
 ## v0.18.x
 
+- v0.18.49 (2026-08-22) — **Comments in the shipped tree that answered a question you cannot ask.** A comment in `lib/` reaches anyone who opens the published package, and twenty of them were written for a reader who remembers the previous version or can look up an issue number that resolves nowhere outside this repository. They now say what the code does and why, in the present tense, keeping every reason they carried. No behaviour changes. **Changed:** *Comments that narrated a change now describe the code* — Fourteen comments across `lib/` were written against a version the reader has never seen: "this used to be opt-in", "it used to declare them in every profile anyway", "the legacy fallback was removed". Each is now a property of the design rather than a diff, and each keeps the reason it carried. The zero-width scan's comment still explains that an opt-in argument is an argument a caller can omit, and still names the six call sites that omitted it — it just no longer reads as a changelog entry pasted into the source.
+
+One of them was wrong in a way worth naming: a note in the gate-contract context builder said a guard "serves bytes it used to examine", which reads as a past version's behaviour. It means bytes the guard would otherwise examine, and now says so. · *Issue numbers that resolve nowhere are gone; the upstream ones stay* — Six comments cited a bare `issue #100` / `#330` / `#430` / `#532`. Opened from the published tarball those name nothing an operator can look up, and the explanation beside them was already doing the work. The references are gone and the explanations stay.
+
+The references that name their upstream are untouched and now read unambiguously: `cure53/DOMPurify issue #233` on the SVG `xlink:href` filtering, and CycloneDX spec issue #702 on the EU CRA property mapping, which is now attributed on both of its mentions rather than one.
+
+The boundary is what ships. `test/` carries 144 of the same kind of reference, most of them a `PR #nnn` on a regression test, and those are left alone: they resolve in the repository a contributor is already reading, and on a regression test the pull-request reference is often the most useful line in the comment. · *Three sentences in SECURITY.md* — A bot-guard rationale said an abuser "simply sends the header", which tells a reader the step is trivial and adds nothing to the argument. Two lists ended in `etc.` without saying where the rest was: the post-quantum algorithm-agility example now names HQC and FrodoKEM as the examples they are, and the session-risk scorer now says it scores whatever signal you have. The other six `etc.` in the file name their generating rule in the next clause and are unchanged.
+
 - v0.18.48 (2026-08-22) — **A guard option you set and a guard option that exists were not the same set.** Every `*Policy` option across the guard family now names the values it takes, and refuses everything else where options are resolved rather than at the first request that trips the scan. Holding the options to their vocabularies surfaced four places where what a guard advertised and what it did had come apart: an option documented under a name nothing read, a value that disabled a critical check without appearing in any opts block, two policies whose settings the gate's floor overrode anyway, and one declared in all three profiles and read nowhere. **Fixed:** *A guard policy refuses a value outside its vocabulary* — The two hundred and sixty-two `*Policy` options across the guard family each declare the values they accept, checked where options are resolved — boot, not the first hostile input — and on every entry point, including the `gate()` and `validate()` of guards that bind their own resolver.
 
 The failure it ends is quiet, because policies are read leniently. `duplicateKeyPolicy: "rejct"` is not `allow`, so the check still runs; it is not `reject` either, so the finding drops from critical to a warning. The operator asked to refuse a duplicate key and silently got an audit line. Nothing was let through that a stricter reading would have caught, so this was never a hole — but a setting that means something other than what it says is worth a restart to learn about.

package/lib/ai-model-manifest.js

@@ -178,8 +178,8 @@ function build(opts) {
     }
   }
 
-  // Hyperparameters → CycloneDX properties[] kv pairs per spec
-  // issue #702 EU CRA alignment.
+  // Hyperparameters → CycloneDX properties[] kv pairs, per CycloneDX spec
+  // issue #702 (EU CRA alignment).
   var properties = [];
   if (opts.hyperparameters && typeof opts.hyperparameters === "object") {
     var keys = Object.keys(opts.hyperparameters);

package/lib/audit-sign.js

@@ -85,8 +85,8 @@ var _err = AuditSignError.factory;
 // via opts.algorithm — e.g. `auditSigning: { algorithm: "ml-dsa-87" }`
 // for throughput-sensitive deployments. Every key file MUST carry the
 // `algorithm` field on disk — the framework refuses to load a key file
-// that lacks it. The legacy implicit-default-to-ml-dsa-87 fallback was
-// removed as part of the pre-v1 compat-shim sweep.
+// that lacks it. There is no implicit default: a key file whose algorithm has
+// to be guessed is a key file whose signatures cannot be attributed.
 var DEFAULT_SIGNING_ALG = "slh-dsa-shake-256f";
 // ml-dsa-65 (FIPS 204 Category 3, ~192-bit symmetric security) is opt-
 // in alongside ml-dsa-87 — same code path (both auto-detected by
@@ -102,7 +102,7 @@ var SIGNING_KEY_SCHEMA = {
   properties: {
     publicKey:  { type: "string" },
     privateKey: { type: "string" },
-    algorithm:  { type: "string" },     // load-time-required — _initPlaintext + _initWrapped both throw KEY_FILE_MISSING_ALG / UNWRAPPED_MISSING_ALG when the field is absent (legacy implicit-default-to-ml-dsa-87 was removed in the pre-v1 compat-shim sweep). Schema's `required` keeps publicKey + privateKey only so the runtime checks fire with the precise error codes operators have wired alerting on.
+    algorithm:  { type: "string" },     // load-time-required — _initPlaintext + _initWrapped both throw KEY_FILE_MISSING_ALG / UNWRAPPED_MISSING_ALG when the field is absent, rather than defaulting to an algorithm the file never named. Schema's `required` keeps publicKey + privateKey only so the runtime checks fire with the precise error codes operators have wired alerting on.
   },
 };
 

package/lib/auth/passkey.js

@@ -986,7 +986,7 @@ function _requireCredentialIdMatches(response, authoritativeId, why) {
   // _credentialDescriptors deliberately supports -- while the browser returns
   // the unpadded spelling. Two spellings of ONE credential must not read as
   // two credentials, or the compatibility this binding sits next to would
-  // lock out exactly the deployments it was added for.
+  // lock out exactly the deployments it exists for.
   var expected = _canonicalBase64Url(authoritativeId);
   var fields = ["id", "rawId"];
   var stated = 0;

package/lib/backup/index.js

@@ -1697,8 +1697,8 @@ function bundleAdapterStorage(opts) {
       // "unknown" rather than risk a full payload load. For
       // rewrap, we already have to load the payload (to unwrap),
       // so fall back to a sniffEnvelope on the loaded sealed
-      // bytes — fixes the regression where adapters satisfying
-      // the minimum contract couldn't use rewrapBundle.
+      // bytes, which keeps rewrapBundle reachable for an adapter
+      // that satisfies only the minimum contract.
       if (envelopeKind === "unknown") {
         envelopeKind = archiveLazy().sniffEnvelope(sealed);
       }

package/lib/client-hints.js

@@ -136,8 +136,7 @@ function _parseSfBrandList(s) {
   // sf-list members don't allow parenthesized inner-list values in
   // the Sec-CH-UA grammar (only sf-string + parameters), so the
   // simple top-level comma split suffices — no `depth` tracking
-  // needed (the earlier inline shape carried defensive paren
-  // tracking left over from a generic sf-list walker prototype).
+  // needed.
   var pieces = structuredFields.splitTopLevel(t, ",");
   var out = [];
   for (var i = 0; i < pieces.length; i += 1) {

package/lib/codepoint-class.js

@@ -860,11 +860,12 @@ function detectCharThreats(text, opts, codePrefix) {
   // zero-width-only input under `strip` reaches the sanitizer instead of being
   // served unchanged.
   //
-  // This used to be OPT-IN via a `zeroWidthSeverity` argument, which meant a
-  // caller that forgot it disabled the scan no matter what the operator's
-  // policy said — and six did, including the shared gate path, so seven guards
-  // declared `zeroWidthPolicy: "reject"` and never applied it. Six more passed
-  // a hardcoded "warn", which dispositions to serve, so they reported the
+  // Not opt-in, and deliberately: an argument the caller has to pass in order
+  // for the scan to run is an argument a caller can omit, and omitting it
+  // disables the scan no matter what the operator's policy says. Six call
+  // sites omitted it, the shared gate path among them, so seven guards declared
+  // `zeroWidthPolicy: "reject"` and never applied it. Six more passed a
+  // hardcoded "warn", which dispositions to serve, so they reported the
   // character and shipped it anyway.
   //
   // Severity follows the resolved POLICY, not a per-caller constant — the same

package/lib/gate-contract.js

@@ -305,7 +305,7 @@ function validateGateShape(gate, label, errorClass) {
 //   - `Object.assign({}, base, ...)` copies OWN enumerable properties, so a
 //     class instance whose fields come from prototype getters arrives with them
 //     missing. A guard reading an absent subject as nothing-to-inspect then
-//     serves bytes it used to examine.
+//     serves bytes it would otherwise examine.
 //   - `Object.create(base)` fixes that but makes inherited getters run with the
 //     DERIVED object as `this`, so a getter returning a private field throws
 //     and a valid context is refused.

package/lib/guard-archive.js

@@ -115,11 +115,12 @@ var MAGIC_SIGNATURES = Object.freeze([
 
 // Character-class policy for an entry NAME comes from `filenameProfile`, which
 // routes the name through b.guardFilename — this guard never reads a
-// bidi/control/null/zero-width policy of its own. It used to declare them in
-// every profile anyway, so an operator passing `zeroWidthPolicy` here was
-// configuring nothing and had no way to find that out. The declarations are
-// gone rather than wired, because `filenameProfile` is already the one place
-// that decides it and two spellings of the same setting is how they disagree.
+// bidi/control/null/zero-width policy of its own, and does not declare them in
+// its profiles either. Declaring an option nothing reads leaves an operator
+// setting `zeroWidthPolicy` here configuring nothing, with no way to find that
+// out. Wiring them instead would give the same setting two spellings, which is
+// how the two come to disagree, and `filenameProfile` is already the one place
+// that decides it.
 var PROFILES = Object.freeze({
   "strict": {
     traversalPolicy:           "reject",

package/lib/guard-regex.js

@@ -201,14 +201,15 @@ function _classUsesSetSyntax(text, from) {
 // ---- pattern parsing ------------------------------------------------------
 //
 // Every analysis below reads a parse tree. None of them reads the pattern
-// source. Reading source with regexes is what this module used to do, and each
-// reader drew the token boundaries a little differently: one could not see
-// past a nested group, one decided whether a `?` was a quantifier by looking at
-// the previous CHARACTER (so the `?` in `\*?` read as a lazy marker and the
-// length variation it contributes was lost), one capped the digits inside
-// `{n,m}` (so a longer bound read as no quantifier at all). Each disagreement
-// was a way to write a catastrophic pattern that one reader found and another
-// waved through, and patching them one at a time only moved the edge.
+// source. Reading source with regexes puts a separate reader behind each
+// analysis, and separate readers draw the token boundaries differently: one
+// cannot see past a nested group, one decides whether a `?` is a quantifier by
+// looking at the previous CHARACTER (so the `?` in `\*?` reads as a lazy marker
+// and the length variation it contributes is lost), one caps the digits inside
+// `{n,m}` (so a longer bound reads as no quantifier at all). Every such
+// disagreement is a way to write a catastrophic pattern that one reader finds
+// and another waves through, and patching them one at a time moves the edge
+// rather than closing it.
 //
 // So: one tokenizer, one tree, and anything it cannot represent becomes an
 // OPAQUE node — which every analysis treats as "cannot prove", never as
@@ -754,9 +755,9 @@ function _codePointAt(src, at, flags) {
 // `k`, but `k` uppercases to `K` and never back to the Kelvin sign, so a pass
 // starting at `K` never reaches it and two branches that both match it were
 // proven disjoint. Which characters an engine treats as equal under `i` is a
-// rule the language states, so the rule is applied — it used to be discovered
-// by building a RegExp per pair of characters and seeing which ones matched,
-// which is the screen reaching for the construct it exists to screen.
+// rule the language states, so the rule is applied rather than discovered by
+// building a RegExp per pair of characters and seeing which ones match, which
+// would be the screen reaching for the construct it exists to screen.
 //
 // Only characters PRESENT in the pattern can create an overlap between two of
 // its sets, so the comparison is made over that alphabet alone. Pairs whose
@@ -796,9 +797,9 @@ function _foldGroups(src, flags) {
       var x = alphabet[a], y = alphabet[b];
       if (_linkedByCase(x, y)) continue;                    // already found by folding
       // Which characters an engine treats as the same under `i` is a rule, not
-      // something to be discovered by asking. This used to build a RegExp per
-      // pair and see whether one matched the other — the screen reaching for
-      // the very construct it screens, and a pattern's worth of them per call.
+      // something to be discovered by asking. Building a RegExp per pair and
+      // seeing whether one matches the other is the screen reaching for the very
+      // construct it screens, and a pattern's worth of them per call.
       // The rule itself is exact and costs a comparison.
       if (_canonical(x, unicodeMode) !== _canonical(y, unicodeMode)) continue;
       _linkFold(groups, x, y);

package/lib/mail-auth.js

@@ -1227,12 +1227,9 @@ function _dmarcAuthorDomainLabels(domain) {
   if (!d) return null;
   // Both RFC 1035 §2.3.4 bounds — 63 octets per label and 253 for the whole
   // name — are enforced by `canonicalDomain` itself, so an over-long or empty
-  // label has already returned "" above. This function used to re-check the
-  // label bound because canonicalDomain enforced only the total; the comment
-  // here argued a label cap was a DNS wire rule rather than a naming one, which
-  // did not survive the observation that the 253 cap is equally a wire rule and
-  // was enforced there anyway. Fixing it at the definition means every caller
-  // gets it, not just this one.
+  // label has already returned "" above. No re-check here: both are wire rules
+  // of the same kind, and enforcing them where the name is defined gives them
+  // to every caller rather than to whichever ones remembered.
   return d.split(".");
 }
 

package/lib/metrics.js

@@ -1024,7 +1024,7 @@ function _serializeRegistry(registry) {
   // a JSON-friendly structured shape. Histograms get full buckets +
   // bucket counts so downstream consumers compose
   // `histogram_quantile()` against the snapshot without a separate
-  // exposition endpoint (issue #100).
+  // exposition endpoint.
   var out = {};
   var names = registry.metrics instanceof Map
     ? Array.from(registry.metrics.keys()).sort()
@@ -1073,8 +1073,8 @@ function snapshotStartWriter(opts) {
     throw new MetricsError("metrics-snapshot/bad-fields",
       "metrics.snapshot.startWriter: opts.fields must be a function returning the snapshot object");
   }
-  // Issue #100 — optional `registry` handle pulls every registered
-  // metric into a structured `metrics` field in the JSON snapshot:
+  // The optional `registry` handle pulls every registered metric into a
+  // structured `metrics` field in the JSON snapshot:
   // counters / gauges as `{ value }` per label set, histograms as
   // `{ buckets, observations }` with bucket counts + sum + count.
   // Sidecar readers compose `histogram_quantile()` against the
@@ -1420,7 +1420,7 @@ 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
+  // Labeled registry families — 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

package/lib/mtls-ca.js

@@ -25,9 +25,9 @@
  *   `ca.crl` (signed CRL derived from the registry).
  *
  *   `caKeySealedMode` defaults to "required" — sealed file required,
- *   plaintext refused. The legacy "auto" fallback was removed; it
- *   defaulted to writing plaintext on a fresh install, which is the
- *   inverse of the framework's security-defaults-on posture for
+ *   plaintext refused. There is no "auto" mode, because deciding
+ *   for the operator means writing plaintext on a fresh install,
+ *   which is the inverse of the framework's security-defaults-on posture for
  *   at-rest key material. The "disabled" mode is a dev-only opt-out
  *   (operator must justify with audited reason).
  *
@@ -2554,7 +2554,7 @@ function create(opts) {
              path: paths.crl };
   }
 
-  // ---- Algorithm migration (issue #532) ----
+  // ---- Algorithm migration ----
 
   // Serialize rotations on this handle. Two concurrent rotate() calls must not
   // both read the same current generation, both mint the next one, and clobber

package/lib/network-dns.js

@@ -535,8 +535,8 @@ function _dnsQueryLabels(host, primitive) {
   // A delimiter is the one that bites, because `domainToASCII` TRUNCATES at
   // one, so `example.com/evil` can masquerade as a trusted prefix of itself.
   //
-  // Mirroring the rule was tried first, and the list of near-misses above is
-  // what that produced. Asking the owner is the version that cannot drift.
+  // Mirroring the rule locally produces the list of near-misses above. Asking
+  // the owner is the version that cannot drift.
   var canonical = publicSuffix.canonicalDomain(h);
   if (!canonical) {
     throw new DnsError("dns/bad-host",

package/lib/session-device-binding.js

@@ -301,8 +301,8 @@ function create(opts) {
   // A no-store instance is still useful: the stateless fingerprint() reads no
   // store and is the soft device-binding building block for self-validating
   // tokens (a sealed cookie / JWT carrying the fingerprint inside). Rather than
-  // refuse to construct (issue #330 — fingerprint() unreachable without a
-  // store), build the instance and let the persisted bind()/verify() lifecycle
+  // refuse to construct, which would put fingerprint() out of reach for want of
+  // a store, build the instance and let the persisted bind()/verify() lifecycle
   // throw a clear "no store configured" when actually called. Operators wanting
   // ONLY the stateless digest can also use the static
   // b.sessionDeviceBinding.fingerprint(req, opts) with no create() at all.

package/lib/vault/index.js

@@ -472,8 +472,8 @@ async function initFirstRunWrapped() {
       "failed to wrap new vault key: " + e.message);
   }
 
-  // Atomic write via the framework's atomic-file primitive (temp + fsync +
-  // rename + dir fsync — same flow this code used to inline manually).
+  // Atomic write via the framework's atomic-file primitive: temp + fsync +
+  // rename + dir fsync.
   atomicFile.writeSync(paths.sealed, sealed, { fileMode: 0o600 });
 
   log("generated and sealed new vault keypair (ML-KEM-1024 + P-384 hybrid)");

package/lib/ws-client.js

@@ -453,8 +453,8 @@ class WsClient extends EventEmitter {
       if (lookup) tlsOpts.lookup = lookup;
       // The group preference arrives with the shared posture above, already
       // reflecting a runtime setKeyShares(). It lands as `ecdhCurve`: node:tls
-      // has no `curves` option — it accepts that key and ignores it, which is
-      // how this preference used to be dropped from the handshake in silence,
+      // has no `curves` option — it accepts that key and ignores it, so a
+      // preference sent under that name leaves the handshake in silence,
       // whereas a bad `ecdhCurve` throws. An operator value in dialTlsOpts
       // still wins, since it is merged last.
       socket = tls.connect(tlsOpts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.18.48",
+  "version": "0.18.49",
   "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.5",
-  "serialNumber": "urn:uuid:a63c2af3-b9b9-4c06-b74a-dd7049ac3f6c",
+  "serialNumber": "urn:uuid:a6344adf-71aa-4268-ba0f-0073a6ead16a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-22T16:44:54.517Z",
+    "timestamp": "2026-08-22T18:41:08.842Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.18.48",
+      "bom-ref": "@blamejs/core@0.18.49",
       "type": "application",
       "name": "blamejs",
-      "version": "0.18.48",
+      "version": "0.18.49",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.18.48",
+      "purl": "pkg:npm/%40blamejs/core@0.18.49",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.18.48",
+      "ref": "@blamejs/core@0.18.49",
       "dependsOn": []
     }
   ]