@sanning/proof 0.19.1 → 0.20.0

package/src/index.ts

@@ -1,39 +1,23 @@
-// @sanning/proof — TypeScript kernel of the Sanning verification stack.
-//
-// The verification primitives for the Verifiable Event Envelope family
-// (specs/envelope-spec.md), sanning.agent/v1 profile: RFC 8785 (JCS)
-// canonicalization, SHA-256, Ed25519 envelope verification, and the
-// content-hash extraction used for reverse provenance lookup. Sibling of the
-// Python `sanning-proof` kernel and the Go `pkg/proof` reference; conformance
-// is byte-for-byte against the shared `test-vectors/` corpus.
-//
-// Scope boundary (envelope-spec §10 #13): this package verifies a SINGLE
-// envelope. Chain walking (previous_hash), checkpoint reconciliation, and
-// gateway/transport concerns are consumer-layer logic composed above it.
+// @sanning/proof: the TypeScript verification kernel for the Verifiable Event
+// Envelope family (specs/envelope-spec.md): RFC 8785 (JCS), SHA-256, Ed25519
+// envelope verification, and the bundle, pack and case readings built on them.
+// Conformance is byte-for-byte against the shared `test-vectors/` corpus.
 
-// ACCEPTED_SPEC_MAJORS is exported for parity with the sibling kernels'
-// 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
-// mutable accept-set would be a runtime-widenable kernel. Additive — no
-// existing export changes.
+// The accept-set this build admits. Frozen at its definition, because the
+// verifier reads the same array.
 export {
   ACCEPTED_SPEC_MAJORS,
   contentHashes,
   jcs,
   specVersionSupported,
   verifyEnvelope,
+  envelopeFault,
+  envelopeFaults,
 } from "./verifier.js";
-// The strict reader of bytes that claim to be JCS, the twin of Python's public
-// `canonicalize.jcs_loads`. The enclave attestation adapters read a token's
-// JSON through it, so they refuse what the kernel refuses. Additive.
+export { ENVELOPE_FAULTS } from "./types.js";
+export type { EnvelopeFault } from "./types.js";
+// The strict reader of bytes that claim to be JCS (Python's `jcs_loads`).
 export { jcsParse } from "./verifier.js";
