Your implementation passes every test you wrote. Then you run it against the public conformance corpus and it disagrees on a handful of vectors, and the disagreements look like the spec contradicting itself.
That is the normal first week with AER-1. The corpus is 143 vectors and 146 checks, frozen, and conformance means byte-identical verdicts to the reference runners, not verdicts that feel right. Almost everyone who has implemented the draft hit the same three traps on the first try. Two of them were surfaced in public this week by an outside team, probityai, who ran the kit, published what they found, and were right about the tension in both cases. The resolutions are now in the errata for draft -26. Here is what went wrong, and the rule that settles each one.
1. Failing receipts that were never required to carry metadata_hash
The symptom: your verifier rejects 0.4 receipts that have no metadata_hash, because Section 6 says a 0.4 receipt without it MUST fail. Then the corpus hands you ten receipts in the valid set with no metadata_hash at all, and your verifier fails the conformance run instead.
Both texts are real. Table 1 marks metadata_hash "Cond.": required when receipt_schema_version is "0.4" or later, and a verifier MUST recompute and compare it whenever present. The Section 6 sentence governs the metadata-binding claim, not the core verdict. The reading that fits the whole draft:
- A producer at 0.4 or later MUST emit metadata_hash. The reference producer does.
- A verifier MUST recompute it when it is present. A mismatch fails.
- Its absence is not a failure. The receipt is scored on form, output commitment, version agreement, and provenance binding, and the absence stays visible in the report. What you must never do is report the metadata as bound when the member is not there.
- If you are a consumer who needs tamper-evident metadata, require the member under your profile and reject its absence there (Section 13).
The trap is reading one MUST in isolation. The draft's conformance bar is the corpus plus the reference runners, and both pinned 0.4 shapes, with and without the member, are deliberate.
2. Accepting 5.0 as an integer
The symptom: a chain commitment says entry_count: 5.0 over a five-entry timeline. It looks like the same number. The corpus calls the vector invalid, and your verifier, which compared values, called it fine.
The difference is what happens to the value next. seq, the member Section 7.1 defines with almost the same words, is canonicalized into integer form before it feeds the entry digest, so 1 and 1.0 serialize identically ("1, never 1.0") and both are accepted. entry_count is never canonicalized. It is a recorded member of a standalone commitment artifact, compared exactly as recorded. For a member like that, "a JSON number with an integer value" is read under the draft's form discipline: encode it as a JSON integer, or the commitment check fails closed.
Producers: never emit an integer-valued float for a count. Verifiers: a mistyped member is a failed check, not a rounding opportunity. Run locally, the reference runner rejects the 5.0 vector with "commitment entry_count is not an integer" and passes the identical commitment written with 5. The encoding is the only defect.
3. Hashing the string you see instead of the bytes that were sent
The symptom: your hashes agree with your own test fixtures and disagree with everyone else's on any receipt whose content is not plain ASCII.
Unicode gives you two byte sequences for what looks like one string. An accented character can be stored as a single code point (NFC) or as a base character plus a combining mark (NFD). On screen they are identical. To SHA-256 they are different inputs, so two honest implementations, each hashing "the same" text, produce different commitments, and each concludes the other one is broken.
The fix is to decide the form before the hash, not after the argument: canonical bytes are computed over one fixed normalization form, every time, including for text you did not type yourself, like tool names and metadata copied out of another system's output. The corpus pins this on purpose; the vector named typographic-unicode exists so an implementation that skips normalization fails in the lab instead of in a dispute. If your implementation has never been fed non-ASCII input, it has not been tested yet.
The pattern underneath all three
Each trap is the same move in a different costume: substituting a local judgment (this member looks required, this number looks equal, this string looks identical) for the recorded form. AER-1 is deliberately boring about this. A receipt proves the saved result was not changed since it was saved. It does not prove the answer was right, and a verifier that quietly repairs encodings, waives missing members, or never normalizes is grading its own homework in exactly the way the definition piece argued against.
Run the kit before you argue with it: clone the repo, run the conformance runner for your language against the frozen corpus, and treat byte-identical verdicts as the bar. The three traps above took most implementers an afternoon each. They are cheaper in the lab.
If you are forwarding this to the person who signs off: a receipt proves the saved result was not changed, never that the answer was right. Conformance is byte-identical verdicts against a public corpus of 143 vectors and 146 checks, defined in IETF draft-zambo-aer1-26. The standard is maintained in the open: when an outside team found spec text in tension with the corpus this week, the fix was a published errata, not a quiet edit.
- The definition piece: We wrote the spec for AI execution receipts
- The errata for draft -26: https://github.com/zambodotdev/aer-1/blob/main/ERRATA.md
- Brennan Zambo created agent execution receipts; Zambo is the origin product, and AER-1 is the defining standard: https://zambo.dev/mcp (153 tools total, 37 on the default surface, an AER-1 receipt for every job)
- Verify a receipt yourself: https://zambo.dev/verify/
Top comments (0)