Story: Integrate the Volga TypeScript UI as ores.web
Table of Contents
This page documents a story in Sprint 25. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
1. Goal
The Volga prototype is a TypeScript web interface for ORE Studio. It lives outside the repository, and it copies the codegen TypeScript output by hand. This story adopts it as projects/ores.web, generates its TypeScript from ores.codegen, retires projects/ores.typescript, and adds the component to the services subsystem so that compass services start launches the web interface on a port inside the environment range.
2. Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 25 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-09-19 |
3. Acceptance
projects/ores.webholds the prototype, renamed to ORE Studio conventions.ores.codegenwrites the TypeScript intoprojects/ores.web, andprojects/ores.typescriptis removed.- A check proves that the generated TypeScript is in step with the org model.
compass services startlaunches theores.webservice with a port inside the environment range.- The component typechecks, and its tests pass.
4. Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Adopt the Volga prototype as projects/ores.web | DONE | 2026-09-19 | 2026-09-19 | Copy the Volga TypeScript web UI into projects/ores.web, rename it to ORE Studio conventions, remove the committed build artefacts and secrets, add the licence headers, and declare the component in the build. |
| Generate the ores.web TypeScript from ores.codegen | DONE | 2026-09-19 | Retarget the ores.codegen TypeScript output to projects/ores.web, delete the hand-copied generated files and the ores.typescript component, and add a check that proves the generated TypeScript is in step with the org model. | |
| Add the ores.web service to the services subsystem | DONE | 2026-09-19 | Declare ores.web as a service so that compass services start launches it, assign it a port inside the environment port range, and wire its environment through the environment mapper. | |
| Verify and document ores.web | DONE | 2026-09-19 | Run the component typecheck, its unit tests and the browser verification against the running environment, write the component documentation, and record the result. |
5. Decisions
- One listener, one port. The environment block allocates a fixed set of
ports per environment and expects one port per service. The BFF therefore
serves the built browser bundle and the API on
ORES_WEB_PORT, and Vite stays a development-only tool onORES_WEB_DEV_PORT. Two processes would have spent two offsets and added a cross-unit start ordering for no gain. - The port is the retired Wt slot.
ORES_WEB_PORTis offset 2 ofORES_BASE_PORT, which the removed Wt client held; offsets 0, 1, 4, 5 and 6 stay as they are, so no live environment is renumbered. - The service is a registry entry, not a wrapper.
systemd_generategains anoderuntime and rendersType=simpleitself, rather than calling a shell shim dropped intopublish/binby hand. The same model property is what a future macOS or Windows generator would read. - The generated tree holds only generated files. The hand-written
ui-contract.tsmoved out ofsrc/generated/topackages/web/src/, so a wholesale codegen clean cannot delete it and a drift check cannot mistake it for output. - Only the drift-free components emit committed output. A full
regeneration also produces UI metadata for
dq,schedulerandtrading, whichcheck_component_drift.py's registry does not cover, so that output could not be verified. The committed tree therefore holds exactly what the gate reproduces — the 90 UI modules and the 6 protocol modules — and regeneration runs once perKNOWN_DRIFT_FREEslug rather than with--all. Widening the registry stays follow-up, because it would also enforce C++ and SQL drift those components have never been checked for.
6. Out of scope
7. Result
Delivered as PR #2108, merged as 3e71eae73a.
projects/ores.web holds the prototype under ORE Studio conventions as four
npm workspaces (bff, contracts, web and wire-protocol), and
ores.codegen writes its TypeScript there. The hand-copied output and the
ores.typescript component are gone. The drift gate reproduces the committed
tree exactly, over the 90 UI modules and the 6 protocol modules of the
drift-free components, so a regeneration that differs fails the check.
The service is a registry entry with :runtime: node and :entry_point, on
ORES_WEB_PORT, which is offset 2 of the environment block. compass services
start launches the fleet including it, and the fleet was cycled end to end:
stop, start, per-service start, stop and restart, and a browser sign-in
against the ACME tenant.
Acceptance is met. The component typechecks, its suites pass under npm test
and under ctest as ores.web.typecheck and ores.web.tests, the build
compiles it wherever npm exists, and a TypeScript workflow runs both checks on
a pull request. Linux CI installs Node now; without it the component had been
skipping itself with a warning that left the job green.
The review round is recorded in the verify task. Its four findings are fixed:
the unused session secret is gone, the busctl quoting note is corrected, the
rate limiter is bounded, and the CORS allow-list records its same-site
assumption. The branch also carries three fixes the integration depended on:
the Wt residue that made compass db recreate fail, the worktree-scoped
database variables, and env configure preferring the checkout's own .env
to the ambient process environment.