@sanning/proof 0.9.2 → 0.11.0

package/src/grading.ts

@@ -68,7 +68,18 @@
 // implementation is wrong.
 
 import { hexToBytes } from "./crypto.js";
-import { hasSideContent, sideContentKeys } from "./side-content.js";
+import type {
+  DeclarationCheck,
+  DeclarationContentKind,
+  DeclarationDeviationKind,
+  DeclarationVerdict,
+} from "./declaration.js";
+import { renderContentFinding, renderDeviation } from "./declaration.js";
+import { hasSideContent, sideContentKeys, type SideContentMap } from "./side-content.js";
+// The kernel's one reader for bytes a producer signed: strict UTF-8, no leading
+// byte-order mark, no non-finite literal. `jcs_loads` in
+// `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
+import { jcsParse } from "./verifier.js";
 
 // ---- The verdict a surface may print ----------------------------------------
 
@@ -140,7 +151,14 @@ export type PackGradeCauseKind =
   | "no-disclosure"
   | "missing-disclosure"
   | "unreadable-disclosure"
-  | "unaccounted-disclosure";
+  | "unaccounted-disclosure"
+  | "declaration-deviation"
+  /**
+   * The pack and the UNSIGNED content handed in beside it do not line up
+   * (proof#147). A cause, so the pack cannot read clean over it and a reader
+   * is told which record; NOT a deviation, so it never reaches `failed`.
+   */
+  | "declaration-content-dependent";
 
 /**
  * One reason a pack is not `verified`, as data.
@@ -166,6 +184,12 @@ export interface PackGradeCause {
   firstEventId?: string;
   /** Why one supplied disclosure could not be used. */
   reason?: string;
+  /**
+   * Which deviation from the pack's own declaration, for
+   * `declaration-deviation`, or which content-dependent finding, for
+   * `declaration-content-dependent`.
+   */
+  deviation?: DeclarationDeviationKind | DeclarationContentKind;
 }
 
 export interface PackGrade {
@@ -175,6 +199,12 @@ export interface PackGrade {
   recordsFailed: number;
   recordsUndetermined: number;
   causes: PackGradeCause[];
+  /**
+   * The declaration check's own verdict, carried so a consumer that reads only
+   * this value can tell a declared pack from an undeclared one. Absent when no
+   * check was passed, which is the pre-§5.4 call.
+   */
+  declaration?: DeclarationVerdict;
 }
 
 // ---- Reading a bundle --------------------------------------------------------
@@ -185,7 +215,7 @@ interface BundleLike {
       envelope?: { event_id?: unknown };
       inclusion?: { checkpoint_ref?: unknown; checkpoint_tx_id?: unknown };
     }[];
-    checkpoints?: { checkpoint_ref?: unknown; tx_id?: unknown; record_bytes?: unknown }[];
+    checkpoints?: { checkpoint_ref?: unknown; tx_id?: unknown; event_bytes?: unknown }[];
   };
 }
 
@@ -225,6 +255,22 @@ function inclusionKeyOf(
   return (hasV2 ? incl.checkpoint_ref : incl.checkpoint_tx_id) as string;
 }
 
+// The key a checkpoint and an inclusion are MATCHED on. A `checkpoint_ref` is
+// folded to lower case, because the verifier lowercases it before comparing.
+// A retired `tx_id` / `checkpoint_tx_id` is compared exactly as written, as the
+// retired reader did, even when it happens to look like hex.
+function checkpointMatchKey(o: { checkpoint_ref?: unknown; tx_id?: unknown } | null | undefined): string | null {
+  const k = joinKeyOf(o);
+  return k !== null && typeof o?.checkpoint_ref === "string" ? k.toLowerCase() : k;
+}
+
+function inclusionMatchKey(
+  incl: { checkpoint_ref?: unknown; checkpoint_tx_id?: unknown } | null | undefined,
+): string | null {
+  const k = inclusionKeyOf(incl);
+  return k !== null && typeof incl?.checkpoint_ref === "string" ? k.toLowerCase() : k;
+}
+
 const eventsOf = (bundle: unknown) => {
   const e = (bundle as BundleLike | null)?.body?.events;
   return Array.isArray(e) ? e : [];
@@ -356,7 +402,11 @@ function unsafeEventIdReason(eventId: string): string | null {
  */
 export function accountDisclosure(
   bundle: unknown,
-  content: Readonly<Record<string, Uint8Array>> | ReadonlyMap<string, Uint8Array>,
+  // `SideContentMap`, which is what `hasSideContent` and `sideContentKeys`
+  // below already take: an entry holding a string that is not hex IS an entry,
+  // and typing it out of this signature made the one map a caller builds
+  // unusable here (proof#147). A widening, so no caller moves.
+  content: SideContentMap,
 ): DisclosureAccount {
   const expected: string[] = [];
   const present: string[] = [];
@@ -402,11 +452,17 @@ export function accountDisclosure(
 }
 
 /** The `leaf_count` a checkpoint's SIGNED record commits to, or null if unreadable. */
-export function signedLeafCount(checkpoint: { record_bytes?: unknown } | null | undefined): number | null {
-  const hex = checkpoint?.record_bytes;
+export function signedLeafCount(checkpoint: { event_bytes?: unknown } | null | undefined): number | null {
+  const hex = checkpoint?.event_bytes;
   if (typeof hex !== "string" || hex.length === 0) return null;
   try {
-    const record = JSON.parse(new TextDecoder().decode(hexToBytes(hex))) as {
+    // `jcsParse`, matching `signed_leaf_count` in `src/sanning_proof/grading.py`.
+    // The pair used to agree by pointing two LENIENT decoders at one input, and
+    // that held for invalid UTF-8 and nowhere else: `TextDecoder` EATS a
+    // leading byte-order mark where Python's `errors="replace"` keeps it, so
+    // `BOM + JCS(checkpoint)` yielded a signed leaf count here and unreadable
+    // there, and that count decides a completeness note (proof#140 gate 5).
+    const record = jcsParse(hexToBytes(hex)) as {
       event?: { leaf_count?: unknown };
     };
     const n = record?.event?.leaf_count;
@@ -442,7 +498,14 @@ export function completenessNotes(bundle: unknown): CompletenessNote[] {
       notes.push({ checkpointRef, signed: null, presented: null, kind: "unreadable" });
       continue;
     }
-    const presented = events.filter((e) => inclusionKeyOf(e?.inclusion) === key).length;
+    // Compared case-folded. The verifier recomputes `checkpoint_ref` and
+    // accepts it in any case (evidence-bundle.md §5.1 names lowercase hex as
+    // the form, and the kernel lowercases before comparing), so a pack whose
+    // checkpoint spells its ref in upper case still verifies. Grading it
+    // case-sensitively reported every record as omitted: a completeness
+    // accusation manufactured by letter case. The ref shown is the pack's own.
+    const want = checkpointMatchKey(cp);
+    const presented = events.filter((e) => inclusionMatchKey(e?.inclusion) === want).length;
     if (presented < signed) notes.push({ checkpointRef, signed, presented, kind: "omitted" });
     else if (presented > signed) notes.push({ checkpointRef, signed, presented, kind: "surplus" });
   }
@@ -458,9 +521,36 @@ export function completenessNotes(bundle: unknown): CompletenessNote[] {
 export function gradeCauses(
   account: DisclosureAccount,
   notes: readonly CompletenessNote[],
+  declaration?: DeclarationCheck | null,
 ): PackGradeCause[] {
   const causes: PackGradeCause[] = [];
 
+  // What the pack CLAIMED to hold comes first, because it frames everything
+  // below it: a reader told "four records are missing from what this pack says
+  // it contains" reads the per-record findings differently. Every deviation
+  // gets its own cause (one defect, one line), so a pack that deviates in
+  // four ways can never be reported as one vague shortfall.
+  for (const deviation of declaration?.deviations ?? []) {
+    causes.push({
+      kind: "declaration-deviation",
+      deviation: deviation.kind,
+      ...(deviation.eventId === undefined ? {} : { firstEventId: deviation.eventId }),
+      reason: renderDeviation(deviation),
+    });
+  }
+
+  // Then what the pack and the UNSIGNED content beside it do not agree on
+  // (proof#147). A cause, so the pack cannot read clean over it; NOT a
+  // deviation, so it never reaches `failed`.
+  for (const finding of declaration?.contentFindings ?? []) {
+    causes.push({
+      kind: "declaration-content-dependent",
+      deviation: finding.kind,
+      ...(finding.eventId === undefined ? {} : { firstEventId: finding.eventId }),
+      reason: renderContentFinding(finding),
+    });
+  }
+
   for (const note of notes) {
     if (note.kind === "omitted") {
       causes.push({
@@ -555,25 +645,78 @@ function passThrough(status: string | null | undefined): PackVerdict {
  * (§5.1: undetermined, not failed), and a proven mismatch is never softened
  * into absence. The last branch passes the kernel's headline through unchanged:
  * this rule DOWNGRADES a verdict, it never invents one.
+ *
+ * ── the declaration (optional fourth argument) ──────────────────────────────
+ *
+ * `declaration` is what `checkDeclaration` in `./declaration.ts` made of the
+ * pack's own signed statement of what it holds (`evidence-bundle.md` §5.4). A
+ * deviation from it is a PROVEN mismatch between what the pack claimed and
+ * what it carries, so it FAILS the pack and each deviation becomes its own
+ * cause. It must never soften into absence: that is how a trimmed hand-over
+ * reads as an innocent gap.
+ *
+ * A check that came back `partial` splits in THREE (proof#147), and the first
+ * of the three is not about the declaration's readability at all. The other
+ * two split on whether the body carried a `declaration` member.
+ *
+ *   content-dependent      the pack and the UNSIGNED content beside it do not
+ *                          line up (proof#147). Each finding is its own cause
+ *                          and the pack is `incomplete`. It must never reach
+ *                          `failed`: whoever assembles a case fills in the
+ *                          side-content map, so an accuser holding an intact
+ *                          pack could otherwise put its holder into `failed`
+ *                          with no key at all, by dropping one file or adding
+ *                          one. `failed` is left to what a signature covers.
+ *   no declaration at all   nothing moves. Every pack built before §5.4 is
+ *                           this case, and re-grading them would move pinned
+ *                           exit codes for artifacts already in customers'
+ *                           hands.
+ *   present and unreadable  the pack is `incomplete`. `declaration_version` is
+ *                           chosen by the same party that assembles the pack
+ *                           and has no accept-set, so a holder who trims a
+ *                           record and then writes one unreadable field can
+ *                           re-seal the pack with its own key and hand a
+ *                           reader a clean verdict over evidence of the trim
+ *                           sitting inside the signed body. UNKNOWN is the
+ *                           only honest answer to a claim the reader cannot
+ *                           read, and it adds no cause: `PackGrade.declaration`
+ *                           says why.
+ *
+ * `verified` adds nothing and moves nothing.
+ *
+ * Omitting the argument entirely is the pre-§5.4 behavior, unchanged, and
+ * `PackGrade.declaration` is then absent.
  */
 export function gradePack(
   result: GradeInput,
   account: DisclosureAccount,
   notes: readonly CompletenessNote[],
+  declaration?: DeclarationCheck | null,
 ): PackGrade {
   const events = Array.isArray(result?.events) ? result.events : [];
   const recordsVerified = events.filter((e) => e.ok && e.contentOk === true).length;
   const recordsFailed = events.filter((e) => e.ok === false || e.contentOk === false).length;
   const recordsUndetermined = events.length - recordsVerified - recordsFailed;
-  const causes = gradeCauses(account, notes);
+  const causes = gradeCauses(account, notes, declaration);
 
   let verdict: PackVerdict;
   if (result?.status === "malformed") verdict = "malformed";
   else if (result?.status === "failed" || recordsFailed > 0) verdict = "failed";
+  else if (declaration?.verdict === "failed") verdict = "failed";
   else if (recordsUndetermined > 0 || causes.length > 0) verdict = "incomplete";
+  else if (declaration?.present === true && declaration.verdict === "partial")
+    verdict = "incomplete";
   else verdict = passThrough(result?.status);
 
-  return { verdict, recordsVerified, recordsFailed, recordsUndetermined, causes };
+  const grade: PackGrade = {
+    verdict,
+    recordsVerified,
+    recordsFailed,
+    recordsUndetermined,
+    causes,
+  };
+  if (declaration != null) grade.declaration = declaration.verdict;
+  return grade;
 }
 
 // ---- Presentation (optional) -------------------------------------------------
@@ -604,7 +747,7 @@ export function renderCause(cause: PackGradeCause, subject = "this pack"): strin
       return `checkpoint ${cause.checkpointRef} has no readable signed leaf_count — completeness is UNKNOWN`;
     case "no-disclosure":
       return (
-        `no record bytes were disclosed — content binding is UNKNOWN for all ${cause.count} ` +
+        `no event bytes were disclosed — content binding is UNKNOWN for all ${cause.count} ` +
         `record(s), not verified`
       );
     case "missing-disclosure":
@@ -619,5 +762,19 @@ export function renderCause(cause: PackGradeCause, subject = "this pack"): strin
         `${cause.count} disclosed file(s) are not accounted for by any record in this bundle ` +
         `(first: ${cause.firstEventId})`
       );
+    // Rendered once, by `renderDeviation` in `./declaration.ts`, and carried
+    // here on `reason`. Re-deriving the sentence from the cause fields would
+    // put the declaration's wording in two places, and one of the two would be
+    // edited alone.
+    case "declaration-deviation":
+      return `this pack deviates from its own declaration: ${cause.reason}`;
+    case "declaration-content-dependent":
+      // Named as what the reader could not establish, never as what the
+      // holder did: the bytes it turns on are unsigned and whoever assembled
+      // the case chose them (proof#147).
+      return (
+        `${subject} and the unsigned content handed in beside it do not line up: ` +
+        `${cause.reason}`
+      );
   }
 }