chore(scripts): add concurrency_audit.sh — Phase 10a baseline tool

[githubrobbi]

Summary

Phase 10a of the playbook Phase-10 effort (issue #302). Adds scripts/dev/concurrency_audit.sh — the workspace concurrency / async / shared-state baseline tool. Mirrors the shape of scripts/dev/build_codegen_audit.sh (Phase 9a).

What it does

Walks every workspace member and emits, per crate, the 7-dimension async/concurrency inventory called out by playbook §1082-1146 and Phase 10 plan §7:

1. tokio::spawn / detached tasks — every call-site for Phase-10c hand-audit.
2. Locks held across .await — literal .read/.write/.lock().await sites for Phase-10b hand-audit.
3. Blocking IO inside async — files containing both async fn AND std::fs::* / std::thread::sleep (Phase-10f candidates).
4. Arc<Mutex<…>> patterns — flat + multi-layer nesting (Arc<Mutex<Arc<…>>> separately flagged).
5. Missing timeouts — IO/network/IPC await sites (.connect/.read_exact/.write_all/.recv/.accept/...) that need a tokio::time::timeout enclosure.
6. Missing cancellation handling — spawn sites whose closure body (next 50 lines) lacks select! / CancellationToken / .cancelled() keywords.
7. Unbounded channels — every unbounded_channel() / broadcast::channel(...) site for Phase-10d backpressure audit.

Default mode runs in ~6 s (pure rg + awk; no cargo invocation). --with-cargo mode also runs cargo build --workspace --tests + cargo clippy --workspace --tests -- -W clippy::await_holding_lock as a Phase-10b enforcement-mode preview.

Baseline at this SHA (prod-only)

Dimension	Count	Phase that consumes it
async fn + async blocks	278	(info)
tokio::spawn( call sites	27	10c
spawn_blocking call sites	53	10f (verification)
std::sync::Mutex/RwLock	22	(info)
tokio::sync::* async locks	6	10b
Arc<Mutex<…>> / Arc<RwLock<…>>	1	(info — flat, no smell)
Bounded channels	5	(info)
Unbounded channels	4	10d
tokio::time::timeout( sites	10	10e
Lock-across-await candidate sites	36	10b (primary target)
Blocking-IO-in-async candidate files	14	10f
Spawn sites lacking nearby cancellation kw	24	10c
#[tokio::test] sites (test code)	127	(info)

The headline finding is 36 lock-across-await candidate sites in uffs-daemon (34) + uffs-mcp (2) — significantly more than the initial 7-site estimate in the plan recon. Each will be hand-audited in Phase 10b for "guard held across an inner .await" (the hazard) vs "guard acquired with .await and dropped before the next .await" (legitimate).

Detection caveats (documented in the script preamble + per-helper comments)

• Lock-across-await uses literal regex. Multi-line guard-then-await patterns (let g = lock(); g.foo(); other.await; drop(g);) require Phase-10b hand-audit to confirm.
• Cancellation-keyword regex uses word boundaries. Bare cancel would match cancel_tx false-positively; we require CancellationToken / cancellation_token / .cancelled() / is_cancelled / select! / abort_signal / recv_cancel.
• Arc<Mutex<…>> output filters doc-comment lines. Rustdoc prose referencing the pattern doesn't inflate the count.
• Counter uses grep -c '^.' (not grep -c .) so echo '' doesn't falsely count as 1 (this was caught + fixed during the script's own smoke-test).
• Glob excludes use !**/tests/** (not bare !tests/**) — UFFS has in-tree test modules under src/.../tests/ which the bare pattern would not exclude.

Why this is Phase 10a (audit-tool first)

Mirroring the established Phase 6a / 7a / 8a / 9a cadence:

1. Build the audit tool first.
2. Run it to capture the precise baseline (output saved locally to docs/dev/baseline/2026-05-19/phase_10_concurrency_baseline.md).
3. Use the baseline numbers to seed the per-sub-phase hand-audits (10b lock-across-await, 10c task ownership, 10d backpressure, 10e timeout coverage, 10f blocking IO).
4. Phase 10g consumes all hand-audit outputs into concurrency_policy.md + per-crate # Concurrency rustdoc.

Rule-1 adherence

Zero #[allow] introductions. Script-level set -uo pipefail (matches sibling audit scripts). One # shellcheck-info-level note (SC2016 — 'single quotes don't expand') is intentional: the affected lines emit Markdown backticks literally, not shell variables.

Cross-references

• Issue: [playbook-phase-10] Async, concurrency, and shared state discipline #302
• Plan (local): docs/dev/architecture/code_clean/phase_10_async_concurrency_shared_state_implementation_plan.md
• Sibling audit scripts: scripts/dev/build_codegen_audit.sh (Phase 9a — same shape), scripts/dev/feature_dep_audit.sh (Phase 8a), scripts/dev/trait_generic_audit.sh (Phase 7a), scripts/dev/clone_alloc_audit.sh (Phase 6a).
• Playbook source: world_class_rust_workspace_refactor_playbook.md §1082-1146 (local-only).

Verification

• bash -n scripts/dev/concurrency_audit.sh → SYNTAX OK
• shellcheck scripts/dev/concurrency_audit.sh → only SC2016 info (intentional, see above)
• scripts/dev/concurrency_audit.sh > /tmp/baseline.md → 316-line Markdown report in ~6 s
• All 12 pre-push gates green (file-size, typos, reuse, cargo-check, lint-ci, lint-ci-no-default, lint-prod, lint-tests, rustdoc, doc-tests, tests, smoke, lint-ci-windows).

Next steps (queued)

• 10b — hand-audit the 36 lock-across-await candidate sites.
• 10c — hand-audit the 24 spawn-sites-without-cancellation-keywords.
• 10d — justify or convert the 4 unbounded channels.
• 10e — timeout coverage map.
• 10f — blocking-IO-in-async hand-audit (14 candidate files).
• 10g — concurrency_policy.md + per-crate # Concurrency rustdoc.
• 10h — CONTRIBUTING cross-link + final report + close [playbook-phase-10] Async, concurrency, and shared state discipline #302.