serverless-ircd 0.5.0 → 0.7.0

package/docs/PlanExtensions.md

@@ -0,0 +1,812 @@
+# ServerlessIRCd — Extensions Plan (post-v1)
+
+Plan for the IRC features that v1 deliberately left out: the remaining
+**IRCv3 client-server extensions** and **IRC services** (NickServ /
+ChanServ / OperServ / HostServ / MemoServ). Each section is scoped,
+mapped onto the existing hexagonal architecture, and proposed as
+tickets for `tickets.md` / `progress.md` once ratified.
+
+> **Status:** planning. Nothing here has landed. Ticket numbers below
+> start at **TICKET-110** (next free id per `todo.md`). When this plan
+> is ratified the tickets get appended to `tickets.md` / `progress.md`
+> under two new phase headings (**Phase 12 — IRCv3 extensions**,
+> **Phase 13 — IRC services**) and the corresponding sections here are
+> superseded.
+
+---
+
+## 1. Goals & non-goals
+
+**Goals**
+- Close the gap between the v1 cap set and what mainstream clients
+  (IRCCloud, TheLounge, Textual, gamja) actually negotiate today.
+- Add the IRCv3 features that compose with work already shipped:
+  `account-tag` is meaningless without `account-notify`; `message-tags`
+  without `msgid` / `labeled-response` leaves clients correlating by
+  content.
+- Provide a services story (NickServ/ChanServ) that fits the
+  pure-reducer + location-of-authority architecture instead of bolting
+  on a pseudo-server.
+- Stay serverless-native: every new persistence need is behind a port
+  (`MessageStore`, `AccountStore`, `ServicesStore`) so the same core
+  runs on Cloudflare and AWS unchanged.
+
+**Non-goals (this plan)**
+- **Server-to-server linking** (TS6, IRCv3 S2S, SALR). Remains a
+  non-goal, same as v1 (`PLAN.md` §1). A `ServerLink` seam is the
+  documented design-for-later; no S2S work is proposed here.
+- **Atheme / Anope compatibility.** Services are integrated into the
+  daemon, not implemented as a separate pseudo-server speaking a link
+  protocol. See §6 architecture decision.
+- **Full services suite parity.** BotServ and StatServ are explicitly
+  out of scope; OperServ ships a minimal AKILL/JUPE set only.
+- **Plaintext :6667 support.** Still TLS-only (ADR-009).
+
+---
+
+## 2. Current cap set (baseline)
+
+`packages/irc-core/src/caps/capabilities.ts:28` advertises:
+
+```
+account-tag, away-notify, batch, chghost, draft/chathistory,
+echo-message, extended-join, invite-notify, message-tags,
+multi-prefix, safelist, sasl=PLAIN[,EXTERNAL], server-time
+```
+
+What follows fills in the missing pieces, grouped by spec maturity.
+
+---
+
+## 3. Missing IRCv3 extensions
+
+### 3.1 Stable spec extensions (high-value, low-risk)
+
+| Cap | Spec | What it adds | Effort | Depends on |
+|-----|------|--------------|--------|------------|
+| `account-notify` | [ircv3.net/specs/extensions/account-notify-3.2](https://ircv3.net/specs/extensions/account-notify-3.2.html) | Push `ACCOUNT` messages to peers in shared channels on login/logout (complements `account-tag`, `extended-join`) | S (2 pts) | SASL AccountStore wiring (TICKET-071 ✅) |
+| `msgid` | [ircv3.net/specs/extensions/message-ids](https://ircv3.net/specs/extensions/message-ids.html) | Stable per-message id as a `msgid` tag on every PRIVMSG/NOTICE to cap-enabled peers (live fanout), sharing the single `IdFactory.nonce()` value also recorded for chathistory replay; needed for `draft/read-marker`, replies, dedup | S (2 pts) | `message-tags` ✅, `IdFactory` ✅ |
+| `standard-replies` | [ircv3.net/specs/extensions/standard-replies-3.0](https://ircv3.net/specs/extensions/standard-replies-3.0.html) | Replace a class of bare numerics with `FAIL`/`WARN`/`NOTE` for cap-enabled clients; better client UX | M (3 pts) | none |
+| `monitor` | [ircv3.net/specs/extensions/monitor-3.2](https://ircv3.net/specs/extensions/monitor-3.2.html) | `MONITOR` command, modern replacement for `ISON`; per-connection watchlist + `730`/`731`/`732`/`733`/`734` numerics | M (5 pts) | Registry lookups ✅ |
+| `labeled-response` | [ircv3.net/specs/extensions/labeled-response-3.2](https://ircv3.net/specs/extensions/labeled-response-3.2.html) | Client tags a request with `label`; server wraps the reply in a `BATCH` carrying that label. Composes with `batch` ✅ | L (8 pts) | `batch` ✅, `message-tags` ✅ |
+| `sts` | [ircv3.net/specs/extensions/sts](https://ircv3.net/specs/extensions/sts.html) | Strict Transport Security: advertise a TLS+port policy to upgrade plaintext/WebSocket clients. Relevant once raw TCP `:6697` is exposed (it is, per Phase 7 ✅) | S (2 pts) | dual transport ✅ |
+
+**Notes:**
+- `account-notify` is the cheapest win and unblocks the
+  `account-tag`/`extended-join`/`account-notify` triple that modern
+  clients render fully.
+- `msgid` is mostly there: the chathistory work (TICKET-063) already
+  produces stable msgids via `IdFactory.nonce()`. This ticket is the
+  cap advertisement + emitting the tag on every PRIVMSG/NOTICE/TAGMSG,
+  not just recorded ones.
+- `labeled-response` is the largest item because the request→reply
+  correlation touches every reducer that emits a client-facing reply;
+  the `BATCH` wrapper already exists (TICKET-025), so the work is in
+  plumbing a per-request label through `ctx`.
+- `sts` is config-driven only (no protocol state); the value is
+  advertising the right TLS port for the deployed adapter.
+
+### 3.2 Draft / spec-pending extensions
+
+| Cap | Spec | What it adds | Effort | Depends on |
+|-----|------|--------------|--------|------------|
+| `draft/pre-away` | [ircv3 draft](https://github.com/ircv3/ircv3-specifications/pull/415) | Persist away status + message across reconnects; cross-device away sync. Noted out-of-scope in TICKET-063. | M (3 pts) | `AccountStore` ✅, services `UserStore` (§6) |
+| `draft/read-marker` | [ircv3 draft](https://github.com/ircv3/ircv3-specifications/pull/416) | Per-`(user, channel)` last-read marker, propagated via `+draft/read-marker` tag. The chathistory plumbing (TICKET-063) already keeps the marker locally; this ticket persists it across connections and shares it. | M (5 pts) | chathistory ✅, services `UserStore` |
+| `draft/multiline` | [ircv3 draft](https://ircv3.net/specs/extensions/multiline.html) | `BATCH +id draft/multiline :target` for multi-line messages up to a byte budget. Clients (TheLounge, gamja) render as joined blocks. | M (5 pts) | `batch` ✅, `message-tags` ✅ |
+| `draft/typing` | [ircv3 client-behavior/typing](https://ircv3.net/specs/client-behavior/typing-notification.html) | `TAGMSG +draft/typing=active|paused|done` to channel members (excluding sender unless `echo-message`). Client UX only; no server state. | S (2 pts) | `message-tags` ✅, `TAGMSG` ✅ |
+
+**Notes:**
+- The `draft/` prefix caps stay namespaced until the spec stabilizes,
+  matching the existing `draft/chathistory` precedent.
+- `draft/typing` is a near-trivial follow-on from TAGMSG (TICKET-076 ✅):
+  just whitelist the `+draft/typing=…` client tag and broadcast.
+
+### 3.3 Already-shipped caps blocked on adapter wiring
+
+Worth calling out explicitly so they are not re-implemented by mistake:
+
+| Cap | Status |
+|-----|--------|
+| `account-tag` | Reducer emits; only meaningful once `AccountStore` is bound per adapter (TICKET-071 ✅). |
+| `extended-join` | Reducer emits the `account realname` form; same dependency as above. |
+| `draft/chathistory` | Reducer + in-memory store shipped (TICKET-063 ✅); adapter `MessageStore` wiring landed in TICKET-070 ✅. Persistent CF (D1/DO) and AWS (DynamoDB) stores are the next step. |
+| `msgid` | Standalone cap advertised and emitted on the live PRIVMSG/NOTICE fanout (TICKET-111 ✅). A single `IdFactory.nonce()` is shared between the live `@msgid=<id>` tag and the chathistory record so the two match for the same message. |
+
+---
+
+## 4. Missing ISUPPORT tokens
+
+`packages/irc-core/src/commands/isupport.ts` should grow:
+
+- `MONITOR=<n>` — maximum entries per connection (TICKET for `monitor`).
+- `ACCOUNTEXTBAN` / `EXTBAN=~,acc` — extended ban by account (services
+  `+r` work).
+- `STATUSMSG=@+` — prefixes that map to status-msg delivery (ships with
+  any `STATUSMSG`-aware PRIVMSG change).
+- `TYPING` — draft advertisement when `draft/typing` lands.
+
+---
+
+## 5. Channel + user modes that arrive with services
+
+The v1 mode set (`o v b i k l t n m s p` channel, `i o w s` user) gains:
+
+| Mode | Type | Meaning | Source |
+|------|------|---------|--------|
+| `r` (channel) | A | Channel is registered with ChanServ | services |
+| `R` (channel) | B | Block join/message from unregistered nicks | services |
+| `M` (channel) | B | Mod speak requires registered nick (vs. `+m` = op) | services |
+| `c` (channel) | B | Block ANSI color (requires message inspection) | optional |
+| `r` (user) | — | User is identified to NickServ | services |
+| `q` (user, recv-only) | — | Protected from oper kick (U-line / services) | services |
+| `S` (user) | — | Connected via TLS (set by transport, read-only) | transport |
+
+`S` is a near-freebie — the transport already knows whether TLS is in
+use (`ConnectionActor` accepts a `transportMeta`); surfacing it as a
+user mode costs one reducer branch.
+
+---
+
+## 6. IRC services
+
+### 6.1 Architecture decision: integrated services (not pseudo-servers)
+
+Two designs exist in the wild:
+
+**A. Pseudo-client services (Atheme / Anope model).** A separate
+process connects as one or more virtual IRC clients named `NickServ`
+etc.; users interact via `PRIVMSG NickServ :REGISTER hunter2 email`.
+The link between ircd and services speaks a server-to-server protocol
+(TS6 / P10 / IRCv3 S2S).
+
+**B. Integrated services.** Service names are reserved nicks
+recognized by the daemon at PRIVMSG time and routed to dedicated
+reducers backed by a `ServicesStore` port. No S2S, no separate process,
+no pseudo-client connection.
+
+**Decision: B — integrated services.** Rationale:
+
+- S2S is an explicit non-goal (`PLAN.md` §1). Model A requires it.
+- The pure-reducer + location-of-authority architecture already has the
+  right seam: a new `ServicesStore` port (`packages/irc-core/src/ports.ts`,
+  mirroring `AccountStore` / `MessageStore`) absorbs the side effects,
+  and reducers stay pure.
+- One storage layer is shared with the existing SASL `AccountStore`
+  (TICKET-071 ✅) — a NickServ registration *is* a SASL account, so the
+  services work composes with auth rather than duplicating it.
+- The serverless substrates (Durable Objects, DynamoDB) handle
+  persistence natively; spinning up a separate long-running services
+  process would defeat the deployment model.
+
+**Trade-off documented:** integrated services are not binary-compatible
+with existing Atheme/Anope modules. Operators migrating from a
+services-aware network should expect to re-register nicks and channels.
+This is called out in `docs/` when the work ships.
+
+### 6.2 The `ServicesStore` port
+
+```ts
+/** Persists services-owned state. Mirrors the AccountStore/MessageStore pattern. */
+export interface ServicesStore {
+  // NickServ
+  registerNick(account: string, passwordHash: string, email?: string): Promise<void>;
+  verifyNick(account: string, password: string): Promise<boolean>;
+  dropNick(account: string): Promise<void>;
+  isRegisteredNick(account: string): Promise<boolean>;
+  setNickEnforce(account: string, mode: 'none' | 'kill' | 'ghost'): Promise<void>;
+
+  // ChanServ
+  registerChannel(chan: string, founder: string): Promise<void>;
+  dropChannel(chan: string): Promise<void>;
+  getChannelFounder(chan: string): Promise<string | null>;
+  setChannelAccess(chan: string, account: string, level: AccessLevel): Promise<void>;
+
+  // HostServ
+  setVhost(account: string, vhost: string): Promise<void>;
+  getVhost(account: string): Promise<string | null>;
+
+  // MemoServ
+  recordMemo(to: string, from: string, body: string): Promise<void>;
+  listMemos(account: string): Promise<Memo[]>;
+  markMemoRead(account: string, id: string): Promise<void>;
+}
+```
+
+Adapter implementations:
+
+| Adapter | Backend |
+|---------|---------|
+| in-memory-runtime | `Map`s, used by local-cli + tests |
+| cf-adapter | D1 (shared with the SASL store from TICKET-093 ✅) or a dedicated `ServicesDO` |
+| aws-adapter | DynamoDB `Accounts` table extended (TICKET-072 ✅ already provisions it) + new `Channels`/`Memos` tables |
+
+### 6.3 Services scope
+
+| Service | In scope | Out of scope (this pass) |
+|---------|----------|--------------------------|
+| **NickServ** | `REGISTER`, `IDENTIFY`, `LOGOUT`, `GHOST`, `DROP`, `INFO`, `SET ENFORCE`/`PASSWORD`/`EMAIL`, link to SASL account, `+r` user mode, nick enforcement | CertFP (covered by mTLS SASL EXTERNAL ✅), grouped nicks (alias list) |
+| **ChanServ** | `REGISTER`, `IDENTIFY`, `DROP`, `SET FOUNDER`/`MLOCK`/`RESTRICTED`/`KEEPTOPIC`, `ACCESS`/`LEVELS` (founder/sop/aop/vop/hop), `+r`/`+R`/`+M` channel modes, KEEPTOPIC persistence | ACL inheritance, fantasy commands, `OP`/`DEOP` shorthand (defer) |
+| **HostServ** | `ON`/`OFF`/`REQUEST`/`SET` (oper), integrate with the existing cloak machinery (`packages/irc-core` cloaking shipped in Phase 5), `+t` user mode (vhost in use) | per-channel vhosts |
+| **OperServ** | `AKILL` (network-wide ban, persisted + applied on connect), `JUPE` (block a nick/server name locally), `RAW` (oper-only, useful for recovery) | STATS aggregation (TICKET-104 🔄 covers server stats), `IGNORE` list |
+| **MemoServ** | `SEND`, `LIST`, `READ`, `DEL`, `FORWARD`, send-on-identify (queued memos delivered at login) | channel memos, group memos |
+| **BotServ** | — | **Out of scope entirely.** Channel-joined bots are a runtime cost serverless deployments should not absorb by default. Operators can run their own bots as ordinary clients. |
+| **StatServ** | — | **Out of scope.** `STATS` (TICKET-104) + observability dashboards (TICKET-045 ✅) cover it. |
+
+### 6.4 Nick enforcement policy
+
+`NickServ SET ENFORCE <mode>` decides what happens when an
+unidentified client uses a registered nick:
+
+- `none` (default): warning notice only.
+- `ghost`: kick the existing unidentified client off after a grace
+  period (default 30s); connection is force-disconnected via the
+  existing `disconnect(conn, reason)` runtime method.
+- `kill`: same as ghost but immediately.
+
+Implemented as a new `EnforceNick` effect emitted from the registration
+reducer when the chosen nick matches a registered account the
+connection is not identified as. The dispatch layer resolves it against
+`runtime.disconnect(...)`.
+
+### 6.5 Services ↔ daemon hooks
+
+Already-present seams the services reuse:
+
+- `AccountStore.verify('PLAIN', ...)` (TICKET-026 ✅) → a successful
+  NickServ `IDENTIFY` and a SASL PLAIN login both reduce to "this
+  connection is now account X", setting the `+r` user mode and
+  emitting `ACCOUNT` to `account-notify`-capable peers.
+- `MessageStore` (TICKET-063 ✅) → MemoServ's `SEND` is a record into
+  a per-account memo queue; delivery is a fanout at identify time.
+- `clock` / `IdFactory` ports → memo ids, enforcement grace timers.
+
+---
+
+## 7. Proposed tickets
+
+Ticket numbers are placeholders starting at **TICKET-110** (next free
+id per `todo.md`). Final ids assigned at ratification. Each ticket
+follows strict TDD (Red → Green → Refactor) per `CLAUDE.md` /
+`AGENTS.md`.
+
+### Phase 12 — IRCv3 extensions
+
+#### TICKET-110 — IRCv3 `account-notify` (push `ACCOUNT` on login/logout)
+- **Phase:** 12
+- **Points:** 2
+- **Dependencies:** TICKET-071 (`AccountStore` wiring, ✅)
+- **Description:** Advertise `account-notify`; emit `ACCOUNT <name|*>`
+  to peers in shared channels (excluding sender unless `echo-message`)
+  on SASL success, NickServ IDENTIFY (services), and `LOGOUT`. Reuses
+  the `extended-join`/`chghost` broadcast helper.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `account-notify`.
+  - A login by peer A visible to peer B (sharing a channel, cap
+    negotiated) produces `:A ACCOUNT alice`.
+  - A logout produces `:A ACCOUNT *`.
+  - No `ACCOUNT` messages to clients without the cap.
+  - 100% coverage on the new broadcast branch.
+- **TDD Outline:** Red on "B sees `ACCOUNT` after A's SASL success";
+  green via the broadcast helper; then cap-gating + echo-message path.
+
+#### TICKET-111 — IRCv3 `msgid` (emit `msgid` tag on every message)
+- **Phase:** 12
+- **Points:** 2
+- **Dependencies:** TICKET-063 (chathistory msgid plumbing, ✅)
+- **Description:** Advertise `msgid` as a standalone cap. Every
+  PRIVMSG/NOTICE/TAGMSG emitted to cap-enabled clients carries a
+  `+msgid=<id>` tag from `IdFactory.nonce()`. The chathistory reducer
+  already records the msgid; this ticket surfaces it on the live
+  fanout line, not just on replay.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `msgid`.
+  - Live PRIVMSG to a cap-enabled peer carries `@+msgid=<id>`.
+  - The msgid on the live line and on the chathistory replay line
+    match for the same recorded message.
+  - Clients without the cap see no `msgid` tag (existing behavior).
+  - 100% coverage on the tag-emission branch.
+- **TDD Outline:** Red on "peer with `msgid` cap sees `@+msgid=…` on a
+  PRIVMSG"; green; then assert parity with the recorded msgid.
+
+#### TICKET-112 — IRCv3 `standard-replies` (`FAIL`/`WARN`/`NOTE`)
+- **Phase:** 12
+- **Points:** 3
+- **Dependencies:** —
+- **Description:** Advertise `standard-replies`. For cap-enabled
+  clients, replace a curated subset of bare numeric error replies
+  (`461 ERR_NEEDMOREPARAMS`, `403 ERR_NOSUCHCHANNEL`, `432/433`
+  registration errors, SASL failures) with the structured
+  `FAIL COMMAND code context :description` form. The code-path
+  branches that *should not* change (numeric-only replies like MOTD
+  lines, NAMES) are left on the numeric form.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `standard-replies`.
+  - For each curated numeric, a cap-enabled client receives a
+    `FAIL`/`WARN`/`NOTE` line; a legacy client receives the unchanged
+    numeric.
+  - The mapping is data-driven (a `numericToStandardReply` table), not
+    scattered `if (hasCap)` checks.
+  - 100% coverage on the table + dispatch helper.
+- **TDD Outline:** Red on `461`→`FAIL` for cap-enabled client; green
+  via the table; then each curated code; then the legacy fallback.
+
+#### TICKET-113 — IRCv3 `MONITOR` (modern `ISON` replacement)
+- **Phase:** 12
+- **Points:** 5
+- **Dependencies:** —
+- **Description:** Advertise `MONITOR=<n>` (configurable max, default
+  30). Implement the `MONITOR + nick{,nick}` / `-` / `C` / `L` / `S`
+  subcommands and the `730 RPL_MONONLINE` / `731 RPL_MONOFFLINE` /
+  `732 RPL_MONLIST` / `734 ERR_MONLISTFULL` numerics. Online/offline
+  transitions push `730`/`731` asynchronously via the Registry's nick
+  reserve/release hooks.
+- **Acceptance Criteria:**
+  - `005` advertises `MONITOR=30`.
+  - `MONITOR +alice` while alice is offline → `731`.
+  - Alice connects → `730` pushed to the watcher.
+  - `MONITOR L` lists the watchlist; `MONITOR C` clears it.
+  - Over-limit → `734` with the rejected nick.
+  - 100% coverage on the reducer and the async push hook.
+- **TDD Outline:** Red on the offline→`731` path; green; then the
+  online push; then list/clear/over-limit.
+
+#### TICKET-114 — IRCv3 `labeled-response` (correlate request→reply via `BATCH`)
+- **Phase:** 12
+- **Points:** 8
+- **Dependencies:** TICKET-025 (`batch`, ✅)
+- **Description:** Advertise `labeled-response`. A client sends a
+  message with `+label=<id>`; the server wraps every reply caused by
+  that message in a `BATCH +id labeled-response … BATCH -id`. If the
+  request produces no reply, the server emits an empty batch. The
+  label is plumbed through `ctx` so every reducer's emitted effects
+  inherit it.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `labeled-response`.
+  - A `PRIVMSG` carrying `+label=foo` produces a `BATCH +foo
+    labeled-response` (echo + any numerics) `BATCH -foo` for
+    cap-enabled clients.
+  - A command that produces no reply (e.g. a no-op `PING` already
+    covered by `PONG` is *not* empty; a `JOIN` to a nonexistent channel
+    that 403s still wraps the 403) — spec edge cases enumerated.
+  - 100% coverage on the label plumbing + wrapping helper.
+- **TDD Outline:** Red on "PRIVMSG with `+label=foo` wraps echo in
+  BATCH"; green; then the no-reply case; then the multi-reply case.
+
+#### TICKET-115 — IRCv3 `sts` (Strict Transport Security policy)
+- **Phase:** 12
+- **Points:** 2
+- **Dependencies:** dual transport (Phase 7 ✅)
+- **Description:** Advertise `sts` with a deployment-configurable
+  policy (`duration`, `port` for the TLS listener, optional `preload`).
+  On a plaintext/WebSocket connection (when one exists), the server
+  emits the `STS` policy so compliant clients upgrade; on the TLS
+  connection the policy is still sent to lock in the duration.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `sts=duration=…,port=6697`.
+  - Values come from `ServerConfig`, not literals.
+  - A wss / irc+tls connection advertises the duration.
+  - 100% coverage on the policy builder.
+- **TDD Outline:** Red on cap advertisement; green; then override via
+  config.
+
+#### TICKET-116 — IRCv3 `draft/typing` (typing indicator broadcast)
+- **Phase:** 12
+- **Points:** 2
+- **Dependencies:** TICKET-076 (`TAGMSG`, ✅)
+- **Description:** Advertise `draft/typing`. A client sends
+  `TAGMSG <target> +draft/typing=active|paused|done`; the server
+  broadcasts to channel members (or routes to a user target),
+  excluding the sender unless `echo-message` is negotiated. No state
+  is kept server-side.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `draft/typing`.
+  - Channel typing TAGMSG fans out to cap-enabled members.
+  - The `+draft/typing=*` client tag is whitelisted for clients
+    without `message-tags` (per the spec's client-tag exception).
+  - 100% coverage on the whitelist + broadcast.
+- **TDD Outline:** Red on channel typing fanout; green; then
+  echo-message path; then user-target path.
+
+#### TICKET-117 — IRCv3 `draft/multiline` (multi-line `BATCH`)
+- **Phase:** 12
+- **Points:** 5
+- **Dependencies:** TICKET-025 (`batch`, ✅)
+- **Description:** Advertise `draft/multiline` with a configurable
+  byte budget (default 4096). A cap-enabled client sends
+  `BATCH +id draft/multiline :target` followed by N PRIVMSG/NOTICE
+  lines, then `BATCH -id`. The server concatenates per spec (with
+  `\n`), enforces the byte cap, and broadcasts as a single PRIVMSG
+  carrying a `+draft/multiline` tag plus the joined body (or a
+  batched replay to other multiline-capable peers — spec calls for
+  the joined form to legacy peers and the batch form to cap peers).
+- **Acceptance Criteria:**
+  - `CAP LS` includes `draft/multiline=35615` (or configured max).
+  - Multi-line batch from a cap-enabled client is delivered to
+    cap-enabled peers as a `draft/multiline` BATCH.
+  - Legacy peers receive the joined single PRIVMSG.
+  - Over-budget batch is rejected with `FAIL`.
+  - 100% coverage on the reducer + byte-budget enforcement.
+- **TDD Outline:** Red on a 2-line batch delivered as joined PRIVMSG
+  to a legacy peer; green; then the cap-peer batched delivery; then
+  budget enforcement.
+
+#### TICKET-118 — IRCv3 `draft/read-marker` (persistent last-read)
+- **Phase:** 12
+- **Points:** 5
+- **Dependencies:** TICKET-063 (chathistory, ✅), services `UserStore`
+  (TICKET-122)
+- **Description:** Advertise `draft/read-marker`. The chathistory
+  work already keeps a per-`(connection, channel)` last-read marker
+  in `ConnectionState`. This ticket persists the marker per
+  `(account, channel)` in `ServicesStore`, propagates updates via
+  `+draft/read-marker=<msgid>` tags on relevant messages, and seeds a
+  fresh connection's marker from the persisted value at identify time.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `draft/read-marker`.
+  - Marking a message read updates the persisted marker.
+  - Reconnect restores the marker.
+  - `CHATHISTORY BEFORE` honours the marker in the absence of an
+    explicit pivot.
+  - 100% coverage on the persistence + tag emission.
+- **TDD Outline:** Red on reconnect-restore; green via the store;
+  then tag emission; then CHATHISTORY integration.
+- **Implementation notes (shipped):** Landed as a focused
+  `ReadMarkerStore` port (`get` / `set` / `forAccount`) plus an
+  `InMemoryReadMarkerStore` reference impl in `irc-core/ports.ts`, rather
+  than waiting on the full services `UserStore` (TICKET-122). The mark is
+  delivered as a `TAGMSG` carrying `+draft/read-marker=<msgid>` (msgid-based,
+  composing with the chathistory marker plumbing, diverging from the
+  work-in-progress ircv3 draft's timestamped `MARKREAD` verb). A mark TAGMSG
+  is persisted via `persistReadMarker`, fanned out to `message-tags` OR
+  `draft/read-marker` peers (mirroring the `draft/typing` precedent), and
+  `+draft/read-marker` is whitelisted in `filterClientTags` so draft-only
+  peers keep the tag. SASL identify seeds `lastReadMarkers` via
+  `seedReadMarkers`; `CHATHISTORY BEFORE` with no pivot falls back to the
+  connection's marker. TICKET-122 should fold this store into the unified
+  services `UserStore` when it lands.
+
+#### TICKET-119 — IRCv3 `draft/pre-away` (persist away status)
+- **Phase:** 12
+- **Points:** 3
+- **Dependencies:** TICKET-061 (`AWAY`, ✅), services `UserStore`
+  (TICKET-122)
+- **Description:** Advertise `draft/pre-away`. Persist away reason in
+  `ServicesStore` keyed by account. On identify (or SASL login), the
+  server re-applies the away state and emits the `AWAY` line +
+  `306 RPL_NOWAWAY` as if the user had sent `AWAY :reason` themselves.
+  Noted out-of-scope in TICKET-063.
+- **Acceptance Criteria:**
+  - `CAP LS` includes `draft/pre-away`.
+  - An identified user who previously went `AWAY :brb` and reconnects
+    is auto-marked away.
+  - `AWAY` (unset) clears the persisted reason.
+  - 100% coverage on the persistence + replay.
+- **TDD Outline:** Red on reconnect auto-away; green; then the unset
+  path.
+- **Implementation notes (shipped):** Landed as a focused `AwayStore`
+  port (`get` / `set` / `clear`) plus an `InMemoryAwayStore` reference
+  impl in `irc-core/ports.ts`, rather than waiting on the full services
+  `UserStore` (TICKET-122) — same shape as the TICKET-118 `ReadMarkerStore`
+  precedent. The `awayReducer` calls `persistAway` on set and
+  `clearPersistedAway` on unset (gated on a bound store AND an
+  identified connection, so unidentified sessions still track their own
+  in-memory `away` for the duration of the connection). SASL identify
+  calls `replayPersistedAway` to copy a stored reason onto the fresh
+  connection's `ConnectionState.away` and emits a single
+  `306 RPL_NOWAWAY` so the user sees they are still away. The
+  companion `away-notify` broadcast is intentionally NOT emitted at
+  identify time — the connection has not joined any channels yet, so it
+  would have no audience; peers learn the away state through the normal
+  `WHO` / `WHOIS` / `AWAY` queries once the user joins. TICKET-122
+  should fold this store into the unified services `UserStore` when it
+  lands.
+
+#### TICKET-120 — ISUPPORT tokens for new caps + modes
+- **Phase:** 12
+- **Points:** 2
+- **Dependencies:** the cap tickets above + services modes
+  (TICKET-122)
+- **Description:** Add `MONITOR=<n>`, `STATUSMSG=@+`, `EXTBAN=~,q`,
+  `ACCOUNTEXTBAN=a`, draft tokens for `draft/typing`/`draft/multiline`
+  to `generateIsupport`. Tokens are config-derived where applicable
+  (max monitor count, extban prefix).
+- **Acceptance Criteria:**
+  - Each token advertises the configured value.
+  - Tokens only appear when the relevant cap/mode is supported (e.g.
+    `ACCOUNTEXTBAN` only once services ship).
+  - 100% coverage on the new branches.
+- **TDD Outline:** Red on each missing token; green by adding it.
+
+#### TICKET-121 — User mode `S` (TLS connected)
+- **Phase:** 12
+- **Points:** 1
+- **Dependencies:** dual transport (Phase 7 ✅)
+- **Description:** When the connection is over TLS (wss or irc+tls),
+  set user mode `S` read-only on the connection at registration. The
+  mode is not settable via `MODE` (parse rejects `+S` with `501`).
+  Surface in WHOIS (`:server 276 nick target :is using a secure
+  connection`) for clients that advertise the `RPL_WHOISSECURE` cap.
+- **Acceptance Criteria:**
+  - TLS connection → `+S` user mode visible in `WHO`/`WHOIS`.
+  - `MODE nick +S` rejected with `501 ERR_UMODEUNKNOWNFLAG`.
+  - 100% coverage on the mode-set + parse rejection.
+- **TDD Outline:** Red on TLS registration setting `+S`; green; then
+  the parse rejection.
+
+### Phase 13 — IRC services
+
+#### TICKET-122 — `ServicesStore` port + in-memory reference impl
+- **Phase:** 13
+- **Points:** 5
+- **Dependencies:** TICKET-029 (`IrcRuntime` port, ✅),
+  TICKET-071 (`AccountStore`, ✅)
+- **Description:** Define `ServicesStore` (§6.2) in
+  `packages/irc-core/src/ports.ts`. Ship `InMemoryServicesStore`
+  (in-memory-runtime) covering NickServ/ChanServ/HostServ/MemoServ
+  primitives. Adapter backends (D1, DynamoDB) ship in dedicated
+  follow-on tickets.
+- **Acceptance Criteria:**
+  - Port interface compiles under strict mode.
+  - `InMemoryServicesStore` implements every method; 100% coverage.
+  - Reused by local-cli and unit tests.
+- **TDD Outline:** Red on `registerNick`/`verifyNick` round-trip;
+  green; then each method.
+
+#### TICKET-123 — NickServ: REGISTER / IDENTIFY / DROP / INFO + `+r`
+- **Phase:** 13
+- **Points:** 8
+- **Dependencies:** TICKET-122
+- **Description:** Wire `PRIVMSG NickServ :<command>` to a NickServ
+  reducer. `REGISTER password email` creates a SASL account (reuses
+  the existing `AccountStore` so SASL PLAIN works immediately after
+  registration). `IDENTIFY password` logs the current connection in
+  (sets `+r` user mode, emits `ACCOUNT` to `account-notify` peers).
+  `DROP` removes the registration. `INFO [nick]` queries it.
+  Successful IDENTIFY triggers MemoServ delivery of queued memos.
+- **Acceptance Criteria:**
+  - `REGISTER hunter2 alice@example.com` followed by SASL PLAIN with
+    `alice:hunter2` succeeds.
+  - `IDENTIFY hunter2` from an unidentified connection sets `+r` and
+    emits `ACCOUNT`.
+  - `DROP alice` requires re-identify.
+  - 100% coverage on the reducer + state transitions.
+- **TDD Outline:** Red on REGISTER→SASL round-trip; green; then
+  IDENTIFY; then DROP; then INFO.
+
+#### TICKET-124 — NickServ: nick enforcement (`SET ENFORCE`)
+- **Phase:** 13
+- **Points:** 5
+- **Dependencies:** TICKET-123
+- **Description:** Implement `NickServ SET ENFORCE none|ghost|kill`
+  plus the `EnforceNick` effect. When a client registers (NICK) with
+  a nick that is registered to an account they are not identified as,
+  the policy fires after the configured grace period. `ghost` force-
+  disconnects; `kill` force-disconnects immediately. Default policy
+  per registered account is `none`.
+- **Acceptance Criteria:**
+  - `SET ENFORCE ghost` + unidentified use of the nick → grace
+    period → `disconnect("Nick enforced by NickServ")`.
+  - `SET ENFORCE kill` → immediate disconnect.
+  - `SET ENFORCE none` → warning notice only.
+  - 100% coverage on the effect + dispatch integration.
+- **TDD Outline:** Red on grace-period disconnect; green; then each
+  policy.
+
+#### TICKET-125 — ChanServ: REGISTER / DROP / SET + `+r`/`+R`/`+M`
+- **Phase:** 13
+- **Points:** 8
+- **Dependencies:** TICKET-123, TICKET-011 (`MODE`, ✅)
+- **Description:** Wire `PRIVMSG ChanServ :<command>`. `REGISTER`
+  records the channel founder; sets channel mode `+r`. `SET
+  FOUNDER/MLOCK/RESTRICTED/KEEPTOPIC` updates the persisted channel
+  record. New channel modes: `+r` (registered, settable only by
+  ChanServ), `+R` (block join/message from unidentified), `+M` (mod
+  speak requires identification). `KEEPTOPIC` persists the topic and
+  restores it on the first join after the channel becomes empty.
+- **Acceptance Criteria:**
+  - `REGISTER #chan` by an identified founder sets `+r`.
+  - `+R` blocks join from unidentified (`519 ERR_ALLMUSTREGISTER`,
+    server-specific numeric) and PRIVMSG (`404`).
+  - `KEEPTOPIC` round-trips a topic across empty-recreate.
+  - `MLOCK` reapplies the locked modes if an op tries to unset them.
+  - 100% coverage on the reducer + mode interactions.
+- **TDD Outline:** Red on REGISTER→`+r`; green; then `+R`/`+M`;
+  then KEEPTOPIC; then MLOCK.
+
+#### TICKET-126 — ChanServ: ACCESS / LEVELS (SOP/AOP/VOP/HOP)
+- **Phase:** 13
+- **Points:** 5
+- **Dependencies:** TICKET-125
+- **Description:** `ChanServ ACCESS #chan ADD nick level` and the
+  shorthand `SOP`/`AOP`/`VOP`/`HOP` variants map an account to a
+  privilege level. On JOIN, ChanServ applies the matching channel
+  prefix (`@`, `+`) automatically. `LEVELS` lets the founder redefine
+  what numeric level each command requires.
+- **Acceptance Criteria:**
+  - `AOP alice ADD` → alice auto-opped on JOIN.
+  - `VOP bob ADD` → bob auto-voiced.
+  - `ACCESS #chan DEL alice` removes.
+  - `LEVELS SET AUTOOP 5` redefines the threshold.
+  - 100% coverage on the access reducer + JOIN hook.
+- **TDD Outline:** Red on AOP→auto-op; green; then DEL; then LEVELS.
+
+#### TICKET-127 — HostServ: ON / OFF / REQUEST / SET (oper)
+- **Phase:** 13
+- **Points:** 3
+- **Dependencies:** TICKET-122, cloaking (Phase 5 ✅)
+- **Description:** Wire `PRIVMSG HostServ :<command>`. `REQUEST
+  vhost` queues a request for oper approval (or auto-approves if
+  configured). `SET account vhost` (oper-only) sets it directly.
+  `ON`/`OFF` toggles the cloak at runtime; the cloak machinery
+  already exists, this ticket wires it to per-account state and emits
+  `CHGHOST` (TICKET-022 ✅) on toggle.
+- **Acceptance Criteria:**
+  - `SET alice example.net` + `ON` → `CHGHOST` emitted to peers;
+    WHOIS shows the vhost.
+  - `OFF` restores the real (cloaked) host.
+  - 100% coverage on the reducer + CHGHOST emission.
+- **TDD Outline:** Red on `ON`→`CHGHOST`; green; then `OFF`; then
+  `REQUEST`/`SET` approval path.
+
+#### TICKET-128 — OperServ: AKILL / JUPE / RAW
+- **Phase:** 13
+- **Points:** 5
+- **Dependencies:** TICKET-075 (`OPER`, ✅), TICKET-122
+- **Description:** Wire `PRIVMSG OperServ :<command>` (oper-only;
+  rejected with a services notice otherwise). `AKILL ADD mask reason`
+  records a network-wide ban persisted in `ServicesStore`; the
+  `$connect`/`$default` admission path checks it on every new
+  connection and on every PRIVMSG, force-disconnecting on match.
+  `JUPE nick` blocks a nick/server name locally (NICK collision
+  reducer returns `432` for the jupe'd nick). `RAW <line>` is oper-
+  only and emits a raw IRC line (useful for recovery; logged).
+- **Acceptance Criteria:**
+  - `AKILL ADD *!*@bad.example.net flooding` → next matching
+    connection is disconnected at `$connect`.
+  - `JUPE moo` → `NICK moo` returns `432 ERR_ERRONEUSNICKNAME`.
+  - Non-oper → service notice rejection, no state change.
+  - 100% coverage on each reducer + the admission hook.
+- **TDD Outline:** Red on AKILL disconnect; green; then JUPE; then
+  RAW; then non-oper rejection.
+
+#### TICKET-129 — MemoServ: SEND / LIST / READ / DEL + queue delivery
+- **Phase:** 13
+- **Points:** 5
+- **Dependencies:** TICKET-123, TICKET-122 (`MessageStore` pattern,
+  ✅)
+- **Description:** Wire `PRIVMSG MemoServ :<command>`. `SEND nick
+  body` records a memo against the recipient's account. On successful
+  NickServ IDENTIFY or SASL login, queued memos are delivered (via
+  the existing MemoServ pseudo-client notice format). `LIST`/`READ`/
+  `DEL`/`FORWARD` round out the surface.
+- **Acceptance Criteria:**
+  - `SEND alice Hi` while alice is offline → alice receives the memo
+    on next IDENTIFY.
+  - `LIST` enumerates unread.
+  - `READ n` delivers memo #n; `DEL n` removes.
+  - 100% coverage on the reducer + delivery hook.
+- **TDD Outline:** Red on offline-send→identify-delivery; green; then
+  list/read/del.
+
+#### TICKET-130 — Adapter backends for `ServicesStore`
+- **Phase:** 13
+- **Points:** 8
+- **Dependencies:** TICKET-122, all of TICKET-123..129 (reducers
+  landed against the in-memory store first)
+- **Description:** Ship persistent `ServicesStore` implementations:
+  - CF: D1 (share the database from TICKET-093 ✅), new tables
+    `nickserv_accounts`, `chanserv_channels`, `chanserv_access`,
+    `hostserv_vhosts`, `memoserv_memos`.
+  - AWS: DynamoDB, extending the existing `Accounts` table
+    (TICKET-072 ✅) and adding `Channels`, `ChannelAccess`, `Vhosts`,
+    `Memos`.
+  - Both adapters wire the store into `ConnectionActorOptions.services`.
+- **Acceptance Criteria:**
+  - Each adapter: end-to-end NickServ register→identify→SASL PLAIN.
+  - Channel registration survives a deploy (state persisted).
+  - Memos delivered on reconnect after identify.
+  - 100% coverage on the new store implementations.
+- **TDD Outline:** Red per adapter on REGISTER→survive-restart; green
+  via the persistent store.
+
+#### TICKET-131 — Docs: services reference + admin tooling
+- **Phase:** 13
+- **Points:** 2
+- **Dependencies:** TICKET-130
+- **Description:** `docs/Services.md` covering: integrated-services
+  architecture decision (§6.1), per-service command reference, admin
+  tooling (`tools/seed-nickserv-accounts.ts` mirroring the existing
+  `seed-{aws,cf}-accounts.ts` scripts), migration notes for operators
+  coming from Atheme/Anope.
+- **Acceptance Criteria:**
+  - A new contributor can register a NickServ account and a ChanServ
+    channel end-to-end following only the doc.
+  - The migration caveat (no Atheme/Anope compatibility) is called
+    out up front.
+- **TDD Outline:** N/A (documentation). Reviewed by walking the
+  steps from a clean checkout.
+
+---
+
+## 8. Sequencing
+
+Recommended landing order, respecting dependencies:
+
+1. **Cheap IRCv3 wins first.** TICKET-110 (`account-notify`),
+   TICKET-111 (`msgid`), TICKET-115 (`sts`), TICKET-121 (`+S` mode),
+   TICKET-116 (`draft/typing`). All small, all compose with shipped
+   work, all unblock better client UX.
+2. **`MONITOR` + `standard-replies`.** TICKET-113, TICKET-112.
+3. **`labeled-response`.** TICKET-114 — largest IRCv3 item, do last
+   among the stable caps; touches every reducer that emits a reply.
+4. **Services foundation.** TICKET-122 (port + in-memory store).
+5. **NickServ core.** TICKET-123, TICKET-124 — needed before ChanServ
+   because every other service keys off the identified account.
+6. **ChanServ.** TICKET-125, TICKET-126.
+7. **HostServ / OperServ / MemoServ.** TICKET-127, TICKET-128,
+   TICKET-129 (parallelizable).
+8. **Persistent adapter backends.** TICKET-130 (unblocks any
+   production use of services).
+9. **Draft caps that depend on services.** TICKET-118 (`draft/read-
+   marker`), TICKET-119 (`draft/pre-away`).
+10. **`draft/multiline`.** TICKET-117 — independent, can land
+    anywhere after the IRCv3 cheap wins.
+11. **Docs + ISUPPORT catch-up.** TICKET-131, TICKET-120.
+
+---
+
+## 9. Risks
+
+| Risk | Mitigation |
+|------|------------|
+| `labeled-response` plumbing touches every reducer | Land `BATCH` wrapping first (already shipped); add label propagation as a `ctx` field and a single dispatch hook. Refactor incrementally per reducer. |
+| Integrated services drift from user expectations (Atheme parity) | Document the decision up front (TICKET-131); keep command names/behaviour aligned where it's free. |
+| Nick enforcement races (NICK + IDENTIFY interleaved) | All mutations through the single `ServicesStore` authority per account; the `EnforceNick` effect is emitted after `reserveNick` succeeds, so the nick is owned before enforcement fires. |
+| Services-backed caps (`draft/read-marker`, `draft/pre-away`) coupled to services launch | Track as Phase 12 tickets with explicit Phase 13 dependencies; ship IRCv3 cheap wins independently. |
+| D1/DynamoDB cost from per-message `msgid` recording | `msgid` is emitted on the live line without persisting; only `MessageStore` records (chathistory) hit storage. Same cost profile as today. |
+| `draft/multiline` byte budget abuse | Hard cap enforced in the reducer (`FAIL` over-budget); per-connection flood control (TICKET-065 ✅) bounds the burst. |
+
+---
+
+## 10. Definition of done (per phase)
+
+**Phase 12 — IRCv3 extensions** is done when:
+
+- [ ] Every stable IRCv3 cap in §3.1 is advertised and exercised by
+      the parametrized contract suite on the in-memory runtime.
+- [ ] The draft caps in §3.2 are advertised under `draft/` namespace
+      and exercised; they can be flipped off via config without code
+      changes.
+- [ ] `005 RPL_ISUPPORT` advertises every new token.
+- [ ] Client compat sweep (TICKET-050 ⬜) passes against ≥3 clients
+      with the new caps negotiated.
+
+**Phase 13 — IRC services** is done when:
+
+- [ ] NickServ/ChanServ/HostServ/OperServ/MemoServ reducers ship at
+      100% coverage against `InMemoryServicesStore`.
+- [ ] Both adapters ship persistent `ServicesStore` backends; the
+      parametrized contract suite is green on both.
+- [ ] End-to-end: register → identify → SASL PLAIN → ChanServ
+      REGISTER → KEEPTOPIC round-trip survives a deploy restart.
+- [ ] `docs/Services.md` is complete and reviewer-validated.
+
+---
+
+## 11. Open questions
+
+- **Account name vs. nick.** Should NickServ register an *account*
+  (multiple nicks group to it, Atheme-style) or register a single
+  nick? Default proposal: account-per-registration with nick grouping
+  as a follow-up, matching SASL's existing account model.
+- **Memo size + retention.** Default cap (256 bytes? 2 KiB?) and TTL
+  (30 days?). Default proposal: 2 KiB per memo, 30-day TTL, both
+  config-tunable.
+- **`+R`/`+M` numerics.** Server-specific `519 ERR_ALLMUSTREGISTER`
+  vs. reusing `473 ERR_INVITEONLYCHAN` semantics. Default proposal:
+  introduce the spec-recognized numerics where they exist, document
+  server-specific ones in `isupport`.
+- **AKILL scope.** Network-wide (persisted) vs. per-listener (edge
+  only). Default proposal: persisted at the `ServicesStore`, enforced
+  in the admission path of every adapter — true network-wide on a
+  single-server deployment.