cadrumo.application.operator_actions.catalogue module

Canonical declarations for operator next actions.

An entry states only the stable action identifier, its canonical result-schema command key, and where a later verdict may obtain each named argument. Adding an action means appending one ActionCatalogueEntry literal to OPERATOR_ACTION_CATALOGUE; applicability remains with the application guard and live command/input resolution remains with the operator-surface projection.

class ActionArgumentBindingSpecification(**data)

Bases: BaseModel

Declare how an application outcome may materialise one target argument.

This is deliberately distinct from the value-bearing ActionArgumentBinding on a verdict. It admits a source strategy but contains neither a runtime value nor a resolution status.

Parameters:

• argument_name (str)

• source (ActionArgumentSource)

• source_key (str)

• source_evidence_id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=160, pattern=^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$, ascii_only=None)] | None)

argument_name: str

source: ActionArgumentSource

source_key: str

source_evidence_id: NamespacedId | None

class ActionCatalogueEntry(**data)

Bases: BaseModel

One stable next action projected to a canonical command-schema key.

Parameters:

• action_id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=160, pattern=^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$, ascii_only=None)])

• target_command_key (str)

• argument_specifications (tuple[ActionArgumentBindingSpecification, ...])

action_id: NamespacedId

target_command_key: str

argument_specifications: tuple[ActionArgumentBindingSpecification, ...]

class ActionCatalogue(**data)

Bases: BaseModel

Immutable deterministic action-id registry with fail-closed lookup.

Parameters:

entries (tuple[ActionCatalogueEntry, ...])

entries: tuple[ActionCatalogueEntry, ...]

lookup(action_id)

Return the one declaration for action_id or fail closed.

Return type:

ActionCatalogueEntry

Parameters:

action_id (str)

build_action_catalogue(entries)

Construct a deterministic catalogue from declarations supplied by one owner.

Return type:

ActionCatalogue

Parameters:

entries (Iterable[ActionCatalogueEntry])

OPERATOR_ACTION_CATALOGUE

Initial evidence-grounded actions for profile and workflow migrations.

The catalogue expands only as an owned producer-to-projection slice introduces another canonical action. It does not infer actions from command strings and does not make external-environment remediation appear executable.

lookup_action(action_id)

Look up one declared operator action in the canonical catalogue.

Return type:

ActionCatalogueEntry

Parameters:

action_id (str)

next_action(action_id)

Resolve a zero-argument action into a fully materialised notice action.

Forward guidance on a SUCCESS path used to be a literal aeat ... string inside a locale message. That is untestable and rots silently: renaming a verb sweeps the registrations and leaves four translated catalogues naming a command that no longer exists, handing the operator - frequently an non-interactive caller - an instruction it cannot recover from.

Resolution runs through lookup_action(), which fails closed on an unknown id, so the command key comes from the catalogue rather than from prose and a renamed action raises here instead of shipping.

This lives beside the catalogue rather than in the CLI transport because the application layer also emits such notices; a CLI-owned helper would force an application module to import entrypoints, against the layer direction.

Parameters:

action_id (str) – A namespaced id declared in the operator action catalogue.

Return type:

ResolvedNoticeAction

Returns:

The fully materialised action to attach as Notice(action=...).

Raises:

KeyError – action_id is not declared in the catalogue.