aeat.domain.modelos._ledger_filing_snapshot module

Immutable ledger snapshot backing a modelo filing revision.

A modelo calculation revision that reaches a verified or filed state carries a content-addressed snapshot of the ledger state it was computed from: a fingerprint over each contributing transaction’s tax-relevant facts plus an aggregate snapshot fingerprint. This is the audit + staleness layer that sits on top of the write-time blocking guard (see the modelo-filing-ledger-snapshot ADR).

This module holds the pure records and the pure fingerprint diff. The Transaction-aware capture (which reads the live catalogue to produce row fingerprints) lives in the application aggregation layer so the domain stays free of the ledger-read dependency, per the hexagonal boundary.

class LedgerRowFingerprint(**data)[source]

Bases: BaseModel

Content fingerprint of one contributing ledger transaction.

Variables:

  • transaction_id – The contributor’s stable ledger transaction id.

  • fingerprint – SHA-256 hex over the transaction’s tax-relevant facts (the fields that can move a casilla), computed by the application capture helper.

Parameters:

  • transaction_id (str)

  • fingerprint (str)

transaction_id: str
fingerprint: str
class LedgerFilingSnapshot(**data)[source]

Bases: BaseModel

Immutable snapshot of the ledger state behind one filing revision.

Empty rows is valid and expected for a non-ledger modelo (no contributing transactions); its snapshot_fingerprint is the digest of the empty contributor set, so every modelo carries a uniform, comparable snapshot regardless of whether it is ledger-fed.

Variables:

  • rows – Per-contributor fingerprints, sorted by transaction id.

  • snapshot_fingerprint – SHA-256 hex over the sorted (id, fingerprint) pairs; the content address of the whole ledger state.

  • captured_at – UTC timestamp the snapshot was taken.

Parameters:
rows: tuple[LedgerRowFingerprint, ...]
snapshot_fingerprint: str
captured_at: datetime
class LedgerFilingStalenessVerdict(**data)[source]

Bases: BaseModel

Drift between a filed snapshot and the current ledger state.

Variables:

  • is_stale – True when any contributor changed or was removed.

  • changed – Contributor ids whose live fingerprint differs from the snapshot.

  • removed – Contributor ids absent from the live catalogue.

  • unchanged – Contributor ids whose live fingerprint matches the snapshot.

Parameters:
is_stale: bool
changed: tuple[str, ...]
removed: tuple[str, ...]
unchanged: tuple[str, ...]
snapshot_fingerprint(rows)[source]

Return the aggregate content address over sorted contributor fingerprints.

Return type:

str

Parameters:

rows (tuple[LedgerRowFingerprint, ...])

diff_ledger_fingerprints(snapshot, current_fingerprints)[source]

Compare a filed snapshot against live per-contributor fingerprints.

current_fingerprints maps each contributor’s transaction id to its freshly-recomputed fingerprint (a contributor missing from the mapping is treated as removed). Pure: no ledger read happens here.

Return type:

LedgerFilingStalenessVerdict

Returns:

The computed LedgerFilingStalenessVerdict detail.

Parameters:
class LedgerEvidenceRow(**data)[source]

Bases: BaseModel

Typed evidence projection of one contributing ledger transaction.

Where LedgerRowFingerprint records only the content hash (for staleness detection), this record carries the actual tax-relevant facts that moved a casilla, plus its regulatory grounding and evidence references, so the fact basis can be reconstituted from the revision and rendered into a filing artefact. fingerprint binds this row to the matching LedgerRowFingerprint, so an evidence/fingerprint mismatch is detectable.

Enum-valued facts are stored as their canonical string value (and dates as ISO-8601 strings) so the record roundtrips cleanly through the strict persistence boundary and the domain stays free of the ledger-read dependency; the application capture layer projects the typed Transaction into this primitive shape.

Parameters:

  • transaction_id (str)

  • fingerprint (str)

  • booked_date (str)

  • value_date (str | None)

  • amount (Decimal)

  • currency (str)

  • direction (str)

  • business_classification (str)

  • business_pct (Decimal | None)

  • taxable_base (Decimal | None)

  • iva_rate (Decimal | None)

  • iva_amount (Decimal | None)

  • iva_category (str | None)

  • category_id (str | None)

  • irpf_category (str | None)

  • counterparty_eu_member_state (str | None)

  • fx_rate (Decimal | None)

  • value_in_eur (Decimal | None)

  • lifecycle_state (str)

  • counterparty (str | None)

  • description (str)

  • purchase_invoice_evidence_id (str | None)

  • attachment_ids (tuple[str, ...])

  • document_link_ids (tuple[str, ...])

  • legal_refs (tuple[LegalRefId, ...])

  • source_refs (tuple[SourceRefId, ...])

transaction_id: str
fingerprint: str
booked_date: str
value_date: str | None
amount: Decimal
currency: str
direction: str
business_classification: str
business_pct: Decimal | None
taxable_base: Decimal | None
iva_rate: Decimal | None
iva_amount: Decimal | None
iva_category: str | None
category_id: str | None
irpf_category: str | None
counterparty_eu_member_state: str | None
fx_rate: Decimal | None
value_in_eur: Decimal | None
lifecycle_state: str
counterparty: str | None
description: str
purchase_invoice_evidence_id: str | None
attachment_ids: tuple[str, ...]
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class ManualFactBasisEntry(**data)[source]

Bases: BaseModel

One operator-entered fact behind a revision that is not ledger-derived.

Manual casilla inputs and binding overrides have no contributing ledger row; they are nonetheless part of the fact basis a filing artefact must explain. casilla_id is the canonical registry casilla id and value is the rendered canonical string of the operator-entered value.

Parameters:

  • casilla_id (CasillaId)

  • value (str)

  • kind (str)

  • note (str)

  • legal_refs (tuple[LegalRefId, ...])

  • source_refs (tuple[SourceRefId, ...])

casilla_id: CasillaId
value: str
kind: str
note: str
legal_refs: tuple[LegalRefId, ...]
source_refs: tuple[SourceRefId, ...]
class LedgerFilingEvidence(**data)[source]

Bases: BaseModel

The bundled fact basis behind one ledger-derived filing revision.

Pegged to the revision’s LedgerFilingSnapshot via snapshot_fingerprint so evidence and the staleness fingerprint share one content address. Empty rows + empty manual_entries is valid for a non-ledger, non-manual revision; a ledger-derived revision MUST carry one LedgerEvidenceRow per fingerprint contributor (the application capture asserts the sets match, so no contributor is silently dropped from the evidence).

Parameters:
snapshot_fingerprint: str
rows: tuple[LedgerEvidenceRow, ...]
manual_entries: tuple[ManualFactBasisEntry, ...]
captured_at: datetime