@sanning/proof 0.9.2 → 0.11.0

package/vectors/pack-grading.json

@@ -1,10 +1,10 @@
 {
   "rule": "pack-grading",
-  "ruleVersion": 2,
-  "statement": "What a verification surface may CLAIM about a pack it was handed. verified is reachable ONLY when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted. Absent or unreadable evidence is incomplete (UNKNOWN), never failed and never verified. A hard kernel verdict wins: malformed > failed > incomplete > the kernel's own headline.",
+  "ruleVersion": 5,
+  "statement": "What a verification surface may CLAIM about a pack it was handed. verified is reachable ONLY when every record's own bytes bound to its own commitment and nothing is missing, unreadable, surplus or omitted. Absent or unreadable evidence is incomplete (UNKNOWN), never failed and never verified. A hard kernel verdict wins: malformed > failed > incomplete > the kernel's own headline. A pack that DEVIATES from its own signed declaration (evidence-bundle.md \u00a75.4) is failed, and every deviation is a cause: a declared record that is absent, a present record nobody declared, or a record the pack declared withheld whose bytes its own SIGNED BODY supplies. A reading that rests instead on the UNSIGNED content handed in beside a pack is not a deviation and never reaches failed (proof#147): each content-dependent finding is its own cause and carries the pack to incomplete, because whoever assembles a case fills that map in, so an accuser holding an intact pack could otherwise reach failed with no key at all. A deviation and a content-dependent finding together are still failed, because the deviation reads off the signed body and a failing check wins. A declaration check that came back partial therefore splits in THREE, and only two of the three turn on the declaration's readability: no declaration member in the body at all moves nothing, because every pack built before \u00a75.4 is that case; a declaration the reader CANNOT READ makes the pack incomplete, because declaration_version is chosen by the party that assembles the pack and has no accept-set, so an unreadable claim must never reach a clean verdict; and a declaration the reader read perfectly well whose disclosure only unsigned bytes could settle makes the pack incomplete as well, named as what the reader could not establish rather than as what the holder did. The grade carries the declaration check verdict in its own output field, so a consumer that keeps only the grade can still tell a declared pack from an undeclared one.",
   "home": "@sanning/proof — ts/vectors/pack-grading.json. This file is the RULE, not a test fixture of one implementation. The kernel implements it in ts/src/grading.ts and is held to it by ts/test/grading.test.ts.",
   "consumers": "A surface that grades packs SHOULD call the kernel's gradePack rather than derive the rule again. A surface that cannot yet (an older pinned kernel, another language) vendors this file byte-for-byte, asserts its own derivation against it, and runs a drift check that compares its copy against the copy shipped in the @sanning/proof tarball at vectors/pack-grading.json. A vendored copy that is not byte-identical to this one is a defect, not a variant.",
-  "howToUse": "Adapt a kernel verification result and a disclosure account into the shapes below, call gradePack, and assert the expectations. `kernel` gives the per-event outcome classes the kernel returns; `logs` gives the account of which records disclosed bytes; `omissions` gives the signed-leaf_count completeness notes. Nothing here depends on how the bytes were transported — a directory read and a browser drop produce the same account and must produce the same verdict.",
+  "howToUse": "Adapt a kernel verification result and a disclosure account into the shapes below, call gradePack, and assert the expectations. `kernel` gives the per-event outcome classes the kernel returns; `logs` gives the account of which records disclosed bytes; `omissions` gives the signed-leaf_count completeness notes. Nothing here depends on how the bytes were transported: a directory read and a browser drop produce the same account and must produce the same verdict. `declaration`, where a case carries one, gives the declaration check's verdict, whether the body carried a declaration member at all, and how many deviations it found; pass a check of that shape as gradePack's optional fourth argument. A case with no `declaration` key calls gradePack with three arguments, which is the pre-§5.4 behavior and must not move, and its `expect.declaration` is absent.",
   "kernelEventClasses": {
     "okBound": "{ ok: true, contentOk: true } — the record's own bytes hashed to its own commitment",
     "okUnknown": "{ ok: true, contentOk: null } — structurally fine, but no bytes were disclosed",
@@ -52,6 +52,14 @@
       "omissions": [],
       "expect": { "verdict": "incomplete", "recordsVerified": 0, "recordsFailed": 0, "recordsUndetermined": 26, "causeCount": 1 }
     },
+    {
+      "id": "withheld-record-clean-account",
+      "why": "the case the terminal got wrong (proof#110). A bundle the kernel grades `verified` under evidence-bundle.md §3, holding one record the producer WITHHELD. The disclosure account is clean, and correctly so: no bytes were ever expected for a record that was never offered, so nothing is missing, unreadable, surplus or omitted and there is no cause to report. The record is still unhashed. The PACK is `incomplete` while the BUNDLE is `verified`: the two enums are distinct, and an undetermined record ON ITS OWN is enough to downgrade, with no cause beside it. Every other incomplete case here carries a cause, so a surface could satisfy all of them by keying off `causes` alone and still print a green verdict over a record nobody checked, which is exactly what `proof verify` did.",
+      "kernel": { "status": "verified", "okBound": 2, "okUnknown": 1, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 2, "present": 2, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "expect": { "verdict": "incomplete", "recordsVerified": 2, "recordsFailed": 0, "recordsUndetermined": 1, "causeCount": 0 }
+    },
     {
       "id": "one-log-unreadable",
       "why": "a file we could not read is our fault, not the record's — UNKNOWN",
@@ -131,6 +139,126 @@
       "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
       "omissions": [],
       "expect": { "verdict": "incomplete", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0 }
+    },
+    {
+      "id": "declaration-matches",
+      "why": "a pack that holds exactly what its declaration says it holds: the declaration adds no cause and moves no verdict",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "declaration": { "verdict": "verified", "present": true, "deviations": 0 },
+      "expect": { "verdict": "verified", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0, "declaration": "verified" }
+    },
+    {
+      "id": "declaration-deviates",
+      "why": "the trimmed hand-over. Every record present verifies and nothing is missing from the disclosure account, so every other check is green; the pack deviates from its own declaration and that is a FAILURE, never an absence",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "declaration": { "verdict": "failed", "present": true, "deviations": 1 },
+      "expect": { "verdict": "failed", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 1, "declaration": "failed" }
+    },
+    {
+      "id": "declaration-content-dependent",
+      "why": "the pack agrees with its own claim everywhere its signature reaches, and does not line up with the UNSIGNED content handed in beside it. A NAMED cause and incomplete, never failed: an accuser holding an intact pack reaches this by dropping one file or adding one, with no key at all (proof#147)",
+      "kernel": {
+        "status": "verified",
+        "okBound": 26,
+        "okUnknown": 0,
+        "mismatched": 0,
+        "brokenNoContent": 0
+      },
+      "logs": {
+        "expected": 26,
+        "present": 26,
+        "missing": 0,
+        "unreadable": 0,
+        "extra": 0
+      },
+      "omissions": [],
+      "declaration": {
+        "verdict": "partial",
+        "present": true,
+        "deviations": 0,
+        "contentFindings": 1
+      },
+      "expect": {
+        "verdict": "incomplete",
+        "recordsVerified": 26,
+        "recordsFailed": 0,
+        "recordsUndetermined": 0,
+        "causeCount": 1,
+        "declaration": "partial"
+      }
+    },
+    {
+      "id": "declaration-deviation-beats-a-content-finding",
+      "why": "one of each, over different records. The deviation reads off the pack's own signed body so the pack FAILS, and the content-dependent finding is still its own cause: two classes, both reported, neither folded into the other",
+      "kernel": {
+        "status": "verified",
+        "okBound": 26,
+        "okUnknown": 0,
+        "mismatched": 0,
+        "brokenNoContent": 0
+      },
+      "logs": {
+        "expected": 26,
+        "present": 26,
+        "missing": 0,
+        "unreadable": 0,
+        "extra": 0
+      },
+      "omissions": [],
+      "declaration": {
+        "verdict": "failed",
+        "present": true,
+        "deviations": 1,
+        "contentFindings": 1
+      },
+      "expect": {
+        "verdict": "failed",
+        "recordsVerified": 26,
+        "recordsFailed": 0,
+        "recordsUndetermined": 0,
+        "causeCount": 2,
+        "declaration": "failed"
+      }
+    },
+    {
+      "id": "declaration-names-every-deviation",
+      "why": "three deviations in one pack are three causes. A rule that reported one shortfall would pass the case above and lose the other two findings",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "declaration": { "verdict": "failed", "present": true, "deviations": 3 },
+      "expect": { "verdict": "failed", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 3, "declaration": "failed" }
+    },
+    {
+      "id": "declaration-deviation-beats-incomplete",
+      "why": "a proven mismatch between what a pack claimed and what it carries is never softened into absence, even when the pack is also missing disclosed bytes",
+      "kernel": { "status": "verified", "okBound": 20, "okUnknown": 6, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 20, "missing": 6, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "declaration": { "verdict": "failed", "present": true, "deviations": 1 },
+      "expect": { "verdict": "failed", "recordsVerified": 20, "recordsFailed": 0, "recordsUndetermined": 6, "causeCount": 2, "declaration": "failed" }
+    },
+    {
+      "id": "declaration-absent-moves-nothing",
+      "why": "a pack with no declaration: partial is the declaration check's own answer, and pack grading keeps its existing verdict. Every pack built before \u00a75.4 is this case, and re-grading them would be a spec change wearing an optional argument. `present` is false, which is what separates this case from the one below it",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "declaration": { "verdict": "partial", "present": false, "deviations": 0 },
+      "expect": { "verdict": "verified", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0, "declaration": "partial" }
+    },
+    {
+      "id": "declaration-unreadable-is-incomplete",
+      "why": "a pack that DOES carry a declaration and wrote it in a shape this reader cannot read. `declaration_version` is chosen by the same party that assembles the pack and has no accept-set, so a holder can trim a record, write one unreadable field and re-seal the whole body with its own key: every other check stays green and the evidence of the trim sits inside the signed body. `partial` keeps its meaning on the CHECK, and the PACK is incomplete, because a claim the reader cannot read is not a claim the reader may ignore. The case above and this one differ only in `present`, and a rule that reads the verdict alone passes both while grading one of them clean",
+      "kernel": { "status": "verified", "okBound": 26, "okUnknown": 0, "mismatched": 0, "brokenNoContent": 0 },
+      "logs": { "expected": 26, "present": 26, "missing": 0, "unreadable": 0, "extra": 0 },
+      "omissions": [],
+      "declaration": { "verdict": "partial", "present": true, "deviations": 0 },
+      "expect": { "verdict": "incomplete", "recordsVerified": 26, "recordsFailed": 0, "recordsUndetermined": 0, "causeCount": 0, "declaration": "partial" }
     }
   ]
 }

package/vectors/stamp-on-chain.json

@@ -4,7 +4,7 @@
   "statement": "What re-fetching a stamp's witness from a gateway DOES and DOES NOT settle. A stamp body carries no producer signature and no inclusion proof of its own, so the witness is the entire independent part of it (evidence-bundle.md §5.2.4): confirming that a gateway holds the exact bytes named by anchor_ref is the only check that turns Sanning's own assertion into evidence. It is an ONLINE act and always optional — an offline verdict is unchanged by it and never claims it happened. Four states, never three: not-checked (no gateway was asked, or the stamp names no witness), confirm (a gateway returned the witnessed bytes), mismatch (a gateway returned DIFFERENT bytes — the only outcome that fails anything), unreachable (we asked and nobody answered — an availability gap, never an accusation). The expected bytes are stamps[].stamp_bytes VERBATIM, because §5.2.2 defines that field as the exact bytes handed to the witness; re-canonicalizing them would compare the chain against bytes nobody signed.",
   "home": "@sanning/proof — ts/vectors/stamp-on-chain.json. This file is the RULE, not a test fixture of one implementation. The TypeScript kernel implements it in ts/src/evidence.ts (refetchStamps / refetchStamp / probeGateway / rollupOnChain) and is held to it by ts/test/stamp-on-chain-vectors.test.ts; the Python kernel implements it in src/sanning_proof/evidence.py (_refetch_stamps / _refetch_stamp / _probe_gateway / _rollup_on_chain) and is held to the SAME file by tests/test_stamp_on_chain_vectors.py. Neither kernel can pass by agreeing with the other.",
   "consumers": "A surface that re-fetches a stamp witness SHOULD call the kernel's verifyEvidenceBundle with `gateways` rather than derive the rule again. A surface that cannot yet (an older pinned kernel, another language) vendors this file byte-for-byte, asserts its own derivation against it, and runs a drift check against the copy shipped in the @sanning/proof tarball at vectors/stamp-on-chain.json — failing when it cannot find a copy to compare against. A vendored copy that is not byte-identical to this one is a defect, not a variant. In particular: a surface MUST NOT collapse the four states into a boolean. A reader that cannot distinguish not-checked from unreachable will report that no gateway could be reached when none was tried, which is a false accusation manufactured by a missing state, and is the defect this table was written after.",
-  "howToUse": "Each case describes one sanning.stamp.evidence/v1 pack and one set of scripted gateway responses. Build the pack from `packScaffold`: for each entry of `stamps` (index i, 0-based) sign ONE sanning.events/v1 envelope over the record {\"event\":{\"content_hash\":\"<64×a>\"},\"i\":i} with event_id `ev-<i>` and the fixed seed, take its leaf under RFC 9162 (SHA-256(0x00 ‖ JCS(envelope))), make a one-leaf tree, and build the stamp body from `stampBodyScaffold` with merkle_root = that root, leaf_count = 1 and one sub-tree covering [0,1). stamp_bytes is JCS(stamp body) hex-encoded; stamp_ref is SHA-256 of the DECODED bytes. When the entry's `witnessed` is true attach anchor_ref = {kind: \"arweave\", id: `<anchorIdPrefix><i>`}, otherwise omit anchor_ref entirely. Give each stamp one event whose inclusion is {stamp_ref, leaf_index: 0, leaf_count: 1, leaf_hash, audit_path: []}. Wrap the body per `wrapperScaffold`, set body_hash = SHA-256(JCS(body)) and sign the wrapper (minus `signature`) with the same seed. Then call the kernel with the case's `gateways` and a fetch seam that answers `{gateway}/{anchor id}` per the `returns` entry for that stamp at that gateway's index, and assert `expect`. A case with an empty `gateways` list is called with no gateway list at all — that is the not-checked state and it must be reachable without a fetch seam.",
+  "howToUse": "Each case describes one sanning.stamp.evidence/v2 pack and one set of scripted gateway responses. Build the pack from `packScaffold`: for each entry of `stamps` (index i, 0-based) sign ONE sanning.events/v2 envelope over the record {\"event\":{\"content_hash\":\"<64×a>\"},\"i\":i} with event_id `ev-<i>` and the fixed seed, take its leaf under RFC 9162 (SHA-256(0x00 ‖ JCS(envelope))), make a one-leaf tree, and build the stamp body from `stampBodyScaffold` with merkle_root = that root, leaf_count = 1 and one sub-tree covering [0,1). stamp_bytes is JCS(stamp body) hex-encoded; stamp_ref is SHA-256 of the DECODED bytes. When the entry's `witnessed` is true attach anchor_ref = {kind: \"arweave\", id: `<anchorIdPrefix><i>`}, otherwise omit anchor_ref entirely. Give each stamp one event whose inclusion is {stamp_ref, leaf_index: 0, leaf_count: 1, leaf_hash, audit_path: []}. Wrap the body per `wrapperScaffold`, set body_hash = SHA-256(JCS(body)) and sign the wrapper (minus `signature`) with the same seed. Then call the kernel with the case's `gateways` and a fetch seam that answers `{gateway}/{anchor id}` per the `returns` entry for that stamp at that gateway's index, and assert `expect`. A case with an empty `gateways` list is called with no gateway list at all, that is the not-checked state and it must be reachable without a fetch seam.",
   "responseKinds": {
     "witnessed": "The exact decoded stamp_bytes. The honest chain.",
     "altered": "JCS of the same stamp body with interval_end changed to 2026-09-09T13:00:00.000Z — a well-formed, canonical, semantically different stamp. This is the forgery shape that matters: a pack built on it is fully self-consistent OFFLINE and lies only about what was witnessed.",
@@ -13,7 +13,7 @@
     "unreachable": "The fetch fails: a network error, a timeout, a non-ok response, or no such transaction. Never a mismatch."
   },
   "alsoAppliesTo": "sanning.stamp.trace/v1 — the same case, with body_type changed and events[] dropped. Every case's `expect` holds UNCHANGED for that body, and a grader MUST run all of them twice. §5.2 and §5.3 carry the same stamps[] array under the same §5.2.2 definition, so they must give the same on-chain answer: a stamp that can be re-fetched inside one wrapper and not the other forces every consumer to know which wrapper it is holding before it can read `onChain: null`, and that is the kind of per-body exception a reader eventually gets wrong. The one case-level difference is outside this rule: a §5.2 body with no stamps at all is `partial` for carrying nothing, which no case here exercises.",
-  "anchorIdPrefix": "stampOnChainFixtureAnchorId0000000000-",
+  "anchorIdPrefix": "stampOnChainFixtureAnchorId00000000000000-",
   "packScaffold": {
     "seedHex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "eventIdPrefix": "ev-",
@@ -30,7 +30,7 @@
   },
   "wrapperScaffold": {
     "spec_version": "sanning.evidence/v1",
-    "body_type": "sanning.stamp.evidence/v1",
+    "body_type": "sanning.stamp.evidence/v2",
     "issuer": { "kind": "sanning" },
     "generated_at": "2026-09-09T12:20:00.000Z",
     "gateway": null,