Typed codec port pattern — domain never touches raw bytes for serde

[flyingrobots]

Migrated from Method backlog

GitHub Issues are now the live work tracker. Repository docs remain Method evidence.

Field	Value
Source backlog	docs/method/backlog/cool-ideas/PROTO_typed-codec-port-pattern.md
Archived source	docs/archive/backlog/github-issue-migration-2026-06-01/docs/method/backlog/cool-ideas/PROTO_typed-codec-port-pattern.md
Original lane	cool-ideas
Original id	PROTO_typed-codec-port-pattern
Original legend	PROTO
Original feature	runtime-boundaries

Original backlog card

Typed codec port pattern — domain never touches raw bytes for serde

The ShardPort pattern (domain works with typed shard objects, port
adapter owns Uint8Array ↔ object conversion) generalizes to ALL ports.

Instead of ports returning Uint8Array and the domain decoding:

// Current — domain does serde
const raw: Uint8Array = await port.read(key);
const decoded = codec.decode(raw);  // domain is doing serde

Every port returns typed domain objects directly:

// Clean — port adapter owns serde
const shard: MetaShard = await shardPort.loadMeta(key);
// MetaShard is a typed domain object. Port decoded it.

This is SSTS P5 ("serialization is the codec's problem") taken to
its logical conclusion. The domain layer never imports a codec. Never
calls encode/decode. Never touches Uint8Array for serde purposes.
Bytes enter and leave through port adapters.

The domain can still work with Uint8Array when bytes ARE the domain
value (content blobs, binary attachments). The distinction: domain
bytes are content; adapter bytes are encoding.

[flyingrobots]

Design note from local Wesley inspection (/Users/james/git/wesley at main): GraphQL becomes credible here only when Wesley is the compiler boundary, not when GraphQL itself is treated as the byte-format authority.

Relevant Wesley source evidence:

• crates/wesley-emit-codec/src/lib.rs#L1-L12 defines a language-neutral LE-binary codec plan lowered from Wesley L1 IR, shared by Rust and TypeScript emitters.
• crates/wesley-emit-codec/src/lib.rs#L21-L45 names the current wire primitives: bool, i32 LE, f32 LE, u32 length-prefixed strings, options, and lists.
• crates/wesley-emit-codec/src/lib.rs#L69-L98 models emitted codecs as enum/struct/operation definitions with fields in wire order.
• crates/wesley-emit-rust/src/le_binary.rs#L1-L15 states the Rust emitter consumes the shared plan and rejects trailing decode input.
• crates/wesley-emit-typescript/src/le_binary.rs#L1-L18 states the TypeScript emitter produces deterministic little-endian variable codecs.
• crates/wesley-cli/src/main.rs#L537-L586 wires wesley emit le-binary-typescript and wesley emit le-binary-rust from GraphQL SDL.

Implication for git-warp v19: do not use GraphQL as serde and do not let generated shapes enter domain directly. Instead, evaluate Wesley as a code-generation boundary for raw LE-binary codec modules under infrastructure/codecs. Generated decoders should produce boundary DTOs or call explicit domain constructors; domain nouns still own invariants.

Known gap before git-warp can rely on it for canonical storage/signature bytes: Wesley's current plan is too small for git-warp wire nouns. git-warp will need fixed bytes/hash scalars, u8/u16/u32/u64/i64 rules, canonical map/list ordering, version/kind envelopes, bounded allocation limits, noncanonical rejection tests, and golden byte vectors. Start with one narrow generated codec candidate and prove byte-for-byte parity before expanding.