@jr2/orchestrator 0.6.0 → 0.7.0

package/docs/reference/decisions/0032-the-console-unlocks-with-the-instance-token.md

@@ -1,61 +0,0 @@
-# The Console unlocks with the Instance token, and the bands do not move
-
-[ADR-0014](0014-observation-is-open-run-state-is-not.md) built the three-band HTTP surface on one premise: the
-visualizer page is a browser, and a browser holds no token — so it got a projection instead of a credential, and "give
-the page a token" was explicitly rejected. That page is now growing into the **Console**: it starts runs and answers
-Gates, both of which are writes on the guarded surface. This ADR records how a browser earns those writes without moving
-a single band — and it can stay this small because of a fact ADR-0014 did not lean on: the Instance token is already one
-`kubectl get secret` away for exactly the audience the Console serves. There is no new distribution problem, only a new
-presentation surface.
-
-## Decision
-
-- **The human presents the token; the page never ships with one.** The Console's nav carries a password field. Empty,
-  the page is precisely ADR-0014's observer: open structure and observation, no control rendered. Filled, the page sends
-  `Authorization: Bearer` on the guarded surface — which unlocks both directions at once: the writes
-  (`POST /workflows/:name/runs`, `POST /runs/:id/gates/:gate/events`) and the `instanceOnly` reads the control UI needs
-  anyway (`GET /runs`, and `GET /runs/:id` — where `GateView` lives). The page as _served_ stays open and inert;
-  ADR-0014's rejection stands, because what it rejected was baking the credential into the page.
-- **The token lives in `sessionStorage`** — survives a reload, dies with the tab, never a cookie (no ambient credential,
-  no CSRF surface). It is validated on entry with a cheap guarded read so the field shows live/invalid immediately; any
-  later 401 drops the UI back to observer mode rather than failing per-widget.
-- **Gate discovery is a frame-triggered guarded read, not an open-band extension.** A Gate exists exactly while its
-  invoking state is entered (ADR-0011), and every entry/exit lands a status frame on the open workflow feed (ADR-0022) —
-  so on each frame, a token-holding Console re-fetches `GET /runs/:id` for the affected run and folds `gates` into its
-  store. Perfectly synchronized, no polling loop, and the observation projection is untouched. A delivery's success is
-  likewise confirmed by the next frame emptying the card, never by local bookkeeping.
-- **Page addresses content-negotiate; JSON is the default dialect.** `/` and `/workflows/:name` serve the Console shell
-  to `Accept: text/html` and JSON to everything else — so the workflow-detail resource keeps its natural address (the
-  run-input schema's home, [ADR-0033](0033-a-machine-declares-the-input-that-starts-it.md)) and no future page has to
-  squat on a mangled sibling path. Nothing existing moves: EventSource asks `text/event-stream`, and the Harness's Menu
-  and the CLI never ask for HTML. `/viz/*` is deleted (greenfield, no redirects); assets move to `/assets/*`, which also
-  retires the "a workflow named `assets` is shadowed" hazard.
-
-## Considered options
-
-- **`jr2 ui` — the CLI opens the browser through an authenticated local proxy.** A convenience layer worth building _on
-  top of_ the token field later, not a substitute: it has no answer for the deployed jr2 Application behind an ingress,
-  where the browser talks to the Service directly and the CLI is not in the path.
-- **A fourth, scoped credential** ("may answer gates, may not cancel or read context"). Still rejected, as in ADR-0014 —
-  but the calculus has narrowed: it becomes worth writing only when gate-answering is delegated to people who must _not_
-  hold cluster RBAC. That is a real future (an approval inbox for non-operators); it is not this one.
-- **Announce gates on the open observation feed** (even just `{runId, gate}`). Rejected: it widens the projection for a
-  convenience the token already solves, and the open band has an unresolved exposure question as it stands (spawn ids —
-  the ADR-0014 open call). The projection stays the one place the line is drawn.
-- **A `/ui` path prefix, or moving the API under `/api`.** Rejected for negotiation: the first is ceremony on the
-  address a human types, the second churns the Harness's Menu, the Custodian's route allowlist, the CLI, and the
-  ADR-0009/0013 route tables for cosmetics.
-
-## Consequences
-
-- **Zero new server surface except negotiation.** No new token, no new band, no new route class; `auth.test.ts`'s
-  boundary assertions are untouched. The server-side diff is: negotiate two addresses, serve the shell, retire `/viz/*`.
-- **Possession remains cluster RBAC.** Whoever can read the instance Secret could already do everything the Console
-  unlocks; the field changes where the token is typed, not who holds it.
-- **The XSS caveat is the real one and is bounded by what the page is:** a token in `sessionStorage` is readable by
-  scripts on the page, so the Console must keep serving only its own assets — no CDN, no third-party script, exactly the
-  constraint the viz page already lives under.
-- **GLOSSARY.md**: **Console** becomes a glossary term (visualizer, dashboard, UI, viz on its Avoid list).
-- **The Console's UX gets a browser tier** — `@console`-tagged Cucumber scenarios holding a Playwright page, in
-  `@jr2/e2e`, excluded from the default profile ([ADR-0010](0010-bdd-acceptance-tests.md) as amended). What the page
-  _believes_ stays unit-tested in `console-store.test.ts`; the browser tier asserts what a user does and sees.

package/docs/reference/decisions/0065-a-persist-survives-a-crash-and-history-is-a-week.md

@@ -1,65 +0,0 @@
-# A persist survives a crash, and history is a week
-
-Every transition of a run persists its whole snapshot (ADR-0007). The scaling review (R6) read the store and listed its
-costs: `JSON.stringify` of the whole run, a synchronous upsert with an fsync on the event loop, a Pool's run as one blob
-holding every worker, terminal rows never deleted, and `restore()` parsing every row before the server listens. It also
-found the words "Postgres opt-in" in GLOSSARY.md, ADR-0008 and ADR-0009, with no such store in the code. Measured on the
-home cluster's chaos Instance (2026-09-30, `local-path` volume): a persist costs **4.5 ms, whatever the blob's size** (1
-KB or 100 KB), because the cost is the fsync, not the JSON; with the write-ahead log and `synchronous=NORMAL` the same
-upserts cost 0.04 ms (1 KB) and 0.18 ms (100 KB). A run's blob is about 1 KB; a Pool of 40 workers is about 100 KB.
-
-## Decision
-
-- **A persist survives a process crash, not a power loss.** The store runs sqlite in WAL mode with `synchronous=NORMAL`:
-  a write is durable once the OS holds it, and sqlite fsyncs only at a checkpoint. A node's power loss can lose the
-  transitions since the last checkpoint; the file stays consistent, and `restore()` treats the older snapshot as it
-  treats any restart — reconcile against the live world, re-attach, or `lost`. The window in which a crash re-POSTs a
-  prompt (ADR-0007's at-most-once sliver) widens from one microtask to one checkpoint, and only on a power loss, which
-  also ends every Sandbox on that node.
-- **The write stays synchronous and on the event loop.** At 0.2 ms for a Pool's blob there is nothing to move off the
-  loop, and the ordering matters: the row is on disk before the Machine's next side effect runs, which is what lets an
-  epoch bump (ADR-0057), an admission (ADR-0016) or an Effect's intent row (ADR-0067) be saved "at the write" — the
-  intent row before its call leaves. A worker thread, an asynchronous driver or a network store would land the row after
-  the next `invoke` fires, on every persist.
-- **One blob per run stays.** The snapshot is a tree that xstate restores from its root, and one row keeps it atomic —
-  with the ledgers beside it (admissions, epochs, notices, timers, outstanding picks, Effects); a Pool's cost at 40
-  workers is 0.2 ms, so its workers do not become rows of their own. The Effect ledger keeps a row for every Effect the
-  run started (ADR-0067), so a Machine that loops through an Effect grows its blob by one row per pass: id, kind and
-  outcome. The output's tail is dropped once the save that carries the Effect's transition is on disk; a push row keeps
-  its published commit, its source, its `squashed` and its sync's answer whole — every later push of its Repo Slot sends
-  them as one of its pairs — and its bundle only while it is its Repo Slot's newest push and its sync did not finish —
-  one bundle per Repo Slot at most. An outstanding pick's hold is the one place tails accumulate: its `chain` keeps
-  every reply since the pick whole until the pick is answered, then it is dropped (ADR-0067).
-- **`restore()` reads live rows only.** The store answers `WHERE status = 'live'`; terminal rows are not parsed at boot.
-- **A finished run's row lives 7 days, fixed.** Every non-live status — `done`, `failed`, `error`, `cancelled`, `lost`,
-  `drifted` — ages from its terminal write, and a sweep at boot and every hour deletes what is older. A `live` row is
-  never swept: a run parked on a Gate for a month stays and is restored. The value is fixed like the Sandbox idle
-  timeout, not config: jr2 is not the record of a run's results (a Machine sends its output where it belongs — a PR, a
-  Source), and `jr2 status` on an old run is a debugging act. A swept id frees its abbreviations (ADR-0009).
-- **The store is sqlite on the Instance's volume. No Postgres is owed.** The `SnapshotStore` interface stays as the
-  seam, with one implementation. `DATABASE_URL` is not a thing jr2 reads.
-
-## Considered options
-
-- **Keep `synchronous=FULL`, move the write to a worker thread.** Rejected: the thread hides 4.5 ms from the loop but
-  does not make the disk faster, so writes queue under load and the loop no longer knows how far behind the store is —
-  and it opens the ordering gap on every write, which NORMAL opens only on a power loss.
-- **Batch persists in a window.** Rejected: one persist per macrostep already coalesces a transition's events, and with
-  the fsync gone there is nothing left to amortize.
-- **A row per worker.** Rejected: it splits an atomic tree across rows (a worker's row saved, the Pool's not), makes
-  restore reassemble what xstate restores whole, and buys nothing measurable at 0.2 ms per blob.
-- **Configurable retention (`runs.retain`), or a count cap per workflow.** Rejected: a count cap does not bound a busy
-  workflow's disk and punishes a quiet one; a config key is owed only when a history surface (a list, a query) exists to
-  use it, and none does — `jr2 runs` and the Console list live runs.
-- **Build the Postgres store.** Rejected: the only thing it buys is an Orchestrator pod that reschedules without its
-  volume, which is a storage-class question (a network RWO volume follows the pod) and belongs to the Orchestrator pod's
-  own decision (R10), not to the store. Its cost is a dependency the owner operates, a second store in every test tier,
-  and the asynchronous write above.
-
-## Consequences
-
-- ADR-0008 and ADR-0009 lose "Postgres opt-in" and `DATABASE_URL`; ADR-0008's Orchestrator persists its snapshots "to
-  sqlite on its volume". ADR-0007 points here for the store's durability.
-- The Instance's volume gains `state.db-wal` and `state.db-shm` beside `state.db`.
-- A `drifted` run (ADR-0030) is swept a week after the deploy that changed its Machine, not a week after it ended; a
-  week is the time a human has to read it.