cadrumo.application.modelo.operation_definitions module

Registered modelo work-lifecycle operations composed from existing writers.

Each definition here supervises a lifecycle writer that already exists; none of them re-implements lifecycle policy. rename_work_unit already decides what a rename means - that a discarded unit is immutable, that the content-addressed id survives, that the catalogue and its lifecycle event co-commit - and this module’s only job is to run that decision under a recorded operation identity.

That separation is the point. An enrolment that re-derived the rules would give the supervised path different behaviour from the direct one, and the lifecycle refusal an operator sees would depend on which door they came through.

See also

rename_work_unit()

The single writer this operation supervises.

Core types: TaxpayerProfile.

MODELO_WORKSPACE_REFRESH_TARGET_SCHEMA_SUFFIX

Suffix appended to a definition id to name that enrolment’s refresh-target schema. Every Modelo enrolment binds the SAME target model, but each needs its own schema identity: the registry resolves a schema binding by scanning every registration and taking the first identity match, so one id shared across enrolments would stop that lookup being definition-scoped.

resolve_modelo_work_unit_refresh_target(terminal_receipt, /)[source]

Derive the workspace read one settled Modelo work operation invalidates.

Every definition below addresses one work unit, so the settled receipt’s subject_ref is that unit’s identifier. It is validated here rather than trusted: a subject that is not a well-formed WorkUnitId raises, and the resolving service turns that into a typed refusal instead of handing a frontend a target it cannot read.

Return type:

ModeloWorkspaceRefreshTargetV1

Parameters:

terminal_receipt (OperationTerminalReceipt)

class ModeloWorkRenameRequest(**data)[source]

Bases: CredentialFreeOperationRequest

The addressed unit and the display name to give it.

Credential-free by construction: a rename names a unit and a label, so the request carries nothing that would be unsafe to journal.

Parameters:

data (Any)

work_unit_id: _WORK_UNIT_ID
new_name: _WORK_UNIT_NAME
actor: Annotated[str, Field(min_length=1, max_length=128)]

The operator this invocation acts as. The platform binds an actor at submission, never at composition, so baking one into a definition would make the production registry per-actor.

class ModeloWorkRenamePublicResultV1(**data)[source]

Bases: BaseModel

The settled rename, as a caller outside this package may see it.

A distinct projection rather than the WorkUnit itself: the stored record carries lifecycle state a result consumer has no business depending on.

Parameters:

  • result_version (int)

  • work_unit_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='\\S')])])

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

  • bucket_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

result_version: int
work_unit_id: _WORK_UNIT_ID
name: _WORK_UNIT_NAME
bucket_id: Annotated[str, Field(min_length=1, max_length=128)]
class ModeloWorkRenameExecutor(*, work_lifecycle_ports_factory)[source]

Bases: object

Run the existing rename writer under one recorded operation identity.

Parameters:

work_lifecycle_ports_factory (ActiveWorkLifecyclePortsFactory)

async execute(request, context)[source]

Delegate to the single writer and return the renamed unit’s id.

The writer owns the atomic write set - the work-unit catalogue and the bucket lifecycle event co-commit inside it - so nothing here opens a second write path around them.

The declared phase is published BEFORE delegating, because a phase marks entering a stage rather than finishing one: an observer watching this operation should see it start, not learn of it only once the write has already landed. Without this the definition advertises a phase no surface can ever show.

Return type:

str | None

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

Bases: BaseModel

The exact unit an operator approved for discard.

Discard is destructive, so approval is bound to a state rather than to an id: the unit must still be the one that was shown. Carrying the observed updated_at is what makes a stale approval refusable instead of silently discarding a unit that moved after the operator looked at it.

Parameters:

  • work_unit_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='\\S')])])

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

  • observed_updated_at (datetime)

work_unit_id: _WORK_UNIT_ID
name: _WORK_UNIT_NAME
observed_updated_at: datetime
class ModeloWorkDiscardRequest(**data)[source]

Bases: CredentialFreeOperationRequest

The approved unit and the reason recorded against its discard.

Parameters:

data (Any)

baseline: ModeloWorkDiscardBaseline
reason: Annotated[str, Field(min_length=1, max_length=500)] | None
actor: Annotated[str, Field(min_length=1, max_length=128)]

The operator this invocation acts as. The platform binds an actor at submission, never at composition, so baking one into a definition would make the production registry per-actor.

class ModeloWorkDiscardPublicResultV1(**data)[source]

Bases: BaseModel

The settled discard, as a caller outside this package may see it.

Parameters:

  • result_version (int)

  • work_unit_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='\\S')])])

  • bucket_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • discarded (bool)

result_version: int
work_unit_id: _WORK_UNIT_ID
bucket_id: Annotated[str, Field(min_length=1, max_length=128)]
discarded: bool
exception ModeloWorkDiscardApprovalStaleError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Raised when the approved unit is no longer the unit on disk.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
class ModeloWorkDiscardExecutor(*, work_lifecycle_ports_factory)[source]

Bases: object

Run the existing discard writer against an exactly approved unit.

Parameters:

