Flybrain Connectome MCP Server

flybrain-connectome

v3.00.3 · 2026-10-25 · 116 functional units · 270 module profiles · 62 gates · EPE 全栈 + AIBOM 供应链披露 + 收据完整性门禁 + Gate 60/61/62/63/64 + fail-loud 纪律 + 版本单一真源 + Xu 2026 树突计算前沿对照 + Xu 2026 双层认知计算参考实现（tools/dendritic_rule_engine.py + examples/07_dendritic_rule_cache_demo.ipynb）+ E4 区室边界 + S1 外部验证 + S2 lesion cascade + S3 统计强化 + 纪律有效性量化（catch-rate 100%，W1–W7 全部关闭）+ Gate 63 research_claims 顶层统计完整性 + 作者署名规范化（P-3 / P-4 → Li Xing + ORCID）+ bioRxiv 投稿准备包 + flybrain demo 一条命令 + 5 分钟上手 + flybrain audit CLI + JOSS 投稿包 + MCP 生态提交包 + 9 篇论文 DOI 补齐

The 89% problem

Deloitte's 2026 agent-pilot survey found 89% of enterprise agent pilots never reach production. Teradata: 78% have pilots, only 14% scaled. The failure pattern repeats across industries in three words:

"跑不稳、管不住、查不清" — unstable, ungovernable, unauditable.

flybrain-connectome addresses the third word. Every agent edge in a generated topology traces back to a real neuron or synapse class in the Drosophila male brain connectome, serialized as W3C PROV-JSON — the same format EU AI Act auditors expect. Your agent swarm isn't a black box; it's a verifiable structure with biological provenance.

5-minute quickstart — from zero to an interactive D3 topology graph in five minutes, no data download.

Auditable Agent Topology — 可审计的 Agent 拓扑生成与溯源, grounded in the real Drosophila male-brain connectome (MaleCNS v1.0 — 166,700 neurons / 124,177,617 synapses, CC-BY).

flybrain-connectome turns a real, published brain wiring diagram into task-tailored multi-agent topologies you can instantiate as agent swarms — and it can prove, for every edge, which real neuron / synapse class it came from. The motif provenance is serialized as W3C PROV-JSON, the same standard EU AI Act auditors expect.

5-module × 8-agent topology (predictive_coding_v2 blueprint) — the same graph you get from flybrain demo. Try it live →

It is a developer toolkit and research artifact, not a trained model and not a simulation of a fly. Read the honest boundaries before you quote it.

Repo status: PUBLIC since 2026-10-18. History was audited and cleaned before publicization (see CHANGELOG v1.3.0 for the original Tier-2 IP leak and docs/D3_REPOSITORY_PUBLICITY_DECISION_2026-10-18.md for the 16-step publicization runbook that was executed). The Tier-1 code is MIT-licensed and reachable at https://github.com/lm203688/flybrain-connectome. Tier-2 raw data (MaleCNS 5.63 GB, C. elegans Witvliet 2020, Drosophila larva edges.csv, Petkova 2025 zebrafish) is fetched via the documented data pipeline — see §"Requirements" and the S1 external-validation script.

---

What it is / what it is NOT

The killer offline feature: generate needs no data — it composes topologies from a 7 KB derived motif snapshot. The connectome data is only needed if you want to query the real brain.

---

Honest status of the unit library

The 116 functional units are split cleanly by how their evidence comes together. This is the number to remember when reading any downstream claim:

The 68.1 % bucket is not a defect and not a hidden error. It is a comparative-neuroscience scaffold: bird song, mammalian cortical layers, fish Mauthner, cephalopod vertical lobe, Aplysia and leech CPGs, insect mushroom-body — all are wired into the library with named references and can be composed like the anchored ones, but they are not measured in a real connectome the way the 37 anchored units are. Reading the library correctly means reading those two numbers together, not the 116 by itself.

How to use this — tiered by what you can actually get today

Rather than a single "this is a X" pitch, the useful things this project does break down into three tiers. Which one you actually need depends on what you are building.

