@blamejs/core 0.13.30 → 0.13.32

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.32 (2026-05-28) — **`b.auditDailyReview` enforces notify under the sox-404 posture; compliance doc corrections.** b.auditDailyReview documented `sox-404` (SOX §404 ICFR — the internal-controls regime this primitive serves) as one of the postures that make a `notify` callback mandatory at construction, but the enforcement set used only `sox`, so pinning `posture: "sox-404"` without a notify channel was silently accepted. `sox-404` is now in the mandatory-notify set, so the advertised guarantee holds (a regression test pins it). The rest are documentation corrections with no behavior change: b.compliance.posturesByDomain / posturesByJurisdiction examples showed small fixed arrays where the functions return every matching posture (the catalog has grown); b.dataAct's surface list named two methods that do not exist (the real surface is declareProduct / recordUserAccess / shareWithThirdParty / recordSwitchRequest, with gatekeeper refusal folded into shareWithThirdParty); b.secCyber.eightKArtifact's documented return key `audit` is actually `deadlineBusinessDays`; and b.compliance.aiAct.transparency's helper summary named `cspMetaTag` / a `watermark({ kind })` argument that are really `metaTags` / `watermark({ mediaKind })`. **Fixed:** *`b.auditDailyReview` requires a notify channel under the `sox-404` posture* — The docs listed `sox-404` among the postures that make a `notify` callback mandatory at create-time, but the enforcement set contained only `sox` — so `posture: "sox-404"` without `notify` was accepted instead of refused. `sox-404` (SOX §404 ICFR) is now in the mandatory-notify set, matching the documented guarantee; constructing without a notify channel under it throws `auditDailyReview/notify-required-under-posture`. · *`b.compliance` jurisdiction/domain lister examples no longer enumerate a stale fixed set* — `posturesByDomain` and `posturesByJurisdiction` return every posture matching the domain/jurisdiction, but their `@example`s showed small fixed arrays from before the posture catalog grew. The examples now show a representative prefix with `...` and note they return the full matching set. · *`b.dataAct` surface list matches the real methods* — The module surface listed `userAccessible(...)` and `refuseGatekeeper(...)`, neither of which exists. The real surface is `declareProduct` / `recordUserAccess` / `shareWithThirdParty` / `recordSwitchRequest`, and DMA-gatekeeper refusal (Art 32 §1) is enforced inside `shareWithThirdParty`. The doc now reflects that. · *`b.secCyber.eightKArtifact` documented return shape corrected* — The signature line showed `{ artifact, deadline, audit }`; the function returns `{ artifact, deadline, deadlineBusinessDays }` (there is no `audit` key). The doc now matches. · *`b.compliance.aiAct.transparency` helper names corrected* — The helper summary named a `cspMetaTag(...)` function and a `watermark({ kind })` argument; the real names are `metaTags(...)` and `watermark({ mediaKind })`. Calling the documented names threw. Also corrected: a `b.aiAdverseDecision` illustration showed an ECOA `statutoryDeadlines` shape that didn't match the regime's actual deadlines.
+
+- v0.13.31 (2026-05-28) — **Circuit-breaker onStateChange callback now fires; mcp / vault-aad doc corrections.** b.circuitBreaker documented an `onStateChange` callback (both an option and an `onStateChange(handler)` registration method) plus a state-change payload, but the callback was never invoked — only an observability event fired. The callback is now implemented: it fires on every transition with `{ name, from, to, at }`, the registration method works, and a non-function handler is rejected at construction. The same primitive's docs are corrected to name the real accessor (`getState()`, not `state()`) and drop a never-read `audit` option. Plus two doc-only corrections: b.mcp.toolResult.sanitize described composing b.guardHtml / b.ai.input.classify (it uses built-in detection) and documented a `classifyInput` option it never read; and b.vault.aad's prose said HKDF-SHAKE256 where the derivation is SHAKE256 (the AEAD AAD-binding itself is unchanged and sound). **Fixed:** *`b.circuitBreaker` onStateChange callback is invoked on every transition* — The `onStateChange` option and the `onStateChange(handler)` registration method are now wired: each registered handler is called with `{ name, from, to, at }` on every state transition (closed→open, open→half, half→closed/open), alongside the existing `breaker.state.change` observability event. A non-function `onStateChange` is rejected at construction. Previously the documented callback never fired. The docs are also corrected to name the real state accessor `getState()` (there is a `state` property, so `state()` was never a method) and to drop a never-read `audit` option. · *`b.mcp.toolResult.sanitize` documents its actual detection and options* — The prose said the sanitizer composes `b.guardHtml`'s strict profile and `b.ai.input.classify`; it uses built-in dangerous-HTML and prompt-injection-marker detection. The `@opts` also listed a `classifyInput` override the function never read. The prose now describes the built-in detection and the unwired `classifyInput` option is removed. The fail-closed refusal behavior (default `posture: "refuse"`) is unchanged. · *`b.vault.aad` derivation named correctly (SHAKE256)* — The module prose described the per-binding key derivation as HKDF-SHAKE256; it is SHAKE256 over the vault root concatenated with the binding inputs (no HKDF extract/expand). The AEAD AAD-binding to (table, row, column, schema version) — the file's actual security guarantee — is unchanged and sound; only the KDF name in the doc was wrong.
+
 - v0.13.30 (2026-05-28) — **Doc corrections in the safe-* parsers (defaults, an error code, an example, a status list).** Four documentation corrections in the safe-* input parsers; no code behavior changed. The parsers' enforced limits and controls are unchanged — these align the docs with what the code already does. b.safeMime.parse's documented default transfer-encoding allowlist listed `binary`, which is excluded by default (opt-in per RFC 3030 BINARYMIME). b.safeDecompress documented a refusal code (`output-too-large`) it never emits — an absolute-size bomb surfaces under `decompress-failed`. b.safeSmtp.findDotTerminator's example output was off by one. b.safeIcap's intro status-code summary omitted 404 / 405 / 408 (the detailed block already listed them). **Fixed:** *`b.safeMime.parse` documents the actual default transfer-encoding allowlist* — The `@opts` default listed `7bit/8bit/binary/qp/base64`, but `binary` is deliberately excluded by default (RFC 3030 BINARYMIME is opt-in); the default is `7bit/8bit/quoted-printable/base64`. The doc now matches, so operators don't expect inbound `Content-Transfer-Encoding: binary` parts to pass without opting in. · *`b.safeDecompress` names the real absolute-size-bomb refusal code* — The refusal-posture list documented `safe-decompress/output-too-large` for a bomb-by-absolute-size, but that code is never emitted — zlib's `maxOutputLength` throws before allocation and the failure surfaces as `safe-decompress/decompress-failed`. The doc now names the code an operator branching on the result will actually see (the ratio, output-byte, and compressed-input caps are unchanged and enforced). · *`b.safeSmtp.findDotTerminator` example output corrected* — The example claimed the `\r\n.\r\n` terminator in `"Hello world.\r\n.\r\n"` is at index 13; it is at index 12. The example now shows 12 (the implementation was already correct). · *`b.safeIcap` intro status-code summary lists 404 / 405 / 408* — The intro summary said only `100 / 200 / 204 / 400 / 403 / 5xx` are honored, but the parser also accepts `404 / 405 / 408` (legitimate RFC 3507 §4.3.3 codes, already listed in the detailed `parse` block). The intro summary now matches.
 
 - v0.13.29 (2026-05-28) — **Doc corrections: AI Act disclosure kind values, SQS queue model, age-gate coupling.** Documentation corrections. The most actionable: b.middleware.aiActDisclosure's @opts listed two EU AI Act transparency `kind` values (`deepfake` and `synthetic-content`) that the middleware does not accept, so they threw at construction; the accepted values use the hyphenated Art. 50 spellings (e.g. `deep-fake`) and include a text-public-interest variant the enum omitted — an operator copying the documented values crashed a compliance middleware at boot. The b.queue docs implied the SQS backend is driven by the generic b.queue.consume loop like local/redis; SQS is actually an SQS-native adapter (complete/fail by message receipt handle, server-side redrive) driven directly, and the docs now say so. b.middleware.ageGate's `requireAge` 451 floor is documented as taking effect only alongside `consentRequired` (it was silently inert without it). Plus a compose-pipeline @since and a flag-context @related correction. No code behavior changed. **Fixed:** *`b.middleware.aiActDisclosure` documents the accepted `kind` values* — The `@opts` listed `kind` as `ai-interaction | deepfake | emotion-recognition | biometric-categorisation | synthetic-content`. Two of those — `deepfake` and `synthetic-content` — are not accepted and threw at construction; the EU AI Act Art. 50 values use hyphenated spellings (e.g. `deep-fake`, the generated-content variant) and include `ai-text-public-interest`, which the documented enum omitted. The `@opts` now lists the full set the middleware accepts. · *`b.queue` SQS backend documented as SQS-native, not consume-driven* — The module docs implied the `sqs` backend is interchangeable with `local`/`redis` under the generic `b.queue.consume` loop. SQS is an SQS-native adapter: `complete` / `fail` act on the message's `receiptHandle` (returned by `lease()`, threaded back by the caller), and DLQ + visibility-expiry are handled server-side by the queue's RedrivePolicy. The docs now state that `sqs` is driven directly (lease → handle → complete/fail) rather than by `b.queue.consume`, and does not use the framework DLQ / sweep. · *`b.middleware.ageGate` documents the `requireAge` / `consentRequired` coupling* — `requireAge` (the HTTP 451 legal floor) is evaluated within the consent classification, so it takes effect only when `consentRequired` is also set — `requireAge` alone, with `consentRequired: null`, never classifies a request as below-threshold and the 451 never fires. The `@opts` and prose now state this coupling instead of presenting `requireAge` as a standalone threshold. · *Smaller doc corrections* — `b.middleware.composePipeline`'s `@since` is corrected to 0.9.43 (its actual ship version). `b.middleware.flagContext`'s `@related` pointed at a non-existent `b.flagClient.getBoolean`; it now references `b.flag.create`.

