cadrumo.domain.calculations.registry.validate_cross_domain_snapshot module

Cross-domain snapshot referential-integrity hooks.

Defines the CrossDomainSnapshotCheck protocol and the registry used to run peer-domain checks against a RegistrySnapshot at snapshot-build time without importing peer domains directly.

class CrossDomainSnapshotCheck(*args, **kwargs)

Bases: Protocol

Snapshot-time referential-integrity check owned by a peer domain.

A peer domain (for example cadrumo.domain.renta) may need to assert that the casilla ids it routes to are real casillas on a registry snapshot. The registry must not import the peer domain directly – that reverses the hexagonal dependency direction. Instead the peer domain registers a CrossDomainSnapshotCheck via register_cross_domain_snapshot_check(); the registry calls every registered check at snapshot-build time without naming the peer.

A check receives the modelo id, the snapshot’s casilla id set, the revision’s OWN renta first-slice ledger-aggregation binding target casillas (a strict subset of the universal routing table’s codomain – older revisions may declare no such bindings at all, so their required set is legitimately empty), and the revision’s declared binding ids. It returns a list of failure strings (empty when consistent).

Both derived inputs exist for the same reason: a peer-domain routing assertion should be conditional on the revision actually declaring the thing that creates the requirement. A check that asserts unconditionally over a modelo fires on revisions it has no claim over – including the synthetic ones built to exercise unrelated properties – and a gate that reddens where it has no claim trains its readers to work around it. revision_binding_ids carries a default so a registered check that predates it stays callable, which keeps the widening additive.

REQUIRED_CROSS_DOMAIN_CHECK_IDENTITIES: Mapping[str, str]

The cross-domain check each modelo requires, keyed by the module that owns it. A modelo absent from this mapping declares no required peer-domain gate.

This is the ONLY place a required check module is named. The snapshot builder installs exactly these modules, so the set it imports and the set the guard demands cannot drift apart, and moving a check module is one edit that fails loudly at import rather than two edits of which one can be forgotten silently.

Keyed by Modelo member and typed on str because the lookup axis is the modelo id a snapshot carries: a StrEnum member hashes and compares as its value, so declaring the member keeps the key greppable while the annotation states what callers may pass.

register_cross_domain_snapshot_check(check)

Register a peer-domain snapshot referential-integrity check under its owner.

The identity a check is registered under is the canonical defining module that owns it, recorded here at registration rather than re-derived by a reader. Owning module, not function name: a check renamed in place is the same gate and must keep the same identity, while the module path is the one fact the registry already declares in REQUIRED_CROSS_DOMAIN_CHECK_IDENTITIES.

Idempotent: registering the same callable twice is a no-op so a peer-domain module re-imported in a fresh interpreter (or under test reload) does not stack duplicate checks.

Return type:

None

Parameters:

check (CrossDomainSnapshotCheck)

registered_cross_domain_check_identities()

Return the owning module of every currently registered check.

Return type:

frozenset[str]

missing_required_cross_domain_check(modelo_id, registered_identities)

Return the required check identity modelo_id is missing, or None.

Asking whether ANY check is registered is not the question the guard needs to answer. A process that registered some other peer-domain check leaves the registration list non-empty while the gate this modelo actually requires is absent, and a guard reading only emptiness grants passage to precisely that state.

Return type:

str | None

Parameters:

• modelo_id (str)

• registered_identities (Collection[str])

check_cross_domain_snapshot_routing(checker, snapshot)

Run every registered peer-domain referential-integrity check.

The registry depends on the abstract CrossDomainSnapshotCheck Protocol only. Concrete checks (such as the renta first-slice routing gate) are injected by their owning domain at import time via register_cross_domain_snapshot_check().

Parameters:

• checker (_SnapshotReferenceChecker) – Snapshot reference checker that accumulates per-prefix failures and exposes the casilla id set against which registered cross-domain checks evaluate routing references.

• snapshot (RegistrySnapshot) – The RegistrySnapshot to run peer-domain checks against.

Return type:

None

A modelo named in REQUIRED_CROSS_DOMAIN_CHECK_IDENTITIES has a known-required gate – Modelo 100’s is the renta first-slice routing referential-integrity check. Each check registers itself as the import side effect of the module that owns it, and the snapshot builder installs those modules before validation. Rather than skip a known-required gate, fail loudly so a missing registration surfaces at snapshot build instead of as a later runtime KeyError.

The requirement is judged by NAME, not by population. A process that registered some other peer-domain check – the M130 retenciones gate, say, which any importer of application.aggregation brings in – leaves the registration list non-empty while the first-slice gate is absent. Reading only emptiness grants passage to exactly that state, which is the silent half of the failure this guard exists to make loud.