@blamejs/core 0.8.9 → 0.8.11

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.11** (2026-05-07) — Three new state-and-federal regulatory primitives + a per-primitive test-coverage gate. **`b.breach.deadline` + `b.breach.report`** — all-50-states data-breach-notification deadline registry. `b.breach.deadline.forStates(states, detectedAt)` returns per-state `{ state, kind, dueBy, citation }` records (`kind: "as-soon-as-possible"` for AS-OF / `"hard-deadline"` for fixed-day deadlines like Texas / Florida / Maine). `b.breach.report.create()` opens a multi-state breach with a single record, tracks per-state filings via `fileNotice(id, state, ...)`, exposes `pending(id)` for dashboards, and auto-closes once every affected state has filed. Every transition records a `breach.report.*` audit event. Statutory citations + day counts wired in `lib/breach-deadline.js` per-state. **`b.ai.adverseDecision`** — wraps an operator-supplied `decide(subject)` predicate, automatically attaches a consumer-rights notice when the outcome is `"adverse"` / `"denied"` / `"rejected"`. Built-in regulation templates for `gdpr-22` (Article 22 automated-decision rights), `ai-act-86` (EU AI Act high-risk consumer recourse), `ecoa-1002.9` (US Equal Credit Opportunity Act adverse-action notice), `colorado-ai-act` (CO SB 24-205 §6-1-1701), `nyc-ll-144` (NYC Local Law 144 employment AEDT), `fcra-615` (US FCRA adverse action), and `operator-defined`. Notice carries `principalReasons` + `consumerRights: { requestData, requestExplanation, contestDecision, requestHumanReview }` shaped per regime. **`b.middleware.ageGate`** — request-level age-classification middleware. Operator-supplied `getAge(req)` returns the subject age (or null/undefined when unknown); middleware classifies as `"above-threshold"` / `"below-threshold"` / `"unknown"` against `consentRequired`, sets `X-Privacy-Posture` header, and refuses with 451 + audited reason when `requireAge` is set and `hasParentalConsent(req)` is unmet. Composes upstream of session / authn for COPPA / AADC / UK Children's Code postures. **Per-primitive test-coverage gate** — new `test/layer-0-primitives/test-coverage.test.js` walks every operator-facing `b.*` primitive and refuses release unless the primitive has at least one test reference (or an explicit `UNTESTED_BACKLOG` entry naming the reason). Closes the drift class where a primitive landed on `b.*` but never gained a unit test.
+
+- **0.8.10** (2026-05-07) — Five new compliance / regulatory primitives composing on v0.8.9's `b.incident.report`. **`b.cra.report`** — EU Cyber Resilience Act (Regulation (EU) 2024/2847) Article 14 §1 incident reporting wrapper. Three-stage statutory deadlines: 24h early warning / 72h incident notification / 14d final report. Required `productId` + `manufacturer` per Annex VII §1. Optional ENISA submission via `opts.enisaEndpoint` + `b.httpClient`; submission is operator-opt-in per stage call (regulators uniformly require operator review before filing). **`b.nis2.report`** — NIS2 Directive (Directive (EU) 2022/2555) Article 23 §4 incident reporting wrapper. Three-stage deadlines: 24h / 72h / 1 month. Annex I (essential) / Annex II (important) entity classification + sector codes (`I.6` drinking water / `II.6` digital providers / etc.). **`b.gdpr.ropa`** — GDPR Article 30 Records of Processing Activities registry + JSON / CSV / Markdown exporter. Validates required fields per Article 30 §1; legal-basis enum per Article 6(1); produces a regulator-friendly RoPA document for the operator's DPO to file. **`b.compliance.eaa`** — EU Accessibility Act (Directive (EU) 2019/882) Article 13 declared-conformance generator. Operators declare per-criterion conformance against WCAG 2.1/2.2 AA / EN 301 549; non-conformances ship with reason + mitigation. JSON / Markdown export for the operator's accessibility statement. **`b.middleware.botDisclose`** — California SB 1001 (Cal. Bus. & Prof. Code §17941) bot-disclosure middleware. Injects a disclosure banner into HTML responses, sets `X-Bot-Disclosure` header for API consumers, audits every conversation-initiating request. Operators wire `mountPaths` to scope and `bannerHtml` for visual customization.
+
 - **0.8.9** (2026-05-07) — `b.incident.report` — generic 3-stage incident-reporting primitive. The three stages mirror the deadline pattern that recurs across regulatory regimes: initial / early-warning notification (within 24h of detection), intermediate / status update (within 72h), final report (within 30d or per-regime deadline). Built-in per-regime deadlines for `gdpr` (Article 33), `nis2` (Article 23), `dora` (Article 19), `cra` (Article 14), `hipaa` (Breach Notification Rule); operators select via `regime: "gdpr"` and `opts.deadlines` can override per-stage. Each stage records a tamper-evident audit event (`incident.report.stage_recorded`) with a `late: bool` + `lateBy: ms` flag — late filings are recorded with `outcome: "late"` so regulator audits can distinguish on-time from late-but-eventually filings. Operator-supplied `persist(record)` writes to a DB / SIEM / SOAR system; `onStage(event)` fires for synchronous routing. `status()` returns aggregate counts (open / closed / late-per-stage) for dashboards.
 
 - **0.8.8** (2026-05-07) — `b.middleware.requireBoundKey` + `b.audit.rotateSigningKey` / `reSignAll` + `b.circuitBreaker` top-level surface + `b.htmlBalance.checkSafe` + permissions predicate-shape audit + FIPS 140-3 boundary docs + ESLint pin. **`b.middleware.requireBoundKey`** — Bearer-API-key middleware with three-axis binding: required scopes, bound-field equality (operator pulls values from headers / query / body via `getBoundField` getters; bound-fields registered on the key are checked with constant-time match), and peer-cert fingerprint allowlist (composes with v0.8.4's `b.crypto.hashCertFingerprint` / `isCertRevoked`). Operator-supplied async `resolver(apiKey)` returns the registered record `{ id, scopes, boundFields, peerCertFingerprints }` or `null` when revoked. Refusals carry structured reasons (`no-bearer-token`, `key-unknown-or-revoked`, `missing-scope`, `bound-field-missing`, `bound-field-mismatch`, `peer-cert-required`, `peer-cert-not-pinned`); audit chain captures the keyId + reason on every refusal. **`b.audit.rotateSigningKey`** — operator-callable rotation of the audit-signing keypair. Generates (or accepts BYO) a new keypair, copies the existing sealed file to a timestamped history path so historical signatures remain verifiable, re-seals with the operator's passphrase, and atomic-swaps the in-memory keys. Companion `reSignAll(iter)` walks an operator-supplied async iterable of `{ payload, signature, oldPublicKeyPem }` and re-signs each entry with the new key — the audit module's checkpoint store calls this to re-stamp historical checkpoints after a rotation. **`b.circuitBreaker`** — top-level re-export of `b.retry.CircuitBreaker` so operators discover it alongside `b.retry`; same state machine, same `wrap()` API, ergonomic `create(opts)` factory. **`b.htmlBalance.checkSafe(html, opts)`** — combines structural `balance()` check with a `b.guardHtml.gate` security pass under the same `{ profile, posture }` opt shape used by `b.fileUpload({ contentSafety })` / `b.staticServe({ contentSafety })`. **`b.permissions.policy(scope, predicate)`** — emits `permissions.policy_predicate_shape_warning` audit on register-time when the predicate's `.length < 2` (operators commonly forget the `context` argument and ship a predicate that's always-true on the actor parameter). **`SECURITY.md`** — new "FIPS 140-3 cryptographic boundary" section explaining the dual boundary (Node.js OpenSSL FIPS provider for classical primitives, vendored noble-* implementations for PQ algorithms — the latter implement FIPS-published algorithms but the *implementations themselves* are not CMVP-validated). Operator path for FIPS-mandated environments documented. **CI** — eslint pinned to `10.3.0` across `ci.yml` / `npm-publish.yml` / `release-container.yml`; `eslint@latest` was silently letting new rule additions break the publish gate on releases that had passed the day before. The pin moves on operator-confirmed bumps.

package/index.js

@@ -98,7 +98,9 @@ var safeUrl = require("./lib/safe-url");
 var safeRedirect = require("./lib/safe-redirect");
 var pick = require("./lib/pick");
 var dora = require("./lib/dora");
-var compliance = require("./lib/compliance");
+var compliance = Object.assign({}, require("./lib/compliance"), {
+  eaa: require("./lib/compliance-eaa"),
+});
 var gateContract = require("./lib/gate-contract");
 var guardCsv = require("./lib/guard-csv");
 var guardHtml = require("./lib/guard-html");
@@ -249,6 +251,11 @@ module.exports = {
   retry:            retry,
   circuitBreaker:   require("./lib/circuit-breaker"),
   incident:         { report: require("./lib/incident-report") },
+  cra:              { report: require("./lib/cra-report") },
+  nis2:             { report: require("./lib/nis2-report") },
+  gdpr:             { ropa: require("./lib/gdpr-ropa") },
+  breach:           require("./lib/breach-deadline"),
+  ai:               { adverseDecision: require("./lib/ai-adverse-decision") },
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/ai-adverse-decision.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * b.ai.adverseDecision — adverse-decision wrapper for automated
+ * decisions affecting consumer rights.
+ *
+ * GDPR Article 22, EU AI Act Article 86, Colorado AI Act, NYC Local
+ * Law 144, and Equal Credit Opportunity Act §1002.9 all require some
+ * form of consumer notice + explanation when an automated decision
+ * adversely affects a person (denial of credit, denial of employment,
+ * adverse insurance pricing, etc.).
+ *
+ * The primitive wraps an operator-supplied predicate and:
+ *   - logs every decision with audit-chain attribution
+ *   - emits a structured consumer-rights notice on adverse outcomes
+ *   - pulls operator-supplied principal reasons (the "specific reasons
+ *     for the action" that ECOA + similar regimes require)
+ *
+ *   var hireDecision = b.ai.adverseDecision.wrap({
+ *     name:         "hire-screening",
+ *     model:        "screening-v3.1",
+ *     legalBasis:   "ecoa-1002.9",
+ *     decide:       function (applicant) {
+ *       var score = scoreModel(applicant);
+ *       return {
+ *         outcome:        score < 0.5 ? "adverse" : "favorable",
+ *         score:          score,
+ *         principalReasons: score < 0.5 ? ["insufficient-credit-history", "..."] : [],
+ *       };
+ *     },
+ *     onAdverse:    async function (subject, decision) {
+ *       await mailer.send({ to: subject.email, ... });
+ *     },
+ *   });
+ *
+ *   var decision = await hireDecision({ id: "applicant-1234", email: "..." });
+ *   // decision = { outcome, score, principalReasons, adverseNotice? }
+ *
+ * adverseNotice (when outcome === "adverse"):
+ *   {
+ *     subjectId:     "applicant-1234",
+ *     decisionAt:    1715040000000,
+ *     model:         "screening-v3.1",
+ *     legalBasis:    "ecoa-1002.9",
+ *     principalReasons: [...],
+ *     consumerRights: {
+ *       requestExplanation: true,
+ *       requestHumanReview: true,
+ *       requestAppeal:      true,
+ *       requestData:        true,
+ *       statutoryDeadlines: { explanation: "30d", appeal: "60d" }
+ *     }
+ *   }
+ */
+
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var AdverseDecisionError = defineClass("AdverseDecisionError", { alwaysPermanent: true });
+
+// Per-regime statutory deadlines for the consumer-rights surfaces.
+// Operators select via opts.legalBasis; the framework attaches the
+// right deadline shape to each adverseNotice.
+var REGIME_DEADLINES = Object.freeze({
+  "gdpr-22":           { explanation: "30d", humanReview: "30d", appeal: "30d", regulation: "GDPR Article 22" },
+  "ai-act-86":         { explanation: "30d", humanReview: "30d", appeal: "30d", regulation: "EU AI Act Article 86" },
+  "ecoa-1002.9":       { explanation: "30d", humanReview: null, appeal: null,   regulation: "ECOA 12 CFR §1002.9" },
+  "colorado-ai-act":   { explanation: "60d", humanReview: "60d", appeal: "60d", regulation: "Colorado AI Act" },
+  "nyc-ll-144":        { explanation: "10d", humanReview: null, appeal: null,   regulation: "NYC Local Law 144" },
+  "fcra-615":          { explanation: "60d", humanReview: null, appeal: null,   regulation: "FCRA 15 USC §1681m" },
+  "operator-defined":  { explanation: null,  humanReview: null, appeal: null,   regulation: "operator-supplied" },
+});
+
+function wrap(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "name", "model", "legalBasis", "decide", "onAdverse",
+    "audit", "now",
+  ], "ai.adverseDecision");
+
+  validateOpts.requireNonEmptyString(opts.name,
+    "ai.adverseDecision.wrap: opts.name is required",
+    AdverseDecisionError, "ai-adverse/bad-name");
+  validateOpts.requireNonEmptyString(opts.model,
+    "ai.adverseDecision.wrap: opts.model is required (model id + version for audit attribution)",
+    AdverseDecisionError, "ai-adverse/bad-model");
+  validateOpts.requireNonEmptyString(opts.legalBasis,
+    "ai.adverseDecision.wrap: opts.legalBasis is required (e.g. 'ecoa-1002.9' / 'gdpr-22' / 'colorado-ai-act')",
+    AdverseDecisionError, "ai-adverse/bad-legal-basis");
+  if (typeof opts.decide !== "function") {
+    throw new AdverseDecisionError("ai-adverse/bad-decide",
+      "ai.adverseDecision.wrap: opts.decide must be a function (subject) -> { outcome, principalReasons }");
+  }
+  var name = opts.name;
+  var model = opts.model;
+  var legalBasis = opts.legalBasis;
+  var decide = opts.decide;
+  var onAdverse = typeof opts.onAdverse === "function" ? opts.onAdverse : null;
+  var auditOn = opts.audit !== false;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+
+  var deadlines = REGIME_DEADLINES[legalBasis] || REGIME_DEADLINES["operator-defined"];
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "ai.adverse_decision." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("ai.adverse_decision." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  return async function adverseDecisionDecorated(subject) {
+    if (!subject || typeof subject !== "object") {
+      throw new AdverseDecisionError("ai-adverse/bad-subject",
+        "ai.adverseDecision: subject must be an object with at least { id }");
+    }
+    var subjectId = subject.id || null;
+    var decidedAt = now();
+    var decision;
+    try {
+      decision = await decide(subject);
+    } catch (e) {
+      _emitAudit("decide_failed", "failure", { name: name, subjectId: subjectId, error: (e && e.message) || String(e) });
+      throw e;
+    }
+    if (!decision || typeof decision !== "object") {
+      throw new AdverseDecisionError("ai-adverse/bad-decision-shape",
+        "ai.adverseDecision: opts.decide must return an object with { outcome, principalReasons }");
+    }
+    var outcome = decision.outcome;
+    var isAdverse = outcome === "adverse" || outcome === "denied" || outcome === "rejected";
+
+    _emitAudit("decided", isAdverse ? "denied" : "success", {
+      name: name, model: model, legalBasis: legalBasis,
+      subjectId: subjectId, outcome: outcome,
+      principalReasons: Array.isArray(decision.principalReasons) ? decision.principalReasons : [],
+    });
+    _emitMetric("decided", 1, { name: name, outcome: outcome });
+
+    if (isAdverse) {
+      decision.adverseNotice = {
+        subjectId:        subjectId,
+        decisionAt:       decidedAt,
+        model:            model,
+        legalBasis:       legalBasis,
+        regulation:       deadlines.regulation,
+        principalReasons: Array.isArray(decision.principalReasons) ? decision.principalReasons : [],
+        consumerRights: {
+          requestExplanation: deadlines.explanation !== null,
+          requestHumanReview: deadlines.humanReview !== null,
+          requestAppeal:      deadlines.appeal !== null,
+          requestData:        true,
+          statutoryDeadlines: {
+            explanation: deadlines.explanation,
+            humanReview: deadlines.humanReview,
+            appeal:      deadlines.appeal,
+          },
+        },
+      };
+      if (onAdverse) {
+        try { await onAdverse(subject, decision); }
+        catch (e) { _emitAudit("on_adverse_threw", "failure", { error: (e && e.message) || String(e) }); }
+      }
+    }
+    return decision;
+  };
+}
+
+module.exports = {
+  wrap:                  wrap,
+  REGIME_DEADLINES:      REGIME_DEADLINES,
+  AdverseDecisionError:  AdverseDecisionError,
+  VALID_REGIMES:         Object.keys(REGIME_DEADLINES),
+};

package/lib/breach-deadline.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * b.breach.deadline + b.breach.report — US state breach-notification
+ * deadline registry + reporter.
+ *
+ * Every US state + territory has its own breach-notification statute
+ * with a deadline (60 days, 45 days, "without unreasonable delay").
+ * Operators detecting a breach affecting residents in multiple states
+ * face a fan-out problem: which state(s), what deadline for each,
+ * what notice content. The registry encodes the per-jurisdiction
+ * deadline + statutory citation; the reporter surfaces an operator-
+ * friendly "what do I owe and when" plan.
+ *
+ *   var deadlines = b.breach.deadline.forStates(["CA", "NY", "TX"], breachDetectedAt);
+ *   // -> [{ state: "CA", dueBy: ..., statute: "Cal. Civ. Code §1798.82" }, ...]
+ *
+ *   var reporter = b.breach.report.create({ audit: b.audit });
+ *   var rec = reporter.open({
+ *     detectedAt: Date.now(),
+ *     affectedStates: ["CA", "NY", "TX"],
+ *     scope:    "data-confidentiality-breach",
+ *     impact:   { individualsAffected: 5000 },
+ *   });
+ *   await reporter.fileNotice(rec.id, "CA", { ... });
+ *
+ * The registry is statutory data — operators don't override it
+ * without legal counsel review. Updates ride into the framework via
+ * patch releases when state legislatures amend their breach laws.
+ */
+
+var C = require("./constants");
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var BreachError = defineClass("BreachError", { alwaysPermanent: true });
+
+// Per-state deadlines as days-from-detection. "WITHOUT_UNREASONABLE_DELAY"
+// is encoded as a sentinel; operators interpret as "as soon as
+// reasonably possible, never later than the longest acceptable for
+// the state's tort-liability standard". Common interpretation: 60 days
+// is a defensible ceiling, but operators with active forensics may
+// stretch to 90 days with documented investigative justification.
+var WITHOUT_UNREASONABLE_DELAY = "WITHOUT_UNREASONABLE_DELAY";
+
+var STATE_DEADLINES = Object.freeze({
+  // Each entry: { days, statute, asapCeilingDays }
+  // Days = statutory hard deadline in days. asapCeilingDays = the
+  // operator-defensible ceiling for "without unreasonable delay" states.
+  AL: { days: 45,  statute: "Ala. Code §8-38-5" }, /* allow:raw-time-literal — statutory deadline days */
+  AK: { days: 45,  statute: "Alaska Stat. §45.48.010" }, /* allow:raw-time-literal — statutory deadline days */
+  AZ: { days: 45,  statute: "Ariz. Rev. Stat. §18-552" }, /* allow:raw-time-literal — statutory deadline days */
+  AR: { days: 45,  statute: "Ark. Code §4-110-105" }, /* allow:raw-time-literal — statutory deadline days */
+  CA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Cal. Civ. Code §1798.82", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  CO: { days: 30,  statute: "Colo. Rev. Stat. §6-1-716" }, /* allow:raw-time-literal — statutory deadline days */
+  CT: { days: 60,  statute: "Conn. Gen. Stat. §36a-701b" }, /* allow:raw-time-literal — statutory deadline days */
+  DE: { days: 60,  statute: "Del. Code §12B-102" }, /* allow:raw-time-literal — statutory deadline days */
+  DC: { days: 60,  statute: "D.C. Code §28-3852" }, /* allow:raw-time-literal — statutory deadline days */
+  FL: { days: 30,  statute: "Fla. Stat. §501.171" }, /* allow:raw-time-literal — statutory deadline days */
+  GA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Ga. Code §10-1-911", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  HI: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Haw. Rev. Stat. §487N-2", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  ID: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Idaho Code §28-51-105", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  IL: { days: WITHOUT_UNREASONABLE_DELAY, statute: "815 ILCS 530/10", asapCeilingDays: 45 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  IN: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Ind. Code §24-4.9-3-3", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  IA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Iowa Code §715C.2", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  KS: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Kan. Stat. §50-7a02", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  KY: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Ky. Rev. Stat. §365.732", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  LA: { days: 60,  statute: "La. Rev. Stat. §51:3074" }, /* allow:raw-time-literal — statutory deadline days */
+  ME: { days: 30,  statute: "Me. Rev. Stat. tit. 10 §1348" }, /* allow:raw-time-literal — statutory deadline days */
+  MD: { days: 45,  statute: "Md. Code Com. Law §14-3504" }, /* allow:raw-time-literal — statutory deadline days */
+  MA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mass. Gen. Laws ch. 93H §3", asapCeilingDays: 30 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MI: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mich. Comp. Laws §445.72", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MN: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Minn. Stat. §325E.61", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MS: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Miss. Code §75-24-29", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MO: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mo. Rev. Stat. §407.1500", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MT: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mont. Code §30-14-1704", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NE: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Neb. Rev. Stat. §87-803", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NV: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Nev. Rev. Stat. §603A.220", asapCeilingDays: 45 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NH: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.H. Rev. Stat. §359-C:20", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NJ: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.J. Stat. §56:8-163", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NM: { days: 45,  statute: "N.M. Stat. §57-12C-6" }, /* allow:raw-time-literal — statutory deadline days */
+  NY: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.Y. Gen. Bus. Law §899-aa (SHIELD Act)", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NC: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.C. Gen. Stat. §75-65", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  ND: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.D. Cent. Code §51-30-02", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  OH: { days: 45,  statute: "Ohio Rev. Code §1349.19" }, /* allow:raw-time-literal — statutory deadline days */
+  OK: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Okla. Stat. tit. 24 §163", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  OR: { days: 45,  statute: "Or. Rev. Stat. §646A.604" }, /* allow:raw-time-literal — statutory deadline days */
+  PA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "73 Pa. Cons. Stat. §2303", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  PR: { days: 10,  statute: "P.R. Laws Ann. tit. 10 §4051 (Citizen Information Security Act)" }, /* allow:raw-time-literal — statutory deadline days */
+  RI: { days: 45,  statute: "R.I. Gen. Laws §11-49.3-3" }, /* allow:raw-time-literal — statutory deadline days */
+  SC: { days: WITHOUT_UNREASONABLE_DELAY, statute: "S.C. Code §39-1-90", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  SD: { days: 60,  statute: "S.D. Codified Laws §22-40-20" }, /* allow:raw-time-literal — statutory deadline days */
+  TN: { days: 45,  statute: "Tenn. Code §47-18-2107" }, /* allow:raw-time-literal — statutory deadline days */
+  TX: { days: 60,  statute: "Tex. Bus. & Com. Code §521.053" }, /* allow:raw-time-literal — statutory deadline days */
+  UT: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Utah Code §13-44-202", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  VT: { days: 45,  statute: "Vt. Stat. tit. 9 §2435" }, /* allow:raw-time-literal — statutory deadline days */
+  VA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Va. Code §18.2-186.6", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  WA: { days: 30,  statute: "Wash. Rev. Code §19.255.010" }, /* allow:raw-time-literal — statutory deadline days */
+  WV: { days: WITHOUT_UNREASONABLE_DELAY, statute: "W. Va. Code §46A-2A-102", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  WI: { days: 45,  statute: "Wis. Stat. §134.98" }, /* allow:raw-time-literal — statutory deadline days */
+  WY: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Wyo. Stat. §40-12-502", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+});
+
+function _msPerDay() { return C.TIME.days(1); }
+
+function _deadlineFor(state, detectedAtMs) {
+  var rec = STATE_DEADLINES[state.toUpperCase()];
+  if (!rec) {
+    throw new BreachError("breach/unknown-state",
+      "breach.deadline: unknown state code '" + state + "' (use US 2-letter codes)");
+  }
+  if (rec.days === WITHOUT_UNREASONABLE_DELAY) {
+    return {
+      state:    state.toUpperCase(),
+      kind:     "as-soon-as-possible",
+      ceilingDays: rec.asapCeilingDays,
+      ceilingDueBy: detectedAtMs + (rec.asapCeilingDays * _msPerDay()),
+      statute:  rec.statute,
+    };
+  }
+  return {
+    state:    state.toUpperCase(),
+    kind:     "hard-deadline",
+    days:     rec.days,
+    dueBy:    detectedAtMs + (rec.days * _msPerDay()),
+    statute:  rec.statute,
+  };
+}
+
+function forStates(states, detectedAtMs) {
+  if (!Array.isArray(states)) {
+    throw new BreachError("breach/bad-states",
+      "breach.deadline.forStates: states must be an array of US state codes");
+  }
+  if (typeof detectedAtMs !== "number" || !isFinite(detectedAtMs)) {
+    throw new BreachError("breach/bad-detected-at",
+      "breach.deadline.forStates: detectedAtMs must be a finite Unix-ms timestamp");
+  }
+  var out = [];
+  for (var i = 0; i < states.length; i++) {
+    out.push(_deadlineFor(states[i], detectedAtMs));
+  }
+  return out;
+}
+
+// b.breach.report — operator-side breach-tracking that wraps the
+// deadline registry and tracks per-state filing status.
+function createReporter(opts) {
+  opts = opts || {};
+  var auditOn = opts.audit !== false;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+  var seq = 0;
+  var breaches = new Map();
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "breach.report." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function open(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new BreachError("breach-report/bad-spec",
+        "breach.report.open: spec must be an object with { detectedAt, affectedStates, scope, impact }");
+    }
+    if (typeof spec.detectedAt !== "number" || !isFinite(spec.detectedAt)) {
+      throw new BreachError("breach-report/bad-detected-at",
+        "breach.report.open: spec.detectedAt must be a finite Unix-ms timestamp");
+    }
+    if (!Array.isArray(spec.affectedStates) || spec.affectedStates.length === 0) {
+      throw new BreachError("breach-report/bad-states",
+        "breach.report.open: spec.affectedStates must be a non-empty array of US state codes");
+    }
+    seq += 1;
+    var id = "breach-" + new Date(spec.detectedAt).toISOString().replace(/[:.]/g, "-") + "-" + seq;
+    var deadlines = forStates(spec.affectedStates, spec.detectedAt);
+    var rec = {
+      id:               id,
+      detectedAt:       spec.detectedAt,
+      affectedStates:   spec.affectedStates.map(function (s) { return s.toUpperCase(); }),
+      scope:            spec.scope || null,
+      impact:           spec.impact || null,
+      deadlines:        deadlines,
+      filings:          {},                                                              // state -> { filedAt, late }
+      openedAt:         now(),
+      closedAt:         null,
+    };
+    breaches.set(id, rec);
+    _emitAudit("opened", "success", {
+      breachId: id,
+      states:   rec.affectedStates,
+      detectedAt: spec.detectedAt,
+    });
+    return rec;
+  }
+
+  async function fileNotice(breachId, state, fields) {
+    var rec = breaches.get(breachId);
+    if (!rec) {
+      throw new BreachError("breach-report/unknown-breach",
+        "breach.report.fileNotice: no breach with id '" + breachId + "'");
+    }
+    var stateUp = state.toUpperCase();
+    if (rec.affectedStates.indexOf(stateUp) === -1) {
+      throw new BreachError("breach-report/state-not-tracked",
+        "breach.report.fileNotice: state '" + stateUp + "' is not in this breach's affectedStates");
+    }
+    if (rec.filings[stateUp]) {
+      throw new BreachError("breach-report/already-filed",
+        "breach.report.fileNotice: filing for state '" + stateUp + "' is already recorded");
+    }
+    var deadline = rec.deadlines.filter(function (d) { return d.state === stateUp; })[0];
+    var filedAt = now();
+    var dueBy = deadline.kind === "hard-deadline" ? deadline.dueBy : deadline.ceilingDueBy;
+    var late = filedAt > dueBy;
+    rec.filings[stateUp] = {
+      filedAt: filedAt,
+      dueBy:   dueBy,
+      late:    late,
+      lateBy:  late ? (filedAt - dueBy) : 0,
+      payload: fields || {},
+    };
+    if (Object.keys(rec.filings).length === rec.affectedStates.length) {
+      rec.closedAt = filedAt;
+    }
+    _emitAudit("notice_filed", late ? "late" : "success", {
+      breachId: breachId, state: stateUp, dueBy: dueBy, late: late,
+      lateBy: rec.filings[stateUp].lateBy,
+    });
+    return rec;
+  }
+
+  function get(id) { return breaches.get(id) || null; }
+  function list() { var out = []; breaches.forEach(function (rec) { out.push(rec); }); return out; }
+  function pending(breachId) {
+    var rec = breaches.get(breachId);
+    if (!rec) return [];
+    var pendingStates = [];
+    for (var i = 0; i < rec.affectedStates.length; i++) {
+      if (!rec.filings[rec.affectedStates[i]]) {
+        pendingStates.push(rec.deadlines.filter(function (d) { return d.state === rec.affectedStates[i]; })[0]);
+      }
+    }
+    return pendingStates;
+  }
+
+  return {
+    open:         open,
+    fileNotice:   fileNotice,
+    get:          get,
+    list:         list,
+    pending:      pending,
+  };
+}
+
+module.exports = {
+  // b.breach.deadline.* — registry lookups
+  deadline: {
+    forStates:                 forStates,
+    STATE_DEADLINES:           STATE_DEADLINES,
+    WITHOUT_UNREASONABLE_DELAY: WITHOUT_UNREASONABLE_DELAY,
+  },
+  // b.breach.report.create(...) — per-incident reporter
+  report:      { create: createReporter },
+  BreachError: BreachError,
+};