protocol: ship the first wire contract as 1.0, not 1.14 #325

Merged

natsukium merged 3 commits from minor-reset into main 2026-09-21 21:34:24 +09:00

Conversation 2 Commits 3 Files changed 39 +555 -2396

natsukium commented 2026-09-21 20:40:48 +09:00

Owner

Copy link

Closes #313.

The minor ledger reached 14 rows before any peer existed. Every one of those rows describes compatibility with a daemon that was never released, so the gates, fallbacks and downgrade paths they justify are dead weight the first release would have to carry forever — and the first ledger row that ever matters would be numbered 15.

This folds the whole pre-release schema into the minor-0 base.

What changes

• PROTOCOL_MINOR 14 -> 0; the 14 MINOR_* constants are gone and MINOR_LEDGER has one row: (0, "the base schema of protocol major 1"). The preface golden vectors move to 1.0.
• felis.proto: the PROTOCOL_MINOR header comment is 0 and all 11 nonzero (felis.v1.arm).since values become since: 0, keeping the explicit-zero style every base arm already used. Generated Rust regenerated with buf lint && buf generate.
• All six GatedField tables in minor.rs are empty, and every since_minor() on the closed enums returns 0. The tables and the requires impls that fold them stay, so the first post-release field is one row and nothing else.
• The Downgrade trait and every impl are deleted: with no older peer to map to, every closed-enum value is in the base schema, and a future narrowing needs its own mapping regardless.
• Every hard-coded minor gate in the client, CLI and daemon is gone (check_scope_minor, check_key_input_minor, check_mode_minor, the atomic-create and attach-by-prefix fallbacks, effective_minor plumbing through the session task, subscriber and bridge link). check_arm_minor, FrameWriter::authorize, TransportError::MinorTooOld and ConnectError::MinorTooOld are retained.
• The send-authorization frame is still exercised end to end by synthetic arms declared at PROTOCOL_MINOR + 1, at three layers: minor.rs (Requires/arm_requires), connector.rs (check_arm_minor) and framing.rs (FrameWriter::authorize via CheckedFrame::raw, behind feature = "test-util").
• Docs: the docs/reference/ipc.md ledger table collapses to row 0 and ~12 prose sites lose their minor numbers; docs/reference/cli.md says wire: 1.0; the architecture, session-lifecycle and testing pages follow.
• CHANGELOG: the four "protocol minor 11/12/13/14" Unreleased entries become plain Wire entries (features stay, numbers go) and a reset entry is added under Changed. The dated [0.1.0] and earlier sections are untouched.

Deviation worth a look

The brief says to drop ConnectionMode::since_minor, and I followed it literally, which also took check_mode_minor and the mode half of the gating with it. since_minor() is kept on AttachFailure, RefusalReason and ResourceKind so the closed-enum half of the_ledger_covers_every_executable_addition stays alive. If modes should keep a declared minor for symmetry, say so and I will put it back at 0.

Gates

• cargo clippy --workspace --all-targets --all-features — clean, no warnings
• cargo nextest run --workspace --all-features --all-targets --retries 2 — 3453 passed, 0 failed, 16 skipped
• just proto-compat — wire-compatible with the base
• just docs-links — 392 unique links, 0 errors
• python3 tools/prose_check.py --range origin/main...HEAD — 0 hits
• pre-commit hooks ran in full on the commit, no SKIP: buf breaking passed (field options are invisible to it)

The #164 follow-up is rewritten as a comment on that issue, since its body described the pre-reset ledger.

Closes #313. The minor ledger reached 14 rows before any peer existed. Every one of those rows describes compatibility with a daemon that was never released, so the gates, fallbacks and downgrade paths they justify are dead weight the first release would have to carry forever — and the first ledger row that ever matters would be numbered 15. This folds the whole pre-release schema into the minor-0 base. ## What changes - `PROTOCOL_MINOR` 14 -> 0; the 14 `MINOR_*` constants are gone and `MINOR_LEDGER` has one row: `(0, "the base schema of protocol major 1")`. The preface golden vectors move to `1.0`. - `felis.proto`: the `PROTOCOL_MINOR` header comment is 0 and all 11 nonzero `(felis.v1.arm).since` values become `since: 0`, keeping the explicit-zero style every base arm already used. Generated Rust regenerated with `buf lint && buf generate`. - All six `GatedField` tables in `minor.rs` are empty, and every `since_minor()` on the closed enums returns 0. The tables and the `requires` impls that fold them stay, so the first post-release field is one row and nothing else. - The `Downgrade` trait and every impl are deleted: with no older peer to map to, every closed-enum value is in the base schema, and a future narrowing needs its own mapping regardless. - Every hard-coded minor gate in the client, CLI and daemon is gone (`check_scope_minor`, `check_key_input_minor`, `check_mode_minor`, the atomic-create and attach-by-prefix fallbacks, `effective_minor` plumbing through the session task, subscriber and bridge link). `check_arm_minor`, `FrameWriter::authorize`, `TransportError::MinorTooOld` and `ConnectError::MinorTooOld` are retained. - The send-authorization frame is still exercised end to end by synthetic arms declared at `PROTOCOL_MINOR + 1`, at three layers: `minor.rs` (`Requires`/`arm_requires`), `connector.rs` (`check_arm_minor`) and `framing.rs` (`FrameWriter::authorize` via `CheckedFrame::raw`, behind `feature = "test-util"`). - Docs: the `docs/reference/ipc.md` ledger table collapses to row 0 and ~12 prose sites lose their minor numbers; `docs/reference/cli.md` says `wire: 1.0`; the architecture, session-lifecycle and testing pages follow. - CHANGELOG: the four "protocol minor 11/12/13/14" Unreleased entries become plain **Wire** entries (features stay, numbers go) and a reset entry is added under Changed. The dated `[0.1.0]` and earlier sections are untouched. ## Deviation worth a look The brief says to drop `ConnectionMode::since_minor`, and I followed it literally, which also took `check_mode_minor` and the mode half of the gating with it. `since_minor()` is kept on `AttachFailure`, `RefusalReason` and `ResourceKind` so the closed-enum half of `the_ledger_covers_every_executable_addition` stays alive. If modes should keep a declared minor for symmetry, say so and I will put it back at 0. ## Gates - `cargo clippy --workspace --all-targets --all-features` — clean, no warnings - `cargo nextest run --workspace --all-features --all-targets --retries 2` — 3453 passed, 0 failed, 16 skipped - `just proto-compat` — wire-compatible with the base - `just docs-links` — 392 unique links, 0 errors - `python3 tools/prose_check.py --range origin/main...HEAD` — 0 hits - pre-commit hooks ran in full on the commit, no `SKIP`: `buf breaking` passed (field options are invisible to it) The #164 follow-up is rewritten as a comment on that issue, since its body described the pre-reset ledger.

natsukium added 1 commit 2026-09-21 20:40:48 +09:00

protocol: ship the first wire contract as 1.0, not 1.14 ... 1945fe60e8

The minor ledger grew fourteen rows while the protocol was still
unreleased, so every row records compatibility with a peer that never
existed. Shipping 1.14 would make each build carry gates, downgrade
paths and fallbacks for development history no deployed daemon can be
speaking, and would leave the ledger's first real entry indexed at 15.

Fold the whole pre-release schema into the minor-0 base: one ledger
row, every arm, field, closed-enum value, connection mode and row-codec
version available from minor 0. The gating machinery stays and is
exercised by synthetic arms declared above PROTOCOL_MINOR, so the first
post-release addition is one ledger row and one table entry rather
than a rebuilt frame.

The Downgrade trait goes with the values it mapped down: with no
older peer to map to, every closed enum is in the base schema, and a
future narrowing would need its own mapping anyway.

Assisted-by: Claude Code

natsukium referenced this pull request 2026-09-21 20:41:13 +09:00

[v0.1/P2] Exercise every minor-ledger row with a mixed-minor conversation #164

natsukium added 1 commit 2026-09-21 20:57:08 +09:00

protocol: keep connection modes inside minor authorization ... 405eca25ce

Folding the pre-release minors into the base left `ConnectionMode`
with no declared minor at all, so `ConnMsg::Hello` inherited only its
arm's base requirement. A mode added after the first release would
then reach an older daemon, which decodes the `Hello` as no mode and
drops the connection, instead of the sender-side `MinorTooOld` the
wire contract promises; the ledger coverage test also lost its only
mechanical check that a mode declares an introducing minor.

Restore `ConnectionMode::since_minor` with every shipped mode at 0,
fold it into `Hello`'s requirement, walk modes again in the generated
enum sweep, and put the pre-send check back in the connector. Both
gates are pinned by a synthetic minor one past this build, since no
real mode is post-baseline.

Reword three comments that still carried development-minor numbers the
reset deleted.

Assisted-by: Claude Code

natsukium commented 2026-09-21 20:57:26 +09:00

Author

Owner

Copy link

Sol round 1 blocker addressed in 405eca25 (additive commit, no rebase, no force-push).

Blocker — ConnectionMode is back inside minor authorization. The deviation I flagged in the description is reverted; treat that section of the body as stale.

