# Changelog

Notable changes to OpenVibe.Run. The service is unreleased; everything below is `0.1.0` in progress.

## Unreleased

### Added

- The Arena's race on the one engine (compare-arena-ecosystem.md §3, contracts 0.422.0): the `race` play as
  `agents.play@1` (one role per side, one parallel phase, an even budget split, `blind: true`, stop on person), listed
  by `GET /api/v1/plays`; `POST /api/v1/races` starts one child `linux` job per side (2–4) under one parent race with
  the same share of the budget each and answers the sides labelled `a, b, …` without names; `GET /api/v1/races/:id`
  returns each side's output so far and its receipts when ended, the names only after a judgement;
  `POST /api/v1/races/:id/judgement` records one `bench.match@1` on Bench (source `arena`, shown order, `blind: true`,
  the receipts, a `human_pairwise` judgement with an HMAC of the person) before revealing the names. Only the person
  who started the race, through the same first-party service, may read or judge it. `matchmaker: true` picks two
  entrants of different model families from `RUN_RACE_ENTRANTS` while Bench has no matchmaker endpoint. Migration
  0020 adds `run_races`. The race request/answer has no released contract yet, so it is validated in
  `server/races/service.js`; everything it stores or sends is validated where a contract exists.
- With `RUN_SESSION_ORIGINS_ENABLED=1`, a browser session may name exact HTTP(S) origins at creation. Run stores the
  list with the session, places it on a user-owned desk that can enforce the boundary, and sends the same list when
  leasing that desk. Commands cannot replace the list. The switch is off by default.

- One Computer (plan 2026-11-07, contracts 0.327.0): `run.session@1` carries `task_id` (the OpenVibe.Actor task the
  session is the Computer of, so the session points back at the task) and `curtain` (the privacy screen).
  `GET /api/v1/sessions/{id}/still` answers the desk's newest frame as a small JPEG (at most 640 px wide, cached for a
  second so it captures at most once a second) from the desk's own capture on the session's lease; it is the session
  person's alone, a signed-out visitor gets 404 like a missing session, `Cache-Control` is `private, no-store`, and
  while `POST /api/v1/sessions/{id}/curtain` holds it up the answer is the curtain picture, never the screen.
  Migration 0008 adds `task_id` and `curtain`.
- Placement A1 (openvibe-sdk 0.76.0): `server/dispatch/placement.js` calls `place()` — Bench priors (an hour's
  cache), the person's learned counts and one plain line — and the same answer is stored on the job. `GET
  /api/v1/jobs/:id?explain=1` answers the line beside the contract body. `placement_outcomes` (migration 0007) learns
  one outcome per ended job: exit 0 is ok, a failure or a timeout is not; a cancelled job is not counted.
- The repository skeleton (plan T14 step 4, R1a): `server/config.js` on port 4920, `server/db.js`,
  `server/app.js`, `server/index.js`, `server/observability.js` (`/api/health`, `/api/ready`, `/release.json`,
  loopback-only `/metrics`), `server/api/auth.js`, `server/events/outbox.js`, `migrations/0001_jobs.sql`
  (`run_jobs`, `run_events_outbox`), `STATUS.json`, the nginx vhost and the systemd unit.
- The job API (plan T14 step 5, R1b): `POST /api/v1/jobs` (`run.job.submit`), `GET /api/v1/jobs/:id`
  (`run.job.read`), `GET /api/v1/jobs` (`run.job.list`), `POST /api/v1/jobs/:id/cancel` (`run.job.cancel`),
  `POST /api/v1/jobs/:id/stream/ticket` and `GET /api/v1/jobs/:id/stream` (`run.job.stream`) and
  `GET /api/v1/admin/jobs` (`run.job.admin`) — each validated against its released contract, with the project and
  the requester taken from the token alone.
- `run.job.queued|started|succeeded|failed|cancelled|expired` through `run_events_outbox`, written in the same
  transaction as the state change, and the two-minute single-use stream ticket with the SSE stream (replay,
  monotonic `seq`, `Last-Event-ID`).
- `server/dispatch/index.js`: the dispatcher-bridge seam (plan T14 step 6) as a no-op, so every job stays `queued`.

- The dispatcher bridge to OpenVibe.Bot (plan T14 step 6, R1c) and placement (step 7, R3): `server/dispatch/bot.js`
  (the client — `send`/`cancel`/`state` with Run's Network client-credentials token for audience `openvibe.bot`
  holding `bot.job.dispatch`, cached until 60 s before expiry), `server/dispatch/placement.js` (the Fabric offers
  plus `openvibe-sdk/placement` `plan()`, with `user-owned` eligible only when the job's requirements name it) and
  `server/jobs/poller.js` (`RUN_POLL_MS`, default 1000 ms): the ttl sweep, the send, the mirror of Bot's state with
  one `run.job.*` event per state change, the node's stdout as stream `output` events, and the job_cancel.
- `GET /api/v1/jobs/:id/stream` also opens with a Bearer service token holding `run.job.stream` for the job's
  project, beside the ticket.
- The managed-browser provider adapter (plan T14 R4a, `server/dispatch/browser-provider.js`): class `browser` jobs
  placed on a `kind=provider` offer named `browser-provider` are sent to the provider's API
  (`browser-provider.job-create-request@1`, the frame alone: no project, subject or requester), mirrored, cancelled
  and expired there; every answer is validated against `job-create-result@1` / `job-state@1` and a malformed one is
  never adopted. Configured by `RUN_BROWSER_PROVIDER_URL`, `RUN_BROWSER_PROVIDER_API_KEY` (Run's env only, never
  logged) and `RUN_BROWSER_PROVIDER_TIMEOUT_MS` (8000); off while the URL or the key is unset.
- Run's own metering of those jobs: the provider's claimed wall time is clamped to Run's observed duration + 5 s
  (a larger claim is logged and never billed), queued as `platform.usage-sample@1` readings in `run_usage_outbox`
  (`migrations/0003_usage_outbox.sql`) with the end state, and relayed to Billing (`RUN_BILLING_URL`) with a Run
  token for audience `openvibe.billing` holding `billing.usage.record` — used for nothing else.

### Changed

- Cancelling a `placed` job no longer settles it at once: a job Run has handed to Bot is marked `cancel_requested`,
  Bot is asked for `job_cancel` and the job ends when Bot reports it — Run never says `cancelled` for work a node may
  still be doing. A `queued` job (sent nowhere) is still cancelled at once.
- `POST /api/v1/jobs` no longer places eagerly: the poller sends each queued job, so a submit never waits on Network
  or Bot and a job whose lifetime ran out is never sent.
- `RUN_JOBS_INTERVAL_MS`/`RUN_DISPATCH_INTERVAL_MS` are replaced by `RUN_POLL_MS` (the poller's own interval).
- `usage.wall_ms`/`usage.seconds` are Bot's metered wall clock: 0 until the job's `job_exit` (Bot is the meter).

### Notes

- OpenVibe.Bot owns the node link and the per-second metering of the jobs it carries (plan T14 L1); Run's Billing
  token is for the external provider's jobs only.
- The repo is not deployed; the first deploy needs `ovhost`'s inventory, the `ov_run` database,
  `/etc/openvibe/run.env` and `openvibe.run` DNS (see STATUS.json).