Phoebe Domain — Technical Specifications

Phase 181 in progress. This document specifies the intended API, data model, contracts, validation, testing, and operational requirements for the Phoebe brain-and-mind science platform. An initial slice already ships (see §1), but the domain is still largely pre-implementation, so most items below are a contract to implement in Phase 181 rather than a description of existing code. Where a concept is named without a concrete schema, it is described at the level Phase 181 commits to and not embellished.

1. Implementation Status#

Phoebe is partially implemented. Phase 181 (§181.1.1) targets thirty libs/phoebe/* libraries plus libs/contracts/phoebe/; four already exist (core, assessment, mbc, comp-psychiatry, ~1,992 non-test LOC), so the 30-library / libs/contracts/phoebe/ target is not yet reached, but packages do exist. Phoebe is a standalone domain that depends on Iris, Aphrodite, Psyche, the Phase 178 autonomous-research substrate, and Kalika via contracts; it does not move or absorb their code.

Polyglot stack (per the Oshun technology principles — TypeScript by default, Rust/C++ where performance requires it, WASM to bridge):

• TypeScript — orchestration, APIs, contracts, dashboards, consoles, and the knowledge/evidence services.
• Rust — the hard-real-time path: streaming DSP and artifact rejection, the decode→stimulate closed loop, the neuromodulation safety governor, and high-throughput connectome graph queries (GPU via wgpu).
• C/C++ — simulation kernels (CoreNEURON, Arbor) and device DSP / FFN inference.
• Python — ML and neuro/clinical pipelines (PyNWB, MNE-Python, SpikeInterface & Kilosort 4, NEST/NEURON/Arbor/Brian2, fMRIPrep/Nipype, DoWhy/causal-learn, Pyro for BOED, ADOpy, PsychoPy, neural-foundation-model training).
• WASM — the frame-precise browser experiment runtime (PsychoJS/PixiJS/ WebGPU) and Rust→TS bridging.

2. Persistence#

• phoebe PostgreSQL database (domain-isolated, per the monorepo convention) with TimescaleDB hypertables for neural and behavioural time-series and EMA, and pgvector for embeddings.
• Knowledge-graph store (Neo4j or RDF triplestore) schema-typed on the Biolink model.
• Object storage (MinIO/S3) with Zarr/OME-Zarr + Neuroglancer-precomputed for petascale imaging/connectomes and NWB (HDF5 + Zarr) for electrophysiology.
• Redis for real-time session/decoder state; Kafka for the neural / experiment / clinical event bus.

3. Canonical Data Model (@phoebe/core)#

The core entity set, each with explicit state machines:

The dimensional clinical model (RDoC 6 domains × 7 units of analysis; HiTOP spectra & p-factor) is a first-class, queryable structure, not free text.

4. Contracts (@phoebe/contracts)#

Zod-based contracts for every endpoint and cross-domain DTO. Phoebe publishes contracts for: neural-stream descriptors, decode results (with calibrated confidence), assessment results, hypotheses, experiment specs, claims, and dataset descriptors. Phoebe consumes contracts from: @iris/bci-* / @iris/multimodal-bci, @aphrodite/biometric-engine, Psyche affect & conversation, the Phase 178 autonomous-research substrate, and Kalika research-agent / notebook services. The global response convention requires a calibrated confidence and an explicit not_configured / insufficient_evidence / out_of_validated_scope seam — never a fabricated result.

5. Hard Requirements (cross-cutting invariants)#

1. Fail-loud uncertainty — every inference/decode/prediction carries calibrated uncertainty; out-of-scope requests return an explicit refusal.
2. Human-in-the-loop — no autonomous diagnosis, prescribing, or unsupervised therapy; patient-facing and human-subjects autonomous actions must pass a human checkpoint.
3. Append-only audit — stimulation events, data access, and autonomous actions are immutably logged.
4. Jurisdiction-aware compliance — feature availability is gated by the user's jurisdiction (Illinois/Nevada/Utah AI-therapy law; CO/CA/MT/CT/Chile neurorights).
5. Standards-native data — recordings are born NWB/BIDS/XDF-conformant with W3C-PROV/RO-Crate provenance.
6. Real-time safety — the decode→stimulate loop has bounded deadlines, a thermal/charge governor (≤0.5 °C), watchdogs, and a fail-safe stop.

6. Validation & Testing (Vitest & domain-correctness suites)#

Tests must assert domain correctness against known-correct values, not data flow. A decoder, twin, or scorer that returns random/fixed output must FAIL. Required suites mirror the acceptance gates in architecture.md: time-sync (sub-ms jitter), decoder benchmarks (chance-level floor for null decoders), stimulation safety (deadlines & hard caps & override), simulation interchange (cross-backend raster match), digital-twin uncertainty (explicit out-of-scope refusal), assessment scoring (published worked examples & crisis hard-trigger), adaptive-design (ADO efficiency reproduction; Type-I control), causal inference (refutation-before-claim), reproducibility (prereg-vs-execution auto-diff; one-command recompute), crosswalk resolution (DSM↔ICD↔MeSH↔SNOMED↔RDoC with provenance), GraphRAG verification (KG-absent triple filtered), governance (unconsented export blocked; immutable log), and the fail-closed AI-IRB (no enrollment without gate & human sign-off).

7. Operational Requirements#

• Latency SLAs on the real-time path (acquisition → DSP → decode → stim), surfaced in the Neural-Interface Control Room with device-health telemetry.
• Crisis backbone availability — 988/Samaritans routing is a high-availability dependency for any patient-facing surface.
• Regulatory lifecycle — model updates flow through a Predetermined Change Control Plan with bias/drift gates and automatic rollback; promotion is blocked on gate failure.
• Privacy-preserving compute — federated learning (NVIDIA FLARE / COINSTAC) and differential privacy (OpenDP) for multi-institution analysis; neural-data exports are consent- and jurisdiction-checked before they run.
• Process & memory hygiene — heavy simulation/connectomics/foundation-model jobs run under GPU/HPC scheduling with memory checkpointing and headroom guards.

8. Cross-Domain Integration (@phoebe/integration)#

Adapters (contract-bound; no re-implementation of the source domain's code): Iris (BCI device/HID), Aphrodite (biosignals incl. EEG), Psyche (affect + conversational delivery), Phase 178 / Nous (autonomous-research substrate & ML platform), Kalika (research agents & notebooks), and Mnemosyne / Maat / Veritas / Themis / Shared. Integration tests cover every adapter (minimum 200 cases) and assert that no Phoebe package re-implements Iris/Aphrodite/Psyche device or affect code.