package/lib/ai-adverse-decision.js

@@ -47,7 +47,7 @@
  *       requestHumanReview: true,
  *       requestAppeal:      true,
  *       requestData:        true,
- *       statutoryDeadlines: { explanation: "30d", appeal: "60d" }
+ *       statutoryDeadlines: { explanation: "30d", humanReview: null, appeal: null }
  *     }
  *   }
  */

package/lib/audit-daily-review.js

@@ -17,8 +17,8 @@
  *   review of activity records), SOX §302/§404 (quarterly self-
  *   attestation), SOC 2 CC7.2 (anomaly identification and response),
  *   GDPR Art. 32 (ongoing security testing/evaluation). When `posture`
- *   is one of `pci-dss` / `hipaa` / `sox` / `soc2`, a `notify`
- *   callback is mandatory at create-time — the regulators all demand
+ *   is one of `pci-dss` / `hipaa` / `sox` / `sox-404` / `soc2`, a
+ *   `notify` callback is mandatory at create-time — the regulators all demand
  *   a follow-up channel.
  *
  *   Severity classification: `denied` / `failure` outcomes default to
@@ -65,7 +65,7 @@ var CRITICAL_PATTERNS = [
   /^ato\.killSwitch\.tripped/,
 ];
 
-var POSTURES_REQUIRING_NOTIFY = ["pci-dss", "hipaa", "sox", "soc2"];
+var POSTURES_REQUIRING_NOTIFY = ["pci-dss", "hipaa", "sox", "sox-404", "soc2"];
 
 function _defaultClassify(event) {
   if (!event || typeof event !== "object" || typeof event.action !== "string") {

package/lib/circuit-breaker.js

@@ -36,8 +36,10 @@ var retryHelper = require("./retry");
  * Build a circuit-breaker. Returns a CircuitBreaker instance with
  * `wrap(fn)` (executes `fn` if the breaker is closed; throws an
  * `Error` with `code: "CIRCUIT_OPEN"` + `isObjectStoreError: true` +
- * `permanent: false` when open), `state()`, `reset()`, and
- * `onStateChange(handler)` listener registration. Pass-through
+ * `permanent: false` when open), `getState()`, `reset()`, and
+ * `onStateChange(handler)` listener registration (the handler, and the
+ * `onStateChange` opt, receive `{ name, from, to, at }` on every
+ * transition). Pass-through
  * factory: identical instance shape to `b.retry.CircuitBreaker`,
  * with the framework's `create(opts)` vocabulary.
  *
@@ -53,8 +55,8 @@ var retryHelper = require("./retry");
  *   failureThreshold: number,    // failures in the closed state before opening
  *   cooldownMs:       number,    // milliseconds the breaker stays open before probing
  *   successThreshold: number,    // probe successes required to close from half-open
- *   audit:            Object,    // optional b.audit instance for state-change emission
- *   onStateChange:    Function,  // ({ name, from, to, at }) → void
+ *   onStateChange:    Function,  // ({ name, from, to, at }) → void; also emits the
+ *                                //   `breaker.state.change` observability event
  *
  * @example
  *   var cb = b.circuitBreaker.create({

package/lib/compliance-ai-act-transparency.js

@@ -31,8 +31,8 @@
  * The framework provides:
  *
  *   - banner({ kind })           → builder for the standard disclosure banner
- *   - watermark({ kind, ... })   → builder for content-marking tags
- *   - cspMetaTag({ ... })        → meta tag pair for HTML pages
+ *   - watermark({ mediaKind, ... }) → builder for content-marking tags
+ *   - metaTags({ ... })          → meta tag pair for HTML pages
  *   - jsonLdDisclosure({ ... })  → JSON-LD <script> for structured-data emit
  *   - C2pa-stub                  → operator-feeds-claims pattern for
  *                                  C2PA Content Credentials integration

package/lib/compliance.js

@@ -1407,14 +1407,11 @@ function postureDefault(posture, key) {
  *
  * @example
  *   b.compliance.posturesByDomain("privacy");
- *   // → ["ccpa", "gdpr", "lgpd-br", "pipl-cn", "appi-jp",
- *   //    "pdpa-sg", "pipeda-ca", "uk-gdpr"]
+ *   // → ["ccpa", "gdpr", "lgpd-br", ...] — every posture whose
+ *   //    domain is "privacy" (the full set grows as regimes are added)
  *
  *   b.compliance.posturesByDomain("health");
- *   // → ["hipaa", "wmhmda"]
- *
- *   b.compliance.posturesByDomain("payment");
- *   // → ["pci-dss"]
+ *   // → ["hipaa", "wmhmda", ...] — every "health"-domain posture
  *
  *   b.compliance.posturesByDomain("not-a-domain");
  *   // → []
@@ -1450,13 +1447,14 @@ function posturesByDomain(domain) {
  *
  * @example
  *   b.compliance.posturesByJurisdiction("EU");
- *   // → ["gdpr", "dora", "nis2", "cra", "ai-act"]
+ *   // → ["gdpr", "dora", "nis2", ...] — every EU-jurisdiction posture
+ *   //    (the full set grows as regimes are added)
  *
  *   b.compliance.posturesByJurisdiction("US");
- *   // → ["hipaa", "soc2", "sox"]
+ *   // → ["hipaa", "soc2", "sox", ...] — every US-jurisdiction posture
  *
  *   b.compliance.posturesByJurisdiction("US-CA");
- *   // → ["ccpa"]
+ *   // → ["ccpa", ...] — every US-CA (California) posture
  *
  *   b.compliance.posturesByJurisdiction("XX");
  *   // → []

package/lib/data-act.js

@@ -20,8 +20,9 @@
  *
  *     - Art 4 §1 — let the user access "readily available product
  *       data" generated by their use of the connected product.
- *       `b.dataAct.userAccessible(productId, userId)` returns the
- *       operator-supplied data slice.
+ *       `b.dataAct.recordUserAccess({ productId, userId, dataSlice })`
+ *       records the operator-supplied data slice for the regulator
+ *       record.
  *     - Art 5 §1 — share that data with a third-party data
  *       recipient on the user's request, "without undue delay,
  *       free of charge to the user, of the same quality as is
@@ -46,7 +47,7 @@
  *     b.dataAct.declareProduct({ productId, dataHolder, ... })
  *     b.dataAct.recordUserAccess({ productId, userId, dataSlice, ... })
  *     b.dataAct.shareWithThirdParty({ productId, userId, recipient, scope })
- *     b.dataAct.refuseGatekeeper({ recipient })
+ *       — refuses a DMA-gatekeeper recipient per Art 32 §1
  *     b.dataAct.recordSwitchRequest({ customerId, targetProvider, dataSlices })
  *
  *   The framework does NOT host the connected-product data itself;

package/lib/mcp.js

@@ -399,10 +399,10 @@ function serverGuard(opts) {
  * exfiltration endpoints. The framework's defense:
  *
  *   - Strip / refuse executable HTML (`<script>` / `<iframe>` /
- *     `javascript:` URLs) — composes b.guardHtml's strict profile
+ *     `javascript:` URLs) via built-in dangerous-HTML detection
  *   - Refuse known prompt-injection markers ("ignore previous
  *     instructions", "system: you are now ...", role-claim prefixes)
- *     — composes b.ai.input.classify
+ *     via a built-in injection-marker matcher
  *   - Cap text length so a tool can't blow the host's context window
  *     out from under it
  *   - Refuse content with `image_url` / `audio_url` / `resource_link`
@@ -418,7 +418,6 @@ function serverGuard(opts) {
  *     posture?:        "refuse" | "sanitize" | "audit-only",  // default "refuse"
  *     maxTextBytes?:   number,    // default 64 KiB per content block
  *     allowedHosts?:   string[],  // for image/audio/resource_link refs
- *     classifyInput?:  fn(text)→{verdict, score} | null,      // default b.ai.input.classify
  *   }
  *
  * @example

package/lib/retry.js

@@ -187,6 +187,10 @@ function _validateBreakerOpts(name, opts) {
     throw new TypeError("retry.CircuitBreaker: successThreshold must be a positive integer, got " +
       typeof opts.successThreshold + " " + JSON.stringify(opts.successThreshold));
   }
+  if (opts.onStateChange != null && typeof opts.onStateChange !== "function") {
+    throw new TypeError("retry.CircuitBreaker: onStateChange must be a function, got " +
+      typeof opts.onStateChange);
+  }
 }
 
 // ---- Public surface ----
@@ -381,6 +385,19 @@ class CircuitBreaker {
     this.consecutiveFailures = 0;
     this.consecutiveSuccesses = 0;
     this.openedAt = 0;
+    this._stateListeners = [];
+    if (typeof merged.onStateChange === "function") this._stateListeners.push(merged.onStateChange);
+  }
+
+  // Register a state-change listener. Called with { name, from, to, at }
+  // on every transition (same payload the constructor's onStateChange
+  // opt receives). Returns this for chaining.
+  onStateChange(handler) {
+    if (typeof handler !== "function") {
+      throw new TypeError("retry.CircuitBreaker.onStateChange: handler must be a function, got " + typeof handler);
+    }
+    this._stateListeners.push(handler);
+    return this;
   }
 
   // Wrap an async function. The breaker observes outcomes and may fail-fast.
@@ -415,7 +432,16 @@ class CircuitBreaker {
   _transition(from, to) {
     if (from === to) return;
     this.state = to;
+    var at = Date.now();
     _emitEvent("breaker.state.change", 1, { name: this.name, from: from, to: to });
+    if (this._stateListeners.length > 0) {
+      var payload = { name: this.name, from: from, to: to, at: at };
+      for (var i = 0; i < this._stateListeners.length; i++) {
+        // Best-effort: a throwing listener must not derail the breaker's
+        // own state machine (the transition has already been applied).
+        try { this._stateListeners[i](payload); } catch (_e) { /* drop-silent */ }
+      }
+    }
   }
 
   _onSuccess() {

package/lib/sec-cyber.js

@@ -32,7 +32,7 @@
  *
  * Public API:
  *
- *   b.secCyber.eightKArtifact(opts) -> { artifact, deadline, audit }
+ *   b.secCyber.eightKArtifact(opts) -> { artifact, deadline, deadlineBusinessDays }
  *     opts:
  *       incidentId:        operator-supplied incident reference (string).
  *       registrant:        { name, cik, filer }

package/lib/vault-aad.js

@@ -35,8 +35,8 @@
  *   .isAadSealed(value) → boolean
  *
  * Per the framework's security-first stance:
- *   - Symmetric key derivation uses HKDF-SHAKE256 (matching the
- *     vault's KDF) over the vault root key concatenated with the
+ *   - Symmetric key derivation uses SHAKE256 (matching the vault's
+ *     KDF) over the vault root key concatenated with the
  *     canonicalized AAD.
  *   - AEAD: XChaCha20-Poly1305 with the AAD threaded into the tag.
  *   - 24-byte nonce, generated fresh per-seal via

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.30",
+  "version": "0.13.32",
   "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:1f064530-435e-44b8-9aad-0b35cd7d93b0",
+  "serialNumber": "urn:uuid:14f840f1-29a7-4656-93d0-e5fa6ece6ae2",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T00:56:19.365Z",
+    "timestamp": "2026-05-29T02:13:04.485Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.30",
+      "bom-ref": "@blamejs/core@0.13.32",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.30",
+      "version": "0.13.32",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.30",
+      "purl": "pkg:npm/%40blamejs/core@0.13.32",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.30",
+      "ref": "@blamejs/core@0.13.32",
       "dependsOn": []
     }
   ]