serverless-ircd 0.3.0 → 0.5.0

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)

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

@@ -1,86 +0,0 @@
-# ADR-006: SASL mechanism scope (PLAIN only, EXTERNAL deferred)
-
-**Date:** 2025-01-20 (Phase 1)
-**Status:** Accepted (EXTERNAL re-evaluation tracked in 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
-
-v1 ships **SASL PLAIN only** as a functional mechanism. EXTERNAL is
-**recognized but stubbed**: the reducer accepts `AUTHENTICATE EXTERNAL`,
-acknowledges the mechanism, and immediately returns `904 ERR_SASLFAIL` with a
-documented code comment cross-referencing TICKET-054 (mTLS) and TICKET-079
-(decision: implement or stop advertising).
-
-The `sasl` cap advertises `PLAIN,EXTERNAL` (both names listed) so clients
-that probe mechanism availability see EXTERNAL as nominally supported. The
-actual `904` on EXTERNAL attempt is the functional gate. TICKET-079 is the
-follow-up that decides whether to implement EXTERNAL against a pluggable
-`MtlsIdentityProvider` or stop advertising it until mTLS lands.
-
-`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.
-
-## Consequences
-
-**Positive:**
-- PLAIN works end-to-end in v1 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 forward-compatible: advertising it now means clients that
-  prefer EXTERNAL will attempt it; once mTLS lands (Phase 7), the same
-  `AUTHENTICATE EXTERNAL` flow succeeds without a client-side 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:**
-- EXTERNAL is advertised but non-functional in v1 — a client that negotiates
-  `sasl` and sends `AUTHENTICATE EXTERNAL` gets `904` with no actionable
-  error message. This is a poor UX until TICKET-079 resolves (stop-advertising
-  is the recommended interim per the ticket).
-- 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

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

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