crabidy/quality/fs-provider.md

Quality gates: fs-provider

Criteria the implementation must satisfy beyond the automated tests in fsdy/src/lib.rs. Check each by reading the code and reasoning; tick only when verified.

Robustness (hard rules)

• No code path panics on the contents of the tree: unreadable files, invalid TOML, invalid UTF-8 file names, symlink cycles, and permission errors all end in a typed error or a warn-and-skip — no unwrap/ expect/panic!/indexing on tree- or client-derived data outside tests.
• Client-supplied paths cannot address anything outside the configured root: every decoded segment is validated (., .., empty, separator) before joining, in one place that all lookups go through.
• All provider I/O is tokio::fs — no std::fs outside #[cfg(test)] (nothing blocks the runtime).
• Directory listing skips symlinks without following them (no cycle can hang the walk; the root cannot be escaped via links).

Contract fidelity

• A link playable rewrites Track.path to the target everywhere a Track is built (listing and metadata) — there is a single file-to-Track conversion both call.
• link targets pointing into /fs are rejected at parse time, so link chains are structurally impossible.
• get_urls_for_track returns plain file paths and http(s) URLs only — never file:// URLs (the player rejects unknown schemes).
• A broken track file is skipped with a warning that names the file and does not remove its siblings from the listing.
• create/rename/delete_lib_node return NotSupported; no fs mutation API sneaks in.
• resolve_tracks_into keeps the trait default (no override), and the listing order equals the resolve order (both come from the same sorted listing).

Orchestrator wiring

• Every ProviderClient method on ProviderOrchestrator routes /fs and /fs/... to the fs client, mirroring the /tidal arms (including is_track_path and resolve_tracks_into).
• fs init failure is non-fatal: the server starts, logs a warning, and /fs is absent from the root listing; no /fs-routing arm can panic when the client is absent.
• The fsdy.toml config is written back with effective defaults on first run, like tidaly.toml.

Hygiene

• Every public item in fsdy has a doc comment stating intent and error behavior; the on-disk format is documented where the schema type is defined.
• Warnings/errors never include file contents (a track file may hold a private URL with a token) — log paths and error kinds, not bodies.
• cargo clippy is warning-free; cargo fmt, taplo, markdownlint clean; no todo!()/unimplemented!() remains.
• The whole workspace test suite passes, not just fsdy.