cadrumo.application.ledger.preflight module

Backend readiness preflight for bucket-scoped ledger transactions.

preflight_ledger_tax_readiness() loads a TransactionCatalogue via TransactionCatalogueRepositoryProtocol from the active bucket and delegates to preflight_transaction_catalogue() for pure in-memory analysis. The report is consumed by modelo readiness projection and ledger read surfaces; it is not a calculation engine and never mutates the catalogue it inspects.

See also

build_operator_state_projection()

Modelo readiness consumer that embeds blocking ledger issues in the operator state projection.

cadrumo.entrypoints.cli._ledger_read_cli

CLI read surface that reports these preflight issues without mutating ledger state.

cadrumo.application.aggregation

Calculation source mesh that consumes ledger facts only after this readiness layer has reported operator-facing gaps.

Core types: UserProfileRecord.

class LedgerPreflightIssueReason(*values)[source]

Bases: StrEnum

Machine-readable ledger facts missing before modelo calculation.

MISSING_BUSINESS_CLASSIFICATION
MISSING_CATEGORY
MISSING_TAXABLE_BASE
MISSING_IVA_AMOUNT
MISSING_IVA_RATE
MISSING_EUR_TAX_SUBSTRATE
MISSING_COUNTERPARTY_IDENTIFICATION_STATE
DOMESTIC_IDENTIFICATION_ON_INTRA_COMMUNITY_TRANSACTION
EU_MEMBER_STATE_ON_EXPORT_TRANSACTION
MISSING_COUNTERPARTY_ESTABLISHMENT_ON_EXPORT
MISSING_PROPORTIONALITY_REFERENCE
UNSUPPORTED_CURRENCY
UNSUPPORTED_PERIOD
CENSO_RATIO_MISMATCH
MISSING_HOME_OFFICE_AFECTACION
ANOMALY_NON_DECLARABLE_IVA_CATEGORY
ANOMALY_NON_DECLARABLE_RECARGO_EQUIVALENCIA
class LedgerPreflightIssue(**data)[source]

Bases: BaseModel

One model-readiness issue attached to a bucket-local transaction.

Parameters:

data (Any)

transaction_id: TransactionId | Literal['__period__']
reason: LedgerPreflightIssueReason
detail: IssueDetail
class LedgerPreflightReport(**data)[source]

Bases: BaseModel

Readiness report for ledger facts consumed by modelo calculation.

Parameters:

data (Any)

bucket_id: BucketId
period: Period
checked_transaction_count: NonNegativeInt
issues: Sequence[LedgerPreflightIssue]
property ready: bool

Whether the report contains no modelo-readiness issues.

preflight_ledger_tax_readiness(*, bucket_id, period, usage_ratio_profile_loader, operation, transaction_repository=None, raw_afectacion_ratio=None)[source]

Load a bucket-local catalogue and report modelo-readiness gaps.

Parameters:

  • bucket_id (str) – Bucket whose ledger catalogue is being checked.

  • period (Period) – Filing period used to decide whether each transaction belongs in the readiness window.

  • usage_ratio_profile_loader (UsageRatioProfileLoader) – Required application-owned read capability for resolving declared usage-ratio profiles.

  • operation (PinnedAuthorityOperation) – Generation-pinned authority for governed ratio and IVA vocabulary.

  • transaction_repository (TransactionCatalogueRepositoryProtocol | None) – Optional transaction-catalogue port used to load the bucket-local catalogue; the outward-composed repository is resolved when None.

  • raw_afectacion_ratio (Decimal | None) – Optional home-office usage ratio from censo data, used only to surface proportionality mismatches.

Return type:

LedgerPreflightReport

Returns:

A LedgerPreflightReport describing blocking or advisory ledger facts for modelo-readiness projection.

preflight_transaction_catalogue(*, bucket_id, period, transactions, operation, censo_ratio_mismatch_detail=None, missing_home_office_afectacion_detail=None)[source]

Report missing ledger facts without mutating the transaction catalogue.

Parameters:

  • bucket_id (str) – Stable bucket identifier for the ledger being checked.

  • period (Period) – Filing period as a typed Period instance.

  • transactions (TransactionCatalogue) – The TransactionCatalogue to inspect for missing facts.

  • operation (PinnedAuthorityOperation) – Generation-pinned authority for governed IVA and category facts.

  • censo_ratio_mismatch_detail (str | None) – Optional censo mismatch detail previously resolved from the secure ratio profile. When supplied, active HOME_OFFICE ratio rows surface it as a preflight issue.

  • missing_home_office_afectacion_detail (str | None) – Optional detail reporting that no afectación proportion resolves at all. When supplied, active HOME_OFFICE ratio rows surface it, so a row that will deduct nothing says so instead of passing as though the expense were absent.

Return type:

LedgerPreflightReport

Returns a LedgerPreflightReport.

OPERATOR_ACTION_BY_IVA_LEDGER_AGGREGATION_ISSUE: Mapping[IvaLedgerAggregationIssueReason, OperatorActionAxis]

Total operator-action projection for every native IVA ledger issue.