Skip to content

Deepen the Cycle module and tidy the seams around it - #2

Merged
archae0pteryx merged 3 commits into
mainfrom
deepen-cycle-module
Oct 29, 2026
Merged

archae0pteryx merged 3 commits into
mainfrom
deepen-cycle-module

Conversation

@archae0pteryx

Copy link
Copy Markdown
Contributor

Why

Presses, focus hooks and the Alt-release watcher are separate processes that agree through a state file. The rule for "is this focus event the cycle's or the user's?" was spread over Cycler, Tracker, ReleaseWaiter, Session and SessionStore, and callers had to use them in the right order (save before focus, take the lock, honour the grace window). This came out of an architecture review; the design decisions are in the commit message and GLOSSARY.md.

What changed

  • Cycle module (src/cycle/): interface is Cycle::{press, observe_focus, release}, Direction, CycleId. State machine and store are private. Saved state is only reachable through a lock-scoped Turn.
  • Rename Session to Cycle; the state file is now cycle-<hash>.json. No migration: an old file is ignored and a cycle lives at most 30s.
  • History owns the live-pane recency rule and hands out an opaque Snapshot. Visit is private.
  • Lock is split from StateFile (Connection::lock).
  • Herdr: LiveConfig moves into the herdr module and HerdrBinary::run is private. Panes has a constructor.
  • Environment: one module reads every variable once. herdr_env.rs and keys/config_path.rs are gone.
  • Clock gains pause, so the release wait loop and its 30s cap are testable.
  • GLOSSARY.md added, defining Cycle.

Behaviour changes

  • observe_focus now holds the cycle lock through its History write (it used to drop it first), matching press.
  • The release wait loop uses Clock instead of Instant/sleep; real behaviour is unchanged.
  • Removed Panes::contains, which had no production caller left.

Tests

117 to 103: overlapping tests were consolidated (one test per behaviour). New tests cover the 30s hold cap, release grace window, idle window, recency order, and the config check/reload adapter. I replaced focus_a_cycle_caused_is_left_out_of_history with a stronger version that passes through a pane, because the old assertion became vacuous once Visit was private. I also injected six deliberate bugs into the focus-ownership logic and each was caught by a test.

cargo fmt --check, cargo clippy --all-targets -- -D warnings and cargo test pass locally on macOS. I also ran the debug binary against a stub herdr (older, older, track, bad args). Not tested: Linux, a real Herdr, a real Alt hold.

Presses, focus hooks and the Alt-release watcher are separate processes
that agree through a state file. That protocol was spread over Cycler,
Tracker, ReleaseWaiter, Session and SessionStore, and had to be called in
the right order. It now lives in one module, src/cycle/, whose interface
is Cycle::{press, observe_focus, release}, Direction and CycleId.

- Rename Session to Cycle; the state file is now cycle-<hash>.json. An
  old session file is simply ignored, and a cycle lasts at most 30s.
- observe_focus holds the cycle lock through its History write, as
  press already did.
- Saved state is only reachable through a lock-scoped Turn.
- History owns the live-pane recency rule and hands out an opaque
  Snapshot; Visit is private.
- Lock is split from StateFile (Connection::lock).
- LiveConfig moves into the herdr module and HerdrBinary::run is private.
- Environment reads every variable once; herdr_env and config_path go.
- Clock gains pause so the release wait loop and its 30s cap are testable.
- Add GLOSSARY.md defining Cycle.

Overlapping tests are consolidated (117 -> 103) and new ones cover the
hold cap, release grace, idle window and config check/reload.
…ook lock

- Socket reads time out after 2s, so a stalled Herdr cannot hold the cycle
  lock forever and queue up every press and hook behind it.
- The release watcher no longer ends the cycle when it gives up at the hold
  cap with Alt still down; the cycle expires on its own after its last press.
- Test that the focus hook holds the cycle lock while it asks Herdr.
- Cycle keeps Collaborators whole instead of copying its five fields.
@archae0pteryx
archae0pteryx merged commit 5e8ae57 into main Oct 29, 2026
2 checks passed
@archae0pteryx
archae0pteryx deleted the deepen-cycle-module branch October 29, 2026 18:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant