@sanning/proof 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanning/proof",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "TypeScript kernel of the Sanning verification stack: RFC 8785 (JCS) canonicalization, SHA-256, and Ed25519 verification for Verifiable Event Envelopes. Full-family verifier (inline + external commitment); accepts sanning.agent/v1 and sanning.events/v2. Conformance-gated byte-for-byte against the test-vectors corpus.",
   "license": "MIT",
   "type": "module",

package/src/case-file.ts

@@ -25,7 +25,7 @@
  * network. How the files were listed and hashed is the caller's.
  */
 
-import { jcsParse } from "./verifier.js";
+import { DuplicateKeyError, jcsParse } from "./verifier.js";
 
 /** The index's dispatch key (5.6.2). An absent or unknown value makes the index unreadable. */
 export const CASE_FILE_VERSION = "sanning.case-file/v1";
@@ -237,7 +237,10 @@ function readIndex(raw: Uint8Array): ReadIndex {
   let value: unknown;
   try {
     value = jcsParse(raw);
-  } catch {
+  } catch (e) {
+    // Named, because an index that lists one pack twice under one member name
+    // reads as whichever copy came last (I-JSON, proof#144).
+    if (e instanceof DuplicateKeyError) throw new Unreadable(e.message);
     throw new Unreadable("not readable as JSON");
   }
   if (!isObject(value)) throw new Unreadable("not a JSON object");

package/src/case.ts

@@ -260,7 +260,7 @@ import {
   readHandoffs,
   recordIsMalformed,
 } from "./handoff.js";
-import { verifyEvidenceBundle } from "./evidence.js";
+import { coSignaturesPresent, verifyEvidenceBundle } from "./evidence.js";
 import type { EvidenceBundleResult } from "./evidence.js";
 import {
   type PackGrade,
@@ -271,6 +271,7 @@ import {
   gradePack,
 } from "./grading.js";
 import type { SideContentMap } from "./side-content.js";
+import { renderWitnessTime } from "./witness-cache.js";
 
 // ---- The vocabulary ---------------------------------------------------------
 
@@ -727,13 +728,25 @@ export const RECORD_PROFILE_QUARANTINED = "record_profile_quarantined";
 export const CASE_HOLDS_NO_PACKS = "case_holds_no_packs";
 
 /**
- * The two NOTEs (5.5.3 v1.20): findings on the reading with no contribution,
- * printed in the scope sentence so a clean verdict never hides either.
- * `pack_undeclared` is a note only where the reading holds no hand-off record;
- * where it holds one, it is the exception of that name.
+ * The three NOTEs (5.5.3 v1.20, extended proof#148): findings on the reading
+ * with no contribution, printed in the scope sentence so a clean verdict
+ * never hides any of them. `pack_undeclared` is a note only where the
+ * reading holds no hand-off record; where it holds one, it is the exception
+ * of that name.
  */
 export const CONTENT_WITHHELD_BY_DECLARATION = "content_withheld_by_declaration";
-export const CASE_NOTE_KINDS = [PACK_UNDECLARED, CONTENT_WITHHELD_BY_DECLARATION] as const;
+/**
+ * A pack's wrapper carries a present `co_signatures` (evidence-bundle.md §2,
+ * decided by Phil 2026-09-24 on proof#148). The field verifies nothing and
+ * sits outside the wrapper's signed scope, so the case reading names it
+ * rather than presenting it as evidence, and it contributes no verdict.
+ */
+export const CO_SIGNATURES_PRESENT = "co_signatures_present";
+export const CASE_NOTE_KINDS = [
+  PACK_UNDECLARED,
+  CONTENT_WITHHELD_BY_DECLARATION,
+  CO_SIGNATURES_PRESENT,
+] as const;
 export type CaseNoteKind = (typeof CASE_NOTE_KINDS)[number];
 
 /**
@@ -1330,6 +1343,16 @@ export async function readCase(
     }
     holderKeys.add(holder);
 
+    if (coSignaturesPresent(pack.bundle)) {
+      // A NOTE, with no contribution (5.5.3 v1.20, proof#148): the wrapper's
+      // co_signatures verifies nothing and sits outside its signed scope, so
+      // the case reading names it rather than moving anything on its account.
+      caseNotes.push({
+        position,
+        note: { kind: CO_SIGNATURES_PRESENT, packRef: pack.ref },
+      });
+    }
+
     const bodyType = bodyTypeOf(pack.bundle);
     const records = packRecords(pack.bundle, pack.content);
     // The per-record gradings below are joined to `records` BY INDEX, so a
@@ -1939,6 +1962,11 @@ export function renderCaseNote(note: CaseNote): string {
       );
     case PACK_UNDECLARED:
       return `${note.packRef} does not say what it holds`;
+    case CO_SIGNATURES_PRESENT:
+      return (
+        `${note.packRef} carries unverified co-signatures in its wrapper; ` +
+        "they are not part of the evidence"
+      );
     default:
       return (note as CaseNote).kind;
   }
@@ -1998,17 +2026,18 @@ export const VERDICT_DISPLAY_TITLES: Readonly<Record<string, string>> = {
 
 /**
  * What a reader may rely on, for each of the six words a case reading reaches
- * (5.5.6 v1.20, A26), the same for every drop. `pending` and `not_found`
- * never head a case reading: they are witness states.
+ * (5.5.6 v1.20, A26; the `verified` text at v1.28, A35), the same for every
+ * drop. `pending` and `not_found` never head a case reading: they are
+ * witness states. `verified` is the base sentence, printed alone where the
+ * drop holds no hand-off record; a caller reads `caseReliance` for
+ * `verified`, never this mapping directly.
  */
 export const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>> = {
   verified:
-    "Every pack in this drop is genuine and unaltered and agrees with its " +
-    "own signed declaration. Every hand-off with both sides here is " +
-    "intact. Every other record is one its holder signed as a step. " +
-    "Nothing here could not be checked. This was read offline, on this " +
-    "device. It does not say these packs are everything the parties " +
-    "recorded.",
+    "Every pack in this drop is genuine, unaltered, and matches its own " +
+    "signed declaration. Every record in it was signed by its holder's " +
+    "key. This was read offline, on this device. It does not say this " +
+    "drop holds everything that was recorded.",
   partial:
     "Nothing here was proven wrong, and a check could not be completed: a " +
     "pack names no witness, or a pack in a hand-off reading does not say " +
@@ -2031,6 +2060,37 @@ export const CASE_RELIANCE: Readonly<Record<CaseVerdict, string>> = {
     "exception before relying on any of it.",
 };
 
+/**
+ * The clause a `verified` drop that holds a hand-off record gains, inserted
+ * after `CASE_RELIANCE`'s first sentence (5.5.6, A35). Never printed alone,
+ * and never where `handoffRecords` is zero: most drops hold one agent's
+ * pack and no hand-off to say anything about.
+ */
+export const CASE_RELIANCE_HANDOFF_CLAUSE =
+  "Every hand-off with both sides in this drop is intact.";
+
+/**
+ * What a reader may rely on for one case reading (5.5.6 v1.28, A35), byte
+ * for byte the text `case_reliance`'s Python sibling returns.
+ *
+ * For every word but `verified` this is `CASE_RELIANCE` unchanged. For
+ * `verified`, the hand-off clause is inserted after the first sentence
+ * where `handoffRecords` is not zero, and left out where it is zero: the
+ * base sentence never claims a hand-off the drop does not hold.
+ */
+export function caseReliance(verdict: CaseVerdict, handoffRecords: number): string {
+  if (verdict === "verified" && handoffRecords > 0) {
+    return (
+      "Every pack in this drop is genuine, unaltered, and matches its own " +
+      "signed declaration. Every hand-off with both sides in this drop is " +
+      "intact. Every record in it was signed by its holder's key. This " +
+      "was read offline, on this device. It does not say this drop holds " +
+      "everything that was recorded."
+    );
+  }
+  return CASE_RELIANCE[verdict];
+}
+
 /** The three witness states, and how each is printed (5.5.6, D7). No other. */
 export const WITNESS_STATES = {
   confirmed: "Confirmed on the public record",
@@ -2050,6 +2110,18 @@ export interface WitnessLine {
   state: WitnessState;
   reasons: string[];
   services: string[];
+  /**
+   * Witness times a pack caches that no lookup settled, as `[blockHeight,
+   * blockTime]`, distinct and in time order (5.6.6, v1.25, A30). Printed labelled
+   * not checked, and never as a time a reader may rely on. Absent reads as none.
+   */
+  cached?: [number, number][];
+  /**
+   * Witness times the public record returned where they matched a pack's
+   * cache, distinct and in time order. The gateway's answer, named with the
+   * service, never the cache's value. Absent reads as none.
+   */
+  recorded?: [number, number][];
 }
 
 /** The line printed where no lookup ran, which is every reading this kernel produces on its own. */
@@ -2060,9 +2132,23 @@ export const WITNESS_NOT_LOOKED_UP: Readonly<WitnessLine> = Object.freeze({
 });
 
 /** The witness line as both kernels print it. */
+/** How a witness time a pack caches is printed where nothing checked it (5.5.6, 5.6.6, v1.25, A30). */
+export const WITNESS_TIME_CACHED = "the pack dates the witness, not checked";
+/** How a witness time the public record returned is printed where it matched the cache. */
+export const WITNESS_TIME_RECORDED = "the public record dates the witness";
+
+function witnessTimes(times: readonly [number, number][]): string {
+  return times.map(([h, t]) => renderWitnessTime(h, t)).join(", ");
+}
+
 export function renderWitnessLine(line: WitnessLine): string {
   let text = `Witness: ${WITNESS_STATES[line.state]}`;
-  if (line.reasons.length > 0) text += `: ${line.reasons.join("; ")}`;
+  const parts = [...line.reasons];
+  if (line.cached && line.cached.length > 0) parts.push(`${WITNESS_TIME_CACHED}: ${witnessTimes(line.cached)}`);
+  if (line.recorded && line.recorded.length > 0) {
+    parts.push(`${WITNESS_TIME_RECORDED}: ${witnessTimes(line.recorded)}`);
+  }
+  if (parts.length > 0) text += `: ${parts.join("; ")}`;
   if (line.services.length > 0) text += ` (answered: ${line.services.join(", ")})`;
   return text;
 }