primalSpring

Coordination and composition validation spring for the ecoPrimals ecosystem.

Domain	Primal coordination, atomic composition, graph execution, emergent systems, multi-node bonding + federation
Version	0.9.25
Edition	Rust 2024 (1.87+)
License	AGPL-3.0-or-later
Tests	602+ lib (602 passed + 2 ignored; unit + integration + doc-tests + proptest)
Experiments	89 (20 tracks) — 21 absorbed as UniBin validation scenarios
Deploy Graphs	77 TOMLs — fragment-first composition with resolve = true (13 root + 9 profiles + 6 fragments + 8 spring validation + 5 multi-node + 5 bonding + 4 patterns + 4 desktop + 3 downstream + 2 spring deploy + 2 chaos + 2 cross-spring + 1 federation + 1 composition + 12 cell graphs)
Coverage	72.5% library line coverage (llvm-cov)
Compositions	Tower + Nest + Node + NUCLEUS + Graph Overlays + Squirrel Discovery + Graph Execution + Provenance Trio + Multi-Node Bonding + biomeOS Substrate + Cross-Gate + Deployment Matrix + Substrate Stress + Pure Composition (ludoSpring + esotericWebb as graph-defined products) + 7 Decomposed Subsystems (C1-C7) + Mixed Atomics (L2) + Bonding Patterns (L3) (87/87 gates). exp091 12/12 routing, exp094 19/19 parity, exp096 14/15 cross-arch (HSM cfg-gated)
Subsystems	C1: Render (petalTongue) + C2: Narration (Squirrel) + C3: Session (esotericWebb) + C4: Game Science (ludoSpring) + C5: Persistence (NestGate) + C6: Proprioception (petalTongue) + C7: Full Interactive
Provenance	All 89 experiments carry structured with_provenance() metadata
Clippy	0 warnings (pedantic + nursery + cast discipline + unwrap/expect discipline)
guideStone	Level 8 — live NUCLEUS (certification engine absorbed as UniBin organelle) (13/13 BTSP authenticated, BTSP alias routing + flex key resolution shipped), 41/41 bare, P3 CHECKSUMS (BLAKE3), seed provenance (Layer 0.5), BTSP default everywhere (Layer 1.5), cellular deployment (Layer 7, 8 cells BTSP-enforced), 46 cross-arch binaries (6 targets, Tier 1 39/39)
Unsafe	Workspace-level deny via [workspace.lints.rust] — zero unsafe blocks (SeedConfig + OnceLock replaced env::set_var)
C deps	Zero (ecoBin compliant, deny.toml enforced)

---

What Is primalSpring?

primalSpring is the spring whose domain IS coordination. Where other springs validate domain science (hotSpring validates physics, wetSpring validates biology), primalSpring validates the ecosystem itself — the coordination, composition, and emergent behavior that biomeOS and the Neural API produce when primals work together.

Its "papers" are the atomics. Its "experiments" are composition patterns. Its validation target is biomeOS itself.

Architecture

primalSpring/
├── ecoPrimal/                     # Library crate + UniBin binaries
│   ├── src/
│   │   ├── lib.rs                 # Library root (unsafe_code = deny)
│   │   ├── cast.rs                # Safe numeric casts (saturating boundary)
│   │   ├── coordination/          # Atomic composition, health probing, composition validation
│   │   ├── deploy/                # Deploy graph parsing, structural + live validation
│   │   ├── graphs/                # Graph execution pattern types (5 patterns)
│   │   ├── emergent/              # Emergent system validation (RootPulse, RPGPT, CoralForge)
│   │   ├── bonding/               # Multi-gate bonding models (Covalent, Metallic, Ionic, Weak, OMS) + graph metadata + STUN tiers
│   │   ├── ipc/                   # JSON-RPC 2.0 client, discovery, capability, error, dispatch, extract, resilience, transport, tcp, methods, probes, provenance, proptest, btsp_handshake
│   │   ├── launcher/              # Primal binary discovery, spawn, profiles, socket nucleation (sync biomeOS port)
│   │   ├── harness/               # Atomic test orchestration: spawn compositions, validate, RAII teardown
│   │   ├── niche.rs               # BYOB niche self-knowledge (capabilities, semantic mappings, registration)
│   │   ├── primal_names.rs        # Canonical slug constants, display names ↔ discovery slugs (neuralSpring pattern)
│   │   ├── validation/            # Experiment harness (check_bool, check_skip, check_relative, OrExit, ValidationSink, NdjsonSink, builder .run())
│   │   ├── tolerances/            # Named latency and throughput bounds
│   │   ├── certification/         # Certification engine (absorbed guidestone, L0-L8)
│   │   ├── validation/scenarios/  # 22 absorbed experiment scenarios (9 tracks)
│   ├── src/bin/
│   │   ├── primalspring/          # UniBin: certify + validate + serve + status + version
│   │   ├── primalspring_primal/   # Legacy RPC server (transitioning → primalspring serve)
│   │   ├── primalspring_guidestone/ # Legacy certification (transitioning → primalspring certify)
│   │   └── validate_all/          # Legacy meta-validator (transitioning → primalspring validate)
│   └── tests/
│       ├── integration/           # Shared test helpers (guards, spawn, RPC)
│       ├── server_integration.rs  # 10 core auto tests
│       ├── server_ecosystem.rs    # Tower atomic + Squirrel AI (#[ignore])
│       ├── server_ecosystem_songbird.rs  # Songbird IPC surface (#[ignore])
│       ├── server_ecosystem_genetics.rs  # Three-tier genetics (#[ignore])
│       ├── server_ecosystem_compose.rs   # Nest/Node composition (#[ignore])
│       └── server_ecosystem_overlay.rs   # Graph-driven overlays (#[ignore])
├── experiments/                   # 89 validation experiments (20 tracks)
├── config/                        # Launch profiles, deployment matrix, capability registry
├── graphs/                        # 77 deploy graph TOMLs (fragment-first composition)
│   ├── fragments/                # 6 atomic building blocks (tower, node, nest, nucleus, meta, provenance)
│   ├── profiles/                 # 9 thin compositions (fragment refs + delta nodes, resolve = true)
│   ├── patterns/                 # 4 coordination patterns: parallel, conditional, streaming, continuous
│   ├── bonding/                  # 5 bonding model graphs: ionic, metallic, OMS, defensive, albatross
│   ├── chaos/                    # 2 chaos engineering: partition recovery, slow start
│   ├── multi_node/               # 5 multi-node federation graphs
│   ├── spring_validation/        # 8 files: template + manifest + nucleus_atomics + crypto_negative + gaming_niche + domain_contract_sweep + content_pipeline_smoke + compute_trio_smoke
│   ├── spring_deploy/            # 2 files: template + manifest (5 springs parameterized)
│   ├── downstream/               # 3 TOML + 2 docs: template + manifest + healthspring_enclave
│   ├── cross_spring/             # 2 cross-spring validators
│   └── federation/               # 1 content distribution
├── docs/                          # Structured gap registry and subsystem documentation
│   └── PRIMAL_GAPS.md            # Per-primal gap inventory with severity and fix paths
├── tools/                         # Operational tooling
│   ├── nucleus_composition_lib.sh # Reusable NUCLEUS composition library (source from domain scripts)
│   ├── composition_template.sh   # Minimal starter skeleton for spring compositions
│   ├── composition_nucleus.sh    # Parameterized NUCLEUS launcher (replaces ad-hoc startup)
│   ├── ttt_composition.sh        # Reference implementation: Tic-Tac-Toe with full NUCLEUS
│   ├── ttt_nucleus.sh            # TTT-specific NUCLEUS launcher (uses composition_nucleus.sh pattern)
│   ├── nucleus_launcher.sh       # Start/stop/restart full NUCLEUS stack
│   ├── cell_launcher.sh          # Cell-graph deployment launcher
│   ├── ws_gateway.py             # Thin WebSocket-to-IPC bridge (no business logic)
│   └── validate_compositions.py  # Live subsystem composition validator (C1-C7)
├── web/
│   └── play.html                 # Composition monitor / debug dashboard (not primary UI)
├── niches/                        # BYOB niche deployment YAML
├── specs/                         # Architecture specs
└── wateringHole/                  # Docs and handoffs

Key Design Principles

• Capability-first discovery: No hardcoded primal rosters. Discovery is capability-based (via discover_by_capability()) or routed through the biomeOS Neural API substrate (via NeuralBridge). Deploy graphs use by_capability for loose coupling — callers ask for capabilities, not primal identities.
• Graphs as source of truth: Deploy graph TOMLs define what capabilities a composition needs. topological_waves() computes startup ordering from dependency edges. graph_required_capabilities() extracts the capability roster from graph nodes.
• Graceful degradation: Experiments honestly skip checks when providers aren't running — never fake a pass.
• Zero domain knowledge: primalSpring validates coordination, not math. Zero barraCuda, zero WGSL, zero domain science.
• BYOB niche model: Full self-knowledge via niche.rs — capabilities, semantic mappings, operation dependencies, cost estimates, and runtime registration with biomeOS.

Quick Start

# Build everything
cargo build --workspace

# Run all tests (auto + ignored live tests)
cargo test --workspace

# Fetch primal binaries from plasmidBin GitHub Releases (first time only)
./tools/fetch_primals.sh

# Run live atomic tests (requires fetched binaries)
cargo test --ignored

