Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
117 lines (78 loc) · 6.73 KB

DOCUMENTATION.md

File metadata and controls

117 lines (78 loc) · 6.73 KB

ToadStool Documentation Hub

Last Updated: April 9, 2026 — S198

Fossil Record

These root documents were fully resolved and fossilized in wateringHole (see ecoPrimals/infra/wateringHole/fossilRecord/toadstool/): UNSAFE_AUDIT_REPORT, SOVEREIGN_COMPUTE_GAPS, PURE_RUST_TRACKING, STATUS, EVOLUTION_TRACKER, QUICK_REFERENCE, SOVEREIGN_COMPUTE, SPRING_ABSORPTION_TRACKER, BREAKING_CHANGES — all renamed with _S166 suffix. Use those paths when citing historical audit, sovereign-gap, or pure-Rust tracking content.

Quick Navigation

I Want To... Document
Get started README.md
See active debt and evolution paths DEBT.md
Universal precision design specs/UNIVERSAL_PRECISION_ARCHITECTURE.md
Roadmap and next steps NEXT_STEPS.md
Full session-by-session changelog CHANGELOG.md
Hardware Transport Layer specs/HARDWARE_TRANSPORT_SPEC.md
Dual-Fabric Architecture specs/DUAL_FABRIC_ARCHITECTURE.md
GPU operations See barraCuda (ecoPrimals/barraCuda/)
FHE encryption docs/guides/QUICK_START_ENCRYPTION.md
Run tests docs/guides/TESTING.md
Deploy NPU drivers docs/guides/AKIDA_DRIVER_DEPLOYMENT.md
NPU driver design specs/NPU_DRIVER_ARCHITECTURE.md
Multi-tenant security specs/MULTITENANT_COMPUTE_ARCHITECTURE.md

Current State (S198 — April 9, 2026)

Post-budding, dependency-sovereign, IPC-first, fully concurrent. 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.

  • 21,600+ tests, 0 failures, 0 clippy warnings, 0 fmt diffs. Full workspace concurrent test suite. Net −5,157 lines across 228 files (S198 session batch).
  • ~67 JSON-RPC methods. Wire Standard L3 (partial): cost_estimates, operation_dependencies. IPC compliant (health.liveness → {"status":"alive"}, health.readiness → ready+version, health.check full envelope, capabilities.list, identity.get, socket at $XDG_RUNTIME_DIR/biomeos/toadstool.sock).
  • TS-01 / shader compiler discovery — visualization_client.rs uses unified capability.discover (no CORALREEF_* env, no coralreef-core.json, no coralreef dir scan).
  • BTSP Phase 2 — Handshake enforced on every UDS accept path (JSON-RPC + tarpc + daemon servers).
  • OpenCL deprecated — ocl removed; GPU OpenCL paths stubbed; GpuFramework::OpenCl retained as deprecated variant.
  • glowPlug/ember subsystem — toadStool-native hardware lifecycle (absorbed from coralReef). toadstool-glowplug, toadstool-ember, toadstool-hw-safe crates.
  • ~66 unsafe blocks (all in hw-safe/GPU/VFIO/display containment crates); S198 hardening (nvpmu ABI types, V4L2 fd checks, secure_enclave madvise). 41 crates forbid, 6 deny unsafe_code.
  • ecoBin v3.0 — Zero C FFI deps. Crypto delegated to security service. HTTP delegated to coordination service. Optional musl-static ~11MB x86_64 PIE binary validated (S198).
  • Capability-based discovery — Primals discover each other by capability, not name. Self-knowledge principle. S176–S198: struct fields, docs, SocketPathEnv / resolve_capability_socket_fallback, embedded thiserror stubs. ~400 intentional legacy-compat refs remain (serde aliases, env var fallbacks, parse_type).
  • Headless GPU — TOADSTOOL_HEADLESS=1 env var for pure headless operation. wgpu crash isolation via catch_unwind + thread timeout.
  • BTSP Tier 2 — validate_insecure_guard() at server startup (GAP-MATRIX-12). Family-scoped socket handshake on all transports (S198 completes UDS parity).
  • Fully concurrent tests — All tests run with unlimited parallelism. Zero #[serial]. Zero fixed sleeps in non-chaos tests.
  • AGPL-3.0-or-later — All Cargo.toml + all .rs files aligned. deny.toml enforced.

Core Documentation

README.md -- Project overview, architecture, quality gates, evolution roadmap.

DEBT.md -- Active debt register, workarounds, and evolution paths.

NEXT_STEPS.md -- Roadmap: active work, upcoming infrastructure, completed milestones.

CHANGELOG.md -- Full session-by-session evolution history.

Architecture and Specs

specs/ -- Technical specifications (FP64 evolution, hybrid core streaming, NPU, multi-tenant, cross-platform).

docs/architecture/ -- Design documents, ADRs, migration patterns.

Guides

docs/guides/TESTING.md -- Testing strategy: unit, integration, property-based, fault, chaos testing.

docs/guides/AKIDA_DRIVER_DEPLOYMENT.md -- NPU driver deployment.

BarraCuda guides have been fossilized to ecoPrimals/infra/wateringHole/fossilRecord/. See the barraCuda primal for current docs.

Scientific Middleware

Scientific computing middleware (linalg, numerical, special, stats, optimize, surrogate, sample, PDE) has moved to barraCuda (ecoPrimals/barraCuda/). Legacy API examples are preserved in the fossil record (ecoPrimals/infra/wateringHole/fossilRecord/toadstool/TOADSTOOL_QUICK_REFERENCE_S166.md).

By Role

ML/AI Engineers: README.md then see barraCuda (ecoPrimals/barraCuda/)

Computational Scientists: See barraCuda (ecoPrimals/barraCuda/) for scientific middleware

System Architects: README.md then specs/

DevOps Engineers: README.md then docs/guides/AKIDA_DRIVER_DEPLOYMENT.md

Directory Structure

README.md                  -- Project overview, honest status
DEBT.md                    -- Active debt register, evolution paths
NEXT_STEPS.md              -- Roadmap and upcoming work
CHANGELOG.md               -- Full session history
CONTEXT.md                 -- Public surface summary
DOCUMENTATION.md           -- This file (navigation hub)
docs/
  guides/                  -- Deployment and usage guides
  architecture/            -- Design documents and ADRs
  reference/               -- API reference, constants
specs/                     -- Technical specifications

Fossil record — 9 session trackers archived with _S166 suffix under ecoPrimals/infra/wateringHole/fossilRecord/toadstool/.