serverless-ircd 0.5.0 → 0.6.0

package/docs/AWS-Deployment.md

@@ -0,0 +1,1275 @@
+# AWS Deployment Guide
+
+End-to-end guide for deploying ServerlessIRCd to AWS (Phase 4 of the
+project plan). Covers prerequisites, first-time AWS setup, local
+development, staging and production deploys, configuration reference,
+DynamoDB capacity planning, region strategy, cost notes, CI/CD, and
+troubleshooting.
+
+Cross-reference: the AWS Adapter Architecture doc
+(`../../ServerlessIRCd/docs/AWS-Adapter-Architecture.md`) for the
+diagrams referenced throughout, and the Cloudflare Deployment Guide
+(`../../ServerlessIRCd/docs/Cloudflare-Deployment-Guide.md`) for the
+equivalent flow on the other supported platform. The shared
+`irc-core`/`irc-server` packages and the contract test suite are
+identical between platforms; only the I/O shell (this stack) differs.
+
+Key in-repo paths cited below:
+
+| Path                                              | What                                          |
+|---------------------------------------------------|-----------------------------------------------|
+| `apps/aws-stack/src/aws-stack.ts`                 | CDK stack — tables, Lambdas, APIGW, schedules.|
+| `apps/aws-stack/bin/aws.ts`                       | CDK app entry. Stack id is `IrcAwsStack`.     |
+| `apps/aws-stack/cdk.json`                         | `app = tsx bin/aws.ts`.                        |
+| `apps/aws-stack/scripts/smoke.mjs`                | CI + local smoke e2e.                         |
+| `apps/aws-stack/tests/stack.test.ts`              | Synth-time assertions (cross-check for facts).|
+| `packages/aws-adapter/src/cdk-table-defs.ts`      | Five DynamoDB table shapes.                   |
+| `packages/aws-adapter/src/config-loader.ts`       | Lambda env → `ServerConfig` mapping.          |
+| `packages/aws-adapter/src/handlers/index.ts`      | Lambda entry (`handler`, `sweeperHandler`, `pingCheckerHandler`). |
+| `.github/workflows/deploy-aws.yml`                | Staging deploy + smoke e2e CI.                |
+
+**Acceptance criterion:** a new contributor can deploy their own
+staging instance following only this doc.
+
+---
+
+## 1. What gets deployed
+
+A single CDK v2 stack (`IrcAwsStack`) provisions the entire AWS
+substrate. There are no static assets — CloudFront and S3 are not part
+of this deployment. Every resource is regional.
+
+```
+   ┌──────────────────────────────────────────────────────────────────┐
+   │  CDK stack: IrcAwsStack  (apps/aws-stack/src/aws-stack.ts)       │
+   │                                                                  │
+   │  ┌─ WebSocketApi (AWS::ApiGatewayV2::Api)  ───────────────────┐  │
+   │  │   routes: $connect  $disconnect  $default                  │  │
+   │  │   → all three wired to IrcHandler                          │  │
+   │  │   stage: prod (auto-deploy)                                │  │
+   │  └────────────────────────────────────────────────────────────┘  │
+   │                           │                                      │
+   │                           ▼  WebSocket event per frame           │
+   │  ┌─ Lambda: IrcHandler ───────────────────────────────────────┐  │
+   │  │   handler export `handler` (Node 20, esbuild bundle)       │  │
+   │  │   entry: packages/aws-adapter/src/handlers/index.ts        │  │
+   │  │   dispatches on event.requestContext.routeKey              │  │
+   │  └────────────────────────────────────────────────────────────┘  │
+   │                                                                  │
+   │  ┌─ Lambda: IrcSweeper ───────────────────────────────────────┐  │
+   │  │   handler export `sweeperHandler`                          │  │
+   │  │   EventBridge schedule: rate(5 minutes)                    │  │
+   │  │   Scans Connections for rows past hard TTL; cleans up.     │  │
+   │  └────────────────────────────────────────────────────────────┘  │
+   │                                                                  │
+   │  ┌─ Lambda: IrcPingChecker ───────────────────────────────────┐  │
+   │  │   handler export `pingCheckerHandler`                      │  │
+   │  │   EventBridge schedule: rate(1 minute)                     │  │
+   │  │   Sends PING to idle connections; disconnects no-PONG.     │  │
+   │  └────────────────────────────────────────────────────────────┘  │
+   │                                                                  │
+   │  ┌─ DynamoDB (on-demand) ─────────────────────────────────────┐  │
+   │  │   Connections    (PK connectionId,     TTL idleSince)      │  │
+   │  │   ChannelMeta    (PK channelName)                          │  │
+   │  │   ChannelMembers (PK channelName, SK connectionId)         │  │
+   │  │   Nicks          (PK nickLower)                            │  │
+   │  │   Accounts       (PK account)                              │  │
+   │  └────────────────────────────────────────────────────────────┘  │
+   │                                                                  │
+   │  CfnOutput: ConnectUrl     = stage.url         (wss://…)         │
+   │  CfnOutput: ManagementUrl  = stage.callbackUrl (https://…)       │
+   └──────────────────────────────────────────────────────────────────┘
+```
+
+All IRC protocol logic lives in the shared `irc-core` reducers and the
+`irc-server` `ConnectionActor`. The Lambdas are a thin I/O shell: they
+forward WebSocket events into the actor and interpret the resulting
+`Effect[]` against DynamoDB and the API Gateway Management API. No IRC
+state is held in the Lambda process between invocations.
+
+The three Lambda functions share a single bundle (esbuild tree-shakes
+per handler export at synth time). They run on `nodejs20.x` and exclude
+`@aws-sdk/*` from the bundle because the AWS SDK v3 ships with the
+Lambda Node 20 runtime.
+
+Stack outputs (`CfnOutput`):
+
+| Output          | Value                       | Purpose                                            |
+|-----------------|-----------------------------|----------------------------------------------------|
+| `ConnectUrl`    | `wss://<id>.execute-api.<region>.amazonaws.com/prod` | WebSocket endpoint IRC clients dial. |
+| `ManagementUrl` | `https://<id>.execute-api.<region>.amazonaws.com/prod` | HTTPS endpoint for `ApiGatewayManagementApi.postToConnection`. |
+
+The same CloudFormation template serves both staging and production.
+The staging/production distinction today is which AWS account and
+region the stack is deployed into — there is no per-environment stack
+parameter (see §6 and §7.4 for the implications).
+
+---
+
+## 2. Prerequisites
+
+| Requirement         | Version / detail                                              |
+|---------------------|---------------------------------------------------------------|
+| Node.js             | ≥ 20 (matches CI; `engines.node` in root `package.json` and in `apps/aws-stack/package.json`). |
+| pnpm                | 9.x (`packageManager: pnpm@9.15.9` in root `package.json`).   |
+| AWS account         | IAM-permissioned to create CloudFormation stacks, IAM roles, API Gateway v2, Lambda, DynamoDB tables, and EventBridge rules. |
+| AWS credentials     | `aws configure`, `AWS_PROFILE`, or SSO. CDK reads the standard SDK chain. |
+| CDK v2              | Comes from `apps/aws-stack/devDependencies` (`aws-cdk ^2.160.0`) — no global install needed. Use `pnpm cdk` (or `pnpm cdk:synth`) so the local binary wins over any globally-installed CDK. |
+| CDK bootstrap       | `cdk bootstrap` must have been run **once** in the target account/region (see §3.3). |
+| Git checkout        | Clean working tree on `main` for production deploys.          |
+
+Confirm the local environment:
+
+```bash
+node --version          # v20.x or newer
+pnpm --version          # 9.x
+aws --version           # aws-cli/2.x (any 2.x is fine)
+pnpm install            # from repo root, installs the whole workspace
+pnpm build              # builds irc-core, irc-server, aws-adapter, aws-stack
+```
+
+`pnpm build` must succeed before `cdk deploy`: the `NodejsFunction`
+construct transpiles the handler entry with esbuild at synth time, and
+esbuild resolves `@serverless-ircd/*` workspace packages via their
+compiled `dist/` outputs.
+
+---
+
+## 3. First-time AWS setup
+
+These steps are done once per AWS account.
+
+### 3.1 Pick a region
+
+API Gateway WebSocket endpoints, DynamoDB, EventBridge Scheduler, and
+Lambda are all regional. WebSocket clients pay round-trip time to the
+region, so pick the one closest to your user base (see §10 for the
+full region discussion). Set it as your default:
+
+```bash
+export AWS_REGION=us-east-1   # or your nearest region
+```
+
+CDK picks the region up via `CDK_DEFAULT_REGION` (set automatically by
+the CDK CLI from the SDK chain).
+
+### 3.2 Configure credentials
+
+Three equivalent options:
+
+```bash
+# Static access key (simplest):
+aws configure
+# → prompts for Access Key ID, Secret Key, region, output format.
+
+# Named profile:
+export AWS_PROFILE=my-profile
+
+# SSO:
+aws sso login --profile my-sso-profile
+export AWS_PROFILE=my-sso-profile
+```
+
+Verify:
+
+```bash
+aws sts get-caller-identity
+```
+
+### 3.3 Bootstrap CDK
+
+CDK needs an S3 bucket + a few IAM roles per account/region to hold
+synthesized CloudFormation assets. Bootstrap once:
+
+```bash
+cd apps/aws-stack
+pnpm cdk bootstrap
+# → creates a CFN stack named CDKToolkit with the bootstrap bucket.
+```
+
+If you skip this, the first `cdk deploy` fails with a bucket-not-found
+error (see §13.1). Bootstrap is idempotent — re-running on an
+already-bootstrapped account is a no-op.
+
+### 3.4 Optional: set up OIDC for CI
+
+If you intend to use the GitHub Actions deploy workflow (§12) without
+long-lived access keys, configure GitHub OIDC:
+
+1. Create an IAM identity provider for `token.actions.githubusercontent.com`.
+2. Create a role with a trust policy granting
+   `sts:AssumeRoleWithWebIdentity` to your repo's `ref:refs/heads/main`.
+3. Attach a permission policy broad enough to manage the stack (IAM,
+   API Gateway v2, Lambda, DynamoDB, EventBridge, CloudFormation).
+4. Note the role ARN — it becomes the `AWS_DEPLOY_ROLE_ARN` secret in
+   CI. Static keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) are
+   the fallback; the workflow supports both.
+
+---
+
+## 4. Local development
+
+Unlike the Cloudflare adapter (which has `wrangler dev` against the
+real `workerd` runtime), the AWS adapter does not yet ship a
+hot-reload local Lambda/API Gateway emulator. The local dev loop is:
+
+1. **Synth-time assertions** (default `pnpm test`) — fast, no Docker.
+2. **Unit tests** for the handler, runtime, and access patterns under
+   `packages/aws-adapter/tests/`.
+3. **Optional localstack validation** — gated, requires Docker.
+
+### 4.1 Synth-time tests
+
+From the repo root:
+
+```bash
+pnpm --filter @serverless-ircd/aws-stack test
+# or, equivalently:
+pnpm test     # runs the whole workspace including aws-stack
+```
+
+These execute `Template.fromStack(...)` in-process — no AWS
+credentials, no Docker. Every assertion in
+`apps/aws-stack/tests/stack.test.ts` corresponds to a fact this guide
+states: five on-demand tables, three Node 20 Lambdas, the
+`$connect`/`$disconnect`/`$default` routes, the `prod` stage, the two
+`rate(...)` schedules, the two CfnOutputs, and least-privilege IAM
+(no `Action: "*"` or `Resource: "*"`).
+
+### 4.2 Synthesize the CloudFormation template
+
+```bash
+pnpm --filter @serverless-ircd/aws-stack cdk:synth
+# → writes cdk.out/<stack>.template.json
+```
+
+Inspecting `cdk.out/` is the fastest way to see exactly what will be
+deployed without touching AWS.
+
+### 4.3 Optional: validate against localstack
+
+A gated test (`apps/aws-stack/tests/localstack.test.ts`) runs
+`cdklocal synth` against a real localstack container and re-asserts
+the five-table shape. It is **skipped unless `LOCALSTACK=1` is set** so
+CI never depends on Docker. To run it locally:
+
+```bash
+# 1. Start localstack (requires Docker):
+docker run --rm -d -p 4566:4566 localstack/localstack
+
+# 2. Install the localstack-aware CDK CLI globally:
+npm install -g aws-cdk-local
+
+# 3. Point the AWS SDK at localstack (cdklocal reads these):
+export AWS_ACCESS_KEY_ID=test
+export AWS_SECRET_ACCESS_KEY=test
+export AWS_DEFAULT_REGION=us-east-1
+
+# 4. Run the gated test:
+LOCALSTACK=1 pnpm --filter @serverless-ircd/aws-stack test
+```
+
+### 4.4 Running the smoke script locally
+
+The smoke e2e (`apps/aws-stack/scripts/smoke.mjs`) defaults to
+`ws://localhost:8787`, inherited from the Cloudflare adapter's dev
+port. To smoke-test the AWS adapter locally you would need to stand up
+an API Gateway WebSocket emulator in front of the Lambda handler
+(sam-cli + localstack can do this); that wiring is not preconfigured.
+In practice, local iteration uses the unit + synth tests, and the
+smoke script is run against a deployed staging URL (§5.2) or against
+the Cloudflare adapter's local dev server when you're iterating on the
+shared protocol layer.
+
+---
+
+## 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:aws:staging
+# Equivalent to:
+#   pnpm --filter @serverless-ircd/aws-stack deploy:staging
+#   → cdk deploy --all --require-approval never
+```
+
+The first deploy of a given account/region will:
+
+1. Upload the esbuild-bundled handler asset to the CDK bootstrap S3
+   bucket.
+2. Create the `IrcAwsStack` CloudFormation stack.
+3. Provision five DynamoDB tables, three Lambda functions, one API
+   Gateway WebSocket API, one `prod` stage, two EventBridge rules,
+   least-privilege IAM roles, and the two stack outputs.
+4. Print the deployed URL on success — look for the `ConnectUrl`
+   output, e.g.
+   `wss://abc123.execute-api.us-east-1.amazonaws.com/prod`.
+
+A typical first deploy takes 2–4 minutes (DynamoDB table creation and
+API Gateway stage auto-deploy dominate).
+
+### 5.2 Verify with the smoke script
+
+```bash
+node apps/aws-stack/scripts/smoke.mjs \
+  --url wss://abc123.execute-api.us-east-1.amazonaws.com/prod
+```
+
+The script replays CONNECT → NICK/USER → JOIN #smoke → PRIVMSG → QUIT
+and asserts the server emits `001`, `376`, `353`, `366`, and closes
+the socket. Expected output on success:
+
+```json
+{"ts":"...","level":"info","msg":"aws-stack smoke e2e passed","url":"wss://..."}
+```
+
+On failure the script writes a `level: "error"` JSON line and exits
+non-zero, which is what the CI workflow gates on.
+
+### 5.3 Connect a real IRC client
+
+Point any RFC-compliant WebSocket-aware IRC client at the deployed
+`wss://` URL. For WeeChat:
+
+```
+/server add ircd abc123.execute-api.us-east-1.amazonaws.com/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 in the parent repo bridge a plain
+TCP IRC client to a WebSocket endpoint.
+
+---
+
+## 6. Deploy production
+
+The repo-level shortcut is:
+
+```bash
+pnpm deploy:aws:prod
+# Equivalent to:
+#   pnpm --filter @serverless-ircd/aws-stack deploy:prod
+#   → cdk deploy --all --require-approval never
+```
+
+**There is no separate production stack.** `deploy:prod` and
+`deploy:staging` run the identical CDK command — both deploy a stack
+named `IrcAwsStack` (hardcoded in `apps/aws-stack/bin/aws.ts`). The
+staging/production distinction is **which AWS account and region the
+stack is deployed into**, controlled by the credentials and
+`AWS_REGION` in the environment.
+
+For a real production deployment, before your first `pnpm deploy:aws:prod`:
+
+1. **Use a dedicated AWS account** (or at least a dedicated region) for
+   production. Do not point production credentials at the same stack
+   CI is deploying to on every push.
+2. **Change `RemovalPolicy.DESTROY` to `RemovalPolicy.RETAIN`** on the
+   five DynamoDB tables (see §9.4). The committed stack deletes all
+   data on `cdk destroy` — intentional for staging, dangerous for
+   production.
+3. **Set the server identity** (`SERVER_NAME`, `NETWORK_NAME`,
+   `MOTD`) — see §7.1. `SERVER_NAME` is required at boot; the stack
+   falls back to `irc.localhost` when the prop is omitted, which is
+   intentionally not production-ready.
+4. **Pick a region close to your users** (see §10).
+
+There is **no CI auto-deploy to production**. The deploy workflow
+(`deploy-aws.yml`) only triggers on push to `main` and targets
+staging. Production deploys are always manual from a clean checkout.
+
+---
+
+## 7. Configuration reference
+
+Server identity (`SERVER_NAME`, `NETWORK_NAME`, `MOTD`) and the logical
+environment name are CDK construct props on `IrcAwsStack`
+(`apps/aws-stack/src/aws-stack.ts`); pass them when instantiating the
+stack. All other deployment knobs still live in the stack source.
+Unlike the Cloudflare adapter (where config lives in a declarative
+`wrangler.toml`), AWS config is code — non-identity overrides require
+editing the stack and re-deploying.
+
+### 7.1 Server identity (construct props)
+
+The three identity values are sourced from `IrcStackProps` and joined
+to the env vars the Lambda config loader reads. `motdLines` is a
+`string[]`; the stack joins it with `\n` so the loader splits it back
+into one entry per IRC numeric (`375` / `372` / `376`):
+
+```ts
+// apps/aws-stack/src/aws-stack.ts (excerpt)
+const motd = (props.motdLines ?? DEFAULT_MOTD_LINES).join('\n');
+handler.addEnvironment('SERVER_NAME', serverName);
+handler.addEnvironment('NETWORK_NAME', networkName);
+handler.addEnvironment('MOTD', motd);
+```
+
+These three values are injected into the `IrcHandler` and
+`IrcPingChecker` Lambda environments at synth time. To override them,
+pass the construct props when creating the stack:
+
+```ts
+new IrcAwsStack(app, 'IrcAwsStack-production', {
+  environmentName: 'production',
+  serverName: 'irc.my.net',
+  networkName: 'MyNet',
+  motdLines: ['Welcome to my network.', 'Be excellent to each other.'],
+});
+```
+
+| Env var         | Purpose                                       | Committed default                              |
+|-----------------|-----------------------------------------------|------------------------------------------------|
+| `SERVER_NAME`   | Server name sent in `001`/`005` numerics. **Required** — the Lambda config loader fails fast with a readable error when unset. | `irc.localhost` (clearly-local fallback; pass an explicit `serverName` in production) |
+| `NETWORK_NAME`  | Network label in `005 NETWORK=…`.             | `ExampleNet`                                   |
+| `MOTD`          | Message-of-the-day. **Delimiter: `\n`** — the loader splits the value on every newline into one MOTD line. | Two-line banner (see note below). |
+
+> **MOTD delimiter contract:** the config loader
+> (`packages/aws-adapter/src/config-loader.ts`) splits `MOTD` on `\n`
+> to form the multi-line MOTD array. The CDK stack's `motdLines`
+> construct prop is a `string[]` joined with `\n`, so each array entry
+> becomes its own line and round-trips back through the loader into the
+> expected number of `motdLines`. Do **not** use a comma (or any other
+> character) as a separator — the loader treats it as literal line
+> content, collapsing the MOTD into a single line.
+
+### 7.2 Lambda runtime config (injected by CDK, do not edit)
+
+These env vars are wired automatically by the stack at synth time. Do
+not hand-set them in the console — the next `cdk deploy` will
+overwrite them.
+
+| Env var                | Source                                    | Consumed by                          |
+|------------------------|-------------------------------------------|--------------------------------------|
+| `MANAGEMENT_URL`       | `stage.callbackUrl` (CfnOutput `ManagementUrl`) | `IrcHandler`, `IrcPingChecker` (builds `ApiGatewayManagementApi` for `postToConnection`). |
+| `CONNECTIONS_TABLE`    | `Connections` (physical table name)       | All three Lambdas (`tablesConfigFromEnv`). |
+| `CHANNELMETA_TABLE`    | `ChannelMeta`                             | All three Lambdas.                   |
+| `CHANNELMEMBERS_TABLE` | `ChannelMembers`                          | All three Lambdas.                   |
+| `NICKS_TABLE`          | `Nicks`                                   | All three Lambdas.                   |
+| `ACCOUNTS_TABLE`       | `Accounts`                                | All three Lambdas.                   |
+| `AWS_REGION`           | Injected by the Lambda runtime, not CDK.  | `buildDepsFromEnv` (constructs the DynamoDB client). |
+
+The `tablesConfigFromEnv` helper
+(`packages/aws-adapter/src/handlers/index.ts:226`) throws on cold
+start if any of the five `<NAME>_TABLE` vars is missing. The smoke
+timeout in §13.2 traces back to this.
+
+### 7.3 Optional config-loader env vars (read if present)
+
+The shared config loader (`packages/aws-adapter/src/config-loader.ts`)
+also reads these optional env vars and feeds them through the shared
+Zod `ServerConfig` schema. **The committed CDK stack does not inject
+any of them** — to enable one, add an `addEnvironment(...)` line in
+`aws-stack.ts` and re-deploy.
+
+| Env var                   | Type    | Schema field          |
+|---------------------------|---------|-----------------------|
+| `MAX_CLIENTS`             | int     | `maxClients`          |
+| `CHANNEL_PREFIXES`        | string  | `channelPrefixes`     |
+| `OPER_USER`               | string  | `operCreds[0].user`   |
+| `OPER_PASSWORD`           | string  | `operCreds[0].password` |
+| `MAX_CHANNELS_PER_USER`   | int     | `maxChannelsPerUser`  |
+| `MAX_TARGETS_PER_COMMAND` | int     | `maxTargetsPerCommand`|
+| `NICK_LEN`                | int     | `nickLen`             |
+| `CHANNEL_LEN`             | int     | `channelLen`          |
+| `TOPIC_LEN`               | int     | `topicLen`            |
+| `MAX_LIST_ENTRIES`        | int     | `maxListEntries`      |
+| `QUIT_MESSAGE`            | string  | `quitMessage`         |
+| `SASL_ACCOUNTS`           | string  | `saslAccounts`        |
+
+`SASL_ACCOUNTS` is the legacy/config fallback (newline-delimited
+`username:password` pairs); it is used only when the `Accounts` table is
+empty. When the table has rows it is authoritative — see §8.1.
+
+Invalid values cause a readable boot-time error — the Lambda will
+throw on the first invocation (cold start). Test changes locally with
+`pnpm --filter @serverless-ircd/aws-adapter test`.
+
+### 7.4 No per-environment stack parameter
+
+There is no `stageName` or `environmentType` parameter on the CDK
+stack. The stack name (`IrcAwsStack`), table names
+(`Connections`, `ChannelMeta`, `ChannelMembers`, `Nicks`, `Accounts`),
+API Gateway stage name (`prod`), and Lambda construct ids are all
+hardcoded. To run staging and production in **the same AWS account**,
+you would need to fork the stack to parameterize these names; the
+recommended path is to use separate accounts (or separate regions) for
+staging vs production. This is the same architectural choice the
+Cloudflare adapter makes (staging and production are separate Worker
+namespaces).
+
+### 7.5 Lambda runtime and bundling
+
+| Knob              | Value                                                      |
+|-------------------|------------------------------------------------------------|
+| Runtime           | `nodejs20.x` (`Runtime.NODEJS_20_X`).                      |
+| Entry             | `packages/aws-adapter/src/handlers/index.ts` (computed by `handlerEntry()` in `aws-stack.ts`). |
+| Handler exports   | `IrcHandler` → `handler`; `IrcSweeper` → `sweeperHandler`; `IrcPingChecker` → `pingCheckerHandler`. |
+| Bundler           | esbuild (via `NodejsFunction`).                            |
+| External modules  | `@aws-sdk/*` (ships with the runtime; keeps the bundle small). |
+| Memory / timeout  | CDK defaults (128 MB / 3 s). Override via `memorySize`/`timeout` props if you observe cold-start or fanout timeouts. |
+
+### 7.6 API Gateway stage
+
+| Knob              | Value                                                      |
+|-------------------|------------------------------------------------------------|
+| Stage name        | `prod` (hardcoded as `STAGE_NAME` in `aws-stack.ts`).     |
+| Auto-deploy       | `true` (changes propagate without a manual deployment).   |
+| Auth on `$connect`| None today (no authorizer). See §13.5.                    |
+| Route responses   | Default (`$connect` returns 200 → upgrade; `$default` and `$disconnect` are fire-and-forget). |
+
+---
+
+## 8. Secrets
+
+**As of v1 the Lambda consumes no Secrets-Manager/SSM bindings.** Server
+password and oper creds are handled by later hardening work; when they
+ship, the natural homes are AWS Secrets Manager or SSM Parameter Store
+(the AWS adapter architecture doc calls both out as supporting
+services). SASL account credentials, however, **are** persisted — in the
+`Accounts` DynamoDB table (see §8.1).
+
+When secrets land, the typical pattern will be:
+
+1. Create the secret in Secrets Manager (or a `SecureString`
+   parameter in SSM).
+2. Grant the Lambda role `secretsmanager:GetSecretValue` (or
+   `ssm:GetParameter`) scoped to that one secret ARN.
+3. Read it inside `buildDepsFromEnv` (cold start) — never inside the
+   per-frame hot path.
+
+```bash
+aws secretsmanager create-secret \
+  --name serverless-ircd/staging/SERVER_PASSWORD \
+  --secret-string "$(openssl rand -base64 32)"
+```
+
+### 8.1 SASL accounts (`Accounts` table + seed tooling)
+
+SASL PLAIN credentials live in the `Accounts` DynamoDB table as
+`HashedAccountCredential` rows — `{ account, algorithm, salt, hash }`,
+all strings, with scrypt hashes encoded as base64 (never plaintext).
+At Lambda cold start, `buildDepsFromEnv` → `resolveAccountStore`
+scans the table once and pre-loads every row into a
+`DynamoAccountStore`; the synchronous `verify()` called from the SASL
+reducer works against that in-memory snapshot. The snapshot is rebuilt
+on every cold start, so account changes take effect within one cold
+start (seconds to minutes).
+
+**Precedence** (`resolveAccountStore`, in `account-store.ts`):
+
+1. The `Accounts` table is **authoritative when it has ≥1 row** — the
+   table wins and the config seed is ignored.
+2. When the table is empty, the adapter falls back to the
+   `SASL_ACCOUNTS` env var (newline-delimited `username:password` pairs,
+   see §7.3) so existing deployments keep working without migrating.
+3. When neither source has accounts, no `AccountStore` is bound and
+   `AUTHENTICATE PLAIN` returns `904 ERR_SASLFAIL`.
+
+**Seed / CRUD tooling.** Provision accounts by writing
+`HashedAccountCredential` rows produced by `hashAccountCredential`
+(scrypt, random salt, base64-encoded). The adapter exports
+`putAccountCredential(docClient, tableName, username, password)`
+for this — a repeat call for the same `username` overwrites the row
+(the PK is `account`). A minimal seeding snippet (Node 20, from the repo
+root):
+
+```bash
+node --input-type=module -e '
+  import { createDynamoDocumentClient, putAccountCredential } from "@serverless-ircd/aws-adapter";
+  const dynamo = createDynamoDocumentClient({ region: "us-east-1" });
+  await putAccountCredential(dynamo, "StagingAccounts", "alice", "change-me");
+  console.log("seeded alice");
+'
+```
+
+A repo-local seed script (`tools/seed-aws-accounts.ts`) wraps the same
+calls for batch provisioning:
+
+```bash
+# Seed against DynamoDB Local:
+npx tsx tools/seed-aws-accounts.ts \
+  --table StagingAccounts \
+  --endpoint http://localhost:8000 \
+  --accounts alice:s3cret bob:password2
+
+# Or from a file (newline-delimited username:password):
+npx tsx tools/seed-aws-accounts.ts \
+  --table StagingAccounts \
+  --region us-east-1 \
+  --file accounts.txt
+```
+
+For a one-off `aws-cli` write, hash the password out-of-band and put the
+row directly:
+
+```bash
+# Hash with the adapter, then write the row yourself:
+aws dynamodb put-item \
+  --table-name StagingAccounts \
+  --item '{"account":{"S":"alice"},"algorithm":{"S":"scrypt"},"salt":{"S":"<base64-salt>"},"hash":{"S":"<base64-hash>"}}'
+```
+
+> The `Accounts` table is granted to all three Lambdas (`handler`,
+> `sweeper`, `pingChecker`) via `grantReadWriteData`; only the handler
+> reads it at cold start. The sweeper/ping-checker never touch SASL
+> state, but sharing the grant keeps the IAM story uniform.
+
+**Never** put credentials, password hashes, or API tokens in
+`aws-stack.ts`, in Lambda env vars, or in committed files. Lambda env
+vars are visible in the console and in CloudFormation describe output;
+they are not secret.
+
+The CI deploy uses **GitHub Actions secrets** plus an optional repo
+variable (see §12):
+
+| Secret                  | Used by           | Purpose                                                       |
+|-------------------------|-------------------|---------------------------------------------------------------|
+| `AWS_ACCESS_KEY_ID`     | `deploy-aws.yml`  | Static access key for CDK deploy. Required unless OIDC is used. |
+| `AWS_SECRET_ACCESS_KEY` | `deploy-aws.yml`  | Companion secret key. Required unless OIDC is used.           |
+| `AWS_DEPLOY_ROLE_ARN`   | `deploy-aws.yml`  | Optional. When set, the job assumes this role via OIDC web identity instead of using static keys. |
+| `AWS_REGION`            | `deploy-aws.yml`  | Region to deploy into (e.g. `us-east-1`).                     |
+
+| Variable        | Purpose                                                              |
+|-----------------|---------------------------------------------------------------------|
+| `AWS_SMOKE_URL` | Optional. `wss://` URL for the smoke e2e step. If unset, the workflow falls back to reading the stack's `ConnectUrl` CloudFormation output via the AWS CLI; if that also fails the smoke step is skipped with a warning. |
+
+Configure all of these under repo **Settings → Secrets and variables
+→ Actions**.
+
+---
+
+## 9. DynamoDB capacity planning
+
+### 9.1 All five tables run on-demand
+
+Every table is created with `BillingMode.PAY_PER_REQUEST` (asserted in
+`apps/aws-stack/tests/stack.test.ts:45`). On-demand pricing charges
+per request:
+
+- **Write request units (WRU)** — one WRU = one write of up to 1 KB
+  (or 2 WRU for a strongly-consistent write of up to 1 KB). A
+  conditional write that fails (e.g. `attribute_not_exists` rejects a
+  nick collision) still costs 1 WRU.
+- **Read request units (RRU)** — one RRU = one eventually-consistent
+  read of up to 4 KB (or 2 RRU for strongly consistent).
+
+There is no minimum spend and no capacity to plan at deploy time.
+This is intentional for v1 — it removes a class of
+`ProvisionedThroughputExceededException` failure modes. See §11 for
+the cost trade-off and when to consider provisioned capacity.
+
+### 9.2 Schema and access patterns
+
+Five tables (defined in
+`packages/aws-adapter/src/cdk-table-defs.ts`):
+
+| Table           | PK (HASH)         | SK (RANGE)       | TTL         | Hottest access pattern                                   |
+|-----------------|-------------------|------------------|-------------|----------------------------------------------------------|
+| `Connections`   | `connectionId`    | —                | `idleSince` | `GetItem`/`UpdateItem` on every frame; `Scan` by sweeper. |
+| `ChannelMeta`   | `channelName`     | —                | —           | `GetItem`/`UpdateItem` on MODE/TOPIC/KICK. Low volume.   |
+| `ChannelMembers`| `channelName`     | `connectionId`   | —           | **`Query` on every channel PRIVMSG for fanout.** Hottest. |
+| `Nicks`         | `nickLower`       | —                | —           | `PutItem` (conditional) on NICK; `GetItem` on PRIVMSG to a nick. |
+| `Accounts`      | `account`         | —                | —           | `GetItem` on SASL AUTHENTICATE. Cold most of the time.   |
+
+Uniqueness invariants are enforced structurally (not in application
+code):
+
+- `Nicks.PK = nickLower` — conditional `PutItem` with
+  `attribute_not_exists(PK)` makes nick reservation atomic across
+  concurrent Lambdas. Two clients racing on `Alice` both get evaluated
+  against the same row; exactly one wins.
+- `ChannelMembers` PK+SK composite — `TransactWriteItems` for JOIN/PART
+  updates `Connections.joined` and `ChannelMembers` in one atomic
+  write (up to 100 items per transaction, the AWS limit).
+- `Accounts` row schema — `{ account (PK), algorithm, salt, hash }`,
+  all strings. `algorithm` is `'scrypt'`; `salt` and `hash` are
+  base64-encoded. Never plaintext. SASL PLAIN verifies against this
+  hash server-side. Seed rows with `putAccountCredential` (see §8.1).
+
+### 9.3 The hottest pattern: channel fanout
+
+Channel PRIVMSG is the dominant cost driver. There is no long-lived
+per-channel process (contrast with the Cloudflare adapter's
+`ChannelDO`). Fanout is computed per message:
+
+1. The reducer emits `Broadcast("#chan", [line], except=sender)`.
+2. `AwsRuntime.broadcast()` issues a `Query` on `ChannelMembers` with
+   `PK = "#chan"` → returns one row per member.
+3. For each member, the Lambda calls
+   `ApiGatewayManagementApi.postToConnection(member, line)`.
+
+That's O(members) Management API calls per message. A 100-member
+channel receiving one PRIVMSG per second produces ~100 `postToConnection`
+calls/second and one `Query`/second. A 1k-member announcement channel
+at the same rate produces ~1k calls/second. Mitigations (batched
+postToConnection, per-channel send-list cache, a dedicated fanout
+Lambda) are deferred to post-v1; the load-test ticket will surface
+the ceiling.
+
+### 9.4 Removal policy (IMPORTANT)
+
+The stack sets `RemovalPolicy.DESTROY` on every table:
+
+```ts
+// apps/aws-stack/src/aws-stack.ts:48
+const tables = Object.entries(TABLE_DEFS).map(
+  ([logicalId, tableProps]) =>
+    new Table(this, logicalId, { ...tableProps, removalPolicy: RemovalPolicy.DESTROY }),
+);
+```
+
+**This means `cdk destroy` deletes every table and all of its data.**
+This is intentional for staging (you want a clean teardown between
+experiments) and **dangerous for production**.
+
+For production, fork the stack to use `RemovalPolicy.RETAIN` (or
+`RETAIN_ON_UPDATE`): tables become orphans on stack deletion and keep
+their data. There is no built-in knob for this today — it requires
+editing `aws-stack.ts`. Recommendation: ship a `production: boolean`
+stack prop in a future change that flips the removal policy. Flagged
+in §15.
+
+### 9.5 TTL on `Connections.idleSince`
+
+The `Connections` table carries a DynamoDB TTL attribute (`idleSince`),
+asserted at synth time (`stack.test.ts:52`). The Lambda updates
+`idleSince` on every frame; DynamoDB silently deletes rows whose
+`idleSince` is older than the TTL window (typically within 48 hours of
+expiry, no SLA). This is a **safety net** for rows the sweeper misses.
+
+### 9.6 The gone-connection sweeper
+
+A second Lambda (`IrcSweeper`, handler export `sweeperHandler`) runs on
+an EventBridge schedule at `rate(5 minutes)`:
+
+```ts
+new Rule(this, 'SweeperSchedule', {
+  schedule: Schedule.rate(Duration.minutes(5)),
+  targets: [new LambdaFunction(sweeper)],
+});
+```
+
+Each tick `Scan`s the entire `Connections` table, identifies rows past
+a hard stale threshold, and runs the same cleanup path as
+`$disconnect` (delete memberships, release nicks, delete the row). The
+sweeper catches connections that vanished without APIGW emitting
+`$disconnect` (e.g. TCP RST that APIGW didn't observe).
+
+**Cost note:** `Scan` reads the **entire** table every 5 minutes. At
+1 KB per row, scanning 10k connections costs ~3 RRU (10k / 4 KB per
+RRU) per tick, ~864 ticks/day, ~2.6k RRU/day — negligible. At 100k
+connections it's ~26k RRU/day — still small but visible. A future
+optimization is to make the sweeper `Query` a sparse GSI keyed by
+`idleSince` instead of `Scan`.
+
+### 9.7 When to consider provisioned capacity
+
+Switch a table to `PROVISIONED` billing (with or without autoscaling)
+when its traffic is predictable and steady. The clearest signal is
+when the on-demand bill for a single table exceeds the cost of
+provisioned capacity for the same throughput — DynamoDB's pricing page
+breaks this out. In practice:
+
+- `ChannelMembers` is the first candidate (channel fanout dominates).
+- `Connections` is a poor candidate (spiky, cold-start-driven).
+- `Accounts`/`ChannelMeta`/`Nicks` are unlikely to need provisioned
+  capacity in any v1-size deployment.
+
+Switching billing modes is a no-downtime `UpdateTable` operation; the
+stack change is `billingMode: BillingMode.PROVISIONED` plus
+`readCapacity`/`writeCapacity` props.
+
+---
+
+## 10. Region strategy
+
+### 10.1 Everything is regional
+
+API Gateway WebSocket endpoints are regional. DynamoDB is regional.
+EventBridge Scheduler is regional. Lambda is regional. The stack
+deploys into exactly one region (the one your credentials resolve to
+via `CDK_DEFAULT_REGION`).
+
+WebSocket clients pay round-trip time to that region. A user in
+Frankfurt connecting to a `us-east-1` deployment will see ~90 ms RTT
+on every PRIVMSG roundtrip; the same user against `eu-central-1` will
+see ~10 ms. **Pick the region closest to your user base.**
+
+### 10.2 Recommendation: single-region for v1
+
+For v1, deploy in one region. There are no static assets (CloudFront
+and S3 are not part of this stack), so a CDN adds no value here.
+Single-region keeps the data model simple: the cross-table
+`TransactWriteItems` flows (§9.2) only work within one region.
+
+### 10.3 Multi-region is out of scope for v1
+
+If you ever need multi-region active-active, the considerations are:
+
+- **DynamoDB global tables** — replicate all five tables. Eventual
+  consistency across regions complicates the conditional-write
+  invariants (nick uniqueness, membership transactions): a nick
+  reserved in region A may not be visible in region B for a second or
+  two, allowing duplicate reservations. The reducer logic would need
+  to tolerate this.
+- **Per-region APIGW + Lambda** — each region runs the full stack;
+  clients are routed by DNS (Route 53 latency-based routing).
+- **Session affinity** — a client's `connectionId` is regional. A
+  reconnect after the 2-hour APIGW cap must land on the same region
+  or treat the new connection as a fresh registration (re-NICK,
+  re-JOIN).
+
+This is post-v1 work; the AWS adapter architecture doc calls it out
+as an open question.
+
+### 10.4 Region pick shortlist
+
+For a globally distributed user base, the typical picks:
+
+- **US-East-1 (N. Virginia)** — newest services, cheapest, ~100 ms to
+  EU and ~150 ms to APAC. Default for the CI workflow's `AWS_REGION`.
+- **EU-West-1 (Ireland)** / **EU-Central-1 (Frankfurt)** — best for
+  EU users.
+- **AP-Northeast-1 (Tokyo)** / **AP-Southeast-1 (Singapore)** — best
+  for APAC users.
+
+---
+
+## 11. Cost notes
+
+All figures are the public AWS list price as of late 2024 — **always
+verify against the current AWS pricing page** before budgeting:
+
+- API Gateway WebSocket: <https://aws.amazon.com/apigateway/pricing/>
+- Lambda: <https://aws.amazon.com/lambda/pricing/>
+- DynamoDB: <https://aws.amazon.com/dynamodb/pricing/>
+- EventBridge: <https://aws.amazon.com/eventbridge/pricing/>
+
+### 11.1 Billable services
+
+| Service                  | Unit                                           | List price (late 2024)        |
+|--------------------------|------------------------------------------------|-------------------------------|
+| API Gateway WebSocket    | connection-minute                              | $0.80 / million               |
+| API Gateway WebSocket    | message (inbound or outbound)                  | $1.00 / million               |
+| Lambda                   | request                                        | $0.20 / million               |
+| Lambda                   | GB-second                                      | $0.0000166667 (≈ $0.0167 / GB-hour) |
+| DynamoDB on-demand       | write request unit (WRU)                       | $1.25 / million               |
+| DynamoDB on-demand       | read request unit (RRU)                        | $0.25 / million               |
+| EventBridge Scheduler    | event published                                | $1.00 / million               |
+| CloudWatch Logs          | GB ingested                                    | $0.50                         |
+
+The Lambda free tier (1M requests + 400k GB-seconds per month) covers
+a meaningful slice of a small staging deployment.
+
+### 11.2 Back-of-envelope: 100 concurrent users
+
+Assume a small staging deployment with 100 concurrent users, average
+5 messages/sec across all channels, each connection active for 1 hour,
+average Lambda invocation 50 ms at 128 MB:
+
+| Dimension                                | Estimate                              | Monthly cost (approx) |
+|------------------------------------------|---------------------------------------|-----------------------|
+| APIGW connection-minutes                 | 100 conn × 60 min × 24 h × 30 d = 4.32M conn-min | ~$3.50        |
+| APIGW messages (inbound + fanout)        | 5 msg/s × 86400 × 30 = 13M inbound, ~3× fanout | ~$50          |
+| Lambda invocations                       | ~1 per inbound + fanout ≈ 40M         | ~$8.00 (free tier offsets some) |
+| Lambda GB-seconds                        | 40M × 0.05 s × 0.125 GB = 250k GB-s   | ~$4.20                |
+| DynamoDB writes (Connections updates + ChannelMembers deltas) | ~5M WRU | ~$6.25                |
+| DynamoDB reads (fanout Queries + Connections GetItem) | ~30M RRU                  | ~$7.50                |
+| EventBridge events (sweeper + pingChecker) | 5-min + 1-min ticks ≈ 50k events    | <$0.10                |
+| CloudWatch Logs                          | ~5 GB                                 | ~$2.50                |
+
+**Rough total: ~$80/month** for a 100-concurrent-user staging
+deployment. The dominant cost is **APIGW messages** (inbound + the
+per-member fanout). The single biggest lever is channel size — a
+single 1k-member announcement channel can multiply the fanout cost by
+10×.
+
+### 11.3 Cost-trim levers
+
+- **Cap channel size** with `+l` mode (the existing MODE enforcement).
+- **Consider provisioned capacity** for `ChannelMembers` once traffic
+  is steady (§9.7).
+- **Shorten the sweeper cadence** if you can tolerate slower cleanup —
+  `rate(5 minutes)` is a balance; `rate(15 minutes)` cuts sweeper
+  cost 3× at the cost of slower gone-connection reaping.
+- **Tune Lambda memory** — 128 MB is the default and cheapest per
+  invocation, but a higher memory allocation can reduce duration
+  enough to win on GB-seconds.
+
+---
+
+## 12. CI/CD
+
+The GitHub Actions workflow at `.github/workflows/deploy-aws.yml`
+deploys staging on every push to `main` and replays the smoke e2e. It
+is the canonical deploy path — manual `pnpm deploy:aws:staging` is for
+iteration only.
+
+### 12.1 What the workflow does
+
+Steps performed (in order):
+
+1. Checkout.
+2. Install pnpm 9 + Node 20 (`cache: pnpm`).
+3. `pnpm install --frozen-lockfile`.
+4. `pnpm build` — builds all workspace packages.
+5. `pnpm typecheck` and `pnpm test` — gate the deploy.
+6. Configure AWS credentials (OIDC if `AWS_DEPLOY_ROLE_ARN` is set,
+   otherwise static keys).
+7. `pnpm deploy:aws:staging` → `cdk deploy --all --require-approval never`.
+8. Resolve the smoke URL: repo variable `AWS_SMOKE_URL` first, else
+   the stack's `ConnectUrl` CloudFormation output via
+   `aws cloudformation describe-stacks --stack-name IrcAwsStack`, else
+   skip the smoke step with a warning.
+9. `pnpm smoke:aws:staging -- --url "$SMOKE_URL"` — failure fails the
+   build.
+
+Concurrency is serialized via `concurrency.group: aws-staging`,
+`cancel-in-progress: false`, so two pushes cannot race the same
+CloudFormation stack.
+
+### 12.2 Required repo configuration
+
+Under **Settings → Secrets and variables → Actions**:
+
+- **Secret `AWS_ACCESS_KEY_ID`** — required unless OIDC.
+- **Secret `AWS_SECRET_ACCESS_KEY`** — required unless OIDC.
+- **Secret `AWS_DEPLOY_ROLE_ARN`** — optional; enables OIDC.
+- **Secret `AWS_REGION`** — required (e.g. `us-east-1`).
+- **Variable `AWS_SMOKE_URL`** — optional but recommended; the
+  workflow can fall back to the CFN output, but setting this variable
+  explicitly avoids the `describe-stacks` round-trip and the
+  possibility of a stale cached value after a redeploy.
+
+### 12.3 OIDC vs static keys
+
+The workflow supports both auth modes:
+
+```yaml
+- name: Configure AWS credentials
+  uses: aws-actions/configure-aws-credentials@v4
+  with:
+    aws-region: ${{ secrets.AWS_REGION }}
+    role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+```
+
+When `AWS_DEPLOY_ROLE_ARN` is set, the action assumes the role via
+OIDC web identity (requires `permissions.id-token: write`, which the
+workflow declares) and ignores the static keys. When unset, it falls
+back to the static access-key pair. OIDC is the recommended path for
+any deployment tied to a real AWS account — no long-lived credentials
+to rotate.
+
+### 12.4 No CI auto-deploy to production
+
+Production deploys are intentionally manual (`pnpm deploy:aws:prod`
+from a clean checkout on `main`, against separate credentials). The
+workflow's `on:` block only triggers on `push` to `main` and
+`workflow_dispatch`, both of which target staging.
+
+---
+
+## 13. Troubleshooting
+
+### 13.1 `cdk deploy` fails with bucket-not-found
+
+> `BUCKET_NAME_PARAMETER_<id> does not exist` or
+> `NoSuchBucket: The specified bucket does not exist`
+
+The CDK bootstrap stack hasn't been created in this account/region.
+
+```bash
+cd apps/aws-stack
+pnpm cdk bootstrap
+pnpm deploy:aws:staging
+```
+
+Bootstrap is idempotent and per-region — re-run it if you change
+regions.
+
+### 13.2 Lambda throws on cold start because of a missing env var
+
+Symptom: smoke e2e times out waiting for `001`; CloudWatch Logs for
+`IrcHandler` show an `Error: Missing env var CONNECTIONS_TABLE (table
+name for Connections)` (or one of the other four `<NAME>_TABLE` vars).
+
+The `tablesConfigFromEnv` helper throws on the first invocation if any
+of `CONNECTIONS_TABLE`, `CHANNELMETA_TABLE`, `CHANNELMEMBERS_TABLE`,
+`NICKS_TABLE`, `ACCOUNTS_TABLE` is missing. The CDK stack always
+injects these — if one is missing in the console, somebody hand-edited
+the Lambda config. Fix by re-deploying:
+
+```bash
+pnpm deploy:aws:staging
+```
+
+If the error mentions `MANAGEMENT_URL` being absent: that env var is
+optional at the loader level (`buildDepsFromEnv` tolerates its absence
+by setting `managementApi = null`), but the handler's fanout path will
+fail at the first `postToConnection`. Verify both `IrcHandler` and
+`IrcPingChecker` carry `MANAGEMENT_URL` in the console.
+
+### 13.3 Smoke e2e times out waiting for `001`
+
+The connection upgrade succeeded (the WebSocket `open` fired) but
+registration didn't complete. Common causes:
+
+- **The handler threw on the first frame.** Tail the logs:
+  ```bash
+  aws logs tail /aws/lambda/IrcHandler --follow
+  ```
+  and reproduce. Look for the cold-start `buildDepsFromEnv` throw
+  (§13.2) or an unexpected exception in `handleDefault`.
+- **The `prod` stage didn't deploy.** The stage is `autoDeploy: true`,
+  so this is rare, but verify the URL ends in `/prod` and that the
+  route is wired:
+  ```bash
+  aws apigatewayv2 get-routes --api-id <api-id>
+  ```
+  You should see three routes: `$connect`, `$disconnect`, `$default`.
+- **Client connected over plain `ws://`.** APIGW WebSocket stages only
+  accept `wss://`. Use the URL printed by `cdk deploy` (the
+  `ConnectUrl` output).
+
+### 13.4 `aws cloudformation describe-stacks` returns nothing in CI
+
+The workflow uses:
+
+```bash
+aws cloudformation describe-stacks \
+  --stack-name IrcAwsStack \
+  --query 'Stacks[0].Outputs[?OutputKey==`ConnectUrl`].OutputValue' \
+  --output text
+```
+
+to resolve the smoke URL. If this returns nothing, either:
+
+- **The stack name is wrong.** It's hardcoded as `IrcAwsStack` in
+  `apps/aws-stack/bin/aws.ts`. If you forked the stack to a different
+  name, the workflow's `--stack-name IrcAwsStack` won't find it.
+  Update the workflow or rename back.
+- **The deploy failed silently.** Check the prior `pnpm
+  deploy:aws:staging` step's exit code. `cdk deploy` with
+  `--require-approval never` can still fail on IAM or
+  CloudFormation errors.
+- **Wrong region.** The `describe-stacks` call uses `AWS_REGION` from
+  the secrets; it must match the region the stack was deployed into.
+
+The workflow prints a `::warning::` and skips the smoke step rather
+than failing the build — a silent skip is the failure mode to watch
+for.
+
+### 13.5 WebSocket client can't connect
+
+The `$connect` route is wired to `IrcHandler` and currently uses **no
+auth** (no authorizer). If the client gets a 4xx/5xx on the HTTP
+upgrade:
+
+- Verify the URL is the `ConnectUrl` output, not `ManagementUrl` (the
+  management endpoint rejects WebSocket upgrades).
+- Verify the `IrcHandler` Lambda has `execute-api:ManageConnections`
+  on this stage (the stack grants this via
+  `stage.grantManagementApiAccess(handler)`).
+- If you add an authorizer or IP allowlist later, the `$connect`
+  Lambda is the natural place to gate by source IP (read
+  `event.requestContext.connectionId` and
+  `event.requestContext.sourceIp`).
+
+### 13.6 DynamoDB table vanished after `cdk destroy`
+
+By design. The stack uses `RemovalPolicy.DESTROY` on every table
+(§9.4) so staging teardowns are clean. **Do not run
+`cdk destroy` against a production stack.** For production, fork the
+stack to `RemovalPolicy.RETAIN` before the first deploy; flagged in
+§15.
+
+### 13.7 High DynamoDB cost on `Connections`
+
+The gone-connection sweeper `Scan`s the entire `Connections` table
+every 5 minutes (§9.6). At very large scale this dominates the read
+bill. Short-term mitigation: increase the sweeper's `rate(...)` to
+`rate(15 minutes)` or `rate(30 minutes)` in `aws-stack.ts`. Long-term:
+add a sparse GSI keyed by `idleSince` and switch the sweeper to a
+`Query` against it (post-v1 work).
+
+### 13.8 Nick reservation always fails
+
+A client's `NICK` always returns `433 ERR_NICKNAMEINUSE`, even for
+nicks that should be free. Two deployments sharing the same DynamoDB
+table name space is the usual cause — e.g. you deployed `IrcAwsStack`
+twice into the same account/region with a forked stack name. The
+`Nicks` table name is hardcoded as `Nicks` (physical name), so two
+stacks in the same region collide on the same table. Use separate
+regions or fork the table-name prefix.
+
+---
+
+## 14. Platform limitations
+
+Architectural constraints of the API Gateway WebSocket + Lambda substrate
+that operators should be aware of. These are not bugs — they are
+consequences of the serverless transport choice (see ADR-005 and
+ADR-009 for the wss-only v1 decision and the dual-transport v1.x path).
+
+### 14.1 A Lambda `$default` invocation cannot close its own socket
+
+This is the most important platform limit to understand.
+
+When a client sends an IRC command that should terminate its own
+connection — `QUIT`, or a flood-control `Disconnect("Excess Flood")`,
+or a fatal protocol error — the `ConnectionActor` emits a `Disconnect`
+effect. On the Cloudflare adapter the bound `ConnectionDO` closes its
+WebSocket immediately. On AWS, **nothing closes the socket from within
+the `$default` Lambda invocation**. The `AwsRuntimeHandlers.disconnect`
+implementation in `packages/aws-adapter/src/handlers/default.ts` is
+deliberately a no-op:
+
+```ts
+disconnect: () => {
+  // No-op: a Lambda `$default` invocation cannot close its own APIGW
+  // socket. … See docs/AWS-Deployment.md §14.1.
+},
+```
+
+**Why.** API Gateway WebSocket connections are managed by the service,
+not by the Lambda compute. A Lambda handling a `$default` frame has no
+API to force-close the calling WebSocket synchronously — the
+`ApiGatewayManagementApi` client can *post* to a connection, but there
+is no `DeleteConnection` call available to the handling Lambda for its
+own socket. The connection stays open until APIGW observes a TCP/FIN
+(the client disconnects) or the 2-hour idle cap elapses.
+
+**What actually tears the connection down.** The canonical teardown
+path is the **`$disconnect` route** (`packages/aws-adapter/src/handlers/disconnect.ts`),
+which APIGW invokes asynchronously after the socket closes. That route
+runs `cleanupConnection` — deleting the `Connections` row, every
+`ChannelMembers` row owned by it, the nick reservation, and broadcasting
+the `QUIT` line to every peer sharing a channel (see §9.6 for the
+sweeper that catches connections which vanish without a `$disconnect`).
+
+So the effect-driven `Disconnect` **is not lost**: the actor's state
+mutations (nick release, roster deltas) are persisted by `handleDefault`
+before the invocation returns, and the eventual `$disconnect` route
+completes the fanout. The only observable gap is that the *socket*
+lingers between the `QUIT` command and the client (or APIGW) actually
+closing it. Well-behaved IRC clients close the socket themselves
+immediately after sending `QUIT`, so the window is sub-second.
+
+**Cross-connection disconnect is also a no-op.** `AwsRuntime.disconnect(remoteConn, reason)`
+(`packages/aws-adapter/src/aws-runtime.ts:183`) cannot directly close
+another connection's WebSocket either. Commands that remove a user from
+a channel (e.g. `KICK`) delete membership rows and fan out the line, but
+do not force-close the target's socket — the kicked client will not be
+disconnected until it observes its own removal (via the `KICK` message)
+and closes, or the ping-checker/sweeper reaps it after the idle window.
+
+### 14.2 Mitigations already in place
+
+The adapter ships three mechanisms that bound the gap left by the
+no-op `disconnect`:
+
+| Mechanism                                    | Where                                              | What it catches                                              |
+|----------------------------------------------|----------------------------------------------------|--------------------------------------------------------------|
+| `$disconnect` route                          | `handlers/disconnect.ts`                           | The normal case: client closes, APIGW emits `$disconnect`.   |
+| Gone-connection sweeper                      | `handlers/sweeper.ts`, `rate(5 minutes)` (§9.6)    | Connections that vanish without APIGW emitting `$disconnect`. |
+| Idle PING / disconnect                       | `handlers/ping-checker.ts`, `rate(1 minute)` (§9.6)| Connections that go idle; reaps after the no-PONG window.    |
+
+Together these ensure ghost rosters and stale nick reservations are
+reaped within minutes even when the transport cannot force-close.
+
+### 14.3 Future enhancement (not implemented)
+
+A possible mitigation for true synchronous force-close from within
+`$default` would be to emit an EventBridge event (or an SQS message)
+from the handler that a sidecar Lambda consumes to call
+`ApiGatewayManagementApi`'s connection-deletion path against the target
+`connectionId`. This would let `KICK`/flood-disconnect close the target
+socket without waiting for the idle window. This is **out of scope for
+v1** and is tracked as a future enhancement; file an ADR before
+implementing it, because it adds a second async hop and a new failure
+mode (the sidecar falling behind).
+
+---
+
+## 15. Quick reference
+
+```bash
+# One-time account setup (per region)
+aws configure                                     # or: export AWS_PROFILE=...
+cd apps/aws-stack && pnpm cdk bootstrap
+
+# Local dev
+pnpm install
+pnpm build
+pnpm --filter @serverless-ircd/aws-stack test     # synth-time assertions
+pnpm --filter @serverless-ircd/aws-stack cdk:synth # writes cdk.out/
+
+# Optional localstack validation (Docker required)
+docker run --rm -d -p 4566:4566 localstack/localstack
+npm install -g aws-cdk-local
+export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1
+LOCALSTACK=1 pnpm --filter @serverless-ircd/aws-stack test
+
+# Staging
+pnpm deploy:aws:staging
+node apps/aws-stack/scripts/smoke.mjs \
+  --url wss://<id>.execute-api.<region>.amazonaws.com/prod
+aws logs tail /aws/lambda/IrcHandler --follow     # live logs
+
+# Production (manual, separate credentials)
+pnpm deploy:aws:prod
+
+# Tests / lint
+pnpm test                                         # full workspace
+pnpm --filter @serverless-ircd/aws-adapter test
+pnpm --filter @serverless-ircd/aws-stack test
+pnpm lint
+```
+
+Key files:
+
+| Path                                              | What                                                |
+|---------------------------------------------------|-----------------------------------------------------|
+| `apps/aws-stack/src/aws-stack.ts`                 | CDK stack — all constructs and env-var wiring.      |
+| `apps/aws-stack/bin/aws.ts`                       | App entry. Hardcodes stack name `IrcAwsStack`.      |
+| `apps/aws-stack/cdk.json`                         | `app = tsx bin/aws.ts`.                              |
+| `apps/aws-stack/scripts/smoke.mjs`                | CI + local smoke e2e.                               |
+| `apps/aws-stack/tests/stack.test.ts`              | Synth-time assertions (cross-check for every fact). |
+| `packages/aws-adapter/src/cdk-table-defs.ts`      | Five DynamoDB table shapes (keys, billing, TTL).    |
+| `packages/aws-adapter/src/tables.ts`              | Runtime table-name + key-column constants.          |
+| `packages/aws-adapter/src/config-loader.ts`       | Lambda env → `ServerConfig` schema mapping.         |
+| `packages/aws-adapter/src/handlers/index.ts`      | Lambda entry points (`handler`, `sweeperHandler`, `pingCheckerHandler`). |
+| `.github/workflows/deploy-aws.yml`                | Staging deploy + smoke e2e CI.                      |
+
+### Known gaps flagged for follow-up
+
+These are facts the **code does not yet have an answer for**; the
+recommendations above are deployer guidance, not built-in knobs:
+
+1. **`RemovalPolicy.DESTROY` is hardcoded.** There is no stack prop to
+   flip it to `RETAIN` for production. Recommendation: a future change
+   adds a `production: boolean` (or similar) construct prop that
+   toggles the removal policy across all five tables.
+2. ~~**`SERVER_NAME` / `NETWORK_NAME` / `MOTD` are hardcoded in
+   `aws-stack.ts`.**~~ **Resolved** — these are now CDK construct props
+   (`serverName`, `networkName`, `motdLines`) on `IrcStackProps` (see
+   §7.1).
+3. ~~**MOTD multiline parsing.**~~ **Resolved** — the stack's
+   `motdLines` prop is a `string[]` joined with `\n`, which the config
+   loader splits back into one line per entry. The delimiter is `\n`
+   only; commas are treated as literal line content (see §7.1).
+4. **No per-environment stack parameter.** Staging and production
+   cannot coexist in the same account/region without forking the
+   stack to parameterize names. Recommendation: separate accounts for
+   staging vs production for v1.