natsukium/felis

Archived

Watch

[v0.1/P1] Strip pre-release history and redundancy from the 1.0 base schema #330

Closed

opened 2026-09-21 23:15:28 +09:00 by natsukium · 2 comments

natsukium commented

2026-09-21 23:15:28 +09:00

Owner

Background

The first public wire contract is the minor-0 base schema (#313, commit db188f6a). felis.proto and the docs state that a number retired while no baseline exists is free again, and AGENTS.md says source comments are never for history. Yet the schema still carries reserved numbers, retired enum values, a superseded field, and history comments from pre-release churn. The freeze is the last inexpensive point to remove them.

Findings

1. Reclaim retired field numbers and enum values

reserved lines plus history comments, all of them pre-release retirements:

RefusalReason (felis.proto:262-263, GENERATION / ENCODING)
ConnHello (:817-818, wire_generation)
ConnRefused (:863-864, daemon_generation)
ImageHeader (:1494-1495, width / height / format / total_bytes)
ImageChunk (:1525-1526), ImageComplete (:1535-1536), ImageShowFrame (:1581-1582)
SessionAttached (:1711-1712, created)
RetargetTarget (:2089-2090, the old optional bag)
ResourceReport (:2225-2226, used / limit), ResourceKind (:2261-2263, worker_threads / grids)
RegionRowsDone (:2395-2396), SearchMsg (:2494)

Renumber the surviving fields densely, delete the reserved lines and the comments that narrate what a number used to be, and acknowledge the wire break in crates/felis-protocol/proto/BREAKING.md with a base: line (the mechanism already exists).

2. Drop `ConnWelcome.build_id`

build_id (:832-840) is "superseded by identity, kept populated for a reader that knows only it." No such reader can exist before the first release. Remove the field and the daemon_build_id it feeds in felis-client-core/src/connector.rs; BuildIdentity is the typed answer.

3. Omit `since: 0` from the base arms

All 86 base arms write since: 0, which is the proto3 default and is absent from the descriptor when 0. It becomes meaningful only when a minor adds an arm. Omit it from the base arms so an addition is the only place a since appears.

Why

AGENTS.md: a comment survives only for a why-not or an invariant, never for history.
felis.proto header: "a number retired while no baseline exists is free again."
The schema is the single machine-readable authority for non-Rust peers; a reader should not have to reason about what field 2 used to hold.

Acceptance criteria

felis.proto carries no reserved line and no history comment for a pre-release retirement; surviving fields are densely numbered.
ConnWelcome carries only BuildIdentity.
Base arms omit since (0 default); the arm-routing sync still passes.
just proto regenerated; BREAKING.md, the protocol tests, and CHANGELOG.md updated.

Parent: #326
#313 — reset the first public protocol minor to 0
#147 — wire major/minor and BREAKING baseline
#115 — wire-gate release baseline workflow

## Background The first public wire contract is the minor-0 base schema (#313, commit `db188f6a`). `felis.proto` and the docs state that a number retired while no baseline exists is free again, and `AGENTS.md` says source comments are never for history. Yet the schema still carries `reserved` numbers, retired enum values, a superseded field, and history comments from pre-release churn. The freeze is the last inexpensive point to remove them. ## Findings ### 1. Reclaim retired field numbers and enum values `reserved` lines plus history comments, all of them pre-release retirements: - `RefusalReason` (`felis.proto:262-263`, GENERATION / ENCODING) - `ConnHello` (`:817-818`, `wire_generation`) - `ConnRefused` (`:863-864`, `daemon_generation`) - `ImageHeader` (`:1494-1495`, width / height / format / total_bytes) - `ImageChunk` (`:1525-1526`), `ImageComplete` (`:1535-1536`), `ImageShowFrame` (`:1581-1582`) - `SessionAttached` (`:1711-1712`, `created`) - `RetargetTarget` (`:2089-2090`, the old optional bag) - `ResourceReport` (`:2225-2226`, used / limit), `ResourceKind` (`:2261-2263`, worker_threads / grids) - `RegionRowsDone` (`:2395-2396`), `SearchMsg` (`:2494`) Renumber the surviving fields densely, delete the `reserved` lines and the comments that narrate what a number used to be, and acknowledge the wire break in `crates/felis-protocol/proto/BREAKING.md` with a `base:` line (the mechanism already exists). ### 2. Drop `ConnWelcome.build_id` `build_id` (`:832-840`) is "superseded by `identity`, kept populated for a reader that knows only it." No such reader can exist before the first release. Remove the field and the `daemon_build_id` it feeds in `felis-client-core/src/connector.rs`; `BuildIdentity` is the typed answer. ### 3. Omit `since: 0` from the base arms All 86 base arms write `since: 0`, which is the proto3 default and is absent from the descriptor when 0. It becomes meaningful only when a minor adds an arm. Omit it from the base arms so an addition is the only place a `since` appears. ## Why - `AGENTS.md`: a comment survives only for a why-not or an invariant, never for history. - `felis.proto` header: "a number retired while no baseline exists is free again." - The schema is the single machine-readable authority for non-Rust peers; a reader should not have to reason about what field 2 used to hold. ## Acceptance criteria - [ ] `felis.proto` carries no `reserved` line and no history comment for a pre-release retirement; surviving fields are densely numbered. - [ ] `ConnWelcome` carries only `BuildIdentity`. - [ ] Base arms omit `since` (0 default); the arm-routing sync still passes. - [ ] `just proto` regenerated; `BREAKING.md`, the protocol tests, and `CHANGELOG.md` updated. ## Related - Parent: #326 - #313 — reset the first public protocol minor to 0 - #147 — wire major/minor and BREAKING baseline - #115 — wire-gate release baseline workflow

natsukium added the

priority/P1

release/v0.1.0

type/design

labels

2026-09-21 23:15:37 +09:00

natsukium referenced this issue

2026-09-21 23:15:42 +09:00

[v0.1/P1] Final interface simplification audit before public freeze #326

natsukium commented

2026-09-21 23:16:16 +09:00

Author

Owner

Coordination note: the ResourceReport / ResourceKind retirements reclaimed here overlap with #328 case 2 (the ResourceReport optional-field shape). Whichever lands second should renumber on top of the other rather than against the current file.

Coordination note: the `ResourceReport` / `ResourceKind` retirements reclaimed here overlap with #328 case 2 (the `ResourceReport` optional-field shape). Whichever lands second should renumber on top of the other rather than against the current file.

natsukium referenced this issue

2026-09-21 23:16:29 +09:00

[v0.1/P1] Final interface simplification audit before public freeze #326

natsukium referenced this issue

2026-09-21 23:20:35 +09:00

[v0.1/P1] Remove minor-reset fallbacks and duplicate status identity #333

natsukium referenced this issue

2026-09-21 23:20:49 +09:00

[v0.1/P1] Final interface simplification audit before public freeze #326

natsukium referenced this issue

2026-09-22 00:48:05 +09:00

[v0.1/P1] Final interface simplification audit before public freeze #326

natsukium referenced this issue

2026-09-22 00:48:05 +09:00

Eliminate implicit-absence meanings from the wire before the baseline freezes #327

natsukium referenced this issue

2026-09-22 00:48:05 +09:00

Freeze wire scalar shapes: attachment ids, resource report, env pair, pacing flag #328

natsukium commented

2026-09-22 00:48:06 +09:00

Author

Owner

Decision: do, mechanical, with one explicit exclusion (reviewed)

Verified: 30 reserved declarations, of which five are live, not history, and must stay: reserved 100; on ConnMsg, InputMsg, GridMsg, ImageMsg, PushMsg hold the wire-wide correlation-envelope slot for the uncorrelated families (felis.proto header, "field 100 of every family wrapper"). The other 25 declarations and their history comments are the pre-release retirements listed above and are removed, with the surviving fields renumbered densely. Also: drop ConnWelcome.build_id and the daemon_build_id it feeds in connector.rs; omit since: 0 from all 86 base arms.

This applies the schema's own rule ("a number retired while no baseline exists is free again"). One base: line in BREAKING.md. Lands first in the proto batch because it renumbers; #328, #327, #333 each rebase on the previous merge with their own base: line (tools/proto/compat.py matches against the immediate merge-base, so sequential lines stay valid). The #326 item-1 retention note for SessionMsg field 100 rides this PR's doc cascade.

## Decision: do, mechanical, with one explicit exclusion (reviewed) Verified: 30 `reserved` declarations, of which **five are live, not history**, and must stay: `reserved 100;` on `ConnMsg`, `InputMsg`, `GridMsg`, `ImageMsg`, `PushMsg` hold the wire-wide correlation-envelope slot for the uncorrelated families (`felis.proto` header, "field 100 of every family wrapper"). The other 25 declarations and their history comments are the pre-release retirements listed above and are removed, with the surviving fields renumbered densely. Also: drop `ConnWelcome.build_id` and the `daemon_build_id` it feeds in `connector.rs`; omit `since: 0` from all 86 base arms. This applies the schema's own rule ("a number retired while no baseline exists is free again"). One `base:` line in `BREAKING.md`. Lands **first** in the proto batch because it renumbers; #328, #327, #333 each rebase on the previous merge with their own `base:` line (`tools/proto/compat.py` matches against the immediate merge-base, so sequential lines stay valid). The #326 item-1 retention note for `SessionMsg` field 100 rides this PR's doc cascade.

natsukium added the

status/planned

label

2026-09-22 00:48:27 +09:00

natsukium referenced this issue from a pull request that will close it,

2026-09-22 02:04:11 +09:00

protocol: reclaim the numbers pre-release churn retired #339

natsukium closed this issue

2026-09-22 03:31:25 +09:00

Commenting is not possible because the repository is archived.