S207: self-registration via DISCOVERY_SOCKET + ipc.register at startup

register_with_discovery() sends ipc.register to Songbird with
compute.dispatch + compute.capabilities + unix:// endpoint.
Honors DISCOVERY_SOCKET (highest precedence). DaemonServer path
now also self-registers. find_by_capability evolved to
ipc.find_capability via discovery path. Old function deprecated.
7,842 lib tests, 0 failures.

Made-with: Cursor

Author: westgate

CONTEXT.md

@@ -29,12 +29,13 @@ ToadStool is the **Layer 0** hardware substrate that other primals and springs d
   - Override: `TOADSTOOL_SOCKET` / `TOADSTOOL_TARPC_SOCKET` env vars
   - 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.
-- **Tests**: 20,000+ (7,841 lib-only S206, 0 failures, unlimited parallelism)
+- **Tests**: 20,000+ (7,842 lib-only S207, 0 failures, unlimited parallelism)
 - **Unsafe**: 49 blocks (all in hw-safe/GPU/VFIO/display/plugin containment, all SAFETY-documented); workspace `unsafe_code = "deny"`, 41 crates `forbid` + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`; all ~40 production `#[allow]` have `reason =` (S206)
 - **async-trait**: DEPRECATED — fully removed and banned in `deny.toml` (S203r); transitive only via axum/config/wiggle
 - **deny.toml**: `ring` + `async-trait` + `zstd-sys` bans active (ecoBin v3 compliant)
 - **Display Phase 2**: `display.present`, `display.subscribe_input`, `display.poll_events` (petalTongue IPC)
 - **Encrypted compute dispatch** (Phase 55): Tower `crypto.encrypt`/`crypto.decrypt` for payloads; `DISCOVERY_SOCKET` highest-precedence capability resolution
+- **Self-registration** (S207): `ipc.register` to Songbird via `DISCOVERY_SOCKET` at startup — dynamic NUCLEUS membership without restart
 - **BTSP**: 13/13 converged — JSON-line relay + NDJSON post-handshake (primalSpring Phase 45c)
 - **Dep hygiene**: `test-mocks` off by default (S206); all workspace deps unified
 - **Monitoring**: Real host queries via `toadstool_sysmon` + `rustix::fs::statvfs`

DEBT.md

@@ -1,13 +1,20 @@
 # Active Technical Debt Register
 
-**Date**: April 2026 — S206
+**Date**: April 2026 — S207
 **Philosophy**: Math is universal, precision is silicon. Workarounds are
 short-term solutions that increase debt. We aim to solve deep debt over
 iterations, evolving toward vendor-agnostic, capability-based solutions—
 with production stubs surfacing typed configuration errors and capability
 guidance, and auth policy driven by explicit environment configuration
 where applicable.
 
+**S207 (Self-Registration via DISCOVERY_SOCKET)**: Resolved **D-SELF-REGISTRATION**
+(`register_with_coordination()` evolved to `register_with_discovery()` — sends
+`ipc.register` to Songbird via `DISCOVERY_SOCKET` with `compute.dispatch` +
+`compute.capabilities` + `unix://` endpoint. DaemonServer also self-registers.
+`find_by_capability` evolved to use `ipc.find_capability` via discovery path.
+Old functions deprecated with migration path). 7,842 lib tests, 0 failures.
+
 **S206 (Lint Evolution + Dep Hygiene + Feature Cleanup)**: Resolved **D-LINT-FULL**
 (all ~40 bare `#[allow(...)]` in production evolved to `#[allow(..., reason = "...")]` —
 17 `unsafe_code` modules, ~23 clippy/deprecated/async-fn-in-trait allows), **D-DEP-UNIFIED**

NEXT_STEPS.md

@@ -1,8 +1,8 @@
 # ToadStool -- Next Steps
 
