protocol, transport, daemon: version the relay carrier payload #338

Merged

natsukium merged 1 commit from issue-332 into main 2026-09-22 02:31:59 +09:00

Conversation 0 Commits 1 Files changed 7 +283 -57

natsukium commented 2026-09-22 01:54:54 +09:00

Owner

Copy link

Closes #332.

The relay carrier payload now starts with a u16 format version; the 8-byte FRLY | u32 length header is unchanged. Version 1 is today's entry encoding under the frozen caps; version 0 is malformed; an unknown version is skipped by length with a warning and the connection continues to FLIS with no carrier, so a future payload change skews safely against any released v1 daemon. Migration against a pre-version-word daemon fails fast in both directions (the old entry-count cap catches the version word; the new reader sees version 0), and CHANGELOG.md states the one restart that upgrade needs.

Decision: the last comment on #332 (six rounds of design review; the original widened-header proposal was rejected there because an old daemon would read the new bytes as a length and hang). Code review: pi luna (one blocker on the reference's skew claim) then pi sol (three rounds: a six-line comment, a missing truncated-header test, the same skew claim in the explanation; PASS).

Docs: ipc.md reference + explanation (decision record with rejected alternatives and a Revisit trigger), spec.md REQ-104c, CHANGELOG.md.

Closes #332. The relay carrier payload now starts with a `u16` format version; the 8-byte `FRLY | u32 length` header is unchanged. Version 1 is today's entry encoding under the frozen caps; version 0 is malformed; an unknown version is skipped by length with a warning and the connection continues to `FLIS` with no carrier, so a future payload change skews safely against any released v1 daemon. Migration against a pre-version-word daemon fails fast in both directions (the old entry-count cap catches the version word; the new reader sees version 0), and `CHANGELOG.md` states the one restart that upgrade needs. Decision: the last comment on #332 (six rounds of design review; the original widened-header proposal was rejected there because an old daemon would read the new bytes as a length and hang). Code review: pi luna (one blocker on the reference's skew claim) then pi sol (three rounds: a six-line comment, a missing truncated-header test, the same skew claim in the explanation; PASS). Docs: `ipc.md` reference + explanation (decision record with rejected alternatives and a Revisit trigger), `spec.md` REQ-104c, `CHANGELOG.md`.

natsukium added 1 commit 2026-09-22 01:54:54 +09:00

protocol, transport, daemon: version the relay carrier payload ... 436ff8ed0b

The FRLY block is read before the FLIS preface, so the protocol major
cannot select a decoder for it. Every change to the payload encoding
was therefore indistinguishable from malformed version-1 data, and
ipc.md's promise that relay <-> daemon skew never needs negotiation
would not survive the first such change. A u16 format version now
leads the payload; a version the reader has no decoder for is skipped
by the length word the envelope already carries, which is the same
degrade a relay that prepends nothing produces.

The version goes at the head of the payload rather than into a widened
header because a daemon expecting the eight-byte header would read
half of a wider one as the payload length, and a declared 65536
against a shorter stream leaves both peers waiting. In the payload,
both skew directions fail fast instead: an old reader takes the
version word as the high half of its entry count and breaks the frozen
4096-entry cap, and a new reader sees a versionless payload's zero
high half as format version 0, which is malformed. Those two closes
are what the CHANGELOG's per-direction remedies rest on.

Closes #332.

Assisted-by: Claude Code

natsukium merged commit 789a3213e6 into main 2026-09-22 02:31:59 +09:00

natsukium deleted branch issue-332 2026-09-22 02:31:59 +09:00

natsukium referenced this pull request from a commit 2026-09-22 02:32:00 +09:00

protocol, transport, daemon: version the relay carrier payload (#338)

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!338

No description provided.