Investigation: Audit the journey, provisioning and web-client architecture before the first implementation story

Four documents agree, and none of them needs to change: Journey execution, User Journeys, Document type: user_journey, and the Journey term in Identity and Access Management. They say the same three things: a journey is a definition and not a server-side object; its progress is a workflow instance; and no journey entity is added.

ores.web, the superseded entity specification and Internal Actor Impersonation are also accurate, and the superseded specification records its own retirement. Change notification is accurate and its consumer is genuinely absent: the runtime should read it before it decides how a journey follows a workflow. The component specification is accurate about the shell, the session and the routes it lists, and it repeats the @ores/contracts error in one row of its package table, so it is not counted as clean: see the table below.

1. The progress subject already exists; the progress payload does not. ores.workflow.workflow_instance_changed is published by the engine on every state change (projects/ores.workflow/core/src/service/workflow_engine.cpp:98), and its subject follows the convention the BFF subscribes on — ores.<component>.<entity>_changed, built at projects/ores.web/packages/bff/src/change-events.ts:67. What the engine sends does not match what the browser can read: the payload is an entity_change_event carrying entity_ids, and the schema the browser decodes every change notification with reads alpha2_codes, a field named for the country event it was written for. Every field of that schema has a default, so the mismatch raises nothing and hands the subscriber an empty identifier list. Provisioning progress therefore needs no new subject, but it does need the payload settled, and it needs a read either way, because the event carries identifiers and a time and no state. The mismatch is filed as a capture.

2. A party-provisioning workflow already exists. workflow.v1.parties.provision takes a list of parties and runs a three-step saga per party — refdata.v1.parties.put, iam.v1.accounts.save, iam.v1.account_parties.put_many — with compensation on failure (projects/ores.workflow/api/include/ores.workflow.api/messaging/workflow_protocol.hpp:66). Its response declares workflow_instance_ids, and the handler leaves that vector empty: it publishes each start request and never learns the instance id (projects/ores.workflow/core/src/messaging/workflow_handler.cpp:108-119), so it returns no instance id per party. The new-party journey records this as missing. The real gap is a mismatch: it creates accounts with passwords and does not take an existing party plus chosen accounts, and it does not activate, onboard or publish bundles.

   Two claims in this finding were re-measured on 2026-09-27 and are corrected above. The audit first named the saga's subjects as refdata.v1.parties.save and iam.v1.account_parties.save; no nats_subject uses either name. It also first said the response returns one instance id per party, which the handler does not do.

3. A retry verb is genuinely absent. No retry, resume or abandon subject exists anywhere in ores.workflow. The only recovery is workflow_engine::recover_in_progress(), run once at service start. This is the one provisioning gap the journey documents state correctly.
4. The browser does not use @ores/contracts. projects/ores.web/packages/web/package.json does not depend on it and no file under packages/web/ imports it; the browser parses with @ores/wire-protocol/browser (packages/web/src/api/transport.ts). README.md and packages/contracts/src/index.ts both claim the browser and the BFF share those schemas. They do not.
5. Two HTTP surfaces exist and nothing relates them. ores.http is the platform's REST gateway, with routes generated per component from the models that opt in. It is never mentioned in any ores.web document, yet the site description carries httpBaseUrl (packages/contracts/src/site.ts:56) and the wire client carries discoverHttpBaseUrl() (packages/wire-protocol/src/client.ts:430), which has no caller anywhere. Nothing states whether the gateway and the BFF are alternatives or layers.
6. The decision record behind the generated wire types is wrong in four ways, and it is the page that anchors the work the first task does. projects/ores.web/modeling/0001-protocol-types-from-codegen.org says the codegen template is not built (the templates exist and the output is committed), that the artefact lives in the C++ repository (it lives under packages/wire-protocol/src/generated/), that the ores.codegen.operation model is deferred (26 models use it), and that hand-writing the TypeScript schemas is the current state. It is the See-also of the component specification, so whoever adds the journey client methods reads it first and is told to hand-write what the generator already produces.
7. The shell is a second client of the same three journeys, and it orchestrates on the client today. ores.shell carries the Setup journeys as porcelain commands — provision system, provision tenant and provision party, 696 lines in one file — which publish bundles, wait on workflows, generate a synthetic organisation and associate the administrator with the operational parties themselves. Three recipes under doc/recipes/shell/provisioning/ run a whole system provisioning, one per value the --source flag accepts, and they are the only artefacts in the tree that take an empty database to a working tenant: acme_system_provision.org on the synthetic path, barclays_system_provision.org on the GLEIF path, and how_do_i_provision_the_system_with_acme_corporation_holding_group.org on the acme path, which reaches the synchronous handler. The accepted seed profile contract already decided the outcome: the shell becomes a thin caller and its client-side orchestration is deleted. So this is accepted, unimplemented scope rather than new work, and the audit missed it because it read the shell only as a consumer of the recipes that named the subjects being retired.

1. The client-side journey runtime. No document defines a step definition: its fields, its declared inputs, which subject it calls, which steps are final, or how one journey inlines another's steps. Journey execution and the document type both name "an ordered list of steps" and stop there. The only implementation is on a throwaway branch, and its source path on main is dead.
2. The step-call contract. How a step reaches a subject — which BFF route, which wire-client method, and what a route may not do — is stated nowhere. The component specification lists the routes that exist today and says only that "a journey screen adds the call it needs".
3. The bootstrap gate. The setup story requires that /setup is the only page while system.bootstrap_mode is set. No architecture document describes that gate.
4. The two HTTP surfaces. See finding 5 above.
5. The ownership of seed-profile data and the step-kind catalogue. The seed profile contract fixes the step kinds and says a profile is rows, and names neither an owning component, a model, nor a codegen path.
6. Where the provision-tenant workflow definition lives and how it registers. The only account of definition registration is in doc/plans/2026-05-14-workflow-engine-hardening.org, not in doc/knowledge/architecture/.
7. What carries the rail position for the human steps. A workflow journey's server work is resumable, but the steps around it — sign in, choose a party, set a password — are not, and nothing states whether the person can leave and come back to them. The prototype held the position in memory.
8. Which standard governs the TypeScript client. The Component Clean Standard names no TypeScript item, and the clean-standard programme story records that "the TypeScript UI is retired". That is true of the generated entity screens and of the TypeScript UI codegen, and false of ores.web, which is now the interface being built.
9. The mapping rule from a browser request to a NATS subject. The BFF is hand-mapped: each handler calls session.client.callAuthenticated(subject, schema), and there is no generic forwarding proxy. Nothing states the rule, what the BFF may not do, or how a route is added. This is the second half of the step-call contract, and the first task cannot settle one half without the other.
10. The dependency direction between the four packages, and why the browser must import @ores/wire-protocol/browser rather than the package root. The component specification gives each package a job and states no direction between them.
11. The end-to-end path from a model to a validated browser response — model, to facet, to src/generated/, to the browser entry point, to the BFF reply, to the Zod parse. It is covered in three places and in none of them whole, and the decision record that should anchor it describes a state that no longer exists.