Skip to content

START_HERE.md

Latest commit

 

History

History
193 lines (155 loc) · 9.6 KB

START_HERE.md

File metadata and controls

193 lines (155 loc) · 9.6 KB

petalTongue -- Start Here

Updated: May 29, 2026 (Wave 61 — DH-1 /tmp cleanup, dep trim, TRUE PRIMAL fix, mock isolation)

Build & Run

cargo build --release

petaltongue ui                     # Desktop display (egui)
petaltongue tui                    # Terminal display (ratatui)
petaltongue web                                # Web interface — live dashboard (SSE topology)
petaltongue web --docroot /var/www/site        # Static file serving (sporePrint/Zola)
petaltongue web --docroot ./nb --strip-sources # Serve .ipynb as HTML, hide code cells
petaltongue web --docroot ./dist --spa         # SPA mode (missing paths → index.html)
petaltongue web --allowed-origins '*'          # CORS: allow all origins
petaltongue web --allowed-origins https://primals.eco,http://localhost:3000
petaltongue web --backend content-provider     # Content backend (GET / resolves via content.resolve)
petaltongue web --docroot ./public --ipc       # HTTP + IPC dual-port (NUCLEUS mode)
petaltongue web --docroot ./public --ipc --ipc-port 9900  # NUCLEUS full deployment
petaltongue web --cache-ttl 7200              # 2-hour Cache-Control on static files
petaltongue headless                           # Headless API server (no display)
# For CLI SVG/PNG/JSON export: cargo run -p petal-tongue-headless -- --mode svg -o out.svg
petaltongue server                             # IPC server (no display)
petaltongue server --socket /path              # IPC server (explicit UDS path)
petaltongue server --port 9090                 # IPC server (TCP on 127.0.0.1:9090)
petaltongue server --port 9090 --bind 0.0.0.0  # TCP on all interfaces (Docker)
petaltongue live                               # NUCLEUS interactive (IPC + GUI)
petaltongue live --port 9090                   # live mode with TCP listener
petaltongue live --port 9090 --bind 0.0.0.0    # live mode network-facing
petaltongue status                             # System info

# Global flags (apply to all subcommands):
petaltongue --socket /run/user/1000/biomeos/petaltongue.sock server
petaltongue --port 9090 web --docroot ./public
petaltongue --family-id nucleus01 live

Configuration

Priority: Environment > Config file > Defaults

export PETALTONGUE_WEB_PORT=8080
export PETALTONGUE_HEADLESS_PORT=9000
export BIOMEOS_NEURAL_API_SOCKET=/run/user/$(id -u)/biomeos-neural-api.sock
export BIOMEOS_SOCKET_DIR=/run/user/$(id -u)/biomeos  # DH-1: socket base dir

# JH-0 MethodGate authorization mode (default: permissive)
export PETALTONGUE_AUTH_MODE=enforced  # reject unauthenticated protected calls

# Web mode: serving, SPA, CORS, notebook rendering
export PETALTONGUE_DOCROOT=/var/www            # static file document root
export PETALTONGUE_SPA=true                    # SPA catch-all (index.html for missing paths)
export PETALTONGUE_ALLOWED_ORIGINS='https://primals.eco,http://localhost:3000'  # CORS
export PETALTONGUE_STRIP_SOURCES=true          # hide code cells in .ipynb rendering
export PETALTONGUE_CACHE_TTL=3600              # Cache-Control max-age (seconds)

# Tuning & timing (optional)
export PETALTONGUE_RPC_TIMEOUT_SECS=5
export PETALTONGUE_HEARTBEAT_INTERVAL_SECS=30
export PETALTONGUE_REFRESH_INTERVAL_SECS=2
export PETALTONGUE_DISCOVERY_TIMEOUT_SECS=5
export PETALTONGUE_TUI_TICK_MS=100
export PETALTONGUE_TELEMETRY_BUFFER=10000
export PETALTONGUE_RETRY_INITIAL_MS=100
export PETALTONGUE_RETRY_MAX_SECS=10
# $XDG_CONFIG_HOME/petaltongue/config.toml
[network]
web_port = 8080
headless_port = 9000

[discovery]
timeout_ms = 5000

Full reference: ENV_VARS.md

Development

cargo test --workspace --all-features           # 6,191+ tests
cargo clippy --workspace --all-features -- -D warnings
cargo fmt --check                               # Format check (clean)
cargo doc --workspace --no-deps                 # Docs (clean)
cargo llvm-cov --workspace --summary-only       # Coverage (~90% line)

Scenarios

petaltongue ui --scenario sandbox/scenarios/paint-simple.json
petaltongue ui --scenario sandbox/scenarios/healthspring-diagnostic.json

Architecture Rules

  1. Self-knowledge only -- petalTongue knows its own name, ports, and capabilities. Other primals discovered at runtime via capability-based discovery.
  2. Constants centralized -- All self-knowledge in petal_tongue_core::constants.
  3. IPC priority -- JSON-RPC 2.0 REQUIRED (Unix sockets / TCP listen surface), tarpc MAY for Rust-to-Rust hot paths, HTTP for external/browser access only.
  4. Typed error handling -- thiserror everywhere, no anyhow in production; deny(unwrap_used, expect_used) with #[expect] for justified cases.
  5. #![forbid(unsafe_code)] unconditional on all crates.
  6. Concurrent testing -- No thread::sleep. Use tokio::time::timeout.
  7. Files under 800 lines -- Smart domain refactoring into cohesive modules.
  8. Zero dyn -- Enum dispatch and generics for custom traits; dyn only for Error/closures.
  9. SPDX headers -- // SPDX-License-Identifier: AGPL-3.0-or-later on all .rs files.
  10. Semantic naming -- JSON-RPC methods follow {domain}.{operation} pattern.
  11. BTSP Phases 1-3 -- Phase 1: validate_insecure_guard() at startup; family-scoped sockets. Phase 2: security provider handshake delegation (UDS + TCP). Phase 3: ChaCha20-Poly1305 AEAD encrypted frame I/O after btsp.negotiate; 13/13 ecosystem parity.

