qat.experimental.system_data.materialisers.purr.materialise module

PuRR-to-canonical materialisation orchestration for the experimental boundary.

This module keeps the public materialisation entrypoint and coordinates adaptation, ingress validation, and canonical assembly via domain-specific builders.

Stage architecture

PuRR materialisation is intentionally staged so source-boundary concerns remain separate from compiler-owned enrichment and canonical assembly:

  1. Source version compatibility check.

  2. Source payload adaptation into boundary-normalised plain data.

  3. Source ingress DTO validation and graph consistency validation.

  4. Compiler-owned enrichment required for canonical assembly.

  5. Canonical system data construction from validated/enriched ingress DTO.

This separation allows validation responsibility to move upstream over time without changing canonical assembly responsibilities.

materialise_purr_v0_1_0(*, source_payload, source_version, target_data=None, supported_acquire_modes=None, native_waveform_shapes=None, decoder_extra_reduce_target_types=None, decoder_extra_reduce_target_suffixes=None)

Materialise canonical system data from a PuRR v0.1.0 source payload.

This runs the PuRR boundary flow:

  1. Source-version compatibility check.

  2. Payload adaptation/decoding into boundary-normalised plain data.

  3. Ingress DTO validation.

  4. Graph-level consistency validation.

  5. Canonical materialisation.

Parameters:

  • source_payload (dict[str, Any]) – Raw parsed PuRR payload.

  • source_version (str) – Source contract version.

  • target_data (Optional[TargetData]) – Compiler target data required by downstream mappings.

  • supported_acquire_modes (Optional[list[str]]) – Fallback acquire modes applied when the source payload does not provide explicit supported modes.

  • native_waveform_shapes (Optional[list[str]]) – Compiler-owned waveform shape defaults injected per physical channel when absent from the source payload.

  • decoder_extra_reduce_target_types (Optional[list[str]]) – Optional extra fully-qualified py/reduce targets allowed by the source decoder at runtime.

  • decoder_extra_reduce_target_suffixes (Optional[list[str]]) – Optional extra terminal type-name suffixes allowed by the source decoder at runtime.

Return type:

CanonicalSystemData

Returns:

Materialised canonical system data.

Raises:

This function is version-specific by design. New PuRR source versions should be implemented as new entrypoints and registered in the boundary registry.