Story: Implement the setup journeys in ores.web

A browser pointed at an empty installation takes a person from nothing to a working installation, and then to as many tenants and parties as they need. Three Setup journeys run against the real server:

• First run — the system administrator, the first tenant inline, the first sign-in, and Ready. This is the only journey in the catalogue that can run on an empty database.
• New tenant — the same steps on their own, for every tenant after the first.
• New party — a legal entity added to a tenant, with the accounts that work in it.

The three share one runtime and one step library. First run expands the new tenant steps inline, so the person sees one flat rail of eight steps and never a journey inside a journey.

This is the first group of Implement the user journeys in ores.web, and it lands the two things every later group needs. The runtime, because a journey is an ordered list of steps and one page renders that list. And the provisioning contract, because provisioning is server-side work that takes minutes and can fail half way, and no journey in the catalogue can be honest about a half-finished installation until the state and the progress are real.

• First run runs in ores.web, from an empty database to Ready, against the real server. No step is simulated and no profile is held in the code.
• New tenant and New party run on the same runtime. They reuse the new tenant step library, and first run inlines those same steps.
• The provisioning progress is server-side. A person can close the page and come back and continue. A failed step stops the instance, and a retry resumes from that step and keeps the steps that completed.
• The seed profiles are registered data. Adding a profile is adding a row; adding a step kind is code.
• A profile may force a password change, and neither card does. The provisioner marks the account when the starting point asks for it and the login answer reports the mark, so a deployment that wants the tenant administrator to set a password only they know states it in the profile's row; the Operational card asked for it until the journey was walked, and the product owner chose to drop it.
• The password rules the screen shows are the rules the server enforces, read from the server rather than declared in the client.
• The bootstrap gate holds. While the system is in bootstrap mode the Setup page is the only page, and nobody can sign in.
• A scripted end-to-end run proves the path on a fresh database, in the shape of scripts/verify-login.ts.
• The shell drives the same three journeys through the same contract. bootstrap setup, provision tenant and provision party call the generic provision request this story added, and the end-to-end provisioning recipes under doc/recipes/shell/provisioning/ each run from an empty installation to a working tenant without orchestrating anything client-side.
• Every gap the three journey documents record is closed, or stated on the screen and recorded in this story.

The architecture change lands first, because step 1 decides the runtime and the step-call contract and cannot decide them against documents that still contradict each other.

The steps are ordered so that each one leaves a state a person can look at. The first three land before the provisioning contract, because none of them depends on it and all of them are permanent.

