# NeuroTwin Project State: NFC Pivot and Evidence-Gated Plan

## One-Paragraph Summary

NeuroTwin is a Python research package and CLI for leakage-audited neural translation experiments. The repo began as a benchmark scaffold for missing-modality reconstruction, future-state forecasting, cross-modal translation, few-shot subject adaptation, and dataset/site generalization under held-out splits. The current research direction keeps that infrastructure but makes NeuroTwin NFC, the Neural Field Compiler, the experimental model primitive: recordings are treated as partial, lossy observations of one evolving latent neural field rather than separate modalities to fuse directly. The repo is currently an evidence-gated research harness, not a completed model-superiority result.

## Architecture Hierarchy

| Layer | Role | Status |
| --- | --- | --- |
| NeuroTwin NFC / Neural Field Compiler | Core experimental architecture | implemented experimental path |
| NeuralStateSpaceTranslator | Legacy/current NeuroTwin baseline | retained baseline |
| NeuroTwinPairOperator | Historical pairwise operator | retained baseline and ablation |
| Ridge/autoregressive ridge/direct MLP/TCN/Transformer/SSM | Local sanity and sequence baselines | implemented baselines |
| BrainVista-style/TRIBE-style | Clean-room approximation lanes | approximations only |
| Manifest, leakage, claim gates, reports | Evidence infrastructure | trusted but must stay claim-hygienic |
| fNIRS/TurboVec/TurboQuant | Optional theory/infrastructure notes | docs only or deferred |

## Track A and Track B

Track A is the reproducibility and model-gates paper lane. It uses MOABB/EEG and synthetic smoke paths to validate leakage audits, identity probes, model cards, paper-mode reports, evidence bundles, and honest claim boundaries. Track A does not require NeuroTwin to beat ridge.

Track B is the model architecture paper lane. It uses NFC. The first proof point is strict synthetic latent-field recovery. Only after that gate passes should the repo move to Algonauts/CNeuroMod fMRI with verified real stimulus features, then later to 1x A100 debug and 6x A100 DDP.

## What Old NeuroTwin Is Now

`NeuralStateSpaceTranslator` remains the legacy/current NeuroTwin baseline. It is useful because it shares the task API, prepared-manifest path, and evaluation surface. It is not the future claim by itself.

## What Pair-Operator Is Now

`NeuroTwinPairOperator` is no longer the main primitive. It is retained as a historical baseline and as an ablation lane for low-rank relational updates inside the NFC question.

## What NFC Is Now

NFC is the experimental architecture path. It models a subject-specific latent field `F_s(x,t,omega)` and learns observation operators for signals such as fMRI, EEG, behavior, and stimulus-conditioned responses.

## What fNIRS Contributes

fNIRS supports the observation-operator worldview: physiology, optics, hemodynamics, and artifacts make measurement a lossy operator over latent activity. This repo does not claim fNIRS support, MDD support, clinical diagnosis, or private-data results.

## What TurboQuant/TurboVec Contributes

TurboQuant/TurboVec is optional future retrieval, compression, and semantic-audit infrastructure around NFC. It is not the core model contribution and must not become a required dependency.

## What Is Implemented

- `nt` CLI for doctor, data prepare/smoke/audit, split audit, estimate, train, eval, and report commands.
- Event manifests, split manifests, leakage audits, prepared-task generation, and claim gates.
- Synthetic and MOABB preparation lanes.
- Prepared-manifest training with checkpointing, resume, metrics, reports, and DDP hooks.
- Local baseline runners and competitor registry.
- NFC model modules under `src/neurotwin/models/nfc/`.
- NFC synthetic suite and falsification report.
- A100 packaging and handoff scripts.

## What Is Scaffolded

- BIDS/OpenNeuro derivative scanning without raw preprocessing.
- A100/H100 cluster templates.
- BrainVista/TRIBE-style approximation lanes.
- Paper-mode artifact contracts.

## What Is Theory Only

- Full fNIRS observation support.
- TurboVec/TurboQuant integration.
- Spike/calcium modality implementations.
- Exact upstream TRIBE v2, BrainVista, Brain-OF, BrainOmni, or Brain Harmony reproduction.

## What Is Archived/Deferred

- Pair-Operator as the main architecture.
- Clinical digital-twin language.
- Depression/MDD diagnostic claims.
- Raw public neural data in git.
- Full Algonauts/CNeuroMod model claims before strict gates.

## Next Experiment Ladder

1. Correct and trust the NFC synthetic falsification gate.
2. Run strict 1x A100 NFC synthetic diagnostic: `synthetic50`.
3. If needed and documented, escalate to `synthetic100`.
4. Only after pass, run Algonauts/CNeuroMod 1x debug with verified stimulus hashes.
5. Only after debug pass, consider 6x A100 DDP.
6. Draft model-paper claims only after held-out evidence and baselines pass.

## Claim Boundaries

Allowed: leakage-audited benchmark infrastructure, experimental NFC path, synthetic NFC smoke/falsification suite, MOABB Track A reproducibility evidence path, A100 handoff packaging from clean committed HEAD.

Not allowed: model superiority, proven NFC, NeurIPS-quality result, clinical diagnosis, fNIRS support, exact TRIBE v2 or BrainVista reproduction, first brain foundation model, or A100 success without evidence bundles.

## Kill Criteria

- NFC cannot beat direct baselines on true field-grounded synthetic tasks.
- NFC equals no-observation or no-pair ablations within the configured threshold.
- Metrics are NaN or missing.
- Shape mismatch is padded or broadcast instead of failing.
- Real stimulus hashes are unavailable for stimulus-to-fMRI claims.
- Held-out splits fail leakage audit.
- Evidence gates and final reports disagree.