A device below sync v4 got no playback snapshot while the queue held an
episode, so its engine never heard the owner's heartbeat and took
playback over by automatic failover after two minutes; this device then
adopted its queue and the episodes were gone. Send such peers the
coordination envelope with the queue redacted like for Jam: every
episode becomes an opaque "Private item", nothing is stripped, and their
commands stay refused while the queue has episodes.
This departs from FRID PLAYBACK_PROTOCOL.md rule 1 ("send None") and is
reported as a contract gap.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
274 lines
11 KiB
Markdown
274 lines
11 KiB
Markdown
# AGENTS.md
|
||
|
||
This file describes how to work safely in the Furumi repository. It applies to
|
||
the entire project.
|
||
|
||
## Project intent
|
||
|
||
Furumi is a cross-platform, federated P2P player for personal music libraries.
|
||
Every node must remain a complete local player without network access. Other
|
||
nodes add discovery, availability, trusted-device synchronization, and direct
|
||
track transfer; they are never a prerequisite for using the local library.
|
||
|
||
Read `ARCHITECTURE.md` before changing federation, device sync, playback
|
||
handoff, persistence, or runtime boundaries.
|
||
|
||
Preserve these architectural invariants:
|
||
|
||
1. Local import, browsing, playback, playlists, likes, and history work
|
||
offline.
|
||
2. No central Furumi service becomes required for discovery, playback, or
|
||
synchronization.
|
||
3. Federation membership does not imply trusted-device membership.
|
||
4. Remote state is merged, replicated, or cached locally; it is not treated as
|
||
an always-available database.
|
||
5. Network, database, filesystem, image, and audio preparation work stays out
|
||
of the interactive UI path.
|
||
6. Losing peers may reduce remote availability but must not invalidate local
|
||
state.
|
||
|
||
## Toolchain and checks
|
||
|
||
The crate uses Rust edition 2024 and Rust 1.97 or newer.
|
||
|
||
Run the checks relevant to every code change:
|
||
|
||
```bash
|
||
cargo fmt --all -- --check
|
||
cargo check --all-targets
|
||
cargo test --all-targets
|
||
cargo clippy --all-targets
|
||
```
|
||
|
||
`cargo clippy --all-targets` currently reports known warnings. Do not hide
|
||
them with broad `allow` attributes. Do not claim `-D warnings` passes unless
|
||
the existing warning set has actually been resolved.
|
||
|
||
Use `cargo fmt --all` after editing Rust. Keep `Cargo.lock` committed and
|
||
update it only when dependencies change.
|
||
|
||
## Source boundaries
|
||
|
||
- `src/main.rs` owns process startup, terminal restoration, Tokio setup, and
|
||
platform media-loop integration.
|
||
- `src/app/state.rs` owns UI/navigation state.
|
||
- `src/app/action.rs` and `src/app/event.rs` define input intent and runtime
|
||
results.
|
||
- `src/app/update.rs` performs state transitions and requests effects. It must
|
||
not perform blocking I/O.
|
||
- `src/app/mod.rs` owns runtime orchestration and effect execution.
|
||
- `src/library/` owns SQLite library queries, models, imports, and migrations.
|
||
- `src/player/` owns rodio playback and audio analysis.
|
||
- `src/federation/` owns DHT discovery, peer catalogs, audio exchange, and
|
||
federation caches.
|
||
- `src/podcasts/` owns podcast feed HTTP and refresh policy, the episode
|
||
stream reader (HTTP Range, bounded buffer) and the ordered progress writer;
|
||
podcast identity, merge rules and the SQLite store come from FRID
|
||
(`music_dht::podcast`, `furumi_library::podcasts`) and must not be
|
||
re-derived here. Queue items are identified by `state::track_key` /
|
||
`TrackItem::key`, never by numeric id (every episode has the same sentinel
|
||
id); music-only code must skip `TrackItem::is_podcast()` items.
|
||
- `src/devices.rs` owns trusted-device replication, membership, and playback
|
||
coordination. Its wire types are the shared `music_dht::device_sync`
|
||
definitions; do not add local copies (golden tests in
|
||
`devices/wire_compat_tests.rs` keep the v3 JSON).
|
||
- `src/ui/` renders `AppState`; rendering code must not start background work
|
||
or mutate persistence.
|
||
- `src/media.rs` owns OS media controls.
|
||
- `src/visualizer.rs` and `src/visualizations/` own the Rhai visualization
|
||
host and bundled scripts.
|
||
|
||
Prefer adding a focused module when a responsibility has a clear boundary.
|
||
Do not split files solely to reduce line count if doing so introduces leaky
|
||
APIs or circular ownership.
|
||
|
||
Keep large test suites in their existing adjacent files:
|
||
|
||
- `src/app/update_tests.rs`
|
||
- `src/devices/tests.rs`
|
||
- `src/federation/tests.rs`
|
||
- `src/library/tests.rs`
|
||
|
||
## Application state and concurrency
|
||
|
||
`AppState` is the single source of truth for the TUI. The normal flow is:
|
||
|
||
```text
|
||
external event -> AppEvent -> Action/update -> Effect -> runtime -> AppEvent
|
||
```
|
||
|
||
Follow these rules:
|
||
|
||
- Keep update logic deterministic wherever practical.
|
||
- Return an `Effect` for work that requires runtime services.
|
||
- Report asynchronous results through `AppEvent`.
|
||
- Use `tokio::task::spawn_blocking` for blocking SQLite, hashing, tag parsing,
|
||
or filesystem-heavy work invoked from async code.
|
||
- Do not hold a mutex guard across `.await`.
|
||
- Do not call terminal rendering APIs from background tasks.
|
||
- Preserve event sequence or request identifiers where they prevent stale
|
||
search, download, or synchronization results from overwriting newer state.
|
||
|
||
## Library and SQLite
|
||
|
||
`library::Library` is the authority for local catalog persistence. Keep SQL in
|
||
the library/device persistence layers rather than spreading it through the UI
|
||
or runtime.
|
||
|
||
When changing schema or stored data:
|
||
|
||
- provide an upgrade path for existing databases;
|
||
- make migrations repeatable and safe on partially upgraded databases;
|
||
- preserve foreign-key and uniqueness invariants;
|
||
- distinguish durable user data from replaceable federation/cache data;
|
||
- test both the new behavior and migration-sensitive queries;
|
||
- never solve a schema problem by deleting or recreating a user's database.
|
||
|
||
Content identifiers are the bridge between independent libraries. Avoid
|
||
assuming that local numeric row IDs identify the same track on another node.
|
||
|
||
## Federation and wire protocols
|
||
|
||
Discovery and transfer are separate concerns:
|
||
|
||
- the DHT provides distributed discovery;
|
||
- peer catalog streams provide richer metadata;
|
||
- audio streams transfer content;
|
||
- the device-sync protocol replicates trusted personal state.
|
||
|
||
Treat protocol and serialized-data changes as compatibility changes:
|
||
|
||
- preserve existing ALPN values unless intentionally introducing a new
|
||
protocol version;
|
||
- retain backward-compatible `serde` defaults for fields added to wire types;
|
||
- tolerate peers with older or partial metadata;
|
||
- bound incoming messages and validate untrusted lengths/identifiers;
|
||
- keep catalog/federation authority separate from trusted-device authority;
|
||
- assume peers can disappear between discovery and transfer;
|
||
- keep retries and fallback sources idempotent.
|
||
|
||
Do not introduce a required coordinator, registry, account server, or canonical
|
||
network database.
|
||
|
||
## Trusted-device synchronization
|
||
|
||
Device sync is offline-first. Operations may arrive late, more than once, or
|
||
in a different order.
|
||
|
||
When changing it:
|
||
|
||
- preserve operation-ID deduplication;
|
||
- use the existing hybrid logical time ordering rules consistently;
|
||
- ensure deletes survive offline replicas through tombstones;
|
||
- compact tombstones only after the required acknowledgements;
|
||
- keep snapshots able to repair peers that missed older operations;
|
||
- treat membership and revocation as replicated durable state;
|
||
- keep playback commands targeted and deduplicated;
|
||
- test merge behavior from at least two operation orders;
|
||
- never store this build's protocol version for another device: use the
|
||
device's own report (`profile_protocol_version`) and only raise a stored
|
||
version from relayed profiles (`relayed_protocol_version`);
|
||
- gate everything a peer cannot parse by the version it reported: podcast
|
||
operations, podcast snapshot sections and playback state with podcast items
|
||
go only to v4 peers (`op_allowed_for_peer`, `SyncSnapshot::for_peer`,
|
||
`playback_allowed_for_peer`), a podcast queue is never handed to an older
|
||
device and its playback commands are ignored while the queue has episodes;
|
||
never strip episodes from a queue to make it fit an old peer; an older
|
||
peer still gets the playback coordination, with the queue redacted
|
||
(`redact_for_jam`), so its engine does not fail over;
|
||
- apply podcast operations and snapshot sections only through
|
||
`PodcastStore` (`apply_remote_op`, `apply_snapshot`); never call the
|
||
podcast store while holding the sync-log connection;
|
||
- keep Jam snapshots redacted (`redact_for_jam`) and map guest placeholders
|
||
back with `restore_jam_private_items`.
|
||
|
||
Do not replace eventual reconciliation with assumptions about a continuously
|
||
connected leader.
|
||
|
||
## Playback and remote resolution
|
||
|
||
The application owns the logical queue; `player::Controller` owns physical
|
||
audio playback.
|
||
|
||
Remote and local tracks should continue through the same queue and UI model.
|
||
When a track is unavailable locally, resolve it asynchronously and replace or
|
||
materialize the pending entry without blocking the event loop.
|
||
|
||
Preserve:
|
||
|
||
- queue position and prefetch indexes when inserting or removing tracks;
|
||
- shuffle/repeat behavior;
|
||
- pause and seek state during device handoff;
|
||
- fallback to another advertised source when a peer disappears;
|
||
- the distinction between cached audio and content imported into the durable
|
||
library.
|
||
|
||
## UI and key bindings
|
||
|
||
The TUI is keyboard-first and cross-platform.
|
||
|
||
- Keep rendering pure over `&AppState`.
|
||
- Use semantic `Action` values rather than checking raw keys inside views.
|
||
- Add default bindings in `src/config/default_keymap.toml`.
|
||
- Preserve user overrides and context-specific bindings.
|
||
- Tabs are ordered Library, Playlists, Queue, Podcasts, Settings, Logs
|
||
(`1`–`6`). `Tab::ALL` defines that order for the tab bar, Tab/Shift+Tab,
|
||
and `GoToTab` indices. Changing it, or the meaning of any other
|
||
positional action argument, requires a new `KEYMAP_VERSION` and an
|
||
in-memory migration of older keymap files; never rewrite the user's file.
|
||
- Account for narrow terminals, Unicode display width, and empty/loading/error
|
||
states.
|
||
- Restore raw mode, alternate screen, bracketed paste, and keyboard
|
||
enhancements on exit and panic.
|
||
|
||
Do not print to stdout/stderr while the alternate-screen UI is active; use
|
||
`tracing` and visible application status instead.
|
||
|
||
## Cross-platform work
|
||
|
||
Furumi supports Linux, macOS, and Windows.
|
||
|
||
- Keep OS-specific code behind narrow `cfg` boundaries.
|
||
- Do not introduce shell-only behavior into portable paths.
|
||
- Use platform data/config/cache directories through the existing config
|
||
helpers.
|
||
- Consider path encoding, separators, and non-UTF-8 filesystem values.
|
||
- Changes to media controls, terminal setup, clipboard behavior, or audio
|
||
devices require explicit review of all three platforms.
|
||
|
||
If only one target can be exercised locally, state which platform-specific
|
||
paths remain unverified.
|
||
|
||
## Tests
|
||
|
||
Add tests at the closest stable boundary:
|
||
|
||
- pure state transitions in `app/update_tests.rs`;
|
||
- SQLite behavior and migrations in `library/tests.rs`;
|
||
- operation merge, tombstone, membership, and playback sync behavior in
|
||
`devices/tests.rs`; podcast sync between device stores and simulated v3
|
||
peers in `devices/podcast_sync_tests.rs`; wire shapes in
|
||
`devices/wire_compat_tests.rs`;
|
||
- search/ranking/federation conversion in `federation/tests.rs`;
|
||
- protocol-specific tests beside `federation/audio.rs` or
|
||
`federation/catalog.rs` when appropriate.
|
||
|
||
Prefer in-memory SQLite databases and deterministic fixtures. Temporary files
|
||
must use unique names and must not depend on a developer's music library,
|
||
configuration, home directory, network peers, or audio hardware.
|
||
|
||
Do not remove a test merely because a refactor makes it inconvenient. Update
|
||
it to assert the preserved behavior.
|
||
|
||
## Documentation and releases
|
||
|
||
Keep public documentation aligned with the decentralized product model.
|
||
README content should explain user value and setup; `ARCHITECTURE.md` should
|
||
explain architectural decisions and invariants rather than restating source
|
||
code.
|
||
|
||
Release archives are produced by `.github/workflows/release.yml` and must
|
||
include the binary, `README.md`, and `LICENSE`.
|
||
|
||
The project is licensed under WTFPL version 2.
|