clean root docs, fossilize debris, handoff — S275 Wave 49

Root docs (README, DOCUMENTATION, sporeprint) bumped to S275 with
9,149+ lib tests. toadstool.toml HTTP-era 364L config fossilized and
replaced with 30L IPC-first config. Stale docs fossilized or session-
tagged (PRIMAL_INTEGRATION_GUIDE, TYPES_REFERENCE, DEPLOYMENT_GUIDE,
DAEMON_MODE_EVOLUTION). primal-capabilities.toml annotated with Wave 49
note. amd_metal.rs #[allow(dead_code)] → #[expect] with reason.
Wave 49 handoff created for primalSpring audit.

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

Author: BiomeOS Developer

DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # ToadStool Documentation Hub
 
-**Last Updated**: May 2026 — S273
+**Last Updated**: May 2026 — S275
 
 ---
 
@@ -30,11 +30,11 @@ These root documents were **fully resolved** and **fossilized** in wateringHole
 
 ---
 
-## Current State (S273 — May 2026)
+## Current State (S275 — 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.
+- **23,000+ tests** (9,149+ lib-only), 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite.
 - **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.
@@ -49,7 +49,7 @@ These root documents were **fully resolved** and **fossilized** in wateringHole
 - **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–S273).
+See [CHANGELOG.md](CHANGELOG.md) for full session-by-session history (S43–S275).
 
 ---
 

README.md

@@ -1,6 +1,6 @@
 # ToadStool
 
-**Sovereign Compute Hardware** | Pure Rust | ecoBin | May 2026 | S273 | v0.2.0
+**Sovereign Compute Hardware** | Pure Rust | ecoBin | May 2026 | S275 | v0.2.0
 
 ---
 
@@ -42,7 +42,7 @@ Nest    = Tower  + Storage            <- storage
 | `cargo fmt --all -- --check` | 0 diffs |
 | `cargo clippy --workspace --all-targets -- -D warnings` | 0 warnings |
 | `cargo doc --workspace --no-deps` (RUSTDOCFLAGS="-D warnings") | 0 warnings |
-| `cargo test --workspace` | **23,000+ tests, 0 failures** (9,131+ lib-only), **~222** ignored (hardware-gated); full workspace ~7m |
+| `cargo test --workspace` | **23,000+ tests, 0 failures** (9,149+ lib-only), **~222** ignored (hardware-gated); full workspace ~7m |
 | Doctests | All passing (common, core, server, cli, testing, display) |
 | Standalone clone test | Pull to any machine, `cargo test` works (GPU-optional, CPU fallback, device-lost resilient) |
 | `unsafe` blocks | **46 actual** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented (S204, 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) |

crates/core/cylinder/src/vfio/amd_metal.rs

@@ -372,7 +372,7 @@ pub struct VegaInitResult {
 /// to AMD GCN/CDNA hardware with completely different register semantics.
 #[derive(Debug)]
 pub struct VegaInit {
-    #[allow(dead_code)]
+    #[expect(dead_code, reason = "BDF stored for future AMD metal init pipeline")]
     bdf: Option<String>,
 }
 

docs/architecture/DAEMON_MODE_EVOLUTION.md

@@ -6,7 +6,7 @@
 > That proposal was for the HTTP-based daemon. The daemon is now fully IPC-first
 > (JSON-RPC 2.0 over Unix sockets) as of S169.
 
-## Current Architecture (S170→S263)
+## Current Architecture (S170→S275)
 
 ```
 toadstool daemon start

docs/guides/PRIMAL_INTEGRATION_GUIDE.md

@@ -1,8 +1,13 @@
 # 🔗 Primal Integration Guide
 
+> **FOSSIL (S275).** This guide predates the S273 capability-based migration. Primal
+> integration is now capability-first — primals discover each other by capability at
+> runtime, not by name. BearDog/SongBird/NestGate names below are legacy references.
+> See `CAPABILITY_BASED_DISCOVERY_STANDARD.md` v1.2 for current patterns.
+
 **Date**: January 14, 2026  
-**Status**: ✅ **ACTIVE**  
-**Purpose**: Runtime integration with ecoPrimals and external systems
+**Status**: 📦 **FOSSILIZED** (Wave 49)  
+**Purpose**: Runtime integration with ecoPrimals and external systems (historical)
 
 ---
 

docs/reference/PRODUCTION_DEPLOYMENT_GUIDE.md

@@ -9,16 +9,17 @@
 ## Current Deployment
 
 ToadStool is a single binary (`toadstool`) following the UniBin standard.
+Distributed via **plasmidBin** depot (post-primordial mandate, Wave 49).
 
 ### Environment Variables
 
 | Variable | Purpose | Default |
 |----------|---------|---------|
 | `XDG_RUNTIME_DIR` | Socket directory | `/run/user/$UID` |
-| `TOADSTOOL_DAEMON_API_PORT` | Optional TCP port (0 = OS-assigned) | `0` |
-| `COORDINATION_PORT` | Songbird capability port | `8080` |
-| `SECURITY_PORT` | BearDog capability port | `8082` |
-| `STORAGE_PORT` | NestGate capability port | `8083` |
+| `TOADSTOOL_SOCKET` | Override JSON-RPC socket path | biomeOS convention |
+| `TOADSTOOL_DEPLOYMENT_MODEL` | `multi` / `rental` for multi-tenant GPU scheduling | unset (LocalDirect) |
+| `TOADSTOOL_STANDALONE` | `1` to skip distributed coordinator | unset (distributed) |
+| `TOADSTOOL_FAMILY_ID` | Family ID for BTSP production mode | unset (development) |
 
 ### Running
 

docs/reference/TYPES_REFERENCE.md

@@ -1,8 +1,8 @@
 # ToadStool Types Reference Guide
 ## Canonical Type Definitions and Usage Patterns
 
-**Last Updated**: April 2026 — S177  
-**Status**: Production-Ready
+**Last Updated**: April 2026 — S177 (fossilized S275)  
+**Status**: 📦 Reference — types are canonical but session tag is historical
 
 ---
 

infra/wateringHole/handoffs/PRIMALSPRING_WAVE49_ECOSYSTEM_TIGHTENING_S275_MAY25_2026.md

@@ -0,0 +1,104 @@
+# toadStool S275 — Wave 49: Ecosystem Tightening
+
+**Date**: May 25, 2026
+**Session**: S275
+**From**: toadStool team
+**To**: primalSpring (downstream audit)
+**Audit**: primalSpring Wave 49 — ecosystem tightening (3 vectors + startup debt)
+
+---
+
+## Summary
+
+All three Wave 49 cleanup vectors resolved. Startup latency pipeline debt
+addressed with deferred wgpu GPU enumeration and pre-bound socket optimization.
+
+## Vector A — Stale Deploy Patterns (High — correctness)
+
+| File | Change |
+|------|--------|
+| `.cargo/config.toml` | `target/release/toadstool` ref → plasmidBin wording |
+| `docs/guides/AKIDA_DRIVER_DEPLOYMENT.md` | `target/release/toadstool` Dockerfile → plasmidBin depot |
+| `crates/cli/README.md` | `cargo install toadstool-cli` → plasmidBin depot docs |
+| `scripts/install-akida-driver.sh` | Prefers plasmidBin depot binary, falls back to local build |
+
+No `which toadstool` patterns found. `notify-plasmidbin.yml` confirmed active.
+
+## Vector B — wateringHole Consolidation (Medium)
+
+36 local handoffs mirrored to central `infra/wateringHole/`:
+
+- **8 active** (S267–S274) → `handoffs/`
+- **28 historical** (S243–S266) → `handoffs/archive/`
+
+Local handoffs remain as canonical source.
+
+## Vector C — Showcase Fossilization (Low)
+
+35 files (8 progressive API demos, 2 levels) archived to
+`fossilRecord/primals/toadStool/showcase_wave49/`. `showcase/` replaced
+with pointer README.
+
+## Pipeline Debt — Startup Latency (>8s → ~3s)
+
+### Root cause
+
+`create_executor()` ran **before** socket bind, with wgpu GPU enumeration
+(1–5s Vulkan driver init) and mDNS coordination discovery (3s) on the
+critical path.
+
+### Fix: deferred wgpu + pre-bound socket
+
+1. **Deferred wgpu GPU enumeration** — `query_local_capabilities()` now
+   returns a fast baseline (cpu, memory, orchestration) immediately and
+   spawns wgpu enumeration in a background `tokio::spawn`. Full GPU
+   capabilities populate the `OnceLock` asynchronously. Saves 1–5s.
+
+2. **Pre-bound JSON-RPC socket** — `prebind_unix_listener()` binds the
+   socket before `create_executor()` runs. `serve_unix_prebound()` accepts
+   the pre-bound listener. Health probes can connect during init.
+
+3. Default `LocalDirect` deployment: no orchestrator overhead.
+
+### New public API
+
+- `prebind_unix_listener(path) → UnixListener`
+- `serve_unix_prebound(handler, listener)`
+- `start_servers_with_fallback(..., jsonrpc_listener: Option<UnixListener>)`
+
+## Additional Cleanup (S275)
+
+| Item | Action |
+|------|--------|
+| `toadstool.toml` | HTTP-era 364-line template fossilized → `toadstool_wave49.toml`; replaced with 30-line IPC-first config |
+| `primal-capabilities.toml` | Added Wave 49 note: legacy primal name sections are reference only |
+| `docs/guides/PRIMAL_INTEGRATION_GUIDE.md` | Fossilized (S275) — predates S273 capability migration |
+| `docs/reference/PRODUCTION_DEPLOYMENT_GUIDE.md` | Env vars updated to IPC-first (removed Songbird/BearDog/NestGate ports) |
+| `docs/reference/TYPES_REFERENCE.md` | Session tag updated to reflect historical status |
+| `docs/architecture/DAEMON_MODE_EVOLUTION.md` | Session range updated to S275 |
+| `crates/core/cylinder/src/vfio/amd_metal.rs` | `#[allow(dead_code)]` → `#[expect(dead_code, reason)]` |
+
+## Verification Checklist
+
+- [x] No `showcase/` directory (pointer README only)
+- [x] Local `wateringHole/` active handoffs mirrored to `infra/wateringHole/handoffs/`
+- [x] No `which toadstool` or `target/release/toadstool` in scripts
+- [x] `notify-plasmidbin.yml` active in `.github/workflows/`
+- [x] Production TODO/FIXME/HACK: 0
+- [x] `toadstool.toml` HTTP-era template fossilized
+
+## Metrics
+
+| Metric | Value |
+|--------|-------|
+| Lib tests | 9,149+ |
+| Workspace tests | 23,000+ |
+| JSON-RPC methods | 88 |
+| Clippy warnings | 0 |
+| Showcase files archived | 35 |
+| Handoffs mirrored to central | 36 (8 active + 28 archive) |
+| Stale deploy refs fixed | 4 |
+
+---
+
+Ready for downstream primalSpring audit.

primal-capabilities.toml

@@ -6,6 +6,11 @@
 # Usage:
 #   let services = discovery.find_by_capability("cryptographic-operations").await?;
 #   // No hardcoded "beardog" - discovered by capability!
+#
+# NOTE (Wave 49, S275): External primal sections below (beardog, songbird, nestgate, etc.)
+# use legacy primal names and HTTP/gRPC protocols from pre-IPC era. These are retained
+# as reference for capability *names* only. Actual discovery is now via Unix socket
+# capability-based lookup. See CAPABILITY_BASED_DISCOVERY_STANDARD.md v1.2.
 
 [registry]
 version = "1.0.0"

sporeprint/validation-summary.md

@@ -1,7 +1,7 @@
 +++
 title = "ToadStool Validation Summary"
-description = "Sovereign compute hardware primal — 9,131+ lib tests, 88 JSON-RPC methods, 47 crates, VFIO GPU init pipeline, v0.2.0"
-date = 2026-05-24
+description = "Sovereign compute hardware primal — 9,149+ lib tests, 88 JSON-RPC methods, 47 crates, VFIO GPU init pipeline, v0.2.0"
+date = 2026-05-25
 
 [taxonomies]
 primals = ["toadstool"]
@@ -10,8 +10,8 @@ springs = ["hotspring", "wetspring", "airspring", "groundspring", "neuralspring"
 
 ## Status
 
-- **Version**: 0.2.0 (Session S273, May 24, 2026)
-- **Lib tests**: 9,131+ (0 failures, unlimited parallelism)
+- **Version**: 0.2.0 (Session S275, May 25, 2026)
+- **Lib tests**: 9,149+ (0 failures, unlimited parallelism)
 - **Workspace tests**: 23,000+ (0 failures, ~222 hardware-gated ignores)
 - **JSON-RPC methods**: 88 (direct) + semantic registry aliases
 - **Workspace crates**: 47