id: design: framing & fragmentation per carrier class (from #5674)

Summary

Follow-on design ticket from #5674 — its decomposition sketch names this as a separate design, and the parent's acceptance requires these tickets to be filed and linked. Filed in the 2026-11-04 gap pass (WS-F) so the design work exists and can be prioritised on its own merits; implementation timing is a separate decision, possibly months out.

What this design must settle

Framing and fragmentation for the three carrier classes — stream, datagram, and store-and-forward — with their different loss and ordering realities.

Context from the parent

The parent design fixes the postcard wire-format family and the transport-adapter model that carries ID over non-UDP transports and relays. The parent issue carries the surrounding decisions this ticket must not re-decide; where this ticket's answer would change a parent decision, record that explicitly rather than silently forking it.

Decision record expected

Close this design with a recorded decision (on this issue or in a doc/ record linked from it): the chosen shape, the alternatives rejected and why, and the invariants implementation must hold. If the design splits further, file the splits and link them here rather than growing this issue.

Relations

Parent: #5674. Programme: epic #2056. Filed by WS-F (2026-11-04 ID design gap & expansion pass).

CODE-1493

🤖 Agent note · triaged

Agent: queue worker (repo-worker-code), lane code-a
Session / ID: task 10213
Found via: queue claim (coverage audit DELTA 2026-11-05 re-queue)
Task: Triage of issue id: design: framing & fragmentation per carrier class (from #5674) #5810 at current state.
Findings: Issue id: design: framing & fragmentation per carrier class (from #5674) #5810 is OPEN and still live — a follow-on design ticket from parent id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674, filed 2026-11-05T01:52Z in the WS-F gap pass and linked from the parent (parent comment 2026-11-05T02:01Z confirms the decomposition filing, satisfying that parent acceptance item). No open or closed PR references id: design: framing & fragmentation per carrier class (from #5674) #5810, and no hard-stop labels are present. Parent id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674 is itself still OPEN with no decision record yet (its own triage, task 10107, was handed to the opencode lane today). Programme epic epic: ID platform expansion — apps, comms, currency, hosting, boards (2026-10-28 directive, LIST 6–15) #2056 is OPEN.
Ordering / blocker: This design must not re-decide parent decisions — it builds on the postcard wire-format family and transport-adapter model that id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674 fixes. Framing/fragmentation choices per carrier class (stream, datagram, store-and-forward) depend on those parent decisions, so the decision record for id: design: framing & fragmentation per carrier class (from #5674) #5810 is ordered AFTER the id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674 decision record. The issue body already states implementation timing is a separate decision, possibly months out; nothing here is closable or implementable yet.
Expectation: When id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674 records its decision, this ticket is unblocked for its own design pass; close it only with a recorded decision (chosen shape, rejected alternatives, invariants) per its Decision record section.
Links: task 10213 (repo-health-code-pilot); parent id: design: Wire format & transport adapters — postcard schema, non-UDP carriers, relays/proxies #5674; epic epic: ID platform expansion — apps, comms, currency, hosting, boards (2026-10-28 directive, LIST 6–15) #2056

Agent note — picked up, handed off to opencode execution lane (lane code-u, task 12311, 2026-11-07)

Task 12311 (triage: re-queued under triage doctrine — queue task 10213 was marked done with no landed evidence) was claimed by lane code-u and assigned by the execution-lane system to the opencode lane (assigned_lane: opencode). Per the worker runbook §1b, the bound opencode session launched by the laptop claimant owns this task from here: revalidation against current state, triage verdict, and any scoped follow-up packet are that session's to produce.

This note is the pickup/handoff record only — no triage verdict is implied. If the claimant has not launched by lease expiry, the task returns to the queue on its own.

🤖 Agent note · handed off

Agent: repo queue worker, lane code-l (repo-worker-code)
Task: task 13585 (small_fix) — execution lane assigned opencode per runbook 1b; handed off to opencode claimant (session ses_e5e425ae66effe8gDytBNKvAA8 bound).
Revalidation: issue id: design: framing & fragmentation per carrier class (from #5674) #5810 OPEN, no hard-stop labels (fresh gh, 2026-11-09T02:2xZ).
Next: claimant session drives the task; task 13585 parked pending session work.

🤖 Agent note · handed off

Agent: repo queue worker, lane code-l (repo-worker-code)
Session / ID: cron repo-queue-worker-shift-l run 2026-11-08; task 13585
Found via: claimed task 13585 this shift; execution-lane assignment returned opencode
Task: task 13585 for issue id: design: framing & fragmentation per carrier class (from #5674) #5810 (small_fix). Fresh check: {"labels":["task/small-fix","status/in-progress","status/parked","queue/claimed","queue/parked","app/id","work/assigned"],"state":"OPEN"}. No hard-stop labels (held / user/owned / do-not-merge / do-not-auto-edit). Handed off to the opencode claimant — the claimant launches the bound opencode session; this lane does not work it directly.
Expectation: claimant session drives task 13585 to a terminal state.
Links: task 13585 · issue id: design: framing & fragmentation per carrier class (from #5674) #5810

🤖 Agent note · handed off

Agent: repo queue worker, lane code-j (repo-worker-code)
Session / ID: cron repo-queue-worker-shift-j run 2026-11-08; task 13585
Found via: claimed task 13585 this shift; execution-lane assignment returned opencode
Task: task 13585 for issue id: design: framing & fragmentation per carrier class (from #5674) #5810 (small_fix). Fresh check: issue id: design: framing & fragmentation per carrier class (from #5674) #5810 is OPEN, no hard-stop labels (held / user/owned / do-not-merge / do-not-auto-edit). Attempts 2/4. Handed off to the opencode claimant — the claimant launches the bound opencode session; this lane does not work it directly.
Expectation: claimant session drives task 13585 to a terminal state.
Links: task 13585 · issue id: design: framing & fragmentation per carrier class (from #5674) #5810

🤖 Agent note · handed off

Agent: repo queue worker, lane code-h (repo-worker-code)
Session / ID: cron repo-queue-worker-shift-h run 2026-11-08 22:25 CST; task 13585
Found via: claimed task 13585 this shift; execution-lane assignment returned opencode; checkpoints claimed and handed_off recorded on the task.
Task: task 13585 for issue id: design: framing & fragmentation per carrier class (from #5674) #5810 (small_fix). Fresh check: issue id: design: framing & fragmentation per carrier class (from #5674) #5810 is OPEN, no hard-stop labels (held / user/owned / do-not-merge / do-not-auto-edit). Handed off to the opencode claimant — the claimant launches the bound opencode session; this lane does not work it directly.
Expectation: claimant session drives task 13585 to a terminal state.
Links: task 13585 · issue id: design: framing & fragmentation per carrier class (from #5674) #5810

agent-note:v1
task: 13585
lane: code-h
state: handed_off

Task 13585 picked up by lane code-h; execution lane assigned opencode. Handed off to the opencode claimant; task 13585 parked 1200s meanwhile. Issue #5810 revalidated OPEN, no hard-stop labels at pickup, 2026-11-09.

Decision recorded: framing & fragmentation across carrier classes

Design record: doc/2026-11-09_decision_id5810_carrier_framing.md (PR: see linked pull request).

Decision in one line. The adapter boundary carries one canonical serialized postcard frame. An adapter adds only the framing its carrier needs and removes it before handing the frame to ID; a frame is never re-encoded (no JSON/base64 variants) and never given carrier-specific message semantics.

Carrier class	Chosen shape	Exposed to ID
Stream	One length-prefixed canonical frame; incremental reads; no application fragmentation	Reliable ordered bytes; clean EOF between frames = close, EOF mid-frame = truncation
Datagram	Whole frame in one datagram when it fits the negotiated/safe payload; otherwise the existing checked-chunk/reassembly representation; never IP fragmentation	Loss/duplication/reorder tolerated; frames exposed in completion order
Store-and-forward	Opaque whole frame, or checked chunks under the existing transfer identity when constrained; assembled before decode	Any arrival order, duplicates idempotent, no partial delivery, expiry is terminal

Rejected: per-read-as-a-message, reject-oversize-datagrams, IP fragmentation, per-adapter chunk formats, re-encoding for constrained carriers, and inferring ordering/exactly-once from unreliable carriers.

Invariants implementation must hold: canonical bytes after deframing/assembly; one frame one decode (only after length/digest validation within the shared 1 MiB frame cap); bounded resources and pre-allocation length checks; chunk identity with idempotent duplicates; arrival order is never order; no accidental reliability promise; expiry is terminal for an assembly; sender obeys carrier-negotiated datagram limits; security stays layered over the fully reconstructed frame.

Parent #5674: this record consumes the parent's adapter direction and fills in the per-carrier mapping. It changes no frozen parent decision. The envelope layout, chunk metadata encoding, fragmented flag semantics and size/extension rules stay with #5674/#5808/#5809; if the parent contract cannot express this shape with the existing checked-chunk representation, that is resolved there before implementation.

Scope: does not split further. Adjacent ownership: #5808 (schema/golden vectors), #5809 (version negotiation), #5813 (relay/proxy), #5814 (conformance harness), #5815 (security binding). Implementation timing remains a separate decision.

Posted by repo-health-code-pilot worker repo-worker-code (task 13585).

Navigation Menu

Repository navigation

id: design: framing & fragmentation per carrier class (from #5674) #5810

Summary

What this design must settle

Context from the parent

Decision record expected

Relations

28 remaining items

Decision recorded: framing & fragmentation across carrier classes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

id: design: framing & fragmentation per carrier class (from #5674) #5810

Description

Summary

What this design must settle

Context from the parent

Decision record expected

Relations

Activity

developing-today commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 8, 2026

28 remaining items

dezren39 commented on Nov 9, 2026

dezren39 commented on Nov 9, 2026

dezren39 commented on Nov 9, 2026

dezren39 commented on Nov 9, 2026

dezren39 commented on Nov 9, 2026

dezren39 commented on Nov 9, 2026

Decision recorded: framing & fragmentation across carrier classes

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions