serverless-ircd 0.4.0 → 0.6.0

package/packages/irc-server/tests/dispatch.test.ts

@@ -18,6 +18,9 @@ function fakeRuntime(calls: RecordedCall[]): IrcRuntime {
     async broadcast(chan, lines, except) {
       calls.push({ method: 'broadcast', args: [chan, lines, except] });
     },
+    async broadcastWallops(lines, except) {
+      calls.push({ method: 'broadcastWallops', args: [lines, except] });
+    },
     async disconnect(conn, reason) {
       calls.push({ method: 'disconnect', args: [conn, reason] });
     },
@@ -60,6 +63,10 @@ function fakeRuntime(calls: RecordedCall[]): IrcRuntime {
     async listChannels() {
       return [];
     },
+    async reloadConfig() {
+      calls.push({ method: 'reloadConfig', args: [] });
+      throw new Error('reloadConfig not configured for this fake');
+    },
   };
 }
 
@@ -126,6 +133,24 @@ describe('dispatch', () => {
     });
   });
 
+  it('routes BroadcastWallops with lines and except', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.broadcastWallops([L(':a WALLOPS :hi')], 'c1')], fakeRuntime(calls));
+    expect(calls[0]).toEqual({
+      method: 'broadcastWallops',
+      args: [[{ text: ':a WALLOPS :hi' }], 'c1'],
+    });
+  });
+
+  it('routes BroadcastWallops preserving undefined except', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.broadcastWallops([L(':a WALLOPS :hi')])], fakeRuntime(calls));
+    expect(calls[0]).toEqual({
+      method: 'broadcastWallops',
+      args: [[{ text: ':a WALLOPS :hi' }], undefined],
+    });
+  });
+
   it('calls reserveNick, changeNick, releaseNick in order', async () => {
     const calls: RecordedCall[] = [];
     await dispatch(
@@ -247,6 +272,7 @@ function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
     async broadcast(chan, lines, except) {
       broadcasts.push({ chan, lines, except });
     },
+    async broadcastWallops() {},
     async disconnect() {},
     async sendToNick() {},
     async reserveNick() {
@@ -268,7 +294,13 @@ function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
         registration: 'registered',
         caps: info.caps,
         joinedChannels: new Set<string>(),
-        userModes: { invisible: false, oper: false, wallops: false, serverNotices: false },
+        userModes: {
+          invisible: false,
+          oper: false,
+          wallops: false,
+          serverNotices: false,
+          tls: false,
+        },
         lastSeen: 0,
         connectedSince: 0,
       };
@@ -304,6 +336,9 @@ function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
     async listChannels() {
       return [];
     },
+    async reloadConfig() {
+      throw new Error('reloadConfig not configured for this fake');
+    },
   };
   return { runtime, sends, broadcasts };
 }
@@ -382,6 +417,7 @@ describe('dispatch — Broadcast cap / capLines', () => {
         sends.push({ to, lines });
       },
       async broadcast() {},
+      async broadcastWallops() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {
@@ -410,6 +446,9 @@ describe('dispatch — Broadcast cap / capLines', () => {
       async listChannels() {
         return [];
       },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
     };
 
     await dispatch([Effect.broadcast('#nope', [L('x')], undefined, 'chghost')], runtime);
@@ -425,6 +464,7 @@ describe('dispatch — Broadcast cap / capLines', () => {
         sends.push({ to, lines });
       },
       async broadcast() {},
+      async broadcastWallops() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {
@@ -445,7 +485,13 @@ describe('dispatch — Broadcast cap / capLines', () => {
             registration: 'registered',
             caps: new Set(['chghost']),
             joinedChannels: new Set<string>(),
-            userModes: { invisible: false, oper: false, wallops: false, serverNotices: false },
+            userModes: {
+              invisible: false,
+              oper: false,
+              wallops: false,
+              serverNotices: false,
+              tls: false,
+            },
             lastSeen: 0,
             connectedSince: 0,
           };
@@ -483,6 +529,9 @@ describe('dispatch — Broadcast cap / capLines', () => {
       async listChannels() {
         return [];
       },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
     };
 
     await dispatch(
@@ -495,6 +544,255 @@ describe('dispatch — Broadcast cap / capLines', () => {
   });
 });
 
+// ============================================================================
+// dispatch — Broadcast `caps` (OR semantics)
+//
+// IRCv3 `draft/typing` ships a TAGMSG to peers that announced EITHER
+// `draft/typing` OR `message-tags`. The reducer annotates the Broadcast
+// effect with `caps` (plural); dispatch resolves per-recipient with OR
+// semantics: a member receives `lines` iff they hold ANY of the listed caps.
+// ============================================================================
+
+describe('dispatch — Broadcast caps (OR semantics)', () => {
+  it('delivers lines to a member holding any of the listed caps', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['message-tags']) }],
+      ['c2', { caps: new Set(['draft/typing']) }],
+      ['c3', { caps: new Set<string>() }],
+    ]);
+    const { runtime, sends, broadcasts } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast(
+          '#foo',
+          [L('@+draft/typing=active :a!u@h TAGMSG #foo')],
+          'c0',
+          undefined,
+          undefined,
+          ['message-tags', 'draft/typing'],
+        ),
+      ],
+      runtime,
+    );
+
+    expect(broadcasts).toHaveLength(0);
+    expect(sends.map((s) => s.to).sort()).toEqual(['c1', 'c2']);
+    expect(sends[0]?.lines).toEqual([L('@+draft/typing=active :a!u@h TAGMSG #foo')]);
+  });
+
+  it('does NOT double-deliver to a member holding both caps', async () => {
+    const members = memberMap([['c1', { caps: new Set(['message-tags', 'draft/typing']) }]]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast('#foo', [L('hi')], undefined, undefined, undefined, [
+          'message-tags',
+          'draft/typing',
+        ]),
+      ],
+      runtime,
+    );
+
+    expect(sends).toHaveLength(1);
+    expect(sends[0]?.to).toBe('c1');
+  });
+
+  it('honors `except` alongside `caps`', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['message-tags']) }],
+      ['c2', { caps: new Set(['draft/typing']) }],
+    ]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast('#foo', [L('hi')], 'c1', undefined, undefined, [
+          'message-tags',
+          'draft/typing',
+        ]),
+      ],
+      runtime,
+    );
+
+    expect(sends.map((s) => s.to)).toEqual(['c2']);
+  });
+
+  it('skips members whose connection info is unavailable (treats as no cap)', async () => {
+    const members = memberMap([['c1', { caps: new Set(['draft/typing']) }]]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    // Override getConnectionInfo to return null for c1 (connection gone).
+    const runtimeWithGone: IrcRuntime = {
+      ...runtime,
+      async getConnectionInfo() {
+        return null;
+      },
+    };
+
+    await dispatch(
+      [Effect.broadcast('#foo', [L('hi')], undefined, undefined, undefined, ['draft/typing'])],
+      runtimeWithGone,
+    );
+
+    expect(sends).toHaveLength(0);
+  });
+
+  it('is a no-op when the channel snapshot is null', async () => {
+    const sends: { to: ConnId; lines: RawLine[] }[] = [];
+    const runtime: IrcRuntime = {
+      async send(to, lines) {
+        sends.push({ to, lines });
+      },
+      async broadcast() {},
+      async broadcastWallops() {},
+      async disconnect() {},
+      async sendToNick() {},
+      async reserveNick() {
+        return { ok: true };
+      },
+      async changeNick() {
+        return true;
+      },
+      async releaseNick() {},
+      async applyChannelDelta() {},
+      async lookupNick() {
+        return null;
+      },
+      async getConnectionInfo() {
+        return null;
+      },
+      async getConnection() {
+        return null;
+      },
+      async getChannelSnapshot() {
+        return null;
+      },
+      async getChannelConnections() {
+        return new Map();
+      },
+      async listChannels() {
+        return [];
+      },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
+    };
+
+    await dispatch(
+      [Effect.broadcast('#nope', [L('x')], undefined, undefined, undefined, ['draft/typing'])],
+      runtime,
+    );
+
+    expect(sends).toHaveLength(0);
+  });
+});
+
+// ===========================================================================
+// dispatch — Broadcast client-tag gating (message-tags)
+//
+// Recipients that did NOT negotiate `message-tags` must never receive a line
+// beginning with `@+<client-tag>`. The dispatch broadcast per-recipient path
+// applies filterClientTags so draft/multiline's `+draft/multiline` joined
+// PRIVMSG is stripped for legacy peers, while message-tags peers still see it.
+// ===========================================================================
+
+describe('dispatch — Broadcast client-tag gating', () => {
+  it('strips +draft/multiline for a non-message-tags recipient (split mode)', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['draft/multiline']) }],
+      ['c2', { caps: new Set<string>() }],
+    ]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast(
+          '#foo',
+          [L('@+draft/multiline :a!a@a PRIVMSG #foo :line one\nline two')],
+          'c0',
+          'draft/multiline',
+          [L('BATCH +b1 draft/multiline #foo'), L('BATCH -b1')],
+        ),
+      ],
+      runtime,
+    );
+
+    const toC2 = sends.find((s) => s.to === 'c2');
+    expect(toC2?.lines).toEqual([L(':a!a@a PRIVMSG #foo :line one\nline two')]);
+  });
+
+  it('preserves +draft/multiline for a message-tags recipient (split mode)', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['draft/multiline']) }],
+      ['c2', { caps: new Set(['message-tags']) }],
+    ]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast(
+          '#foo',
+          [L('@+draft/multiline :a!a@a PRIVMSG #foo :line one\nline two')],
+          'c0',
+          'draft/multiline',
+          [L('BATCH +b1 draft/multiline #foo'), L('BATCH -b1')],
+        ),
+      ],
+      runtime,
+    );
+
+    const toC2 = sends.find((s) => s.to === 'c2');
+    expect(toC2?.lines).toEqual([L('@+draft/multiline :a!a@a PRIVMSG #foo :line one\nline two')]);
+  });
+
+  it('leaves capLines (BATCH replay) untouched for multiline-cap recipients', async () => {
+    const members = memberMap([['c1', { caps: new Set(['draft/multiline', 'message-tags']) }]]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast(
+          '#foo',
+          [L('@+draft/multiline :a!a@a PRIVMSG #foo :joined')],
+          'c0',
+          'draft/multiline',
+          [L('BATCH +b1 draft/multiline #foo'), L(':a!a@a PRIVMSG #foo :one'), L('BATCH -b1')],
+        ),
+      ],
+      runtime,
+    );
+
+    const toC1 = sends.find((s) => s.to === 'c1');
+    expect(toC1?.lines).toEqual([
+      L('BATCH +b1 draft/multiline #foo'),
+      L(':a!a@a PRIVMSG #foo :one'),
+      L('BATCH -b1'),
+    ]);
+  });
+
+  it('strips client tags in cap-only mode too (no capLines)', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['message-tags']) }],
+      ['c2', { caps: new Set<string>() }],
+    ]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [Effect.broadcast('#foo', [L('@+draft/typing=active :a TAGMSG #foo')], 'c0', 'message-tags')],
+      runtime,
+    );
+
+    // c1 has message-tags → verbatim.
+    const toC1 = sends.find((s) => s.to === 'c1');
+    expect(toC1?.lines).toEqual([L('@+draft/typing=active :a TAGMSG #foo')]);
+    // c2 lacks message-tags AND the cap → receives nothing (cap-only mode).
+    const toC2 = sends.find((s) => s.to === 'c2');
+    expect(toC2).toBeUndefined();
+  });
+});
+
 // ===========================================================================
 // dispatch observability
 // ===========================================================================

