feat(conversation): CHAT-02 read-only Pi history reader and two board routes (#1507)

packages/conversation is a library with no server: safe-fs, the Pi session parser, CHAT-01 pages, pinned snapshots, cursors and follow. The control board adds GET /api/conversations and /api/conversation behind the Host and Origin guard. Both are read-only, their queries are validated, and each refusal code maps to a status. Dewey authored it (packet 0cf177b1, revision 2). Filbert reviewed the code: R1 revise (branch ids moving on append, the assumed-link bridge merging branches, one unreadable seat directory turning the catalogue into a 500), then R2 approve (3b14d66c). Darkwing reviewed the routes: R1 approve (07b10ad1), R2 approve (b9d92003). The package lands with the routes, because serve.mjs imports the reader at load. On an index export: the eight suites 24/90/43/17/14/15/63/18, conversation and control-board 153/153, webui 9/9. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-09-26 16:36:20 -05:00
parent c5db8c8819
commit a5beb6d97d
22 changed files with 3247 additions and 3 deletions
@@ -0,0 +1,54 @@
+# CHAT-02 board routes: Darkwing's review (#1507)
+
+Reviewer: Darkwing, 2026-09-26, per Sage's D3. Requested by Dewey. Scope: the
+two read-only routes only. Filbert reviews `packages/conversation` in full.
+
+Candidate, base 34777c56, uncommitted. I verified both hashes:
+- `packages/control-board/src/serve.mjs` afc95bdb…c540d
+- `packages/control-board/tests/serve.test.mjs` e60aa14b…ecbc
+
+**Verdict: approve**, with one commit condition and two nonblocking notes.
+
+## What I checked
+
+- Order. `foreignRequest` runs first on every request, then the POST routes,
+  then the GET/HEAD check (405 otherwise), then these routes. A POST to
+  either path is 405, and a foreign Host or Origin is 403 before any read.
+- Query validation. `/api/conversations` refuses any parameter.
+  `/api/conversation` accepts only `id`, `branch` and `cursor`, one value
+  each, each matching `QUERY_VALUE`. That is the same pattern as
+  `parts.mjs` `ID`, so every id the reader issues (`safeId`, `root`, `c-`
+  cursors, `pi-` conversations) passes. No path comes from the request.
+- Responses. JSON with `no-store` and `nosniff`, no CORS headers. A thrown
+  error gives a fixed 500 body and logs to stderr only.
+- Refusal bodies. Every `Refusal` message in `packages/conversation/src` is
+  a fixed string. The one interpolated message (`denied`, safe-fs.mjs:34)
+  interpolates only "session root" or "session file". No path or content
+  reaches the client through `error`.
+- Status map. It covers every code the route can reach. `unknown-actor` and
+  `unsupported-purpose` are absent, and the route can't produce them because
+  it always passes the default actor and purpose.
+- Tests: `serve.test.mjs` plus `packages/conversation/tests/`, 61/61 on the
+  pinned files.
+
+## Commit condition
+
+`serve.mjs` imports `../../conversation/src/reader.mjs` at module load, and
+`packages/conversation/` is untracked. Committing the routes without that
+package breaks the board's start, not only these routes. The package must
+land in the same commit or an earlier one, after Filbert's review.
+
+## Notes (nonblocking)
+
+1. **A cursor needs its branch.** The header comment says `branch` and
+   `cursor` are optional. But `next()` compares `branch !== record.branch`,
+   and every cursor record carries a string branch (`safeId` or `root`). So
+   `?id=X&cursor=C` without `branch` is always 409 `cursor-foreign`, with
+   `reconcile: true`. That is safe, but a client that follows `nextCursor`
+   alone gets a refusal that reads like a stale view. The test passes the
+   page's branch, so it doesn't show this. Either say in the comment that a
+   cursor call must repeat `page.branch`, or answer 400 "cursor requires
+   branch". I'd take the comment now and let CHAT-03's client decide.
+2. **New codes fall to 422.** A code the reader adds later maps to 422
+   without a test failing. A test that runs the reader's refusal codes
+   through `REFUSAL_STATUS` would catch that. That's optional.
@@ -0,0 +1,69 @@
+# CHAT-02 board routes, revision 2: Darkwing's review (#1507)
+
+Reviewer: Darkwing, 2026-09-26, at Sage's request. Scope: the route delta
+since my R1 approval (`chat-02-routes-review-2026-09-26.md`, 07b10ad1). Filbert
+reviewed the backend (packet `agents/dewey/work/chat-02/BACKEND.md`, 0cf177b1).
+
+Candidate, base 34777c56, uncommitted. I verified both hashes:
+- `packages/control-board/src/serve.mjs` d62720dc…a2f3
+- `packages/control-board/tests/serve.test.mjs` d38aa2b2…3f4a
+
+**Verdict: approve.** The R1 commit condition still holds, and I have two
+new nonblocking notes.
+
+## What I checked
+
+I kept no copy of the R1 files, so I read the whole route change against the
+base (`git diff 34777c56 -- packages/control-board`) instead of only the
+delta. It covers every item the packet's §0 lists and nothing else in the
+route path.
+
+- **Cursor needs its branch.** This was my R1 note 1. `conversationQuery` now
+  answers 400 "a cursor call repeats the page's branch" when `cursor` comes
+  without `branch`. The check runs after the per-key validation, so a
+  malformed value still gets its own 400 first. The header comment says the
+  same. A test covers it, and removing the line fails it.
+- **Status map.** My R1 note 2. `REFUSAL_STATUS` is exported and now has 16
+  entries. I listed every `new Refusal("<code>"` in
+  `packages/conversation/src` myself and got 15 codes plus
+  `unsupported-harness`, which reader.mjs:352 raises by value. That matches the
+  map exactly. `parts.mjs` raises none. `unavailable`, which safe-fs.mjs:58
+  raises when a session root doesn't exist, is 404. That fits the rest of the
+  map, where not-found is 404. `unknown-actor` 403 and `unsupported-purpose` 422
+  are explicit now.
+- **Order and guards** are unchanged from R1. The foreign Host or Origin check
+  comes first, then the POST routes, then 405, then these routes. No path comes
+  from the request, and responses carry `no-store` and `nosniff` with no CORS
+  headers.
+- **Tests.** `serve.test.mjs` plus `packages/conversation/tests/` pass
+  67/67 on the pinned files.
+- **Mutations** on a scratch clone of HEAD with the conversation package and
+  the two pinned files:
+
+  | Mutation | Result |
+  |---|---|
+  | cursor-without-branch check removed | 1 fails |
+  | `unknown-actor` entry dropped | 1 fails (the scan test) |
+  | `nosniff` removed | 1 fails |
+  | repeated-parameter check removed | 1 fails |
+  | catalogue parameter check removed | 1 fails |
+  | `unavailable` changed from 404 to 422 | nothing fails |
+
+  The last row is note 1 below.
+
+## Commit condition (unchanged)
+
+`serve.mjs` imports `../../conversation/src/reader.mjs` at module load, and
+`packages/conversation/` is still untracked. The package must land in the
+same commit as the routes or an earlier one. Otherwise the board fails to
+start.
+
+## Notes (nonblocking)
+
+1. **The scan test checks keys, not values.** It proves every code has an
+   entry. No test proves `unavailable` is 404. If someone edits that value, or
+   any status no route test exercises, nothing fails. A table test that
+   asserts the whole `REFUSAL_STATUS` object would pin them. That's optional.
+2. **The scan reads a fixed list of three files.** If a refusal is added to
+   `parts.mjs` or a new file, the scan won't see it, and that code falls to 422.
+   Reading every `.mjs` in `packages/conversation/src` would close the gap.