refactor: carry the connection's role in its phase #84

Merged

natsukium merged 3 commits from refactor/driver-phases-46 into main 2026-09-04 20:37:11 +09:00

Conversation 0 Commits 3 Files changed 21 +1115 -378

natsukium commented 2026-09-04 20:16:09 +09:00

Owner

Copy link

Fixes #46.

Phase stopped at Steady, so one state served a welcomed connection
waiting to attach, an attached session, and a notification observer.
Kind-level admission had to be permissive enough for all three, and each
call site made up the difference by hand: the daemon's pre-attach loop
refused a second opener, the attached pump refused a second Attach, the
observer loop refused everything but a cancel, and the client decoded
uncorrelated session replies straight off a kind match, past the driver's
direction and phase columns. A peer reading the arm table saw none of that.

The phase splits into Setup | Attached | Observing, each arm declares its
phases in the same table felis.proto restates, and the driver admits every
inbound frame against it once: the kind fold before the body decodes, the
arm's own row after. The hand guards go with it, and DriverError::OutOfPhase
names the phases an arm does belong to. Mode is checked before phase so a
surface the connection never asked for is answered with a typed
Conn::Refused rather than told to wait for a state it can never reach.

Doc cascade: docs/reference/ipc.md gains the "Connection phases" ladder and
transition table beside the arm table's phases column; the explanation twin
docs/explanation/architecture/ipc.md records why the ladder is data the
driver owns rather than a typestate (the driver is shared behind a mutex in
the GUI and behind &mut in three daemon loops) and why there is no Closing
phase; REQ-114 in docs/reference/spec.md now names the out-of-phase frame
and the ladder; CHANGELOG.md records the wire-visible phases column change.

Verified: just check green (fmt, clippy, nextest, deny); reviewed by
plan/correctness/docs lenses and pi sol.

Fixes #46. `Phase` stopped at `Steady`, so one state served a welcomed connection waiting to attach, an attached session, and a notification observer. Kind-level admission had to be permissive enough for all three, and each call site made up the difference by hand: the daemon's pre-attach loop refused a second opener, the attached pump refused a second `Attach`, the observer loop refused everything but a cancel, and the client decoded uncorrelated session replies straight off a kind match, past the driver's direction and phase columns. A peer reading the arm table saw none of that. The phase splits into `Setup | Attached | Observing`, each arm declares its phases in the same table `felis.proto` restates, and the driver admits every inbound frame against it once: the kind fold before the body decodes, the arm's own row after. The hand guards go with it, and `DriverError::OutOfPhase` names the phases an arm does belong to. Mode is checked before phase so a surface the connection never asked for is answered with a typed `Conn::Refused` rather than told to wait for a state it can never reach. Doc cascade: `docs/reference/ipc.md` gains the "Connection phases" ladder and transition table beside the arm table's `phases` column; the explanation twin `docs/explanation/architecture/ipc.md` records why the ladder is data the driver owns rather than a typestate (the driver is shared behind a mutex in the GUI and behind `&mut` in three daemon loops) and why there is no `Closing` phase; REQ-114 in `docs/reference/spec.md` now names the out-of-phase frame and the ladder; `CHANGELOG.md` records the wire-visible `phases` column change. Verified: just check green (fmt, clippy, nextest, deny); reviewed by plan/correctness/docs lenses and pi sol.

natsukium added 2 commits 2026-09-04 20:16:09 +09:00

docs: record the connection phase ladder ... 64815fef6d

The reference promised one shared validator for phase, direction, mode
and correlation while the phase model stopped at the handshake, so an
implementer of a non-Rust peer had to reconstruct the attach/subscribe
sequencing from felis's own handlers. Name the five phases and their
transitions where the arm table's `phases` column is defined, state that
teardown is the connection ending rather than a phase, and record in the
explanation twin why the ladder is data the driver owns rather than a
typestate — the driver is shared behind a mutex in the GUI and behind
`&mut` in three daemon loops, and a typestate would force three drivers.

Refs #46

refactor: carry the connection's role in its phase ... f4723e6bff

`Phase` stopped at `Steady`, so one state served a welcomed connection
waiting to attach, an attached session, and a notification observer.
Kind-level admission had to be permissive enough for all three, and each
call site made up the difference by hand: the daemon's pre-attach loop
refused a second opener, the attached pump refused a second `Attach`,
the observer loop refused everything but a cancel, and the client
decoded uncorrelated session replies straight off a kind match, past the
driver's direction and phase columns. A peer reading the arm table saw
none of that.

Split the phase into `Setup | Attached | Observing`, declare each arm's
phases in the same table `felis.proto` restates, and let the driver
admit every inbound frame against it once — the kind fold before the
body decodes, the arm's own row after. The hand guards go with it, and
`DriverError::OutOfPhase` names the phases an arm does belong to.

Mode is checked before phase so a surface the connection never asked for
is still answered with a typed `Conn::Refused` rather than told to wait
for a state it can never reach.

Refs #46

natsukium added 1 commit 2026-09-04 20:22:18 +09:00

fix(daemon): gate the operation-echo attach test on unix ... 5b68d0d979

`an_attach_echoing_an_operation_lands_that_target` reaches for the
duplex-socket helpers (`create_parked_session`, `shell_factory`,
`framed`, `hello_welcome`, `send_kind`), every one of which is
`#[cfg(unix)]` because the harness drives a real PTY. Without the same
gate the Windows job fails to compile the daemon's test target, which
is what it is now doing on main; this branch only inherits the break.

The test keeps its coverage where the helpers exist rather than growing
a Windows path for them: what it pins is the ledger's attribution, not
anything platform-specific.

natsukium merged commit ffe62c9592 into main 2026-09-04 20:37:11 +09:00

natsukium deleted branch refactor/driver-phases-46 2026-09-04 20:37:11 +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

Sign in to join this conversation.

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

Notifications

Subscribe

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

No description provided.