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.web holds the prototype, renamed to ORE Studio conventions.
  • ores.codegen writes the TypeScript into projects/ores.web, and projects/ores.typescript is removed.
  • A check proves that the generated TypeScript is in step with the org model.
  • compass services start launches the ores.web service 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 on ORES_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_PORT is offset 2 of ORES_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_generate gains a node runtime and renders Type=simple itself, rather than calling a shell shim dropped into publish/bin by 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.ts moved out of src/generated/ to packages/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, scheduler and trading, which check_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 per KNOWN_DRIFT_FREE slug 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.

Emacs 29.3 (Org mode 9.6.15)