# 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:

| Entity                   | Key fields                                                          | State machine                      |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------- |
| Subject/Participant      | id, demographics (de-identified), consent refs, neural-data class   | —                                  |
| Study / Protocol         | id, hypotheses, preregistration lock, IRB-approval status           | IRB approval; preregistration lock |
| Session / Recording      | modality, channel geometry, sampling rate, reference, NWB/BIDS refs | acquisition lifecycle              |
| Signal / Channel         | modality, units, quality/impedance, provenance                      | —                                  |
| Stimulus / Trial         | paradigm, timing, condition, response                               | trial lifecycle                    |
| ConsentRecord            | broad/dynamic variant, scope, withdrawal, portability               | consent lifecycle                  |
| Assessment / Measurement | instrument & version, item scores, band, crisis flag                | —                                  |
| Hypothesis               | statement, novelty score, feasibility score, evidence paths         | —                                  |
| Experiment               | design spec, runtime config, analysis DAG, status                   | experiment lifecycle               |
| Claim                    | subject-predicate-object, evidence, support label, provenance       | —                                  |
| Dataset                  | source, modality, scale, access tier, FAIR metadata                 | —                                  |
| OntologyTermRef          | ontology, IRI, version, crosswalk mappings                          | —                                  |

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.