cadrumo.application.modelo.declarations_workspace module

Pure, frontend-neutral projection for the Declarations workspace.

Callers preload the secure Modelo catalogues and provide explicit source observations. This module validates their joins and projects only natural declaration coordinates, lifecycle states, and non-sensitive timestamps. It does not resolve repositories, contact AEAT, or retain financial/evidence payloads for serialization.

Core types: CalculationRevision, ModeloRecord.

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

Bases: CadrumoError

The supplied authorities cannot form one coherent safe snapshot.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
class DeclarationsWorkspaceZone(*values)[source]

Bases: StrEnum

Exact read areas owned by the Declarations landing.

DECLARATIONS
CALCULATION_REVISIONS
FILING_HISTORY
class DeclarationsWorkspaceSource(*values)[source]

Bases: StrEnum

Canonical source axes retained by the projection.

LOCAL_DECLARATIONS
LOCAL_CALCULATIONS
LOCAL_FILINGS
LOCAL_LIFECYCLE
AEAT_EVIDENCE
class DeclarationsWorkspaceAvailability(*values)[source]

Bases: StrEnum

Whether a source snapshot can make an authoritative claim.

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

Bases: StrEnum

Sanitized lifecycle meanings accepted by the workspace projection.

VERIFICATION_REFUSED exists because a refusal has nowhere else honest to go. Without it a surface reading the kind alone would either drop the event, which turns a refusal into an absence, or fold it into VERIFIED, which reports a refused verification as a passed one.

CREATED
RENAMED
CALCULATED
VERIFIED
VERIFICATION_REFUSED
FILED
SUPERSEDED
AMENDED
DISCARDED
EXTERNAL_EVIDENCE_IMPORTED
EXPORTED
RECONCILED
OBSERVATION_OVERRIDDEN
OBSERVATION_OVERRIDE_CLEARED
class DeclarationsWorkspaceZoneObservationV1(**data)[source]

Bases: BaseModel

Caller-observed availability before any rows are projected.

Parameters:

data (Any)

zone: DeclarationsWorkspaceZone
availability: DeclarationsWorkspaceAvailability
observed_at: UtcInstant | None
reason_code: NamespacedId | None
class DeclarationsWorkspaceZoneStateV1(**data)[source]

Bases: DeclarationsWorkspaceZoneObservationV1

One zone’s authority, freshness, and measured cardinality.

Parameters:
sources: tuple[DeclarationsWorkspaceSource, ...]
item_count: NonNegativeInt | None
class DeclarationsWorkspaceDeclarationRefV1(**data)[source]

Bases: BaseModel

Safe natural coordinate for one local declaration.

Parameters:

data (Any)

work_unit_id: WorkUnitId
modelo: ModeloCode
filing_year: FilingYear
period: Period
state: WorkUnitState
has_current_calculation: bool
has_current_filing: bool
settled_result: str | None

The declaration’s own settled figure, when the registry grounds one.

None means the answer is UNKNOWN, and a surface must render it that way rather than as a blank or a zero. Three distinct situations reach it, and none of them is “the result is nothing”: the modelo’s settlement chain is not modelled (303 and 130 today declare no result role at all), no current calculation exists yet, or the calculation exists and has not computed that cell.

class DeclarationsWorkspaceCalculationRevisionRefV1(**data)[source]

Bases: BaseModel

Safe state reference for one calculation version.

Parameters:

data (Any)

calculation_revision_id: CalculationRevisionId
work_unit_id: WorkUnitId
modelo: ModeloCode
filing_year: FilingYear
period: Period
state: CalculationRevisionState
created_at: UtcInstant
updated_at: UtcInstant
is_current: bool
is_filed: bool
class DeclarationsWorkspaceFilingRefV1(**data)[source]

Bases: BaseModel

One chain entry: local currency, origin, AEAT confirmation and correction link.

Parameters:

data (Any)

filing_record_id: FilingRecordId
work_unit_id: WorkUnitId
calculation_revision_id: CalculationRevisionId
modelo: ModeloCode
filing_year: FilingYear
period: Period
filed_at: UtcInstant
local_status: ModeloRecordStatus
origin: FilingOrigin
confirmation: AeatConfirmationState
declaration_kind: FilingDeclarationKind
amends_filing_record_id: FilingRecordId | None
evidence_kind: ExternalEvidenceKind | None
property aeat_accepted: bool

Return whether AEAT has been observed to hold this entry.

property amends_prior_entry: bool

Return whether this entry corrects an earlier declaration of its period.

class DeclarationsSanitizedLifecycleFactV1(**data)[source]

Bases: BaseModel

Payload-free lifecycle fact supplied by an application authority.

Parameters:

data (Any)

fact_id: str
work_unit_id: WorkUnitId
occurred_at: UtcInstant
kind: DeclarationsLifecycleKind
class DeclarationsWorkspaceLifecycleRefV1(**data)[source]

Bases: BaseModel

Sanitized lifecycle fact joined to its natural declaration address.

Parameters:

data (Any)

fact_id: str
work_unit_id: WorkUnitId
modelo: ModeloCode
filing_year: FilingYear
period: Period
occurred_at: UtcInstant
kind: DeclarationsLifecycleKind
class DeclarationsWorkspaceProjectionV1(**data)[source]

Bases: BaseModel

Immutable safe index over one coherent preloaded Declarations snapshot.

Parameters:

data (Any)

contract_version: int
bucket_id: BucketId
zones: tuple[DeclarationsWorkspaceZoneStateV1, ...]
declarations: tuple[DeclarationsWorkspaceDeclarationRefV1, ...]
calculation_revisions: tuple[DeclarationsWorkspaceCalculationRevisionRefV1, ...]
filings: tuple[DeclarationsWorkspaceFilingRefV1, ...]
lifecycle: tuple[DeclarationsWorkspaceLifecycleRefV1, ...]
project_declarations_workspace(*, operation, bucket_id, work_units, calculation_revisions, filing_records, lifecycle_facts, zone_observations, result_casilla_reader=None)[source]

Validate and safely project already-loaded local authorities.

Return type:

DeclarationsWorkspaceProjectionV1

Parameters:
DeclarationResultCasillaReaderV1

Names the casilla that settles one modelo revision, or nothing.

Injected rather than resolved here: this module joins already-loaded local authorities and holds no registry access, and giving it some would put registry loading inside a projection that is meant to be a pure join.

alias of Callable[[ModeloCode, int, Period], str | None]

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

Bases: Protocol

The work-unit surface _settled_result() actually reads.

Declared structurally so the reader’s contract is the four attributes it consumes rather than the whole WorkUnit aggregate. A caller that can supply a modelo, year, period and current calculation id is a valid argument, which is what the settlement tests exercise.

property modelo: ModeloCode
property filing_year: Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])]
property period: Period
property current_calculation_revision_id: str | None
class SettledResultRevisionV1(*args, **kwargs)[source]

Bases: Protocol

The calculation-revision surface _settled_result() actually reads.

property casilla_values: Mapping[CasillaId, Decimal]