cadrumo.application.invoices.transaction_linking module

Application service for explicit invoice-to-transaction linking.

link_invoice_transaction_repositories() loads both the InvoiceCatalogue via InvoiceCatalogueRepository and the TransactionCatalogue via TransactionCatalogueRepository, applies the bidirectional link, and commits both updated catalogues in one unit of work through TransactionCatalogueRepository.save_with_secure_object_writes().

class InvoiceTransactionLinkResult(**data)

Bases: BaseModel

Result of a persisted bidirectional invoice link command.

Parameters:

data (Any)

invoice_id: InvoiceId

transaction_id: TransactionId

invoice: Invoice

invoices: InvoiceCatalogue

transactions: TransactionCatalogue

link_invoice_transaction_catalogues(invoices, transactions, *, invoice_id, transaction_id)

Link one invoice to one transaction, returning the updated catalogues.

Returns an InvoiceTransactionLinkResult where the invoice and transaction cite each other.

Parameters:

• invoices (InvoiceCatalogue) – The InvoiceCatalogue to update with the new link.

• transactions (TransactionCatalogue) – The TransactionCatalogue to update with the new link.

• invoice_id (str) – Identifier of the invoice to link.

• transaction_id (str) – Identifier of the transaction to link; resolved to its canonical form against transactions before linking.

Return type:

InvoiceTransactionLinkResult

link_invoice_transaction_repositories(*, bucket_id, invoice_id, transaction_id, invoice_repository=None, transaction_repository=None, extra_writes=())

Persist a bidirectional invoice link as one all-or-nothing write.

Both sides of the link commit together: the updated invoice catalogue is serialised into a SecureObjectWrite and handed to save_with_secure_object_writes() alongside the transaction-catalogue diff, so both land in the single apply_batch() transaction. A crash or error mid-write rolls both back, so the catalogues cannot come to rest in the one-sided state verify_link_consistency() reports.

Parameters:

• bucket_id (str) – Profile bucket owning both catalogues.

• invoice_id (str) – Identifier of the invoice to link.

• transaction_id (str) – Identifier of the transaction to link, resolved to its canonical catalogue form before linking.

• invoice_repository (InvoiceCatalogueCoCommitWriterProtocol | None) – The invoice-catalogue co-commit port supplied by the composition root. The application layer does not construct a persistence adapter when it is omitted.

• transaction_repository (TransactionCatalogueCoCommitWriterProtocol | None) – The transaction-catalogue co-commit port supplied by the composition root. The application layer does not construct a persistence adapter when it is omitted.

• extra_writes (tuple[SecureObjectWrite, ...]) – Further secure-object upserts to commit in the same unit of work as the link, such as the caller’s bucket-event history. Treated as opaque: this service commits them atomically with the two catalogues but never inspects or constructs them, so the invoice layer stays free of event-history concerns.

Return type:

InvoiceTransactionLinkResult

Both repositories are application-owned co-commit ports. Their concrete secure-object implementations are supplied by an outer composition root; this module owns only the atomic linkage orchestration.

Returns an InvoiceTransactionLinkResult with the updated invoice and transaction catalogues after the link is written.