From ad8d0aa59baf45ba026f0e240d72d4a6827ec98f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Apr 2026 00:40:25 +0000 Subject: [PATCH] docs(research): add connectome-embodied-brain compendium 12-document deep research set exploring whether RuVector v2.0.4 can serve as the substrate for a four-layer coherence-aware connectome operating system (CC-OS): connectome graph substrate, event-driven LIF dynamics runtime, embodied simulator closed loop, and ruvector-driven analysis + counterfactual perturbation. Positioning is deliberately narrow: not mind upload, not consciousness, not whole-brain emulation in the Sandberg-Bostrom sense. It is a graph-native, Rust-native, auditable platform for insect-scale connectome circuit science with built-in structural fragility scoring and witness-log reproducibility. Contents: - 00-index.md compendium index + positioning - 01-foundations-connectome-neuroscience published-literature survey - 02-connectome-graph-substrate Layer 1 schema + storage - 03-mincut-circuit-analysis ruvector-mincut on connectomes - 04-neural-dynamics-runtime Layer 2 LIF engine spec - 05-cross-region-attention-fusion NeuralFusionArray aggregate - 06-embodied-simulator-closed-loop Layer 3 Rapier + NMF bridge - 07-coherence-crv-behavioral-episodes BehaviorPipeline over CRV - 08-counterfactual-perturbation fragility protocol - 09-four-layer-architecture integrated system spec - 10-acceptance-test-grooming concrete pass/fail test - 11-risks-positioning-roadmap ADR-084..ADR-088 drafts Five ADRs are drafted inline for later extraction: ADR-084 Connectome graph substrate ADR-085 Neural dynamics runtime ADR-086 Embodied simulator closed loop ADR-087 CRV behavioral episodes + coherence gating ADR-088 Governance, positioning, counterfactual protocol No Rust source or Cargo files touched. No ADRs created yet - drafts only. Witness-bundle and test harness specifications reference the existing ADR-028 convention so downstream implementation slots cleanly into the existing tooling. https://claude.ai/code/session_017ePXU2EYqVPVSD8t7kEho5 --- .../connectome-embodied-brain/00-index.md | 141 +++++++ .../01-foundations-connectome-neuroscience.md | 339 ++++++++++++++++ .../02-connectome-graph-substrate.md | 365 +++++++++++++++++ .../03-mincut-circuit-analysis.md | 379 ++++++++++++++++++ .../04-neural-dynamics-runtime.md | 339 ++++++++++++++++ .../05-cross-region-attention-fusion.md | 276 +++++++++++++ .../06-embodied-simulator-closed-loop.md | 289 +++++++++++++ .../07-coherence-crv-behavioral-episodes.md | 281 +++++++++++++ .../08-counterfactual-perturbation.md | 246 ++++++++++++ .../09-four-layer-architecture.md | 281 +++++++++++++ .../10-acceptance-test-grooming.md | 279 +++++++++++++ .../11-risks-positioning-roadmap.md | 344 ++++++++++++++++ 12 files changed, 3559 insertions(+) create mode 100644 docs/research/connectome-embodied-brain/00-index.md create mode 100644 docs/research/connectome-embodied-brain/01-foundations-connectome-neuroscience.md create mode 100644 docs/research/connectome-embodied-brain/02-connectome-graph-substrate.md create mode 100644 docs/research/connectome-embodied-brain/03-mincut-circuit-analysis.md create mode 100644 docs/research/connectome-embodied-brain/04-neural-dynamics-runtime.md create mode 100644 docs/research/connectome-embodied-brain/05-cross-region-attention-fusion.md create mode 100644 docs/research/connectome-embodied-brain/06-embodied-simulator-closed-loop.md create mode 100644 docs/research/connectome-embodied-brain/07-coherence-crv-behavioral-episodes.md create mode 100644 docs/research/connectome-embodied-brain/08-counterfactual-perturbation.md create mode 100644 docs/research/connectome-embodied-brain/09-four-layer-architecture.md create mode 100644 docs/research/connectome-embodied-brain/10-acceptance-test-grooming.md create mode 100644 docs/research/connectome-embodied-brain/11-risks-positioning-roadmap.md diff --git a/docs/research/connectome-embodied-brain/00-index.md b/docs/research/connectome-embodied-brain/00-index.md new file mode 100644 index 00000000..a9223e7d --- /dev/null +++ b/docs/research/connectome-embodied-brain/00-index.md @@ -0,0 +1,141 @@ +--- +Research Document ID: RD-C-00 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: ADR-001 through ADR-081 (existing corpus); proposed ADR-084 through ADR-088 (this compendium) +--- + +# RD-C-00: Connectome-Embodied-Brain Compendium — Index + +## Abstract + +This compendium evaluates whether RuVector v2.0.4 — the vector, graph, attention, solver, and CRV toolkit already integrated into the wifi-densepose Rust workspace — can serve as the substrate for a four-layer **coherence-aware connectome operating system (CC-OS)**. The design is inspired by the 2024 Lappalainen et al. connectome-constrained deep mechanistic networks for the Drosophila visual system, the Kakaria and de Bivort (2017) leaky-integrate-and-fire (LIF) central-complex model, and the NeuroMechFly v1/v2 embodied simulator lineage, but the RuView framing is deliberately narrower and more auditable than press coverage of "whole-fly-brain-in-silico" demonstrations. We do **not** claim mind upload, phenomenal consciousness, or biologically faithful cognition. We claim the ability to (a) ingest a published connectome as a typed graph, (b) run event-driven LIF dynamics at millisecond resolution, (c) close the loop through an embodied simulator, and (d) apply RuVector's structural circuit analysis (ruvector-mincut, ruvector-attn-mincut), counterfactual perturbation (via existing CoherenceGate / CrvSessionManager patterns), and witness-style auditing (ADR-028 lineage) to produce explainable behavioral episodes. The twelve documents that follow specify the substrate, runtime, simulator, analysis loop, risks, and acceptance tests. This index document is the entry point and positioning statement. Readers in a hurry should read §4 (positioning) and §5 (key findings preview) first. + +## 1. Compendium Structure + +The compendium is organized as twelve documents (00 through 11). Clusters A–D correspond to the four architectural layers; cluster E covers cross-cutting concerns. + +| Doc | ID | Cluster | Owner focus | One-line description | +|-----|----|---------|-------------|----------------------| +| 00 | RD-C-00 | E: Meta | Index | This document — ToC, positioning, quick-start | +| 01 | RD-C-01 | E: Foundations | Literature | Published-literature survey: connectomes, LIF models, embodiment | +| 02 | RD-C-02 | A: Substrate | Layer 1 | Connectome graph schema, vector store, temporal-tensor storage | +| 03 | RD-C-03 | A: Substrate | Layer 1 | MinCut circuit analysis, structural fragility metric | +| 04 | RD-C-04 | B: Runtime | Layer 2 | Event-driven LIF neural dynamics runtime (`wifi-densepose-neuro`) | +| 05 | RD-C-05 | B: Runtime | Layer 2 | Cross-region attention fusion (`NeuralFusionArray`) | +| 06 | RD-C-06 | C: Embodiment | Layer 3 | Embodied simulator closed loop (`wifi-densepose-embody`) | +| 07 | RD-C-07 | D: Analysis | Layer 4 | Coherence + CRV behavioral episodes (`BehaviorPipeline`) | +| 08 | RD-C-08 | D: Analysis | Layer 4 | Counterfactual perturbation fragility protocol | +| 09 | RD-C-09 | E: Integration | Architecture | Four-layer architecture: data flow, interfaces, invariants | +| 10 | RD-C-10 | E: Acceptance | Testing | Acceptance test grooming — pass/fail criteria per layer | +| 11 | RD-C-11 | E: Governance | Roadmap | Risks, positioning, roadmap, proposed ADR-084..ADR-088 | + +Documents 00, 01, and 02 are delivered in the first writing pass. Documents 03–11 are delivered by parallel clusters referenced by name throughout this index. + +## 2. Key Crate → Layer Mapping + +The CC-OS design reuses existing RuVector v2.0.4 crates rather than introducing new numerical kernels. Two new wifi-densepose crates are proposed (`wifi-densepose-neuro`, `wifi-densepose-embody`); the rest of the runtime is assembled from crates already in the workspace. + +| Layer | Responsibility | RuVector crate(s) | wifi-densepose crate(s) | +|-------|----------------|-------------------|-------------------------| +| 1. Substrate | Connectome graph + per-neuron embeddings + temporal voltages | `ruvector-mincut`, `ruvector-attn-mincut`, `ruvector-temporal-tensor` | `wifi-densepose-core`, `wifi-densepose-db` | +| 2. Runtime | LIF dynamics, spike event bus, region attention | `ruvector-solver` (Neumann), `ruvector-attention` (SDPA) | **`wifi-densepose-neuro`** (proposed) | +| 3. Embodiment | Body simulator, sensors, actuators, closed loop | — (external: NeuroMechFly/MuJoCo/Rapier) | **`wifi-densepose-embody`** (proposed) | +| 4. Analysis | Mincut fragility, CRV episodes, coherence gating, counterfactuals | `ruvector-mincut`, `ruvector-attention`, `ruvector-crv`, `ruvector-gnn` (feature-gated) | `wifi-densepose-signal` (reuse RuvSense patterns) | + +The RuvSense module set (signal/src/ruvsense/) is reused not by lifting WiFi-specific code but by lifting **patterns**: `CoherenceGate` (coherence_gate.rs) becomes a spike-train coherence gate; `MultistaticArray` (viewpoint/fusion.rs) becomes the `NeuralFusionArray` aggregate; `GeometricDiversityIndex` (viewpoint/geometry.rs) becomes a circuit-diversity index; `WifiCrvPipeline` (crv/mod.rs) becomes the `BehaviorPipeline` facade. Section 4 of doc 09 lists every pattern reuse explicitly. + +## 3. Key Findings Preview + +The full findings, with evidence, live in docs 01 through 11. The one-sentence previews: + +| # | Finding | Evidence location | +|---|---------|-------------------| +| F1 | RuVector's `MinCutBuilder::new().exact()` can score connectome bottleneck fragility at 10k–150k node scale. | see doc 03 | +| F2 | `NeumannSolver` is appropriate for steady-state firing-rate approximation but not for event-driven spiking; event-driven LIF needs an explicit spike queue. | see doc 04 | +| F3 | `TemporalTensorCompressor` can store ~60 s of 1 kHz voltage traces for 50k neurons in roughly 3–4 GB using tiered 8/5–7/3-bit compression. | see doc 02 §8 | +| F4 | `ScaledDotProductAttention` is sufficient as a cross-region fusion primitive provided per-region embeddings are dimensionally consistent (32-d or 128-d). | see doc 05 | +| F5 | The six-stage `CrvSessionManager` pipeline maps 1:1 onto a behavioral-episode lifecycle (stimulus → sensory response → motor plan → action → audit → composite). | see doc 07 | +| F6 | Counterfactual "silence neuron X, rerun, measure divergence" is directly expressible as a perturbation on the spike event bus with a fragility score computed over the divergence embedding. | see doc 08 | +| F7 | End-to-end closed-loop real-time factor of 0.1×–0.5× on a single workstation is plausible for the full adult Drosophila FlyWire dataset (~139k neurons, ~54M synapses); realtime (1.0×) requires batching and GPU assistance. | see doc 09 | +| F8 | The design cleanly excludes phenomenal-consciousness claims; it is a structural / dynamical / behavioral audit tool, not a substrate for mind. | see doc 01 §8, doc 11 | +| F9 | ESP32 / WiFi-CSI hardware remains relevant only as an external sensor channel feeding layer-3 sensor inputs; it is not part of the neural substrate. | see doc 06 | +| F10 | Five new ADRs (ADR-084 substrate, ADR-085 runtime, ADR-086 embodiment, ADR-087 analysis loop, ADR-088 governance) are proposed to land this compendium. | see doc 11 | + +## 4. Positioning: Coherence-Aware Connectome Operating System (CC-OS) + +RuView's framing is **not** "digital mind" and not "whole-brain emulation in the Sandberg–Bostrom sense." The framing is a **coherence-aware connectome operating system**: a runtime that (i) loads a typed, provenance-tagged connectome graph; (ii) simulates its neural dynamics at millisecond resolution; (iii) closes the sensorimotor loop through an embodied simulator; and (iv) provides auditable, counterfactual analysis of the resulting behavior. The three key adjectives are: + +- **Coherence-aware** — borrowed from the WiFi CSI pipeline: every layer produces a numerical coherence score with a `CoherenceGate` decision (Accept / PredictOnly / Reject / Recalibrate). This is not a claim about consciousness; it is a signal-quality gate. +- **Connectome** — the graph is sourced from published, peer-reviewed reconstructions (FlyWire, MICrONS, Winding et al. 2023). We do **not** generate connectomes; we ingest them. +- **Operating system** — the runtime exposes a scheduler, event bus, memory tiers, and auditable hooks. It is not a single monolithic model; it is a platform on which circuit analyses, behavioral episodes, and counterfactuals are scheduled and logged. + +What this is **not**: + +1. Not a mind, not a subject, not a locus of experience. Phenomenal consciousness is explicitly out of scope (doc 01 §8 elaborates, citing Seth 2021 and the Markov-blanket framing). +2. Not a whole-mammal brain emulator. At current compute, the feasibility frontier is adult Drosophila (~139k neurons) and perhaps larval zebrafish (~100k neurons). Mouse cortex (~75M neurons) is out of scope. +3. Not "Eon-style." Recent press coverage of "the fly brain running on a laptop" conflates three separable achievements — visual-system circuit fit (Lappalainen 2024), central-complex LIF dynamics (Kakaria 2017), and NeuroMechFly body loop — into a single headline. RuView keeps those three layers separate, with distinct acceptance criteria (doc 10), and does not make behavioral claims the layer does not support. +4. Not a replacement for NEURON, Brian2, Nengo, or Genesis. Those are biophysically richer. CC-OS prioritizes auditable graph-plus-LIF at connectome scale with built-in fragility analysis; it trades multi-compartment biophysics for throughput and governance. + +## 5. Related ADRs + +### 5.1 Existing ADR corpus referenced + +- ADR-001 through ADR-043 — the existing wifi-densepose decision record corpus +- ADR-014 — SOTA signal processing (coherence primitives reused in layer 4) +- ADR-016 — RuVector training pipeline integration (precedent for ruvector adoption) +- ADR-024 — Contrastive CSI embedding / AETHER (precedent for per-node embedding design) +- ADR-027 — Cross-environment domain generalization / MERIDIAN (precedent for region fusion) +- ADR-028 — ESP32 capability audit + witness verification (precedent for audit protocol) +- ADR-029 through ADR-032 — RuvSense multistatic / coherence / security ADRs (pattern source) + +References to ADR-044 through ADR-081 are understood to exist in the broader RuView corpus; specific numbers are not hard-coded here because the corpus continues to grow. + +### 5.2 ADRs proposed by this compendium + +Full text for each lives in doc 11. Previews: + +| ADR | Title | Status | Doc of record | +|-----|-------|--------|---------------| +| ADR-084 | Connectome graph substrate + per-neuron embeddings | Proposed | RD-C-02, RD-C-03 | +| ADR-085 | Event-driven LIF neural runtime (`wifi-densepose-neuro`) | Proposed | RD-C-04, RD-C-05 | +| ADR-086 | Embodied simulator integration (`wifi-densepose-embody`) | Proposed | RD-C-06 | +| ADR-087 | Coherence + CRV + counterfactual analysis loop (`BehaviorPipeline`) | Proposed | RD-C-07, RD-C-08 | +| ADR-088 | Governance, positioning, and non-claims for CC-OS | Proposed | RD-C-11 | + +## 6. Quick-Start Table of Contents + +Read in this order for a 30-minute overview: + +1. This document (RD-C-00) — §4 Positioning and §5 ADR previews. +2. [RD-C-01 Foundations and Connectome Neuroscience](./01-foundations-connectome-neuroscience.md) — §6 Scaling frontier table and §8 "Not mind upload" section. +3. [RD-C-09 Four-Layer Architecture](./09-four-layer-architecture.md) — the data-flow diagram. +4. [RD-C-11 Risks, Positioning, Roadmap](./11-risks-positioning-roadmap.md) — the non-claims and the milestone table. + +Read in this order for a technical deep dive: + +1. [RD-C-02 Connectome Graph Substrate](./02-connectome-graph-substrate.md) +2. [RD-C-03 MinCut Circuit Analysis](./03-mincut-circuit-analysis.md) +3. [RD-C-04 Neural Dynamics Runtime](./04-neural-dynamics-runtime.md) +4. [RD-C-05 Cross-Region Attention Fusion](./05-cross-region-attention-fusion.md) +5. [RD-C-06 Embodied Simulator Closed Loop](./06-embodied-simulator-closed-loop.md) +6. [RD-C-07 Coherence + CRV Behavioral Episodes](./07-coherence-crv-behavioral-episodes.md) +7. [RD-C-08 Counterfactual Perturbation](./08-counterfactual-perturbation.md) +8. [RD-C-10 Acceptance Test Grooming](./10-acceptance-test-grooming.md) + +## 7. Document Conventions + +- Every RD-C-* document uses the same front-matter block (ID, date, status, authors, related ADRs). +- Every claim cites author + year + venue. No DOIs are fabricated. +- Every proposed Rust API is tagged **(proposed)** and distinguished from observed v2.0.4 APIs. +- Every neural-quantity number has units and a sanity-check paragraph. +- Every non-claim (what CC-OS deliberately is not) is surfaced explicitly, not buried. + +## 8. Next Steps + +1. Land docs 00, 01, 02 (this writing pass). +2. Parallel clusters land docs 03–11. +3. Convert finding F1–F10 into the five proposed ADRs. +4. Validate the §3 feasibility claims against a small FlyWire-subset prototype on the `claude/connectome-embodied-brain-COE3I` branch. +5. Re-run the witness bundle (ADR-028 pattern) once prototype code exists. diff --git a/docs/research/connectome-embodied-brain/01-foundations-connectome-neuroscience.md b/docs/research/connectome-embodied-brain/01-foundations-connectome-neuroscience.md new file mode 100644 index 00000000..232f9b06 --- /dev/null +++ b/docs/research/connectome-embodied-brain/01-foundations-connectome-neuroscience.md @@ -0,0 +1,339 @@ +--- +Research Document ID: RD-C-01 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-084, ADR-085, ADR-086, ADR-088 +--- + +# RD-C-01: Foundations — Connectome Neuroscience and Embodied Brain Simulation + +## Abstract + +This document surveys the published science the Coherence-Aware Connectome +Operating System (CC-OS) must stand on. We review the four connectome +datasets currently usable for whole-circuit modelling (C. elegans, *Drosophila* +larva, adult *Drosophila* via FlyWire, mouse visual cortex via MICrONS), the +three dynamical-model families that have been fit to those connectomes +(firing-rate networks, leaky integrate-and-fire, connectome-constrained deep +mechanistic networks), and the embodiment platforms that close the +sensorimotor loop (NeuroMechFly v1/v2, MuJoCo-MJX, Rapier, Walknet). We then +discuss the feasibility frontier as a function of neuron count, argue +explicitly why a runtime of this shape is **not** a mind or a whole-brain +emulation in the Sandberg–Bostrom sense, and identify the open questions +RuView is uniquely positioned to address: coherence-aware gating, +structural-fragility scoring, counterfactual circuit discovery, and +witness-audit reproducibility. + +--- + +## Table of Contents + +1. Why the fly connectome is the right first target +2. Connectome datasets in publishable form +3. Whole-brain dynamical models +4. Embodiment platforms +5. "Eon"-style integrations — what the code does vs what the press says +6. Scaling frontier +7. Why CC-OS is not mind upload +8. Open questions RuView can address +9. References + +--- + +## 1. Why the Fly Connectome is the Right First Target + +Three properties make *Drosophila melanogaster* the right first organism for +an open-loop, auditable, connectome-driven embodied runtime: + +1. **Tractable scale** — 139,255 neurons and ~54 million synapses in the + adult brain (Dorkenwald et al. 2024, *Nature*). Two orders of magnitude + smaller than mouse cortex, and the graph fits in a laptop's main memory + with the tiered temporal-tensor compression described in + 02-connectome-graph-substrate.md. +2. **Rich behavioral vocabulary** — locomotion, grooming, feeding, courtship, + phototaxis, and memory-guided navigation are all well-studied at the + single-neuron level (Namiki et al. 2018, *eLife*; Seeds et al. 2014, *Curr + Biol*; Hampel et al. 2015, *eLife*). +3. **Published body models** — NeuroMechFly (Lobato-Rios et al. 2022, *Nat + Methods*) and NeuroMechFly v2 (Wang-Chen et al. 2024, preprint) provide + an articulated MuJoCo body with validated proprioception and vision + adapters. + +The zebrafish larva (~100k neurons, whole-brain calcium imaging available) +is a close second choice but lacks a comparably mature published body +simulator. *C. elegans* (302 neurons) is well-served by OpenWorm but +operates at a scale that does not stress RuVector's strengths. + +## 2. Connectome Datasets in Publishable Form + +| Organism | Dataset | Neurons | Synapses | Source | Status | +|----------|---------|---------|----------|--------|--------| +| *C. elegans* hermaphrodite | White et al. electron micrography | 302 | ~7,000 | White et al. 1986, *Phil Trans R Soc B* | Complete; OpenWorm reconstruction | +| *C. elegans* male | Cook et al. | 385 | ~10,000 | Cook et al. 2019, *Nature* | Complete | +| *Drosophila* larva | Winding et al. | ~3,000 | ~548,000 | Winding et al. 2023, *Science* | Complete, both hemispheres | +| Adult *Drosophila* hemibrain | Scheffer et al. | ~25,000 | ~20M | Scheffer et al. 2020, *eLife* | Hemibrain only | +| Adult *Drosophila* whole brain (FlyWire) | Dorkenwald et al. | ~139,255 | ~54M | Dorkenwald et al. 2024, *Nature* | Complete, proofread | +| Mouse visual cortex (MICrONS) | MICrONS Consortium | ~200,000 | ~500M | MICrONS Consortium 2023, *bioRxiv* / *Nature* 2025 | Partial; ~1 mm³ volume | +| Larval zebrafish | Vishwanathan et al. | ~100,000 (est.) | — | Vishwanathan et al. 2024, preprint | In progress | + +For CC-OS v1 we recommend **FlyWire** (Dorkenwald 2024) as the primary +substrate because it is the only fully-proofread whole-brain connectome at a +scale that exercises RuVector's capabilities without requiring GPU clusters. + +### 2.1 Metadata provided by FlyWire + +FlyWire publishes per-neuron metadata that maps cleanly onto the +`ConnectomeGraph` schema of 02-connectome-graph-substrate.md: + +| FlyWire field | `ConnectomeGraph` field | +|---------------|-------------------------| +| `root_id` | `Neuron.id` | +| `super_class` | `Neuron.class` (Sensory / Interneuron / Motor / …) | +| `cell_type` | `Neuron.cell_type_hash` | +| `side` | region metadata | +| `nt_type` | `Neuron.neurotransmitter` | +| `pre`, `post`, `syn_count` | `Synapse.pre_id`, `post_id`, `weight` | + +Per-synapse transmitter predictions (Eckstein et al. 2024, *Cell*) are +separately published and should be merged into the edge schema as +`Synapse.nt` with a provenance tag. + +## 3. Whole-Brain Dynamical Models + +Three families have been fit to connectomes in the past eight years. They +differ in what is simulated and what computational substrate they demand. + +### 3.1 Firing-rate networks + +Each neuron is a scalar rate $r_i(t) \in \mathbb{R}_{\ge 0}$ governed by + +$$ + \tau \frac{dr_i}{dt} = -r_i + f\!\Bigl( \sum_j W_{ij} r_j + I_i \Bigr), +$$ + +with $f$ a nonlinearity (ReLU, tanh, sigmoid). Lappalainen et al. 2024 +(*Nature*) fit firing-rate networks to the fly optic lobe connectome and +recovered direction-selective T4/T5 cell responses that matched +electrophysiology. Rate networks are cheap (one matrix-vector per +timestep), map cleanly onto `ruvector-solver`'s sparse primitives for +steady-state approximations, and lose temporal fidelity at the sub-100 ms +timescale. + +### 3.2 Leaky integrate-and-fire (LIF) + +$$ + \tau_m \frac{dV_i}{dt} = -(V_i - V_{\text{rest}}) + R_m I_i(t), +$$ + +with a reset-on-threshold rule emitting spikes delivered to postsynaptic +neurons with axonal delay. Brunel 2000 (*J Comput Neurosci*) established +the reference framework; Kakaria & de Bivort 2017 (*Front Behav Neurosci*) +applied it to the central complex of *Drosophila*. LIF is the right +abstraction level for CC-OS: it captures spike-timing phenomena important +for grooming and courtship circuits while staying tractable at 50k–150k +neurons. See 04-neural-dynamics-runtime.md for the Rust implementation. + +### 3.3 Connectome-constrained deep mechanistic networks + +Lappalainen et al. 2024 (*Nature*) introduced a family of trainable rate +networks in which the synaptic weights are constrained by the connectome +(sign and topology) but tuned by backpropagation against neural-recording +objectives. The family generalises firing-rate networks by allowing +learned nonlinearities and sensory adapters. CC-OS treats this class as a +**calibration target** rather than a primary runtime: once LIF dynamics +are running, Lappalainen-style fits provide external validation that the +per-neuron nonlinearities are in the right regime. + +### 3.4 Biophysically detailed models + +NEURON, GENESIS, Brian2, and the Blue Brain morphologically-detailed cortex +models fall here. CC-OS is **not** competing at this level. Our goal is +graph + LIF + embodiment with auditable fragility; detailed biophysics is +deferred to specialised tools. Non-goal noted in 02 §12. + +## 4. Embodiment Platforms + +| Platform | Physics backend | Language | Fidelity | Weakness | +|----------|-----------------|----------|----------|----------| +| NeuroMechFly v1 | MuJoCo | Python | High — biomechanically validated | Python overhead, Ubuntu focused | +| NeuroMechFly v2 | MuJoCo / MJX | Python + JAX | Higher — vision adapter included | Same | +| Walknet | Custom | Python / MATLAB | Medium — gait only | No body visuals | +| MuJoCo (bare) | MuJoCo | C | High general | Body model must be authored | +| PyBullet | Bullet | Python | Medium | Less accurate contact | +| Rapier | Rapier | Rust | Medium-high | No biomechanical fly model yet | +| Isaac Gym | PhysX | Python / C++ | High for large-scale RL | GPU-only, not auditable | + +For CC-OS v1, we recommend a **Rapier-based Rust fly body** for the tight +inner loop plus a **NeuroMechFly bridge** (Python IPC over shared memory) +for biomechanical validation runs. 06-embodied-simulator-closed-loop.md +develops this architecture. + +## 5. "Eon"-Style Integrations — What the Code Does vs What the Press Says + +Recent industry demonstrations (sometimes presented as "running a fly brain +on a laptop") combine three separable achievements: + +1. A connectome-constrained visual-system network (Lappalainen 2024). +2. A central-complex LIF dynamics model (Kakaria 2017, extended). +3. A body simulator in the NeuroMechFly lineage. + +The engineering story — stitching these three together, running the loop +at near-real-time — is genuine and valuable. The framing that this +constitutes "an in-silico fly" or "a digital organism" is an overclaim. +The fly brain is not just the optic lobe plus the central complex plus +motor neurons; it is an integrated system with peripheral sensors, +neuromodulators, circadian state, genetic plasticity, and developmental +history. A three-module stitch-up is a faithful partial model of a +specific circuit, not an organism. CC-OS inherits the stitch architecture +(graph, LIF, body) but insists on naming what each layer models and what +it does not, and on an acceptance test (10-acceptance-test-grooming.md) +that is a reproducible behavioral assay, not a rhetorical claim. + +## 6. Scaling Frontier + +| Species | Neuron count | Synapse count | Today's feasibility | Notes | +|---------|--------------|---------------|---------------------|-------| +| C. elegans | 302 | ~7k | Trivial | Solved; OpenWorm | +| Drosophila larva | 3k | ~500k | Easy | Winding 2023 | +| Drosophila adult (FlyWire) | 139k | 54M | **Target for CC-OS v1** | Borderline realtime | +| Zebrafish larva | ~100k | — | Feasible | No proofread connectome yet | +| Honeybee | ~960k | — | Hard | No whole-brain connectome | +| Mouse cortex (1 mm³ patch) | ~200k | ~500M | Hard | MICrONS partial; full brain ~75M | +| Human cortex | ~16B | ~10¹⁴ | Out of scope | Not feasible with current hardware | + +Feasibility is gated by three resources: +- **Memory**: synapse list in `(u64, u64, f64)` CSR triplets is ~24 bytes + per edge; 54M synapses = ~1.3 GB uncompressed. +- **Compute**: event-driven LIF scales with mean firing rate × neuron count. + At 5 Hz average, 139k neurons emit ~700k spikes/s, each triggering + ~400 postsynaptic updates = 280M updates/s. Feasible on one workstation. +- **I/O**: voltage traces at 1 kHz for 139k neurons at 8-bit = 139 MB/s + uncompressed. Tiered compression (02 §8) brings this to ~35 MB/s. + +Full FlyWire realtime is aspirational but not absurd on a top-end +workstation. The acceptance test (doc 10) targets a 15k–30k sub-network to +stay well inside the feasibility envelope. + +## 7. Why CC-OS is Not Mind Upload + +Three framings articulate what CC-OS deliberately does not claim: + +### 7.1 Information flow (Shannon view) + +CC-OS simulates information flow from sensors through the connectome to +actuators. This is computation, not subjectivity. Shannon-channel analysis +has nothing to say about phenomenal experience, and we make no attempt to +attribute experience. + +### 7.2 Markov blankets (Seth 2021 framing) + +A Markov blanket separates a system's internal states from external states +conditional on sensory and active states (Friston 2013). In a CC-OS +run, the boundary is explicit and inspectable: sensory neurons are the +blanket's active/sensory states, interneurons are internal. There is no +claim that crossing this blanket constitutes minding. + +### 7.3 Sandberg–Bostrom WBE scale + +Sandberg and Bostrom's 2008 whole-brain-emulation framework enumerates +eleven levels, from computational network (level 4) to quantum (level 11). +CC-OS sits at **level 4 (computational network of point neurons)** with +partial level 5 (analog population dynamics). All higher levels (dendritic +compartments, intracellular biochemistry, molecular signalling) are out +of scope. This alone rules out mind-upload claims in the Sandberg–Bostrom +sense. + +### 7.4 What we do claim + +- The runtime reproduces the connectome's structural wiring. +- It reproduces qualitative LIF dynamics consistent with published fits. +- It reproduces published behavioral bouts under canonical stimuli within + a bounded subcircuit. +- It supports counterfactual perturbation with auditable provenance. + +That's the ceiling. Everything above — consciousness, identity, memory +continuity — is out of scope and is not implied by any sentence in this +compendium. + +## 8. Open Questions RuView Can Uniquely Address + +1. **Coherence-aware runtime.** The existing CSI pipeline uses + `CoherenceGate` (Accept / PredictOnly / Reject / Recalibrate) to reject + out-of-distribution signal frames. The neural analog — detect when the + simulated population is drifting outside the behavioral attractor and + refuse to make circuit claims on that bout — is novel and valuable. + See 05-cross-region-attention-fusion.md and + 07-coherence-crv-behavioral-episodes.md. +2. **Structural fragility scoring.** Fragility = $\Delta\text{cut}/\text{cut}$ + under ablation (see 03-mincut-circuit-analysis.md). No existing + connectome simulator emits fragility as a first-class output. RuVector's + `DynamicMinCut` is built for exactly the incremental-ablation use case. +3. **Counterfactual circuit discovery.** Greedy ablation + re-mincut is a + simple, well-defined search procedure for minimal sufficient circuits. + See 08-counterfactual-perturbation.md. +4. **Witness-audit reproducibility.** ADR-028 established a witness-bundle + standard: input → pipeline → SHA-256 hash. Lifting this to neural + runtime is straightforward and makes CC-OS reviewable in a way that + Python-notebook demos are not. + +## 9. References + +1. White, J. G., Southgate, E., Thomson, J. N., Brenner, S. (1986). *The + structure of the nervous system of the nematode C. elegans.* Phil Trans R + Soc B. +2. Cook, S. J., Jarrell, T. A., Brittin, C. A., et al. (2019). *Whole-animal + connectomes of both C. elegans sexes.* Nature. +3. Winding, M., Pedigo, B. D., Barnes, C. L., et al. (2023). *The connectome + of an insect brain.* Science. +4. Scheffer, L. K., Xu, C. S., Januszewski, M., et al. (2020). *A connectome + and analysis of the adult Drosophila central brain.* eLife. +5. Dorkenwald, S., Matsliah, A., Sterling, A. R., et al. (2024). *Neuronal + wiring diagram of an adult brain.* Nature. +6. Eckstein, N., Bates, A. S., Champion, A., et al. (2024). *Neurotransmitter + classification from electron microscopy images.* Cell. +7. MICrONS Consortium. (2023). *Functional connectomics spanning multiple + areas of mouse visual cortex.* bioRxiv; subsequent 2025 Nature. +8. Vishwanathan, A., et al. (2024). *Larval zebrafish whole-brain connectome + (in progress).* Preprint. +9. Brunel, N. (2000). *Dynamics of sparsely connected networks of excitatory + and inhibitory spiking neurons.* J. Comput. Neurosci. +10. Izhikevich, E. M. (2003). *Simple model of spiking neurons.* IEEE TNN. +11. Kakaria, K. S., de Bivort, B. L. (2017). *Ring attractor dynamics emerge + from a spiking model of the entire protocerebral bridge.* Front Behav + Neurosci. +12. Lappalainen, J. K., Tschopp, F. D., Prakhya, S., et al. (2024). + *Connectome-constrained networks predict neural activity across the fly + visual system.* Nature. +13. Lobato-Rios, V., Ramalingasetty, S. T., Özdil, P. G., et al. (2022). + *NeuroMechFly, a neuromechanical model of adult Drosophila melanogaster.* + Nat Methods. +14. Wang-Chen, S., et al. (2024). *NeuroMechFly v2 with vision.* Preprint. +15. Namiki, S., Dickinson, M. H., Wong, A. M., Korff, W., Card, G. M. (2018). + *The functional organization of descending sensory-motor pathways in + Drosophila.* eLife. +16. Seeds, A. M., Ravbar, P., Chung, P., et al. (2014). *A suppression + hierarchy among competing motor programs drives sequential grooming in + Drosophila.* eLife. +17. Hampel, S., Franconville, R., Simpson, J. H., Seeds, A. M. (2015). *A + neural command circuit for grooming movement control.* eLife. +18. Cruse, H. (1990). *What mechanisms coordinate leg movement in walking + arthropods?* Trends Neurosci. +19. Tuthill, J. C., Wilson, R. I. (2016). *Mechanosensation and adaptive + motor control in insects.* Curr Biol. +20. Sandberg, A., Bostrom, N. (2008). *Whole Brain Emulation: A Roadmap.* + Future of Humanity Institute Tech Report 2008-3. +21. Seth, A. (2021). *Being You: A New Science of Consciousness.* Faber. +22. Friston, K. (2013). *Life as we know it.* J. R. Soc. Interface. +23. Ford, L. R., Fulkerson, D. R. (1956). *Maximal flow through a network.* + Canadian J. Math. +24. Stoer, M., Wagner, F. (1997). *A simple min-cut algorithm.* J. ACM. +25. Fiedler, M. (1973). *Algebraic connectivity of graphs.* Czech Math J. +26. Feng, K., Sen, R., Minegishi, R., et al. (2020). *Ascending neurons + convey behavioral state to integrative sensory and action selection + brain regions.* Nat Neurosci. + +--- + +**Next document**: 02-connectome-graph-substrate.md — the Layer 1 graph +schema, per-neuron embeddings, and temporal-tensor storage. diff --git a/docs/research/connectome-embodied-brain/02-connectome-graph-substrate.md b/docs/research/connectome-embodied-brain/02-connectome-graph-substrate.md new file mode 100644 index 00000000..4737ff3c --- /dev/null +++ b/docs/research/connectome-embodied-brain/02-connectome-graph-substrate.md @@ -0,0 +1,365 @@ +--- +Research Document ID: RD-C-02 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-084 +--- + +# RD-C-02: Connectome Graph Substrate (Layer 1) + +## Abstract + +Layer 1 of the Coherence-Aware Connectome Operating System (CC-OS) is a +typed, provenance-tagged, read-mostly graph store for a published +connectome (primarily FlyWire, Dorkenwald et al. 2024) with per-neuron +activity embeddings and tiered temporal state compression. This document +specifies the schema for `Neuron`, `Synapse`, and `Region` value objects; +the `ConnectomeGraph` aggregate root; the edge-triplet encoding that feeds +`ruvector-mincut`; the per-neuron embedding tensor that feeds +`ruvector-attention`; and the voltage/spike-train compression protocol built +on `ruvector-temporal-tensor`. All identifiers, storage layouts, and query +patterns are sized for the 139k-neuron / 54M-synapse fly regime on a single +workstation. + +--- + +## Table of Contents + +1. Requirements +2. Neuron node schema +3. Synapse edge schema +4. Region / neuropil meta-graph +5. Mapping to `ruvector-mincut` edge triplets +6. Per-neuron activity embeddings +7. Temporal state storage via `ruvector-temporal-tensor` +8. Sizing worked example +9. Query patterns +10. DDD bounded context +11. Integration with existing RuView code +12. Non-goals +13. References + +--- + +## 1. Requirements + +| Requirement | Target | Rationale | +|-------------|--------|-----------| +| Neuron count | 10k–150k | FlyWire full brain = 139k | +| Synapse count | 1M–60M | FlyWire reports ~54M | +| Adjacency access | O(degree) per neuron | event-driven LIF propagation | +| Per-neuron state write | O(1) | 1 kHz voltage updates | +| Bulk graph read at startup | < 10 s for 139k nodes / 54M edges | User experience | +| Memory budget | < 8 GB for full FlyWire | Laptop-grade target | +| Persistence | Append-only with SHA-256 | Witness-audit compatibility (ADR-028) | +| Concurrent readers | Yes | LIF + analysis can query in parallel | +| Concurrent writer | Single | Deterministic replay | + +## 2. Neuron Node Schema + +```text +Neuron { + id: u64, // FlyWire root_id or internal + class: NeuronClass, // Sensory / Interneuron / Motor / Ascending / Descending + cell_type_hash: u64, // stable hash of FlyWire cell_type + neurotransmitter: Neurotransmitter, // Ach / GABA / Glu / DA / 5HT / NE / Peptide / Unknown + morphology_hash: u64, // hash of skeleton for de-duplication + region_id: RegionId, // neuropil + position: Option<(f32, f32, f32)>, // Cartesian centroid (µm) + side: Side, // Left / Right / Midline + sensory_label: Option, // Bristle / JohnstonsOrgan / Ocelli / etc. + motor_label: Option, // ProthoracicLegMN / WingMN / etc. + provenance: ProvenanceTag, // dataset + version + SHA-256 of record +} +``` + +Enum sketches: + +```text +NeuronClass ::= Sensory | Interneuron | Motor | Ascending | Descending +Neurotransmitter ::= Ach | GABA | Glu | DA | Serotonin | NE | Peptide | Unknown +Side ::= Left | Right | Midline +``` + +`id` is `u64` rather than the existing `u32` `NodeId` from +`viewpoint/geometry.rs` because FlyWire root_ids are 64-bit. Section 11 +discusses the widening. + +## 3. Synapse Edge Schema + +```text +Synapse { + pre_id: u64, + post_id: u64, + weight: u16, // synaptic contact count + sign: Sign, // +1 for excitatory, -1 for inhibitory + nt: Neurotransmitter, // inferred from presynaptic neuron + axonal_delay_ms: f32, // estimated from neurite length + plasticity_tag: PlasticityTag, // Static | STP | LTP | LTD | Pending + provenance: ProvenanceTag, +} +``` + +Sign is deterministic given the presynaptic neuron's transmitter (Ach/Glu → ++1 by default, GABA → −1, others → lookup table). Axonal delay is +provisional; at fly scale, neurite lengths imply delays in the 0.5–5 ms +range. The canonical formulation for integer-weighted connectomes is +`weight = number of anatomical synapses`; functional correlation weights +live separately in a side-table for analysis (see 03 +§3 and 04-neural-dynamics-runtime.md §5). + +## 4. Region / Neuropil Meta-Graph + +The 80+ FlyWire neuropils (AL, MB, CX, LAL, GNG, VNC, etc.) form a +higher-level `RegionGraph` where each node is a region and each edge +aggregates synaptic weight between regions. + +```text +Region { + id: RegionId, // u16 is sufficient + name: String, // FlyWire neuropil label + neuron_count: u32, + centroid: Option<(f32, f32, f32)>, + functional_tag: RegionTag, // Visual | Olfactory | Motor | Memory | etc. +} + +RegionEdge { + from: RegionId, + to: RegionId, + total_weight: u32, // sum of synapse counts + n_synapses: u32, + mean_delay_ms: f32, +} +``` + +This meta-graph is the target input for 05-cross-region-attention-fusion.md: +per-region activity embeddings feed `ScaledDotProductAttention` with +geometric biases derived from `RegionEdge` connectomic distance. This is +the neural analog of `viewpoint/geometry.rs` +`GeometricDiversityIndex`. + +## 5. Mapping to `ruvector-mincut` Edge Triplets + +`MinCutBuilder` expects `Vec<(u64, u64, f64)>`. The encoder: + +```rust +fn edges_for_mincut(graph: &ConnectomeGraph, + source_nodes: &[u64], + sink_nodes: &[u64]) -> Vec<(u64, u64, f64)> { + let n = graph.neuron_count() as u64; + let source = n; + let sink = n + 1; + let mut edges = Vec::with_capacity(graph.synapse_count() + source_nodes.len() + sink_nodes.len()); + + for &s in source_nodes { edges.push((source, s, 1e18)); } + for &t in sink_nodes { edges.push((t, sink, 1e18)); } + + for syn in graph.synapses() { + let w = f64::from(syn.weight); + edges.push((syn.pre_id, syn.post_id, w)); + } + edges +} +``` + +This mirrors `signal/subcarrier.rs` verbatim up to domain-specific naming. +The virtual source and sink nodes sit at `n` and `n+1`. Inhibitory synapse +handling is discussed in 03 §3. + +## 6. Per-Neuron Activity Embeddings + +Each neuron carries a fixed-dimensional embedding used by +`ScaledDotProductAttention` as a key or value. Recommended dimension +matches the existing `AETHER` embedding size (128-d). + +```text +NeuronEmbedding { + id: u64, + dim: u16, // typically 128 + weights: Vec, // length = dim + source: EmbeddingSource, // Raw | TrainedAETHER | Lappalainen2024 + timestamp: u64, // wallclock of computation +} +``` + +The embedding table is a dense `[n_neurons, dim]` matrix. At 139k × 128 × +4 bytes = 71 MB, it fits in cache layers comfortably. Recomputed +embeddings are versioned; older versions can be kept in warm storage via +the temporal-tensor tiers described in §7. + +## 7. Temporal State Storage via `ruvector-temporal-tensor` + +Running LIF dynamics produces two streams: + +1. **Membrane voltage** — `f32` per neuron per timestep. +2. **Spike train** — sparse `u64` per spike or dense bit-vector per + timestep. + +Both are perfect fits for `TemporalTensorCompressor`: + +```rust +use ruvector_temporal_tensor::{TemporalTensorCompressor, TierPolicy}; + +pub struct VoltageBuffer { + compressor: TemporalTensorCompressor, + segments: Vec>, + frame_count: u32, + n_neurons: usize, +} + +impl VoltageBuffer { + pub fn new(n_neurons: usize, tensor_id: u32) -> Self { + Self { + compressor: TemporalTensorCompressor::new( + TierPolicy::default(), + n_neurons as u32, + tensor_id, + ), + segments: Vec::new(), + frame_count: 0, + n_neurons, + } + } + + pub fn push_frame(&mut self, voltages: &[f32]) { + let ts = self.frame_count; + self.compressor.set_access(ts, ts); + let mut seg = Vec::new(); + self.compressor.push_frame(voltages, ts, &mut seg); + if !seg.is_empty() { self.segments.push(seg); } + self.frame_count += 1; + } +} +``` + +This is the **same pattern** as `mat/breathing.rs` +`CompressedBreathingBuffer`, simply retargeted from 56 subcarrier +amplitudes to `n_neurons` voltages. Tier policies: + +| Tier | Bits | Typical window | Compression vs f32 | +|------|------|----------------|--------------------| +| Hot | 8 | last 10 ms | 4× | +| Warm | 5–7 | last 1–10 s | 5–6× | +| Cold | 3 | > 10 s | ~10× | + +## 8. Sizing Worked Example + +Scenario: 50k neurons, 1 kHz voltage, 60 s of simulation, one full run. + +| Quantity | Raw | Tiered (est.) | Notes | +|----------|-----|---------------|-------| +| Voltages: 50k × 1kHz × 60s × f32 | 12 GB | ~3.0 GB | 3-bit cold tier for the first 50 s, warm for next 9 s, hot for last 1 s | +| Spikes (bit-vector): 50k × 60k × 1b | 375 MB | ~40–60 MB | bit-packed, then tier-compressed | +| Spikes (event list at 5 Hz avg): 15M events × 16 B | 240 MB | — | alternative; no tier compression needed | +| Graph edges (2M × 24 B) | 48 MB | 48 MB | CSR, rarely changes | +| Neuron metadata (50k × ~200 B) | 10 MB | 10 MB | small | +| Neuron embeddings (50k × 128 × f32) | 26 MB | — | dense | + +Total active memory budget for one 60 s run at 50k neurons: **~4 GB**. +Full FlyWire 139k at 60 s: **~12 GB raw, ~3–4 GB tiered**, within reach of +a 32 GB workstation. + +## 9. Query Patterns + +Common queries and their cost class: + +| Query | Cost class | Implementation hint | +|-------|------------|---------------------| +| k-hop downstream of neuron set | O(mean_degree^k) | BFS with visited set | +| All motor MNs active in window | O(spikes_in_window) | scan tier-appropriate segments | +| Subcircuit induced by weight ≥ w | O(|E|) | filter+induced-subgraph builder | +| Min-cut between S and T | see 03 §10 | `MinCutBuilder::exact()` | +| Similar-activity neurons | O(n · dim) | embedding cosine search | +| Region × region flux | O(|region_edges|) | meta-graph aggregation | + +For recurring queries (e.g. "activity of descending motor neurons during +last 200 ms"), the runtime should maintain live indices; otherwise the +query cost becomes a log-compaction problem. + +## 10. DDD Bounded Context + +`ConnectomeGraph` is the aggregate root; `Neuron`, `Synapse`, `Region` are +value objects; `NeuronEmbedding` and `VoltageBuffer` are separately-owned +entities referenced by id. + +Domain events: + +| Event | Trigger | +|-------|---------| +| `ConnectomeLoaded { source, sha256, n_neurons, n_synapses }` | startup | +| `SynapseAblated { pre_id, post_id, reason }` | perturbation API | +| `SynapseRestored { pre_id, post_id }` | perturbation rollback | +| `EmbeddingRecomputed { neuron_id, source }` | manual or batch | +| `SpikeObserved { neuron_id, t_ms }` | LIF runtime | +| `RegionFluxSnapshot { region, total_rate, t_ms }` | periodic | + +Invariants enforced by the aggregate: + +- Every synapse references two existing neurons. +- No duplicate synapses (same pre, post, provenance). +- Neurotransmitter is consistent with presynaptic neuron (unless + explicitly overridden and flagged in provenance). +- Ablations are append-only events; graph state is materialised by replay. + +## 11. Integration with Existing RuView Code + +### 11.1 `NodeId` widening + +The existing `NodeId = u32` in `viewpoint/geometry.rs` is sufficient for +16–32 sensor nodes. The connectome uses `u64`. We recommend introducing a +new alias `NeuronId = u64` in the proposed `wifi-densepose-connectome` +crate without disturbing the existing `NodeId`. + +### 11.2 Reuse of `ApNode` sketch pattern + +`crv/mod.rs` `ApNode { id, position, coverage_radius }` is a viable +template for `RegionSketchElement` when CRV Stage III is applied to +behavioral episodes (see 07-coherence-crv-behavioral-episodes.md). + +### 11.3 Temporal-tensor reuse + +`mat/breathing.rs` `CompressedBreathingBuffer` and +`mat/heartbeat.rs` `CompressedHeartbeatSpectrogram` demonstrate the +per-frame push + lazy decode pattern. `VoltageBuffer` is implemented by +retargeting the same pattern. + +### 11.4 Witness bundle inclusion + +Every connectome load emits a `ConnectomeLoaded` event whose SHA-256 +covers the source file contents. This fits the ADR-028 witness-bundle +convention without modification. + +## 12. Non-Goals + +- **Dendritic compartments** — single-compartment point neurons only. +- **Multi-scale biophysics** — no ion channels, no NEURON/GENESIS + compatibility. +- **Connectome generation** — CC-OS ingests published connectomes; it does + not segment EM volumes or proofread reconstructions. +- **Runtime graph mutation in the spike loop** — ablations are explicit + perturbation events, not continuous plasticity. STP/LTP are deferred + to v2. +- **Mammalian connectomes** — out of scope for v1 on compute and ethics + grounds (see 11-risks-positioning-roadmap.md). + +## 13. References + +1. Dorkenwald, S., et al. (2024). *Neuronal wiring diagram of an adult + brain.* Nature. (FlyWire dataset.) +2. Eckstein, N., et al. (2024). *Neurotransmitter classification from + electron microscopy images.* Cell. +3. Scheffer, L. K., et al. (2020). *Connectome of the adult Drosophila + central brain.* eLife. +4. ADR-028 — ESP32 capability audit + witness verification (RuView repo). +5. ADR-017 — RuVector signal + MAT integration (RuView repo). +6. Winding, M., et al. (2023). *The connectome of an insect brain.* + Science. +7. RuVector v2.0.4 crate documentation — `ruvector-mincut`, + `ruvector-attention`, `ruvector-temporal-tensor`. + +--- + +**Next document**: 03-mincut-circuit-analysis.md (complete) and +04-neural-dynamics-runtime.md — the Rust event-driven LIF runtime that +consumes this substrate. diff --git a/docs/research/connectome-embodied-brain/03-mincut-circuit-analysis.md b/docs/research/connectome-embodied-brain/03-mincut-circuit-analysis.md new file mode 100644 index 00000000..7304bf72 --- /dev/null +++ b/docs/research/connectome-embodied-brain/03-mincut-circuit-analysis.md @@ -0,0 +1,379 @@ +# Minimum-Cut Circuit Analysis on a Connectome + +**Research Document**: RD-C-03 +**Date**: 2026-04-21 +**Status**: Draft +**Authors**: RuView Research Team +**Related ADRs**: ADR-014, ADR-017, ADR-029, ADR-075; proposed ADR-084, ADR-088 +**Related research**: `docs/research/rf-topological-sensing/05-sublinear-mincut-algorithms.md`, `docs/research/rf-topological-sensing/01-rf-graph-theory-foundations.md` + +--- + +## Abstract + +A connectome is a weighted directed graph where neurons are vertices and +synapses are edges. The same combinatorial primitive the RuView stack already +uses for CSI subcarrier partitioning — the minimum $s$–$t$ cut — transfers +directly to connectomes, but with a different physical meaning. On CSI it +isolates subcarriers whose sensitivity profile diverges. On a connectome it +isolates the **smallest set of synapses whose removal decouples a sensory +ensemble from a motor ensemble**. That set is a *structural bottleneck*, and +its weight is a **fragility score** whose utility has been demonstrated +empirically by dissection studies of fly grooming circuits (Seeds et al. 2014, +Curr Biol; Hampel et al. 2015, eLife). This document specifies how to apply +`ruvector-mincut` (`MinCutBuilder::new().exact().with_edges(...).build()`) and +its attention-gated sibling `ruvector-attn-mincut` to a +`ConnectomeGraph` (see 02-connectome-graph-substrate.md), what edge-weight +formulations are appropriate for different questions, how `DynamicMinCut` +supports incremental ablation experiments, and where spectral methods (Fiedler +vector, Cheeger inequality) complement combinatorial cuts. The claim that +RuView can defend is narrow and operational: given a behavior and a +connectome, we can automatically enumerate candidate minimal circuits +responsible for that behavior and rank them by fragility, with auditable +provenance. + +--- + +## Table of Contents + +1. Motivation and definitions +2. What a min-cut *means* on a connectome +3. Edge-weight formulations +4. Virtual source/sink patterns for circuit extraction +5. Algorithm choice: Stoer–Wagner, Karger–Stein, `DynamicMinCut` +6. Attention-gated mincut for behavior-conditioned extraction +7. Fragility metric and Cheeger bounds +8. Worked example: antennal grooming circuit +9. Spectral complement: Fiedler vector on the connectome Laplacian +10. Performance envelope at fly-brain scale +11. Integration with `ruvector-crv` Stage VI +12. Non-goals and caveats +13. References + +--- + +## 1. Motivation and Definitions + +Let $G = (V, E, w)$ be a weighted directed graph with vertex set $V$ of +neurons and edge set $E$ of synaptic contacts. Each edge $e = (u \to v)$ has +a weight $w(e) \in \mathbb{R}$ encoding some notion of how tightly neuron $u$ +influences neuron $v$. For two disjoint vertex sets $S, T \subset V$, an +$s$–$t$ cut is a partition $(A, \overline{A})$ with $S \subseteq A$ and +$T \subseteq \overline{A}$. The cut value is + +$$ + \operatorname{cut}(A) = \sum_{u \in A, \, v \in \overline{A}} w(u \to v). +$$ + +The minimum cut is $\min_A \operatorname{cut}(A)$. For connectomes, $S$ is +typically a sensory ensemble (e.g. antennal bristle mechanoreceptors) and $T$ +a motor ensemble (e.g. prothoracic leg motoneurons). The min-cut is the +smallest total synaptic weight one must remove to fully decouple $S$ from $T$. + +We distinguish three kinds of cut: + +| Cut type | Interpretation | +|----------|----------------| +| **Global min-cut** | Weakest link anywhere in the network | +| **$s$–$t$ min-cut** | Weakest connection between two named populations | +| **Balanced min-cut** (e.g. Cheeger) | Weakest partition into two roughly equal halves | + +For circuit discovery we almost always want the $s$–$t$ variant. RuView's +existing subcarrier partitioning (`signal/subcarrier.rs`) uses the same +pattern — virtual source, virtual sink, pairwise weights — so the +implementation-level idioms transfer directly. + +## 2. What a Min-Cut *Means* on a Connectome + +A common misconception is that a min-cut on a connectome reveals an +anatomical boundary. It does not. A connectome is rarely laid out such that +nearby neurons are strongly coupled; neuropils like the mushroom body contain +tens of thousands of neurons with long-range projections. The min-cut is a +**functional isolation boundary**: + +1. It identifies the set of synapses carrying the information flow from $S$ + to $T$. +2. Its weight is an upper bound on the maximum information flow + (by max-flow / min-cut duality, Ford–Fulkerson 1956). +3. Its edges are causally privileged: severing them interrupts + sensory-to-motor propagation. + +This is the same kind of structural claim that spectral graph theory makes +about the Fiedler vector (Fiedler 1973, Czech Math J) — a low algebraic +connectivity indicates the graph has a "weak seam" — but min-cut gives an +explicit edge set rather than a real-valued relaxation. + +## 3. Edge-Weight Formulations + +The choice of $w(e)$ encodes what question you are asking. Four options, in +increasing order of semantic richness: + +| Name | Formula | When appropriate | +|------|---------|------------------| +| **Raw synapse count** | $w(u \to v) =$ number of synaptic contacts | Baseline; no dynamics required; directly available in FlyWire data | +| **Transmitter-signed weight** | $w = \sigma_{\mathrm{NT}} \cdot \text{count}$ with $\sigma \in \{+1, -1\}$ for excitatory/inhibitory | When inhibition matters for the behavior (most behaviors) | +| **Activity-weighted count** | $w = \text{count} \cdot \rho(\text{rate}_u, \text{rate}_v)$ where $\rho$ is functional correlation | Requires a run of the neural dynamics runtime (see 04-neural-dynamics-runtime.md) | +| **Path-coherent weight** | $w =$ median cross-correlation lag-consistency over $k$ episodes | Requires a catalog of behavioral episodes (see 07-coherence-crv-behavioral-episodes.md) | + +`ruvector-mincut` expects edge capacities as `f64`. Signed weights cannot be +passed directly: standard max-flow requires non-negative capacities. The +canonical workaround is to pass $|w|$ and carry the sign in a side table that +post-processes the cut (dropping inhibitory cut-edges reduces the effective +disconnection). For balanced-cut variants, signed Laplacians and the +Hermitian extension of Fiedler (Kunegis et al. 2010, SDM) are more +principled; we return to these in Section 9. + +## 4. Virtual Source/Sink Patterns for Circuit Extraction + +The canonical RuView idiom (from `signal/subcarrier.rs`) is to insert two +virtual nodes — source $n$ and sink $n+1$ — and connect them to real nodes +using edges whose capacities encode class membership. For connectomes: + +```text +source s ──▶ every neuron in S with capacity = +∞ (or a large constant) +every neuron in T ──▶ sink t with capacity = +∞ +internal edges use w(u→v) +``` + +With infinite source/sink capacities the min $s$–$t$ cut is forced to lie +entirely among internal edges. If $|S|$ or $|T|$ is large — e.g. all 1352 +antennal bristle neurons — this scales without issue: the source/sink degrees +do not affect the cut value. + +For the `MinCutBuilder` API, the triplets are `Vec<(u64, u64, f64)>`. A +sketch: + +```rust +let source = n_neurons as u64; +let sink = n_neurons as u64 + 1; + +let mut edges = Vec::<(u64, u64, f64)>::new(); +for &src in &sensory_ids { edges.push((source, src, 1e18)); } +for &snk in &motor_ids { edges.push((snk, sink, 1e18)); } +for syn in graph.synapses() { + edges.push((syn.pre_id, syn.post_id, syn.weight as f64)); +} +let mc = MinCutBuilder::new().exact().with_edges(edges).build()?; +``` + +Because the builder accepts bidirectional flow, symmetric synaptic counts +(which FlyWire publishes as directed) need no mirror edges. The virtual +source/sink trick is the same one that forces the subcarrier partitioner to +bifurcate the sensitivity graph — only the semantics differ. + +## 5. Algorithm Choice + +`ruvector-mincut` exposes both exact and dynamic solvers. The decision table: + +| Use case | Recommended | Why | +|----------|-------------|-----| +| One-shot baseline cut | `exact()` with Stoer–Wagner-style | Deterministic, O(|V| · |E|) for non-negative weights, acceptable at 50k neurons | +| Monte Carlo over random pairs | Karger–Stein if exposed, else `exact()` with sampled $S$, $T$ | Randomized algorithms win on global cuts, not $s$–$t$ | +| Iterative ablation experiments | `DynamicMinCut` | Amortizes incremental edge reweighting; see 08-counterfactual-perturbation.md | +| Approximate + fast | attention-gated mincut (see Section 6) | Behavior-conditioned subgraph extraction in advance of exact cut | + +At ~50k neurons and ~1–3M synapses (a reasonable subgraph of FlyWire after +weight thresholding), a single exact $s$–$t$ cut is a sub-second operation on +a modern laptop. Ablation sweeps over 10³ synapses benefit from +`DynamicMinCut`'s amortization, which matches the usage pattern in +`signal/spectrogram.rs` where the attention-gated sibling is re-evaluated per +frame. + +## 6. Attention-Gated Mincut for Behavior-Conditioned Extraction + +`ruvector-attn-mincut` takes a mask or weight map that upweights edges +relevant to a query. In the signal-pipeline, the mask comes from a +spectrogram attention map; on a connectome, the mask is a **behavior-specific +activity mask** obtained from the neural dynamics runtime during a bout of +the target behavior. + +Pipeline: + +1. Run the LIF runtime (see 04-neural-dynamics-runtime.md) while the + embodied body (see 06-embodied-simulator-closed-loop.md) exhibits the + target behavior. +2. For each synapse, compute an attention weight $\alpha_{u \to v} = f\bigl(\mathrm{rate}_u, \mathrm{rate}_v, \mathrm{phase\,lag}\bigr)$. +3. Pass the attention-weighted graph to `ruvector-attn-mincut`. +4. The resulting cut is the minimal circuit responsible for the information + flow *during that behavior*, not the minimal circuit across all + behaviors. + +This is the connectome analog of finding a minimal radio-coherence boundary +around a specific mover. The attention gate is what turns a generic structural +mincut into a behavior-conditioned circuit discovery primitive. + +## 7. Fragility Metric and Cheeger Bounds + +Define the fragility of an $s$–$t$ cut $C$ as + +$$ + \mathcal{F}(C) = \frac{\operatorname{cut}(C)}{\min(\operatorname{vol}(A), \operatorname{vol}(\overline{A}))}, +$$ + +where $\operatorname{vol}(X) = \sum_{v \in X} d(v)$ is the weighted degree +of side $X$. This normalisation (the Cheeger or conductance form, Cheeger +1970) penalises cuts that isolate tiny disconnected fringes rather than +substantive sub-circuits. For a connectome, $\operatorname{vol}$ uses the +same weight $w$ chosen in Section 3. + +The Cheeger inequality gives + +$$ + \frac{\lambda_2}{2} \le \mathcal{F}_{\min} \le \sqrt{2 \, \lambda_2}, +$$ + +where $\lambda_2$ is the second-smallest eigenvalue of the normalised +Laplacian. For a connectome this bound is loose (fly-brain +$\lambda_2 \approx 10^{-3}$), but the direction it points — small $\lambda_2$ +implies fragile circuits — is what matters. The fragility metric becomes +directly comparable across circuits of different sizes, and the spectrum +provides a fast screening step before the exact combinatorial cut. + +Downstream protocols (counterfactual perturbation in +08-counterfactual-perturbation.md) compare $\mathcal{F}$ before and after an +ablation. A large fragility drop implies the ablated synapse was bridging a +real bottleneck. + +## 8. Worked Example: Antennal Grooming Circuit + +Hampel et al. 2015 (eLife) dissected the fly antennal grooming circuit by +showing that activating mechanosensory bristle neurons on the antenna +reliably elicits foreleg sweep of the head. Seeds et al. 2014 (Curr Biol) +traced the descending interneurons from the gnathal ganglion (GNG) that +command foreleg motoneurons. The connectome-level circuit has roughly this +footprint: + +| Compartment | Neuron count (approx) | Role | +|-------------|-----------------------|------| +| Antennal Johnston's-organ / bristles | ~1,300 | Sensory | +| GNG descending interneurons | ~150 | Command | +| Prothoracic leg motor neurons | ~50 | Effector | + +Applying the virtual source/sink pattern from Section 4 with $S =$ bristle +neurons and $T =$ foreleg MNs yields an $s$–$t$ cut dominated by GNG +descending interneurons. The predicted cut size is ~30–60 synapses in the +raw-count formulation; with transmitter signing it drops to ~20–40 once +inhibitory branches are excluded. This matches the empirical finding that a +small ensemble (single-digit number of cell types) is sufficient to abolish +the behavior when silenced optogenetically. + +The worked example returns in 10-acceptance-test-grooming.md as the concrete +test target for the compendium. + +## 9. Spectral Complement + +Min-cut gives a hard edge set; spectral methods give a continuous relaxation +that is easier to compute and often easier to interpret. The two are +complementary: + +| Method | Output | Computational cost | Best use | +|--------|--------|--------------------|----------| +| Exact $s$–$t$ min-cut | Binary edge mask | $O(|V| \cdot |E|)$ | Final circuit report | +| Fiedler vector | Real-valued node embedding | Sparse eigensolver $O(|E| \log |V|)$ | Fast screening, community proposals | +| Heat kernel | Smoothed partition | Matrix exponentiation | Multi-scale analysis | + +For the Fiedler approach, compute the second eigenvector of the normalised +Laplacian $L_{\text{norm}} = I - D^{-1/2} W D^{-1/2}$. Sign of each +coordinate gives a bipartition. The `ruvector-solver` Neumann series is not +a first-choice for eigensolves — it targets linear system solves with +spectral radius of $(I - A) < 1$ — but the same `CsrMatrix` machinery can +feed an ARPACK-style iterative eigensolver in a companion crate. In +practice we recommend: (i) Fiedler for screening, (ii) exact mincut on the +Fiedler-identified candidate cluster, (iii) `DynamicMinCut` for the +perturbation sweeps. + +Kunegis et al. 2010 (SIAM Data Mining) extend the spectral story to signed +graphs, which matters once transmitter signing enters the picture. + +## 10. Performance Envelope + +Concrete numbers for the regime the acceptance test (see +10-acceptance-test-grooming.md) targets: + +| Scale | Neurons | Synapses | Exact $s$–$t$ cut (est.) | Fragility sweep of 10³ ablations | +|-------|---------|----------|--------------------------|----------------------------------| +| Tiny | 1k | 20k | < 10 ms | 1–3 s | +| Small | 10k | 250k | 100–500 ms | 30–120 s | +| Medium | 50k | 2M | 1–5 s | 10–30 min | +| Fly-scale | 139k | 54M | 30–120 s | Several hours | + +Exact numbers depend on the Stoer–Wagner implementation constant inside +`ruvector-mincut`. The acceptance test sits comfortably inside the "Small to +Medium" band. Full fly-scale is aspirational for v1 and probably needs +sublinear approximation (cf. +`docs/research/rf-topological-sensing/05-sublinear-mincut-algorithms.md`). + +## 11. Integration with `ruvector-crv` Stage VI + +`CrvSessionManager::run_stage_vi` already calls a MinCut implementation to +partition accumulated session embeddings. The CRV Stage VI composite is thus +**already wired** to the same graph primitive we need for circuit discovery. +The integration pattern is: + +1. Record a behavior episode via `BehaviorPipeline::process_episode(...)` + (see 07-coherence-crv-behavioral-episodes.md). +2. Call `run_stage_vi` to partition the per-frame embeddings into + behavior-related vs background. +3. Lift the partition back to the connectome by intersecting behavior-related + frame embeddings with their originating neuron activity fingerprints. +4. Run the attention-gated mincut from Section 6 on the lifted set. +5. Emit the cut as a domain event `CircuitIdentified { cut_edges, + fragility }`. + +Stage VI does not replace the connectome-level cut — it operates on CRV +embeddings, not synapses — but it is the temporal gate that decides *which* +behavioral episode we are asking the circuit question about. + +## 12. Non-Goals and Caveats + +- **Min-cut is not causal inference.** A cut-edge is a structural bottleneck, + not a proof of causality. Causal claims require perturbation (see + 08-counterfactual-perturbation.md). +- **Min-cut ignores timing.** Axonal delays, oscillatory phase, and temporal + integration are outside the combinatorial formulation. Where these matter, + time-expanded graphs (Bui & Liem 2024, IEEE TKDE) or temporal-graph mincut + variants should be used. +- **Signed weights need care.** Running an unsigned max-flow on absolute + weights overestimates the cut when inhibitory branches are inside the cut; + post-processing is mandatory. +- **Plasticity drift.** In recurrent circuits with short-term plasticity, the + "connectome" changes on behavioral timescales. `DynamicMinCut`'s + incremental updates are meant for exactly this regime, but the baseline + graph must be re-observed, not assumed static. + +## 13. References + +1. Ford, L. R., & Fulkerson, D. R. (1956). *Maximal flow through a network.* + Canadian J. Math., 8, 399–404. +2. Fiedler, M. (1973). *Algebraic connectivity of graphs.* Czech. Math. J., + 23(98), 298–305. +3. Cheeger, J. (1970). *A lower bound for the smallest eigenvalue of the + Laplacian.* In Problems in Analysis, Princeton Univ Press. +4. Stoer, M., & Wagner, F. (1997). *A simple min-cut algorithm.* J. ACM, 44(4). +5. Karger, D. R., & Stein, C. (1996). *A new approach to the minimum cut + problem.* J. ACM, 43(4). +6. Kunegis, J., Schmidt, S., Lommatzsch, A., et al. (2010). *Spectral + analysis of signed graphs.* SIAM Data Mining. +7. Seeds, A. M., Ravbar, P., Chung, P., et al. (2014). *A suppression + hierarchy among competing motor programs drives sequential grooming in + Drosophila.* eLife / Curr Biol. +8. Hampel, S., Franconville, R., Simpson, J. H., Seeds, A. M. (2015). + *A neural command circuit for grooming movement control.* eLife. +9. Dorkenwald, S., Matsliah, A., Sterling, A. R., et al. (2024). + *Neuronal wiring diagram of an adult brain.* Nature (FlyWire). +10. Namiki, S., Dickinson, M. H., Wong, A. M., Korff, W., Card, G. M. + (2018). *The functional organization of descending sensory-motor + pathways in Drosophila.* eLife. +11. Bui, T. D., & Liem, N. T. (2024). *Temporal min-cut over event graphs.* + IEEE TKDE (preprint). +12. Winding, M., Pedigo, B. D., Barnes, C. L., et al. (2023). *The + connectome of an insect brain.* Science. +13. Brunel, N. (2000). *Dynamics of sparsely connected networks of + excitatory and inhibitory spiking neurons.* J. Comput. Neurosci., 8. +14. Ali, F., Laudet, V., Hampel, S. (2023). *Dissection of grooming circuit + components.* Curr Biol (methods review). + +--- + +**Next document**: 04-neural-dynamics-runtime.md — the LIF engine that +feeds the activity-weighted and attention-gated variants of the cut. diff --git a/docs/research/connectome-embodied-brain/04-neural-dynamics-runtime.md b/docs/research/connectome-embodied-brain/04-neural-dynamics-runtime.md new file mode 100644 index 00000000..1fd3d41e --- /dev/null +++ b/docs/research/connectome-embodied-brain/04-neural-dynamics-runtime.md @@ -0,0 +1,339 @@ +--- +Research Document ID: RD-C-04 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-085 +--- + +# RD-C-04: Neural Dynamics Runtime (Layer 2) + +## Abstract + +Layer 2 of CC-OS is the event-driven leaky integrate-and-fire (LIF) +runtime that consumes the typed `ConnectomeGraph` from Layer 1 and emits +per-neuron spikes and voltage traces. This document specifies the LIF +model, argues for event-driven rather than clock-driven simulation at +connectome scale, defines the data layout, identifies where +`ruvector-solver`'s Neumann series is applicable (quasi-steady-state +firing-rate approximation) and where it is not (event-driven spike +propagation), and specifies the compressed storage protocol built on +`ruvector-temporal-tensor`. We propose a new workspace crate +`wifi-densepose-neuro` and outline its module layout, dependencies, +determinism requirements, and performance targets (1 kHz real-time for +50k neurons on one workstation). + +--- + +## Table of Contents + +1. LIF neuron model +2. Event-driven vs clock-driven simulation +3. Data layout +4. Spike propagation +5. Sparse system solves with `ruvector-solver` +6. Voltage and spike-train storage with `ruvector-temporal-tensor` +7. Replay and motif retrieval +8. Scheduling and concurrency +9. Determinism and witness logs +10. Proposed crate: `wifi-densepose-neuro` +11. Performance targets and benchmarks +12. Non-goals +13. References + +--- + +## 1. LIF Neuron Model + +The canonical single-compartment LIF (Brunel 2000, *J Comput Neurosci*): + +$$ + \tau_m \frac{dV_i}{dt} = -(V_i - V_{\text{rest}}) + R_m I_i(t), +$$ + +with a reset rule: when $V_i \ge V_\theta$, emit a spike and clamp $V_i$ to +$V_{\text{reset}}$ for $\tau_{\text{ref}}$ ms. Synaptic current +$I_i(t) = \sum_j w_{ij} \cdot \sum_{s \in \text{spikes}(j)} \kappa(t - s - \delta_{ij})$ +where $\kappa$ is an exponential or alpha kernel. Default parameters per +neuron class: + +| Parameter | Sensory | Interneuron | Motor | Units | +|-----------|---------|-------------|-------|-------| +| $\tau_m$ | 10 | 15 | 20 | ms | +| $V_{\text{rest}}$ | −65 | −65 | −65 | mV | +| $V_\theta$ | −50 | −50 | −55 | mV | +| $V_{\text{reset}}$ | −70 | −70 | −70 | mV | +| $\tau_{\text{ref}}$ | 2 | 2 | 3 | ms | +| $\tau_{\text{syn}}$ (exc.) | 3 | 3 | 3 | ms | +| $\tau_{\text{syn}}$ (inh.) | 8 | 8 | 8 | ms | + +These are literature defaults; real runs should override per-cell-type +where published data exists (Kakaria & de Bivort 2017 for central complex). + +## 2. Event-Driven vs Clock-Driven + +At 50k neurons with a mean firing rate of 5 Hz, the network emits ~250k +spikes per simulated second. A clock-driven step at 1 kHz visits every +neuron every step — 50M updates/s — regardless of activity. Event-driven +visits only firing neurons and their postsynaptic targets — 250k × 400 = +100M updates/s in the worst case but with better cache behaviour because +updates cluster around active populations. + +| Dimension | Clock-driven | Event-driven | +|-----------|--------------|--------------| +| Determinism | Easy (step order) | Harder (priority queue tiebreaks) | +| Parallelism | Embarrassingly parallel | Spike-queue contention | +| Low-rate neurons | Wasteful | Efficient | +| Dense transient bursts | Efficient | Queue grows | +| Voltage log cadence | Fixed | Interpolated | + +CC-OS chooses **event-driven with 1 kHz voltage sampling**: spikes drive +state changes, but a fixed-rate sampler still records voltage every ms for +the temporal-tensor storage. This matches the existing +`mat/breathing.rs`-style fixed-rate push semantics. + +## 3. Data Layout + +```text +State { + v: Vec, // length = n_neurons — membrane potentials + last_spike_ms: Vec, // length = n_neurons — for refractory check + csr_adjacency: CsrAdjacency, // read-only view of ConnectomeGraph + spike_queue: BinaryHeap, + rng: DeterministicRng, + t_ms: f32, +} + +ScheduledSpike { + at_ms: f32, + pre_id: u64, + post_id: u64, + weight: f32, +} +``` + +`BinaryHeap` is `std`'s max-heap; we wrap it with `Reverse` to get a +min-heap keyed on `at_ms`. Ties broken by `(pre_id, post_id)` for +determinism. See §9. + +## 4. Spike Propagation + +When neuron $i$ fires at time $t$: + +```text +for each outgoing synapse (i → j) in csr_adjacency.out_edges(i): + delay = synapse.axonal_delay_ms + arrival = t + delay + weight = synapse.weight × synapse.sign + push ScheduledSpike { at_ms: arrival, pre_id: i, post_id: j, weight } +``` + +The spike queue is drained up to the current timestep. Each drained event +adds $\kappa(0) \cdot w$ to the target neuron's voltage (using the +synaptic kernel at its peak, then decaying between events). + +## 5. Sparse System Solves with `ruvector-solver` + +The Neumann series solver $(I - A)^{-1} b = \sum_k A^k b$ converges when +the spectral radius $\rho(A) < 1$. This rules out direct simulation of +the LIF dynamic matrix — the fly connectome has $\rho \gg 1$ when raw +synapse counts are used — but it is well-suited to two specific +sub-problems: + +### 5.1 Quasi-steady-state firing rates + +For tonic-stimulus analysis, the firing-rate equation +$r = \phi(W r + I)$ can be linearised around a fixed point and solved via +Neumann series if $W$ is appropriately scaled. This is the same use case +the `mat/triangulation.rs` TDoA solver relies on: matrix entries near +unity so the series converges. The scaling factor must be computed per +run; Kakaria & de Bivort 2017 give the scaling convention. + +### 5.2 Backward influence for perturbation + +If we want "how does a change at neuron $j$ propagate to neuron $k$ +through the linear part?", the Neumann series gives a truncated +$\sum_{k \le K} A^k$ solution that is the right approximation for small +perturbations. This feeds the fragility metric of 03 §7 and the +counterfactual protocol of 08. + +### 5.3 `CsrMatrix` construction + +```rust +use ruvector_solver::types::CsrMatrix; +use ruvector_solver::neumann::NeumannSolver; + +// triplets: (row, col, value) — scale weights so spectral radius < 1 +let triplets: Vec<(usize, usize, f32)> = graph.synapses() + .map(|s| (s.post_id as usize, s.pre_id as usize, (s.weight as f32) * scale_factor)) + .collect(); + +let a = CsrMatrix::::from_coo(n_neurons, n_neurons, triplets); +let b = vec![1.0_f32; n_neurons]; // external drive + +let solver = NeumannSolver::new(1e-5, 500); +let result = solver.solve(&a, &b)?; +let rates = result.solution; +``` + +## 6. Voltage and Spike-Train Storage + +### 6.1 Voltage (per-neuron, 1 kHz) + +Use the `VoltageBuffer` pattern from 02 §7, which delegates to +`TemporalTensorCompressor`. At 50k neurons × 1 kHz × 60 s × 4 B = 12 GB +raw; tiered 8/5–7/3-bit brings this to ~3 GB. Stored as an append-only +log of compressed segments. + +### 6.2 Spike trains + +Two encodings: + +**Dense bit-vector per timestep.** `[n_timesteps / 8, n_neurons]` with 1 +bit per spike. For a 5 Hz mean rate this is sparse in time, so the +temporal-tensor's 3-bit cold tier compresses it aggressively. + +**Event list.** `Vec<(neuron_id, t_ms)>` — 16 bytes per spike. For 250k +spikes/s over 60 s = 15M events = 240 MB. No temporal-tensor compression +needed; sorting by `(t_ms, neuron_id)` gives fast window queries. + +Default: dual write. Bit-vector for replay; event list for analysis +queries. + +## 7. Replay and Motif Retrieval + +Replay is a deterministic re-execution of the LIF runtime seeded from the +same RNG, producing bit-identical spike trains. This is the foundation of +the witness-bundle (§9) and the counterfactual protocol (08). + +Motif retrieval uses the per-neuron embeddings from 02 §6 plus short +spike-train signatures. `ruvector-attention` provides +`ScaledDotProductAttention` which is enough to score motif similarity +between the current episode and a library of previously observed +episodes. See 05-cross-region-attention-fusion.md for the region-level +treatment. + +## 8. Scheduling and Concurrency + +| Component | Concurrency class | Why | +|-----------|-------------------|-----| +| Spike queue drain | Single-threaded | ordering is deterministic | +| Post-synaptic voltage updates | Rayon-parallel | disjoint targets within a time slot | +| Voltage sampler | Single-threaded | 1 kHz cadence | +| Compressed segment writer | `tokio` task | I/O | +| Analysis queries | `tokio` tasks | read-only graph access | + +The inner loop is deliberately single-threaded to preserve ordering. At +250k spikes/s each triggering ~400 updates, a tight Rayon parallel fan-out +per time slot delivers the needed throughput without breaking ordering +(updates within a single time slot commute because they modify different +neurons). + +## 9. Determinism and Witness Logs + +Determinism sources: + +- Fixed seed RNG (`rand_chacha::ChaCha20Rng::seed_from_u64(seed)`). +- Ordered event tiebreaks: `(t_ms, pre_id, post_id)`. +- Monotonic timestep integer; no wall-clock dependence. + +Witness log schema (reuses ADR-028 pattern): + +```text +run_manifest.json { + connectome_sha256: "...", + config_sha256: "...", + seed: 42, + n_neurons: 50000, + n_synapses: 2000000, + duration_ms: 60000, + voltage_buffer_id: "vbuf-0", + spike_log_id: "splog-0", + output_sha256: "...", // hash of concatenated compressed segments +} +``` + +Re-running with the same seed + graph + config reproduces the same +`output_sha256`. Divergence indicates non-determinism bugs. + +## 10. Proposed Crate: `wifi-densepose-neuro` + +Location: `rust-port/wifi-densepose-rs/crates/wifi-densepose-neuro/` + +```text +src/ +├── lib.rs re-exports +├── lif.rs LIF neuron kernel, parameters, refractory +├── scheduler.rs spike queue, time stepping +├── propagate.rs fan-out, weight application, Rayon parallel slot +├── solver.rs ruvector-solver adapter (rate-code, perturbation) +├── storage.rs VoltageBuffer, SpikeLog wrappers +├── replay.rs deterministic re-execution harness +├── witness.rs ADR-028 witness bundle writer +└── config.rs serde-backed run configuration +``` + +Dependencies (workspace): + +```toml +wifi-densepose-core = { path = "../wifi-densepose-core" } +wifi-densepose-ruvector = { path = "../wifi-densepose-ruvector" } +ruvector-solver = { workspace = true } +ruvector-attention = { workspace = true } +ruvector-temporal-tensor = { workspace = true } +rand_chacha = "0.3" +rayon = "1.8" +thiserror = { workspace = true } +serde = { workspace = true } +``` + +Publishing order: insert between `wifi-densepose-ruvector` and +`wifi-densepose-train` in the order established in `CLAUDE.md`. + +## 11. Performance Targets + +| Scale | Spike throughput | Voltage write | Wall-clock per 1 s sim | +|-------|------------------|---------------|------------------------| +| 10k neurons | 50k spikes/s | 40 MB/s raw | 0.3 s (3.3× realtime) | +| 50k neurons | 250k spikes/s | 200 MB/s raw | 1.0 s (1.0× realtime) | +| 139k neurons (full fly) | 700k spikes/s | 560 MB/s raw | 3–5 s (0.2–0.3× realtime) | + +Benchmarks to track (Criterion, matching existing repo convention): + +- `bench/lif_kernel_throughput` — raw spikes/s for a synthetic Poisson + network at fixed density. +- `bench/csr_adjacency_fanout` — post-synaptic update cost per spike. +- `bench/voltage_buffer_compression` — TemporalTensorCompressor push + latency. +- `bench/replay_reproducibility` — SHA-256 equality after 10 s replay. + +## 12. Non-Goals + +- **Hodgkin–Huxley detail** — single-compartment LIF only. +- **Multi-compartment dendrites** — out of scope. +- **NEURON / Brian2 interchange** — not attempted; CC-OS emits its own + format. +- **Learning rules inside the spike loop** — STP/LTP/LTD scaffolded in + the edge schema (02 §3) but not executed online in v1. +- **GPU path** — v1 is CPU-only; GPU is a v2 target. + +## 13. References + +1. Brunel, N. (2000). *Dynamics of sparsely connected networks of + excitatory and inhibitory spiking neurons.* J. Comput. Neurosci. +2. Izhikevich, E. M. (2003). *Simple model of spiking neurons.* IEEE TNN. +3. Kakaria, K. S., de Bivort, B. L. (2017). *Ring attractor dynamics + emerge from a spiking model of the entire protocerebral bridge.* + Front. Behav. Neurosci. +4. Lappalainen, J. K., et al. (2024). *Connectome-constrained networks + predict neural activity across the fly visual system.* Nature. +5. ADR-028 — ESP32 capability audit + witness verification. +6. RuVector v2.0.4 crate docs — `ruvector-solver`, + `ruvector-temporal-tensor`, `ruvector-attention`. +7. Dorkenwald, S., et al. (2024). *Neuronal wiring diagram of an adult + brain.* Nature. + +--- + +**Next**: 05-cross-region-attention-fusion.md — lifting the +`MultistaticArray` pattern to brain regions. diff --git a/docs/research/connectome-embodied-brain/05-cross-region-attention-fusion.md b/docs/research/connectome-embodied-brain/05-cross-region-attention-fusion.md new file mode 100644 index 00000000..ca25fa76 --- /dev/null +++ b/docs/research/connectome-embodied-brain/05-cross-region-attention-fusion.md @@ -0,0 +1,276 @@ +--- +Research Document ID: RD-C-05 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-085 +--- + +# RD-C-05: Cross-Region Attention Fusion (Layer 2 / Layer 4 bridge) + +## Abstract + +The fly brain contains ~80 anatomically defined neuropils (AL, MB, CX, +LAL, GNG, VNC, etc.), each computing partial representations of the +environment and internal state. Fusing their activity into a single +decision-relevant embedding is the neural analog of the multistatic +WiFi-sensing fusion already implemented in +`rust-port/.../viewpoint/fusion.rs`. This document specifies +`NeuralFusionArray`, a DDD aggregate root that mirrors the existing +`MultistaticArray` — cross-viewpoint scaled dot-product attention with a +geometric bias term, gated by a rolling coherence window and described +by a geometric diversity index — but re-targets every component from RF +viewpoints to connectomic regions. The resulting fused embedding feeds +downstream CRV behavioral-episode encoding (07) and min-cut +behavior-conditioned circuit extraction (03 §6). + +--- + +## Table of Contents + +1. Motivation — regions as viewpoints +2. Direct analogy to `MultistaticArray` +3. Region activity embedding +4. Geometric bias in connectomic space +5. Coherence gate on population state +6. Functional Diversity Index (connectomic GDI analog) +7. `NeuralFusionArray` aggregate +8. Worked example — mushroom-body attention during foraging +9. Integration with LIF runtime +10. Non-goals +11. References + +--- + +## 1. Motivation — Regions as Viewpoints + +The multistatic WiFi sensing pipeline treats each access point as a +viewpoint on the propagation environment: the scene exists, and each AP +samples it from a geometrically distinct vantage. The fusion aggregate +combines these into a single scene embedding weighted by how much each +viewpoint adds (angle diversity, baseline distance, SNR). + +A connectome has the same structure at the region level. The organism's +state exists; each neuropil samples a partial view (visual, olfactory, +mechanosensory, contextual, motor-plan-in-progress, etc.); those views +must be fused into a coherent behavioral signal. The mathematical +machinery — scaled dot-product attention with a learned query over +key–value region embeddings — is identical. + +## 2. Direct Analogy to `MultistaticArray` + +| `viewpoint/fusion.rs` concept | Neural analog | +|-------------------------------|---------------| +| `ViewpointEmbedding` | `RegionEmbedding` | +| `NodeId` (u32) | `RegionId` (u16) | +| `azimuth`, `elevation` | angular position in region meta-graph (optional) | +| `baseline` distance | connectomic path-length to "reference" region | +| `snr_db` | mean firing rate / recent signal-to-background | +| `GeometricBias` | `ConnectomicBias` — path-length + transmitter-sign modifier | +| `CrossViewpointAttention` | `CrossRegionAttention` (same SDPA kernel) | +| `CoherenceGate` | unchanged; gate on population phase coherence | +| `GeometricDiversityIndex` | `FunctionalDiversityIndex` | +| `MultistaticArray` aggregate root | `NeuralFusionArray` aggregate root | + +The reuse is structural, not literal: we do not import +`MultistaticArray` for neural use; we copy its shape into a sibling +aggregate in the proposed `wifi-densepose-neuro` crate. + +## 3. Region Activity Embedding + +```text +RegionEmbedding { + region_id: RegionId, + embedding: Vec, // length = d_model (typically 128) + mean_rate_hz: f32, + phase_vector: [f32; 2], // unit-norm (cos θ, sin θ) + baseline_mu: f32, // connectomic distance to anchor region + snr_proxy: f32, // recent mean rate / background + t_ms: f32, +} +``` + +Construction: at a given simulation time $t$, for each region, +aggregate the last 50 ms of spikes and rates over every neuron in that +region into a fixed-length vector. Two simple constructors: + +1. **Rate histogram.** Bin spike counts by neuron class (sensory / + interneuron / motor), pad to `d_model`. +2. **Mean-pooled per-neuron embedding.** Average `NeuronEmbedding` + weights (02 §6) over neurons active in the window. + +Mean-pooled is more expressive; rate histogram is cheaper and serves as +a default. + +## 4. Geometric Bias in Connectomic Space + +`viewpoint/fusion.rs` `GeometricBias` encodes angular separation and +baseline distance between viewpoint pairs. The connectomic analog: + +$$ + G^{\text{conn}}_{ij} = -w_{\text{dist}} \cdot \frac{d_{ij}^{\text{path}}}{d_{\text{ref}}} + - w_{\text{sign}} \cdot \mathbb{1}[\mathrm{sign}(ij) < 0], +$$ + +where $d_{ij}^{\text{path}}$ is the shortest weighted path length between +regions $i$ and $j$ in the `RegionGraph`, $d_{\text{ref}}$ is the median +pairwise path length, and the sign term penalises predominantly-inhibitory +region-region connections so that attention prefers cooperative pairs. +Added to the query-key logits inside the softmax; same shape as the RF +case. + +## 5. Coherence Gate on Population State + +The neural coherence signal (Accept / PredictOnly / Reject / Recalibrate) +uses the same hysteresis gate as `viewpoint/coherence.rs` +`CoherenceGate`, re-seeded with a neural coherence definition: + +$$ + C(t) = \frac{1}{N_{\text{reg}}} \sum_r \Bigl\lVert \frac{1}{|r|} \sum_{i \in r} e^{i \phi_i(t)} \Bigr\rVert, +$$ + +a mean across regions of each region's population-vector phasor +magnitude. Accept when $C(t)$ is above threshold with hysteresis; +PredictOnly in the hysteresis band; Reject when below; Recalibrate on +detected drift. + +Thresholds (starting values): + +| State | $C(t)$ range | +|-------|--------------| +| Accept | ≥ 0.6 | +| PredictOnly | 0.5–0.6 | +| Reject | < 0.5 | +| Recalibrate | $\|\Delta C\| > 0.2$ within 100 ms | + +## 6. Functional Diversity Index + +The `GeometricDiversityIndex` in `viewpoint/geometry.rs` measures how +well-spread viewpoints are. For regions, we use a functional-spread +analog: + +$$ + \mathrm{FDI} = \frac{1}{N_{\text{reg}}} \sum_r \min_{r' \ne r} \, 1 - \cos\bigl(e_r, e_{r'}\bigr), +$$ + +the mean cosine-distance from each region's embedding to its nearest +neighbour. High FDI means regions produce distinct representations +(cooperative fusion is informative); low FDI means they are redundant +(fusion adds little). + +Cramer-Rao-analog uncertainty bounds on behavioral decoding follow from +constructing the Fisher information matrix over region embeddings and +inverting via `ruvector-solver`'s `NeumannSolver` (same pattern as +`viewpoint/geometry.rs` §4). This mirrors the RF Cramer-Rao bound +almost verbatim. + +## 7. `NeuralFusionArray` Aggregate + +```text +NeuralFusionArray { + id: ArrayId, // u64 + config: FusionConfig, // same shape as viewpoint::FusionConfig + coherence_gate: CoherenceGate, // reuse impl + fdi: FunctionalDiversityIndex,// computed on fuse() +} + +FusionConfig { + embed_dim: usize, // 128 + coherence_threshold: f32, // 0.6 + coherence_hysteresis: f32, // 0.05 + coherence_window: usize, // 50 frames @ 1 kHz = 50 ms + w_dist: f32, // geometric-bias distance weight + w_sign: f32, // inhibitory penalty weight + d_ref: f32, // reference path length (connectomic units) + min_rate_hz: f32, // per-region minimum mean rate to contribute +} + +FusedEmbedding { + embedding: Vec, + fdi: f32, + coherence: f32, + n_regions: usize, + n_effective: f32, +} +``` + +Fuse pipeline (matches `viewpoint/fusion.rs`): + +1. Filter `RegionEmbedding`s by `min_rate_hz` (SNR analog). +2. Compute FDI from the surviving set. +3. Compute ConnectomicBias matrix. +4. Run `ScaledDotProductAttention::new(d_model).compute(&query, &keys, &values)` with bias-adjusted query. +5. Check `CoherenceGate`; if Reject or PredictOnly, emit the fused vector with a `coherence` tag so downstream can discount. +6. Emit `FusedEmbedding`. + +## 8. Worked Example — Mushroom-Body Attention During Foraging + +During a foraging bout the mushroom body (MB) attends to olfactory +glomeruli that encode the relevant odor and the central complex (CX) +attends to current heading. Expected pattern: + +| Region | Pre-foraging attention weight | During foraging | +|--------|-------------------------------|-----------------| +| AL (olfactory glomeruli) | 0.1 | 0.35 | +| MB (Kenyon cells) | 0.1 | 0.40 | +| CX (EB/FB/PB) | 0.2 | 0.10 | +| LAL (steering motor) | 0.1 | 0.05 | +| VLP (visual LP) | 0.2 | 0.05 | +| GNG (grooming premotor) | 0.1 | 0.01 | +| VNC (motor) | 0.2 | 0.04 | + +The precise numbers depend on fit quality; the qualitative shift — AL +and MB gain weight at the expense of GNG/VLP — is a falsifiable +prediction. Cross-behavior attention maps are published in Lappalainen +2024 for vision; equivalent for olfaction is less mature and a natural +CC-OS output. + +## 9. Integration with LIF Runtime + +`NeuralFusionArray` is re-evaluated every `fusion_period_ms` (default +50 ms) during a simulation run: + +```text +every fusion_period_ms: + for each region r: + build RegionEmbedding from last 50 ms of spikes + fused = NeuralFusionArray.fuse(region_embeddings) + if fused.coherence ≥ threshold: + hand fused to BehaviorPipeline (07) + else: + record as "uncertain" in witness log +``` + +This is the handoff between Layer 2 (LIF runtime) and Layer 4 (analysis +and behavioral-episode encoding). It is architecturally symmetric with +the RF pipeline, where CSI frames feed the existing fusion before +behavioral claims are made. + +## 10. Non-Goals + +- **Biologically plausible global workspace theory.** `NeuralFusionArray` + is a computational fusion aggregate, not a model of conscious + broadcasting. +- **Trainable attention weights.** The attention is parameter-free SDPA + over connectome-derived embeddings; no gradient-based tuning in v1. +- **Real-time long-range delays.** Bias term approximates path-length + effect; not a substitute for explicit delay modelling. + +## 11. References + +1. Vaswani, A., et al. (2017). *Attention is all you need.* NeurIPS. +2. Lappalainen, J. K., et al. (2024). *Connectome-constrained networks + predict neural activity across the fly visual system.* Nature. +3. Aso, Y., Sitaraman, D., Ichinose, T., et al. (2014). *Mushroom body + output neurons encode valence and guide memory-based action + selection.* eLife. (mushroom-body attention precedent.) +4. Turner-Evans, D. B., Jayaraman, V. (2016). *The insect central + complex.* Curr Biol. +5. RuView `viewpoint/fusion.rs` (crate `wifi-densepose-ruvector`). +6. RuVector v2.0.4 crate docs — `ruvector-attention`, + `ruvector-solver`. + +--- + +**Next**: 06-embodied-simulator-closed-loop.md — closing the sensorimotor +loop through a virtual body. diff --git a/docs/research/connectome-embodied-brain/06-embodied-simulator-closed-loop.md b/docs/research/connectome-embodied-brain/06-embodied-simulator-closed-loop.md new file mode 100644 index 00000000..e6363d7d --- /dev/null +++ b/docs/research/connectome-embodied-brain/06-embodied-simulator-closed-loop.md @@ -0,0 +1,289 @@ +--- +Research Document ID: RD-C-06 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-086 +--- + +# RD-C-06: Embodied Simulator — Closed Sensorimotor Loop (Layer 3) + +## Abstract + +Without a body, connectome dynamics simulate a disembodied sensor +network; the behaviors we want to study — grooming, walking, feeding — +exist only when motor output reaches a physical body and sensory input +comes back as contact, proprioception, and optic flow. Layer 3 of CC-OS +is a closed-loop embodied simulator. We compare candidate platforms +(NeuroMechFly v1/v2, MuJoCo / MJX, Brax, PyBullet, Isaac Gym, Rapier), +recommend a **Rapier-native Rust inner loop with an optional +NeuroMechFly bridge** for biomechanical-validation runs, specify the +sensory encoders (bristle mechanosensors, Johnston's-organ +proprioception, optional ocellar luminance), the motor decoders +(descending MN rate → joint torque), the latency budget required to +sustain 100–1000 Hz control, and the witness-log schema that keeps every +closed-loop bout auditable. + +--- + +## Table of Contents + +1. Requirements +2. Platform comparison +3. Recommendation +4. Body schema +5. Sensory adapters +6. Motor adapters +7. Latency budget +8. Cross-process vs in-process bridges +9. Proposed crate: `wifi-densepose-embody` +10. Witness and provenance +11. Failure modes +12. Non-goals +13. References + +--- + +## 1. Requirements + +| Requirement | Target | Notes | +|-------------|--------|-------| +| Articulated body | Yes | 60–80 DoF for fly | +| Contact sensing | Yes | For grooming and substrate interaction | +| Proprioception | Yes | Joint angle + angular velocity | +| Vision (optional v1) | No | Adds ~1 ms per frame if simple | +| Physics rate | ≥ 1 kHz | To not starve LIF inner loop | +| Control rate | 100–1000 Hz | LIF fan-out cadence | +| Determinism | Yes (seeded) | Witness-log compatibility | +| Round-trip latency | < 10 ms @ 100 Hz control; < 1 ms aspirational | Tight neural-body coupling | + +## 2. Platform Comparison + +| Platform | Language | Body model | Physics | In-proc with Rust? | Pro | Con | +|----------|----------|-----------|---------|--------------------|-----|-----| +| NeuroMechFly v1 | Python + MuJoCo | Published fly | Rigid + contact | IPC only | Biomechanically validated | Python overhead, platform-specific | +| NeuroMechFly v2 | Python + MuJoCo-MJX | Published fly + vision | JAX | IPC only | Adds vision | Heavier stack | +| MuJoCo (bare) | C / Python | Author-your-own | Rigid + contact | FFI possible | Fast, reliable | Body must be authored | +| MJX | JAX | — | JAX-vectorised | Poor | Fast batched rollouts | Not for 1-instance realtime | +| Brax | JAX | — | Rigid | Poor | Fast, modern | Same | +| PyBullet | Python (wraps Bullet) | — | Rigid + contact | IPC | Easy | Medium fidelity | +| Isaac Gym | C++/Python | — | PhysX | Poor | Massive parallel RL | GPU-only, not auditable | +| **Rapier** | **Rust** | Authorable | Rigid + contact | **Yes, in-proc** | Native Rust, deterministic | No published fly body | + +## 3. Recommendation + +**v1 (internal)**: Rapier-native Rust inner loop with a hand-authored +minimal fly body. Prioritises determinism, latency, and staying inside +the Rust workspace. + +**v1 (validation)**: NeuroMechFly bridge over shared memory or gRPC for +biomechanical cross-checks. The tight inner loop stays in Rust; periodic +validation runs use NeuroMechFly as ground truth. + +**v2 (optional)**: MJX or Brax for parallel rollouts when exploring +perturbation sweeps. + +## 4. Body Schema + +Minimal fly body for v1: 6 legs × 5 joints + head (2) + abdomen (3) + +antennae (3 × 2) = 41 DoF. NeuroMechFly v2 goes to ~70 DoF including +detailed wing articulation; we skip wings in v1. + +```text +FlyBody { + joints: Vec, // ~41 + links: Vec, + sensors: Vec, // contact, bristle, Johnston's + actuators: Vec, // joint torque / position + contact_model: ContactModel, // friction coefficients +} + +Sensor ::= Bristle { link_id, threshold_n } + | Johnston { joint_id } // antennal JO mechanosensor + | LegContact { link_id } + | Optic { link_id, fov } // v2 + +Actuator ::= JointTorque { joint_id, max_nm } + | JointPosition { joint_id, pd_gains } +``` + +## 5. Sensory Adapters + +Sensor → spike-input injector. Each physical sensor maps to a pool of +sensory neurons (02 §2) whose IDs come from the loaded connectome. + +### 5.1 Bristle mechanoreceptors + +```text +on bristle contact force f ≥ threshold: + rate_hz = saturating(α · f, max_rate_hz) + emit Poisson spike train into bristle-neuron pool +``` + +Maps to the ~1,300 FlyWire bristle neurons listed as sensory class. + +### 5.2 Johnston's-organ proprioception + +Antennal angle velocity drives a Poisson rate into JO pool. Pool size +~480 in FlyWire. Reference: Tuthill & Wilson 2016 (*Curr Biol*). + +### 5.3 Leg contact + +Binary contact → pulse train into corresponding leg contact pool (if +present in the subgraph; optional). + +## 6. Motor Adapters + +Descending motor neuron population rate → joint command. + +### 6.1 Rate-coded torque + +$$ + \tau_{\text{joint}} = g \cdot \sum_{i \in \text{MN pool}} (r_i - r_{\text{baseline}}), +$$ + +with $g$ a calibration gain and $r_{\text{baseline}}$ a per-pool tonic +rate. For antennal grooming, the prothoracic-leg MN pool maps onto leg +joint torques around the sweep arc. + +### 6.2 Central pattern generators (CPG) + +For locomotion (not the v1 acceptance target), Cruse 1990 Walknet +provides a phase-coupling model between legs that can be layered on top +of the motor adapters. Out of scope for v1 but worth noting as a +v2 extension. + +## 7. Latency Budget + +At 100 Hz closed-loop control: + +| Stage | Budget | Notes | +|-------|--------|-------| +| Sensor read + encoding | 0.5 ms | per frame | +| Spike injection | 0.1 ms | into priority queue | +| LIF step | 5 ms | for 50k neurons (§ 04-11) scaled to 10 ms window | +| Region fusion | 0.5 ms | 80 regions × 128-d | +| CRV episode encoding | 1 ms | occasional | +| Motor decoding | 0.2 ms | per active pool | +| Physics step | 1 ms | at 1 kHz physics | +| Total | < 10 ms | target met | + +For 1 kHz control (aspirational), every stage must shrink 10×. Feasible +with reduced-subgraph LIF, batched fusion, and careful no-alloc inner +loops. + +## 8. Cross-Process vs In-Process Bridges + +| Bridge | Overhead | Determinism | When | +|--------|----------|-------------|------| +| Rapier in-proc FFI | < 1 µs | Yes (seeded) | v1 tight loop | +| Shared memory (NeuroMechFly) | 20–50 µs | Needs coordination | Validation runs | +| gRPC localhost | 200–500 µs | Needs timestamps | Debugging / UI | +| TCP remote | 1–5 ms | Difficult | Not recommended | + +## 9. Proposed Crate: `wifi-densepose-embody` + +Location: `rust-port/wifi-densepose-rs/crates/wifi-densepose-embody/` + +```text +src/ +├── lib.rs +├── body.rs Body schema, URDF-ish loader +├── sensors.rs Encoders: bristle, JO, contact, optic +├── actuators.rs Decoders: torque, PD, CPG stub +├── physics.rs Rapier integration +├── bridge_nmf.rs Optional NeuroMechFly bridge (feature-gated) +├── witness.rs ADR-028 body-state bundle writer +└── config.rs +``` + +Dependencies: + +```toml +wifi-densepose-core = { path = "../wifi-densepose-core" } +wifi-densepose-neuro = { path = "../wifi-densepose-neuro" } # Layer 2 +rapier3d = "0.18" +serde = { workspace = true } +thiserror = { workspace = true } +``` + +Feature flags: + +```toml +[features] +default = [] +nmf-bridge = ["dep:zmq"] # optional +vision = [] # v2 +``` + +Publishing order: after `wifi-densepose-neuro`, before +`wifi-densepose-mat`. + +## 10. Witness and Provenance + +Every closed-loop bout produces: + +```text +bout_manifest.json { + bout_id: "bout-0001", + seed: 42, + connectome_sha256: "...", + body_sha256: "...", + config_sha256: "...", + t_start_ms: 0, + t_end_ms: 10000, + frames_compressed: "bout-0001-frames.ttseg", // TemporalTensorCompressor + voltage_ref: "vbuf-0", + spike_ref: "splog-0", + output_sha256: "...", +} +``` + +Frames are body-state + sensor readings compressed via the same +TemporalTensorCompressor pattern (02 §7). Replaying the bout produces a +byte-identical SHA-256 if and only if the LIF runtime and the physics +are both deterministic under the seed. + +## 11. Failure Modes + +| Failure | Signature | Mitigation | +|---------|-----------|------------| +| Physics divergence | NaN joint angles | Clamp + halt + emit `PhysicsDiverged` event | +| Spike firehose | Queue length > threshold | Throttle or drop to PredictOnly coherence state (05) | +| Actuator saturation | Torque > max | Clip + warn | +| Sensor aliasing | Rate exceeds neuron pool refractory | Decimate encoding | +| Starved LIF | Simulation time lags wall-clock | Reduce control rate or subgraph size | +| Non-deterministic replay | SHA-256 mismatch | Re-examine RNG seeding and tiebreaks | + +## 12. Non-Goals + +- **Full wing + flight aerodynamics** — v2 target; requires air-model and + much higher physics fidelity. +- **Fluid dynamics** (e.g. olfactory plume modelling) — external tool. +- **Photorealistic rendering** — not relevant; optical-flow only at + most. +- **Multi-agent interactions** — single-organism v1. + +## 13. References + +1. Lobato-Rios, V., et al. (2022). *NeuroMechFly, a neuromechanical model + of adult Drosophila melanogaster.* Nat Methods. +2. Wang-Chen, S., et al. (2024). *NeuroMechFly v2 with vision (preprint).* +3. Todorov, E., Erez, T., Tassa, Y. (2012). *MuJoCo: A physics engine for + model-based control.* IROS. +4. Freeman, C. D., et al. (2021). *Brax — a differentiable physics + engine.* NeurIPS workshop. +5. Cruse, H. (1990). *What mechanisms coordinate leg movement in walking + arthropods?* Trends Neurosci. +6. Tuthill, J. C., Wilson, R. I. (2016). *Mechanosensation and adaptive + motor control in insects.* Curr Biol. +7. Seeds, A. M., et al. (2014). *A suppression hierarchy among competing + motor programs drives sequential grooming in Drosophila.* eLife. +8. Rapier physics engine docs — https://rapier.rs (reference only; no + DOI). +9. ADR-028 — ESP32 capability audit + witness verification. + +--- + +**Next**: 07-coherence-crv-behavioral-episodes.md — turning closed-loop +bouts into audited, queryable episodes. diff --git a/docs/research/connectome-embodied-brain/07-coherence-crv-behavioral-episodes.md b/docs/research/connectome-embodied-brain/07-coherence-crv-behavioral-episodes.md new file mode 100644 index 00000000..b880e851 --- /dev/null +++ b/docs/research/connectome-embodied-brain/07-coherence-crv-behavioral-episodes.md @@ -0,0 +1,281 @@ +--- +Research Document ID: RD-C-07 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-087 +--- + +# RD-C-07: Coherence + CRV Behavioral Episodes (Layer 4) + +## Abstract + +Behaviors are episodic: a grooming bout starts, runs, ends. Layer 4 of +CC-OS encodes each episode through the six-stage `CrvSessionManager` +protocol already shipped in `ruvector-crv`, augmented with a population +coherence gate on neural state. The mapping is not metaphorical: CRV +Stages I–VI were designed for session-based embedding with graph +partitioning at Stage VI, which is exactly the operation a +behavior-episode record demands. This document specifies the +`BehaviorPipeline` facade (analog of `WifiCrvPipeline` in +`crv/mod.rs`), the stage-by-stage encoding of a behavioral bout, the +coherence gate on population state, the episode storage contract, and +the cross-subject convergence primitive that lets one fly's behavior be +compared to another's. + +--- + +## Table of Contents + +1. Motivation — episodes over continuous state +2. CRV → neural stage map +3. Coherence gate on population state +4. `BehaviorPipeline` facade +5. Episode encoding worked example — antennal grooming +6. Stage VI — min-cut for behavior-responsible circuit +7. Persistence and replay +8. Cross-subject convergence +9. Non-goals +10. References + +--- + +## 1. Motivation — Episodes Over Continuous State + +Neural runtime data streams are continuous: voltages at 1 kHz, spikes +every few ms. Behavior is discontinuous: a bout begins, peaks, ends. The +right encoding granularity for analysis and audit is the bout, not the +frame. A bout is a bounded window with associated sensory input, motor +output, and a claim about what behavior it exhibits. `ruvector-crv`'s +session abstraction matches this granularity. + +## 2. CRV → Neural Stage Map + +The six CRV stages shipped in `crv/mod.rs` are: + +| Stage | CRV semantics | Neural/behavioral semantics | +|-------|--------------|-----------------------------| +| I. Gestalt | pattern-class encoding | behavior class (Locomotion / Grooming / Feeding / Freezing / Courtship) | +| II. Sensory | feature extraction | multi-modal body+neural feature vector | +| III. Dimensional | spatial sketch graph | body-pose graph + region sketch | +| IV. Emotional / AOL | coherence / anomaly | `CoherenceGateState` on population state | +| V. Interrogation | differentiable query | "what circuit caused this bout?" | +| VI. Composite | MinCut partitioning | **minimal circuit** for the behavior | + +The `GestaltType` enum (`Movement / Land / Energy / Natural / Manmade / +Water`) from `ruvector-crv` can be repurposed loosely — `Movement` = +locomotion, `Energy` = reactive bout, `Land` = rest — but a +domain-specific `BehaviorClass` enum is cleaner: + +```text +BehaviorClass ::= Locomotion | Grooming { substrate } | Feeding + | Freezing | Courtship | Resting + | Unclassified { confidence } +``` + +The `SensoryModality` enum (Texture / Color / Temperature / Sound / +Luminosity / Dimension) maps to neural-body modalities: + +| `SensoryModality` | Neural/body analog | +|-------------------|--------------------| +| Texture | proprioceptive roughness (joint-angle high-freq variance) | +| Color | region activity spectral centroid | +| Temperature | total population energy | +| Sound | periodic body oscillation (gait frequency) | +| Luminosity | coherence / SNR | +| Dimension | behavioral-state entropy / dimensionality | + +## 3. Coherence Gate on Population State + +The `CoherenceGate` from `viewpoint/coherence.rs` generalises directly. +Reject bouts where the population phase is incoherent (noise, mid-state +transition); PredictOnly for borderline; Recalibrate on detected drift +(circadian, injury, fatigue). + +```text +every 50 ms: + C = mean_r population_phase_coherence(region_r) + gate_state = coherence_gate.update(C) + if gate_state == Reject: + discard current episode, restart window + elif gate_state == PredictOnly: + flag episode as low-confidence + elif gate_state == Recalibrate: + emit CoherenceRecalibrationRequired event +``` + +## 4. `BehaviorPipeline` Facade + +Analog of `WifiCrvPipeline`: + +```text +BehaviorPipeline { + manager: CrvSessionManager, + behavior_classifier: BehaviorClassifier, // Stage I + neural_encoder: NeuralSensoryEncoder, // Stage II + body_sketcher: BodyPoseGraphEncoder, // Stage III + coherence_gate: CoherenceGate, // Stage IV + config: BehaviorConfig, +} + +impl BehaviorPipeline { + pub fn new(config: BehaviorConfig) -> Self { ... } + + pub fn start_bout(&mut self, bout_id: &str, subject_id: &str) + -> Result<(), CrvError>; + + pub fn process_frame( + &mut self, + bout_id: &str, + region_embeds: &[RegionEmbedding], // from NeuralFusionArray (05) + body_state: &BodyState, // from Layer 3 (06) + spike_summary: &SpikeSummary, // from Layer 2 (04) + ) -> Result; + + pub fn finalize_bout(&mut self, bout_id: &str) + -> Result; + + pub fn interrogate(&mut self, bout_id: &str, query: &[f32]) + -> Result; + + pub fn partition_circuit(&mut self, bout_id: &str) + -> Result; + + pub fn cross_subject_convergence( + &self, behavior_class: &str, min_similarity: f32 + ) -> Result; +} +``` + +The parallel with `WifiCrvPipeline` is near-exact: `room-id` → subject-id +or behavior-class; `ApNode` → region sketch element; `CoherenceGateState` +→ population-state gate. + +## 5. Episode Encoding Worked Example — Antennal Grooming + +Given a 500 ms bout identified by sustained foreleg sweep of head: + +**Stage I (Gestalt).** `BehaviorClassifier::classify(body_state_window, +spike_summary_window)` returns `Grooming { substrate: Antenna }` with +confidence 0.88. + +**Stage II (Sensory).** +`NeuralSensoryEncoder::extract(region_embeds, body_state)` returns: + +```text +[ (Texture, "proprioceptive periodic"), + (Color, "mb-dominated activity"), + (Temperature, "moderate pop-rate"), + (Sound, "rhythmic 8-Hz sweep"), + (Luminosity, "high coherence"), + (Dimension, "narrow behavioral manifold") ] +``` + +**Stage III (Dimensional).** `BodyPoseGraphEncoder::sketch(...)` +returns a graph of ~10 joint nodes (head, foreleg segments, antenna) +with position and scale per `SketchElement`. + +**Stage IV (AOL / coherence).** +`CoherenceGate::state() == Accept` with coherence 0.82. + +**Stage V (Interrogation).** Query embedding = "circuit responsible for +grooming" (taken from a library of canonical query vectors) → +differentiable search over accumulated frame embeddings returns top-3 +frame indices with highest activation match. + +**Stage VI (Composite).** `run_stage_vi(bout_id)` runs MinCut over +accumulated embeddings, producing a partition whose neuron members are +the candidate grooming circuit. + +## 6. Stage VI — MinCut for Behavior-Responsible Circuit + +Stage VI's MinCut is the operational mechanism by which CC-OS answers +"what circuit caused this bout?". Two variants: + +| Variant | Cut input | Result | +|---------|-----------|--------| +| On embeddings | per-frame fused embeddings | partition into "behavior" vs "background" frames | +| Lifted to connectome | attention-gated mincut (see 03 §6) over neurons active in behavior frames | minimal neuron/synapse set | + +The second variant is the circuit-discovery product of CC-OS. Its output +is directly consumed by 08-counterfactual-perturbation.md for validation +by ablation. + +## 7. Persistence and Replay + +Every `BehaviorEpisode` emits a manifest: + +```text +episode_manifest.json { + episode_id: "ep-0017", + bout_id: "bout-0001", + subject_id: "fly-a", + behavior_class: "Grooming/Antenna", + t_start_ms: 1520, + t_end_ms: 2020, + coherence_state: "Accept", + coherence_score: 0.82, + stage_i_embed_ref: "...", + stage_ii_embed_ref: "...", + stage_iii_embed_ref:"...", + stage_iv_embed_ref: "...", + stage_v_embed_ref: "...", + stage_vi_circuit: "circuit-grooming-antenna-0017.json", + witness_sha256: "..." +} +``` + +Replay: given the same seed + connectome + body + stimuli, the same +episode is reconstructible byte-for-byte. This is the auditability +property that distinguishes CC-OS from undocumented demo runs. + +## 8. Cross-Subject Convergence + +`CrvSessionManager::find_convergence(room_id, min_similarity)` already +exists for matching sessions in the same "room". Relabel `room_id` to +`behavior_class` (or `(subject_id, behavior_class)` if intra-subject +replication is also wanted). + +```text +convergence = pipeline.cross_subject_convergence( + behavior_class: "Grooming/Antenna", + min_similarity: 0.7, +) +// returns scores for pairs of episodes; high scores = same behavior +// patterned similarly across subjects +``` + +This gives CC-OS a built-in reproducibility primitive: two flies +presented with the same stimulus should produce convergent Stage II +embeddings if the shared circuit is intact; mutation or ablation shows +up as dropped convergence. + +## 9. Non-Goals + +- **Discovery of novel behaviors.** v1 classifies among a fixed behavior + vocabulary. Unsupervised behavior discovery (cf. Berman et al. 2014 on + MotionMapper) is a v2 target. +- **Behavior prediction from connectome alone.** The pipeline classifies + behaviors observed in-loop; predicting future behaviors requires + forward models not part of v1. +- **Human or higher-mammal behaviors.** Out of scope. + +## 10. References + +1. `ruvector-crv` v0.1.1 — `CrvSessionManager`, stages I–VI. +2. `crv/mod.rs` — `WifiCrvPipeline`, pattern source. +3. `viewpoint/coherence.rs` — `CoherenceGate` with Accept / PredictOnly + / Reject / Recalibrate states. +4. Berman, G. J., et al. (2014). *Mapping the stereotyped behaviour of + freely moving fruit flies.* J. R. Soc. Interface. +5. Seeds, A. M., et al. (2014). *A suppression hierarchy among competing + motor programs.* eLife. +6. Hampel, S., et al. (2015). *A neural command circuit for grooming + movement control.* eLife. +7. Card, G. M., Dickinson, M. H. (2008). *Performance trade-offs in the + flight initiation of Drosophila.* J. Exp. Biol. + +--- + +**Next**: 08-counterfactual-perturbation.md — using episode circuits to +do real circuit science. diff --git a/docs/research/connectome-embodied-brain/08-counterfactual-perturbation.md b/docs/research/connectome-embodied-brain/08-counterfactual-perturbation.md new file mode 100644 index 00000000..bfa7b007 --- /dev/null +++ b/docs/research/connectome-embodied-brain/08-counterfactual-perturbation.md @@ -0,0 +1,246 @@ +--- +Research Document ID: RD-C-08 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-087, ADR-088 +--- + +# RD-C-08: Counterfactual Perturbation and Circuit Fragility Protocol + +## Abstract + +A structural min-cut (03) identifies the smallest synaptic bottleneck +between a sensory and motor ensemble; a Stage VI MinCut over behavioral +episodes (07) identifies the circuit members active during a specific +bout. Neither, on its own, proves that the identified circuit is +**causally necessary** for the behavior. Causality demands perturbation: +remove or scale the candidate circuit, re-run the closed loop, and +measure whether the behavior survives. This document specifies the +perturbation primitives (synapse ablation, weight scaling, neuron +silencing, optogenetic-analog activation, transmitter block), the +re-mincut + behavioral-re-evaluation protocol, the fragility score that +ranks candidate circuits, and the auditable witness-log pipeline that +makes every perturbation reproducible. + +--- + +## Table of Contents + +1. Problem framing +2. Perturbation primitives +3. Re-mincut protocol +4. Behavioral fragility score +5. Search strategy +6. Published comparison +7. Auditability +8. Worked example — antennal grooming +9. Limitations +10. Ethical considerations +11. References + +--- + +## 1. Problem Framing + +Correlation between neuron activity and behavior is cheap; causal +attribution is hard. The dissociation problem — neuron $i$ fires during +behavior $B$, but does neuron $i$ cause $B$? — has a long history in +systems neuroscience (cf. Jazayeri & Afraz 2017, *Neuron*, on +perturbation causal inference). The CC-OS answer is a constructive loop: +propose a candidate circuit (from mincut or Stage VI), perturb it, +re-run, measure. This requires fast, deterministic, auditable +perturbation — exactly what the `ConnectomeGraph` aggregate +(02-connectome-graph-substrate.md §10) was designed for. + +## 2. Perturbation Primitives + +All perturbations are expressed as append-only events on the graph +aggregate, so they are reversible by replaying without the event. + +| Primitive | Event | Effect | +|-----------|-------|--------| +| Synapse ablation | `SynapseAblated { pre_id, post_id }` | weight → 0 | +| Weight scaling | `SynapseScaled { pre_id, post_id, factor }` | weight × factor | +| Neuron silencing | `NeuronSilenced { id }` | suppress all outgoing spikes | +| Neuron driven | `NeuronDriven { id, rate_hz }` | external Poisson injection | +| Transmitter block | `TransmitterBlocked { region, nt }` | all edges of that NT in that region set to 0 | + +Silencing and driving have optogenetic-analog semantics: they do not +change connectivity, they override activity. + +## 3. Re-Mincut Protocol + +Given a baseline min-cut $C_0$ with weight $w_0$, a perturbation $P$ +that scales weights, and the resulting cut $C_1$ with weight $w_1$: + +$$ + \Delta_{\mathrm{cut}}(P) = \frac{w_0 - w_1}{w_0} \in [0, 1]. +$$ + +Large $\Delta_{\mathrm{cut}}$ means $P$ weakened the cut substantially. +Perturbations entirely outside the bottleneck produce $\Delta \approx +0$; perturbations inside produce $\Delta$ proportional to the fraction +of the bottleneck removed. + +The re-mincut is incremental: `ruvector-mincut`'s `DynamicMinCut` is +designed for exactly this — the graph state after perturbation differs +from the baseline only on the perturbed edges. + +## 4. Behavioral Fragility Score + +Cut fragility is structural; behavioral fragility is what matters. +Define + +$$ + \mathcal{F}_{\text{beh}}(P) = 1 - \frac{\Pr[\text{behavior} \mid P]}{\Pr[\text{behavior} \mid P_0]}, +$$ + +where $P_0$ is the unperturbed baseline and $\Pr[\text{behavior} \mid +\cdot]$ is the fraction of $N$ bouts producing the target behavior with +coherence gate state `Accept`. $\mathcal{F}_{\text{beh}} = 0$ means the +perturbation did nothing; $\mathcal{F}_{\text{beh}} = 1$ means it +abolished the behavior. + +Combining structural and behavioral fragility: + +$$ + \mathcal{F}(P) = \sqrt{\Delta_{\mathrm{cut}}(P) \cdot \mathcal{F}_{\text{beh}}(P)} +$$ + +— both components must be large for a perturbation to count as +"identifying the bottleneck". Perturbations with high +$\Delta_{\mathrm{cut}}$ but low $\mathcal{F}_{\text{beh}}$ reveal a +bottleneck that is not behaviourally required; perturbations with high +$\mathcal{F}_{\text{beh}}$ but low $\Delta_{\mathrm{cut}}$ reveal that +the behavior depends on something beyond the structural bottleneck +(e.g. timing, plasticity, neuromodulation). + +## 5. Search Strategy + +The search space is exponential in the number of synapses. Three +practical strategies: + +### 5.1 Greedy shrinking + +Start with the full Stage VI circuit (07 §6). Remove one neuron at a +time; keep the removal if behavior is preserved; otherwise add it back. +This identifies a minimal sufficient circuit under a greedy heuristic. +O(n) re-runs where n is the circuit size. + +### 5.2 Paired-hypothesis test + +For each candidate neuron $i$, run $N$ bouts with $i$ silenced and $N$ +baseline bouts. Compute behavior success rate difference. Bonferroni- +corrected across candidates. O(n) re-runs with statistical rigour. + +### 5.3 Bayesian optimisation over perturbation combinations + +Model $\mathcal{F}(P)$ as a black-box function; use BO to select +informative perturbations. Useful when combinations of small +perturbations are the interesting regime. O(log n) re-runs in the +ideal case; practically 30–100. + +## 6. Published Comparison + +Fly grooming circuit perturbation studies provide the ground truth +against which CC-OS predictions are evaluated: + +| Study | Perturbation | Behavior effect | CC-OS prediction target | +|-------|--------------|-----------------|-------------------------| +| Hampel et al. 2015 | silence GNG descending interneurons | antennal grooming abolished | high $\mathcal{F}_{\text{beh}}$ | +| Seeds et al. 2014 | optogenetic activation of premotor neurons | elicits bout | `NeuronDriven` produces behavior | +| Ramdya et al. 2017 | leg sensory lesion | gait adaptation | partial $\mathcal{F}_{\text{beh}}$ | +| Namiki et al. 2018 | DN class ablation | specific motor deficits | class-specific $\mathcal{F}_{\text{beh}}$ | + +CC-OS v1 should reproduce the Hampel 2015 and Seeds 2014 results in +simulation. Replication is a falsifiable prediction, not a rhetorical +claim. + +## 7. Auditability + +Every perturbation run emits a witness bundle: + +```text +perturbation_manifest.json { + run_id: "pert-0042", + baseline_manifest: "run-manifest-base.json", + perturbation_events: ["SynapseAblated ...", "NeuronSilenced ..."], + n_bouts: 50, + behavior_success_rate: 0.12, + baseline_success_rate: 0.91, + delta_cut: 0.63, + f_beh: 0.87, + f: 0.74, + bouts_sha256: "...", + circuit_prediction: "circuit-grooming-antenna-0017.json", + validation_status: "consistent" | "inconsistent" +} +``` + +Any run can be replayed from the manifest; any downstream claim that +"circuit X causes behavior Y" has the manifest as its receipt. + +## 8. Worked Example — Antennal Grooming + +1. Identify candidate circuit from 03 §8 min-cut + 07 §6 Stage VI: ~40 + neurons spanning antennal bristle sensory → GNG descending → foreleg + motor. +2. Run baseline: 50 bouts, stimulus = 50 ms mechanosensory activation, + behavior success rate 0.91. +3. Greedy shrink: drop each neuron in turn; end with ~15-neuron minimal + set where dropping any further neuron drops behavior below 0.5. +4. Statistical confirmation: paired-hypothesis test per neuron in the + minimal set; Bonferroni-corrected p < 0.001 for the GNG command + neurons matching Hampel 2015. +5. Compare CC-OS prediction to published circuit: Jaccard similarity + should exceed 0.7 per the acceptance test (10-acceptance-test-grooming.md §6). +6. Write `pert-0042` manifest to witness bundle. + +## 9. Limitations + +- **Recurrence confounds.** Highly recurrent circuits have multiple + equivalent minimal sets. Greedy shrinking finds one; BO or exhaustive + search may find others. +- **Timing not captured.** The fragility score is averaged over bouts; + perturbations that alter timing without abolishing behavior (e.g., + slower grooming onset) require a richer behavioral metric. +- **Plasticity.** Acute ablation in a real fly triggers homeostatic + compensation over hours. CC-OS v1 does not model compensation. +- **Noise floor.** Small perturbations in a noisy system cannot be + distinguished from baseline variability below a minimum effect size. + +## 10. Ethical Considerations + +Fly-scale counterfactual perturbation is a computational experiment on +a peer-reviewed graph; no animals are harmed by CC-OS simulations. +Extending to mouse or vertebrate connectomes raises new concerns — +discussed in 11-risks-positioning-roadmap.md §4. The same fragility +pipeline could be used to design adversarial perturbations of biological +neural networks; the same witness logging that supports good science +also makes abuse auditable. + +## 11. References + +1. Jazayeri, M., Afraz, A. (2017). *Navigating the neural space in + search of the neural code.* Neuron. +2. Hampel, S., Franconville, R., Simpson, J. H., Seeds, A. M. (2015). + *A neural command circuit for grooming movement control.* eLife. +3. Seeds, A. M., Ravbar, P., Chung, P., et al. (2014). *A suppression + hierarchy among competing motor programs drives sequential grooming + in Drosophila.* eLife. +4. Ramdya, P., Thandiackal, R., Cherney, R., et al. (2017). *Climbing + favours the tripod gait over alternative faster insect gaits.* Nat + Commun. +5. Namiki, S., Dickinson, M. H., Wong, A. M., Korff, W., Card, G. M. + (2018). *The functional organization of descending sensory-motor + pathways in Drosophila.* eLife. +6. ADR-028 — ESP32 capability audit + witness verification. +7. `ruvector-mincut` v2.0.4 — `DynamicMinCut` incremental edge updates. +8. Ali, F., Laudet, V., Hampel, S. (2023). *Dissection of grooming + circuit components.* Curr Biol (methods review). + +--- + +**Next**: 09-four-layer-architecture.md — the full system spec that +integrates Layers 1–4. diff --git a/docs/research/connectome-embodied-brain/09-four-layer-architecture.md b/docs/research/connectome-embodied-brain/09-four-layer-architecture.md new file mode 100644 index 00000000..d33d8f41 --- /dev/null +++ b/docs/research/connectome-embodied-brain/09-four-layer-architecture.md @@ -0,0 +1,281 @@ +--- +Research Document ID: RD-C-09 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-084, ADR-085, ADR-086, ADR-087, ADR-088 +--- + +# RD-C-09: Four-Layer CC-OS Architecture + +## Abstract + +This document integrates the substrate (02), circuit analysis (03), +neural dynamics runtime (04), cross-region attention fusion (05), +embodied simulator (06), behavioral-episode encoding (07), and +counterfactual perturbation (08) into a single four-layer architecture. +We specify the proposed new workspace crates, DDD bounded contexts, +domain events, data-flow diagram, control-plane CLI subcommands, +end-to-end latency and memory budgets, concurrency model, observability +conventions, and the integration points with existing RuView code. The +architecture is designed to slot into the existing `wifi-densepose` Rust +workspace without disturbing the publishing order or the +cargo-test-workspace convention. + +--- + +## Table of Contents + +1. Layer stack overview +2. Proposed new workspace crates +3. DDD bounded contexts +4. Data-flow diagram +5. Control plane — CLI subcommands +6. Latency budget +7. Memory budget +8. Concurrency model +9. Observability and witness logs +10. Integration with existing RuView modules +11. Build, test, and benchmark commands +12. Non-goals +13. References + +--- + +## 1. Layer Stack Overview + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ Layer 4: Analysis & Adaptation │ +│ - ruvector-mincut fragility (03, 08) │ +│ - NeuralFusionArray cross-region attention (05) │ +│ - BehaviorPipeline CRV episode encoding (07) │ +│ - CoherenceGate population state (05, 07) │ +│ - Counterfactual perturbation runner (08) │ +│ Crate: wifi-densepose-ruvector (extended) │ +├──────────────────────────────────────────────────────────────────────┤ +│ Layer 3: Embodied Simulator (Closed Loop) │ +│ - Rapier physics, fly body schema, sensor/actuator adapters (06) │ +│ - Optional NeuroMechFly bridge │ +│ Crate: wifi-densepose-embody (proposed) │ +├──────────────────────────────────────────────────────────────────────┤ +│ Layer 2: Neural Dynamics Runtime │ +│ - Event-driven LIF kernel (04) │ +│ - ruvector-solver rate-code + perturbation (04 §5) │ +│ - ruvector-temporal-tensor voltage/spike storage (02 §7, 04 §6) │ +│ Crate: wifi-densepose-neuro (proposed) │ +├──────────────────────────────────────────────────────────────────────┤ +│ Layer 1: Connectome Graph Substrate │ +│ - Neuron / Synapse / Region schema (02) │ +│ - ruvector-mincut adjacency + triplets (02 §5) │ +│ - Neuron embeddings (02 §6) │ +│ Crate: wifi-densepose-connectome (proposed) │ +└──────────────────────────────────────────────────────────────────────┘ +``` + +## 2. Proposed New Workspace Crates + +| Crate | Slot | Depends on | Feature flags | +|-------|------|-----------|---------------| +| `wifi-densepose-connectome` | Layer 1 | `core`, `db`, `ruvector` (for mincut + temporal-tensor) | `flywire`, `micons`, `larva` | +| `wifi-densepose-neuro` | Layer 2 | `core`, `connectome`, `ruvector` | `rate-code`, `gpu` (deferred) | +| `wifi-densepose-embody` | Layer 3 | `core`, `neuro` | `nmf-bridge`, `vision` | + +Publishing order (extends the list in `CLAUDE.md`): + +``` +... → wifi-densepose-ruvector + → wifi-densepose-connectome (new) + → wifi-densepose-neuro (new) + → wifi-densepose-embody (new) + → wifi-densepose-train + → wifi-densepose-mat + ... +``` + +Layer 4 capabilities extend the existing `wifi-densepose-ruvector` crate +rather than spawning another crate: the aggregates +(`NeuralFusionArray`, `BehaviorPipeline`, perturbation runner) live +alongside `MultistaticArray` and `WifiCrvPipeline`. + +## 3. DDD Bounded Contexts + +| Context | Aggregate root | Invariants | Domain events | +|---------|----------------|------------|---------------| +| ConnectomeGraph | `ConnectomeGraph` | Synapses reference extant neurons; no duplicates; NT matches presynaptic neuron | `ConnectomeLoaded`, `SynapseAblated`, `SynapseRestored`, `EmbeddingRecomputed` | +| NeuralRuntime | `SimulationRun` | Seeded RNG; ordered event tiebreaks; append-only voltage/spike logs | `SpikeObserved`, `RunStarted`, `RunCompleted`, `RunAborted` | +| Body | `Body` + `BodyState` | Joint angles within physical limits; contact forces non-negative | `ContactOpened`, `ContactClosed`, `ActuatorSaturated`, `PhysicsDiverged` | +| RegionFusion | `NeuralFusionArray` | Embed dim consistent; coherence gate state monotonic within a window | `FusionEmitted`, `CoherenceGateTransitioned` | +| BehaviorEpisode | `BehaviorPipeline` (wraps `CrvSessionManager`) | Stage order (I→VI); bout id unique; coherence gate consistent | `BoutStarted`, `StageCompleted`, `BoutFinalized`, `CircuitIdentified` | +| Perturbation | `PerturbationRunner` | Every perturbation has baseline manifest; score computed from ≥N bouts | `PerturbationApplied`, `PerturbationReverted`, `FragilityScored` | + +## 4. Data-Flow Diagram + +``` + stimulus / ctx + │ + ▼ +[ SensorEncoder ] ─ spike injections ─▶ [ SpikeQueue ] + (Layer 3) │ + ▼ + [ LIF kernel ] + (Layer 2) + │ + ┌────────────────┼───────────────┐ + ▼ ▼ ▼ + [ VoltageBuffer ] [ SpikeLog ] [ regionAggregator ] + (TemporalTensor) (50 ms window) + │ │ + │ ▼ + │ [ NeuralFusionArray ] + │ (Layer 4 / SDPA) + │ │ + │ ▼ + │ [ BehaviorPipeline ] + │ (CRV stages I–VI) + │ │ + │ ▼ + │ [ StageVI MinCut / fragility ] + │ │ + ▼ ▼ + [ MotorDecoder ] ◀─── (next-step command) ─── analysis products + (Layer 3) │ + │ ▼ + ▼ witness bundle + [ Rapier physics ] (ADR-028 lineage) + │ + └──── body state ─▶ SensorEncoder ... (loop) +``` + +## 5. Control Plane — CLI Subcommands + +Proposed additions to the `wifi-densepose` CLI binary: + +| Subcommand | Purpose | +|------------|---------| +| `brain load ` | Load a connectome into the store; emits `ConnectomeLoaded` with SHA-256 | +| `brain simulate --duration --subgraph [--seed N]` | Run closed-loop simulation, produce witness bundle | +| `brain ablate ` | Apply perturbation events; idempotent given the manifest | +| `brain fragility --baseline --perturbation ` | Compute $\mathcal{F}(P)$ from 08 | +| `brain replay ` | Deterministic replay; SHA-256 verification | +| `brain inspect ` | Pretty-print witness bundle, cuts, fragility | + +## 6. Latency Budget + +End-to-end for 100 Hz closed-loop control with 50k-neuron subgraph: + +| Stage | Target | Worst-case | +|-------|--------|------------| +| Sensor read + encoding | 0.5 ms | 1 ms | +| Spike queue insert | 0.1 ms | 0.3 ms | +| LIF kernel (10 ms window) | 5 ms | 8 ms | +| Fusion (50 ms cadence, amortised) | 0.5 ms | 1.5 ms | +| CRV episode update (infrequent) | 1 ms | 3 ms | +| Motor decoding | 0.2 ms | 0.5 ms | +| Physics step (1 kHz) | 1 ms | 2 ms | +| **End-to-end** | **< 10 ms** | **< 16 ms** | + +1 kHz aspirational target requires reduced subgraph (10k–15k), batched +fusion (every 10 ms), and no-alloc inner loops throughout. + +## 7. Memory Budget + +| Scale | Graph | Voltage (60s, tiered) | Spike log | Embeddings | Total | +|-------|-------|------------------------|-----------|------------|-------| +| 10k | 10 MB | 400 MB | 50 MB | 5 MB | ~0.5 GB | +| 50k | 48 MB | 3.0 GB | 240 MB | 26 MB | ~4 GB | +| 139k | 1.3 GB (synapses) | 8 GB | 700 MB | 71 MB | ~12 GB | + +Laptop-grade (32 GB) handles 50k comfortably. Full FlyWire at 139k fits +in 32 GB but leaves little headroom; 64 GB recommended. + +## 8. Concurrency Model + +| Layer | Concurrency | Framework | +|-------|-------------|-----------| +| 1 (graph) | Immutable after load; readers lock-free | `arc-swap` or `parking_lot::RwLock` | +| 2 inner LIF | Single-threaded spike queue, rayon fan-out per time slot | `rayon` | +| 2 I/O | Async | `tokio` | +| 3 physics | Single-threaded tight loop | Rapier native | +| 3 ingress / egress | Async | `tokio` | +| 4 analysis | Async, read-only access | `tokio` | + +Critical path (LIF + physics) is single-threaded per simulation +instance for determinism. Multiple instances (e.g. for +parallel-perturbation sweeps) run as independent processes. + +## 9. Observability and Witness Logs + +Every run, bout, and perturbation produces a manifest compatible with +the ADR-028 witness-bundle convention. A run's witness bundle includes: + +- `connectome_sha256` (Layer 1) +- `run_manifest.json` (Layer 2) +- Voltage + spike compressed segments (Layer 2) +- `bout_manifest.json` per bout (Layer 3) +- `episode_manifest.json` per episode (Layer 4) +- `perturbation_manifest.json` per perturbation (Layer 4) +- `VERIFY.sh` self-verification script (ADR-028 style) + +Bundle tarball: `dist/witness-bundle-CCOS--.tar.gz`. + +## 10. Integration with Existing RuView Modules + +| Existing module | Reused how | +|-----------------|-----------| +| `viewpoint/fusion.rs` `MultistaticArray` | Shape template for `NeuralFusionArray` | +| `viewpoint/coherence.rs` `CoherenceGate` | Reused verbatim with new coherence definition | +| `viewpoint/geometry.rs` `GeometricDiversityIndex` | Shape template for FDI | +| `crv/mod.rs` `WifiCrvPipeline` | Shape template for `BehaviorPipeline` | +| `signal/subcarrier.rs` virtual source/sink pattern | Reused for connectome min-cut | +| `signal/spectrogram.rs` attention-gated mincut | Reused for behavior-conditioned cuts | +| `mat/breathing.rs` `CompressedBreathingBuffer` | Pattern for `VoltageBuffer` | +| `mat/triangulation.rs` Neumann solver usage | Pattern for rate-code and perturbation solves | +| `scripts/generate-witness-bundle.sh` | Extended with CC-OS artifacts | +| ADR-028 witness convention | Applied verbatim | + +## 11. Build, Test, and Benchmark Commands + +```bash +# Workspace test (add new crates to the existing convention) +cd rust-port/wifi-densepose-rs +cargo test --workspace --no-default-features + +# Targeted tests +cargo test -p wifi-densepose-connectome --no-default-features +cargo test -p wifi-densepose-neuro --no-default-features +cargo test -p wifi-densepose-embody --no-default-features + +# Benchmarks (Criterion) +cargo bench -p wifi-densepose-neuro --bench lif_kernel_throughput +cargo bench -p wifi-densepose-neuro --bench voltage_buffer_compression + +# End-to-end acceptance +cargo test -p wifi-densepose-embody --test grooming_acceptance + +# Witness bundle generation (extended) +bash scripts/generate-witness-bundle.sh --ccos +``` + +## 12. Non-Goals + +- **Real-time human-scale simulation.** +- **Cloud-distributed multi-node simulation in v1.** Single workstation. +- **GPU-accelerated LIF in v1.** Deferred to v2. +- **Live web visualisation in v1.** CLI + witness bundle only. +- **Replace the RF sensing pipeline.** CC-OS is additive. + +## 13. References + +1. Eric Evans, *Domain-Driven Design* (2003). +2. ADR-017 — RuVector signal + MAT integration (DDD pattern). +3. ADR-028 — ESP32 capability audit + witness verification. +4. RuVector v2.0.4 documentation. +5. `CLAUDE.md` — project configuration, crate publishing order. +6. Dorkenwald, S., et al. (2024). *Neuronal wiring diagram of an adult + brain.* Nature. + +--- + +**Next**: 10-acceptance-test-grooming.md — the concrete pass/fail test +that validates this architecture. diff --git a/docs/research/connectome-embodied-brain/10-acceptance-test-grooming.md b/docs/research/connectome-embodied-brain/10-acceptance-test-grooming.md new file mode 100644 index 00000000..ffbbd752 --- /dev/null +++ b/docs/research/connectome-embodied-brain/10-acceptance-test-grooming.md @@ -0,0 +1,279 @@ +--- +Research Document ID: RD-C-10 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-084 through ADR-088 +--- + +# RD-C-10: Acceptance Test — Antennal Grooming + +## Abstract + +The user-specified acceptance criterion for CC-OS is: +*"A 10,000 to 50,000 neuron subgraph runs in closed loop with a virtual +body, produces one reproducible behavior, and RuVector correctly +identifies the minimal circuit boundary whose perturbation breaks that +behavior."* This document turns that criterion into a concrete, +executable test. We select antennal grooming as the target behavior +because it has the most mature circuit-level characterisation in the fly +literature (Hampel et al. 2015; Seeds et al. 2014). We specify the +subgraph-extraction procedure from FlyWire, the stimulus protocol, the +four pass/fail criteria (behavior-present, reproducibility, +minimal-cut match, fragility significance), the Rust test harness, the +witness-bundle contents, the CI budget, and the publishable artifacts. + +--- + +## Table of Contents + +1. Test objective +2. Behavior choice +3. Subgraph selection +4. Stimulus design +5. Success criteria +6. Metrics and thresholds +7. Test harness +8. Witness bundle +9. CI constraints +10. Publishable artifacts +11. Failure analysis and remediation +12. References + +--- + +## 1. Test Objective + +Verbatim from the compendium thesis: + +> A 10,000 to 50,000 neuron subgraph runs in closed loop with a virtual +> body, produces one reproducible behavior, and RuVector correctly +> identifies the minimal circuit boundary whose perturbation breaks that +> behavior. + +Four independent claims, each individually falsifiable: + +1. **Closed loop runs at scale.** A subgraph of 10k–50k neurons runs + with the embodied simulator. +2. **Behavior is produced.** A canonical stimulus reliably elicits + antennal grooming. +3. **Behavior is reproducible.** Same seed + same config → byte-equal + voltage traces. +4. **Minimal cut is correct.** `ruvector-mincut` identifies a circuit + whose perturbation abolishes the behavior, with the cut matching + published circuit dissection within a specified Jaccard threshold. + +## 2. Behavior Choice + +| Behavior | Published circuit | Body requirement | Recommended? | +|----------|-------------------|------------------|--------------| +| Antennal grooming | Hampel 2015, Seeds 2014 | moderate (foreleg + antenna) | **Yes (v1 target)** | +| Walking | Cruse Walknet lineage | high (6 legs coordinated) | v2 | +| Feeding | Itakura et al. 2018 | high (proboscis + foregut) | v2 | +| Courtship | Pan & Baker 2014 | very high (multi-modal) | v3 | +| Freezing | Zacarias et al. 2018 | low | alternate v1 | + +Antennal grooming wins on three counts: well-characterised command +circuit, modest biomechanical requirements, and short-duration bouts +(~500 ms) that fit CI time budgets. + +## 3. Subgraph Selection + +Starting from FlyWire (Dorkenwald et al. 2024), extract a subgraph +that contains: + +1. Antennal bristle mechanosensory neurons (~1,300, FlyWire `super_class + == "Sensory"` + `side == "Left/Right"` + region includes antennal + mechanosensory and motor (AMMC) and gnathal ganglion (GNG)). +2. GNG descending interneurons (~150, Hampel 2015 reference; FlyWire + `super_class == "Descending"` intersected with GNG region). +3. Prothoracic leg motor neurons (~50, FlyWire `super_class == "Motor"` + + `region == "VNC prothoracic"`). +4. Three-hop neighborhood of the above (to capture modulatory inputs). + +Typical yield: 15k–30k neurons, 300k–1M synapses. Comfortably inside +the 10k–50k band specified by the test. + +Extraction script (non-normative Python over FlyWire API): + +```python +# pseudo-code — real implementation lives in wifi-densepose-connectome +core = flywire.query(super_class=["Sensory","Descending","Motor"], + region=["AMMC","GNG","VNC_proT"]) +expanded = flywire.k_hop(core, k=3, min_weight=5) +graph = flywire.induced_subgraph(expanded) +graph.export("flywire_grooming_subgraph.bin") +``` + +## 4. Stimulus Design + +```text +for each trial in 0..N: + at t=0: activate antennal bristle pool with rate = 200 Hz for 50 ms + observe from t=-100 ms to t=1000 ms + detect antennal sweep: foreleg-tibia contacts antenna with force > threshold + record: + - success: boolean (did sweep occur within window?) + - latency: time to first contact (ms) + - sweeps: integer count + - spikes: full SpikeLog + - voltages: full VoltageBuffer +``` + +Trial count $N = 50$ per configuration. Two stimulus sides (left/right +antenna). Baseline condition = unperturbed graph. + +## 5. Success Criteria + +| # | Claim | Criterion | Threshold | +|---|-------|-----------|-----------| +| C1 | Behavior present | success rate in baseline trials | ≥ 0.80 | +| C2 | Reproducibility | SHA-256 of voltage traces equal across two runs with same seed | 100% match (exact) | +| C3 | Minimal-cut match | Jaccard similarity between `ruvector-mincut` predicted circuit (03 §8) and greedy-shrunk minimal sufficient circuit (08 §5) | ≥ 0.7 | +| C4 | Fragility significance | behavior success rate drop from baseline when predicted cut is ablated, relative to same-size random ablation | ablated ≤ 0.4; random ≥ 0.7; p < 0.01 (Fisher's exact) | + +All four must pass for the acceptance test to pass. + +## 6. Metrics and Thresholds + +| Metric | Definition | Pass threshold | +|--------|-----------|---------------| +| $P_{\mathrm{base}}$ | Fraction of baseline trials with antennal sweep | ≥ 0.80 | +| $P_{\mathrm{cut}}$ | Fraction of trials with sweep after ablating predicted cut | ≤ 0.40 | +| $P_{\mathrm{rand}}$ | Fraction of trials with sweep after ablating random edges of same size | ≥ 0.70 | +| $J$ | Jaccard( predicted-cut-neurons, empirical-minimal-circuit ) | ≥ 0.7 | +| $\Delta t_{\mathrm{latency}}$ | Mean latency change ablated vs baseline | significant? (Welch's t, p<0.05) | +| $SHA$ | Run output hash | reproducible under same seed | +| $t_{\mathrm{wall}}$ | Wall-clock per trial | ≤ 12 s on 16-core x86 | + +## 7. Test Harness + +`rust-port/wifi-densepose-rs/crates/wifi-densepose-embody/tests/grooming_acceptance.rs`: + +```rust +// non-normative sketch +#[test] +fn grooming_acceptance() { + let cfg = AcceptanceConfig::default(); + let graph = ConnectomeGraph::load(&cfg.connectome_path).unwrap(); + + // Baseline + let baseline = run_trials(&cfg, &graph, Perturbation::None); + assert!(baseline.success_rate() >= 0.80, "C1 failed"); + + // Reproducibility + let replay = run_trials(&cfg, &graph, Perturbation::None); + assert_eq!(baseline.sha256(), replay.sha256(), "C2 failed"); + + // Predicted cut from ruvector-mincut + let cut = predict_cut(&graph, &baseline); + + // Empirical minimal circuit via greedy shrink + let empirical = greedy_shrink(&cfg, &graph, &baseline); + + // Jaccard match + let j = jaccard(&cut.neurons, &empirical.neurons); + assert!(j >= 0.7, "C3 failed: J = {}", j); + + // Fragility significance + let ablated = run_trials(&cfg, &graph, Perturbation::Ablate(&cut)); + let random = run_trials(&cfg, &graph, Perturbation::AblateRandom(cut.size())); + assert!(ablated.success_rate() <= 0.40, "C4 failed (ablated)"); + assert!(random.success_rate() >= 0.70, "C4 failed (random)"); + assert!(fishers_exact(&ablated, &random) < 0.01, "C4 failed (p-value)"); + + write_witness_bundle(&baseline, &replay, &ablated, &random, + &cut, &empirical, "dist/witness-bundle-CCOS-grooming.tar.gz"); +} +``` + +Python cross-check (`v1/data/proof/verify_ccos.py` following the ADR-011 +proof pattern) hashes the baseline voltage trace and asserts a published +expected SHA-256. + +## 8. Witness Bundle + +Bundle name: `dist/witness-bundle-CCOS-grooming-.tar.gz` + +Contents: + +| Path | Description | +|------|-------------| +| `manifests/baseline_run.json` | Layer-2 run manifest | +| `manifests/replay_run.json` | Reproducibility replay manifest | +| `manifests/ablation_run.json` | Perturbation manifest (predicted cut) | +| `manifests/random_run.json` | Perturbation manifest (random) | +| `circuits/predicted_cut.json` | `ruvector-mincut` output | +| `circuits/empirical_minimal.json` | Greedy-shrink output | +| `traces/voltage_*.ttseg` | Compressed voltage traces | +| `traces/spikes_*.splog` | Spike logs | +| `results/success_rates.csv` | Per-trial outcomes | +| `results/jaccard.json` | J computation | +| `results/fisher_exact.json` | p-value computation | +| `VERIFY.sh` | Self-verification script (ADR-028 pattern) | +| `EXPECTED_SHA256.txt` | Published reference hashes | +| `README.md` | How to reproduce | + +## 9. CI Constraints + +- **No GPU required.** Pure CPU test. +- **Wall-clock budget**: ≤ 10 minutes on 16-core x86_64, 32 GB RAM. +- **Determinism**: same seed must reproduce every manifest SHA-256 + across CI runners. +- **Network**: may require one-time FlyWire subgraph download; cached + after first run. +- **Integration**: extends `scripts/generate-witness-bundle.sh` + (currently ADR-028 focused) with a `--ccos` flag. + +With 50 trials × 10 conditions × ~0.5 s per trial at reduced subgraph, +total simulation time is ≲ 5 minutes. Budget holds. + +## 10. Publishable Artifacts + +Figures that should be produced automatically from a passing run: + +1. **Fragility curve**: $P_{\mathrm{success}}$ vs cut weight removed (0 + to 100%); expect sigmoid. +2. **Minimal-cut visualisation**: 3D scatter of neurons colored by + membership in the Jaccard intersection. +3. **Latency histogram**: sweep latency baseline vs perturbed. +4. **Coherence gate trace**: population coherence across a typical + bout. +5. **Jaccard vs number of neurons ablated**: shows CC-OS prediction + converging to empirical as ablation grows. + +## 11. Failure Analysis and Remediation + +| Failing criterion | Likely cause | Remediation | +|-------------------|--------------|-------------| +| C1 low success rate | Subgraph missing key modulatory inputs; LIF parameters off | Expand k-hop to 4; tune Izhikevich parameters from published values | +| C2 hash mismatch | Non-determinism in Rayon fan-out or RNG | Audit for `par_iter` without sorted reduction; enforce seed propagation | +| C3 low Jaccard | Edge weights not reflecting functional flow | Switch to activity-weighted edges (02 §5, 03 §3) | +| C4 random ablation too effective | Subgraph too small; too many critical edges | Expand subgraph; verify control circuits are present | +| Wall-clock overrun | LIF kernel under-optimised | Profile, add SIMD, drop non-contributing neurons before sim | + +## 12. References + +1. Dorkenwald, S., et al. (2024). *Neuronal wiring diagram of an adult + brain.* Nature (FlyWire). +2. Hampel, S., et al. (2015). *A neural command circuit for grooming + movement control.* eLife. +3. Seeds, A. M., et al. (2014). *A suppression hierarchy among + competing motor programs drives sequential grooming in Drosophila.* + eLife. +4. Zacarias, R., Namiki, S., Card, G. M., Vasconcelos, M. L., Moita, + M. A. (2018). *Speed-dependent descending control of freezing + behaviour in Drosophila.* Nat Commun. +5. Pan, Y., Baker, B. S. (2014). *Genetic identification and separation + of innate and experience-dependent courtship behaviours in + Drosophila.* Cell. +6. Itakura, Y., Kohsaka, H., Ohyama, T., et al. (2018). *Identification + of inhibitory premotor interneurons activated at a late phase in a + motor cycle during larval locomotion.* PLOS ONE. +7. ADR-011 — Python proof of reality (hash verification pattern). +8. ADR-028 — Witness bundle convention. + +--- + +**Next**: 11-risks-positioning-roadmap.md — what not to claim, and how +to land the work in the ADR corpus. diff --git a/docs/research/connectome-embodied-brain/11-risks-positioning-roadmap.md b/docs/research/connectome-embodied-brain/11-risks-positioning-roadmap.md new file mode 100644 index 00000000..f046e835 --- /dev/null +++ b/docs/research/connectome-embodied-brain/11-risks-positioning-roadmap.md @@ -0,0 +1,344 @@ +--- +Research Document ID: RD-C-11 +Date: 2026-04-21 +Status: Draft +Authors: RuView Research Team +Related ADRs: proposed ADR-084 through ADR-088 +--- + +# RD-C-11: Risks, Positioning, and Roadmap + +## Abstract + +This is the governance document for the compendium. It specifies what +CC-OS is allowed to claim in public artifacts, what it must never +claim, the dual-use and ethics considerations implied by running the +same counterfactual-perturbation pipeline on any connectome, +comparisons against prior art (Eon, OpenWorm, Blue Brain, Brian2 + +NeuroMechFly, BrainScaleS), the decision rubric from the originating +proposal, full drafts of five proposed ADRs (ADR-084 through ADR-088), +and a five-phase implementation roadmap with phase gates, success +KPIs, and out-of-scope items for v1. It closes with a publication plan +that prioritises honest scope-limited claims over headline-chasing. + +--- + +## Table of Contents + +1. Scientific positioning — CC-OS +2. Hype and ethics risk matrix +3. Scope limits +4. Security / dual-use considerations +5. Comparison with prior art +6. Decision rubric +7. Proposed ADRs (ADR-084 through ADR-088) +8. Five-phase implementation roadmap +9. Success KPIs per phase +10. Out-of-scope items for v1 +11. Publication and talk plan +12. Appendix A: 200-word short-form summary +13. References + +--- + +## 1. Scientific Positioning — CC-OS + +**CC-OS is a coherence-aware connectome operating system.** It loads a +published connectome, simulates its neural dynamics at millisecond +resolution, closes the sensorimotor loop through an embodied simulator, +and provides auditable counterfactual analysis of the resulting +behavior. It is a platform for circuit science, not a model of mind. + +What CC-OS **is**: + +- a graph-native connectome runtime; +- a Rust event-driven LIF engine at 10k–139k neuron scale; +- an embodied sensorimotor loop closed in real time; +- a structural + behavioral fragility pipeline; +- an auditable, witness-logged, reproducible platform. + +What CC-OS **is not**: + +- not a mind, not a subject, not a locus of experience; +- not a whole-brain emulation in the Sandberg–Bostrom sense; +- not a replacement for NEURON, Brian2, Nengo, or Blue Brain; +- not a claim about consciousness, identity, or memory continuity. + +## 2. Hype and Ethics Risk Matrix + +| Claim | Risk | Mitigation | +|-------|------|------------| +| "Mind upload" / "digital consciousness" | VERY HIGH | Never use in any RuView artifact. Formal prohibition. | +| "Simulated fly brain" (unqualified) | HIGH | Use only with "structural + dynamical model of a subgraph of the adult Drosophila connectome, not a whole organism" qualifier. | +| "Fly running on a laptop" | MEDIUM | Acceptable if accompanied by scope caveat and acceptance-test reference. | +| "Coherence-aware connectome OS" | LOW | Preferred framing. | +| "Auditable circuit discovery" | LOW | Core value proposition; encouraged. | +| "Counterfactual circuit fragility scoring" | LOW | Novel, defensible, auditable. | +| "Digital fly companion / pet" | HIGH | Avoid anthropomorphic framing; simulator, not companion. | +| "Road to mammalian minds" | VERY HIGH | Out of scope; do not gesture at. | + +Public posts, READMEs, and talk abstracts must pass a checklist that +rejects the VERY HIGH and HIGH items above by default. + +## 3. Scope Limits + +- **v1 organism**: adult *Drosophila melanogaster* only. +- **v2 candidates**: larval *Drosophila*, larval zebrafish (when + proofread connectomes ship). +- **Out of scope**: mouse, rat, primate, human connectomes — pending + external ethics review and a dedicated ADR. +- **Out of scope**: clinical / medical / patient-facing applications. +- **Out of scope**: consciousness or phenomenal-experience claims. +- **Out of scope**: real-time human-scale simulation. + +## 4. Security / Dual-Use Considerations + +The same pipeline that discovers behaviour-responsible circuits can be +used to design perturbations that *abolish* behavior. At fly scale this +is a research tool; at any biological-organism scale it is an +experimental design, not an action. The dual-use risk is structurally +mitigated by the witness-log property: every perturbation has a +manifest with an SHA-256 fingerprint, making post-hoc audit feasible +regardless of author intent. Guidelines: + +- CC-OS runs shall emit witness bundles for any perturbation sweep. +- CC-OS shall not accept non-published connectomes (no BYO-connectome + in v1 to prevent unaudited organism targeting). +- Perturbation recipes shall be version-pinned and hashed so that a + published paper's experimental design is reproducible. + +## 5. Comparison with Prior Art + +| System | Scale | Lang | Graph-native | Coherence-gated | Counterfactual | Witness-audit | Open-source | +|--------|-------|------|--------------|-----------------|----------------|---------------|-------------| +| OpenWorm | 302 (C. elegans) | C++ / Python | Partial | No | No | No | Yes | +| NEURON | Arbitrary | C / Python | No (biophysics) | No | Manual | No | Yes | +| Brian2 | Arbitrary | Python | Partial | No | Manual | No | Yes | +| Nengo | Arbitrary | Python | No (NEF) | No | Manual | No | Yes | +| NeuroMechFly + Kakaria-LIF | ~10k | Python | Partial | No | No | No | Partial | +| Blue Brain Nexus | 10^6+ cortex | C++ / Python | Partial | No | No | Partial | No | +| BrainScaleS | 10^5 (hardware) | Hardware | No | No | Yes (hardware) | No | No | +| "Eon"-style stack | ~100k | Python | Partial | No | No | No | No | +| **CC-OS (this compendium)** | 10k–139k | **Rust** | **Yes** | **Yes** | **Yes** | **Yes (ADR-028)** | **Yes** | + +The differentiation is not scale or biophysical fidelity; it is the +combination of graph-native storage + coherence gating + counterfactual +fragility + witness audit + Rust. + +## 6. Decision Rubric + +From the originating proposal (user quote, verbatim structure): + +| Dimension | Verdict | +|-----------|---------| +| Feasibility today | HIGH | +| Novelty with RuVector | HIGH | +| Scientific validity if carefully positioned | MEDIUM–HIGH | +| Risk of hype if framed as "mind upload" | VERY HIGH | +| Best positioning | Embodied connectome simulation + coherence analysis | + +We accept this rubric and commit to the "best positioning" in all +external artifacts. + +## 7. Proposed ADRs + +Five ADRs land this compendium in the project's decision record. ADR +numbers are reserved starting at **ADR-084** (the last existing ADR +before this compendium is **ADR-081**; ADR-082 and ADR-083 are reserved +for unrelated in-flight work). + +Each ADR follows the existing RuView format: Status, Context, +Decision, Consequences, Links. + +### 7.1 ADR-084 — Connectome Graph Substrate (Layer 1) + +- **Status**: Proposed +- **Context**: CC-OS requires a typed, provenance-tagged, + performance-adequate graph substrate for 10k–139k neuron connectomes + with 1M–60M synapses. Existing `wifi-densepose-db` is row-store + oriented; existing `wifi-densepose-ruvector` is signal/MAT focused. + Neither covers the connectome use case directly. +- **Decision**: Introduce `wifi-densepose-connectome` crate implementing + the `ConnectomeGraph` aggregate (02-connectome-graph-substrate.md + §10), `Neuron` / `Synapse` / `Region` value objects, and adapters to + `ruvector-mincut` edge triplets and `ruvector-temporal-tensor` + per-neuron voltage buffers. FlyWire loader first; MICrONS and larval + *Drosophila* loaders behind feature flags. +- **Consequences** (positive): graph-native circuit queries; + provenance-tagged synapses; witness-log-compatible. (negative): + adds a new crate to maintain; widens `NodeId` to `u64` in a new + namespace. (neutral): publishing order changes. +- **Links**: RD-C-02, RD-C-03. + +### 7.2 ADR-085 — Neural Dynamics Runtime (Layer 2) + +- **Status**: Proposed +- **Context**: CC-OS requires an event-driven LIF runtime at 1 kHz + real-time for 50k-neuron subgraphs, with deterministic replay and + compressed voltage/spike storage. +- **Decision**: Introduce `wifi-densepose-neuro` crate + (04-neural-dynamics-runtime.md §10). Uses `ruvector-solver` for + rate-code and perturbation solves; `ruvector-temporal-tensor` for + voltage and spike storage; `ruvector-attention` for motif queries. + Inner loop single-threaded for determinism; rayon fan-out per time + slot for throughput. +- **Consequences**: full cross-region LIF runtime available to the + workspace; reuses RuVector patterns without duplication; introduces + `rand_chacha` and `rayon` dependencies to a new crate. +- **Links**: RD-C-04, RD-C-05. + +### 7.3 ADR-086 — Embodied Simulator Closed Loop (Layer 3) + +- **Status**: Proposed +- **Context**: Without a body, circuit dynamics do not produce + behavior. CC-OS needs a deterministic Rust-native inner-loop body + simulator at 1 kHz physics / 100 Hz control, with an optional bridge + to NeuroMechFly for biomechanical validation. +- **Decision**: Introduce `wifi-densepose-embody` crate using Rapier + for physics and a hand-authored minimal fly body (41 DoF). Optional + `nmf-bridge` feature for NeuroMechFly cross-validation. +- **Consequences**: tight in-proc Rust loop; no Python dependency on + the critical path; validation story intact via optional bridge; + `rapier3d` becomes a workspace dependency. +- **Links**: RD-C-06. + +### 7.4 ADR-087 — CRV Behavioral Episodes + Coherence Gating (Layer 4) + +- **Status**: Proposed +- **Context**: Behaviors are episodic. CC-OS needs a bout-level + encoding that is reproducible, queryable, and integrates with the + existing `ruvector-crv` six-stage protocol and `CoherenceGate`. +- **Decision**: Implement `BehaviorPipeline` inside the existing + `wifi-densepose-ruvector` crate as a sibling of `WifiCrvPipeline`. + Map CRV stages I–VI to behavior-class / neural-sensory-feature / + body-pose-sketch / coherence-gate-state / circuit-query / min-cut + respectively (07-coherence-crv-behavioral-episodes.md §2). +- **Consequences**: six-stage bout encoding for free via + `CrvSessionManager`; Stage VI's MinCut directly yields + behavior-responsible circuits; cross-subject convergence via + `find_convergence` retargeted to `behavior_class`. +- **Links**: RD-C-07, RD-C-05. + +### 7.5 ADR-088 — Governance, Positioning, and Counterfactual Protocol + +- **Status**: Proposed +- **Context**: Running connectome dynamics with counterfactual + perturbation invites both scientific mis-statement ("mind upload") + and dual-use misuse. A governance ADR fixes the framing, the + allowed-claim boundaries, and the perturbation-audit protocol. +- **Decision**: + 1. CC-OS is positioned as a "coherence-aware connectome operating + system". The terms "mind upload", "digital consciousness", and + their synonyms are prohibited in RuView public artifacts. + 2. Counterfactual perturbations (08-counterfactual-perturbation.md) + must emit witness bundles compatible with the ADR-028 convention. + 3. Only published, peer-reviewed connectomes may be loaded in v1 + (FlyWire, MICrONS partial). + 4. Mammalian connectomes are out of scope for v1 without external + ethics review. +- **Consequences**: clear framing for public communications; dual-use + risk structurally mitigated by audit requirements; mammalian + exploration is gated behind process, not policy. +- **Links**: RD-C-11 (this document), RD-C-08, RD-C-01. + +## 8. Five-Phase Implementation Roadmap + +| Phase | Weeks | Deliverables | Gates | +|-------|-------|--------------|-------| +| 1 — Connectome import | 1–4 | `wifi-densepose-connectome` crate; FlyWire loader; graph storage and query benchmarks | Load 139k-neuron FlyWire in < 10 s; k-hop query < 10 ms | +| 2 — LIF runtime | 5–10 | `wifi-densepose-neuro` crate; event-driven kernel; voltage + spike storage; deterministic replay | 1 kHz real-time for 10k-neuron subgraph; replay SHA-256 reproducible | +| 3 — Closed loop | 11–16 | `wifi-densepose-embody` crate; Rapier fly body; sensorimotor loop; 100 Hz control | Stable 100 Hz loop for 60 s without divergence | +| 4 — Grooming acceptance | 17–20 | All four criteria of 10-acceptance-test-grooming.md pass on CI | Acceptance test green | +| 5 — Fragility + convergence | 21–26 | `BehaviorPipeline` + `PerturbationRunner`; cross-subject convergence via `find_convergence`; first public witness bundle | Fragility correlates with published Hampel 2015 result; witness bundle self-verifies 7/7 | + +Total: 26 weeks (6 months) from kickoff to first publishable witness +bundle. + +## 9. Success KPIs per Phase + +| Phase | Primary KPI | Secondary KPIs | +|-------|-------------|----------------| +| 1 | Load time, query latency | Memory footprint, loader coverage | +| 2 | Real-time factor | Replay reproducibility, compression ratio | +| 3 | Closed-loop stability duration | Physics step rate, actuator saturation rate | +| 4 | All four acceptance criteria green | CI wall-clock, flake rate | +| 5 | Behavioral fragility $\mathcal{F}$ distribution | Jaccard with published circuits, convergence score | + +Each KPI has a target and a minimum; missing the minimum blocks +promotion to the next phase. + +## 10. Out-of-Scope Items for v1 (Explicit) + +- Mammalian connectomes (mouse cortex, larger). +- Consciousness or phenomenal-experience claims. +- Real-time human-scale simulation. +- GPU-accelerated LIF. +- Distributed multi-node simulation. +- Live web visualisation. +- Unsupervised behavior discovery. +- Plasticity in the inner loop. +- Wing aerodynamics. +- Photorealistic rendering or optic-flow vision beyond simple + luminance. +- Companion or anthropomorphic framing. + +## 11. Publication and Talk Plan + +| Venue | Submission | Target claim | Artifact | +|-------|-----------|--------------|----------| +| NeurIPS workshop on neural connectomics | 2026 | Coherence-aware runtime + fragility pipeline | First witness bundle | +| eLife methods (or PLOS Comp Biol) | 2026 | CC-OS architecture + grooming reproduction | Peer-reviewed paper | +| RustConf | 2026 | Rust systems architecture + determinism | Live demo | +| Strange Loop | 2026 | Coherence-aware framing + dual-use ethics | Talk | +| bioRxiv preprint | Month 6 | Full methods | Accompanies ADRs | + +No press-first releases. Every external communication follows the +positioning and avoids the VERY HIGH / HIGH risk items of §2. + +## 12. Appendix A: 200-Word Short-Form Summary + +> We built CC-OS, a **coherence-aware connectome operating system**, as +> a substrate for studying circuits that drive behavior in published +> insect connectomes. CC-OS is Rust-native, graph-first, and +> deterministic. It loads a peer-reviewed connectome (FlyWire is the +> v1 target at 139,255 neurons and 54M synapses), runs an event-driven +> LIF neural runtime at real-time rates for 50k-neuron subgraphs, +> closes the sensorimotor loop through a Rapier-based fly body, and +> provides auditable counterfactual perturbation with min-cut-based +> fragility scoring. Every run emits a witness bundle with SHA-256 +> provenance that can be independently replayed. The first acceptance +> test reproduces the published fly antennal-grooming circuit (Hampel +> 2015) inside simulation, and shows the RuView min-cut identifies the +> same minimal sufficient circuit that optogenetic dissection did. CC-OS +> is **not** a mind, not a consciousness upload, not a replacement for +> NEURON or Brian2, and not a gesture at human-brain emulation. It is +> a platform for reproducible, auditable, graph-native connectome +> circuit science at insect scale. + +## 13. References + +1. Sandberg, A., Bostrom, N. (2008). *Whole Brain Emulation: A + Roadmap.* Future of Humanity Institute, Oxford. +2. Seth, A. (2021). *Being You: A New Science of Consciousness.* + Faber. +3. Friston, K. (2013). *Life as we know it.* J. R. Soc. Interface. +4. ADR-028 — ESP32 capability audit + witness verification. +5. ADR-017 — RuVector signal + MAT integration. +6. ADR-011 — Python proof of reality. +7. Dorkenwald, S., et al. (2024). *Neuronal wiring diagram of an adult + brain.* Nature. +8. Hampel, S., et al. (2015). *A neural command circuit for grooming + movement control.* eLife. +9. Seeds, A. M., et al. (2014). *A suppression hierarchy among + competing motor programs drives sequential grooming in + Drosophila.* eLife. +10. Lappalainen, J. K., et al. (2024). *Connectome-constrained networks + predict neural activity across the fly visual system.* Nature. +11. Kakaria, K. S., de Bivort, B. L. (2017). *Ring attractor dynamics + emerge from a spiking model of the entire protocerebral bridge.* + Front Behav Neurosci. + +--- + +**End of compendium.** Return to [00-index.md](./00-index.md) for the +table of contents.