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

[githubrobbi]

Phase 7 of the workspace refactor playbook.

Playbook section: docs/dev/architecture/code_clean/world_class_rust_workspace_refactor_playbook.md §858-924 (local-only).
Plan: docs/dev/architecture/code_clean/phase_7_traits_generics_dispatch_implementation_plan.md (local-only — gitignored under /docs/dev/).
Predecessor: #193 (Phase 6 — ownership/borrowing/allocation, CLOSED 2026-05-19).

Sub-phases (per plan §5)

• 7a — Baseline tool: scripts/dev/trait_generic_audit.sh + prod-only inventory snapshot
• 7b — Trait justification audit (J1/J2/J3/J4 per playbook §879-886)
• 7c — Generic-function audit (G1-G5 per plan §3.2)
• 7d — Dispatch audit (D1-D4 + S1-S3 per plan §3.3)
• 7e — Trait sealing decisions (per playbook §902-904, carrying forward Phase 3b §3.7)
• 7f — Bound rationalization: add clippy::trait_duplication_in_bounds, wrong_self_convention, too_many_arguments denies + multiple_bound_locations warn
• 7g — docs/architecture/code-quality/trait_policy.md + CONTRIBUTING.md cross-link
• 7h — Benchmark + cargo build --timings refresh
• 7i — Final validation + closeout report

Acceptance criteria (plan §7)

15 criteria — every prod trait classified, every generic fn classified, every dyn site classified, trait_policy.md landed, strict-lint posture extended without relaxations, benchmarks within envelope, plan §11 filled in.

Strict rules (carry-overs from Phase 5 / 6)

1. No suppression hacks (no blanket #[allow], no #![expect] workarounds)
2. Surgical, correct fixes (minimal idiomatic Rust)
3. Preserve behavior & contracts (no public-API breakage without feat: prefix)
4. Improve tests, do not dodge them (no skipped/relaxed tests)
5. Small, atomic, signed commits with clear messages

Starting SHA

d2d533021 (post-PR #286, Phase 6 closeout — current main).

[githubrobbi]

Phase 7 — Traits, generics, and dispatch discipline — CLOSED 2026-05-19

Outcome

Metric	Before	After	Delta
Prod pub traits	3	3	unchanged
Prod pub(crate) traits	10	9	−1 (DirCacheExt demoted)
Prod generic fns	127	127	unchanged (all G1/G2/G5 by construction)
True dyn dispatch sites	40	40	unchanged (all D1-PLUGIN / D2-HETERO)
Workspace where clauses	192	192	unchanged
Workspace trait/generic/dispatch lints at deny	1	4	+3
Workspace trait/generic/dispatch lints at warn	0	1	+1
Workspace policy docs	2 (panic + allocation)	3 (+ trait)	+1

Public API delta: zero. Behavior preserved bit-for-bit (the single demotion was a non-virtual associated-fn → free-fn rewrite with identical monomorphized machine code).

PRs

PR	Phase	Title	Merged
#288	7a	chore(scripts): add trait_generic_audit.sh — Phase 7a baseline tool	2026-05-19T16:58:45Z
#289	7b	refactor(uffs-core): demote DirCacheExt to free fn dir_cache_with_capacity	2026-05-19T17:51:19Z
#290	7g	docs(architecture): add trait_policy.md and CONTRIBUTING.md cross-link	2026-05-19
#291	7f	chore(lints): activate 4 Phase-7 trait/generic/dispatch lints	2026-05-19T17:31:17Z

Wall-clock

~3-3.5 h actual vs 7-10 h planned — same pattern as Phase 5 / Phase 6. Strict-clippy pre-validated 80%+ of the audit surface.

Acceptance scorecard

15 / 15 criteria green. Full report: docs/dev/baseline/2026-05-19/phase_7_final_report.md (local-only). Plan §11 closeout populated in docs/dev/architecture/code_clean/phase_7_traits_generics_dispatch_implementation_plan.md.

Local-only findings

• phase_7_trait_generic_baseline.md (7a inventory)
• phase_7_trait_justification_findings.md (7b — 13 traits classified, 1 demoted)
• phase_7_generic_audit_findings.md (7c — 127 sites; zero G3 / G4)
• phase_7_dispatch_findings.md (7d — 40 true sites; zero D3 / D4 / S2)
• phase_7_sealing_findings.md (7e — all 3 pub traits OPEN; RuntimeDir structurally sealed)
• phase_7_bench_delta.md (7h — macOS query bench within envelope; compile-time 7-crate chain 15.36 s)
• phase_7_final_report.md (7i — closeout)

Strict-lint posture (after Phase 7)

Cargo.toml [workspace.lints.clippy] — 5 active trait/generic/dispatch lints:

• type_complexity = "deny" (Phase 6 carryover)
• too_many_arguments = "deny" (Phase 7f)
• trait_duplication_in_bounds = "deny" (Phase 7f)
• wrong_self_convention = "deny" (Phase 7f)
• multiple_bound_locations = "warn" (Phase 7f)

Zero workspace-wide diagnostics. Zero relaxations. Pre-existing 19 #[expect(too_many_arguments)] annotations across uffs-cli/core/daemon/mft carry forward unchanged.

Follow-ups (out of Phase-7 scope)

1. Run Windows mft_read + search_benchmarks bench (15 min reproducible recipe in phase_7_bench_delta.md).
2. Optional one-line rustdoc note on RuntimeDir documenting the structural seal.
3. Annual workspace audit re-run per trait_policy.md §9.
4. Phase 8 — Feature flags and dependency hygiene (playbook §926-1004).