• ConnectionMode::since_minor() restored in crates/felis-protocol/src/minor.rs, every shipped mode at 0.
• ConnMsg::Hello folds it again: arm.max(Requires::new(mode.since_minor(), "ConnectionMode")), so a mode is no longer carried by its arm's base requirement alone.
• Modes are walked again in gated_enum_values, so the_ledger_covers_every_executable_addition mechanically checks that every mode declares an introducing minor.
• check_mode_minor restored in crates/felis-client-core/src/connector.rs and called before the Hello goes out, yielding the non-transient ConnectError::MinorTooOld rather than an unexplained EOF.
• Two tests, both pinned by a synthetic minor one past this build since no real mode is post-baseline: a_hello_costs_the_minor_that_defined_its_mode (protocol) and a_mode_above_the_effective_minor_is_refused (connector, asserts MinorTooOld and !is_transient()).
• docs/reference/ipc.md gets its send-side half back: the Hello bullet says the sender names only a mode the effective minor defines, and "Connection modes" states both ends of the rule again.

Non-blocking — development-minor history removed from comments.

• crates/felis-client-core/src/roster.rs: "a pre-minor-3 roster" -> "a roster that carries no sequences".
• crates/felis-protocol/src/messages.rs: "a // Minor 13. beside a since:" -> "a comment beside a since:".
• The sweep for minor [1-9] / minor-[1-9] / 1.[1-9] found one more: crates/felis-protocol/proto/BREAKING.md claimed "1.9 is the first public baseline", now "the first public baseline is still unpublished". Every other hit in the tree is an unrelated decimal (byte counts, ratios, MSRV).

Gates on 405eca25

• cargo clippy --workspace --all-targets --all-features — clean
• cargo nextest run --workspace --all-features --all-targets --retries 2 — 3455 passed, 0 failed, 16 skipped
• just proto-compat — wire-compatible with the base
• just docs-links — 392 unique, 0 errors
• python3 tools/prose_check.py --range origin/main...HEAD — 0 hits
• hooks on, no --no-verify, no SKIP

Sol round 1 blocker addressed in `405eca25` (additive commit, no rebase, no force-push). **Blocker — `ConnectionMode` is back inside minor authorization.** The deviation I flagged in the description is reverted; treat that section of the body as stale. - `ConnectionMode::since_minor()` restored in `crates/felis-protocol/src/minor.rs`, every shipped mode at 0. - `ConnMsg::Hello` folds it again: `arm.max(Requires::new(mode.since_minor(), "ConnectionMode"))`, so a mode is no longer carried by its arm's base requirement alone. - Modes are walked again in `gated_enum_values`, so `the_ledger_covers_every_executable_addition` mechanically checks that every mode declares an introducing minor. - `check_mode_minor` restored in `crates/felis-client-core/src/connector.rs` and called before the `Hello` goes out, yielding the non-transient `ConnectError::MinorTooOld` rather than an unexplained EOF. - Two tests, both pinned by a synthetic minor one past this build since no real mode is post-baseline: `a_hello_costs_the_minor_that_defined_its_mode` (protocol) and `a_mode_above_the_effective_minor_is_refused` (connector, asserts `MinorTooOld` and `!is_transient()`). - `docs/reference/ipc.md` gets its send-side half back: the `Hello` bullet says the sender names only a mode the effective minor defines, and "Connection modes" states both ends of the rule again. **Non-blocking — development-minor history removed from comments.** - `crates/felis-client-core/src/roster.rs`: "a pre-minor-3 roster" -> "a roster that carries no sequences". - `crates/felis-protocol/src/messages.rs`: "a `// Minor 13.` beside a `since:`" -> "a comment beside a `since:`". - The sweep for `minor [1-9]` / `minor-[1-9]` / `1.[1-9]` found one more: `crates/felis-protocol/proto/BREAKING.md` claimed "1.9 is the first public baseline", now "the first public baseline is still unpublished". Every other hit in the tree is an unrelated decimal (byte counts, ratios, MSRV). **Gates on `405eca25`** - `cargo clippy --workspace --all-targets --all-features` — clean - `cargo nextest run --workspace --all-features --all-targets --retries 2` — 3455 passed, 0 failed, 16 skipped - `just proto-compat` — wire-compatible with the base - `just docs-links` — 392 unique, 0 errors - `python3 tools/prose_check.py --range origin/main...HEAD` — 0 hits - hooks on, no `--no-verify`, no `SKIP`

natsukium added 1 commit 2026-09-21 21:19:30 +09:00

cli: keep the frozen protocol_mismatch kind without a constructor ... ec9d85a8ef

The only site that raised `ErrorKind::ProtocolMismatch` was the
keyboard-input minor gate, which went when the whole schema became
minor 0: with one wire generation and no post-baseline surface
version, nothing can reach the kind. The token is published in the
`v1` vocabulary, the golden fixture and the CLI reference, so deleting
the variant would break a consumer that already branches on it.

