aeat.domain.modelos._participation_index module

Transaction-to-revision participation index for audit cross-reference.

The ledger persists only the forward link: a CalculationRevision names its source_transaction_ids. The inverse question an auditor asks of a single ledger transaction — which finalized modelo revisions, filings, and justificantes consumed it — has no persisted, surfaced answer; the only inverse traversal is the transient _blocking_modelo_references write-guard scan.

This module introduces the TransactionRevisionParticipationIndex, a derived, rebuildable secure-object recording, per ledger transaction id, the set of finalized-revision participations: the calculation_revision_id, work_unit_id, modelo, filing_year, period and revision_state, plus, where the revision is filed, the filing_record_id and the justificante reference. The index is co-written atomically inside the same save_with_secure_object_writes unit of work that persists the revision (per the composition-service single-writer discipline); it is a read-side cache, never a second source of truth, and is fully rebuildable from the revision catalogue.

The index is keyed by transaction_id and persisted one secure Envelope per transaction, so a revision over N contributing transactions co-emits N index upserts. Each upsert merges its new participation into that transaction’s entry without disturbing the participations already recorded for it.

See derive_participation_index_id() for the object-key grammar, and the TransactionParticipationIndexRepository for the encrypted persistence boundary mirroring the CalculationRevision catalogue repository at SensitivityClass FINANCIAL.

derive_participation_index_id(transaction_id)[source]

Return the secure-object key for one transaction’s participation entry.

The index is content-addressed by the ledger transaction id: each TransactionId owns exactly one TransactionRevisionParticipationIndex secure object, so the object key IS the (trimmed) transaction id. This keeps the inverse lookup an O(1) keyed read from a transaction id alone.

Return type:

str

Parameters:

transaction_id (str)

class TransactionRevisionParticipation(**data)[source]

Bases: BaseModel

One finalized-revision participation recorded against a ledger transaction.

Records that a single ledger transaction contributed to one finalized CalculationRevision. filing_record_id and justificante_reference are populated only when the revision reached a filed state; a freshly verified-complete (not yet filed) participation leaves both None.

Parameters:

  • calculation_revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • work_unit_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • modelo (ModeloCode)

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])])

  • period (Period)

  • revision_state (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)])

  • filing_record_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)] | None)

  • justificante_reference (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

calculation_revision_id: CalculationRevisionId
work_unit_id: WorkUnitId
modelo: ModeloCode
filing_year: Annotated[int, Field(ge=2000, le=2099)]
period: Period
revision_state: _RevisionState
filing_record_id: FilingRecordId | None
justificante_reference: _JustificanteReference | None
class TransactionRevisionParticipationIndex(**data)[source]

Bases: BaseModel

All finalized-revision participations recorded for one ledger transaction.

Keyed-by-transaction secure object: each instance carries the full, ordered participation set for a single TransactionId. The model_validator rejects duplicate calculation_revision_id entries so a re-emission cannot accumulate a second row for the same revision; an upsert (upsert_transaction_participation()) replaces in place instead.

Parameters:

  • transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • participations (tuple[TransactionRevisionParticipation, ...])

transaction_id: TransactionId
participations: tuple[TransactionRevisionParticipation, ...]
upsert_transaction_participation(index, participation)[source]

Return a new TransactionRevisionParticipationIndex with participation merged.

The merge is keyed by calculation_revision_id: an existing entry for the same revision is REPLACED in place (so a verified-then-filed transition overwrites the verified row with the filed one, gaining filing_record_id), and a new revision is APPENDED. Participations for other revisions are never disturbed, and entry order is otherwise stable so the audit trail reads chronologically.

Return type:

TransactionRevisionParticipationIndex

Parameters:
exception TransactionParticipationIndexPersistenceError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloError

Raised when the participation index cannot be persisted or loaded.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]