# ISAES domain adapters and compatible integration migration

New integration executions and private workflows can use the same scientific
input contracts, versioned analysis plan, evidence graph, presentation document
and HTML/PDF/PPTX/figure exports. Existing reports remain readable; migration
does not overwrite their bytes or rerun their simulations.

## Implemented adapter catalog

`pf_reporting.adapters.adapter_catalog()` returns the machine-readable catalog.
The public translation API is `adapt(adapter_id, payload, metadata, name=...)`.
It returns a normal private-workflow result with explicit reporting datasets and
an original-payload digest. It does not call a provider or acquire hardware.

| Adapter | Required meaning | Accepted operation | Refusal |
|---|---|---|---|
| `pf.integration-receipt/1` | Original schema-1 integration identity, execution status, evidence status and uniquely named checks | Preserve declarations, inputs and provenance in the shared evidence core | Unknown status, non-boolean verdict, ambiguous/duplicate checks, nonfinite JSON |
| `pf.srgr-timing/1` | Coordinate frame/chart, metric/signature, clock definition, origin and propagation assumptions | Preserve an actual `gr_photon.solve_null_geodesic` ray; plot coordinate time and spatial coordinates with linked sample identities; evaluate declared residual tolerances | Missing clock/frame semantics, unsupported chart/metric, occulted/failed ray, inconsistent shapes or endpoint times |
| `pf.declared-series/1` | x/y units, frame, quantity, sampling and origin | Preserve ordered quantities; optionally convert compatible y units explicitly through Pint | Missing semantics, incompatible units, complex or unequal axes; no automatic frame or clock conversion |

The existing `pf_reporting.domain` adapters remain the quantum path: actual
Qiskit/QuTiP object conversion and explicitly supplied counts, observables,
checkpoints, mitigation, calibration, variational, chemistry and shadow records.
Their required basis, tensor order, shot and origin semantics remain in effect.
A package being installed does not establish adapter qualification or hardware
execution. A supplied chemistry/calibration/mitigation record is not a newly
executed chemistry calculation, hardware calibration or mitigation experiment.

Adapters preserve original values separately from conversions. The recorded
conversion binds original and converted values by canonical SHA-256, with both
units recorded. Frame and clock conversion are never inferred from compatible
units. Changing Schwarzschild coordinate time into receiver proper time requires
an explicitly implemented physical transformation and retained input data.

## Integration reports and migration

`pf_integrations.runner.run_study` now writes an `isaes/` companion before sealing
the integration evidence manifest. Its existing `report.json`, `report.md` and
`report.html` formats are retained. The legacy HTML links to the shared ISAES
report and shows the migration status. Source hashes now also bind `pf_reporting`.

Every backend receives a bounded execution-receipt migration. This preserves
its original failed/unassessed/passed declarations without converting them into
new core checks. For example, an imported acquisition's data-integrity pass
does not become a physics-validation pass. The report explicitly distinguishes
legacy execution from migration completion. The shared numerical status remains
unassessed unless a real shared analyzer computes a check over retained values.

The `relativity_benchmarks/published_clocks_and_links` path additionally consumes
its retained `raw_radial_rays.json` through the SR/GR adapter. These are the
production solver's actual Earth and strong-field radial rays. The adapter
does not reconstruct rays from a summary or substitute analytic sample data.
Other backend-specific arrays remain preserved in the legacy bundle until their
semantics are supplied explicitly through the declared-series contract or a
qualified specialized adapter. This is compatible migration, not a claim of
automatic understanding of every third-party API.

To migrate a retained integration bundle using the qualified research runtime:

```console
python -m pf_integrations.reporting path/to/original-study path/to/new-migration
```

The destination must be new and separate. The original evidence manifest is
verified first. Only manifest-bound artifacts are copied, capped at 128 MiB and
2,048 files. Original report and manifest bytes are copied into `legacy/`;
new shared exports are in `isaes/`. `migration_manifest.json` binds the copied
inputs and new outputs. Integrity verification establishes byte consistency,
not source authenticity. A missing local analysis/export dependency produces an
explicit unavailable migration with a recovery action; it does not suppress the
usable legacy record or claim complete delivery.

This local command reads files that the caller already controls. It does not
accept another owner's service-object IDs, attach literature, alter workflow
retention or authorize imports across private workspaces. For private workflows,
use the normal workflow/report services: they capture immutable inputs, enforce
ownership, associate retained literature, and apply the existing dependency and
lifecycle rules. A report copied to a standalone directory does not itself
register a new server-side retention dependency.

## Actual PF core SR/GR example

Import `documentation/workflow_examples/srgr_timing_isaes.json` through the normal
private-workflow import flow. The same Python program is supplied separately as
`documentation/workflow_examples/srgr_timing_isaes/main.py` for inspection.
The bundle pins NumPy 2.3.5 and SciPy 1.18.1, matching the numerical-worker lock;
use that qualified runtime when validating or running the example.

The program executes `gr_photon.solve_null_geodesic` twice at the chosen static
radial endpoints: the GM=0 special-relativistic limit and the exterior
Schwarzschild model. It retains both full ray results, the exact executed core
file hash, coordinates, units, clock definition, metric/sign convention,
propagation assumptions, schedule and explicit absence of noise. Its numerical
validation compares actual solver flight times with the independently derived
radial Schwarzschild coordinate-time integral. Analytic reference values are
used only for validation, never substituted for solver output.

After validation and activation, run the workflow and generate its normal ISAES
report. Two linked ray views per scenario show retained affine samples in time
and space. The reported excess coordinate time is conditional on these stated
models, endpoints and coordinates. It does not measure an operational PF timing
advantage, experimental agreement or commercial benefit.

`tests/test_isaes_domain_adapters.py` exercises real core computations, missing
semantics, incompatible clocks/charts, conversion provenance, legacy failure
preservation, source immutability, manifest tampering, missing renderers and the
actual private workflow → validate → activate → run → report/export service path
with a provider that refuses any access. Cross-owner report access is rejected.
Native Windows, real hardware and production containment remain environment
qualification gates; local execution is not evidence that those gates passed.