cadrumo.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 and the application-owned CalculationActionPorts, 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_with_diagnostics() 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. It is the only entry point into that orchestration, and it returns the non-blocking source diagnostics with the revision rather than beside it, so no caller can reach the mesh and lose the advisories on the way out. 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, profile, source_diagnostics=())[source]

Bases: object

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

revision is the persisted CalculationRevision; profile is the work profile the calculation checked and read. 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
profile: ModeloWorkProfile
source_diagnostics: tuple[CalculationSourceDiagnostic, ...]
calculate_modelo_revision(work_unit_id, *, ports, 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, borrador_snapshot_id=None, relation_values=None, unresolved_relation_ids=(), unresolved_binding_ids=(), source_transaction_ids=(), m210_official_tipo_renta_code=None, m210_gross_income_source_mode=None, filing_period_date=None, detail_rows=(), filing_instance_evidence=None, clock=None)[source]

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

This public service accepts operator and application calculation inputs only. Source-mesh provenance and unresolved-source issues are established solely by the private mesh bridge below; callers cannot manufacture the M369 OSS/IOSS source-assessment record used by verification and export.

Parameters:

  • work_unit_id (str) – Identifier of the filing work unit to calculate.

  • actor (str) – Audit actor recorded on the persisted calculation revision.

  • casilla_inputs (Mapping[TypeAliasType, Decimal]) – Operator-supplied numeric values keyed by casilla.

  • text_casilla_inputs (Mapping[TypeAliasType, str] | None) – Optional operator-supplied text values keyed by casilla.

  • binding_values (Mapping[TypeAliasType, Decimal] | None) – Optional numeric overrides for registry bindings.

  • enum_binding_values (Mapping[TypeAliasType, str] | None) – Optional enumerated registry-binding values.

  • backend_binding_values (Mapping[TypeAliasType, Decimal] | None) – Optional binding values resolved by backend authorities.

  • row_binding_values (Mapping[tuple[TypeAliasType, int], Decimal | str | int | bool] | None) – Optional detail-row binding values keyed by binding and row.

  • backend_casilla_inputs (Mapping[TypeAliasType, Decimal] | None) – Optional casilla values resolved by backend authorities.

  • iva_compensation_decision (object | None) – Optional IVA compensation election for this calculation.

  • ports (CalculationActionPorts) – Required application-owned persistence capabilities for this calculation and its source mesh.

  • borrador_snapshot_id (str | None) – Optional Modelo 100 draft snapshot selected as input.

  • relation_values (Mapping[TypeAliasType, Decimal] | None) – Optional numeric overrides for declared registry relations.

  • unresolved_relation_ids (tuple[TypeAliasType, ...]) – Relations that source resolution could not satisfy.

  • unresolved_binding_ids (tuple[TypeAliasType, ...]) – Bindings that source resolution could not satisfy.

  • source_transaction_ids (tuple[str, ...]) – Ledger transactions contributing to the calculation.

  • m210_official_tipo_renta_code (str | None) – Optional official Modelo 210 income-type code.

  • m210_gross_income_source_mode (M210GrossIncomeSourceMode | None) – Selected Modelo 210 gross-income source authority.

  • filing_period_date (date | None) – Date used to resolve the applicable filing period.

  • detail_rows (tuple[Modelo184MemberRow | Modelo232VinculadaRow | Modelo349OperadorRow | Modelo349RectificacionRow | Modelo347ContraparteRow | Modelo210AgrupacionRentaRow, ...]) – Repeating detail rows supplied to the registry engine.

  • filing_instance_evidence (FilingInstanceEvidence | None) – Immutable operator-selected Modelo 303 filing facts.

  • clock (datetime | None) – Optional deterministic timestamp for the persisted revision.

Return type:

CalculationRevision

resolve_bucket_source_mesh(snapshot, work_unit, *, ports, foreign_asset_observations, foreign_asset_row_observations, casilla_inputs=None, text_casilla_inputs=None, m210_official_tipo_renta_code=None, m210_gross_income_source_mode=None, binding_values=None, enum_binding_values=None, date_binding_values=None, relation_values=None, filing_period_date=None, profile=None, transaction_repository=None)[source]

Resolve the live source mesh for a bucket-aggregation calculation.

Builds the CalculationSourceContext, runs every enrolled ledger / invoice / carry resolver through merge_source_resolutions(), and augments the result with the unhandled-binding-source advisories for any declared source with no enrolled resolver. Returns the merged CalculationSourceResolution.

The transaction repository from ports is wrapped in MemoizedTransactionCatalogueRepository so every enrolled ledger resolver shares one load() of the bucket’s transaction catalogue instead of each resolver independently re-scanning and re-decrypting it.

profile is the work profile the calculation already checked; when omitted, this entry loads it once. Every resolver reads that one record from profile.

Core types: RegistrySnapshot.

Return type:

CalculationSourceResolution

Parameters:
calculate_modelo_revision_from_bucket_aggregation_with_diagnostics(work_unit_id, *, ports, actor='system', casilla_inputs=None, text_casilla_inputs=None, cleared_casilla_ids=(), m210_official_tipo_renta_code=None, m210_gross_income_source_mode=None, binding_values=None, enum_binding_values=None, iva_compensation_decision=None, borrador_snapshot_id=None, relation_values=None, filing_period_date=None, foreign_asset_observations=(), foreign_asset_row_observations=(), detail_rows=(), filing_instance_evidence=None, clock=None, additional_secure_object_writes_for_revision=None, profile=None)[source]

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

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 calculation ports; 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.

profile is the work profile the calling command already loaded for this bucket. When omitted, the readiness gate loads it once; either way the profile the gate checked is the only one the calculation reads.

Return type:

BucketAggregationCalculationResult

Parameters:
assert_no_novel_source_kinds(revision)[source]

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

A scalar binding whose source is not in the executable resolver union would silently blank on every calculation. Row-producing bindings travel through the detail-row and export channel instead, so requiring a scalar resolver for them conflates two executable mechanisms. This gate converts a genuinely unrouted scalar source into a loud ModeloAggregationBindingError at calculation time so a novel TOML source cannot compile into a silently-zero revision.

The accepted set is:

  • CALCULATION_ROUTE_ENROLLED_SOURCES — executable resolver and intrinsic production-channel ownership.

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 executable production ownership and not registered as deferred or non-runtime. Deferred kinds are not refused here; they surface as deferred_binding_source diagnostics at resolution.

Return type:

None

list_calculation_revisions(*, ports, work_unit_id=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, *, ports)[source]

Return one calculation revision by id, or raise.

Returns the CalculationRevision matching calculation_revision_id.

Return type:

CalculationRevision

Parameters: