@sanning/proof 0.12.0 → 0.13.0

package/dist/declaration.js

@@ -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
@@ -132,10 +132,130 @@
 // `src/sanning_proof/canonicalize.py` is the twin (proof#140 gate 5).
 import { hexToBytes } from "./crypto.js";
 import { jcsParse } from "./verifier.js";
-import { isConformantHandoffRecord } from "./handoff.js";
+import { isConformantHandoffRecord, isHandoffNamespace } from "./handoff.js";
 import { hasSideContent, inBodyContentOffered } 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];
+/**
+ * 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"];
+/** The three states a declaration check can reach, from the §3 vocabulary. */
+export const DECLARATION_VERDICTS = ["verified", "failed", "partial"];
+export const DECLARATION_DEVIATION_KINDS = [
+    /** The declaration is written to this version and is not readable as one. */
+    "declaration_malformed",
+    /** A record the declaration expects is not in the pack. */
+    "declared_absent",
+    /** A record in the pack the declaration never expected. */
+    "undeclared_present",
+    /**
+     * A record declared `content_withheld` whose bytes the pack supplies INSIDE
+     * its own signed body, in `events[].content`.
+     */
+    "withheld_but_disclosed",
+    /** The pack carries one `event_id` on two or more records. */
+    "duplicate_event_id",
+    /** A claimed hand-off names a record the declaration does not declare. */
+    "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",
+    /**
+     * 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",
+];
+/**
+ * Every way a pack and the UNSIGNED content handed in beside it fail to line
+ * up, as a closed set. Neither of these is a deviation, and neither of them
+ * fails (proof#147, ratified by Phil 2026-09-22).
+ *
+ * WHY THEY ARE NOT DEVIATIONS. 5.4 grades a pack's declaration partly against
+ * content the reader was HANDED, and that content is not signed by anybody.
+ * `events[].content` rides inside `body`, so the wrapper signature and
+ * `body_hash` cover it and what it says about the holder is the holder's own
+ * word. The side-content map is the other channel, and whoever assembles a
+ * case fills it in: an accuser could put an intact pack into
+ * `pack_declaration_deviates`, which contributed `failed`, WITH NO KEY AT
+ * ALL, by dropping the bytes of a record the pack declared `disclosed` or by
+ * adding bytes for one it declared `content_withheld`. The pack was intact,
+ * its wrapper verified, and its holder had done nothing.
+ *
+ * This is the mirror of proof#143. There a counterparty makes itself look
+ * better by choosing what it hands over; here an accuser makes a counterparty
+ * look worse the same way. Both now read as what the READER established, so
+ * `failed` stays for what a signature covers.
+ *
+ * WHAT A HOSTILE HOLDER GAINS FROM THE WEAKER WORD: nothing, because a
+ * cheaper move already dominates it. Declaring a record `content_withheld` is
+ * legal and grades `verified`, which is strictly better than the `incomplete`
+ * these carry.
+ */
+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
+     * beside the pack as `logs/<event_id>.json`, so "no bytes arrived" is a
+     * 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",
+    /**
+     * 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.
+     */
+    "content_dependent_disclosure",
+];
+/** Everything this check reports that is NOT a deviation, as a closed set. */
+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",
+    /**
+     * 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",
+    /**
+     * 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",
+];
 /**
  * The record committed inside one `events[]` entry, or `null`.
  *
@@ -250,8 +370,13 @@ const isId = (v) => typeof v === "string" && v.length > 0;
  * and a reader that names one defect in a claim with four sends its holder
  * round the loop four times.
  */
-function readDeclaration(declaration) {
+function readDeclaration(declaration, version = DECLARATION_VERSION) {
     const reasons = [];
+    // 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 = [];
+    const v2 = version === DECLARATION_VERSION_V2;
     const note = (r) => reasons.push(r);
     if (!isId(declaration["case_id"]))
         note("case_id is not a non-empty string");
@@ -289,12 +414,21 @@ function readDeclaration(declaration) {
                 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 });
         }
     }
     const pairs = [];
@@ -321,7 +455,7 @@ function readDeclaration(declaration) {
             pairs.push({ sent: sent, received: received });
         }
     }
-    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 ---------------------------------------------------------------
 const noDeclaration = () => ({
@@ -332,7 +466,40 @@ const noDeclaration = () => ({
     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) {
+    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, role, claimed) {
+    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.
  *
@@ -368,22 +535,29 @@ export function checkDeclaration(bundle, content) {
     // 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, 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);
@@ -404,7 +578,7 @@ export function checkDeclaration(bundle, content) {
     // 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 });
+            deviations.push({ kind: "declared_absent", eventId: r.eventId });
     }
     // Present and undeclared, and the pack carrying one id twice.
     //
@@ -421,13 +595,13 @@ export function checkDeclaration(bundle, content) {
     const seenInPack = new Set();
     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 });
         }
     }
     // The bytes that did not travel. Over the records declared `disclosed` that
@@ -441,7 +615,7 @@ export function checkDeclaration(bundle, content) {
         .filter((p) => p !== undefined);
     const nothingTravelled = disclosedHeld.length > 0 && !disclosedHeld.some((p) => p.disclosed);
     const notes = 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
     // actually holds: an absent record is already named above, and naming it
@@ -467,14 +641,14 @@ export function checkDeclaration(bundle, content) {
             // 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 });
             }
         }
     }
@@ -504,7 +678,7 @@ export function checkDeclaration(bundle, content) {
             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);
@@ -512,13 +686,39 @@ export function checkDeclaration(bundle, content) {
                 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();
+        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
@@ -534,6 +734,8 @@ export function checkDeclaration(bundle, content) {
         present: true,
         declared,
         declaredWithheld: records.filter((r) => r.withheld).map((r) => r.eventId),
+        version,
+        roles,
     };
 }
 /**
@@ -550,15 +752,18 @@ export function declarationClaims(bundle) {
         readable: false,
         caseId: null,
         claimedSides: [],
+        version: null,
+        roles: [],
     };
     const body = bodyOf(bundle);
     if (!isObject(body) || !("declaration" in body))
         return none;
     const declaration = body["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 = [];
@@ -574,6 +779,8 @@ export function declarationClaims(bundle) {
         readable: true,
         caseId: typeof caseId === "string" ? caseId : null,
         claimedSides,
+        version,
+        roles: read.read.roles,
     };
 }
 export function renderDeclarationSummary(check) {
@@ -621,13 +828,16 @@ export function renderDeclarationSummary(check) {
  */
 export function renderNote(note) {
     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");
     }
 }
 /**
@@ -640,11 +850,11 @@ export function renderNote(note) {
  */
 export function renderContentFinding(finding) {
     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 " +
                 "whether the holder disclosed them is UNKNOWN");
@@ -652,23 +862,36 @@ export function renderContentFinding(finding) {
 }
 export function renderDeviation(deviation) {
     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");
     }
 }

package/dist/evidence.d.ts

@@ -1,4 +1,6 @@
 import type { Envelope } from "./types.js";
+/** The accepted `sanning.evidence/v1` wrapper majors; exported in both kernels (P-01, 0.13.0). */
+export declare const ACCEPTED_EVIDENCE_MAJORS: readonly string[];
 export declare const ANCHOR_TRACE_BODY_TYPE = "sanning.anchor.trace/v3";
 /**
  * The name `event_bytes` replaced. Under the new majors a body entry that still