cadrumo.application.ledger.list_query module

The canonical selection semantics behind one Ledger transaction listing.

Filtering, group selection, sort order, and paging decide WHICH ledger rows an operator is shown and in what order. That is query policy over stored facts, so it belongs beside the other Ledger use cases rather than inside whichever frontend happens to ask: the CLI adapter owned all of it, which left the TUI with no way to list transactions except by reproducing the same rules a second time.

The split this module draws is between selecting rows and rendering them. The page it returns carries canonical application results plus the two facts a caller needs to describe the window truthfully – the unfiltered total and whether the window omits anything – and nothing about columns, labels, or line formatting, which stay with the surface that displays them.

Core types: TransactionCatalogue.

LLM_DECISION_EVENT_TYPES: Final

an accepted (applied) classification, or a rejection. The most recent of the two is the standing decision. One home, so a surface reading it cannot drift from another.

Type:

The two terminal model decisions on a row

class LedgerTransactionListQuery(**data)[source]

Bases: BaseModel

One operator-intent request for a window over the stored ledger.

Parameters:

data (Any)

spec: LedgerReviewFilterSpec
group: str | None
by_group: bool
limit: int | None
offset: NonNegativeInt
sort_by: LedgerSortField | None
sort_order: LedgerSortOrder
exclude_llm_rejected: bool
class LedgerTransactionListPageV1(**data)[source]

Bases: BaseModel

The selected window plus the facts needed to describe it honestly.

total counts every row that survived filtering, not the window, so a caller can say how much it is not showing. truncated is that judgement already made, covering both a window that starts past the first row and one that ends before the last.

Parameters:

data (Any)

bucket_id: str
results: tuple[ManualLedgerTransactionResult, ...]
total: NonNegativeInt
truncated: bool
sort_ledger_results(results, *, sort_by, sort_order)[source]

Stably order results on one axis, tie-broken by transaction id.

The composite key is (missing, primary, transaction_id): a row with no value on the axis always sorts last regardless of direction, and the content-addressed id makes the order deterministic between equal rows.

Return type:

tuple[ManualLedgerTransactionResult, ...]

Parameters:
latest_llm_decision_is_rejection(event_catalogue, transaction_id)[source]

Report whether this transaction’s most recent model decision was a rejection.

Reads the event history only and never consults review_status: a rejection is a decision that was made, which the current status cannot distinguish from a row that was never assessed.

Return type:

bool

Parameters:
query_ledger_transaction_list(query, *, bucket_id, ports)[source]

Select, order, and page one window over a bucket’s stored transactions.

Order of operations is part of the contract: filter, then group selection, then sort, then group partitioning, then paging. Sorting before paging is what makes a page mean the same thing to every caller, and partitioning after sorting keeps the chosen order inside each group block.

Parameters:
Return type:

LedgerTransactionListPageV1

Returns:

The selected window with its unfiltered total and truncation flag.