aeat.application.modelo._calculation_actions module

Calculation revision actions for modelo work units.

The calculate paths resolve a law-determined RegistrySnapshot from each WorkUnit, merge manual inputs with profile, borrador, IVA-wallet, and bucket aggregation channels, and execute calculate_registry_snapshot() against the asserted ModeloRevision.

Persistence is centralized through CalculationRevision, CalculationRevisionCatalogueRepository, and BucketEventHistoryRepository, so the work-unit pointer and modelo.calculation.created event advance with the stored draft revision.

calculate_modelo_revision() is the lower-level calculation service: callers provide already-resolved manual, binding, enum-binding, relation, borrador, and IVA-wallet inputs. calculate_modelo_revision_from_bucket_aggregation() first runs the application source mesh over bucket-local ledgers, invoices, previous filings, relation prefill, retenciones, withholding, and detail rows, then feeds the resolved backend channels into the same persistence path. Source-owned bindings and their bound casillas are guarded before the engine runs so a persisted revision cannot claim bucket-source grounding while carrying a caller substitute for the same value.

See also

aggregation:

Public source-mesh contracts and diagnostics consumed by the bucket aggregation path.

resolve_calculation_binding_channels():

Merges caller, backend, borrador, and date binding channels for the registry engine.

build_typed_observations():

Projects engine output into provenance-bearing casilla observations.

persist_calculation_revision():

Stores the content-addressed BORRADOR revision and emits the bucket event.

verify_modelo_revision():

Lifecycle gate that promotes a calculated revision after verification.

class BucketAggregationCalculationResult(revision, source_diagnostics=())[source]

Bases: object

Calculation revision plus the non-blocking source diagnostics raised while resolving it.

revision is the persisted CalculationRevision. source_diagnostics carries the CalculationSourceDiagnostic rows the source mesh emitted during resolution, notably the unconsumed-declarable-IVA advisories (a declarable IVA observation no ledger_iva_aggregation binding selects). They are NON-blocking: the revision was computed and persisted regardless. Surfacing them keeps an unrouted declarable observation from being silently under-declared (no-silent-under-declaration).

Parameters:
revision: CalculationRevision
source_diagnostics: tuple[CalculationSourceDiagnostic, ...]
calculate_modelo_revision(work_unit_id, *, actor='system', casilla_inputs, text_casilla_inputs=None, binding_values=None, enum_binding_values=None, backend_binding_values=None, row_binding_values=None, backend_casilla_inputs=None, iva_compensation_decision=None, iva_compensation_decision_repository=None, ledger_preflight_transaction_repository=None, borrador_snapshot_id=None, relation_values=None, unresolved_relation_ids=(), unresolved_binding_ids=(), source_transaction_ids=(), filing_period_date=None, work_unit_repository=None, calculation_repository=None, bucket_event_repository=None, borrador_snapshot_repository=None, detail_rows=(), source_provenance=(), clock=None)[source]

Run the registry formula engine, persist a draft revision, and return a CalculationRevision.

ledger_preflight_transaction_repository is a TransactionCatalogueRepository used for the ledger preflight check before calculation.

Pipeline:

  1. Load the work unit; refuse on DISCARDED.

  2. Resolve the RegistrySnapshot for the work unit’s (modelo, filing_year, period) and assert its ModeloRevision. Failure to resolve raises CalculationRegistryUnavailableError — the calculate path runs the engine, so a missing snapshot is a hard refusal.

  3. Run calculate_registry_snapshot() over the snapshot with the operator-supplied manual casilla inputs, binding values, enum-binding values, and relation values. The engine evaluates every declared formula in dependency order and returns the full casilla_values map (inputs plus formula outputs).

  4. Build canonical replay payloads for inputs, binding overrides, enum/date bindings, and relation overrides (so the content-addressed revision id is stable across structurally identical re-runs).

  5. Project the engine result to CasillaObservation rows and persist the revision in BORRADOR state; advance the work unit’s current_calculation_revision_id pointer; emit modelo.calculation.created.

The revision starts in BORRADOR state; callers must run verify_modelo_revision() and file_modelo_revision() explicitly to advance through the lifecycle.

See also

build_calculation_replay_payloads():

Canonicalizes the values that participate in the revision id.

build_typed_observations():

Carries registry legal/source provenance onto the persisted revision.

persist_calculation_revision():

Owns duplicate detection, work-unit pointer advancement, and event emission.

Return type:

CalculationRevision

Parameters:
calculate_modelo_revision_from_bucket_aggregation(work_unit_id, *, actor='system', casilla_inputs=None, text_casilla_inputs=None, binding_values=None, enum_binding_values=None, iva_compensation_decision=None, iva_compensation_decision_repository=None, borrador_snapshot_id=None, relation_values=None, filing_period_date=None, work_unit_repository=None, calculation_repository=None, bucket_event_repository=None, transaction_repository=None, invoice_repository=None, foreign_asset_observations=(), borrador_snapshot_repository=None, detail_rows=(), clock=None)[source]

