aeat.domain.portals._drift module

Typed portal-drift record and read-only divergence detection.

A PortalDriftEvent captures a single detected divergence between a registered portal assumption (the canonical URL / host declared on the frozen PortalMetadata entry) and an observed live state. Detection is advisory and read-only: evaluate_portal_drift() compares an already-observed value the caller supplies against the registry entry and, when they diverge, materialises the typed record. This module never contacts AEAT — the observation itself is produced elsewhere, under the live-read access gate, and handed in as a plain value. The catalogue package as a whole performs no live AEAT access (see the package docstring); this module only describes a divergence someone else observed.

The record carries the entry’s UrlStability tier so downstream health reporting (the portal-registry:health doctor row in application.preflight) can grade a drift by how stable the URL was promised to be: a drift on a BOE-referenced STABLE_PROTOCOL_GRADE URL is a real integrity concern, whereas a drift on a VOLATILE_APP_PATH shell URL is an expected rotation.

class PortalDriftField(*values)[source]

Bases: StrEnum

The registered portal assumption a PortalDriftEvent diverges on.

URL — the observed canonical URL differs from the registered URL (same host, different path or query). SUBDOMAIN — the observed URL is hosted on a different AEAT-family host than the registered PortalHost. AVAILABILITY — the portal did not answer as reachable when the registered assumption is that it is a live surface.

URL
SUBDOMAIN
AVAILABILITY
class PortalDriftEvent(**data)[source]

Bases: BaseModel

One detected divergence between a registered portal assumption and live state.

A strict, frozen record. It asserts an actual divergence: expected (the registered assumption) and observed (the live state) must differ, so a PortalDriftEvent can only exist for a genuine drift.

Variables:

  • portal – The Portal whose assumption drifted.

  • field – The PortalDriftField that diverged.

  • expected – The registered assumption value (the registry’s truth).

  • observed – The observed live-state value the caller supplied.

  • url_stability – The registered UrlStability tier of the entry, carried so health reporting can grade the drift.

  • detected_at – UTC-aware instant the divergence was observed.

  • note – Optional free-text operator note describing the observation.

Parameters:
portal: Portal
field: PortalDriftField
expected: str
observed: str
url_stability: UrlStability
detected_at: AwareDatetime
note: str
evaluate_portal_drift(metadata, *, observed_url, detected_at=None)[source]

Compare a registered portal entry against an observed live URL.

Read-only and pure: performs no network access. The observed_url is a value the caller obtained under the live-read access gate (or from a recorded observation) and passes in for comparison against the registry truth. When the observed URL matches the registered URL exactly, there is no drift and None is returned. Otherwise a typed PortalDriftEvent is materialised: a differing host yields a PortalDriftField.SUBDOMAIN record; any other difference yields a PortalDriftField.URL record.

Parameters:
Return type:

PortalDriftEvent | None

Returns:

A PortalDriftEvent when the observed URL diverges from the registered URL, or None when they match.