cadrumo.entrypoints.tui.modelo.view.controller module

The read-only session and controller behind the Modelo workspace destinations.

A session is one operator’s read of one target. It holds what the producer already settled and re-checks it; it resolves nothing itself, and it has no mutation authority of any kind. Every judgement it makes is a comparison between two projections the application layer produced.

The identity discipline is the whole point of this module. A workspace read has TWO independent axes, and conflating them breaks both:

• the SEMANTIC axes – target, selected_revision_id and schema_identity – name WHICH read this is;

• the LOCALE axes – the locale summary and, through the contributor stamps, the baseline token – name what LANGUAGE it was rendered in.

Two reads of the same target in different languages carry DIFFERENT baselines, so staleness keys on the semantic axes ALONE. Keying it on the baseline would make every language switch invalidate the whole session, which would make a locale-only refresh impossible to express.

One measured caveat, because the obvious shortcut is wrong: baseline.locale_catalogue_digest is NOT a language discriminator. When the requested language has no entry for a key, resolution falls back to Spanish and reports the SPANISH shard’s digest, so a Spanish read and an English read that fell back carry the SAME digest. Spanish is the mandatory source language for these catalogues, so that fallback is the common case rather than an edge one. The locale SUMMARY is the honest axis: it keeps requested_language distinct from resolved_language precisely so the fallback stays visible.

SUPPORTED_WORKSPACE_CONTRACT_VERSION: Final[int]

The one contract version this cohort reads.

Exact, never a floor: a future version may move a field this controller narrows, so admitting >= 1 would let a shape this code cannot read reach a renderer. Refusing an unequal version is the forward-compatibility posture, not a legacy one – there is no older version to tolerate.

exception ModeloWorkspaceSessionAdmissionError(message=None, *, context=None, translated_message=None)

Bases: CadrumoError

The result could not open a session and carried no typed refusal to explain it.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

class ModeloWorkspaceSemanticIdentityV1(target_token, selected_revision_id, schema_identity_token)

Bases: object

The three axes that say WHICH read this is, independent of language.

Compared by value, so two reads agree exactly when they name the same target, the same law-selected revision, and the same registry schema. Deliberately excludes every locale-bearing field: a language switch must not read as a different workspace.

Parameters:

• target_token (str)

• selected_revision_id (str)

• schema_identity_token (str)

target_token: str

selected_revision_id: str

schema_identity_token: str

semantic_identity(projection)

Read one projection’s semantic identity, ignoring every locale axis.

Return type:

ModeloWorkspaceSemanticIdentityV1

Parameters:

projection (ModeloWorkspaceProjectionV1)

class ModeloWorkspaceReadSession(projection, identity)

Bases: object

One pinned, read-only workspace session over one admitted projection.

Frozen: a refresh produces a NEW session rather than mutating this one, so a renderer holding a session can never observe it change underneath it mid-render. The previous session stays valid for comparison, which is what makes the locale-only and staleness judgements expressible at all.

Parameters:

• projection (ModeloWorkspaceProjectionV1)

• identity (ModeloWorkspaceSemanticIdentityV1)

projection: ModeloWorkspaceProjectionV1

identity: ModeloWorkspaceSemanticIdentityV1

property output_language: str

Return the language this session’s text was actually resolved in.

cursor_for(facet)

Return the continuation this facet declared, or None when complete.

Custody only. This controller does NOT turn the page: no public application entry point accepts a cursor today, and the one client-side shortcut – re-resolving and taking a later page – would defeat the cursor’s purpose, because a fresh resolve captures a new baseline and the held cursor is stale against it by construction. Returning the cursor honestly, and refusing to fake traversal, is the correct behaviour until that entry point exists.

Return type:

ModeloWorkspaceCursorV1 | None

Parameters:

facet (ModeloWorkspaceFacetName)

has_more(facet)

Report whether the producer bounded this facet short of the whole set.

Return type:

bool

Parameters:

facet (ModeloWorkspaceFacetName)

page_completeness(facet)

Return whether this facet’s page IS the whole set, as a closed two-arm answer.

Boundedness disclosure is part of this session’s contract, not a courtesy the destinations may each decide to offer. Until a page-turn entry point exists, an over-cap facet shows its first page and stops – so a destination that renders a bounded page as though it were complete turns a truncation the producer declared into one the operator cannot see.

Returned as the discriminated pair rather than a bool for the reason the pair exists: a caller must handle both arms, where a has_more flag can simply not be read. That matters most for provenance, where one source reference fans out to one row per casilla it names, so a page can overflow without the revision growing and row count tells an operator nothing about completeness.

Return type:

TypeAliasType

Parameters:

facet (ModeloWorkspaceFacetName)

open_workspace_read_session(projection)

Open the canonical immutable session from an already-admitted projection.

Installed composition receives projections from its one captured generation, rather than re-wrapping them as synthetic application outcomes. Both admission paths therefore share the exact version and semantic-identity checks before a renderer can receive the session.

Return type:

ModeloWorkspaceReadSession

Parameters:

projection (ModeloWorkspaceProjectionV1)