nsauditor-ai 0.2.51 → 0.2.53

package/README.md

@@ -17,6 +17,16 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
+**Latest: CE 0.2.53 + Enterprise 0.46.0 — a documentation release: the PCI DSS claims in this README were wrong.** The Enterprise cycle derived the PCI Customized-Approach eligibility set from PCI DSS v4.0.1 itself rather than from a transcribed list, and this README carried the transcribed one: a stale triple (now **19 covered / 9 partial / 44 OOS across 72**), a retired `MVP-67` density label, an "Appendix E" attribution that names the wrong appendix, and a sampling citation that belongs to Section 6. No scanner change and no plugin change — Community stays at 27 plugins. **npm freezes a README at publish time, which is why a doc-only correction gets a version.**
+is deleted: it validated any reply of at least 48 bytes with a non-null transmit timestamp and nothing
+else — no mode byte, no stratum, no originate echo — so over unauthenticated UDP a datagram of the right
+shape produced a false clean reading, and it measured the SCANNER's own clock rather than your estate.
+It had never been reachable from any shipped entry point.
+RFC 3161 trusted timestamping is untouched, opt-in, and is the capability that answers the question —
+off unless you configure a Time-Stamp Authority, and an outbound call to a third party when you do. On the Community side this cycle changes no behaviour: the
+withdrawn-claim guard over `license --capabilities` descriptions learns the wording the product actually
+published, so the class cannot recur silently here. See [CHANGELOG.md](./CHANGELOG.md).
+
 **The Pro `report` subcommand, over a run record that states its own coverage (CE 0.2.51 / Enterprise 0.44.0).**
 `nsauditor-ai report --from <dir> --format executive|jira` turns a completed scan run into a
 client-facing deliverable — a self-contained, print-ready HTML report a consultant sends to their
@@ -140,7 +150,7 @@ Scan → Analyze → Prioritize → Track → Act
 - **Smart result fusion** — the Result Concluder merges all plugin outputs into a normalized view with OS detection, service fingerprinting, and evidence linking
 - **Structured finding format** — all findings use a common schema with category, severity, evidence, and remediation — enabling consistent SARIF export and MCP integration
 - **AI-powered analysis** — send redacted scan results to OpenAI or Claude (your keys, your choice) for vulnerability assessments and remediation guidance
-- **Risk-scored prioritization (Pro)** — findings carry a composite risk score (CVSS weighted by verification status, with an uplift for initial-access techniques) and a status field, and an operator suppression workflow (accepted-risk / false-positive with expiry) keeps triaged findings out of the report until they expire
+- **Risk-scored prioritization (Pro/Enterprise)** — findings carry a composite risk score (CVSS weighted by verification status, with an uplift for initial-access techniques) and a status field, and an operator suppression workflow (accepted-risk / false-positive with expiry) keeps triaged findings out of the report until they expire
 - **Continuous monitoring (CTEM)** — watch mode rescans on a schedule, diffs against previous results, and fires webhook alerts on changes
 - **MCP integration** — expose scanning tools to AI assistants like Claude Code via Model Context Protocol
 - **CI/CD ready** — SARIF output with `--fail-on` severity gating for pipeline integration
@@ -158,7 +168,7 @@ If you're heading into a **SOC 2, HIPAA, NIST CSF 2.0, PCI DSS, ISO 27001, CIS C
   - **SOC 2** (AICPA TSC 2017) — 10 fully-covered + 4 partial controls
   - **HIPAA Security Rule §164.312** — 7 covered + 3 partial Technical Safeguards; **Zero BAA required** (ePHI never leaves your infrastructure)
   - **NIST CSF 2.0 Core** (NIST CSWP 29, Feb 2024) — 13 covered + 10 partial Subcategories across 106 of CSF 2.0's 107 Subcategories; Subcategory-level mapping (auditor-canonical, not high-level Function/Category claims)
-  - **PCI DSS v4.0.1** (PCI SSC, June 2024 errata; v3.2.1 retired March 31, 2024) — **19 covered + 9 partial + 39 OOS sub-requirements across 67 of ~250 (MVP-67)**; sub-requirement-level mapping for QSA Report on Compliance workflow; Defined-vs-Customized Approach discipline per Appendix E (15 Defined-only sub-requirements enforced at schema layer); CHD Scope operator-attested via CDE Data Flow Diagram per Req 1.2.4; Card-brand AOC enforcement priority view (Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC)
+  - **PCI DSS v4.0.1** (PCI SSC, June 2024 errata; v3.2.1 retired March 31, 2024) — **19 covered + 9 partial + 44 OOS sub-requirements across 72 of ~250**; sub-requirement-level mapping for QSA Report on Compliance workflow; Defined-vs-Customized Approach discipline enforced at the schema layer, derived from the standard rather than from a list: PCI DSS v4.0.1 states ineligibility in each requirement's own Customized Approach Objective cell, not in an appendix, and no sub-requirement mapped here is ineligible; CHD Scope operator-attested via CDE Data Flow Diagram per Req 1.2.4; Card-brand AOC enforcement priority view (Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC)
   - **ISO/IEC 27001:2022** (ISO + IEC, Oct 2022; 2013 edition retired Oct 31, 2025) — **17 covered + 14 partial + 62 OOS across 93 Annex A controls** (the complete Annex A universe); per-Annex-A-code mapping auditor-canonical for ISO/IEC 17021-1 certification body assessors; Statement of Applicability per Clause 6.1.3.d discipline + ISMS Clauses 4-10 OOS-by-design with 7 Major Nonconformity classes
   - **CIS Critical Security Controls v8** (CIS, May 2021; v8.1 errata June 2024) — **17 covered + 23 partial + 113 OOS across 153 Safeguards / 18 Controls**; per-Safeguard mapping with the **Implementation Group cumulative discipline** (IG1=56 cyber-insurance baseline / IG2 cumulative=130 / IG3 cumulative=153); no-certification-body attestation discipline (INPUT to your CSAT / CIS-CAT Pro self-attestation, never "CIS certified"); Cloud Companion Guide v8 shared-responsibility + CIS-Hardened-Image substrate-evidence credit (4.1/4.2/4.6)
   - **GDPR Article 32 (Security of Processing)** (Regulation (EU) 2016/679) — **4 covered + 5 partial + 2 OOS across 11 Art. 32 sub-measure units**; **GDPR Article 32 infrastructure substrate only — NOT GDPR compliance** (GDPR is a 99-article legal regime; Art. 32 security-of-processing is the only article an infrastructure scanner can substrate-evidence; the rest is operator-side, out of scope by design). Four-factor proportionality (substrate *for* your "appropriate to the risk" determination, never an absolute pass/fail); personal-data-scope attestation (pair with your Art. 30 records of processing); **Art. 83(4) lower fine tier** (€10M/2%, not the €20M/4% headline tier); Art. 32(3)/Art. 42 cloud-provider certification-inheritance
@@ -205,7 +215,7 @@ How Marketplace fulfillment works (ZDE and air-gap preserved — no runtime AWS
 | SOC 2 (AICPA TSC 2017) — 10 covered + 4 partial controls | — | — | ✅ |
 | HIPAA Security Rule §164.312 — Zero BAA required | — | — | ✅ |
 | NIST CSF 2.0 Core — Subcategory-level mapping (106 of 107 Subcategories) | — | — | ✅ |
-| PCI DSS v4.0.1 — Sub-requirement-level mapping for QSA RoC (MVP-67) | — | — | ✅ |
+| PCI DSS v4.0.1 — Sub-requirement-level mapping for QSA RoC | — | — | ✅ |
 | ISO/IEC 27001:2022 — per-Annex-A-code mapping + SoA discipline (93 Annex A controls) | — | — | ✅ |
 | CIS Critical Security Controls v8 — per-Safeguard mapping + IG-cumulative discipline (153 Safeguards / 18 Controls) | — | — | ✅ |
 | **GDPR Article 32 (Security of Processing)** — Art. 32 infrastructure substrate (4 covered + 5 partial + 2 OOS / 11 sub-measure units); **not GDPR compliance** · Art. 83(4) lower fine tier | — | — | ✅ |
@@ -411,7 +421,7 @@ Results land in `./out/<host>_<timestamp>/`:
 | — | SOC 2 Compliance Engine | Enterprise | AICPA TSC 2017 mapping (10 covered + 4 partial controls), SHA-256 chain-of-custody, opt-in RFC 3161 timestamps, exercised against a live TSA on both the npm path and the `:0.33.0` container image, and the suppression workflow. (Ed25519 SIGNING of suppressions is reachable from EE 0.35.0 and PROVEN at EE 0.36.0, verified per approver holding **key material**.) |
 | — | **HIPAA Compliance Engine (EE 0.9.0)** | Enterprise | HIPAA Security Rule §164.312 Technical Safeguards mapping (7 covered + 3 partial + 45 OOS within §164.312 + entire §164.308 + entire §164.310). HHS Required/Addressable discipline per control. Same evidence infrastructure as SOC 2 (SHA-256 chain-of-custody; opt-in RFC 3161 timestamps; suppression signing reachable from EE 0.35.0, proven at EE 0.36.0 and verified per approver holding **key material**). Use `--compliance hipaa` or `--compliance soc2,hipaa` for dual-framework reports from a single scan. **Zero BAA required** — Zero Data Exfiltration architecture means ePHI never leaves customer infrastructure. |
 | — | **NIST CSF 2.0 Compliance Engine (EE 0.10.0)** | Enterprise | NIST Cybersecurity Framework 2.0 Core mapping at the auditor-canonical Subcategory level — 13 covered + 10 partial + 83 OOS across 106 of CSF 2.0's 107 Subcategories. Govern function OOS-by-design (GV.SC-04 partial as substrate exception); Respond function OOS-entirely; Implementation Tiers 1-4 OOS as organizational-maturity claims. NIST SP 800-53 Rev. 5 + CIS Critical Security Controls v8 cross-references baked into `informativeReferences`. Use `--compliance nist-csf` or `--compliance soc2,hipaa,nist-csf` for triple-framework reports from a single scan. |
-| — | **PCI DSS v4.0.1 Compliance Engine (EE 0.11.0)** | Enterprise | PCI DSS v4.0.1 (PCI SSC, June 2024 errata; supersedes v4.0 March 2022; v3.2.1 retired March 31, 2024) mapping at the auditor-canonical sub-requirement level for QSA Report on Compliance workflow — **19 covered + 9 partial + 39 OOS across 67 of ~250 sub-requirements (MVP-67 density)** (Req 7.2.2 down-rated covered→partial in EE 0.19.4 — access-by-job-classification is process/HR-gated). Req 12 Information Security Program OOS-by-design entirely. Req 5 anti-malware + Req 9 physical OOS-entirely. **Defined-vs-Customized Approach discipline per Appendix E** — 15 Defined-only sub-requirements enforced at schema layer. **Cardholder Data Environment (CDE) scope operator-attested** via CDE Data Flow Diagram per Req 1.2.4 + Req 12.5.1. **Card-brand AOC enforcement priority view** (Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC). **4 load-bearing schema enrichments** per control: `controlType` + `approachEligibility` + `cloudProviderAttestation` (AWS / Azure / GCP currently-named AOCs) + `cdeScope`. CAO MVP-deferred to EE 0.11.1. Use `--compliance pci-dss` or `--compliance soc2,hipaa,nist-csf,pci-dss` for quad-framework reports from a single scan. |
+| — | **PCI DSS v4.0.1 Compliance Engine (EE 0.11.0)** | Enterprise | PCI DSS v4.0.1 (PCI SSC, June 2024 errata; supersedes v4.0 March 2022; v3.2.1 retired March 31, 2024) mapping at the auditor-canonical sub-requirement level for QSA Report on Compliance workflow — **19 covered + 9 partial + 39 OOS across 67 of ~250 sub-requirements (MVP-67 density)** (Req 7.2.2 down-rated covered→partial in EE 0.19.4 — access-by-job-classification is process/HR-gated). Req 12 Information Security Program OOS-by-design entirely. Req 5 anti-malware + Req 9 physical OOS-entirely. **Defined-vs-Customized Approach discipline per Appendix E** — 15 Defined-only sub-requirements enforced at schema layer. ⚠️ **That doctrine is CORRECTED and the figures above are left as the 0.11.0 record:** PCI DSS v4.0.1 states ineligibility in each requirement's own Customized Approach Objective cell, never in an appendix, and the enumeration this line described was wrong about most of its members. **Cardholder Data Environment (CDE) scope operator-attested** via CDE Data Flow Diagram per Req 1.2.4 + Req 12.5.1. **Card-brand AOC enforcement priority view** (Visa CISP / Mastercard SDP / Amex DSOP / Discover DISC). **4 load-bearing schema enrichments** per control: `controlType` + `approachEligibility` + `cloudProviderAttestation` (AWS / Azure / GCP currently-named AOCs) + `cdeScope`. CAO MVP-deferred to EE 0.11.1. Use `--compliance pci-dss` or `--compliance soc2,hipaa,nist-csf,pci-dss` for quad-framework reports from a single scan. |
 | — | **ISO/IEC 27001:2022 Compliance Engine (EE 0.12.0)** | Enterprise | ISO/IEC 27001:2022 (ISO + IEC, October 2022; 2013 edition retired October 31, 2025) Annex A mapping at the auditor-canonical per-Annex-A-code level for ISO/IEC 17021-1 certification body assessors — **17 covered + 14 partial + 62 OOS across 93 Annex A controls** (the complete Annex A universe across 4 themes: A.5 Organizational 37 + A.6 People 8 + A.7 Physical 14 + A.8 Technological 34). **Statement of Applicability per Clause 6.1.3.d discipline** — engine produces substrate for INCLUDED controls; SoA inclusion/exclusion is operator-side. **ISMS Clauses 4-10 OOS-by-design** with 7 Major Nonconformity classes (absence of internal audit per Clause 9.2 OR management review per Clause 9.3 = auto-fail Stage 2). 11 NEW 2022 controls + 5-attribute taxonomy (cybersecurityConcepts 5 categories, NOT 6 like NIST CSF) + 2013-to-2022 transition discipline + Cloud-Provider Certificate Inheritance Matrix. Use `--compliance iso-27001` or any combination for multi-framework reports from a single scan. |
 | — | **CIS Critical Security Controls v8 Compliance Engine (EE 0.13.0)** | Enterprise | CIS Controls v8 (Center for Internet Security, May 2021; v8.1 errata June 2024) mapping at the per-Safeguard level (the atomic, attestable unit; coverage claimed at the SAFEGUARD level, never the Control level) — **17 covered + 23 partial + 113 OOS across 153 Safeguards / 18 Controls**. **Implementation Group cumulative discipline** — IG1=56 (cyber-insurance baseline; ~50-70% of mid-market policies require IG1 attestation), IG2 cumulative=130, IG3 cumulative=153; smallest-IG-membership tagging (NEVER report IG2 as 74-of-74 in isolation). **No-certification-body attestation discipline** — engine output is INPUT to CSAT / CIS-CAT Pro self-attestation OR a SOC 2 auditor cross-validating CIS scope, never "CIS certified." Cloud Companion Guide v8 shared-responsibility-model boundary + CIS-Hardened-Image substrate-evidence credit (Safeguards 4.1/4.2/4.6) + 5 Security Functions (NOT 6 — no Govern) + 6 Asset Types + MS-ISAC/EI-ISAC/H-ISAC sector baselines + v7.1-to-v8 cross-reference. Use `--compliance cis-v8` or `--compliance soc2,hipaa,nist-csf,pci-dss,iso-27001,cis-v8,gdpr` for hepta-framework reports from a single scan. |
 | — | **GDPR Article 32 Compliance Engine (EE 0.20.0)** | Enterprise | **GDPR Article 32 (Security of Processing)** infrastructure substrate (Regulation (EU) 2016/679) — **4 covered + 5 partial + 2 OOS across 11 Art. 32 sub-measure units** (the 7th framework). **This is GDPR Article 32 infrastructure substrate ONLY — NOT GDPR compliance.** GDPR is a 99-article legal regime; Art. 32 security-of-processing is the only article whose evidence is technical infrastructure state, so the rest of GDPR (lawful basis, consent, DSARs, records of processing, DPIAs, transfers) is operator-side and out of scope by design. **Four-factor proportionality** — Art. 32 measures are "appropriate to the risk" taking into account state-of-the-art / cost / nature-scope-context-purposes / risk; nothing is an absolute pass/fail, the engine produces substrate *for* the operator's determination. **Personal-data-scope attestation** — the scanner reads configuration, not data classification; a finding is an Art. 32 concern only if the resource processes personal data (pair with your Art. 30 records of processing). Controller-vs-processor role applicability + Art. 28 processor agreements. **Art. 83(4) lower fine tier** — Art. 32 infringements cap at €10M or 2% of turnover, NOT the €20M / 4% Art. 83(5) headline tier (which is for the basic principles + data-subject rights). Art. 32(3)/Art. 42 cloud-provider certification-inheritance (ISO 27001 / SOC 2 / C5 / EU Cloud CoC adherence as an element of demonstrable compliance, not a substitute). Use `--compliance gdpr` or any combination for multi-framework reports from a single scan. |
@@ -782,7 +792,7 @@ nsauditor-ai validate
 nsauditor-ai feed bundle --from <dir-of-NVD-feeds> --out <bundle.json.gz> [--kev <f>] [--epss <f>]
 nsauditor-ai feed import --file <feed-or-bundle> [--cache-dir <d>] [--extras-dir <d>] [--append]   # the feeds you downloaded
 nsauditor-ai compliance <attest|suppress|review|renew|keygen|sign-pack|verify-pack>   (Enterprise)
-nsauditor-ai report --from <dir> --format executive|jira [--run <id>] [--brand <brand.json>] [--out <path>] [--allow-partial]   (Pro)
+nsauditor-ai report --from <dir> --format executive|jira [--run <id>] [--brand <brand.json>] [--out <path>] [--allow-partial]   (Pro/Enterprise)
 nsauditor-ai mcp
 nsauditor-ai --help        (or -h, or `help`)
 nsauditor-ai --version     (or -v, or `version`)
@@ -876,7 +886,7 @@ HEALTHCHECK --interval=60s --timeout=5s --start-period=10s --retries=3 \
   CMD nsauditor-ai validate --json | grep -q '"overall": "ok"' || exit 1
 ```
 
-### `report` command (Pro)
+### `report` command (Pro/Enterprise)
 
 `nsauditor-ai report --from <dir> --format executive|jira` turns a completed scan run under `--from` into a client-facing deliverable — an HTML report a consultant sends to their customer, or a Jira-importer CSV.
 
@@ -907,6 +917,51 @@ nsauditor-ai report --from out/2026-08-26 --format executive --brand brand.json
 nsauditor-ai report --from out/2026-08-26 --format jira
 ```
 
+#### The `brand.json` file
+
+`--brand` takes a small JSON object. Every field is optional; omit the file entirely and the report
+renders unbranded with the default title.
+
+```json
+{
+  "title": "Q3 External Perimeter Review",
+  "companyName": "Acme Manufacturing GmbH",
+  "preparedBy": "J. Rivera, Security Consulting LLC",
+  "contact": "security@example.com",
+  "logoPath": "acme-logo.png"
+}
+```
+
+| field | type | default | notes |
+|---|---|---|---|
+| `title` | string | `Network Scan Report` | Replaces the report's headline. |
+| `companyName` | string | *(empty)* | The client the report is prepared **for**. |
+| `preparedBy` | string | *(empty)* | The consultant or firm preparing it. |
+| `contact` | string | *(empty)* | Free text — an address, an email, a phone number. |
+| `logoPath` | string | *(none)* | A **local** PNG or JPEG, resolved relative to the brand file's own directory. Embedded into the HTML as a data URI. |
+
+**`logoPath` is deliberately restrictive, and each refusal protects the report's core promise —
+that it opens with no external network reference of any kind:**
+
+- **A URL is refused and never fetched.** A remote logo is egress at render time and a tracking
+  pixel every time your client opens the file.
+- **A UNC share (`\\host\share\...`) is refused** for the same reason: it is a network reference.
+- **SVG is refused.** SVG is markup and can carry a script, which would break the report's
+  no-script guarantee from inside the image. Use PNG or JPEG.
+- **The path must stay inside the brand file's own directory** — `../` escapes are refused, checked
+  both as typed and again after symlinks are resolved.
+- **2 MB maximum**, and the format is detected by **magic bytes, not by file extension** — renaming
+  `logo.svg` to `logo.png` does not get it past the check.
+- **An empty string is read as "no logo"**, the same as omitting the key, so a generated
+  `brand.json` that emits `""` is not an error.
+
+A brand file that cannot be read, is not valid JSON, is not a JSON object, or whose `logoPath` is
+refused is a **fatal error** — the report is not written. A flag you passed is never silently
+dropped, because that is how a report goes out unbranded without anyone noticing.
+
+⚠️ `--brand` applies to `--format executive` only. Passing it with `--format jira` is **refused**,
+not ignored: a CSV has nowhere to put a cover page.
+
 ---
 
 ## Configuration
@@ -957,7 +1012,7 @@ NSAUDITOR_PLUGIN_PATH=                   # Additional plugin directories (colon-
 **Longitudinal compliance evidence (Enterprise CLI, new alongside the variables below):**
 
 A single scan shows configuration at an instant. A SOC 2 Type II auditor — and the ISO
-surveillance cadence, PCI Appendix E sampling, HIPAA §164.312(b) and GDPR Art. 32(1)(d)
+surveillance cadence, PCI DSS v4.0.1 Section 6 sampling (the assessor's documented determination; the standard prescribes no size), HIPAA §164.312(b) and GDPR Art. 32(1)(d)
 equivalents — asks whether controls operated over a *period*. Every scan has always written
 a per-framework `scan_attestation_<framework>.json`, so a history you already have is
 aggregatable today:

package/cli.mjs

@@ -1452,7 +1452,7 @@ export async function main(testHooks = {}) {
 Usage:
   nsauditor-ai [scan] --host <ip|cidr|hostname> [options]
   nsauditor-ai [scan] --host-file <path> [options]
-  nsauditor-ai report --from <dir> --format executive|jira [options]   (Pro)
+  nsauditor-ai report --from <dir> --format executive|jira [options]   (Pro/Enterprise)
   nsauditor-ai license <subcommand>
   nsauditor-ai security <subcommand>
   nsauditor-ai validate
@@ -1644,7 +1644,7 @@ Examples:
   nsauditor-ai license install enterprise_eyJhbGciOiJFUzI1NiIs...
   nsauditor-ai license --status
 
-Report subcommand (Pro):
+Report subcommand (Pro/Enterprise):
   nsauditor-ai report --from <dir> --format executive|jira [--run <id>]
                        [--brand <brand.json>] [--out <path>] [--allow-partial]
         Renders a client-facing deliverable from a completed scan run under --from.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.2.51",
-  "description": "Modular AI-assisted network security audit platform \u2014 Community Edition",
+  "version": "0.2.53",
+  "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,
   "scripts": {

package/utils/executive_report.mjs

@@ -350,9 +350,25 @@ function renderCoverageSummary(model) {
       return `${escapeHtml(String(u.host))}: ${names}`;
     });
     const total = unread.reduce((a, u) => a + Object.values(u.unread).reduce((x, y) => x + y, 0), 0);
-    lines.push(`<p class="caveat">⚠️ ${total} recorded finding-like object(s) live in containers `
-      + `this report does not read, and are NOT included above — ${parts.join(' · ')}. `
-      + 'Treat this report as incomplete for those surfaces.</p>');
+    // ⚠️ TWO REASONS, TWO SENTENCES — and conflating them put a FALSE QUANTITY in front of a
+    // client. A container nobody reads is genuinely absent from this document. A carve-out whose
+    // PREMISE BROKE is different: its objects ARE rendered above except for the break, so saying
+    // they "are NOT included above" contradicts the body of the same report. Plugin 1150 emits
+    // `data: findings`, so one orphan among sixteen mirrors used to announce that seventeen
+    // objects were missing from a report containing sixteen of them.
+    const broken = unread.some((u) => Object.keys(u.premiseFailures ?? {}).length);
+    if (broken) {
+      const why = unread.flatMap((u) => Object.values(u.premiseFailures ?? {}));
+      lines.push(`<p class="caveat">⚠️ ${total} recorded finding-like object(s) are NOT accounted `
+        + `for by this report — ${parts.join(' · ')}. Some containers are not read at all; others `
+        + 'are summaries whose link to a rendered finding could not be re-derived on this run, so '
+        + 'their objects may appear above under a different heading. '
+        + `${escapeHtml(why.join(' · '))}</p>`);
+    } else {
+      lines.push(`<p class="caveat">⚠️ ${total} recorded finding-like object(s) live in containers `
+        + `this report does not read, and are NOT included above — ${parts.join(' · ')}. `
+        + 'Treat this report as incomplete for those surfaces.</p>');
+    }
   }
   if (!model.findings.length) {
     lines.push(`<p>No findings were recorded for the ${c.written} hosts scanned in this run.</p>`);
@@ -549,7 +565,54 @@ function renderFooter(model) {
   return `<footer>Generated by NSAuditor AI ${escapeHtml(tier)} ${escapeHtml(String(ceVersion))}${eeSuffix}</footer>`;
 }
 
+// Names what `brand` actually was, for the refusal below — never called on a plain object.
+// Same voice and job as brand.mjs's own `describeLogoPathType`: a caller told only "must be an
+// object" over a value it cannot see has to open this module to learn what it did wrong.
+function describeBrand(v) {
+  if (v === null) return 'null';
+  if (v === undefined) return 'undefined';
+  if (Array.isArray(v)) return 'an array';
+  return `a ${typeof v}`;
+}
+
+// ⚠️ REFUSES rather than defaulting, and the choice is the opposite of what "make it total"
+// usually means: this renders a CLIENT-FACING deliverable, so silently normalising an absent
+// brand into an unbranded report is the WORSE failure — it hands the caller a complete,
+// plausible document at exit 0 with the consultant's identity missing, and that is the copy
+// that reaches the client.
+//
+// That is the CC-4 ruling one layer down. `tests/report_command.test.mjs` already pins "a
+// value-less --brand is FATAL, not a silent unbranded default", recorded there because a shell
+// glob that swallowed the path "produced the IDENTICAL unbranded default report, at exit 0, as
+// never asking for a brand at all — silently". An absent argument here is indistinguishable
+// from a lost one for exactly the same reason, and refusing costs the honest caller nothing:
+// "no branding wanted" stays expressible as `{}`, which renders precisely what it rendered
+// before (measured: byte-identical to loadBrand(null)'s defaults, 4579 bytes on the fixture).
+//
+// WHAT WAS MEASURED, over eight brand shapes, before this guard existed: null / undefined / an
+// omitted second argument all threw `TypeError: Cannot read properties of null (reading
+// 'title')` — the loud half. A string, a number, a boolean and an array all RENDERED, 4579
+// bytes, titled "Network Scan Report", with no company line — the quiet half, and the one a
+// caller passing its company NAME where the brand OBJECT belongs would have shipped.
+//
+// A DEFAULTED PARAMETER (`brand = {}`) was rejected: it fires only on `undefined`, so it fixes
+// the omitted-argument call and leaves an explicit `null` — the shape a caller that lost its
+// brand actually produces — crashing exactly as before. The guard is a normalisation check at
+// the single public entry point instead. `renderCover` and `renderBrandBlock` dereference
+// `brand` freely — DERIVED, not counted by hand: 11 dereferences in this module, 7 in
+// renderBrandBlock + 3 in renderCover + this one — and are reachable ONLY through here; that
+// premise is not
+// left to a reading — `tests/executive_report_brand_absent.test.mjs` pins this module's export
+// surface, so exporting either helper fails the build rather than silently opening an
+// unguarded path.
 export function renderExecutiveReport(model, brand, { renderedAt = new Date() } = {}) {
+  if (brand === null || typeof brand !== 'object' || Array.isArray(brand)) {
+    throw new TypeError(
+      'renderExecutiveReport: `brand` must be an object — pass the `brand` field of '
+      + "loadBrand()'s result, or `{}` for a deliberately unbranded report. It is "
+      + `${describeBrand(brand)}. Refusing rather than rendering a client-facing report with `
+      + 'the branding silently missing.');
+  }
   const title = escapeHtml(brand.title || 'Network Scan Report');
 
   return `<!DOCTYPE html>

package/utils/report_finding_census.mjs

@@ -25,6 +25,16 @@
 // because the network path's failure is a SOURCE the consumer never opens. A fixture
 // drawn from a producer's field names cannot catch a producer whose output lives in a
 // different artifact.
+//
+// ⚠️ AND THEN THE ALLOWLIST BECAME THE NEXT INSTANCE OF THE SAME CLASS. Its entries were
+// PROSE, and two of them asserted a FACT about one run rather than a property of a shape —
+// the cisAlarmCoverage entry closed with its own instruction, "re-derive, do not re-assert",
+// and NOTHING RE-DERIVED IT. A carve-out that outlives the fact justifying it excludes real
+// findings from a client deliverable while the census still prints `unread: {}`: a false
+// clean wearing the exit code of a measurement. So an entry is now `{reason, verify}`, and a
+// premise that FAILS or THROWS withdraws the carve-out — the container is counted UNREAD and
+// reported in `premiseFailures` with the detail, because "nobody wrote a reader" and "the
+// reason we wrote no reader stopped being true" need different repairs.
 
 /** Containers the report READS. Adding a reader means adding its key here. */
 export const READ_CONTAINERS = Object.freeze([
@@ -36,38 +46,304 @@ export const READ_CONTAINERS = Object.freeze([
 ]);
 
 /**
- * Containers that carry a `severity` but are NOT findings. Each needs a written reason —
- * an allowlist entry with no reason is how a real door gets closed by accident.
+ * THE CENSUS'S SUBJECT, in one place, because a verifier that vouches for a different set of
+ * objects than the census counted is vouching for nothing. Both the walk below and every
+ * `verify` use this predicate: it is the DEFINITION of what is being carved out, not a
+ * second opinion about it.
+ */
+export function isCensusSubject(node) {
+  return !!node && typeof node === 'object' && !Array.isArray(node) && typeof node.severity === 'string';
+}
+
+const resultsOf = (raw) => (Array.isArray(raw?.results) ? raw.results : []);
+const arrayAt = (o, k) => (Array.isArray(o?.[k]) ? o[k] : []);
+
+/** Key-sorted serialisation, so two rows compare by CONTENT and not by key order. */
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  if (v && typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(v ?? null);
+}
+
+// ── The premises, one per carve-out ──────────────────────────────────────────
+
+/**
+ * (i) `result.summary.cisAlarmCoverage.uncovered[]` — the mirror is still 1:1.
+ *
+ * Derived from the real records, never invented: an uncovered entry is
+ * `{id:'cis-3.1', title, severity, coverageMode}` and its paired rendered finding carries
+ * BOTH `details.cisId` (with `details.category` = 'cis-alarm-coverage-no-filter') AND an
+ * `issues[]` string reading "CloudWatch alarm missing: … (CIS AWS Foundations Benchmark
+ * cis-3.1)". Measured over the 152 sample records: 48 plugin results carry an alarm-coverage
+ * summary, 624 uncovered entries in total, and BOTH channels independently pair 100% of them.
+ * Either channel is therefore accepted — a class the reader receives is not a lost finding,
+ * whichever field carried it — and the details channel is scoped to alarm-coverage findings
+ * so a `cisId` on an unrelated finding cannot stand in for the mirror.
+ */
+function verifyAlarmCoverageStillMirrorsItsFindings(raw) {
+  const broken = [];
+  for (const e of resultsOf(raw)) {
+    const res = e?.result ?? {};
+    const uncovered = arrayAt(res?.summary?.cisAlarmCoverage, 'uncovered').filter(isCensusSubject);
+    if (!uncovered.length) continue;
+
+    const rendered = new Set();
+    for (const f of arrayAt(res, 'findings')) {
+      if (!f || typeof f !== 'object') continue;
+      for (const issue of arrayAt(f, 'issues')) {
+        if (typeof issue !== 'string' || !/alarms?\s+missing/i.test(issue)) continue;
+        for (const m of issue.matchAll(/\bcis-\d+(?:\.\d+)*\b/gi)) rendered.add(m[0].toLowerCase());
+      }
+      const d = f.details;
+      if (d && typeof d.cisId === 'string' && typeof d.category === 'string' && /alarm/i.test(d.category)) {
+        rendered.add(d.cisId.toLowerCase());
+      }
+    }
+    for (const u of uncovered) {
+      if (typeof u.id !== 'string' || !u.id) {
+        broken.push(`plugin ${e?.id ?? '?'}: an uncovered entry with no \`id\` — nothing can pair it`);
+      } else if (!rendered.has(u.id.toLowerCase())) {
+        broken.push(`plugin ${e?.id ?? '?'}: ${u.id}`);
+      }
+    }
+  }
+  return broken.length
+    ? { ok: false,
+      unreadCount: broken.length,
+      detail: `the 1:1 mirror has BROKEN — ${broken.length} uncovered alarm class(es) have no rendered `
+        + `"alarm missing" finding, so they reach no reader: ${broken.join(' · ')}` }
+    : { ok: true, detail: 'every uncovered alarm class pairs with a rendered finding' };
+}
+
+/**
+ * (ii) `result.findings[].policyAnalyses[].issues[]` — the parent really is rendered.
+ *
+ * The carve-out calls the nested issues EVIDENCE FOR a finding that IS rendered. That is
+ * true only while the parent carries content of its own: `shapeFinding` titles a finding
+ * from its `issues[]` (falling back to `detail`/`description`), and with none of those it
+ * renders "(untitled finding)" — utils/report_inputs.mjs:139-151. A parent with no issue of
+ * its own is an empty row whose only real content is the nested detail nobody reads, which
+ * is the carve-out's own negation. Measured: 104 parents across the sample corpus carry
+ * counted policy-analysis issues, and 0 of them lack their own.
+ */
+function verifyPolicyAnalysisBacksARenderedFinding(raw) {
+  const orphans = [];
+  for (const e of resultsOf(raw)) {
+    const findings = arrayAt(e?.result, 'findings');
+    for (let i = 0; i < findings.length; i += 1) {
+      const f = findings[i];
+      if (!f || typeof f !== 'object') continue;
+      const nested = arrayAt(f, 'policyAnalyses')
+        .flatMap((pa) => arrayAt(pa, 'issues'))
+        .filter(isCensusSubject);
+      if (!nested.length) continue;
+      // Presence is not content: an `issues: ['']` renders as no text at all.
+      const own = arrayAt(f, 'issues')
+        .filter((x) => (typeof x === 'string' ? x.trim().length > 0 : !!x));
+      if (!own.length) {
+        orphans.push(`plugin ${e?.id ?? '?'} findings[${i}] carries ${nested.length} policy-analysis `
+          + 'issue(s) and NO issue of its own');
+      }
+    }
+  }
+  return orphans.length
+    ? { ok: false,
+      unreadCount: orphans.length,
+      detail: 'the nested detail is no longer EVIDENCE FOR a rendered finding — the parent renders as '
+        + `"(untitled finding)" with nothing in it: ${orphans.join(' · ')}` }
+    : { ok: true, detail: 'every policy-analysis parent carries its own issue text' };
+}
+
+/**
+ * (iii) `result.data[]` — on the cloud path it still MIRRORS `findings[]`.
+ *
+ * ⚠️ THE PREDICATE IS DELIBERATELY SCOPED TO THE CENSUS'S SUBJECT, AND THAT IS WHAT MAKES
+ * THE NETWORK SHAPE PASS WITHOUT AN EXEMPTION. A network host legitimately has
+ * `findings[] = 0` and `data[] = 85` — measured on the 192.168.1.1 run, 84 of them
+ * `{probe_protocol, probe_port, probe_info}`. Not one carries a `severity`, so not one is a
+ * census subject and there is nothing to mirror: the acceptance is STRUCTURAL, not a list of
+ * telemetry field names that a producer could quietly step outside. The corollary is
+ * intended: a telemetry row that GAINS a severity is a severity-bearing object in a container
+ * nobody reads, and it fails.
+ *
+ * Matching is CONTENT-DEEP within one plugin result. Measured across the sample corpus: 86
+ * plugin results carry severity-bearing data rows (1150 and 1170 only, 1075 rows), and every
+ * row is deep-equal to a row in the same result's findings[]. A laxer key of
+ * severity+resource+issues was measured too — also 0 unmatched — and REJECTED: it collapses
+ * to a constant on rows that carry neither `resource` nor `issues`, which is a false-clean
+ * generator on exactly the network-ish shape this entry has to keep accepting.
+ *
+ * One stated limit: the mirror is looked for in `findings[]` in its ARRAY form only. A
+ * producer that emitted the 060 DICT-of-categories shape AND severity-bearing data[] would
+ * FAIL this premise rather than be excused by it. Nothing does today; failing is the
+ * noise-costing direction, and a lax read here would be a carve-out granted on a shape
+ * nobody has looked at.
+ */
+function verifyDataMirrorsFindings(raw) {
+  const unmirrored = [];
+  for (const e of resultsOf(raw)) {
+    const res = e?.result ?? {};
+    const rows = arrayAt(res, 'data').filter(isCensusSubject);
+    if (!rows.length) continue;
+    const rendered = new Set(arrayAt(res, 'findings')
+      .filter((f) => f && typeof f === 'object').map(canonical));
+    for (const r of rows) {
+      if (!rendered.has(canonical(r))) {
+        // Locate it well enough to act on: `resource` alone is not distinguishing — on some
+        // producers it holds the REGION, so a dozen rows share it.
+        const excerpt = arrayAt(r, 'issues').map((x) => (typeof x === 'string' ? x : x?.detail ?? ''))
+          .find((t) => t && t.trim()) ?? '';
+        unmirrored.push(`plugin ${e?.id ?? '?'}: ${r.severity.toUpperCase()} `
+          + `${r.resource ?? '(no resource)'}${excerpt ? ` — "${excerpt.slice(0, 80)}"` : ''}`);
+      }
+    }
+  }
+  return unmirrored.length
+    ? { ok: false,
+      unreadCount: unmirrored.length,
+      detail: `result.data[] is no longer a mirror — ${unmirrored.length} severity-bearing row(s) have no `
+        + `content-equal finding in the same plugin result, so nothing renders them: ${unmirrored.join(' · ')}` }
+    : { ok: true, detail: 'every severity-bearing data row is mirrored by a rendered finding' };
+}
+
+/**
+ * (iv) `result.portResults[]` — the roll-up really is a roll-up.
+ *
+ * The reason claims the entry's severity "summarises the port's own issues[], which ARE
+ * read". That is checkable in both directions, and both directions matter:
+ *   · a severity over an EMPTY issues[] summarises nothing — it is a finding nothing renders,
+ *     which is the exact hazard the carve-out denies;
+ *   · a severity ABSENT from its own issues' severities is a roll-up of something the port
+ *     does not hold.
+ * The empty case is not simply forbidden, because 040 seeds the roll-up at SEVERITY.PASS and
+ * raises it to the max of the port's issues (plugins/040_tls_cert_auditor.mjs:491-496), so a
+ * clean port emits exactly `{severity:'pass', issues:[]}`. PASS is the identity element of
+ * this roll-up; failing it would flag every healthy HTTPS port and teach an operator to read
+ * past the warning. Measured over 232 records (samples + both out/ trees): 7 portResults
+ * entries carry a severity, all 7 hold it among their own issue severities, and none has an
+ * empty issues[].
+ */
+const ROLLUP_IDENTITY_SEVERITY = 'pass';
+
+function verifyPortRollUpSummarisesItsOwnIssues(raw) {
+  const bad = [];
+  for (const e of resultsOf(raw)) {
+    const ports = arrayAt(e?.result, 'portResults');
+    for (let i = 0; i < ports.length; i += 1) {
+      const pr = ports[i];
+      if (!isCensusSubject(pr)) continue;
+      const where = `plugin ${e?.id ?? '?'} port ${pr.port ?? `[${i}]`}`;
+      const issueSeverities = arrayAt(pr, 'issues').filter(isCensusSubject).map((x) => x.severity);
+      if (!issueSeverities.length) {
+        if (pr.severity !== ROLLUP_IDENTITY_SEVERITY) {
+          bad.push(`${where}: severity "${pr.severity}" over an EMPTY issues[] — it summarises nothing, `
+            + 'so nothing renders it');
+        }
+        continue;
+      }
+      if (!issueSeverities.includes(pr.severity)) {
+        bad.push(`${where}: roll-up severity "${pr.severity}" is not among its own issue severities `
+          + `(${[...new Set(issueSeverities)].join(', ')})`);
+      }
+    }
+  }
+  return bad.length
+    ? { ok: false, unreadCount: bad.length, detail: `the roll-up no longer summarises its own issues[]: ${bad.join(' · ')}` }
+    : { ok: true, detail: 'every port roll-up is carried by its own issues' };
+}
+
+/**
+ * Containers that carry a `severity` but are NOT findings. Each needs a written reason AND,
+ * where the reason rests on a checkable fact, a `verify(raw, queue) => {ok, detail}` that
+ * re-derives it on every run — an allowlist entry with no reason is how a real door gets
+ * closed by accident, and one whose reason nothing re-derives is how a closed door stays
+ * shut after the reason has gone.
  */
 export const ALLOWLISTED_CONTAINERS = Object.freeze({
-  'result.portResults[]':
-    'A per-port ROLL-UP, not a finding: its severity summarises the port\'s own '
-    + '`issues[]`, which ARE read. Rendering both would double-count every TLS issue.',
-  'result.summary.cisAlarmCoverage.uncovered[]':
-    'A 1:1 SUMMARY MIRROR of 1040\'s own alarm-coverage findings, not a second source. '
-    + 'Adjudicated on the 0.44.0 cloud run: 13 uncovered classes, 13 "alarm missing" '
-    + 'findings, and the set difference of their cis-N.N ids is EMPTY. If that ever stops '
-    + 'holding the mirror has broken and this entry is wrong — re-derive, do not re-assert.',
-  'result.findings[].policyAnalyses[].issues[]':
-    'Per-statement EVIDENCE nested inside a finding that IS rendered — e.g. "Full admin '
-    + 'grant: Action \'*\' in policy X" backing a parent whose own issues[] already say '
-    + '"SHADOW ADMIN: User has full wildcard (*) permissions". Not a missed finding. '
-    + 'RESIDUAL, stated rather than hidden: the per-statement detail is not surfaced in the '
-    + 'report at all, which is a DEPTH choice nobody has ruled on, not a coverage gap.',
-  'result.data[]':
-    'NOT a findings container, and the report must never read it. On a CLOUD host it '
-    + 'MIRRORS result.findings (verified 0.44.0: 1150 16/16, 1170 9/9). On a NETWORK host '
-    + 'it is PROBE TELEMETRY — measured on the 192.168.1.1 run, findings[]=0 while '
-    + 'data[]=85, 84 of them {probe_protocol, probe_port, probe_info} ("Connect refused '
-    + '(ECONNREFUSED)", "No UDP response"). ⚠️ A `findings ?? data` fallback was written '
-    + 'here and REVERTED: it put scan telemetry into a client deliverable, hidden because '
-    + 'the telemetry rows collided on one content hash and collapsed to two. '
-    + 'cloud_finding_summary\'s findingsOf may use that precedence — it only ever sees '
-    + 'cloud producers; this consumer sees both paths.',
+  'result.portResults[]': Object.freeze({
+    reason:
+      'A per-port ROLL-UP, not a finding: its severity summarises the port\'s own '
+      + '`issues[]`, which ARE read. Rendering both would double-count every TLS issue.',
+    verify: verifyPortRollUpSummarisesItsOwnIssues,
+  }),
+  'result.summary.cisAlarmCoverage.uncovered[]': Object.freeze({
+    reason:
+      'A 1:1 SUMMARY MIRROR of 1040\'s own alarm-coverage findings, not a second source. '
+      + 'Adjudicated on the 0.44.0 cloud run: 13 uncovered classes, 13 "alarm missing" '
+      + 'findings, and the set difference of their cis-N.N ids is EMPTY. That was a fact '
+      + 'about one run, so `verify` re-derives it on every run rather than re-asserting it.',
+    verify: verifyAlarmCoverageStillMirrorsItsFindings,
+  }),
+  'result.findings[].policyAnalyses[].issues[]': Object.freeze({
+    reason:
+      'Per-statement EVIDENCE nested inside a finding that IS rendered — e.g. "Full admin '
+      + 'grant: Action \'*\' in policy X" backing a parent whose own issues[] already say '
+      + '"SHADOW ADMIN: User has full wildcard (*) permissions". Not a missed finding. '
+      + 'RESIDUAL, stated rather than hidden: the per-statement detail is not surfaced in the '
+      + 'report at all, which is a DEPTH choice nobody has ruled on, not a coverage gap.',
+    verify: verifyPolicyAnalysisBacksARenderedFinding,
+  }),
+  'result.data[]': Object.freeze({
+    reason:
+      'NOT a findings container, and the report must never read it. On a CLOUD host it '
+      + 'MIRRORS result.findings (verified 0.44.0: 1150 16/16, 1170 9/9). On a NETWORK host '
+      + 'it is PROBE TELEMETRY — measured on the 192.168.1.1 run, findings[]=0 while '
+      + 'data[]=85, 84 of them {probe_protocol, probe_port, probe_info} ("Connect refused '
+      + '(ECONNREFUSED)", "No UDP response"). ⚠️ A `findings ?? data` fallback was written '
+      + 'here and REVERTED: it put scan telemetry into a client deliverable, hidden because '
+      + 'the telemetry rows collided on one content hash and collapsed to two. '
+      + 'cloud_finding_summary\'s findingsOf may use that precedence — it only ever sees '
+      + 'cloud producers; this consumer sees both paths.',
+    verify: verifyDataMirrorsFindings,
+  }),
 });
 
 const QUEUE_CONTAINER = 'findingQueue[]';
 
