protocol: make the minor ledger schema-first #129

New issue

Closed

opened 2026-10-12 22:07:15 +09:00 by natsukium · 0 comments

natsukium commented

2026-10-12 22:07:15 +09:00

Owner

The minor ledger (docs/reference/ipc.md "The minor ledger") is currently the hand-written source of truth for what each protocol minor added, and a sync test holds it against declarations spread over Rust: arm metadata, GatedField tables, ADDED_FIELDS, closed-enum values, row-codec versions, and MINOR_LEDGER in preface.rs. Every wire addition means editing several of these by hand and keeping them consistent.

Make the schema the source instead: annotate each post-baseline element in felis.proto with the minor that added it, and derive the rest from that.

What could come from the schema

Arms and fields: a custom FieldOptions extension, next to the existing (felis.v1.arm) option and its sync test.
Closed-enum values and connection modes: an EnumValueOptions extension.
The ledger's "Addition" column, ADDED_FIELDS, the arm/enum-value requirements the send gate reads, and possibly the presence test for a gated optional field.

What stays outside

Row-codec versions: they live inside packed_cells, not in the proto.
The "Older peer" column: a human judgment of the degradation. A test can still require that every element with a minor annotation is covered by a row, so the ledger keeps its role as the review gate.

Open points

buf breaking does not compare field options, so changing a released element's minor would go unnoticed; the wire-compat check needs to compare annotations against the release baseline.
Whether the ledger table is generated into the doc, or stays prose that a test checks against the schema.
How a "gated" field (one an older peer must not skip, like SearchQuery.source) is marked versus a plain added field.
Migration is cheapest now, while the ledger has only minors 0 and 1.

The approach is to be worked out before implementation; this issue records the direction.

The minor ledger (`docs/reference/ipc.md` "The minor ledger") is currently the hand-written source of truth for what each protocol minor added, and a sync test holds it against declarations spread over Rust: arm metadata, `GatedField` tables, `ADDED_FIELDS`, closed-enum values, row-codec versions, and `MINOR_LEDGER` in `preface.rs`. Every wire addition means editing several of these by hand and keeping them consistent. Make the schema the source instead: annotate each post-baseline element in `felis.proto` with the minor that added it, and derive the rest from that. ## What could come from the schema - Arms and fields: a custom `FieldOptions` extension, next to the existing `(felis.v1.arm)` option and its sync test. - Closed-enum values and connection modes: an `EnumValueOptions` extension. - The ledger's "Addition" column, `ADDED_FIELDS`, the arm/enum-value requirements the send gate reads, and possibly the presence test for a gated optional field. ## What stays outside - Row-codec versions: they live inside `packed_cells`, not in the proto. - The "Older peer" column: a human judgment of the degradation. A test can still require that every element with a minor annotation is covered by a row, so the ledger keeps its role as the review gate. ## Open points - `buf breaking` does not compare field options, so changing a released element's minor would go unnoticed; the wire-compat check needs to compare annotations against the release baseline. - Whether the ledger table is generated into the doc, or stays prose that a test checks against the schema. - How a "gated" field (one an older peer must not skip, like `SearchQuery.source`) is marked versus a plain added field. - Migration is cheapest now, while the ledger has only minors 0 and 1. The approach is to be worked out before implementation; this issue records the direction.

natsukium added the

Area/protocol

Kind/Enhancement

labels

2026-10-13 09:55:42 +09:00

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

2026-10-13 12:13:03 +09:00

Generate the minor ledger's metadata from the schema #135

natsukium closed this issue

2026-10-13 22:27:08 +09:00