aeat.domain.transactions._repository module

Domain-side transaction-catalogue port surface.

This module owns the pure transaction-catalogue persistence vocabulary that carries no SQL/crypto coupling: the ImportSummary record returned by a ledger import, the transaction_object_key() / transaction_index_object_key() secure-object key-derivation helpers, and the TX_BUCKET_NAMESPACE / schema-version constants that name the persisted envelope contract. The concrete encrypted SQL repository lives in the persistence adapter TransactionCatalogueRepository, behind the read-side TransactionCatalogueRepositoryProtocol; the domain package depends only on the structural port.

The namespace authority is adapters.persistence.storage.TRANSACTION_CATALOGUE_NAMESPACE; this module derives the bucket-local transaction row keys with transaction_object_key() and the membership-index key with transaction_index_object_key().

transaction_index_object_key(bucket_id)[source]

Return the per-bucket transaction-membership-index secure-object key.

The index row shares adapters.persistence.storage.TRANSACTION_CATALOGUE_NAMESPACE with the per-transaction rows and bounds reads/deletions to one bucket.

Return type:

str

Parameters:

bucket_id (str)

transaction_object_key(bucket_id, transaction_id)[source]

Return the per-transaction secure-object key within a profile bucket.

Each transaction is its own secure-object row. The key qualifies with the bucket id (transaction:{bucket_id}:{transaction_id}); cross-bucket aggregation must qualify with (bucket_id, tx_id) because tx_id alone is unique only within one bucket. Rows live under adapters.persistence.storage.TRANSACTION_CATALOGUE_NAMESPACE.

Return type:

str

Parameters:

  • bucket_id (str)

  • transaction_id (str)

class ImportSummary(**data)[source]

Bases: BaseModel

Frozen summary of one ledger import persistence operation.

Variables:

  • imported – Number of new transactions persisted by this call.

  • skipped – Number of input rows already present in the catalogue. A row is a duplicate when its stable import fingerprint (derive_import_fingerprint()) is already present — the fingerprint is stamped at import and survives both later edits and a re-export in a different file format.

  • errors – Reserved for future per-row error counts; today the repository raises on any error rather than tallying.

  • likely_duplicate_refs – Rows that were imported but share an effective date and amount with an existing transaction while carrying a divergent narrative — a probable, but not confident, cross-format duplicate. The operator is warned so they can review rather than discovering a silent double-count later.

  • catalogue_path – Logical URI of the encrypted database object.

Parameters:
imported: int
skipped: int
errors: int
bucket_id: BucketId
imported_refs: tuple[BucketTransactionRef, ...]
skipped_refs: tuple[BucketTransactionRef, ...]
likely_duplicate_refs: tuple[BucketTransactionRef, ...]
catalogue_path: str