@sanning/proof 0.12.0 → 0.14.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/index.d.ts

@@ -2,19 +2,26 @@ 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, CO_SIGNATURES_NOTE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, coSignaturesPresent, 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_RELIANCE_HANDOFF_CLAUSE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, CO_SIGNATURES_PRESENT, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, WITNESS_TIME_CACHED, WITNESS_TIME_RECORDED, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.js";
+export type { CachedWitnessTime, WitnessTimeAnswer, WitnessTimeCheck } from "./witness-cache.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 { FILE_MATCH_SCOPE, NOT_READ_REASONS, fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch, } from "./file-match.js";
+export type { FileCommitment, FileMatchPack, FileMatchReading, MatchedFile, NotRead, NotReadReason, OfferedFile, UnmatchedFile, } from "./file-match.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, CO_SIGNATURES_NOTE, EXPORT_BODY_TYPE, STAMP_BODY_VERSION, STAMP_TRACE_BODY_TYPE, STAMP_EVIDENCE_BODY_TYPE, coSignaturesPresent, 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.
@@ -85,7 +85,18 @@ export { DECLARATION_VERSION, checkDeclaration, declarationClaims, packRecords,
 //
 // 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_RELIANCE_HANDOFF_CLAUSE, CASE_VERDICTS, CONTENT_WITHHELD_BY_DECLARATION, CO_SIGNATURES_PRESENT, VERDICT_DISPLAY_TITLES, WITNESS_NOT_LOOKED_UP, WITNESS_STATES, WITNESS_TIME_CACHED, WITNESS_TIME_RECORDED, caseReliance, readCase, renderCaseNote, renderCaseSummary, renderException, renderWitnessLine, } from "./case.js";
+// The witnessed-time cache (evidence-bundle 5.6.6, v1.25, A30): read it, look it
+// up, print it. Never an input to a verdict.
+export { MAX_BLOCK_TIME, MAX_WITNESS_CACHE_DEPTH, WITNESS_CACHE_NAME, WITNESS_CACHE_VERSION, checkWitnessCache, formatBlockTime, readWitnessCache, renderWitnessTime, witnessTimeQuery, } from "./witness-cache.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";
+// Files handed in beside a pack (src/file-match.ts, evidence-bundle.md §5.7,
+// A29, proof#92): each file's SHA-256 matched against the commitments the
+// pack's SIGNED records make, by hash alone. Never moves a verdict.
+export { FILE_MATCH_SCOPE, NOT_READ_REASONS, fileMatchToJson, matchCaseFiles, matchFiles, renderFileMatch, } from "./file-match.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.
 //
@@ -111,11 +122,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,19 +118,27 @@ 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. Settled at `bytes` alone (envelope-spec §4.1, A31, proof#163): that
+ * is A2A's spelling, the one the wedge actually emits, and it is the only
+ * inline spelling either reference kernel has read from a real producer.
+ * `content` and `data` were added on inference rather than on an observed
+ * wire shape, and sanning-io/anchor's `filePart()` and `file_part()` SDK
+ * helpers, the only producer this plane ships, confirm the inference was
+ * wrong: both emit a descriptor part, `kind: "file"` plus `content_hash` and
+ * `content_length`, and neither ever writes a `content` or `data` wire key
+ * for inline bytes. None is A2A 1.0.0's either: 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 one key present with a
+ * value that is not `null` is the inline content.
  *
  * 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"];
+export declare const INLINE_BYTES_KEYS: readonly ["bytes"];
 /**
  * The largest integer a double carries exactly, the same bound section 4.1 puts
  * on `event.sequence`: a `content_length` outside it is a value the two kernels

package/dist/message-parts.js

@@ -262,23 +262,33 @@ 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. Settled at `bytes` alone (envelope-spec §4.1, A31, proof#163): that
+ * is A2A's spelling, the one the wedge actually emits, and it is the only
+ * inline spelling either reference kernel has read from a real producer.
+ * `content` and `data` were added on inference rather than on an observed
+ * wire shape, and sanning-io/anchor's `filePart()` and `file_part()` SDK
+ * helpers, the only producer this plane ships, confirm the inference was
+ * wrong: both emit a descriptor part, `kind: "file"` plus `content_hash` and
+ * `content_length`, and neither ever writes a `content` or `data` wire key
+ * for inline bytes. None is A2A 1.0.0's either: 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 one key present with a
+ * value that is not `null` is the inline content.
  *
  * 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.
- */
-// A conformant DESCRIPTOR part that also carries a `content` or `data` key
-// meaning something else (a filename, a metadata blob) is reclassified by this
-// list and never checked against supplied bytes. That is inside section 4.1's
-// stated rule, and whether these parts ought to fall into it is proof#163.
-export const INLINE_BYTES_KEYS = ["bytes", "content", "data"];
+ * 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.
+ */
+// Before A31 this list also carried `content` and `data`, and a conformant
+// DESCRIPTOR part that happened to carry either key meaning something else (a
+// filename, a caption) was silently reclassified as inline and never checked
+// against supplied bytes: the swapped-bytes check A18 exists to run
+// (proof#145) never ran on it. proof#163 is resolved by narrowing to `bytes`
+// alone, closing that gap.
+export const INLINE_BYTES_KEYS = ["bytes"];
 const HEX64 = /^[0-9a-fA-F]{64}$/;
 const HEX_CHARSET = /^[0-9a-fA-F]+$/;
 const LOWER_HEX = "0123456789abcdef";

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

@@ -8,11 +8,13 @@ export declare function jcs(value: unknown): string;
  * twin is `jcs_loads` in `src/sanning_proof/canonicalize.py`, and every site in
  * either kernel that reads bytes a producer signed goes through one of the two.
  *
- * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Four checks
+ * ONE RULE, SPELLED OUT, BECAUSE TWO BUILT-INS ARE NOT ONE RULE. Five checks
  * carry it, none of them left to a decoder's defaults: strict UTF-8, no leading
  * byte-order mark, no non-finite literal (this kernel's `JSON.parse` rejects
  * `NaN`, `Infinity` and `-Infinity` natively, and Python names them in a
- * `parse_constant` hook), and no unpaired surrogate in the parsed value.
+ * `parse_constant` hook), no object that repeats a member name
+ * (`DuplicateKeyError`, proof#144), and no unpaired surrogate in the parsed
+ * value.
  *
  * THE FOURTH CHECK IS NOT THE FIRST ONE TWICE. The strict decode refuses a
  * surrogate written as raw bytes; it cannot see one written as the ASCII
@@ -38,11 +40,68 @@ 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;
+/**
+ * A JSON object that names one member twice (I-JSON, RFC 7493 section 2.3).
+ * The Python twin is `DuplicateKey` in `canonicalize.py`, and the message is
+ * the same kernel wording in both: `duplicate key ` and the name as
+ * `renderKey` spells it.
+ *
+ * JCS (RFC 8785) is defined over I-JSON, and I-JSON forbids duplicate member
+ * names, so bytes that repeat a name are MALFORMED rather than another spelling
+ * of the last value. `JSON.parse` and Python's `json.loads` both keep the last
+ * value and say nothing, which let a bundle carrying `"spec_version":"junk"`
+ * before its real `spec_version` read `verified` in both kernels (proof#144).
+ */
+export declare class DuplicateKeyError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * A member name as a quoted, pure-ASCII string, identically in both kernels
+ * (`render_key` in the Python twin). Printable ASCII other than `"` and `\` is
+ * kept; `"` and `\` are backslash-escaped; every other UTF-16 code unit is
+ * `\uXXXX` in lower-case hex. A rendering longer than 64 characters is cut
+ * there and `...` follows the closing quote.
+ */
+export declare function renderKey(key: string): string;
+/**
+ * `JSON.parse(text)`, refusing an object that repeats a member name. The Python
+ * twin is `loads_refusing_duplicates` in `canonicalize.py`.
+ *
+ * `JSON.parse` cannot see a repeat, because it keeps the last value, so the
+ * text is scanned once more AFTER it parsed. The parse runs first, so text
+ * that is not JSON at all fails as JSON and never as a duplicate, as it does in
+ * the Python twin. Throws `DuplicateKeyError`.
+ */
+export declare function parseRefusingDuplicates(text: string): unknown;
+/**
+ * The repeated member name to report for text `JSON.parse` has already
+ * accepted, or `undefined` when no object repeats one.
+ *
+ * WHICH ONE, because both kernels must name the same one. Objects are checked
+ * as they CLOSE, innermost first, which is the order Python's
+ * `object_pairs_hook` sees them in; inside one object the name reported is the
+ * first whose repeat comes earliest. Names compare after unescaping, so `"a"`
+ * and `"\u0061"` are one name, as they are to both parsers.
+ *
+ * ITERATIVE, with an explicit stack, for the reason `rejectUnpairedSurrogates`
+ * is: this walks bytes a producer wrote. It relies on the text being valid
+ * JSON, which is why it runs only after `JSON.parse` succeeded: outside a
+ * string, only `{`, `[`, `}`, `]`, `,` and `"` change what comes next.
+ */
+export declare function firstDuplicateKey(text: string): string | undefined;
+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>;