serverless-ircd 0.4.0 → 0.6.0

package/docs/ADR-003-durable-object-sharding.md

@@ -0,0 +1,110 @@
+# ADR-003: Cloudflare Durable Object sharding strategy
+
+**Date:** 2025-02-01 (Phase 3)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+Cloudflare Durable Objects (DOs) are single-threaded per-instance: all
+requests to a given DO instance are serialized. This is ideal for enforcing
+uniqueness invariants (two racing requests land on the same DO, one after the
+other), but a single DO instance is a throughput ceiling. ServerlessIRCd needs
+three DO classes:
+
+1. **ConnectionDO** — one per WebSocket connection. Keyed by `connectionId`.
+   No sharding needed: each connection is its own instance.
+2. **ChannelDO** — one per channel. Keyed by lowercased channel name.
+   No sharding needed: one DO per channel is the natural unit; a hot channel
+   (1k+ members) is bounded by DO fanout latency, not by DO count.
+3. **RegistryDO** — holds the global nick → connectionId map. If this were a
+   single DO, every nick registration on the entire server would serialize
+   through one instance. That is an unacceptable bottleneck for any non-trivial
+   deployment.
+
+The open question (PLAN §9): *"Channel DO sharding granularity (one DO per
+channel vs. bucketed)?"* and *"Registry DO: how to shard?"*
+
+## Decision
+
+**ConnectionDO:** one instance per connection (`idFromName(connectionId)`).
+No sharding.
+
+**ChannelDO:** one instance per channel
+(`idFromName(lowercasedChannelName)`). No bucketing. If a hot channel exceeds
+DO throughput limits, the mitigation is fanout batching (one `stub()` call
+carrying multiple lines) rather than splitting the channel across DOs. A
+single channel's roster and modes live in one DO so that all mutations are
+serialized correctly.
+
+**RegistryDO:** sharded by `hash(lowercased(nick)) % N`, where `N` defaults
+to **32** (`DEFAULT_REGISTRY_SHARDS`). The hash function is FNV-1a 32-bit,
+chosen for its uniform distribution, deterministic output (no randomness),
+and trivial implementation.
+
+```
+shard = fnv1a32(nick.toLowerCase()) % N
+key   = `s${shard}`   // e.g. "s7", "s31"
+stub  = env.REGISTRY_DO.get(env.REGISTRY_DO.idFromName(key))
+```
+
+Two clients racing on the same nick always land on the same shard (because
+lowercasing collapses case variants), so the single-shard uniqueness check
+covers all case variants. Different nicks spread across shards, so
+registration throughput scales with the fleet size.
+
+Cross-shard nick changes (old nick and new nick hash to different shards)
+use a two-phase reserve-new-then-release-old. The new-nick shard wins the
+race; the old-nick shard is released only after the new reservation succeeds.
+
+`N` is configurable via the `REGISTRY_SHARDS` environment variable. Changing
+`N` in production requires a migration (re-sharding every existing nick entry
+to its new shard).
+
+## Consequences
+
+**Positive:**
+- Nick uniqueness is race-free within the DO model. No conditional writes,
+  no optimistic concurrency — the DO's serial execution is the lock.
+- Registration throughput scales horizontally: 32 shards handle 32× the
+  single-DO throughput for distinct nicks.
+- One DO per channel keeps channel semantics simple: JOIN/PART/MODE/KICK all
+  serialize through the same instance.
+
+**Negative:**
+- Changing `N` (the shard count) requires migrating every existing nick to
+  its new shard. This is an offline migration, not a live reshard. The shard
+  count should be chosen conservatively at deployment time.
+- The channel registry problem: there is no DO that "knows" all channels
+  (LIST, TICKET-073). A dedicated registry DO or KV index is needed — this is
+  a known gap tracked in TICKET-073.
+- Hot-nick collisions (many nicks hashing to the same shard) are possible but
+  statistically rare with FNV-1a and `N = 32` for typical populations.
+
+### Outbound batching scope (TICKET-087)
+
+The fanout batching decided above is implemented **per call**:
+`ConnectionDO.deliver()` joins every line of one ChannelDO broadcast into a
+single `WebSocket.send()`, and the actor's `send` handler does the same for
+all lines of one frame's response. A speculative **cross-call** coalescing
+optimization (queueing lines from independent `deliver`/`send` invocations
+within one microtask and flushing them as one write) was reserved as a
+commented-out field in `ConnectionDO` and subsequently **dropped**: it would
+add a drain queue and a `queueMicrotask` scheduler, introduce ordering
+hazards between independent fan-out calls, and yield no measured benefit —
+nothing in the TICKET-049 load-test report or the ChannelDO fan-out path
+shows WS round-trips as a bottleneck. The AWS adapter batches at a different
+layer (per-invocation `outbound: string[]` accumulated then posted once), so
+no shared abstraction is worth extracting. Revisit only if WS round-trips
+become a demonstrated bottleneck.
+
+## References
+
+- PLAN §9 — open question: "Channel DO sharding granularity"
+- PLAN §6.1 — `RegistryDO` sharded by `hash(nick) % N`
+- `packages/cf-adapter/src/sharding.ts` — `shardNick`, `registryKeyForNick`,
+  `DEFAULT_REGISTRY_SHARDS = 32`
+- `packages/cf-adapter/src/registry-do.ts` — per-shard registry authority
+- TICKET-034 — RegistryDO implementation
+- TICKET-073 — CF runtime stubbed lookups (channel registry gap)