# Run all 89 experiments (meta-validator)
cargo run --release --bin validate_all

# Run exp001 with live primals (harness auto-starts them)
cargo run --bin exp001_tower_atomic

# Start the primalSpring JSON-RPC server
cargo run --bin primalspring_primal -- server

# Show ecosystem status
cargo run --bin primalspring_primal -- status

# === UniBin (eukaryotic) ===
# Run certification (absorbed guidestone)
cargo run --bin primalspring_unibin -- certify

# Run bare certification (no primals needed)
cargo run --bin primalspring_unibin -- certify --bare

# Run all validation scenarios (absorbed experiments)
cargo run --bin primalspring_unibin -- validate

# List available scenarios
cargo run --bin primalspring_unibin -- validate --list

# Filter by track or tier
cargo run --bin primalspring_unibin -- validate --track atomic-composition
cargo run --bin primalspring_unibin -- validate --tier rust

Code coverage (cargo-llvm-cov)

Install the tool (cargo install cargo-llvm-cov --locked or a release binary) and rustup component add llvm-tools-preview, then:

cargo coverage

This runs LLVM source-based coverage for the whole workspace, skips paths matching tests/ in the report. Release gate (scripts/validate_release.sh) enforces a 70% floor. For HTML output, run cargo llvm-cov --workspace --html (see upstream docs for --open, --lcov, CI, etc.).

Server Mode

The primalspring_primal binary exposes coordination capabilities via JSON-RPC 2.0:

Method	Description
health.check	Self health status
health.liveness	Kubernetes-style liveness probe
health.readiness	Readiness probe (Neural API + discovered primals)
capabilities.list	Niche capabilities + semantic mappings + cost estimates
coordination.validate_composition	Validate an atomic composition (capability-based by default)
coordination.validate_composition_by_capability	Explicitly capability-based validation
coordination.discovery_sweep	Enumerate capabilities in a composition
coordination.probe_capability	Probe a single capability provider
coordination.neural_api_status	Neural API reachability
graph.list	Structurally validate all deploy graphs
graph.validate	Validate a specific graph (structural or live)
graph.waves	Compute topological startup waves from a deploy graph
graph.capabilities	Extract required capabilities from a deploy graph
lifecycle.status	Primal status report
mcp.tools.list	MCP tool definitions for Squirrel AI

Deployment Matrix

primalSpring includes a deployment validation matrix (config/deployment_matrix.toml) that defines 43 test cells across architectures (x86_64, aarch64), topologies, network presets, and transport modes. Each cell validates a specific primal composition under specific conditions.

# Run all cells (dry-run to see what would execute)
scripts/validate_deployment_matrix.sh --dry-run --all

# Run a specific cell
scripts/validate_deployment_matrix.sh --cell tower-x86-homelan

# Run all cells in an experiment group
scripts/validate_deployment_matrix.sh --tier docker

Topology categories: Tower (2-node), NUCLEUS (3-node), Federation (10-node), Bonding (ionic, metallic, OMS), Showcase (fieldMouse, Albatross, skunkBat, neuromorphic, gaming), Agentic (biomeOS+Squirrel+petalTongue), Storytelling (esotericWebb+ludoSpring+Squirrel+petalTongue).

Deploy Graphs

primalSpring ships 77 deploy graph TOMLs using fragment-first composition (all nodes declare by_capability):

Root-level graphs (13):

Graph	Pattern	Primals
tower_atomic_bootstrap.toml	Sequential	beardog, songbird, skunkbat
tower_ai.toml	Sequential	beardog, songbird, squirrel
tower_ai_viz.toml	Sequential	beardog, songbird, squirrel, petaltongue
node_atomic_compute.toml	Sequential	beardog, songbird, toadstool
node_ai.toml	Sequential	beardog, songbird, toadstool, squirrel
nest_viz.toml	Sequential	beardog, songbird, nestgate, petaltongue
nucleus_complete.toml	Sequential	biomeos, beardog, songbird, skunkbat, nestgate, toadstool, squirrel (+compute trio +provenance trio)
provenance_overlay.toml	Sequential	beardog, songbird, rhizocrypt, loamspine, sweetgrass
coralforge_pipeline.toml	Pipeline	beardog, songbird, nestgate, toadstool, sweetgrass
hotspring_qcd_pipeline.toml	Pipeline	hotSpring QCD composition
neuralspring_inference_pipeline.toml	Pipeline	neuralSpring ML inference composition
healthspring_clinical_pipeline.toml	Pipeline	healthSpring clinical composition
spring_byob_template.toml	Sequential	template for new springs

Multi-node federation graphs (5) — graphs/multi_node/:

