@sanning/proof 0.19.1 → 0.20.0

package/src/claims.ts

@@ -0,0 +1,1253 @@
+// Six claims, three verdicts, and the person layer (`evidence-bundle.md` section 3).
+//
+// Every detailed kind a reader emits (a bundle problem, a pack grade cause, a declaration
+// problem, a case exception, a record-layer reason) maps here, and only here, to one claim and
+// one state. A verdict is read off the claims and nothing else:
+//
+// - `failed`: a claim is `disproven`. `reason_kind` is `nonconforming` when the only
+//   disproven claim is `follows_rules`, otherwise `changed`.
+// - `incomplete`: nothing is disproven and a claim is `not_proven`.
+// - `verified`: every claim in scope is `proven`.
+//
+// The person layer (`renderPerson`) reads the machine layer this module builds, never a
+// kernel object, so a surface holding only `--json` renders the same words. The Python twin
+// is `src/sanning_proof/claims.py`; both are held to one output by `cross-kernel/`.
+
+import type { EnvelopeFault } from "./types.js";
+
+export const CLAIMS = [
+  "signed",
+  "unchanged",
+  "witnessed",
+  "complete",
+  "agreed",
+  "follows_rules",
+] as const;
+export type Claim = (typeof CLAIMS)[number];
+
+export const CLAIM_LABELS: Readonly<Record<Claim, string>> = Object.freeze({
+  signed: "Signed",
+  unchanged: "Unchanged",
+  witnessed: "Witnessed",
+  complete: "Complete",
+  agreed: "Agreed",
+  follows_rules: "Follows the rules",
+});
+
+/** The question each claim answers, as a page prints it beside the label. */
+export const CLAIM_QUESTIONS: Readonly<Record<Claim, string>> = Object.freeze({
+  signed: "Did the key the pack or record names sign it?",
+  unchanged: "Do the bytes agree with what was signed?",
+  witnessed: "Does a stamp cover each record?",
+  complete: "Does the pack hold everything its own signed declaration and its stamp say it holds?",
+  agreed: "Do the two sides of each hand-off agree?",
+  follows_rules: "Does each record follow the vocabulary it names?",
+});
+
+// `not_in_scope` is never printed.
+export const CLAIM_STATES = ["proven", "disproven", "not_proven", "not_in_scope"] as const;
+export type ClaimState = (typeof CLAIM_STATES)[number];
+export const NOT_PROVEN_REASONS = ["missing", "unreadable", "not_checked"] as const;
+export type NotProvenReason = (typeof NOT_PROVEN_REASONS)[number];
+/** Why a claim is `not_in_scope`: nothing in the pack or case is about it. */
+export const NOT_IN_SCOPE_REASONS = [
+  "no_declaration",
+  "no_declaration_and_no_handoff",
+  "no_handoff",
+  "no_agent_records",
+  "no_agent_or_handoff_records",
+] as const;
+export type NotInScopeReason = (typeof NOT_IN_SCOPE_REASONS)[number];
+
+export const VERDICTS = ["verified", "failed", "incomplete"] as const;
+export type Verdict = (typeof VERDICTS)[number];
+export const REASON_KINDS = ["changed", "nonconforming"] as const;
+export type ReasonKind = (typeof REASON_KINDS)[number];
+
+// One display title and one colour per verdict, on every surface.
+export const VERDICT_TITLES: Readonly<Record<Verdict, string>> = Object.freeze({
+  verified: "Verified",
+  failed: "Failed",
+  incomplete: "Incomplete",
+});
+export const VERDICT_COLOURS: Readonly<Record<Verdict, string>> = Object.freeze({
+  verified: "green",
+  failed: "red",
+  incomplete: "neutral",
+});
+
+/** The headline the person layer prints, by verdict and reason kind (`status:reason_kind`). */
+export const PERSON_TITLES: Readonly<Record<string, string>> = Object.freeze({
+  verified: "Verified",
+  "failed:changed": "Failed: do not rely on this evidence.",
+  "failed:nonconforming": "Failed: a record does not follow the rules.",
+  incomplete: "Incomplete: not everything could be checked.",
+});
+
+/** The same headline as a word and a sentence, for a surface that sets them apart. */
+export const PERSON_TITLE_PARTS: Readonly<Record<string, { word: string; sentence: string | null }>> = Object.freeze({
+  verified: { word: "Verified", sentence: null },
+  "failed:changed": { word: "Failed", sentence: "Do not rely on this evidence." },
+  "failed:nonconforming": { word: "Failed", sentence: "A record does not follow the rules." },
+  incomplete: { word: "Incomplete", sentence: "Not everything could be checked." },
+});
+
+export const SANDBOX_PERSON_LINE = "these records are sandbox records, not production evidence.";
+
+const D = "disproven";
+const N = "not_proven";
+
+type Mapping = readonly [Claim, ClaimState, NotProvenReason | null];
+
+/** kind -> [claim, state, reason]. The reason is set only on `not_proven`. */
+export const KIND_CLAIMS: Readonly<Record<string, Mapping>> = Object.freeze({
+  // Case exceptions (section 5.5.3).
+  pack_does_not_verify: ["signed", D, null],
+  record_envelope_does_not_verify: ["signed", D, null],
+  pair_failed: ["agreed", D, null],
+  record_does_not_verify_in_its_pack: ["unchanged", D, null],
+  record_content_mismatch: ["unchanged", D, null],
+  pack_declaration_deviates: ["complete", D, null],
+  record_nonconforming: ["follows_rules", D, null],
+  record_malformed: ["agreed", N, "unreadable"],
+  record_bytes_withheld: ["unchanged", N, "missing"],
+  record_bytes_unreadable: ["unchanged", N, "unreadable"],
+  record_content_dependent: ["unchanged", N, "not_checked"],
+  pack_bundle_content_dependent: ["unchanged", N, "not_checked"],
+  pack_declaration_content_dependent: ["unchanged", N, "not_checked"],
+  counterpart_absent: ["agreed", N, "missing"],
+  counterpart_absent_from_counterparty_records: ["agreed", N, "missing"],
+  counterpart_absent_signer_unknown: ["agreed", N, "missing"],
+  counterpart_ambiguous: ["agreed", N, "not_checked"],
+  counterpart_malformed: ["agreed", N, "unreadable"],
+  counterpart_nonconforming: ["agreed", N, "unreadable"],
+  record_unclaimed_by_its_pack: ["agreed", N, "not_checked"],
+  pack_declaration_unreadable: ["complete", N, "unreadable"],
+  pack_undeclared: ["complete", N, "not_checked"],
+  pack_body_type_unknown: ["complete", N, "not_checked"],
+  pack_holds_no_records: ["complete", N, "missing"],
+  pack_key_unreadable: ["signed", N, "unreadable"],
+  record_profile_quarantined: ["follows_rules", N, "not_checked"],
+  case_holds_no_packs: ["complete", N, "missing"],
+  // Pack grade causes (section 5.4.5).
+  records_omitted: ["complete", N, "missing"],
+  records_surplus: ["complete", N, "not_checked"],
+  leaf_count_unreadable: ["complete", N, "unreadable"],
+  no_disclosure: ["unchanged", N, "missing"],
+  missing_disclosure: ["unchanged", N, "missing"],
+  unreadable_disclosure: ["unchanged", N, "unreadable"],
+  unaccounted_disclosure: ["complete", N, "not_checked"],
+  declaration_deviation: ["complete", D, null],
+  declaration_nonconforming: ["follows_rules", D, null],
+  declaration_content_dependent: ["unchanged", N, "not_checked"],
+  agent_record_nonconforming: ["follows_rules", D, null],
+  // `agent_record_incomplete` maps through its record-layer reason (RECORD_REASON_CLAIMS).
+  // Bundle problems (bundleProblems below) and the pack's own declaration.
+  pack_unreadable: ["signed", N, "unreadable"],
+  pack_version_unknown: ["follows_rules", N, "not_checked"],
+  pack_body_unreadable: ["complete", N, "unreadable"],
+  pack_body_hash_mismatch: ["unchanged", D, null],
+  generated_at_nonconforming: ["follows_rules", D, null],
+  record_bytes_unbound: ["unchanged", D, null],
+  record_bytes_nonconforming: ["follows_rules", D, null],
+  record_envelope_nonconforming: ["follows_rules", D, null],
+  record_envelope_unreadable: ["signed", N, "unreadable"],
+  record_key_unreadable: ["signed", N, "unreadable"],
+  record_envelope_version_unknown: ["follows_rules", N, "not_checked"],
+  record_not_covered: ["witnessed", D, null],
+  stamp_signature_failed: ["signed", D, null],
+  stamp_does_not_verify: ["unchanged", D, null],
+  stamp_unwitnessed: ["witnessed", N, "missing"],
+  records_unstamped: ["witnessed", N, "missing"],
+  stamp_absent: ["witnessed", N, "missing"],
+  anchor_ref_nonconforming: ["follows_rules", D, null],
+  witness_differs: ["witnessed", D, null],
+  witness_time_differs: ["witnessed", D, null],
+  export_does_not_verify: ["unchanged", D, null],
+  export_source_nonconforming: ["follows_rules", D, null],
+  attestation_signature_failed: ["signed", D, null],
+  attestation_nonconforming: ["follows_rules", D, null],
+  export_not_checked: ["complete", N, "not_checked"],
+  bundle_does_not_verify: ["unchanged", D, null],
+  bundle_not_checked: ["complete", N, "not_checked"],
+  records_not_bound: ["unchanged", N, "not_checked"],
+  declaration_not_checked: ["complete", N, "not_checked"],
+});
+
+// Every reason the record layer can give (agent-events.md section 10.1), to one claim and
+// state. The two reasons that read `incomplete` are not proven; every other reason reads
+// `failed` and disproves `follows_rules`.
+const RECORD_FAILED_REASONS = [
+  "event_type_not_in_set",
+  "event_schema_misplaced",
+  "event_schema_missing",
+  "event_schema_invalid",
+  "unknown_field",
+  "missing_field",
+  "bad_value",
+  "hidden_field_present",
+  "revealed_field_absent",
+  "revealed_field_unlisted",
+  "capture_not_at_head",
+  "file_parts_exceed_parts",
+  "unchecked_held_parts_missing",
+  "unchecked_held_parts_mismatch",
+  "unchecked_held_parts_exceed_file_parts",
+  "part_index_out_of_range",
+  "closing_count_mismatch",
+  "artifact_reason_mismatch",
+  "pair_type_mismatch",
+  "pair_run_mismatch",
+  "pair_call_mismatch",
+  "pair_field_mismatch",
+];
+export const RECORD_REASON_CLAIMS: Readonly<Record<string, Mapping>> = Object.freeze({
+  ...Object.fromEntries(
+    RECORD_FAILED_REASONS.map((r) => [r, ["follows_rules", D, null] as Mapping]),
+  ),
+  event_schema_unknown: ["follows_rules", N, "not_checked"],
+  listed_record_absent: ["complete", N, "missing"],
+});
+
+/** One plain line per record-layer rule. */
+export const RECORD_REASON_LINES: Readonly<Record<string, string>> = Object.freeze({
+  event_type_not_in_set: "Its type is not one its vocabulary defines.",
+  event_schema_misplaced: "It names its vocabulary in the wrong place.",
+  event_schema_missing: "It does not name the vocabulary it follows.",
+  event_schema_invalid: "The vocabulary version it names is not written as a version.",
+  event_schema_unknown: "It uses a newer vocabulary version than this verifier knows.",
+  unknown_field: "It carries a field its vocabulary does not define.",
+  missing_field: "It is missing a field its vocabulary requires.",
+  bad_value: "A field holds a value its vocabulary does not allow.",
+  hidden_field_present: "It carries a field it says is hidden.",
+  revealed_field_absent: "It says a field is revealed and does not carry it.",
+  revealed_field_unlisted: "It carries a revealed field it does not list.",
+  capture_not_at_head:
+    "It says what its adapter captures, and it is not the first record of its run.",
+  file_parts_exceed_parts: "It counts more file parts than parts.",
+  unchecked_held_parts_missing: "It does not say how many held parts were not checked.",
+  unchecked_held_parts_mismatch:
+    "Its count of held parts that were not checked does not match its list.",
+  unchecked_held_parts_exceed_file_parts: "It counts more unchecked held parts than file parts.",
+  part_index_out_of_range: "It names a part the message does not have.",
+  closing_count_mismatch: "Its closing counts do not match the records it lists.",
+  artifact_reason_mismatch: "Its file reason does not match its file role.",
+  pair_type_mismatch: "The record it names as its start is another kind of operation.",
+  pair_run_mismatch: "The record it names as its start belongs to another run.",
+  pair_call_mismatch: "The record it names as its start belongs to another call.",
+  pair_field_mismatch: "It and its start disagree on a field they must share.",
+  listed_record_absent: "The run's closing record lists records that are not in the pack.",
+});
+
+/** Every record-layer finding is a note (agent-events.md section 10.1). One plain sentence each. */
+export const NOTE_FINDINGS: Readonly<Record<string, string>> = Object.freeze({
+  not_an_agent_record: "the record is not an agent record",
+  plumbing: "the record carries fields about the recording software, not the agent",
+  content_scrubbed: "the record's content was removed before it was signed",
+  start_absent: "the record that started this operation is not held",
+  start_ambiguous: "more than one record could be the start of this operation",
+  start_not_captured: "end only; start not observed by this adapter",
+  start_undeclared: "the record ends an operation and does not name its start",
+  unended: "the operation this record starts has no end held",
+  ended_more_than_once: "the operation this record starts is ended more than once",
+  completed_with_open_operation: "the run closed as completed while an operation in it was open",
+  handoff_parts_mismatch: "the two records of this message count its parts differently",
+  data_mode_mixed: "the run's records were sent to Sanning in more than one data mode",
+  seq_duplicate: "two records in the run hold the same position",
+  ran_after_refusal: "the tool ran after its approval refused it",
+  seq_gap:
+    "the run may be incomplete: no verified record is held at the position before this record",
+  closing_not_held: "the run may be incomplete: the promised closing record is not held",
+});
+
+function n(count: number, one: string, many?: string): string {
+  return `${count} ${count === 1 ? one : (many ?? `${one}s`)}`;
+}
+
+// Python's `str()` of a value a template reads, so both kernels fill a gap alike.
+function pyStr(v: unknown): string {
+  if (v === null || v === undefined) return "None";
+  if (v === true) return "True";
+  if (v === false) return "False";
+  return String(v);
+}
+
+const A_PACK_CHANGED = "Do not rely on this pack. Ask the sender how it changed after it was signed.";
+const A_RECORD_CHANGED =
+  "Do not rely on this record. Ask the sender how it changed after it was signed.";
+const A_NEW_COPY = "Ask the sender for a new copy of the pack.";
+const A_REPORT = "Ask the sender to report the record to whoever makes their recording software.";
+const A_UPDATE = "Update the verifier and run it again.";
+const A_LOGS = "Ask the sender for the logs/ folder.";
+const A_DECLARATION = "Do not rely on this pack. Ask the sender why it differs from its declaration.";
+const A_OWN_LOGS = "Ask the sender for the event bytes from their own logs.";
+const A_COUNTERPART = "Ask the holder of key {key} for their pack.";
+const A_WAIT = "Wait for the stamp, then run it again.";
+const A_WITNESSING = "Wait for the stamp to reach the public record, then run it again.";
+const A_STAMP = "Ask the sender for the pack with its stamp.";
+const A_FIX = "Ask the sender to fix the software that made the pack, then send it again.";
+const A_EXPORT_CHANGED =
+  "Do not rely on this export. Ask the issuer how it changed after it was signed.";
+const A_EXPORT_FIX =
+  "Ask the issuer to fix the software that made the export, then send it again.";
+const A_HANDOFF = "Do not rely on this hand-off. Ask both sides which message was sent.";
+const A_WITNESS = "Do not rely on this pack. Ask the sender which stamp the public record holds.";
+
+// Bytes handed in beside a pack that disagree with what was signed: a disproof that
+// rests on bytes nobody signed reads with these words, whatever its kind.
+const L_OUTSIDE =
+  "The bytes handed in beside the pack do not match what was signed. Anyone could have supplied them.";
+const L_NO_STAMP = "No stamp covers {them}.";
+const L_UNALTERED = " Nothing was proven altered.";
+
+// kind -> [line, next action]. A line is a template over the problem's own values:
+// `{count}`, `{of}`, `{presented}`, `{key}`; the `{records}` placeholder is the
+// number of records the problems of that kind are about, counted.
+const WORDS: Readonly<Record<string, readonly [string, string]>> = Object.freeze({
+  pack_does_not_verify: ["The pack's signature does not match its contents.", A_PACK_CHANGED],
+  record_envelope_does_not_verify: ["A record's signature does not verify.", A_RECORD_CHANGED],
+  pair_failed: ["The two sides of a hand-off do not agree.", A_HANDOFF],
+  record_does_not_verify_in_its_pack: ["A record does not match the pack it is in.", A_RECORD_CHANGED],
+  record_content_mismatch: [
+    "The event bytes do not match what the record signed.",
+    "Do not rely on this record. Ask the sender how the bytes changed.",
+  ],
+  pack_declaration_deviates: [
+    "The pack does not hold what its own signed declaration says.",
+    A_DECLARATION,
+  ],
+  record_nonconforming: [
+    "A hand-off record does not follow the rules of its vocabulary. Nothing was proven altered.",
+    A_REPORT,
+  ],
+  record_malformed: ["A record that claims to be a hand-off cannot be read as one.", A_REPORT],
+  record_bytes_withheld: [
+    "Its record bytes are not in the pack.",
+    "Ask the sender for the pack with its record bytes.",
+  ],
+  record_bytes_unreadable: ["Its record bytes cannot be read.", A_NEW_COPY],
+  record_content_dependent: [L_OUTSIDE, A_OWN_LOGS],
+  pack_bundle_content_dependent: [L_OUTSIDE, A_OWN_LOGS],
+  pack_declaration_content_dependent: [L_OUTSIDE, A_OWN_LOGS],
+  counterpart_absent: ["The other side of this hand-off is not in the case.", A_COUNTERPART],
+  counterpart_absent_from_counterparty_records: [
+    "The other side of this hand-off is not in the case.",
+    A_COUNTERPART,
+  ],
+  counterpart_absent_signer_unknown: [
+    "The other side of this hand-off is not in the case.",
+    A_COUNTERPART,
+  ],
+  counterpart_ambiguous: [
+    "More than one record could be the other side.",
+    "Ask the sender which record is the other side.",
+  ],
+  counterpart_malformed: [
+    "The other side cannot be read.",
+    "Ask the holder of the other side for a new copy.",
+  ],
+  counterpart_nonconforming: [
+    "The other side cannot be read.",
+    "Ask the holder of the other side for a new copy.",
+  ],
+  record_unclaimed_by_its_pack: [
+    "The pack declares this record and names it in no hand-off.",
+    "Ask the sender whether it was meant to be handed over.",
+  ],
+  pack_declaration_unreadable: ["The pack's declaration cannot be read.", A_NEW_COPY],
+  pack_undeclared: [
+    "The pack does not say what it holds.",
+    "Ask the sender for a pack made with a declaration.",
+  ],
+  pack_body_type_unknown: ["This verifier does not read this kind of pack.", A_UPDATE],
+  pack_holds_no_records: [
+    "The pack holds no records this verifier can read.",
+    "Ask the sender for the pack again.",
+  ],
+  pack_key_unreadable: ["The key that signed the pack cannot be read.", A_NEW_COPY],
+  record_profile_quarantined: [
+    "The record uses a format this verifier does not read yet.",
+    A_UPDATE,
+  ],
+  case_holds_no_packs: ["The case holds no packs.", "Add the packs and run it again."],
+  records_omitted: [
+    "The stamp covers {of_records} and the pack holds {presented}.",
+    "Ask the sender for the missing records.",
+  ],
+  records_surplus: [
+    "The pack holds more records than its stamp covers.",
+    "Ask the sender which records the stamp covers.",
+  ],
+  leaf_count_unreadable: ["The stamp's record count cannot be read.", A_NEW_COPY],
+  no_disclosure: ["No event bytes are in the pack.", A_LOGS],
+  missing_disclosure: ["The event bytes of {count} of {of_records} are not in the pack.", A_LOGS],
+  unreadable_disclosure: [
+    "The event bytes of a record cannot be read.",
+    "Ask the sender for a new copy of the logs/ folder.",
+  ],
+  unaccounted_disclosure: [
+    "The pack holds event bytes that no record names.",
+    "Ask the sender what the extra files are.",
+  ],
+  declaration_deviation: [
+    "The pack does not hold what its own signed declaration says.",
+    A_DECLARATION,
+  ],
+  declaration_content_dependent: [L_OUTSIDE, A_OWN_LOGS],
+  declaration_nonconforming: [
+    "The pack's signed declaration does not follow its format." + L_UNALTERED,
+    A_FIX,
+  ],
+  agent_record_nonconforming: [
+    "{records_do} not follow the rules of {their} vocabulary. Nothing was proven altered.",
+    A_REPORT,
+  ],
+  pack_unreadable: ["The pack cannot be read, so its signature could not be checked.", A_NEW_COPY],
+  pack_version_unknown: ["This verifier does not know this pack's version.", A_UPDATE],
+  pack_body_unreadable: ["The pack's contents cannot be read.", A_NEW_COPY],
+  pack_body_hash_mismatch: ["The pack's contents do not match the hash it signed.", A_PACK_CHANGED],
+  generated_at_nonconforming: [
+    "The pack's signed wrapper gives its time in a form that does not follow the format." + L_UNALTERED,
+    A_FIX,
+  ],
+  record_bytes_unbound: [
+    "A record's bytes do not match what its signature covers.",
+    A_RECORD_CHANGED,
+  ],
+  record_envelope_nonconforming: [
+    "A record's signed envelope does not follow the envelope format." + L_UNALTERED,
+    A_FIX,
+  ],
+  record_envelope_unreadable: ["A record's envelope cannot be read.", A_NEW_COPY],
+  record_key_unreadable: ["The key that signed a record cannot be read.", A_NEW_COPY],
+  record_envelope_version_unknown: ["This verifier does not know the version of a record's envelope.", A_UPDATE],
+  record_bytes_nonconforming: ["A record's signed bytes do not follow the record format." + L_UNALTERED, A_FIX],
+  record_not_covered: ["A record is not covered by the stamp it names.", A_RECORD_CHANGED],
+  stamp_signature_failed: ["A stamp's signature does not verify.", A_PACK_CHANGED],
+  stamp_does_not_verify: ["A stamp does not match the records it covers.", A_PACK_CHANGED],
+  stamp_unwitnessed: ["The stamp that covers {them} names no public record.", A_WITNESSING],
+  records_unstamped: [L_NO_STAMP, A_WAIT],
+  stamp_absent: ["The pack does not hold the stamp that covers {them}.", A_STAMP],
+  anchor_ref_nonconforming: [
+    "A stamp names its public record in a form that does not follow the format." + L_UNALTERED,
+    A_FIX,
+  ],
+  witness_differs: ["The public record holds different bytes for a stamp.", A_WITNESS],
+  witness_time_differs: ["The public record dates a stamp differently from the pack.", A_WITNESS],
+  export_does_not_verify: ["The export does not match the evidence it carries.", A_EXPORT_CHANGED],
+  export_source_nonconforming: [
+    "The source bundle the export signed cannot be read as a pack." + L_UNALTERED,
+    A_EXPORT_FIX,
+  ],
+  attestation_signature_failed: ["An attestation's signature does not verify.", A_EXPORT_CHANGED],
+  attestation_nonconforming: [
+    "An attestation's signature verifies and a field in it does not follow the format." +
+      L_UNALTERED,
+    A_EXPORT_FIX,
+  ],
+  export_not_checked: [
+    "Part of the evidence this export carries could not be checked.",
+    "Ask the issuer for the export with its source bundle.",
+  ],
+  bundle_does_not_verify: ["The pack does not verify.", A_PACK_CHANGED],
+  bundle_not_checked: ["Part of the pack could not be checked.", A_NEW_COPY],
+  records_not_bound: [
+    "The event bytes of a record were not checked against what it signed.",
+    A_LOGS,
+  ],
+  declaration_not_checked: [
+    "The pack says its chains are complete and in order, and this verifier did not check that.",
+    A_NEW_COPY,
+  ],
+});
+
+// The words of an `agent_record_incomplete` cause, by its record-layer reason.
+/**
+ * Why a record's envelope does not verify (`ENVELOPE_FAULTS`), to the kind that says so.
+ * Read from the envelope layer's own classification, never from its prose.
+ */
+export const ENVELOPE_FAULT_KINDS: Readonly<Record<EnvelopeFault, string>> = Object.freeze({
+  not_an_envelope: "record_envelope_unreadable",
+  key_unreadable: "record_key_unreadable",
+  signature_failed: "record_envelope_does_not_verify",
+  payload_unbound: "record_bytes_unbound",
+  spec_version_unknown: "record_envelope_version_unknown",
+  nonconforming: "record_envelope_nonconforming",
+});
+
+// The words of a `pair_failed` problem, by the hand-off check that failed
+// (envelope-spec.md section 4.1).
+const PAIR_WORDS: Readonly<Record<string, readonly [string, string]>> = Object.freeze({
+  message_hash: ["The two sides of a hand-off signed different messages.", A_HANDOFF],
+  sequence: ["The two sides of a hand-off give it different sequence numbers.", A_HANDOFF],
+  self_handoff: [
+    "One key signed both sides of a hand-off.",
+    "Do not rely on this hand-off. Ask the sender who the other side was.",
+  ],
+  counterparty_named: [
+    "A side of a hand-off does not name the key that signed the other side.",
+    "Do not rely on this hand-off. Ask both sides who they handed it to.",
+  ],
+});
+
+const INCOMPLETE_WORDS: Readonly<Record<string, readonly [string, string]>> = Object.freeze({
+  event_schema_unknown: ["{records_use} a newer vocabulary version than this verifier knows.", A_UPDATE],
+  listed_record_absent: [
+    "The run's closing record lists {count_records} that {count_are} not in the pack.",
+    "Ask the sender for the run's other records.",
+  ],
+});
+
+/**
+ * What a problem is about: `[pack, record]` by position. `[p, null]` is a pack, `[null, null]`
+ * the case, and `[p, null, eventId]` a record pack `p` names and does not hold.
+ */
+export type ProblemItem = readonly [number | null, number | null] | readonly [number | null, null, string];
+
+/**
+ * One detailed kind, mapped to its claim and state. The optional values are what the
+ * person line reads; an absent one is `undefined`.
+ */
+export interface Problem {
+  readonly kind: string;
+  readonly claim: Claim;
+  readonly state: ClaimState;
+  readonly reason: NotProvenReason | null;
+  readonly items: readonly ProblemItem[];
+  readonly count?: number;
+  readonly of?: number;
+  readonly presented?: number;
+  readonly key?: string;
+  readonly rule?: string;
+}
+
+/** A problem as the machine layer carries it. */
+export interface ProblemJson {
+  kind: string;
+  claim: Claim;
+  state: ClaimState;
+  items: { pack: number | null; record: number | null; event_id?: string }[];
+  reason?: NotProvenReason;
+  count?: number;
+  of?: number;
+  presented?: number;
+  key?: string;
+  rule?: string;
+}
+
+const PROBLEM_VALUES = ["count", "of", "presented", "key", "rule"] as const;
+
+export function problemToJson(p: Problem): ProblemJson {
+  const out: ProblemJson = {
+    kind: p.kind,
+    claim: p.claim,
+    state: p.state,
+    items: p.items.map((i) => (i.length > 2 ? { pack: i[0], record: i[1], event_id: i[2] } : { pack: i[0], record: i[1] })),
+  };
+  if (p.reason !== null) out.reason = p.reason;
+  for (const name of PROBLEM_VALUES) {
+    const value = p[name];
+    if (value !== undefined && value !== null) (out as unknown as Record<string, unknown>)[name] = value;
+  }
+  return out;
+}
+
+export interface ProblemValues {
+  rule?: string | null;
+  count?: number | null;
+  of?: number | null;
+  presented?: number | null;
+  key?: string | null;
+}
+
+function lookup(table: Readonly<Record<string, Mapping>>, key: string): Mapping {
+  if (!Object.prototype.hasOwnProperty.call(table, key)) throw new Error(`KeyError: '${key}'`);
+  return table[key]!;
+}
+
+/**
+ * The `Problem` of a detailed kind. A kind with no mapping throws: a new kind is a
+ * decision, never a quiet `verified`. `rule` is a record-layer reason; for
+ * `agent_record_incomplete` it decides the claim.
+ */
+export function problem(
+  kind: string,
+  items: readonly ProblemItem[] = [],
+  values: ProblemValues = {},
+): Problem {
+  const rule = values.rule ?? undefined;
+  let mapping: Mapping;
+  if (kind === "agent_record_incomplete") {
+    mapping = lookup(RECORD_REASON_CLAIMS, rule ?? "");
+    if (mapping[1] === D) throw new Error(`'${rule}' disproves a record`);
+  } else if (kind === "agent_record_nonconforming") {
+    mapping = lookup(KIND_CLAIMS, kind);
+    if (rule !== undefined && lookup(RECORD_REASON_CLAIMS, rule)[1] !== D) {
+      throw new Error(`'${rule}' does not disprove a record`);
+    }
+  } else {
+    mapping = lookup(KIND_CLAIMS, kind);
+  }
+  const [claim, state, reason] = mapping;
+  const out: {
+    kind: string;
+    claim: Claim;
+    state: ClaimState;
+    reason: NotProvenReason | null;
+    items: readonly ProblemItem[];
+    count?: number;
+    of?: number;
+    presented?: number;
+    key?: string;
+    rule?: string;
+  } = { kind, claim, state, reason, items: [...items] };
+  if (values.count !== undefined && values.count !== null) out.count = values.count;
+  if (values.of !== undefined && values.of !== null) out.of = values.of;
+  if (values.presented !== undefined && values.presented !== null) out.presented = values.presented;
+  if (values.key !== undefined && values.key !== null) out.key = values.key;
+  if (rule !== undefined && rule !== null) out.rule = rule;
+  return out;
+}
+
+/** The same problem about other items. */
+export function withItems(p: Problem, items: readonly ProblemItem[]): Problem {
+  return { ...p, items: [...items] };
+}
+
+/**
+ * A disproof that rests on bytes nobody signed: the claim is `not_proven`
+ * (`not_checked`), never `disproven`.
+ */
+export function downgraded(p: Problem): Problem {
+  if (p.state !== D) return p;
+  return { ...p, state: N, reason: "not_checked" };
+}
+
+// Disproofs a lookup on the public record makes. They read no bytes handed in beside a pack,
+// so the reading without those bytes, which is offline, never needs to make them too.
+const PUBLIC_RECORD_KINDS: readonly string[] = ["witness_differs", "witness_time_differs"];
+
+/**
+ * The problems of a pack read with the bytes handed in beside it (`full`), where each
+ * disproof the same pack read without them (`signed`) does not also make is `downgraded`.
+ * A disproof only the signed reading makes is kept, and so is one the public record makes.
+ */
+export function restOnSigned(full: readonly Problem[], signed: readonly Problem[]): Problem[] {
+  const key = (p: Problem) =>
+    JSON.stringify([p.kind, p.claim, p.items, p.rule === undefined ? null : p.rule]);
+  const held = new Set(signed.filter((p) => p.state === D).map(key));
+  const out = full.map((p) =>
+    p.state !== D || held.has(key(p)) || PUBLIC_RECORD_KINDS.includes(p.kind) ? p : downgraded(p),
+  );
+  const kept = new Set(out.filter((p) => p.state === D).map(key));
+  for (const p of signed) if (p.state === D && !kept.has(key(p))) out.push(p);
+  return out;
+}
+
+/** One item a claim is about, with the names a person reads. */
+export interface ClaimItem {
+  pack: number | null;
+  record: number | null;
+  pack_ref: string | null;
+  event_id: string | null;
+}
+
+/** One claim as the machine layer carries it. */
+export interface ClaimEntry {
+  claim: Claim;
+  label: string;
+  question: string;
+  state: ClaimState;
+  items: ClaimItem[];
+  problems: ProblemJson[];
+  /** Why it is not proven, or, for `not_in_scope`, why nothing is about it. */
+  reason?: NotProvenReason | NotInScopeReason;
+}
+
+/** An item's `[pack_ref, event_id]`, the names a person reads. */
+export type Labels = (pack: number | null, record: number | null) => readonly [string | null, string | null];
+
+const NO_LABELS: Labels = () => [null, null];
+
+/**
+ * The claims, in claim order, as the machine layer carries them, each with its label and
+ * its question. A claim is in scope when it is named in `inScope` or a problem is about
+ * it; `signed`, `unchanged` and `witnessed` always are. A claim not in scope is left out,
+ * unless `notInScope` gives the reason, which it then carries as `not_in_scope`.
+ *
+ * `labels(pack, record)` gives an item's `[pack_ref, event_id]`; a record a pack names and
+ * does not hold carries its own `event_id`.
+ */
+export function claimsOf(
+  problems: readonly Problem[],
+  inScope: Iterable<string> = [],
+  options: { notInScope?: Readonly<Partial<Record<Claim, NotInScopeReason>>>; labels?: Labels } = {},
+): ClaimEntry[] {
+  const scope = new Set<string>(["signed", "unchanged", "witnessed", ...inScope]);
+  const label = options.labels ?? NO_LABELS;
+  const out: ClaimEntry[] = [];
+  for (const claim of CLAIMS) {
+    const mine = problems.filter((p) => p.claim === claim);
+    if (mine.length === 0 && !scope.has(claim)) {
+      const why = options.notInScope?.[claim];
+      if (why !== undefined) {
+        out.push({
+          claim,
+          label: CLAIM_LABELS[claim],
+          question: CLAIM_QUESTIONS[claim],
+          state: "not_in_scope",
+          reason: why,
+          items: [],
+          problems: [],
+        });
+      }
+      continue;
+    }
+    let state: ClaimState;
+    if (mine.some((p) => p.state === D)) state = D;
+    else if (mine.length > 0) state = N;
+    else state = "proven";
+    const shown = mine.filter((p) => p.state === state);
+    const items: ClaimItem[] = [];
+    for (const p of shown) {
+      for (const i of p.items) {
+        const [pack, record] = [i[0], i[1]];
+        const [packRef, eventId] = label(pack, record);
+        const item: ClaimItem = {
+          pack,
+          record,
+          pack_ref: packRef,
+          event_id: i.length > 2 ? (i[2] as string) : eventId,
+        };
+        if (
+          !items.some(
+            (x) =>
+              x.pack === item.pack &&
+              x.record === item.record &&
+              x.pack_ref === item.pack_ref &&
+              x.event_id === item.event_id,
+          )
+        ) {
+          items.push(item);
+        }
+      }
+    }
+    const entry: ClaimEntry = {
+      claim,
+      label: CLAIM_LABELS[claim],
+      question: CLAIM_QUESTIONS[claim],
+      state,
+      items,
+      problems: mine.map(problemToJson),
+    };
+    if (state === N) entry.reason = shown[0]!.reason ?? undefined;
+    out.push(entry);
+  }
+  return out;
+}
+
+/** A verdict: `reason_kind` only on `failed`. */
+export interface VerdictJson {
+  status: Verdict;
+  reason_kind?: ReasonKind;
+}
+
+/** The verdict of a set of claims: failed, then incomplete, then verified. */
+export function verdictOf(claims: readonly { claim: string; state: string }[]): VerdictJson {
+  const disproven = claims.filter((c) => c.state === D).map((c) => c.claim);
+  if (disproven.length > 0) {
+    const onlyRules = disproven.every((c) => c === "follows_rules");
+    return { status: "failed", reason_kind: onlyRules ? "nonconforming" : "changed" };
+  }
+  if (claims.some((c) => c.state === N)) return { status: "incomplete" };
+  return { status: "verified" };
+}
+
+type Item = { pack: number | null; record: number | null; event_id?: string | null };
+
+/** A record the pack holds, or one it names and does not hold. */
+function isRecord(i: Item): boolean {
+  return i.record !== null || (i.event_id !== undefined && i.event_id !== null);
+}
+
+/**
+ * What a line is about, as `[count, noun]` parts: records, then packs, then the case
+ * (`[null, "the case"]`).
+ */
+function scopeParts(items: readonly Item[]): [number | null, string][] {
+  const records = items.filter((i) => isRecord(i)).length;
+  const packs = items.filter((i) => !isRecord(i) && i.pack !== null).length;
+  const theCase = items.some((i) => !isRecord(i) && i.pack === null);
+  const parts: [number | null, string][] = [];
+  if (records) parts.push([records, records === 1 ? "record" : "records"]);
+  if (packs) parts.push([packs, packs === 1 ? "pack" : "packs"]);
+  if (theCase) parts.push([null, "the case"]);
+  return parts;
+}
+
+function scopeText(items: readonly Item[]): string {
+  return scopeParts(items)
+    .map(([count, noun]) => (count === null ? noun : `${count} ${noun}`))
+    .join(" and ");
+}
+
+function recordsIn(problems: readonly ProblemJson[]): number {
+  const seen: [number | null, number | null, string | null][] = [];
+  for (const p of problems) {
+    for (const i of p.items) {
+      const eventId = i.event_id ?? null;
+      if (isRecord(i) && !seen.some(([a, b, c]) => a === i.pack && b === i.record && c === eventId)) {
+        seen.push([i.pack, i.record, eventId]);
+      }
+    }
+  }
+  return seen.length;
+}
+
+function wordsOf(p: ProblemJson): readonly [string, string] {
+  if (p.kind !== "agent_record_incomplete" && p.state === N && lookup(KIND_CLAIMS, p.kind)[1] === D) {
+    // Downgraded: the disproof rests on bytes handed in beside the pack.
+    return [L_OUTSIDE, A_OWN_LOGS];
+  }
+  if (
+    p.kind === "pair_failed" &&
+    p.rule !== undefined &&
+    Object.prototype.hasOwnProperty.call(PAIR_WORDS, p.rule)
+  ) {
+    return PAIR_WORDS[p.rule]!;
+  }
+  const table = p.kind === "agent_record_incomplete" ? INCOMPLETE_WORDS : WORDS;
+  const key = p.kind === "agent_record_incomplete" ? (p.rule ?? "") : p.kind;
+  if (!Object.prototype.hasOwnProperty.call(table, key)) throw new Error(`KeyError: '${key}'`);
+  return table[key]!;
+}
+
+function fill(template: string, p: ProblemJson, group: readonly ProblemJson[]): string {
+  const records = recordsIn(group) || 1;
+  const count = p.count !== undefined ? p.count : records;
+  const of = p.of;
+  const values: Record<string, string> = {
+    count: pyStr(count),
+    count_records: n(count, "record"),
+    count_are: count === 1 ? "is" : "are",
+    of_records: typeof of === "number" && Number.isInteger(of) ? n(of, "record") : pyStr(of),
+    presented: pyStr(p.presented),
+    key: pyStr(p.key),
+    records_do: n(records, "agent record") + (records === 1 ? " does" : " do"),
+    their: records === 1 ? "its" : "their",
+    them: records === 1 ? "it" : "them",
+    records_use: n(records, "record") + (records === 1 ? " uses" : " use"),
+  };
+  return template.replace(/\{([a-z_]+)\}/g, (_, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(values, name)) throw new Error(`KeyError: '${name}'`);
+    return values[name]!;
+  });
+}
+
+function groupKey(p: ProblemJson): string {
+  return p.kind !== "agent_record_incomplete" ? p.kind : `${p.kind}:${pyStr(p.rule)}`;
+}
+
+/**
+ * The reasons behind one claim's line: one sentence per kind, counted over every
+ * problem of that kind, then each record-layer rule it breaks, each said once.
+ */
+function why(problems: readonly ProblemJson[]): string {
+  const sentences: string[] = [];
+  const kinds: string[] = [];
+  for (const p of problems) {
+    const key = groupKey(p);
+    if (!kinds.includes(key)) kinds.push(key);
+  }
+  for (const key of kinds) {
+    const group = problems.filter((p) => groupKey(p) === key);
+    const counted =
+      group[0]!.kind === "agent_record_nonconforming" || group[0]!.kind === "agent_record_incomplete";
+    for (const p of counted ? group.slice(0, 1) : group) {
+      const line = fill(wordsOf(p)[0], p, group);
+      if (!sentences.includes(line)) sentences.push(line);
+    }
+    if (group[0]!.kind === "agent_record_nonconforming") {
+      for (const p of group) {
+        const rule = Object.prototype.hasOwnProperty.call(RECORD_REASON_LINES, p.rule ?? "")
+          ? RECORD_REASON_LINES[p.rule ?? ""]
+          : undefined;
+        if (rule !== undefined && !sentences.includes(rule)) sentences.push(rule);
+      }
+    }
+  }
+  return sentences.join(" ");
+}
+
+/** One note for a record-layer finding carried by `records` records. */
+export function renderFindingNote(finding: string, records: number): string {
+  const text = Object.prototype.hasOwnProperty.call(NOTE_FINDINGS, finding)
+    ? NOTE_FINDINGS[finding]!
+    : finding.split("_").join(" ");
+  return `${text} (${n(records, "record")}).`;
+}
+
+/** One note as the machine layer carries it: its kind and its sentence. */
+export interface NoteEntry {
+  kind: string;
+  text: string;
+}
+
+/** One person line, laid out: the claim, its state, what it is about and why. */
+export interface LinePart {
+  claim: Claim;
+  state: ClaimState;
+  reason: NotProvenReason | NotInScopeReason | null;
+  count: number | null;
+  noun: string;
+  scope: string;
+  why: string;
+  text: string;
+}
+
+/** The person layer: what a reader is told, from the machine layer alone. */
+export interface Person {
+  title: string;
+  title_parts: { word: string; sentence: string | null };
+  lines: string[];
+  line_parts: LinePart[];
+  next: string | null;
+  notes: string[];
+  note_parts: NoteEntry[];
+  sandbox: string | null;
+  witness: string;
+  witness_state: string;
+}
+
+// Every note kind, in the order notes are printed: first what can change what a reader does
+// (a run or chain that may be incomplete, a tool that ran after a refusal, content that did
+// not travel), then what only describes the records.
+export const NOTE_ORDER: readonly string[] = Object.freeze([
+  "ran_after_refusal",
+  "completed_with_open_operation",
+  "pack_undeclared",
+  "disclosure_did_not_travel",
+  "content_withheld_by_declaration",
+  "pair_record_withheld",
+  "role_step_withheld",
+  "other_declaration_held",
+  "other_declaration_withheld",
+  "chain_claim_withheld",
+  "chains_unreadable",
+  "chain-link-dangling",
+  "chain-gap",
+  "chain-second-root",
+  "seq_gap",
+  "closing_not_held",
+  "start_absent",
+  "unended",
+  "ended_more_than_once",
+  "start_ambiguous",
+  "start_undeclared",
+  "seq_duplicate",
+  "handoff_parts_mismatch",
+  "data_mode_mixed",
+  "case_index_unreadable",
+  "case_index_pack_missing",
+  "case_index_pack_unlisted",
+  "case_index_file_missing",
+  "case_index_file_unlisted",
+  "case_index_file_differs",
+  "case_index_file_too_large",
+  "case_index_names_absent",
+  "witness_cache_refused",
+  "start_not_captured",
+  "plumbing",
+  "content_scrubbed",
+  "not_an_agent_record",
+  "co_signatures_present",
+]);
+
+/**
+ * One note as the machine layer carries it. A kind with no place in `NOTE_ORDER` throws:
+ * a new note is a decision about where it is printed.
+ */
+export function note(kind: string, text: string): NoteEntry {
+  if (!NOTE_ORDER.includes(kind)) throw new Error(`KeyError: '${kind}' has no place in NOTE_ORDER`);
+  return { kind, text };
+}
+
+/** The notes in `NOTE_ORDER`, each kind's notes in the order they came. */
+export function orderedNotes(notes: readonly NoteEntry[]): NoteEntry[] {
+  return notes
+    .map((n, i) => [n, i] as const)
+    .sort(([a, i], [b, j]) => NOTE_ORDER.indexOf(a.kind) - NOTE_ORDER.indexOf(b.kind) || i - j)
+    .map(([n]) => ({ kind: n.kind, text: n.text }));
+}
+
+/**
+ * The person layer, from the machine layer alone: the title, one line per claim that is
+ * disproven or not proven (disproven first, then the claim order), one next action from the
+ * first line, the notes, the sandbox line and the witness line.
+ *
+ * Each string member has a structured twin for a surface that lays the words out:
+ * `title_parts` (the verdict word and the sentence), `line_parts` (each line's claim,
+ * state, reason, what it is about and why), `note_parts` (each note's kind) and
+ * `witness_state`. The text in a twin is the string member's, word for word.
+ */
+export function renderPerson(
+  verdict: VerdictJson,
+  claims: readonly ClaimEntry[],
+  notes: readonly NoteEntry[],
+  environmentMarker: string | null,
+  witness: string,
+  witnessState: string,
+): Person {
+  const titleKey =
+    verdict.reason_kind !== undefined ? `${verdict.status}:${verdict.reason_kind}` : verdict.status;
+  if (!Object.prototype.hasOwnProperty.call(PERSON_TITLES, titleKey)) {
+    throw new Error(`KeyError: '${titleKey}'`);
+  }
+  const title = PERSON_TITLES[titleKey]!;
+  const parts = PERSON_TITLE_PARTS[titleKey]!;
+  const shown = [...claims.filter((c) => c.state === D), ...claims.filter((c) => c.state === N)];
+  const lines: string[] = [];
+  const lineParts: LinePart[] = [];
+  for (const c of shown) {
+    const said = c.state === D ? "disproven" : "not proven";
+    const mine = c.problems.filter((p) => p.state === c.state);
+    const scope = scopeParts(c.items);
+    const scopeLine = scopeText(c.items);
+    const because = why(mine);
+    const text = `${CLAIM_LABELS[c.claim]}: ${said} for ${scopeLine}. ${because}`;
+    lines.push(text);
+    lineParts.push({
+      claim: c.claim,
+      state: c.state,
+      reason: c.reason ?? null,
+      count: scope[0]![0],
+      noun: scope[0]![1],
+      scope: scopeLine,
+      why: because,
+      text,
+    });
+  }
+  let next: string | null = null;
+  if (shown.length > 0) {
+    const first = shown[0]!.problems.filter((p) => p.state === shown[0]!.state)[0]!;
+    next = fill(wordsOf(first)[1], first, [first]);
+  }
+  const noteParts = notes.map((x) => ({ kind: x.kind, text: x.text.endsWith(".") ? x.text : `${x.text}.` }));
+  return {
+    title,
+    title_parts: { word: parts.word, sentence: parts.sentence },
+    lines,
+    line_parts: lineParts,
+    next,
+    notes: noteParts.map((x) => x.text),
+    note_parts: noteParts,
+    sandbox: environmentMarker !== null ? SANDBOX_PERSON_LINE : null,
+    witness,
+    witness_state: witnessState,
+  };
+}
+
+/** The person layer as the text report prints it, first, before the detail. */
+export function personText(person: Person): string[] {
+  const out = [person.title, ...person.lines];
+  if (person.next !== null) out.push(`Next: ${person.next}`);
+  for (const note of person.notes) out.push(`Note: ${note}`);
+  if (person.sandbox !== null) out.push(`Sandbox: ${person.sandbox}`);
+  out.push(`Witness: ${person.witness}`);
+  return out;
+}
+
+// The bundle problems: what a bundle verifier's result says, as data. Read from the result's
+// own fields, never from its prose.
+const KNOWN_BODIES = [
+  "sanning.anchor.trace/v3",
+  "sanning.stamp.trace/v1",
+  "sanning.stamp.evidence/v2",
+  "sanning.evidence.export/v2",
+];
+
+type Loose = Record<string, unknown>;
+
+function field(obj: unknown, name: string): unknown {
+  return obj !== null && typeof obj === "object" ? (obj as Loose)[name] : undefined;
+}
+
+function isFalse(obj: unknown, name: string): boolean {
+  return field(obj, name) === false;
+}
+
+function listOf(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : [];
+}
+
+/**
+ * An export's own problems: each attestation whose signature fails or whose signed fields
+ * break their format, a signed source that cannot be read, then anything else that keeps
+ * the export from verifying.
+ */
+function exportProblems(exp: unknown, status: unknown, whole: readonly ProblemItem[]): Problem[] {
+  const out: Problem[] = [];
+  const attestations = listOf(field(exp, "attestations"));
+  const fieldError = (a: unknown) => {
+    const v = field(a, "fieldError");
+    return v === undefined ? null : v;
+  };
+  for (const a of attestations) {
+    if (isFalse(a, "signatureOk")) out.push(problem("attestation_signature_failed", whole));
+    else if (fieldError(a) !== null) out.push(problem("attestation_nonconforming", whole));
+  }
+  if (field(exp, "sourceUnreadable") === true) {
+    // The issuer signed a source no reader can read: whatever else then fails to bind
+    // follows from it.
+    out.push(problem("export_source_nonconforming", whole));
+    return out;
+  }
+  const other =
+    isFalse(exp, "sourceLinkageOk") ||
+    isFalse(exp, "verdictAgreementOk") ||
+    field(exp, "sourceStatus") === "failed" ||
+    attestations.some(
+      (a) => isFalse(a, "ok") && field(a, "signatureOk") === true && fieldError(a) === null,
+    );
+  if (status === "failed" && (other || out.length === 0)) {
+    out.push(problem("export_does_not_verify", whole));
+  } else if (status !== "failed" && out.length === 0) {
+    out.push(problem("export_not_checked", whole));
+  }
+  return out;
+}
+
+/**
+ * Every problem the bundle verifier found, mapped. `pack` is the pack's position in a
+ * case (`null` for a single pack read on its own). The result is read structurally, so a
+ * field a result does not carry is never read as a failure; a result whose status is not
+ * `verified` always yields at least one problem, and a `failed` one a disproof.
+ */
+export function bundleProblems(result: unknown, pack: number | null = null): Problem[] {
+  const status = field(result, "status");
+  const out: Problem[] = [];
+  const whole: ProblemItem[] = [[pack, null]];
+  const add = (kind: string, items: readonly ProblemItem[] = whole) => {
+    out.push(problem(kind, items));
+  };
+
+  const timeMalformed = field(result, "generatedAtMalformed") === true;
+  if (field(result, "unreadable") === true) {
+    const holds = !isFalse(result, "signatureOk") && !isFalse(result, "bodyHashOk");
+    if (field(result, "versionUnknown") === true) add("pack_version_unknown");
+    else add(holds ? "pack_body_unreadable" : "pack_unreadable");
+    if (timeMalformed) add("generated_at_nonconforming");
+    return out;
+  }
+  // No key to check the signature against: not a signature that fails, and the body is still
+  // read, so a disproof inside it stands.
+  const keyUnreadable = field(result, "keyUnreadable") === true;
+  if (keyUnreadable) add("pack_key_unreadable");
+  else if (isFalse(result, "signatureOk")) add("pack_does_not_verify");
+  if (isFalse(result, "bodyHashOk")) add("pack_body_hash_mismatch");
+  if (out.length > (keyUnreadable ? 1 : 0)) return out;
+  // The wrapper's time breaks its format, and the body is still read: a disproof inside it
+  // stands beside this one.
+  if (timeMalformed) add("generated_at_nonconforming");
+
+  const bodyType = field(result, "bodyType");
+  const events = listOf(field(result, "events"));
+  const recordItems: ProblemItem[] =
+    events.length > 0 ? events.map((_, i) => [pack, i] as ProblemItem) : whole;
+  if (typeof bodyType === "string" && !KNOWN_BODIES.includes(bodyType)) {
+    add("pack_body_type_unknown");
+    return out;
+  }
+
+  const checkpoints = listOf(field(result, "checkpoints"));
+  for (const cp of checkpoints) {
+    if (!isFalse(cp, "ok")) continue;
+    if (isFalse(cp, "onChainOk")) add("witness_differs");
+    else if (isFalse(cp, "envelopeOk")) add("stamp_signature_failed");
+    else if (field(cp, "anchorRefMalformed") === true) add("anchor_ref_nonconforming");
+    else add("stamp_does_not_verify");
+  }
+  const stamps = listOf(field(result, "stamps"));
+  for (const st of stamps) {
+    if (isFalse(st, "ok")) {
+      const rollup = field(field(st, "onChain"), "rollup");
+      if (rollup === "mismatch") add("witness_differs");
+      else if (field(st, "anchorRefMalformed") === true) add("anchor_ref_nonconforming");
+      else add("stamp_does_not_verify");
+    }
+  }
+  // A stamp or checkpoint nobody has witnessed yet (no anchor_ref) leaves `witnessed` not
+  // proven, as does an anchor trace with no checkpoint at all.
+  if (
+    stamps.some((st) => field(st, "anchorRef") === null) ||
+    checkpoints.some((cp) => field(cp, "anchorRef") === null)
+  ) {
+    add("stamp_unwitnessed", recordItems);
+  } else if (bodyType === "sanning.anchor.trace/v3" && checkpoints.length === 0) {
+    add("records_unstamped", recordItems);
+  }
+
+  events.forEach((ev, index) => {
+    const at: ProblemItem[] = [[pack, index]];
+    if (isFalse(ev, "ok") || isFalse(ev, "contentOk")) {
+      // Every check on the record speaks for itself. A claim one check cannot settle (a key
+      // or an envelope that cannot be read, a version this verifier does not know, bytes
+      // nobody signed) is not proven on that claim only, and never hides a disproof another
+      // check makes.
+      const said = out.length;
+      const listed = field(ev, "envelopeFaults");
+      const fault = field(ev, "envelopeFault");
+      const faults: EnvelopeFault[] =
+        Array.isArray(listed) && listed.length > 0
+          ? (listed as EnvelopeFault[])
+          : typeof fault === "string"
+            ? [fault as EnvelopeFault]
+            : [];
+      for (const f of faults) add(ENVELOPE_FAULT_KINDS[f], at);
+      if (isFalse(ev, "envelopeOk") && faults.length === 0) add("record_envelope_does_not_verify", at);
+      if (isFalse(ev, "payloadBindingOk") && !faults.includes("payload_unbound")) add("record_bytes_unbound", at);
+      if (field(ev, "recordNotJson") === true) add("record_bytes_nonconforming", at);
+      if (isFalse(ev, "contentOk")) {
+        const mismatch = problem("record_content_mismatch", at);
+        // Bytes nobody signed that disagree prove nothing changed.
+        out.push(field(ev, "contentUnsigned") === true ? downgraded(mismatch) : mismatch);
+      }
+      if (field(ev, "stampAbsent") === true) add("stamp_absent", at);
+      else if (isFalse(ev, "inclusionOk") || isFalse(ev, "checkpointBound")) add("record_not_covered", at);
+      // A retired field or present bytes that cannot be read fail the record in its own
+      // right wherever its key can be read: no claim left not proven, and no bytes beside
+      // the pack, stand in for that disproof.
+      const ownForm =
+        field(ev, "ownFormFailed") === true &&
+        (faults.length === 0 || lookup(KIND_CLAIMS, ENVELOPE_FAULT_KINDS[faults[0]])[1] === D);
+      if (out.length === said || (ownForm && !out.slice(said).some((p) => p.state === D))) {
+        add("record_does_not_verify_in_its_pack", at);
+      }
+    } else if (
+      ev !== null &&
+      typeof ev === "object" &&
+      "payloadBindingOk" in ev &&
+      (ev as Loose).payloadBindingOk === null
+    ) {
+      add("record_bytes_withheld", at);
+    }
+  });
+
+  if (bodyType === "sanning.stamp.trace/v1" && stamps.length === 0) add("pack_holds_no_records");
+  if (bodyType === "sanning.stamp.evidence/v2" && events.length === 0) add("pack_holds_no_records");
+  const exp = field(result, "export");
+  // An export reads on its own status, apart from the failure its wrapper's time makes.
+  const exportStatus = timeMalformed ? (field(exp, "status") ?? status) : status;
+  const others = out.filter((p) => p.kind !== "generated_at_nonconforming");
+  if (exp !== undefined && exp !== null && exportStatus !== "verified" && others.length === 0) {
+    out.push(...exportProblems(exp, exportStatus, whole));
+  }
+
+  // Fail closed: a status the problems above do not account for still reads as itself.
+  // A failure that rests only on bytes nobody signed is accounted for, not proven.
+  if (status === "failed" && !out.some((p) => p.state === D || (p.state === N && lookup(KIND_CLAIMS, p.kind)[1] === D))) {
+    add("bundle_does_not_verify");
+  }
+  else if (status !== "verified" && out.length === 0) add("bundle_not_checked");
+  return out;
+}