cadrumo.application.ledger.stale_filing_query module

Which of this profile’s finalized filings no longer match the live ledger.

stale_filed_revisions already decides whether one revision has drifted, but it is pure over inputs a caller must assemble: the revision catalogue, the work units, and the live transactions. Assembling them – and deciding which revisions belong to this profile at all – was done inside the CLI status verb, so the finding existed only where that verb happened to look.

The bucket filter is the part that most needs a home. A revision reaches this code through a catalogue that is not itself bucket-scoped, so ownership is established by joining to the work unit and comparing its bucket. Getting that wrong shows one profile another profile’s filings, which is why it is a cross-aggregate rule rather than a display detail.

The work-unit join also supplies the only address an operator recognises: a revision id names nothing they filed, whereas modelo, year and period do.

class LedgerStaleFilingV1(**data)

Bases: BaseModel

One finalized filing whose ledger basis has since changed.

Carries the natural filing address rather than only the revision id, because that is what an operator can act on.

Parameters:

data (Any)

modelo: str

filing_year: int

period: str

calculation_revision_id: str

work_unit_id: str

changed_count: NonNegativeInt

removed_count: NonNegativeInt

covers_current_fact_set: bool

Whether the comparison behind this finding spanned every tax fact this build knows can move a casilla. False means the filing was sealed under an older fingerprint field set and was compared under that set, so the counts are sound but narrower than today’s. Reported, never acted on: a narrow comparison is not evidence of drift, and treating it as drift would restate every historical filing at once.

class StaleFilingPeriodV1(*args, **kwargs)

Bases: Protocol

The period surface this query reads.

property registry_token: str

class StaleFilingWorkUnitV1(*args, **kwargs)

Bases: Protocol

The work-unit surface this query reads: four fields, no more.

property bucket_id: str

property modelo: str

property filing_year: int

property period: StaleFilingPeriodV1

class StaleFilingWorkUnitLookupV1(*args, **kwargs)

Bases: Protocol

The catalogue surface this query reads.

Structural rather than WorkUnitCatalogue because the query calls exactly one method on it. A caller’s minimal stand-in is then a legitimate argument rather than something that has to be waved past the type checker, and the real catalogue satisfies it unchanged.

get(work_unit_id, /)

Return type:

StaleFilingWorkUnitV1 | None

Parameters:

work_unit_id (str)

read_stale_ledger_filings(*, bucket_id, revisions, work_units, transactions, detector=<function stale_filed_revisions>)

Report this bucket’s finalized filings that no longer match the ledger.

A revision whose work unit is missing, or belongs to another profile, is excluded: the revision catalogue is not bucket-scoped, so ownership can only be established through the work-unit join.

Parameters:

• bucket_id (str) – The owning profile bucket.

• revisions (Mapping[str, CalculationRevision]) – The calculation revisions to consider.

• work_units (StaleFilingWorkUnitLookupV1) – The work units the revisions are addressed through.

• transactions (TransactionCatalogue) – The live ledger the snapshots are re-evaluated against.

• detector (TypeAliasType) – The staleness decision, injectable so the ownership join can be exercised without reproducing a drifted snapshot.

Return type:

tuple[LedgerStaleFilingV1, ...]

Returns:

One entry per drifted filing owned by bucket_id.

Core types: CalculationRevision, TransactionCatalogue.