package/docs/ADR-004-dynamodb-schema.md

@@ -0,0 +1,96 @@
+# ADR-004: AWS DynamoDB schema
+
+**Date:** 2025-02-15 (Phase 4)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+The AWS adapter runs IRC state on DynamoDB (single table family, not
+single-table design). Unlike Cloudflare Durable Objects, DynamoDB does not
+serialize access to a record by default — concurrent writes can interleave.
+Nick uniqueness, channel membership atomicity, and gone-connection cleanup
+all require explicit concurrency control.
+
+The schema must support: connection records, channel metadata, channel
+membership (roster), nick registry, and SASL account credentials. It must
+also handle the Lambda invocation model: each `$default` invocation is a
+fresh process that reads state, runs a reducer, and writes back — there is no
+in-memory state between invocations.
+
+## Decision
+
+Five tables, each with a clear partition-key boundary:
+
+| Table | Partition Key | Sort Key | TTL | Purpose |
+|---|---|---|---|---|
+| `Connections` | `connectionId` | — | `idleSince` | Per-connection state: nick, user, host, caps, joined channels, away |
+| `ChannelMeta` | `channelName` | — | — | Topic, modes, key, limit |
+| `ChannelMembers` | `channelName` | `connectionId` | — | Roster: membership + prefix flags (op/voice) |
+| `Nicks` | `nickLower` | — | — | Nick → connectionId registry |
+| `Accounts` | `account` | — | — | SASL credentials (scrypt-hashed, never plaintext) |
+
+**Concurrency invariants:**
+- **Nick uniqueness:** enforced via conditional `PutItem`
+  (`ConditionExpression: attribute_not_exists(nickLower)`). Two racing
+  Puts for the same nick — exactly one succeeds; the other gets a
+  `ConditionalCheckFailedException` → `433 ERR_NICKNAMEINUSE`.
+- **Membership atomicity:** `TransactWriteItems` spans `Connections`
+  (update `joinedChannels`) and `ChannelMembers` (add/remove member) in a
+  single atomic transaction. Concurrent JOIN/PART by the same connection
+  cannot leave inconsistent state.
+- **Gone connections:** `ApiGatewayManagementApi.postToConnection` throws
+  `GoneException` for a stale connection. The handler catches this, triggers
+  lazy cleanup (removes the `Connections` row + `ChannelMembers` rows), and
+  broadcasts QUIT to peers (TICKET-074). A sweeper Lambda reaps rows whose
+  `idleSince` TTL has expired.
+- **Environment isolation:** physical table names are environment-prefixed
+  (`<Env>Connections`, e.g. `StagingConnections`) so staging and production
+  can coexist in the same account + region (TICKET-066).
+
+**SASL credentials** (`Accounts`): stored as scrypt `HashedAccountCredential`
+rows (`{ account, algorithm, salt, hash }`, base64-encoded). The Lambda
+pre-loads all rows at cold start into an in-memory `DynamoAccountStore`; the
+reducer's `AccountStore.verify()` stays synchronous (reducers are pure — no
+async). Seed tooling (`tools/seed-aws-accounts.ts`) writes hashed rows; never
+plaintext.
+
+## Consequences
+
+**Positive:**
+- Clear separation of concerns: each table is one authority (matches
+  ADR-002). A channel's metadata, membership, and each member's connection
+  record are independently addressable.
+- Conditional writes + `TransactWriteItems` give race-free semantics without
+  locks — the natural fit for DynamoDB.
+- `idleSince` TTL auto-reaps idle connections even if the sweeper misses a
+  tick; the sweeper is a belt-and-suspenders cleanup, not the only path.
+- Pay-per-request billing means idle tables cost nothing; the schema does not
+  over-provision.
+
+**Negative:**
+- Five tables (vs. a single-table design) means more `TransactWriteItems`
+  spanning multiple partitions. `TransactWriteItems` consumes more RCUs than
+  individual writes and has a 100-item-per-transaction cap. Membership
+  transactions are 2 items (well within limits), but a future feature that
+  touches many channels in one command could approach the cap.
+- No cross-table GSI for "all channels a connection is in" — the
+  `Connections` row stores `joinedChannels` as a set, which must be updated
+  on every JOIN/PART. This duplicates membership data between `Connections`
+  and `ChannelMembers`, kept consistent by the transaction.
+- `Accounts` pre-loading at cold start means every Lambda cold start scans
+  the table. For deployments with thousands of accounts, this adds latency.
+  Mitigated by Lambda reuse (warm starts skip the scan); a cache layer or
+  on-demand lookup is a documented follow-up.
+
+## References
+
+- PLAN §4 — state model & authoritative ownership
+- PLAN §6.2 — DynamoDB tables
+- `packages/aws-adapter/src/cdk-table-defs.ts` — `TABLE_DEFS` (source of truth)
+- `packages/aws-adapter/src/aws-runtime.ts` — `AwsRuntime` implementation
+- TICKET-039 — CDK stack
+- TICKET-041 — DynamoDB transactions for membership
+- TICKET-066 — environment-name prefixing
+- TICKET-072 — `Accounts` table scrypt-hashed `AccountStore`

