cadrumo.entrypoints.tui.navigation module

Closed, frontend-only navigation contracts for the TUI root.

The root owns route composition. It receives truthful admission outcomes and screen factories from its caller; this module does not read application state, perform I/O, translate labels, or import a concrete destination screen.

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

Bases: CadrumoError

Base error for an invalid or non-admittable navigation contract.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

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

Bases: NavigationContractError

Raised when a destination is outside the closed catalogue.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

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

Bases: NavigationContractError

Raised when an admission does not match the route it claims.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

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

Bases: NavigationContractError

Raised when navigation tries to open a non-available route.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

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

Bases: NavigationContractError

Raised when a search action candidate has no catalogue declaration.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

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

Bases: NavigationContractError

Raised when a route cannot produce a valid Textual screen.

Parameters:

• message (str | None)

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

• translated_message (str | None)

Return type:

None

code

class TuiDestinationDescriptorV1(**data)

Bases: BaseModel

Static metadata for one shell destination.

Parameters:

• destination (TuiDestinationIdV1)

• label_key (TuiDestinationLabelKeyV1)

• zone (TuiDestinationZoneV1)

destination: TuiDestinationIdV1

label_key: TuiDestinationLabelKeyV1

zone: TuiDestinationZoneV1

class TuiDestinationAdmissionV1(**data)

Bases: BaseModel

Truthful, explicit admission for one closed destination.

The state enum is owned by the S368 workbench projection. Reusing it keeps search results and shell routing on one vocabulary for unavailable, stale, locked, and never-captured destinations.

Parameters:

data (Any)

destination: TuiDestinationIdV1

state: WorkbenchDestinationAdmissionState

reason_code: NamespacedId | None

classmethod from_workbench(admission)

Adapt the S368 search admission without widening its state set.

Return type:

Self

Parameters:

admission (WorkbenchDestinationAdmission)

class TuiFocusIdentityV1(**data)

Bases: BaseModel

A stable semantic focus address independent of rendered row position.

Parameters:

data (Any)

destination: TuiDestinationIdV1

semantic_key: NamespacedId

restore_token: Hex64Str | None

class TuiNavigationTargetV1(**data)

Bases: BaseModel

A destination plus the semantic focus to restore after mounting it.

Parameters:

data (Any)

destination: TuiDestinationIdV1

focus: TuiFocusIdentityV1

action_candidate_id: NamespacedId | None

class TuiScreenContextV1(**data)

Bases: BaseModel

Immutable context handed to an injected destination screen factory.

Parameters:

data (Any)

destination: TuiDestinationIdV1

focus: TuiFocusIdentityV1 | None

action_candidate_id: NamespacedId | None

class TuiScreenFactoryV1(*args, **kwargs)

Bases: Protocol

Build one host-agnostic Textual screen from an admitted context.

class TuiActionCandidateV1(**data)

Bases: BaseModel

A declared action candidate that a result may refer to.

Parameters:

data (Any)

action_candidate_id: NamespacedId

destination: TuiDestinationIdV1

class TuiDestinationRouteV1(descriptor, admission, factory=None, action_candidates=())

Bases: object

One descriptor, admission, optional factory, and admitted actions.

Parameters:

• descriptor (TuiDestinationDescriptorV1)

• admission (TuiDestinationAdmissionV1)

• factory (TuiScreenFactoryV1 | None)

• action_candidates (tuple[TuiActionCandidateV1, ...])

descriptor: TuiDestinationDescriptorV1

admission: TuiDestinationAdmissionV1

factory: TuiScreenFactoryV1 | None

action_candidates: tuple[TuiActionCandidateV1, ...]

action_candidate(action_candidate_id)

Resolve one action candidate declared by this route.

Return type:

TuiActionCandidateV1

Parameters:

action_candidate_id (str)

declared_destination_ids()

Return the destination set from the closed type alias.

Return type:

frozenset[str]

TUI_DESTINATION_CATALOGUE: Final[tuple[TuiDestinationDescriptorV1, ...]]

The static, localized-key-only destination catalogue.

class TuiDestinationCatalogueV1(routes)

Bases: object

Immutable runtime catalogue assembled from explicit admissions/factories.

Parameters:

routes (Iterable[TuiDestinationRouteV1])

property routes: tuple[TuiDestinationRouteV1, ...]

Return the immutable route sequence.

resolve(destination)

Resolve one closed destination identity or fail closed.

Return type:

TuiDestinationRouteV1

Parameters:

destination (str)

target_for_search_result(result)

Turn an S368 result into an admitted semantic navigation target.

Return type:

TuiNavigationTargetV1

Parameters:

result (WorkbenchSearchResult)

create_screen(target)

Invoke the injected factory for an admitted target.

Return type:

Screen[None]

Parameters:

target (TuiNavigationTargetV1)

build_destination_catalogue(*, admissions, factories=None, action_candidates=())

Compose the closed catalogue from caller-supplied boundary values.

Return type:

TuiDestinationCatalogueV1

Parameters:

• admissions (Mapping[str, TuiDestinationAdmissionV1 | WorkbenchDestinationAdmission])

• factories (Mapping[str, TuiScreenFactoryV1] | None)

• action_candidates (Iterable[TuiActionCandidateV1])