@sanning/proof 0.12.0 → 0.13.0

package/dist/case.js

@@ -166,7 +166,9 @@
  *    gets, since that reads wrapper keys.
  *
  *    Not exits: a record whose envelope verifies and whose content does not
- *    match its commitment is `RECORD_CONTENT_MISMATCH`, and one that fails
+ *    match its commitment is `RECORD_CONTENT_MISMATCH` where that content is
+ *    inside the signed body and `RECORD_CONTENT_DEPENDENT` where it was handed
+ *    in beside the pack (proof#159), and one that fails
  *    another check inside its pack is `RECORD_DOES_NOT_VERIFY_IN_ITS_PACK`.
  *    Both are named and both STAY in the pile, so neither unsigned content
  *    handed in beside a pack nor a broken inclusion proof removes a record
@@ -207,7 +209,9 @@
  * verdict, exactly as `counterpart_absent` and `not_a_handoff_record` are
  * findings beside a verdict in 4.1.
  *
- * A case with more than one outcome is `mixed` (anchor#198, criterion 4).
+ * A case with any `failed` contribution is `failed`: a proven failure keeps
+ * the headline (5.5.4 v1.16, A17, proof#158). Otherwise a case with more than
+ * one outcome is `mixed` (anchor#198, criterion 4).
  *
  * WHAT THIS READER DOES NOT CLAIM
  * ===============================
@@ -237,9 +241,10 @@
  * sequence. Narrowing any of it here with `handoffs[]` is precisely the move
  * that would reopen proof#137's door.
  */
-import { checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
+import { DECLARATION_VERSION, DECLARATION_VERSION_V2, checkDeclaration, declarationClaims, packRecords, } from "./declaration.js";
 import { NOT_A_HANDOFF_FINDING, normalizedSigningKey, readHandoffs, recordIsMalformed, } from "./handoff.js";
 import { verifyEvidenceBundle } from "./evidence.js";
+import { accountDisclosure, completenessNotes, gradePack, } from "./grading.js";
 // ---- The vocabulary ---------------------------------------------------------
 /**
  * The verdicts a case can reach. Every one is already in use in
@@ -578,17 +583,26 @@ export const PACK_KEY_UNREADABLE = "pack_key_unreadable";
  */
 export const PACK_DOES_NOT_VERIFY = "pack_does_not_verify";
 /**
- * The pack's wrapper HOLDS and its own bundle verdict, from
- * `verifyEvidenceBundle` run here offline over the pack and the content handed
- * in beside it, is not `verified`. The exception carries that verdict
- * (`status`) and the verifier's reasons (`reasons`: its bundle errors, then its
- * stamp errors, then its checkpoint errors, each as the verifier wrote it), and
- * it CONTRIBUTES that verdict, so the case verdict never reads above its
- * weakest pack. Gate 3 on proof#140: two unwitnessed (`partial`) packs read as
- * a `verified` case with no exception. It does not say who is at fault:
- * content handed in beside a pack is not signed by its holder.
+ * The pack's wrapper HOLDS and its CASE GRADE is not `verified`
+ * (evidence-bundle 5.5.1 step 1 v1.20, A23; it replaces
+ * `pack_bundle_not_verified`, which carried the bundle status alone). The case
+ * grade is the pack grade of 5.4.5, taken twice: the SIGNED grade over the run
+ * with the side map empty, and the FULL grade over the run with it. The signed
+ * grade decides where it is `failed` or `malformed`; a failure only the full
+ * grade reaches is `incomplete`, because it rests on bytes nobody signed;
+ * otherwise the full grade. A body the verifier could not read is `malformed`,
+ * a body that is not one of the two event-carrying bodies takes the signed
+ * run's status, and a verifier that graded a different number of records than
+ * the pack holds takes the signed status, or `malformed` where that status is
+ * `verified`.
+ *
+ * The exception carries `status`, the case grade; `causes`, the 5.4.5 cause
+ * kinds of the grade that decided it (none in the first three branches); and
+ * `reasons`, the verifier's reasons from the run with the side map empty. It
+ * CONTRIBUTES the grade, and `incomplete` for `pending`, `not_found` or
+ * `mixed`, so the case verdict never reads above its weakest pack.
  */
-export const PACK_BUNDLE_NOT_VERIFIED = "pack_bundle_not_verified";
+export const PACK_GRADE_NOT_VERIFIED = "pack_grade_not_verified";
 /**
  * A record in a pack whose wrapper holds, whose OWN envelope does not verify
  * (`EventResult.envelopeOk` is false). Not read by 4.1, and NAMED with the
@@ -609,12 +623,39 @@ export const RECORD_ENVELOPE_DOES_NOT_VERIFY = "record_envelope_does_not_verify"
 export const RECORD_DOES_NOT_VERIFY_IN_ITS_PACK = "record_does_not_verify_in_its_pack";
 /**
  * A record whose envelope verifies and whose disclosed content does not hash to
- * the `content_hash` it commits to (`EventResult.contentOk` is false). `failed`,
- * and the record STAYS in the pile: content beside a pack is unsigned and often
+ * the hash it commits to, its `content_hash` or a hand-off record's
+ * `message_hash` (evidence-bundle v1.19, A20) (`EventResult.contentOk` is false), with the
+ * side map EMPTY: the content is inside the signed body. The same mismatch from
+ * content handed in beside the pack is `RECORD_CONTENT_DEPENDENT` (proof#159).
+ * `failed`, and the record STAYS in the pile: content beside a pack is unsigned and often
  * supplied by whoever assembled the case, and gate 3 on proof#140 showed that
  * party erasing an honest verified pair by swapping it.
  */
 export const RECORD_CONTENT_MISMATCH = "record_content_mismatch";
+/**
+ * The two readings proof#147 did not reach, given its shape (proof#159, ruled
+ * by Phil 2026-09-22, evidence-bundle.md 5.5.4 v1.16, A17). A pack whose
+ * bundle verdict is `failed` ONLY when read with the unsigned content handed
+ * in beside it, and `failed` no longer when read with that map empty, is
+ * `PACK_BUNDLE_CONTENT_DEPENDENT`; a record whose content mismatch comes from
+ * that map alone is `RECORD_CONTENT_DEPENDENT`. Both are `incomplete`: the
+ * reader established that the bytes it was handed are not the bytes the record
+ * commits to, and nothing about the party that signed the record, because
+ * whoever assembled the case chose those bytes with no key. Up to v1.15 both
+ * readings carried `failed`, and one flipped nibble of accuser-supplied content
+ * put a `failed` against an intact pack; under A17's headline rule that would
+ * have become the case's headline.
+ *
+ * The test that separates the two is the one proof#159 states for the inverse:
+ * every deviation a signature covers still reads `failed` with the side map
+ * EMPTY. So the pack is verified twice, with the map and without it, and what
+ * fails without it is `PACK_GRADE_NOT_VERIFIED`, `RECORD_CONTENT_MISMATCH`
+ * (content inside the signed body) or `RECORD_DOES_NOT_VERIFY_IN_ITS_PACK`,
+ * each still `failed`. Emptying the map is the most a party that signed
+ * nothing can do to starve the check, and it cannot remove any of those.
+ */
+export const PACK_BUNDLE_CONTENT_DEPENDENT = "pack_bundle_content_dependent";
+export const RECORD_CONTENT_DEPENDENT = "record_content_dependent";
 /**
  * A record signed under a ratified profile that is under quarantine
  * (`CASE_QUARANTINED_PROFILES`, pending DL-63). Not read, in any kernel.
@@ -624,11 +665,13 @@ export const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
 /** The reader was handed no packs at all. */
 export const CASE_HOLDS_NO_PACKS = "case_holds_no_packs";
 /**
- * Every pack was read and not one hand-off record came out of any of them.
- * There is no hand-off to have a verdict about, and saying `verified` over that
- * would be the defect class in its purest form.
+ * The two NOTEs (5.5.3 v1.20): findings on the reading with no contribution,
+ * printed in the scope sentence so a clean verdict never hides either.
+ * `pack_undeclared` is a note only where the reading holds no hand-off record;
+ * where it holds one, it is the exception of that name.
  */
-export const CASE_HOLDS_NO_HANDOFF_RECORDS = "case_holds_no_handoff_records";
+export const CONTENT_WITHHELD_BY_DECLARATION = "content_withheld_by_declaration";
+export const CASE_NOTE_KINDS = [PACK_UNDECLARED, CONTENT_WITHHELD_BY_DECLARATION];
 /**
  * Every exception this reader can report, as a closed set. A surface may render
  * them and a test may assert over them; nothing outside this array is emitted.
@@ -652,13 +695,14 @@ export const CASE_EXCEPTION_KINDS = [
     PACK_HOLDS_NO_RECORDS,
     PACK_KEY_UNREADABLE,
     PACK_DOES_NOT_VERIFY,
-    PACK_BUNDLE_NOT_VERIFIED,
+    PACK_GRADE_NOT_VERIFIED,
+    PACK_BUNDLE_CONTENT_DEPENDENT,
     RECORD_ENVELOPE_DOES_NOT_VERIFY,
     RECORD_DOES_NOT_VERIFY_IN_ITS_PACK,
     RECORD_CONTENT_MISMATCH,
+    RECORD_CONTENT_DEPENDENT,
     RECORD_PROFILE_QUARANTINED,
     CASE_HOLDS_NO_PACKS,
-    CASE_HOLDS_NO_HANDOFF_RECORDS,
 ];
 /**
  * What each exception kind contributes to the case verdict. It is a TABLE and
@@ -671,10 +715,10 @@ export const CASE_EXCEPTION_KINDS = [
  * contributes a clean verdict, which is what makes the invariant in `verdictOf`
  * hold.
  *
- * `PACK_BUNDLE_NOT_VERIFIED` is the one row that is not a constant: it
- * contributes the pack's own bundle verdict, which is `partial`, `failed` or
- * `malformed` and never `verified` (the exception is emitted only when it is
- * not). `null` marks that row, and `readCase` fills it from `status`.
+ * `PACK_GRADE_NOT_VERIFIED` is the one row that is not a constant: it
+ * contributes the pack's case grade, which is never `verified` (the exception
+ * is emitted only when it is not). `null` marks that row, and `readCase` fills
+ * it from `status`.
  */
 const EXCEPTION_VERDICT = {
     [COUNTERPART_ABSENT]: "incomplete",
@@ -695,14 +739,26 @@ const EXCEPTION_VERDICT = {
     [PACK_HOLDS_NO_RECORDS]: "incomplete",
     [PACK_KEY_UNREADABLE]: "incomplete",
     [PACK_DOES_NOT_VERIFY]: "failed",
-    [PACK_BUNDLE_NOT_VERIFIED]: null,
+    [PACK_GRADE_NOT_VERIFIED]: null,
+    [PACK_BUNDLE_CONTENT_DEPENDENT]: "incomplete",
     [RECORD_ENVELOPE_DOES_NOT_VERIFY]: "failed",
     [RECORD_DOES_NOT_VERIFY_IN_ITS_PACK]: "failed",
     [RECORD_CONTENT_MISMATCH]: "failed",
+    [RECORD_CONTENT_DEPENDENT]: "incomplete",
     [RECORD_PROFILE_QUARANTINED]: "incomplete",
     [CASE_HOLDS_NO_PACKS]: "partial",
-    [CASE_HOLDS_NO_HANDOFF_RECORDS]: "partial",
 };
+/**
+ * The case grades `PACK_GRADE_NOT_VERIFIED` contributes as themselves. Every
+ * other grade a pack can reach (`pending`, `not_found`, `mixed`, which a pack
+ * grade passes through and a case verdict never issues) is `incomplete`.
+ */
+const GRADE_CONTRIBUTES = new Set([
+    "partial",
+    "incomplete",
+    "failed",
+    "malformed",
+]);
 // ---- The reading ------------------------------------------------------------
 const bodyTypeOf = (bundle) => typeof bundle === "object" && bundle !== null
     ? bundle["body_type"]
@@ -740,6 +796,23 @@ const wrapperHolds = (result) => result.signatureOk && result.bodyHashOk;
  * bundle-level error at all, and an exception that named the verdict and no
  * reason would send a reader looking for a defect in the pack as a whole.
  */
+/**
+ * The reasons a reading carries only because of the side map, in the order the
+ * verifier wrote them: what the content-dependent kinds are about, and nothing
+ * a signature covers.
+ */
+const onlyIn = (withMap, withoutMap) => withMap.filter((reason) => !withoutMap.includes(reason));
+/**
+ * Whether a side-content map holds any key. Python's `if pack.content` is
+ * the twin: `None` and an empty map both mean the two verify runs are one run.
+ */
+function sideMapHasKeys(content) {
+    if (content === null || content === undefined)
+        return false;
+    if (content instanceof Map)
+        return content.size > 0;
+    return Object.keys(content).length > 0;
+}
 const bundleReasons = (result) => [
     ...result.errors,
     ...(result.stamps ?? []).flatMap((stamp) => stamp.errors),
@@ -775,8 +848,13 @@ function underQuarantine(specVersion) {
 /**
  * The case verdict, from the contributions alone.
  *
- * One outcome is that outcome; more than one is `mixed` (anchor#198,
- * criterion 4). `mixed` is in the 3 vocabulary and coins no word.
+ * **A proven failure keeps the headline** (`evidence-bundle.md` 5.5.4 v1.16,
+ * A17, proof#158): if any contribution is `failed`, the case is `failed`,
+ * whatever else contributes, and every other exception stays named beside it.
+ * Otherwise one outcome is that outcome, and more than one is `mixed`
+ * (anchor#198, criterion 4), so `mixed` never holds a `failed`. `malformed`
+ * does NOT keep the headline: it says a record cannot be read, not that a
+ * check ran and did not pass. `mixed` is in the 3 vocabulary and coins no word.
  *
  * THE INVARIANT, stated so a mutation test has something to kill: `verified` is
  * reachable ONLY when `exceptions` is empty. Every exception kind carries a
@@ -785,14 +863,25 @@ function underQuarantine(specVersion) {
  * The assertion is here anyway, because that is the property every one of the
  * seventeen findings on this program violated.
  */
-function verdictOf(exceptions, contributions) {
-    // Unreachable through `readCase`, which names a case with no contributions
-    // rather than returning one. Defended anyway: an empty aggregate reading as
-    // `verified` is the defect class itself.
-    if (contributions.length === 0)
-        return "partial";
+function verdictOf(exceptions, contributions, holdsPacks = true) {
+    // A reading that holds at least one pack and no contribution at all is
+    // `verified` (5.5.4 v1.20, A23): every pack in it graded `verified` and
+    // nothing in it was an exception. Every exception contributes, so no
+    // contribution means no exception. A reading with no packs always carries
+    // `case_holds_no_packs`, and is defended here anyway: an empty aggregate over
+    // nothing reading as `verified` is the defect class itself.
+    if (contributions.length === 0) {
+        if (exceptions.length > 0) {
+            throw new Error(`exceptions with no contribution: ${exceptions.map((e) => e.kind).join(", ")}`);
+        }
+        return holdsPacks ? "verified" : "partial";
+    }
     const outcomes = new Set(contributions.map(([, v]) => v));
-    const verdict = outcomes.size === 1 ? [...outcomes][0] : "mixed";
+    const verdict = outcomes.has("failed")
+        ? "failed"
+        : outcomes.size === 1
+            ? [...outcomes][0]
+            : "mixed";
     if (verdict === "verified" && exceptions.length > 0) {
         throw new Error(`verified over a non-empty exception list: ${exceptions.map((e) => e.kind).join(", ")}`);
     }
@@ -826,23 +915,35 @@ function verdictOf(exceptions, contributions) {
  * see is the counterpart that is missing.
  */
 export async function readCase(packs) {
+    // A `null` slot is held for each pack that carries no declaration, and
+    // settled once the pile says whether the reading holds a hand-off record.
     const exceptions = [];
     const contributions = [];
     const note = (kind, fields = {}) => {
         exceptions.push({ kind, ...fields });
-        // `null` is PACK_BUNDLE_NOT_VERIFIED: the pack's own verdict, never verified.
-        const contribution = EXCEPTION_VERDICT[kind] ?? fields.status;
+        // `null` is PACK_GRADE_NOT_VERIFIED: the pack's case grade, never
+        // verified, and `incomplete` for a word a pack grade passes through and a
+        // case verdict never issues (5.5.1 step 1 v1.20).
+        let contribution = EXCEPTION_VERDICT[kind];
+        if (contribution === null) {
+            const status = fields.status;
+            contribution = GRADE_CONTRIBUTES.has(status) ? status : "incomplete";
+        }
         contributions.push([fields.eventId ?? fields.packRef ?? "case", contribution]);
     };
     if (packs.length === 0) {
         note(CASE_HOLDS_NO_PACKS);
+        const named = exceptions;
+        const contributed = contributions;
         return {
-            verdict: verdictOf(exceptions, contributions),
-            exceptions,
+            verdict: verdictOf(named, contributed, false),
+            exceptions: named,
             records: [],
-            contributions,
+            contributions: contributed,
             handoffRecords: 0,
             onChainChecked: false,
+            notes: [],
+            packs: [],
         };
     }
     // Step 1 and 2, pack by pack, in the order the reader was given them.
@@ -884,6 +985,15 @@ export async function readCase(packs) {
     // below, from the pack envelope and never from the body, so no body type, no
     // disclosure choice and no record content decides whether it is read.
     const holderKeys = new Set();
+    // One reading per pack, in the order the reader was given them (5.5.4 v1.20).
+    const packReadings = [];
+    // The NOTEs (5.5.3 v1.20), with the pack position they are about.
+    const caseNotes = [];
+    // The role each pack's readable v2 declaration signs for each record, keyed
+    // by the pack's POSITION for the reason `claimsByPack` is.
+    const rolesByPack = new Map();
+    // The undeclared packs' slots, settled after the pile is read.
+    const undeclaredSlots = [];
     // How many packs this reader could not tie to a key: an unreadable wrapper
     // key, or a wrapper that does not hold. While it is not zero, "no pack in this
     // case is signed by the named key" is not established, so the innocent
@@ -899,6 +1009,13 @@ export async function readCase(packs) {
             // of these spellings (proof#135) and the reading must not.
             note(PACK_KEY_UNREADABLE, { packRef: pack.ref });
             unattributed += 1;
+            packReadings.push({
+                ref: pack.ref,
+                signingKey: null,
+                grade: null,
+                recordsWithheld: 0,
+                declarationVersion: null,
+            });
             continue;
         }
         // The precondition `HeldRecord` states, met HERE rather than trusted to a
@@ -910,28 +1027,121 @@ export async function readCase(packs) {
             content: (pack.content ?? undefined),
         });
         witnessChecked.push(verified.onChainChecked);
+        // The same pack with the side map EMPTY (proof#159): what fails here is
+        // what a signature covers, and what fails only above rests on bytes nobody
+        // signed. Skipped where there is no map, because the two runs are then the
+        // same run.
+        const signed = sideMapHasKeys(pack.content)
+            ? await verifyEvidenceBundle(pack.bundle, {})
+            : verified;
         // WHOSE PACK IS IT. The wrapper, and only the wrapper.
         if (!wrapperHolds(verified)) {
             note(PACK_DOES_NOT_VERIFY, { packRef: pack.ref });
             unattributed += 1;
+            packReadings.push({
+                ref: pack.ref,
+                signingKey: holder,
+                grade: null,
+                recordsWithheld: 0,
+                declarationVersion: null,
+            });
             continue;
         }
         holderKeys.add(holder);
-        // WHAT IS WRONG INSIDE IT, from here on. First the pack's own assurance,
-        // which propagates: the case never reads above its weakest pack.
-        if (verified.status !== "verified") {
-            note(PACK_BUNDLE_NOT_VERIFIED, {
+        const bodyType = bodyTypeOf(pack.bundle);
+        const records = packRecords(pack.bundle, pack.content);
+        // The per-record gradings below are joined to `records` BY INDEX, so a
+        // verifier that graded a different number of records than the pack holds
+        // leaves this loop with no grading to read. That is not hypothetical: a
+        // pack whose `body_hash` does not cover its body reads `failed` with
+        // `events` EMPTY while `packRecords` reads every record in it, and only
+        // `wrapperHolds` above stands between that pack and this loop. A reader
+        // must never crash on a pack a party can build, so the gap is graded rather
+        // than indexed into, and the pack's records are dropped exactly as a
+        // `malformed` pack's are (gate 4 on proof#140, finding 3).
+        const ungraded = verified.events.length !== records.length || signed.events.length !== records.length;
+        const knownBody = CASE_BODY_TYPES.includes(bodyType);
+        // WHAT IS WRONG INSIDE IT, from here on. First the pack's own GRADE, which
+        // propagates: the case never reads above its weakest pack (5.5.1 step 1
+        // v1.20, A23; up to v1.19 it was the bundle status).
+        let check = null;
+        let full = null;
+        let causes = [];
+        let grade;
+        if (signed.status === "malformed") {
+            grade = "malformed";
+        }
+        else if (!knownBody) {
+            grade = signed.status;
+        }
+        else if (ungraded) {
+            grade = signed.status === "verified" ? "malformed" : signed.status;
+        }
+        else {
+            check = checkDeclaration(pack.bundle, pack.content);
+            const completeness = completenessNotes(pack.bundle);
+            full = gradePack(verified, accountDisclosure(pack.bundle, pack.content ?? {}), completeness, check);
+            const bareGrade = gradePack(signed, accountDisclosure(pack.bundle, {}), completeness, checkDeclaration(pack.bundle, null));
+            // NO `failed` HERE RESTS ON BYTES NOBODY SIGNED. The signed grade decides
+            // where it is `failed` or `malformed`; a failure only the side map
+            // produced is `incomplete`; otherwise the full grade.
+            if (bareGrade.verdict === "failed" || bareGrade.verdict === "malformed") {
+                grade = bareGrade.verdict;
+                causes = bareGrade.causes.map((c) => c.kind);
+            }
+            else if (full.verdict === "failed" || full.verdict === "malformed") {
+                grade = "incomplete";
+                causes = full.causes.map((c) => c.kind);
+            }
+            else {
+                grade = full.verdict;
+                causes = full.causes.map((c) => c.kind);
+            }
+        }
+        if (grade !== "verified") {
+            const reasons = bundleReasons(signed);
+            if (knownBody && ungraded && signed.status !== "malformed") {
+                // Said, because nothing else says it: the verifier's own reasons are
+                // about the bundle, and this pack's records are dropped for a reason
+                // of this reader's.
+                reasons.push(`this verifier graded ${verified.events.length} of the ${records.length} ` +
+                    "record(s) the pack holds, so none of them is read");
+            }
+            note(PACK_GRADE_NOT_VERIFIED, {
                 packRef: pack.ref,
-                status: verified.status,
-                reasons: bundleReasons(verified),
+                status: grade,
+                causes,
+                reasons,
+            });
+        }
+        if (verified.status === "failed" && signed.status !== "failed") {
+            note(PACK_BUNDLE_CONTENT_DEPENDENT, {
+                packRef: pack.ref,
+                reasons: onlyIn(bundleReasons(verified), bundleReasons(signed)),
+            });
+        }
+        const recordsWithheld = full !== null ? full.recordsWithheld : 0;
+        packReadings.push({
+            ref: pack.ref,
+            signingKey: holder,
+            grade,
+            recordsWithheld,
+            declarationVersion: knownBody ? declarationVersionOf(pack.bundle) : null,
+        });
+        if (recordsWithheld > 0) {
+            // A NOTE, with no contribution (5.5.3 v1.20): the holder signed that
+            // these records' content does not travel, and the scope sentence counts
+            // them, so a clean verdict never hides them.
+            caseNotes.push({
+                position,
+                note: { kind: CONTENT_WITHHELD_BY_DECLARATION, packRef: pack.ref, count: recordsWithheld },
             });
         }
         // The body is one the verifier could not read, so it graded no record, and
         // nothing below has a grading to read. Named above.
-        if (verified.status === "malformed")
+        if (signed.status === "malformed")
             continue;
-        const bodyType = bodyTypeOf(pack.bundle);
-        if (!CASE_BODY_TYPES.includes(bodyType)) {
+        if (!knownBody) {
             // `sanning.evidence.export/v2` lands here, and it is NOT unwrapped: its
             // records sit under `body.source_bundle`, and reading them is a change to
             // which packs this reader grades, so it is a decision of its own and not
@@ -941,58 +1151,39 @@ export async function readCase(packs) {
             note(PACK_BODY_TYPE_UNKNOWN, { packRef: pack.ref });
             continue;
         }
-        const records = packRecords(pack.bundle, pack.content);
-        // The per-record gradings below are joined to `records` BY INDEX, so a
-        // verifier that graded a different number of records than the pack holds
-        // leaves this loop with no grading to read. That is not hypothetical: a
-        // pack whose `body_hash` does not cover its body reads `failed` with
-        // `events` EMPTY while `packRecords` reads every record in it, and only
-        // `wrapperHolds` above stands between that pack and this loop. A reader
-        // must never crash on a pack a party can build, so the gap is NAMED rather
-        // than indexed into, and the pack's records are dropped exactly as a
-        // `malformed` pack's are (gate 4 on proof#140, finding 3: under the
-        // mutation that dropped `bodyHashOk` from the wrapper test, this kernel
-        // threw `Cannot read properties of undefined (reading 'envelopeOk')` here
-        // and nothing in the ladder said so).
-        if (verified.events.length !== records.length) {
-            note(PACK_BUNDLE_NOT_VERIFIED, {
-                packRef: pack.ref,
-                status: verified.status,
-                reasons: [
-                    `this verifier graded ${verified.events.length} of the ` +
-                        `${records.length} record(s) the pack holds, so none of them is read`,
-                ],
-            });
+        // Graded above (`malformed` where the verifier called it `verified`), and
+        // none of its records are read.
+        if (ungraded)
             continue;
-        }
         if (records.length === 0) {
             note(PACK_HOLDS_NO_RECORDS, { packRef: pack.ref });
             continue;
         }
-        const check = checkDeclaration(pack.bundle, pack.content);
+        const checked = check;
         claimsByPack.set(position, declarationClaims(pack.bundle));
-        if (check.contentFindings.length > 0) {
+        rolesByPack.set(position, new Map((checked.roles ?? []).map((r) => [r.eventId, r.role])));
+        if (checked.contentFindings.length > 0) {
             // BESIDE the deviation exception and never instead of it: a pack can do
             // both, over different records, and the two say different things. This
             // one is `incomplete` because whoever assembled the case chose the bytes
             // it turns on (proof#147).
             note(PACK_DECLARATION_CONTENT_DEPENDENT, {
                 packRef: pack.ref,
-                count: check.contentFindings.length,
+                count: checked.contentFindings.length,
             });
         }
-        if (check.verdict === "failed") {
+        if (checked.verdict === "failed") {
             note(PACK_DECLARATION_DEVIATES, {
                 packRef: pack.ref,
-                count: check.deviations.length,
+                count: checked.deviations.length,
             });
         }
-        else if (check.contentFindings.length > 0) {
+        else if (checked.contentFindings.length > 0) {
             // Already named above. `partial` here is not "the reader cannot read the
             // claim": the claim was read, and part of it rests on bytes nobody
             // signed.
         }
-        else if (check.verdict === "verified") {
+        else if (checked.verdict === "verified") {
             // A pack that agrees with its own claim contributes NOTHING, rather than
             // a `verified` of its own. The case verdict is over the hand-off
             // readings, and criterion 4's "mixed" is about mixed HAND-OFF outcomes: a
@@ -1001,7 +1192,7 @@ export async function readCase(packs) {
             // read `mixed` and the failure would be the quieter half of a two-word
             // answer. A pack-level PROBLEM still contributes, through its exception.
         }
-        else if (check.present) {
+        else if (checked.present) {
             // `partial` with a declaration present is 5.4.3's "a claim this reader
             // cannot read", which `gradePack` already carries to `incomplete`. The
             // same posture here, for the same reason: the field has no accept-set and
@@ -1009,7 +1200,18 @@ export async function readCase(packs) {
             note(PACK_DECLARATION_UNREADABLE, { packRef: pack.ref });
         }
         else {
-            note(PACK_UNDECLARED, { packRef: pack.ref });
+            // WHAT IT CONTRIBUTES TURNS ON THE WHOLE READING (5.5.1 step 2 v1.20,
+            // A23, I4): `partial` where the reading holds a hand-off record, and a
+            // NOTE where it holds none. That is not known until the pile is read, so
+            // the slot is held HERE, in pack order, and settled below.
+            undeclaredSlots.push({
+                exceptionAt: exceptions.length,
+                contributionAt: contributions.length,
+                position,
+                ref: pack.ref,
+            });
+            exceptions.push(null);
+            contributions.push(null);
         }
         // Each record on its OWN envelope. `packRecords` and the verifier both walk
         // `body.events` in order and emit one entry per element, so the index is
@@ -1017,6 +1219,7 @@ export async function readCase(packs) {
         for (let index = 0; index < records.length; index += 1) {
             const record = records[index];
             const graded = verified.events[index];
+            const bare = signed.events[index];
             if (underQuarantine(recordSpecVersion(pack.bundle, index))) {
                 note(RECORD_PROFILE_QUARANTINED, { packRef: pack.ref, eventId: record.eventId });
                 continue;
@@ -1043,20 +1246,31 @@ export async function readCase(packs) {
                 });
                 continue;
             }
-            // Named, and the record stays in the pile (see the kinds).
-            if (graded.contentOk === false) {
+            // Named, and the record stays in the pile (see the kinds). A mismatch
+            // the signed body carries on its own is `failed`; one that appears only
+            // with the side map is `incomplete` (proof#159).
+            if (bare.contentOk === false) {
                 note(RECORD_CONTENT_MISMATCH, {
                     packRef: pack.ref,
                     eventId: record.eventId,
-                    reasons: [...graded.errors],
+                    reasons: [...bare.errors],
                 });
             }
-            if (!(graded.inclusionOk && graded.checkpointBound) ||
-                (!graded.ok && graded.contentOk !== false)) {
+            else if (graded.contentOk === false) {
+                note(RECORD_CONTENT_DEPENDENT, {
+                    packRef: pack.ref,
+                    eventId: record.eventId,
+                    reasons: onlyIn(graded.errors, bare.errors),
+                });
+            }
+            // Every other check on the SIGNED reading, so side content can neither
+            // add a failure here nor take one away.
+            if (!(bare.inclusionOk && bare.checkpointBound) ||
+                (!bare.ok && bare.contentOk !== false)) {
                 note(RECORD_DOES_NOT_VERIFY_IN_ITS_PACK, {
                     packRef: pack.ref,
                     eventId: record.eventId,
-                    reasons: [...graded.errors],
+                    reasons: [...bare.errors],
                 });
             }
             held.push({
@@ -1085,6 +1299,7 @@ export async function readCase(packs) {
             findings: [...reading.findings],
             failedChecks: [...reading.failedChecks],
             counterparts: [...reading.candidates],
+            role: rolesByPack.get(position)?.get(eventId) ?? null,
         });
         // proof#137's door, named. Read from the ONE reader of the declaration
         // (`declarationClaims`), never from a second parse here. Only a READABLE
@@ -1098,9 +1313,13 @@ export async function readCase(packs) {
         // `not_a_handoff_record` exit it was a check the audited party switched off
         // by respelling two fields, and behind the `malformed` exit it was one a
         // party switched off by breaking its own record.
+        //
+        // v1's ALONE (5.5.1 v1.20, A21). A v2 pack's claim check is rule 9, which
+        // the declaration check already ran on the signed body.
         const claims = claimsByPack.get(position);
         if (claims !== undefined &&
             claims.readable &&
+            claims.version === DECLARATION_VERSION &&
             !claims.claimedSides.includes(eventId)) {
             note(RECORD_UNCLAIMED, { packRef, eventId });
         }
@@ -1190,17 +1409,54 @@ export async function readCase(packs) {
             contributions.push([`${packRef}/${eventId}`, "verified"]);
         }
     }
-    if (handoffRecords === 0)
-        note(CASE_HOLDS_NO_HANDOFF_RECORDS);
+    // A reading with no hand-off record in it is not an exception (5.5.3 v1.20,
+    // A23, D6). The undeclared packs, settled: the exception `pack_undeclared`,
+    // contributing `partial`, in the slot it was given in pack order where the
+    // reading holds a hand-off record; a NOTE with no contribution where it holds
+    // none.
+    for (const slot of undeclaredSlots) {
+        if (handoffRecords > 0) {
+            exceptions[slot.exceptionAt] = { kind: PACK_UNDECLARED, packRef: slot.ref };
+            contributions[slot.contributionAt] = [slot.ref, EXCEPTION_VERDICT[PACK_UNDECLARED]];
+        }
+        else {
+            caseNotes.push({ position: slot.position, note: { kind: PACK_UNDECLARED, packRef: slot.ref } });
+        }
+    }
+    const named = exceptions.filter((e) => e !== null);
+    const contributed = contributions.filter((c) => c !== null);
+    // Pack order, stable. A pack carries at most one note: one with no
+    // declaration withholds nothing by one.
+    const notes = caseNotes
+        .map((n, i) => ({ ...n, i }))
+        .sort((a, b) => a.position - b.position || a.i - b.i)
+        .map((n) => n.note);
     return {
-        verdict: verdictOf(exceptions, contributions),
-        exceptions,
+        verdict: verdictOf(named, contributed),
+        exceptions: named,
         records,
-        contributions,
+        contributions: contributed,
         handoffRecords,
         onChainChecked: witnessChecked.length > 0 && witnessChecked.every((c) => c),
+        notes,
+        packs: packReadings,
     };
 }
+/**
+ * `body.declaration.declaration_version` where it is one this reader knows,
+ * and `null` otherwise.
+ */
+function declarationVersionOf(bundle) {
+    const at = (v, k) => typeof v === "object" && v !== null && !Array.isArray(v)
+        ? v[k]
+        : undefined;
+    const declaration = at(at(bundle, "body"), "declaration");
+    if (typeof declaration !== "object" || declaration === null || Array.isArray(declaration)) {
+        return null;
+    }
+    const version = declaration["declaration_version"];
+    return version === DECLARATION_VERSION || version === DECLARATION_VERSION_V2 ? version : null;
+}
 // ---- Presentation (optional) ------------------------------------------------
 /**
  * The house wording for one exception.
@@ -1285,13 +1541,20 @@ export function renderException(exception) {
             return (`${exception.packRef} carries a wrapper signature over its body that ` +
                 "does not verify, so none of its records are read and the key it " +
                 "names is not counted as its signer");
-        case PACK_BUNDLE_NOT_VERIFIED: {
-            let head = `${exception.packRef} reads ${(exception.status ?? "").toUpperCase()} as ` +
-                "a bundle, together with any content handed in beside it";
+        case PACK_GRADE_NOT_VERIFIED: {
+            let head = `${exception.packRef} grades ${(exception.status ?? "").toUpperCase()} as a pack`;
+            if (exception.causes !== undefined && exception.causes.length > 0) {
+                head += ` (${exception.causes.join(", ")})`;
+            }
             if (exception.status === "malformed")
                 head += ", so none of its records are read";
             return head + because(exception.reasons);
         }
+        case PACK_BUNDLE_CONTENT_DEPENDENT:
+            return (`${exception.packRef} reads FAILED as a bundle only together with ` +
+                "the unsigned content handed in beside it, which anyone could have " +
+                "supplied, so whether that failure is the pack's is UNKNOWN" +
+                because(exception.reasons));
         case RECORD_ENVELOPE_DOES_NOT_VERIFY:
             return (`${where} is in a pack whose wrapper verifies, and its own envelope ` +
                 "does not verify, so it is not read as a hand-off record" +
@@ -1304,45 +1567,128 @@ export function renderException(exception) {
             return (`${where} is read with content that does not match what it commits ` +
                 "to, and it is still read as a hand-off record" +
                 because(exception.reasons));
+        case RECORD_CONTENT_DEPENDENT:
+            return (`${where} commits to content that the unsigned content handed in ` +
+                "beside its pack does not match, and anyone could have supplied " +
+                "that content, so what it says about the record is UNKNOWN; the " +
+                "record is still read as a hand-off record" +
+                because(exception.reasons));
         case RECORD_PROFILE_QUARANTINED:
             return (`${where} is signed under a profile this case reader does not read ` +
                 "while its admission is undecided, so what it says is UNKNOWN");
         case CASE_HOLDS_NO_PACKS:
             return "this case holds no packs";
-        case CASE_HOLDS_NO_HANDOFF_RECORDS:
-            return ("no record this verifier read in this case is a hand-off record, " +
-                "so no hand-off was verified");
         default:
             return exception.kind;
     }
 }
+/** The house wording for one NOTE. Offered, not imposed, as `renderException` is. */
+export function renderCaseNote(note) {
+    switch (note.kind) {
+        case CONTENT_WITHHELD_BY_DECLARATION:
+            return (`${note.packRef} withholds the content of ${note.count} record(s) by ` +
+                "its own signed declaration: their signatures and commitments were " +
+                "checked, their content was not");
+        case PACK_UNDECLARED:
+            return `${note.packRef} does not say what it holds`;
+        default:
+            return note.kind;
+    }
+}
 /**
- * One line a surface can print for a whole case.
+ * The scope sentence, printed directly under the headline (evidence-bundle
+ * 5.5.6 v1.20, A26), byte for byte the text `render_case_summary` returns.
+ *
+ * The packs in the reading; the distinct keys, compared as keys, that signed
+ * the wrapper of a pack whose wrapper held; the hand-off records; the
+ * exceptions; and that the reading was made offline. Where any pack holds
+ * records withheld by its declaration, their total; where any pack is noted
+ * `pack_undeclared`, how many. Those two lines are part of what the headline
+ * MEANS, and a surface MUST print them with it.
  *
- * Both kernels print this sentence, so a reader who runs the Python command and
- * the TypeScript one over one case archive reads one sentence rather than two
- * that differ by a word.
+ * What was not checked on the public record is no longer a clause here. It is
+ * the witness line (`renderWitnessLine`), printed with every headline.
  */
 export function renderCaseSummary(reading) {
-    const n = reading.handoffRecords;
-    // What was NOT checked, in the same sentence as what was, and in the
-    // `verified` one above all (gate 4 on proof#140, finding 3). It is a
-    // statement of SCOPE and not a doubt: every pack here was verified offline,
-    // and no `anchor_ref` any of them names was fetched from a chain, because
-    // this reader makes no network call. Left unsaid, a clean case reads as
-    // though a witness had been checked, which nobody established. It is not an
-    // exception, and it must never become one: an empty exception list is the
-    // only shape a reader may read as clean, so a standing exception here would
-    // put `verified` out of reach for good.
-    const scope = reading.onChainChecked
-        ? ""
-        : "; no anchor_ref in it was re-fetched on chain, which this reader never does";
-    if (reading.verdict === "verified") {
-        return (`this case verifies across ${reading.records.length} record(s): ` +
-            `${n} hand-off record(s), every one matched, no exceptions` +
-            scope);
+    const keys = new Set(reading.packs.filter((p) => p.grade !== null).map((p) => p.signingKey));
+    const withheld = reading.packs.reduce((n, p) => n + p.recordsWithheld, 0);
+    const undeclared = reading.notes.filter((n) => n.kind === PACK_UNDECLARED).length;
+    const lines = [
+        `${reading.packs.length} pack(s), ${keys.size} signing key(s), ` +
+            `${reading.handoffRecords} hand-off record(s), ` +
+            `${reading.exceptions.length} exception(s), read offline.`,
+    ];
+    if (withheld > 0) {
+        lines.push(`${withheld} record(s)' content withheld by their holder: their ` +
+            "signatures and commitments were checked, their content was not.");
     }
-    return (`this case reads ${reading.verdict.toUpperCase()} over ${n} hand-off ` +
-        `record(s), with ${reading.exceptions.length} exception(s)` +
-        scope);
+    if (undeclared > 0)
+        lines.push(`${undeclared} pack(s) do not say what they hold.`);
+    return lines.join(" ");
+}
+// ---- The headline and the witness line (evidence-bundle 5.5.6 v1.20) -------
+/**
+ * The one display title of each of the eight 3 words. A surface prints the
+ * title, never the word, and never a title of its own (#173, A18). The wording
+ * is Will's to change through the glossary (DL-71); what each MEANS is pinned
+ * in the spec.
+ */
+export const VERDICT_DISPLAY_TITLES = {
+    verified: "Verified",
+    partial: "Partial",
+    pending: "Pending",
+    incomplete: "Incomplete",
+    failed: "Failed",
+    malformed: "Not readable",
+    not_found: "Not found",
+    mixed: "Mixed",
+};
+/**
+ * What a reader may rely on, for each of the six words a case reading reaches
+ * (5.5.6 v1.20, A26), the same for every drop. `pending` and `not_found`
+ * never head a case reading: they are witness states.
+ */
+export const CASE_RELIANCE = {
+    verified: "Every pack in this drop is genuine and unaltered and agrees with its " +
+        "own signed declaration. Every hand-off with both sides here is " +
+        "intact. Every other record is one its holder signed as a step. " +
+        "Nothing here could not be checked. This was read offline, on this " +
+        "device. It does not say these packs are everything the parties " +
+        "recorded.",
+    partial: "Nothing here was proven wrong, and a check could not be completed: a " +
+        "pack names no witness, or a pack in a hand-off reading does not say " +
+        "what it holds. The exceptions say which.",
+    incomplete: "Nothing here was proven wrong, and part of it could not be checked: " +
+        "the other side of a hand-off is not in this drop, bytes were not " +
+        "handed over, or a claim could not be read. Each exception says what " +
+        "is missing and, where a key is known, whose pack would supply it.",
+    failed: "A check ran and did not pass. Do not rely on this drop until the " +
+        "named failure is explained. The failure is named on the pack or " +
+        "record it is about, and every other exception is listed beside it.",
+    malformed: "Part of this drop could not be read as evidence, and nothing was " +
+        "proven wrong. The exceptions name what could not be read.",
+    mixed: "The readings here differ and none of them failed: some are verified " +
+        "and some could not be checked. Read each pack's row and each " +
+        "exception before relying on any of it.",
+};
+/** The three witness states, and how each is printed (5.5.6, D7). No other. */
+export const WITNESS_STATES = {
+    confirmed: "Confirmed on the public record",
+    not_checked: "Not checked",
+    differs: "The public record holds different bytes",
+};
+/** The line printed where no lookup ran, which is every reading this kernel produces on its own. */
+export const WITNESS_NOT_LOOKED_UP = Object.freeze({
+    state: "not_checked",
+    reasons: ["no lookup was run"],
+    services: [],
+});
+/** The witness line as both kernels print it. */
+export function renderWitnessLine(line) {
+    let text = `Witness: ${WITNESS_STATES[line.state]}`;
+    if (line.reasons.length > 0)
+        text += `: ${line.reasons.join("; ")}`;
+    if (line.services.length > 0)
+        text += ` (answered: ${line.services.join(", ")})`;
+    return text;
 }