@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/concepts/coordinator.md

@@ -0,0 +1,297 @@
+# Coordinator
+
+The instance that owns a board — the only one that can see across all of its runtimes, and therefore the one that answers questions no single runtime can.
+
+---
+
+## The question it answers
+
+A runtime knows its own services and nothing else. That is enough for almost
+everything a board does, because a service's work is local: take the input, do
+the thing, hand the result on.
+
+Some questions are not local:
+
+- *What address did that service on the other runtime publish?* — a mount is
+  assigned when its runtime loads, so nobody can write it into a board.
+- *This board is about to be exported to a phone that will not have these
+  runtimes — what concrete addresses should its references become?*
+- *What state does a service on another runtime currently report?*
+
+Each of those needs a view of the **whole board**, and no runtime has one. The
+role that does is the **coordinator**.
+
+---
+
+## Why it is easy to miss that there always is one
+
+In the playground and in Readymade, one browser tab plays every role at once:
+it renders the UI, it hosts the browser runtime, it provisions the remote
+runtimes over REST, and it holds the board's engine state. Asking "who
+coordinates this board?" in that setting sounds like a trick question — the
+answer is "the same thing that does everything else".
+
+That is precisely why the role has to be named. **Coordinating a board and
+hosting a runtime are separate jobs**, and they come apart as soon as a board is
+deployed:
+
+| Board runs as | Coordinator | Hosts browser runtimes | Provisions remote runtimes |
+|---|---|---|---|
+| Playground / Readymade | the browser | the browser | the browser, over REST |
+| Cloud board | hkp-node | a connected browser | hkp-node, over connections their runtime servers opened to it |
+
+Both rows are the **same board**. What changes is who owns it. A board moves
+from the first row to the second by being **deployed**, and from that moment the
+browser is a viewer of something it no longer owns.
+
+Making the role explicit is what lets the same service code work in both: a
+service asks *the coordinator*, not *the browser*, and does not know or care
+which one answered.
+
+---
+
+## The interface
+
+Deliberately small — four methods, in `hkp-frontend/src/core/coordinator.ts`:
+
+| Method | Answers |
+|---|---|
+| `getServiceState(runtimeId, serviceUuid)` | what a service last reported, from anywhere on the board |
+| `resolveMountUrl(value)` | a `__hkpMount` value as an address — resolving a `hkp-mount://` reference, passing an address through |
+| `resolveMount(value)` | the same, split into host / port / path / secure for a client that dials by parts |
+| `resolveMountsInBoard(board)` | every reference in a board document replaced by the address it currently resolves to (used when exporting) |
+
+`createBoardCoordinator(readState)` builds one. Its only argument is *where
+board state comes from* — which is the whole reason the same implementation
+serves two very different situations.
+
+**Undefined is a normal answer.** A board restores its runtimes concurrently, so
+a service asking early gets nothing back; callers retry rather than treating it
+as failure.
+
+---
+
+## The implementations
+
+### 1. The browser owns the board
+
+`BoardProvider` creates one per provider lifetime and reads through a ref, so
+everything holding it sees current state (`hkp-frontend/src/BoardContext.tsx`,
+`localCoordinatorRef`). This is the playground, Readymade, and any board opened
+from a file.
+
+### 2. The browser is attached to someone else's board
+
+`hkp-frontend/src/views/cloud/index.tsx` calls the *same* factory, but reads
+from the coordinator's pushed snapshot instead of local state:
+
+```ts
+const boardCoordinator = createBoardCoordinator(() =>
+  bridgeAccess.snapshot.asCoordinatorState(),
+);
+```
+
+and passes it into `BoardProvider` as the `coordinator` prop. `BoardProvider`
+prefers a coordinator it is given over the one it would make
+(`coordinatorProp ?? localCoordinatorRef.current`), and the prop's doc comment is
+the rule in one line: *omit it when this provider owns the board*.
+
+So a facade widget or a service panel resolving a mount runs identical code in
+both cases. What differs is whether the state behind it is this browser's or a
+copy of hkp-node's.
+
+### 3. hkp-node coordinates a deployed board
+
+Server-side, and **not** the same type despite the shared name:
+
+| | frontend | hkp-node |
+|---|---|---|
+| Name | `BoardCoordinator` (interface) | `BoardCoordinator` (class) |
+| File | `hkp-frontend/src/core/coordinator.ts` | `hkp-node/src/coordinator/coordinator.ts` |
+| Holds | a way to read board state | `userId → boardName → BoardSession` |
+| Does | answers cross-runtime questions | owns boards: provisions, persists, serves, tears down |
+
+The node class is the *role*, played by a server; the frontend interface is the
+*capability*, handed to services and UI. A `BoardSession`
+(`hkp-node/src/coordinator/session.ts`) is one board being coordinated, and it
+is where the equivalent cross-runtime work happens —
+`recordMountAddress()` and `publishMountAddresses()` do there what
+`resolveMountUrl` does here.
+
+---
+
+## How a service reaches it
+
+A runtime host may hand the coordinator to the services it hosts, as
+`AppInstance.coordinator` (`hkp-frontend/src/types.ts`). `BrowserRuntimeApp`
+exposes it as a **read-through getter**, not a captured value, because the host
+assigns it after services are built:
+
+```ts
+get coordinator() {
+  return scope.coordinator ?? undefined;
+}
+```
+
+A host that cannot see the board leaves it unset, and callers treat that exactly
+like a lookup that has not resolved yet. `PeerConnection.resolveActivePeerHost()`
+is the reference consumer: it resolves at *connect* time, not at load time, and
+retries.
+
+**A service on a remote runtime cannot do this at all** — it sees its own
+runtime and nothing else, and the coordinator may be on another machine. So the
+coordinator pushes instead: `hkp-frontend/src/core/mountPublication.ts`
+(`pendingMountConfigures()`) computes what each remote consumer still needs and
+configures it with the plain address. hkp-node's session does the same for the
+boards it owns.
+
+For that it has to know the address, and a remote owner that claims its mount
+after load — unbypassed from a facade, say — says so only in a notification
+and in the state it answers the configure with. Both are taken into the board's
+state for that service (`withReportedMount()`, fed by the REST scope's report
+targets), the address and nothing else; hkp-node's session does the same with
+the notifications it receives.
+
+---
+
+## Ownership, which is what the role really is
+
+**A board has exactly one owner, and the owner provisions its runtimes.** Most
+bugs in this area are one side acting as though it owned something it did not.
+
+Runtime lifecycle is declared by whoever creates the runtime, in the create
+payload — never inferred from who is connected:
+
+| `garbageCollected` | Meaning | Who sends it |
+|---|---|---|
+| `true` | reap when the last client socket closes | a browser — its runtimes should not outlive the tab |
+| absent / `false` | persist until an explicit `DELETE` | a coordinator, a config file, a script |
+
+Deploying is an introduction followed by a registration
+(`hkp-frontend/src/core/deploy.ts`), and the browser gives nothing up for it.
+Both sides use the board's own runtime ids and still hold different runtimes:
+a runtime server keeps what a coordinator builds for a board in that board's
+own space, apart from what its clients create. The browser's runtimes stay its
+own and go when it leaves. Pinned by `core/tests/deploy.test.ts` and
+`core/tests/board-unmount.test.tsx`; the spaces are described in
+`concepts/cloud-boards.md`.
+
+---
+
+## What a coordinating hkp-node holds
+
+Per board, in `BoardSession`:
+
+| Field | What it is |
+|---|---|
+| `participants` | the runtime servers connected for this board, one connection per remote runtime — they connected in; the coordinator dials nothing (→ `concepts/remotes.md`) |
+| `built`, `live` | the runtimes this session has built, and those whose runtime server is connected right now |
+| `runtimeErrors` | why each runtime is not as the board wants it — what `error` names |
+| `mountAddresses` | what each service published, keyed `runtimeId/serviceUuid` |
+| `serviceStates`, `registries` | the board as the coordinator knows it — what an attached browser renders |
+| `bridges` | every browser currently attached, each with what it is to the board (owner or member), who attached with it, the runtime ids it hosts, and its own `seq` — ordering, so a browser can tell it missed an update |
+| `access` | what the board's facade lets a member do and see, read from the facade once per session |
+
+Who a board is shared with is not among them: the member list belongs to the
+board and outlives every session, so `BoardCoordinator` keeps it and a session
+is told who it is admitting.
+
+**It persists the board, not the run.** `hkp-node/src/coordinator/fileBoardStore.ts`
+writes `userId`, `boardName`, `createdAt`, `config`, whether the board was
+stopped, the hashes of its tickets and its member list — and nothing else: built runtimes, live
+state, registries, mount addresses and status each describe one run against
+processes that may not exist on load. A restored board that was running
+therefore comes back **waiting** — in `error`, naming each runtime — and builds
+them as their runtime servers reconnect with the tickets they kept. No user is
+needed for that, which is what a ticket is for.
+
+---
+
+## The bridge
+
+One WebSocket per attached browser, at `/coordinator/bridge`. Who may have one
+is decided in `hkp-node/src/coordinator/bridge.ts` — the board's owner, or
+somebody on its member list — and the socket is then handed to
+`BoardSession.registerBrowserSocket()` with that role.
+Message shapes live in `hkp-node/src/coordinator/bridgeProtocol.ts`; the browser
+half is `hkp-frontend/src/views/cloud/useCoordinatorBridge.ts` and
+`coordinatorSnapshot.ts`.
+
+| Direction | Message | Meaning |
+|---|---|---|
+| → browser | `snapshot` | the whole board at a `seq`: config, each runtime's registry, each service's state — and what the browser is to it (`role`, `you`). For a member, a projection of all that |
+| → browser | `serviceState` | one service's state changed |
+| → browser | `notification` | a service's output — *not* state; a Monitor's message never appears in `getState()` |
+| → browser | `processRuntime` | run this data through a **browser** runtime the coordinator cannot host |
+| → coordinator | `resync` | I reconnected or saw a gap — tell me the board again |
+| → coordinator | `configureService` | configure a service on a runtime you own |
+| → coordinator | `processService` | have a service do its job with a payload, from that service onward — a facade's `process` action. Answered with `response`: accepted, or why not |
+| → coordinator | `result-from-browser` | what that browser runtime produced, so the chain can continue |
+| → coordinator | `log` | an entry from a browser runtime, which has no other route into the board's log |
+
+Two consequences worth holding on to:
+
+- **A cloud board with a browser runtime cannot run headless.** The coordinator
+  routes results into it over a bridge, so that link of the chain stalls with no
+  viewer attached (`routeResult()` / `nextRuntime()`).
+- **A run begun over the bridge is the browser's.** Its caller is whoever
+  attached with that bridge, established when it was admitted and carried
+  across every runtime the run reaches. Nothing in a message can change it.
+- **A member is not sent the board.** Their bridge gets the facade and what it
+  reads, may ask for what the facade asks for, and hosts no runtime. The rules
+  are in **Cloud boards** (`concepts/cloud-boards.md#sharing-a-board-members`).
+- **Attaching is a read.** `views/cloud/bridgeRuntimeApi.ts` builds scopes that
+  open no socket, because the bridge already carries every runtime's state and a
+  cloud runtime may live where the browser has no route at all. Structural edits
+  are refused: adding a service means owning the board.
+
+---
+
+## Coordinators are also runtime hosts
+
+Coordinating and hosting are separate roles played by the *same process*: the
+coordinator API is under `/coordinator`, the runtime API at the server root. So
+a board can put runtimes on the host of a coordinator it already knows, which is
+why coordinators show up among the available engines —
+`coordinatorRuntimeEngine()` and `withCoordinatorEngines()` in
+`hkp-frontend/src/common.tsx`, pinned by `src/tests/coordinator-runtime-engines.test.ts`.
+
+Users configure coordinators as `{ name, url }` pairs kept in `localStorage`
+under `hkp-coordinators` (`restoreCoordinators()` / `storeCoordinators()`).
+
+---
+
+## Rough index into the source
+
+| Concern | Where |
+|---|---|
+| Interface + browser implementation | `hkp-frontend/src/core/coordinator.ts` |
+| Owned-vs-given decision | `hkp-frontend/src/BoardContext.tsx`, `hkp-frontend/src/core/boardContextTypes.ts` (`coordinator?` prop) |
+| Handing it to services | `hkp-frontend/src/types.ts` (`AppInstance.coordinator`), `runtime/browser/BrowserRuntimeApp.ts` |
+| Pushing addresses to remote runtimes | `hkp-frontend/src/core/mountPublication.ts` |
+| Deploying | `hkp-frontend/src/core/deploy.ts`, `components/Toolbar/DeployMenu.tsx` |
+| Attached mode | `hkp-frontend/src/views/cloud/` — `index.tsx`, `useCoordinatorBridge.ts`, `coordinatorSnapshot.ts`, `bridgeRuntimeApi.ts` |
+| Server-side role | `hkp-node/src/coordinator/coordinator.ts` (`BoardCoordinator`) |
+| One board being coordinated | `hkp-node/src/coordinator/session.ts` (`BoardSession`) |
+| HTTP API | `hkp-node/src/coordinator/router.ts` |
+| Bridge socket | `hkp-node/src/coordinator/bridge.ts`, `bridgeProtocol.ts`, mounted in `hkp-node/src/index.ts` |
+| Members and what a facade grants them | `hkp-node/src/coordinator/members.ts`, `facadeAccess.ts` |
+| Persistence | `hkp-node/src/coordinator/boardStore.ts`, `fileBoardStore.ts` |
+| Tickets and the runtime servers connected with them | `hkp-node/src/coordinator/participants.ts`, `join.ts`, `participantProtocol.ts` |
+| Tests that pin the rules | `hkp-frontend/src/core/tests/coordinator-ownership.test.tsx`, `board-unmount.test.tsx`; `hkp-node/tests/coordinator-*.test.ts`, `bridge-snapshot.test.ts`, `bridge-process.test.ts`, `board-members.test.ts` |
+
+---
+
+## Known gaps
+
+- **Two processes, one data directory** both restore every board and both believe
+  they own them. There is no lock — keep a data directory to one coordinator.
+- **An absent coordinator is indistinguishable from an unresolved lookup.** Both
+  are "nothing yet", so a host that forgot to pass one looks like a slow board.
+
+---
+
+See also: **Mounts** (`concepts/mounts.md`) for the questions that need a
+coordinator most, **Cloud boards** (`concepts/cloud-boards.md`) for what
+happens when the role moves to a server, and **Remotes**
+(`concepts/remotes.md`) for how a board's runtime servers connect to it.

