berkus
/
wifi-densepose
mirror of https://github.com/ruvnet/wifi-densepose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Claude 2026-04-22 00:40:25 +00:00
parent 79477c17a9
commit ad8d0aa59b
No known key found for this signature in database
12 changed files with 3559 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
docs/research/connectome-embodied-brain/00-index.md Normal file
View File

@ -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.

339
docs/research/connectome-embodied-brain/01-foundations-connectome-neuroscience.md Normal file
View File

@ -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.

365
docs/research/connectome-embodied-brain/02-connectome-graph-substrate.md Normal file
View File

@ -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<SensoryLabel>, // Bristle / JohnstonsOrgan / Ocelli / etc.
motor_label: Option<MotorLabel>, // 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<f32>, // 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<Vec<u8>>,
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.

379
docs/research/connectome-embodied-brain/03-mincut-circuit-analysis.md Normal file
View File

@ -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.

339
docs/research/connectome-embodied-brain/04-neural-dynamics-runtime.md Normal file
View File

@ -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<f32>, // length = n_neurons — membrane potentials
last_spike_ms: Vec<f32>, // length = n_neurons — for refractory check
csr_adjacency: CsrAdjacency, // read-only view of ConnectomeGraph
spike_queue: BinaryHeap<ScheduledSpike>,
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::<f32>::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.

276
docs/research/connectome-embodied-brain/05-cross-region-attention-fusion.md Normal file
View File

@ -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<f32>, // 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<f32>,
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.

289
docs/research/connectome-embodied-brain/06-embodied-simulator-closed-loop.md Normal file
View File

@ -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<Joint>, // ~41
links: Vec<Link>,
sensors: Vec<Sensor>, // contact, bristle, Johnston's
actuators: Vec<Actuator>, // 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.

281
docs/research/connectome-embodied-brain/07-coherence-crv-behavioral-episodes.md Normal file
View File

@ -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<FrameDigest, CrvError>;
pub fn finalize_bout(&mut self, bout_id: &str)
-> Result<BehaviorEpisode, CrvError>;
pub fn interrogate(&mut self, bout_id: &str, query: &[f32])
-> Result<StageVData, CrvError>;
pub fn partition_circuit(&mut self, bout_id: &str)
-> Result<MinimalCircuit, CrvError>;
pub fn cross_subject_convergence(
&self, behavior_class: &str, min_similarity: f32
) -> Result<ConvergenceResult, CrvError>;
}
```
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.

246
docs/research/connectome-embodied-brain/08-counterfactual-perturbation.md Normal file
View File

@ -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.

281
docs/research/connectome-embodied-brain/09-four-layer-architecture.md Normal file
View File

@ -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 <connectome.bin>` | Load a connectome into the store; emits `ConnectomeLoaded` with SHA-256 |
| `brain simulate --duration <s> --subgraph <selector> [--seed N]` | Run closed-loop simulation, produce witness bundle |
| `brain ablate <spec.json>` | Apply perturbation events; idempotent given the manifest |
| `brain fragility --baseline <manifest> --perturbation <spec>` | Compute $\mathcal{F}(P)$ from 08 |
| `brain replay <manifest.json>` | Deterministic replay; SHA-256 verification |
| `brain inspect <run-id>` | 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-<run-id>-<sha>.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.

279
docs/research/connectome-embodied-brain/10-acceptance-test-grooming.md Normal file
View File

@ -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-<sha>.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.

344
docs/research/connectome-embodied-brain/11-risks-positioning-roadmap.md Normal file
View File

@ -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.