aeat.application.aggregation._percepciones_observations_repository module¶

Encrypted persistence for per-perceptor-clave percepciones records (Modelo 190).

The DEDICATED store the percepciones-count resolver reads to count percepciones DISTINCTLY. Modelo 190 casilla decl.total-percepciones (“Número total de percepciones … Número de registros de tipo 2”, AEAT Diseño de Registros) is the count of DISTINCT (perceptor NIF, clave, subclave) type-2 records on the annual declaration — a perceptor paid under two claves files two percepciones — NOT the distinct-NIF perceptor count (that is RET-1’s perceptor_count for Modelo 180/193) and NOT the sum of the quarterly Modelo 111 perceptor counts. The validated distinct-count primitive (the percepcion_count withholding fact) already exists; what it lacked was a persisted, calc-mesh-readable per-perceptor source so the calculate path could compute the distinct count instead of falling back to the wrong quarterly sum. This module is that source: it persists each clave-bearing WithholdingObservation keyed by (modelo, filing_year, period) plus the per-perceptor-clave identity, so the pull and calculate surfaces read ONE store (one-aggregation-path-pull-equals-calculate).

Sensitivity is SensitivityClass FINANCIAL — perceptor NIFs are identity-bearing financial data, stored encrypted at rest through a SecureBoundRepository that writes Envelope records. The plaintext NIF lives only inside the encrypted payload; the object key carries the sha256 of the NIF (the iva-wallet-decision key convention), never the cleartext value (sensitive-financial-data-secure-storage-only). The namespace, schema version, object-key grammar, and custody disposition are declared by adapters.persistence.storage.WITHHOLDING_OBSERVATIONS_NAMESPACE.

ADR 2026-06-25-modelo-190-percepciones-count-adr. Producers (the pull/aggregate entrypoints) write here through one shared helper; the P03 calc-mesh resolver reads here and calls the distinct-count primitive. This is the percepciones counterpart of _retencion_observations_repository (the perceptores store); the two stores are intentionally distinct — different distinct keys (NIF+clave+subclave vs NIF), different models, different modelos.

This module was renamed from _withholding_observations_repository.py per the import-centralization ADR ruling 4: the “withholding” stem collided with the project’s Spanish-stem naming convention (retencion already names the sibling Modelo 180/193 store), so this module — and the repository symbols it owns locally — follow the percepciones stem instead. The WithholdingObservation domain type it wraps is an unrelated, widely shared registry taxonomy type and is out of scope for this rename.

percepcion_observation_key(modelo, filing_year, period, perceptor_tax_id, clave, subclave)[source]¶

Opaque per-perceptor-clave object key — the NIF is hashed, never cleartext.

Secure-object payloads are encrypted, but object keys are storage metadata, so the perceptor NIF is sha256-hashed (the iva-wallet-decision key convention). Distinct (perceptor NIF, clave, subclave) triples persist as distinct rows so a perceptor paid under more than one clave is preserved as the distinct percepciones the Diseño counts (registros de tipo 2).

Return type:

str

Parameters:

modelo (str)
filing_year (int)
period (Period)
perceptor_tax_id (str)
clave (str)
subclave (str)

class PercepcionObservationRepository(*, bucket_id=None, objects=None, settings=None)[source]¶

Bases: SecureBoundRepository[_PercepcionObservationEnvelopePayload]

Encrypted repository for per-perceptor-clave WithholdingObservation payloads.

The SecureBoundRepository base wraps each payload in a Envelope under adapters.persistence.storage.WITHHOLDING_OBSERVATIONS_NAMESPACE and enforces the namespace’s FINANCIAL SensitivityClass.