cadrumo.application.live.filed_observation_ports module

Application-owned ports for filed-observation persistence.

The filed-history use case consumes an authenticated declaration observation, turns it into calculation evidence, and records the resulting local evidence. This module names the small surfaces that use case needs. Sede readers, receipt parsers, and encrypted repositories are composed outside the application layer and implement these ports there.

Core types: ModeloRecord.

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

Bases: Protocol

The captured artefact facts read by persistence and receipt matching.

property kind: str

Return the captured artefact kind.

property source_url: object

Return the source URL associated with the artefact.

property byte_count: int

Return the byte count recorded in the manifest.

property sha256: str

Return the manifest SHA-256 digest.

property captured_at: datetime

Return the capture timestamp.

property storage_ref: str | None

Return the encrypted storage reference, when persisted.

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

Bases: Protocol

The observed casilla facts used by baseline and skip projections.

property casilla_id: str

Return the observed casilla identifier.

property value: str

Return the observed lexical value.

property value_kind: CasillaValueKind

Return the parser’s value-kind classification.

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

Bases: Protocol

Application view of one authenticated filed declaration observation.

property modelo: str

Return the declaration modelo code.

property ejercicio: int

Return the declaration filing year.

property period: Period

Return the declaration fiscal period.

property expediente_id: str

Return the Sede expediente identifier.

property status: str

Return the register status.

property presented_at: datetime

Return the filing presentation timestamp.

property authenticated_identity: str

Return the authenticated taxpayer identity token.

property artefacts: Sequence[FiledObservationArtefactProtocol]

Return the captured artefact manifest.

property casillas: Sequence[FiledObservedCasillaProtocol]

Return observed casilla values.

property headers: tuple[ObservedHeaderFact, ...]

Return typed submitted-file header facts.

property metadata: Mapping[str, str]

Return untyped register provenance metadata.

property registry_snapshot_ref: RegistrySnapshotRef

Return the registry revision selected for this observation.

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

Bases: Protocol

Period-bearing register row facts used for latest-row selection.

property modelo: str

Return the declaration modelo code.

property period: Period

Return the declaration period.

property expediente_id: str

Return the Sede expediente identifier.

property estado: str

Return the register declaration status.

property presented_at: datetime

Return the declaration presentation timestamp.

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

Bases: Protocol

Non-numeric casilla projection returned for the operator report.

property casilla_id: str

Return the skipped casilla identifier.

property label: str

Return the operator-facing casilla label.

property value_kind: CasillaValueKind

Return the skipped value-kind classification.

property reason: str

Return the reason the casilla was skipped.

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

Bases: Protocol

Parse receipt bytes and recover the independent AEAT CSV witness.

parse_justificante(body)[source]

Parse receipt bytes into domain justificante metadata.

Return type:

Justificante

Parameters:

body (bytes)

csv_from_source_url(source_url)[source]

Recover the independent CSV witness from a source URL.

Return type:

str

Parameters:

source_url (str)

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

Bases: Protocol

Translate filed evidence into application/domain projections.

registry_observation(observation)[source]

Translate one filed observation into a registry-grounded row.

Return type:

RegistryModeloObservation

Parameters:

observation (FiledObservationProtocol)

non_numeric_casillas(observation)[source]

Return non-numeric casillas for the operator skip report.

Return type:

Sequence[FiledObservationSkipProtocol]

Parameters:

observation (FiledObservationProtocol)

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

Bases: Protocol

Encrypted custody of captured observation manifests and artefacts.

persist_observation(observation)[source]

Persist an observation manifest and return its logical path.

Return type:

Path

Parameters:

observation (FiledObservationProtocol)

persist_artefact(observation_key, artefact, body)[source]

Persist artefact bytes and return the manifest with its storage reference.

Return type:

FiledObservationArtefactProtocol

Parameters:
load_artefact(storage_ref)[source]

Load plaintext bytes addressed by an encrypted storage reference.

Return type:

bytes

Parameters:

storage_ref (str)

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

Bases: Protocol

Calculation-observation repository operations used by this capability.

load_observation(modelo, period)[source]

Load one existing calculation-observation envelope before replacement.

Return type:

ObservationEnvelopePayload | None

Parameters:
prepare_observation_envelope(observation, *, source_kind, stamped_revision_id, captured_at=None, source_metadata=None, source_headers=())[source]

Build a validated calculation-observation envelope.

Return type:

ObservationEnvelopePayload

Parameters:
save(payload)[source]

Persist a prepared calculation-observation envelope.

Return type:

None

Parameters:

payload (ObservationEnvelopePayload)

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

Bases: Protocol

Read the persisted IVA history row after a M303 co-commit.

load_period(period)[source]

Load one persisted IVA compensation history period.

Return type:

IvaCompensationPeriodState | None

Parameters:

period (Period)

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

Bases: Protocol

Atomically persist a calculation envelope and its M303 history state.

persist(*, observation_repository, history_repository, envelope, taxpayer_nif, source_observation_key, expediente_id, status, source_artefact_sha256)[source]

Atomically persist the calculation envelope and IVA history state.

Return type:

IvaCompensationPeriodState

Parameters:
class FiledFilingReconciliationPort(*args, **kwargs)[source]

Bases: Protocol

Apply one AEAT register entry to the filing chain of its period.

reconcile(entry, *, actor, clock)[source]

Reconcile entry and return the chain decision.

Return type:

FilingReconciliationResult

Parameters:
class FiledObservationPersistencePorts(parser, transformation, observation_persistence, calculation_repository, iva_history_repository, iva_observation_persistence, justificante_repository, filing_repository, bucket_event_repository, filing_reconciliation)[source]

Bases: object

Immutable dependency bundle for the filed-observation capability.

Parameters:
parser: FiledObservationParserPort
transformation: FiledDeclarationTransformationPort
observation_persistence: FiledObservationPersistencePort
calculation_repository: FiledCalculationObservationRepositoryPort
iva_history_repository: FiledIvaHistoryRepositoryPort
iva_observation_persistence: FiledIvaObservationPersistencePort
justificante_repository: JustificanteRepositoryProtocol
filing_repository: ModeloRecordCatalogueRepositoryProtocol
bucket_event_repository: BucketEventHistoryRepositoryProtocol
filing_reconciliation: FiledFilingReconciliationPort