feat(export): IMAS-shaped replay export adapter (#49)

[obvious-autobuild]

Fixes #49.

Human author: Tapan Ganatma Nakkina ([email protected])

Why

Issue #49 asks FusionLab's replay bundle to speak to IMAS dictionaries. Today the export surfaces are derived CSV/JSON, OpenUSD, and the replay bundle itself; none names quantities the way the fusion community's data dictionary does. The backlog program's locked decision: IMAS is an export direction only — an adapter at the edge, never an internal data spine and never an import path. This PR ships that adapter.

What

• fusionlab/imas_export.py (new, on the usd_export.py pattern): a pure function over the same bundle dict usd_export.export_shot takes, mapping the ShotBundle v1 arrays to IMAS data-dictionary paths via a static, in-repo table. Units convert once at this edge — house units (m, T, MA, 1e20 m^-3, keV, MW, MJ) → the dictionary's (A, W, m^-3, eV) — with api_replay._UNIT as the conversion table's test oracle. Nothing is recomputed: every emitted value is the bundle's own.
• GET /replay/{shot_id}/imas (sibling of the USD route): a strict-JSON attachment, imas_{id}.json, whose values equal the /replay bundle path-for-path, plus the sibling fusionlab_annotations.json in the same body: the catalog's useful/abort flags, the per-series provenance labels (measured/model/learned/computed), the machine-specific eq_inputs block, and the series the dictionary has no home for (n_e20 line density, Thomson radii, R_m, P_rad_MW, dWdt_MW, midplane-radius q_mid). The IMAS payload points at the sidecar via ids_properties.comment and carries no flag or label as data.
• Graceful degradation inherited: groups the bundle lacks are omitted, never emitted as empty IDS stubs — the same rule /replay applies.
• Dictionary verification (flagged as training knowledge in the spec, verified this session against the IMAS Data Dictionary, DD 4.2.x build, imas-data-dictionary.readthedocs.io, accessed 2026-10-12): equilibrium.time_slice.global_quantities.ip in A; q_95/beta_tor_norm dimensionless; boundary.elongation/minor_radius in m; profiles_1d.f in T.m with psi in Wb; profiles_2d.psi in Wb on a rectangular grid (grid_type.index = 1, dim1=R, dim2=Z); pf_active coil rectangle geometry fields r/z/width/height (geometry_type.index = 2); wall limiter unit[].outline r/z in m; ids_properties.comment exists as free text. Two honest omissions: vacuum_toroidal_field.r0 is left out because the bundle does not record the reference radius B_T was measured at (noted in the IDS comment); the wall description.type enum is left unfilled because no option honestly describes a single open limiter.
• Docs: DATA_CONTRACT.md's "future adapter" paragraph now states the export direction and the import-never-as-spine rule; .obvious route maps updated.
• No new dependency (omas not taken, not even as an extra — a dev cross-check can be added later if wanted); base pyproject.toml untouched.

How to Review

• The mapping table + sidecar lists in fusionlab/imas_export.py are the whole design — everything else is mechanics. test_mapping_table_partitions_the_spec guarantees every future SPEC field gets classified (IMAS home or sidecar entry), never silently unexported.
• tests/fixtures/imas/golden_30166.json is a committed full-value snapshot (~6 MB, one value per line). When the export changes deliberately, regenerate with the one-liner in the test module's docstring and review the diff — the snapshot diff is the failure mode.
• Intentionally excluded: IMAS import, omas as a dependency, any change to /replay or the bundle spec.

Test Evidence

• Full suite on the rebased tree (main @ a7a6e87): 539 passed, 1 skipped (main alone: 526; +13 new — 11 in tests/test_imas_export.py, 2 in tests/test_api.py), uv run ruff check clean, uv run mypy fusionlab clean.
• New tests cover: the golden snapshot of shot 30166; conversion-vs-oracle; equality of the attachment with the /replay bundle at IMAS paths; degraded bundles (minimal and LCFS-only) exporting core traces only; sidecar contents; the comment-pointer rule; GET-only + clean 404s; no non-finite float in the attachment.
• Backend-only change — no rendered UI surface is touched (the download affordance is an attachment header, same style as the USD/export routes), so visual dogfood evidence is not applicable.

🔗 Obvious Project · 🧵 Obvious Thread · 🔀 Obvious PR Artifact