S273: update root docs, handoff, clean debris for primalSpring audit

Update all root docs (README, CONTEXT, DOCUMENTATION, NEXT_STEPS) and
secondary docs (sporeprint, docs/README, TESTING, .env.example) to S273
metrics: 9,131+ lib tests, 88 JSON-RPC methods, 47 crates, 700 cylinder
tests, zero production panics.

Create S273 handoff documenting deep debt evolution pass: panic surface
elimination, dispatch/sovereign.rs extraction, warm_init module split,
CLI capability-based discovery, activity_tracker wiring, hw-safe validation.

Clean debris: remove orphan crates/barracuda/ (last budding remnant, not
in workspace), remove stale squirrel_mcp_coordination_demo.rs stub, fix
barracuda::ops reference in pending test README.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: BiomeOS Developer

.env.example

@@ -1,5 +1,5 @@
 # ToadStool Environment Configuration
-# Updated: S266 (May 20, 2026)
+# Updated: S273 (May 24, 2026)
 #
 # All values have sensible defaults. Only override what you need.
 # Copy this file to .env and customize for your environment.

CONTEXT.md

@@ -30,9 +30,9 @@ ToadStool is the **Layer 0** hardware substrate that other primals and springs d
   - Family: `compute-{family_id}.sock` / `compute-{family_id}-tarpc.sock`
 - **Peer primals**: Resolved at runtime via capability IDs and Unix-socket discovery (e.g. `capability.discover`, `resolve_capability_socket_fallback`) — not hardcoded URLs or legacy per-primal env manifests
 - **Discovery hierarchy** (primalSpring cross-cutting): Songbird `ipc.resolve` → biomeOS `capability.discover` → UDS filesystem convention → socket registry → TCP probing. toadStool implements tiers 1–4; TCP probing (tier 5) not used for local IPC
