cadrumo.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 the caller supplies expected values) — the authoritative reference. The harness holds no capture corpus of its own and reads no bundled scenario file: the expected figures are passed in by the caller, whatever their provenance. This pins the local registry against AEAT’s truth only to the extent the caller’s figures came from AEAT.

  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 CalcSheetsParityApplyResult(spreadsheet_id, spreadsheet_url)[source]

Bases: object

Application-facing outcome of materialising one parity workbook.

The parity algorithm only needs the stable workbook identifiers. Keeping this projection here prevents the Google adapter’s result model and its write-count fields from becoming part of the application contract.

Parameters:

  • spreadsheet_id (str)

  • spreadsheet_url (str)

spreadsheet_id: str
spreadsheet_url: str
class CalcSheetsParityApplyPort(*args, **kwargs)[source]

Bases: Protocol

Required outbound capability for the parity harness’s workbook write.

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:

data (Any)

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:

data (Any)

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, apply_port)[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 (Credentials) – 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.

  • apply_port (CalcSheetsParityApplyPort) – Composed application capability that materialises the workbook and returns its normalized identity.

Return type:

ParityReport

Returns a ParityReport.

Side effects:

  • Idempotently creates (or updates) a cadrumo-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.