serverless-ircd 0.1.0

package/packages/cf-adapter/tests/cf-integration.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Parametrized IRC scenarios against the Cloudflare runtime — 036.
+ *
+ * Reuses the scenario runner from `./integration/scenarios.js`
+ * (032) and registers the CF harness factory built on top of the
+ * real ConnectionDO / RegistryDO / ChannelDO worker bindings. Each
+ * scenario spawns one or more real WebSockets and drives the full
+ * bytes → actor → CfRuntime pipeline inside `workerd`.
+ *
+ * Test isolation: `vitest.config.ts` sets `isolatedStorage: true`, so
+ * every test gets a fresh DO storage namespace even though they all
+ * address the same `wrangler.test.toml` bindings.
+ *
+ * Known-issue notebook (these scenarios are the same ones that pass
+ * against the in-memory runtime; CF-specific failures stem from the
+ * ConnectionDO's `PassthroughChannelAccess` not yet fetching
+ * authoritative roster state from ChannelDO before running channel
+ * reducers. That wiring lands in a follow-up to keep this ticket
+ * focused on the CfRuntime class itself):
+ *   - Multi-client channel reads (NAMES of peers, KICK roster refresh)
+ *     see only the local connection until the actor's channel access
+ *     is upgraded to read from ChannelDO.
+ *   - ChannelDO.getChannelSnapshot has an unrelated bug in the parallel
+ *     ChannelDO ticket (035) that returns a malformed snapshot;
+ *     that bug is not introduced here.
+ */
+
+import { env, reset } from 'cloudflare:test';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import { makeCfHarnessFactory } from './cf-harness';
+import { runIrcScenarios } from './integration/scenarios.js';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+    }
+  }
+}
+
+let factory: ReturnType<typeof makeCfHarnessFactory> | undefined;
+
+beforeAll(() => {
+  factory = makeCfHarnessFactory({ env });
+});
+
+// DO storage persists across tests in the same file; reset between each so
+// nick reservations, connection state, and channel rosters from one scenario
+// never leak into the next.
+afterEach(async () => {
+  await reset();
+});
+
+afterAll(async () => {
+  await reset();
+});
+
+// Registered lazily inside beforeAll because vitest collects `describe`
+// trees at module load; we build the factory on first run so the env is
+// guaranteed to be initialized.
+runIrcScenarios([
+  {
+    name: 'cf',
+    async create() {
+      if (factory === undefined) {
+        factory = makeCfHarnessFactory({ env });
+      }
+      return factory.create();
+    },
+  },
+]);

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

@@ -0,0 +1,527 @@
+/**
+ * CfRuntime — 036.
+ *
+ * Verifies that every {@link IrcRuntime} method on {@link CfRuntime} issues
+ * the correct DO `stub()` call:
+ *
+ *   - Nick registry ops route to `REGISTRY_DO` sharded by `registryKeyForNick`.
+ *   - Channel ops route to `CHANNEL_DO` keyed by lowercased channel name.
+ *   - Cross-connection send / getConnectionInfo route to `CONNECTION_DO` RPC.
+ *   - Local-conn shortcuts (`to === connId`, snapshot via handlers) hit the
+ *     injected per-connection handlers instead of RPC-to-self.
+ *
+ * Tests run inside real workerd via miniflare so DO RPC, storage, and
+ * hibernation behave as in production. Each test gets isolated storage.
+ *
+ * Two envs are used:
+ *   - `env`              — production bindings (recording stubs for the
+ *                          033 unit suite; swapped to `_REAL` for
+ *                          the CfRuntime uniqueness + end-to-end tests).
+ *   - `envWithRealDOs()` — a shim that re-exposes the real RegistryDO +
+ *                          ChannelDO under the production binding names,
+ *                          so CfRuntime exercises the real sharded path.
+ */
+
+import { env, reset, runInDurableObject } from 'cloudflare:test';
+import {
+  type ChanSnapshot,
+  type ConnectionState,
+  type RawLine,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { type CfConnectionHandlers, CfRuntime } from '../src/cf-runtime';
+import type { Env, RegistryRpc } from '../src/env';
+import { registryKeyForNick } from '../src/sharding';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      REGISTRY_DO_REAL: DurableObjectNamespace;
+      REGISTRY_DO_STUB: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+      CHANNEL_DO_REAL: DurableObjectNamespace;
+      CHANNEL_DO_STUB: DurableObjectNamespace;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Env shims
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns an env shim where REGISTRY_DO and CHANNEL_DO point at the real
+ * DO classes. Use this to verify CfRuntime against production-correct
+ * semantics (real nick uniqueness, real channel state).
+ */
+function envWithRealDOs(): Env {
+  return {
+    CONNECTION_DO: env.CONNECTION_DO,
+    REGISTRY_DO: env.REGISTRY_DO_REAL,
+    CHANNEL_DO: env.CHANNEL_DO_REAL,
+    SERVER_NAME: 'irc.example.com',
+    NETWORK_NAME: 'ExampleNet',
+    MOTD_LINES: '',
+  };
+}
+
+/**
+ * Returns an env shim where CHANNEL_DO points at the recording stub.
+ * Used for tests that assert on the *shape* of the RPC call rather than
+ * the end-to-end fanout (which the real ChannelDO owns).
+ */
+function envWithChannelStub(): Env {
+  return {
+    CONNECTION_DO: env.CONNECTION_DO,
+    REGISTRY_DO: env.REGISTRY_DO_REAL,
+    CHANNEL_DO: env.CHANNEL_DO_STUB,
+    SERVER_NAME: 'irc.example.com',
+    NETWORK_NAME: 'ExampleNet',
+    MOTD_LINES: '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Lines-only handlers used by every test; the asserts inspect `sent`. */
+function recordingHandlers(
+  snapshot?: () => ConnectionState | undefined,
+): CfConnectionHandlers & { sent: string[]; disconnects: string[] } {
+  const sent: string[] = [];
+  const disconnects: string[] = [];
+  return {
+    sent,
+    disconnects,
+    send: (lines: RawLine[]): void => {
+      for (const l of lines) sent.push(l.text);
+    },
+    disconnect: (reason?: string): void => {
+      disconnects.push(reason ?? '');
+    },
+    snapshot: snapshot ?? ((): undefined => undefined),
+  };
+}
+
+/** Returns a registry DO RPC stub for the shard owning `nick`. */
+function registryForNick(targetEnv: Env, nick: string): RegistryRpc {
+  const key = registryKeyForNick(nick);
+  const stub = targetEnv.REGISTRY_DO.get(targetEnv.REGISTRY_DO.idFromName(key));
+  return stub as unknown as RegistryRpc;
+}
+
+/** Returns the RecordingChannelDO call log for the lowercased channel name. */
+async function channelCallLog(chanLower: string): Promise<{ method: string; args: unknown[] }[]> {
+  const stub = env.CHANNEL_DO_STUB.get(env.CHANNEL_DO_STUB.idFromName(chanLower));
+  return runInDurableObject(stub, async (instance: unknown) => {
+    const doi = instance as {
+      recordedCalls?: () => Promise<{ method: string; args: unknown[] }[]>;
+    };
+    return (await doi.recordedCalls?.()) ?? [];
+  });
+}
+
+async function waitForChannelCall(
+  chanLower: string,
+  method: string,
+  timeoutMs = 2000,
+): Promise<{ method: string; args: unknown[] }[]> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const all = await channelCallLog(chanLower);
+    const matching = all.filter((c) => c.method === method);
+    if (matching.length > 0) return matching;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  return [];
+}
+
+/**
+ * Opens a WebSocket to a fresh ConnectionDO named `connId`, so the
+ * hibernatable socket exists for `deliver` RPC to write to.
+ */
+async function openConnection(connId: string): Promise<WebSocket> {
+  const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(connId));
+  const response = await stub.fetch('https://do/upgrade', {
+    headers: { Upgrade: 'websocket' },
+  });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  return new Promise<WebSocket>((resolve) => {
+    setTimeout(() => resolve(ws as WebSocket), 0);
+  });
+}
+
+/** Drains received WebSocket frames into a string array. */
+function drainSocket(ws: WebSocket): string[] {
+  const received: string[] = [];
+  ws.addEventListener('message', (ev: MessageEvent) => {
+    const d = ev.data as string;
+    for (const line of d.split('\r\n')) {
+      if (line.length > 0) received.push(line);
+    }
+  });
+  return received;
+}
+
+/** Resolves the hex id of a ConnectionDO instance (its canonical ConnId). */
+async function getConnectionHexId(connId: string): Promise<string> {
+  const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(connId));
+  return runInDurableObject(stub, async (instance: unknown) => {
+    const doi = instance as { __peekHexId?: () => string };
+    return doi.__peekHexId?.() ?? connId;
+  });
+}
+
+/**
+ * Manually reserves `nick` for `connHexId` in the *real* registry, so
+ * CfRuntime.sendToNick can resolve the owner without having to drive the
+ * full registration handshake through the actor.
+ */
+async function reserveNickInRealRegistry(nick: string, connHexId: string): Promise<void> {
+  await registryForNick(envWithRealDOs(), nick).reserveNick(nick, connHexId);
+}
+
+// ---------------------------------------------------------------------------
+// Tests — registry routing (sharded by nick, real RegistryDO)
+// ---------------------------------------------------------------------------
+
+// DO storage persists across tests in the same file; reset between each so
+// nick reservations and connection state from one test never leak into the
+// next.
+afterEach(async () => {
+  await reset();
+});
+
+afterAll(async () => {
+  await reset();
+});
+
+describe('CfRuntime — nick registry routes through sharded RegistryDO', () => {
+  it('reserveNick routes to the shard owning the nick and stores the owner', async () => {
+    const realEnv = envWithRealDOs();
+    const handlers = recordingHandlers();
+    const rt = new CfRuntime(realEnv, 'conn-local-1', handlers);
+
+    const result = await rt.reserveNick('alice', 'conn-local-1');
+    expect(result).toEqual({ ok: true });
+
+    // Cross-check via the real registry RPC.
+    expect(await registryForNick(realEnv, 'alice').lookupNick('alice')).toBe('conn-local-1');
+  });
+
+  it('two concurrent reservations for the same nick from different runtimes — one wins', async () => {
+    const realEnv = envWithRealDOs();
+    const rt1 = new CfRuntime(realEnv, 'conn-race-1', recordingHandlers());
+    const rt2 = new CfRuntime(realEnv, 'conn-race-2', recordingHandlers());
+
+    const [a, b] = await Promise.all([
+      rt1.reserveNick('race', 'conn-race-1'),
+      rt2.reserveNick('race', 'conn-race-2'),
+    ]);
+    expect([a, b].filter((r) => r.ok).length).toBe(1);
+    expect([a, b].filter((r) => !r.ok).length).toBe(1);
+  });
+
+  it('changeNick reserves the new nick and releases the old', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-cn', recordingHandlers());
+    expect(await rt.reserveNick('oldnick', 'conn-cn')).toEqual({ ok: true });
+    expect(await rt.changeNick('conn-cn', 'oldnick', 'newnick')).toBe(true);
+
+    expect(await registryForNick(realEnv, 'oldnick').lookupNick('oldnick')).toBeNull();
+    expect(await registryForNick(realEnv, 'newnick').lookupNick('newnick')).toBe('conn-cn');
+  });
+
+  it('changeNick across two shards atomically reserves new then releases old', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-cross-shard', recordingHandlers());
+    expect(await rt.reserveNick('shardA', 'conn-cross-shard')).toEqual({ ok: true });
+    expect(await rt.changeNick('conn-cross-shard', 'shardA', 'shardB')).toBe(true);
+    expect(await registryForNick(realEnv, 'shardA').lookupNick('shardA')).toBeNull();
+    expect(await registryForNick(realEnv, 'shardB').lookupNick('shardB')).toBe('conn-cross-shard');
+  });
+
+  it('releaseNick clears the mapping', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-rel', recordingHandlers());
+    await rt.reserveNick('releaseme', 'conn-rel');
+    await rt.releaseNick('releaseme');
+    expect(await registryForNick(realEnv, 'releaseme').lookupNick('releaseme')).toBeNull();
+  });
+
+  it('lookupNick returns the owning conn id', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-look', recordingHandlers());
+    await rt.reserveNick('lookme', 'conn-look');
+    expect(await rt.lookupNick('lookme')).toBe('conn-look');
+    expect(await rt.lookupNick('unknown-look')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — channel routing (recording stub verifies call shape)
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — channel ops route through ChannelDO keyed by lowercase', () => {
+  it('broadcast forwards lines+except to the channel DO', async () => {
+    const stubEnv = envWithChannelStub();
+    const handlers = recordingHandlers();
+    const rt = new CfRuntime(stubEnv, 'conn-bcast', handlers);
+
+    await rt.broadcast('#Bcast', [{ text: ':alice!u@h PRIVMSG #Bcast :hi' }], 'conn-bcast');
+
+    const calls = await waitForChannelCall('#bcast', 'broadcast');
+    expect(calls.length).toBeGreaterThan(0);
+    const args = calls[0]?.args;
+    expect(args?.[0]).toEqual([':alice!u@h PRIVMSG #Bcast :hi']);
+    expect(args?.[1]).toBe('conn-bcast');
+  });
+
+  it('applyChannelDelta forwards the delta to the channel DO', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-delta', recordingHandlers());
+    const delta = {
+      memberships: [{ type: 'add' as const, conn: 'conn-delta', nick: 'alice' }],
+    };
+    await rt.applyChannelDelta('#Delta', delta);
+
+    const calls = await waitForChannelCall('#delta', 'applyChannelDelta');
+    expect(calls.length).toBeGreaterThan(0);
+    expect(calls[0]?.args[0]).toEqual(delta);
+  });
+
+  it('getChannelSnapshot routes to the channel DO and returns its value', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-snap', recordingHandlers());
+    // The RecordingChannelDO returns `null`; CfRuntime is a pass-through.
+    const snap = await rt.getChannelSnapshot('#snapchan');
+    expect(snap).toBeNull();
+    // Routing was made (recorded call).
+    const calls = await waitForChannelCall('#snapchan', 'getChannelSnapshot');
+    expect(calls.length).toBeGreaterThan(0);
+  });
+
+  it('broadcast with no except forwards undefined', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-bcast-noex', recordingHandlers());
+    await rt.broadcast('#NoEx', [{ text: ':srv NOTICE #NoEx :all ears' }]);
+    const calls = await waitForChannelCall('#noex', 'broadcast');
+    expect(calls.length).toBeGreaterThan(0);
+    expect(calls[0]?.args[1]).toBeUndefined();
+  });
+
+  it('broadcast routes to a different DO instance per lowercased channel name', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-isolation', recordingHandlers());
+    await rt.broadcast('#One', [{ text: ':srv NOTICE #One :first' }]);
+    await rt.broadcast('#Two', [{ text: ':srv NOTICE #Two :second' }]);
+    const one = await waitForChannelCall('#one', 'broadcast');
+    const two = await waitForChannelCall('#two', 'broadcast');
+    expect(one[0]?.args[0]).toEqual([':srv NOTICE #One :first']);
+    expect(two[0]?.args[0]).toEqual([':srv NOTICE #Two :second']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — local connection shortcuts
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — local connection shortcut', () => {
+  it('send(to=this.connId, ...) uses the injected handlers, not RPC', async () => {
+    const stubEnv = envWithChannelStub();
+    const handlers = recordingHandlers();
+    const rt = new CfRuntime(stubEnv, 'conn-self', handlers);
+    await rt.send('conn-self', [{ text: ':server 001 alice :Welcome' }]);
+    expect(handlers.sent).toEqual([':server 001 alice :Welcome']);
+  });
+
+  it('disconnect(this.connId, ...) invokes the injected disconnect handler', async () => {
+    const stubEnv = envWithChannelStub();
+    const handlers = recordingHandlers();
+    const rt = new CfRuntime(stubEnv, 'conn-disc', handlers);
+    await rt.disconnect('conn-disc', 'test');
+    expect(handlers.disconnects).toEqual(['test']);
+  });
+
+  it('getConnectionInfo(this.connId) returns the snapshot from handlers', async () => {
+    const stubEnv = envWithChannelStub();
+    const state = createConnection({ id: 'conn-info', connectedSince: 0 });
+    state.nick = 'alice';
+    const handlers: CfConnectionHandlers = {
+      send: (): void => {},
+      disconnect: (): void => {},
+      snapshot: () => state,
+    };
+    const rt = new CfRuntime(stubEnv, 'conn-info', handlers);
+    const result = await rt.getConnectionInfo('conn-info');
+    expect(result?.nick).toBe('alice');
+    expect(result?.id).toBe('conn-info');
+  });
+
+  it('getConnectionInfo returns null when handlers.snapshot returns undefined', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-null', recordingHandlers());
+    expect(await rt.getConnectionInfo('conn-null')).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — cross-connection RPC
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — cross-connection RPC via ConnectionDO', () => {
+  it('send(remoteConnId, ...) delivers via the remote ConnectionDO WebSocket', async () => {
+    const targetName = 'conn-x-send-target';
+    const ws = await openConnection(targetName);
+    const received = drainSocket(ws);
+
+    const targetHexId = await getConnectionHexId(targetName);
+
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-x-sender', recordingHandlers());
+    await rt.send(targetHexId, [{ text: ':server NOTICE target :hi from afar' }]);
+
+    await new Promise<void>((resolve, reject) => {
+      const deadline = Date.now() + 1500;
+      const tick = (): void => {
+        if (received.some((l) => l.includes('hi from afar'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          reject(new Error(`timed out; received=${JSON.stringify(received)}`));
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    ws.close();
+  });
+
+  it('getConnectionInfo(remoteConnId) returns the remote snapshot via RPC', async () => {
+    const targetName = 'conn-x-info-target';
+    const ws = await openConnection(targetName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+    ws.send('NICK bob\r\n');
+    ws.send('USER bob 0 * :Bob\r\n');
+    await new Promise<void>((r) => setTimeout(r, 100));
+
+    const targetHexId = await getConnectionHexId(targetName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-x-info-caller', recordingHandlers());
+    const snap = await rt.getConnectionInfo(targetHexId);
+    expect(snap).not.toBeNull();
+    expect(snap?.nick).toBe('bob');
+
+    ws.close();
+  });
+
+  it('sendToNick resolves via the registry then forwards via deliver RPC', async () => {
+    const aliceName = 'conn-x-stn-alice';
+    const ws = await openConnection(aliceName);
+    const aliceReceived = drainSocket(ws);
+    const aliceHexId = await getConnectionHexId(aliceName);
+
+    // Manually register alice in the REAL registry so sendToNick can
+    // resolve the owner. (Driving the full NICK handshake through the
+    // actor would reserve in the recording stub instead.)
+    await reserveNickInRealRegistry('alice', aliceHexId);
+
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-x-stn-sender', recordingHandlers());
+    await rt.sendToNick('alice', 'conn-x-stn-sender', [{ text: ':bob!u@h PRIVMSG alice :hello' }]);
+
+    await new Promise<void>((resolve, reject) => {
+      const deadline = Date.now() + 1500;
+      const tick = (): void => {
+        if (aliceReceived.some((l) => l.includes('hello'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          reject(new Error(`timed out; received=${JSON.stringify(aliceReceived)}`));
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    ws.close();
+  });
+
+  it('sendToNick with notFoundLines delivers the fallback to the sender', async () => {
+    const realEnv = envWithRealDOs();
+    const handlers = recordingHandlers();
+    const sender = new CfRuntime(realEnv, 'conn-x-stn-sender2', handlers);
+    await sender.sendToNick(
+      'ghost',
+      'conn-x-stn-sender2',
+      [],
+      [{ text: ':server 401 sender ghost :No such nick' }],
+    );
+    expect(handlers.sent).toEqual([':server 401 sender ghost :No such nick']);
+  });
+
+  it('sendToNick without notFoundLines is a silent drop for unknown nicks', async () => {
+    const realEnv = envWithRealDOs();
+    const handlers = recordingHandlers();
+    const sender = new CfRuntime(realEnv, 'conn-x-stn-silent', handlers);
+    await sender.sendToNick('ghost', 'conn-x-stn-silent', [
+      { text: ':bob!u@h NOTICE ghost :psst' },
+    ]);
+    expect(handlers.sent).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — implements IrcRuntime
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — IrcRuntime structural conformance', () => {
+  it('is a class that can be constructed with (env, connId, handlers)', () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-shape', recordingHandlers());
+    expect(typeof rt.send).toBe('function');
+    expect(typeof rt.broadcast).toBe('function');
+    expect(typeof rt.disconnect).toBe('function');
+    expect(typeof rt.sendToNick).toBe('function');
+    expect(typeof rt.reserveNick).toBe('function');
+    expect(typeof rt.changeNick).toBe('function');
+    expect(typeof rt.releaseNick).toBe('function');
+    expect(typeof rt.applyChannelDelta).toBe('function');
+    expect(typeof rt.lookupNick).toBe('function');
+    expect(typeof rt.getConnectionInfo).toBe('function');
+    expect(typeof rt.getChannelSnapshot).toBe('function');
+  });
+
+  it('getChannelSnapshot return type is assignable to ChanSnapshot | null', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-type', recordingHandlers());
+    const snap: ChanSnapshot | null = await rt.getChannelSnapshot('#typecheck');
+    // The recording stub returns null; CfRuntime passes it through.
+    expect(snap).toBeNull();
+  });
+
+  it('makeCfRuntime factory constructs an equivalent runtime', async () => {
+    const stubEnv = envWithChannelStub();
+    const { makeCfRuntime } = await import('../src/cf-runtime');
+    const handlers = recordingHandlers();
+    const rt = makeCfRuntime(stubEnv, 'conn-factory', 'ignored-stub-key', handlers);
+    // Same shape as a direct CfRuntime construction.
+    expect(typeof rt.send).toBe('function');
+    expect(typeof rt.sendToNick).toBe('function');
+    await rt.send('conn-factory', [{ text: ':server 001 alice :Welcome' }]);
+    expect(handlers.sent).toEqual([':server 001 alice :Welcome']);
+  });
+});