contracts: Receipt v1 schema, canonicalization, verify rules, test vectors

verify_rules.md

@@ -0,0 +1,42 @@
+# Receipt Verification Rules (v1)
+
+Applies to receipts conforming to `receipt_v1.schema.json`.
+
+## Receipt verification
+
+A verifier MUST:
+
+1. Parse JSON and validate against the schema.
+2. Recompute `canonical_json_bytes` (per `canonicalization.md`) **excluding** signature fields.
+3. Recompute `blake3` and `sha256`; require they match the envelope fields.
+4. If signature fields are present:
+   - Require `sig_alg == "ed25519"`.
+   - Verify `signature` over UTF-8 bytes of the **hex `blake3` string** (vm-cloud convention).
+   - Require `signer_pub` matches verification key.
+5. Return success only if all checks pass.
+
+## Chain verification
+
+- `prev_blake3` forms a singly-linked chain of receipts.
+- If a `HEAD` file is maintained, verify:
+  - `HEAD.created_at` is ISO-8601.
+  - `HEAD.blake3` matches the `blake3` of the latest receipt.
+  - The latest receipt’s `prev_blake3` matches the previous `HEAD.blake3` (or null for genesis).
+- For a sequence of receipts, iterate in order and ensure every `prev_blake3` matches the prior receipt’s `blake3`; fail on the first discontinuity.
+
+## Merkle receipts (for external checkpoints)
+
+When receipts are batched into Merkle proofs:
+
+- **Input ordering**: preserve the chronological order of receipts as leaves (stable, prefix-based trees).
+- **Leaf hashing**: `leaf = BLAKE3("VM-receipt-leaf-v1" || blake3_bytes)` where `blake3_bytes` is the 32-byte digest of the receipt body (not hex string; decode hex to bytes).
+- **Node hashing**: `node = BLAKE3("VM-receipt-node-v1" || left || right)`.
+- **Odd count rule**: duplicate the last node at each level when odd (standard Merkle padding).
+- **Root format**: hex-encoded lowercase BLAKE3 of the final root node.
+- **Inclusion proof**: sibling list from leaf → root, each sibling annotated with side ("left" | "right").
+
+## Fail-closed guidance
+
+- Any missing or invalid `session_token` in tool-executed receipts SHOULD be treated as unverifiable and rejected by consumers.
+- Signature presence is optional, but if present must verify; otherwise treat as invalid.
+- Reject receipts whose `hash_alg` is not exactly `blake3+sha256`.