cadrumo.application.live.filed_capture_finalizer module

One typed finalizer for filed-declaration calculation-history enrollment.

Single, bulk, and source capture all drive their calculation-history enrollment through finalize_filed_capture(). The finalizer owns latest-observation selection, history ordering (delegated to the persistence authority’s select_latest_filed_observations_in_history_order()), per-observation registry-grounded persistence, and typed failure accumulation. The caller chooses the failure policy: fail-fast for single and source capture (a registry-enrollment failure aborts the operation), best-effort for bulk capture (failures accumulate into the report and the sweep continues).

Consolidating these into one authority removes the duplicate selector and persistence loop that capture orchestration previously carried, and guarantees every route persists the same observations in the same order rather than each reimplementing selection.

class FiledCaptureFailurePolicy(*values)[source]

Bases: StrEnum

How a filed-capture finalizer reacts to a registry-enrollment failure.

FAIL_FAST

abort the operation on the first failure.

Type:

Single and source capture

BEST_EFFORT

accumulate failures into the report and keep persisting.

Type:

Bulk capture

class FiledCaptureFinalization(calculation_observation_keys, failures, skipped_casillas=())[source]

Bases: object

Result of finalising a filed-capture batch into calculation history.

Parameters:
calculation_observation_keys: tuple[str, ...]
failures: tuple[FiledDataCaptureFailureRow, ...]
skipped_casillas: tuple[FiledCasillaSkipRow, ...]

Casillas the filing carries that the Decimal-only registry channel cannot read. Reported separately from failures because they are not a failed capture: the artefact was read correctly and these are what it holds. Collected whether or not the observation went on to enrol, so an operator learns which fields of their own return are outside the channel rather than inferring it from a refusal that names only the first one.

finalize_filed_capture(observations, *, justificante_csvs_by_observation=None, policy, ports)[source]

Persist the latest filed observation per period into calculation history.

Selection and history ordering delegate to the persistence authority, so all capture routes agree. Each registry-enrollment failure is accumulated as a typed FiledDataCaptureFailureRow. Under FiledCaptureFailurePolicy.FAIL_FAST any accumulated failure is raised as a LiveApplicationError; under FiledCaptureFailurePolicy.BEST_EFFORT the failures are returned for the caller’s report.

Return type:

FiledCaptureFinalization

Parameters: