serverless-ircd 0.2.0 → 0.4.0

package/docs/Cloudflare-Deployment-Guide.md

@@ -1,660 +0,0 @@
-# Cloudflare Deployment Guide
-
-End-to-end guide for deploying ServerlessIRCd to Cloudflare Workers
-(Phase 3 of `PLAN.md`). Covers prerequisites, first-time account setup,
-local development, staging deploy, production deploy, configuration,
-secrets, sharding, CI/CD, cost, and troubleshooting.
-
-Cross-reference: `PLAN.md` §6.1 (CF mapping), `apps/cf-worker/wrangler.toml`,
-`packages/cf-adapter/`, `.github/workflows/deploy-cf.yml`. For the AWS
-equivalent, see `docs/deployment-aws.md` (TICKET-044).
-
-**Acceptance criterion (TICKET-038):** a new contributor can deploy their
-own staging instance following only this doc.
-
----
-
-## 1. What gets deployed
-
-A single Cloudflare Worker (`serverless-ircd`) plus three Durable Object
-namespaces that hold all IRC state:
-
-```
-   ┌─────────────────────────────────────────────────────────────┐
-   │  Worker: serverless-ircd  (apps/cf-worker/src/worker.ts)    │
-   │                                                             │
-   │   fetch(request, env):                                      │
-   │     Upgrade: websocket  ──▶  ConnectionDO.idFromName(uuid)  │
-   │     else                 ──▶  200 human health string       │
-   └─────────────────────────┬───────────────────────────────────┘
-                             │ env.CONNECTION_DO.get(id).fetch()
-                             ▼
-   ┌─────────────────────────────────────────────────────────────┐
-   │  ConnectionDO  (one per WebSocket connection)               │
-   │    • hibernatable WS via HibernatingWebSocketHandler       │
-   │    • owns ConnectionState, drives ConnectionActor          │
-   │    • DO storage persists state across hibernation          │
-   │    • alarm() drives the PING / no-PONG disconnect sweep    │
-   └────┬───────────────────────────────┬────────────────────────┘
-        │ stub() RPC                    │ stub() RPC
-        ▼                               ▼
-   ┌──────────────────────┐    ┌─────────────────────────────────┐
-   │  RegistryDO          │    │  ChannelDO                       │
-   │  (sharded by nick)   │    │  (one per lowercased chan name)  │
-   │  • nick uniqueness   │    │  • roster + modes + topic        │
-   │  • nick→connId map   │    │  • fanout to members             │
-   └──────────────────────┘    └──────────────────────────────────┘
-```
-
-The Worker itself is a thin edge: it allocates a server-generated
-`connectionId` (`crypto.randomUUID()`) and routes the upgrade to that
-connection's `ConnectionDO`. All IRC protocol logic lives in the shared
-`irc-core` reducers, run by `ConnectionActor` inside the DO. No state is
-held in the Worker process itself.
-
-The same artifacts serve both staging and production; the only difference
-is the `--env` flag and the `[env.staging]` block in `wrangler.toml`.
-
----
-
-## 2. Prerequisites
-
-| Requirement           | Version / detail                                       |
-|-----------------------|--------------------------------------------------------|
-| Node.js               | ≥ 20 (matches CI; `engines.node` in root `package.json`)|
-| pnpm                  | 9.x (`packageManager: pnpm@9.15.9` in root `package.json`)|
-| Cloudflare account    | Free tier is enough for staging. Workers Paid plan     |
-|                       | (USD $5/mo) is recommended for production — see §10.   |
-| `wrangler` CLI        | Comes from `apps/cf-worker/devDependencies`; no global install needed. |
-| Git checkout          | Clean working tree on `main` for production deploys.   |
-
-A **Workers Paid plan** is not strictly required for staging, but
-Durable Objects only run on the Paid plan in any meaningful production
-scenario. The free tier caps DO requests and disables hibernation
-budget headroom. See §10 (Cost).
-
-Confirm the local environment:
-
-```bash
-node --version          # v20.x or newer
-pnpm --version          # 9.x
-pnpm install            # from repo root, installs the whole workspace
-pnpm build              # builds irc-core, irc-server, cf-adapter, cf-worker
-```
-
-`pnpm build` must succeed before `wrangler deploy` — the Worker's
-`main = "src/worker.ts"` is transpiled by wrangler, but it imports
-compiled `dist/` from the workspace packages.
-
----
-
-## 3. First-time Cloudflare setup
-
-These steps are done once per Cloudflare account.
-
-### 3.1 Claim a workers.dev subdomain
-
-Every Worker is reachable at `<worker-name>.<subdomain>.workers.dev`.
-Claim your subdomain in the dashboard: **Workers & Pages → General →
-Subdomain** (or via `wrangler subdomain <name>`). This guide assumes
-your subdomain is `example`; substitute your own.
-
-If you intend to use a custom domain (`irc.example.com`), you can skip
-the workers.dev subdomain and add a **Route** + DNS record instead (see
-§8.4).
-
-### 3.2 Create an API token
-
-The `wrangler` CLI needs a token with permission to deploy Workers and
-manage Durable Objects.
-
-1. Go to <https://dash.cloudflare.com/profile/api-tokens> → **Create
-   Token**.
-2. Use the **"Edit Cloudflare Workers"** template, which grants:
-   - `Account · Workers Scripts · Edit`
-   - `Account · Durable Objects · Edit`
-   - `Account · Worker Routes · Edit` (only if using custom domains)
-3. Restrict to the target **Account Resources**.
-4. Copy the token. You will set it as `CLOUDFLARE_API_TOKEN` (env var
-   for local CLI; Actions secret for CI).
-
-Also grab your **Account ID** from the dashboard sidebar — set it as
-`CLOUDFLARE_ACCOUNT_ID` if your token doesn't carry an unambiguous
-account context.
-
-### 3.3 Authenticate the CLI locally
-
-Two equivalent options:
-
-```bash
-# Interactive (recommended for humans):
-npx wrangler login
-
-# Non-interactive (CI or ephemeral):
-export CLOUDFLARE_API_TOKEN=...
-export CLOUDFLARE_ACCOUNT_ID=...
-```
-
-When `CLOUDFLARE_API_TOKEN` is set in the environment, `wrangler` uses
-it directly and skips the OAuth store. The deploy commands in
-`apps/cf-worker/package.json` (`deploy:staging`, `deploy:prod`) honor
-both.
-
----
-
-## 4. Local development
-
-Before deploying, run the Worker locally with the real `workerd`
-runtime. This exercises the DOs, storage, and alarms against Miniflare
-without touching Cloudflare.
-
-From the repo root:
-
-```bash
-pnpm build
-pnpm --filter @serverless-ircd/cf-worker dev
-# → boots wrangler dev on http://localhost:8787
-```
-
-In another terminal, run the smoke e2e against the local URL (the
-script defaults to `ws://localhost:8787`):
-
-```bash
-node apps/cf-worker/scripts/smoke.mjs
-```
-
-Expected output (success):
-
-```json
-{"ts":"...","level":"info","msg":"cf-worker smoke e2e passed","url":"ws://localhost:8787"}
-```
-
-The smoke script (`scripts/smoke.mjs`) replays
-CONNECT → NICK/USER → JOIN #smoke → PRIVMSG → QUIT and asserts the
-server emits `001`, `376`, `353`, `366`, and closes the socket. It is
-the exact same script CI runs against the deployed staging URL.
-
-The unit + integration suites live in `packages/cf-adapter/tests/` and
-`apps/cf-worker/tests/`; both run under `@cloudflare/vitest-pool-workers`
-against real `workerd`, so behavior matches production. Run them with:
-
-```bash
-pnpm --filter @serverless-ircd/cf-adapter test
-pnpm --filter @serverless-ircd/cf-worker test
-```
-
----
-
-## 5. Deploy staging
-
-Staging is the environment CI deploys on every push to `main`; you can
-also deploy it manually from a clean checkout.
-
-### 5.1 Deploy from your machine
-
-```bash
-# From the repo root:
-pnpm deploy:cf:staging
-# Equivalent to:
-#   pnpm --filter @serverless-ircd/cf-worker deploy:staging
-#   → wrangler deploy --env staging
-```
-
-The first deploy of a given account will:
-
-1. Create the Worker `serverless-ircd-staging`.
-2. Apply the `[[env.staging.migrations]]` block (`tag = "v1"`,
-   `new_classes = [ConnectionDO, RegistryDO, ChannelDO]`). This is what
-   provisions the three DO namespaces.
-3. Print the deployed URL, e.g.
-   `https://serverless-ircd-staging.example.workers.dev`.
-
-If you see `Migration tag has already been applied`, the namespaces
-already exist; subsequent deploys just update the Worker code.
-
-### 5.2 Verify with the smoke script
-
-```bash
-node apps/cf-worker/scripts/smoke.mjs \
-  --url wss://serverless-ircd-staging.example.workers.dev
-```
-
-The same JSON `level: "info"` line on stdout means the full
-REGISTER/JOIN/PRIVMSG/QUIT flow completed against the deployed Worker.
-
-### 5.3 Connect a real IRC client
-
-Point any RFC-compliant WebSocket-aware IRC client at the deployed URL.
-For WeeChat:
-
-```
-/server add ircd serverless-ircd-staging.example.workers.dev/443
-/set irc.server.ircd.ssl on
-/connect ircd
-/join #test
-```
-
-For a quick text-only check, the `apps/local-cli` and
-`tools/tcp-ws-forwarder` packages bridge a plain TCP IRC client to the
-Worker's WebSocket endpoint — see the README "Bridging raw TCP clients"
-section.
-
----
-
-## 6. Deploy production
-
-Production is the default `wrangler.toml` environment (no `--env`
-flag). It deploys the Worker named `serverless-ircd` (no `-staging`
-suffix) with its own DO namespaces.
-
-```bash
-# From the repo root:
-pnpm deploy:cf:prod
-```
-
-Before your first production deploy, edit `apps/cf-worker/wrangler.toml`:
-
-1. Set `[vars].SERVER_NAME` to the public hostname clients should see
-   in numerics (`001`, `005`, etc.) — e.g. `irc.example.com`.
-2. Set `[vars].NETWORK_NAME` to your network label.
-3. Set `[vars].MOTD_LINES` to your message-of-the-day (newline-delimited).
-4. (Optional) Add a custom-domain Route under `[[routes]]` — see §8.4.
-
-**First-time production migration:** the default `[[migrations]]` block
-applies on the first `deploy:cf:prod` and creates the production DO
-classes. This is one-way: once a DO namespace has data, you cannot
-rename or delete a class without an explicit migration entry (see
-§9.2).
-
-There is **no CI auto-deploy to production** — production deploys are
-always manual (`workflow_dispatch` only is intentionally not wired; see
-`.github/workflows/deploy-cf.yml`). Staging deploys on every push to
-`main`.
-
----
-
-## 7. Configuration reference
-
-All deployment knobs live in `apps/cf-worker/wrangler.toml`. The file
-is the single source of truth for both environments.
-
-### 7.1 Top-level / `[vars]`
-
-| Var             | Purpose                                            | Default                              |
-|-----------------|----------------------------------------------------|--------------------------------------|
-| `name`          | Worker name. Staging overrides to `...-staging`.   | `serverless-ircd`                    |
-| `main`          | Worker entry.                                      | `src/worker.ts`                      |
-| `compatibility_date` | Pins Workers runtime behavior.                | `2024-11-01`                         |
-| `compatibility_flags` | `nodejs_compat` enables Node-style APIs.    | `["nodejs_compat"]`                  |
-| `SERVER_NAME`   | Server name sent in `001`/`005` numerics.          | `irc.example.com` (override!)        |
-| `NETWORK_NAME`  | Network label in `005 NETWORK=…`.                  | `ServerlessIRCd`                     |
-| `MOTD_LINES`    | Message-of-the-day, `\n`-delimited.                | Welcome banner string.               |
-
-These are read by `ConnectionDO` via `Env` (see
-`packages/cf-adapter/src/env.ts:20` and the `serverConfig()` method in
-`connection-do.ts:337`). They are **not** secrets — they ship in the
-bundle and are visible in the dashboard.
-
-### 7.2 `[env.staging]`
-
-The staging block overrides `name` and `[vars]` only. The DO bindings
-and migrations must be redeclared per-environment (wrangler requires
-explicit per-env blocks — they do not inherit):
-
-```toml
-[env.staging]
-name = "serverless-ircd-staging"
-
-[env.staging.vars]
-SERVER_NAME = "irc-staging.example.com"
-NETWORK_NAME = "ServerlessIRCd (staging)"
-MOTD_LINES = "..."
-```
-
-### 7.3 Durable Object bindings
-
-Three DO classes are exported from `src/worker.ts` (re-exported from
-`@serverless-ircd/cf-adapter`) and bound in `wrangler.toml`:
-
-| Binding name      | Class          | Owned state                                |
-|-------------------|----------------|--------------------------------------------|
-| `CONNECTION_DO`   | `ConnectionDO` | Socket + ConnectionState + PING alarms.    |
-| `REGISTRY_DO`     | `RegistryDO`   | Nick uniqueness, nick→connId map (sharded).|
-| `CHANNEL_DO`      | `ChannelDO`    | Per-channel roster, modes, topic, fanout.  |
-
-The class names in `wrangler.toml`'s `class_name` field MUST match the
-re-exports at the top of `apps/cf-worker/src/worker.ts:29`.
-
-### 7.4 Migrations
-
-```toml
-[[migrations]]
-tag = "v1"
-new_classes = ["ConnectionDO", "RegistryDO", "ChannelDO"]
-```
-
-`tag` is the migration id (string, monotonically tracked by wrangler).
-`new_classes` declares the DO classes on first deploy. To **rename** or
-**delete** a class after data exists, append a new `[[migrations]]`
-block with `tag = "v2"` (etc.) and a `renamed_classes` or `deleted_classes`
-entry. See <https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/>.
-
-Both the default and staging environments carry their own migration
-list. Keep them in sync unless you intentionally diverge.
-
-### 7.5 Custom domain (optional)
-
-To serve the Worker on `irc.example.com` instead of the workers.dev
-subdomain, add a route and bind a Cloudflare-managed DNS record:
-
-```toml
-[[routes]]
-pattern = "irc.example.com/*"
-zone_name = "example.com"
-custom_domain = false   # true if you'd rather use a Worker Custom Domain
-```
-
-Custom domains are optional for staging and recommended for production
-(many IRC clients expect a stable, owned hostname). DNS records are
-managed separately in the dashboard.
-
----
-
-## 8. Secrets
-
-**As of v1 the Worker consumes no secret bindings.** Server password,
-SASL `AccountStore` credentials, and oper creds land in later tickets
-(TICKET-046 / TICKET-047). When they ship, secrets will be set via:
-
-```bash
-wrangler secret put SERVER_PASSWORD --env staging
-# → prompts for the value; stores it in the Workers secret store,
-#   NOT in wrangler.toml or the repo.
-```
-
-Secrets are visible to the Worker as plain `env.SECRET_NAME` bindings,
-but their values are never written to disk, the bundle, or the
-dashboard's variable listing. To rotate, run `wrangler secret put`
-again; to remove, `wrangler secret delete <NAME>`.
-
-**Never** put credentials, API tokens, or password hashes in
-`wrangler.toml`, in `[vars]`, or in committed files. The
-`wrangler.toml` header enforces this with a comment block (see lines
-15-20).
-
-The CI deploy uses two **GitHub Actions secrets**, not Workers
-secrets:
-
-| Secret                  | Used by                  | Purpose                              |
-|-------------------------|--------------------------|--------------------------------------|
-| `CLOUDFLARE_API_TOKEN`  | `deploy-cf.yml`          | Authenticates `wrangler deploy`.     |
-| `CLOUDFLARE_ACCOUNT_ID` | `deploy-cf.yml`          | Disambiguates account context.       |
-
-And one **Actions variable**:
-
-| Variable       | Purpose                                                    |
-|----------------|------------------------------------------------------------|
-| `CF_SMOKE_URL` | `wss://` URL the smoke e2e step hits. If unset, smoke is skipped with a warning. |
-
-Configure both under repo **Settings → Secrets and variables → Actions**.
-
----
-
-## 9. Sharding
-
-### 9.1 How nick registry sharding works
-
-The `RegistryDO` fleet is sharded so no single DO becomes a hot spot
-for popular nicknames. Shard assignment is:
-
-```
-shard = fnv1a32(lowercased(nick)) mod N
-```
-
-Properties (see `packages/cf-adapter/src/sharding.ts` for full rationale):
-
-- **Deterministic** — every Worker instance computes the same shard for
-  a given nick with zero coordination.
-- **Case-insensitive** — `Alice`, `alice`, and `ALICE` collide in the
-  same shard, so the single-shard uniqueness check covers all RFC 1459
-  case variants.
-- **Synchronous & dependency-free** — runs on every nick reservation,
-  so no `await` and no external hash library.
-
-The shard id (`s0`, `s1`, …, `s31`) becomes the `idFromName()` key for
-that nick's `RegistryDO`. Two clients racing on `Alice` both route to
-`RegistryDO s7`, where DO single-threadedness makes the uniqueness
-invariant **structural** rather than optimistic.
-
-### 9.2 `REGISTRY_SHARDS`
-
-The default fleet size is **32**, defined as
-`DEFAULT_REGISTRY_SHARDS` in
-`packages/cf-adapter/src/sharding.ts:42`. This is the value used by
-the production `CfRuntime` (`cf-runtime.ts:91`).
-
-> **Planned knob:** `sharding.ts` documents a future `REGISTRY_SHARDS`
-> environment variable (see the doc comment at line 39). That override
-> path is **not yet wired** through `Env` / `ConnectionDO` — the shard
-> count is currently a code-level default. Once TICKET-047 (config
-> schema) ships, this will become a true env var. Until then, changing
-> the shard count requires a code edit in `cf-runtime.ts`.
-
-### 9.3 Re-sharding caveat
-
-**Changing `REGISTRY_SHARDS` after the DOs hold data is a migration.**
-Existing nick→connId mappings live in the *old* shard layout; the new
-layout will not find them. Plan a migration window:
-
-1. Drain live connections (announce + reconnect window), or accept that
-   in-flight nick reservations during the cutover can briefly succeed
-   against both layouts.
-2. Iterate the old shard range, read each `nick→connId` entry, and write
-   it to the shard computed under the new `N`.
-3. Verify with a sample of known nicks before re-enrolling write traffic.
-
-There is **no in-repo re-sharding tool** today (post-v1 work). For v1
-deployments the recommendation is: pick `REGISTRY_SHARDS` once, and
-prefer over-provisioning (64 or 128) if you anticipate >10k concurrent
-users — the per-shard cost is negligible because hibernated DOs are
-free to hold.
-
----
-
-## 10. Cost notes
-
-Cloudflare bills Durable Objects on three dimensions (figures below are
-the public list price as of 2024-11; verify current pricing at
-<https://developers.cloudflare.com/durable-objects/platform/pricing/>):
-
-| Dimension                  | Notes for ServerlessIRCd                              |
-|----------------------------|-------------------------------------------------------|
-| **Duration** (GB-second)   | Hibernation (`HibernatingWebSocketHandler`) drops idle connections to ~zero memory while asleep. A 10k-user deployment with most connections idle is the entire reason this adapter exists. |
-| **Requests**               | Each WebSocket frame in/out is a request. PRIVMSG to a 1k-member channel fans out via the ChannelDO; each member's `ConnectionDO.deliver()` is one request. |
-| **DO storage** (MB-month)  | ConnectionState is small (a few KB). Channel roster / modes are small per channel. The Nicks registry is the only fleet that grows linearly with MAU. |
-
-Practical numbers:
-
-- **Workers Free plan**: sufficient to bring up staging, exercise the
-  smoke e2e, and validate a handful of concurrent connections. Not
-  suitable for production traffic (request caps, no reserved DO
-  compute).
-- **Workers Paid plan** (USD $5/mo base + usage): enough headroom for a
-  small production network. The dominant cost driver at scale is
-  **fanout requests on hot channels**, not connection count — thanks to
-  hibernation. Plan accordingly for channels with >1k members.
-
-Other billable surfaces (all optional for v1):
-
-- **Workers KV** — not used today; planned for MOTD / config offload.
-- **D1** — not used today; planned for account/SASL persistence.
-- **Workers Analytics** — free tier covers basic dashboards.
-
-See PLAN §10 (Risk / Cost) for the scaling ceilings and post-v1
-mitigations (batched fanout, per-channel send-list cache).
-
----
-
-## 11. CI/CD
-
-The GitHub Actions workflow at `.github/workflows/deploy-cf.yml`
-deploys staging on every push to `main` and replays the smoke e2e. It
-is the canonical deploy path — manual `pnpm deploy:cf:staging` is for
-iteration only.
-
-Steps performed by the workflow (in order):
-
-1. Checkout (frozen lockfile).
-2. Install pnpm 9 + Node 20.
-3. `pnpm install --frozen-lockfile`.
-4. `pnpm build` — builds all workspace packages.
-5. `pnpm typecheck` and `pnpm test` — gate the deploy.
-6. `pnpm deploy:cf:staging` — `wrangler deploy --env staging`.
-7. Resolve the smoke URL from the `CF_SMOKE_URL` repo variable. If
-   unset, the smoke step is skipped with a warning.
-8. Run `node scripts/smoke.mjs --url "$SMOKE_URL"`. Failure fails the
-   build.
-
-Concurrency is serialized via `concurrency.group: cf-staging` so two
-deploys cannot race the same DO namespace.
-
-Required repo configuration (under Settings → Secrets and variables →
-Actions):
-
-- **Secret `CLOUDFLARE_API_TOKEN`** — required.
-- **Secret `CLOUDFLARE_ACCOUNT_ID`** — required if the token's account
-  context is ambiguous.
-- **Variable `CF_SMOKE_URL`** — set to the staging Worker's `wss://`
-  URL. Without it, the smoke step silently no-ops.
-
-There is **no auto-deploy to production**. Production deploys are
-intentionally manual (`pnpm deploy:cf:prod` from a clean checkout on
-`main`).
-
----
-
-## 12. Troubleshooting
-
-### 12.1 `wrangler deploy` fails with `Migration tag has already been applied`
-
-The on-disk migration list in `wrangler.toml` doesn't match the live
-Worker state. If you previously deployed `tag = "v1"` and then edited
-the `[[migrations]]` block, wrangler refuses to proceed.
-
-- If you intentionally changed the DO schema, append a new
-  `[[migrations]]` block with `tag = "v2"` (and `renamed_classes` /
-  `deleted_classes` as needed). Never edit an already-applied `tag`.
-- If the staging namespace has stale state from an aborted experiment,
-  you can destroy and recreate it from the dashboard (Workers & Pages →
-  Durable Objects → namespaces). **Production namespaces must never be
-  deleted** — that data is gone permanently.
-
-### 12.2 `Cannot find module '@serverless-ircd/cf-adapter'`
-
-The workspace packages weren't built. Run `pnpm build` from the repo
-root before `wrangler deploy`. The Worker entry imports compiled
-`dist/` from `irc-core`, `irc-server`, and `cf-adapter`.
-
-### 12.3 Smoke e2e times out waiting for `001`
-
-The connection upgrade succeeded but registration didn't complete.
-Common causes:
-
-- The deployed Worker is reachable but the DO threw on the first frame.
-  Tail the logs: `wrangler tail --env staging` and reproduce.
-- The `MOTD_LINES` or `SERVER_NAME` var was deleted — `ConnectionDO`'s
-  `serverConfig()` falls back to defaults, but a malformed value can
-  break parsing. Check the `[env.staging.vars]` block.
-- Client connected over `ws://` to a Worker that requires `wss://`.
-  Use the `wss://` URL the deploy step printed.
-
-### 12.4 `wrangler tail` shows `alarm() threw`
-
-The DO alarm fired but the handler threw. The most likely cause is a
-stale persisted-state version after a code change; the serializer in
-`packages/cf-adapter/src/serialize.ts` carries `PERSISTED_STATE_VERSION`
-and will reject incompatible blobs. If this happens after an upgrade,
-ship a `deserialize` migration that upgrades the old version (or, on
-staging, clear the DO storage from the dashboard).
-
-### 12.5 Nick reservation always fails
-
-A client's `NICK` command always returns `433 ERR_NICKNAMEINUSE`, even
-for nicknames that should be free. This happens when two deployments
-share a `RegistryDO` namespace but were supposed to be separate —
-e.g., staging and production point at the same DO class name. Verify
-that each environment has its own DO namespace (the Worker name
-differs: `serverless-ircd` vs `serverless-ircd-staging`, and wrangler
-allocates a distinct namespace per Worker).
-
-### 12.6 High request cost / DO request spike
-
-Hot-channel fanout is the dominant cost driver. Each PRIVMSG to a
-channel of N members produces ~N `ConnectionDO.deliver()` RPC requests
-(one per member). Mitigations:
-
-- Cap channel size in application policy (no built-in cap today beyond
-  `+l` mode).
-- For very hot announcement channels, consider a future batched-fanout
-  path (post-v1 — PLAN §10).
-
-Reach for the Workers Analytics dashboard to identify the channel
-driving the spike before optimizing.
-
-### 12.7 Lost connection state after a deploy
-
-DO storage persists across Worker code deploys by design. If state
-appears lost, either:
-
-- The DO namespace was deleted (irreversible — see 12.1).
-- A `[[migrations]]` rename or split moved the data to a different
-  class id without a migration entry mapping the old class to the new.
-- The persisted-state version changed without a deserialize migration
-  (see 12.4).
-
-For staging, the fastest recovery is usually to clear DO storage and
-re-test. For production, treat any migration tag change as a release
-blocker requiring a runbook entry.
-
----
-
-## 13. Quick reference
-
-```bash
-# One-time account setup
-npx wrangler login                              # or set CLOUDFLARE_API_TOKEN
-
-# Local dev
-pnpm install
-pnpm build
-pnpm --filter @serverless-ircd/cf-worker dev    # http://localhost:8787
-node apps/cf-worker/scripts/smoke.mjs           # smoke against localhost
-
-# Staging
-pnpm deploy:cf:staging
-node apps/cf-worker/scripts/smoke.mjs \
-  --url wss://serverless-ircd-staging.<subdomain>.workers.dev
-npx wrangler tail --env staging                 # live logs
-
-# Production (manual only)
-pnpm deploy:cf:prod
-npx wrangler tail                               # default env = production
-
-# Tests / lint
-pnpm test                                       # full workspace
-pnpm --filter @serverless-ircd/cf-adapter test
-pnpm --filter @serverless-ircd/cf-worker test
-pnpm lint
-```
-
-Key files:
-
-| Path                                    | What                                         |
-|-----------------------------------------|----------------------------------------------|
-| `apps/cf-worker/wrangler.toml`          | Deploy config, DO bindings, migrations.      |
-| `apps/cf-worker/src/worker.ts`          | Edge fetch handler; re-exports DO classes.   |
-| `apps/cf-worker/scripts/smoke.mjs`      | CI + local smoke e2e.                        |
-| `packages/cf-adapter/src/`              | `ConnectionDO`, `RegistryDO`, `ChannelDO`, `CfRuntime`, sharding. |
-| `packages/cf-adapter/src/sharding.ts`   | Shard function + `DEFAULT_REGISTRY_SHARDS`.  |
-| `packages/cf-adapter/src/env.ts`        | `Env` interface (binding contract).          |
-| `.github/workflows/deploy-cf.yml`       | Staging deploy + smoke e2e CI.               |

package/docs/Home.md

@@ -1 +0,0 @@
-Welcome to the Wiki.