work_lifecycle_ports_factory (ActiveWorkLifecyclePortsFactory)

async execute(request, context)[source]

Verify the approval still holds, then delegate to the single writer.

The approval check is about freshness, not lifecycle: whether a discarded unit may be discarded again is the writer’s rule, and it refuses that itself with no effect. This only refuses acting on a unit the operator did not actually see.

The declared phase is published before the approval check, so a REFUSED discard is still observably a discard that started. Emitting only on success would make a stale-approval refusal indistinguishable from an operation that never ran.

Return type:

str | None

Parameters:
build_modelo_work_discard_definition(*, work_lifecycle_ports_factory)[source]

Bind the discard writer to its registered operation contract.

Return type:

OperationDefinition

Parameters:

work_lifecycle_ports_factory (ActiveWorkLifecyclePortsFactory)

build_modelo_work_discard_registration(definition)[source]

Bind the discard definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

resolve_active_workflow_profile(operation)[source]

Resolve the active taxpayer profile when an operation actually runs.

Injected as a strategy rather than a value: a definition composed into the production registry must not close over whichever profile happened to be active when the registry was built.

Return type:

TaxpayerProfile

Parameters:

operation (PinnedAuthorityOperation)

class ModeloWorkVerifyRequest(**data)[source]

Bases: CredentialFreeOperationRequest

The calculation revision to verify.

The taxpayer profile the gates are evaluated against is deliberately NOT carried here. It is resolved at execution from live state, so a request replayed later cannot verify against a profile the taxpayer has since changed.

Parameters:

data (Any)

calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128, pattern='\S')]
actor: Annotated[str, Field(min_length=1, max_length=128, pattern='\S')]

The operator this invocation acts as. The platform binds an actor at submission, never at composition, so baking one into a definition would make the production registry per-actor.

class ModeloWorkVerifyPublicResultV1(**data)[source]

Bases: BaseModel

The settled verification outcome a caller outside this package may see.

Counts rather than casilla id lists: a result consumer needs to know whether the revision is complete and how much is outstanding, and shipping the resolved ids would put a filing-shaped payload in the operation result where the verification report is the record of truth.

Parameters:

  • result_version (int)

  • verification_report_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • calculation_revision_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • completeness_status (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=64)])])

  • granted_verificado_completo (bool)

  • finding_count (Annotated[int, Ge(ge=0)])

  • missing_required_casilla_count (Annotated[int, Ge(ge=0)])

result_version: int
verification_report_id: Annotated[str, Field(min_length=1, max_length=128)]
calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128)]
completeness_status: Annotated[str, Field(min_length=1, max_length=64)]
granted_verificado_completo: bool
finding_count: NonNegativeInt
missing_required_casilla_count: NonNegativeInt
class ModeloWorkVerifyExecutor(*, certificate_secret_backend_factory, profile_resolver, operator_scope_ports, verification_repository_bundle_factory)[source]

Bases: object

Run the existing verification authority under a recorded identity.

Parameters:
async execute(request, context)[source]

Delegate to the verification authority and return its report id.

The authority owns the guarded persistence and the events it emits; nothing here writes a report or decides completeness.

Publishes its entry phase only – see DELEGATED PHASE REPORTING above.

Return type:

str | None

Parameters:
build_modelo_work_verify_definition(*, certificate_secret_backend_factory, operator_scope_ports, verification_repository_bundle_factory, profile_resolver=<function resolve_active_workflow_profile>)[source]

Bind the verification authority to its registered operation contract.

Return type:

OperationDefinition

Parameters:
build_modelo_work_verify_registration(definition)[source]

Bind the verify definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

class ModeloWorkFileApproval(**data)[source]

Bases: BaseModel

The exact verified revision an operator approved for local filing.

Filing is a durable declaration of what the taxpayer intends to submit, so approval names the revision AND the verification that justified it. A revision re-verified since approval is a different fact, and filing it on the strength of the older look would record an intent nobody formed.

Parameters:

  • calculation_revision_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • verification_report_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128)]
verification_report_id: Annotated[str, Field(min_length=1, max_length=128)]
class ModeloWorkFileRequest(**data)[source]

Bases: CredentialFreeOperationRequest

The approved revision and the operator’s declared election choices.

Parameters:

data (Any)

approval: ModeloWorkFileApproval
refund_election: RefundElection
payment_election: PaymentElection
notes: Annotated[str, Field(min_length=1, max_length=500)] | None
actor: Annotated[str, Field(min_length=1, max_length=128)]

The operator this invocation acts as. The platform binds an actor at submission, never at composition, so baking one into a definition would make the production registry per-actor.

class ModeloWorkFilePublicResultV1(**data)[source]

Bases: BaseModel

The recorded local filing, as a caller outside this package may see it.

handoff_required is always true and is part of the contract, not a computed field: this operation records a filing locally and hands the operator the artefacts to submit themselves. Nothing here reaches AEAT.

Parameters:

  • result_version (int)

  • filing_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • work_unit_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128), _PydanticGeneralMetadata(pattern='\\S')])])

  • calculation_revision_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • handoff_required (bool)