Tier 1 — usable today, offline, no data download. Neuron-circuit search across 3 species × 4 axes (system / function / species / provenance); compose a virtual-organism topology from any subset of units; run the four canonical DEMOs (mammal, insect, electrosensory, swim) end-to-end. This is the developer tool the project actually is. flybrain search, flybrain compose, flybrain generate cover it.

Tier 2 — for people designing AI-agent scaffolds. The composed topologies trace back to real circuitry via W3C PROV-JSON, which means a downstream agent framework (LangGraph / CrewAI / AutoGen / SwarmLabs) can pick up a starting topology and audit where each wiring decision came from. This is not a general agent infra — it is a biology-prior layer you plug into one.

Tier 3 — what this project explicitly does not do. It does not beat biology at anything (Phase 3 measured negative and is not claimed). It does not replace any EM reconstruction pipeline. It does not ship a trained model or a spiking simulator. If someone reads a v1.x changelog entry that promises any of those, the honest answer is "that was aspirational; the withdrawal is documented in docs/PROJECT_REALITY_ASSESSMENT.md".

---

The four moats (measured, not marketed)

We ran the experiments. Two of the "obvious" advantages turned out to be false under controlled testing, and we say so.

What we explicitly do not claim

Honesty is a feature. The reproducible experiment scripts live in integrations/swarmlabs/diagnostics/ and the reports in the repo root (SNN_ENERGY_REPORT.md, MULTI_READOUT_REPORT.md, FAULT_ISOLATION_REPORT.md).

---

Install

The toolkit needs one runtime dependency (numpy, because the connectome engine imports it at module level) plus optional extras for provenance and columnar IO. No other third-party code is required. Pick either setup:

Repo status: PUBLIC since 2026-10-18. No authentication required — the clone commands below work directly. History was audited and cleaned before publicization (see CHANGELOG v1.3.0 for the original Tier-2 IP leak and docs/D3_REPOSITORY_PUBLICITY_DECISION_2026-10-18.md for the 16-step publicization runbook).

A. Clone and run (recommended, verified end-to-end)

git clone https://github.com/lm203688/flybrain-connectome.git
cd flybrain-connectome
python flybrain_cli.py --help

B. Editable install (puts flybrain on your PATH)

git clone https://github.com/lm203688/flybrain-connectome.git
cd flybrain-connectome
pip install -e .
flybrain info

pip install -e . is editable: the flybrain entry point maps back to the checkout, which is precisely what lets it find the toolkit. A plain pip install . ships only the launcher, so point it at a checkout explicitly:

pip install .
export FLYBRAIN_HOME=/path/to/flybrain-connectome
flybrain info

This path is verified in CI, not just documented. The package job in .github/workflows/ci.yml runs pip install ".[prov]", invokes the console script, resolves the toolkit via FLYBRAIN_HOME, generates an organism, and asserts the artifact's invariants — so the install instructions cannot silently rot.

C. Optional: the standardized provenance bundle

Structural provenance (motif_provenance, with the snapshot sha256) is always recorded. The standardized W3C PROV-JSON bundle (prov_json) is serialized by the optional dataprov package:

pip install dataprov                     # or: pip install "flybrain-connectome[prov]" (once on PyPI)

Without it the toolkit still runs: prov_json becomes null and get_provenance_bundle answers with prov_available: false plus the reason, rather than crashing. Both arms are asserted by scripts/check_degraded_mode.py — absent must degrade, present must actually produce the bundle.

Always check what you got

flybrain info

reports the resolved toolkit root, the motif snapshot, the data dir, API-key status, and how many tools are exposed. Run it first whenever something looks wrong — it turns "ImportError" into a named, fixable problem.

To query the real connectome you also need the data

MaleCNS v1.0 is CC-BY, ~5.63 GB, and deliberately not in this repo:

export FLYBRAIN_DATA_DIR=/path/to/your/male_cns

generate and the bundled motif snapshot need no data at all.

---

Quickstart

Every flybrain <cmd> below also works as python flybrain_cli.py <cmd> (setup A), so you can try the project without installing anything.

0. Sanity-check the install

