natsukium/felis

Watch

docs: state why the FRLY carrier caps are 4096 / 1 MiB #154

Merged

natsukium merged 3 commits from docs/frly-carrier-caps-139 into main

2026-09-06 03:42:16 +09:00

natsukium commented

2026-09-06 03:26:48 +09:00

Owner

Fixes #139.

The FRLY carrier block's limit table stated 4096 entries and 1 MiB without saying where the numbers came from, and the caps are frozen for the protocol major — v1 is the last chance to change them, so the sizing argument has to be readable now. This records that argument and the degrade contract that follows from it, and pins the degrade in a test.

docs/reference/ipc.md / docs/explanation/architecture/ipc.md: state the measurement the caps are set against (a login environment measures tens of KiB), why the payload cap bounds the single allocation the declared length word buys before any of it is trusted, and why chunking the payload is rejected (chunk boundaries are framing; a relay that respects them is no longer a byte pump).
crates/felis-daemon/src/relay.rs: take the carrier block as an argument so a test can drive an environment past MAX_CARRIER_ENTRIES, and pin the over-cap behavior — the relay warns and sends the client's bare FLIS stream rather than failing the connection.
crates/felis-protocol/src/preface.rs, docs/reference/spec.md (REQ-104c), and the relay module doc: qualify the carrier-block prefix as omittable, since the unqualified prose read as if the block were sent unconditionally and contradicted the degrade path documented on the same page.

Doc cascade: reference (docs/reference/ipc.md, docs/reference/spec.md) states the resulting facts; the explanation twin (docs/explanation/architecture/ipc.md) carries the sizing rationale, the degrade argument, and the rejected chunking alternative; the code mirrors (preface.rs, relay.rs module docs) keep only the invariant and cite the docs.

Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high

Deferred

No BREAKING.md acknowledgment or proto-compat base line — the accepted verdict freezes 4096 / 1 MiB unchanged, so there is no wire break to acknowledge; just proto-compat reports wire-compatible with the base.
No typed "carrier block too large" diagnostic or exit-class change — explicitly dropped by the accepted plan: the relay degrades instead of failing, so there is no failure to type.
Environment gaps hit while gating (yq missing from PATH for just skill-check; cross-worktree artifact contamination in the shared cargo target dir) — harness/environment issues, not repository defects, and unrelated to #139's scope; both were worked around.

Fixes #139. The FRLY carrier block's limit table stated 4096 entries and 1 MiB without saying where the numbers came from, and the caps are frozen for the protocol major — v1 is the last chance to change them, so the sizing argument has to be readable now. This records that argument and the degrade contract that follows from it, and pins the degrade in a test. - `docs/reference/ipc.md` / `docs/explanation/architecture/ipc.md`: state the measurement the caps are set against (a login environment measures tens of KiB), why the payload cap bounds the single allocation the declared length word buys before any of it is trusted, and why chunking the payload is rejected (chunk boundaries are framing; a relay that respects them is no longer a byte pump). - `crates/felis-daemon/src/relay.rs`: take the carrier block as an argument so a test can drive an environment past `MAX_CARRIER_ENTRIES`, and pin the over-cap behavior — the relay warns and sends the client's bare FLIS stream rather than failing the connection. - `crates/felis-protocol/src/preface.rs`, `docs/reference/spec.md` (REQ-104c), and the relay module doc: qualify the carrier-block prefix as omittable, since the unqualified prose read as if the block were sent unconditionally and contradicted the degrade path documented on the same page. Doc cascade: reference (`docs/reference/ipc.md`, `docs/reference/spec.md`) states the resulting facts; the explanation twin (`docs/explanation/architecture/ipc.md`) carries the sizing rationale, the degrade argument, and the rejected chunking alternative; the code mirrors (`preface.rs`, `relay.rs` module docs) keep only the invariant and cite the docs. Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high ## Deferred - No BREAKING.md acknowledgment or proto-compat base line — the accepted verdict freezes 4096 / 1 MiB unchanged, so there is no wire break to acknowledge; `just proto-compat` reports wire-compatible with the base. - No typed "carrier block too large" diagnostic or exit-class change — explicitly dropped by the accepted plan: the relay degrades instead of failing, so there is no failure to type. - Environment gaps hit while gating (`yq` missing from PATH for `just skill-check`; cross-worktree artifact contamination in the shared cargo target dir) — harness/environment issues, not repository defects, and unrelated to #139's scope; both were worked around.

natsukium added 3 commits

2026-09-06 03:26:48 +09:00

docs: state why the FRLY carrier caps are 4096 / 1 MiB 8bef97d46c

A contributor reading the carrier block's limit table had no way to
tell whether 1 MiB is generous or a hazard, and the caps are frozen for
the protocol major: v1 is the last chance to change them, so the
sizing argument has to be readable now. A login environment measures
tens of KiB (53 KiB in a login shell, 59 KiB inside this repo's
`nix develop` shell), which is the measurement the caps are set
against, and the payload cap is what bounds the single allocation the
declared length word buys before any of it is trusted.

Also record the degrade contract the caps imply: an environment over
either limit is dropped rather than fatal, since a create with a stale
agent socket beats no session on a host the user reached to get one.
Chunking the payload is rejected with the protocol-aware relay it
resembles — chunk boundaries are framing, and a relay that respects
them is no longer a byte pump.

Refs #139

daemon: pin the relay's over-cap environment degrade 02a148b16e

Nothing held the relay to dropping an over-cap carrier block rather
than failing the connection: the existing tests cover the happy path
and an ordinary environment's `encode()`, so a change that turned the
warning into an error would have gone unnoticed while looking to the
user like an unreachable daemon. Taking the block as an argument lets
the test drive an environment past `MAX_CARRIER_ENTRIES` without
touching the process environment.

Refs #139

docs: qualify the relay's carrier-block prefix as omittable

bench / Criterion full-suite snapshot (pull_request) Has been skipped

Details

fuzz / cargo fuzz nightly long-run (pull_request) Has been skipped

Details

darwin / build felis (aarch64-darwin) (pull_request) Successful in 48s

Details

bench / Criterion regression gate (pull_request) Failing after 2m15s

Details

fuzz / cargo fuzz smoke (per target) (pull_request) Successful in 1m4s

Details

pr / cargo build / clippy / test / deny (pull_request) Successful in 1m46s

Details

pr / wire schema is compatible with the base (pull_request) Successful in 10s

Details

pr / nix flake check (pull_request) Successful in 25s

Details

windows / cargo nextest (Windows) (pull_request) Successful in 5m59s

Details

pr / frontend smoke (x86_64-linux) (pull_request) Successful in 53s

Details

pr / publish felis (x86_64-linux) (pull_request) Has been skipped

Details

windows / cargo clippy (Windows cross) (pull_request) Successful in 14s

Details

windows / frontend smoke (Windows) (pull_request) Successful in 1m38s

Details

windows / package felis (x86_64-pc-windows-msvc) (pull_request) Has been skipped

Details

643bc89fc8

The overview prose, REQ-104c, and the relay module doc all read as if
the carrier block were sent unconditionally, which contradicts the
degrade path the same reference page documents: over either frozen cap
the relay warns and sends the client's bare FLIS stream, so a reader
of the unqualified sentences would treat a block-less stream as a bug.

The module doc keeps only the relay's invariant and its citations; the
environment provenance and the degrade argument belong to the
explanation twin, which already carries them, and a comment that
argues them at the site exceeds the five-line ceiling.

Refs #139

natsukium merged commit 43de8a799b into main

2026-09-06 03:42:16 +09:00

natsukium deleted branch docs/frly-carrier-caps-139

2026-09-06 03:42:16 +09:00

natsukium referenced this pull request

2026-09-07 16:09:12 +09:00

[v0.1/Proto Review] Freeze protobuf and IPC contracts (7 issues) #52