Graph	Scenario	Bond Type	Trust Model
basement_hpc_covalent.toml	LAN HPC mesh	Covalent	GeneticLineage
friend_remote_covalent.toml	Remote friend + NAT traversal	Covalent	GeneticLineage
idle_compute_federation.toml	Federated idle compute sharing	Covalent	GeneticLineage
data_federation_cross_site.toml	NestGate cross-site replication	Covalent	GeneticLineage
three_node_covalent_cross_network.toml	3-node cross-network mesh	Covalent	GeneticLineage

Spring validation graphs (8) — graphs/spring_validation/: parameterized spring_validate_template.toml + spring_validate_manifest.toml (9 compositions covering all 7 springs plus products), nucleus_atomics_validate.toml (all 4 NUCLEUS tiers), crypto_negative_validate.toml (negative security boundary tests), gaming_niche_validate.toml (ludoSpring gaming niche validation), domain_contract_sweep.toml (cross-domain method exercise), content_pipeline_smoke.toml (NestGate content round-trip), and compute_trio_smoke.toml (compute trio health + capabilities + math + sovereign dispatch). All graphs include biomeOS Neural API as orchestration substrate.

Composition graphs (1) — graphs/compositions/: foundation_validation.toml — full NUCLEUS composition for scientific validation via the foundation sediment pipeline (12 nodes, 3 optional with fallback = "skip"). Purpose: "foundation".

Cross-spring graphs (2) — graphs/cross_spring/: ecology validation (ET₀ → diversity → spectral) and full sweep across all springs.

Bonding model graphs (5) — graphs/bonding/: ionic capability sharing, metallic GPU pool, organo-metal-salt complex, defensive mesh (skunkBat), Albatross multiplex (Songbird fleet).

Chaos engineering graphs (2) — graphs/chaos/: network partition recovery and slow-start composition convergence.

Spring deploy graphs (2) — graphs/spring_deploy/: parameterized template + manifest covering 5 per-spring science compositions. Each includes biomeOS Phase 0 substrate, Tower base, optional ToadStool for GPU-compute springs, and the spring primal.

Downstream graphs (3) — graphs/downstream/: parameterized template + manifest for 7 proto-nucleate compositions, plus healthspring_enclave_proto_nucleate.toml (unique dual-tower ionic bridge pattern).

Patterns (4) — graphs/patterns/: streaming pipeline, continuous tick, parallel capability burst, conditional fallback.

All graphs have by_capability on every node and are structurally validated + topologically sorted at test time. Multi-node graphs include [graph.metadata] and [graph.bonding_policy] sections validated by graph_metadata.rs.

IPC Resilience

Converged IPC resilience stack absorbed from 7 sibling springs: IpcError (8 typed variants with is_retriable(), is_recoverable(), is_timeout_likely(), etc.), CircuitBreaker, RetryPolicy, resilient_call(), DispatchOutcome<T>, Transport enum (Unix + Tcp), normalize_method() for prefix-agnostic dispatch, OnceLock-cached runtime probes, and centralized extract_rpc_result / extract_rpc_dispatch for JSON-RPC result extraction. Capability parsing handles all 4 ecosystem wire formats (A/B/C/D). Provenance trio calls use an epoch-based circuit breaker with exponential backoff (absorbed from healthSpring V41).

Discovery (6-Tier)

Discovery walks 6 tiers in priority order:

1. {PRIMAL}_SOCKET env override
2. $XDG_RUNTIME_DIR/biomeos/{primal}-{family}.sock (XDG convention)
3. Plain socket name: {primal}.sock or {primal}-ipc.sock
4. {temp_dir}/biomeos/{primal}-{family}.sock (temp fallback)
5. Primal manifest: $XDG_RUNTIME_DIR/ecoPrimals/manifests/{primal}.json
6. Socket registry: $XDG_RUNTIME_DIR/biomeos/socket-registry.json

Tiers 5–6 absorbed from biomeOS v2.50 and Squirrel alpha.12.

MCP Tools

primalSpring exposes 8 typed MCP tools via mcp.tools.list for Squirrel AI coordination tool discovery. Each tool has a JSON Schema input definition.

Live Atomic Harness

primalSpring absorbs primal coordination from biomeOS — binary discovery, socket nucleation, process spawning, and wave-based startup — ported to pure synchronous Rust (std::process + std::thread, no tokio).

Module	Responsibility
launcher/	discover_binary(), spawn_primal(), spawn_biomeos(), wait_for_socket(), SocketNucleation, LaunchProfile, LaunchError (incl. HealthCheckFailed)
harness/	AtomicHarness::new() / ::with_graph(), .start() (topological waves), .start_with_neural_api(), RunningAtomic (capability-based socket_for / client_for, RAII lifecycle, NeuralBridge)

Run ./tools/fetch_primals.sh to bootstrap primal binaries into ~/.local/share/ecoPrimals/plasmidBin/. Override with ECOPRIMALS_PLASMID_BIN if needed. Without fetched binaries, experiments fall back to discovering whatever is already running.

gen4 Deployment Evolution

primalSpring validates the biomeOS substrate model end-to-end: biomeOS as the neural-api orchestrator, capability routing across primals (crypto, beacon, mesh, AI, visualization), and cross-gate deployment to heterogeneous hardware.

Phase 18 (done): Full NUCLEUS deployed and validated on Eastgate (biomeOS + BearDog + Songbird + NestGate + Squirrel, all running concurrently under seed-derived FAMILY_ID 8ff3b864a4bc589a). Cross-gate federation: Pixel Songbird TCP via ADB port forwarding, registered on Eastgate biomeOS via route.register. Mobile SELinux gap documented — GrapheneOS blocks sock_file creation for shell context, requiring TCP-only transport modes for all primals on Android.

Phase 17 (done): biomeOS neural-api validated on Eastgate in coordinated mode with 24 capability domains and 39 deploy graphs. Cross-gate routing to Pixel via ADB-forwarded TCP. Squirrel AI primal validated. Spring deploy sweep confirms all 7 sibling springs' biomeOS graphs load correctly.

gen4 prototypes (archived to fossilRecord/stale_graphs_apr12_2026/gen4/): sovereign tower (Dark Forest ready), science substrate (multi-spring pipeline), agentic tower (AI-orchestrated), interactive substrate (full UI + AI + crypto + mesh surface), spring composition (Tower + biomeOS + 5 spring primals + cross-spring capability routing).

Spring Gen4 Scaffolding (Phase 19): 5 of 6 spring primal binaries built and deployed to plasmidBin/springs/ (groundspring, healthspring_primal, ludospring, neuralspring, wetspring). All spring validation graphs updated to deploy biomeOS as substrate. Launch profiles added for all 6 springs.

See specs/CROSS_SPRING_EVOLUTION.md for full evolution path.

Phase 56: Desktop Substrate + The Rhizome (April 28, 2026)

• 8 new experiments (exp099–exp106) across Track 18 — Desktop Substrate:
  • exp099: Agentic loop substrate (petalTongue ↔ biomeOS ↔ Squirrel feedback loop)
  • exp100: MCP ecosystem tools (Squirrel tool.list across springs)
  • exp101: fieldMouse AI triage (sensor → NestGate → Squirrel → petalTongue)
  • exp102: Storytelling session loop (esotericWebb → ludoSpring → Squirrel → petalTongue → trio)
  • exp103: ludoSpring expanded IPC (14 IPC methods esotericWebb needs)
  • exp104: RPGPT provenance replay (DAG → ledger → replay verification)
  • exp105: The Rhizome micro-game — full roguelike loop on NUCLEUS (Barracuda noise, game loop, save/load, provenance, narration)
  • exp106: Micro-desktop shell — desktop composition wrapping The Rhizome (biomeOS routing, 12/13 primal health bar, multi-session petalTongue, provenance sidebar)
• 4 desktop app deploy graphs: desktop_shell.toml, app_esotericwebb.toml, app_system_monitor.toml, app_rhizome.toml — biomeOS-managed desktop applications with continuous coordination
• desktop_nucleus.sh: 13-primal NUCLEUS launcher with auto-symlink for petalTongue discovery, FAMILY_ID management, validate mode
• Live gap harvesting: 23 gaps documented in fossilRecord/wateringHole_phase56_apr2026/LIVE_DEPLOYMENT_GAP_REPORT_PHASE56.md — socket naming, capability routing, IPC parameter schemas, biomeOS graph parser inconsistencies
• Provenance trio E2E fully resolved: rhizoCrypt DAG + loamSpine ledger + sweetGrass attribution — all parameter schemas documented and corrected
• The Rhizome: Procedural roguelike game running on NUCLEUS — Barracuda Perlin noise for biome generation, deterministic floor layout, 5 biome types, creature/item systems, TOML save format, gap-tolerant validation

BTSP, Inference Abstraction, and Proto-Nucleate Graphs (April 10, 2026)

• Zero-Port Tower Atomic achieved: 0 TCP ports across all 10+ primals. Pure Unix domain socket IPC with BTSP handshake authentication.
• BTSP Phase 2 ecosystem cascade → Phase 3 full convergence (May 2, 2026): 13/13 capabilities BTSP-authenticated (was 5/13 pre-escalation). Phase 3 ChaCha20-Poly1305 AEAD achieved across all 13 primals — every primal ships btsp.negotiate returning cipher: "chacha20-poly1305" with HKDF-SHA256 key derivation and encrypted framing wire format. JSON-line BTSP auto-detection wired in all relay primals. Phase 45c resolved final upstream debt: Songbird SecurityRpcClient::new_direct() (Wave 169), ToadStool post-handshake connection persistence, loamSpine btsp.negotiate non-fatal fallback, petalTongue BearDog field alignment. Client-side ipc::btsp_handshake module with 15-second relay timeout. upgrade_btsp_clients() two-pass strategy (cleartext probe + BTSP-first for enforcing primals). All deploy graphs carry secure_by_default = true metadata.
• Inference provider abstraction: Vendor-agnostic inference.complete/embed/models wire standard in ecoPrimal. Squirrel bridge routes through AiRouter (Ollama as OpenAI-compatible HTTP endpoint). No vendor lock-in to CUDA or Ollama.
• WGSL shader composition model: ML inference, QCD physics, and biology are compositions of existing barraCuda WGSL shaders (826 kernels: matmul, attention, FFT, df64) compiled by coralReef and dispatched by toadStool.
• 5 proto-nucleate graphs (graphs/downstream/): neuralSpring ML inference, hotSpring QCD (metallic GPU pool, df64, provenance), healthSpring dual-tower enclave (ionic bond, egress fence, clinical AI).
• 3 pipeline graphs: neuralSpring inference pipeline, hotSpring QCD pipeline, healthSpring clinical pipeline — modeling end-to-end data flow through primal compositions.
• 13/13 critical experiments ALL PASS — 89 total experiments across 19 tracks.
• 46 cross-architecture binaries (6 target triples, Tier 1 39/39) — genomeBin v5.1, zero C dependencies.

Fragment-First Graph Consolidation (April 16, 2026)