flybrain info
# -> toolkit root [ok] · motif snapshot [ok, 7363 bytes] · tools exposed: 36

1. Serve the connectome (optional — only for querying real data)

flybrain serve --port 8799
# or: python flybrain-connectome-mcp/run_api.py

2. Query the real brain

export FLYBRAIN_API_KEY=<your-key>   # set in config.json or env

flybrain query pair_synapses --args '{"pre":10540,"post":12569}'
# -> 711   (the real APL → DPM connection)

flybrain query connectome_overview
# -> {"total_synapses": 124177617, "annotated_neurons": 211577, ...}

3. Pull the derived motif document

flybrain motifs --out motifs.json      # live pull from the service
# offline snapshot (no server, no data): flybrain-connectome-mcp/motifs/swarm_agent_topology_motifs.json

4. Generate a synthetic bio-topology (offline, no data)

flybrain generate --blueprint predictive_coding_v2 --modules 5 --agents-per-module 8
# -> flybrain-connectome-mcp/generated_organisms/<name>.{json,html} + flybrain-connectome-mcp/swarmlabs/<name>.swarm.{json,yaml}

5. Read the C. elegans developmental axis

flybrain stages         # L1 x4 / L2 / L3 / adult x2, measured per animal
flybrain stages --caveat            # why the L1 columns are a floor
flybrain stages --unit cel_amphid_chemosensory_unit

6. Read the larva connectome cluster ledger

flybrain larva-clusters             # network totals + per-unit coverage
flybrain larva-clusters --top 20    # the 20 biggest clusters
flybrain larva-clusters --unannotated
flybrain larva-clusters --caveat    # what "covered" does and does not mean

7. Read the MaleCNS male-dimorphic ledger

flybrain composition               # can declared combinations actually form?
flybrain costs                      # latency/energy per connection type
flybrain function                   # coverage by FUNCTION, not by species
flybrain function --vision          # only what PROJECT_VISION requires
flybrain dimorphism                 # 2,368 cells nobody has looked at
flybrain dimorphism --provenance    # ... with the curator note behind each sex label
flybrain dimorphism --top 20 --internal
flybrain dimorphism --caveat        # what "male-specific" does not mean here

8. Verify everything still works

flybrain verify        # needs FLYBRAIN_DATA_DIR set to your data

9. Profile a topology (offline, no data)

The topology-aware layer turns "what shape is this organism?" into a callable, reproducible answer — density, degree spread, reciprocity, modularity Q, transitivity, spectral radius (power iteration, no numpy), feedback-edge fraction, a directed 3-node motif census, and a deterministic structural signature. It is honest by construction: not_measured names what a structural profile cannot speak to (dynamics, energy, task performance).

flybrain generate --blueprint predictive_coding_v2 --modules 5 --agents-per-module 6 --name demo
flybrain profile generated_organisms/demo.json
flybrain profile generated_organisms/demo.json --json          # full profile
flybrain profile generated_organisms/demo.json --compare generated_organisms/other.json

Self-validated by Gate 15 (scripts/check_topology_profile.py).

---

Repository layout

flybrain-connectome/
├── flybrain_cli.py                 ★ developer CLI (serve/query/motifs/generate/verify/info)
├── pyproject.toml                  zero deps, `flybrain` console script
├── LICENSE · CITATION.cff · CHANGELOG.md
├── flybrain-connectome-mcp/
│   ├── mcp_connectome/             query engine (core) + 47-tool MCP + HTTP API (:8799)
│   ├── motifs/                     drop-in client + derived motif snapshot
│   ├── synthetic_bio_topology.py   ★ C1 generator (motif → agent graph + config + PROV)
│   ├── _verify.py                  end-to-end smoke test (70/70)
│   └── flybrain-connectome-mcp/
│       ├── generated_organisms/     example artifacts (json/html + swarm configs)
│       └── swarmlabs/               swarm config exports
├── integrations/swarmlabs/         consistency checkers + diagnostics (reproducible experiments)
├── scripts/                        run_gates.py · check_no_secrets.py · check_docs_consistency.py
│                                   check_mcp_tools.py · check_degraded_mode.py
│                                   check_generated_artifact.py · gh_publish.py
├── .github/workflows/ci.yml        the same gates, on py3.10/3.12/3.13 + packaged-CLI job
└── docs/                           arxiv_paper.md · mcp_setup.md · module_factory.md

