update

docs/8-runbook.md

@@ -0,0 +1,72 @@
+# Runbook: natsClient_JS
+
+## Connection Issues
+
+### `getNats` fails to connect
+
+**Symptom**: `connectionStatus` lands in `error`, `getNats` throws.
+
+**Steps**:
+1. Check the resolved URL precedence: `opts.servers` → `VITE_NATS_URL` → `config.nats_server_info.url` → `wss://natsws.yiem.cc` (`4-specification.md:SP-001`).
+2. Verify broker reachability: `nc -z -w5 <nats-host> <nats-port>`.
+3. Confirm `nats.ws` is available (browser/WSS transport, `NFR-101`).
+4. Retry after fixing config; the consumer should call `getNats` again.
+
+### Connection stuck after a disconnect
+
+**Symptom**: Status stays `disconnected` and does not return to `connected`.
+
+**Steps**:
+1. Confirm `nc.status()` is wired to emit `disconnect`/`reconnect` (`2-solution_design.md:SD-004`).
+2. Check `nc.closed()` for a permanent close (`4-specification.md:SP-001`).
+3. Restart the consuming app to re-establish the shared socket.
+
+**References**: `4-specification.md:SP-001` (connection), `3-walkthrough.md:#wt-007`.
+
+## Message Issues
+
+### Subscribe receives no messages
+
+**Symptom**: No `onMessage` callbacks fire.
+
+**Steps**:
+1. Verify the subject string matches the broker's subject exactly.
+2. Confirm the connection reached `connected` before subscribing.
+3. Check the subscription is tracked in the `Map` (`4-specification.md:SP-002`).
+
+### `sendMsghandlerRequest` throws
+
+**Symptom**: `throw new Error(data)` or `No valid response found`.
+
+**Steps**:
+1. Confirm the backend returns a `jsontable`/`dictionary` payload, not `text` (`4-specification.md:SP-011`).
+2. Verify `msghandlerCSR.smartpack`/`smartunpack` are in use (`2-solution_design.md:SD-006`).
+3. Check the broker envelope format (`4-specification.md:SP-010`, `SP-011`).
+
+### `reply` handler produces no response
+
+**Symptom**: Requests to the subject time out.
+
+**Steps**:
+1. Confirm `handler` returns a value that gets published on `m.subject` (`4-specification.md:SP-005`).
+2. Verify the subject is not also consumed by a `request` on the same endpoint.
+
+## Error Code Reference
+
+| Error | Symptom | Action | Reference |
+|-------|---------|--------|-----------|
+| `error` status | `getNats` failed | Fix URL/config, retry | `4-specification.md:SP-001` |
+| `text` msghandler payload | `sendMsghandlerRequest` throws | Confirm backend returns dictionary/jsontable | `4-specification.md:SP-011` |
+| decode error | subscription message dropped | Handled by per-message guard (NFR-302) | `4-specification.md:SP-002` |
+
+## Escalation
+
+- If the shared socket never reconnects (NFR-102), treat the broker as down and page the backend
+  team; the library only reports state via `connectionStatus`.
+- Contact: backend/NATS on-call via the `nats_client_reconnect_rate` alert.
+
+## Post-Incident
+
+- [ ] Review logs for root cause (`[NATS] ...` lines).
+- [ ] Update this runbook if a new failure mode appears.
+- [ ] Link findings to `6-validation.md` so the case is covered by a test.