cadrumo.application.aeat_sync.workspace module

Safe immutable projection for the six-zone AEAT Sync workspace.

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

Bases: CadrumoError

Already-loaded authorities cannot form one safe snapshot.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
class AeatSyncWorkspaceZone(*values)[source]

Bases: StrEnum

Closed workspace areas.

OVERVIEW
CENSUS
FILED_DECLARATIONS
NOTIFICATIONS
EVIDENCE_COMPARISON
RECONCILIATION
class AeatSyncWorkspaceSource(*values)[source]

Bases: StrEnum

Canonical local and AEAT source authorities.

LOCAL_PROFILE
LOCAL_FILINGS
LOCAL_NOTIFICATION_CUSTODY
LOCAL_RECONCILIATION
AEAT_CENSUS
AEAT_FILED_DECLARATIONS
AEAT_NOTIFICATIONS
class AeatSyncWorkspaceAvailability(*values)[source]

Bases: StrEnum

Availability and freshness of one source observation.

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

Bases: StrEnum

Safe observed state of one comparison side.

NOT_OBSERVED
ABSENT
PRESENT
ACCEPTED
REJECTED
CONFLICT
class AeatSyncDiscrepancyKind(*values)[source]

Bases: StrEnum

Closed comparison outcomes.

NONE
LOCAL_ONLY
AEAT_ONLY
STATE_MISMATCH
CONTRADICTORY_SOURCE
UNOBSERVED
class AeatSyncOverviewArea(*values)[source]

Bases: StrEnum

Closed overview areas.

CENSUS
FILED_DECLARATIONS
NOTIFICATIONS
EVIDENCE_COMPARISON
RECONCILIATION
class AeatSyncCensusCategory(*values)[source]

Bases: StrEnum

The censo field families a census row is grouped under.

ADDRESS
ACTIVITY
OBLIGATION
CONTACT
OTHER
class AeatSyncCensusStatus(*values)[source]

Bases: StrEnum

The census comparison verdicts, plus the state of having none yet.

The first four are VERDICTS: each claims someone compared the local censo field against the AEAT one and says how they came out. NOT_COMPARED claims the opposite – that nobody has looked at the AEAT side at all – and exists because before a pull there is no honest verdict to give. Made to reuse one of the four, a pre-pull row would have to assert a comparison that never happened; UNSET in particular says the field HAS no value, which is a statement about the value rather than about whether anyone checked.

ADOPTED
CONFLICT
UNCHANGED
UNSET
NOT_COMPARED
COMPARED_CENSUS_STATUSES: Final

The census statuses that assert a comparison against the AEAT actually ran.

class AeatSyncLocalFilingState(*values)[source]

Bases: StrEnum

Local filing states.

NOT_OBSERVED
DRAFT
READY
FILED
class AeatSyncAeatObservationState(*values)[source]

Bases: StrEnum

AEAT declaration observation states.

NOT_OBSERVED
SUBMITTED
ACCEPTED
REJECTED
class AeatSyncJustificanteState(*values)[source]

Bases: StrEnum

Justificante availability states.

NOT_OBSERVED
UNAVAILABLE
AVAILABLE
VERIFIED
class AeatSyncNotificationCategory(*values)[source]

Bases: StrEnum

The notification families the AEAT distinguishes.

FORMAL
COMMUNICATION
PENDING
OTHER
class AeatSyncNotificationReadState(*values)[source]

Bases: StrEnum

Notification read states.

UNKNOWN
UNREAD
READ
class AeatSyncDocumentCustodyState(*values)[source]

Bases: StrEnum

Encrypted document custody states.

NOT_CAPTURED
HELD
REFUSED
UNAVAILABLE
class AeatSyncReconciliationState(*values)[source]

Bases: StrEnum

Closed reconciliation outcomes.

UNRESOLVED
KEEP_LOCAL
ACCEPT_AEAT
DISMISSED
NO_ACTION
class AeatSyncWorkspaceSourceObservationV1(**data)[source]

Bases: BaseModel

One authority’s independent availability/freshness/count axis.

Parameters:

data (Any)

source: AeatSyncWorkspaceSource
availability: AeatSyncWorkspaceAvailability
observed_at: UtcInstant | None
refusal: NamespacedId | None
item_count: NonNegativeInt | None
class AeatSyncWorkspaceZoneObservationV1(**data)[source]

Bases: BaseModel

Independent source observations for one zone.

Parameters:

data (Any)

zone: AeatSyncWorkspaceZone
sources: tuple[AeatSyncWorkspaceSourceObservationV1, ...]
class AeatSyncWorkspaceZoneStateV1(**data)[source]

Bases: BaseModel

Projected zone state retaining its independent sources.

Parameters:

data (Any)

zone: AeatSyncWorkspaceZone
availability: AeatSyncWorkspaceAvailability
sources: tuple[AeatSyncWorkspaceSourceObservationV1, ...]
item_count: NonNegativeInt | None
class AeatSyncWorkspaceActionRowV1(**data)[source]

Bases: BaseModel

Public immutable capability provenance shared by every workspace row.

Parameters:

data (Any)

supported_actions: tuple[ActionReference, ...]
supported_operations: tuple[OperationDefinitionId, ...]
class AeatSyncWorkspaceOverviewRowV1(**data)[source]

