[playbook-phase-7] Traits, generics, and dispatch discipline

[githubrobbi]

Playbook section: docs/dev/architecture/code_clean/world_class_rust_workspace_refactor_playbook.md § Phase 7.

Baseline anchor: Phase-0 final report docs/dev/baseline/2026-05-12/phase_0_final_report.md (local-only per .gitignore:135). Workspace commit at baseline: 710ca6044 (cast-cleanup, PR #186).

Goals (from playbook)

Audit generic dispatch + SIMD specialization paths. Decide between dyn-trait vs generic vs match-based dispatch where it's currently inconsistent.

Current state (from Phase-0 baseline § 7 entry-point map)

Estimated cost: 2-3 days

Recommended entry points: uffs-core search engine dispatch · uffs-text case-fold + trigram-key SIMD

Acceptance criteria

• Read playbook § Phase 7 Check / Refactor / Validate subsections
• Open a tracking branch (refactor/phase-7-...) and a draft PR
• Land work in surgical commits — preserve behavior and contracts (workspace rules: no suppression hacks, no relaxing tests, signed commits)
• Update tests where the refactor changes invariants
• Re-run just baseline-snapshot after merge and compare deltas against docs/dev/baseline/2026-05-12/
• Close this issue with a one-line summary of the LOC / API / risk-marker delta

Workspace policy reminders

1. No suppression hacks (#[allow] blankets, disabled lints, commented-out tests, cfg(any()) hiding)
2. Surgical correct fixes (root cause, not workaround)
3. Preserve behavior & contracts (public API stable unless CI proves it wrong)
4. Improve tests, do not dodge them

[githubrobbi]

Phase 7 closeout — Traits, generics, and dispatch discipline

Closes via PRs #288 / #289 / #290 / #291 (all merged 2026-05-19), with two post-closeout decisions-log backfills (#296 / #297).

Starting SHA: d2d533021 (post-PR #286, Phase 6 closeout).
Closing SHA: 33f22b572 (post-PR #289 — final Phase-7 PR).
Wall-clock: 2026-05-19 (single-day execution).

Delta summary

The audit at SHA d2d533021 found the workspace already textbook-clean by construction against the playbook §858-924 contract:

• 0 of 127 generic-fn sites required refactoring (all G1/G2 — local or zero-overhead).
• 0 of 40 true dyn-dispatch sites required refactoring (all D1/D2 — plugin or closed-set).
• 1 of 13 prod traits was a demotion candidate (DirCacheExt — single call site per impl).

Phase 7 therefore landed as 1 refactor + 1 script + 2 documentation PRs + 4 new lints:

PR	Sub-phase	What
#288	7a	scripts/dev/trait_generic_audit.sh — 532-LOC baseline inventory tool
#289	7b	DirCacheExt demoted to free fn dir_cache_with_capacity (−1 pub(crate) trait, behavior preserved bit-for-bit)
#290	7g	docs/architecture/code-quality/trait_policy.md (194 LOC) + CONTRIBUTING.md §"Trait, generic, and dispatch policy" (17 LOC)
#291	7f	4 new [workspace.lints.clippy] entries at deny/warn
#296	8e	Backfilled trait_policy.md:193 decisions-log TBD → #291
#297	8e	Backfilled trait_policy.md:194 decisions-log this PR → #290

What changed

• crates/uffs-core/src/search/tree.rs — DirCacheExt trait + impl deleted (15 LOC); free fn dir_cache_with_capacity added (14 LOC). 7 call sites across 4 files updated; 4 use … DirCacheExt as _; imports removed. Generated machine code unchanged.
• Cargo.toml [workspace.lints.clippy] — 4 new lints: too_many_arguments = "deny", trait_duplication_in_bounds = "deny", wrong_self_convention = "deny", multiple_bound_locations = "warn". 0 relaxations. 19 pre-existing #[expect(too_many_arguments)] annotations continue to satisfy the deny gate.
• docs/architecture/code-quality/trait_policy.md — 194-LOC policy doc: J1-J4/G1-G5/D1-D4/S1-S3 taxonomies, per-trait registry (12 KEEP + 1 demoted), seal/open decision tree, anti-patterns, audit cadence, decisions log.
• CONTRIBUTING.md — 17-LOC §"Trait, generic, and dispatch policy" + link.

What didn't change

• Zero API changes — public surface of all 14 crates preserved bit-for-bit.
• Zero new #[allow(…)] or #[expect(…)] annotations introduced (4 new lints produced 0 new diagnostics workspace-wide).
• Zero deny.toml / Cargo.lock / Cargo.toml content changes.

Verification highlights

• cargo clippy --workspace --all-targets --no-deps -- -D warnings — 0 diagnostics across all 4 new lints.
• cargo nextest run --workspace — 1,833 / 1,833 tests preserved (no regression from Phase 6).
• Pre-push gate green on every PR: chore(scripts): add trait_generic_audit.sh — Phase 7a baseline tool (refs #287) #288 (69 s), refactor(uffs-core): demote DirCacheExt to free fn dir_cache_with_capacity (Phase 7b, refs #287) #289 (94 s), docs(architecture): add trait_policy.md and CONTRIBUTING.md cross-link (Phase 7g, refs #287) #290 (4 s, docs-only fast path), chore(lints): activate 4 Phase-7 trait/generic/dispatch lints (Phase 7f, refs #287) #291 (163 s).

Wall-clock

Sub-phase	Plan	Actual
7a — Baseline tool	~30 min	~25 min
7b — Trait justification + 1 demotion	~1.5–2 h	~50 min
7c–7e — Generic / dispatch / sealing audits	~2.5–4 h	~50 min total
7f — Bound rationalization (4 new lints)	~1–2 h	~15 min
7g — trait_policy.md + CONTRIBUTING	~45 min	~30 min
7h/7i — Bench refresh + closeout	~1.5 h	~35 min
Total	~7–10 h	~3–3.5 h

Follow-ups (out of Phase 7 scope)

1. Windows mft_read + search_benchmarks bench refresh — reproducible recipe in phase_7_bench_delta.md.
2. Add one-line rustdoc on RuntimeDir documenting its structural-sealing reality.
3. Annual workspace-wide trait/generic audit re-run per trait_policy.md §9.

Full report (local-only, gitignored): docs/dev/baseline/2026-05-19/phase_7_final_report.md.