Silence `dead_code` on the variant alone. The workspace lint run hid
this because `--all-features` compiles the `schema` feature, whose
`ALL` slice names every variant; the Windows cross job lints without
it and failed.

Assisted-by: Claude Code

natsukium commented 2026-09-21 21:19:45 +09:00

Author

Owner

Copy link

Windows clippy fixed in ec9d85a8 (additive, no rebase, no force-push).

The failure is not target-specific. ErrorKind::ProtocolMismatch has no constructor on any target: its only one was the keyboard-input minor gate in cli_sessions.rs, which went when the whole schema became minor 0. ConnectError::MinorTooOld already maps to ErrorKind::Unsupported (cli_output.rs:267), target-independently and unchanged from main, so there was no unix-only mapping to generalize.

What hid it on the Linux job is the feature set, not the target: ErrorKind::ALL is #[cfg(any(test, feature = "schema"))] and names every variant, so --all-features constructs the variant while the Windows cross job — cargo clippy --workspace --all-targets --target x86_64-pc-windows-gnu, no --all-features — does not. cargo clippy -p felis-cli --all-targets on Linux reproduces it exactly.

Fix: the variant stays and is annotated deliberately. protocol_mismatch is published in crates/felis-cli/schemas/felis-cli-v1.schema.json, tests/golden/error_kinds.txt and docs/reference/cli.md, and the vocabulary is frozen within a v, so deleting it would break a consumer that already branches on it. The doc comment now says nothing can raise it while major 1 is the only generation and the schema is all minor 0, and #[allow(dead_code)] sits on that variant alone. The golden still lists it (felis-cli suite: 331 passed).

Verified

• nix develop .#windows -c cargo clippy --workspace --all-targets --target x86_64-pc-windows-gnu -- -D warnings — passes. The one remaining warning is the pre-existing unused dependency \rustix`manifest warning infelis-pty`, unrelated to this PR and not fatal.
• cargo clippy --workspace --all-targets (no --all-features) — clean
• cargo clippy --workspace --all-targets --all-features — clean
• cargo nextest run -p felis-cli --all-features --all-targets --retries 2 — 331 passed
• python3 tools/prose_check.py --range origin/main...HEAD — 0 hits
• hooks on, no --no-verify, no SKIP

Windows clippy fixed in `ec9d85a8` (additive, no rebase, no force-push). **The failure is not target-specific.** `ErrorKind::ProtocolMismatch` has no constructor on *any* target: its only one was the keyboard-input minor gate in `cli_sessions.rs`, which went when the whole schema became minor 0. `ConnectError::MinorTooOld` already maps to `ErrorKind::Unsupported` (`cli_output.rs:267`), target-independently and unchanged from main, so there was no unix-only mapping to generalize. What hid it on the Linux job is the feature set, not the target: `ErrorKind::ALL` is `#[cfg(any(test, feature = "schema"))]` and names every variant, so `--all-features` constructs the variant while the Windows cross job — `cargo clippy --workspace --all-targets --target x86_64-pc-windows-gnu`, no `--all-features` — does not. `cargo clippy -p felis-cli --all-targets` on Linux reproduces it exactly. **Fix:** the variant stays and is annotated deliberately. `protocol_mismatch` is published in `crates/felis-cli/schemas/felis-cli-v1.schema.json`, `tests/golden/error_kinds.txt` and `docs/reference/cli.md`, and the vocabulary is frozen within a `v`, so deleting it would break a consumer that already branches on it. The doc comment now says nothing can raise it while major 1 is the only generation and the schema is all minor 0, and `#[allow(dead_code)]` sits on that variant alone. The golden still lists it (`felis-cli` suite: 331 passed). **Verified** - `nix develop .#windows -c cargo clippy --workspace --all-targets --target x86_64-pc-windows-gnu -- -D warnings` — passes. The one remaining warning is the pre-existing `unused dependency \`rustix\`` manifest warning in `felis-pty`, unrelated to this PR and not fatal. - `cargo clippy --workspace --all-targets` (no `--all-features`) — clean - `cargo clippy --workspace --all-targets --all-features` — clean - `cargo nextest run -p felis-cli --all-features --all-targets --retries 2` — 331 passed - `python3 tools/prose_check.py --range origin/main...HEAD` — 0 hits - hooks on, no `--no-verify`, no `SKIP`

natsukium merged commit db188f6a67 into main 2026-09-21 21:34:24 +09:00

natsukium deleted branch minor-reset 2026-09-21 21:34:24 +09:00

natsukium referenced this pull request from a commit 2026-09-21 21:34:25 +09:00

protocol: ship the first wire contract as 1.0, not 1.14 (#325)

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

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

natsukium referenced this pull request 2026-09-22 20:38:09 +09:00

[v0.1/P2] Exercise every minor-ledger row with a mixed-minor conversation #164

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

No description provided.