package/docs/ADR-005-wss-only-transport-v1.md

@@ -0,0 +1,83 @@
+# ADR-005: wss-only transport in v1 (no raw TCP)
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Superseded by ADR-009 (Phase 7 — TICKET-052)
+**Supersedes:** —
+
+## Context
+
+IRC is traditionally spoken over raw TCP (port 6667 plaintext, 6697 TLS).
+WebSocket Secure (wss) is a framing layer over TLS that adds an HTTP upgrade
+handshake. Serverless compute platforms have fundamentally different support
+for these two transports:
+
+- **Cloudflare Workers** can accept WebSocket upgrades but **cannot accept raw
+  TCP**. Spectrum (Enterprise tier) can terminate TLS and proxy to an origin,
+  but Workers itself is request-response.
+- **AWS API Gateway WebSocket API** provides persistent WebSocket connections
+  with per-message Lambda invocation. Raw TCP requires a Network Load Balancer
+  + Lambda streaming (invoke mode) — a fundamentally different integration.
+
+The v1 goal is a clean serverless story: one codebase, two adapters, zero
+stateful origin servers. Raw TCP on either platform requires additional,
+non-serverless infrastructure (a long-running container on CF; NLB + Lambda
+streaming on AWS).
+
+Additionally, wss carries one IRC message per WebSocket text frame, which
+simplifies framing: the server does not need to implement a stateful
+byte-stream line buffer. The parser still tolerates `\r\n`-joined frames
+(multiple messages in one text frame) for robustness, but the common case is
+one-message-per-frame.
+
+## Decision
+
+v1 ships **wss-only**. No plaintext TCP listener, no `irc://` scheme, no
+port 6667/6697. Clients connect via `wss://server.tld/` and speak IRC inside
+WebSocket text frames.
+
+Rationale:
+1. Both target platforms support wss natively without additional
+   infrastructure.
+2. wss is TLS-terminated at the edge (CF) or at API Gateway (AWS) — the
+   Lambda/Worker never sees plaintext credentials.
+3. One-message-per-frame eliminates the need for a TCP-style line-framing
+   buffer in the core (though the parser tolerates joined frames).
+4. The serverless cost/ops model is clean: no long-running origin, no TCP
+   keepalive management.
+
+The `ConnectionActor` transport seam accepts WebSocket text frames directly.
+A `Transport` interface is not abstracted in v1 — the actor's
+`receiveTextFrame(text)` is the only entry point.
+
+## Consequences
+
+**Positive:**
+- Zero infrastructure beyond the serverless platform. No TCP listener, no
+  origin server, no port management.
+- TLS everywhere — no accidental plaintext exposure.
+- Simple framing: WebSocket text frames are message-delimited by definition.
+- Lower operational burden for v1.
+
+**Negative:**
+- RFC 1459/2812 clients that only speak raw TCP cannot connect. WeeChat and
+  HexChat support WebSocket; some older clients and bots do not.
+- The WebSocket overhead (HTTP upgrade, per-frame masking) adds ~2–10 bytes
+  per message vs. raw TCP. Negligible for IRC's small message sizes.
+- Some IRCv3 extensions assume a TCP transport (e.g. SASL EXTERNAL via client
+  certs over TLS passthrough). Without raw TCP, mTLS must be done at the edge
+  (CF API Shield, API Gateway custom domain), which changes the cert
+  verification surface.
+
+**Superseded:** Phase 7 (TICKET-052) reverses this decision for v1.x: a
+dual-transport model (wss stays the default; `irc+tls` on :6697 is added via
+Cloudflare Spectrum + Container origin, and AWS NLB + Lambda streaming). This
+ADR documents the original v1 rationale; the superseding ADR covers the
+reversal and per-platform TCP+TLS mapping.
+
+## References
+
+- PLAN §3 — "No plaintext TCP in v1 (wss only)"
+- PLAN §9 — "Framing: wss-only"
+- TICKET-052 — superseding ADR: dual wss + irc+tls
+- `packages/irc-server/src/actor.ts` — `receiveTextFrame(text)` (single
+  transport entry point in v1)

package/docs/ADR-006-sasl-mechanism-scope.md

@@ -0,0 +1,96 @@
+# ADR-006: SASL mechanism scope (PLAIN always; EXTERNAL mTLS-conditional)
+
+**Date:** 2025-01-20 (Phase 1) · revised 2025-07-27 (TICKET-079)
+**Status:** Superseded (TICKET-079)
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+IRCv3 SASL (`CAP sasl`) lets a client authenticate during registration,
+before the welcome sequence. The server advertises supported mechanisms in
+the `sasl` cap value (e.g. `sasl=PLAIN,EXTERNAL`). Each mechanism has
+different infrastructure requirements:
+
+- **PLAIN:** the client sends `AUTHENTICATE PLAIN`, then a base64 payload of
+  `\0username\0password`. The server verifies the credentials against an
+  `AccountStore`. No client certificates, no TLS-passthrough — works over
+  any transport, including wss with edge-terminated TLS.
+- **EXTERNAL:** the server authenticates the client based on an external
+  identity, typically a client certificate verified via mutual TLS (mTLS).
+  This requires the TLS handshake to present the client cert to the
+  application layer. On serverless platforms with edge-terminated TLS
+  (Cloudflare, API Gateway), the application does not see the raw client
+  cert — it must be configured at the edge (API Shield mTLS, custom-domain
+  mTLS trust store). That infrastructure does not exist in v1 (ADR-005:
+  wss-only, no raw TCP; mTLS passthrough is Phase 7, TICKET-054).
+
+## Decision
+
+The server ships **SASL PLAIN** as the always-available mechanism and
+**SASL EXTERNAL** as an mTLS-conditional mechanism:
+
+- When **no** `MtlsIdentityProvider` is bound to the connection (the default
+  for non-mTLS deployments), the `sasl` cap advertises `PLAIN` only and
+  `AUTHENTICATE EXTERNAL` returns `908 ERR_SASLMECHS` listing `PLAIN` as the
+  sole available mechanism.
+- When an `MtlsIdentityProvider` **is** bound (the operator configured mTLS
+  at the edge — CF API Shield mTLS or AWS custom-domain mTLS), the `sasl` cap
+  advertises `PLAIN,EXTERNAL` and `AUTHENTICATE EXTERNAL` proceeds through
+  the full handshake: the verified client-cert subject is resolved via the
+  provider and verified against the `AccountStore`.
+
+This means EXTERNAL advertisement and functionality are driven entirely by
+whether mTLS is configured — operators enable EXTERNAL by configuring edge
+mTLS, with no code change required. The `saslCapValue(hasMtls)` helper in
+`caps/capabilities.ts` and the `supportedMechs(ctx)` helper in
+`commands/sasl.ts` are the single sources of truth for the advertised value.
+
+`AccountStore` is a port in `irc-core` consumed by the SASL reducer. The
+`verify(mechanism, payload)` method is **synchronous** — adapters pre-load
+credentials at boot so the reducer stays pure (ADR-001). PLAIN verification
+decodes the base64 payload, extracts username + password, and matches
+against the store. EXTERNAL verification resolves the cert subject via the
+`MtlsIdentityProvider` and matches it against the store.
+
+## Consequences
+
+**Positive:**
+- PLAIN works end-to-end with no special infrastructure. The
+  `AccountStore` port abstracts the credential store; adapters seed it from
+  config (in-memory), DynamoDB (AWS), or a persistent backend (D1/DO for CF,
+  TICKET-093).
+- EXTERNAL is fully functional when mTLS is configured (TICKET-054) and
+  correctly unadvertised when it is not — clients never waste a round-trip
+  on a mechanism that cannot succeed.
+- The mTLS-conditional advertisement is driven by the `MtlsIdentityProvider`
+  binding, so operators enable EXTERNAL by configuring edge mTLS with no
+  code change.
+- The synchronous `AccountStore.verify()` keeps the reducer pure and
+  deterministic. Async credential lookups (DynamoDB) are resolved at cold
+  start or via pre-loading, not inside the reducer.
+
+**Negative:**
+- Deployments without mTLS (the common case) cannot offer EXTERNAL. This is
+  inherent — EXTERNAL requires client-certificate verification at the TLS
+  layer, which is only available via edge mTLS configuration.
+- PLAIN sends the password base64-encoded (not encrypted) inside the wss
+  frame. wss provides the TLS layer, so the password is encrypted in transit
+  — but PLAIN is still weaker than EXTERNAL (no mutual auth).
+- The synchronous `AccountStore` contract means the adapter must pre-load all
+  credentials. For deployments with many accounts, cold-start latency grows
+  linearly with account count. A lazy/async lookup variant is a documented
+  follow-up but would require an async-reducer or effect-based credential
+  query — a significant architecture change.
+
+## References
+
+- PLAN §3 — "sasl (mechanisms: PLAIN, EXTERNAL reserved for later with mTLS)"
+- PLAN §9 — SASL mechanism scope
+- TICKET-026 — SASL reducer implementation
+- TICKET-071 — AccountStore wiring into ConnectionActor
+- TICKET-072 — AWS DynamoDB AccountStore (scrypt hashing)
+- TICKET-079 — SASL EXTERNAL: implement or stop advertising (interim decision)
+- TICKET-054 — mTLS support (Phase 7, enables functional EXTERNAL)
+- `packages/irc-core/src/commands/sasl.ts` — `authenticateReducer`
+- `packages/irc-core/src/ports.ts` — `AccountStore` port

package/docs/ADR-007-deterministic-ports.md

@@ -0,0 +1,82 @@
+# ADR-007: Deterministic ports for time and ID generation
+
+**Date:** 2025-01-15 (Phase 1)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+IRC protocol behaviour is time-sensitive: idle/PING timers, WHOIS signon
+time, `server-time` tags (ISO-8601 timestamps on every message), SASL nonce
+generation, chathistory message IDs. A traditional ircd calls `Date.now()`
+and `crypto.randomUUID()` directly in handlers. This makes tests
+non-deterministic: the same input produces different output on every run,
+depending on when the test executed.
+
+Non-determinism is fatal for the parametrized contract suite (TICKET-032),
+which runs identical scenarios across in-memory, CF, and AWS runtimes. If a
+reducer embeds `Date.now()`, the expected `@time=` tag changes every
+millisecond and the assertion cannot be written.
+
+## Decision
+
+Time and ID generation are **injected ports**, not global calls:
+
+```ts
+interface Clock {
+  now(): number;  // epoch milliseconds
+}
+
+interface IdFactory {
+  nonce(): string;     // unique message ID for message-tags/chathistory
+  traceId(): string;   // per-request trace ID for observability
+}
+```
+
+Both are passed through `Ctx` to every reducer. Reducers read `ctx.clock.now()`
+and `ctx.ids.nonce()` — never `Date.now()` or `Math.random()`.
+
+Concrete implementations:
+- **`FakeClock`** (tests): returns a fixed value set at construction.
+  Deterministic: `new FakeClock(10_000)` always reports `now() === 10_000`.
+- **`SystemClock`** (production): wraps `Date.now()`.
+- **`SequentialIdFactory`** (tests): returns `id-0`, `id-1`, `id-2`, …
+  Deterministic: the same sequence of calls produces the same IDs.
+- **`RandomIdFactory`** (production): wraps `crypto.randomUUID()`.
+
+## Consequences
+
+**Positive:**
+- Reducer tests are fully deterministic. The same `(state, message, ctx)`
+  triple always produces the same `{ state, effects }`. No flaky tests.
+- The contract suite can assert exact wire output including `@time=` tags
+  and `msgid=` tags, because the fake clock and ID factory are pinned.
+- Time travel is trivial in tests: advance the `FakeClock` between messages
+  to test idle/PING logic, flood-control refill, and chathistory bounds.
+- The reducer purity contract (ADR-001) is enforceable: a reducer that calls
+  `Date.now()` is simply not using the injected port, and the test will fail
+  because the output is wrong.
+
+**Negative:**
+- Every call site that needs time or an ID must thread `ctx` — there is no
+  shortcut. This is a small constant cost per reducer.
+- The `Clock` and `IdFactory` must be consistent across the actor's lifetime.
+  The actor pins them at construction; switching mid-connection would
+  produce inconsistent timestamps. This is enforced by the actor's readonly
+  fields.
+- `Date.now()` resolution is milliseconds; sub-millisecond ordering is not
+  possible with this port. This has not been a problem for IRC (message
+  ordering is preserved by connection/channel authority serialization, not
+  by timestamp).
+
+## References
+
+- PLAN §9 — "Time/IDs: injected ports (Clock, IdFactory) for deterministic
+  tests"
+- PLAN §8 — "Determinism rules: inject a Clock and deterministic ID/nonce
+  ports. No real timers/random in reducers."
+- ADR-001 — pure reducers (why determinism matters)
+- `packages/irc-core/src/ports.ts` — `Clock`, `IdFactory`, `FakeClock`,
+  `SequentialIdFactory`, `SystemClock`, `RandomIdFactory`
+- `packages/irc-core/src/types.ts` — `Ctx.clock`, `Ctx.ids`

