@sanning/proof 0.12.0 → 0.14.0

package/src/case.ts

@@ -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
  * ===============================
@@ -239,7 +243,11 @@
  */
 
 import {
+  type DeclarationCheck,
   type DeclarationClaims,
+  type DeclarationRole,
+  DECLARATION_VERSION,
+  DECLARATION_VERSION_V2,
   checkDeclaration,
   declarationClaims,
   packRecords,
@@ -252,10 +260,18 @@ import {
   readHandoffs,
   recordIsMalformed,
 } from "./handoff.js";
-import { verifyEvidenceBundle } from "./evidence.js";
+import { coSignaturesPresent, verifyEvidenceBundle } from "./evidence.js";
 import type { EvidenceBundleResult } from "./evidence.js";
-import type { PackVerdict } from "./grading.js";
+import {
+  type PackGrade,
+  type PackGradeCauseKind,
+  type PackVerdict,
+  accountDisclosure,
+  completenessNotes,
+  gradePack,
+} from "./grading.js";
 import type { SideContentMap } from "./side-content.js";
+import { renderWitnessTime } from "./witness-cache.js";
 
 // ---- The vocabulary ---------------------------------------------------------
 
@@ -623,17 +639,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
@@ -657,13 +682,41 @@ export const RECORD_DOES_NOT_VERIFY_IN_ITS_PACK = "record_does_not_verify_in_its
 
 /**
  * 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.
@@ -675,11 +728,26 @@ export const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
 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 three NOTEs (5.5.3 v1.20, extended proof#148): findings on the reading
+ * with no contribution, printed in the scope sentence so a clean verdict
+ * never hides any of them. `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 CONTENT_WITHHELD_BY_DECLARATION = "content_withheld_by_declaration";
+/**
+ * A pack's wrapper carries a present `co_signatures` (evidence-bundle.md §2,
+ * decided by Phil 2026-09-24 on proof#148). The field verifies nothing and
+ * sits outside the wrapper's signed scope, so the case reading names it
+ * rather than presenting it as evidence, and it contributes no verdict.
  */
-export const CASE_HOLDS_NO_HANDOFF_RECORDS = "case_holds_no_handoff_records";
+export const CO_SIGNATURES_PRESENT = "co_signatures_present";
+export const CASE_NOTE_KINDS = [
+  PACK_UNDECLARED,
+  CONTENT_WITHHELD_BY_DECLARATION,
+  CO_SIGNATURES_PRESENT,
+] as const;
+export type CaseNoteKind = (typeof CASE_NOTE_KINDS)[number];
 
 /**
  * Every exception this reader can report, as a closed set. A surface may render
@@ -704,13 +772,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,
 ] as const;
 
 export type CaseExceptionKind = (typeof CASE_EXCEPTION_KINDS)[number];
@@ -726,10 +795,10 @@ export type CaseExceptionKind = (typeof CASE_EXCEPTION_KINDS)[number];
  * 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: Record<CaseExceptionKind, CaseVerdict | null> = {
   [COUNTERPART_ABSENT]: "incomplete",
@@ -750,15 +819,28 @@ const EXCEPTION_VERDICT: Record<CaseExceptionKind, CaseVerdict | null> = {
   [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: ReadonlySet<string> = new Set([
+  "partial",
+  "incomplete",
+  "failed",
+  "malformed",
+]);
+
 // ---- Inputs -----------------------------------------------------------------
 
 /**
@@ -804,11 +886,18 @@ export interface CaseException {
    * (v1.17, A20), and it is how many were set aside.
    */
   count?: number;
-  /** The pack's own bundle verdict, for `PACK_BUNDLE_NOT_VERIFIED`. */
+  /** The pack's case grade, for `PACK_GRADE_NOT_VERIFIED`. */
   status?: CaseVerdict;
+  /**
+   * The 5.4.5 cause kinds of the grade that decided the case grade, for
+   * `PACK_GRADE_NOT_VERIFIED`, in the grade's order. Empty where the grade was
+   * not computed (an unreadable body, a body that is not one of the two
+   * event-carrying ones, a verifier that graded too few records).
+   */
+  causes?: PackGradeCauseKind[];
   /**
    * What the bundle verifier said, as it said it, for the kinds that carry a
-   * verifier's grading: `PACK_BUNDLE_NOT_VERIFIED` and the three record kinds
+   * verifier's grading: `PACK_GRADE_NOT_VERIFIED` and the three record kinds
    * graded on the record's own envelope and content.
    */
   reasons?: string[];
@@ -830,6 +919,54 @@ export interface CaseRecordReading {
   findings: string[];
   failedChecks: string[];
   counterparts: string[];
+  /**
+   * The role the pack's v2 declaration signs for this record, `handoff` or
+   * `step`, or `null` where the pack's declaration is absent, unreadable or
+   * v1, or does not declare the record (5.5.1 v1.20).
+   */
+  role: DeclarationRole | null;
+}
+
+/**
+ * One NOTE on the reading (5.5.3 v1.20): something true a reader needs and
+ * nothing a reader could not tell, so it carries no contribution.
+ */
+export interface CaseNote {
+  kind: CaseNoteKind;
+  /** Which pack, by the reader's own name for it. */
+  packRef: string;
+  /**
+   * For `CONTENT_WITHHELD_BY_DECLARATION`, how many of the pack's records its
+   * declaration withholds.
+   */
+  count?: number;
+}
+
+/**
+ * One pack as the reading read it, in the order the reader was given them
+ * (5.5.4 v1.20). A surface names a pack by `signingKey`, the key that signed
+ * its wrapper, and never by an organization (D10).
+ */
+export interface CasePackReading {
+  ref: string;
+  /** The wrapper key, normalized, or `null` where this reader could not read it. */
+  signingKey: string | null;
+  /**
+   * The case grade (5.5.1 step 1), or `null` where the wrapper did not hold or
+   * the key could not be read.
+   */
+  grade: PackVerdict | null;
+  /**
+   * Records withheld by the pack's declaration (5.4.5): in scope for their
+   * signature and commitment only. Never counted as verified records.
+   */
+  recordsWithheld: number;
+  /**
+   * `sanning.declaration/v1`, `sanning.declaration/v2`, or `null` where the
+   * pack carries no declaration, one this reader does not know, or a body this
+   * reader does not read.
+   */
+  declarationVersion: string | null;
 }
 
 export interface CaseReading {
@@ -873,6 +1010,10 @@ export interface CaseReading {
    * checked packs, which is false.
    */
   onChainChecked: boolean;
+  /** The NOTEs, in pack order (5.5.3 v1.20). No contribution. */
+  notes: CaseNote[];
+  /** One reading per pack, in the order the reader was given them. */
+  packs: CasePackReading[];
 }
 
 // ---- The reading ------------------------------------------------------------
@@ -919,6 +1060,24 @@ const wrapperHolds = (result: EvidenceBundleResult): boolean =>
  * 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: readonly string[], withoutMap: readonly string[]): string[] =>
+  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: CasePack["content"]): boolean {
+  if (content === null || content === undefined) return false;
+  if (content instanceof Map) return content.size > 0;
+  return Object.keys(content as object).length > 0;
+}
+
 const bundleReasons = (result: EvidenceBundleResult): string[] => [
   ...result.errors,
   ...(result.stamps ?? []).flatMap((stamp) => stamp.errors),
@@ -955,8 +1114,13 @@ function underQuarantine(specVersion: unknown): boolean {
 /**
  * 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
@@ -968,13 +1132,26 @@ function underQuarantine(specVersion: unknown): boolean {
 function verdictOf(
   exceptions: readonly CaseException[],
   contributions: readonly [string, CaseVerdict][],
+  holdsPacks = true,
 ): CaseVerdict {
-  // 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";
+  // 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: CaseVerdict = outcomes.size === 1 ? [...outcomes][0] : "mixed";
+  const verdict: CaseVerdict = 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(", ")}`,
@@ -1013,28 +1190,40 @@ function verdictOf(
 export async function readCase(
   packs: readonly CasePack[],
 ): Promise<CaseReading> {
-  const exceptions: CaseException[] = [];
-  const contributions: [string, CaseVerdict][] = [];
+  // 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: (CaseException | null)[] = [];
+  const contributions: ([string, CaseVerdict] | null)[] = [];
 
   const note = (
     kind: CaseExceptionKind,
     fields: Omit<CaseException, "kind"> = {},
   ) => {
     exceptions.push({ kind, ...fields });
-    // `null` is PACK_BUNDLE_NOT_VERIFIED: the pack's own verdict, never verified.
-    const contribution = EXCEPTION_VERDICT[kind] ?? (fields.status as CaseVerdict);
+    // `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 as string;
+      contribution = GRADE_CONTRIBUTES.has(status) ? (status as CaseVerdict) : "incomplete";
+    }
     contributions.push([fields.eventId ?? fields.packRef ?? "case", contribution]);
   };
 
   if (packs.length === 0) {
     note(CASE_HOLDS_NO_PACKS);
+    const named = exceptions as CaseException[];
+    const contributed = contributions as [string, CaseVerdict][];
     return {
-      verdict: verdictOf(exceptions, contributions),
-      exceptions,
+      verdict: verdictOf(named, contributed, false),
+      exceptions: named,
       records: [],
-      contributions,
+      contributions: contributed,
       handoffRecords: 0,
       onChainChecked: false,
+      notes: [],
+      packs: [],
     };
   }
 
@@ -1079,6 +1268,20 @@ export async function readCase(
   // 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<string>();
+  // One reading per pack, in the order the reader was given them (5.5.4 v1.20).
+  const packReadings: CasePackReading[] = [];
+  // The NOTEs (5.5.3 v1.20), with the pack position they are about.
+  const caseNotes: { position: number; note: CaseNote }[] = [];
+  // 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<number, Map<string, DeclarationRole>>();
+  // The undeclared packs' slots, settled after the pile is read.
+  const undeclaredSlots: {
+    exceptionAt: number;
+    contributionAt: number;
+    position: number;
+    ref: string;
+  }[] = [];
   // 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
@@ -1095,6 +1298,13 @@ export async function readCase(
       // 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;
     }
 
@@ -1110,40 +1320,40 @@ export async function readCase(
         | 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, {
-        packRef: pack.ref,
-        status: verified.status as CaseVerdict,
-        reasons: bundleReasons(verified),
+    if (coSignaturesPresent(pack.bundle)) {
+      // A NOTE, with no contribution (5.5.3 v1.20, proof#148): the wrapper's
+      // co_signatures verifies nothing and sits outside its signed scope, so
+      // the case reading names it rather than moving anything on its account.
+      caseNotes.push({
+        position,
+        note: { kind: CO_SIGNATURES_PRESENT, packRef: pack.ref },
       });
     }
-    // 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") continue;
 
     const bodyType = bodyTypeOf(pack.bundle);
-    if (!(CASE_BODY_TYPES as readonly unknown[]).includes(bodyType)) {
-      // `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
-      // a repair (evidence-bundle.md 5.5.1 step 1 says so too). What this exit
-      // costs is that pack's RECORDS, and it is named every time. It no longer
-      // costs the pack's KEY: that was read above.
-      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
@@ -1151,50 +1361,136 @@ export async function readCase(
     // 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
+    // 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: 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, {
+    // `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 as readonly unknown[]).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: DeclarationCheck | null = null;
+    let full: PackGrade | null = null;
+    let causes: PackGradeCauseKind[] = [];
+    let grade: PackVerdict;
+    if (signed.status === "malformed") {
+      grade = "malformed";
+    } else if (!knownBody) {
+      grade = signed.status as PackVerdict;
+    } else if (ungraded) {
+      grade = signed.status === "verified" ? "malformed" : (signed.status as PackVerdict);
+    } 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: grade as CaseVerdict,
+        causes,
+        reasons,
+      });
+    }
+    if (verified.status === "failed" && signed.status !== "failed") {
+      note(PACK_BUNDLE_CONTENT_DEPENDENT, {
         packRef: pack.ref,
-        status: verified.status as CaseVerdict,
-        reasons: [
-          `this verifier graded ${verified.events.length} of the ` +
-            `${records.length} record(s) the pack holds, so none of them is read`,
-        ],
+        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 (signed.status === "malformed") continue;
+
+    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
+      // a repair (evidence-bundle.md 5.5.1 step 1 says so too). What this exit
+      // costs is that pack's RECORDS, and it is named every time. It no longer
+      // costs the pack's KEY: that was read above.
+      note(PACK_BODY_TYPE_UNKNOWN, { packRef: pack.ref });
       continue;
     }
+    // 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 as DeclarationCheck;
     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
@@ -1202,14 +1498,25 @@ export async function readCase(
       // every case, so one broken pair beside two honest declarations would
       // 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
       // the holder writes it.
       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
@@ -1218,6 +1525,7 @@ export async function readCase(
     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;
@@ -1244,22 +1552,32 @@ export async function readCase(
         });
         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],
+        });
+      } 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 (
-        !(graded.inclusionOk && graded.checkpointBound) ||
-        (!graded.ok && graded.contentOk !== false)
+        !(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({
@@ -1290,6 +1608,7 @@ export async function readCase(
       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
@@ -1303,10 +1622,14 @@ export async function readCase(
     // `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 });
@@ -1408,18 +1731,57 @@ export async function readCase(
     }
   }
 
-  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] as CaseVerdict];
+    } else {
+      caseNotes.push({ position: slot.position, note: { kind: PACK_UNDECLARED, packRef: slot.ref } });
+    }
+  }
+  const named = exceptions.filter((e): e is CaseException => e !== null);
+  const contributed = contributions.filter((c): c is [string, CaseVerdict] => 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: unknown): string | null {
+  const at = (v: unknown, k: string): unknown =>
+    typeof v === "object" && v !== null && !Array.isArray(v)
+      ? (v as Record<string, unknown>)[k]
+      : undefined;
+  const declaration = at(at(bundle, "body"), "declaration");
+  if (typeof declaration !== "object" || declaration === null || Array.isArray(declaration)) {
+    return null;
+  }
+  const version = (declaration as Record<string, unknown>)["declaration_version"];
+  return version === DECLARATION_VERSION || version === DECLARATION_VERSION_V2 ? version : null;
+}
+
 // ---- Presentation (optional) ------------------------------------------------
 
 /**
@@ -1536,13 +1898,21 @@ export function renderException(exception: CaseException): string {
         "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 ` +
@@ -1561,6 +1931,14 @@ export function renderException(exception: CaseException): string {
         "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 ` +
@@ -1568,47 +1946,209 @@ export function renderException(exception: CaseException): string {
       );
     case CASE_HOLDS_NO_PACKS:
       return "this case holds no packs";
-    case CASE_HOLDS_NO_HANDOFF_RECORDS:
+    default:
+      return exception.kind;
+  }
+}
+
+/** The house wording for one NOTE. Offered, not imposed, as `renderException` is. */
+export function renderCaseNote(note: CaseNote): string {
+  switch (note.kind) {
+    case CONTENT_WITHHELD_BY_DECLARATION:
       return (
-        "no record this verifier read in this case is a hand-off record, " +
-        "so no hand-off was verified"
+        `${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`;
+    case CO_SIGNATURES_PRESENT:
+      return (
+        `${note.packRef} carries unverified co-signatures in its wrapper; ` +
+        "they are not part of the evidence"
       );
     default:
-      return exception.kind;
+      return (note as CaseNote).kind;
   }
 }
 
 /**
- * One line a surface can print for a whole case.
- *
- * 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.
+ * 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.
+ *
+ * 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: CaseReading): string {
-  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") {
+  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.",
+    );
+  }
+  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: Readonly<Record<string, string>> = {
+  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 `verified` text at v1.28, A35), the same for every
+ * drop. `pending` and `not_found` never head a case reading: they are
+ * witness states. `verified` is the base sentence, printed alone where the
+ * drop holds no hand-off record; a caller reads `caseReliance` for
+ * `verified`, never this mapping directly.
+ */
+export const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>> = {
+  verified:
+    "Every pack in this drop is genuine, unaltered, and matches its own " +
+    "signed declaration. Every record in it was signed by its holder's " +
+    "key. This was read offline, on this device. It does not say this " +
+    "drop holds everything that was 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 clause a `verified` drop that holds a hand-off record gains, inserted
+ * after `CASE_RELIANCE`'s first sentence (5.5.6, A35). Never printed alone,
+ * and never where `handoffRecords` is zero: most drops hold one agent's
+ * pack and no hand-off to say anything about.
+ */
+export const CASE_RELIANCE_HANDOFF_CLAUSE =
+  "Every hand-off with both sides in this drop is intact.";
+
+/**
+ * What a reader may rely on for one case reading (5.5.6 v1.28, A35), byte
+ * for byte the text `case_reliance`'s Python sibling returns.
+ *
+ * For every word but `verified` this is `CASE_RELIANCE` unchanged. For
+ * `verified`, the hand-off clause is inserted after the first sentence
+ * where `handoffRecords` is not zero, and left out where it is zero: the
+ * base sentence never claims a hand-off the drop does not hold.
+ */
+export function caseReliance(verdict: CaseVerdict, handoffRecords: number): string {
+  if (verdict === "verified" && handoffRecords > 0) {
     return (
-      `this case verifies across ${reading.records.length} record(s): ` +
-      `${n} hand-off record(s), every one matched, no exceptions` +
-      scope
+      "Every pack in this drop is genuine, unaltered, and matches its own " +
+      "signed declaration. Every hand-off with both sides in this drop is " +
+      "intact. Every record in it was signed by its holder's key. This " +
+      "was read offline, on this device. It does not say this drop holds " +
+      "everything that was recorded."
     );
   }
-  return (
-    `this case reads ${reading.verdict.toUpperCase()} over ${n} hand-off ` +
-    `record(s), with ${reading.exceptions.length} exception(s)` +
-    scope
-  );
+  return CASE_RELIANCE[verdict];
+}
+
+/** 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",
+} as const;
+export type WitnessState = keyof typeof WITNESS_STATES;
+
+/**
+ * The witness line: a lookup of the public record, reported beside the
+ * headline and never in it (D7). It never raises or lowers the headline and
+ * never changes its title. `reasons` says why a `not_checked` line did not
+ * settle, in a fixed order; `services` names each service that answered, as
+ * the URL the lookup used: named, never trusted (6).
+ */
+export interface WitnessLine {
+  state: WitnessState;
+  reasons: string[];
+  services: string[];
+  /**
+   * Witness times a pack caches that no lookup settled, as `[blockHeight,
+   * blockTime]`, distinct and in time order (5.6.6, v1.25, A30). Printed labelled
+   * not checked, and never as a time a reader may rely on. Absent reads as none.
+   */
+  cached?: [number, number][];
+  /**
+   * Witness times the public record returned where they matched a pack's
+   * cache, distinct and in time order. The gateway's answer, named with the
+   * service, never the cache's value. Absent reads as none.
+   */
+  recorded?: [number, number][];
+}
+
+/** The line printed where no lookup ran, which is every reading this kernel produces on its own. */
+export const WITNESS_NOT_LOOKED_UP: Readonly<WitnessLine> = Object.freeze({
+  state: "not_checked",
+  reasons: ["no lookup was run"],
+  services: [],
+});
+
+/** The witness line as both kernels print it. */
+/** How a witness time a pack caches is printed where nothing checked it (5.5.6, 5.6.6, v1.25, A30). */
+export const WITNESS_TIME_CACHED = "the pack dates the witness, not checked";
+/** How a witness time the public record returned is printed where it matched the cache. */
+export const WITNESS_TIME_RECORDED = "the public record dates the witness";
+
+function witnessTimes(times: readonly [number, number][]): string {
+  return times.map(([h, t]) => renderWitnessTime(h, t)).join(", ");
+}
+
+export function renderWitnessLine(line: WitnessLine): string {
+  let text = `Witness: ${WITNESS_STATES[line.state]}`;
+  const parts = [...line.reasons];
+  if (line.cached && line.cached.length > 0) parts.push(`${WITNESS_TIME_CACHED}: ${witnessTimes(line.cached)}`);
+  if (line.recorded && line.recorded.length > 0) {
+    parts.push(`${WITNESS_TIME_RECORDED}: ${witnessTimes(line.recorded)}`);
+  }
+  if (parts.length > 0) text += `: ${parts.join("; ")}`;
+  if (line.services.length > 0) text += ` (answered: ${line.services.join(", ")})`;
+  return text;
 }