+/**
+ * Adjudicate ONE allowlist entry against a record.
+ *
+ * ⚠️ FAILS CLOSED IN EVERY DIRECTION THAT IS NOT AN EXPLICIT `ok: true`. A verifier that
+ * throws has not established the premise; neither has one that returns a shape nobody can
+ * read. Both are treated as a broken premise, because the alternative — a thrown TypeError
+ * silently restoring the carve-out — is the false clean this whole mechanism exists to
+ * close, and it would arrive precisely when a producer changed shape.
+ *
+ * @returns {string|null} null when the carve-out stands (premise held, or none declared);
+ *                        otherwise the operator-facing detail of why it does not.
+ */
+export function adjudicateAllowlistEntry(entry, raw, queue) {
+  // An entry that declares no premise keeps its carve-out: a shape nobody can check yet is
+  // better carved out loudly, with its reason readable, than checked wrongly. The ratchet
+  // that stops "undeclared" becoming the default lives in the tests, not here.
+  if (typeof entry?.verify !== 'function') return null;
+  let verdict;
+  try {
+    verdict = entry.verify(raw, queue);
+  } catch (err) {
+    return { detail: `premise check THREW (${err?.message ?? String(err)}) — a check that cannot `
+      + 'run has established nothing, so the carve-out is withdrawn' };
+  }
+  if (!verdict || typeof verdict !== 'object' || typeof verdict.ok !== 'boolean') {
+    return { detail: 'premise check returned no verdict — treated as FAILED, because a check that '
+      + 'cannot answer has not established anything' };
+  }
+  if (verdict.ok) return null;
+  // ⚠️ THE COUNT TRAVELS WITH THE DETAIL. This used to return the detail STRING alone, so the
+  // caller had a sentence saying "1 row has no mirror" and no number to act on — and fell back to
+  // the container's whole population, which is exactly the false quantity the consumer renders.
+  // A failure is `{detail, unreadCount}`; `unreadCount` is whatever the verifier claimed and is
+  // VALIDATED downstream by resolveUnreadCount, never trusted here.
+  return {
+    detail: typeof verdict.detail === 'string' && verdict.detail.trim()
+      ? verdict.detail
+      : 'premise FAILED, with no detail given',
+    unreadCount: verdict.unreadCount,
+  };
+}
+
 /**
  * Classify where a severity-bearing object lives. Path is the dotted walk from `result`.
  * @returns {string} a container key
@@ -91,7 +367,7 @@ function* severityObjects(node, path = '') {
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i += 1) yield* severityObjects(node[i], `${path}[${i}]`);
   } else if (node && typeof node === 'object') {
-    if (typeof node.severity === 'string') yield { path, obj: node };
+    if (isCensusSubject(node)) yield { path, obj: node };
     for (const [k, v] of Object.entries(node)) yield* severityObjects(v, `${path}.${k}`);
   }
 }
@@ -102,22 +378,61 @@ function* severityObjects(node, path = '') {
  * @param {Array}  queue the host's finding queue (scan_finding_queue.json, or the
  *                       eeEnrichment fallback) — passed in because it is a SIBLING
  *                       artifact, not part of `raw`, which is the whole reason it was missed.
- * @returns {{byContainer: Object<string, number>, unread: Object<string, number>, total: number}}
+ * @returns {{byContainer: Object<string, number>, unread: Object<string, number>,
+ *            premiseFailures: Object<string, string>, total: number}}
+ *   `unread` is the operator's answer to "what does this report not read?" and a container
+ *   lands there for one of TWO reasons; `premiseFailures` says which, keyed on the same
+ *   container, because the repairs are opposite — an unknown container needs a reader
+ *   written, a withdrawn carve-out needs its justification re-argued or removed.
+ */
+/**
+ * HOW MANY OBJECTS A BROKEN PREMISE ACTUALLY LEAVES UNREAD.
+ *
+ * ⚠️ THE REPAIR FOR ONE FALSE CLEAN INTRODUCED A FALSE QUANTITY, and the number reaches a
+ * CUSTOMER. `unread[k]` used to be the container's WHOLE population, and `executive_report.mjs`
+ * renders it as "N recorded finding-like object(s) … are NOT included above". For a MIRROR
+ * carve-out that breaks PARTIALLY, most of those objects ARE rendered above — plugin 1150 emits
+ * `data: findings`, so 16 mirrored rows and one orphan told a client that 17 objects were missing
+ * from a report containing 16 of them. **A caveat that contradicts the body of its own document.**
+ *
+ * ⚠️ AND `unreadCount ?? population` IS NOT ENOUGH — that only catches null/undefined. A verifier
+ * returning `0` on a real break, or `"3"`, or a count ABOVE the population, would put a garbage
+ * number into a client-facing sentence. Every one of those degrades to the population instead:
+ * **over-report, never emit a silent or impossible number.** `0` is deliberately refused rather
+ * than trusted — a failure claiming nothing is unread is a verifier bug silencing itself.
  */
+export function resolveUnreadCount(failure, population) {
+  const n = failure?.unreadCount;
+  if (typeof n !== 'number' || !Number.isInteger(n) || n <= 0 || n > population) return population;
+  return n;
+}
+
 export function censusFindingContainers(raw, queue = []) {
   const byContainer = {};
   const bump = (k) => { byContainer[k] = (byContainer[k] || 0) + 1; };
 
-  for (const e of (Array.isArray(raw?.results) ? raw.results : [])) {
+  for (const e of resultsOf(raw)) {
     for (const { path } of severityObjects(e?.result ?? {}, '')) bump(containerOf(path));
   }
   if (Array.isArray(queue) && queue.length) byContainer[QUEUE_CONTAINER] = queue.length;
 
   const unread = {};
+  const premiseFailures = {};
   for (const [k, n] of Object.entries(byContainer)) {
     if (READ_CONTAINERS.includes(k)) continue;
-    if (Object.prototype.hasOwnProperty.call(ALLOWLISTED_CONTAINERS, k)) continue;
-    unread[k] = n;
+    if (!Object.prototype.hasOwnProperty.call(ALLOWLISTED_CONTAINERS, k)) { unread[k] = n; continue; }
+    // The premise is only adjudicated where something is actually being carved out: running
+    // it over a container this record does not carry would report on nothing.
+    const failure = adjudicateAllowlistEntry(ALLOWLISTED_CONTAINERS[k], raw, queue);
+    if (failure === null) continue;
+    // The BREAK, not the container — see resolveUnreadCount for why the count is validated
+    // rather than trusted, and why the population stays in `byContainer` where it belongs.
+    unread[k] = resolveUnreadCount(failure, n);
+    // `premiseFailures` stays a map of container -> DETAIL STRING: it is the operator- and
+    // reader-facing half, and the count already lives in `unread`. Putting the verdict OBJECT
+    // here would change a published shape for no gain and hand two numbers to a consumer that
+    // needs one.
+    premiseFailures[k] = failure.detail;
   }
-  return { byContainer, unread, total: Object.values(byContainer).reduce((a, b) => a + b, 0) };
+  return { byContainer, unread, premiseFailures, total: Object.values(byContainer).reduce((a, b) => a + b, 0) };
 }

package/utils/report_inputs.mjs

@@ -384,7 +384,14 @@ async function finishLoadingRecord(outRoot, rec, allowPartial) {
     // container announces itself on the first render, which is how all three of the doors
     // found tonight SHOULD have been found.
     const census = censusFindingContainers(raw, findingQueue);
-    if (Object.keys(census.unread).length) unreadByHost.push({ host, unread: census.unread });
+    // ⚠️ `premiseFailures` TRAVELS WITH THE COUNTS, because the two reasons a container is
+    // unread need DIFFERENT sentences. A container nobody wrote a reader for is genuinely NOT
+    // IN the report; a carve-out whose premise BROKE has most of its objects rendered and only
+    // the break unread. Handing the consumer one number and no reason is what let the report
+    // tell a client that 17 objects were missing from a document containing 16 of them.
+    if (Object.keys(census.unread).length) {
+      unreadByHost.push({ host, unread: census.unread, premiseFailures: census.premiseFailures });
+    }
     hosts.push(shapeHost(host, dir, { ...raw, __findingQueue: findingQueue }));
   }