cadrumo.application.ledger.protocols module

Application-layer port protocols for the ledger service.

Defines structural typing.Protocol interfaces consumed by cadrumo.application.ledger.actions_import so that the application layer depends only on these protocol types, not on concrete adapter classes.

class ParsedLedgerRowProtocol(*args, **kwargs)

Bases: Protocol

Structural view of one parsed financial source row.

property raw: RawTransaction

Return the domain raw transaction carried by this row.

property direction: TransactionDirection

Return the authoritative flow direction for this row.

class ProviderValidationProtocol(*args, **kwargs)

Bases: Protocol

Structural validation result returned by a financial source port.

property is_valid: bool

Whether the source can be ingested.

property warnings: tuple[str, ...]

Warnings produced while validating the source.

property detected_encoding: str | None

Detected source encoding, when the provider reports one.

property detected_dialect: str | None

Detected source dialect or layout, when available.

property unavailable_optional_extra: Mapping[str, str | bool] | None

Optional-extra facts when the provider cannot run locally.

class FinancialProviderProtocol(*args, **kwargs)

Bases: Protocol

Protocol satisfied by any file-backed raw transaction provider.

Covers exactly the two methods called by the ledger import service: ingest() and validate_source(). Adapter-internal helpers (build_provenance, _read_source_bytes, etc.) remain private to the adapter implementation.

ingest(path)

Yield parsed ledger rows from path.

Each yielded item carries a magnitude RawTransaction plus its TransactionDirection, parsed from the provider-format file.

Return type:

Iterator[ParsedLedgerRowProtocol]

Parameters:

path (Path)

validate_source(path)

Validate path and return a structured validation result.

Return type:

ProviderValidationProtocol

Parameters:

path (Path)

class TransactionCatalogueCoCommitWriterProtocol(*args, **kwargs)

Bases: TransactionCatalogueRepositoryProtocol, Protocol

Transaction-catalogue port for an atomic multi-object ledger write.

save_with_secure_object_writes(catalogue, extra_writes)

Persist the catalogue and related secure objects atomically.

Core types: TransactionCatalogue.

Return type:

None

Parameters:

• catalogue (TransactionCatalogue)

• extra_writes (tuple[SecureObjectWrite, ...])

class InvoiceCatalogueCoCommitWriterProtocol(*args, **kwargs)

Bases: InvoiceCatalogueRepositoryProtocol, Protocol

Invoice-catalogue port for an atomic ledger co-commit.

load_revisioned()

Load the catalogue with the secure-object revision observed.

Return type:

tuple[InvoiceCatalogue, str]

to_secure_object_write(catalogue, *, expected_revision_id=None)

Build the invoice secure-object write without committing it.

Core types: InvoiceCatalogue.

Return type:

SecureObjectWrite

Parameters:

• catalogue (InvoiceCatalogue)

• expected_revision_id (str | None)

class BucketEventHistoryCoCommitWriterProtocol(*args, **kwargs)

Bases: BucketEventHistoryRepositoryProtocol, Protocol

Bucket-event port for a revision-guarded ledger co-commit.

load_revisioned()

Load event history with the secure-object revision observed.

Return type:

tuple[BucketEventHistoryCatalogue, str]