refactor(uffs-core): demote DirCacheExt to free fn dir_cache_with_capacity (Phase 7b, refs #287)#289
Merged
Merged
Conversation
…acity (Phase 7b, refs #287) `DirCacheExt` was a single-method `pub(crate)` extension trait providing `with_capacity(n) -> Self` over the `DirCache = FxHashMap<u32, String>` type alias. Per the Phase 7 trait-justification audit (playbook §879-886 J1/J2/J3/J4), it satisfied none of the four criteria: * J1 multiple impls: ❌ 1 impl (for `DirCache` only) * J2 test substitution: ❌ no test fakes * J3 extension surface: ❌ `pub(crate)`, no rustdoc claim * J4 high-level/infra decoupling: ❌ single-method ergonomic constructor The trait forced every caller to write `use … DirCacheExt as _;` just to spell `DirCache::with_capacity(n)`, and the indirection made the call site easy to misread as an inherent method on `DirCache`. This refactor replaces the trait with a free `pub(crate) fn dir_cache_with_capacity(capacity: usize) -> DirCache` and updates the 7 call sites across 4 files in `uffs-core::search::query`. Behavior preserved bit-for-bit: the new function body is the same `FxHashMap::with_capacity_and_hasher(n, FxBuildHasher)` expression that the trait impl had. API impact: zero (trait + impl were `pub(crate)`). Verification: * `cargo check -p uffs-core` — clean * `cargo clippy -p uffs-core --all-targets -- -D warnings` — clean * `cargo nextest run -p uffs-core` — 817/817 passing (3 skipped) Findings doc (local-only): docs/dev/baseline/2026-05-19/phase_7_trait_justification_findings.md records all 13 prod traits classified J1-J4; `DirCacheExt` is the only demotion. The 12 other traits (9 `uffs-daemon::cache` hooks + `FileReader` + `FormatRow` + `RuntimeDir`) are confirmed KEEP under J1 / J2 / J3. Refs: #287
This was referenced May 19, 2026
Merged
This was referenced May 19, 2026
githubrobbi
added a commit
that referenced
this pull request
May 19, 2026
The Phase 7g decisions-log row in `trait_policy.md:194` read 'this PR' at the time of authoring (when PR #290 was open). After PR #290 merged the placeholder needed backfilling to '#290' to match the surrounding rows (#288/#289/#291). Companion to Phase 8e (PR #296), which already backfilled the sibling 'TBD' placeholder on row 193 (Phase 7f -> #291). This 1-line edit completes the decisions-log hygiene pass for Phase 7.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 7b — the only trait demotion from the Phase 7 justification audit (issue #287).
Background
The Phase 7 trait justification audit classified 13 prod traits against the playbook §879-886 J1/J2/J3/J4 taxonomy:
FileReader,FormatRow,RuntimeDir,JournalSource, plus 9uffs-daemon::cachelifecycle hooks (BodyLoader,CacheCleaner,PatchSink,CursorStore,Prefetch,PressureSignal,WorkingSetTrim,BackgroundIoPriority).DirCacheExt.The demotion
DirCacheExtwas a single-methodpub(crate)extension trait providingwith_capacity(n) -> Selfover theDirCache = FxHashMap<u32, String>type alias. It satisfied none of the four justification criteria:DirCacheonly)pub(crate); rustdoc claims no extensibilityThe trait forced every caller to write
use … DirCacheExt as _;just to spellDirCache::with_capacity(n), and the indirection made the call site easy to misread as an inherent method on theDirCachetype alias (which is not legal — type aliases cannot have inherent methods).What changed
crates/uffs-core/src/search/tree.rs: deleted the trait + impl (15 LOC); added a freepub(crate) fn dir_cache_with_capacity(capacity: usize) -> DirCachewith the same body (FxHashMap::with_capacity_and_hasher(n, FxBuildHasher)). Doc-comment documents the playbook §879-886 rationale inline.crates/uffs-core/src/search/query/mod.rs: droppedDirCacheExt as _from theuseline; switched 2 call sites.crates/uffs-core/src/search/query/numeric_top_n.rs: same — 1 call site.crates/uffs-core/src/search/query/path_only_top_n.rs: same — 2 call sites.crates/uffs-core/src/search/query/path_sorted_top_n.rs: same — 2 call sites.Behavior preserved bit-for-bit; the function body is the exact same expression the trait impl had.
API impact
Zero.
DirCacheExtwaspub(crate); no external code could reference it.Verification
cargo check -p uffs-core— ✅ cleancargo clippy -p uffs-core --all-targets -- -D warnings— ✅ cleancargo nextest run -p uffs-core— ✅ 817/817 passing, 3 skipped (2.7 s)lint-pre-push) — ✅ green (94 s)3628BD817A687030E83025A8E406D32B4736D09FDiff summary
Findings doc (local-only, gitignored)
docs/dev/baseline/2026-05-19/phase_7_trait_justification_findings.mdrecords every J1-J4 verdict for all 13 prod traits, with full per-trait justification text.Next: 7c — generic-function audit (129 prod-path
fn<…>sites).Refs: #287