aeat.application.modelo._semantic_role_resolution module

Single-casilla semantic-role resolution for modelo application services.

Snapshot-backed callers pass a RegistrySnapshot so semantic roles resolve only to declared canonical casilla.id values for that revision. Advisory helpers that already hold a revision object use the structural revision resolver and get the same ambiguity guard.

See also

_calculate_input

Work-unit input shortcuts that resolve operator-facing semantic-role tokens through a registry snapshot.

_binding_resolution

Declaration-period metadata binding path that only accepts informational semantic-role casillas.

_taxation_comparison

Snapshot-backed comparison surface that uses semantic roles for the Modelo 100 result and quota casillas.

class SemanticRoleCasillaAmbiguity(semantic_role, modelo_id, revision_id, casilla_ids)

Bases: object

Structured detail for a semantic role that resolves to multiple casillas.

Attached to AmbiguousSemanticRoleCasillaError so callers can relay the ambiguous role, modelo, revision, and candidate casillas without parsing the error message.

Parameters:

• semantic_role (str)

• modelo_id (str | None)

• revision_id (str | None)

• casilla_ids (tuple[CasillaId, ...])

semantic_role: str

modelo_id: str | None

revision_id: str | None

casilla_ids: tuple[TypeAliasType, ...]

context()

Return structured error context for AeatError envelopes.

Return type:

dict[str, object]

exception AmbiguousSemanticRoleCasillaError(ambiguity)

Bases: ModeloError, ValueError

Raised when a semantic-role resolver would emit an arbitrary casilla id.

The exception carries a SemanticRoleCasillaAmbiguity payload instead of selecting one candidate, preserving the canonical casilla.id contract.

Parameters:

ambiguity (SemanticRoleCasillaAmbiguity)

Return type:

None

code: ClassVar[ErrorCode]

casilla_id_for_unique_semantic_role(snapshot, semantic_role)

Return the unique casilla id for semantic_role in snapshot.

None means the concrete revision does not declare the role. Multiple matches are refused because returning one would silently convert a non- canonical reference into an arbitrary canonical casilla.id.

Parameters:

• snapshot (RegistrySnapshot) – The RegistrySnapshot whose revision is inspected.

• semantic_role (str) – Semantic role token to resolve.

Return type:

TypeAliasType | None

casilla_id_for_unique_revision_semantic_role(revision, semantic_role, *, modelo_id=None)

Return the unique casilla id for semantic_role in revision.

This accepts a structural revision object so advisory helpers that only receive a revision can share the same ambiguity guard as snapshot-backed services. The object must expose id and casillas attributes compatible with the registry ModeloRevision shape.

Return type:

TypeAliasType | None

Parameters:

• revision (object)

• semantic_role (str)

• modelo_id (str | None)