-- **Wave 8 Compute Trio** (S235–S263): `compute.dispatch.submit` trio-standard IPC contract. Phase A–D complete. NV VFIO e2e dispatch validated on Titan V (S263). **87 JSON-RPC methods.**
-- **Deep Debt** (S240–S266): All Duration literals → named constants. Zero production mocks/TODO/FIXME/unreachable!(). All unsafe SAFETY-documented. All `#[allow]`/`#[expect]` have `reason`. `cargo deny check bans` clean. Stale socket hygiene (S264). sporePrint Wave 28 (S265). Sandbox `working_dir` production + `data_dependencies` validation (S266).
-- **Tests**: 23,000+ (9,122+ lib-only, 0 failures, unlimited parallelism)
+- **Wave 8 Compute Trio** (S235–S263): `compute.dispatch.submit` trio-standard IPC contract. Phase A–D complete. NV VFIO e2e dispatch validated on Titan V (S263). **88 JSON-RPC methods.**
+- **Deep Debt** (S240–S273): All Duration literals → named constants. Zero production mocks/TODO/FIXME/unreachable!(). All unsafe SAFETY-documented. All `#[allow]`/`#[expect]` have `reason`. `cargo deny check bans` clean. Stale socket hygiene (S264). sporePrint Wave 28 (S265). Sandbox `working_dir` production + `data_dependencies` validation (S266). Kernel health preflight (S268). Sovereign driver rotation (S267). Production panic surface eliminated (S273). dispatch/sovereign.rs extraction (S273). warm_init module split (S273). CLI capability-based discovery migration (S273).
+- **Tests**: 23,000+ (9,131+ lib-only, 0 failures, unlimited parallelism)
 - **Unsafe**: 46 blocks (all in hw-safe/GPU/VFIO/display/plugin containment, all SAFETY-documented; reconciled S221); workspace `unsafe_code = "deny"`, 41 crates `forbid` + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`; all lint attrs have `reason =` (S211+S213)
 - **async-trait**: DEPRECATED — fully removed and banned in `deny.toml` (S203r); transitive only via axum/config/wiggle
 - **deny.toml**: `ring` + `async-trait` + `zstd-sys` + `aws-lc-sys` bans active (ecoBin v3 compliant, `SOVEREIGNTY_STANDARDS.md` dark forest gate). `ring` present only as conditional transitive dep via quinn-proto/rustls-webpki (not on default build path)

DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # ToadStool Documentation Hub
 
-**Last Updated**: May 2026 — S272
+**Last Updated**: May 2026 — S273
 
 ---
 
@@ -30,25 +30,26 @@ These root documents were **fully resolved** and **fossilized** in wateringHole
 
 ---
 
-## Current State (S272 — May 2026)
+## Current State (S273 — May 2026)
 
 **Post-budding, dependency-sovereign, IPC-first, fully concurrent, capability-based.** barraCuda is a separate primal at `ecoPrimals/barraCuda/`. ToadStool is the hardware infrastructure layer — GPU/NPU/CPU discovery, capability probing, workload orchestration, and shader dispatch.
 
 - **23,000+ tests** (9,131+ lib-only), 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite.
-- **87 JSON-RPC methods** (direct) + semantic registry. Wire Standard L3 (partial): `cost_estimates`, `operation_dependencies`. **Recommended caller timeout: ≥3 seconds** for health probes during startup.
-- **Phase C complete** (S245–S253) — toadstool-cylinder (153 .rs, 520 tests), DRM/MMIO/AMD/NVIDIA/VFIO hardware modules absorbed from `coral-driver`. `OwnedFd` VFIO fd ownership (S253). SwapOrchestrator real quiesce/persist/restore (S253). `toadstool device` CLI with swap/list/status/warm subcommands (S253). GspBridge trait boundary.
+- **88 JSON-RPC methods** (direct) + semantic registry. Wire Standard L3 (partial): `cost_estimates`, `operation_dependencies`. **Recommended caller timeout: ≥3 seconds** for health probes during startup.
+- **Phase C complete** (S245–S253) — toadstool-cylinder (153 .rs, 700 tests), DRM/MMIO/AMD/NVIDIA/VFIO hardware modules absorbed from `coral-driver`. `OwnedFd` VFIO fd ownership (S253). SwapOrchestrator real quiesce/persist/restore (S253). `toadstool device` CLI with swap/list/status/warm subcommands (S253). GspBridge trait boundary.
 - **Phase D: Sovereign dispatch validated** (S250–S263) — `try_local_dispatch()` via `ComputeDevice` trait before `coral_client` IPC forward. Full buffer lifecycle. AMD DRM dispatch live. **NV VFIO e2e dispatch validated on Titan V** (S263): warm handoff → VFIO open → channel → DMA roundtrip → GR init. Current frontier: FECS PENDING_CTX_RELOAD.
 - **Stale socket hygiene** (S264) — CLI daemon SIGTERM + socket cleanup. Display IPC Drop impl. UDS unlink-before-bind audited.
 - **sporePrint Wave 28** (S265) — `sporeprint/validation-summary.md` + CI dispatch to sporePrint.
 - **Neural API primal.announce wiring** (S270) — `primal.announce` wired into JSON-RPC dispatch, startup self-announcement to biomeOS Neural API with capabilities (compute, science, inference), cost hints, latency estimates, signal tier (node). 88 JSON-RPC methods.
 - **Sandbox working_dir production** (S269) — `data_dependencies` pre-dispatch validation with BLAKE3 integrity. `SandboxSpec.working_directory` wired into sandbox manager. 90+ upstream clippy errors absorbed.
-- **Deep Debt** (S240–S272) — All Duration literals extracted to named constants. `CORALREEF_*` env vars deprecated with `TOADSTOOL_*` primaries + deprecation warnings (S253). Zero `#[allow(deprecated)]` remaining. All lint attrs have `reason`. Zero production mocks/TODO/FIXME/unreachable!(). All unsafe SAFETY-documented. `cargo deny check bans` passes clean.
-- **Capability-based everywhere**: 0 hardcoded primal names, 0 production mocks, all primal references use capability identifiers. All production logging via `tracing`.
+- **Deep Debt** (S240–S273) — All Duration literals extracted to named constants. `CORALREEF_*` env vars deprecated with `TOADSTOOL_*` primaries + deprecation warnings (S253). Zero `#[allow(deprecated)]` remaining. All lint attrs have `reason`. Zero production mocks/TODO/FIXME/unreachable!(). All unsafe SAFETY-documented. `cargo deny check bans` passes clean.
+- **Deep Debt Evolution** (S273) — Production panic surface eliminated (`kernel_health.rs`, dispatch cache, `ember_client.rs`, `secure_enclave`). `dispatch/mod.rs` 1,638→839L via `dispatch/sovereign.rs` extraction. `warm_init.rs` → module dir. 6 CLI `well_known::*` sites migrated to capability-based discovery. VFIO `activity_tracker().record()` wired. hw-safe abstractions validated.
+- **Capability-based everywhere**: 6 CLI hardcoded primal name sites migrated to capability-based discovery (S273); ~400 intentional legacy-compat refs remain (env fallbacks, serde aliases). 0 production mocks. All production logging via `tracing`.
 - **ecoBin v3.0** — Zero C FFI deps. `deny.toml` ring + async-trait + zstd-sys bans active.
 - **46 unsafe blocks** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented. Workspace `unsafe_code = "deny"`, **41 crates `forbid`**.
 - **Dual-socket IPC** — `compute.sock` (JSON-RPC primary) + `compute-tarpc.sock` (tarpc hot-path).
 
