protocol: say "no value" by absence in the session roster #165

Merged

natsukium merged 2 commits from fix/proto-session-normalize-144 into main 2026-09-06 15:51:17 +09:00

Conversation 0 Commits 2 Files changed 32 +533 -152

natsukium commented 2026-09-06 15:10:46 +09:00

Owner

Copy link

Fixes #144.

Three fields of the session roster row spelled "the daemon has no value
here" with a value drawn from the field's own domain: sequence = 0 for
a daemon below minor 3, idle_seconds = 0 for an attached session, and
a hand-formatted string for an attach instant whose shape nothing could
check. Presence carries all three now:

• SessionInfo.sequence is explicitly optional and 1-based, so a wire
  0 is a decode error rather than a fourth meaning; the switch ring
  falls back to id order only on absence.
• SessionInfo.idle_seconds is absent while attached, which frees 0
  to mean the second it names.
• Attachment.attached_at is a google.protobuf.Timestamp, whose range
  a decoder checks. The RFC 3339 formatter moves to felis-cli, its
  only user, so the CLI's machine surface keeps publishing the same
  string.

This is a pre-release wire break, acknowledged in
crates/felis-protocol/proto/BREAKING.md against the rebase base:
daemon and client must be rebuilt together.

Doc cascade: docs/reference/ipc.md (per-field absent-value semantics
and the minor-3 ledger row), docs/explanation/ipc.md (the argument for
absence over an in-band sentinel, recorded once rather than per field),
the docs/how-to/ reap recipe whose jq filter documented 0 as
"attached", and CHANGELOG.md.

Verified: just check green (fmt, clippy, nextest, deny, proto-compat);
reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high

Deferred

• Convert the reference/ipc.md "Session (kind = 4)" bullets into a field
  table — #29/#146 own that table rewrite; the three fields' frozen
  semantics are already stated in the existing bullets.
• Ledger row 2 wording — it names Attachment's fields only, none of
  which was renamed.
• Attachment timestamp assertion can flake on a non-monotonic clock —
  describes a rare CI-flake risk from SystemTime::now()
  non-monotonicity, not a concrete wrong output or a named acceptance
  criterion; hardening beyond what #144 requires.
• BREAKING.md/ipc.md/CHANGELOG.md overstate the wire-break mechanism for
  attached_at — duplicate of the "guaranteed decode failure" finding
  (same lines, same wire-type/decode-outcome inaccuracy); merged under
  that title and fixed there.
• pi sol unavailable — tooling/infra unavailability of the pi sol
  reviewer, not a finding about the diff itself; no fix in this PR's
  scope addresses it.

Fixes #144. Three fields of the session roster row spelled "the daemon has no value here" with a value drawn from the field's own domain: `sequence = 0` for a daemon below minor 3, `idle_seconds = 0` for an attached session, and a hand-formatted string for an attach instant whose shape nothing could check. Presence carries all three now: - `SessionInfo.sequence` is explicitly optional and 1-based, so a wire `0` is a decode error rather than a fourth meaning; the switch ring falls back to id order only on absence. - `SessionInfo.idle_seconds` is absent while attached, which frees `0` to mean the second it names. - `Attachment.attached_at` is a `google.protobuf.Timestamp`, whose range a decoder checks. The RFC 3339 formatter moves to `felis-cli`, its only user, so the CLI's machine surface keeps publishing the same string. This is a pre-release wire break, acknowledged in `crates/felis-protocol/proto/BREAKING.md` against the rebase base: daemon and client must be rebuilt together. Doc cascade: `docs/reference/ipc.md` (per-field absent-value semantics and the minor-3 ledger row), `docs/explanation/ipc.md` (the argument for absence over an in-band sentinel, recorded once rather than per field), the `docs/how-to/` reap recipe whose jq filter documented `0` as "attached", and `CHANGELOG.md`. Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high ## Deferred - Convert the reference/ipc.md "Session (kind = 4)" bullets into a field table — #29/#146 own that table rewrite; the three fields' frozen semantics are already stated in the existing bullets. - Ledger row 2 wording — it names `Attachment`'s fields only, none of which was renamed. - Attachment timestamp assertion can flake on a non-monotonic clock — describes a rare CI-flake risk from `SystemTime::now()` non-monotonicity, not a concrete wrong output or a named acceptance criterion; hardening beyond what #144 requires. - BREAKING.md/ipc.md/CHANGELOG.md overstate the wire-break mechanism for `attached_at` — duplicate of the "guaranteed decode failure" finding (same lines, same wire-type/decode-outcome inaccuracy); merged under that title and fixed there. - pi sol unavailable — tooling/infra unavailability of the pi sol reviewer, not a finding about the diff itself; no fix in this PR's scope addresses it.

natsukium added 2 commits 2026-09-06 15:10:46 +09:00

protocol: say "no value" by absence in the session roster ... 972b0cafae

Three fields of the roster row spelled "the daemon has no value here"
with a value from the field's own domain: sequence 0 for a daemon below
minor 3, idle_seconds 0 for an attached session, and a formatted string
for an attach instant whose shape nothing could check. A sentinel drawn
from the domain cannot be told apart from a peer that meant it, so the
exclusion lives in prose that every consumer has to remember, and the
one that forgets returns a wrong answer instead of an error.

Presence carries it now. sequence is explicitly optional and 1-based,
so a wire 0 is a decode error rather than a fourth meaning, and the
switch ring falls back to id order only on absence; idle_seconds is
absent while attached, which frees 0 to mean the second it names; and
attached_at is a google.protobuf.Timestamp, whose range a decoder
checks. A felis-private epoch integer was rejected: every protobuf
consumer already maps the well-known type and none maps our convention.
The RFC 3339 formatter moves to felis-cli, its only user, so the CLI
surface keeps publishing the same string.

This breaks the wire before the first release, acknowledged in
proto/BREAKING.md: a peer from either side of it fails to decode any
roster carrying an attachment, so daemon and client must be rebuilt
together.

Refs #144

Assisted-by: Claude Code

docs: freeze the roster row's absent-value semantics ... c19ccfcef9

The reference described idle_seconds as "Some(0) while attached" and
the ledger's minor-3 row as "every row reads 0", which left absence and
0 meaning the same thing in two of the three fields the roster row can
omit. State one meaning per field where a reader looks it up, record
the argument for absence over an in-band sentinel once in the IPC
explanation rather than per field, and fix the reap recipe, whose jq
filter documented 0 as "attached".

Refs #144

Assisted-by: Claude Code

natsukium force-pushed fix/proto-session-normalize-144 from c19ccfcef9 to 14fe57a30b 2026-09-06 15:26:54 +09:00 Compare

natsukium force-pushed fix/proto-session-normalize-144 from 14fe57a30b to 6f29d13313 2026-09-06 15:42:58 +09:00 Compare

natsukium merged commit 6f29d13313 into main 2026-09-06 15:51:17 +09:00

natsukium deleted branch fix/proto-session-normalize-144 2026-09-06 15:51:17 +09:00

natsukium referenced this pull request 2026-09-07 16:09:12 +09:00

[v0.1/Proto Review] Freeze protobuf and IPC contracts (7 issues) #52

Sign in to join this conversation.

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

Notifications

Subscribe

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!165

No description provided.