# Phoebe Domain - Architecture

> Planned Brain-Computer Interface, Neuroscience, Clinical Psychology &
> Autonomous Discovery Platform (TODO Phase 181)

Phoebe is the Oshun domain for the science and medicine of the brain and mind.
It spans five frontier fields and the connective tissue between them:
brain-computer interfaces (BCI), computational and systems neuroscience,
clinical psychology and psychiatry, the AI-driven design and execution of
experiments on brains and behaviour, and a unified knowledge graph linking
molecules → cells → circuits → cognition → behaviour → disorders. Every layer is
AI-integrated, and every layer is built to one standard: read biological reality
honestly, report uncertainty loudly, keep a qualified human in the loop wherever
a living brain or a patient is involved, and turn passive observation into
causal, model-driven discovery.

The domain is **planned-only**. No `libs/phoebe/*` or `apps/phoebe/*` packages
exist in the monorepo yet. All design detail here belongs to **TODO Phase 181
(§181.1.1)**, which creates the workspace and implements the platform from
scratch. This document captures the intended topology, layer structure, and
ownership boundaries so implementation can begin against a defined contract
rather than an empty namespace.

## Status

Planned-only domain. No workspace packages exist yet. Phoebe is a **standalone
domain that depends on existing assets** (Iris, Aphrodite, Psyche, the Phase 178
autonomous-research substrate, Kalika) **via contracts**; it does not move or
absorb their code.

## Planned Workspace Shape

Phase 181 (§181.1.1) creates thirty `libs/phoebe/*` libraries plus a
`libs/contracts/phoebe/` contracts package. The application suite (Researcher
Workbench, Clinician Console, Neural-Interface Control Room, Knowledge Explorer,
Participant/Patient app) lives inside `libs/phoebe/apps/` (§181.30); there are
no standalone `apps/phoebe/*` projects in the planned scope.

```text
libs/phoebe/
  core/                  # domain primitives, RDoC/HiTOP dimensional model, state machines
  neural-io/             # multimodal acquisition & LSL/XDF sub-ms time-sync
  signal/                # real-time DSP (Rust): ICA/CSP/xDAWN/Riemannian
  decoding/              # decoder runtime, neural foundation models, cross-subject adaptation
  neuromodulation/       # closed-loop aDBS/RNS/tFUS/TI, read–write, safety governor
  connectomics/          # FFN segmentation, CAVE proofreading, petascale graph serving
  simulation/            # NEST/NEURON/Arbor/Brian2 over SONATA, multi-scale co-sim
  brain-models/          # brain foundation models & circuit/region digital twins
  neuro-analysis/        # SpikeInterface/Kilosort, LFADS/CEBRA, manifolds
  assessment/            # PHQ-9/GAD-7/PCL-5/C-SSRS & DSM-5-TR/ICD-11 coding
  mbc/                   # measurement-based & collaborative care
  phenotyping/           # passive sensing, EMA, voice biomarkers, JITAI
  comp-psychiatry/       # RDoC/HiTOP models, biotypes, treatment matching
  therapeutics/          # CBT/DBT/ACT/MI content, anti-sycophancy, clinician copilot
  hypothesis/            # KG-grounded generate/debate/rank & novelty/feasibility
  design/                # BOED/DAD/ADO, Bayesian adaptive trials, SMART/JITAI
  experiment-runtime/    # frame-precise authoring/runtime & closed-loop/robotic execution
  subjects/              # panel connectors, data-quality firewall, eligibility matching
  analysis/              # BIDS-App/MNE pipelines, causal inference
  reproducibility/       # auto-preregistration, multiverse, provenance ledger
  knowledge-graph/       # Biolink KG, ontology service, RDoC OWL & DSM↔ICD crosswalk
  literature/            # PubMed/OpenAlex/S2 ingestion, SciFact claim extraction
  evidence-synthesis/    # living systematic reviews, GraphRAG & KGARevion
  datasets/              # FAIR catalog, NWB/BIDS/DICOM I/O
  governance/            # neurorights/HIPAA/GDPR, defacing, federated & DP compute
  regulatory/            # FDA SaMD & PCCP, bias/drift testing, RCT evidence
  safety/                # 988 crisis routing, age-gating, jurisdiction-aware HITL
  ai/                    # autonomous closed-loop neuroscientist & fail-closed AI-IRB
  apps/                  # researcher/clinician/control-room/explorer/patient surfaces
  integration/           # cross-domain hub

libs/contracts/phoebe/
```

## Architecture

The domain is structured in seven layers. Each layer builds on the one below it;
no layer reaches across a layer boundary without going through the contracts
package.

- **Core** — the foundation: subject/participant, study, protocol, signal,
  recording, stimulus, trial, consent, assessment, hypothesis, experiment,
  claim, dataset, and ontology-term primitives, plus the RDoC/HiTOP dimensional
  model and the state machines (consent, IRB approval, preregistration lock,
  crisis escalation) that every other package depends on.
- **Neural-interface layer** — acquisition, real-time signal processing,
  decoding/foundation models, and closed-loop neuromodulation. The hard
  real-time path is **Rust**; it owns the decode→stimulate loop and the
  stimulation safety governor.
- **Neuroscience layer** — connectomics, multi-scale simulation, brain
  foundation models / digital twins, and spike-sorting & latent-dynamics
  analysis. Governed by the **fail-loud uncertainty** hard requirement: digital
  twins always carry calibrated uncertainty and refuse to overstate; whole-brain
  emulation is explicitly out of scope.