---

HTTP API reference

Service: flybrain-connectome-mcp/mcp_connectome/api_server.py.

Auth: Authorization: Bearer <key> or X-API-Key: <key>. Keys come from config.json (api_keys) or env FLYBRAIN_API_KEY. If none is configured the server generates a temporary per-boot key and warns loudly — it never falls back to a key committed to source.

The 47 tools (real names, do not invent — verified against GET /tools by scripts/check_docs_consistency.py):

Real-connectome queries — the 11 marked ⚠ need FLYBRAIN_DATA_DIR:

connectome_overview ⚠ · neuron_info ⚠ · pair_synapses ⚠ · neuron_outputs ⚠ · neuron_inputs ⚠ · degree ⚠ · search_neurons ⚠ · superclass_projection ⚠ · hub_targets ⚠ · list_superclasses ⚠ · pathway ⚠ · export_swarm_motifs

Generator surface — offline-capable, served from the motif snapshot:

list_blueprints · list_modules · list_bio_motifs · batch_generate_topologies · get_provenance_bundle · list_stacked_blueprints · get_stacked_feasibility · list_neuropils · get_neuropil_detail · get_module · check_module_compatibility · compose_virtual_organism · list_virtual_organisms · list_presets · get_preset · apply_preset · organism_to_swarmlabs · get_module_agent_roles · save_market_organism · load_market_organism · list_market_organisms · rate_market_organism · search_market_organisms · delete_market_organism · list_combination_rules · validate_combination · expand_organism · get_multiplier_metrics · profile_topology · profile_health

Functional-unit composition library — the composable layer above neuron types:

list_functional_units · get_functional_unit · list_connection_types · list_evidence_ledger · compose_from_units

---

Synthetic organism schema

synthetic_bio_topology.design_organism(spec) returns:

{
  "organism": {
    "nodes": [ {"id": "m0_rep", "role": "tissue_rep", "module": 0,
                "profile": "memory", "ref_superclass": "CB", ...} ],
    "edges": [ {"from": "m0_rep", "to": "m0_c0", "weight": -0.31,
                "kind": "inhibitory", "module": 0, "ref_body": 10540} ]
  },
  "metrics": {
    "n_nodes": 29, "n_edges": 18, "avg_degree": 1.24,
    "inhibition_ratio": 0.11, "n_modules": 4,
    "intra_module_edges": 14, "inter_module_edges": 4,
    "modularity_est": 0.778, "profile_breakdown": { ... }
  },
  "blueprint": "predictive_coding_v2",
  "motif_provenance": {            // 3-stage traceability
    "mode": "local_snapshot",
    "motif_synapse_stats": { ... },     // % of the 124M-synapse dataset
    "motif_query": "SELECT ...",        // runnable provenance query
    "blueprint_to_motif": { ... }
  },
  "prov_json": { ... }             // W3C PROV-JSON bundle (schema v1.2.1)
}

The W3C PROV-JSON (prov_json) bundle records entity / activity / agent nodes with wasDerivedFrom / wasAssociatedWith / wasAttributedTo edges, attributing every topology to FlyCellAtlas and the flybrain:dataset_anchor (MaleCNS v1.0). It is consumable by yProv4ML, MLflow2PROV, and MIT Sloan provenance tooling.

---

Blueprint & module library

