qat.experimental.system_data.materialisers.purr.adapter module

Boundary adapter for PuRR source payloads.

The adapter sits between raw source payload loading and ingress DTO validation. It is responsible for light structural checks, format detection, source decoding, and projection into an acyclic ingress-friendly shape.

Adapter responsibilities

This module normalises source payloads into a stable shape expected by ingress DTO validation. It intentionally keeps this logic compiler-local so ingress DTO models can remain strict while legacy source quirks are handled in one place.

Current normalisation includes:

  1. Top-level key presence checks for required entity collections.

  2. Defaults for optional top-level collections.

  3. Legacy default_acquire_mode coercion into str | None.

  4. Projection of decoded source graphs into an acyclic structure suitable for

    deterministic DTO validation.

adapt_purr_payload(payload, *, extra_reduce_target_types=None, extra_reduce_target_suffixes=None)

Adapt raw PuRR payload into decoder-normalised plain data.

Parameters:

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

  • extra_reduce_target_types (Optional[set[str]]) – Optional extra fully-qualified py/reduce target types allowed by the source decoder at runtime.

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

Return type:

dict[str, Any]

Returns:

Acyclic, boundary-normalised payload ready for ingress DTO validation. The returned mapping is the source-payload representation consumed by the ingress DTO. Compiler-owned enrichment happens after this stage.