cadrumo.application.live.remote_state_models module

Typed report models for live AEAT filed-data and IVA remote-state services.

These frozen records are renderer-facing summaries, not raw evidence stores. They carry typed Period values, secure-storage references, redacted diagnostic fields, and counts/ids needed by CLI and workflow surfaces after live capture has persisted the underlying observations.

See also

cadrumo.application.live.remote_state_models.IvaRemoteStateAcquisitionReport

Combined read-only IVA remote-state acquisition result.

class FiledCaptureEvidenceTally(**data)[source]

Bases: BaseModel

What one filed-declaration capture produced, counted and referenced.

Every filed-declaration capture report — single, bulk, and source-scoped — reports the same tally: how many observations were captured, where their encrypted stores and artefacts live, how much justificante and filing-evidence metadata was enrolled (including conflicts), and how many casillas and calculation observations came back.

Declared once so the three reports cannot drift apart. A counter added to one report but forgotten on another would leave that capture path silently under-reporting its own evidence, which is precisely the divergence a single declaration prevents.

Parameters:

data (Any)

captured_count: int
reached_count: int

Units REACHED, counted in every mode. captured_count is the persisted-path tally and a preview leaves it at zero, so only this one can answer whether a limited sweep was truncated.

observation_paths: tuple[str, ...]
artefact_refs: tuple[str, ...]
justificante_metadata_count: int
justificante_csvs: tuple[str, ...]
filing_evidence_stamped_count: int
filing_record_ids: tuple[str, ...]
filing_evidence_conflict_count: int
filing_evidence_conflict_record_ids: tuple[str, ...]
evidence_notices: tuple[Notice, ...]

Per-observation capture advisories, each retaining the concrete cause.

These are internal capture-report transport, not a command result payload: CLI entrypoints forward them on the shared envelope notices channel. Keeping the lane on the shared tally means single, bulk, and source capture cannot silently diverge.

casilla_count: int
calculation_observation_count: int
calculation_observation_keys: tuple[str, ...]
reconciliation_results: tuple[FilingReconciliationResult, ...]

One filing-chain decision per reconciled AEAT register entry, in capture order.

class FiledDataCaptureReport(**data)[source]

Bases: FiledCaptureEvidenceTally

Read-only filed-declaration capture report.

Parameters:
output_root: str
modelo: str
year: int
class FiledDataCaptureFailureRow(**data)[source]

Bases: BaseModel

One failed filed-declaration capture attempt in a bulk run.

Parameters:

data (Any)

modelo: str
year: int
period: Period | None
expediente_id: AeatExpedienteId | None
error_type: str
message: str
class FiledCasillaSkipRow(**data)[source]

Bases: BaseModel

One casilla a filing carries that the registry channel cannot read.

Sibling of FiledDataCaptureFailureRow and keyed the same way, but a different kind of event: the capture succeeded and this row says what the artefact holds that could not be enrolled as an amount. A failure row says the capture did not happen.

Carries no value, by the same rule as ObservedCasillaSkip: these casillas are the non-numeric ones, which include a referencia catastral and the taxpayer’s address, and this row is built to be rendered.

Parameters:

data (Any)

modelo: str
year: int
period: Period | None
expediente_id: AeatExpedienteId | None
casilla_id: str
label: str
value_kind: str
reason: str
class BulkFiledDataCaptureReport(**data)[source]

Bases: FiledCaptureEvidenceTally

Read-only bulk filed-declaration capture report.

Parameters:
output_root: str
modelos: tuple[str, ...]
year_from: int
year_to: int
failed_count: int
sync_run_ref: SyncRunRecordReference | None
failures: tuple[FiledDataCaptureFailureRow, ...]
skipped_casillas: tuple[FiledCasillaSkipRow, ...]
recapture_notices: tuple[Notice, ...]

One advisory per re-captured filing whose casilla values this sweep changed, read before each upsert while the prior values still existed.

dry_run: bool

it read AEAT and computed the recapture advisories above, and wrote nothing.

Type:

True when the sweep ran as a preview

class ExpedientesBulkCaptureFailureRow(**data)[source]

Bases: BaseModel

One failed expedientes register walk in a bulk run.

Parameters:

data (Any)

modelo: str
year: int
error_type: str
message: str
class ExpedientesBulkCaptureReport(**data)[source]

Bases: BaseModel

Read-only bulk expedientes snapshot capture report.

Parameters:

data (Any)

bucket_id: BucketId
modelos: tuple[str, ...]
year_from: int
year_to: int
captured_snapshot_count: int
declaration_count: int
snapshot_ids: tuple[str, ...]
failures: tuple[ExpedientesBulkCaptureFailureRow, ...]
class SourceFiledDataCaptureReport(**data)[source]

Bases: FiledCaptureEvidenceTally

Read-only source-observation capture report for one target filing.

Parameters:
output_root: str
target_modelo: str
target_year: int
target_period: Period
class IvaWalletCaptureReport(**data)[source]

Bases: BaseModel

Read-only IVA compensation wallet capture report.

Parameters:

data (Any)

taxpayer_ref: str
target_year: int
target_period: Period
observation_path: str
decision_key: str
row_count: int
total_pending: str
selected_authority: str
selected_amount: str | None
local_recurrence_amount: str | None
divergence: str
blocked: bool
captured_at: datetime
class IvaCompensationHistoryRow(**data)[source]

Bases: BaseModel

One secure stored Modelo 303 IVA compensation history row.

Parameters:

data (Any)

