serverless-ircd 0.3.0 → 0.4.0

package/packages/irc-test-support/tests/in-memory-scenarios.test.ts

@@ -1,19 +1,33 @@
 /**
- * Parametrized IRC scenarios — 032.
+ * Parametrized IRC scenarios — 032 + 057.
  *
  * The scenario bodies live in `src/scenarios.ts` (now re-exported as
  * `runIrcScenarios`) so adapter packages can register their own
  * {@link IrcHarnessFactory} against the exact same suite under their
  * native vitest configuration (CF runs in `workerd`, AWS runs in node
- * with dynamodb-local, etc.). This file is the in-memory entry point —
- * it registers only {@link inMemoryHarnessFactory}.
+ * with dynamodb-local, etc.). This file is the in-memory entry point.
  *
- * Adding a runtime to the in-memory suite = appending one entry to the
- * `FACTORIES` array (acceptance criterion: "adding a new runtime
- * requires only registering a factory").
+ * The transport dimension extends the matrix: every scenario runs
+ * against (runtime × transport). The in-memory runtime
+ * registers both transports — `inMemoryWsHarnessFactory` (WebSocket
+ * text-frame framing) and `inMemoryTcpHarnessFactory` (raw TCP+TLS
+ * byte-stream framing) — proving the same scenario suite is green across
+ * both transports on the reference runtime. CF and AWS append their own
+ * factories (per transport) to their package suites.
+ *
+ * Adding a runtime OR a transport to the in-memory suite = appending one
+ * entry to the `FACTORIES` array (acceptance criterion: "adding a new
+ * transport requires only registering a factory").
  */
 
-import { inMemoryHarnessFactory, runIrcScenarios } from '../src/index.js';
+import {
+  inMemoryTcpHarnessFactory,
+  inMemoryWsHarnessFactory,
+  runIrcScenarios,
+} from '../src/index.js';
 
-/** The runtime matrix. Adding a runtime = appending one entry here. */
-runIrcScenarios([inMemoryHarnessFactory]);
+/**
+ * The (runtime × transport) matrix. Adding a runtime or transport =
+ * appending one entry here.
+ */
+runIrcScenarios([inMemoryWsHarnessFactory, inMemoryTcpHarnessFactory]);

package/pnpm-workspace.yaml

@@ -1,5 +1,13 @@
-linkedWorkspacePackages: true
 packages:
   - "packages/*"
   - "apps/*"
   - "tools/*"
+linkWorkspacePackages: true
+allowBuilds:
+  '@biomejs/biome': true
+  cpu-features: true
+  esbuild: true
+  protobufjs: true
+  sharp: true
+  ssh2: true
+  workerd: true

package/tools/ci-hardening/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/ci-hardening",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
   "license": "BSD-3-Clause",

package/tools/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/tools/seed-aws-accounts.ts

@@ -17,12 +17,9 @@
  * Re-running with the same username overwrites the prior row.
  */
 
-import { parseArgs } from 'node:util';
 import { readFileSync } from 'node:fs';
