Journey execution

Four words are in play and they are not synonyms. Each sits at a different level.

A step is one of two kinds, and the kind decides whether it survives a reload.

• A workflow step runs server work that takes time. Its progress is the workflow instance, so the person can leave and come back, and a retry resumes it.
• A human step waits on the person: a sign-in, a new password, a party chosen. Nothing on the server records that the person is here, so the step does not survive a reload. The journey document must say which steps those are, because the screen has to be honest about it rather than implying the whole rail is resumable.

The temptation is to call the workflow instance a "journey" too, because it holds a journey's state. Resist it, because the journey is not server-side; its state is. That sentence settles the confusion, and it is why this page drops the phrase "server-side journey" altogether: it is a category error, not a distinction.

The same reasoning means no second entity is needed. workflow_instance already carries everything a journey's progress requires: type names the journey, beside state_id, step_count, request_json, result_json, error and completed_at. The chain the run was started with is not a column on it: the run's plan steps and the dependencies between them are their own relations, so a run is judged by the chain it was given rather than by the definition as it stands now. A journey is the definition; a workflow instance is that definition running. The bootstrap map's decision to add "a journey entity in ores.workflow, next to workflow instance" is therefore redundant, and the cheapest time to notice that is before it is built.

A saga is a way to keep several writes consistent without holding one transaction: a sequence of local transactions, each with a compensating action, coordinated so the whole either completes or is undone in part. Its defining property is that it is not atomic, and that intermediate states are visible.

That makes it a different kind of thing from a journey, at a different level:

• A journey is what the person does. A saga is how the system stays consistent.
• One journey step may be a saga; a journey may contain no saga at all.
• A saga can exist with no journey anywhere near it, as when one service calls another.

So "saga" cannot replace "journey" — doing so would name the person's experience after an implementation pattern. The useful move is the opposite: where a journey step is a saga, the journey document must say so, because the screen then has to be honest about partial state rather than implying the work either happened or did not.

Every journey falls into one of four classes. The class is a property of the journey, and it decides how much machinery the journey gets. Most journeys need none.

Only two of the four want a service, and for different reasons: composite wants a transaction boundary, workflow wants resumable state. A read-model journey wants a query that returns the joined rows in one request, not a service and not a call per row.

This is the decision that the phrase "a service with the journey's interface" hides. A service that makes five subject calls still makes five transactions. The half-way failure does not disappear; it moves to the server, where it is harder to show the person what happened. Correctness across several writes needs one of two things, and the choice is per step:

• One transaction. One subject, the server applying several tables' writes together. Atomic. Use it when the writes are one conceptual act that cannot sensibly be half-done — creating an account is the account, its contact record, its parties and its role, and the person thinks of that as one thing.
• A saga. Idempotent steps, recorded progress, a compensating action each. Not atomic, intermediate states visible. Use it when the work is long or crosses services, and recovery matters more than isolation.

Choosing "a service" without choosing between these changes nothing observable, which is why the class must be recorded per journey rather than assumed.

A coordinator is a state machine over commands. It may own order, idempotency, retry, compensation and progress. It must not own field validation, business rules or SQL, and the entity subjects remain the only write path.

That is not a stylistic preference. The repo already carries the counter-example. account_setup_service is a coordinator, and its own header says:

Use this service instead of calling account_operations_service::create_account() directly to ensure accounts are properly initialized with roles.

A comment telling callers which of two creation entry points to use is a contract that cannot be enforced. The consequences are already visible: save_account_request carries account_type, the coordinator does not pass it on, and the layer beneath hard-codes new_account.account_type = "user";, so a service account cannot be created at all. The same shape appears one layer up, where account_handler.hpp and account_operations_handler.hpp both handle the account entity and the permission guard was applied to one and not the other — one of the ores.iam handler permission defects the security hardening has since closed.

So the guard rails are: one entry point per concern; a declared contract for what a coordinator must preserve; and a test that a request field reaches the table. Where a journey is composite, prefer a single subject over a coordinator, because it removes the seam rather than policing it.

Fifteen of the twenty-one journeys are runs of immediate operations, and one, See who has access, is a read model, so sixteen need none of the machinery above. The five that do are the three Setup journeys, which are workflows, and Bring someone in and Change someone's details, which are composite. A journey with several writes is still direct when each write is its own step and none has to land with another, which is the shape Register a service account has; it is direct for that reason, not because its step count is small.