protocol: version connection modes through the minor ledger #319

Merged

natsukium merged 3 commits from connection-mode-minor into main 2026-09-21 15:53:47 +09:00

Conversation 0 Commits 3 Files changed 14 +434 -55

natsukium commented 2026-09-21 13:32:41 +09:00

Owner

Copy link

Option 1 from the issue: a connection mode is an additive minor, recorded in the ledger and gated on the effective minor.

What lands

• ConnectionMode::since_minor() plus a Downgrade impl that withholds rather than maps: a mode decides which families
  a connection speaks at all, so answering with another one would open a surface the caller did not ask for. Every
  shipped mode is a base-schema one (since = 0).
• ConnMsg::Hello folds its mode's requirement into MinorGated, so the send gate reads it like any other addition,
  and the ledger's schema walk now covers every ConnectionMode value: a mode added later cannot reach the wire
  without a ledger row.
• Client side: check_mode_minor refuses the dial with ConnectError::MinorTooOld before the Hello is written, so
  the skew is reported instead of lost in an EOF (CLI exit 2, daemon_unreachable).
• Daemon side: a Hello whose mode this build cannot read is answered Refused { UnknownMode } and then closed,
  rather than dropped as a corrupt body. Widening Role was rejected: re-reading an existing enum value is a semantic
  change the minor rule does not admit.
• Protocol minor 11 for RefusalReason::UNKNOWN_MODE, with its ledger row in MINOR_LEDGER, felis.proto and
  docs/reference/ipc.md. A peer below the minor is closed unanswered, as AtCapacity already is.

Tests

• felis-protocol: a_hello_costs_the_minor_that_defined_its_mode, a_mode_is_withheld_rather_than_downgraded, plus
  the existing ledger-coverage test, which now fails if a mode is added without a row.
• felis-client-core: a_mode_above_the_effective_minor_is_refused — a synthetic mode one minor past this build is
  refused at the negotiated minor, and the refusal is not transient.
• felis-daemon: a_hello_naming_an_unknown_mode_is_refused_by_name — a hand-encoded future-mode Hello (the shape a
  newer client writes) gets the typed refusal and then a clean close.

Gates run: cargo nextest run for felis-protocol, felis-client-core, felis-daemon, felis-cli (--all-features),
felis-transport and the workspace guards; cargo clippy --workspace --all-targets (clean); just proto,
just proto-compat (wire-compatible with the base), just schema, just prose-check, just docs-links.

Left undone

An end-to-end mixed-version test on the client side is not possible in-tree: every mode this build ships is since = 0,
so no ConnectionMode value exists that a real connect() could refuse. The client half is pinned at the gate
function with a synthetic minor; the daemon half uses a hand-encoded wire value, which is exactly what a newer client
would write.

Closes #312

Option 1 from the issue: a connection mode is an additive minor, recorded in the ledger and gated on the effective minor. ## What lands - `ConnectionMode::since_minor()` plus a `Downgrade` impl that withholds rather than maps: a mode decides which families a connection speaks at all, so answering with another one would open a surface the caller did not ask for. Every shipped mode is a base-schema one (since = 0). - `ConnMsg::Hello` folds its mode's requirement into `MinorGated`, so the send gate reads it like any other addition, and the ledger's schema walk now covers every `ConnectionMode` value: a mode added later cannot reach the wire without a ledger row. - Client side: `check_mode_minor` refuses the dial with `ConnectError::MinorTooOld` before the `Hello` is written, so the skew is reported instead of lost in an EOF (CLI exit `2`, `daemon_unreachable`). - Daemon side: a `Hello` whose mode this build cannot read is answered `Refused { UnknownMode }` and then closed, rather than dropped as a corrupt body. Widening `Role` was rejected: re-reading an existing enum value is a semantic change the minor rule does not admit. - Protocol minor 11 for `RefusalReason::UNKNOWN_MODE`, with its ledger row in `MINOR_LEDGER`, `felis.proto` and `docs/reference/ipc.md`. A peer below the minor is closed unanswered, as `AtCapacity` already is. ## Tests - `felis-protocol`: `a_hello_costs_the_minor_that_defined_its_mode`, `a_mode_is_withheld_rather_than_downgraded`, plus the existing ledger-coverage test, which now fails if a mode is added without a row. - `felis-client-core`: `a_mode_above_the_effective_minor_is_refused` — a synthetic mode one minor past this build is refused at the negotiated minor, and the refusal is not transient. - `felis-daemon`: `a_hello_naming_an_unknown_mode_is_refused_by_name` — a hand-encoded future-mode `Hello` (the shape a newer client writes) gets the typed refusal and then a clean close. Gates run: `cargo nextest run` for felis-protocol, felis-client-core, felis-daemon, felis-cli (`--all-features`), felis-transport and the workspace guards; `cargo clippy --workspace --all-targets` (clean); `just proto`, `just proto-compat` (wire-compatible with the base), `just schema`, `just prose-check`, `just docs-links`. ## Left undone An end-to-end mixed-version test on the *client* side is not possible in-tree: every mode this build ships is since = 0, so no `ConnectionMode` value exists that a real `connect()` could refuse. The client half is pinned at the gate function with a synthetic minor; the daemon half uses a hand-encoded wire value, which is exactly what a newer client would write. Closes #312