25 blueprints across three categories, composed from 270 modules: 10 cognitive-function modules (sensory / memory / motor / integration / attention / working_memory / reward / punishment / habit / metacognition) + 190 cross-species neuron types spanning cortical pyramidal (L2/3 CX1/CX5, L4b/L4c, L5 basal tuft, L6 reticulo-thalamic, L7 temporal, Mayeret) + intermediate interneurons (Calbindin/LAMP/NPH/NPF/VLAC/SST-dendritic/ SST-somatic/KCN, plus PV/SST/VIP/chandelier/basket) + modulatory systems (dopaminergic A9/A11/VMC/VTA/SNC, serotonergic dorsal/ventral/median raphe, noradrenergic LC, cholinergic MT/horizontal, histaminergic TM, orexin) + retinal (bipolar cone/rod, amacrine ACL1/ACL2, midget/PV ganglion, horizontal) + spinal/cerebellar (α/γ motor, Icc/Ih/Ihp interneurons, glycinergic, nociceptive, Purkinje/granule/stellate, inferior olive) + thalamic/basal ganglia (LGN/MD/VA/VL/VPL/VPM/RTN, STN, red nucleus, striatal D1/D2 MSN) + limbic/edge (hippocampal CA1/CA2/CA3/CA4/granule/subiculum, amygdala BLA/LA, septum, entorhinal L2/L3, grid cell) + special senses (pineal, melanopsin, olfactory, vestibular, cochlear outer hair)

• reactive astrocyte

• four clades whose neurons have no vertebrate-cortex counterpart (35 further types, each carrying its own biological_reference):

• insect (14) — Kenyon cell / mushroom-body output / PPL1-PAM dopaminergic / APL, antennal-lobe projection and local neurons, protocerebral bridge / ellipsoid body / fan-shaped body / noduli / ring neurons, s-LNv and lateral clock neurons, descending neuron
• bird (6) — HVC, RA, LMAN, Area X, DLM, NIf (the song system)
• fish (8) — Mauthner cell, reticulospinal neuron, lateral-line hair cell, ampullary and tuberous electroreceptors, ELL pyramidal cell, electrosensory inhibitory interneuron, electric-organ pacemaker neuron
• cephalopod (7) — vertical-lobe large / amacrine / small cells, superior frontal lobe cell, chromatophore motor neuron, arm motor neuron, arm sensory afferent

• a second non-cortical batch: rhythm, state and error (24 further types, v1.6.0):

• segmental / peripheral oscillators (9) — leech swim-CPG interneuron and body-wall motor neuron with its mechanosensory T cell, ascidian larval motor neuron and ocellus photoreceptor, Aplysia sensory / motor / serotonergic facilitating neurons, buccal ganglion CPG neuron
• infrared and amphibian (5) — trigeminal infrared afferent, infrared tectal map neuron, multimodal optic-tectum neuron, tectal T5-type prey detector, tongue motor neuron
• error teaching and state (6) — climbing fibre, cerebellar Golgi cell, vestibular nucleus neuron, pre-Bötzinger complex neuron, phrenic motor neuron, VLPO neuron
• navigation and active sensing (4) — head-direction cell, place cell, barrel cortex neuron, whisker motor neuron

Every blueprint traces to one of 40 topology motifs (3 original MaleCNS-extracted + 37 conceptual patterns spanning anatomical / functional / plasticity / specialized categories) or is honestly marked motif: none (synthetic orchestration, no bio-prior) — 16 bio-prior, 9 not:

• 5 basic — flat / hub / ring / layered / random reference topologies
• 16 biological — e.g. predictive_coding_v2 (recurrent_feedback+reward), metacognitive_control (inhibitory_hub), habit_consolidation (recurrent_feedback), hierarchical_deep (reservoir_smallworld) …
• 4 synthetic — rl_actor_critic, curiosity_driven, cognitive_control, multi_motif_blend (honestly motif: none)

Nested composition a+(b+c) is parsed as isomorphic to a+b+c. Full list:

from flybrain_connectome_mcp.synthetic_bio_topology import BLUEPRINTS  # (in-repo path)
# or after pip install: import synthetic_bio_topology as c1; c1.BLUEPRINTS

Machine-readable equivalents (same data, over HTTP/MCP): list_blueprints, list_modules, list_bio_motifs.

---

Functional-unit & connection-type library

The neuron list above is the vocabulary. It is not the unit of composition: a single neuron type does nothing on its own, and wiring two of them together means nothing. What composes is a function with a known interface. So the library is split into two tiers, and the upper tier is the one you actually build from:

• 116 functional units — each is ONE function (phototransduction, action selection, theta pacing, gliotransmission, sparse mushroom-body coding, ring-attractor heading, song timing, Mauthner escape, active electrolocation, camouflage, leech swim rhythm, infrared thermal imaging, climbing-fibre error teaching, sleep/wake switching …) delivered by a group of neuron populations (1–6 of them, taken from the 254-module vocabulary) wired into an internal sub-circuit, and exposing typed ports (light in → high_res out; candidates + value in → selected_action out). Composition: 40 mammal-cortex-shaped + 16 cross-clade (insect / bird / fish / cephalopod, v1.4.1) + 16 rhythm/state/error and active-sensing (annelid, ascidian, mollusc, pit viper, frog, cerebellum, brainstem, hippocampus, barrel cortex, v1.6.0)
  • 10 Drosophila-shaped (optic lobe, giant-fiber escape, male courtship & song, lateral horn, v1.8.0 — every one of them fully anchored, see below).
  • 5 Drosophila-shaped (thermal preference, feeding circuit, leg motor, multimodal LAL, sleep memory, v1.10.0 — first batch anchored, see below).
  • 4 C. elegans connectome-derived (forward locomotion command, touch-avoidance reflex, amphid chemosensory, nociceptive avoidance — v2.27.0, see below; each also carries a L1 → L2 → L3 → adult axis, v2.30.0).
  • 8 Drosophila larva connectome-derived (larv_olfactory_associative_learning_unit, larv_somatosensory_escape_unit, larv_gustatory_feeding_program_unit, larv_descending_motor_command_unit, larv_mushroom_body_feedback_unit — v2.28.0, third connectome — plus larv_thermosensory_relay_unit, larv_visual_relay_unit, larv_respiratory_relay_unit — v2.29.0, one unit per traced sensory channel, see below).
• 66 connection types — each is one connection FORM, constrained on the port types it may join, in six families: micro (axo-dendritic / axo-somatic / axo-axonic / dendro-dendritic … point-to-point contact sites) · circuit (feedforward / feedback / lateral / mutual / recurrent / disinhibition / winner-take-all / global inhibitory gain control / synfire chain / efference-copy cancellation / half-centre oscillation / grid phase precession …) · modulatory (diffuse / volume / retrograde / state gating) · electrical (gap junction / ephaptic / mixed electro-chemical / tripartite astrocyte / plateau-potential bistability) · plasticity (STDP / LTP-LTD / short-term / homeostatic scaling / modulator-gated / repeated-activation LTS / serotonergic presynaptic facilitation / short-term habituation / coincidence detection) · macro (topographic mapping / divergent fan-out / convergent fan-in / corollary discharge / global broadcast / sparse expansion / command-neuron recruitment / bistable state switch / thermal cross-modal convergence).

So the algebra is virtual organism = units (nodes) + connection types (typed edges), and every edge is mechanically checkable because both endpoints declare port types:

unit A .out_port[type]  --connection_type(from_port, to_port)-->  unit B .in_port[type]

compose_from_units enforces port-type compatibility, required-port satisfaction, external drivability/readability of the whole organism, and reports feedback loops as warnings (an intentional feedback loop is a first-class citizen here). An unsatisfied required input on the organism boundary is the organism's external input, not a defect — pass allow_boundary_inputs: false to validate an interior sub-chain instead.

Four canonical chains ship as fixtures and are re-validated by Gate 9 on every run — --demo mammal (retina → thalamus → cortex → basal ganglia → motor thalamus), --demo insect (antennal lobe → mushroom body sparse code → learned valence → central complex heading/steering, clock-biased), --demo electrosensory (EOD pacemaker → efference-copy cancellation → electrolocation, plus a passive-electric cue into the Mauthner escape command) and --demo swim (leech half-centre swim CPG → ascidian larval oscillator → frog reticulospinal escape swim). --demo with no argument runs all four.

Developmental axis (v2.30.0) — the same four circuits at L1 / L2 / L3 / adult

