cadrumo.application.modelo.filing_chain_reconciliation module

Reconcile one AEAT register entry with the filing chain of its period.

The filing catalogue holds, per (bucket, modelo, year, period, member), a linear chain of declarations. A local filing stays PENDIENTE until AEAT is seen to hold it; AEAT register entries are the only proof of presentation. reconcile_aeat_register_entry() is the single decision point that turns one normalized register entry into a chain transition:

  • ALREADY_RECORDED – the register reference is already on the chain.

  • CONFIRMED – the in-force pending entry carries the content AEAT holds; it becomes CONFIRMADA and its pending-local observation layer becomes the official one.

  • CONTRADICTED – AEAT holds different content than the pending entry; the AEAT content is appended in force, amending the latest confirmed entry, and the pending entry becomes DISCREPANTE.

  • APPENDED – no pending entry exists; the AEAT content is appended in force.

  • UNVERIFIABLE – the entry cannot be compared or materialized; nothing is stamped and a notice says why.

Every transition and its bucket event commit in one unit of work with the filing catalogue.

A chain entry is a ModeloRecord, and the content compared against the register is the CalculationRevision that entry was filed from.

class FilingReconciliationOutcome(*values)[source]

Bases: StrEnum

Closed result of reconciling one AEAT register entry.

ALREADY_RECORDED
CONFIRMED
CONTRADICTED
APPENDED
UNVERIFIABLE
class FilingReconciliationNoticeCode(*values)[source]

Bases: StrEnum

Stable codes for conditions a reconciliation reports to the operator.

  • CONTENT_UNAVAILABLE – the entry carries neither casillas nor a comparable receipt, or carries no casillas to record AEAT content from.

  • RECEIPT_TOTALS_NOT_RECONCILED – the receipt total could not be compared; reason names why.

  • RECEIPT_TOTALS_MISMATCH – the receipt total disagrees with the pending entry, but without casillas the AEAT content cannot be recorded.

  • RECEIPT_TOTALS_ONLY – a confirmation rests on receipt totals rather than per-casilla equality.

  • DECLARATION_KIND_MISMATCH – AEAT states a different declaration kind than the pending entry.

  • DECLARATION_KIND_UNDETERMINED – AEAT presents after a confirmed declaration without stating the correction kind.

  • CORRECTION_WITHOUT_CONFIRMED_BASELINE – AEAT states a correction kind but the chain holds no confirmed declaration to link it to.

  • FILING_INSTANCE_EVIDENCE_UNAVAILABLE – the modelo’s content can only be recorded with its filing-instance evidence, which the entry lacks.

CONTENT_UNAVAILABLE
RECEIPT_TOTALS_NOT_RECONCILED
RECEIPT_TOTALS_MISMATCH
RECEIPT_TOTALS_ONLY
DECLARATION_KIND_MISMATCH
DECLARATION_KIND_UNDETERMINED
CORRECTION_WITHOUT_CONFIRMED_BASELINE
FILING_INSTANCE_EVIDENCE_UNAVAILABLE
class FilingReconciliationNotice(code, context=<factory>)[source]

Bases: object

One reported condition, keyed by a stable code with identifier-only context.

Parameters:
code: FilingReconciliationNoticeCode
context: Mapping[str, str]
class AeatRegisterEntry(bucket_id, modelo, filing_year, period, register, evidence_kind, tax_id, member_nif=None, declared_kind=None, justificante=None, casilla_values=None, source_lexicals=None, filing_instance_evidence=None, source_headers=(), target_work_unit_id=None)[source]

Bases: object

One normalized AEAT register entry for a filing coordinate.

casilla_values are the values AEAT holds for the presentation, when the source exposes them, and source_lexicals their printed spellings when the source kept them; justificante is the parsed receipt, when one is available. tax_id is the presenting taxpayer’s identifier. target_work_unit_id names the work unit AEAT content is recorded on when the caller has already chosen it.

Parameters:
bucket_id: str
modelo: str
filing_year: int
period: Period
register: AeatRegisterRef
evidence_kind: ExternalEvidenceKind
tax_id: str
member_nif: str | None
declared_kind: FilingDeclarationKind | None
justificante: Justificante | None
casilla_values: Mapping[TypeAliasType, Decimal] | None
source_lexicals: Mapping[TypeAliasType, str] | None
filing_instance_evidence: FilingInstanceEvidence | None
source_headers: tuple[ObservedHeaderFact, ...]
target_work_unit_id: str | None
class FilingReconciliationResult(outcome, bucket_id, modelo, filing_year, period, member_nif, filing_record_id, affected_filing_record_ids=(), differing_casilla_ids=(), evidence_basis=None, notices=())[source]

Bases: object

What one reconciliation decided, reported as identifiers only.

filing_record_id is the chain entry the outcome is about: the recorded, confirmed or appended entry, or the pending entry an unverifiable entry could not be compared with. affected_filing_record_ids lists every other chain entry whose state changed.

Parameters:
outcome: FilingReconciliationOutcome
bucket_id: str
modelo: str
filing_year: int
period: Period
member_nif: str | None
filing_record_id: str | None
affected_filing_record_ids: tuple[str, ...]
differing_casilla_ids: tuple[TypeAliasType, ...]
evidence_basis: Optional[Literal['casillas', 'receipt_totals']]
notices: tuple[FilingReconciliationNotice, ...]
class FilingReconciliationPorts(filing_repository, calculation_repository, work_lifecycle, observation_repository, justificante_repository)[source]

Bases: object

Persistence authorities one reconciliation reads and co-commits.

Parameters:
filing_repository: ModeloRecordCatalogueRepositoryProtocol
calculation_repository: CalculationRevisionCatalogueRepositoryProtocol
work_lifecycle: WorkLifecyclePorts
observation_repository: CalculationObservationRepositoryProtocol
justificante_repository: JustificanteRepositoryProtocol
reconcile_aeat_register_entry(entry, *, ports, operation, actor, clock)[source]

Apply one AEAT register entry to its period’s filing chain.

The receipt, when present, is stored before any chain entry cites it. A register reference already on the chain is a no-op and emits no event, so re-reading the same register is idempotent. Every other outcome emits one modelo.filing.reconciled event in the same unit of work as its chain transition.

Raises:

ExternalModeloImportError – The entry’s receipt evidence cannot be bound to the coordinate, or its casillas are not declared by the registry.

Return type:

FilingReconciliationResult

Parameters:
recorded_chain_entry(history, register)[source]

Return the chain entry that already records register, if any.

An entry records the register when its stored register reference names the same expediente or CSV, or when its evidence reference is that expediente or CSV. CSVs compare in their canonical form, so one receipt spelled two ways is still one receipt.

Parameters:
Return type:

ModeloRecord | None

Returns:

The ModeloRecord already recording register, or None when no entry does.