crabidy/quality/orphans.md

Quality gates — the orphans provider

Gates for architecture/orphans.md and the crabidy-server/src/orphans.rs stub. Each is pass/fail by reading/reasoning or by a named test. Tests live in crabidy-server/src/crabidy_store.rs (the store methods) and crabidy-server/src/orphans.rs (the provider), run via devenv shell -- cargo test -p crabidy-server.

Correctness of the orphan diff

• G1 — All items enumerated. list_orphans counts every store entry that has both a <name>.cbd-store.toml sidecar and a readable <name> audio file. Test: capture two distinct tracks (two store entries), reference neither → both listed.
• G2 — Referenced entries excluded. An entry referenced by a Playable::Store toml under any ref_root is not listed. Test: capture one track into a /crabidy save (which writes a store toml), then list_orphans with that tree as a ref root → the entry is not an orphan; delete the save's toml → it becomes an orphan.
• G3 — /fs references count. A Playable::Store toml under the /fs root (as scan --capture writes) excludes its target. Test: hand-write a store toml under an fs ref root → its target is not an orphan.
• G4 — References outside ref roots do not count. A store toml under a directory that is not a ref root does not rescue its target from being an orphan (documented boundary). Test asserts the target is still listed.
• G5 — Malformed residue is reclaimable. A sidecar with no audio (or audio with no sidecar) is reported as an orphan, never as "referenced". Test: drop a lone x.cbd-store.toml into the store → listed.
• G6 — Fresh every call. No persisted orphan list; two consecutive list_orphans calls straddling a reference change reflect the change (covered by G2's two-phase assertion).

Presentation contract (reuse, no new wire)

• G7 — Child capability flags. Every /orphans child advertises is_queable, is_editable, is_deletable, and is_captured all true, and is_downloadable = false. The root is is_queable = true, is_creatable = false. Verified by reading get_lib_node; test asserts the flags on a listed child.
• G8 — Leaf carries exactly one track. get_lib_node("/orphans/<seg>") returns a childless, queueable node with one track whose is_captured is true and whose metadata matches the sidecar. Test asserts tracks.len() == 1 and children.is_empty().
• G9 — Queueing resolves the audio. Resolving an orphan node (default walk) yields one track whose get_urls_for_track returns store_root/<name>. Test drives resolve_tracks_into("/orphans") and checks the resolved URL is the store path.
• G10 — No proto/TUI/web change. Confirm by inspection that the feature adds no field to any proto message and no binding/gesture to cbd-tui or cbd-web: it relies solely on existing is_editable/is_deletable/ is_queable handling. (If this gate cannot hold, the design in architecture/orphans.md must be revisited before implementing.)

Rename safety

• G11 — Renames both files. rename_orphan(old, new) renames the audio <old>→<new> and <old>.cbd-store.toml→<new>.cbd-store.toml; neither old name remains on disk. Test.
• G12 — Rename updates the index. After a rename, the index resolves the same content hash / provider ids to the new name and no longer to the old (so a subsequent capture de-dups against the renamed entry). Test via StoreIndex lookups or a follow-up capture.
• G13 — Rename validates and refuses collisions. An empty / separator / leading-dot new is rejected (InvalidInput); a new already taken by another store audio or sidecar is refused without touching disk. Tests for both.
• G14 — Rename is reference-safe by construction. Only unreferenced entries are exposed under /orphans, so a rename never invalidates a live toml. Verified by reasoning against the diff definition; no test needed beyond G2.

Delete safety

• G15 — Deletes both files. delete_orphan(name) removes the audio and the sidecar and drops the entry from the index. Test asserts both files gone and list_orphans no longer lists it.
• G16 — Idempotent. Deleting an already-gone entry returns Ok (a refreshed root), not an error. Test.
• G17 — Delete stays inside the store root. The name is a validated bare file name; delete joins it onto store_root and never follows separators or ... Verified by reasoning (mirrors Playable::Store bare-name validation) plus a test that a crafted /orphans/..%2Fx path is MalformedPath, not a file operation.

Always-on rules (AGENTS.md)

• G18 — No panics on input or I/O. Every error path (missing entry, unreadable dir, bad toml, taken rename target, malformed path) is a typed ProviderError/StoreError; no unwrap/expect/panic!/todo! remains in shipped code. A bad sidecar or track toml during the walk is skipped with a warning, never fatal (mirrors StoreIndex::scan and fsdy listing).
• G19 — Bounded work, no unbounded channels. The reference walk and enumeration use ordinary async fs iteration; if any channel is introduced it is bounded. No new external calls (so no timeout/retry surface is added).
• G20 — Public items documented. Every public item in orphans.rs and every new public CrabidyStore/fsdy::Client method has a doc comment stating intent and error behavior.
• G21 — Mount is optional and non-fatal. /orphans mounts only when the store is present; its absence (no data/state dir) drops the subtree without affecting the server, exactly like /crabidy and /fs. get_lib_root includes the orphans child only when mounted. Verified by reading the orchestrator wiring.