aeat.core.access_gate._authorization module

Multi-year-renta modelo authorization manifest, types, and derivation.

This module owns the type spine of the multi-year-renta authorization gate decided in the modelo-multiyear-renta ADR. The gate’s governing principle is default-deny-by-absence: a modelo’s calculation backend is treated as NON-FUNCTIONAL until its authorization is derived from the declarative manifest and verified by an enrolling end-to-end persona test that drove the real backend across at least two distinct renta (annual) periods.

Four collaborating pieces live here:

The manifest is the only writable authorization surface; everything else is a derivation of it. This is the same trust-but-verify shape codified for fixtures in fixture-provenance-declared-in-sidecar: a declaration in data, cross-checked against evidence the declaration cannot fabricate (here, the year-set a recorder observes a real test exercising).

MIN_DISTINCT_RENTA_YEARS: Final[int]

Minimum number of distinct renta (annual) years an enrolling test must exercise before a modelo may be authorized. The owner mandate is two distinct years: a single-period test cannot prove cross-year stability.

AUTHORIZATION_MANIFEST_DIRNAME: Final[str]

Directory holding the per-modelo authorization manifest fragments, resolved relative to the AEAT registry root (sibling of legal/ and modelos/). The manifest is directory-mode: each enrolled modelo owns one authorization.d/<modelo>.toml file, mirroring the registry’s own directory-mode layout. The loader merges every fragment. Per-modelo files mean concurrent enrollment across the campaign swarm writes disjoint files — zero cross-coder contention on a single manifest.

CANONICAL_MODELO_FLEET: Final[tuple[str, ...]]

The canonical fleet of modelo ids the gate enrolls. The owner mandate is non-negotiable: every modelo enrolls, none is out-of-scope. This is the honest denominator behind the meta-test’s authorized N/30 line. It is the union of every modelo the registry authority can load today plus the engine-build modelos whose registry directory carries no manifest.toml yet (151 Beckham, 714 Patrimonio, 721 crypto), which the ADR’s engine-build sub-decision keeps in scope. The meta-test pins this tuple against the live registry so a registry change that adds or drops a modelo surfaces loudly rather than silently moving the denominator. Retired identifiers carried by Modelo but with no registry definition (NON_REGISTRY_MODELOS, e.g. the suppressed M037 censo simplificada) are NOT enrolled and are excluded here.

FLEET_SIZE: Final[int]

The enrolled-fleet size used as the meta-test denominator. Derived from the canonical fleet rather than hard-coded so the two cannot disagree.

class AuthorizationState(*values)[source]

Bases: StrEnum

Closed two-state authorization verdict for a modelo’s backend.

UNAUTHORIZED is the default for every modelo not proven by an enrolling test; AUTHORIZED is granted only once a verified enrollment record exists in the manifest.

UNAUTHORIZED
AUTHORIZED
class EnrollmentEvidenceClass(*values)[source]

Bases: StrEnum

Closed set of enrollment-evidence shapes across the modelo fleet.

The owner mandate keeps every modelo in scope, but the shape of the cross-year evidence varies by modelo class (see the modelo-multiyear-renta ADR’s cross-modelo-class ruling):

  • CALCULATION — engine plus a cross-year carry (130, 100, 200, 202, 303, 131, …); the recorder captures two filing_year values computed through calculate_modelo_revision.

  • RECONCILIATION — periodic→annual summary reconciled across two years (390, 180, 190, 193).

  • DATA_FIDELITY — informativa year-over-year fidelity plus provenance, with no numeric oracle (347, 184, 721, 232, 349, …).

  • THRESHOLD_CONTINUITY — structural exemption / obligation logic across two years (720, 840, 036).

CALCULATION
RECONCILIATION
DATA_FIDELITY
THRESHOLD_CONTINUITY
class ModeloAuthorizationEntry(**data)[source]

Bases: BaseModel

One enrolling claim from the authorization manifest.

An entry is a claim the enrolling end-to-end test must verify, not a trusted grant. The >=2 distinct renta years invariant is enforced here at the pydantic boundary so a single-year (un-cross-year) claim cannot even construct — the minimum-two-years contract is unconstructable to violate, not merely asserted in a test.