-See [CHANGELOG.md](CHANGELOG.md) for full session-by-session history (S43–S272).
+See [CHANGELOG.md](CHANGELOG.md) for full session-by-session history (S43–S273).
 
 ---
 

NEXT_STEPS.md

@@ -1,9 +1,9 @@
 # ToadStool -- Next Steps
 
-**Updated**: May 2026 — S268 (Kernel Health Preflight: 3-layer `autoconf.h` mismatch detection in `cylinder::vfio::kernel_health`. Blocks warm handoff / DKMS builds on corrupted build env. `sovereign.kernel_health` RPC + `toadstool kernel-health` CLI. 700 cylinder tests.)
+**Updated**: May 2026 — S273 (Deep Debt Evolution: production panic surface eliminated, dispatch/sovereign.rs extraction, warm_init module split, CLI capability-based discovery migration, VFIO activity tracking wired. 88 JSON-RPC methods. 9,131+ lib tests. 700 cylinder tests.)
 **Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | tests verified (23,000+ workspace, 0 failures; 9,131+ lib-only) | **88 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | **Zero production panics/expects** | **Zero production TODO/FIXME/HACK** | **Zero production unreachable!()** | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **46 unsafe blocks** (all in hw containment, all SAFETY-documented) | **rustix 1.x workspace-wide** | **capability-based primal references (no hardcoded names)** | **`async-trait` DEPRECATED** (banned in `deny.toml`) | **`deny.toml` ring + async-trait + zstd-sys bans active** | **Phase C complete — all blocking items resolved (S253)** | **Phase D dispatch live — QMD-based VFIO PBDMA dispatch wired (S258–S263)** | **`OwnedFd` VFIO fd ownership (S253)** | **`toadstool device` CLI (S253)** | **CORALREEF_* env vars deprecated with TOADSTOOL_* primaries (S253)** | **Zero `#[allow(deprecated)]` remaining** | **700 cylinder tests** | **E2E sovereign dispatch VALIDATED on Titan V (warm handoff)**
-**Latest**: S268 — **Kernel Health Preflight**: `kernel_health.rs` 3-layer build env check (autoconf freshness, struct probe, RELA cross-check). Integrated into sovereign handoff step 0d, DKMS build guard, `sovereign.kernel_health` RPC, `toadstool kernel-health` CLI. Post-fix audit: all 20 DKMS + 10 installed modules clean. S267 — Sovereign driver rotation via diesel engine.
-**Previous**: S266 — PLX keepalive root cause fix. S265r — Driver Lab + Containment. S264 — PCIe bridge keepalive. S263 — CPUCTL_ALIAS breakthrough, GR context scheduler, warm handoff on Titan V.
+**Latest**: S273 — **Deep Debt Evolution**: Production panic surface eliminated — 29 `unwrap()` in `kernel_health.rs` → error propagation, dispatch cache `.expect()` → `Result`, 5 `.expect()` in `ember_client.rs` → `?`, 2 fallible `Default` impls removed from `secure_enclave`. `dispatch/mod.rs` 1,638→839L via 7 sovereign handlers extracted to `dispatch/sovereign.rs` (814L). `warm_init.rs` 1,439L → module dir (`mod.rs` + `seeders.rs` + `trials.rs`). 6 CLI `well_known::*` sites migrated to capability-based discovery with legacy fallback. `activity_tracker().record()` wired into 7 VFIO dispatch paths. hw-safe abstractions validated; cylinder migration deferred.
+**Previous**: S268 — Kernel Health Preflight. S267 — Sovereign driver rotation. S266 — PLX keepalive root cause fix. S265r — Driver Lab + Containment. S264 — PCIe bridge keepalive. S263 — CPUCTL_ALIAS breakthrough, GR context scheduler, warm handoff on Titan V.
 
 ---
 
@@ -34,7 +34,7 @@ syntax fixed in 3 server files. Test suite fully unblocked.
 
 ### P1: Test Coverage → 90% (D-COV) — Ongoing (S164)
 
-**~83.6% line coverage** (lib-only, 185K lines instrumented). **22,900+ tests** (0 failures, 8,849+ lib-only). Target 90%.
+**~83.6% line coverage** (lib-only, 185K lines instrumented). **23,000+ tests** (0 failures, 9,131+ lib-only). Target 90%.
 
 **S164** expanded coverage with **+94 new tests** across 7 low-coverage files:
 - `resource_validator.rs` 20% → ~75% (+19 tests)
@@ -65,6 +65,17 @@ names directly. Deprecated API definitions retained for backward compatibility o
 | **Phase C: Multi-unit routing engine** | ✅ LANDED — `compute.route.multi_unit` handler, tolerance-based routing, heuristic fallback, shader-core fallback on every decision |
 | **Phase D: Mixed command streams** | Planned — blocked on coralReef FECS firmware loading; extends PBDMA with draw/RT/texture/tensor/framebuffer commands |
 
+### S273 Deep Debt Evolution
+
+| Item | Status |
+|------|--------|
+| Production panic surface eliminated (`kernel_health.rs`, dispatch cache, `ember_client.rs`, `secure_enclave`) | **DONE** |
+| `dispatch/mod.rs` 1,638→839L — sovereign handlers extracted to `dispatch/sovereign.rs` (814L) | **DONE** |
+| `warm_init.rs` 1,439L → module dir (`mod.rs` + `seeders.rs` + `trials.rs`) | **DONE** |
+| 6 CLI `well_known::*` hardcoded primal name sites → capability-based discovery with legacy fallback | **DONE** |
+| `activity_tracker().record()` wired into 7 VFIO dispatch paths | **DONE** |
+| hw-safe abstractions validated; cylinder migration deferred | **DONE** |
+
 ### Wave 47 Behavioral Convergence (S272)
 
 | Item | Status |
@@ -199,7 +210,7 @@ after Phase D.
 - [x] **Clippy pedantic clean** -- `cargo clippy --workspace --all-targets -- -D warnings -W clippy::pedantic` zero warnings (S130+)
 - [x] **`#[expect]` evolution** -- production `#[allow]` evolved to `#[expect(lint, reason)]` where the lint fires; ~80 justified `#[allow]` remain (S198); S131+ removed stale suppressions
 - [x] **Spring sync S131+** -- all 5 springs pinned to latest, SPRING_ABSORPTION_TRACKER updated (S131+)
-- [ ] **Test coverage target 90%** -- 22,900+ tests (8,849+ lib-only); ~83.6% line; mock hardware layers for V4L2/VFIO (MockV4l2Device, MockVfioDevice); push to 90% ongoing
+- [ ] **Test coverage target 90%** -- 23,000+ tests (9,131+ lib-only); ~83.6% line; mock hardware layers for V4L2/VFIO (MockV4l2Device, MockVfioDevice); push to 90% ongoing
 - [x] **C dep elimination** -- flate2 → rust_backend, procfs default features disabled (S129)
 - [x] **Capability-based ports** -- `resolve_capability_or_legacy_port()` with graceful legacy fallback (S129)
 - [x] **God file splits (round 4)** -- ipc/server.rs, container/lib.rs, ecosystem.rs, handler/mod.rs, nestgate/client.rs (S129)
@@ -235,4 +246,4 @@ after Phase D.
 
 ## Completed Sessions (Archived)
 
-Session history for S43–S266 lives in [CHANGELOG.md](CHANGELOG.md). Fossil record for S87–S240 archived to `ecoPrimals/infra/wateringHole/fossilRecord/toadstool/`.
+Session history for S43–S273 lives in [CHANGELOG.md](CHANGELOG.md). Fossil record for S87–S240 archived to `ecoPrimals/infra/wateringHole/fossilRecord/toadstool/`.