package/bundle/docs/content/concepts/logging.md

@@ -0,0 +1,293 @@
+# Logging
+
+What a board recorded about itself — one entry at a time, stitched across every
+runtime it spans, kept where it survives with nobody watching.
+
+---
+
+## The problem
+
+A board in the playground is watched. Its services notify, its panels update,
+and if something goes wrong the person who built it is looking at it.
+
+A deployed board is not. It receives a webhook at three in the morning, runs
+eleven services across two runtimes and a nested pipeline, and produces nothing
+— and the question the next morning is *where did that stop*. Nothing that
+exists for a watcher can answer it:
+
+- **Notifications are for whoever is attached.** They are dropped when nobody
+  is, which is the case a log is for.
+- **A runtime's own console answers for its own slice.** A board spans several
+  runtimes, possibly on several machines; four separate stdout streams in
+  timestamp order are not a trace.
+- **The payload cannot say which invocation it belongs to.** The same data flows
+  through the same services for entirely unrelated reasons, so attribution needs
+  an identity that the data does not carry.
+
+Logging is the answer to all three: **runtimes record, the coordinator keeps**,
+and every entry names the run it belongs to.
+
+---
+
+## A run
+
+A **run** is one invocation of a board — one user action, one timer tick, one
+arriving message — followed across every service and runtime it reaches.
+
+The ordered service list says what runs; the run says *which invocation it is
+running as*. It travels as a `ProcessContext`:
+
+| Field | What it is |
+|---|---|
+| `runId` | This invocation. Minted where the invocation begins. |
+| `parentRunId` | The run this one was invoked *from*, for a nested pipeline. Absent when the trigger came from outside, which is what makes a trace a tree rather than a list. |
+| `requestId` | A **reply address**, not an identity: built from a message's sender, alive only while a response is awaited, consumed on resolution. |
+| `actor` | What is acting: a verified person with an authority deadline, the board, a public mount, or a local/auth-disabled client. |
+
+`runId` is deliberately not folded into `requestId`. They have different
+lifetimes — one run makes any number of awaited calls.
+
+### Where a run begins
+
+At the **origin**, not at the first runtime that happens to need one. Every
+entry point into a board mints it: the ▶ control, a facade action, a board's
+play, a service calling another runtime by name — in the browser through
+`startedRun()` (`hkp-frontend/src/runtime/processContext.ts`), on the other
+runtimes through `newRun()` and its equivalents. A context that is already set
+is a call being *continued*, and is passed through untouched.
+
+Minting late is what produces a trace that starts with the trigger already lost.
+
+### How it crosses a runtime boundary
+
+A peer that drives a runtime names the run its call belongs to, so a board
+spanning several runtimes reads as one trace rather than one per runtime:
+
+- over the WebSocket, as `context` beside `params`,
+- over REST, as `__context` in the body,
+- read back by `contextFromWire()` (node), `context_from_wire()` (python),
+  `ProcessContext::fromJson` (C++).
+
+A caller that names no run is not continuing one, so a run is *begun* rather
+than left unidentified. Work attributed to a run of its own is recoverable;
+work attributed to nothing is not.
+
+What a runtime does by itself — a timer ticking, a source handing on a buffer —
+begins a run per emission for the same reason. hkp-rt does so only while the
+board keeps a log: an identity per emission is paid on the path audio takes,
+and the log is the only thing that reads it. Without one, its autonomous work
+shares a single standing board run per runtime.
+
+### Nesting, and leaving the call
+
+A nested pipeline gets a run of its own with `parentRunId` set to the run around
+it (`childRun`), so work done *inside* a sub-pipeline stays distinguishable from
+work done around it.
+
+A service that finishes after its `process` returns — an HTTP response arriving,
+a socket pushing — has left its call by the time it has something to pass on. It
+captures the context while still inside `process` (`host.currentContext()`) and
+hands it back to `processFrom`, which is what keeps the two halves recognisable
+as one run. A service that forgets to capture starts a new run instead: its
+trace splits in two rather than being misattributed to whichever run happened to
+be in flight. **Fragmentation is visible in a trace; misattribution reads as
+fact.**
+
+In hkp-node the current run is held in an `AsyncLocalStorage`, not a field: a
+timer tick and an arriving message interleave freely across awaits, and a plain
+field would let the second overwrite the first's context mid-await.
+
+---
+
+## The entry
+
+One thing worth recording about a run. The same shape on every runtime, because
+a board's log is assembled from all of them:
+
+| Field | What it holds |
+|---|---|
+| `runId`, `parentRunId` | which run, and which run invoked it |
+| `ts` | ISO 8601 UTC to milliseconds, `Z`-suffixed, stamped by the runtime that produced it — the store orders and filters by comparing it as text, so a runtime with its own dialect would sort against the others rather than among them |
+| `runtimeId`, `serviceUuid` | where it happened |
+| `level` | `debug` \| `info` \| `warn` \| `error` |
+| `event` | what happened, as a short stable name a reader can group by |
+| `data` | optional payload — see below |
+| `durationMs` | how long the call took, on `service.processed` |
+
+**A service says only what happened.** It calls `host.log(level, event, data)`;
+the run and the service are filled in from the call in progress. It cannot
+mislabel an entry, because it never writes those fields.
+
+The exception is `host.forwardLog(entry)`, which passes an entry a nested
+pipeline produced outward unchanged — re-deriving its run and service from the
+outer call would relabel work done *inside* a sub-pipeline as the work of the
+service hosting it, which is the nesting the entry exists to record. A nested
+runtime is built from a service's own configuration, which says nothing about
+logging, so it asks the runtime around it (`host.logSettings()`) and records the
+same.
+
+### What `debug` buys
+
+The runtime itself records the flow: `service.process` before a call,
+`service.processed` with `durationMs` after it, `pipeline.stopped` where a
+service returned null. All at `debug`.
+
+That is the difference between a log that answers *what did this board report*
+and one that answers *where did it stop*. A read defaults to `info` for the same
+reason: a caller who did not ask for `debug` is asking what happened, not what
+ran.
+
+### `data` is a separate decision
+
+`logging` says whether anything is recorded. `logData` says whether an entry may
+carry the payload it is about. They are not the same question — what a board
+records about its own flow and what it is willing to write down of the data
+passing through it are different decisions — and the switch in the UI touches
+only the first. A verbosity control that quietly did both would be an exposure
+control.
+
+Reading applies the same rule: `data` is withheld unless explicitly asked for,
+because filtering it after it had crossed the wire would defeat the point of
+withholding it.
+
+---
+
+## Where entries go
+
+A runtime does not know what a board is; it hands entries to whoever registered
+for them.
+
+```
+service.log ─▶ runtime ─▶ log targets ─┬─▶ output socket ──▶ coordinator ─▶ log store
+                                       └─▶ (browser: bridge) ┘
+```
+
+- **A remote runtime** (node, python, hkp-rt) sends `{ type: "log", entry }` on
+  the same result socket a notification takes — the connection the board's
+  coordinator already holds, authenticated with a credential minted to outlive
+  the user's session. The coordinator **writes it before broadcasting it**: a
+  browser may or may not be attached, and the log exists for the case where none
+  is.
+- **A browser runtime** has no socket of its own to the coordinator, so its
+  entries travel over the bridge as `log` messages
+  (`views/cloud/useCoordinatorBridge.ts`). Those are stored and *not* fanned out
+  again: the browser that sent them already has them, and a second browser
+  watching the same board is not hosting the runtime that produced them.
+- **Off means off.** No entry is built when `logging` is false, when the level
+  is below the runtime's floor, or when nothing is registered to receive one —
+  so nothing is spent deciding what an entry would have said.
+
+### The store
+
+One JSONL file per board, under `HKP_COORDINATOR_LOG_DIR` (default: beside the
+boards), in the same per-user directories as the board store with `0o700` on the
+directory and `0o600` on the file — entries carry board data, so they inherit
+that posture.
+
+One file per board, holding entries from every runtime it spans, is the whole
+reason the log is kept by the coordinator: a runtime could only ever answer for
+its own slice.
+
+JSONL rather than a JSON array, for three reasons at once: it appends without
+rewriting, a crash mid-write costs the last line rather than the file, and it
+reads back a line at a time, so serving a query never loads a long-running
+board's whole history into memory. A torn line is skipped and the rest is still
+readable.
+
+Bounded by **size**, not age: what fills a disk is bytes, and a board ticking
+once a second and one that runs twice a day would need wildly different day
+counts to mean the same thing. Past 32 MB the live file rolls aside (`.1`, `.2`,
+…) and the oldest of four is dropped. A read spans the live file and the rolled
+ones behind it — right after a roll the live file is empty and everything being
+asked for is in `.1` — and reads each one **backwards from its end**, because
+the newest entries are what a log is asked for.
+
+---
+
+## Reading it, and switching it on
+
+| | |
+|---|---|
+| Read | `GET /coordinator/users/:username/boards/:boardName/runs?runId=&level=&since=&limit=&withData=` |
+| Switch | `POST /coordinator/users/:username/boards/:boardName/logging` `{ enabled, level }` |
+
+Both sit behind the same `auth` + `requireSelf` as every other board route — a
+valid token whose `sub` matches the username — and deliberately **not** behind a
+runtime session token: that is a machine credential minted to outlive a user's
+session, and reading a board's history is not something it should be able to do.
+
+The switch is its own route rather than part of re-registering the board,
+because it is a setting a board revisits *while it runs*; registering again
+would rebuild every runtime to change one boolean. It is applied to the runtimes
+already running (`PATCH /runtimes/:id/state`) **and** written into the stored
+config, so it neither restarts anything nor quietly reverts on the next start.
+Runtimes that did not take it are reported, not assumed — partly applied is
+worth saying out loud.
+
+The setting lives in the board where it can be read back: `state.logging` and
+`state.logLevel` on each runtime. The Cloud Boards view reads it from there
+rather than keeping it locally, so the toggle shows what the coordinator will
+actually do — after a reload, and for a board somebody else switched on.
+
+---
+
+## What each runtime actually does
+
+| Runtime | Records | Sends entries | Takes the live switch |
+|---|---|---|---|
+| hkp-node | entries + the `debug` flow | result socket | yes (`PATCH /runtimes/:id/state`) |
+| hkp-python | entries + the `debug` flow | result socket | yes (`PATCH /runtimes/:id/state`) |
+| hkp-rt (C++) | entries + the `debug` flow | result socket | no — set at provision time |
+| Browser | entries only | the coordinator bridge | at provision time |
+
+For hkp-rt the level and the on/off come from the runtime's `state` in the board
+config, which is why the live switch reports it as *unreachable* and why the
+setting still takes effect the next time that board is started.
+
+Note that the switch is a server-to-server call: neither hkp-node nor hkp-python
+lists `PATCH` among its CORS methods, so a browser attached straight to a runtime
+cannot make it — the coordinator is the caller this route exists for.
+
+---
+
+## Known gaps
+
+- **There is no log viewer for history.** What arrives while the owner has a
+  deployed board open is shown — each service's panel lists its recent runs
+  (*Runs*: when, who, what it did, how long; `runtime/ui/ServiceRuns.tsx`), fed
+  by the entries the coordinator sends the owner as it writes them, each with
+  its caller named the way the board's list names them. Nothing yet reads
+  `/runs` for what happened before the view opened; that is read over HTTP
+  directly.
+- **A playground board records nothing.** Log targets are registered by the
+  bridge, so a board that no coordinator holds has nowhere to put an entry.
+  Logging is presently a property of a deployed board.
+- **The live switch does not reach hkp-rt**, which takes its logging settings
+  when the runtime is provisioned (above).
+- **No sampling and no rate limit.** `debug` on a busy board rolls its files
+  quickly; the bound is on bytes kept, not on entries produced.
+- **Nothing correlates a run with an outside request id** — a webhook's own
+  identifier is data, not context.
+
+---
+
+## Where it lives in the code
+
+| Concern | Where |
+|---|---|
+| Entry + context types | `hkp-frontend/src/types.ts`, `hkp-node/src/types.ts`, `hkp-python/src/hkp/types.py`, `hkp-rt/lib/include/log_entry.h`, `hkp-rt/lib/src/process_context.h` |
+| Minting a run | `hkp-frontend/src/runtime/processContext.ts`, `hkp-node/src/runtime.ts` (`newRun`, `childRun`, `contextFromWire`) |
+| Recording | `hkp-node/src/runtime.ts` (`log`, `logProcessed`), `hkp-python/src/hkp/runtime.py`, `hkp-rt/lib/src/runtime.cpp` |
+| Nested forwarding | `hkp-node/src/services/sub-service.ts`, `services/nested-pipeline.ts` |
+| Egress | `hkp-node/src/server.ts` (`sendJsonLog`), `hkp-python/src/hkp/server.py` (`_send_log`), `hkp-rt/lib/src/runtime.cpp` |
+| Browser leg | `hkp-frontend/src/runtime/browser/BrowserRuntimeScope.ts`, `views/cloud/useCoordinatorBridge.ts` |
+| Store | `hkp-node/src/coordinator/logStore.ts` |
+| Routes | `hkp-node/src/coordinator/router.ts` (`…/runs`, `…/logging`), `coordinator/session.ts` (`setLogging`) |
+| UI | `hkp-frontend/src/views/cloud/index.tsx`, `coordinatorClient.ts` |
+| Tests | `hkp-node/tests/board-log.test.ts`, `hkp-rt/tests/runtime_log.test.cpp`, `hkp-python/tests/test_board_log.py`, `test_board_log_socket.py` |
+
+---
+
+See also: **Cloud boards** (`concepts/cloud-boards.md`) for the boards this is
+for, and **Coordinator** (`concepts/coordinator.md`) for why the instance that
+owns a board is the one that keeps its log.