package/packages/irc-server/tests/raw-modules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient declaration so `?raw` imports (Vite's built-in transform that
+ * inlines a file's text at bundle time) typecheck under the strict
+ * `tsconfig.test.json`. Used by source-level regression guards that
+ * assert the actor default-branch triage stays accurate.
+ */
+declare module '*?raw' {
+  const content: string;
+  // eslint-disable-next-line import/no-default-export
+  export default content;
+}

package/packages/irc-server/tests/routing.test.ts

@@ -131,6 +131,7 @@ describe('buildRoutedReducers', () => {
         'privmsgChannel',
         'privmsgUser',
         'quit',
+        'setname',
         'tagmsgChannel',
         'tagmsgUser',
         'time',

package/packages/irc-server/tests/runtime.test.ts

@@ -34,6 +34,10 @@ describe('IrcRuntime contract', () => {
       async listChannels() {
         return [];
       },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
+      async broadcastWallops() {},
     };
     expect(runtime).toBeDefined();
     expect(typeof runtime.send).toBe('function');
@@ -48,5 +52,8 @@ describe('IrcRuntime contract', () => {
     expect(typeof runtime.getConnectionInfo).toBe('function');
     expect(typeof runtime.getConnection).toBe('function');
     expect(typeof runtime.getChannelSnapshot).toBe('function');
+    expect(typeof runtime.listChannels).toBe('function');
+    expect(typeof runtime.reloadConfig).toBe('function');
+    expect(typeof runtime.broadcastWallops).toBe('function');
   });
 });

package/packages/irc-test-support/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-test-support",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Shared IRC scenario runner + harness seam used by every adapter's integration suite",
   "license": "BSD-3-Clause",

package/packages/irc-test-support/src/index.ts

@@ -25,3 +25,9 @@ export {
   inMemoryWsHarnessFactory,
 } from './in-memory-harness.js';
 export { runIrcScenarios } from './scenarios.js';
+export {
+  TEST_NETWORK_NAME,
+  TEST_SERVER_NAME,
+  makeTestServerConfig,
+  type TestServerConfigOverrides,
+} from './test-config.js';

package/packages/irc-test-support/src/scenarios.ts

@@ -192,7 +192,15 @@ export function runIrcScenarios(factories: readonly IrcHarnessFactory[]): void {
         await alice.waitForLine((l) => l.includes('JOIN #bar'));
         alice.received.length = 0;
         await alice.send('JOIN 0');
-        await alice.waitForLine((l) => l.includes('PART'));
+        // The two PART echoes arrive as separate deliveries (one per
+        // channel, with an ApplyChannelDelta in between). On distributed
+        // runtimes (cf-adapter) they land in distinct WS messages with
+        // cross-DO latency between them, so waiting for the first generic
+        // PART and then snapshotting `received` races the second one.
+        // Wait for each channel's PART explicitly to make the observation
+        // deterministic across in-memory and DO-backed runtimes.
+        await alice.waitForLine((l) => l.includes('PART') && l.includes('#foo'));
+        await alice.waitForLine((l) => l.includes('PART') && l.includes('#bar'));
         const parts = alice.received.filter((l) => l.includes('PART'));
         expect(parts.length).toBe(2);
         expect(parts.some((l) => l.includes('#foo'))).toBe(true);

package/packages/irc-test-support/src/test-config.ts

@@ -0,0 +1,54 @@
+/**
+ * Test-only server-config builder.
+ *
+ * Production config no longer ships a baseline `serverName` — every
+ * adapter's loader fails fast when the knob is missing. Test code that
+ * previously spread `DEFAULT_SERVER_CONFIG` needs an explicit, clearly
+ * test-scoped substitute so a forgotten override never silently advertises
+ * a placeholder hostname on the wire.
+ *
+ * The helper funnels its result through the shared `parseServerConfig` so
+ * the object shape stays schema-valid even when a test overrides
+ * individual knobs.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * Input accepted by {@link makeTestServerConfig}: any subset of the
+ * schema's input shape. Fields the caller omits fall back to the
+ * test-only baseline.
+ */
+export type TestServerConfigOverrides = Partial<Parameters<typeof parseServerConfig>[0]> &
+  Record<string, unknown>;
+
+/**
+ * Test-only baseline hostname. Deliberately not `irc.example.com` (the
+ * retired placeholder) so any assertion that catches the placeholder
+ * leaking into production stays loud.
+ */
+export const TEST_SERVER_NAME = 'irc.test.local';
+
+/** Test-only baseline network name. */
+export const TEST_NETWORK_NAME = 'TestNet';
+
+/**
+ * Builds a fresh, schema-valid `ParsedServerConfig` for tests.
+ *
+ * Callers may omit `serverName`/`networkName` entirely — the helper
+ * supplies a test-only baseline that round-trips through
+ * `parseServerConfig`. Overrides are merged before parsing so the result
+ * always satisfies the schema (a bad override surfaces as a throw, same
+ * as a malformed production config).
+ *
+ * Each call returns an independent object; mutating the result never
+ * bleeds into subsequent calls.
+ */
+export function makeTestServerConfig(overrides?: TestServerConfigOverrides): ParsedServerConfig {
+  const input: Record<string, unknown> = {
+    serverName: TEST_SERVER_NAME,
+    networkName: TEST_NETWORK_NAME,
+    ...overrides,
+  };
+  return parseServerConfig(input);
+}

package/packages/irc-test-support/tests/in-memory-scenarios.test.ts

@@ -1,5 +1,5 @@
 /**
- * Parametrized IRC scenarios — 032 + 057.
+ * Parametrized IRC scenarios.
  *
  * The scenario bodies live in `src/scenarios.ts` (now re-exported as
  * `runIrcScenarios`) so adapter packages can register their own

package/packages/irc-test-support/tests/test-config.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Unit tests for the `makeTestServerConfig` test helper.
+ *
+ * The helper exists so test code can build a valid `ParsedServerConfig`
+ * without sourcing `serverName` from the production default constant
+ * (which no longer carries one). Every adapter's integration suite
+ * spreads this baseline; the helper guarantees the result still parses
+ * cleanly through the shared schema.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { makeTestServerConfig } from '../src/test-config.js';
+
+describe('makeTestServerConfig', () => {
+  it('returns a config whose serverName is not the public placeholder', () => {
+    const cfg = makeTestServerConfig();
+    expect(cfg.serverName).not.toBe('irc.example.com');
+    expect(cfg.serverName.length).toBeGreaterThan(0);
+  });
+
+  it('returns a config that round-trips through parseServerConfig', () => {
+    const cfg = makeTestServerConfig();
+    const reparsed = parseServerConfig(cfg);
+    expect(reparsed).toEqual(cfg);
+  });
+
+  it('supplies a non-empty networkName by default', () => {
+    const cfg = makeTestServerConfig();
+    expect(cfg.networkName.length).toBeGreaterThan(0);
+  });
+
+  it('lets the caller override serverName with an explicit test value', () => {
+    const cfg = makeTestServerConfig({ serverName: 'irc.test.local' });
+    expect(cfg.serverName).toBe('irc.test.local');
+  });
+
+  it('lets the caller override arbitrary knobs without dropping the baseline', () => {
+    const cfg = makeTestServerConfig({ maxClients: 7, nickLen: 9 });
+    expect(cfg.maxClients).toBe(7);
+    expect(cfg.nickLen).toBe(9);
+    expect(cfg.serverName.length).toBeGreaterThan(0);
+  });
+
+  it('returns a fresh object each call (no shared mutable baseline)', () => {
+    const a = makeTestServerConfig() as ParsedServerConfig & { motdLines: string[] };
+    const b = makeTestServerConfig() as ParsedServerConfig & { motdLines: string[] };
+    a.motdLines.push('mutated');
+    expect(b.motdLines).not.toContain('mutated');
+  });
+});

package/pnpm-workspace.yaml

@@ -1,6 +1,7 @@
 packages:
   - "packages/*"
   - "apps/*"
+  - "tools"
   - "tools/*"
 linkWorkspacePackages: true
 allowBuilds:

package/tools/ci-hardening/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/ci-hardening",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
   "license": "BSD-3-Clause",

package/tools/ci-hardening/tests/ddb-local.test.ts

@@ -0,0 +1,82 @@
+/**
+ * CI capability self-checks for DynamoDB Local.
+ *
+ * The `aws-adapter` package's `globalSetup` boots a real DynamoDB Local
+ * instance so the integration suite (handlers/default.ts,
+ * handlers/nlb-stream.ts, aws-runtime.ts, …) can be exercised under
+ * coverage. Without a DynamoDB Local backend, 171 of 294 tests
+ * `describe.skipIf` away and `aws-adapter` coverage collapses to ~42%,
+ * blowing the 90% gate.
+ *
+ * These tests assert that the CI workflow wires the runner capability
+ * the globalSetup needs (a JRE for the official ZIP fallback) and that
+ * the strategy is pinned deterministically so the testcontainers
+ * probe does not burn ~60s of CI time before falling back.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const REPO_ROOT = resolve(import.meta.dirname, '..', '..', '..');
+
+function repoPath(rel: string): string {
+  return resolve(REPO_ROOT, rel);
+}
+
+function readText(rel: string): string {
+  return readFileSync(repoPath(rel), 'utf8');
+}
+
+describe('DynamoDB Local CI capability', () => {
+  it('installs a JRE on the CI runner so the ZIP fallback can fire', () => {
+    // The self-hosted Gitea runner image ships with neither Docker nor
+    // Java, so the globalSetup's testcontainers strategy fails fast
+    // ("Failed to connect to Reaper") and the ZIP strategy bails on
+    // `which('java') === null`. Installing a JRE via `setup-java`
+    // unblocks the ZIP path without requiring privileged mode or a
+    // `docker.sock` mount.
+    const ci = readText('.github/workflows/ci.yml');
+    expect(ci).toMatch(/setup-java/);
+  });
+
+  it('pins the DynamoDB Local strategy to ZIP in CI to skip the testcontainers probe', () => {
+    // testcontainers' Ryuk reaper container cannot start without a
+    // privileged runner / `docker.sock` mount; the probe blocks for
+    // tens of seconds (timeout) before falling back, which is flaky
+    // and slow. Pinning `DDB_LOCAL_STRATEGY=zip` on the coverage step
+    // makes globalSetup skip the Docker attempt entirely.
+    const ci = readText('.github/workflows/ci.yml');
+    expect(ci).toMatch(/DDB_LOCAL_STRATEGY/);
+    expect(ci).toMatch(/DDB_LOCAL_STRATEGY.*zip|zip.*DDB_LOCAL_STRATEGY/s);
+  });
+
+  it('documents the DynamoDB Local capability requirement in workflow comments', () => {
+    // The next contributor who touches the coverage job needs to know
+    // why Java is installed and why the strategy is pinned, so the
+    // capability is not silently dropped during a refactor.
+    const ci = readText('.github/workflows/ci.yml');
+    expect(ci).toMatch(/DynamoDB Local/i);
+    expect(ci).toMatch(/ZIP|Java/i);
+  });
+});
+
+describe('globalSetup strategy pinning', () => {
+  it('honors DDB_LOCAL_STRATEGY to skip the testcontainers attempt', () => {
+    // The globalSetup reads `DDB_LOCAL_STRATEGY` and short-circuits the
+    // Docker probe when set to `zip`, and the ZIP probe when set to
+    // `docker`. Default (`auto`) tries both for local dev parity.
+    const setup = readText('packages/aws-adapter/tests/global-setup.ts');
+    expect(setup).toMatch(/DDB_LOCAL_STRATEGY/);
+    // The two real strategies must be selectable explicitly.
+    expect(setup).toMatch(/['"]zip['"]/);
+    expect(setup).toMatch(/['"]docker['"]/);
+  });
+
+  it('still allows `auto` (both strategies) for local development', () => {
+    // The default behavior — try Docker, then ZIP — must remain so a
+    // developer with Docker Desktop still gets the testcontainers path.
+    const setup = readText('packages/aws-adapter/tests/global-setup.ts');
+    expect(setup).toMatch(/auto/);
+  });
+});