Key Modules

Core (petal-tongue-core)

  • constants/ -- Centralized self-knowledge (name, ports, socket names); submodules: mod.rs, network.rs, display.rs, timeouts.rs, thresholds.rs, tufte_tolerances.rs
  • graph_engine/ -- Graph data model (nodes, edges, layout); submodules: mod.rs, types.rs, layout.rs, tests.rs
  • config_system/ -- XDG-compliant configuration (env > file > defaults); submodules: types.rs, loader.rs
  • data_channel.rs -- Re-exports DataBinding and ThresholdRange from petal-tongue-types (11 variants: TimeSeries, Distribution, Bar, Gauge, Spectrum, Heatmap, Scatter, Scatter3D, FieldMap, GameScene, Soundscape)
  • capability_names.rs -- Centralized capability/method/socket/primal constants (62+ capabilities, 2 self-knowledge identities)
  • sensory_matrix/ -- Sensory Capability Matrix (input×output negotiation); submodules: capability_sets.rs, matrix.rs
  • telemetry_adapter.rs -- JSONL telemetry ingestion (hotSpring)
  • or_exit.rs -- OrExit<T> trait for zero-panic validation binaries

IPC (petal-tongue-ipc)

  • unix_socket_server.rs -- JSON-RPC 2.0 server over Unix sockets
  • tarpc_client.rs -- tarpc binary RPC client
  • tarpc_types/ -- tarpc types split into submodules
  • socket_path.rs -- XDG-compliant socket path discovery
  • ipc_errors.rs -- IpcErrorPhase, StreamItem (NDJSON), DispatchOutcome<T>, exit_code, extract_rpc_error()
  • resilience.rs -- CircuitBreaker, RetryPolicy for IPC fault tolerance
  • discovery_helpers.rs -- Primal socket resolution, env var helpers

Discovery (petal-tongue-discovery)

  • lib.rs -- Provider discovery orchestrator
  • unix_socket_provider.rs -- Unix socket JSON-RPC discovery (universal fallback path)
  • neural_api_provider/ -- biomeOS Neural API discovery (provider, parse, tests)
  • discovery_service_client/ -- Discovery service capability queries (mod, protocol, methods)
  • discovery_service_provider.rs -- Discovery service visualization provider (topology inference)
  • jsonrpc_provider/ -- JSON-RPC visualization provider
  • mdns_provider/ -- mDNS/DNS-SD zero-config discovery (optional mdns feature)
  • capability_parse.rs -- 4-format capability parsing (flat, enriched, nested, result-wrapped)
  • cache.rs -- LRU discovery result cache
  • dns_parser/ -- Pure-Rust DNS packet parser (SRV, TXT, PTR, A records); submodules: header.rs, name.rs, record.rs

UI (petal-tongue-ui)

  • scene_bridge/paint/ (color, geometry, primitives)
  • device_panel/ (list_view, detail_view)
  • graph_editor/graph/ (validation, serialization)
  • app/init.rs + panel_init.rs, provider_init.rs, scenario_init.rs

Specs

Architectural specifications in specs/ -- read these before making major changes:

  • GRAMMAR_OF_GRAPHICS_ARCHITECTURE.md -- Next evolution (composable grammar)
  • UNIVERSAL_VISUALIZATION_PIPELINE.md -- Data→render pipeline
  • TUFTE_CONSTRAINT_SYSTEM.md -- Visualization quality constraints

Cross-Primal Integration

All cross-primal connections use capability-first discovery via biomeOS Neural API. petalTongue never hardcodes primal names in routing or socket resolution — names exist only in primal_names constants for logging context.

  • biomeOS -- Topology visualization (JSON-RPC), Neural API lifecycle
  • healthSpring -- Diagnostic data channels, clinical theme, streaming sessions
  • hotSpring -- JSONL telemetry ingestion to TimeSeries
  • neuralSpring -- Pipeline DAGs, diverging color scales
  • wetSpring -- Backpressure-aware streaming, Scatter 2D ordinations
  • ludoSpring -- 7 GameDataChannel types, 60 Hz sensor feed, GameScene/Soundscape rendering
  • Display backend -- Discovered via display capability (JSON-RPC/UDS primary, capability-discovered)
  • Audio backend -- Discovered via audio.play capability
  • GPU compute -- Discovered via compute.dispatch / physics-compute capabilities
  • Discovery service -- Discovered via discovery.query_capability
  • AI agent adapter -- ai_adapter (InputModality::Agent, AgentInputAdapter)

Inter-primal standards and handoff documents live in the ecoPrimals monorepo at infra/wateringHole/ (accessed via ../../infra/wateringHole/ from this repo's checkout location).

License

AGPL-3.0-or-later -- See LICENSE.