Variables:

  • modelo – The modelo id the entry authorizes (e.g. "130").

  • renta_years – The distinct renta (annual) years the enrolling evidence must exercise. At least MIN_DISTINCT_RENTA_YEARS distinct years are required; duplicates are rejected.

  • evidence_class – The enrollment-evidence shape for this modelo.

  • enrolling_test – Dotted-or-path reference to the end-to-end persona test that enrolls this modelo. The meta-test confirms the referenced test exists and that the year-set its recorder observes equals renta_years.

Parameters:
modelo: str
renta_years: tuple[int, ...]
evidence_class: EnrollmentEvidenceClass
enrolling_test: str
property distinct_renta_years: tuple[int, ...]

Return the claim’s distinct renta years, sorted ascending.

class AuthorizationManifest(**data)[source]

Bases: BaseModel

Parsed, validated view of the directory-mode authorization manifest.

The manifest is the merge of every authorization.d/<modelo>.toml fragment. Default-deny is literal: an absent directory or one with no fragments yields an empty entries tuple and therefore authorizes zero modelos. A modelo id may appear at most once across fragments; a duplicate is an authoring error, not a silent last-wins overwrite.

Parameters:

entries (tuple[ModeloAuthorizationEntry, ...])

entries: tuple[ModeloAuthorizationEntry, ...]
entry_for(modelo)[source]

Return the enrolling ModeloAuthorizationEntry for modelo, or None if absent.

Return type:

ModeloAuthorizationEntry | None

Parameters:

modelo (str)

property authorized_modelos: frozenset[str]

Return the set of modelo ids the manifest authorizes.

class ModeloAuthorization(**data)[source]

Bases: BaseModel

Derived per-modelo authorization capability the runtime consults.

This record is computed at the registry boundary from the manifest cross-checked against the loadable registry — it is never authored independently per revision, so it cannot drift from the manifest. See domain.calculations.registry.ValidatedRegistryAuthority.authorization().

Variables:

  • modelo – The modelo id this capability describes.

  • state – AUTHORIZED iff the manifest enrolls the modelo; UNAUTHORIZED otherwise (the default for every modelo).

  • has_engine – Whether the modelo declares a calculation surface application-link in the loaded registry. Drives the CLI ADVISORY-vs-refusal split: an UNAUTHORIZED modelo that has an engine still computes (with an advisory banner); a modelo with no loadable engine is refused at work create by the established stub guard.

  • entry – The manifest entry backing an AUTHORIZED state, or None when UNAUTHORIZED.

Parameters:
modelo: str
state: AuthorizationState
has_engine: bool
entry: ModeloAuthorizationEntry | None
property is_authorized: bool

Return whether the modelo’s backend is authorized.

manifest_dir(registry_root)[source]

Return the authorization.d directory for an AEAT registry root.

The directory is a sibling of legal/ and modelos/ under the registry root, so callers that hold the registry root (the authority, the fingerprint walker) resolve it the same way.

Return type:

Path

Parameters:

registry_root (Path)

load_authorization_manifest(registry_root)[source]

Load and validate the directory-mode authorization manifest.

The manifest is directory-mode: every enrolled modelo owns one authorization.d/<modelo>.toml fragment under registry_root. The loader merges every fragment in sorted order into one AuthorizationManifest.

Default-deny-by-absence: when the authorization.d directory is missing or holds no *.toml fragments, the result is an empty manifest (zero authorized modelos), never an error. A present-but- malformed fragment raises AuthorizationManifestError so a broken authorization surface fails loudly rather than silently authorizing nothing or everything.

Parameters:

registry_root (Path) – The AEAT registry root directory.

Return type:

AuthorizationManifest

Returns:

The validated AuthorizationManifest.

Raises:

AuthorizationManifestError – When a fragment cannot be parsed or violates an entry/manifest invariant (single-year claim, duplicate modelo across fragments, stem/id mismatch, unknown field).

derive_modelo_authorization(modelo, *, manifest, has_engine)[source]

Derive the per-modelo capability from the manifest and engine presence.

This is the canonical derivation the registry authority exposes. The capability is a pure function of (a) the manifest entry, if any, and (b) whether the modelo declares a calculation surface in the loaded registry — never an independently authored flag.

Parameters:

  • modelo (str) – The modelo id to derive a capability for.

  • manifest (AuthorizationManifest) – The loaded authorization manifest (default-deny source).

  • has_engine (bool) – Whether the modelo declares a calculation surface application-link in the registry.

Return type:

ModeloAuthorization

Returns:

The derived ModeloAuthorization.