# Code Architecture Map

This map ties research concepts to current repository files. Treat it as a navigation layer, not a replacement for tests or code review.

## Research Concepts to Files

| Research concept | Current files | Status |
| --- | --- | --- |
| NFC core | `src/neurotwin/models/nfc/` | implemented experimental |
| Neural Field Compiler config/model | `src/neurotwin/models/nfc/compiler.py` | implemented experimental |
| Latent neural field | `src/neurotwin/models/nfc/latent_field.py` | implemented experimental |
| Causal field update | `src/neurotwin/models/nfc/field_update.py` | implemented experimental |
| Low-rank pair kernel | `src/neurotwin/models/nfc/pair_kernel.py` | implemented ablation primitive |
| Observation operators | `src/neurotwin/models/nfc/observations/` | implemented fMRI/EEG/behavior operators |
| Synthetic field generator | `src/neurotwin/data/synthetic_field.py` | implemented, gate pending |
| NFC falsification suite | `src/neurotwin/benchmarks/nfc_suite.py` | critical gate |
| Architecture registry | `src/neurotwin/models/architecture_registry.py` | canonical model dispatch |
| Old translator | `src/neurotwin/models/torch_models.py` | baseline/current model |
| Pair-Operator | `src/neurotwin/models/pair_operator.py` | historical ablation |
| Local baselines | `src/neurotwin/models/baselines.py`, `src/neurotwin/benchmarks/baseline_suite.py` | implemented |
| Prepared tasks | `src/neurotwin/data/prepared_tasks.py` | trusted task layer |
| Leakage audits | `src/neurotwin/data/audit.py`, `src/neurotwin/data/leakage.py`, `src/neurotwin/eval/audit.py` | trusted infrastructure |
| Split manifests | `src/neurotwin/data/split_manifest.py`, `src/neurotwin/data/manifest_io.py` | trusted infrastructure |
| Evidence gates | `src/neurotwin/reports/evidence_gate.py`, `src/neurotwin/eval/paper_gate.py` | trusted if finalization is explicit |
| Model cards/reports | `src/neurotwin/reports/`, `src/neurotwin/benchmarks/reports.py` | read-only reporting path |
| CLI | `src/neurotwin/cli.py`, `src/neurotwin/eval/command.py`, `src/neurotwin/training/command.py` | public command surface |
| Runtime estimates/preflight | `src/neurotwin/runtime/` | cluster safety layer |
| A100 handoff | `scripts/a100_krish_agent_autorun.sh.in`, `scripts/package_runner_bundle.sh`, `scripts/package_a100_handoff_zip.sh`, `README_HANDOFF.md.in` | package after clean commit |
| TurboVec layer | `src/neurotwin/retrieval/` if added | optional/deferred |
| fNIRS | docs only | theory/deferred |

## Files Not to Mutate Casually

- `src/neurotwin/data/split_manifest.py`
- `src/neurotwin/data/audit.py`
- `src/neurotwin/eval/audit.py`
- `src/neurotwin/reports/evidence_gate.py`
- `src/neurotwin/eval/paper_gate.py`
- `src/neurotwin/training/prepared_loop.py`
- `scripts/package_runner_bundle.sh`
- `scripts/package_a100_handoff_zip.sh`
- `README_HANDOFF.md.in`

These files define trust boundaries, packaging behavior, or long-running experiment contracts.

## Claim Boundary Files

- `README.md`
- `docs/CLAIMS.md`
- `docs/BASELINES.md`
- `docs/ROADMAP.md`
- `docs/research/neurotwin_project_state.md`
- `docs/research/nfc_falsification_criteria.md`
- `docs/research/neurotwin_master_research_state.md`

Any change to these files must preserve the rule that synthetic and smoke results are plumbing checks unless evidence gates explicitly permit a claim.

## Current Falsification Gate Files

- `src/neurotwin/benchmarks/nfc_suite.py`
- `src/neurotwin/eval/command.py`
- `src/neurotwin/cli.py`
- `tests/benchmarks/test_nfc_suite.py`
- `tests/cli/test_expanded.py`
- `docs/research/nfc_falsification_criteria.md`

The gate must fail hard on shape mismatch, missing metrics, NaNs, target leakage, and non-pass status under `--require-pass`.

## Files to Check Before A100 Handoff

- `git status --short`
- `src/neurotwin/benchmarks/nfc_suite.py`
- `src/neurotwin/eval/command.py`
- `scripts/a100_krish_agent_autorun.sh.in`
- `README_HANDOFF.md.in`
- `scripts/package_runner_bundle.sh`
- `scripts/package_a100_handoff_zip.sh`
- `docs/research/neurotwin_project_state.md`
- `docs/research/nfc_falsification_criteria.md`

The next A100 step is strict 1x NFC synthetic diagnostic only. Do not jump to Algonauts or 6x DDP before the synthetic gate passes.