feat(envelope): pkg/envelope decoder and pkg/canonjson writer (AFDEV-11)

[foae]

What

Package 3 of the v1 write path: pkg/envelope, the decoder, plus pkg/canonjson, the contract's canonical JSON writer.

• pkg/envelope: Decode(body) (*Envelope, []schema.Detail, error). A token-stream parser (RFC 8259 only; number spellings kept as json.Number; duplicate members last-wins with one duplicate_key and the discarded value's warnings dropped; invalid UTF-8 repaired one U+FFFD per maximal subpart; lone surrogate escapes replaced; 512-level nesting limit), then the inference table in the contract's order, the normalisation order via pkg/schema, the kind schema as a guide for an explicit kind, and the envelope's recommended check. Only the four bodies the contract names are refused, as a *Rejection{Status, Code, Message}. Envelope.Tree() is the JSON tree identity and the store will consume.
• Warnings in a path trie during parse and inference: duplicate drop, remap and collapse are subtree operations, so a 10 MiB body with a warning per member decodes in linear time (a literal port of the reference's slice rewrites is quadratic; a test pins this).
• Limits from the compiled envelope schema at init (byte limits, trim/token, truncation, context entry and value limits, recommended list, member set); body limit, depth, schema_version rule and maximum are constants checked against conformance/ by tests.
• pkg/canonjson: Marshal, Append, AppendString on the write path's JSON tree; panics on any other Go value, a malformed json.Number or invalid UTF-8. internal/canonjson stays as the frozen v3 event-hash form (develop.md now says which is which).

Contract changes

• The inference table now states that unknown members move into payload in code point order of their names (observable only when one of them is named moved). The reference used dict order and crashed with a KeyError on a top-level moved with no payload.moved; the context-overflow pointer remap also ran before placement, so under a wrapped payload.moved the pointers were wrong. Both fixed in conformance/reference/decode.py; new fixtures moved-named-member-order and context-overflow-under-wrapped-moved pin them. All 87 fixtures agree with the reference and with the Go decoder.

Tests

• One named test per inference-table row reading its fixture (with a row-specific assertion), every interaction fixture, the hash fixtures' bodies projected onto the identity members; the fixture directory sets must equal manifest.json and the row table.
• Parser: grammar rejections, spellings, escapes, depth, duplicates, pointer escaping; UTF-8 repair vectors from Unicode table 3-8 plus an exhaustive cross-check of every 1- and 2-byte sequence and shaped 3/4-byte sequences against an independent oracle formulation.
• FuzzDecode: seeded with every fixture body plus hand-written cases under testdata/fuzz/FuzzDecode; oracle json.Valid + token scan for object/depth; invariants on the stored shape and a canonical fixed point. just fuzz (30 s) is a new CI step and gate.

Gates

All green locally: just check with a clean tree, go test -race -count=1 ./..., just fuzz, live e2e 55/55, shellcheck (both forms), skill tests 124/124, just contract (87 fixtures), staticcheck 2026.2.1 clean.

Out of scope: identity and hashing (AFDEV-13), storage (AFDEV-12). The running service still implements the v3 API; nothing here is reachable from it yet.

Review round

Panel default on 24a6894 (4 of 5 ran). Fixed in the follow-up commit: warnings of a value discarded by an inference replacement (payload.moved.<name>, context.occurred_at_raw) are dropped, in Go and in the reference, with two fixtures; pkg/canonjson validates member names; the fuzz fixed-point invariant runs through the raw parser instead of Decode; the invalid-escape rejection message no longer echoes a body byte. Acknowledged: warning pointers are unbounded because member names are, so a small body can produce a very large warning list; that is the contract-level question already tracked as a Backlog follow-up, not something this package can decide.