{
  "schema_version": 1,
  "backends": [
    "cpu-reference",
    "cuda",
    "mps",
    "swift-metal",
    "webgpu",
    "vulkan"
  ],
  "contract": {
    "coordinate_order": "row-column",
    "real_space_crop": "explicit-only",
    "detector_bin": "explicit-count-preserving-with-partial-edges",
    "cpu_fallback": "explicit-reference-only",
    "integer_outputs": "byte-exact",
    "floating_outputs": "frozen-operation-specific-metric",
    "required_provenance": [
      "source_identity",
      "source_shape",
      "source_dtype",
      "scan_region",
      "detector_region",
      "scan_bin",
      "detector_bin",
      "output_shape",
      "output_dtype",
      "backend",
      "device",
      "source_revision"
    ]
  },
  "gold_fixtures": {
    "scan_rotation_v1": {
      "path": "src/quantem/gpu/parity/scan_rotation_v1.json",
      "sha256": "8dde7144ae5f297dffc7b1330b6db66301ff42849a39b6adadfb078acb6fd35f"
    }
  },
  "capabilities": [
    {
      "id": "io.packed-display-precision",
      "contract_version": "precision/v1",
      "public_owner": "quantem.gpu.io.load / quantem.gpu.io.save",
      "parity": "Explicit scaled uint16 codes (source-wide or per region; saved float16 exports convert on load) held ANS encoded on the device, restored intensity units, selected scan and detector regions, and GPU-measured error reports persisted through HDF5 export.",
      "coverage": {
        "cpu-reference": {
          "level": "not-implemented",
          "gates": [
            "docs/maintainer/migration.md"
          ],
          "qualification": "Accelerator implementations are required; CPU scientific conversion is intentionally unsupported."
        },
        "cuda": {
          "level": "required-hardware",
          "gates": [
            "tests/hardware/cuda/test_precision.py",
            "tests/parity/precision_fixture.py"
          ],
          "qualification": "CUDA save/load, exact restored frames, scan and detector regions, mean diffraction, binary detector sums, and persisted error reports against the shared independent NumPy oracle."
        },
        "mps": {
          "level": "required-hardware",
          "gates": [
            "tests/hardware/mps/test_precision.py",
            "tests/parity/precision_fixture.py"
          ],
          "qualification": "Python Metal/MPS save/load, exact restored frames, scan and detector regions, mean diffraction, binary detector sums, and persisted error reports against the shared independent NumPy oracle; numerical reports use float32 Metal reductions."
        },
        "swift-metal": {
          "level": "partial-hardware",
          "gates": [
            "docs/api/native_resident.md",
            "tests/hardware/mps/test_precision.py"
          ],
          "qualification": "Native scaled uint16 conversion, exact packed reads, GPU error accounting and standard HDF5 save/reopen are implemented and checked in the native MAPED consumer on an Apple Silicon workstation. Float16 native export, arbitrary detector geometry, detector-query coverage and minimum-memory release signoff remain incomplete."
        },
        "webgpu": {
          "level": "not-implemented",
          "gates": [
            "docs/maintainer/migration.md"
          ],
          "qualification": "CUDA save/load, selections and detector queries; Metal and browser-only precision formats are not implemented."
        },
        "vulkan": {
          "level": "not-implemented",
          "gates": [
            "docs/maintainer/migration.md"
          ],
          "qualification": "CUDA save/load, selections and detector queries; Metal and browser-only precision formats are not implemented."
        }
      }
    },
    {
      "id": "io.empad-float-resident",
      "contract_version": "empad-source/v1",
      "public_owner": "quantem.gpu.io.load / NativeEMPADSource.open / MetalEMPADResidentSource.load",
      "parity": "Original 128x128 float32 detector bits, explicit rectangular scan shape, footer separation, selected-frame ordering, and floating-point aperture sums without quantization.",
      "coverage": {
        "cpu-reference": {"level": "reference-fixture", "gates": ["tests/hardware/metal/test_empad_source.py", "tests/hardware/metal/test_empad_public.py"], "qualification": "Independent original-byte and NumPy float64 aperture oracles; not a Python resident implementation."},
        "swift-metal": {"level": "partial-hardware", "gates": ["tests/hardware/metal/test_empad_source.py", "tests/hardware/metal/test_empad_public.py"], "qualification": "Native original EMPAD source, exact float-word packing, DP and aperture kernels. Consumer integration, DPC, full cancellation and native release gates remain pending."},
        "cuda": {"level": "partial-hardware", "gates": ["tests/hardware/test_array_ans_workflows.py", "docs/maintainer/empad-contract.md"], "qualification": "io.load reads EMPAD XML/RAW and EMPAD2 XML records through formats.empad.load_array_source into a float32 ANS resident with unchanged IEEE bits. The QEM_TEST_BACKEND=cuda hardware tests use synthetic records: native frames and .qem round trips are bit-exact, EMPAD record footer words are excluded, several XML detector regions are kept as metadata, and encoded EMPAD2 sensor words are rejected. No real EMPAD acquisition, DPC or performance qualification is retained."},
        "mps": {"level": "partial-hardware", "gates": ["tests/hardware/test_array_ans_workflows.py", "docs/maintainer/empad-contract.md"], "qualification": "io.load reads EMPAD XML/RAW and EMPAD2 XML records through formats.empad.load_array_source into a float32 ANS resident with unchanged IEEE bits. The QEM_TEST_BACKEND=mps hardware tests use synthetic records: native frames and .qem round trips are bit-exact, EMPAD record footer words are excluded, several XML detector regions are kept as metadata, and encoded EMPAD2 sensor words are rejected. No real EMPAD acquisition, DPC or performance qualification is retained."},
        "webgpu": {"level": "not-implemented", "gates": ["docs/maintainer/empad-contract.md"]},
        "vulkan": {"level": "not-implemented", "gates": ["docs/maintainer/empad-contract.md"]}
      }
    },
    {
      "id": "geometry.scan-quarter-turn",
      "parity": "Byte-exact scan-row/column quarter turns with unchanged detector patterns, dtype, and coordinate convention.",
      "coverage": {
        "vulkan": {
          "level": "not-implemented",
          "qualification": "No Vulkan scan-quarter-turn primitive is exported.",
          "gates": [
            "native/vulkan/README.md"
          ]
        },
        "cpu-reference": {
          "level": "reference-fixture",
          "gates": ["tests/parity/test_geometry.py", "src/quantem/gpu/parity/scan_rotation_v1.json"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/parity/test_geometry.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/parity/test_geometry.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/Metal4DSTEMKernelsTests/ScanRotationParityTests.swift"]
        },
        "webgpu": {
          "level": "required-hardware",
          "gates": ["src/quantem/gpu/geometry/webgpu/quarter-turn.ts", "tests/infrastructure/test_webgpu_sources.py"]
        }
      }
    },
    {
      "id": "io.decode-bin-provenance",
      "parity": "Exact corrected integer values, shape, dtype, crop/bin geometry, and provenance.",
      "coverage": {
        "vulkan": {
          "level": "partial-hardware",
          "qualification": "Indexed uint16 decode and dense staging; packed residency with expanded 32/128-scan uint16 descriptors or compact 32-scan uint8 headers. Scan bin1, detector bin1, crop none only. Expanded32 and compact malformed-header regressions require Android execution; fresh shared-pin full-real-source device qualification remains pending.",
          "gates": [
            "native/vulkan/tests/contract_tests.cpp",
            "native/vulkan/tests/qh5_indexed_source_tests.cpp",
            "native/vulkan/tests/packed_admission_tests.cpp",
            "native/vulkan/tests/packed_detector_session_tests.cpp"
          ]
        },
        "cpu-reference": {
          "level": "reference",
          "gates": ["tests/contracts/io/test_load.py", "tests/contracts/io/test_public_api.py"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/hardware/cuda/test_streamed_h5.py", "tests/parity/test_native_dense_median.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/hardware/mps/test_streamed_h5_ans.py", "tests/hardware/mps/test_mps_buffer_release.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/Native4DSTEMIOTests/Native4DSTEMIOTests.swift", "native/swift/Tests/Metal4DSTEMKernelsTests/Metal4DSTEMKernelsTests.swift", "tests/hardware/metal/test_original_packing.py", "tests/hardware/metal/test_detector_regions.py"]
        },
        "webgpu": {
          "level": "required-hardware",
          "gates": ["tests/infrastructure/test_webgpu_sources.py", "tests/e2e/test_webgpu_widget_sync.py", "docs/maintainer/backend-4dstem-load-checklist.md"]
        }
      }
    },
    {
      "id": "io.selective-scan-loading",
      "contract_version": "quantem-gpu-selective-scan/v2",
      "public_owner": "quantem.gpu.io.Dataset4dstemGPU.read",
      "parity": "Exact selected detector evidence for half-open row/column scan and detector rectangles, with dtype, shape, failure behavior, and provenance.",
      "selectors": {
        "scan_region": {
          "coordinates": [
            "scan_row_start",
            "scan_row_stop",
            "scan_column_start",
            "scan_column_stop"
          ],
          "interval": "half-open",
          "bounds": "nonempty-and-contained-in-source-scan",
          "output_order": "logical-row-major",
          "output_shape": "(selected_scan_rows, selected_scan_columns, detector_rows, detector_columns)"
        }
      },
      "detector_region": {
        "coordinates": [
          "detector_row_start",
          "detector_row_stop",
          "detector_column_start",
          "detector_column_stop"
        ],
        "interval": "half-open",
        "bounds": "nonempty-and-contained-in-working-detector",
        "application_order": "after-explicit-detector-bin",
        "output_shape": "(selected_scan_rows, selected_scan_columns, selected_detector_rows, selected_detector_columns)"
      },
      "exact_result": {
        "scan_bin": 1,
        "counts": "unchanged-exact-integer-counts",
        "detector_bin_1_dtype": "source-dtype-unless-caller-requests-a-proven-lossless-output-dtype",
        "detector_bin_gt_1_dtype": "provably-sufficient-exact-integer-dtype",
        "lossy_or_saturating_output": "outside-this-parity-contract",
        "required_provenance": [
          "source_identity",
          "source_shape",
          "source_dtype",
          "scan_region",
          "detector_region",
          "scan_order",
          "scan_bin",
          "detector_bin",
          "output_shape",
          "output_dtype",
          "backend",
          "device",
          "source_revision"
        ]
      },
      "failure_contract": {
        "empty_selection": "error-before-decode",
        "out_of_bounds": "error-before-decode",
        "unsupported_backend": "error-without-fallback"
      },
      "coverage": {
        "vulkan": {
          "level": "not-implemented",
          "qualification": "Single-position diffraction is available, but the canonical rectangle scan-selection contract is not implemented.",
          "gates": [
            "native/vulkan/tests/selected_diffraction_c_api_tests.cpp",
            "native/vulkan/README.md"
          ],
          "implemented_selectors": [],
          "implemented_subset": [
            "single-position-indexed-accessor"
          ]
        },
        "cpu-reference": {
          "level": "not-implemented",
          "implemented_selectors": [],
          "limitations": [
            "public-io-load-selectors-rejected",
            "reference-oracle-is-separate"
          ],
          "gates": [
            "src/quantem/gpu/io/hdf5/cpu.py",
            "tests/contracts/io/test_load.py"
          ]
        },
        "cuda": {
          "level": "required",
          "implemented_selectors": [
            "scan_region"
          ],
          "qualification": "encoded-resident-read(scan_region, detector_region); io.load keeps complete acquisitions and has no sparse selectors",
          "gates": [
            "tests/hardware/cuda/test_ans_resident.py",
            "tests/hardware/test_ans_io_acceptance.py"
          ]
        },
        "mps": {
          "level": "required",
          "implemented_selectors": [
            "scan_region"
          ],
          "qualification": "encoded-resident-read(scan_region, detector_region); io.load keeps complete acquisitions and has no sparse selectors",
          "gates": [
            "tests/hardware/mps/test_resident_read.py",
            "tests/hardware/mps/test_mps_buffer_release.py"
          ]
        },
        "swift-metal": {
          "level": "not-implemented",
          "implemented_selectors": [],
          "implemented_subset": [
            "strict-half-open-rectangle-load-plan",
            "single-position-indexed-accessor"
          ],
          "limitations": [
            "no-bulk-rectangle-loader",
            "no-detector-region-selective-loader"
          ],
          "gates": [
            "native/swift/Sources/Metal4DSTEMKernels/Metal4DSTEMLoadPlan.swift",
            "native/swift/Sources/Native4DSTEMIO/Native4DSTEMIndexedSource.swift",
            "native/swift/Sources/Metal4DSTEMStreamingIO/Metal4DSTEMIndexedLoader.swift"
          ]
        },
        "webgpu": {
          "level": "partial-hardware",
          "implemented_selectors": [
            "scan_region"
          ],
          "limitations": [
            "bounds-round-and-clamp-instead-of-strict-rejection",
            "no-detector-region-selective-loader",
            "whole-intersecting-files-read-before-selective-decode"
          ],
          "gates": [
            "src/quantem/gpu/io/hdf5/webgpu/local-h5.ts",
            "tests/infrastructure/test_webgpu_sources.py"
          ]
        }
      }
    },
    {
      "id": "detector.integer-products",
      "parity": "Exact mean-DP integer accumulation and BF/ABF/ADF/DF sums using one mask definition.",
      "contract_profiles": ["quantem.gpu.resident-integer-products/v1"],
      "coverage": {
        "vulkan": {
          "level": "partial-hardware",
          "qualification": "Bounded native integer products and packed BF/DF/ADF/selected diffraction exist; shared-pin physical full-source parity remains pending.",
          "gates": [
            "native/vulkan/tests/packed_detector_tests.cpp",
            "native/vulkan/tests/packed_selected_diffraction_tests.cpp"
          ]
        },
        "cpu-reference": {
          "level": "reference",
          "gates": ["tests/parity/test_products_parity.py", "tests/parity/test_integer_detector_products.py", "tests/parity/test_resident_integer_contract.py"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/hardware/cuda/test_cuda_virtual_image.py", "tests/e2e/test_realdata_parity.py", "tests/hardware/cuda/test_resident_integer_contract.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/parity/test_products_parity.py", "tests/contracts/test_mps_chunk_dispatch.py", "tests/hardware/mps/test_resident_integer_contract.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/Metal4DSTEMKernelsTests/Metal4DSTEMKernelsTests.swift", "native/swift/Tests/Native4DSTEMIOTests/ResidentIntegerContractTests.swift"]
        },
        "webgpu": {
          "level": "required-hardware",
          "qualification": "No WebGPU adapter exercises the exact integer products since the compact-v1 adapter was removed. Dense maskedSum and selected-frame sums return float32 and do not satisfy the exact-output or duplicate-selected-frame-sum subcontracts.",
          "gates": ["tests/infrastructure/test_webgpu_sources.py", "docs/maintainer/backend-4dstem-load-checklist.md"]
        }
      }
    },
    {
      "id": "screening.prepared-products",
      "parity": "Same source identity, load plan, mean DP, BF/DF, CoM row/column, rotation, iDPC, cache signature, and provenance; ADF is not yet part of ScreeningResult.",
      "coverage": {
        "vulkan": {
          "level": "partial-hardware",
          "qualification": "Source-bound prepared detector maps and moments exist; the complete screening preparation/cache contract is not implemented.",
          "gates": [
            "native/vulkan/tests/packed_detector_session_tests.cpp",
            "native/vulkan/README.md"
          ]
        },
        "cpu-reference": {
          "level": "reference",
          "gates": ["tests/contracts/test_screening.py", "docs/api/core.md"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/contracts/test_screening.py", "tests/hardware/test_screening_products.py", "docs/maintainer/backend-4dstem-load-checklist.md"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/contracts/test_screening.py", "tests/hardware/test_screening_products.py", "docs/maintainer/backend-4dstem-load-checklist.md"]
        },
        "swift-metal": {
          "level": "not-implemented",
          "gates": ["docs/api/core.md", "docs/platforms/swift-metal.md"]
        },
        "webgpu": {
          "level": "not-implemented",
          "gates": ["docs/api/core.md", "docs/platforms/webgpu.md"]
        }
      }
    },
    {
      "id": "dpc.com-rotation-idpc",
      "parity": "Same row/column CoM convention, rotation, centering, FFT normalization, and frozen float metric.",
      "coverage": {
        "vulkan": {
          "level": "partial-hardware",
          "qualification": "Prepared exact moments and centered CoM exist; a complete shared rotation/iDPC workflow is not qualified.",
          "gates": [
            "native/vulkan/shaders/prepared_dpc_com.comp",
            "native/vulkan/shaders/prepared_dpc_center.comp",
            "native/vulkan/tests/packed_detector_session_tests.cpp"
          ]
        },
        "cpu-reference": {
          "level": "reference",
          "gates": ["tests/parity/test_dpc_rotation_agreement.py", "tests/parity/test_products_parity.py"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/parity/test_products_parity.py", "tests/e2e/test_real_product_env_match.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/parity/test_products_parity.py", "tests/e2e/test_real_product_env_match.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/Metal4DSTEMKernelsTests/Metal4DSTEMKernelsTests.swift"]
        },
        "webgpu": {
          "level": "required-hardware",
          "gates": ["tests/infrastructure/test_webgpu_sources.py", "docs/maintainer/backend-4dstem-load-checklist.md"]
        }
      }
    },
    {
      "id": "display.transform-histogram-color-fft",
      "parity": "Exact histogram/RGBA integer outputs and frozen float32 transform/FFT metrics.",
      "coverage": {
        "vulkan": {
          "level": "partial-hardware",
          "qualification": "Native radial FFT is limited to 512-square scans; other display operations and physical shared-pin qualification remain pending.",
          "gates": [
            "native/vulkan/tests/radial_fft_tests.cpp",
            "native/vulkan/README.md"
          ]
        },
        "cpu-reference": {
          "level": "reference",
          "gates": ["tests/parity/test_display_parity.py", "tests/parity/test_display_fft_parity.py"]
        },
        "cuda": {
          "level": "not-implemented",
          "qualification": "quantem.gpu has no CUDA display module; display transforms run in the CPU reference (quantem.gpu.display.cpu), WebGPU and native Swift/Metal.",
          "gates": ["tests/parity/test_display_parity.py", "tests/parity/test_display_shared_goldens.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/parity/test_display_shared_goldens.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/MetalDisplayKernelsTests/MetalDisplayKernelsTests.swift", "native/swift/Tests/MetalImageFFTTests/MetalImageFFTTests.swift"]
        },
        "webgpu": {
          "level": "required-hardware",
          "gates": ["tests/parity/test_display_fft_parity.py", "tests/parity/test_display_shared_goldens.py", "tests/e2e/test_webgpu_widget_sync.py"]
        }
      }
    },
    {
      "id": "ssb.object-phase-loss",
      "parity": "Same BF selection, aberrations, precision, objective, optimizer settings, and frozen phase/loss metric.",
      "coverage": {
        "vulkan": {
          "level": "not-implemented",
          "qualification": "No shared Vulkan SSB implementation.",
          "gates": [
            "native/vulkan/README.md"
          ]
        },
        "cpu-reference": {
          "level": "reference-fixture",
          "gates": ["tests/parity/fixtures/ssb_reference_512_mps.json", "tests/contracts/test_ssb_backend_contract.py"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/hardware/cuda/test_ssb_cuda_128.py", "tests/hardware/mps/test_ssb_mps_cuda_reference.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/hardware/mps/test_ssb_mps_cuda_reference.py", "tests/contracts/test_ssb_mps_close.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/MetalSSBKernelsTests/MetalSSBKernelsTests.swift", "docs/maintainer/native-metal-ssb-migration.md"]
        },
        "webgpu": {
          "level": "partial-hardware",
          "gates": ["tests/infrastructure/test_webgpu_sources.py", "tests/contracts/test_ssb_backend_contract.py", "docs/maintainer/ssb-performance.md"]
        }
      }
    },
    {
      "id": "ssb.calibration-200-nelder-mead",
      "parity": "Same full active BF selection, seed, 200 exact TPE candidates, candidate history, Nelder-Mead refinement, fitted aberrations, loss, precision, and final independent reconstruction.",
      "coverage": {
        "vulkan": {
          "level": "not-implemented",
          "qualification": "No shared Vulkan SSB optimizer implementation.",
          "gates": [
            "native/vulkan/README.md"
          ]
        },
        "cpu-reference": {
          "level": "reference-fixture",
          "gates": ["tests/parity/fixtures/ssb_reference_512_mps.json", "tests/infrastructure/test_ssb_structure.py"]
        },
        "cuda": {
          "level": "required",
          "gates": ["tests/contracts/test_ssb_batch_optuna.py", "tests/hardware/cuda/test_ssb_cuda_128.py", "tests/infrastructure/test_ssb_structure.py"]
        },
        "mps": {
          "level": "required",
          "gates": ["tests/hardware/mps/test_ssb_mps_cuda_reference.py", "tests/infrastructure/test_ssb_structure.py"]
        },
        "swift-metal": {
          "level": "required",
          "gates": ["native/swift/Tests/MetalSSBKernelsTests/MetalSSBKernelsTests.swift", "native/swift/Benchmarks/MetalSSBBenchmark/main.swift", "docs/maintainer/native-metal-ssb-migration.md"]
        },
        "webgpu": {
          "level": "not-implemented",
          "gates": ["tests/infrastructure/test_webgpu_sources.py", "docs/api/ssb.md"]
        }
      }
    }
  ]
}