natsukium added 1 commit 2026-09-21 13:32:41 +09:00

protocol: version connection modes through the minor ledger ... f5fe7e14e0

A mode is the extension path for a whole surface: the design says a new
surface earns a new mode rather than a per-feature bit, so mode growth
is an expected additive change, not a corner case. Until now the gate
covered `ConnWelcome.identity` alone, `ConnectionMode` carried no
`since_minor`, and a client naming a mode an older daemon predates lost
the connection at that daemon's decode with no sender-side verdict and
no frame back.

Every mode now carries a ledger row the schema walk enforces, the
`Hello` folds its mode's requirement into what the send gate reads, and
the client refuses the dial locally when the effective minor does not
define the mode it asks for. The receiving half is a typed refusal:
`RefusalReason::UnknownMode` (minor 11) names the skew before the close,
so the peer reports a daemon too old instead of an EOF it would retry.
Widening `Role` to cover it was rejected, since re-reading an existing
enum value is a semantic change the minor rule does not admit.

No mode down-maps: answering a peer with a mode it did not name would
wire up a surface it did not ask for, so the send gate and the refusal
are the whole accommodation.

Assisted-by: Claude Code

natsukium added 1 commit 2026-09-21 13:47:32 +09:00

daemon: answer UnknownMode only for a mode a newer peer could have sent ... 44d9dc91ce

Recovering from any driver error over a re-decode made two frames a
newer peer never writes look like one: `CONNECTION_MODE_UNSPECIFIED`,
which no build ever names, and an unknown mode under a `Correlation`
envelope, which the second decode cannot see because field 100 is
reserved on the Conn family. Both are corruption, and answering them by
name tells the peer its daemon is old when its frame is wrong. The
recovery now requires an uncorrelated body and a nonzero unknown mode,
so every other undecodable `Hello` keeps the bare close.

The gate's doc comment loses the note that it takes a minor rather than
a `ConnectionMode`: the reason is that no shipped mode is above the
base schema, so a test needs a minor the enum cannot spell.

Assisted-by: Claude Code

natsukium added 1 commit 2026-09-21 14:06:18 +09:00

protocol: say in the schema that Hello.mode is minor-gated ... 0907edf1e2

The `ConnHello` and `ConnWelcome` comments still promised that nothing
in the handshake is a compatibility signal and that any `Hello` the
daemon read was decodable, which a non-Rust client generating its codec
from the schema would take at face value and skip the one send gate the
handshake has.

The ledger row overstated the old client's position too: an EOF it
reads as transient is one it retries, and no number of retries makes a
daemon define a mode it does not have, so the row now says the retry
settles nothing and names who can act.

Assisted-by: Claude Code

natsukium referenced this pull request 2026-09-21 14:11:27 +09:00

protocol: terminate a pull-paced grid cycle on the wire #321

natsukium referenced this pull request 2026-09-21 14:31:19 +09:00

Resolve attach targets on the daemon, and answer sessions info in one reply #322

natsukium referenced this pull request 2026-09-21 14:32:23 +09:00

protocol: terminate a pull-paced grid cycle on the wire #321

natsukium referenced this pull request 2026-09-21 14:33:57 +09:00

Encode keys where the keyboard modes are authoritative #323

natsukium merged commit 48fdbce87e into main 2026-09-21 15:53:47 +09:00

natsukium deleted branch connection-mode-minor 2026-09-21 15:53:47 +09:00

natsukium referenced this pull request from a commit 2026-09-21 15:53:48 +09:00

protocol: version connection modes through the minor ledger (#319)

natsukium referenced this pull request from a commit 2026-09-21 16:11:11 +09:00

Merge origin/main into grid-cycle-end

natsukium referenced this pull request from a commit 2026-09-21 16:11:22 +09:00

Merge origin/main into daemon-key-encoding

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

Encode keys where the keyboard modes are authoritative #323

natsukium referenced this pull request from a commit 2026-09-21 16:13:33 +09:00

Merge origin/main into attach-by-prefix

natsukium referenced this pull request 2026-09-21 16:14:03 +09:00

Resolve attach targets on the daemon, and answer sessions info in one reply #322

natsukium referenced this pull request 2026-09-21 21:35:04 +09:00

[v0.1/Tracker] Close release blockers before v0.1.0 #12

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

No description provided.