• The gate answers the deployment, not the tab. An installation is set up when it has an administrator and a tenant of its own, so the setup screen is the only screen while either is missing, and the tab's own memory holds the rail afterwards, until the person finishes. The earlier rule stopped at the administrator, which left a browser that reloaded half way through stranded on a sign-in screen with no way back to the work: closing a page is not finishing a journey. The deployment's state survives a reload; a position held only in memory does not, so the rail opens at the step that signs in as the administrator the deployment already has rather than at the beginning.
• The three journeys share one runtime and one step library. First run inlines the new tenant steps. Positions in the rail are named rather than counted, so adding a step to one journey cannot silently shift the meaning of another.
• The accepted contracts are the target. The design retires iam.v1.bootstrap.provision-tenant and iam.v1.tenants.provision-acme; the generic request replaces both, first tenant included. iam.v1.bootstrap.create-admin stays, because the accepted contract keeps system bootstrap to the system administrator alone.
• The seed profile is data. A profile orders step kinds from a fixed catalogue, so a new profile is a row and a new step kind is code. The screen builds its form from the profile's declared parameter schema and holds no profile of its own.
• A step kind reads what it acts on from its own arguments. A profile's row states the bundles, the parties, the datasets and the keys a kind works from, so the executor holds no profile's names and one kind serves every profile that orders it. A kind that needs the run's parameters reads them too, which is how a form supplies an LEI the row leaves out. A row whose kind cannot be honoured is refused before the run starts, naming the kind, so no card can half-provision a tenant.
• A party is named by the legal name its hierarchy import created it with. A party's external identifier is guarded by party isolation, which a step's own context does not carry, so the name is the handle the profile can state and the deployment's party read answers.
• A run belongs to the tenant that asked for it. The progress read answers the tenant that owns a run and nobody else, so a provisioning run owned by the tenant it creates could not be followed by the person who asked for it: their session is in another tenant. The run's tenant scopes its rows and the tenant it provisions travels in the request, so the starter can watch and resume their own work and no tenant gains a view of another's runs.
• The failure policy belongs to the definition. A definition declares whether a failed step rolls its completed work back or stops the run on that step. Provisioning declares stop, because its completed work is published data a person expects to keep; the default stays compensate for a short saga of writes. A stopped run keeps every completed step and waits for a retry.
• Every kind fails its step rather than half-finishing it. The engine keeps the steps that completed and stops the run on the one that failed. The synchronous ACME handler the work was lifted from is not the model: it reported no step, so its uneven best-effort behaviour is not carried.
• The tenant's type is the starting point's, and a replaced verb retires with its last caller. A tenant row carries a type that a lookup table validates, and the profile states it: Operational's tenants are production and ACME demo's are evaluation. The column went on seed_profile rather than the provision request, because a request that named the type would be a second starting point beside the one the person chose. For the same reason the two verbs the generic request replaces stay reachable until their last caller moves: the shell is that caller, plan step 12 is where it moves, and the work the ACME verb orchestrates server-side is the work the provisioning definition orders — retiring it before step 7 would leave --source acme creating a tenant with none of its data.
• The provisioning steps are idempotent. A retry resumes from the failed step and keeps the steps that completed. Discarding a half-provisioned tenant is a separate administrator action.
• The journey's state is a workflow instance. It already carries the kind, the current step, the request, the result and the error. No journey entity is added, and no subject returns a journey as an object. Journey execution records why.
• Bootstrap mode is the system setting system.bootstrap_mode. ores_iam_create_initial_admin_fn clears it, so the gate closes when the administrator is created and not before.
• The prototype is the design record for the rail, not for the code. prototype/first-run-journey is the accepted authority on the step sequence, the copy and the layout. The variants that lost, and the prototype switcher, are not carried.
• ores.workflow is another environment's component. Two of its stories are in flight: its clean-up and its end-to-end exercise. This story consumes the engine and adds the retry verb the journey needs. It does not rewrite the engine or its models.
• A step reaches the server through one hand-written BFF route per step, each parsing a generated schema and each listed in The component specification. There is no generic forwarding route, so the browser cannot name a subject.
• The BFF is the browser's only HTTP surface. ores.http serves external clients, and the browser never reaches it.
• Only the server-side workflow resumes. The steps around it hold no server state, so a journey progress record is not added and the decision that no journey entity is needed stands.
• ores.iam owns the seed profile, its parameter schema and the step-kind catalogue.
• The architecture documents are corrected before this story's first task starts. The audit found the accepted sprint 25 catalogue still mandating a journey entity and shell journey commands, three journey documents claiming ores.workflow does not exist, and no page defining the runtime at all. The answers above are recorded in that audit and land as their own documentation change.

• Every journey has two clients, and the shell is the other one. ores.shell carries the three Setup journeys as porcelain commands — bootstrap setup, provision tenant and provision party. The recipes under doc/recipes/shell/provisioning/ run a whole system provisioning, one per starting point, and between them they cover the three journeys this story builds in the browser:

  • barclays_system_provision.org creates barclays from the GLEIF starting point with the hierarchy's root LEI, then runs the party stage and sets the default party.
  • how_do_i_provision_the_system_with_acme_corporation_holding_group.org creates acme_corporation from the demonstration starting point, whose own steps import the Acme hierarchy, publish each party's data, attach the staff photographs and start the market feeds. It stops after the tenant stage and additionally publishes the vendored compute packages, so it is the only one that does not run the party stage on its own.
  • tenant_provision.org adds a tenant to a system that is already set up, which is the New tenant journey's shell form.

  A step's contract therefore has two callers from the day it lands, and a contract that suits only one of them is wrong.

