serverless-ircd 0.3.0 → 0.4.0

package/docs/Observability.md

@@ -1,87 +0,0 @@
-# Observability
-
-The server ships a structured-logger port that every adapter uses to emit
-JSON log lines carrying a per-request `traceId` and per-connection
-`connectionId`. The canonical event names are the contract dashboards and
-log queries are built against.
-
-## Log contract
-
-Every record is one physical line of JSON with at least:
-
-| Field          | Source                                          |
-|----------------|-------------------------------------------------|
-| `ts`           | ISO-8601 timestamp from the injected `Clock`.   |
-| `level`        | `debug` / `info` / `warn` / `error`.            |
-| `msg`          | Event name (see below).                         |
-| `traceId`      | Per-request id; fresh per inbound frame.        |
-| `connectionId` | The bound connection's id (`ConnId`).           |
-
-Additional structured fields appear per event. The `msg` catalogue:
-
-| `msg`              | Level | Emitted by              | Notes                                                |
-|--------------------|-------|-------------------------|------------------------------------------------------|
-| `frame.receive`    | debug | `ConnectionActor`       | One per parsed IRC line. Fields: `command`, `lines`. |
-| `frame.parse-error`| warn  | `ConnectionActor`       | A line failed to parse. Fields: `line`, `token`.     |
-| `dispatch`         | debug | `dispatch()`            | Before interpreting an effect list. Fields: `effects` (array of tags), `histogram`. |
-| `dispatch.error`   | warn  | `dispatch()`            | A runtime method rejected. Fields: `effect`, `err`.  |
-
-Adapters may emit their own events (e.g. `local-cli listening`, `shutdown`)
-following the same shape.
-
-## Cloudflare Workers
-
-The `apps/cf-worker/wrangler.toml` enables `[observability]` so every
-`console.*` line emitted by the `ConsoleLogger` inside `ConnectionDO` is
-captured by Workers Analytics.
-
-- Tail the live feed: `pnpm --filter @serverless-ircd/cf-worker tail`
-- Filter by connection: `connectionId = "<DO hex id>"`
-- Filter by trace: `traceId = "<uuid>"`
-- Errors only: `level = "error" or msg = "dispatch.error"`
-
-Workers Analytics dashboards can be built on the Cloudflare dashboard
-under **Workers & Pages → <Worker> → Observability**.
-
-## AWS (Lambda + API Gateway WebSocket)
-
-The Lambda handler writes to CloudWatch Logs via the global `console`.
-Each invocation emits one JSON line per log record; the log group name
-follows the standard `/aws/lambda/<function-name>` convention.
-
-A starter CloudWatch dashboard is checked in at
-`dashboards/cloudwatch-irc.json`. Provision it via:
-
-```sh
-aws cloudwatch put-dashboard \
-  --dashboard-name ServerlessIRCd-staging \
-  --dashboard-body file://dashboards/cloudwatch-irc.json
-```
-
-The dashboard variables (`API_ID`, `LAMBDA_NAME`, `LOG_GROUP_ARN`,
-`AWS_REGION`) are templated by CloudWatch's dashboard variables feature —
-set them once in the dashboard UI after import.
-
-Sample CloudWatch Logs Insights query — count dispatched effects by tag
-over the last hour:
-
-```
-fields @timestamp, msg, fields.histogram
-| filter msg = "dispatch"
-| sort @timestamp desc
-```
-
-## Local CLI
-
-The local-cli server uses the same `ConsoleLogger` so the structured
-stream is visible while developing:
-
-```
-{"ts":"2026-07-22T12:34:56.789Z","level":"debug","msg":"frame.receive","traceId":"…","connectionId":"…","command":"PRIVMSG","lines":1}
-```
-
-Filter with `jq`:
-
-```
-pnpm --filter local-cli start | jq 'select(.msg=="dispatch.error")'
-```

package/docs/PlanIRCv3Websocket.md

