@sanning/proof 0.12.0 → 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/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.
@@ -85,7 +85,11 @@ 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_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.
 //
@@ -111,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>;

package/dist/verifier.js

@@ -19,7 +19,7 @@ import { ed25519Verify, isHexField, sha256Hex, utf8 } from "./crypto.js";
 // profile-specific dialect (no underscore strip, that is mlflow-only).
 //
 // Exported for parity with the sibling kernels' registries — Python
-// `ACCEPTED_SPEC_VERSIONS`, Go `SupportedSpecMajor` — so the accept-set is
+// `ACCEPTED_SPEC_MAJORS`, Go `SupportedSpecMajor` — so the accept-set is
 // assertable rather than inferable: test/accept-set.test.ts holds it to the
 // ratified §4/§5 set transcribed in cross-kernel/accept-set.json, and the
 // cross-kernel gate probes one signed envelope per identifier. This entry list
@@ -217,6 +217,15 @@ const JCS_BOM = "";
  * 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 function utf8Strict(bytes) {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
 export function jcsParse(bytes) {
     const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
     if (text.startsWith(JCS_BOM))
@@ -299,10 +308,14 @@ function hasLoneSurrogate(s) {
 // `<major>.<minor>` where minor is `[0-9]+`. A non-numeric minor suffix is
 // malformed, not a tolerated future version — matching the Python kernel's
 // 0.1.1 semantics (the TS/Go fail-open lenience was closed deliberately).
-export function specVersionSupported(specVersion) {
+//
+// `accepted` NARROWS the registry and never widens it, as the Python twin's
+// `spec_version_supported(spec_version, accepted)` does (P-10, 0.13.0).
+export function specVersionSupported(specVersion, accepted) {
     if (typeof specVersion !== "string" || specVersion === "")
         return false;
-    return ACCEPTED_SPEC_MAJORS.some((m) => {
+    const registry = accepted === undefined ? ACCEPTED_SPEC_MAJORS : ACCEPTED_SPEC_MAJORS.filter((m) => accepted.includes(m));
+    return registry.some((m) => {
         if (specVersion === m)
             return true;
         if (!specVersion.startsWith(`${m}.`))
@@ -444,18 +457,21 @@ export function contentHashes(env) {
 // signature, so stripping it to fake "external" — or injecting one to fake
 // "inline" — breaks the signature).
 //
-// The second argument accepts the legacy `expectedContentHash` string form
-// or a VerifyOptions object ({ payloadBytes, expectedContentHash }).
-export async function verifyEnvelope(env, optionsOrContentHash) {
-    const opts = typeof optionsOrContentHash === "string"
-        ? { expectedContentHash: optionsOrContentHash }
-        : (optionsOrContentHash ?? {});
+// The second argument is a VerifyOptions object ({ payloadBytes,
+// expectedContentHash, acceptedSpecMajors }). Until 0.13.0 it could also be a
+// bare `expectedContentHash` string; that overload is gone (P-10), so the two
+// kernels take one options shape: write `{ expectedContentHash: hash }`.
+export async function verifyEnvelope(env, options) {
+    if (typeof options === "string") {
+        throw new TypeError("verifyEnvelope: pass { expectedContentHash } rather than a bare string (0.13.0)");
+    }
+    const opts = options ?? {};
     // REFUSE an unknown option key rather than ignore it. `expected_content_hash`
     // — the Python kernel's spelling — previously fell through as `undefined`, so
     // the content bind silently never ran and the caller got a clean pass with no
     // errors at all. A check that quietly does not happen is worse than one that
     // fails: the caller believes they verified an artifact they never checked.
-    const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash"]);
+    const KNOWN_VERIFY_OPTIONS = new Set(["payloadBytes", "expectedContentHash", "acceptedSpecMajors"]);
     const unknownOptions = Object.keys(opts).filter((k) => !KNOWN_VERIFY_OPTIONS.has(k));
     if (unknownOptions.length > 0) {
         throw new TypeError(`verifyEnvelope: unknown option(s) ${unknownOptions.join(", ")}. ` +
@@ -528,7 +544,7 @@ async function verifyEnvelopeChecked(env, opts) {
             errors: ["envelope is not a JSON object"],
         };
     }
-    const specVersionOk = specVersionSupported(env.spec_version);
+    const specVersionOk = specVersionSupported(env.spec_version, opts.acceptedSpecMajors);
     if (!specVersionOk)
         errors.push(`unsupported spec_version: ${JSON.stringify(env.spec_version)}`);
     // Skeleton field format (envelope-spec §2, proof#95): a present `signed_at`
@@ -598,7 +614,7 @@ async function verifyEnvelopeChecked(env, opts) {
     let signatureOk = false;
     try {
         const { signature: _signature, co_signatures: _coSignatures, ...envelopeForSig } = env;
-        signatureOk = await ed25519Verify(env.signature, utf8(jcs(envelopeForSig)), env.public_key);
+        signatureOk = await ed25519Verify(utf8(jcs(envelopeForSig)), env.signature, env.public_key);
         if (!signatureOk)
             errors.push("Ed25519 signature verification failed");
     }

package/dist/zip-reader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one ZIP reader `case` uses, for a case file named on the command line.
+ *
+ * The TypeScript half of `src/sanning_proof/zip_reader.py`. Node has no ZIP
+ * reader, and Python's `zipfile` is not used, so the two kernels read one
+ * archive by one rule rather than by two libraries that disagree on the edges:
+ * a central directory that contradicts a local header, a name that is not
+ * UTF-8, data after the end of a deflate stream. Where either library would
+ * have made a choice, this module refuses instead.
+ *
+ * What it reads (evidence-bundle.md 5.6.1): the central directory, and each
+ * entry's data through its local header. Stored and deflate only. What it
+ * REFUSES, as a whole archive: no end-of-central-directory record, ZIP64, more
+ * than one disk, an entry the central directory places outside the archive, a
+ * local header that does not match its central entry, a size or CRC-32 that
+ * does not match the data, two entries with one name, a name that is not
+ * UTF-8, more than MAX_ZIP_ENTRIES entries or MAX_ZIP_BYTES bytes in all, and
+ * a name nested deeper than MAX_ZIP_DEPTH folders. What it REPORTS and never
+ * reads, entry by entry: an encrypted entry, a symbolic link, a method other
+ * than stored or deflate, and a name that is absolute, holds a backslash or a
+ * NUL, or has an empty, `.` or `..` segment.
+ *
+ * Pure: bytes in, entries out. The caller turns them into the tree `case`
+ * splits.
+ */
+/** More entries than this refuse the archive: the walk's own bound on names. */
+export declare const MAX_ZIP_ENTRIES = 50000;
+/** More uncompressed bytes than this, across every entry, refuse the archive. */
+export declare const MAX_ZIP_BYTES: number;
+/** A name nested deeper than this many folders refuses the archive. */
+export declare const MAX_ZIP_DEPTH = 32;
+/** The archive cannot be read as a case file. `message` is the whole report, identical in both kernels. */
+export declare class ZipReadError extends Error {
+    constructor(message: string);
+}
+/**
+ * One file entry. `refused` is why the entry is reported and not read, or
+ * `null`; `data` is its bytes where it was read.
+ */
+export interface ZipEntry {
+    name: string;
+    refused: string | null;
+    data: Uint8Array | null;
+}
+/**
+ * Every FILE entry of a ZIP archive, in central-directory order. A directory
+ * entry (a name ending in `/`) is not a file and is not returned. Throws
+ * `ZipReadError`.
+ */
+export declare function readZip(data: Uint8Array): ZipEntry[];