cadrumo.application.ledger.history_query module

What counts as one ledger transaction’s history, and in what order.

Answering that is not transport work. It decides which prior identities anchor a row’s events after an id-affecting edit, whether split siblings belong to the same story, which of the bucket’s event types are history at all, and how evidence events – which are anchored elsewhere and reference the transaction only through their payload – join the chain. All of it lived in the CLI adapter, so a second surface showing a transaction’s history had no choice but to reimplement the same four decisions.

The two event-type sets are part of the contract rather than an implementation detail. History is a curated subset: a bucket carries events that are not this transaction’s story, and widening the set silently turns an audit trail into a log.

LEDGER_HISTORY_EVENT_TYPES: Final[tuple[BucketEventType, ...]]

Events anchored on the transaction identity itself.

LEDGER_EVIDENCE_HISTORY_EVENT_TYPES: Final[tuple[BucketEventType, ...]]

Evidence events anchored on their own object, naming the transaction only in their payload. They belong to the row’s story but cannot be found by object-id lookup, which is why they are collected separately.

class LedgerHistoryQuery(**data)[source]

Bases: BaseModel

One request for a transaction’s chronological event chain.

Parameters:

data (Any)

transaction_id: str
include_split_siblings: bool
class LedgerHistoryV1(**data)[source]

Bases: BaseModel

The assembled chain plus the identities it was assembled from.

object_ids is returned rather than hidden because it is the answer to “why is this event here”: an operator looking at events under an id they did not ask for is seeing the edit lineage work, not a leak.

Parameters:

data (Any)

bucket_id: str
transaction_id: str
object_ids: tuple[str, ...]
events: tuple[BucketEvent, ...]
event_count: NonNegativeInt
ledger_history_object_ids(*, transaction_id, transaction_repository, include_split_siblings=False)[source]

Return every event-anchor id whose events belong to transaction_id.

Always the id itself plus every prior id in its edit lineage. An update that edits an id-affecting fact anchors the pre-edit events (create, import) on the OLD id and everything after on the new one, so walking the lineage is what lets an operator holding a superseded id still see the whole chain instead of a truncated one.

Split siblings are a different relationship – rows that came from the same parent, not earlier names for this row – so they are included only when the caller opts in.

Return type:

tuple[str, ...]

Parameters:
read_ledger_history(query, *, bucket_id, transaction_repository, bucket_event_repository)[source]

Assemble one transaction’s chronological event chain.

Parameters:
Return type:

LedgerHistoryV1

Returns:

The chain, ordered by occurrence, with the anchor ids it came from.