@@ -1,489 +0,0 @@
-# ServerlessIRCd — IRCv3 WebSocket Extension Plan
-
-Bring the existing WebSocket entry points into compliance with the
-[IRCv3 WebSocket support spec](https://ircv3.net/specs/extensions/websocket).
-Today the server transports IRC over WebSocket but ignores the spec's
-defining features: **subprotocol negotiation**, **one-line-per-message
-framing**, the **510-byte message budget**, and **binary/text frame mode
-distinction**. This plan closes those gaps across the pure core and all
-three adapters (Cloudflare Workers, AWS, local CLI) plus the in-tree TCP
-bridge.
-
-> **Status:** planning. No code has landed. Seven tickets proposed in §7
-> under a new **Phase 9 — IRCv3 WebSocket extension** heading; once
-> ratified they will be appended to `tickets.md` / `progress.md` and
-> supersede the corresponding sections here.
-
----
-
-## 1. Goals & non-goals
-
-**Goals**
-- Full compliance with the normative MUSTs of the IRCv3 WebSocket spec:
-  - Negotiate the `binary.ircv3.net` **and** `text.ircv3.net` subprotocols,
-    honoring the client's order of preference.
-  - One IRC line per WebSocket message, with no trailing `\r\n`.
-  - 510-byte default message budget (content; the server re-inserts
-    `\r\n` internally for any TCP relay / line accounting).
-  - Distinct binary vs text frame handling; never relay non-UTF-8 to a
-    text-mode client.
-- Keep the change **inside the transport layer**. The hexagonal core
-  (`irc-core` reducers, `irc-server` `ConnectionActor`) stays
-  transport-agnostic; only framing/byte-boundary concerns move.
-- Preserve backward compatibility: clients that do **not** negotiate a
-    subprotocol keep working via a legacy-tolerant path (the spec permits
-    this).
-- Same TDD discipline as the rest of the monorepo: pure negotiation &
-  framing helpers unit-tested; per-adapter integration tests against a
-  real WS handshake.
-
-**Non-goals (v1 of this work)**
-- Non-UTF-8 *channel communities*. The core already reasons in JS strings
-  (UTF-8 at the boundary); we validate/replace lone surrogates but do not
-  introduce a raw-bytes code path through the reducers. Binary mode is
-  supported at the frame layer only.
-- A second transport or SockJS gateway. `webircgateway` remains an
-  optional sidecar; not in scope here.
-- WebSocket `Origin` allowlisting. That is CSWSH defense tracked separately
-  (PLAN-WEB-CLIENT §7, TICKET-070). This plan assumes an Origin check, if
-  added, layers on top of the upgrade handler untouched by subprotocol
-  work.
-- Resumable sessions / `X-Connection-Id`. The upgrade handler will gain a
-  clean seam for future subprotocol-derived routing, but session resume is
-  out of scope.
-
-**Design-for-later**
-- The subprotocol selector returns the chosen mode as a value the adapters
-  stash on connection state. A future resumable-session ticket can ride
-  the same field instead of re-deriving it.
-
----
-
-## 2. Current state (the compliance gap)
-
-Audited against the spec. Findings, with file:line references:
-
-| Spec requirement | Status | Evidence |
-|---|---|---|
-| Negotiate `binary.ircv3.net` / `text.ircv3.net` | **Missing** | `packages/cf-adapter/src/connection-do.ts:108-121` returns `101` with no protocol; `apps/cf-worker/src/worker.ts:45-49` checks only `Upgrade`. No `Sec-WebSocket-Protocol` / `subprotocol` strings anywhere. |
-| One IRC line per WS message, no trailing CRLF | **Violated (legacy-tolerant instead)** | `packages/irc-server/src/actor.ts:150-159` `receiveTextFrame` splits every frame on `\r?\n` (`splitFrameLines`, line 454-457); outbound batches multiple lines into one frame joined by `\r\n` (`connection-do.ts:234`, `apps/local-cli/src/server.ts:507`, `packages/aws-adapter/src/handlers/default.ts:127`). |
-| 510-byte message budget | **Off by 2** | `packages/irc-core/src/protocol/parser.ts:30` `MAX_INPUT_BYTES = 512`; `packages/irc-core/src/protocol/outbound.ts:27` `MAX_LINE_BYTES = 512` (defines `TRAILING_CRLF_LEN = 2` at line 30 but never subtracts it). |
-| Binary vs text frame mode | **Not distinguished** | `connection-do.ts:128-129` silently `TextDecoder`-decodes `ArrayBuffer`; no `binaryType`, no mode tracking. |
-| Don't relay non-UTF-8 to text clients | N/A until text mode exists | — |
-| PING/PONG keepalive | **Already compliant** | CF alarms (`connection-do.ts:185-204`); AWS EventBridge (`ping-checker.ts`). |
-| Impose message-size limits (security SHOULD) | **Present**, wrong threshold | 512 caps exist; spec wants 510 for WS. |
-
-The transport itself works today (CF Hibernating WebSockets, AWS API
-Gateway, local `ws`). What's missing is the *spec framing* layered on top.
-
----
-
-## 3. Architecture
-
-WebSocket framing is a **transport-boundary** concern, so the work fans
-out across the hexagon but the *logic* stays pure and central:
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  packages/irc-core   (pure, no cloud deps)                       │
-│    ws-subprotocol.ts   parseSecWsProtocolOffers / selectSubproto │
-│    ws-framing.ts       frameMode, stripTrailingCrLf,             │
-│                        splitWsFrame (legacy), enforce 510 budget │
-│    protocol/outbound.ts  WS-aware line-limit (510) + lone-       │
-│                          surrogate sanitization for text mode    │
-└──────────────────────────────────────────────────────────────────┘
-                                ▲ used by
-┌─────────────────────────────────────────────────────────────────┐
-│  packages/irc-server   ConnectionActor                          │
-│    receiveFrame(text|bytes, mode)   mode-aware entry: spec =    │
-│                                     one line; legacy = split    │
-└─────────────────────────────────────────────────────────────────┘
-        ▲                              ▲                      ▲
-┌──────────────────────┐  ┌─────────────────────┐  ┌──────────────────────┐
-│  cf-adapter          │  │  aws-adapter        │  │  local-cli           │
-│  ConnectionDO.fetch: │  │  $connect: echo     │  │  ws handleProtocols; │
-│   read header, echo  │  │   Sec-WebSocket-    │  │   per-conn mode;     │
-│   subprotocol, store │  │   Protocol via CDK  │  │   per-message send   │
-│   mode; hibernation  │  │   integration resp; │  │                      │
-│   tag; per-message   │  │   Connections.mode; │  │                      │
-│   send; binary/text  │  │   per-message send  │  │                      │
-└──────────────────────┘  └─────────────────────┘  └──────────────────────┘
-        ▲
-┌─────────────────────────┐
-│  tools/tcp-ws-forwarder │  offer binary.ircv3.net upstream;
-│                         │   strip/append CRLF at the TCP seam
-└─────────────────────────┘
-```
-
-**Key invariant:** the *reducers never change*. Framing (how bytes become
-`IrcMessage`s and how `Effect`s become bytes) is the only thing touched.
-
----
-
-## 4. Design decisions
-
-### 4.1 Subprotocol selection (pure)
-
-A pure helper set in `irc-core`:
-
-```ts
-export const WS_SUBPROTO_BINARY = 'binary.ircv3.net';
-export const WS_SUBPROTO_TEXT    = 'text.ircv3.net';
-export type WsSubprotocol = typeof WS_SUBPROTO_BINARY | typeof WS_SUBPROTO_TEXT;
-
-/** Parse a `Sec-WebSocket-Protocol` header (comma list, trimmed). */
-export function parseSecWsProtocolOffers(header: string | null): string[];
-
-/**
- * Pick the first offered protocol we support, in client-preference order.
- * Returns null if none match (caller MAY still accept the connection per spec).
- */
-export function selectSubprotocol(offers: string[]): WsSubprotocol | null;
-```
-
-Selection order is **the client's order** (spec: "respecting the client's
-order of preference"). We accept the first of `[binary.ircv3.net,
-text.ircv3.net]` the client listed. If the client offers neither, return
-`null` — the adapter still upgrades (legacy path) per the spec's MAY.
-
-### 4.2 Frame mode on connection state
-
-Adapters store the negotiated mode on per-connection state. We do **not**
-thread it through the core reducers (they're mode-blind); only the
-framing entry point and the outbound serializer consult it.
-
-- CF: hibernation tag via `acceptWebSocket(ws, [tag])` where
-  `tag = "ws:" + mode`; recovered in `webSocketMessage` via
-  `ws.deserialize`-equivalent tag read. Persisted as a field in DO state
-  for the outbound path.
-- AWS: new `mode` column on the `Connections` table (default `null` =
-  legacy).
-- Local CLI: a `Map<WebSocket, WsSubprotocol | null>` on the server.
-
-### 4.3 Inbound framing — spec mode vs legacy mode
-
-```ts
-export type WsFrameMode = 'spec-text' | 'spec-binary' | 'legacy';
-
-/** One frame -> one line in spec mode; tolerant split in legacy mode. */
-export function frameToLines(frame: string, mode: WsFrameMode): string[];
-```
-
-- **spec-text / spec-binary:** the frame *is* the line. Strip an optional
-  single trailing `\r\n`/`\n` (defensive; clients SHOULD NOT send it), then
-  return `[frame]` if non-empty else `[]`. Never split on embedded
-  newlines.
-- **legacy:** current `splitFrameLines` behavior (`/\r?\n/`), preserved
-  verbatim for clients that never negotiated.
-
-`ConnectionActor` gains `receiveFrame(payload: string, mode)`; existing
-`receiveTextFrame` becomes a thin caller passing `'legacy'` so all current
-call sites and tests keep their behavior until updated.
-
-### 4.4 Outbound framing — one message per line in spec mode
-
-Today adapters batch `lines.map(l => l.text).join('\r\n') + '\r\n'` into a
-single `ws.send`. In **spec mode** each outbound IRC line is its own WS
-message with **no** trailing CRLF:
-
-```ts
-// spec mode
-for (const line of outboundLines) ws.send(line.text);   // one msg each, no CRLF
-// legacy mode (unchanged)
-ws.send(outboundLines.map(l => l.text).join('\r\n') + '\r\n');
-```
-
-This is the largest mechanical change (three adapters + their tests), but
-localized to the delivery functions.
-
-### 4.5 Size budget — 510 for WS, 512 for TCP
-
-Introduce `MAX_WS_MESSAGE_BYTES = 510` alongside the existing 512 TCP cap.
-The WS inbound path enforces 510 on the message (no CRLF to discount);
-`enforceLineLimit` gains a mode-aware budget so spec-mode clients get the
-correct outbound ceiling. TCP and legacy-WS paths are unchanged.
-
-### 4.6 Binary vs text handling
-
-- **spec-binary (`binary.ircv3.net`):** frames are `ArrayBuffer`. CF
-  `webSocketMessage` already receives `string | ArrayBuffer`; we pass
-  bytes through `TextDecoder` (our core is string-based) **but only after**
-  validating. Binary mode is the "any valid IRC line" mode; for our
-  UTF-8-string core this collapses to the same decode as text, with the
-  difference being that we *accept* a binary frame without complaint.
-- **spec-text (`text.ircv3.net`):** frames are `string`. If a binary frame
-  arrives on a text-mode connection, reject per spec (close 1003 /
-  unsupported data) rather than silently decoding.
-- **Non-UTF-8 to text clients:** our outbound is always JS strings → valid
-  UTF-8. The residual risk is *lone surrogates* (unpaired halves of
-  surrogate pairs, which `TextEncoder` rejects). `sanitizeForTextMode`
-  replaces lone surrogates with U+FFFD before send on text-mode sockets.
-
-### 4.7 Backward compatibility
-
-The web client (PLAN-WEB-CLIENT) and `tcp-ws-forwarder` currently rely on
-the legacy `\r\n`-batched framing. Because un-negotiated connections fall
-into `'legacy'` mode, **nothing breaks** until each client opts in by
-offering a subprotocol. The forwarder is updated in the same phase so the
-in-tree bridge immediately exercises the spec path.
-
----
-
-## 5. Component placement
-
-No new workspace packages. Changes are additions/edits within existing
-packages:
-
-```
-packages/irc-core/src/
-├── ws-subprotocol.ts        NEW — parseSecWsProtocolOffers, selectSubprotocol
-├── ws-framing.ts            NEW — WsFrameMode, frameToLines, stripTrailingCrLf,
-│                                  MAX_WS_MESSAGE_BYTES, sanitizeForTextMode
-└── protocol/outbound.ts     EDIT — mode-aware enforceLineLimit (510 vs 512)
-packages/irc-core/tests/
-├── ws-subprotocol.test.ts   NEW
-└── ws-framing.test.ts       NEW
-
-packages/irc-server/src/actor.ts        EDIT — receiveFrame(text, mode);
-                                                  receiveTextFrame delegates
-packages/irc-server/tests/actor.*.test.ts  EDIT — add spec-mode cases
-
-packages/cf-adapter/src/connection-do.ts   EDIT — upgrade negotiation, mode
-                                                  tag/storage, per-msg send,
-                                                  binary/text branch
-packages/aws-adapter/src/handlers/connect.ts  EDIT — read header, persist mode
-packages/aws-adapter/src/handlers/default.ts  EDIT — per-message send
-apps/aws-stack/src/aws-stack.ts               EDIT — integration response
-                                                  Sec-WebSocket-Protocol header
-apps/local-cli/src/server.ts                  EDIT — handleProtocols, mode map,
-                                                  per-message send
-tools/tcp-ws-forwarder/src/forwarder.ts       EDIT — offer binary subproto,
-                                                  framing translation
-```
-
----
-
-## 6. Testing strategy
-
-- **Pure units (Red-first):** `ws-subprotocol.test.ts` and
-  `ws-framing.test.ts` drive the helpers — header parsing edge cases
-  (whitespace, duplicates, empty), preference ordering, spec-vs-legacy
-  line splitting, 510-boundary, lone-surrogate replacement.
-- **Actor unit:** extend `actor.*.test.ts` to call `receiveFrame(...,
-  'spec-text')` and assert one-line-per-message semantics; keep existing
-  `receiveTextFrame` tests green (legacy).
-- **CF integration (`vitest-pool-workers` / Miniflare):** open a real WS
-  to `ConnectionDO` offering `text.ircv3.net`, assert the 101 response
-  echoes the protocol, send `NICK`/`USER` as separate CRLF-less messages,
-  assert registration replies arrive one-per-message. A second case
-  offers neither protocol and asserts legacy batching still works.
-- **AWS:** unit-test the connect handler's header→mode mapping and the CDK
-  integration-response header; local-stack smoke optional.
-- **Determinism:** all of the above are hermetic except an optional real-
-  browser check, which stays behind a `--e2e` flag like the web client
-  plan.
-
----
-
-## 7. Proposed tickets
-
-Seven new tickets under a new **Phase 9 — IRCv3 WebSocket extension**
-heading in `tickets.md` / `progress.md`. Each follows the existing
-Red → Green → Refactor TDD outline.
-
-### TICKET-073 — Core: WebSocket subprotocol negotiation helpers
-- **Phase:** 9
-- **Points:** 2
-- **Dependencies:** —
-- **Description:** Add `packages/irc-core/src/ws-subprotocol.ts` with
-  `WS_SUBPROTO_BINARY`/`WS_SUBPROTO_TEXT` constants, the `WsSubprotocol`
-  type, `parseSecWsProtocolOffers(header)`, and
-  `selectSubprotocol(offers)` honoring client-preference order, returning
-  `null` when neither is offered. Pure, zero deps.
-- **Acceptance Criteria:**
-  - `parseSecWsProtocolOffers('text.ircv3.net, binary.ircv3.net')`
-    yields `['text.ircv3.net','binary.ircv3.net']` (whitespace-tolerant).
-  - `selectSubprotocol` returns the first supported entry in offer order.
-  - Offering only unsupported protocols returns `null`.
-  - `null`/empty header → `[]` offers → `null` selection.
-- **TDD Outline:** Red on preference-order test; green. Red on duplicate/
-  whitespace cases; green. Red on no-match returns null; green.
-
-### TICKET-074 — Core: WS frame framing & 510-byte budget
-- **Phase:** 9
-- **Points:** 3
-- **Dependencies:** TICKET-073
-- **Description:** Add `packages/irc-core/src/ws-framing.ts`: `WsFrameMode`
-  (`'spec-text' | 'spec-binary' | 'legacy'`), `MAX_WS_MESSAGE_BYTES = 510`,
-  `stripTrailingCrLf`, `frameToLines(frame, mode)` (spec = single line;
-  legacy = current `splitFrameLines` behavior), and
-  `sanitizeForTextMode(str)` replacing lone surrogates with U+FFFD. Move
-  the existing `splitFrameLines` body here (or re-export) so legacy mode
-  is literally the current code. Make `enforceLineLimit` in `outbound.ts`
-  budget-aware (510 in spec modes, 512 otherwise).
-- **Acceptance Criteria:**
-  - `frameToLines('NICK bob\r\n', 'spec-text')` → `['NICK bob']` (one
-    line; CRLF stripped; not split).
-  - Embedded `\n` in a spec-mode frame stays a single line.
-  - `frameToLines('a\r\nb', 'legacy')` → `['a','b']` (unchanged behavior).
-  - WS inbound rejects a 511-byte message; accepts 510.
-  - `sanitizeForTextMode` turns a lone surrogate into U+FFFD.
-- **TDD Outline:** Red per bullet above; minimal green; refactor shared
-  strip logic.
-
-### TICKET-075 — CF adapter: negotiate subprotocol + per-message framing
-- **Phase:** 9
-- **Points:** 3
-- **Dependencies:** TICKET-073, TICKET-074
-- **Description:** In `ConnectionDO.fetch` read `Sec-WebSocket-Protocol`,
-  run `selectSubprotocol`, echo the chosen protocol back in the `101`
-  response headers, and tag the hibernated socket (`acceptWebSocket(ws,
-  [\`ws:${mode}\`])`). Derive `WsFrameMode` in `webSocketMessage` (binary
-  frame on a `spec-text` connection → close 1003). Store the mode in DO
-  state for the outbound path. Change outbound delivery to one
-  `ws.send(line)` per IRC line in spec mode (no CRLF); keep legacy
-  batching otherwise. Apply `sanitizeForTextMode` on `spec-text` sends.
-- **Acceptance Criteria:**
-  - 101 response to an offer of `text.ircv3.net` includes
-    `Sec-WebSocket-Protocol: text.ircv3.net`.
-  - A client offering both gets the first-listed supported protocol.
-  - An un-negotiated client still connects (legacy mode) and existing CF
-    WS tests stay green.
-  - Registration replies to a spec-mode client arrive as N separate WS
-    messages with no trailing CRLF.
-  - Binary frame on a text-mode socket closes 1003.
-- **TDD Outline:** Red on a Miniflare WS asserting the echoed header;
-  green. Red asserting per-message send (count messages); green. Red on
-  binary-on-text close; green.
-
-### TICKET-076 — Local CLI adapter: `handleProtocols` + per-message framing
-- **Phase:** 9
-- **Points:** 2
-- **Dependencies:** TICKET-073, TICKET-074
-- **Description:** Give `apps/local-cli/src/server.ts`'s `WebSocketServer`
-  a `handleProtocols` callback backed by the core selector; keep a
-  `Map<WebSocket, WsSubprotocol | null>` for mode. Route inbound through
-  the actor's `receiveFrame`; switch the `ws.send` delivery to per-message
-  in spec mode. Un-negotiated clients keep today's behavior.
-- **Acceptance Criteria:**
-  - `wscat -s text.ircv3.net` against the local server negotiates the
-    protocol and exchanges one-line-per-message frames.
-  - Existing local-cli integration tests pass unchanged (legacy path).
-- **TDD Outline:** Red on a `ws` client asserting the echoed subprotocol
-  and one-message-per-line; green.
-
-### TICKET-077 — AWS adapter: subprotocol echo + per-message framing
-- **Phase:** 9
-- **Points:** 3
-- **Dependencies:** TICKET-073, TICKET-074
-- **Description:** API Gateway lets the integration choose the
-  subprotocol via the `$connect` route's integration-response header
-  `Sec-WebSocket-Protocol`. Read the offered header in `connect.ts`, run
-  the selector, persist the chosen `mode` (new `Connections` column,
-  default null = legacy), and emit the header in the CDK
-  integration-response (`apps/aws-stack/src/aws-stack.ts`). In
-  `default.ts`, deliver each outbound line as its own `postToConnection`
-  in spec mode.
-- **Acceptance Criteria:**
-  - A `$connect` offering `binary.ircv3.net` gets the protocol echoed and
-    a non-null `mode` row.
-  - `$default` replies to a spec-mode connection arrive one per
-    `postToConnection`.
-  - Legacy connections (no offer) are unaffected.
-- **TDD Outline:** Red on connect-handler unit asserting header→mode;
-  green. Red on CDK template asserting the integration-response header;
-  green. Red on default-handler per-message delivery; green.
-
-### TICKET-078 — tcp-ws-forwarder: negotiate `binary.ircv3.net` upstream
-- **Phase:** 9
-- **Points:** 2
-- **Dependencies:** TICKET-075
-- **Description:** When `tools/tcp-ws-forwarder` dials the IRCd WebSocket,
-  offer `['binary.ircv3.net', 'text.ircv3.net']`. Translate framing at the
-  TCP seam: each TCP IRC line (CRLF-terminated) → one WS message **with
-  the CRLF stripped**; each inbound WS message → one TCP line **with CRLF
-  re-appended**. This makes the in-tree bridge exercise the spec path
-  end-to-end against the CF worker.
-- **Acceptance Criteria:**
-  - A real IRC TCP client (e.g. weechat/irssi) through the forwarder
-    completes registration against a spec-mode worker.
-  - Forwarder unit tests assert CRLF strip on send and re-append on
-    receive.
-- **TDD Outline:** Red on send-translation (no trailing CRLF in WS msg);
-  green. Red on receive-translation (CRLF appended to TCP); green.
-
-### TICKET-079 — Integration: spec-compliance test + docs note
-- **Phase:** 9
-- **Points:** 2
-- **Dependencies:** TICKET-075, TICKET-076, TICKET-077
-- **Description:** Add a `vitest-pool-workers` integration test that
-  negotiates `text.ircv3.net` against `ConnectionDO` end-to-end and
-  asserts the full spec contract (echoed header, one-line-per-message
-  both directions, 510 budget, legacy fallback still works). Add a short
-  "WebSocket (IRCv3)" section to the README listing supported
-  subprotocols and the legacy fallback behavior.
-- **Acceptance Criteria:**
-  - The integration test is green and runs in the normal `pnpm test`
-    suite (no `--e2e` flag needed — it's hermetic against Miniflare).
-  - README documents `binary.ircv3.net` / `text.ircv3.net` support.
-- **TDD Outline:** Red on the end-to-end spec assertions; green as the
-  dependency tickets land. Docs reviewed by reading the rendered README.
-
----
-
-## 8. Risks
-
-| Risk | Mitigation |
-|---|---|
-| Per-message send (N `ws.send`/`postToConnection` calls) raises CF/AWS cost or latency vs one batched frame | Measure in TICKET-075/077; batching IRC lines into one message is itself spec-non-compliant, so the cost is accepted. Cap bursts if needed via the existing rate limiter. |
-| Hibernation tag API (`acceptWebSocket(ws, [tag])`) surface drift across runtime versions | Confirm against current `compatibility_date` in `apps/cf-worker/wrangler.toml`; fall back to persisting mode in DO state if the tag read is unavailable. |
-| Existing clients (Kiwi via PLAN-WEB-CLIENT, forwarder) break if legacy mode regresses | Legacy mode is literally the moved `splitFrameLines`/batched-send code; keep its tests unchanged and gate spec behavior strictly on a negotiated subprotocol. |
-| API Gateway subprotocol echo has regional/CDK quirks | Validate on a real stack before merging TICKET-077; keep legacy (no-offer) path as the safe default. |
-| 510 vs 512 boundary rejects a currently-accepted 511-byte legacy line | The 510 budget applies **only** to spec-mode WS; TCP and legacy-WS keep 512. No regression for existing traffic. |
-| Lone-surrogate sanitization alters message content | Applies to text mode only and matches the spec's U+FFFD guidance; binary-mode clients are unaffected. |
-
----
-
-## 9. Out of scope for v1 of this work
-
-- Raw-bytes / non-UTF-8 channel communities through the reducers. Binary
-  mode is honored at the frame layer; the core stays string-based.
-- A new transport (SockJS / `webircgateway` integration). The gateway
-  remains an optional sidecar.
-- WebSocket `Origin` allowlisting (tracked in PLAN-WEB-CLIENT
-  TICKET-070).
-- Resumable sessions / `X-Connection-Id` routing.
-- Per-message compression (permessage-deflate) — a Cloudflare/AWS platform
-  concern, not an IRCv3 WebSocket spec item.
-
----
-
-## 10. Deliverables checklist (definition of done)
-
-- [ ] `ws-subprotocol.ts` + `ws-framing.ts` land in `irc-core` with unit
-  tests green and ≥90% coverage.
-- [ ] `ConnectionActor.receiveFrame` supports spec/legacy modes; all
-  existing actor tests pass.
-- [ ] CF, AWS, and local-cli adapters negotiate a subprotocol, echo it,
-  and send one message per IRC line in spec mode; legacy path unchanged.
-- [ ] `tcp-ws-forwarder` offers the binary subprotocol and translates
-  framing at the TCP seam.
-- [ ] Hermetic Miniflare integration test asserts the full spec contract.
-- [ ] README documents IRCv3 WebSocket support and the legacy fallback.
-- [ ] All new tickets green in `progress.md`; PLAN §2 gap table updated to
-  show compliance.
-
----
-
-## 11. Open questions
-
-- Should un-negotiated connections default to **text** mode (stricter,
-  simpler) instead of legacy-tolerant? Lean toward legacy for max compat;
-  revisit once the web client adopts subprotocol negotiation.
-- Do we want to advertise WS subprotocol support via an IRCv3 capability
-  (there isn't a standard one) or purely at the HTTP layer? Lean HTTP-only
-  — the spec defines no IRC-level CAP for this.
-- For AWS, is the per-message `postToConnection` cost acceptable at scale,
-  or do we need a spec-compliant batching strategy (e.g. one message per
-  IRC line but coalesced within a single Lambda response where API
-  Gateway permits)? Defer until measured.