@sanning/proof 0.12.0 → 0.14.0

package/src/compose.ts

@@ -39,7 +39,7 @@ import {
   sha256Hex,
   utf8,
 } from "./crypto.js";
-import { jcs } from "./verifier.js";
+import { isRfc3339UtcInstant, jcs } from "./verifier.js";
 
 // The exporter's Ed25519 wrapper-signing key. `privateKey` is a 32-byte seed as
 // lowercase hex (the @noble/ed25519 / stack convention, e.g. the fixtures'
@@ -133,6 +133,13 @@ export async function composeExport(
     throw new Error("composeExport: exporterKey.privateKey (32-byte hex seed) is required");
   }
 
+  if (options.generatedAt !== undefined && !isRfc3339UtcInstant(options.generatedAt)) {
+    // The verifier reads this as `malformed generated_at` (evidence-bundle §2,
+    // A31), so composing one would sign an export this kernel rejects.
+    throw new Error(
+      "composeExport: generatedAt is not an RFC 3339 UTC date-time with Z naming a real date and time",
+    );
+  }
   const generatedAt = options.generatedAt ?? new Date().toISOString();
   const previousHash = options.previousHash ?? GENESIS;
   const issuerId = options.issuerId ?? "sanning-verify";

package/src/crypto.ts

@@ -80,9 +80,13 @@ export async function sha256Hex(bytes: Uint8Array): Promise<string> {
 // appear in the envelope; message is raw bytes. Never throws — a malformed
 // signature or key is "not verified," not an exception, so a hostile envelope
 // can't crash the checker.
+// Arguments in the Python twin's order, `ed25519_verify(message,
+// signature_hex, public_key_hex)` (P-03, 0.13.0). The message came second
+// until 0.13.0; a caller that still passes the signature first gets a compile
+// error, because a string is not a Uint8Array.
 export async function ed25519Verify(
-  signatureHex: string,
   message: Uint8Array,
+  signatureHex: string,
   publicKeyHex: string,
 ): Promise<boolean> {
   try {

package/src/declaration.ts

@@ -119,7 +119,7 @@
 //   last-write-wins in both languages, so a second record under a declared id
 //   was graded by neither rule 2 nor rule 7 and was never reported as surplus.
 //   FIRST in bundle order is now the record every other rule grades, and every
-//   record after it under the same id is a `duplicate-event-id` deviation.
+//   record after it under the same id is a `duplicate_event_id` deviation.
 //
 //   MINIMUM DISCLOSURE IS NOT A DEVIATION. A claimed side whose `event_bytes`
 //   the pack withholds was graded "not a conformant hand-off record", so an
@@ -133,36 +133,75 @@
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
 import { hexToBytes } from "./crypto.js";
 import { jcsParse } from "./verifier.js";
-import { isConformantHandoffRecord, type HandoffRecord } from "./handoff.js";
+import { isConformantHandoffRecord, isHandoffNamespace, type HandoffRecord } from "./handoff.js";
 import { hasSideContent, inBodyContentOffered, type SideContentMap } from "./side-content.js";
 
-/** The declaration schema this reader knows. */
+/** The first declaration schema, which every earlier reader knows. */
 export const DECLARATION_VERSION = "sanning.declaration/v1";
 
+/**
+ * v1 plus a signed `records[].role` on every record (evidence-bundle.md
+ * 5.4.1 v1.20, A21). A reader that knows only v1 reads a v2 declaration as one
+ * it cannot read, which is the safe direction.
+ */
+export const DECLARATION_VERSION_V2 = "sanning.declaration/v2";
+
+/** Every declaration schema this reader knows, in the order they were added. */
+export const DECLARATION_VERSIONS = [DECLARATION_VERSION, DECLARATION_VERSION_V2] as const;
+
+/**
+ * What a v2 declaration may sign a record IS, compared exactly: `handoff`, a
+ * record 4.1 governs that the pack claims as a side in `handoffs[]`, or
+ * `step`, any other record.
+ */
+export const DECLARATION_ROLES = ["handoff", "step"] as const;
+export type DeclarationRole = (typeof DECLARATION_ROLES)[number];
+
 /** The three states a declaration check can reach, from the §3 vocabulary. */
-export type DeclarationVerdict = "verified" | "failed" | "partial";
+export const DECLARATION_VERDICTS = ["verified", "failed", "partial"] as const;
+export type DeclarationVerdict = (typeof DECLARATION_VERDICTS)[number];
 
-export type DeclarationDeviationKind =
+export const DECLARATION_DEVIATION_KINDS = [
   /** The declaration is written to this version and is not readable as one. */
-  | "declaration-malformed"
+  "declaration_malformed",
   /** A record the declaration expects is not in the pack. */
-  | "declared-absent"
+  "declared_absent",
   /** A record in the pack the declaration never expected. */
-  | "undeclared-present"
+  "undeclared_present",
   /**
    * A record declared `content_withheld` whose bytes the pack supplies INSIDE
    * its own signed body, in `events[].content`.
    */
-  | "withheld-but-disclosed"
+  "withheld_but_disclosed",
   /** The pack carries one `event_id` on two or more records. */
-  | "duplicate-event-id"
+  "duplicate_event_id",
   /** A claimed hand-off names a record the declaration does not declare. */
-  | "pair-record-undeclared"
+  "pair_record_undeclared",
   /**
    * A claimed hand-off names a record that is not a conformant hand-off
    * record of the side it is claimed on (envelope-spec.md 4.1).
    */
-  | "pair-record-not-a-handoff";
+  "pair_record_not_a_handoff",
+  /**
+   * Rule 9 (v1.20, A21), `sanning.declaration/v2` only. A record declared
+   * `handoff` that no `handoffs[]` entry names as a side.
+   */
+  "role_handoff_unclaimed",
+  /** A record a `handoffs[]` entry names as a side, declared `step`. */
+  "role_step_claimed",
+  /**
+   * A record declared `step` that 4.1's scope test puts in scope: its `event`
+   * carries `counterparty_public_key`, or its folded `event_type` has a
+   * `handoff` segment. The holder signed that a hand-off record is not one.
+   */
+  "role_step_governed",
+  /**
+   * A record declared `step` whose supplied `event_bytes` this reader cannot
+   * read under rule 7's parser rule.
+   */
+  "role_step_unreadable",
+] as const;
+export type DeclarationDeviationKind = (typeof DECLARATION_DEVIATION_KINDS)[number];
 
 /**
  * Every way a pack and the UNSIGNED content handed in beside it fail to line
@@ -190,7 +229,7 @@ export type DeclarationDeviationKind =
  * legal and grades `verified`, which is strictly better than the `incomplete`
  * these carry.
  */
-export type DeclarationContentKind =
+export const DECLARATION_CONTENT_KINDS = [
   /**
    * A record declared `disclosed` whose bytes reached this reader from
    * neither channel. ALWAYS content-dependent: 5.4.1 lets those bytes travel
@@ -198,14 +237,16 @@ export type DeclarationContentKind =
    * fact about what the READER was handed and never a fact about what the
    * holder supplied. No signature covers the absence of a file nobody signed.
    */
-  | "content-dependent-withholding"
+  "content_dependent_withholding",
   /**
    * A record declared `content_withheld` whose bytes reached this reader ONLY
    * from the unsigned side-content map. The pack's own body supplies none, so
    * the holder committed to no such disclosure. The in-body half of the same
-   * rule is the `withheld-but-disclosed` DEVIATION and still fails.
+   * rule is the `withheld_but_disclosed` DEVIATION and still fails.
    */
-  | "content-dependent-disclosure";
+  "content_dependent_disclosure",
+] as const;
+export type DeclarationContentKind = (typeof DECLARATION_CONTENT_KINDS)[number];
 
 /**
  * One way the pack and the unsigned content beside it do not line up. Named
@@ -218,18 +259,27 @@ export interface DeclarationContentFinding {
 }
 
 /** Everything this check reports that is NOT a deviation, as a closed set. */
-export type DeclarationNoteKind =
+export const DECLARATION_NOTE_KINDS = [
   /**
    * Every record declared `disclosed` supplied no bytes, so nothing was
    * selected: the bytes did not travel with the pack.
    */
-  | "disclosure-did-not-travel"
+  "disclosure_did_not_travel",
   /**
    * A claimed hand-off side whose `event_bytes` the pack withholds. The reader
    * cannot see what the record is either way, so it is neither a conformant
    * hand-off record nor a non-conformant one.
    */
-  | "pair-record-withheld";
+  "pair_record_withheld",
+  /**
+   * A record a v2 declaration signs `step` whose `event_bytes` the pack
+   * withholds (rule 9, v1.20). Its role cannot be checked in either direction,
+   * so it is a note; the pack grade still holds the pack at `incomplete`,
+   * because its payload binding is undetermined.
+   */
+  "role_step_withheld",
+] as const;
+export type DeclarationNoteKind = (typeof DECLARATION_NOTE_KINDS)[number];
 
 /**
  * One named non-deviation finding, as data.
@@ -244,9 +294,9 @@ export interface DeclarationNote {
   count?: number;
   /** The record this is about, where it is about one. */
   eventId?: string;
-  /** Which side of a claimed hand-off named it, for `pair-record-withheld`. */
+  /** Which side of a claimed hand-off named it, for `pair_record_withheld`. */
   side?: "sent" | "received";
-  /** Which claimed hand-off, by position, for `pair-record-withheld`. */
+  /** Which claimed hand-off, by position, for `pair_record_withheld`. */
   pairIndex?: number;
 }
 
@@ -259,8 +309,14 @@ export interface DeclarationDeviation {
   side?: "sent" | "received";
   /** Which claimed hand-off, by position, for the two `pair-record-` deviations. */
   pairIndex?: number;
-  /** What is wrong with the declaration itself, for `declaration-malformed`. */
+  /** What is wrong with the declaration itself, for `declaration_malformed`. */
   reason?: string;
+  /**
+   * The `declaration_version` the object claimed, for `declaration_malformed`,
+   * so the rendered sentence names the version the holder wrote to rather than
+   * the first one this reader learned.
+   */
+  version?: string;
 }
 
 export interface DeclarationCheck {
@@ -286,6 +342,19 @@ export interface DeclarationCheck {
   declared: string[];
   /** Of those, the ones declared withheld on purpose. */
   declaredWithheld: string[];
+  /**
+   * The `declaration_version` this reader read the object as, one of
+   * `DECLARATION_VERSIONS`, or `null` where the body carries no declaration or
+   * one whose version this reader does not know. Set for a malformed object
+   * too: the version was read, the rest was not. Optional so a check a caller
+   * builds by hand, as rule version 5 adapters do, still type-checks.
+   */
+  version?: string | null;
+  /**
+   * Every record a v2 declaration signs a role for, in declaration order.
+   * Empty for v1, and for anything this reader could not read.
+   */
+  roles?: { eventId: string; role: DeclarationRole }[];
 }
 
 // ---- Reading the pack --------------------------------------------------------
@@ -476,6 +545,7 @@ const isId = (v: unknown): v is string => typeof v === "string" && v.length > 0;
 interface ReadDeclaration {
   records: { eventId: string; withheld: boolean }[];
   pairs: { sent: string | null; received: string | null }[];
+  roles: { eventId: string; role: DeclarationRole }[];
 }
 
 /**
@@ -488,8 +558,14 @@ interface ReadDeclaration {
  */
 function readDeclaration(
   declaration: Record<string, unknown>,
+  version: string = DECLARATION_VERSION,
 ): { ok: true; read: ReadDeclaration } | { ok: false; reasons: string[] } {
   const reasons: string[] = [];
+  // Under v2 every `records[]` entry must also carry `role`, exactly `handoff`
+  // or `step` (5.4.1 v1.20, A21); under v1 the member is not read at all, so a
+  // v1 declaration carrying `role` reads exactly as the same object without it.
+  const roles: { eventId: string; role: DeclarationRole }[] = [];
+  const v2 = version === DECLARATION_VERSION_V2;
   const note = (r: string) => reasons.push(r);
 
   if (!isId(declaration["case_id"])) note("case_id is not a non-empty string");
@@ -526,12 +602,20 @@ function readDeclaration(
         note(`records[${i}] (${eventId}) has no disclosure of "disclosed" or "content_withheld"`);
         continue;
       }
+      // Compared exactly: `Handoff`, `hand-off` and `step ` are other values,
+      // and a non-string never equals one.
+      const role = r["role"];
+      if (v2 && !(role === "handoff" || role === "step")) {
+        note(`records[${i}] (${eventId}) has no role of "handoff" or "step"`);
+        continue;
+      }
       if (seen.has(eventId)) {
         note(`records[${i}] declares ${eventId} a second time`);
         continue;
       }
       seen.add(eventId);
       records.push({ eventId, withheld: disclosure === "content_withheld" });
+      if (v2) roles.push({ eventId, role: role as DeclarationRole });
     }
   }
 
@@ -559,7 +643,7 @@ function readDeclaration(
     }
   }
 
-  return reasons.length > 0 ? { ok: false, reasons } : { ok: true, read: { records, pairs } };
+  return reasons.length > 0 ? { ok: false, reasons } : { ok: true, read: { records, pairs, roles } };
 }
 
 // ---- The check ---------------------------------------------------------------
