cadrumo.application.aggregation.impatriado_income_ledger module¶

Repository-backed impatriado income ledger mechanics.

The module retains transaction filtering, amount projection, period partitioning, typed issue emission, and aggregation mechanics. Target coordinates, selected model/revision applicability, source-jurisdiction membership, eligible income categories, and binding/legal declarations belong to the selected registry revision.

No target, jurisdiction, category, applicability, or binding identifier is declared as a Python fallback.

class ImpatriadoIncomeLedgerAggregationIssueReason(*values)[source]¶

Bases: StrEnum

Machine-readable reasons why a ledger row did not fold into the impatriado base.

UNSUPPORTED_DIRECTION¶

UNSUPPORTED_CURRENCY¶

UNCLASSIFIED_BUSINESS_STATE¶

PERSONAL_TRANSACTION¶

OUTSIDE_PERIOD¶

UNSUPPORTED_PERIOD¶

BECKHAM_FOREIGN_SOURCE_SEGREGATED¶

class ImpatriadoIncomeLedgerAggregationIssue(**data)[source]¶

Bases: BaseModel

Traceable exclusion emitted while aggregating impatriado income ledger rows.

Parameters:: data (Any)

model_config: ClassVar[ConfigDict]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

transaction_id: TransactionId¶

reason: ImpatriadoIncomeLedgerAggregationIssueReason¶

detail: IssueDetail¶

rejected_source_jurisdiction: str | None¶

class ImpatriadoIncomeObservation(**data)[source]¶

Bases: BaseModel

One eligible INCOMING income ledger row for the selected registry target.

Carries the typed gross amount and selected target casilla. The registry resolver sums the fiscally computable amount (taxable_base_amount when the row carries an explicit IVA tagging, else gross_amount) across the observations for that target.

source_jurisdiction is retained for provenance after source-scope membership has been resolved by the selected registry revision.

Parameters:: data (Any)

model_config: ClassVar[ConfigDict]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

transaction_id: TransactionId¶

target_casilla_id: CasillaId¶

gross_amount: Decimal¶

taxable_base_amount: Decimal | None¶

filing_date: date¶

source_jurisdiction: CountryCodeAlpha2¶

class ImpatriadoIncomeLedgerAggregation(**data)[source]¶

Bases: LedgerAggregationResultBase[ImpatriadoIncomeObservation, ImpatriadoIncomeLedgerAggregationIssue]

Annual income observations for one selected filing revision.

out_of_window_summary is populated by repository-backed date partitions. Full-catalogue aggregation keeps row-level issues because every transaction is already loaded for classification.

Parameters:

modelo (Annotated[str, MinLen(min_length=1), MaxLen(max_length=16)])
period (Period)
observations (Sequence)
issues (Sequence)
casilla_aggregation (CasillaAggregation)

out_of_window_summary: OutOfWindowTransactionSummary | None¶

model_config: ClassVar[ConfigDict]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

aggregate_impatriado_income_ledger_from_repositories(*, bucket_id, period, modelo, target_casilla_id, source_jurisdictions, eligible_income_categories, transaction_repository)[source]¶

Load the transaction catalogue and aggregate annual registry-admitted income.

The caller supplies the bucket-bound transaction catalogue capability. The application layer never constructs the persistence adapter.

Returns an ImpatriadoIncomeLedgerAggregation.

Return type:

ImpatriadoIncomeLedgerAggregation

Parameters:

bucket_id (str)
period (Period)
modelo (str)
target_casilla_id (CasillaId)
source_jurisdictions (frozenset[str])
eligible_income_categories (frozenset[str])
transaction_repository (TransactionCatalogueRepositoryProtocol)

aggregate_impatriado_income_ledger(transactions, *, bucket_id, period, modelo, target_casilla_id, source_jurisdictions, eligible_income_categories)[source]¶

Aggregate INCOMING income into the selected registry target.

Applies the selected source scope over the full annual period. Only rows admitted by the selected registry jurisdiction and category declarations fold into the selected target. Out-of-scope and unresolved rows are segregated into typed issues rather than silently entering or disappearing from the aggregate.

Parameters:

transactions (TransactionCatalogue) – The TransactionCatalogue to aggregate.
bucket_id (str) – Bucket identifier carried through to provenance so the aggregation cannot be silently misattributed.
period (Period) – The annual Period whose year anchors the window.
modelo (str) – Selected registry model identifier.
target_casilla_id (TypeAliasType) – Selected registry target identifier.
source_jurisdictions (frozenset[str]) – Selected registry source-scope membership.
eligible_income_categories (frozenset[str]) – Selected registry income-category membership.

Return type:

ImpatriadoIncomeLedgerAggregation

Returns an ImpatriadoIncomeLedgerAggregation for the ejercicio. period must be the annual period.