|
1 | 1 | # Active Technical Debt Register |
2 | 2 |
|
3 | | -**Date**: April 14, 2026 — S203i |
| 3 | +**Date**: April 15, 2026 — S203k |
4 | 4 | **Philosophy**: Math is universal, precision is silicon. Workarounds are |
5 | 5 | short-term solutions that increase debt. We aim to solve deep debt over |
6 | 6 | iterations, evolving toward vendor-agnostic, capability-based solutions. |
7 | 7 |
|
8 | 8 | ## Active Debt |
9 | 9 |
|
| 10 | +### D-SANDBOX-SIMULATION — Active |
| 11 | +**Crate**: `security/sandbox` | **File**: `linux.rs` |
| 12 | +Linux sandbox operations (`destroy_sandbox`, `setup_mount`, `apply_security_policy`, |
| 13 | +`get_sandbox_logs`, `monitor_sandbox`) return success without actual namespace/cgroup/ |
| 14 | +seccomp/mount operations. `monitor_sandbox` returns all-zero `ResourceUsage`. Logs are |
| 15 | +synthetic strings. Requires real kernel namespace/cgroup integration to evolve. |
| 16 | + |
| 17 | +### D-PLUGIN-SIMULATE — Active |
| 18 | +**Crate**: `core/toadstool` | **File**: `plugin_system/manager.rs` |
| 19 | +`load_plugin` / `unload_plugin` simulate load/unload (no `dlopen`, no cleanup). |
| 20 | +Evolution requires plugin ABI design. |
| 21 | + |
| 22 | +### D-BYOB-RESOURCE-SIM — Active |
| 23 | +**Crate**: `core/toadstool` | **File**: `byob/byob_impl/mod.rs` |
| 24 | +`update_resource_usage` returns simulated CPU/memory/network from service specs, |
| 25 | +not real metrics. Evolution requires integration with cgroup stats or monitoring. |
| 26 | + |
| 27 | +### D-WORKLOAD-CLIENT-IPC — Active |
| 28 | +**Crate**: `client` | **File**: `client/core.rs` |
| 29 | +`submit_workload` / `get_execution_status` always return `Err` for non-GPU workload |
| 30 | +types. JSON-RPC method mapping not yet wired for native/container/wasm/python paths. |
| 31 | + |
| 32 | +### D-HW-LEARN-VERIFY — Active |
| 33 | +**Crate**: `core/hw-learn` | **File**: `applicator/verify.rs` |
| 34 | +`verify_register`, `verify_compute_readback`, `verify_memory_accessible` return |
| 35 | +failure results with debt-tracking messages. Requires nouveau UAPI parsing. |
| 36 | + |
10 | 37 | ### D-TARPC-PHASE3-BINARY |
11 | 38 | **Crate**: `integration/protocols` | **Feature**: `tarpc-transport` |
12 | 39 | `TRpcTransport::send_message` now wired (S197): resolves target primal's Unix |
@@ -55,12 +82,163 @@ Files: `fuzz/Cargo.toml`, `fuzz/fuzz_targets/*.rs`, `.github/workflows/ci.yml`. |
55 | 82 |
|
56 | 83 | ## Known Limitations (not actionable debt) |
57 | 84 |
|
58 | | -### D-ASYNC-DYN-MARKERS — Rust language constraint |
59 | | -**Scope**: Workspace (~55 files) | **Marker**: `NOTE(async-dyn)` |
60 | | -Traits using `#[async_trait]` because native `async fn` in `dyn Trait` is not yet |
61 | | -stable in Rust. Cannot resolve until Rust stabilizes this feature. The `#[async_trait]` |
62 | | -dependency is pure Rust (proc-macro) and zero-overhead at runtime for non-dyn paths. |
63 | | -**Not actionable** — resolves when Rust stabilizes the feature. Markers are accurate documentation. |
| 85 | +### D-ASYNC-DYN-MARKERS — Partially resolved, ongoing |
| 86 | +**Scope**: Workspace (~148 remaining `#[async_trait]` annotations, down from 183) |
| 87 | +**Wave 1-2**: Migrated 7 traits (zero-dyn + dead-code + concrete-type). Freed 3 crates. |
| 88 | +**Wave 3** (S203j): Migrated 6 more zero-dyn traits: `HealthMonitor`, `SwapExecutor`, |
| 89 | +`DeviceDiscovery`, `HealthProbe`, `CrossCompilationToolchain` (+ 3 impls), `GpuDiscovery`. |
| 90 | +10 more annotations removed. 5 more crates freed from `async-trait` dependency: |
| 91 | +`toadstool-glowplug`, `toadstool-management-monitoring`, `toadstool-runtime-native`, |
| 92 | +`toadstool-integration-security`, `toadstool-runtime-container` (moved to dev-dep). |
| 93 | +Total: 13 traits migrated, 8 crates freed across all waves. |
| 94 | +**Remaining ~148**: On traits with production `dyn` dispatch (`AuthBackend`, `AgentBackend`, |
| 95 | +`CryptoProvider`, `UnifiedMemoryBackend`, `EdgeDevice`, `WorkloadExecutor`, etc.). |
| 96 | +Migration requires Send-aware generics or enum dispatch (Squirrel Wave 2/3 pattern). |
| 97 | + |
| 98 | +## S203k Resolved Debt (Deep Debt Execution: Comprehensive Evolution Pass) |
| 99 | + |
| 100 | +### D-NET-CONFIG-VALIDATION — RESOLVED S203k |
| 101 | +**Scope**: `cli/network_config/configurator` (5 modules) |
| 102 | +Empty `apply_*` functions evolved with explicit "deferred to orchestration layer" debug |
| 103 | +messages. Empty `validate_*` functions evolved with structural validation: circuit breaker |
| 104 | +thresholds, health check intervals, DNS timeout/server validation, auth method checks, |
| 105 | +PKI/audit/isolation field validation, traffic management percentages, port range ordering. |
| 106 | +Files: `reliability.rs`, `security.rs`, `traffic.rs`, `service_mesh.rs`, `discovery.rs`. |
| 107 | + |
| 108 | +### D-ENV-INTERN-WAVE2 — RESOLVED S203k |
| 109 | +**Scope**: Workspace (6 modules, ~40+ raw strings) |
| 110 | +Remaining raw env var string literals centralized to `socket_env::*` constants. Added |
| 111 | +`TOADSTOOL_COORDINATION_URL/PORT`, `TOADSTOOL_SECURITY_URL/PORT`, `TOADSTOOL_STORAGE_URL/PORT`, |
| 112 | +`TOADSTOOL_SONGBIRD_PORT`, discovery/bind/auth/endpoint constants. Wired in |
| 113 | +`primal_discovery_complete`, `infant_discovery/fallback`, `distributed/scheduler`, |
| 114 | +`server/unibin/execution`, `integration/security/discovery`. |
| 115 | +Files: `socket_env.rs`, 6 consumer modules. |
| 116 | + |
| 117 | +### D-HTTP-PROTOCOL-LITERAL — RESOLVED S203k |
| 118 | +**Scope**: Workspace (7 modules) |
| 119 | +Raw `"http://"` in `format!` URLs replaced with `HTTP_PROTOCOL` constant from |
| 120 | +`toadstool_common::constants::network`. Added `UNIX_SOCKET_URL_SCHEME` (`"unix"`) and |
| 121 | +`UNIX_SOCKET_URL_PREFIX` (`"unix://"`) constants for Unix socket URL handling. |
| 122 | +Files: `network.rs`, `primal_discovery_mdns.rs`, `primal_discovery_complete/mod.rs`, |
| 123 | +`discovery_defaults.rs`, `discovery_engine/mod.rs`, `zero_config/service_discovery.rs`, |
| 124 | +`ecosystem_network.rs`, `config/types/network.rs`. |
| 125 | + |
| 126 | +### D-ERROR-SWALLOW — RESOLVED S203k |
| 127 | +**Scope**: 4 production paths |
| 128 | +`.unwrap_or_default()` silent error swallowing evolved to `tracing::warn!` + fallback: |
| 129 | +`agents/manager.rs` (list_agents/list_models), `monitoring/platform.rs` (proc I/O reads), |
| 130 | +`pipeline.rs` (serde serialization), `hw_learn/status.rs` (recipe store open). |
| 131 | +Files: 4 handler/service modules. |
| 132 | + |
| 133 | +### D-DEAD-CODE-LINT — RESOLVED S203k |
| 134 | +**Scope**: 4 crates |
| 135 | +`#[allow(dead_code)]` evolved to `#[cfg_attr(not(test), expect(dead_code, reason = "..."))]` |
| 136 | +with documented reasons: `load_balancer.rs` (retry policy), `internal.rs` (ML selection), |
| 137 | +`mdns/service.rs` (reconfig path). `background/mod.rs` unused import cleaned via |
| 138 | +`#[cfg(test)]` gating. |
| 139 | + |
| 140 | +### D-LARGE-FILE-REFACTOR-S203K — RESOLVED S203k |
| 141 | +**Scope**: 4 production files across 3 crates |
| 142 | +Smart refactoring (not line splits) into cohesive submodules: |
| 143 | +- `edge/platforms/arduino.rs` (679L) → directory module: `device.rs`, `serial.rs`, |
| 144 | + `deploy.rs`, `edge_device.rs` (4 submodules) |
| 145 | +- `edge/discovery.rs` (644L) → directory module: `serial.rs`, `network.rs`, `usb.rs`, |
| 146 | + `bluetooth.rs`, `mdns.rs` (5 strategy modules) |
| 147 | +- `crypto_lock/access_control/manager.rs` (601L) → extracted `validation.rs` |
| 148 | + (delegation validation, resource limits, chain depth) |
| 149 | +- `security/policies/manager.rs` (546L) → extracted `cache.rs` (CachedPolicy, TTL) |
| 150 | + and `composition.rs` (merge/compose helpers) |
| 151 | + |
| 152 | +### D-ACTIVE-DEBT-CATALOG — RESOLVED S203k |
| 153 | +Cataloged 5 previously-undocumented active debt items with D- prefix: |
| 154 | +`D-SANDBOX-SIMULATION`, `D-PLUGIN-SIMULATE`, `D-BYOB-RESOURCE-SIM`, |
| 155 | +`D-WORKLOAD-CLIENT-IPC`, `D-HW-LEARN-VERIFY`. |
| 156 | + |
| 157 | +## S203j Resolved Debt (Deep Debt Execution: Idiomatic Evolution Pass) |
| 158 | + |
| 159 | +### D-ASYNC-WAVE3-ZERO-DYN — RESOLVED S203j |
| 160 | +**Scope**: Workspace | **Audit**: primalSpring async-trait migration (Class 4) |
| 161 | +Migrated 6 zero-dyn traits to native `async fn` in trait: `HealthMonitor` (byob), |
| 162 | +`SwapExecutor`, `DeviceDiscovery`, `HealthProbe` (glowplug), `CrossCompilationToolchain` |
| 163 | +(specialty, +3 impls), `GpuDiscovery` (gpu). 10 annotations removed. 5 crates freed |
| 164 | +from `async-trait` dep (`glowplug`, `monitoring`, `native`, `integration/security`; |
| 165 | +`container` → dev-dep). All use `#[expect(async_fn_in_trait)]` with documented reasons. |
| 166 | +Files: `byob/health_monitor.rs`, `glowplug/{swap,discovery,health}.rs`, |
| 167 | +`specialty/{types/cross_compilation,cross_compilation}.rs`, `gpu/glowplug/discovery.rs`, |
| 168 | +5× `Cargo.toml`. |
| 169 | + |
| 170 | +### D-UNSAFE-LINT-NVPMU — RESOLVED S203j |
| 171 | +**Crate**: `nvpmu` | **Audit**: unsafe code audit |
| 172 | +Removed 4 redundant `#[allow(unsafe_code)]` attributes from `init.rs` functions that |
| 173 | +contain zero `unsafe` blocks. The functions call `RecipeApplicator::apply()` through |
| 174 | +safe `RegisterAccess` trait — no unsafe needed. |
| 175 | +Files: `nvpmu/src/init.rs`. |
| 176 | + |
| 177 | +### D-HARDCODED-DRI-DEVICE — RESOLVED S203j |
| 178 | +**Crate**: `nvpmu` | **Audit**: hardcoding evolution |
| 179 | +Hardcoded `/dev/dri/card0` in 3 init functions evolved to `DEFAULT_DRI_DEVICE` constant. |
| 180 | +Documents future: accept device path as parameter for multi-GPU support. |
| 181 | +Files: `nvpmu/src/init.rs`. |
| 182 | + |
| 183 | +### D-ENV-RAW-STRINGS — RESOLVED S203j |
| 184 | +**Scope**: `primal_sockets` | **Audit**: hardcoding evolution |
| 185 | +30+ raw env var string literals in `SocketPathEnv::from_env()` evolved to interned |
| 186 | +constants in `socket_env::*`. Added `TOADSTOOL_TARPC_SOCKET` and 25+ connection hint |
| 187 | +constants (`TOADSTOOL_COORDINATION_ENDPOINT`, `LEGACY_SONGBIRD_URL`, etc.). |
| 188 | +Files: `interned_strings/socket_env.rs`, `primal_sockets/env.rs`. |
| 189 | + |
| 190 | +### D-DEPRECATED-STUBS — RESOLVED S203j |
| 191 | +**Scope**: `runtime/gpu`, `runtime/universal`, `distributed` |
| 192 | +Deprecated CUDA/OpenCL production stubs marked with `#[deprecated(since = "0.1.0")]`: |
| 193 | +`CudaBackend`, `OpenClBackend`, `OpenClComputeUnit`, unified memory `OpenClBackend`, |
| 194 | +OpenCL detection helpers. Compile-time deprecation replaces runtime-only error returns. |
| 195 | +Files: `cuda_impl/mod.rs`, `opencl_impl/mod.rs`, `unified_memory/backends/opencl.rs`, |
| 196 | +`universal/backends/opencl.rs`, `distributed/universal/detection/gpu.rs`. |
| 197 | + |
| 198 | +### D-PLATFORM-PATHS-CONSTANTS — RESOLVED S203j |
| 199 | +**Scope**: Workspace | **Audit**: hardcoding evolution |
| 200 | +Created `constants::platform_paths` module with organized constants for procfs |
| 201 | +(`CPUINFO`, `MEMINFO`, `LOADAVG`, cgroup paths), devfs (`KVM`, `DRI_DIR`, |
| 202 | +`VFIO_CONTAINER`), sysfs (`BUS_PCI_DEVICES`), etc paths (`OS_RELEASE`, |
| 203 | +`TOADSTOOL_DIR`, `RESOLV_CONF`), install paths (`OPT_TOADSTOOL`). Helper functions |
| 204 | +for dynamic `/proc/{pid}/` paths. ~20 call sites across 10 crates evolved. |
| 205 | +Files: new `constants/platform_paths.rs`, + ~15 production files. |
| 206 | + |
| 207 | +### D-HARDCODED-PRIMAL-NAMES-S203J — RESOLVED S203j |
| 208 | +**Scope**: Workspace | **Audit**: capability-based evolution |
| 209 | +Remaining hardcoded `"toadstool"` string literals in production code evolved to |
| 210 | +`PRIMAL_NAME` constant: `policies/types.rs`, `secret_string.rs`, `platform_paths/paths.rs`, |
| 211 | +`display/ipc/client/discovery.rs`, `integration/primals/primal_types.rs`, `config/lib.rs`. |
| 212 | +Files: 6 production files. |
| 213 | + |
| 214 | +### D-WORKSPACE-DEPS — RESOLVED S203j |
| 215 | +**Scope**: Workspace manifests |
| 216 | +Unified inline dependency versions to `workspace = true` across all workspace member |
| 217 | +crates. `tokio`, `serde`, `serde_json`, `async-trait`, `thiserror`, `tracing`, |
| 218 | +`tracing-subscriber`, `uuid`, `futures`, `regex` — all consolidated. Extra features |
| 219 | +preserved where needed (e.g. `serde = { workspace = true, features = ["rc"] }`). |
| 220 | +Files: ~20 `Cargo.toml` files. |
| 221 | + |
| 222 | +### D-MAGIC-NUMBERS — RESOLVED S203j |
| 223 | +**Scope**: Workspace | **Audit**: hardcoding evolution |
| 224 | +Magic numbers evolved to named constants: discovery fallback ports (`DEFAULT_COORDINATION_PORT`, |
| 225 | +`DEFAULT_SECURITY_PORT`, `DEFAULT_STORAGE_PORT`), BYOB config (`RESOURCE_MONITORING_INTERVAL_SECS`, |
| 226 | +`HEALTH_CHECK_INTERVAL_SECS`, `DEPLOYMENT_TIMEOUT_SECS`, named web port constants), |
| 227 | +policy defaults (`POLICY_CACHE_TTL_HOURS`, `DEFAULT_MAX_COMPOSITION_DEPTH`, |
| 228 | +`POLICY_VALIDATION_TIMEOUT_MS`). |
| 229 | +Files: `primal_discovery_complete/mod.rs`, `byob/config.rs`, `policies/types.rs`, |
| 230 | +`discovery_ports.rs`, `defaults/ports.rs`. |
| 231 | + |
| 232 | +### D-TARPC-CLIENT-SOCKET — RESOLVED S203j |
| 233 | +**Crate**: `client` | **Audit**: primalSpring downstream (socket unification) |
| 234 | +`ToadStoolTarpcClient::discover()` resolved to the JSON-RPC socket (`compute.sock`) |
| 235 | +instead of the tarpc socket (`compute-tarpc.sock`). Client connections to the wrong |
| 236 | +socket got binary/JSON protocol mismatch errors. |
| 237 | +**Fix**: Added `resolve_toadstool_tarpc_socket` to `primal_sockets` (mirrors server's |
| 238 | +`tarpc_socket_filename_for_family` convention), interned `TOADSTOOL_TARPC_SOCKET` env |
| 239 | +var, and wired `discover()` to `get_toadstool_tarpc_socket_path()`. +3 unit tests. |
| 240 | +Files: `primal_sockets/paths.rs`, `primal_sockets/env.rs`, `primal_sockets/api.rs`, |
| 241 | +`primal_sockets/mod.rs`, `interned_strings/socket_env.rs`, `client/tarpc_client.rs`. |
64 | 242 |
|
65 | 243 | ## S203 Resolved Debt (Deep Audit & Evolution Execution) |
66 | 244 |
|
|
0 commit comments