cadrumo.application.aggregation.ledger_filing_snapshot module

Capture and staleness for the modelo filing ledger snapshot.

Used by: application.modelo._ledger_drift_gate for the calculate-time staleness refusal, entrypoints.cli._ledger_read_cli for the stale-revision listing, and application.modelo.verification_actions for the Modelo 303 deductible-evidence verify gate.

That list names the callers as they stand and is not a guarantee that no other site reaches these functions; grep before relying on it. It previously named two modules that call nothing here at all, which is worse than naming none: a reader auditing the staleness refusal went looking in the wrong package, found nothing, and had every reason to conclude the enforcement did not exist.

The pure records live in domain.modelos.ledger_filing_snapshot. This application module holds the Transaction-aware halves: computing a contributor’s content fingerprint from the live TransactionCatalogue, building a LedgerFilingSnapshot for a CalculationRevision’s source_transaction_ids, and evaluating drift between a filed snapshot and the current ledger state.

The fingerprint covers exactly the transaction facts that can move a casilla – dates, amount magnitude, currency, direction, business classification and proportionality, the IVA base/rate/amount/category, the spending and IRPF categories, the M210 source-jurisdiction/classification facts, the EU member state, the FX conversion, and the lifecycle state. Cosmetic fields (description, counterparty, notes) are deliberately excluded so staleness fires on material change, not on a relabel.

This module uses LedgerFilingStalenessVerdict for drift evaluation.

CURRENT_FINGERPRINT_FIELD_SET_VERSION: Final

The version every NEW snapshot is sealed under.

row_fingerprint(transaction, *, field_set_version=2)[source]

Return the SHA-256 content fingerprint of one transaction’s tax facts.

Parameters:

  • transaction (Transaction) – The contributing row to fingerprint.

  • field_set_version (int) – Which field set to hash over. Defaults to the current one, which is what a NEW capture wants. A comparison against a stored snapshot must pass that snapshot’s own version instead, or it compares two different questions and calls the difference drift.

Return type:

str

compute_ledger_filing_snapshot(*, source_transaction_ids, catalogue, captured_at)[source]

Capture an immutable LedgerFilingSnapshot over a revision’s contributing rows.

Contributor ids absent from the catalogue are skipped (a snapshot records the rows that exist at capture time); an empty contributor set yields a valid empty snapshot, which is the uniform shape for non-ledger modelos.

Parameters:
Return type:

LedgerFilingSnapshot

compute_ledger_filing_evidence(*, source_transaction_ids, catalogue, snapshot_fingerprint, captured_at, legal_refs, source_refs, manual_entries=())[source]

Capture the bundled LedgerFilingEvidence fact basis behind one filing revision.

Projects every contributor in source_transaction_ids present in the catalogue into a typed LedgerEvidenceRow, binding the bundle to the revision’s snapshot_fingerprint. manual_entries carries the operator-entered fact basis (casilla inputs / binding overrides) that has no contributing ledger row. Contributor ids absent from the catalogue are skipped (mirroring compute_ledger_filing_snapshot()); the caller’s no-silent-omission guard cross-checks the evidence set against the fingerprint set.

Parameters:

  • source_transaction_ids (Iterable[str]) – Contributor identifiers.

  • catalogue (TransactionCatalogue) – The live TransactionCatalogue.

  • snapshot_fingerprint (str) – The fingerprinted snapshot identifier.

  • captured_at (datetime) – Captured timestamp.

  • legal_refs (Iterable[TypeAliasType]) – Registry legal references grounding this evidence bundle.

  • source_refs (Iterable[TypeAliasType]) – Official source references grounding this evidence bundle.

  • manual_entries (tuple[ManualFactBasisEntry, ...]) – The manual entries basis.

Return type:

LedgerFilingEvidence

assert_evidence_covers_snapshot(snapshot, evidence)[source]

Raise when bundled evidence omits or invents fingerprinted contributors.

Return type:

None

Parameters:
evaluate_ledger_filing_staleness(snapshot, catalogue)[source]

Compare a filed snapshot against the current ledger state, returning a LedgerFilingStalenessVerdict.

The comparator is selected HERE rather than inside diff_ledger_fingerprints(), which stays a pure equality diff over fingerprints it is handed. This is the layer that knows which question a stored snapshot was asking, so it is the layer that recomputes under the same one.

Parameters:
Return type:

LedgerFilingStalenessVerdict

stale_filed_revisions(*, revisions, catalogue)[source]

Return finalized snapshot-backed revisions whose ledger drifted.

Each item pairs a CalculationRevision with its LedgerFilingStalenessVerdict. Scans verified/filed revisions carrying a ledger_filing_snapshot and re-evaluates each against the live catalogue. A revision with no snapshot or a non-finalized state is skipped. Pure given its inputs.

Parameters:
Return type:

tuple[tuple[CalculationRevision, LedgerFilingStalenessVerdict], ...]