year: int
period: Period
provenance: IvaCompensationStateProvenance
register_status: str | None
presented_at: datetime
prior_pending_amount: str | None
applied_amount: str | None
pending_for_later_amount: str | None
period_result_amount: str | None
final_result_amount: str | None
generated_amount: str
available_end_amount: str
class IvaCompensationCarryForwardLotRow(**data)[source]

Bases: BaseModel

One CLI-safe IVA compensation carry-forward lot.

Parameters:

data (Any)

taxpayer_ref: str
source_filing_year: int
source_period: Period
generated_amount: str
applied_amount: str
remaining_amount: str
age_years: int
expiry_review_state: str
source_observation_key: str
class IvaWalletAuthorityDecisionRow(**data)[source]

Bases: BaseModel

One persisted wallet/local/override authority decision for CLI display.

Parameters:

data (Any)

taxpayer_ref: str
target_year: int
target_period: Period
selected_authority: str
selected_amount: str | None
wallet_amount: str | None
local_recurrence_amount: str | None
override_amount: str | None
divergence: str
blocked: bool
stale_wallet: bool
reason_identity: IvaCompensationDecisionReason
operator_explanation: str | None
wallet_captured_at: datetime | None
decided_at: datetime
authority_sources: tuple[str, ...]
class IvaCompensationHistoryReport(**data)[source]

Bases: BaseModel

Profile-local IVA compensation history report.

Parameters:

data (Any)

row_count: int
rows: tuple[IvaCompensationHistoryRow, ...]
as_of_year: int
carry_forward_lot_count: int
carry_forward_lots: tuple[IvaCompensationCarryForwardLotRow, ...]
unallocated_applied_amount: str
authority_decision_count: int
authority_decisions: tuple[IvaWalletAuthorityDecisionRow, ...]
class IvaCompensationHistoryCaptureReport(**data)[source]

Bases: BaseModel

Read-only multi-year Modelo 303 IVA compensation history capture report.

Parameters:

data (Any)

output_root: str
year_from: int
year_to: int
captured_count: int
observation_paths: tuple[str, ...]
artefact_refs: tuple[str, ...]
casilla_count: int
calculation_observation_count: int
calculation_observation_keys: tuple[str, ...]
reloaded_history_count: int
reloaded_rows: tuple[IvaCompensationHistoryRow, ...]
failed_declaration_count: int
failed_declarations: tuple[str, ...]
class LiveIvaReadSurface(*values)[source]

Bases: StrEnum

Read-only IVA remote-state surfaces acquired from AEAT.

FILED_HISTORY
WALLET_CARTERA
class LiveIvaReadStatus(*values)[source]

Bases: StrEnum

Per-surface outcome for one live IVA read attempt.

SUCCEEDED
FAILED
class LiveIvaReadOutcome(**data)[source]

Bases: BaseModel

Redacted per-surface acquisition outcome.

Parameters:

data (Any)

surface: LiveIvaReadSurface
status: LiveIvaReadStatus
outcome_mode: LiveIvaAcquisitionFailureMode
failure_mode: LiveIvaAcquisitionFailureMode | None
failure_type: str | None
failure_context: dict[str, object] | None
captured_count: int | None
calculation_observation_count: int | None
class LiveIvaAuthOutcome(**data)[source]

Bases: BaseModel

Redacted authentication outcome for a live IVA acquisition.

Parameters:

data (Any)

status: LiveIvaReadStatus
outcome_mode: LiveIvaAcquisitionFailureMode
failure_mode: LiveIvaAcquisitionFailureMode | None
failure_type: str | None
diagnostic_ref: LiveIvaDiagnosticRef | None
provider_kind: str | None
reused_persisted_session: bool | None
fresh: bool | None
class IvaRemoteStateAcquisitionReport(**data)[source]

Bases: BaseModel

Combined read-only IVA remote-state acquisition report.

Parameters:

data (Any)

acquisition_manifest_id: str | None
output_root: str
year_from: int
year_to: int
target_year: int
target_period: Period
auth: LiveIvaAuthOutcome
filed_history: IvaCompensationHistoryCaptureReport | None
wallet: IvaWalletCaptureReport | None
outcomes: tuple[LiveIvaReadOutcome, ...]
property filed_history_succeeded: bool

Return True when the filed-history surface outcome is SUCCEEDED.

property wallet_succeeded: bool

Return True when the wallet-cartera surface outcome is SUCCEEDED.

class IvaRemoteStateAcquisitionSurfaceManifest(**data)[source]

Bases: BaseModel

One persisted redacted surface outcome from a live IVA acquisition.

Parameters:

data (Any)

surface: LiveIvaReadSurface
status: LiveIvaReadStatus
outcome_mode: LiveIvaAcquisitionFailureMode
failure_mode: LiveIvaAcquisitionFailureMode | None
failure_type: str | None
failure_context: dict[str, object] | None
captured_count: int | None
calculation_observation_count: int | None
reloaded_history_count: int | None
wallet_row_count: int | None
decision_ref: str | None
selected_authority: str | None
divergence: str | None
blocked: bool | None
class IvaRemoteStateAcquisitionManifest(**data)[source]

Bases: BaseModel

Encrypted profile-local manifest for one read-only live IVA acquisition.

Parameters:

data (Any)

acquisition_id: str
captured_at: datetime
year_from: int
year_to: int
target_year: int
target_period: Period
auth: LiveIvaAuthOutcome
filed_history_succeeded: bool
wallet_succeeded: bool
surfaces: tuple[IvaRemoteStateAcquisitionSurfaceManifest, ...]