-**Updated**: April 2026 — S206 (Lint Evolution + Dep Hygiene + Feature Cleanup)
-**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | **7,841 lib-only** tests verified (20,000+ workspace, 0 failures) | **~65 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | Zero production unwraps | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **49 unsafe blocks** (all in hw containment, all SAFETY-documented) | **0 production TODOs** | **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** | **env centralized via config structs** | **real Linux sandbox (rustix)** | **real resource metrics (cgroup v2/proc)** | **plugin loading (libloading)** | **binary tarpc framing (MessagePack)** | **BTSP JSON-line relay (Phase 45c)** | **Display Phase 2 (petalTongue IPC)** | **Encrypted compute dispatch (Phase 55)** | **All lint attrs with reason (S206)** | **test-mocks off by default (S206)**
-**Latest**: S206 — Lint Evolution + Dep Hygiene + Feature Cleanup: All ~40 production bare `#[allow(...)]` evolved to `#[allow(..., reason)]` (17 `unsafe_code`, ~23 clippy/deprecated). `humantime-serde`, `rand`, `tokio-util`, `temp-env` unified to workspace in 20+ Cargo.toml files. GPU `spirv`/`jit`/`testing` + testing `integration-tests`/`benchmarks`/`wiremock` stale features and deps removed. `test-mocks` removed from core default features. **7,841 lib-only** tests, 0 failures, clippy clean, fmt clean.
+**Updated**: April 2026 — S207 (Self-Registration via DISCOVERY_SOCKET)
+**Status**: Production-grade | Rust edition **2024** (MSRV 1.85) | **AGPL-3.0-or-later** | **All quality gates green** | **7,842 lib-only** tests verified (20,000+ workspace, 0 failures) | **~65 JSON-RPC methods** | Wire Standard L3 (partial) | Zero C FFI deps (ecoBin v3.0) | Zero production unwraps | IPC-first | workspace `unsafe_code = "deny"`, **41 crates `forbid`** | **49 unsafe blocks** (all in hw containment, all SAFETY-documented) | **0 production TODOs** | **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** | **env centralized via config structs** | **real Linux sandbox (rustix)** | **real resource metrics (cgroup v2/proc)** | **plugin loading (libloading)** | **binary tarpc framing (MessagePack)** | **BTSP JSON-line relay (Phase 45c)** | **Display Phase 2 (petalTongue IPC)** | **Encrypted compute dispatch (Phase 55)** | **All lint attrs with reason (S206)** | **test-mocks off by default (S206)** | **Self-registration with Songbird (S207)**
+**Latest**: S207 — Self-Registration via DISCOVERY_SOCKET: `register_with_coordination()` evolved to `register_with_discovery()` — sends `ipc.register` to Songbird via `DISCOVERY_SOCKET` (highest-precedence, set by `composition_nucleus.sh`). Capabilities: `compute.dispatch` + `compute.capabilities`. Endpoint: `unix:///…/compute.sock` (actual listen path via `resolve_toadstool_socket`). DaemonServer startup now also self-registers. `find_by_capability` evolved to use `ipc.find_capability` via DISCOVERY_SOCKET. Old function deprecated with migration path. **7,842 lib-only** tests, 0 failures, clippy clean, fmt clean.
 
 ---
 

README.md

@@ -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` | **20,000+ tests, 0 failures** (7,841 lib-only verified S205), **~93** ignored (hardware-gated); full workspace ~3m30s |
+| `cargo test --workspace` | **20,000+ tests, 0 failures** (7,842 lib-only verified S207), **~93** ignored (hardware-gated); full workspace ~3m30s |
 | 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 | **49 actual** (all in hw-safe/GPU/VFIO/display/plugin containment crates); all SAFETY-documented (S204); workspace `unsafe_code = "deny"`, **41 crates `forbid`** + 5 hw crates with narrow `#[allow(unsafe_code, reason)]`; **all ~40 production `#[allow]` have `reason =`** (S206) |
@@ -272,7 +272,7 @@ toadStool/
 - **Test coverage** -- pushing toward 90% target; 22,000+ tests; ~83.6% lib-only line (185K lines instrumented); remaining gap: hardware-dependent paths, specialty runtimes
 - **DF64 / ComputeDispatch** -- transferred to barraCuda team (S93); toadStool serves hardware capabilities
 - **Sovereign compiler Phase 4+** -- register pressure estimation, loop software pipelining (barraCuda)
-- **NUCLEUS crypto integration** -- compute payloads encrypted via Tower `crypto.encrypt`/`crypto.decrypt` (S205); next: primal self-registration with Songbird (`ipc.register`)
+- **NUCLEUS crypto integration** -- compute payloads encrypted via Tower `crypto.encrypt`/`crypto.decrypt` (S205); **self-registration with Songbird** via `DISCOVERY_SOCKET` + `ipc.register` at startup (S207)
 
 ### Recently Completed
 - **S206 (Apr 28, 2026)**: **Lint Evolution + Dep Hygiene + Feature Cleanup** — All ~40 production bare `#[allow(...)]` evolved to `#[allow(..., reason)]` (17 `unsafe_code`, ~23 clippy/deprecated). `humantime-serde`, `rand`, `tokio-util`, `temp-env` unified to `{ workspace = true }` in 20+ Cargo.toml files. GPU `spirv`/`jit`/`testing` + testing `integration-tests`/`benchmarks`/`wiremock` stale features/deps removed. `test-mocks` removed from core default features (production builds no longer compile mock backends). 7,841 lib tests, 0 failures, clippy clean.

crates/cli/src/daemon/server.rs

@@ -66,8 +66,14 @@ impl DaemonServer {
         let workload_manager = WorkloadManager::new(config.max_concurrent_workloads).await?;
         info!("✅ Workload manager initialized");
 
-        // Phase 4: Resource monitor via system metrics
-        // Phase 5: Health reporting via coordination service integration
+        // Self-register with Songbird via DISCOVERY_SOCKET (fire-and-forget)
+        match toadstool::ipc_helpers::register_with_discovery().await {
+            Ok(()) => info!("✅ Self-registered with discovery service"),
+            Err(e) => {
+                warn!("Could not self-register with discovery service: {e}");
+                warn!("Operating in standalone mode (no discovery)");
+            }
+        }
 
         info!("✅ ToadStool daemon server initialized");
 

crates/core/toadstool/src/ipc/mod.rs

@@ -39,7 +39,12 @@ pub use server::IpcServer;
 
 // Re-export legacy helpers for backward compatibility
 // These will gradually migrate to use the new platform layer
+#[expect(
+    deprecated,
+    reason = "re-export kept for callers migrating to register_with_discovery"
+)]
+pub use crate::ipc_helpers::register_with_coordination;
 pub use crate::ipc_helpers::{
     find_by_capability, get_default_coordination_socket, get_semantic_name, is_semantic_method,
-    list_semantic_methods, register_with_coordination, resolve_method_name,
+    list_semantic_methods, register_with_discovery, resolve_method_name,
 };

crates/core/toadstool/src/ipc_helpers/connection.rs

@@ -12,6 +12,9 @@ use tracing::{debug, info};
 use crate::{ToadStoolError, ToadStoolResult};
 use toadstool_common::constants::PRIMAL_NAME;
 use toadstool_common::constants::timeouts;
+use toadstool_common::primal_sockets::{
+    SocketPathEnv, resolve_capability_socket_fallback, resolve_toadstool_socket,
+};
 
 use super::framing;
 
@@ -35,54 +38,49 @@ fn get_runtime_dir() -> String {
         })
 }
 
-fn resolve_coordination_socket() -> String {
-    std::env::var("BIOMEOS_COORDINATION_SOCKET")
-        .or_else(|_| std::env::var("COORDINATION_SOCKET"))
-        .unwrap_or_else(|_| get_default_coordination_socket())
-}
-
 /// Default coordination-capability socket path.
 ///
 /// biomeOS convention: `$XDG_RUNTIME_DIR/biomeos/coordination.sock`
 pub fn get_default_coordination_socket() -> String {
     format!("{}/biomeos/coordination.sock", get_runtime_dir())
 }
 
-/// Register ToadStool with coordination/discovery service
+/// Self-register with Songbird via `DISCOVERY_SOCKET` (preferred) or coordination fallback.
+///
+/// Sends `ipc.register` so Songbird can resolve `toadstool` by capability
+/// without the composition launcher doing it on our behalf. Fire-and-forget
+/// at the call site — if this fails the primal continues in standalone mode.
 ///
 /// # Errors
 ///
-/// Returns error if the coordination service is unreachable, JSON-RPC framing
+/// Returns error if the discovery service is unreachable, JSON-RPC framing
 /// fails, or registration is rejected.
-pub async fn register_with_coordination() -> ToadStoolResult<()> {
-    let socket_path = resolve_coordination_socket();
+pub async fn register_with_discovery() -> ToadStoolResult<()> {
+    let env = SocketPathEnv::from_env();
+    let discovery_path = resolve_capability_socket_fallback("discovery", &env);
+    let socket_path = discovery_path.to_string_lossy().to_string();
 
-    info!("Registering with coordination service at {}", socket_path);
+    info!("Self-registering with discovery service at {}", socket_path);
 
-    let mut stream = timeout(IPC_TIMEOUT, UnixStream::connect(&socket_path))
+    let mut stream = timeout(IPC_TIMEOUT, UnixStream::connect(discovery_path.as_path()))
         .await
-        .map_err(|_| ToadStoolError::integration("Timeout connecting to coordination service"))?
+        .map_err(|_| ToadStoolError::integration("Timeout connecting to discovery service"))?
         .map_err(|e| {
             ToadStoolError::integration(format!(
-                "Failed to connect to coordination service at {socket_path}: {e}"
+                "Failed to connect to discovery service at {socket_path}: {e}"
             ))
         })?;
 
-    let socket_endpoint = std::env::var("TOADSTOOL_SOCKET").unwrap_or_else(|_| {
-        let runtime_dir = get_runtime_dir();
-        format!("{runtime_dir}/biomeos/{PRIMAL_NAME}.sock")
-    });
+    let own_socket = resolve_toadstool_socket(&env);
+    let endpoint = format!("unix://{}", own_socket.display());
 
     let request = json!({
         "jsonrpc": toadstool_common::constants::jsonrpc::VERSION,
-        "method": "capability.register",
+        "method": "ipc.register",
         "params": {
-            "primal_name": PRIMAL_NAME,
-            "capabilities": [
-                "compute", "workload", "orchestration", "ai_local",
-                "gpu", "wasm", "container", "shader.dispatch"
-            ],
-            "endpoint": socket_endpoint
+            "primal_id": PRIMAL_NAME,
+            "capabilities": ["compute.dispatch", "compute.capabilities"],
+            "endpoint": endpoint
         },
         "id": 1
     });
@@ -92,37 +90,58 @@ pub async fn register_with_coordination() -> ToadStoolResult<()> {
 
     if let Some(error) = response.get("error") {
         return Err(ToadStoolError::integration(format!(
-            "Coordination service registration failed: {error}"
+            "Discovery service registration failed: {error}"
         )));
     }
 
-    info!("Successfully registered with coordination service");
+    info!("Self-registered with discovery service ({})", endpoint);
     debug!("Registration response: {:?}", response);
 
     Ok(())
 }
 
-/// Find primals by capability via coordination service
+/// Register ToadStool with coordination/discovery service.
+///
+/// Delegates to [`register_with_discovery`], which uses `DISCOVERY_SOCKET`
+/// (highest precedence, set by `composition_nucleus.sh` → Songbird) with
+/// full fallback through `resolve_capability_socket_fallback("discovery", …)`.
+///
+/// # Errors
+///
+/// Returns error if the coordination service is unreachable, JSON-RPC framing
+/// fails, or registration is rejected.
+#[deprecated(note = "use register_with_discovery — aligns with DISCOVERY_SOCKET + ipc.register")]
+pub async fn register_with_coordination() -> ToadStoolResult<()> {
+    register_with_discovery().await
+}
+
+/// Find primals by capability via discovery/coordination service
+///
+/// Uses `DISCOVERY_SOCKET` (highest precedence) with full fallback chain.
 ///
 /// # Errors
 ///
 /// Returns error if the coordination service is unreachable, the response is
 /// invalid, or the query fails.
 pub async fn find_by_capability(capability: &str) -> ToadStoolResult<Vec<String>> {
-    let socket_path = resolve_coordination_socket();
+    let env = SocketPathEnv::from_env();
+    let discovery_path = resolve_capability_socket_fallback("discovery", &env);
+    let socket_path = discovery_path.to_string_lossy().to_string();
 
     debug!("Finding primals with capability: {}", capability);
 
-    let mut stream = timeout(IPC_TIMEOUT, UnixStream::connect(&socket_path))
+    let mut stream = timeout(IPC_TIMEOUT, UnixStream::connect(discovery_path.as_path()))
         .await
-        .map_err(|_| ToadStoolError::integration("Timeout connecting to coordination service"))?
+        .map_err(|_| ToadStoolError::integration("Timeout connecting to discovery service"))?
         .map_err(|e| {
-            ToadStoolError::integration(format!("Failed to connect to coordination service: {e}"))
+            ToadStoolError::integration(format!(
+                "Failed to connect to discovery service at {socket_path}: {e}"
+            ))
         })?;
 
     let request = json!({
         "jsonrpc": toadstool_common::constants::jsonrpc::VERSION,
-        "method": "capability.find",
+        "method": "ipc.find_capability",
         "params": {
             "capability": capability
         },

crates/core/toadstool/src/ipc_helpers/mod.rs

@@ -23,8 +23,13 @@ use crate::semantic_methods::SemanticMethodRegistry;
 use std::sync::OnceLock;
 use tracing::debug;
 
+#[expect(
+    deprecated,
+    reason = "re-export kept for callers migrating to register_with_discovery"
+)]
+pub use connection::register_with_coordination;
 pub use connection::{
-    find_by_capability, get_default_coordination_socket, register_with_coordination,
+    find_by_capability, get_default_coordination_socket, register_with_discovery,
 };
 
 /// Global semantic method registry (initialized once)