review: update readme

Author: archandatta

server/lib/cdpmonitor/README.md

@@ -79,4 +79,88 @@ Fields that need no mutex use `sync/atomic`: `nextID`, `mainSessionID`, `running
 
 ### WebSocket concurrency
 
-`coder/websocket` guarantees one concurrent `Read` and one concurrent `Write` are safe on the same connection. `readLoop` is the sole reader. All writes go through `send`, which calls `conn.Write` directly -- `conn.Write` is internally serialized by the library, so no external write mutex is needed.
+`coder/websocket` guarantees one concurrent `Read` and one concurrent `Write` are safe on the same connection. `readLoop` is the sole reader. All writes go through `send`, which calls `conn.Write` directly -- `conn.Write` is internally serialized by the library, so no external write mutex is needed.
+
+## Event data model
+
+### Envelope and top-level fields
+
+Every event arrives as an `Envelope`:
+
+```json
+{
+  "capture_session_id": "cs_abc123",
+  "seq": 42,
+  "event": {
+    "ts": 1746123456789000,
+    "type": "network_request",
+    "category": "network",
+    "source": { ... },
+    "data": { ... },
+    "truncated": false
+  }
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `capture_session_id` | string | Pipeline-assigned ID for the capture session (not a CDP concept). |
+| `seq` | uint64 | Monotonically increasing per-capture-session sequence number. |
+| `event.ts` | int64 | Wall-clock time the monitor emitted the event, as **Unix microseconds** (µs since epoch). |
+| `event.type` | string | See [Event taxonomy](#event-taxonomy). |
+| `event.category` | string | One of: `console`, `network`, `page`, `interaction`, `system`. |
+| `event.truncated` | bool | `true` if `data` was nulled to fit the 1 MB pipeline limit. |
+
+### Source object
+
+```json
+"source": {
+  "kind": "cdp",
+  "event": "Network.requestWillBeSent",
+  "metadata": {
+    "cdp_session_id": "...",
+    "target_id": "...",
+    "target_type": "page"
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `event` | The raw CDP method that triggered the event (e.g. `Network.requestWillBeSent`). Empty for computed events. |
+| `metadata.cdp_session_id` | The CDP WebSocket session multiplexer ID for this target. Changes if Chrome restarts. |
+| `metadata.target_id` | Stable identifier for the browser target (tab/window). Survives navigations within the same tab. |
+| `metadata.target_type` | Target type as reported by Chrome: `page`, `iframe`, `worker`, etc. |
+
+### CDP identity primer
+
+Five IDs appear across events. Understanding how they nest prevents confusion:
+
+```
+target_id          <- one per tab/window; stable across navigations
+└── cdp_session_id <- WebSocket multiplexer channel to that target; resets on Chrome restart
+    └── frame_id   <- one per frame (top-level or iframe); changes on navigation
+        └── loader_id  <- one per document load; links a navigation to its network requests
+            └── request_id <- one per request (stable across redirects in a chain)
+```
+
+| ID | Where it appears | What it identifies |
+| --- | --- | --- |
+| `target_id` | `source.metadata`, most `data` objects | The browser tab. Use this to group all events from one tab session. |
+| `cdp_session_id` | `source.metadata` | The WebSocket sub-channel. Not stable across reconnects. |
+| `frame_id` | `page_navigation`, `network_request`, `network_response`, `network_loading_failed` | The frame the request or navigation belongs to. Top-level frame has no `parent_frame_id`. |
+| `source_frame_id` | `page_layout_shift` | The frame where the layout shift occurred. Distinct from the nav context `frame_id`, which is always the top-level navigated frame. |
+| `loader_id` | `page_navigation`, `network_request`, `network_response` | The document load that owns a request. Join `network_request.loader_id` to `page_navigation.loader_id` to correlate requests with the navigation that triggered them. |
+| `request_id` | `network_request`, `network_response`, `network_loading_failed` | A single request chain (including redirects). Links request to its eventual response or failure. |
+
+### Navigation context fields
+
+Most event `data` objects include a nav context block stamped at the last `page_navigation`. These fields reflect the top-level frame most recently navigated in the session:
+
+| Field | Description |
+| --- | --- |
+| `session_id` | Same as `source.metadata.cdp_session_id`. Repeated for data-only consumers. |
+| `frame_id` | Frame ID of the navigated top-level frame. |
+| `loader_id` | Loader ID of the current document. |
+| `url` | URL of the current page at the time of the last navigation. |
+| `nav_seq` | Monotonically increasing counter, incremented on each `page_navigation`. Use it to detect that the page has navigated between two events in the same session. |