-import {
-  createDynamoDocumentClient,
-  putAccountCredential,
-} from '@serverless-ircd/aws-adapter';
+import { parseArgs } from 'node:util';
+import { createDynamoDocumentClient, putAccountCredential } from '@serverless-ircd/aws-adapter';
 
 const { values } = parseArgs({
   options: {
@@ -35,7 +32,9 @@ const { values } = parseArgs({
 });
 
 if (values.table === undefined) {
-  console.error('Usage: seed-aws-accounts --table <TableName> [--endpoint <url>] [--accounts user:pass ...] [--file <path>]');
+  console.error(
+    'Usage: seed-aws-accounts --table <TableName> [--endpoint <url>] [--accounts user:pass ...] [--file <path>]',
+  );
   process.exit(1);
 }
 

package/tools/seed-cf-accounts.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Seed SASL PLAIN accounts into a Cloudflare D1 `accounts` table.
+ *
+ * Usage:
+ *   node --import tsx tools/seed-cf-accounts.ts \
+ *     --database serverless-ircd-accounts-staging \
+ *     --env staging \
+ *     --remote \
+ *     --accounts alice:s3cret bob:password2
+ *
+ * Or read from a file (newline-delimited `username:password`):
+ *   node --import tsx tools/seed-cf-accounts.ts \
+ *     --database serverless-ircd-accounts-staging \
+ *     --env staging \
+ *     --remote \
+ *     --file accounts.txt
+ *
+ * The script hashes each password with scrypt (never writes plaintext) and
+ * executes the resulting `INSERT OR REPLACE` via `wrangler d1 execute`.
+ * Re-running with the same username overwrites the prior row. The `accounts`
+ * table is created (IF NOT EXISTS) on the first run.
+ *
+ * Flags:
+ *   --database   D1 database name (as declared in wrangler.toml). Required.
+ *   --env        Wrangler environment (e.g. `staging`). Optional.
+ *   --remote     Target the remote D1 (default: local preview).
+ *   --local      Target local D1 (explicit; default).
+ *   --accounts   One or more `username:password` pairs.
+ *   --file       Path to a newline-delimited `username:password` file.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { CREATE_ACCOUNTS_TABLE_SQL, buildAccountPutStatement } from '@serverless-ircd/cf-adapter';
+
+const { values } = parseArgs({
+  options: {
+    database: { type: 'string' },
+    env: { type: 'string', default: undefined },
+    remote: { type: 'boolean', default: false },
+    local: { type: 'boolean', default: false },
+    accounts: { type: 'string', multiple: true, default: [] },
+    file: { type: 'string', default: undefined },
+  },
+});
+
+if (values.database === undefined) {
+  console.error(
+    'Usage: seed-cf-accounts --database <d1-name> [--env staging] [--remote] [--accounts user:pass ...] [--file <path>]',
+  );
+  process.exit(1);
+}
+
+const pairs: Array<{ username: string; password: string }> = [];
+
+for (const pair of values.accounts) {
+  const sep = pair.indexOf(':');
+  if (sep <= 0) {
+    console.error(`Skipping malformed entry (no colon): ${pair}`);
+    continue;
+  }
+  pairs.push({ username: pair.slice(0, sep), password: pair.slice(sep + 1) });
+}
+
+if (values.file !== undefined) {
+  const content = readFileSync(values.file, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    const sep = trimmed.indexOf(':');
+    if (sep <= 0) continue;
+    pairs.push({ username: trimmed.slice(0, sep), password: trimmed.slice(sep + 1) });
+  }
+}
+
+if (pairs.length === 0) {
+  console.error('No accounts to seed. Use --accounts or --file.');
+  process.exit(1);
+}
+
+/** Runs `wrangler d1 execute` with the supplied SQL command. */
+function runD1Execute(sql: string): void {
+  const args = ['d1', 'execute', values.database as string, '--command', sql];
+  if (values.env !== undefined) {
+    args.push('--env', values.env);
+  }
+  if (values.remote) {
+    args.push('--remote');
+  }
+  execFileSync('npx', ['wrangler', ...args], { stdio: 'inherit' });
+}
+
+// Ensure the table exists (idempotent).
+runD1Execute(CREATE_ACCOUNTS_TABLE_SQL);
+
+for (const { username, password } of pairs) {
+  const { entry, sql } = buildAccountPutStatement(username, password);
+  runD1Execute(sql);
+  console.log(`Seeded ${username} (algorithm=${entry.algorithm})`);
+}
+
+console.log(`Done: ${pairs.length} account(s) written to D1 database ${values.database}.`);

package/tools/tcp-ws-forwarder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/tcp-ws-forwarder",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": true,
   "description": "Local TCP to ws/wss forwarder so standard IRC clients can reach the WebSocket-only ServerlessIRCd transport",
   "license": "BSD-3-Clause",

package/docs/ADR-001-pure-reducers-and-effect-system.md

@@ -1,74 +0,0 @@
-# ADR-001: Pure reducers and the effect system
-
-**Date:** 2025-01-15 (Phase 1)
-**Status:** Accepted
-**Supersedes:** —
-**Superseded by:** —
-
-## Context
-
-Every IRC daemon must decide where side effects happen. A traditional ircd
-threads mutable state and IO through command handlers — the handler reads a
-channel roster, sends messages, mutates a user record, and returns. That makes
-handlers hard to unit-test (they require a live socket, a real timer, a
-populated data store) and hard to reason about (the handler's observable
-behaviour is inseparable from its IO).
-
-ServerlessIRCd targets two cloud adapters (Cloudflare Workers, AWS Lambda)
-that share one protocol core. If the core performed IO directly, each adapter
-would need its own mock surface for every core test — or worse, the core
-would grow adapter-specific code paths.
-
-## Decision
-
-Every command handler is a **pure function** with the signature:
-
-```ts
-type Reducer<S> = (state: S, msg: IrcMessage, ctx: Ctx) => { state: S; effects: Effect[] };
-```
-
-- **No IO in the reducer.** No `await`, no `fetch`, no `setTimeout`, no
-  `Date.now()`, no `Math.random()`. The reducer reads `ctx.clock.now()` and
-  `ctx.ids.nonce()` instead (see ADR-007).
-- **Side effects are values.** The reducer returns an `Effect[]` — a
-  discriminated union (`Send`, `Broadcast`, `Disconnect`, `ReserveNick`,
-  `ChangeNick`, `ReleaseNick`, `ApplyChannelDelta`, `SendToNick`, …). Each
-  effect tag maps one-to-one to an `IrcRuntime` method.
-- **A single `dispatch(effects, runtime)` function** in `irc-server`
-  interprets the effects against the bound runtime. Only `dispatch` awaits.
-- **Reducer purity is enforced by convention and testability, not by a
-  sandbox.** The type system carries the contract; the 100% coverage gate on
-  `irc-core` verifies it empirically.
-
-## Consequences
-
-**Positive:**
-- Every reducer is a trivial unit test: arrange state, apply message, assert
-  `state` and `effects`. No mocks, no fakes beyond an injected `Clock` and
-  `IdFactory`.
-- The same reducer code runs unchanged on in-memory, CF, and AWS runtimes.
-  Adapter work is "wire the runtime", not "rewrite the handler".
-- Reducer behaviour is deterministic and reproducible — critical for the
-  parametrized contract suite (TICKET-032) that runs identical scenarios
-  across all three runtimes.
-- Mutation testing (Stryker, TICKET-048) is meaningful because reducers have
-  no hidden IO to mask a mutation's effect.
-
-**Negative:**
-- The `Effect` union grows with every new side-effect type. Adding a novel
-  effect (e.g. `QueryHistory` for chathistory) requires touching `effects.ts`,
-  `dispatch.ts`, and every runtime implementation. This is by design (the
-  type system makes missing-runtime-support a compile error) but adds
-  ceremony.
-- Reducers cannot directly observe the result of a side effect they emit
-  (e.g. "did the broadcast actually reach anyone?"). Cross-effect
-  coordination is deferred to the actor layer, which can pre-fetch runtime
-  state before invoking the reducer.
-
-## References
-
-- PLAN §2.1 — "The key idea: pure reducers + location-of-authority"
-- PLAN §2.2 — `IrcRuntime` port
-- `packages/irc-core/src/effects.ts` — `Effect` union
-- `packages/irc-core/src/types.ts` — `Reducer<S>` signature
-- `packages/irc-server/src/dispatch.ts` — `dispatch(effects, runtime)`

package/docs/ADR-002-location-of-authority.md

@@ -1,82 +0,0 @@
-# ADR-002: Location-of-authority state split
-
-**Date:** 2025-01-15 (Phase 1)
-**Status:** Accepted
-**Supersedes:** —
-**Superseded by:** —
-
-## Context
-
-An IRC server manages several kinds of state: connection records (nick, caps,
-away status), channel rosters (who is in `#foo`, with what prefix), channel
-metadata (topic, modes, ban lists), and the nick registry (nick → connection
-map). In a single-process ircd all of this lives in one address space, so
-read-modify-write races are handled with locks or a single event loop.
-
-ServerlessIRCd runs on stateless-per-request compute (Lambda) or
-per-entity-isolated compute (Durable Objects). There is no global lock. If
-two connections race to JOIN the same channel, or two clients race to claim
-the same nick, the outcome must still be correct. Traditional locking is
-impossible across instances.
-
-## Decision
-
-Each piece of state has **exactly one authority** — the single entity that
-owns the canonical copy and serializes all mutations to it. Reducers are
-routed to the authority that owns the state they mutate:
-
-| Command family | Authority | Primary state |
-|---|---|---|
-| Registration (NICK/USER/PASS) | Connection entity | `ConnectionState` |
-| PING/PONG, QUIT, AWAY, user MODE | Connection entity | `ConnectionState` |
-| JOIN/PART/channel MODE/TOPIC/KICK/INVITE | Channel entity | `ChannelState` + roster |
-| PRIVMSG/NOTICE to channel | Channel entity | Fanout (reads roster) |
-| PRIVMSG/NOTICE to user | Sender Connection | Nick → Connection route |
-| Nick reservation | Registry entity | Nick → Connection map |
-
-Cross-authority coordination is done via **effects**, not direct mutation.
-When a connection accepts a JOIN, the connection-authority reducer emits an
-`ApplyChannelDelta` effect that the channel authority consumes. The channel
-authority is the sole writer of its roster; the connection never touches it
-directly.
-
-Platform mapping:
-- **Cloudflare:** each authority is a Durable Object (`ConnectionDO`,
-  `ChannelDO`, `RegistryDO`). DO single-threaded serial execution gives the
-  uniqueness invariant for free — two concurrent requests to the same DO are
-  queued, not racing.
-- **AWS:** each authority is a DynamoDB table with conditional writes
-  (`ConditionExpression`) or `TransactWriteItems` for multi-row atomicity
-  (e.g. JOIN spans `Connections` and `ChannelMembers`).
-
-## Consequences
-
-**Positive:**
-- Races are structurally impossible, not defended against. Two clients
-  claiming the same nick both route to the same `RegistryDO` shard (or the
-  same `Nicks` row with a conditional PutItem) — exactly one wins.
-- The reducer signature stays uniform (`Reducer<S>`) regardless of which
-  authority it runs in. The actor layer routes; the reducer does not know or
-  care whether it is running in a DO or a Lambda.
-- Each authority can be tested in isolation. The channel reducer tests
-  arrange a `ChannelState` and assert effects; they never need a live
-  connection registry.
-
-**Negative:**
-- Cross-authority coordination requires a round-trip (DO `stub()` call on CF;
-  extra DynamoDB write on AWS). A JOIN that updates both the connection's
-  joined-list and the channel roster is two writes, not one.
-- The actor layer must pre-fetch authoritative state before invoking a
-  reducer (e.g. WHOIS needs the target connection's state from a different
-  authority). This adds a `prefetchChannelState` step in the actor pipeline.
-- Listing all channels (LIST) or resolving every member of a channel (WHO)
-  requires aggregating across authorities — there is no global view. The CF
-  adapter needs a channel registry (TICKET-073); the AWS adapter does a
-  DynamoDB scan.
-
-## References
-
-- PLAN §2.1 — location-of-authority table
-- PLAN §4 — state model & authoritative ownership
-- ADR-001 — pure reducers (how effects flow between authorities)
-- `packages/irc-server/src/actor.ts` — `route()` switch (authority routing)

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

@@ -1,93 +0,0 @@
-# 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.
-
-## 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

@@ -1,96 +0,0 @@
-# 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

@@ -1,83 +0,0 @@
-# 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)