- **Clinical layer** — assessment, measurement-based care, digital phenotyping,
  computational psychiatry, and regulated therapeutics. Governed by the
  **human-in-the-loop** hard requirement: no autonomous diagnosis, prescribing,
  or unsupervised therapy.
- **Discovery layer** — hypothesis generation, optimal experimental design,
  experiment runtime, subject management, analysis, and reproducibility. The AI
  breakthrough engine orchestrates these into a closed loop.
- **Knowledge layer** — the knowledge graph & ontology service, literature
  ingestion, evidence synthesis, and the dataset catalog. The single source of
  truth for "what is known" and the substrate every reasoning step is grounded
  and verified against.
- **Governance & experience layer** — neuroethics/neurorights/privacy
  governance, the FDA SaMD regulatory harness, the crisis-safety backbone, the
  application suite, and the cross-domain integration hub. Governed by the
  **append-only audit** and **jurisdiction-aware compliance** hard requirements.

## Boundaries

Phoebe's scope is the science and medicine of the brain and mind. The boundaries
below define where Phoebe ends and an adjacent domain begins, so the same fact
is never owned twice.

- **Phoebe** owns neuroscience-grade decoding and analysis, neural foundation
  models, closed-loop neuromodulation, clinical-psychology evidence and
  regulated therapeutics, the brain/behaviour experiment lifecycle, and the
  brain-mind knowledge graph.
- **Iris** owns the multimodal human–computer interface, including the BCI
  device/HID layer (`libs/iris/bci/*`, `libs/iris/multimodal/bci/*`). Phoebe
  consumes those device primitives; it does not re-implement drivers, intent
  HID, or the device-level privacy framework.
- **Aphrodite** owns the consumer biometric engine
  (`libs/aphrodite/biometric-engine`, incl. `eeg/`). Phoebe consumes biosignal
  acquisition and adds clinical/research interpretation.
- **Psyche** owns affective computing and digital humans. Phoebe consumes
  affect/sentiment signals for phenotyping and uses the conversational stack to
  deliver therapeutic content, but owns the clinical guardrails on what is safe
  to say.
- **Phase 178 (Autonomous Research & Agentic Scientist) / Nous** own the generic
  autonomous-scientist substrate and the ML platform. Phoebe specializes and
  constrains them for living brains and human subjects (BOED/ADO, IRB gating,
  neuro/behavioural execution, BIDS-App analysis).
- **Kalika** owns mathematics/physics/materials research agents and notebooks.
  Phoebe reuses that infrastructure for the neuro/psych domain.
- **Lilith / Tara** own contemplative wellness and meditation (consumer,
  non-regulated; `libs/meditation/*`). The boundary is the clinical line: a
  wellness practice is Lilith/Tara; a validated diagnostic/therapeutic with a
  clinician in the loop and a regulatory pathway is Phoebe.
- **Mnemosyne** owns memory infrastructure; Phoebe consumes it and studies
  _biological_ memory rather than owning the platform's artificial memory.

## Verification Expectations

When the packages are implemented, each area must be covered by a dedicated test
suite asserting domain correctness, not data flow. The acceptance gates:

- **Time-sync tests** — multimodal LSL streams synchronized to sub-millisecond
  jitter (≈≤200 µs SD).
- **Decoder benchmark tests** — WER / bits-per-second / co-bps / ITR on held-out
  cross-session and cross-subject splits, where a random or fixed-output decoder
  scores at chance (the metric tests decoding, not plumbing).
- **Stimulation safety tests** — latency-deadline adherence, thermal/charge
  hard-caps (≤0.5 °C), manual-override, and append-only incident logging.
- **Simulation interchange tests** — a SONATA model produces matching spike
  rasters across at least two backends within numerical tolerance.
- **Digital-twin uncertainty tests** — twins always emit calibrated bounds; an
  out-of-validated-scope request returns an explicit refusal, not a fabrication.
- **Assessment scoring tests** — PHQ-9/GAD-7/PCL-5/C-SSRS scored against
  published worked examples; a C-SSRS or PHQ-9 item-9 positive hard-triggers the
  crisis backbone.
- **Adaptive-design tests** — ADO reproduces the delay-discounting efficiency
  result (≥0.95 reliability in 10–20 trials) on a simulated participant;
  adaptive trials enforce Type-I control.
- **Causal-inference tests** — the refutation step runs before any effect is
  reported; a confounded fixture is flagged by a placebo/refutation test.
- **Reproducibility tests** — preregistration-vs-execution auto-diff flags an
  undisclosed analysis deviation; provenance graphs recompute with one command.
- **Crosswalk tests** — a DSM-5-TR disorder resolves to its ICD-11/MeSH/SNOMED
  codes and related RDoC constructs through the SSSOM crosswalk, with
  provenance.
- **Verification tests** — a GraphRAG triple absent from / contradicted by the
  KG is filtered before reaching an answer (KGARevion pattern).
- **Governance tests** — a neural-data export for an unconsented purpose is
  hard-blocked; every access is immutably logged.
- **AI-IRB tests** — the autonomous engine cannot enroll a human subject without
  passing the fail-closed ethics gate plus a human sign-off; a protocol
  violation halts the loop.