cadrumo.application.overview.next_actions module

Locale-neutral next-action declarations shared by every overview read model.

The overview surfaces used to state their forward guidance as literal aeat command strings on application records (next_command, fix_command) and inside locale prose. That put executable identity in four translated catalogues and in three unrelated producers, so a verb rename silently handed the operator a dead instruction, and the text and JSON surfaces each rebuilt the advice from different material.

Producers here name a stable catalogue action and the concrete arguments their own outcome already holds; nothing else. Resolution against the live command tree and its required inputs belongs to the operator-surface projection, which refuses a declaration it cannot fully materialise - so an unexecutable step can never be dressed up as an executable one.

A step whose real continuation needs operator-supplied input the read model cannot know (which statement file to import, which document to attach) declares no action at all. That is the honest outcome: the guidance survives as localized prose, and the executable channel stays empty rather than shipping a placeholder command.

See also

DeclaredNextAction

The shared producer-side record every declaration here returns.

application.operator_surface

Owner of catalogue lookup and live required-input coverage.

declare_next_action(action_id, /, **arguments)[source]

Declare one catalogue action from concrete producer-outcome values.

Every argument is verdict-context provenance: the value comes from the read model’s own resolved outcome rather than from operator request input or from a failed condition’s evidence.

Parameters:

  • action_id (str) – A namespaced identifier declared in the operator action catalogue. An unknown id fails closed at resolution, not here.

  • **arguments (str | int) – Target argument names mapped to the concrete values this producer holds. The catalogue must declare a matching verdict-context source for each name.

Return type:

DeclaredNextAction

Returns:

The producer-side DeclaredNextAction.

class OverviewStatusNextStepId(*values)[source]

Bases: StrEnum

Closed identifier for one overview status forward-guidance row.

The identifier is the whole presentation contract: the renderer resolves it to localized prose, and the executable half rides on the row’s optional declared action. Neither the identifier nor the producer carries text.

Variables:

  • CREATE_PROFILE – No active profile exists, so nothing else can be scoped until one does.

  • RESUME_WORK_UNIT – Work units exist; list them and resume one.

  • START_ANOTHER_WORK_UNIT – Work is already under way; a further modelo may still need its own work unit.

  • START_WORK_UNIT_FROM_LEDGER – Ledger data exists but no work unit does; the declaration can be started from that data.

  • MODELO_210_SEDE_ONLY – Modelo 210 is discoverable but has no local work-unit creation path, so the row diverts to its description.

  • REVIEW_LEDGER – Imported rows are waiting for review.

  • IMPORT_TRANSACTIONS – The ledger is empty; a bank statement must be imported before anything else can proceed.

  • REPAIR_STORAGE – Local rows could not be read, so the storage diagnostics surface should be run before the numbers are trusted.

  • COMMAND_GUIDE – Return to the top-level command guide.

CREATE_PROFILE
RESUME_WORK_UNIT
START_ANOTHER_WORK_UNIT
START_WORK_UNIT_FROM_LEDGER
MODELO_210_SEDE_ONLY
REVIEW_LEDGER
IMPORT_TRANSACTIONS
REPAIR_STORAGE
COMMAND_GUIDE
class OverviewStatusNextStep(**data)[source]

Bases: BaseModel

One ordered forward-guidance row for overview status.

Variables:

  • step_id – Closed OverviewStatusNextStepId the renderer resolves to localized prose.

  • next_action – The executable continuation when one exists and every required input is already known, otherwise None.

Parameters:

data (Any)

step_id: OverviewStatusNextStepId
next_action: DeclaredNextAction | None
build_overview_status_next_steps(report)[source]

Return forward guidance that reflects the actual workspace state.

A workspace with ledger data already recorded must not be told to import a bank statement - that step is done. The guidance walks the operator forward: import when the ledger is empty, review and start a declaration once transactions exist, resume the modelo flow when work units are already in progress. A Modelo with no local work-unit creation path is diverted to discovery instead of a dead command.

Parameters:

report (OverviewStatusReport) – The assembled workspace status read model.

Return type:

tuple[OverviewStatusNextStep, ...]

Returns:

The ordered guidance rows, each carrying its executable continuation when one is fully known.