External Consumer Integration Contract

[yjmaxpayne]

Overview

Defines and tracks the integration contract between HELIX and an external
downstream simulation platform that currently uses a QuTiP-based HEOM solver
and is migrating to call HELIX as a drop-in backend. This is a
physics-correctness contract, not just an API contract — unit conventions,
rotating/lab-frame handling, bath-channel ownership, and result schema must
match exactly, or the swap silently produces wrong physics.

Background

The consuming platform expects a specific result shape
({states, times, expect}) and specific unit/frame conventions (GHz input,
internal angular-frequency representation, lab-frame restore after any
rotating-frame integration). A mismatch here is invisible at the API-typing
level — it only shows up as a wrong physical answer — which is why this is
tracked separately from general API evolution and needs joint tests, not
just interface types.

Core Objectives

1. Unit convention

GHz-input / internal-angular-frequency / restore-on-output, exposed via
SolverOptions::units.

2. Frame convention

Lab (default) and Rotating (internal transform, integrate, restore),
exposed via SolverOptions::frame, with the rotating frequency captured in
RunResult.frame_metadata.

3. Result schema compatibility

HELIX's RunResult must convert, without semantic loss, into the
{states, times, expect} shape the existing consumer plugin expects,
including density-matrix wrapping compatible with existing conventions.

4. Bath ownership contract

HELIX must not reinterpret or duplicate dissipation-channel ownership
decisions made by the calling platform — e.g. when a fluctuation channel is
already represented as a HEOM bath, HELIX must not also apply an
independent relaxation channel for the same physical process.

5. Error/diagnostics mapping

HELIX StatusCode values must map predictably onto the exception types the
calling convention expects (unsupported-feature / invalid-input /
resource-unavailable / numerical-warning).

6. Optional compatibility adapter

Convert external quantum-object representations to/from HELIX's sparse
operator representation, as an independent, opt-in module.

Success Criteria

Metric	Target
Rotating-frame phase restore	≤ 1e-3 rad phase error vs. reference
Result shape requires zero caller-side code changes when switching backend	0 caller diffs
Bath-ownership exclusion rule	verified by contract test
Version-compatibility policy	documented

Dependencies

Depends on Bath Layer Redesign (bath kind coverage) and Physics
Validation & Test Infrastructure (shared oracle data feeds both sides'
regression tests). This Epic is the acceptance gate for the minimal-viable
release (v1.0-minimal).