Datasets and Data Registry

scpn-quantum-control ships two classes of data artefact:

1. In-repo, authoritative hardware results under data/<campaign>/. Small JSON files (a few MB each) that feed publication claims. Tracked in git; every row of every JSON must reproduce the numbers in CHANGELOG.md and docs/results.md (enforced by tests/test_phase1_dla_parity_reproduces.py).
2. Legacy exploration cache under results/. Pre-2026-04 experiments; kept for archaeology but not part of any current scientific claim. New items are gitignored (.gitignore:65).

This document names the policy for both classes and the trigger for moving a dataset off the filesystem into a persistent-archive (Zenodo) record.

In-repo dataset policy

A data/<campaign>/ directory must have:

• A literature/README.md describing the campaign, the hardware, the capture date, and the claim-to-file mapping.
• Every JSON embedded with a provenance block emitted by hardware/provenance.py (git hash, versions, runtime, host).
• A reproducer test that loads the JSON and asserts every number cited elsewhere in the repo.
• A row in docs/results.md with a one-line summary and links.
• An entry in the campaign's pre-registration (from v0.9.11 onward — see docs/preregistration.md).

Example that already conforms: data/phase1_dla_parity/ + tests/test_phase1_dla_parity_reproduces.py + docs/results.md §Phase 1 DLA parity + docs/falsification.md §C2.

Application benchmark datasets also conform to this contract at data/public_application_benchmarks/. They are small curated public benchmarks for EEG, ITER-style MHD mode locking, IEEE 5-bus power-grid synchronisation, and FEP predictive-coding workflows. The loader path is scpn_quantum_control.applications.load_application_benchmark_artifact, and the plugin suite is documented in docs/application_benchmarks.md.

The BL-63 audit_application_benchmark_privacy() API additionally binds each packaged application artifact to its exact curated source mode, privacy class, licence boundary, personal-data flag, and embedded array hashes. Its deterministic aggregate report is described in Domain Application Honesty Kits. The audit does not inspect external plugin inputs or turn curated benchmark matrices into raw domain evidence.

Differentiable-programming exact-answer fixtures are code-defined rather than stored as raw data files. scpn_quantum_control.phase.domain_benchmark_datasets ships synthetic bounded phase-QNN and two-oscillator Kuramoto-XY cases with analytic probabilities, losses, gradients, order parameters, and energies. The claim boundary is deliberately narrow: these fixtures validate differentiable math and benchmark harness inputs; they are not measured datasets, hardware evidence, or performance benchmark artefacts.

The same module indexes published public-domain benchmark artefacts from data/public_application_benchmarks/ for differentiable conformance. Those records keep source references, licences, transforms, artefact hashes, and source-equation formulae such as PLV phase locking, MHD mode coupling, IEEE 5-bus swing-equation power flow, and FEP variational free energy. Validation checks that those formulae round-trip through the public case payloads together with Kuramoto conversion metadata, without duplicating raw files or promoting the examples as live hardware/timing evidence.

Soft size cap: 20 MB per campaign. Above that, move to Zenodo per the next section and leave a DOI pointer in the repo.

Graduation to Zenodo / Software Heritage

When a campaign's dataset exceeds ~20 MB, is sealed for publication, or becomes part of a formal preprint, it moves to an externally-archived Zenodo record:

1. Reserve a Zenodo DOI via the API (token in user-supplied credentials vault under Zenodo). Write the DOI into the campaign literature/README.md before the upload, so readers see the eventual citation target.
2. Upload the raw JSONs (plus the analysis script from scripts/ and the reproducer test). Zenodo versioning handles updates; the concept DOI stays stable across versions.
3. Replace the in-repo dataset with a thin stub MANIFEST.json recording the Zenodo DOI, file SHA-256s, and row-count checksums. Consumers fetch the data via the DOI. The reproducer test gains an opt-in download (if DATASET_DIR.exists(): run_asserts(); else: pytest.skip("data not present")).
4. Update docs/results.md to prefer the Zenodo URL over the in-repo path.

The Phase 1 DLA parity dataset (~2 MB) is under the cap and stays in-repo for now. Phase 2, if it exceeds 20 MB, will use this graduation path.

DVC (Data Version Control) — not adopted

DVC adoption was considered during the 2026-04-17 audit (item B10) and deferred. Rationale:

• In-tree JSONs plus Zenodo DOIs already provide versioning, integrity, and public archival without a second tool.
• DVC adds a remote-storage dependency (S3 / GCS / SSH / WebDAV) that would require a new credential in the vault and a CI bootstrap step.
• The current data volume is small (~2 MB at Phase 1); DVC shines above 1 GB.

Re-evaluate when any single campaign's dataset exceeds the 20 MB graduation threshold or when a non-quantum backend starts emitting large per-run traces (e.g. full state-vector dumps on 20+ qubit Lindblad simulations). At that point, either DVC with a Zenodo remote or a direct Zenodo-first workflow (option 3 above) is chosen.

Checksum verification

Any consumer that depends on the exact numerical reproducibility of a published claim should verify file SHA-256s against the MANIFEST.json that ships with each campaign directory. The manifest is generated by scripts/manifest_campaign.py (to be added — see follow-up).

Template of a data/<campaign>/MANIFEST.json:

{
  "campaign": "phase1_dla_parity",
  "zenodo_doi": null,
  "files": {
    "phase1_bench_2026-04-10T183728Z.json": {
      "sha256": "<64-hex>",
      "rows": 42,
      "size_bytes": 812345
    }
  },
  "claims": {
    "mean_asymmetry_depths_ge_4_percent": 10.8,
    "peak_asymmetry_depth_6_percent": 17.48,
    "fisher_chi2": 123.4,
    "fisher_df": 16
  }
}

The claims block duplicates the numbers in docs/results.md so a single file is the ground truth for "what this dataset claims to show".

Review cycle

Per campaign. Every new entry in data/ triggers this document's review. Missing literature/README.md, missing reproducer test, or a filesystem-size overshoot marks the campaign as non-compliant and blocks release.

Audit item B10 closes once the Phase 2 campaign either stays under 20 MB (in-repo + MANIFEST) or migrates to Zenodo under the graduation path above.