result_version: int
filing_record_id: Annotated[str, Field(min_length=1, max_length=128)]
work_unit_id: _WORK_UNIT_ID
calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128)]
handoff_required: bool
class ModeloWorkFileExecutor(*, profile_resolver, operator_scope_ports, filing_action_ports_factory, certificate_secret_backend_factory)[source]

Bases: object

Record one local filing through the existing filing authority.

This never submits to AEAT and never can: it calls the local filing authority and returns its record id. Live submission is prohibited, so the operation’s whole output is a local record plus the operator’s handoff.

Parameters:
async execute(request, context)[source]

Delegate to the filing authority and return its record id.

Every precondition - verification state, cross-period cleanliness, election legality - belongs to that authority and refuses there.

Publishes its entry phase only – see DELEGATED PHASE REPORTING above.

Return type:

str | None

Parameters:
build_modelo_work_file_definition(*, operator_scope_ports, filing_action_ports_factory, certificate_secret_backend_factory, profile_resolver=<function resolve_active_workflow_profile>)[source]

Bind the local filing authority to its registered operation contract.

Return type:

OperationDefinition

Parameters:
build_modelo_work_file_registration(definition)[source]

Bind the local filing definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

class ModeloExportRequest(**data)[source]

Bases: CredentialFreeOperationRequest

The revision to export and where the operator wants the artefact.

The path is the operator’s chosen destination, journalled because it is a location rather than content. The exported bytes never enter the request or the result.

Parameters:

data (Any)

calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128)]
output_path: Annotated[str, Field(min_length=1, max_length=4096, pattern='\S')]

pattern=r"\S" refuses an all-whitespace destination, which min_length alone admits. NOT stripped: a path must stay byte-exact, and silently trimming one would mask a typo rather than surface it.

actor: Annotated[str, Field(min_length=1, max_length=128)]

The operator this invocation acts as; stamped onto the exported artefact through the command built from this request.

class ModeloExportPublicResultV1(**data)[source]

Bases: BaseModel

Evidence that one export happened, without the exported material.

Custody of the artefact is the operator’s from the moment it lands: this result names the file and fingerprints it so a later reader can prove which bytes were produced, and carries none of them.

Parameters:

  • result_version (int)

  • calculation_revision_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • output_path (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=4096), _PydanticGeneralMetadata(pattern='\\S')])])

  • byte_size (Annotated[int, Ge(ge=0)])

  • file_sha256 (ContentDigest)

  • export_format (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=64)])])

  • handoff_required (bool)

result_version: int
calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128)]
output_path: Annotated[str, Field(min_length=1, max_length=4096, pattern='\S')]

pattern=r"\S" refuses an all-whitespace destination, which min_length alone admits. NOT stripped: a path must stay byte-exact, and silently trimming one would mask a typo rather than surface it.

byte_size: NonNegativeInt
file_sha256: ContentDigest
export_format: Annotated[str, Field(min_length=1, max_length=64)]
handoff_required: bool
class ModeloExportExecutor(*, profile_resolver, export_ports_factory)[source]

Bases: object

Export one revision through the existing authority, locally only.

The authority is local by construction and never contacts AEAT; this enrolment adds no transport of its own, so an exported artefact reaches the tax authority only when a human carries it there.

Parameters:
async execute(request, context)[source]

Delegate to the export authority and return the artefact digest.

The command is built from the journalled request, so the identity an artefact is stamped with is the one this invocation recorded rather than whatever a closure happened to hold when the definition was built.

Publishes its entry phase only – see DELEGATED PHASE REPORTING above.

Return type:

str | None

Parameters:
build_modelo_export_definition(*, profile_resolver=<function resolve_active_workflow_profile>, export_ports_factory)[source]

Bind the export authority to its registered operation contract.

Return type:

OperationDefinition

Parameters:
build_modelo_export_registration(definition)[source]

Bind the export definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

class ModeloWorkAmendBaseline(**data)[source]

Bases: BaseModel

The externally filed return an amendment corrects.

An amendment is only meaningful against a specific filed baseline, so the request names that record rather than a work unit: the baseline supplies the full casilla map, and the overrides replace only what changed.

Parameters:

from_filing_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

from_filing_record_id: Annotated[str, Field(min_length=1, max_length=128)]
class ModeloWorkAmendOverride(**data)[source]

Bases: BaseModel

One corrected casilla and the value that replaces it.

The value crosses as an exact decimal STRING rather than a number. A public operation schema must validate and serialize to the same shape, and a bare Decimal does not: it accepts number-or-string and emits string. Carrying the digits avoids that asymmetry and any float coercion on the way.

