[v0.1/P1] Make IPC arm routing metadata machine-readable #303

Closed

opened 2026-09-21 12:08:09 +09:00 by natsukium · 1 comment

natsukium commented

2026-09-21 12:08:09 +09:00

Owner

Problem

The routing contract is represented twice: as // arm: comments in crates/felis-protocol/proto/felis.proto and as hand-maintained ArmMeta tables in crates/felis-protocol/src/messages/*.

The comments are useful for repository checks, but they are not part of the protobuf descriptor consumed by non-Rust implementations. A client generated from felis.proto cannot discover direction, correlation class, allowed modes/phases, or minor availability from the machine-readable schema. It must duplicate the contract from the Rust tables or documentation.

This weakens the stated cross-language reuse surface and makes schema/routing drift possible when a new oneof arm is added.

Proposed resolution

Before the first public wire freeze, make routing metadata part of the schema authority:

encode the arm columns as protobuf custom options, or
generate the Rust arm tables and an external contract manifest from one authoritative schema.

Do not require external implementations to parse comments.

Acceptance criteria

A non-Rust implementation can obtain the arm routing metadata without parsing comments or Rust source.
The Rust driver tables are generated or mechanically checked against that same metadata.
Adding or removing an arm fails the relevant compatibility check when routing metadata is missing or inconsistent.
The decision and any intentional limitations are recorded in the IPC explanation/reference docs.

Sources

crates/felis-protocol/proto/felis.proto
crates/felis-protocol/src/messages/arm.rs
crates/felis-protocol/src/messages/*
docs/reference/ipc.md (arm table and versioning)

## Problem The routing contract is represented twice: as `// arm:` comments in `crates/felis-protocol/proto/felis.proto` and as hand-maintained `ArmMeta` tables in `crates/felis-protocol/src/messages/*`. The comments are useful for repository checks, but they are not part of the protobuf descriptor consumed by non-Rust implementations. A client generated from `felis.proto` cannot discover direction, correlation class, allowed modes/phases, or minor availability from the machine-readable schema. It must duplicate the contract from the Rust tables or documentation. This weakens the stated cross-language reuse surface and makes schema/routing drift possible when a new oneof arm is added. ## Proposed resolution Before the first public wire freeze, make routing metadata part of the schema authority: - encode the arm columns as protobuf custom options, or - generate the Rust arm tables and an external contract manifest from one authoritative schema. Do not require external implementations to parse comments. ## Acceptance criteria - A non-Rust implementation can obtain the arm routing metadata without parsing comments or Rust source. - The Rust driver tables are generated or mechanically checked against that same metadata. - Adding or removing an arm fails the relevant compatibility check when routing metadata is missing or inconsistent. - The decision and any intentional limitations are recorded in the IPC explanation/reference docs. ## Sources - `crates/felis-protocol/proto/felis.proto` - `crates/felis-protocol/src/messages/arm.rs` - `crates/felis-protocol/src/messages/*` - `docs/reference/ipc.md` (arm table and versioning)

natsukium added the

priority/P1

release/v0.1.0

type/design

labels

2026-09-21 12:08:16 +09:00

natsukium referenced this issue

2026-09-21 12:23:11 +09:00

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

natsukium referenced this issue

2026-09-21 13:02:36 +09:00

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

natsukium commented

2026-09-21 13:02:48 +09:00

Author

Owner

Direction agreed 2026-09-21 after three sol design-review rounds (final verdict PASS). Full plan and batch order: see the comment on #12.

#303 — protobuf custom options, not a manifest. The architecture
overview already rejects a committed contract manifest and says the answer
for a schema-only consumer is the FileDescriptorSet the schema compiles to;
a routing-only JSON would reopen that. Each oneof arm carries a
(felis.v1.arm) field option with direction, correlation, modes, phases and
since; the // arm: comments are deleted. prost ignores options, so the
generated Rust is unchanged; the_schema_declares_the_same_arm_table parses
the option text instead of the comment (same grammar). A non-Rust peer reads
the options from the descriptor (buf build / protoc reflection). Adding an
arm without an option, or with a disagreeing one, still fails the build; the
compat gate's buf breaking does not see options, so the Rust test remains
the mechanical check and the docs say so. ipc.md "The arm table" and
workspace.md "Cross-language wire contract" are updated.

Direction agreed 2026-09-21 after three `sol` design-review rounds (final verdict PASS). Full plan and batch order: see the comment on #12. - **#303** — protobuf custom options, not a manifest. The architecture overview already rejects a committed contract manifest and says the answer for a schema-only consumer is the `FileDescriptorSet` the schema compiles to; a routing-only JSON would reopen that. Each oneof arm carries a `(felis.v1.arm)` field option with direction, correlation, modes, phases and since; the `// arm:` comments are deleted. prost ignores options, so the generated Rust is unchanged; `the_schema_declares_the_same_arm_table` parses the option text instead of the comment (same grammar). A non-Rust peer reads the options from the descriptor (`buf build` / protoc reflection). Adding an arm without an option, or with a disagreeing one, still fails the build; the compat gate's `buf breaking` does not see options, so the Rust test remains the mechanical check and the docs say so. `ipc.md` "The arm table" and `workspace.md` "Cross-language wire contract" are updated.

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

2026-09-21 19:20:17 +09:00

protocol: carry arm routing in the descriptor, not in comments #324

natsukium closed this issue

2026-09-21 19:57:13 +09:00

natsukium referenced this issue

2026-09-21 21:35:04 +09:00

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

natsukium referenced this issue

2026-09-21 22:54:14 +09:00

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

natsukium referenced this issue