cadrumo.application.modelo.m145_communication_records module

Modelo 145 local communication record creation and read-back.

This module owns the bucket-local record lifecycle for the Modelo 145 payer communication workflow. It validates operator-provided casilla values against the active registry revision, persists the local record, renders the official export layout, and records delivery/completion transitions without creating an AEAT filing path.

See also

m145_communication

Focused ownership contract consumed by this record service.

build_m145_communication_service_contract()

Registry-backed ownership contract that refuses filing-like surfaces.

M145CommunicationCreateCommand

Strict create-command DTO consumed by create_m145_communication_record().

M145CommunicationRecord

Persisted bucket-local communication record handled by this module.

M145CommunicationValidationResult

Validation result returned before export and on explicit validation.

ModeloRevision

Registry revision whose casillas, legal refs, source refs, and export layouts ground every record and rendered payload.

RegistrySnapshot

Snapshot wrapper resolved before create, validate, and export work.

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

Bases: ModeloError

Base error for Modelo 145 local communication service failures.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

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

Bases: M145CommunicationServiceError

Raised when a Modelo 145 communication record lookup targets no record.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

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

Bases: M145CommunicationServiceError

Raised when a Modelo 145 communication record prefix matches multiple records.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

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

Bases: M145CommunicationServiceError

Raised when a Modelo 145 communication operation is blocked by validation.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

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

Bases: M145CommunicationServiceError

Raised when a Modelo 145 communication export cannot be rendered.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

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

Bases: M145CommunicationServiceError

Raised when a Modelo 145 communication state transition is not allowed.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
class M145CommunicationRecordState(*values)[source]

Bases: StrEnum

Creation-state vocabulary for local Modelo 145 communication records.

CREATED
DELIVERED_TO_PAYER
LOCALLY_COMPLETED
class M145CommunicationValidationIssueKind(*values)[source]

Bases: StrEnum

Closed issue vocabulary for Modelo 145 local communication validation.

REVISION_MISMATCH
SOURCE_AUTHORITY_MISMATCH
UNDECLARED_CASILLA
MISSING_REQUIRED
INVALID_VALUE
MISSING_SOURCE_AUTHORITY
UNSUPPORTED_DATA_TYPE
class M145CommunicationValidationIssue(**data)[source]

Bases: BaseModel

One registry-backed validation issue for a local communication record.

Parameters:

data (Any)

kind: M145CommunicationValidationIssueKind
casilla_id: CasillaId | None
data_type: str | None
message: str
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
class M145CommunicationValidationResult(**data)[source]

Bases: BaseModel

Registry-backed validation result for one local communication record.

Parameters:

data (Any)

schema_version: str
communication_record_id: M145CommunicationRecordId
bucket_id: BucketId
service_owner: str
modelo: str
communication_year: int
period_token: M145CommunicationPeriod
revision_id: RevisionId
valid: bool
issue_count: NonNegativeInt
issues: tuple[M145CommunicationValidationIssue, ...]
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
class M145CommunicationExportResult(**data)[source]

Bases: BaseModel

Registry-layout export payload for one local communication record.

byte_length and payload_sha256 are a RECEIPT for payload: the communication event records them, and later history is anchored on them rather than on the bytes. A receipt that does not describe its own payload is worse than no receipt, because it reads as verified provenance.

Parameters:

data (Any)

schema_version: str
communication_record_id: M145CommunicationRecordId
bucket_id: BucketId
service_owner: str
modelo: str
communication_year: int
period_token: M145CommunicationPeriod
revision_id: RevisionId
export_layout_id: str
encoding: str
record_count: int
byte_length: int
payload_sha256: ContentDigest
payload: bytes
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
class M145CommunicationCreateCommand(**data)[source]

Bases: BaseModel

Operator request to create a local Modelo 145 payer communication record.

Parameters:

data (Any)

communication_year: int
period_token: M145CommunicationPeriod
field_values: dict[CasillaId, M145CommunicationFieldValue]
note: str | None
class M145CommunicationRecord(**data)[source]

Bases: BaseModel

Persisted bucket-local Modelo 145 communication record.

Parameters:

data (Any)

communication_record_id: M145CommunicationRecordId
bucket_id: BucketId
service_owner: str
modelo: str
communication_year: int
period_token: M145CommunicationPeriod
revision_id: RevisionId
state: M145CommunicationRecordState
field_values: dict[CasillaId, M145CommunicationFieldValue]
legal_refs: tuple[str, ...]
source_refs: tuple[str, ...]
created_at: datetime
delivered_to_payer_at: datetime | None
locally_completed_at: datetime | None
note: str | None
property registry_snapshot_ref: RegistrySnapshotRef

Return the canonical coordinate represented by this record’s distributed identity fields.

property snapshot_id: str

Return the communication record id under the generic name the snapshot repository expects.

derive_m145_communication_record_id(*, bucket_id, communication_year, period_token, revision_id, field_values)[source]

Return the content-addressed id for a Modelo 145 communication record.

Return type:

str

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)])

  • communication_year (int)

  • period_token (M145CommunicationPeriod | str)

  • revision_id (RevisionId)

  • field_values (Mapping[str, str])

m145_communication_record_object_key(bucket_id, communication_record_id)[source]

Return the secure-object storage key for one Modelo 145 communication record.

Return type:

str

Parameters:

  • bucket_id (str)

  • communication_record_id (str)

read_m145_communication_record(communication_record_id, *, bucket_id, ports, operation)[source]

Return one Modelo 145 communication record by id or unambiguous prefix.

Return type:

M145CommunicationRecord

Parameters:
validate_m145_communication_record(communication_record_id, *, bucket_id, ports, operation)[source]

Validate one persisted Modelo 145 communication record against registry authority.

Return type:

M145CommunicationValidationResult

Parameters:
export_m145_communication_record(communication_record_id, *, bucket_id, renderer, ports, operation, actor='cadrumo.application.modelo')[source]

Render one Modelo 145 communication record through the registry export layout.

renderer is supplied by the composition root rather than resolved here: the fixed-width AEAT wire format is an adapter concern, and importing it from this layer is what the port exists to avoid.

Return type:

M145CommunicationExportResult

Parameters:
mark_m145_communication_record_delivered_to_payer(communication_record_id, *, bucket_id, ports, operation, actor='cadrumo.application.modelo')[source]

Mark one valid local communication record as delivered to the payer.

Return type:

M145CommunicationRecord

Parameters:
mark_m145_communication_record_locally_completed(communication_record_id, *, bucket_id, ports, operation, actor='cadrumo.application.modelo')[source]

Mark one payer-delivered local communication record as locally completed.

Return type:

M145CommunicationRecord

Parameters:
create_m145_communication_record(command, *, bucket_id, ports, operation, actor='cadrumo.application.modelo')[source]

Persist a bucket-local Modelo 145 communication record.

Creation stores the operator-provided registry casilla values as a local payer communication record. It validates that every value is keyed by a casilla declared in the active Modelo 145 registry revision, persists the local record, and emits the communication-created bucket event.

Return type:

M145CommunicationRecord

Parameters: