@sanning/proof 0.11.1 → 0.13.0

package/dist/grading.js

@@ -41,13 +41,13 @@
 //               presents a different number of records than a checkpoint
 //               signed for — UNKNOWN
 //
-// `incomplete` is the surface's word for undetermined, and it is deliberately
-// NOT `verdict.status` from `evidence-bundle.md` §3. That enum grades a signed
-// bundle; this one grades a PACK — a strictly larger object, the bundle plus
-// whatever bytes travelled beside it. A pack can be incomplete while the bundle
-// it carries is impeccable, which is exactly the case that used to render green
-// over zero hashed bytes. Widening §3 to carry `incomplete` would be a spec
-// change; keeping the two enums distinct is not.
+// `incomplete` is one of the eight words of `evidence-bundle.md` §3 (v1.17,
+// A18), and it is a PACK verdict, never a bundle status. The bundle status
+// grades a signed bundle; this grades a PACK — a strictly larger object, the
+// bundle plus whatever bytes travelled beside it. A pack can be incomplete
+// while the bundle it carries is impeccable, which is exactly the case that
+// used to render green over zero hashed bytes. One vocabulary, two layers,
+// each issuing the subset it can reach.
 //
 // `recordsVerified` counts CONTENT-BOUND records only. The kernel's own
 // `event.ok` tolerates undisclosed content by design — a bundle may legitimately
@@ -73,6 +73,37 @@ import { hasSideContent, sideContentKeys } from "./side-content.js";
 // 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 ----------------------------------------
+// A superset of `EvidenceStatus`: the four the kernel can return, plus the
+// pack-level `incomplete`, plus `pending` from the shared §3 vocabulary so a
+// kernel headline this module does not downgrade can pass through unchanged.
+export const PACK_VERDICTS = [
+    "verified",
+    "partial",
+    "pending",
+    "not_found",
+    "mixed",
+    "failed",
+    "malformed",
+    "incomplete",
+];
+// ---- Output ------------------------------------------------------------------
+export const PACK_GRADE_CAUSE_KINDS = [
+    "records_omitted",
+    "records_surplus",
+    "leaf_count_unreadable",
+    "no_disclosure",
+    "missing_disclosure",
+    "unreadable_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",
+];
 /**
  * The checkpoint's join key, in whichever vocabulary the bundle speaks.
  *
@@ -358,7 +389,19 @@ export function completenessNotes(bundle) {
  * Every reason this pack is not `verified`, in the order a reader should hear
  * them: what is missing from the whole, then what is missing from the parts.
  */
-export function gradeCauses(account, notes, declaration) {
+export function gradeCauses(account, notes, declaration, withheld = []) {
+    // The `event_id`s WITHHELD BY THEIR DECLARATION (rule version 6) are taken
+    // out of `expected` and `missing` before the disclosure causes are computed,
+    // so a pack whose every record its declaration withholds earns neither
+    // `no_disclosure` nor `missing_disclosure`.
+    if (withheld.length > 0) {
+        const gone = new Set(withheld);
+        account = {
+            ...account,
+            expected: account.expected.filter((e) => !gone.has(e)),
+            missing: account.missing.filter((e) => !gone.has(e)),
+        };
+    }
     const causes = [];
     // 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
@@ -367,7 +410,7 @@ export function gradeCauses(account, notes, declaration) {
     // four ways can never be reported as one vague shortfall.
     for (const deviation of declaration?.deviations ?? []) {
         causes.push({
-            kind: "declaration-deviation",
+            kind: "declaration_deviation",
             deviation: deviation.kind,
             ...(deviation.eventId === undefined ? {} : { firstEventId: deviation.eventId }),
             reason: renderDeviation(deviation),
@@ -378,7 +421,7 @@ export function gradeCauses(account, notes, declaration) {
     // deviation, so it never reaches `failed`.
     for (const finding of declaration?.contentFindings ?? []) {
         causes.push({
-            kind: "declaration-content-dependent",
+            kind: "declaration_content_dependent",
             deviation: finding.kind,
             ...(finding.eventId === undefined ? {} : { firstEventId: finding.eventId }),
             reason: renderContentFinding(finding),
@@ -387,7 +430,7 @@ export function gradeCauses(account, notes, declaration) {
     for (const note of notes) {
         if (note.kind === "omitted") {
             causes.push({
-                kind: "records-omitted",
+                kind: "records_omitted",
                 checkpointRef: note.checkpointRef,
                 signed: note.signed,
                 presented: note.presented,
@@ -396,7 +439,7 @@ export function gradeCauses(account, notes, declaration) {
         }
         else if (note.kind === "surplus") {
             causes.push({
-                kind: "records-surplus",
+                kind: "records_surplus",
                 checkpointRef: note.checkpointRef,
                 signed: note.signed,
                 presented: note.presented,
@@ -404,7 +447,7 @@ export function gradeCauses(account, notes, declaration) {
             });
         }
         else {
-            causes.push({ kind: "leaf-count-unreadable", checkpointRef: note.checkpointRef });
+            causes.push({ kind: "leaf_count_unreadable", checkpointRef: note.checkpointRef });
         }
     }
     // "Nothing at all was disclosed" is reported once, as itself. It is the
@@ -412,22 +455,22 @@ export function gradeCauses(account, notes, declaration) {
     // reader deserves to be told the pack disclosed nothing rather than counting
     // N absences.
     if (account.expected.length > 0 && account.present.length === 0 && account.unreadable.length === 0) {
-        causes.push({ kind: "no-disclosure", count: account.expected.length, of: account.expected.length });
+        causes.push({ kind: "no_disclosure", count: account.expected.length, of: account.expected.length });
     }
     else if (account.missing.length > 0) {
         causes.push({
-            kind: "missing-disclosure",
+            kind: "missing_disclosure",
             count: account.missing.length,
             of: account.expected.length,
             ...(account.missing[0] === undefined ? {} : { firstEventId: account.missing[0] }),
         });
     }
     for (const u of account.unreadable) {
-        causes.push({ kind: "unreadable-disclosure", firstEventId: u.eventId, reason: u.reason });
+        causes.push({ kind: "unreadable_disclosure", firstEventId: u.eventId, reason: u.reason });
     }
     if (account.extra.length > 0) {
         causes.push({
-            kind: "unaccounted-disclosure",
+            kind: "unaccounted_disclosure",
             count: account.extra.length,
             ...(account.extra[0] === undefined ? {} : { firstEventId: account.extra[0] }),
         });
@@ -445,7 +488,8 @@ export function gradeCauses(account, notes, declaration) {
  * the type and renders the verdict verbatim would then print the one word
  * `evidence-bundle.md` §6 forbids, over a pack this rule never graded.
  *
- * So: the six states of the §3 vocabulary pass through, and ANYTHING ELSE is
+ * So: the five words of the §3 vocabulary that a bundle status can pass up to
+ * a pack pass through, and ANYTHING ELSE is
  * `incomplete`. A verdict we cannot interpret is a check we could not run, and
  * the answer to that is UNKNOWN — never a pass, and never an accusation.
  * (`failed` and `malformed` are handled before this is reached.)
@@ -466,8 +510,9 @@ function passThrough(status) {
  * The verdict a surface may print, and the counts it may print beside it.
  *
  * The invariant, stated so a mutation test can kill it: `verified` is reachable
- * ONLY when every record's supplied bytes bound to its own commitment and
- * nothing is missing, unreadable, surplus or omitted.
+ * ONLY when every record's supplied bytes bound to its own commitment, or
+ * (rule version 6) the record is withheld by its declaration, and nothing is
+ * missing, unreadable, surplus or omitted.
  *
  * Precedence: malformed > failed > incomplete > the kernel's own headline.
  * A hard verdict wins — "the bytes are absent" is never reported as failure
@@ -520,8 +565,20 @@ export function gradePack(result, account, notes, declaration) {
     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, declaration);
+    // WITHHELD BY ITS DECLARATION (rule version 6, 5.4.5 v1.20, A22, D5). All
+    // four conditions, each on its own. `declaredWithheld` is empty for an
+    // absent, unreadable or malformed declaration.
+    const declaredWithheld = new Set(declaration?.declaredWithheld ?? []);
+    const withheldEventIds = events
+        .filter((e) => typeof e.eventId === "string" &&
+        declaredWithheld.has(e.eventId) &&
+        e.ok === true &&
+        e.contentOk === null &&
+        e.payloadBindingOk === true)
+        .map((e) => e.eventId);
+    const recordsWithheld = withheldEventIds.length;
+    const recordsUndetermined = events.length - recordsVerified - recordsFailed - recordsWithheld;
+    const causes = gradeCauses(account, notes, declaration, withheldEventIds);
     let verdict;
     if (result?.status === "malformed")
         verdict = "malformed";
@@ -541,6 +598,8 @@ export function gradePack(result, account, notes, declaration) {
         recordsFailed,
         recordsUndetermined,
         causes,
+        recordsWithheld,
+        withheldEventIds,
     };
     if (declaration != null)
         grade.declaration = declaration.verdict;
@@ -559,32 +618,32 @@ export function gradePack(result, account, notes, declaration) {
  */
 export function renderCause(cause, subject = "this pack") {
     switch (cause.kind) {
-        case "records-omitted":
+        case "records_omitted":
             return (`checkpoint ${cause.checkpointRef} commits to ${cause.signed} record(s); ${subject} presents ` +
                 `${cause.presented} — ${cause.count} record(s) OMITTED`);
-        case "records-surplus":
+        case "records_surplus":
             return (`checkpoint ${cause.checkpointRef} commits to ${cause.signed} record(s); ${subject} presents ` +
                 `${cause.presented} — more records than the signed tree accounts for`);
-        case "leaf-count-unreadable":
+        case "leaf_count_unreadable":
             return `checkpoint ${cause.checkpointRef} has no readable signed leaf_count — completeness is UNKNOWN`;
-        case "no-disclosure":
+        case "no_disclosure":
             return (`no event bytes were disclosed — content binding is UNKNOWN for all ${cause.count} ` +
                 `record(s), not verified`);
-        case "missing-disclosure":
+        case "missing_disclosure":
             return (`${cause.count} of ${cause.of} record(s) disclose no bytes (first: ${cause.firstEventId}) — ` +
                 `content binding is UNKNOWN, not verified`);
-        case "unreadable-disclosure":
+        case "unreadable_disclosure":
             return `the disclosure for ${cause.firstEventId} is unreadable: ${cause.reason}`;
-        case "unaccounted-disclosure":
+        case "unaccounted_disclosure":
             return (`${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":
+        case "declaration_deviation":
             return `this pack deviates from its own declaration: ${cause.reason}`;
-        case "declaration-content-dependent":
+        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).

package/dist/handoff.d.ts

@@ -126,6 +126,16 @@ export interface CandidateReading {
     ref: string;
     verdict: HandoffVerdict;
     failedChecks: string[];
+    /**
+     * The ref of the record that ACCOUNTS FOR this candidate, or `null` (4.1
+     * v1.17, A20). Set only on a candidate that graded `failed` and that the
+     * reader holds a verified pair for elsewhere; such a candidate is still
+     * reported here and takes no part in the subject's verdict, failed checks or
+     * ambiguity. Every reading this kernel returns carries it. It is optional in
+     * the type only so that code which builds a `CandidateReading` itself keeps
+     * compiling: the field is an addition.
+     */
+    accountedFor?: string | null;
 }
 export interface HandoffReading {
     ref: string;
@@ -135,7 +145,12 @@ export interface HandoffReading {
     findings: string[];
     /** Ordered, never filtered. */
     candidates: string[];
-    /** One entry per candidate, in the same order, and nothing left out of it. */
+    /**
+     * One entry per candidate, in the same order, and nothing left out of it. A
+     * candidate another record accounts for is here with `accountedFor` set, and
+     * where every candidate is accounted for the reading is `counterpart_absent`
+     * with the candidates still listed.
+     */
     candidateReadings: CandidateReading[];
 }
 /**

package/dist/handoff.js

@@ -1,4 +1,4 @@
-// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.9).
+// The hand-off pairing rule of specs/envelope-spec.md §4.1 (v1.17).
 //
 // Two agents exchange a message and each side records what it held. This module
 // is the TypeScript half of the reference reading of those two records: which
@@ -119,14 +119,23 @@
 // `not_a_handoff_record` are findings reported beside a verdict rather than
 // verdicts.
 //
-// THE COST OF GRADING EVERY CANDIDATE, stated rather than left to be found. A
-// reader whose pile holds two or more records of the complementary type signed
-// by the counterparty key can no longer reach `verified`: every one of them is
-// graded and the worst of them is the reading. Two agents that exchange more
-// than one message land there. That is the price of never letting a value the
-// audited party writes decide what reaches a check, and the belt is the pack
-// layer: the declaration (evidence-bundle.md 5.4) says which records a pack
-// claims are a pair.
+// THE COST OF GRADING EVERY CANDIDATE, AND THE ACCOUNTED-FOR RULE THAT PAYS
+// MOST OF IT (envelope-spec.md 4.1 v1.17, amendment A20). Grading every
+// candidate means the records of a party's OTHER exchanges are candidates too,
+// and they fail. Up to v1.16 that put `verified` out of reach for any two agents
+// that exchanged more than one message in one direction, and the declaration
+// named as the belt cannot be one: evidence-bundle.md 5.5 forbids the reading
+// to consult `handoffs[]` to pair anything. So a candidate that grades `failed`
+// is SET ASIDE from the subject's verdict, failed checks and ambiguity when,
+// and only when, the reader holds another record `o` that accounts for it
+// (`accountedFor` below): `o` is signed by the subject's own key and is the
+// subject's type; `o` names the candidate's signer and the candidate names the
+// subject's key back; `o`'s sequence differs from the subject's; and the
+// candidate grades `verified` against `o`. The candidate stays in `candidates`
+// and `candidateReadings`, with `accountedFor` set. Setting one aside needs a
+// verified pair with a record the OTHER side signed, so a tampered record
+// stays live. Fan-in, fan-out, and one pair in two cases at one sequence still
+// read `failed`: the Python half's module docstring says why.
 export const CANDIDATE_NAMESPACE = "handoff.";
 export const DEFINED_EVENT_TYPES = ["handoff.sent", "handoff.received"];
 /**
@@ -546,21 +555,39 @@ export function readHandoff(subject, held) {
     // and took none of them out of this list.
     const graded = candidates.map((candidate) => {
         const { verdict, checks } = gradePair(subject, candidate);
-        return { ref: candidate.ref, verdict, failedChecks: checks };
+        const by = verdict === "failed" ? accountedFor(subject, candidate, held) : null;
+        return { ref: candidate.ref, verdict, failedChecks: checks, accountedFor: by };
     });
-    const worst = Math.max(...graded.map((g) => VERDICT_RANK[g.verdict]));
+    // The verdict, the failed checks and the ambiguity are taken over the
+    // candidates nothing accounts for. The others stay in the report.
+    const live = graded.filter((g) => g.accountedFor === null);
+    if (live.length === 0) {
+        // Every candidate is another exchange's record, each proven so by a
+        // verified pair with a record the subject's own key signed: an absence,
+        // reported with the candidates it looked at.
+        return {
+            ref: subject.ref,
+            verdict: null,
+            failedChecks: [],
+            findings: ["counterpart_absent"],
+            candidates: candidates.map((c) => c.ref),
+            candidateReadings: graded,
+        };
+    }
+    const worst = Math.max(...live.map((g) => VERDICT_RANK[g.verdict]));
     const verdict = Object.keys(VERDICT_RANK).find((name) => VERDICT_RANK[name] === worst);
-    // Over every candidate, not only the ones at the winning verdict: `malformed`
-    // outranks `failed`, so a single junk record would otherwise strip the named
-    // `message_hash` failure out of the report (proof#133 review, ruling 6).
+    // Over every live candidate, not only the ones at the winning verdict:
+    // `malformed` outranks `failed`, so a single junk record would otherwise
+    // strip the named `message_hash` failure out of the report (proof#133
+    // review, ruling 6).
     const failed = new Set();
-    for (const g of graded)
+    for (const g of live)
         for (const check of g.failedChecks)
             failed.add(check);
     const findings = [];
     // Never a free choice: a reader permitted to take one match can be handed an
     // honest decoy beside a tampered record.
-    if (candidates.length > 1)
+    if (live.length > 1)
         findings.push("counterpart_ambiguous");
     if (verdict === "malformed")
         findings.push("malformed_record");
@@ -573,6 +600,54 @@ export function readHandoff(subject, held) {
         candidateReadings: graded,
     };
 }
+/**
+ * The ref of the record that accounts for a FAILED candidate, or `null` (4.1
+ * v1.17, A20). The candidate is another exchange's record, and not a deviation
+ * on this one, only where the reader holds a record `o`, other than the
+ * subject, for which all four hold:
+ *
+ *   1. `o` is signed by the SUBJECT's own key, and is the subject's type;
+ *   2. `o` names the candidate's signer, and the candidate names the subject's
+ *      key back;
+ *   3. `o`'s `sequence` differs from the subject's;
+ *   4. the candidate grades `verified` against `o`.
+ *
+ * Condition 1 is what the audited party cannot supply: a verified pair needs
+ * the OTHER side's signature over the digest and the number. Condition 3 is
+ * the position guard (proof#129): a second record at the subject's own number
+ * is a second claim about the subject's message. The first `o` in the order
+ * the records are held is reported, so two kernels name one record. The
+ * Python half, `_accounted_for`, carries the full reasoning.
+ */
+function accountedFor(subject, candidate, held) {
+    const own = normalizedSigningKey(subject.publicKey);
+    const theirs = normalizedSigningKey(candidate.publicKey);
+    // Condition 2: the candidate names the subject's key back.
+    if (normalizedSigningKey(section(candidate.record, "event").counterparty_public_key) !== own) {
+        return null;
+    }
+    const subjectSequence = section(subject.record, "event").sequence;
+    for (const other of held) {
+        if (other === subject)
+            continue;
+        // Condition 1: signed by the subject's own key, of the subject's own type.
+        if (normalizedSigningKey(other.publicKey) !== own)
+            continue;
+        if (eventType(other) !== eventType(subject))
+            continue;
+        // Condition 2: o names the candidate's signer.
+        if (normalizedSigningKey(section(other.record, "event").counterparty_public_key) !== theirs) {
+            continue;
+        }
+        // Condition 3: another position than the subject's.
+        if (sameNumber(section(other.record, "event").sequence, subjectSequence))
+            continue;
+        // Condition 4: a verified pair.
+        if (gradePair(other, candidate).verdict === "verified")
+            return other.ref;
+    }
+    return null;
+}
 /**
  * EVERY record the reader holds gets a reading, in the order given.
  *

package/dist/index.d.ts

@@ -2,19 +2,22 @@ export { ACCEPTED_SPEC_MAJORS, contentHashes, jcs, specVersionSupported, verifyE
 export { bytesToHex, deriveOperatorAddress, ed25519Verify, hexToBytes, sha256Bytes, sha256Hex, utf8, verifyRsaPssSha256, } from "./crypto.js";
 export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyInclusion, } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
-export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
 export type { AnchorTraceBody, AttestationPayload, AttestationRecord, AttestationResult, CheckpointResult, ComposeVerdictResult, DisclosedContentResult, DisclosedEventContent, DisclosureStatus, EvidenceBundle, EvidenceBundleResult, EvidenceIssuer, EvidenceStatus, EvidenceVerdict, EventResult, ExportBody, ExportResult, OnChainOutcome, OnChainResult, PerGatewayOutcome, AnchorRef, StampBody, StampEntry, StampResult, StampSubtree, StampSubtreeResult, StampTraceBody, StampEvidenceBody, StampEvidenceEvent, StampEvidenceInclusion, TraceCheckpoint, TraceEvent, TraceInclusion, VerdictAttestation, VerdictCheckpoint, VerdictEvent, VerdictObject, VerdictOnChain, VerdictOnChainGateway, VerifyEvidenceOptions, } from "./evidence.js";
-export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
+export { PACK_GRADE_CAUSE_KINDS, PACK_VERDICTS, accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 export type { CompletenessNote, DisclosureAccount, GradeInput, PackGrade, PackGradeCause, PackGradeCauseKind, PackVerdict, } from "./grading.js";
-export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
-export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, DeclarationContentKind, DeclarationDeviation, DeclarationDeviationKind, DeclarationNote, DeclarationNoteKind, DeclarationVerdict, PackRecord, } from "./declaration.js";
-export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_VERDICTS, readCase, renderCaseSummary, renderException, } from "./case.js";
-export type { CaseException, CaseExceptionKind, CasePack, CaseReading, CaseRecordReading, CaseVerdict, } from "./case.js";
+export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
+export type { DeclarationCheck, DeclarationClaims, DeclarationContentFinding, DeclarationContentKind, DeclarationDeviation, DeclarationDeviationKind, DeclarationNote, DeclarationNoteKind, DeclarationRole, DeclarationVerdict, PackRecord, } from "./declaration.js";
+export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+export type { CaseException, CaseExceptionKind, CaseNote, CaseNoteKind, CasePack, CasePackReading, CaseReading, CaseRecordReading, CaseVerdict, WitnessLine, WitnessState, } from "./case.js";
+export { CASE_FILE_FINDING_KINDS, CASE_FILE_INDEX_NAME, CASE_FILE_VERSION, HOW_TO_VERIFY_NAME, REPORT_README_FIRST_LINE, howToVerifyText, isPackRef, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
+export type { CaseFileFinding, CaseFileFindingKind, CaseFileIndexReading, } from "./case-file.js";
 export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainFinding, } from "./chain.js";
 export type { ChainFinding, ChainFindingKind, ChainReading, ChainSource, ChainSummary, } from "./chain.js";
+export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
-export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+export { AGENT_PROOF_SPEC_VERSION, isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 export type { AgentProofBundle, AgentProofResult, VerifyAgentProofOptions, } from "./agent-proof.js";
 export { CANDIDATE_NAMESPACE, DEFINED_EVENT_TYPES, NOT_A_HANDOFF_FINDING, isConformantHandoffRecord, readHandoff, readHandoffs, recordIsMalformed, } from "./handoff.js";
 export type { CandidateReading, HandoffReading, HandoffRecord, HandoffVerdict, HeldRecord, } from "./handoff.js";

package/dist/index.js

@@ -11,7 +11,7 @@
 // envelope. Chain walking (previous_hash), checkpoint reconciliation, and
 // gateway/transport concerns are consumer-layer logic composed above it.
 // ACCEPTED_SPEC_MAJORS is exported for parity with the sibling kernels'
-// registries (Python ACCEPTED_SPEC_VERSIONS, Go SupportedSpecMajor): a consumer
+// registries (Python ACCEPTED_SPEC_MAJORS, Go SupportedSpecMajor): a consumer
 // can see which profiles this build admits without inferring it from probe
 // calls. It is frozen at its definition (`Object.freeze`, typed
 // `readonly string[]`) because the verifier reads that same array — an exported
@@ -34,7 +34,7 @@ export { EMPTY_TREE_ROOT_HEX, auditPath, leafHash, merkleRoot, nodeHash, verifyI
 // files that failed verification on genuine evidence. This hands back DECODED
 // bytes, and only for events whose verification bound them to the committed
 // content_hash. Additive; verifyEvidenceBundle's behavior is unchanged.
-export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
+export { ACCEPTED_EVIDENCE_MAJORS, ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, disclosedContent, recomputeExportVerdict, verifyEvidenceBundle, } from "./evidence.js";
 // Pack grading (src/grading.ts): what a verification SURFACE may claim about a
 // pack — the signed bundle PLUS whatever disclosed bytes travelled beside it.
 //
@@ -50,7 +50,7 @@ export { ANCHOR_TRACE_BODY_TYPE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRA
 // consumer that cannot yet import `gradePack` can vendor the table, hold its own
 // derivation to it, and diff its copy against ours. Additive — no existing
 // export changes.
-export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
+export { PACK_GRADE_CAUSE_KINDS, PACK_VERDICTS, accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCause, signedLeafCount, } from "./grading.js";
 // The declaration (src/declaration.ts): what a pack SAYS it holds, checked
 // against what it does (evidence-bundle.md §5.4).
 //
@@ -67,7 +67,7 @@ export { accountDisclosure, completenessNotes, gradeCauses, gradePack, renderCau
 // Pure: data in, data out, no I/O. `gradePack` takes the result as an
 // optional fourth argument, so a surface gets one verdict; omitting it is the
 // pre-§5.4 behavior, unchanged. Additive: no existing export changes.
-export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
+export { DECLARATION_CONTENT_KINDS, DECLARATION_DEVIATION_KINDS, DECLARATION_NOTE_KINDS, DECLARATION_ROLES, DECLARATION_VERDICTS, DECLARATION_VERSION, DECLARATION_VERSION_V2, DECLARATION_VERSIONS, checkDeclaration, declarationClaims, packRecords, renderContentFinding, renderDeclarationSummary, renderDeviation, renderNote, } from "./declaration.js";
 // The case (src/case.ts): one verdict over SEVERAL packs, across organizations
 // (anchor#198). The layer above the declaration, and the closure for what a
 // declaration cannot reach.
@@ -77,14 +77,19 @@ export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords,
 // because the omission happens before any reader runs. Reading several parties'
 // packs at once is what closes it: a `handoff.sent` with no counterpart is
 // always named, and where a pack signed by the key it names is in the case, the
-// reading says that pack holds no counterpart. Whether a party that presented
+// reading says that pack holds no counterpart (unless every candidate was
+// accounted for under A20, which reads as no counterpart and names no pack). Whether a party that presented
 // no such pack recorded anything is not established (proof#143). `readCase`
 // verifies every pack itself, offline, so it is async. Matching is on keys and hashes alone and NEVER on tenancy, so a pair from two
 // organizations verifies (DL-60).
 //
 // Pure: data in, data out, no I/O. Additive: a new module, no existing export
 // changes, and no new verdict word anywhere.
-export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_VERDICTS, readCase, renderCaseSummary, renderException, } from "./case.js";
+export { CASE_BODY_TYPES, CASE_EXCEPTION_KINDS, CASE_QUARANTINED_PROFILES, CASE_RECORD_PROFILES, CASE_NOTE_KINDS, CASE_RELIANCE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+// The case file's index (src/case-file.ts, evidence-bundle.md §5.6, A25):
+// compared with the drop it describes, with NO verdict contribution. The index
+// is never an input to `readCase`. Pure: bytes and a file list in.
+export { CASE_FILE_FINDING_KINDS, CASE_FILE_INDEX_NAME, CASE_FILE_VERSION, HOW_TO_VERIFY_NAME, REPORT_README_FIRST_LINE, howToVerifyText, isPackRef, readCaseFileIndex, renderCaseFileFinding, } from "./case-file.js";
 // Chain reading (src/chain.ts): following the pointer every sanning.events/v2
 // record carries to the record before it, over the records ONE bundle presents.
 //
@@ -110,11 +115,14 @@ export { ADAPTER_CHAIN_NAMESPACES, CHAIN_READING_SCOPE, readChains, renderChainF
 // signed, offline-verifiable sanning.evidence.export/v2 artifact from a source
 // anchor-trace bundle + operator attestations + an exporter Ed25519 key. The
 // inverse of verifyEvidenceBundle's verifyExportBody dispatch.
+// One exit-code table for every verb (0.13.0): the verdict word to the exit
+// code, and the help text every verb prints. Additive.
+export { EXIT_CODES, EXIT_CODES_HELP, EXIT_FAILED, EXIT_MALFORMED, EXIT_MIXED, EXIT_UNDETERMINED, EXIT_VERIFIED, exitCodeFor, } from "./exit-codes.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 // Agent inclusion-proof bundle verification: the
 // sanning.agent.proof/v1 bundle. The CLI sniffs spec_version and routes here so
 // one verifier covers both agent and anchor bundles.
-export { AGENT_PROOF_SPEC_PREFIX, isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
+export { AGENT_PROOF_SPEC_VERSION, isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
 // The hand-off pairing rule (src/handoff.ts): which records are candidates to
 // be the counterpart of a hand-off record, how a candidate set of more than one
 // is ordered, and what a formed pair grades to (specs/envelope-spec.md §4.1

package/dist/message-parts.d.ts

@@ -118,17 +118,19 @@ export declare const REFUSAL_ORDER: readonly ["bytes_for_unknown_part", "conflic
 export declare const MESSAGE_RESULT_ORDER: readonly ["parts_not_an_array"];
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes` is A2A's spelling of an inline file
- * part, and `data` and `content` are the two other spellings in the wild. The
- * FIRST of them present with a value that is not `null` is the inline content,
- * so a part spelling it twice reads one way in both kernels.
+ * read. Named rather than inferred: `bytes`, `data` and `content` are the
+ * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * carries a file as `raw` or `url`, so a literal A2A part reads
+ * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
+ * a value that is not `null` is the inline content, so a part spelling it
+ * twice reads one way in both kernels.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
- * absent value and one written as `null` name one thing. That matters: an A2A
- * `FilePart` with `uri` set carries `"bytes": null`, and so does proto3 JSON,
- * and reading those as inline made a conformant DESCRIPTOR part uncheckable
- * (proof#156 gate). They fall through to the descriptor rule, which is what
- * they are.
+ * absent value and one written as `null` name one thing. That matters: a
+ * proto3 JSON encoder can write an unset field as `"bytes": null`, and reading
+ * that as inline made a conformant DESCRIPTOR part uncheckable
+ * (proof#156 gate). Such a part falls through to the descriptor rule, which is
+ * what it is.
  */
 export declare const INLINE_BYTES_KEYS: readonly ["bytes", "content", "data"];
 /**

package/dist/message-parts.js

@@ -262,17 +262,19 @@ const HELD_UNCHECKED_RESULTS = [
 ];
 /**
  * The keys that make a part carry its content INLINE, in the order they are
- * read. Named rather than inferred: `bytes` is A2A's spelling of an inline file
- * part, and `data` and `content` are the two other spellings in the wild. The
- * FIRST of them present with a value that is not `null` is the inline content,
- * so a part spelling it twice reads one way in both kernels.
+ * read. Named rather than inferred: `bytes`, `data` and `content` are the
+ * spellings in the wild. None is A2A 1.0.0's: its `Part` has no `kind` and
+ * carries a file as `raw` or `url`, so a literal A2A part reads
+ * `part_not_a_file` (envelope-spec §4.1, A19). The FIRST of them present with
+ * a value that is not `null` is the inline content, so a part spelling it
+ * twice reads one way in both kernels.
  *
  * A key present with `null` is an ABSENT inline value, on A14's ruling that an
- * absent value and one written as `null` name one thing. That matters: an A2A
- * `FilePart` with `uri` set carries `"bytes": null`, and so does proto3 JSON,
- * and reading those as inline made a conformant DESCRIPTOR part uncheckable
- * (proof#156 gate). They fall through to the descriptor rule, which is what
- * they are.
+ * absent value and one written as `null` name one thing. That matters: a
+ * proto3 JSON encoder can write an unset field as `"bytes": null`, and reading
+ * that as inline made a conformant DESCRIPTOR part uncheckable
+ * (proof#156 gate). Such a part falls through to the descriptor rule, which is
+ * what it is.
  */
 // A conformant DESCRIPTOR part that also carries a `content` or `data` key
 // meaning something else (a filename, a metadata blob) is reclassified by this

package/dist/types.d.ts

@@ -22,6 +22,7 @@ export type ContentRole = "asset" | "baseline" | "observed";
 export interface VerifyOptions {
     payloadBytes?: Uint8Array;
     expectedContentHash?: string;
+    acceptedSpecMajors?: readonly string[];
 }
 export interface VerificationResult {
     ok: boolean;

package/dist/verifier.d.ts

@@ -38,11 +38,18 @@ export declare function jcs(value: unknown): string;
  * Throws for anything that is not conformant; every call site treats a throw as
  * "this reader cannot read these bytes" and names the check that failed.
  */
+/**
+ * Bytes as strict UTF-8, a leading byte-order mark KEPT as a character.
+ * `utf8_strict` in the Python twin's `canonicalize.py` is the same rule, and
+ * `jcsParse` below performs the identical decode. Throws on bytes that are not
+ * UTF-8.
+ */
+export declare function utf8Strict(bytes: Uint8Array): string;
 export declare function jcsParse(bytes: Uint8Array): unknown;
-export declare function specVersionSupported(specVersion: string): boolean;
+export declare function specVersionSupported(specVersion: string, accepted?: readonly string[]): boolean;
 export declare function isRfc3339UtcInstant(value: unknown): boolean;
 export declare function contentHashes(env: Envelope): {
     role: ContentRole;
     hash: string;
 }[];
-export declare function verifyEnvelope(env: Envelope, optionsOrContentHash?: string | VerifyOptions): Promise<VerificationResult>;
+export declare function verifyEnvelope(env: Envelope, options?: VerifyOptions): Promise<VerificationResult>;