-// The same reader within the enclave readers' limits (enclave-attestation
-// section 2.1): depth checked on the bytes first, every number finite. The
-// adapters read a token's header and claims and the manifest through it.
-// Additive.
-export { exceedsTextDepth, hasNonFiniteNumber, jcsParseWithinLimits, MAX_READ_DEPTH } from "./verifier.js";
 export {
   bytesToHex,
   deriveOperatorAddress,
@@ -55,20 +39,10 @@ export {
 } from "./merkle.js";
 export type { ContentRole, Envelope, Subject, VerificationResult, VerifyOptions } from "./types.js";
 
-// Evidence-bundle verification (specs/evidence-bundle.md): the signed
-// sanning.evidence/v1 wrapper carrying the sanning.anchor.trace/v3 body. The CLI
-// (`npx @sanning/proof verify`) is built on this. The same path dispatches on the
-// issuer-composed sanning.evidence.export/v2 body (specs/evidence-export.md) to
-// verifyExportBody (embedded RSA-PSS operator attestations + a recomputed §4
-// verdict object with per-gateway on-chain outcomes).
-//
-// `disclosedContent` is the INGEST half of the same path (evidence-bundle
-// §5.1). A received bundle carries its disclosed raw bytes as lowercase hex, so
-// materializing them was, until now, every consumer re-implementing the
-// encoding convention — and a consumer that copied the field VERBATIM wrote
-// 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.
+// Evidence-bundle verification (specs/evidence-bundle.md), including the
+// sanning.evidence.export/v2 body (specs/evidence-export.md).
+// `disclosedContent` returns decoded disclosed bytes, only for events whose
+// verification bound them to the committed content_hash.
 export {
   ACCEPTED_EVIDENCE_MAJORS,
   ANCHOR_TRACE_BODY_TYPE,
@@ -96,7 +70,6 @@ export type {
   EvidenceBundleResult,
   EvidenceIssuer,
   EvidenceStatus,
-  EvidenceVerdict,
   EventResult,
   ExportBody,
   ExportResult,
@@ -125,21 +98,9 @@ export type {
   VerifyEvidenceOptions,
 } 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.
-//
-// The rule is already normative in evidence-bundle.md §5.1 (absent disclosure is
-// undetermined, not failed) and §6 (no status ever means "safe"); what the
-// surfaces added on top was a sharper word for undetermined and an account of
-// what the pack failed to disclose. It lived twice, in two repos and two
-// languages, and the two derivations had already diverged once. It lives here.
-//
-// Pure — data in, data out, no I/O, so the kernel's scope boundary
-// (specs/architecture.md §3) is unchanged. `vectors/pack-grading.json` is the
-// conformance statement of the rule and ships in the published tarball, so a
-// 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.
+// Pack grading: what a verification surface may claim about a pack and the
+// disclosed bytes beside it (evidence-bundle.md §5.1, §6). Pure.
+// `vectors/pack-grading.json` states the rule for consumers to test against.
 export {
   PACK_GRADE_CAUSE_KINDS,
   PACK_VERDICTS,
@@ -160,22 +121,9 @@ export type {
   PackVerdict,
 } from "./grading.js";
 
-// The declaration (src/declaration.ts): what a pack SAYS it holds, checked
-// against what it does (evidence-bundle.md §5.4).
-//
-// Every other check in this kernel checks a record that is PRESENT, so a pack
-// with half its records dropped verifies perfectly and an auditor cannot tell
-// a full hand-over from a trimmed one. The declaration is the pack's own
-// statement of what it was meant to contain, inside `body` and therefore under
-// the bundle's signature. Any deviation FAILS and every deviation is NAMED; a
-// pack that carries no declaration is `partial`, never `verified`; and a
-// reading that rests on the UNSIGNED content handed in beside the pack is
-// named on its own and carries the weaker word, because whoever assembles a
-// case chose those bytes (proof#147).
-//
-// 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.
+// The declaration: what a pack says it holds, checked against what it does
+// (evidence-bundle.md §5.4). Pure. `gradePack` takes the result as an optional
+// fourth argument.
 export {
   DECLARATION_CONTENT_KINDS,
   DECLARATION_DEVIATION_KINDS,
@@ -208,23 +156,10 @@ export type {
   PackRecord,
 } 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.
-//
-// A pack a party assembles about itself is not self-proving about what that
-// party LEFT OUT (envelope-spec.md §4.1 A15, evidence-bundle.md §5.4.2 rule 7),
-// 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 (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.
+// The case: one verdict over several parties' packs, closing what a single
+// pack cannot prove about its own omissions (evidence-bundle.md §5.5).
+// Matching is on keys and hashes alone, never tenancy, so a pair across two
+// organizations verifies. `readCase` verifies every pack itself, offline.
 export {
   CASE_BODY_TYPES,
   CASE_EXCEPTION_KINDS,
@@ -243,6 +178,7 @@ export {
   WITNESS_STATES,
   WITNESS_TIME_CACHED,
   WITNESS_TIME_RECORDED,
+  caseProblems,
   caseReliance,
   readCase,
   renderCaseNote,
@@ -250,8 +186,8 @@ export {
   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.
+// The witnessed-time cache (evidence-bundle.md §5.6.6). Never an input to a
+// verdict.
 export {
   MAX_BLOCK_TIME,
   MAX_WITNESS_CACHE_DEPTH,
@@ -265,21 +201,73 @@ export {
 } from "./witness-cache.js";
 export type { CachedWitnessTime, WitnessTimeAnswer, WitnessTimeCheck } from "./witness-cache.js";
 
-// The public-record (witness) lookup the CLI runs with `--gateways`
-// (src/witness-lookup.ts, proof#200): moved out of the CLI so a consumer
-// that is not the CLI, the verify page, calls the SAME implementation
-// rather than keeping its own copy (verify-page#70). Pure kernel scope: the
-// one network call lives in `lookupPublicRecord` and `onChainHalf`, runs
-// only when a caller hands in a gateway, and goes through `options.fetchImpl`
-// where a caller supplies one (a browser page's own `fetch`) or the ambient
-// global `fetch` otherwise, so this export runs in a browser exactly as it
-// runs in Node. `onChainHalf` and `witnessLine` are the CLI's own unchanged
-// building blocks; `lookupPublicRecord` is the new one-call, four-state entry
-// point a page wants, additive over both. `confirmed` from
-// `lookupPublicRecord` is a claim about the BYTES only, never about whether
-// the pack itself verifies, and a caller must never show it apart from the
-// pack's own verdict.
-export { lookupPublicRecord, onChainHalf, witnessLine } from "./witness-lookup.js";
+// The public-record lookup behind `--gateways`. The only network call runs when
+// a caller hands in a gateway, through `options.fetchImpl` or the global
+// `fetch`, so it runs in a browser. `confirmed` is a claim about the bytes
+// only: never show it apart from the pack's own verdict.
+export {
+  lookupPublicRecord,
+  onChainHalf,
+  onChainOutcome,
+  onChainRow,
+  witnessLine,
+} from "./witness-lookup.js";
+
+// Six claims, three verdicts, and the person layer (evidence-bundle.md section 3): every
+// detailed kind maps to one claim and one state, and the verdict is read off the claims.
+export {
+  CLAIMS,
+  CLAIM_LABELS,
+  CLAIM_QUESTIONS,
+  CLAIM_STATES,
+  ENVELOPE_FAULT_KINDS,
+  KIND_CLAIMS,
+  NOTE_FINDINGS,
+  NOTE_ORDER,
+  NOT_IN_SCOPE_REASONS,
+  NOT_PROVEN_REASONS,
+  PERSON_TITLES,
+  PERSON_TITLE_PARTS,
+  REASON_KINDS,
+  RECORD_REASON_CLAIMS,
+  RECORD_REASON_LINES,
+  SANDBOX_PERSON_LINE,
+  VERDICTS,
+  VERDICT_COLOURS,
+  VERDICT_TITLES,
+  bundleProblems,
+  claimsOf,
+  downgraded,
+  note,
+  orderedNotes,
+  restOnSigned,
+  personText,
+  problem,
+  problemToJson,
+  renderFindingNote,
+  renderPerson,
+  verdictOf,
+  withItems,
+} from "./claims.js";
+export type {
+  Claim,
+  ClaimEntry,
+  ClaimItem,
+  ClaimState,
+  Labels,
+  LinePart,
+  NoteEntry,
+  NotInScopeReason,
+  NotProvenReason,
+  Person,
+  Problem,
+  ProblemItem,
+  ProblemJson,
+  ProblemValues,
+  ReasonKind,
+  Verdict,
+  VerdictJson,
+} from "./claims.js";
 export type {
   OnChainHalf,
   OnChainRow,
@@ -304,9 +292,8 @@ export type {
   WitnessState,
 } 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.
+// The case file's index (evidence-bundle.md §5.6), compared with the drop it
+// describes. Never an input to `readCase` or any verdict.
 export {
   CASE_FILE_FINDING_KINDS,
   CASE_FILE_INDEX_NAME,
@@ -324,9 +311,8 @@ export type {
   CaseFileIndexReading,
 } 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.
+// Files handed in beside a pack (evidence-bundle.md §5.7), matched by SHA-256
+// against the pack's signed commitments. Never moves a verdict.
 export {
   FILE_MATCH_SCOPE,
   NOT_READ_REASONS,
@@ -350,29 +336,11 @@ export type {
   UnmatchedFile,
 } 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.
-//
-// Every anchored event has carried that pointer since the profile was ratified
-// and nothing we shipped read it, so a bundle with an event removed — and a
-// chain that restarted after a crash and now asserts two beginnings — passed
-// every check we had (proof#43). The verifier was right not to do this: it
-// verifies a single envelope and says so. Nothing above it did it either.
-//
-// Pure — data in, data out, no I/O — so the kernel's scope boundary
-// (specs/architecture.md §3) is unchanged, and the rule ships as
-// `vectors/chain-reading.json` beside the pack-grading table for the same
-// reason: a rule consumers must agree with needs a statement they can fetch.
-//
-// It returns FINDINGS, never a verdict, and it feeds no status on its own: a
-// pack's signed v3 declaration can claim a chain complete and in order, and
-// `checkDeclaration` holds that claim to the links `readChainLinks` reads
-// (evidence-bundle.md 5.4.2 rule 11). Chain links are
-// deletion/reorder-evidence for the events present and NOT a completeness proof
-// (`anchor/docs/profile-sanning.events-v2.md` §5), drop the last N events of a
-// chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
-// every surface prints the same limit rather than paraphrasing it into a claim.
-// Additive — no existing export changes.
+// Chain reading: findings over the `previous_hash` links one bundle presents,
+// never a verdict and never a completeness proof. `CHAIN_READING_SCOPE` is the
+// sentence every surface prints beside them. `vectors/chain-reading.json`
+// states the rule; a v3 declaration's chain claim is checked against
+// `readChainLinks` (evidence-bundle.md §5.4.2 rule 11).
 export {
   ADAPTER_CHAIN_NAMESPACES,
   CHAIN_READING_SCOPE,
@@ -389,55 +357,31 @@ export type {
   ChainSummary,
 } from "./chain.js";
 
-// The `proof export` composer (specs/evidence-export.md §5, phase 2): produce a
-// 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.
+// The `proof export` composer (specs/evidence-export.md §5): a signed,
+// offline-verifiable sanning.evidence.export/v2 artifact. Also the one
+// exit-code table and help text every verb uses.
 export {
   EXIT_CODES,
   EXIT_CODES_HELP,
+  EXIT_COULD_NOT_RUN,
   EXIT_FAILED,
-  EXIT_MALFORMED,
-  EXIT_MIXED,
+  EXIT_INCOMPLETE,
   EXIT_SANDBOX,
-  EXIT_UNDETERMINED,
   EXIT_VERIFIED,
   exitCodeFor,
-  sandboxExit,
 } from "./exit-codes.js";
-// Sandbox evidence: the environment marker over the envelopes a pack or case
-// holds (envelope-spec §2, the `environment_marker` MAY), and the headline and
-// line both commands print for it. Additive.
+// Sandbox evidence: the environment marker over a pack's or case's envelopes
+// (envelope-spec section 2).
 export {
-  SANDBOX_HEADLINE,
-  SANDBOX_LINE,
-  SANDBOX_TITLE,
   environmentMarker,
-  onlySimulatedUnsettled,
   packEnvelopes,
 } from "./environment.js";
 export type { EnvironmentMarker } from "./environment.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } 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_VERSION, isAgentProofSpec, verifyAgentProof } from "./agent-proof.js";
-export type {
-  AgentProofBundle,
-  AgentProofResult,
-  VerifyAgentProofOptions,
-} 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
-// v1.9, proof#132 and proof#136). The Python half is src/sanning_proof/handoff.py and the two
-// answer identically on identical bytes. Additive: a new module, and no
-// existing export changes.
+// The hand-off pairing rule (envelope-spec.md §4.1). The Python half answers
+// identically on identical bytes.
 export {
   CANDIDATE_NAMESPACE,
   DEFINED_EVENT_TYPES,
@@ -445,7 +389,9 @@ export {
   isConformantHandoffRecord,
   readHandoff,
   readHandoffs,
+  recordDefect,
   recordIsMalformed,
+  recordIsNonconforming,
 } from "./handoff.js";
 export type {
   CandidateReading,
@@ -455,14 +401,9 @@ export type {
   HeldRecord,
 } from "./handoff.js";
 
-// A file part's BYTES (src/message-parts.ts): what a file part is, and what a
-// receiver that HOLDS a part's bytes commits to (envelope-spec.md section 4.1
-// v1.13, A18, proof#145). A receiver that holds the bytes hashes them and, on a
-// mismatch, commits to the message AS IT HELD IT, so the pair fails on
-// `message_hash` rather than verifying over bytes nobody checked. The Python
-// half is src/sanning_proof/message_parts.py and the two are held together by
-// cross-kernel/run_parts.sh. Pure: it neither canonicalizes nor hashes the
-// message.
+// File parts (envelope-spec.md §4.1): a receiver holding a part's bytes
+// commits to the message as it held it, so a mismatch fails on `message_hash`
+// rather than verifying over unchecked bytes.
 export {
   BYTES_FOR_UNKNOWN_PART,
   CONFLICTING_PART_BYTES,
@@ -484,3 +425,16 @@ export {
   uncheckedHeldParts,
 } from "./message-parts.js";
 export type { HeldMessage, Note, PartReading, Refusal, SuppliedPart } from "./message-parts.js";
+
+// Reading a sanning.agent record (vendor/specs/agent-events.md §10) against
+// the schemas bundled from the pinned specs release: no file read, no fetch.
+export {
+  AGENT_EVENT_TYPES,
+  RECORD_TYPES_OUTSIDE_AGENT,
+  readAgentRecord,
+  readAgentRecordWithHeld,
+  readAgentRecords,
+  renderAgentReading,
+} from "./agent-record.js";
+export type { AgentHeldRecord, AgentReason, AgentRecordReading, AgentVerdict } from "./agent-record.js";
+export { AGENT_SCHEMA_PIN, AGENT_SCHEMA_VERSIONS } from "./agent-schemas.generated.js";