• The shell's provisioning orchestration is replaced, not preserved. The accepted seed profile contract already decided this: "ores.web and ores.shell are thin callers. The shell's client-side orchestration is deleted." The three porcelain commands were 696 lines that published bundles, waited on workflows, generated a synthetic organisation and associated parties themselves. That landing left bootstrap setup, provision tenant and provision party as thin callers of iam.v1.tenants.provision and iam.v1.parties.provision – the same subjects the browser calls – and retired the verbs the shell was their last caller of. The synthetic organisation generator went too: provisioning creates no synthetic parties, and synthetic tenants and parties are their own work when they return.
• The shell is lined up in the same group, not afterwards. A shell that still drives the retired subjects while the browser uses the new one is two clients disagreeing about what provisioning is, and the disagreement is invisible until somebody runs one of those scripts.
• The three end-to-end provisioning recipes are the acceptance sequence. They are the only artefacts in the tree that take an empty database to a working tenant, one per provisioning path, and between them they cover the three journeys — two of them through the party journey as well as the tenant one. All three are kept working, and they are what the story's last plan step runs.
• The scripted proof drives the browser's client, not a browser. The last acceptance line asks for a run in the shape of verify-login.ts, and that verifier asserts against the real system with no screen in the way. scripts/verify-first-run.ts is the same: it calls the browser's own client, its own request-building and its own password rules, and supplies only the two things a browser provides and Node does not — a base address for the relative paths and a jar for the session cookie. An answer the browser could not parse fails it, because the browser's schema is what parses it. A driven browser would prove the rendering too, and would fail for reasons that are not the contract's: the rails and the screens are covered by the web suite, and the path is covered here.
• A journey that can only happen once is proved on a fresh database or not at all. The proof's first assertion is that the installation still needs its administrator, and a deployment that is already set up is refused rather than half-walked. The alternative — a script that sets a deployment back into bootstrap mode — would prove a state no person reaches.
• A starting point that needs a legal entity asks the deployment for it. The Operational card declared its root LEI as free text while the GLEIF entity card searched the register, so one card could be answered only by somebody who already knew a code. Both now declare legal_entity, which the form renders as the search over the deployment's entities and the parameter check guards, and the entity stays optional because a tenant nobody holds an entity for is still a tenant: its parties come from the party stage.

The three journey documents name what they still reach for, and none of it is silent. Each gap is either owned by a document of its own or stated here:

• A tenant cannot be reset in a way that also stops its run. Retire or reset a tenant records it.
• The engine's change event cannot be read by the browser, because the shared schema reads a country-shaped field. The progress read is the contract instead, and the mismatch is captured.
• The party describe step carries no accounts picker. Nothing writes the chosen associations — the run joins the caller alone — and a picker whose choices went nowhere would be worse than no picker.
• Where a party hangs is the deployment's answer and not the person's. Draw the reporting line is that journey.
• The standalone /tenants/new and /parties/new routes are walked in a browser and recorded as evidence rather than scripted. Only the first run can happen on an empty database, and that is the path the scripted proof walks.

• The Tenants and Parties pages as permanent homes. The journeys link to them; the pages are their own work.
• The Entry group. First run signs in through the path that exists. The Entry story builds the screen, self registration and the failure paths.
• The seed profile step kinds that no profile uses yet.
• The ores.qt bootstrap wizards, which are evidence and not a design.
• The producer of a profile's bundles, which belongs to the component that owns that data.

Both clients run the three Setup journeys' work against the same contract, and nothing is left of the provisioning the wizards did client-side. The browser sets an empty installation up from the setup page — the first administrator, the first tenant from a registered starting point, the hand-over, the first sign-in and Ready — and a reload comes back to the rail rather than stranding the person. The shell says the same things with bootstrap setup, provision tenant and provision party, each sending one request per stage and following the run through the same progress read the browser's rail renders, and the end-to-end recipes each ran from their own empty installation to a working tenant. The two verbs the generic request replaced retired with the shell, and so did the generated duplicates of the porcelain commands and the synthetic organisation generator. Every acceptance line is met, the last one by scripts/verify-first-run.ts, and the Operational card now chooses its root legal entity from the deployment's register rather than taking a code it cannot check.