• 78 → 56 deploy graph TOMLs: Eliminated isomorphic duplication through template+manifest parameterization and fragment-first resolve = true composition.
• Template+manifest pattern: Spring validation (13 → 4: template + manifest + 2 unique), spring deploy (5 → 2: template + manifest), downstream proto-nucleate (7 → 3: template + manifest + healthspring enclave).
• Fragment resolution in load_graph(): Profiles declaring resolve = true in [graph.metadata] inherit nodes from graphs/fragments/*.toml as a base layer, then apply only their delta nodes. Profiles trimmed from ~40 lines to ~15 lines each.
• Removed: primalspring_deploy.toml (absorbed into nucleus_complete.toml), full_overlay.toml (absorbed into profiles/full.toml), fossilRecord/graphs/ stale snapshots, 9 per-spring validation wrappers, 5 per-spring deploy files, 7 individual proto-nucleate files.
• Zero-regression: All 631 tests at time of consolidation (585 passed + 46 ignored), 0 clippy warnings. Current: 687 tests (635 passed + 52 ignored).

Graph Consolidation + Composition Evolution (April 9, 2026)

• ludoSpring and esotericWebb evolved to pure compositions: No longer spawnable binaries — the graph IS the product, biomeOS IS the execution engine. All prior "binary" work is validation that proves composition patterns work.
• 6 atomic-aligned fragments (graphs/fragments/): tower_atomic (electron), node_atomic (proton), nest_atomic (neutron), nucleus (full atom), meta_tier (cross-atomic), provenance_trio (Nest sub-pattern) — aligned to the 3 NUCLEUS atomics.
• 7 graphs deleted (5 redundant sketches + 2 duplicate compositions): ludospring_game_deploy, esotericwebb_tower_deploy, game_science_standalone, session_standalone, esotericwebb_composed_deploy, render_standalone, tower_ai_viz.
• 10 graphs rewritten: 2 proto-nucleates + 8 science/gen4/sketch graphs — all ludo/webb binary nodes replaced with constituent NUCLEUS primals.
• 100% fragment + composition_model metadata: Every deploy graph annotated with fragments and composition_model (pure/nucleated/validation).
• Gen4 naming normalized: All 10 gen4 graphs use canonical biomeos_neural_api node name.
• Deploy graph count: 100 → 93 (+ 6 atomic-aligned fragment definitions). 8 root-level subset graphs → 9 profiles. 6 per-spring validates → 1 template + manifest. 3 compositions absorbed. hotspring_deploy merged into proto-nucleate. 4 execution patterns moved to patterns/.

Mixed Composition + Live Validation Matrix (April 7, 2026)

• Particle model adopted: Tower = electron (trust boundary, mediates bonds), Node = proton (compute, fungible), Nest = neutron (data at rest, non-fungible), NUCLEUS = atom. Grounded in Paper 23 (Mass-Energy-Information Equivalence). See specs/MIXED_COMPOSITION_PATTERNS.md.
• Layered validation framework: L0 (biomeOS + any primal), L1 (each atomic), L2 (mixed atomics), L3 (bonding patterns on top of atomics). Full NUCLEUS Validation Matrix at specs/NUCLEUS_VALIDATION_MATRIX.md.
• 12 sketch graphs (archived to fossilRecord/stale_graphs_apr12_2026/sketches/): L0 primal routing matrix, L2 dual-tower ionic / dedicated tower / nest enclave, L3 covalent mesh backup / ionic lease / organo-metal-salt.
• 3 new experiments (exp091–093): L0 primal routing matrix, L2 dual-tower ionic structural, L3 covalent mesh backup structural.
• Live validation on Eastgate: Tower Atomic (BearDog + Songbird) fully validated — crypto, HTTPS, discovery all LIVE PASS. Neural API running, capability registration resolved (GAP-09 shipped in biomeOS v3.51 method.register). All 6 GAP-MATRIX items from Phase 56 are now resolved or superseded by eukaryotic architecture.

Modernization Sweep (April 7, 2026)

• Graph format unified: All 92+ graphs migrated from [[graph.node]] to canonical [[graph.nodes]]. Parser accepts both via serde alias; GraphMeta gains optional id field for biomeOS GraphId compatibility.
• Capability names canonical: dag.dehydration.trigger, dag.session.create, dag.event.append, dag.merkle.root, session.commit, entry.append — cleaned across 17 graph files, capability_registry.toml, and niche.rs.
• http_health_probe deprecated: All primals expose JSON-RPC health.liveness. Four experiments (exp073, exp074, exp076, exp081) updated to use tcp_rpc instead.
• nest-deploy.toml v4.0: Gold standard graph — BearDog + Songbird + NestGate + Squirrel + HTTPS validation phase + composition validation.
• exp090 Tower Atomic LAN probe: BirdSong mesh discovery, peer capability enumeration, HTTPS through Tower Atomic, STUN/NAT detection.
• exp073 covalent bonding modernized: Neural API routing validation, FAMILY_ID genetic lineage, end-to-end HTTPS.
• Basement HPC graph aligned: basement_hpc_covalent.toml updated with canonical capability names and HTTPS validation phase.
• NA-009, NA-016 resolved in specs/CROSS_SPRING_EVOLUTION.md.

Live Composition Validation (April 1, 2026)

7 decomposed subsystem compositions validated independently against live stack:

Composition	Result	Notes
C1: Render (petalTongue)	6/6 PASS	Dashboard render, SVG export, SceneGraph storage, session awareness
C2: Narration (Squirrel)	3/4 PARTIAL	SQ-02 resolved (code wired); ai.query fails only because no local Ollama running
C3: Session (esotericWebb)	8/8 PASS	Full session lifecycle, actions, act, graph
C4: Game Science (ludoSpring)	6/6 PASS	Flow, Fitts, WFC, engagement
C5: Persistence (NestGate)	5/5 PASS	Store, retrieve round-trip, list with family_id
C6: Proprioception (petalTongue)	5/5 PASS	Subscribe, apply, poll, showing
C7: Full Interactive	10/10 PASS	Full cross-subsystem: session→render→export, game science, Squirrel health, NestGate

43/44 (98%) — up from 93%. See docs/PRIMAL_GAPS.md for the structured gap registry (6 LOW, zero critical).

Live Integration Status (March 28, 2026)

Primal	Eastgate	Pixel (ADB)	Notes
BearDog	healthy v0.9.0 (Unix socket)	BLOCKED (no TCP mode)	Needs --listen for Android SELinux
Songbird	healthy v0.2.1 (Unix socket + mesh)	healthy v0.1.0 (TCP :9901)	--listen works on Android
NestGate	healthy (Unix socket, store/retrieve)	not deployed	Needs --listen for Android
Squirrel	alive v0.1.0 (abstract @squirrel)	not deployed	Abstract sockets TBD on Android
biomeOS	neural-api (39+ graphs, route.register)	BLOCKED (forces Unix socket)	api --port ignored
ToadStool	structural	not deployed	CLI-only, no server

Cross-gate federation: Pixel Songbird registered on Eastgate biomeOS as gate: pixel8a with capabilities [network, discovery, http, mesh, birdsong]. ADB forwards Pixel TCP 9901 → Eastgate 19901 for JSON-RPC IPC.

See fossilRecord → springs/primalSpring/wateringHole_phase58_59_may2026/ for the full cross-gate SELinux gap analysis and per-primal remediation plan (archived from March 2026 mobile deployment spike).

Docs

• wateringHole/README.md — Outward-facing guidance index
• ARCHITECTURE.md — UniBin cell model, two-tier validation, organelle map
• wateringHole/PRIMALSPRING_V0925_EVOLUTION_HANDOFF_MAY09_2026.md — v0.9.25 evolution handoff (primals, springs, NUCLEUS)
• wateringHole/CROSS_SPRING_PARITY_HANDOFF_MAY08_2026.md — Cross-spring parity audit
• wateringHole/CRYPTO_CONSUMPTION_HIERARCHY.md — Crypto posture per primal role
• wateringHole/METHOD_GATE_STANDARD.md — MethodGate pre-dispatch authorization standard (JH-0)
• specs/CROSS_SPRING_EVOLUTION.md — Evolution path (Phase 0–25+ done — live validation matrix, GAP-MATRIX items all resolved)
• specs/NUCLEUS_VALIDATION_MATRIX.md — NUCLEUS capability validation matrix with particle model
• specs/MIXED_COMPOSITION_PATTERNS.md — Particle model, layered validation (L0-L3), gap inventory, spring specialization guide
• specs/TOWER_STABILITY.md — 87-gate acceptance criteria and progression
• specs/CAPABILITY_ROUTING_TRACE.md — Hardcoded → semantic routing evolution (incl. gen4 categories 8–11)
• specs/GEN4_COMPOSITION_AUDIT.md — Shortcomings audit: primalSpring vs esotericWebb gen4 needs
• specs/PAPER_REVIEW_QUEUE.md — Coordination patterns ready for validation
• specs/BARRACUDA_REQUIREMENTS.md — barraCuda relationship (indirect only)
• specs/AGENTIC_TRIO_EVOLUTION.md — biomeOS + Squirrel + petalTongue evolution guidance for the agentic loop
• specs/STORYTELLING_EVOLUTION.md — ludoSpring + esotericWebb evolution for AI DM storytelling
• specs/RHIZOME_MICRO_GAME.md — The Rhizome roguelike game spec: world gen, biomes, tile rendering, save format, primal usage
• specs/MICRO_DESKTOP_COMPOSITION.md — Micro-desktop shell: layout, session model, provenance sidebar
• specs/DESKTOP_NUCLEUS_DEPLOYMENT.md — Desktop NUCLEUS deployment spec
• specs/DESKTOP_SESSION_MODEL.md — Desktop session model (petalTongue + biomeOS)
• specs/LIVE_GUI_COMPOSITION_PATTERN.md — Live GUI composition patterns
• specs/SHOWCASE_MINING_REPORT.md — Showcase patterns mined from primals for substrate validation
• config/deployment_matrix.toml — 43-cell deployment validation matrix
• whitePaper/baseCamp/README.md — baseCamp paper pointer

Scripts and Tools

scripts/ (11 files) — build, validation, and deployment:

Script	Purpose
scripts/validate_release.sh	Release quality gate: fmt + clippy + deny + test floor (400+) + docs
scripts/validate_deployment_matrix.sh	Run deployment matrix cells: topology × arch × preset × transport validation
scripts/validate_composition.sh	Validate NUCLEUS composition health and binary presence
scripts/validate_local_lab.sh	Quick local lab validation for benchScale topologies
scripts/validate_remote_gate.sh	Probe a remote gate's NUCLEUS health via TCP JSON-RPC
scripts/build_ecosystem_genomeBin.sh	Build all primals across the full genomeBin target matrix (9 targets, 3 tiers)
scripts/build_ecosystem_musl.sh	Legacy musl-only build (x86_64 + aarch64); superseded by genomeBin script
scripts/prepare_spore_payload.sh	Assemble USB spore deployment payload (binaries + graphs + scripts + genetics)
scripts/chaos-inject.sh	Inject chaos conditions (partition, kill, disk-fill, slow DNS, clock drift)
scripts/pixel_cross_arch_lab.sh	Cross-arch validation lab for Pixel/Android targets
scripts/lan_covalent_lab.sh	LAN covalent bonding lab for multi-node federation

tools/ (24 files) — operational tooling for NUCLEUS composition, method auditing, and desktop:

Tool	Purpose
tools/nucleus_composition_lib.sh	Reusable NUCLEUS composition library (sourced by domain scripts)
tools/nucleus_launcher.sh	Start/stop/restart full NUCLEUS stack
tools/desktop_nucleus.sh	13-primal NUCLEUS launcher with auto-symlink for petalTongue discovery
tools/check_method_coverage.sh	Inverse drift: flag 413-registry methods never exercised in scenarios/tests/graphs
tools/check_method_gate.sh	Verify MethodGate pre-dispatch authorization compliance
tools/check_method_strings.sh	Audit method string literals against canonical registry
tools/check_graph_methods.sh	Verify deploy graph nodes reference valid registry methods
tools/fetch_primals.sh	Bootstrap primal binaries from plasmidBin GitHub Releases
tools/regenerate_checksums.sh	Regenerate BLAKE3 checksums for local validation assets
tools/validate_compositions.py	Live subsystem composition validator (C1-C7)
tools/ws_gateway.py	Thin WebSocket-to-IPC bridge (no business logic)

---

License: AGPL-3.0-or-later