Bases: AeatSyncWorkspaceActionRowV1

One area’s local-versus-AEAT standing, with the actions it admits.

Parameters:
area: AeatSyncOverviewArea
local_state: AeatSyncSourceState
aeat_state: AeatSyncSourceState
local_observed_at: UtcInstant | None
aeat_observed_at: UtcInstant | None
discrepancy_kind: AeatSyncDiscrepancyKind
class AeatSyncWorkspaceCensusRowV1(**data)[source]

Bases: AeatSyncWorkspaceActionRowV1

One census field’s local-versus-AEAT status.

Carries no value yet, and the docstring no longer claims that as a safety property: it is a GAP. Nothing produces these rows outside fixtures, and their AEAT side stays never-captured until a pull happens, so there is no captured value to carry. When a producer exists the values belong here, on the same reasoning as every other authenticated surface.

Parameters:
path: str
category: AeatSyncCensusCategory
status: AeatSyncCensusStatus
local_value: str | None

What the local profile holds for this field, or nothing when unobserved.

aeat_value: str | None

What the AEAT censo holds, or nothing when no pull has observed it.

None on either side is UNOBSERVED, never an empty field. A censo entry the taxpayer has genuinely left blank is the empty string, and collapsing the two would tell an operator AEAT holds nothing where in truth nobody has looked – which is the difference between “correct” and “unchecked” on a comparison whose entire purpose is to show what differs.

class AeatSyncWorkspaceFiledDeclarationRowV1(**data)[source]

Bases: AeatSyncWorkspaceActionRowV1

One declaration this profile filed, against what the AEAT shows for it.

Parameters:
modelo: ModeloCode
filing_year: FilingYear
period: Period
local_filing_state: AeatSyncLocalFilingState
local_filed_at: UtcInstant | None
aeat_observation_state: AeatSyncAeatObservationState
aeat_observed_at: UtcInstant | None
justificante_state: AeatSyncJustificanteState
justificante_observed_at: UtcInstant | None
property aeat_submission_state: AeatSyncAeatObservationState

Return the AEAT declaration state.

class AeatSyncWorkspaceNotificationRowV1(**data)[source]

Bases: BaseModel

One notification’s metadata, and the coordinate that opens its document.

selection_key is populated only by project_aeat_sync_workspace(). An admission row may leave it absent; the projector always replaces it from the fact’s private coordinate before exposing the row publicly.

Parameters:

data (Any)

issued_on: date
read_on: date | None
read_state: AeatSyncNotificationReadState
category: AeatSyncNotificationCategory
document_custody_state: AeatSyncDocumentCustodyState
document_custody_observed_at: UtcInstant | None
selection_key: AeatSyncNotificationSelectionKey | None
property issue_date: date

Return the notification issue date.

class AeatSyncWorkspaceEvidenceComparisonRowV1(**data)[source]

Bases: _DualRow

One declaration figure as the local record holds it and as the AEAT shows it.

Parameters:
class AeatSyncWorkspaceReconciliationRowV1(**data)[source]

Bases: _DualRow

One reconciliation item, its two sides and how it was resolved.

Parameters:
reconciliation_state: AeatSyncReconciliationState
class AeatSyncWorkspaceFactV1(bucket_id, subject_key, row, private_identity=None)[source]

Bases: Generic

Admission-only scope/private identity projected away from row.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • subject_key (str)

  • row (RowT)

  • private_identity (str | None)

bucket_id: Annotated[str]
subject_key: str
row: TypeVar(RowT, bound= BaseModel)
private_identity: str | None
class AeatSyncWorkspaceProjectionV1(**data)[source]

Bases: BaseModel

Public result, physically free of protected admission fields.

Parameters:

data (Any)

contract_version: int
zones: tuple[AeatSyncWorkspaceZoneStateV1, ...]
overview: tuple[AeatSyncWorkspaceOverviewRowV1, ...]
census: tuple[AeatSyncWorkspaceCensusRowV1, ...]
filed_declarations: tuple[AeatSyncWorkspaceFiledDeclarationRowV1, ...]
notifications: tuple[AeatSyncWorkspaceNotificationRowV1, ...]
evidence_comparison: tuple[AeatSyncWorkspaceEvidenceComparisonRowV1, ...]
reconciliation: tuple[AeatSyncWorkspaceReconciliationRowV1, ...]
aeat_sync_workspace_sources(zone)[source]

Return the canonical independent sources required by one zone.

Return type:

tuple[AeatSyncWorkspaceSource, ...]

Parameters:

zone (AeatSyncWorkspaceZone)

notification_selection_key(private_identity)[source]

Derive a process-stable public focus key without retaining private data.

Return type:

TypeAliasType

Parameters:

private_identity (str)

public_notification_row(row, selection_key)[source]

Rebuild one notification row and inject only its safe selection key.

Return type:

AeatSyncWorkspaceNotificationRowV1

Parameters:
source_observation_is_observable(value)[source]

Return whether a source has an observation that can support a claim.

Return type:

bool

Parameters:

value (AeatSyncWorkspaceAvailability)

project_aeat_sync_workspace(**arguments)[source]

Project already-loaded, scoped facts through the single projection owner.

Return type:

AeatSyncWorkspaceProjectionV1

Parameters:

arguments (Unpack[_AeatSyncWorkspaceProjectionArguments])