cadrumo.domain.transactions package

Inert namespace for immutable ledger transactions.

The transaction domain boundary used by ledger is defined across the owning modules listed below. Transaction wraps an upstream RawTransaction and its RawProvenance, while TransactionCatalogue keeps the immutable mapping keyed by the content-derived transaction id. Import helpers such as derive_transaction_id(), derive_import_fingerprint(), and normalise_movement_reference() are the public identity helpers.

The row model separates amount magnitude from TransactionDirection; downstream tax calculations route by direction rather than by signed amounts. It carries classification, tax substrate, evidence, split, edit, lifecycle, FX, jurisdiction, and timestamp provenance through typed records such as ClassificationHistoryEntry, TransactionEvidenceProvenanceEntry, TransactionEditLineageEntry, and TransactionLifecycleLineageEntry. Classification helpers set_classification(), snapshot_classification_state(), and link_invoice() return fresh catalogues instead of mutating callers’ instances.

Persistence is served by the read-side TransactionCatalogueRepositoryProtocol port; the concrete encrypted implementation lives in the persistence adapter TransactionCatalogueRepository. It stores each transaction under the bucket-scoped transaction namespace as FINANCIAL SensitivityClass rows wrapped in Envelope through SecureObjectRepository; callers should not write plaintext catalogues or reach into private modules. The pure port surface, key-derivation helpers, and namespace constant are imported from their defining modules.

LLM-facing LLMClassifier, LLMSplitProposer, PromptSpec, LedgerClassificationRule, and ledger_irpf_category_catalogue() are likewise imported from their defining modules. They constrain model choices to typed BusinessClassification, CategoryChoice, and IvaCategoryChoice allow-lists; regulated tax numbers are derived by application services, not originated by this package.

Downstream modelo calculation records keep only forward transaction ids on CalculationRevision. Aggregation services consume this catalogue to produce registry binding values and ledger filing snapshots, while TransactionRevisionParticipationIndex provides the rebuildable inverse audit lookup from one ledger transaction to finalized revisions and filing records.

See also

ledger

Operator-facing lifecycle that creates, edits, classifies, splits, attaches evidence, and preflights bucket-scoped transactions.

aggregation

Source resolvers that turn transaction catalogues into CalculationSourceResolution payloads for modelo calculation.

compute_ledger_filing_snapshot()

Captures tax-relevant transaction fields for finalized calculation revisions.

invoices

Invoice catalogue and reconciliation records referenced by invoice_id and purchase_invoice_evidence_id.

usage_ratios

Proportionality profiles referenced by ledger rows before aggregation.

Consumers import from the owning module – models, llm, enums, irpf_categories, retencion_facts, raw_transaction, repository, service, model_tier, classification_rule, model_validation, errors – rather than from this package root, which is inert.

The root carried a lazy guard for the persistence port so an importer did not pay for the repository module. That deferral is now structural: a caller naming repository asks for it, and one naming models does not.

Submodules