cadrumo.application.ledger.workspace module

Frontend-neutral read projection for the local Ledger workspace.

The provider in this module is deliberately pure. Its callers load the bucket-scoped catalogues and canonical Ledger query results, then hand those facts in as one snapshot. No repository, adapter, entrypoint, filesystem, or network dependency is resolved here.

Only safe coordinates and aggregate state cross the frontend boundary. The source catalogues can contain descriptions, counterparties, monetary values, invoice contents, and filing evidence; none is retained by, serialised from, or exposed in the representation of LedgerWorkspaceProjectionV1.

exception LedgerWorkspaceProjectionError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Canonical input facts cannot form one truthful workspace snapshot.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class LedgerWorkspaceArea(*values)[source]

Bases: StrEnum

Closed set of operator-facing areas in the Ledger workspace.

OVERVIEW
ENTRIES
REVIEW
IMPORT
CLASSIFICATION
EVIDENCE
RECONCILIATION
class LedgerWorkspaceSource(*values)[source]

Bases: StrEnum

Closed local authority that supplied an area projection.

There is intentionally no AEAT member. Remote evidence comparison and reconciliation belong to the AEAT Sync workspace, not Ledger.

LOCAL_LEDGER
LOCAL_INVOICES
LOCAL_DECLARATIONS
class LedgerWorkspaceAvailability(*values)[source]

Bases: StrEnum

Whether the already-admitted local area can currently be opened.

AVAILABLE
LOCKED
STALE
NEVER_CAPTURED
UNAVAILABLE
class LedgerWorkspaceStatus(*values)[source]

Bases: StrEnum

Source-native state, kept distinct from route availability.

READY
EMPTY
NEEDS_ATTENTION
UNMEASURED
class LedgerWorkspaceAreaStateV1(**data)[source]

Bases: BaseModel

Safe availability and status for one workspace area.

Parameters:

data (Any)

area: LedgerWorkspaceArea
sources: tuple[LedgerWorkspaceSource, ...]
availability: LedgerWorkspaceAvailability
reason_code: NamespacedId | None
status: LedgerWorkspaceStatus
item_count: NonNegativeInt
class LedgerWorkspaceEntryRefV1(**data)[source]

Bases: BaseModel

One local Ledger entry, as the operator’s own record.

This carries the entry’s substance, not a coordinate pointing at it. The surface that reads this projection is reached only through an authenticated session over the operator’s own ledger, so withholding the date, amount, counterparty or classification withholds nothing from an adversary and everything from the person doing the work: an opaque identifier and a status word cannot be reviewed, and review is what the surface is for.

Storage and transport rules are untouched by this. Nothing here weakens encryption at rest, and a diagnostic or log record – which can travel somewhere an authenticated session does not – keeps its own redaction.

Parameters:

data (Any)

transaction_id: TransactionId
review_status: str
date: str
amount: str
currency: str
direction: str
counterparty: str
description: str
business_classification: str
class LedgerInvoiceReconciliationRefV1(**data)[source]

Bases: BaseModel

One suggested invoice/entry link, with the values it was suggested on.

The booleans alone are unreviewable. amount_match=True asks the operator to confirm a link while withholding the two amounts that supposedly match, and amount_match=False is worse: it reports a disagreement without saying between what and what. A suggestion is a claim the operator is meant to ADJUDICATE, and adjudicating it means seeing both sides.

Both values are local records the session is already authenticated for, and both are in scope where the suggestion is built – they were being discarded, not protected.

Parameters:

data (Any)

invoice_id: InvoiceId
transaction_id: TransactionId
amount_match: bool
counterparty_match: bool
score: str
invoice_total: str
transaction_amount: str
invoice_counterparty: str
transaction_counterparty: str
class LedgerLinkInconsistencyRefV1(**data)[source]

Bases: BaseModel

Safe coordinate for one inconsistent local invoice/entry link.

Parameters:

data (Any)

invoice_id: str
transaction_id: TransactionId
direction: str
class LedgerAffectedDeclarationRefV1(**data)[source]

Bases: BaseModel

Natural declaration address whose sealed revision has Ledger drift.

Parameters:

data (Any)

modelo: ModeloCode
filing_year: FilingYear
period: Period
calculation_revision_id: CalculationRevisionId
changed_count: NonNegativeInt
removed_count: NonNegativeInt
class LedgerWorkspaceProjectionV1(**data)[source]

Bases: BaseModel

Serializable safe index over one preloaded local Ledger snapshot.

Parameters:

data (Any)

contract_version: int
bucket_id: str
areas: tuple[LedgerWorkspaceAreaStateV1, ...]
entries: tuple[LedgerWorkspaceEntryRefV1, ...]
review_transaction_ids: tuple[TransactionId, ...]
invoice_reconciliations: tuple[LedgerInvoiceReconciliationRefV1, ...]
affected_declarations: tuple[LedgerAffectedDeclarationRefV1, ...]
class LedgerFilingStalenessReaderProtocol(*args, **kwargs)[source]

Bases: Protocol

Pure injected reader for sealed-revision Ledger staleness.

class LedgerInvoiceReconciliationReaderProtocol(*args, **kwargs)[source]

Bases: Protocol

Pure injected reader for local invoice/entry match suggestions.

class LedgerLinkConsistencyReaderProtocol(*args, **kwargs)[source]

Bases: Protocol

Pure injected reader for local bidirectional-link consistency.

project_affected_declaration_reconciliations(*, bucket_id, revisions, transactions, work_units, staleness_reader=<function _canonical_filing_staleness_reader>)[source]

Project local Ledger drift onto natural declaration addresses.

Every input is preloaded. Missing or cross-bucket declaration identity is refused instead of silently dropping an affected revision.

Core types: CalculationRevision, TransactionCatalogue.

Return type:

tuple[LedgerAffectedDeclarationRefV1, ...]

Parameters:
project_ledger_workspace(*, summary, preflight, review, transactions, invoices, revisions, work_units, evidence_pending_review, last_import_count, invoice_reconciliation_reader=<function suggest_reconciliations>, link_consistency_reader=<function verify_link_consistency>, filing_staleness_reader=<function _canonical_filing_staleness_reader>)[source]

Build one deterministic, frontend-neutral snapshot from canonical facts.

Core types: CalculationRevision, InvoiceCatalogue, TransactionCatalogue.

Return type:

LedgerWorkspaceProjectionV1

Parameters: