Journey execution

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

The temptation is to call the second one 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, current_step_index, step_count, materialised_steps_json, request_json, result_json, error and completed_at. 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 defects in IAM handlers skip their permission checks.

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.

Sixteen of the twenty-one journeys are direct or read-only, and need none of this.