Parameters:

  • casilla_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=64)])])

  • value (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^-?\\d{1,15}(?:\\.\\d{1,6})?$')])])

casilla_id: Annotated[str, Field(min_length=1, max_length=64)]
value: Annotated[str, Field(pattern='^-?\d{1,15}(?:\.\d{1,6})?$')]
as_decimal()[source]

Return the exact value this override carries.

Return type:

Decimal

class ModeloWorkAmendRequest(**data)[source]

Bases: CredentialFreeOperationRequest

One amendment: which baseline, which corrections, and why.

reason is required because an amendment is a declaration to the tax authority that a previously filed figure was wrong; a correction with no stated reason is not something the operator should be able to file.

Parameters:
baseline: ModeloWorkAmendBaseline
amendment_kind: CalculationRevisionAmendmentKind
overrides: Annotated[tuple[ModeloWorkAmendOverride, ...], Field(min_length=1, max_length=500)]
reason: Annotated[str, Field(min_length=1, max_length=500)]
m303_rectificativa_motive: M303RectificativaMotive | None
detail_rows: Annotated[tuple[ModeloDetailRowWireV1, ...], Field(max_length=_MAX_AMENDMENT_DETAIL_ROWS)] | None

The rows this amendment declares, or None where it declares none.

THREE STATES, NOT TWO, and the authority reads all three. For M184, M232, M347 and M349 the per-counterpart rows ARE the declaration, so None – the caller having said nothing – is refused rather than guessed: a complementaria COMPLETES a return while a sustitutiva REPLACES it (LGT art. 122.2 para. 2), and silence would be read differently by each. An empty tuple is not that silence; it is the positive statement that the period had no rows, and is accepted as one. Every other modelo has no rows to declare, so None there is simply its ordinary shape.

Optional here rather than required because those other modelos are the majority of this operation’s traffic; the refusal that makes the distinction binding lives with the authority that knows which modelo the baseline belongs to, which this request does not carry.

The rows cross as their payload-safe wire mirror rather than the domain ModeloDetailRow: two of those six hydrate registry codes through before-validators, which the payload-graph gate refuses because a published schema would then not describe what validation accepts. The mirror already exists for the edit operation, and reusing it keeps one translation rather than a second free to drift.

actor: Annotated[str, Field(min_length=1, max_length=128)]

The operator this invocation acts as. The platform binds an actor at submission, never at composition, so baking one into a definition would make the production registry per-actor.

class ModeloWorkAmendPublicResultV1(**data)[source]

Bases: BaseModel

The recorded amendment, as a caller outside this package may see it.

Parameters:

  • result_version (int)

  • filing_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • amended_from_filing_record_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • amendment_kind (CalculationRevisionAmendmentKind)

  • corrected_casilla_count (Annotated[int, Ge(ge=0)])

  • handoff_required (bool)

result_version: int
filing_record_id: Annotated[str, Field(min_length=1, max_length=128)]
amended_from_filing_record_id: Annotated[str, Field(min_length=1, max_length=128)]
amendment_kind: CalculationRevisionAmendmentKind
corrected_casilla_count: NonNegativeInt
handoff_required: bool
class ModeloWorkAmendExecutor(*, amendment_action_ports_factory)[source]

Bases: object

Record one amendment through the existing amendment authority.

Like the filing enrolment this is local: an amendment is built and recorded here, and the operator submits it themselves.

Parameters:

amendment_action_ports_factory (AmendmentActionPortsFactory)

async execute(request, context)[source]

Delegate to the amendment authority and return its record id.

Which overrides are legal, which kinds a modelo admits, and whether the baseline is AEAT-attested are all the authority’s decisions.

Publishes its entry phase only – see DELEGATED PHASE REPORTING above.

Return type:

str | None

Parameters:
build_modelo_work_amend_definition(*, amendment_action_ports_factory)[source]

Bind the amendment authority to its registered operation contract.

Return type:

OperationDefinition

Parameters:

amendment_action_ports_factory (AmendmentActionPortsFactory)

build_modelo_work_amend_registration(definition)[source]

Bind the amendment definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

class ModeloEditApplyBaselineV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloEditBaselineV1 with a plain-string modelo code.

Every field of ModeloEditBaselineV1 except modelo already crosses an operation payload safely: Hex64Str, bounded Annotated str, Period and the permitted-surface union are all plain Pydantic shapes with no custom core schema. Only modelo: ModeloCode does - it is a str subclass that customises its Pydantic core schema, which the operations payload-graph gate refuses inside a registered request payload - so only that one field is mirrored here. to_baseline re-validates it through the real type.

Parameters:

  • compatibility (ModeloEditCompatibilityTupleV1)

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

  • modelo (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=3), MaxLen(max_length=3), _PydanticGeneralMetadata(pattern='^\\d{3}$')])])

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])])

  • period_filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])])

  • period_code (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=16)])])

  • work_unit_id (WorkUnitId)

  • work_catalogue_revision (ContentDigest)

  • calculation_catalogue_revision (ContentDigest)

  • current_calculation_revision_id (CalculationRevisionId | None)

  • law_selected_revision_id (RevisionId)

  • schema_identity (ModeloEditSchemaIdentityV1)

  • schema_version (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1)])])

  • permitted_surface (Annotated[tuple[ModeloEditPermittedSurfaceEntryV1, ...], FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=2000)])])

  • permitted_surface_digest (ContentDigest)

  • mutation_family (ModeloEditMutationFamily)

  • issued_at (datetime)

  • expires_at (datetime)

  • baseline_id (ModeloEditBaselineId)

compatibility: ModeloEditCompatibilityTupleV1
bucket_id: BucketId
modelo: Annotated[str, Field(min_length=3, max_length=3, pattern='^\d{3}$')]
filing_year: FilingYear
period_filing_year: FilingYear
period_code: Annotated[str, Field(min_length=1, max_length=16)]
work_unit_id: WorkUnitId
work_catalogue_revision: ContentDigest
calculation_catalogue_revision: ContentDigest
current_calculation_revision_id: CalculationRevisionId | None
law_selected_revision_id: RevisionId
schema_identity: ModeloEditSchemaIdentityV1
schema_version: Annotated[int, Field(ge=1)]
permitted_surface: Annotated[tuple[ModeloEditPermittedSurfaceEntryV1, ...], Field(max_length=2000)]
permitted_surface_digest: ContentDigest
mutation_family: ModeloEditMutationFamily
issued_at: datetime
expires_at: datetime
baseline_id: ModeloEditBaselineId
to_baseline()[source]

Translate back to the real, fully re-validated domain baseline.

period is mirrored the same way as modelo: Period is a core BaseModel that does not declare strict=True, which the operations payload-graph gate also refuses, so the wire form carries its two source fields and reconstructs the real type here.

Return type:

ModeloEditBaselineV1

classmethod from_baseline(baseline)[source]

Mirror a domain baseline onto the wire form to_baseline reverses.

Kept beside its inverse so the two directions cannot drift into disagreeing about which fields are mirrored: adding a field to the wire type without teaching this method is a validation error here, not a silently dropped coordinate.

Return type:

ModeloEditApplyBaselineV1

Parameters:

baseline (ModeloEditBaselineV1)

class ModeloEditApplyScalarIntentV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloScalarEditIntentV1 with a payload-safe value.

Parameters:
address: ModeloEditScalarAddressV1
kind: ModeloEditScalarIntentKind
value: _ModeloEditApplyScalarValue
to_intent()[source]

Translate back to the real, fully re-validated domain intent.

Return type:

ModeloScalarEditIntentV1

classmethod from_intent(intent)[source]

Mirror a domain scalar intent onto the wire form to_intent reverses.

Return type:

ModeloEditApplyScalarIntentV1

Parameters:

intent (ModeloScalarEditIntentV1)

class ModeloEditApplyBindingIntentV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloBindingEditIntentV1 with a payload-safe value.

Parameters:
address: ModeloEditBindingAddressV1
kind: ModeloEditBindingIntentKind
value: _ModeloEditApplyScalarValue
to_intent()[source]

Translate back to the real, fully re-validated domain intent.

Return type:

ModeloBindingEditIntentV1

classmethod from_intent(intent)[source]

Mirror a domain binding intent onto the wire form to_intent reverses.

Return type:

ModeloEditApplyBindingIntentV1

Parameters:

intent (ModeloBindingEditIntentV1)

class ModeloEditApplyRowIntentV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloRowEditIntentV1 with payload-safe row values.

Parameters:
address: ModeloEditRowAddressV1
kind: ModeloEditRowIntentKind
row: Annotated[tuple[ModeloEditApplyScalarIntentV1, ...], Field(max_length=200)] | None
move_to_index: Annotated[int, Field(ge=1)] | None
to_intent()[source]

Translate back to the real, fully re-validated domain intent.

Return type:

ModeloRowEditIntentV1

classmethod from_intent(intent)[source]

Mirror a domain row intent, including each of its scalar entries.

Return type:

ModeloEditApplyRowIntentV1

Parameters:

intent (ModeloRowEditIntentV1)

class Modelo184MemberRowWireV1(**data)[source]

Bases: _WireDetailRowMirror

Wire mirror of Modelo184MemberRow with decimal amounts as characters.

Parameters:

  • row_type (Literal['miembro'])

  • nif (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=20)])])

  • nombre (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=200)])])

  • pais (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=2, max_length=2, pattern=None, ascii_only=None)] | None)

  • porcentaje (_WireAmount)

  • importe (_WireAmount)

  • clave (M184Clave)

  • subclave (M184Subclave | None)

  • codigo_provincia (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=2)])] | None)

  • miembro_a_31_diciembre (bool | None)

  • dias_miembro (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=366)])] | None)

  • domicilio_fiscal (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=40)])] | None)

  • naturaleza_inmueble (M184NaturalezaInmueble | None)

  • situacion_inmueble (M184SituacionInmueble | None)

  • referencia_catastral (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=20)])] | None)

  • clave_declarado (M184ClaveDeclarado | None)

  • porcentaje_titularidad_inmueble (_WireOptionalAmount)

  • dias_arrendamiento (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0), Le(le=366)])] | None)

  • reduccion (_WireOptionalAmount)

  • rendimiento_neto_previo_eo (_WireOptionalAmount)

  • rendimiento_neto_minorado_agricola_eo (_WireOptionalAmount)

row_type: Literal['miembro']
nif: Annotated[str, Field(min_length=1, max_length=20)]
nombre: Annotated[str, Field(max_length=200)]
pais: CountryCodeAlpha2 | None
porcentaje: _WireAmount
importe: _WireAmount
clave: M184Clave
subclave: M184Subclave | None
codigo_provincia: Annotated[str, Field(max_length=2)] | None
miembro_a_31_diciembre: bool | None
dias_miembro: Annotated[int, Field(ge=0, le=366)] | None
domicilio_fiscal: Annotated[str, Field(max_length=40)] | None
naturaleza_inmueble: M184NaturalezaInmueble | None
situacion_inmueble: M184SituacionInmueble | None
referencia_catastral: Annotated[str, Field(max_length=20)] | None
clave_declarado: M184ClaveDeclarado | None
porcentaje_titularidad_inmueble: _WireOptionalAmount
dias_arrendamiento: Annotated[int, Field(ge=0, le=366)] | None
reduccion: _WireOptionalAmount
rendimiento_neto_previo_eo: _WireOptionalAmount
rendimiento_neto_minorado_agricola_eo: _WireOptionalAmount
to_row()[source]

Translate back to the real, fully re-validated domain row.

Return type:

Modelo184MemberRow

class Modelo232VinculadaRowWireV1(**data)[source]

Bases: _WireDetailRowMirror

Wire mirror of Modelo232VinculadaRow carrying its codes unhydrated.

Parameters:

  • row_type (Literal['vinculada'])

  • nif (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=20)])])

  • nombre (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=200)])])

  • pais (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=2, max_length=2, pattern=None, ascii_only=None)])

  • tipo_vinculacion (_WireCode)

  • tipo_operacion (_WireCode)

  • metodo (_WireCode)

  • importe (_WireAmount)

row_type: Literal['vinculada']
nif: Annotated[str, Field(min_length=1, max_length=20)]
nombre: Annotated[str, Field(max_length=200)]
pais: CountryCodeAlpha2
tipo_vinculacion: _WireCode
tipo_operacion: _WireCode
metodo: _WireCode
importe: _WireAmount
to_row()[source]

Translate back through the row type’s own code hydration.

Return type:

Modelo232VinculadaRow

class Modelo349OperadorRowWireV1(**data)[source]

Bases: _WireDetailRowMirror

Wire mirror of Modelo349OperadorRow with its importe as characters.

Parameters:

  • row_type (Literal['operador'])

  • codigo_pais (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=2, max_length=2, pattern=None, ascii_only=None)])

  • nif_comunitario (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=20)])])

  • razon_social (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=200)])])

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

  • importe (_WireAmount)

row_type: Literal['operador']
codigo_pais: CountryCodeAlpha2
nif_comunitario: Annotated[str, Field(min_length=1, max_length=20)]
razon_social: Annotated[str, Field(min_length=1, max_length=200)]
clave_operacion: Modelo349ClaveOperacionValue
importe: _WireAmount
to_row()[source]

Translate back to the real, fully re-validated domain row.

Return type:

Modelo349OperadorRow

class Modelo349RectificacionRowWireV1(**data)[source]

Bases: _WireDetailRowMirror

Wire mirror of Modelo349RectificacionRow with its bases as characters.

Parameters:

  • row_type (Literal['rectificacion'])

  • codigo_pais (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=2, max_length=2, pattern=None, ascii_only=None)])

  • nif_comunitario (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=20)])])

  • razon_social (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=200)])])

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

  • ejercicio (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=4), MaxLen(max_length=4)])])

  • periodo (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=2)])])

  • base_rectificada (_WireAmount)

  • base_anterior (_WireAmount)

row_type: Literal['rectificacion']
codigo_pais: CountryCodeAlpha2
nif_comunitario: Annotated[str, Field(min_length=1, max_length=20)]
razon_social: Annotated[str, Field(min_length=1, max_length=200)]
clave_operacion: Modelo349ClaveOperacionValue
ejercicio: Annotated[str, Field(min_length=4, max_length=4)]
periodo: Annotated[str, Field(min_length=1, max_length=2)]
base_rectificada: _WireAmount
base_anterior: _WireAmount
to_row()[source]

Translate back through the row type’s own periodo normalisation.

Return type:

Modelo349RectificacionRow

class Modelo347ContraparteRowWireV1(**data)[source]

Bases: _WireDetailRowMirror

Wire mirror of Modelo347ContraparteRow with quarterly amounts as characters.

Parameters:

  • row_type (Literal['contraparte'])

  • nif (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=20)])])

  • nombre (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=200)])])

  • importe_Q1 (_WireAmount)

  • importe_Q2 (_WireAmount)

  • importe_Q3 (_WireAmount)

  • importe_Q4 (_WireAmount)

  • clave_operacion (Literal[Modelo347ClaveOperacion.A, Modelo347ClaveOperacion.B, Modelo347ClaveOperacion.C, Modelo347ClaveOperacion.D, Modelo347ClaveOperacion.E, Modelo347ClaveOperacion.F, Modelo347ClaveOperacion.G])

  • pais_codigo (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=2, max_length=2, pattern=None, ascii_only=None)] | None)

