cadrumo.application.storage.calc_sheets.engine module

Engine driver that compiles a RegistrySnapshot into a SheetExportPlan.

The engine walks every casilla, binding, and parameter declared in the ModeloRevision embedded in the snapshot and maps each to a typed cell or range in the generated workbook plan.

The result is renderer-neutral: Google Sheets consumes the SheetExportPlan. The engine stamps registry identity, formula provenance, relation prefills, styling facets, and row-set layout; the ledger-evidence facet is supplied separately when the caller has bundled cadrumo.domain.modelos.ledger_filing_snapshot.LedgerFilingEvidence.

registry_sha(snapshot)

Stable identity hash of the calculation surface in this RegistrySnapshot.

The hash covers casilla ids, formula expressions, and parameter values. Two snapshots that produce the same calculation graph yield the same SHA; any registry edit yields a different SHA. The pull adapter uses this to refuse merges that would silently cross a registry boundary.

Return type:

str

Parameters:

snapshot (RegistrySnapshot)

build_export_plan(snapshot, *, operator_inputs=None, relation_values=None, relation_resolver=None, ledger_filing_evidence=None, casilla_ids_by_contributor_id=None)

Walk a registry snapshot and produce a complete SheetExportPlan.

The plan is a pure function of snapshot, operator_inputs, and the resolved relation values: workbook renderers write exactly what is in the plan, no more, no less. Two engine runs with the same inputs yield the same plan modulo the exported_at timestamp.

Parameters:

• snapshot (RegistrySnapshot) – The validated RegistrySnapshot to export.

• operator_inputs (OperatorInputs | None) – Optional pre-populated operator-input values for the Entradas tab. Casillas not supplied here render as blank cells the operator fills in by hand.

• relation_values (RelationValues | None) – Optional pre-resolved cross-revision aggregations mirrored into the Tarifas tab. Required when the revision’s formulas consume relation leaves (annual roll-ups like modelo 190 over modelo 111); when absent and relation_resolver is also unset, the engine emits blank cells the operator must populate before the Sheet’s formulas yield correct values.

• relation_resolver (Callable[[RegistrySnapshot], RelationValues] | None) – Optional callable that resolves the snapshot’s relations from a structured source (typically the local observation store via cadrumo.application.calculations.resolve_relations_from_local_store). When supplied AND relation_values is None, the engine invokes the resolver and stamps each resolved value’s provenance onto the workbook so the pull adapter can detect stale prefills. Explicit relation_values take precedence over the resolver.

• ledger_filing_evidence (LedgerFilingEvidence | None) – Optional bundled fact basis captured for the ledger-derived calculation revision this workbook explains. When supplied, it is projected into the plan’s evidence facet, which the workbook materializer renders into the Evidencia tab and the machine-readable evidence sidecar. When absent the facet stays empty and the tab carries only its headers.

• casilla_ids_by_contributor_id (Mapping[str, Iterable[TypeAliasType]] | None) – The attribution map from each contributing transaction id to the canonical casilla ids it supports. Required alongside ledger_filing_evidence whenever the evidence carries contributor rows: the projection refuses to infer modelo-specific tax attribution from row contents and raises for an unattributed contributor.

Return type:

SheetExportPlan

Returns:

A complete SheetExportPlan ready for the Google apply adapter.

collect_row_sets(revision)

Collect row-producer bindings into per-grouping SheetRowSet blocks.

Parameters:

revision (ModeloRevision) – The ModeloRevision whose bindings are scanned for row-producer declarations.

Return type:

tuple[SheetRowSet, ...]

Walks revision.bindings for invoice / counterpart bindings with aggregation = { op = "rows" }, groups them by selector.grouping (typically operator_clave or operator_clave_period), and lays them out as stacked header+data blocks in the Detalle tab. Each grouping occupies a contiguous column block; groupings stack vertically with a one-row gap between blocks. The pull adapter reads row data from first_data_row downwards.

Each element in the returned tuple is a SheetRowSet.