cadrumo.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)[source]

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 (RevisionId | None)

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

semantic_role: str
modelo_id: str | None
revision_id: TypeAliasType | None
casilla_ids: tuple[TypeAliasType, ...]
context()[source]

Return structured error context for CadrumoError envelopes.

Return type:

dict[str, object]

exception AmbiguousSemanticRoleCasillaError(ambiguity)[source]

Bases: ModeloError

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
casilla_id_for_unique_semantic_role(snapshot, semantic_role)[source]

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:
Return type:

TypeAliasType | None

casilla_id_for_unique_revision_semantic_role(revision, semantic_role, *, modelo_id=None)[source]

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)

casilla_id_for_unambiguous_revision_semantic_role(revision, semantic_role, *, modelo_id=None)[source]

Return the casilla id only when semantic_role resolves unambiguously.

The sibling above raises on ambiguity so a caller that must not proceed on a guess gets an instructive refusal. An advisory has the opposite need: it is a non-blocking diagnostic, so a revision it cannot address unambiguously is a revision it declines to speak about, and None already means “no casilla to address” for the absent case. This collapses both to that one answer.

Two returns share it, and they are not the same fact: an absent role and an ambiguous one. A caller that needs to tell them apart must use the raising sibling, because this function deliberately cannot.

Return type:

TypeAliasType | None

Parameters:

  • revision (object)

  • semantic_role (str)

  • modelo_id (str | None)