@@ -572,8 +656,48 @@ const noDeclaration = (): DeclarationCheck => ({
   present: false,
   declared: [],
   declaredWithheld: [],
+  version: null,
+  roles: [],
 });
 
+/**
+ * The `declaration_version` of an object this reader knows, or `null`: a
+ * declaration that is not an object, an absent or `null` version and a version
+ * outside `DECLARATION_VERSIONS` are each a claim this reader cannot read.
+ */
+function knownVersion(declaration: unknown): string | null {
+  if (!isObject(declaration)) return null;
+  const version = declaration["declaration_version"];
+  return version === DECLARATION_VERSION || version === DECLARATION_VERSION_V2 ? version : null;
+}
+
+/**
+ * Rule 9 over one record the pack holds: the deviation or note it earns, or
+ * `null` where the signed role agrees with the pack and the record. The first
+ * of the four deviations that applies, in the order 5.4.2 lists them. Whether
+ * 4.1 governs the record is `isHandoffNamespace`, CALLED, never restated.
+ */
+function roleReading(
+  p: { eventId: string; publicKey: string; record: HandoffRecord | null; bytesSupplied: boolean },
+  role: DeclarationRole,
+  claimed: boolean,
+):
+  | "role_handoff_unclaimed"
+  | "role_step_claimed"
+  | "role_step_governed"
+  | "role_step_unreadable"
+  | "role_step_withheld"
+  | null {
+  if (role === "handoff") return claimed ? null : "role_handoff_unclaimed";
+  if (claimed) return "role_step_claimed";
+  if (!p.bytesSupplied) return "role_step_withheld";
+  if (p.record === null) return "role_step_unreadable";
+  if (isHandoffNamespace({ publicKey: p.publicKey, record: p.record, ref: p.eventId })) {
+    return "role_step_governed";
+  }
+  return null;
+}
+
 /**
  * Check a pack against the declaration inside its body.
  *
@@ -612,24 +736,31 @@ export function checkDeclaration(
   // a deleted one, a null one, and a `declaration` that is a string, an array
   // or null. Each of those hides the evidence of a trim inside a signed body,
   // so none of them may reach a clean pack verdict.
-  if (!isObject(declaration) || declaration["declaration_version"] !== DECLARATION_VERSION) {
+  const version = knownVersion(declaration);
+  if (version === null) {
     return { ...noDeclaration(), present: true };
   }
 
-  const read = readDeclaration(declaration);
+  const read = readDeclaration(declaration as Record<string, unknown>, version);
   if (!read.ok) {
     return {
       verdict: "failed",
-      deviations: read.reasons.map((reason) => ({ kind: "declaration-malformed", reason })),
+      deviations: read.reasons.map((reason) => ({
+        kind: "declaration_malformed",
+        reason,
+        version,
+      })),
       contentFindings: [],
       notes: [],
       present: true,
       declared: [],
       declaredWithheld: [],
+      version,
+      roles: [],
     };
   }
 
-  const { records, pairs } = read.read;
+  const { records, pairs, roles } = read.read;
   const declared = records.map((r) => r.eventId);
   const declaredSet = new Set(declared);
   const pack = packRecords(bundle, content);
@@ -650,7 +781,7 @@ export function checkDeclaration(
   // Declared and absent. The trimmed hand-over, which is the whole reason a
   // declaration exists: nothing else in the pack can see it.
   for (const r of records) {
-    if (!byId.has(r.eventId)) deviations.push({ kind: "declared-absent", eventId: r.eventId });
+    if (!byId.has(r.eventId)) deviations.push({ kind: "declared_absent", eventId: r.eventId });
   }
 
   // Present and undeclared, and the pack carrying one id twice.
@@ -668,12 +799,12 @@ export function checkDeclaration(
   const seenInPack = new Set<string>();
   for (const p of pack) {
     if (p.nameable && seenInPack.has(p.eventId)) {
-      deviations.push({ kind: "duplicate-event-id", eventId: p.eventId });
+      deviations.push({ kind: "duplicate_event_id", eventId: p.eventId });
       continue;
     }
     if (p.nameable) seenInPack.add(p.eventId);
     if (!p.nameable || !declaredSet.has(p.eventId)) {
-      deviations.push({ kind: "undeclared-present", eventId: p.eventId });
+      deviations.push({ kind: "undeclared_present", eventId: p.eventId });
     }
   }
 
@@ -688,7 +819,7 @@ export function checkDeclaration(
     .filter((p): p is NonNullable<typeof p> => p !== undefined);
   const nothingTravelled = disclosedHeld.length > 0 && !disclosedHeld.some((p) => p.disclosed);
   const notes: DeclarationNote[] = nothingTravelled
-    ? [{ kind: "disclosure-did-not-travel", count: disclosedHeld.length }]
+    ? [{ kind: "disclosure_did_not_travel", count: disclosedHeld.length }]
     : [];
 
   // The two disclosure rules, in declaration order, over the records the pack
@@ -713,12 +844,12 @@ export function checkDeclaration(
       // the pack, so no pack can prove it supplied them and no reader can
       // prove it did not: an accuser holding a twenty-file drop reaches this
       // reading by deleting one file.
-      contentFindings.push({ kind: "content-dependent-withholding", eventId: r.eventId });
+      contentFindings.push({ kind: "content_dependent_withholding", eventId: r.eventId });
     } else if (r.withheld && p.disclosed) {
       if (p.disclosedInBody) {
-        deviations.push({ kind: "withheld-but-disclosed", eventId: r.eventId });
+        deviations.push({ kind: "withheld_but_disclosed", eventId: r.eventId });
       } else {
-        contentFindings.push({ kind: "content-dependent-disclosure", eventId: r.eventId });
+        contentFindings.push({ kind: "content_dependent_disclosure", eventId: r.eventId });
       }
     }
   }
@@ -748,20 +879,42 @@ export function checkDeclaration(
       const id = pair[side];
       if (id === null) continue;
       if (!declaredSet.has(id)) {
-        deviations.push({ kind: "pair-record-undeclared", eventId: id, side, pairIndex: i });
+        deviations.push({ kind: "pair_record_undeclared", eventId: id, side, pairIndex: i });
         continue;
       }
       const p = byId.get(id);
       if (p === undefined) continue;
       const reading = sideReading(p, side);
       if (reading === "withheld") {
-        notes.push({ kind: "pair-record-withheld", eventId: id, side, pairIndex: i });
+        notes.push({ kind: "pair_record_withheld", eventId: id, side, pairIndex: i });
       } else if (reading === "not-a-handoff") {
-        deviations.push({ kind: "pair-record-not-a-handoff", eventId: id, side, pairIndex: i });
+        deviations.push({ kind: "pair_record_not_a_handoff", eventId: id, side, pairIndex: i });
       }
     }
   }
 
+  // Rule 9 (5.4.2 v1.20, A21), `sanning.declaration/v2` only: a record's
+  // signed role against the pack and against the record. Its deviations follow
+  // every deviation rules 1 to 8 report, and its note follows every other
+  // note, both in `records[]` order. It reads the signed body alone and NEVER
+  // the side-content map, so no party that signed nothing can create, move or
+  // remove one of its findings.
+  if (roles.length > 0) {
+    const claimed = new Set<string>();
+    for (const pair of pairs) {
+      if (pair.sent !== null) claimed.add(pair.sent);
+      if (pair.received !== null) claimed.add(pair.received);
+    }
+    for (const { eventId, role } of roles) {
+      const p = byId.get(eventId);
+      // Declared and absent: rule 1 named it, and one defect is one finding.
+      if (p === undefined) continue;
+      const kind = roleReading(p, role, claimed.has(eventId));
+      if (kind === "role_step_withheld") notes.push({ kind, eventId });
+      else if (kind !== null) deviations.push({ kind, eventId });
+    }
+  }
+
   // A proven deviation wins: it is a mismatch between what the pack claimed
   // and what its own signed body carries, and a failing check always wins.
   // With no deviation and a content-dependent finding, the pack lines up with
@@ -779,6 +932,8 @@ export function checkDeclaration(
     present: true,
     declared,
     declaredWithheld: records.filter((r) => r.withheld).map((r) => r.eventId),
+    version,
+    roles,
   };
 }
 
@@ -827,7 +982,7 @@ export interface DeclarationClaims {
    */
   present: boolean;
   /**
-   * Whether this reader could read the claim as `DECLARATION_VERSION` AND the
+   * Whether this reader could read the claim as one of `DECLARATION_VERSIONS` AND the
    * object satisfies 5.4.1. `false` covers an absent declaration, an unknown
    * version and a malformed object, and a case reader must not read any of the
    * three as "the holder claimed nothing to check".
@@ -841,6 +996,14 @@ export interface DeclarationClaims {
    * is legal and is exactly the shape a case reader has to name.
    */
   claimedSides: string[];
+  /**
+   * The version the claim was read as, where `readable`; else `null`. The case
+   * reader's claim check is v1's alone (5.5.1 v1.20): a v2 pack's claim check
+   * is rule 9, which the declaration check already ran.
+   */
+  version: string | null;
+  /** Every record a READABLE v2 declaration signs a role for. Empty for v1. */
+  roles: { eventId: string; role: DeclarationRole }[];
 }
 
 /**
@@ -857,14 +1020,17 @@ export function declarationClaims(bundle: unknown): DeclarationClaims {
     readable: false,
     caseId: null,
     claimedSides: [],
+    version: null,
+    roles: [],
   };
   const body = bodyOf(bundle);
   if (!isObject(body) || !("declaration" in body)) return none;
   const declaration = (body as Record<string, unknown>)["declaration"];
-  if (!isObject(declaration) || declaration["declaration_version"] !== DECLARATION_VERSION) {
+  const version = knownVersion(declaration);
+  if (version === null || !isObject(declaration)) {
     return { ...none, present: true };
   }
-  const read = readDeclaration(declaration);
+  const read = readDeclaration(declaration, version);
   if (!read.ok) return { ...none, present: true };
 
   const claimedSides: string[] = [];
@@ -879,6 +1045,8 @@ export function declarationClaims(bundle: unknown): DeclarationClaims {
     readable: true,
     caseId: typeof caseId === "string" ? caseId : null,
     claimedSides,
+    version,
+    roles: read.read.roles,
   };
 }
 
@@ -936,17 +1104,22 @@ export function renderDeclarationSummary(check: DeclarationCheck): string {
  */
 export function renderNote(note: DeclarationNote): string {
   switch (note.kind) {
-    case "disclosure-did-not-travel":
+    case "disclosure_did_not_travel":
       return (
         `this pack declares ${note.count} record(s) disclosed and supplies no bytes for ` +
         "any of them: the bytes did not travel with the pack, so their content is UNKNOWN"
       );
-    case "pair-record-withheld":
+    case "pair_record_withheld":
       return (
         `the claimed hand-off at position ${note.pairIndex} names ${note.eventId} on its ` +
         `${note.side} side, whose record bytes this pack withholds, so what that record ` +
         "IS is UNKNOWN"
       );
+    case "role_step_withheld":
+      return (
+        `${note.eventId} is signed as a step and this pack withholds its ` +
+        "record bytes, so whether it is one is UNKNOWN"
+      );
   }
 }
 
@@ -960,13 +1133,13 @@ export function renderNote(note: DeclarationNote): string {
  */
 export function renderContentFinding(finding: DeclarationContentFinding): string {
   switch (finding.kind) {
-    case "content-dependent-withholding":
+    case "content_dependent_withholding":
       return (
         `${finding.eventId} is declared disclosed and no bytes for it reached this ` +
         "verifier, from the pack or from beside it, so whether the holder supplied " +
         "them is UNKNOWN"
       );
-    case "content-dependent-disclosure":
+    case "content_dependent_disclosure":
       return (
         `${finding.eventId} is declared withheld and bytes for it were handed in ` +
         "beside this pack, which the pack does not carry and nobody signed, so " +
@@ -977,29 +1150,52 @@ export function renderContentFinding(finding: DeclarationContentFinding): string
 
 export function renderDeviation(deviation: DeclarationDeviation): string {
   switch (deviation.kind) {
-    case "declaration-malformed":
-      return `the declaration is not readable as ${DECLARATION_VERSION}: ${deviation.reason}`;
-    case "declared-absent":
+    case "declaration_malformed":
+      return (
+        "the declaration is not readable as " +
+        `${deviation.version || DECLARATION_VERSION}: ${deviation.reason}`
+      );
+    case "declared_absent":
       return `${deviation.eventId} is declared and is NOT in this pack`;
-    case "undeclared-present":
+    case "undeclared_present":
       return `${deviation.eventId} is in this pack and is NOT declared`;
-    case "withheld-but-disclosed":
+    case "withheld_but_disclosed":
       return (
         `${deviation.eventId} is declared withheld and this pack carries its bytes ` +
         "in its own signed body"
       );
-    case "duplicate-event-id":
+    case "duplicate_event_id":
       return `this pack carries ${deviation.eventId} more than once`;
-    case "pair-record-undeclared":
+    case "pair_record_undeclared":
       return (
         `the claimed hand-off at position ${deviation.pairIndex} names ` +
         `${deviation.eventId} on its ${deviation.side} side, which the declaration does not declare`
       );
-    case "pair-record-not-a-handoff":
+    case "pair_record_not_a_handoff":
       return (
         `the claimed hand-off at position ${deviation.pairIndex} names ` +
         `${deviation.eventId} on its ${deviation.side} side, which is not a conformant ` +
         `${SIDE_EVENT_TYPES[deviation.side ?? "sent"]} record`
       );
+    case "role_handoff_unclaimed":
+      return (
+        `${deviation.eventId} is signed as a hand-off record and no claimed ` +
+        "hand-off names it"
+      );
+    case "role_step_claimed":
+      return (
+        `${deviation.eventId} is signed as a step and a claimed hand-off ` +
+        "names it as a side"
+      );
+    case "role_step_governed":
+      return (
+        `${deviation.eventId} is signed as a step and is a record the ` +
+        "hand-off rules govern"
+      );
+    case "role_step_unreadable":
+      return (
+        `${deviation.eventId} is signed as a step and this pack carries ` +
+        "record bytes for it that this verifier cannot read"
+      );
   }
 }