Story: Clean ores.workflow to the component clean standard

Table of Contents

This page documents a story in Sprint 26. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

ores.workflow meets the Component Clean Standard: every item: All, Protocol and Entity pass, each item that does not apply is recorded with its reason, and ores.workflow joins COMPONENTS_UNDER_TEST. Order 22 of 35 in the sprint 26 component clean-up, tier 2 (higher infrastructure).

2. Status

Field Value
State DONE
Parent sprint Sprint 26
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-10-02

3. Acceptance

  • Every checklist item that applies to a component of kind Entity passes, with its evidence recorded on the task.
  • Every item that does not apply is recorded as not applicable, with the reason.
  • Every generator defect found is fixed at its source, with a regression test.
  • ores.workflow is listed in COMPONENTS_UNDER_TEST, and check_component_drift.py --all passes.

4. Tasks

Task State Start End Description
Bring ores.workflow to the clean standard DONE 2026-09-26 2026-09-26 Work ores.workflow through the Component Clean Standard in order and record each item.
Model the workflow query protocol as an operation DONE 2026-10-01 2026-10-02 ores.workflow's query, steps and retry protocols are hand-written C++, and ores.web mirrors them by hand. A missing optional field silently broke the tenant roster's run read. Model them as one ores.codegen.operation, generate C++ and TypeScript, delete the hand mirrors, and commit the workflow entity TypeScript.
Close the workflow verification items DONE 2026-10-02 2026-10-02 Survey V07 and V08 for ores.workflow, fix the vacuous half-target test, add tests for the retry handler, the instance-list filters and the service config parser, record each untested file's reason, and close the story.

5. Notes

  • Survey on 2026-09-23: 2 entity, junction or operation models; 53 C++ files outside tests, 0 of them generated (0%); 8 messaging headers, 8 of them hand-written.
  • Nothing is generated yet. Workflows are operations, not entity verbs (P04).

6. Decisions

  • The party provisioning workflow is deleted, not moved. The first task chose option 2, each commissioner owns its payload, and planned to move provision_parties to refdata. Nothing sends workflow.v1.parties.provision: the shell and the web provision a party through iam.v1.parties.provision. The workflow is deleted with its payload, handler, definition and permission, which reaches option 2's goal with no dead code to move. (Product owner, 2026-10-02.)
  • One operation model holds the whole conversation. The start message, the step event, the step result, the run, step and definition reads and the retry are one ores.workflow.workflow_messages model, because the TypeScript projection cannot reference a message in a sibling model. (Implementation, 2026-10-02.)
  • What a model cannot state stays in one header. The step outcome and log level enumerations, their reflectors and the NATS header names are in workflow_vocabulary.hpp. The enumerations are registered custom types, so they cross to TypeScript as strings. (Implementation, 2026-10-02.)
  • An empty filter is no filter. The instances list filters were std::optional<std::string> and are plain strings with an empty default. The handler already read an empty value as no filter, and the shell can only fill a field with a default. (Implementation, 2026-10-02.)
  • Two shell verbs stay hand-written. workflow wait polls and workflow start publishes on the stream with no reply, so neither is a message the shell facet can generate. They join the generated workflow menu through extend_menu. (Implementation, 2026-10-02.)

7. Result

ores.workflow meets the Component Clean Standard. Three tasks did it:

  • Bring ores.workflow to the clean standard regenerated the component, wired its registrars, generated its entity shell units and entered it in COMPONENTS_UNDER_TEST (PRs #2173, #2179). It closed with the Protocol section, V07 and V08 open, and its rows now say so.
  • Model the workflow query protocol as an operation put the whole operation conversation in one model, generated its C++, TypeScript and shell, deleted the party workflow nothing started, and fixed a definitions read that timed out for every caller (PR #2498).
  • Close the workflow verification items surveyed V07 and V08, repaired a refusal test that could not fail, and tested the retry handler, the list filters and the service config parser.

check_component_drift.py --all passes with workflow-cpp listed. The engine still links the components that commission it; that is the capture The workflow engine depends on the components that commission it.

8. Out of scope

Emacs 29.3 (Org mode 9.6.15)