The Witvliet 2020 series is eight reconstructions, not two: four L1 animals, one L2, one L3 and two adults. The library used to carry only the two adults. All eight are now loaded and measured per animal. Each of the four C. elegans units above carries the result in provenance.developmental_stages; run flybrain stages to print it.

The four circuits, measured at every stage (synapses per animal):

Those four rows do not add up (v2.34.0). The circuits are not disjoint cell-class sets — AIA sits in all four, AIB/AIZ/AVB/PV in two or three — so an edge like AIZ → AIB is internal wiring for two circuits at once and gets counted by both. Adding the column overstates the wiring that is actually internal to these circuits by ~1.27×. Both figures are now reported per stage:

Use union for "how much of this animal's wiring sits inside these circuits"; use the sum only when the circuits are counted individually. The extractor now asserts that the per-circuit rows reconstruct the sum, and refuses to write when they disagree.

One circuit is measured wider than the unit it attaches to (v2.35.0). PROFILES declares 11 cell classes for the touch-avoidance circuit, PLM among them, but extract_cel_profiles.py only emits a member profile for a declared class that actually has an edge inside the module — and in the adult reconstruction PLM has none, so the v2.27 unit ships 10 members and cel.plm does not exist anywhere in this library. Merged across all eight reconstructions PLM does have edges, so this series measures 11. Both are correct; the unit name is identical, which is exactly why the gap had no name and no guard. The artifact now records it as declared_vs_shipped and the extractor refuses to write if a unit ever ships a class the series cannot measure. Practical consequence: compare the touch-avoidance stage numbers against the unit by that one class, not directly.

Across all 16 measurements the four circuits are present in every animal at every stage (6–37 edges at L1), so what development adds is synapse weight, not new topology.

The boundary that matters here. A side result — 271 edge pairs appear in L1 and not in the adults — is not reported as transient developing synapses. A single L1 file carries 566–795 distinct edges against 1,107 for a single L2 file, so "seen at L1" is confounded with reconstruction depth. Only the claim that survives that confound is published; the caveat field of cel_development_stages.json states this in the artifact itself. As of v2.34.0 that 271 is computed (stage_diffs.l1_only_keys, alongside l1_union_keys 1,188, adult_union_keys 1,980, shared_keys 917, adult_only_keys 1,063) rather than written into the caveat as a literal that could not be re-derived if the source changed.

Larva cluster ledger (v2.31.0) — how much of the larva network the units cover

The eight larva units were built by aggregating nodes on (cell_type, annotations). That left one question unanswered: how much of the 352,611-synapse larva network do they actually span? flybrain larva-clusters answers it by walking all 116,922 edges.

A synapse counts as covered only when both endpoints' (cell_type, modality bucket) resolve to a larv.* profile that at least one unit declares as a member. A synapse is frontier when neither endpoint does.

Per unit, at both-endpoint resolution:

Three cell classes sit entirely outside every unit: the unlabelled class (346 cells), MB-FFN and pre-DN-SEZ.

_unannotated in a profile id does not mean "unannotated" (v2.36.0). 15 of the 43 profile classes carry that suffix, and it is bucket()'s modality-recognition fallback, not an annotation verdict: a cell whose annotations string is literally KC contains no modality keyword, so it lands in the fallback bucket while being fully named. 13 of those 15 classes hold annotated cells — 1,686 of them, including larv.kc_unannotated (144 cells, all annotated KC), larv.mb_fbn_unannotated (100, all annotated like CN-10; FAN-2) and larv.mb_ffn_unannotated (54, all FFN-23 and siblings). The earlier line in this README that read the frontier list as an annotation verdict was wrong on exactly this point: MB-FFN's 54 cells all carry names.

The network-wide figure is unaffected — 1,560 cells (52.77%) genuinely have no official annotation, because it reads the annotations column directly and never touches the bucket. What was wrong was the reading of the names. The ids are unchanged (40 profile keys, gate 9 and every published artifact index them by name); the two notions are now measured apart in annotation_identity and carried on each unit as member_id_caveat.

