aeat.application.storage.calc_sheets._parity_harness module

Per-modelo backend-spreadsheet parity harness.

For any (modelo, period, year) plus a synthetic operator-input set, this harness drives the same calculation through three independent paths and surfaces a per-casilla parity verdict. All three paths start from the same RegistrySnapshot so revision drift between them is impossible.

  1. AEAT live oracle (when a scenario file is provided) — the authoritative reference. Pre-captured outputs from AEAT’s own simulator (Renta WEB Open, equivalent surfaces) stored under corpus/parity_replays/…. This pins the local registry against AEAT’s truth.

  2. Local Decimal runtime — calculate_registry_snapshot against the same registry snapshot. This is the “backend”.

  3. Sheets — the engine-emitted workbook applied to the operator’s Drive, with operator inputs written into the Entradas tab and computed values read back from Cálculos. This is the “spreadsheet”.

The harness returns a ParityReport summarising:

  • local_vs_aeat — does the local registry match AEAT for the computed casillas the AEAT scenario captures?

  • sheets_vs_local — does the Sheets workbook match the local registry across every computed casilla?

  • sheets_vs_aeat — transitive proof that operator-facing Sheets output matches AEAT.

A clean run returns verdict=”all_match”. Any divergence surfaces per casilla so the operator can inspect which formula failed.

class CasillaParity(**data)[source]

Bases: BaseModel

Per-casilla parity verdict across three calculation surfaces.

Parameters:

  • casilla_id (CasillaId)

  • display_number (str)

  • label (str)

  • local (Decimal | None)

  • sheets (Decimal | None)

  • aeat (Decimal | None)

  • sheets_vs_local (bool | None)

  • local_vs_aeat (bool | None)

  • sheets_vs_aeat (bool | None)

casilla_id: CasillaId
display_number: str
label: str
local: Decimal | None
sheets: Decimal | None
aeat: Decimal | None
sheets_vs_local: bool | None
local_vs_aeat: bool | None
sheets_vs_aeat: bool | None
class ParityReport(**data)[source]

Bases: BaseModel

Aggregate parity verdict across every computed casilla.

verdict collapses the per-casilla flags into a single answer:

  • all_match — every pair compared matches; no surface lies.

  • divergence — at least one pair disagrees somewhere. The divergences field lists offending casillas with both values for inspection.

  • inconclusive — the AEAT oracle is absent so we can only compare backend↔Sheets; that pair matches.

Parameters:
modelo_id: str
revision_id: RevisionId
period: Period
filing_year: int
spreadsheet_id: str
spreadsheet_url: str
casillas: tuple[CasillaParity, ...]
aeat_oracle_present: bool
verdict: Literal['all_match', 'divergence', 'inconclusive']
divergences: tuple[CasillaParity, ...]
class OperatorInputScenario(**data)[source]

Bases: BaseModel

Caller-supplied scenario for the parity harness.

inputs_by_casilla_id maps canonical registry casilla.id values to input Decimals. expected_by_casilla_id mirrors that shape for AEAT-published expected outputs; an empty mapping is allowed and signals “no AEAT oracle available, fall back to backend↔Sheets only”.

Parameters:
inputs_by_casilla_id: Mapping[CasillaId, Decimal]
bindings: Mapping[BindingId, Decimal]
enum_bindings: Mapping[BindingId, str]
relation_values: Mapping[RelationId, Decimal]
expected_by_casilla_id: Mapping[CasillaId, Decimal]
scenario_label: str
verify_modelo_parity(snapshot, scenario, *, credentials, root_folder_id)[source]

Run the full three-way parity verification for one modelo+period.

Parameters:

  • snapshot (RegistrySnapshot) – The RegistrySnapshot whose calculation surface is verified.

  • scenario (OperatorInputScenario) – OperatorInputScenario supplying operator inputs and relation overrides for the run.

  • credentials (object) – Google API credentials used by the calc-sheets apply path to read/write the per-modelo spreadsheet.

  • root_folder_id (str) – Google Drive folder id under which the parity spreadsheet is created or updated.

Return type:

ParityReport

Returns a ParityReport.

Side effects:

  • Idempotently creates (or updates) a aeat-vault/calc-sheets/ {modelo}-{period}-{year}/AEAT … {modelo} {period} {year} spreadsheet under the operator’s Drive root.

  • Writes the scenario’s operator inputs into Entradas and relations into Tarifas.

  • Reads every formula cell back from Cálculos.

Does NOT mutate any local persistence beyond the registry snapshot’s process-local cache. The local Decimal runtime is invoked once and consulted only for comparison.