# Engineered visual-to-spiking bridge and direct-drive diagnostic

This is an open-loop neural interface experiment, not a reconstructed animal or
body controller. The first interface failed its prespecified direction criterion.
The later diagnostic directly stimulated upstream visual neurons and passed;
it does not repair the visual interface or establish autonomous behavior.

## Sources and layout

- Original spiking model: https://github.com/philshiu/Drosophila_brain_model/tree/91bdd1e7dcf193f3e7ca5a8933497fcef63b7960
- Visual model: https://github.com/TuragaLab/flyvis/tree/0a69fa2fc8e1bfe1d837d722c252ab5f5d6fcbfa
- Original annotation: https://github.com/flyconnectome/flywire_annotations/tree/df6bb136f5b3d91c3992df4e8de2642329e2a384
- Later annotation: https://github.com/flyconnectome/flywire_annotations/tree/ebd66db2596fcc39c6950fb54ea3efa00f7fe8a0
- HS/H2 circuit study: https://doi.org/10.1038/s41593-025-01948-9
- T4 subtype directions: https://doi.org/10.7554/eLife.40025

The public `run.py` and `diagnose.py` copies replace only the private absolute
baseline location with a portable relative path. `script-normalization.json`
records executed-original and public-copy SHA-256 values. Original execution
summaries retain the original hashes; the public auditors accept either an exact
runner hash or this explicit normalization mapping. Private executed scripts and
all numerical data remain unchanged. Recreate the documented Linux runs layout;
record a new script hash for any further edits. Source/data Git blobs are checked
before and after execution.

Place v630 `annotations-v1.1.0.tsv` at
`runs/2026-10-28/steering-v01/sources/annotations-v1.1.0.tsv`, and the later
`annotations-v2.1.0.tsv` at
`runs/2026-10-28/visual-steering-v01/sources/annotations-v2.1.0.tsv`.
Their source commits and hashes are recorded in `source-provenance.json` and
`structure-v01/summary.json`. The later subtype labels actually select the
candidate inputs after exact original-ID and v630-side filtering; this is an
annotation-transfer assumption.

The baseline source path is `runs/2026-10-26/2026-10-26_fly-baseline_v01/source`;
its seven original files and source manifest must come from the pinned model.
The two dependencies are isolated: `requirements-visual.txt` for Flyvis and
`requirements-spiking.txt` for Brian2. The visual source snapshot is installed
as `0.0+g0a69fa2` using setuptools-scm's explicit snapshot version; this is not
an official release number. The official pretrained ZIP has SHA-256
`71c78d4070556a536b13b23ee3139cd2788aa2a9d07d430a223b4edead281db1`;
the selected checkpoint SHA-256 is
`d0e42857e738d0315897c2d50fde9eb3fb1a3fb1f071d55dfc13d53d72bccc3f`.

## Execution sequence

1. With the original full source and pinned annotation files present, run
   `prepare.py` under the spiking environment. This generates `structure-v01`.
2. Freeze `protocol.json` before observing any motor simulation.
3. Run `project_visual.py` under the visual environment. It copies the fixed
   checkpoint into a new data directory, saves all 721 columns of each T4a/b
   type for two moving movies and a uniform-grey control, then computes the
   population projection and original-model identity/side eligibility.
4. Run `run.py` under the spiking environment. It records a local-clock preflight
   hash receipt, generates common per-cell random numbers, and executes 30 fresh
   full-network trials into `results-v01`. Only the specified eight chemical
   rows are zeroed in route cuts; fresh restores reinstate their original weights.
5. Run `validate.py --source-root <original-baseline-root>` in the spiking
   environment to reconstruct the means/rates, random candidates, driver events,
   all pathway counts, direction criteria and complete spike-event restorations.
6. After the bridge's failure, freeze `diagnostic-plan.json` and run `diagnose.py`.
   This executes nine fresh full-network trials with new seeds and matching
   four-channel direct HS/H2 candidates. Run `validate_diagnostic.py` afterward.
7. Run `analyze-v02.py` to produce `analysis-v02` from saved data only.

Use fresh output folders; the simulation scripts refuse to overwrite runs.
The recorded Linux invocations used one CPU thread and nice15, a 30-minute
timeout for the main run and 15 minutes for the diagnostic:

```sh
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 NUMBA_NUM_THREADS=1 nice -n 15 timeout --kill-after=30s 1800 <spiking-python> -u run.py
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MPLBACKEND=Agg <spiking-python> validate.py --source-root <original-baseline-root>
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 nice -n 15 timeout --kill-after=30s 900 <spiking-python> -u diagnose.py
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 <spiking-python> validate_diagnostic.py
```

## Scope of the evidence

The projection uses **positive changes in population-mean model activity**.
It is not Flyvis's native per-neuron rectified synaptic-output function, and
does not preserve individual retinotopy, signed deviations below baseline,
biological firing rates, electrical synapses or graded-cell dynamics. Stable
root membership plus matching annotation sides is a lookup check, not independent
biological identity or spatial validation. The gain is an engineering assumption
fixed before motor trials, not calibrated using desired steering.

`results-v01` includes the actual driver monitors and whole-network spikes.
The diagnostic archived candidate schedules and actual whole-network spikes;
its actual driver equality was asserted inside the runner, while separate
per-trial diagnostic driver-monitor files were not archived. Audits verify saved
data and source hashes, not a new neural inference or biological validity.

The first post hoc analysis used original weights as reference values even on
cut rows, with an inactive-edge flag. It remains private as `analysis-v01`.
`analyze-v02.py` records zero actual weighted arrivals for cut rows. Intact
curves, primary counts and criteria were unaffected. Nominal arrivals are model
weight times arriving spike count before decay, integration and refractoriness;
they are not membrane voltage, measured current or a biological causal fraction.

The public manifest covers exported files. Logs have private run roots redacted
and newline formatting normalized; original raw logs remain in the Linux and
private local run. No model weights were trained or tuned after the results.