Calculate a modelo revision through the bucket-local source mesh.

transaction_repository is a TransactionCatalogueRepository used to load bucket-local ledger transactions for aggregation. invoice_repository is an InvoiceCatalogueRepository used by invoice and OSS/IOSS resolvers. foreign_asset_observations feeds the repository-free M720 foreign-asset resolver when the caller has already supplied typed asset observations. The wrapper resolves enrolled source families into backend binding, casilla, relation, detail-row, and provenance channels, rejects caller collisions with source-owned bindings, and then delegates to calculate_modelo_revision().

Returns a CalculationRevision. Use calculate_modelo_revision_from_bucket_aggregation_with_diagnostics() when the caller also needs the non-blocking source diagnostics (e.g. the operator-facing CLI calculate surface, which surfaces unconsumed-declarable IVA advisories).

See also

_resolve_bucket_source_mesh():

Runs the enrolled resolver set and returns the merged CalculationSourceResolution.

_reject_caller_overrides_of_source_bindings():

Refuses caller values for source-owned binding and bound-casilla slots.

Return type:

CalculationRevision

Parameters:
calculate_modelo_revision_from_bucket_aggregation_with_diagnostics(work_unit_id, *, actor='system', casilla_inputs=None, text_casilla_inputs=None, binding_values=None, enum_binding_values=None, iva_compensation_decision=None, iva_compensation_decision_repository=None, borrador_snapshot_id=None, relation_values=None, filing_period_date=None, work_unit_repository=None, calculation_repository=None, bucket_event_repository=None, transaction_repository=None, invoice_repository=None, foreign_asset_observations=(), borrador_snapshot_repository=None, detail_rows=(), clock=None)[source]

Calculate a modelo revision and return it alongside the source diagnostics.

Identical orchestration to calculate_modelo_revision_from_bucket_aggregation(), but returns a BucketAggregationCalculationResult carrying both the persisted CalculationRevision and the NON-blocking CalculationSourceDiagnostic rows the source mesh raised while resolving the bucket ledger (the unconsumed-declarable-IVA advisories the operator-facing CLI surfaces so an unrouted observation is never silently under-declared).

The bucket evidence is read from the injected TransactionCatalogueRepository and InvoiceCatalogueRepository; the source mesh projects their contributing rows plus explicitly supplied foreign-asset observations, previous-filing, relation-prefill, withholding, retenciones, and detail-row sources into the backend channels that feed the revision.

Return type:

BucketAggregationCalculationResult

Parameters:
assert_no_novel_source_kinds(revision)[source]

Raise if any binding source kind is unknown to the live mesh (S26 boundary gate).

A binding whose source is not in the enrolled-resolver union, the explicitly-deferred set, or manual_input would silently blank on every calculation. This gate converts that silent blank into a loud ModeloAggregationBindingError at calculation time so a novel TOML source cannot compile into a silently-zero revision.

The accepted set is:

  • ACCEPTED_BUCKET_AGGREGATION_SOURCE_KINDS — enrolled resolvers plus explicitly deferred advisory sources.

Parameters:

revision (ModeloRevision) – The ModeloRevision whose binding source kinds are checked against the live source-mesh enrollment.

Raises:

ModeloAggregationBindingError – When a binding carries a source kind absent from both the enrolled and the deferred sets.

Return type:

None

list_calculation_revisions(*, work_unit_id=None, calculation_repository=None)[source]

List calculation revisions, optionally filtered to one work unit.

Results are sorted by (work_unit_id, created_at) so the chronological revision chain for one work unit is contiguous and stable across calls.

Each element is a CalculationRevision.

Return type:

tuple[CalculationRevision, ...]

Parameters:
get_calculation_revision(calculation_revision_id, *, calculation_repository=None)[source]

Return one calculation revision by id, or raise.

Returns the CalculationRevision matching calculation_revision_id.

Return type:

CalculationRevision

Parameters:
mark_revision_verificado_completo(calculation_revision_id, *, actor, calculation_repository=None, work_unit_repository=None, clock=None)[source]

Transition a draft revision to VERIFICADO_COMPLETO.

The revision must currently be in BORRADOR state. After the transition the revision is immutable; subsequent calculation work on the same work unit must produce a new revision.

Parameters:

  • calculation_revision_id (str) – The id of the draft revision to promote.

  • actor (str) – Operator identifier stamped as verified_by.

  • calculation_repository (CalculationRevisionCatalogueRepositoryProtocol | None) – Optional calculation-revision catalogue repository override.

  • work_unit_repository (WorkUnitCatalogueRepositoryProtocol | None) – Optional work-unit catalogue repository override used to refuse direct promotion for cross-period dependency revisions.

  • clock (datetime | None) – Optional UTC timestamp override for verified_at.

Return type:

CalculationRevision

Returns:

The updated CalculationRevision in VERIFICADO_COMPLETO state.

Raises: