[shreyanshjain7174]

Plan

Phase 1 of the AgentGate scale-out prompt: freeze the receipt spec as the code behaves today. No Rust or v2 work starts before this is merged.

What changed

• docs/spec/RECEIPT-v1.md describes exactly what the code does:

  • the length-prefixed binary hash preimage (fields, order, widths, domain strings, limits, 3,106-byte max);
  • the JCS rule for params_sha256;
  • the JSONL encoding;
  • the export manifest preimage and signature;
  • key ID derivation;
  • the policy decision enum and error-code rules;
  • the delegation-chain element format;
  • genesis linkage;
  • the step-by-step verification algorithm and its rejection reasons;
  • versioning rules.

  §10 has a byte-level worked example produced by the code.

• 20 golden vectors in pkg/receiptspec/testdata/v1/: valid chains (genesis, multi-receipt, delegation, unicode, boundary values), tampered body, reordered chain, truncated chain (middle and tail), wrong-key signature, bad prev_hash, unknown signer, manifest mismatch and more. A committed generator with fixed keys rebuilds them byte for byte.

• TestV1GoldenVectors runs every vector through the real ReadJSONL, LoadTrustedKeys and VerifyBundle, under explicit and embedded trust.

• Version lock. A test hashes the canonical preimages of the ok vectors and compares them against digests the generator never writes. Any encoding change fails it, with a message to bump format_version and write RECEIPT-v2.md.

• The README and package docs link the spec. Production code is unchanged apart from a 2-line doc comment.

Code and doc differences found (documented, not changed)

• Record root and raw-size limits differ from DECISION.md.
• genesis-unicode-max.bin actually holds seq MaxUint64.
• Empty exports are rejected. This fails closed.
• Delegation elements are not format-checked. The encoding stays unambiguous and the elements are signed.
• The verifier does not check manifest metadata, including the manifest signer's validity window. A follow-up PR hardens this without a wire change.

Validation

• go build ./...: passed
• go vet ./...: passed
• go test -race ./...: passed
• semgrep --config auto --error --quiet ./internal ./cmd ./pkg: passed, no findings
• Vectors regenerated twice: git diff empty

Review

Reviewed by a second model (Claude Opus 5.5). It recomputed §10's example independently: key, key ID, 183-byte preimage, entry hash, Ed25519 signature and manifest hash all match. It also rehashed every receipt in the valid vectors. Verdict: approved, no spec errors.