serverless-ircd 0.8.0 → 0.9.0

package/apps/web/tests/landing-content.test.ts

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const landingSrc = path.join(pkgRoot, 'landing', 'index.html');
+
+// Pure-string assertions over landing/index.html. The file is copied verbatim
+// to dist/index.html by scripts/build.mjs (verified separately by
+// build-smoke.test.ts), so these checks run against the source in CI without
+// paying the Kiwi SPA build cost.
+const html = readFileSync(landingSrc, 'utf8');
+
+describe('landing page "Connect" section', () => {
+  it('contains a "Connect" heading', () => {
+    // The project front door must tell visitors how to reach the IRC server.
+    expect(html).toMatch(/<h2[^>]*>\s*Connect\s*<\/h2>/i);
+  });
+
+  it('documents the WeeChat client', () => {
+    expect(html).toMatch(/WeeChat/i);
+  });
+
+  it('documents the HexChat client', () => {
+    expect(html).toMatch(/HexChat/i);
+  });
+
+  it('documents the irssi client', () => {
+    expect(html).toMatch(/irssi/i);
+  });
+
+  it('documents the IRCCloud client', () => {
+    expect(html).toMatch(/IRCCloud/i);
+  });
+
+  it('documents TheLounge client', () => {
+    expect(html).toMatch(/TheLounge/i);
+  });
+
+  it('mentions the wss (secure WebSocket) transport for the web client', () => {
+    expect(html).toMatch(/\bwss\b/i);
+  });
+
+  it('mentions port 443 for the wss transport', () => {
+    expect(html).toMatch(/443\b/);
+  });
+
+  it('mentions the irc+tls :6697 direct-connect transport', () => {
+    expect(html).toMatch(/6697\b/);
+  });
+
+  it('hides the low-level WebSocket subprotocol framing detail', () => {
+    // The subprotocol negotiation + 510-byte frame budget is IRC-wire-level
+    // detail that doesn't belong on the project front door. It lives in the
+    // docs; the page should not surface `text.ircv3.net` or the 510 figure.
+    expect(html).not.toMatch(/text\.ircv3\.net/i);
+    expect(html).not.toMatch(/\b510\b/);
+  });
+
+  it('links to the Web Client Guide doc', () => {
+    // Cross-references to the docs/ subtree keep the page terse while still
+    // pointing at full instructions. The docs are out-of-tree (git submodule)
+    // so the link is a relative repo path, not a served route.
+    expect(html).toMatch(/WebClientGuide/i);
+  });
+
+  it('references the tcp-ws-forwarder bridge for stock TCP clients', () => {
+    expect(html).toMatch(/tcp-ws-forwarder/i);
+  });
+
+  it('uses a generic hostname placeholder (no per-env host baked in)', () => {
+    // The landing page is built once and served across staging + prod, so it
+    // must NOT pin a concrete worker hostname.
+    expect(html).toMatch(/irc\.example\.com|{{\s*hostname\s*}}|your deployed Worker host/i);
+  });
+
+  it('includes a WeeChat /server add snippet', () => {
+    expect(html).toMatch(/\/server add/i);
+  });
+
+  it('renders the connect instructions as a radio-backed client tab picker', () => {
+    // A horizontal list of client "buttons" selects which instructions show.
+    // Radio inputs share one name so the picker works without JavaScript
+    // (the build-smoke suite asserts the page ships no <script> tags).
+    const tabRadios = html.match(/type=["']radio["'][^>]*name=["']client-tab["']/gi) ?? [];
+    expect(tabRadios.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('renders a tab label for each documented client', () => {
+    expect(html).toMatch(/<label[^>]*for=["']tab-web["']/i);
+    expect(html).toMatch(/<label[^>]*for=["']tab-weechat["']/i);
+    expect(html).toMatch(/<label[^>]*for=["']tab-hexchat["']/i);
+    expect(html).toMatch(/<label[^>]*for=["']tab-irccloud["']/i);
+  });
+
+  it('hides client panels by default and reveals the selected one via :checked', () => {
+    // Pure-CSS tabs: panels are display:none unless their radio is checked,
+    // then `:checked ~ #panel-x` flips them to display:block.
+    expect(html).toMatch(/\.panel\s*\{[^}]*display:\s*none/i);
+    expect(html).toMatch(/:checked\s*~\s*#panel-/i);
+  });
+});

package/apps/web/tests/render-docs.test.ts

@@ -0,0 +1,198 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildDocs, renderMarkdown, rewriteDocLinks } from '../src/render-docs';
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const docsSrc = path.resolve(pkgRoot, '..', '..', 'docs');
+
+// ============================================================================
+// renderMarkdown — GFM rendering of markdown source
+// ============================================================================
+describe('renderMarkdown', () => {
+  it('renders an ATX H1 heading as <h1>', () => {
+    const html = renderMarkdown('# Title');
+    expect(html).toMatch(/<h1[^>]*>\s*Title\s*<\/h1>/);
+  });
+
+  it('renders a fenced code block as <pre><code>', () => {
+    const md = ['```ts', 'const x = 1;', '```'].join('\n');
+    const html = renderMarkdown(md);
+    expect(html).toMatch(/<pre[^>]*><code[^>]*>/);
+  });
+
+  it('renders GFM tables', () => {
+    const md = ['| a | b |', '| --- | --- |', '| 1 | 2 |'].join('\n');
+    const html = renderMarkdown(md);
+    expect(html).toContain('<table>');
+    expect(html).toContain('<th');
+  });
+
+  it('renders inline code', () => {
+    const html = renderMarkdown('Use `npm` to install.');
+    expect(html).toContain('<code>npm</code>');
+  });
+});
+
+// ============================================================================
+// rewriteDocLinks — intra-docs link rewriting
+// ============================================================================
+describe('rewriteDocLinks', () => {
+  const known = new Set([
+    'Services',
+    'Home',
+    'ADR-Index',
+    'ADR-001-pure-reducers-and-effect-system',
+  ]);
+
+  it('rewrites a relative OtherDoc.md href to OtherDoc.html', () => {
+    const input = '<a href="./Services.md">Services</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Services.html"');
+    expect(out).not.toContain('Services.md');
+  });
+
+  it('rewrites a bare wikilink-style href (no extension) when the slug is a known doc', () => {
+    const input = '<a href="Services">Services</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Services.html"');
+  });
+
+  it('leaves unknown bare hrefs alone (could be an external path)', () => {
+    const input = '<a href="SomeUnknownPage">x</a>';
+    const out = rewriteDocLinks(input, new Set(['Services']));
+    expect(out).toContain('href="SomeUnknownPage"');
+  });
+
+  it('preserves an anchor fragment when rewriting', () => {
+    const input = '<a href="./Services.md#section">link</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Services.html#section"');
+  });
+
+  it('does not touch external (http/https) links', () => {
+    const input = '<a href="https://example.com/foo.md">external</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="https://example.com/foo.md"');
+  });
+
+  it('does not touch pure-anchor (#section) links', () => {
+    const input = '<a href="#section">anchor</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="#section"');
+  });
+
+  it('handles a trailing anchor on a bare wikilink-style href', () => {
+    const input = '<a href="Home#pages">Home</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Home.html#pages"');
+  });
+});
+
+// ============================================================================
+// buildDocs — end-to-end render pipeline (against the real docs/ submodule)
+// ============================================================================
+describe('buildDocs against docs/ submodule', () => {
+  let outDir: string;
+
+  beforeEach(() => {
+    outDir = mkdtempSync(path.join(os.tmpdir(), 'render-docs-'));
+  });
+
+  afterEach(() => {
+    rmSync(outDir, { recursive: true, force: true });
+  });
+
+  it('throws a clear error when the docs source directory is missing', async () => {
+    await expect(buildDocs({ srcDir: path.join(outDir, 'nope'), outDir })).rejects.toThrow(
+      /docs.*missing|missing.*docs|submodule/iu,
+    );
+  });
+
+  it('throws a clear error when the docs source directory is present but empty', async () => {
+    // Mirrors the build-script guard: an empty `docs/` checkout (submodule
+    // init'd but not populated) must fail loudly with the recovery command,
+    // not silently produce a docs section with zero pages.
+    const empty = mkdirSync(path.join(outDir, 'empty-docs'), { recursive: true });
+    if (empty === undefined) {
+      throw new Error('test setup failed: could not create empty-docs dir');
+    }
+    await expect(buildDocs({ srcDir: empty, outDir })).rejects.toThrow(/empty|submodule/iu);
+  });
+
+  it('emits an index.html under the output directory', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const idx = path.join(outDir, 'index.html');
+    expect(existsSync(idx)).toBe(true);
+    expect(statSync(idx).size).toBeGreaterThan(0);
+  });
+
+  it('emits one HTML file per markdown source (non-empty output directory)', async () => {
+    const result = await buildDocs({ srcDir: docsSrc, outDir });
+    expect(result.emitted.length).toBeGreaterThanOrEqual(20);
+    for (const f of result.emitted) {
+      expect(f.endsWith('.html')).toBe(true);
+      expect(existsSync(path.join(outDir, f))).toBe(true);
+    }
+    expect(readdirSync(outDir).filter((f) => f.endsWith('.html')).length).toBe(
+      result.emitted.length,
+    );
+  });
+
+  it('renders Services.html with an <h1> and at least one <code> block', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const html = readFileSync(path.join(outDir, 'Services.html'), 'utf8');
+    expect(html).toMatch(/<h1[^>]*>/);
+    expect(html).toMatch(/<pre[^>]*><code/);
+    // The raw markdown marker should not survive rendering.
+    expect(html).not.toMatch(/^# IRC Services Reference/m);
+  });
+
+  it('emits Home as the index (index.html)', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const html = readFileSync(path.join(outDir, 'index.html'), 'utf8');
+    // Home.md's "Welcome to the Wiki." lead-in should be present.
+    expect(html).toMatch(/Welcome to the Wiki/i);
+  });
+
+  it('rewrites intra-docs links to .html in the rendered output (no .md hrefs remain)', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const files = readdirSync(outDir).filter((f) => f.endsWith('.html'));
+    expect(files.length).toBeGreaterThan(0);
+    for (const f of files) {
+      const html = readFileSync(path.join(outDir, f), 'utf8');
+      // No intra-docs .md href may remain. (External https://…/foo.md is fine.)
+      const intraMd = html.match(/href="(?!https?:|mailto:|#)[^"]*\.md[^"]*"/g) ?? [];
+      expect(intraMd).toEqual([]);
+    }
+  });
+
+  it('emits a shared stylesheet (referenced by every page)', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const files = readdirSync(outDir).filter((f) => f.endsWith('.html'));
+    // Every page links the same stylesheet.
+    for (const f of files) {
+      const html = readFileSync(path.join(outDir, f), 'utf8');
+      expect(html).toMatch(/<link[^>]+rel=["']stylesheet["']/);
+    }
+    // And the stylesheet actually exists in the output.
+    const css = readdirSync(outDir).filter((f) => f.endsWith('.css'));
+    expect(css.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('emits an ADR-Index page that links each ADR via a rewritten .html href', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const html = readFileSync(path.join(outDir, 'ADR-Index.html'), 'utf8');
+    expect(html).toMatch(/ADR-001-pure-reducers-and-effect-system\.html/);
+  });
+});

package/docs/AWS-Adapter-Architecture.md

@@ -373,8 +373,9 @@ scheme (post-v1).
         │
         │  all-or-nothing → races structurally impossible
         │
-        ▼
-   dispatch Broadcast(JOIN), 353 NAMES, 366 END-NAMES
+         ▼
+   dispatch Broadcast(JOIN), 353 NAMES, 366 END-NAMES,
+           and when a topic is set: 332 RPL_TOPIC, 333 RPL_TOPICWHOTIME
 ```
 
 A `CancellationException` from `TransactWriteItems` maps to the

package/docs/Services.md

@@ -126,6 +126,38 @@ Notable conventions:
   `519` (ChanServ `+R` JOIN gate), `432` (OperServ JUPE), `404` (ChanServ
   `+R`/`+M` send gates), `472` (services-only channel-mode letters).
 
+### Shortcut aliases (`/NICKSERV`, `/NS`, `/CS`, …)
+
+For compatibility with the Atheme/Anope services convention (and IRCd
+alias modules such as InspIRCd `m_alias` / UnrealIRCd `alias{}`), every
+service also accepts a **shortcut verb** that the daemon rewrites to the
+canonical `PRIVMSG <ServiceNick> :<joined args>` before routing. These are
+not RFC-standardized but are widely expected by clients and users.
+
+| Shortcut verb(s) | Equivalent to |
+|---|---|
+| `NICKSERV`, `NS` | `PRIVMSG NickServ :<args>` |
+| `CHANSERV`, `CS` | `PRIVMSG ChanServ :<args>` |
+| `HOSTSERV`, `HS` | `PRIVMSG HostServ :<args>` |
+| `MEMOSERV`, `MS` | `PRIVMSG MemoServ :<args>` |
+| `OPERSERV`, `OS` | `PRIVMSG OperServ :<args>` |
+
+The alias verb is the first token; everything after it is joined with
+single spaces and becomes the `PRIVMSG` trailing body, so e.g.
+`NICKSERV IDENTIFY hunter2` behaves identically to
+`PRIVMSG NickServ :IDENTIFY hunter2`, and `NS REGISTER pw email` is the
+same as `PRIVMSG NickServ :REGISTER pw email`. A colon-trailing form
+(`NS :IDENTIFY hunter2`) is accepted too. The verbs are matched
+case-insensitively. The alias → service nick table is the single source
+of truth in `packages/irc-core/src/commands/service-aliases.ts`
+(`SHORTCUT_TO_SERVICE`); both the dispatcher rewrite and the service-nick
+routing consult it, so no service-reducer changes were needed.
+
+When no `ServicesStore` is bound, a shortcut behaves exactly like a direct
+`PRIVMSG` to the service nick — it falls through to the normal nick-target
+path (a `401 ERR_NOSUCHNICK` for the unrecognised pseudo-client), never a
+bare `421 ERR_UNKNOWNCOMMAND`.
+
 ---
 
 ## 4. NickServ — nick registration & identification
@@ -142,7 +174,7 @@ policy, and nick-info queries. A registered nick is an account.
 | `REGISTER` | `PRIVMSG NickServ :REGISTER <password> <email>` | Registers the *current* nick. Does **not** auto-identify (no `+r` set). Reply: `Nickname <nick> is now registered.` Already-registered → `Nickname <nick> is already registered.` |
 | `IDENTIFY` | `PRIVMSG NickServ :IDENTIFY [nick] <password>` | One-arg form identifies the current nick; two-arg form identifies a named nick. On success: sets `state.account`, sets user mode **`+r`**, fans `ACCOUNT` to `account-notify` peers, then delivers unread MemoServ memos. Reply: `You are now identified for nick <account>.` |
 | `DROP` | `PRIVMSG NickServ :DROP [nick]` | Requires prior identify. Drops the registration, clears `state.account` and `+r`, fans `ACCOUNT *`. Reply: `Nickname <nick> has been dropped.` |
-| `INFO` | `PRIVMSG NickServ :INFO [nick]` | Defaults to the current nick. Replies (NOTICE): `Nick:`, `Account:`, `Email:`. Unregistered → `Nick <target> is not registered.` |
+| `INFO` | `PRIVMSG NickServ :INFO [nick]` | Defaults to the current nick. Replies (NOTICE): `Nick:`, `Account:`, and (only if the caller is identified as the owning account **or** is an oper) `Email:`. A non-owner sees `Nick:` / `Account:` only. Unregistered → `Nick <target> is not registered.` |
 | `SET ENFORCE` | `PRIVMSG NickServ :SET ENFORCE none|ghost|kill` | Requires identify as the owning account. See enforcement below. |
 
 Help / unknown command: `Available commands: REGISTER, IDENTIFY, DROP, INFO, SET`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.1.10",
-    "@serverless-ircd/aws-adapter": "0.8.0"
+    "@serverless-ircd/aws-adapter": "0.9.0"
   },
   "scripts": {
     "build": "turbo run build",

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

package/packages/aws-adapter/src/aws-runtime.ts

@@ -459,10 +459,15 @@ export class AwsRuntime implements IrcRuntime {
   // -------------------------------------------------------------------------
 
   private async readConnectionRow(conn: ConnId): Promise<MarshalledConnection | null> {
+    // Strongly consistent: peer lookups (WHOIS, roster hydration) read a
+    // row that may have just been written by another frame. An eventually-
+    // consistent Get could present a stale peer snapshot under replication
+    // lag.
     const result = await this.dynamo.send(
       new GetCommand({
         TableName: this.tables.Connections,
         Key: { connectionId: conn },
+        ConsistentRead: true,
       }),
     );
     if (result.Item === undefined) return null;
@@ -723,7 +728,16 @@ export async function cleanupConnection(
   quitMessage = 'Client Quit',
 ): Promise<void> {
   const connRow = await dynamo.send(
-    new GetCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
+    // Strongly consistent: $disconnect (and the send()/broadcast()
+    // GoneException path) can fire on the very next frame after the
+    // connection's own row was last written/updated. An eventually-
+    // consistent Get can miss that just-written row under DynamoDB
+    // replication lag and skip nick release + roster fanout.
+    new GetCommand({
+      TableName: tables.Connections,
+      Key: { connectionId: connId },
+      ConsistentRead: true,
+    }),
   );
   const item = connRow.Item as unknown as MarshalledConnection | undefined;
   if (item === undefined) return; // idempotent — already cleaned up

package/packages/aws-adapter/src/handlers/nlb-stream.ts

@@ -321,14 +321,22 @@ function readHeader(event: NlbStreamEvent, name: string): string | undefined {
   return undefined;
 }
 
-/** Loads a raw Connections row (includes transportBuffer if present). */
+/**
+ * Loads a raw Connections row (includes transportBuffer if present).
+ *
+ * Strongly consistent: the NLB handler has no `$connect` event — it writes
+ * the row itself on the first chunk and reads it back on the very next
+ * invocation. An eventually-consistent Get can miss that just-written row
+ * under DynamoDB replication lag and drop the first frame(s) of a
+ * raw-IRC-over-`:6697` connection.
+ */
 async function loadRow(
   dynamo: DynamoDBDocumentClient,
   tableName: string,
   connId: string,
 ): Promise<RawConnectionRow | null> {
   const result = await dynamo.send(
-    new GetCommand({ TableName: tableName, Key: { connectionId: connId } }),
+    new GetCommand({ TableName: tableName, Key: { connectionId: connId }, ConsistentRead: true }),
   );
   if (result.Item === undefined) return null;
   return result.Item as unknown as RawConnectionRow;

package/packages/aws-adapter/tests/aws-runtime.test.ts

@@ -7,6 +7,7 @@
  */
 
 import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
 import {
   type ChannelDelta,
   type Clock,
@@ -15,7 +16,7 @@ import {
   type ServerConfig,
   createConnection,
 } from '@serverless-ircd/irc-core';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { AwsRuntime } from '../src/aws-runtime.js';
 import type { AwsRuntimeHandlers, PostToConnection } from '../src/aws-runtime.js';
 import { TABLE_DEFS } from '../src/cdk-table-defs.js';
@@ -235,6 +236,27 @@ describe.skipIf(!available)('AwsRuntime', () => {
       const got = await rt.getConnection('self');
       expect(got).toBe(state);
     });
+
+    it('getConnectionInfo reads a peer Connections row strongly consistently', async () => {
+      // Peer lookups (WHOIS, roster hydration via readConnectionRow) read
+      // another connection's row. Strong consistency avoids presenting a
+      // stale peer snapshot under DynamoDB replication lag.
+      const rt = makeRuntime('self', noopHandlers());
+      const state = createConnection({ id: 'c1', connectedSince: 0 });
+      state.nick = 'Alice';
+      await rt.persistConnectionState(state);
+      const sendSpy = vi.spyOn(fx.client, 'send');
+      await rt.getConnectionInfo('c1');
+      const conGets = sendSpy.mock.calls
+        .map((call) => call[0] as unknown)
+        .filter(
+          (cmd): cmd is GetCommand =>
+            cmd instanceof GetCommand && (cmd.input.TableName?.endsWith('Connections') ?? false),
+        );
+      expect(conGets.length).toBeGreaterThan(0);
+      expect((conGets[0]?.input as { ConsistentRead?: boolean }).ConsistentRead).toBe(true);
+      sendSpy.mockRestore();
+    });
   });
 
   // -------------------------------------------------------------------------

package/packages/aws-adapter/tests/connection-counter.test.ts

@@ -95,6 +95,23 @@ describe('incrementConnectionCount', () => {
     expect(stub.count).toBe(1);
     expect(CONNECTION_COUNT_META_ID).toContain('__meta:');
   });
+
+  it('returns 0 when the response carries no numeric count (defensive)', async () => {
+    // A malformed/empty response must not crash the connect path; the
+    // handler treats a missing count as a 0 reservation so admission still
+    // proceeds conservatively rather than throwing.
+    const dynamo = {
+      send: async () => ({ Attributes: { count: 'not-a-number' } }),
+    } as unknown as DynamoDBDocumentClient;
+    await expect(incrementConnectionCount(dynamo, 'Connections')).resolves.toBe(0);
+  });
+
+  it('returns 0 when the response carries no Attributes at all', async () => {
+    const dynamo = {
+      send: async () => ({}),
+    } as unknown as DynamoDBDocumentClient;
+    await expect(incrementConnectionCount(dynamo, 'Connections')).resolves.toBe(0);
+  });
 });
 
 describe('decrementConnectionCount', () => {

package/packages/aws-adapter/tests/global-setup.ts

@@ -71,7 +71,11 @@ export default async function globalSetup(): Promise<(() => Promise<void>) | und
   const wantZip = strategy === 'auto' || strategy === 'zip';
 
   // Strategy 1: testcontainers (Docker).
-  if (wantDocker) {
+  // Pre-probe the Docker daemon: `docker info` hangs indefinitely on macOS
+  // when Docker Desktop is installed but not running (the CLI waits for
+  // the daemon to spin up). Bound that wait so we fall through to the
+  // ZIP strategy instead of stalling the whole test run.
+  if (wantDocker && (await dockerDaemonReachable())) {
     try {
       const handle = await tryTestcontainers();
       if (handle !== null) {
@@ -85,6 +89,10 @@ export default async function globalSetup(): Promise<(() => Promise<void>) | und
     } catch (err: unknown) {
       console.warn('[aws-adapter global-setup] testcontainers unavailable:', renderErr(err));
     }
+  } else if (wantDocker) {
+    console.warn(
+      '[aws-adapter global-setup] Docker daemon not reachable within probe window; skipping testcontainers.',
+    );
   }
 
   // Strategy 2: local ZIP + Java.
@@ -119,6 +127,25 @@ export default async function globalSetup(): Promise<(() => Promise<void>) | und
 // Strategy 1: testcontainers
 // ---------------------------------------------------------------------------
 
+/**
+ * Bounds the `docker info` probe. The Docker CLI on macOS waits silently for
+ * the daemon to start when Docker Desktop is installed but stopped, which
+ * would otherwise hang the entire global setup. Treat anything that doesn't
+ * return within `DOCKER_PROBE_MS` as "unavailable" and fall through to the
+ * ZIP strategy.
+ */
+const DOCKER_PROBE_MS = 5_000;
+
+async function dockerDaemonReachable(): Promise<boolean> {
+  if (which('docker') === null) return false;
+  try {
+    await execAsync('docker info', { timeout: DOCKER_PROBE_MS });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function tryTestcontainers(): Promise<DdbHandle | null> {
   let mod: typeof import('testcontainers') | undefined;
   try {

package/packages/aws-adapter/tests/gone-exception.test.ts

@@ -10,10 +10,10 @@
 
 import { GoneException } from '@aws-sdk/client-apigatewaymanagementapi';
 import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
-import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { GetCommand, PutCommand } from '@aws-sdk/lib-dynamodb';
 import { type Nick, type ParsedServerConfig, createConnection } from '@serverless-ircd/irc-core';
 import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { AwsRuntime, type PostToConnection, cleanupConnection } from '../src/aws-runtime.js';
 import { TABLE_DEFS } from '../src/cdk-table-defs.js';
 import { createDynamoDocumentClient } from '../src/dynamo.js';
@@ -219,6 +219,25 @@ describe.skipIf(!available)('GoneException cleanup', () => {
     ).resolves.toBeUndefined();
   });
 
+  it('cleanupConnection reads the Connections row strongly consistently', async () => {
+    // $disconnect runs cleanupConnection immediately after the connection's
+    // own row was last written/updated. An eventually-consistent Get can miss
+    // that just-written row under replication lag and skip nick release +
+    // roster fanout. The Get MUST be strongly consistent.
+    await seedConnection(requireFx().client, requireFx().tables, 'cr', 'crnick', '#room');
+    const sendSpy = vi.spyOn(requireFx().client, 'send');
+    await cleanupConnection(requireFx().client, requireFx().tables, 'cr', null);
+    const conGets = sendSpy.mock.calls
+      .map((call) => call[0] as unknown)
+      .filter(
+        (cmd): cmd is GetCommand =>
+          cmd instanceof GetCommand && (cmd.input.TableName?.endsWith('Connections') ?? false),
+      );
+    expect(conGets.length).toBeGreaterThan(0);
+    expect((conGets[0]?.input as { ConsistentRead?: boolean }).ConsistentRead).toBe(true);
+    sendSpy.mockRestore();
+  });
+
   it('broadcast() skips and cleans up gone members', async () => {
     await seedConnection(requireFx().client, requireFx().tables, 'gone3', 'eve', '#room');
     const mgmt: PostToConnection = {

package/packages/aws-adapter/tests/nlb-stream.test.ts

@@ -9,9 +9,10 @@
  */
 
 import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
 import { type ParsedServerConfig, StaticMotdProvider } from '@serverless-ircd/irc-core';
 import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { AwsRuntime } from '../src/aws-runtime.js';
 import type { PostToConnection } from '../src/aws-runtime.js';
 import { TABLE_DEFS } from '../src/cdk-table-defs.js';
@@ -164,6 +165,33 @@ describe.skipIf(!available)('NLB stream handler — byte framing', () => {
     expect(info?.registration).toBe('pre-registration');
   });
 
+  it('reads the Connections row strongly consistently on every chunk', async () => {
+    // The NLB handler has no $connect event — it writes its own row on the
+    // first chunk and reads it back on every subsequent chunk. An eventually-
+    // consistent Get can miss the just-written row under replication lag and
+    // drop the first frame(s) of a raw-IRC-over-:6697 connection. The Get
+    // MUST be strongly consistent.
+    const f = requireFx();
+    const sendSpy = vi.spyOn(f.client, 'send');
+    await handleNlbStream(nlbEvent('10.0.0.50', '50050', 'PING :tok\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    const conGets = sendSpy.mock.calls
+      .map((call) => call[0] as unknown)
+      .filter(
+        (cmd): cmd is GetCommand =>
+          cmd instanceof GetCommand && (cmd.input.TableName?.endsWith('Connections') ?? false),
+      );
+    expect(conGets.length).toBeGreaterThan(0);
+    expect((conGets[0]?.input as { ConsistentRead?: boolean }).ConsistentRead).toBe(true);
+    sendSpy.mockRestore();
+  });
+
   it('returns a PONG in the response body for a single PING', async () => {
     const f = requireFx();
     // First chunk establishes the connection.