The per-unit rows are not additive either (v2.34.0). Nineteen larv.* profiles are declared by more than one unit — larv.lhn_unannotated, larv.lhn_mechano, larv.kc_unannotated and friends — so one synapse legitimately counts toward each of them. The eight rows sum to 319,064 against a covered total of 271,956 (1.17×). Use the union figure for network coverage and the per-unit rows only to compare units with one another; the shared-profile list is in unit_attribution and flybrain larva-clusters --caveat prints it. The extractor asserts that the sum can only exceed the covered total, that the coverage partition closes, and that per-cluster internal + out reconstructs the network.

The headcount was the wrong measure. The larva network has 1,560 cells with no official annotation — 52.77% of its neurons, and the number that made the network look mostly uncharacterised. They touch 212,542 synapses, 60.28% of the total, because the units do declare the unannotated populations as filler roles. Coverage and characterisation are different things, and the ledger holds them apart on purpose: a unit can span three quarters of the larva synapses while its unannotated members still have no known function. Cluster 0 — the authors' unassigned bucket, 364 cells — is the single largest holder of synapses in the whole network (51,211) and is not given a function here.

Male dimorphic ledger (v2.32.0, audited v2.33.0) — 2,368 cells inside the male connectome

MaleCNS v1.0 is a male reconstruction, and its annotation table carries a dimorphism column. Nobody in this library had ever read it: the 58 anchored profiles were built from superclass / type, and type is not sex-aware. flybrain dimorphism streams all 151,856,684 weight rows and asks, for every edge, whether at least one endpoint is one of the 2,368 bodies the column flags.

The gap between those last two rows is the finding. The male population is not an island: it is a thin, widely-connected subset that mostly talks to universal cells, and only about one in nine of the synapses it touches sits between two of its own cells. A "male circuit" declared on these numbers would have to be the 1.28% — which is smaller than the measurement noise of the surrounding network. So no circuit is declared: FUNCTIONAL_UNITS stays at 115, and 29 units carry the population's distance in provenance.male_dimorphic.

The heaviest type is TmY21 (372 bodies, 732,527 synapses, 0.590% of the network). The heaviest both-ends pair is TmY21 → LoVP92 (442 edges / 2,721 synapses), then AN09B017b → mAL_m1, then pC1_2a → mAL_m8.

How big is "big" here (v2.33.0). v2.32.0 quoted those totals with nothing to compare them against, which is how oviIN's two bodies / 196,360 synapses came to look like an error — it is 10× the "1k–10k per neuron" folk rule. It is not an error. The per-body distribution in this connectome is heavy-tailed:

So oviIN sits at the 99.98th percentile — the top of a long tail, not an outlier — while TmY21, the heaviest type by total, sits at only the 72nd percentile per body. Cell count and per-cell strength are different things and the ledger now carries both.

Three things the type names will not tell you (v2.33.0). First, the annotation table carries three independent type axes — type (MaleCNS, 11,751 classes), flywireType (8,199) and hemibrainType (4,495) — and type disagrees with flywireType on 33.08% of bodies. TmY21 in this ledger is the class FlyWire calls Tm36; the alias travels with every top type. All 5,413 anchored type names were checked to sit on the type axis, and the script refuses to write if that ever stops being true. Second, each type now carries the curator's own matchingNotes sentence behind the sex label (oviIN: "more extensive dendrites in male") plus its trace grade — 150 of 479 types have such a note and 327 are only Roughly traced. Third, the per-type totals are now checked on every run: each pair is charged once per dimorphic endpoint, so they must sum to touching + both-ends (14,966,115), and the extractor refuses to write if they do not. They did not in v2.32.0 — internal pairs were counted four times, which inflated every per-type figure by 3× the internal total.

What this ledger cannot say. MaleCNS contains no female reconstruction, so a dimorphism label is the curator's annotation, not a comparison made here. Nothing in it supports "larger in males", and the artifact says so in its own caveat field. Two counters are also kept separate on purpose: 194 dimorphic types are listed in an anchored profile's own type list (someone looked at them), while all 479 sit inside some anchored ^XXX family rule — family membership is not tracing.

Documentation truncated — see the full README on GitHub.