row_type: Literal['contraparte']
nif: Annotated[str, Field(min_length=1, max_length=20)]
nombre: Annotated[str, Field(max_length=200)]
importe_Q1: _WireAmount
importe_Q2: _WireAmount
importe_Q3: _WireAmount
importe_Q4: _WireAmount
clave_operacion: Modelo347ClaveOperacionValue
pais_codigo: CountryCodeAlpha2 | None
to_row()[source]

Translate back to the real, fully re-validated domain row.

Return type:

Modelo347ContraparteRow

class Modelo210AgrupacionRentaRowWireV1(**data)[source]

Bases: _WireDetailRowMirror

Wire mirror of Modelo210AgrupacionRentaRow with its rates as characters.

Parameters:

  • row_type (Literal['agrupacion_renta'])

  • source_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=200)])])

  • tipo_renta_code (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=2), MaxLen(max_length=2)])])

  • importe (_WireAmount)

  • tipo_gravamen (_WireAmount)

  • pagador_mode (str)

  • pagador_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=200)])] | None)

  • deriva_de_bien_derecho (bool)

  • bien_derecho_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=200)])] | None)

row_type: Literal['agrupacion_renta']
source_id: Annotated[str, Field(min_length=1, max_length=200)]
tipo_renta_code: Annotated[str, Field(min_length=2, max_length=2)]
importe: _WireAmount
tipo_gravamen: _WireAmount
pagador_mode: str
pagador_id: Annotated[str, Field(min_length=1, max_length=200)] | None
deriva_de_bien_derecho: bool
bien_derecho_id: Annotated[str, Field(min_length=1, max_length=200)] | None
to_row()[source]

Translate back to the real, fully re-validated domain row.

Return type:

Modelo210AgrupacionRentaRow

class ModeloEditApplyDetailRowAddressV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloEditDetailRowAddressV1 carrying the key’s components.

The domain address holds a natural_key: the row’s own identity fields joined with |. That joined string is a bounded free-form string, which is the same shape a passphrase has, so the credential-free journal check refuses it on the key token in its name and no schema predicate could tell the two apart.

Nothing is exempted to get around that. The joined string is a derived convenience rather than information: every component is one of the row’s own declared identity fields, already carried in the clear by the row mirrors in this module and already admitted by the same check. So the components cross instead, and to_address derives the key exactly as the domain type expects it.

Carrying the components is also strictly less ambiguous than carrying the join, because a component that itself contains the separator is indistinguishable from a boundary once joined.

Parameters:

  • kind (Literal['detail_row'])

  • detail_row_kind (DetailRowKindToken)

  • identity_components (Annotated[tuple[Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=200)])], ...], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=8)])])

kind: Literal['detail_row']
detail_row_kind: DetailRowKindToken
identity_components: Annotated[tuple[Annotated[str, Field(min_length=1, max_length=200)], ...], Field(min_length=1, max_length=8)]
to_address()[source]

Derive the domain address by joining the components it was built from.

Return type:

ModeloEditDetailRowAddressV1

class ModeloEditApplyDetailRowIntentV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloDetailRowEditIntentV1 with a payload-safe row.

Parameters:
address: ModeloEditApplyDetailRowAddressV1
kind: ModeloEditDetailRowIntentKind
row: ModeloDetailRowWireV1 | None
to_intent()[source]

Translate back to the real, fully re-validated domain intent.

Return type:

ModeloDetailRowEditIntentV1

class ModeloEditApplySubmissionV1(**data)[source]

Bases: BaseModel

Wire mirror of ModeloEditSubmissionV1 carrying a payload-safe baseline.

Scalar, binding and row intents are mirrored only for their value field: ModeloScalar (Decimal | int | str | bool | date | None) fails the operations payload-graph gate’s validation/serialization schema-identity check, because Decimal validates from a number or a string but always serializes to a string. Every other field of these three families - addresses, intent kinds, move_to_index - is already payload-safe and carried through unchanged. This is a total translation: every field of every mirrored intent converts, nothing is dropped.

detail_row_intents is carried, one wire type per per-modelo row kind. Each mirrors its row’s Decimal fields as the exact characters submitted, and the two kinds that hydrate registry codes carry them raw so the real row type runs its own hydration during translation - one hydration shared with the CLI --row key=value path rather than a second copy free to drift.

The address is mirrored too, and deliberately not by mirroring its natural_key: see ModeloEditApplyDetailRowAddressV1 for why the components cross instead of the string derived from them.

The mirrored payload is INPUT, not authority: apply_modelo_edit re-resolves and independently re-validates every coordinate at the guarded commit point regardless of what this wire type carried, so a stale or forged mirror cannot be believed - a mismatch surfaces as the typed no-effect result, never a bad write.

Parameters:
edit_contract_version: Literal[1]
baseline: ModeloEditApplyBaselineV1
mutation_family: ModeloEditMutationFamily
scalar_intents: Annotated[tuple[ModeloEditApplyScalarIntentV1, ...], Field(max_length=500)]
binding_intents: Annotated[tuple[ModeloEditApplyBindingIntentV1, ...], Field(max_length=500)]
row_intents: Annotated[tuple[ModeloEditApplyRowIntentV1, ...], Field(max_length=500)]
detail_row_intents: Annotated[tuple[ModeloEditApplyDetailRowIntentV1, ...], Field(max_length=500)]
to_submission()[source]

Translate back to the real, fully re-validated domain submission.

Return type:

ModeloEditSubmissionV1

classmethod from_submission(submission)[source]

Mirror a domain submission onto the wire form the operation accepts.

This is the direction an operator surface needs. The executor already owned wire-to-domain; without its inverse the registered apply operation had no caller outside this package’s own tests, because a frontend that stages domain intents had no way to reach it.

REFUSES A SUBMISSION CARRYING DETAIL ROWS, and the refusal is the honest answer rather than a gap. A domain ModeloEditDetailRowAddressV1 holds only the JOINED natural_key, while the wire form carries the identity components that were joined to make it – deliberately, per ModeloEditApplyDetailRowAddressV1, because a component containing the separator is indistinguishable from a boundary once joined. Splitting the key here would reconstruct the components by guessing, and would guess wrong exactly when a taxpayer’s own identifier contains the separator. A caller staging detail rows still holds the components and must build the wire address from those; it does not come back out of the domain address.

Return type:

ModeloEditApplySubmissionV1

Parameters:

submission (ModeloEditSubmissionV1)

class ModeloEditApplyOperationRequestV1(**data)[source]

Bases: CredentialFreeOperationRequest

The admitted Edit Contract submission this operation is authorized to apply.

Credential-free by construction: every field is a pre-validated, pre-admitted coordinate or typed value the Edit Contract admission phase already produced, so nothing here is unsafe to journal.

Parameters:

data (Any)

submission: ModeloEditApplySubmissionV1
class ModeloEditApplyPublicResultV1(**data)[source]

Bases: BaseModel

The settled receipt id a caller outside this package may see.

Only the id: the full receipt is the domain record of truth, addressable through the ModeloEditReceiptRepositoryPort capability, and this result exists to confirm which one a submission produced.

Parameters:

  • result_version (int)

  • receipt_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

  • calculation_revision_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1), MaxLen(max_length=128)])])

result_version: int
receipt_id: Annotated[str, Field(min_length=1, max_length=128)]
calculation_revision_id: Annotated[str, Field(min_length=1, max_length=128)]
class ModeloEditApplyExecutor(*, calculation_action_ports_factory, receipt_repository_factory)[source]

Bases: object

Run the Edit Contract’s guarded compare-and-swap apply under one recorded identity.

apply_modelo_edit already owns the commit-point baseline recheck, the calculate/recalculate discrimination (recalculate refuses honestly, by design, until it is wired) and the co-committed result receipt; this only binds the running operation’s own identity to that call and re-implements no lifecycle policy.

Parameters:
async execute(request, context)[source]

Delegate to apply_modelo_edit and return the settled receipt id.

A failed compare-and-swap is a typed domain fact (ModeloEditExecutionNoEffectV1), not an unexpected error, but the executor protocol this method implements returns only an optional reference. No channel exists yet to carry the typed refusal back to a caller outside this package through the operation result path, so it is reported here as a no-effect None rather than fabricated into an exception the refusal was deliberately designed not to be.

Unlike its delegating siblings this executor declares ONE phase and publishes it, because there is no inner transition it cannot see.

Return type:

str | None

Parameters:
build_modelo_edit_apply_definition(*, calculation_action_ports_factory, receipt_repository_factory)[source]

Bind the Edit Contract’s guarded apply path to its registered operation contract.

Return type:

OperationDefinition

Parameters:
build_modelo_edit_apply_registration(definition)[source]

Bind the edit-apply definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

build_modelo_work_rename_definition(*, work_lifecycle_ports_factory)[source]

Bind the rename writer to its registered operation contract.

Return type:

OperationDefinition

Parameters:

work_lifecycle_ports_factory (ActiveWorkLifecyclePortsFactory)

build_modelo_work_rename_registration(definition)[source]

Bind the rename definition to its stable public schemas.

Return type:

OperationPublicDefinitionRegistrationV1

Parameters:

definition (OperationDefinition)

build_modelo_lifecycle_operation_definitions(*, certificate_secret_backend_factory, operator_scope_ports, export_ports_factory, calculation_action_ports_factory, amendment_action_ports_factory, filing_action_ports_factory, work_lifecycle_ports_factory, receipt_repository_factory, verification_repository_bundle_factory)[source]

Return the one canonical modelo lifecycle operation population.

Every definition this module exports belongs here. A definition that is exported and never composed is capacity nothing can reach, which is the shape this population exists to make impossible to ship.

Return type:

tuple[OperationDefinition, ...]

Parameters:
build_modelo_lifecycle_operation_registrations(definitions)[source]

Bind each lifecycle definition to its stable public schemas.

Return type:

tuple[OperationPublicDefinitionRegistrationV1, ...]

Parameters:

definitions (tuple[OperationDefinition, ...])