feat(relay): routing-envelope wrapper type (#1)

[ilmoniemi]

What

Adds the canonical Go vocabulary for the relay↔binary routing envelope:

• Envelope struct with ConnID string and Frame json.RawMessage matching the wire shape {conn_id, frame}.
• Marshal(connID string, frame []byte) ([]byte, error) — validates non-empty conn id, validates inner-frame JSON syntax via json.Valid, emits the envelope with the inner bytes preserved verbatim (modulo whitespace).
• Unmarshal(data []byte) (Envelope, error) — rejects malformed JSON, absent/empty/null conn_id, and absent/null frame.
• Five exported sentinel errors (ErrEmptyConnID, ErrInvalidFrameJSON, ErrMalformedEnvelope, ErrMissingConnID, ErrMissingFrame) so downstream code branches via errors.Is instead of string matching.

The opacity invariant is enforced by json.RawMessage: the relay never deserialises the inner frame on either side.

Issue

Closes #1

Testing

• internal/relay/envelope_test.go:
  • Round-trip with a non-trivial nested-JSON frame (unicode, null, arrays); asserts bytewise equality after json.Compact to honour the "modulo whitespace" caveat.
  • Marshal rejection table: empty conn id, nil/empty/garbage/truncated frame.
  • Unmarshal rejection table: malformed JSON, non-object payload, missing/empty/null conn_id, missing/null frame.
  • All rejection assertions go through errors.Is.
• make vet, make test (with -race), make build all clean.

Architecture compliance

• Lives in internal/relay/ next to doc.go per the spec; no edits to cmd/pyrycode-relay/main.go (binary still builds unchanged).
• Stdlib only (encoding/json, errors, bytes, fmt).
• Pure functions, no goroutines, no I/O — matches the "library code" framing in the spec.
• Marshal validates inner-frame syntax but never semantics; Unmarshal collapses absent/empty/null conn_id and absent/null frame into single sentinels per the spec's algorithm.
• Out-of-scope items (conn_id format, networking, registry, header validation) deliberately untouched.

🤖 Generated with Claude Code

[ilmoniemi]

Code Review: #1

Decision: PASS

Findings

• [NIT] internal/relay/envelope.go:59-60 — Doc says Unmarshal returns ErrMalformedEnvelope "wrapping the underlying decoder error". The implementation at line 70 uses fmt.Errorf("%w: %v", ErrMalformedEnvelope, err) — the json decoder error is included in the message text only, not wrapped in the unwrap chain. So errors.Is(err, ErrMalformedEnvelope) works, but errors.As(err, &jsonSyntaxErr) would not. Either drop "wrapping" from the doc, or use Go 1.20+ multi-%w (fmt.Errorf("%w: %w", ErrMalformedEnvelope, err)) to make the doc accurate. Non-blocking.
• [NIT] internal/relay/envelope.go:75 — bytes.Equal(env.Frame, []byte("null")) works; string(env.Frame) == "null" would let you drop the bytes import. Either is fine.

Summary

Faithful, minimal implementation of the spec. Envelope + Marshal + Unmarshal + five sentinel errors, stdlib-only, pure functions, no concurrency or I/O. Doc comments on every exported symbol, each naming the opacity invariant.

Validation hits the right boundaries:

• Marshal rejects empty connID and invalid-JSON frame (covering nil/empty/garbage/truncated in one json.Valid call).
• Unmarshal collapses absent/empty/null conn_id into ErrMissingConnID and absent/null frame into ErrMissingFrame — the explicit bytes.Equal(env.Frame, []byte("null")) check is necessary because json.RawMessage retains the literal four bytes for "frame": null and would otherwise pass the length check. Good catch.
• Inner-frame contents are never parsed on the read path, preserving the opacity invariant.

Tests cover every row of both rejection tables plus the round-trip with nested JSON, unicode, and a null value. Assertions go through errors.Is, not string compare. t.Parallel() used on outer tests and subtests. The opacity assertion uses json.Compact on both sides, which correctly implements the "modulo whitespace" caveat without flaking on encoder formatting. make vet, make test (with -race), and make build all clean.

The defensive error-wrap at envelope.go:49-53 is dead in practice (the only non-static field is a pre-validated json.RawMessage), but the in-line comment names exactly that, so it reads as deliberate rather than cargo-culted. Fine.