package/docs/ADR-008-monorepo-tooling.md

@@ -0,0 +1,60 @@
+# ADR-008: Monorepo and tooling stack
+
+**Date:** 2025-01-10 (Phase 0)
+**Status:** Accepted
+**Supersedes:** —
+**Superseded by:** —
+
+## Context
+
+ServerlessIRCd is a multi-package TypeScript project: a platform-agnostic
+core (`irc-core`), an orchestration layer (`irc-server`), a reference runtime
+(`in-memory-runtime`), two cloud adapters (`cf-adapter`, `aws-adapter`), and
+several apps (`local-cli`, `cf-worker`, `aws-stack`). The toolchain must
+support cross-package type checking, incremental builds, a unified test
+runner, and CI that enforces coverage gates per package.
+
+## Decision
+
+| Concern | Choice | Rationale |
+|---|---|---|
+| Package manager | **pnpm** (workspaces) | Fast, disk-efficient, first-class monorepo support |
+| Build orchestration | **turbo** (caching) | Incremental builds, remote cache, task dependency graph |
+| TypeScript | Project references + `tsconfig.base.json` | Strict mode, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess` |
+| Test runner | **vitest** | ESM-native, fast, integrates with Workers (`vitest-pool-workers`), built-in coverage |
+| Coverage | v8 provider, gate ≥90% (100% on `irc-core`) | Enforced in CI (`.github/workflows/ci.yml`) |
+| Lint/format | **Biome** | Single tool (replaces ESLint + Prettier), fast, zero config drift |
+| CF bundler | **wrangler** (esbuild internally) | Native Workers toolchain |
+| AWS bundler | **esbuild** (Lambda bundles) + **CDK v2** (infra) | Tree-shaking, fast cold starts |
+| Runtime target | Node 20 (Lambda) + latest Workers runtime; ES2022+ | Aligns with platform-supported runtimes |
+
+## Consequences
+
+**Positive:**
+- pnpm workspaces + turbo give fast local dev: only changed packages rebuild;
+  tests run incrementally.
+- vitest's ESM-native design avoids the CJS/ESM interop pain that plagues
+  Jest-based monorepos. The same test files run under `vitest-pool-workers`
+  (real `workerd`) for CF adapter tests.
+- Biome eliminates the ESLint/Prettier config drift problem — one tool, one
+  config, one command (`biome check`).
+- TypeScript project references enforce package boundaries at compile time:
+  `irc-core` cannot accidentally import from `cf-adapter`.
+
+**Negative:**
+- pnpm's strict node-linker can surprise contributors used to npm/yarn's
+  hoisting. `node_modules` is per-package; global scripts need
+  `pnpm --filter`.
+- turbo's caching requires consistent environment hashing; a CI cache miss
+  (e.g. different Node minor version) degrades to a full rebuild silently.
+- Biome is newer than ESLint and lacks some ecosystem plugins. Custom rules
+  (e.g. "no ticket IDs in source files") are enforced via convention
+  (`AGENTS.md`) rather than a Biome plugin.
+
+## References
+
+- PLAN §9 — "Monorepo: pnpm + TypeScript project references; turbo for
+  caching"
+- `pnpm-workspace.yaml`, `turbo.json`, `tsconfig.base.json`, `biome.json`
+- `.github/workflows/ci.yml` — coverage gates and CI pipeline
+- `AGENTS.md` — code style conventions

package/docs/ADR-009-dual-transport-wss-and-irc-tls.md

@@ -0,0 +1,138 @@
+# ADR-009: Dual transport — wss (default) + irc+tls on :6697
+
+**Date:** 2026-07-26 (Phase 7)
+**Status:** Accepted
+**Supersedes:** ADR-005 (wss-only transport in v1)
+**Superseded by:** —
+
+## Context
+
+ADR-005 chose **wss-only** for v1. That decision rested on four points, all
+still accurate as facts about the serverless substrates:
+
+1. Both target platforms (CF Workers, AWS API Gateway WebSocket) support wss
+   natively with zero additional infrastructure; neither can accept raw TCP
+   from its request-response compute (Workers is request-response; API Gateway
+   is WebSocket-only).
+2. wss is TLS-terminated at the edge (CF) or at API Gateway (AWS), so the
+   Lambda/Worker never sees plaintext credentials.
+3. One IRC message per WebSocket text frame eliminates the need for a
+   stateful byte-stream line buffer in the core (the parser already tolerates
+   `\r\n`-joined frames for robustness).
+4. The serverless cost/ops story stays clean: no long-running origin, no TCP
+   keepalive management, one codebase + two adapters.
+
+What changed the decision is **demand, not capability**:
+
+- **RFC 1459/2812 compliance.** The target modern clients (WeeChat, HexChat,
+  IRCCcd, TheLounge) mostly support wss, but there is a long tail of older
+  clients, bots, bridges, and monitoring tools that only speak `irc+tls`
+  (raw TCP + TLS on :6697). Supporting them was a non-goal for the initial v1
+  cut; the gap now matters for the compatibility-sweep deliverable.
+- **SASL EXTERNAL (mTLS).** `AUTHENTICATE EXTERNAL` needs the client
+  certificate to reach the application layer (ADR-006). With wss and
+  edge-terminated TLS, the cert is consumed at the edge and the app only gets
+  a verified subject via platform config (CF API Shield mTLS, API Gateway
+  custom-domain mTLS — both TICKET-054). A real `irc+tls` path gives a more
+  conventional mTLS surface that matches client expectations.
+- **Marginal cost is small.** The core is transport-agnostic by design: pure
+  reducers + a `ConnectionActor` that already accepts `\r\n`-joined frames.
+  Adding a second transport is a **second per-platform entry-point adapter**,
+  not a re-architecture. The generalized TCP byte-stream transport seam is
+  TICKET-053; the per-platform adapters are TICKET-055 (CF) and TICKET-056
+  (AWS).
+
+## Decision
+
+v1.x adopts a **dual-transport** model:
+
+- **wss stays the serverless default.** `wss://server.tld/` with one IRC
+  message per WebSocket text frame remains the primary path. It needs zero
+  extra infrastructure on either platform and keeps the clean serverless
+  story for the common case.
+- **`irc+tls` on :6697 is added** as a second, per-platform adapter for
+  RFC-compliant clients. TLS is mandatory; **plaintext TCP on :6667 stays
+  unsupported.** The entry point differs per platform because neither
+  serverless compute can accept raw TCP directly:
+
+  | Platform | Edge (TLS termination)              | Origin / compute                              |
+  |----------|-------------------------------------|-----------------------------------------------|
+  | CF       | Cloudflare Spectrum (Enterprise)     | Cloudflare Container running TCP byte-stream  |
+  |          |                                     | `ConnectionActor` over a persistent runtime  |
+  | AWS      | Network Load Balancer (`tls` listener) | Lambda **streaming** function (target);     |
+  |          |                                     | connection ID derived from NLB flow metadata |
+
+  Spectrum terminates TLS at the edge and forwards plaintext TCP to the
+  container origin; NLB terminates TLS and invokes a Lambda streaming
+  function as target. Both reuse `AwsRuntime`/the CF runtime storage layer
+  for connection/channel/nick state.
+
+The **pure reducer core and `ConnectionActor` are shared** across both
+transports and both platforms. Only two things differ on the new path:
+
+1. The **transport seam** (TICKET-053): `ConnectionActor` accepts either a
+   `WsTextFrameTransport` (one message per frame — current behavior) or a
+   `TcpByteStreamTransport` (stateful `\r\n` framing across chunks with
+   partial-line buffering). Parser → reducer → dispatch is unchanged.
+2. The **entry-point adapter** (TICKET-055 / TICKET-056): Spectrum+Container
+   on CF, NLB+Lambda streaming on AWS.
+
+mTLS (TICKET-054) is done at the edge on the wss path (CF API Shield mTLS /
+API Gateway custom-domain mTLS) and via the TLS handshake on the TCP path
+(Spectrum cert verification / NLB ACM cert + optional client-cert
+verification).
+
+## Consequences
+
+**Positive:**
+- RFC 1459/2812-compliant clients, bots, and bridges connect natively without
+  a `tcp-ws-forwarder` bridge. This unblocks the compatibility-sweep
+  deliverable for the long tail of TCP-only clients.
+- A conventional mTLS surface opens for SASL `EXTERNAL` (TICKET-054): the
+  client cert reaches the application via the TLS handshake on the TCP path,
+  matching standard IRC client expectations, in addition to the edge-mTLS
+  path on wss.
+- Core reuse: the pure reducers, `IrcRuntime` port, and `ConnectionActor`
+  are shared verbatim. The transport seam (TICKET-053) is the only new
+  abstraction in the core; everything else is per-platform glue.
+- The wss default is untouched — deployments that do not need raw TCP pay no
+  infra cost and keep the clean serverless story.
+
+**Negative:**
+- **CF breaks the pure-serverless story on the TCP path.** Spectrum is an
+  Enterprise-tier feature, and the origin is a stateful Cloudflare Container
+  (or external compute), not a Worker. Connection state must survive origin
+  reconnects via the runtime's persistence layer — a new operational surface
+  that the wss path (Durable Objects) does not have.
+- **AWS NLB + Lambda streaming has hard limits:** Lambda streaming invoke
+  idle timeout and maximum connection/duration caps. Long-idle IRC clients
+  can be dropped; reconnect/PING behavior must tolerate this (same class of
+  risk as the APIGW 2h WS cap, PLAN §10).
+- **Extra per-platform adapter surface.** Two entry-point adapters
+  (TICKET-055, TICKET-056) and a new transport contract dimension
+  (TICKET-057) are added to the test matrix. Cross-adapter drift is now a
+  transport × runtime matrix, mitigated by the parametrized contract suite.
+- **Double deploy/ops paths per platform.** Each platform now ships a wss
+  stack and a TCP+TLS stack with different infra (DO vs Container; APIGW vs
+  NLB). Deploy docs, cost monitoring, and incident runbooks must cover both
+  (TICKET-058).
+
+## References
+
+- ADR-005 — wss-only transport in v1 (**superseded** by this ADR)
+- ADR-006 — SASL mechanism scope (PLAIN only; EXTERNAL deferred to Phase 7;
+  this ADR unblocks the mTLS path for EXTERNAL)
+- PLAN §3 — Protocol scope (connection framing)
+- PLAN §9 — Key technical decisions (framing)
+- TICKET-052 — this ADR; revises the transport decision
+- TICKET-053 — generalize `ConnectionActor` transport seam (TCP byte-stream
+  framing)
+- TICKET-054 — mTLS support (edge config + `AccountStore` plumbing; enables
+  functional SASL EXTERNAL)
+- TICKET-055 — CF TCP+TLS adapter via Cloudflare Spectrum + Container origin
+- TICKET-056 — AWS TCP+TLS adapter via Network Load Balancer (TLS) + Lambda
+  streaming
+- TICKET-057 — extend integration contract suite over transport
+  (wss × TCP+TLS)
+- TICKET-058 — docs: `Cloudflare-TCP-Deployment.md` and `AWS-TCP-Deployment.md`
+  (TCP+TLS variants)