review: update

Author: archandatta

plans/external-events.md

@@ -43,29 +43,28 @@ Accepts a JSON `events.Event` body and publishes it into the currently active `C
 
 **Defaults applied server-side when caller omits them:**
 
-- `category` — derived from `type` via `cdpmonitor.CategoryFor()`. Splits `type` on the first `_` and maps the prefix to a category.
 - `source.kind` — stamped to `kernel_api` when absent, so downstream consumers can distinguish external traffic from CDP traffic.
 
 **Validation and status codes:**
 
 - `400` on invalid JSON body.
 - `400` when `type` is empty.
-- `400` when `category` is present but not in the known set (`events.ValidCategory`).
+- `400` when `category` is absent or not in the known set (`events.ValidCategory`). External callers always know their category; derivation is not performed.
 - `404` when no capture session is active (consistent with the resource model — publish has no implicit session).
 - `200` on successful publish.
 
 The handler does not take `monitorMu` — `CaptureSession.Publish` is serialised internally and guarantees monotonic seq delivery.
 
-**Request** — only `type` is required:
+**Request** — `type` and `category` are required:
 
 ```json
-POST /events/publish
+POST /events/capture_session/publish
 Content-Type: application/json
 
 {
   "type": "network_request",
-  "ts": 1713100000000000,
   "category": "network",
+  "ts": 1713100000000000,
   "source": {
     "kind": "kernel_api",
     "event": "fetch",
@@ -80,7 +79,7 @@ Content-Type: application/json
 Minimal valid request:
 
 ```json
-{ "type": "network_request" }
+{ "type": "network_request", "category": "network" }
 ```
 
 **Response** `200` — pipeline stamps `seq` and `capture_session_id`, returns the full `Envelope`:
@@ -133,7 +132,7 @@ data: {envelope-json}
 ## 3. Key Design Decisions
 
 1. **Shared pipeline, not a new queue.** External events flow through the same `CaptureSession` as CDP events, so `seq` is globally monotonic across all sources. Consumers never have to merge streams.
-2. `**source.kind` is the fan-out key.\*\* `kernel_api` for publish, `cdp` for the monitor, `extension` / `local_process` reserved for future producers. Category is a coarse bucket derived from `type`; source is the precise provenance.
+2. `**source.kind` is the fan-out key.\*\* `kernel_api` for publish, `cdp` for the monitor, `extension` / `local_process` reserved for future producers. Category is a required caller-supplied field; source is the precise provenance.
 3. **Publish does not honour** `CaptureConfig.Categories`**.** The config is a filter on what the CDP monitor records — an explicit publish is a deliberate caller action and bypasses it.
 4. **SSE over WebSocket.** SSE is one-way, proxy-friendly, and has built-in reconnection semantics (`Last-Event-ID`) that map cleanly to our `seq` cursor. No extra framing library.
 5. **Direct writes, no goroutine.** `StreamEvents` writes straight to the `ResponseWriter` from the request goroutine. No `io.Pipe`, no background worker — correct for HTTP/1.1 SSE and simpler to reason about on disconnect.
@@ -148,7 +147,7 @@ data: {envelope-json}
 ### Added
 
 - `server/cmd/api/api/events.go` — `PublishEvent`, `StreamEvents`, `writeSSEEnvelope` helper. (Re-introduced; the base branch folded the prior `events.go` handlers into `capture_session.go`.)
-- `server/cmd/api/api/events_publish_test.go` — subtests: happy path + ring read, invalid JSON, missing type, unknown category, no-session 404, liveview routing, captcha routing, category derivation from type, default `source.kind` = `kernel_api`.
+- `server/cmd/api/api/events_publish_test.go` — subtests: happy path + ring read, invalid JSON, missing type, missing category, unknown category, no-session 404, liveview routing, captcha routing, default `source.kind` = `kernel_api`.
 - `server/cmd/api/api/events_stream_test.go` — subtests: `no_flusher_returns_500`, no-session 404, live streaming, `Last-Event-ID` resume across gaps, context cancellation on client disconnect.
 
 ---