serverless-ircd 0.3.0 → 0.5.0

package/packages/irc-core/tests/effects.test.ts

@@ -67,27 +67,6 @@ describe('Effect constructors', () => {
     });
   });
 
-  it('LookupNick carries nick', () => {
-    expect(Effect.lookupNick('alice')).toEqual<EffectType>({
-      tag: 'LookupNick',
-      nick: 'alice',
-    });
-  });
-
-  it('GetConnectionInfo carries conn', () => {
-    expect(Effect.getConnectionInfo('c1')).toEqual<EffectType>({
-      tag: 'GetConnectionInfo',
-      conn: 'c1',
-    });
-  });
-
-  it('GetChannelSnapshot carries chan', () => {
-    expect(Effect.getChannelSnapshot('#foo')).toEqual<EffectType>({
-      tag: 'GetChannelSnapshot',
-      chan: '#foo',
-    });
-  });
-
   it('SendToNick carries nick, sender, lines, and optional notFoundLines', () => {
     expect(Effect.sendToNick('alice', 'c1', [line('hi')])).toEqual<EffectType>({
       tag: 'SendToNick',
@@ -103,6 +82,18 @@ describe('Effect constructors', () => {
       notFoundLines: [{ text: '401' }],
     });
   });
+
+  it('BroadcastWallops carries lines and optional except', () => {
+    expect(Effect.broadcastWallops([line(':a WALLOPS :hi')])).toEqual<EffectType>({
+      tag: 'BroadcastWallops',
+      lines: [{ text: ':a WALLOPS :hi' }],
+    });
+    expect(Effect.broadcastWallops([line(':a WALLOPS :hi')], 'c1')).toEqual<EffectType>({
+      tag: 'BroadcastWallops',
+      lines: [{ text: ':a WALLOPS :hi' }],
+      except: 'c1',
+    });
+  });
 });
 
 describe('Effect tag set', () => {
@@ -115,10 +106,8 @@ describe('Effect tag set', () => {
     'ChangeNick',
     'ReleaseNick',
     'ApplyChannelDelta',
-    'LookupNick',
-    'GetConnectionInfo',
-    'GetChannelSnapshot',
     'SendToNick',
+    'BroadcastWallops',
   ];
 
   it.each(expectedTags)('exposes a constructor for the %s tag', (tag) => {
@@ -130,10 +119,8 @@ describe('Effect tag set', () => {
       ChangeNick: Effect.changeNick('c', 'a', 'b'),
       ReleaseNick: Effect.releaseNick('n'),
       ApplyChannelDelta: Effect.applyChannelDelta('#c', { memberships: [] }),
-      LookupNick: Effect.lookupNick('n'),
-      GetConnectionInfo: Effect.getConnectionInfo('c'),
-      GetChannelSnapshot: Effect.getChannelSnapshot('#c'),
       SendToNick: Effect.sendToNick('n', 'c', []),
+      BroadcastWallops: Effect.broadcastWallops([]),
     };
     expect(constructors[tag].tag).toBe(tag);
   });

package/packages/irc-core/tests/nick-history-store.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import { FakeClock } from '../src/ports';
+import {
+  InMemoryNickHistoryStore,
+  type NickHistoryEntry,
+  type NickHistoryStore,
+} from '../src/ports';
+
+/** Builds a history entry with sensible defaults for tests. */
+function entry(
+  nick: string,
+  signoffTime: number,
+  opts: Partial<NickHistoryEntry> = {},
+): NickHistoryEntry {
+  return {
+    nick,
+    connId: opts.connId ?? 'c1',
+    signoffTime,
+    ...(opts.username !== undefined ? { username: opts.username } : {}),
+    ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+    ...(opts.realname !== undefined ? { realname: opts.realname } : {}),
+  };
+}
+
+describe('InMemoryNickHistoryStore — record + query', () => {
+  it('implements the NickHistoryStore port', () => {
+    const store: NickHistoryStore = new InMemoryNickHistoryStore(new FakeClock(1_000));
+    expect(store).toBeDefined();
+  });
+
+  it('returns a recorded entry on query (most-recent-first)', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('alice', 1_000, { username: 'alice', hostname: 'ex.org' }));
+
+    const out = store.query('alice', 10);
+
+    expect(out).toHaveLength(1);
+    expect(out[0]?.nick).toBe('alice');
+    expect(out[0]?.username).toBe('alice');
+    expect(out[0]?.hostname).toBe('ex.org');
+    expect(out[0]?.signoffTime).toBe(1_000);
+  });
+
+  it('returns multiple entries most-recent-first', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('alice', 1_000, { connId: 'c1' }));
+    clock.advance(500);
+    store.record(entry('alice', 1_500, { connId: 'c2' }));
+    clock.advance(500);
+    store.record(entry('alice', 2_000, { connId: 'c3' }));
+
+    const out = store.query('alice', 10);
+    expect(out.map((e) => e.connId)).toEqual(['c3', 'c2', 'c1']);
+  });
+
+  it('caps the result at the requested count', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('alice', 1_000, { connId: 'c1' }));
+    clock.advance(500);
+    store.record(entry('alice', 1_500, { connId: 'c2' }));
+    clock.advance(500);
+    store.record(entry('alice', 2_000, { connId: 'c3' }));
+
+    const out = store.query('alice', 2);
+
+    expect(out.map((e) => e.connId)).toEqual(['c3', 'c2']);
+  });
+
+  it('returns an empty array for a nick with no history', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    expect(store.query('ghost', 10)).toEqual([]);
+  });
+
+  it('matches nicks case-insensitively (rfc1459 fold)', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('Ali[e', 1_000));
+
+    expect(store.query('ali{e', 10)).toHaveLength(1);
+    expect(store.query('ALI{E', 10)).toHaveLength(1);
+    expect(store.query('ALI[E', 10)).toHaveLength(1);
+  });
+
+  it('returns an empty array when count is zero', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('alice', 1_000));
+
+    expect(store.query('alice', 0)).toEqual([]);
+  });
+
+  it('keeps nick histories independent', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('alice', 1_000));
+    clock.advance(500);
+    store.record(entry('bob', 1_500));
+
+    expect(store.query('alice', 10)).toHaveLength(1);
+    expect(store.query('bob', 10)).toHaveLength(1);
+  });
+});
+
+describe('InMemoryNickHistoryStore — TTL purge', () => {
+  it('purges entries older than maxAge on query', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock, { maxAge: 5_000 });
+    store.record(entry('alice', 1_000, { connId: 'c1' }));
+    clock.advance(3_000);
+    store.record(entry('alice', 4_000, { connId: 'c2' }));
+    clock.advance(3_000);
+
+    const out = store.query('alice', 10);
+
+    expect(out.map((e) => e.connId)).toEqual(['c2']);
+  });
+
+  it('purges all entries once they exceed maxAge', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock, { maxAge: 1_000 });
+    store.record(entry('alice', 1_000));
+    clock.advance(2_000);
+
+    expect(store.query('alice', 10)).toEqual([]);
+  });
+
+  it('purges on record so the per-nick buffer does not grow unbounded', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock, { maxAge: 1_000 });
+    for (let i = 0; i < 50; i++) {
+      store.record(entry('alice', clock.now(), { connId: `c${i}` }));
+      clock.advance(100);
+    }
+    // clock.now() is now 6_000; entries older than cutoff 5_000 are purged.
+    const out = store.query('alice', 100);
+    expect(out.length).toBeLessThan(50);
+  });
+
+  it('purges to an empty array when all entries expire, then query returns empty', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock, { maxAge: 1_000 });
+    store.record(entry('alice', 1_000, { connId: 'c1' }));
+    clock.advance(2_000);
+    // First query purges the lone entry → empty buffer remains in the map.
+    expect(store.query('alice', 10)).toEqual([]);
+    // Second query hits purgeExpired on the now-empty buffer (no-op splice).
+    expect(store.query('alice', 10)).toEqual([]);
+  });
+
+  it('uses a sane default maxAge when omitted', () => {
+    const clock = new FakeClock(1_000);
+    const store = new InMemoryNickHistoryStore(clock);
+    store.record(entry('alice', 1_000));
+    clock.advance(10_000);
+
+    expect(store.query('alice', 10)).toHaveLength(1);
+  });
+});

package/packages/irc-core/tests/numerics.test.ts

@@ -23,6 +23,80 @@ describe('Numerics registry', () => {
     expect(Numerics.ERR_NEEDMOREPARAMS).toBe(461);
   });
 
+  it('maps RPL_WHOWASUSER to 314', () => {
+    expect(Numerics.RPL_WHOWASUSER).toBe(314);
+  });
+
+  it('maps RPL_ENDOFWHOWAS to 369', () => {
+    expect(Numerics.RPL_ENDOFWHOWAS).toBe(369);
+  });
+
+  it('maps RPL_TRACELINK to 200', () => {
+    expect(Numerics.RPL_TRACELINK).toBe(200);
+  });
+
+  it('maps RPL_TRACEOPERATOR to 204', () => {
+    expect(Numerics.RPL_TRACEOPERATOR).toBe(204);
+  });
+
+  it('maps RPL_TRACEUSER to 205', () => {
+    expect(Numerics.RPL_TRACEUSER).toBe(205);
+  });
+
+  it('maps RPL_TRACESERVER to 206', () => {
+    expect(Numerics.RPL_TRACESERVER).toBe(206);
+  });
+
+  it('maps RPL_ENDOFTRACE to 262', () => {
+    expect(Numerics.RPL_ENDOFTRACE).toBe(262);
+  });
+
+  // -- LUSERS (RFC 2812 §4.6.2) ----------------------------------------------
+  it('maps RPL_LUSERCLIENT to 251', () => {
+    expect(Numerics.RPL_LUSERCLIENT).toBe(251);
+  });
+
+  it('maps RPL_LUSEROP to 252', () => {
+    expect(Numerics.RPL_LUSEROP).toBe(252);
+  });
+
+  it('maps RPL_LUSERUNKNOWN to 253', () => {
+    expect(Numerics.RPL_LUSERUNKNOWN).toBe(253);
+  });
+
+  it('maps RPL_LUSERCHANNELS to 254', () => {
+    expect(Numerics.RPL_LUSERCHANNELS).toBe(254);
+  });
+
+  it('maps RPL_LUSERME to 255', () => {
+    expect(Numerics.RPL_LUSERME).toBe(255);
+  });
+
+  it('maps RPL_LOCALUSERS to 265', () => {
+    expect(Numerics.RPL_LOCALUSERS).toBe(265);
+  });
+
+  it('maps RPL_GLOBALUSERS to 266', () => {
+    expect(Numerics.RPL_GLOBALUSERS).toBe(266);
+  });
+
+  // -- STATS (RFC 2812 §4.6.3) -----------------------------------------------
+  it('maps RPL_STATSLINKINFO to 211', () => {
+    expect(Numerics.RPL_STATSLINKINFO).toBe(211);
+  });
+
+  it('maps RPL_ENDOFSTATS to 219', () => {
+    expect(Numerics.RPL_ENDOFSTATS).toBe(219);
+  });
+
+  it('maps RPL_STATSUPTIME to 242', () => {
+    expect(Numerics.RPL_STATSUPTIME).toBe(242);
+  });
+
+  it('maps ERR_WASNOSUCHNICK to 406', () => {
+    expect(Numerics.ERR_WASNOSUCHNICK).toBe(406);
+  });
+
   it('maps ERR_NICKNAMEINUSE to 433', () => {
     expect(Numerics.ERR_NICKNAMEINUSE).toBe(433);
   });
@@ -65,6 +139,26 @@ describe('numericToName', () => {
     expect(numericToName.get(1)).toBe('RPL_WELCOME');
   });
 
+  it('reverses RPL_LUSERCLIENT', () => {
+    expect(numericToName.get(251)).toBe('RPL_LUSERCLIENT');
+  });
+
+  it('reverses RPL_GLOBALUSERS', () => {
+    expect(numericToName.get(266)).toBe('RPL_GLOBALUSERS');
+  });
+
+  it('reverses RPL_STATSLINKINFO', () => {
+    expect(numericToName.get(211)).toBe('RPL_STATSLINKINFO');
+  });
+
+  it('reverses RPL_ENDOFSTATS', () => {
+    expect(numericToName.get(219)).toBe('RPL_ENDOFSTATS');
+  });
+
+  it('reverses RPL_STATSUPTIME', () => {
+    expect(numericToName.get(242)).toBe('RPL_STATSUPTIME');
+  });
+
   it('returns undefined for an unregistered code', () => {
     expect(numericToName.get(600)).toBeUndefined();
   });
@@ -95,4 +189,12 @@ describe('formatNumeric', () => {
   it('zero-pads RPL_ISUPPORT', () => {
     expect(formatNumeric('RPL_ISUPPORT')).toBe('005');
   });
+
+  it('formats RPL_LUSERCLIENT as 251', () => {
+    expect(formatNumeric('RPL_LUSERCLIENT')).toBe('251');
+  });
+
+  it('formats RPL_ENDOFSTATS as 219', () => {
+    expect(formatNumeric('RPL_ENDOFSTATS')).toBe('219');
+  });
 });

package/packages/irc-core/tests/outbound.test.ts

@@ -9,6 +9,7 @@ import {
 } from '../src/protocol/outbound';
 import { parse } from '../src/protocol/parser';
 import { serialize } from '../src/protocol/serializer';
+import { MAX_WS_MESSAGE_BYTES } from '../src/ws-framing';
 
 const L = (text: string): RawLine => ({ text });
 
@@ -192,6 +193,56 @@ describe('enforceLineLimit', () => {
   });
 });
 
+// ============================================================================
+// enforceLineLimit — budget-aware optional WsFrameMode parameter
+// ============================================================================
+
+describe('enforceLineLimit — WsFrameMode budget', () => {
+  // The optional `mode` parameter selects the byte budget. Spec modes cap at
+  // MAX_WS_MESSAGE_BYTES (510) directly — there is no trailing CRLF on a WS
+  // message. Legacy mode caps at MAX_LINE_BYTES - 2 (512 - 2 = 510). Both
+  // resolve to 510 today, but the API is mode-aware so a future change to
+  // either constant needs no call-site edits.
+  const SPEC_BUDGET = MAX_WS_MESSAGE_BYTES;
+
+  it('accepts an optional spec-text mode and caps at MAX_WS_MESSAGE_BYTES', () => {
+    const exact: RawLine = L('x'.repeat(SPEC_BUDGET));
+    expect(enforceLineLimit(exact, new Set<string>(), 'spec-text')).toBe(exact);
+
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const out = enforceLineLimit(tooLong, new Set<string>(), 'spec-text');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+  });
+
+  it('accepts an optional spec-binary mode and caps at MAX_WS_MESSAGE_BYTES', () => {
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const out = enforceLineLimit(tooLong, new Set<string>(), 'spec-binary');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+  });
+
+  it('uses the legacy budget when mode is explicitly "legacy"', () => {
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const out = enforceLineLimit(tooLong, new Set<string>(), 'legacy');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+  });
+
+  it('omitting mode defaults to the legacy budget (backward compatible)', () => {
+    const tooLong: RawLine = L('x'.repeat(SPEC_BUDGET + 5));
+    const withDefault = enforceLineLimit(tooLong, new Set<string>());
+    const withLegacy = enforceLineLimit(tooLong, new Set<string>(), 'legacy');
+    expect(withDefault).toEqual(withLegacy);
+  });
+
+  it('preserves the tag section in spec-text mode just as in legacy mode', () => {
+    const tagPrefix = '@time=2024-01-15T12:34:56.789Z ';
+    const body = `:alice PRIVMSG #foo :${'x'.repeat(500)}`;
+    const line: RawLine = L(`${tagPrefix}${body}`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']), 'spec-text');
+    expect(out.text.length).toBe(SPEC_BUDGET);
+    expect(out.text.startsWith(tagPrefix)).toBe(true);
+  });
+});
+
 // ============================================================================
 // Round-trip through serialize -> applyServerTime -> parse
 // ============================================================================

package/packages/irc-core/tests/ports.test.ts

@@ -5,6 +5,7 @@ import {
   ConsoleLogger,
   FakeClock,
   type IdFactory,
+  InMemoryMtlsIdentityProvider,
   LogLevel,
   type LogRecord,
   type Logger,
@@ -362,3 +363,24 @@ const _assertLogRecord: LogRecord = {
   msg: '',
 };
 void _assertLogRecord;
+
+describe('InMemoryMtlsIdentityProvider', () => {
+  it('returns the certificate subject for a known connection id', () => {
+    const provider = new InMemoryMtlsIdentityProvider([
+      { connId: 'c1', identity: 'CN=alice' },
+      { connId: 'c2', identity: 'CN=bob' },
+    ]);
+    expect(provider.getIdentity('c1')).toBe('CN=alice');
+    expect(provider.getIdentity('c2')).toBe('CN=bob');
+  });
+
+  it('returns undefined for an unknown connection id', () => {
+    const provider = new InMemoryMtlsIdentityProvider([{ connId: 'c1', identity: 'CN=alice' }]);
+    expect(provider.getIdentity('nope')).toBeUndefined();
+  });
+
+  it('handles an empty identity table', () => {
+    const provider = new InMemoryMtlsIdentityProvider([]);
+    expect(provider.getIdentity('c1')).toBeUndefined();
+  });
+});

package/packages/irc-core/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 removed numerics stay removed.
+ */
+declare module '*?raw' {
+  const content: string;
+  // eslint-disable-next-line import/no-default-export
+  export default content;
+}

package/packages/irc-core/tests/stats-store.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from 'vitest';
+import {
+  FakeClock,
+  InMemoryStats,
+  type ServerStats,
+  type ServerStatsSnapshot,
+  computeStatsSnapshot,
+} from '../src/ports';
+import type { ChannelState } from '../src/state/channel';
+import { createChannel } from '../src/state/channel';
+import type { ConnId, ConnectionState } from '../src/state/connection';
+import { createConnection } from '../src/state/connection';
+
+/** Builds a registered connection with the supplied modes. */
+function makeConn(
+  id: ConnId,
+  opts: { oper?: boolean; invisible?: boolean; registered?: boolean } = {},
+): ConnectionState {
+  const s = createConnection({ id, connectedSince: 0 });
+  s.nick = id;
+  s.user = id;
+  s.host = 'example.com';
+  s.realname = id;
+  s.registration = opts.registered === false ? 'pre-registration' : 'registered';
+  if (opts.oper !== undefined) s.userModes.oper = opts.oper;
+  if (opts.invisible !== undefined) s.userModes.invisible = opts.invisible;
+  return s;
+}
+
+function emptyChannel(name: string): ChannelState {
+  return createChannel({ name, nameLower: name.toLowerCase(), createdAt: 0 });
+}
+
+describe('InMemoryStats', () => {
+  it('implements the ServerStats port', () => {
+    const stats: ServerStats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+    expect(stats).toBeDefined();
+  });
+
+  it('returns zero counts for an empty deployment', async () => {
+    const stats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap).toEqual<ServerStatsSnapshot>({
+      users: 0,
+      invisible: 0,
+      opers: 0,
+      unknownConnections: 0,
+      channels: 0,
+      servers: 1,
+      localConns: 0,
+      globalConns: 0,
+      uptimeStartedAt: 0,
+      maxLocalConns: 0,
+      maxGlobalConns: 0,
+    });
+  });
+
+  it('derives the seed counts from the maps (3 conns, 1 oper, 2 channels)', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2', { invisible: true })],
+      ['c3', makeConn('c3', { oper: true })],
+    ]);
+    const channels = new Map<string, ChannelState>([
+      ['#a', emptyChannel('#a')],
+      ['#b', emptyChannel('#b')],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels,
+      uptimeStartedAt: 1_000,
+    });
+
+    const snap = await stats.getStats();
+
+    // 3 registered (2 visible + 1 invisible), 1 oper, 0 unknown, 2 channels.
+    expect(snap.users).toBe(2); // visible registered
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    expect(snap.unknownConnections).toBe(0);
+    expect(snap.channels).toBe(2);
+    expect(snap.servers).toBe(1);
+    expect(snap.localConns).toBe(3);
+    expect(snap.globalConns).toBe(3);
+    expect(snap.uptimeStartedAt).toBe(1_000);
+  });
+
+  it('counts pre-registration connections as unknown', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2', { registered: false })],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap.users).toBe(1);
+    expect(snap.unknownConnections).toBe(1);
+    expect(snap.localConns).toBe(2);
+  });
+
+  it('reports the live max as equal to current count when never higher', async () => {
+    const conns = new Map<ConnId, ConnectionState>([['c1', makeConn('c1')]]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+      maxLocalConns: 5,
+      maxGlobalConns: 7,
+    });
+
+    const snap = await stats.getStats();
+
+    expect(snap.maxLocalConns).toBe(5);
+    expect(snap.maxGlobalConns).toBe(7);
+  });
+
+  it('clamps max to the current count when the live count exceeds the recorded max', async () => {
+    const conns = new Map<ConnId, ConnectionState>([
+      ['c1', makeConn('c1')],
+      ['c2', makeConn('c2')],
+      ['c3', makeConn('c3')],
+    ]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+      maxLocalConns: 2,
+      maxGlobalConns: 2,
+    });
+
+    const snap = await stats.getStats();
+
+    // Live count (3) > seeded max (2); the snapshot reports the live value
+    // so the wire numeric never claims a max below the current count.
+    expect(snap.maxLocalConns).toBe(3);
+    expect(snap.maxGlobalConns).toBe(3);
+  });
+
+  it('reflects map mutations on subsequent getStats() calls', async () => {
+    const conns = new Map<ConnId, ConnectionState>([['c1', makeConn('c1')]]);
+    const stats = new InMemoryStats({
+      connections: conns,
+      channels: new Map(),
+      uptimeStartedAt: 0,
+    });
+
+    let snap = await stats.getStats();
+    expect(snap.users).toBe(1);
+
+    conns.set('c2', makeConn('c2'));
+    conns.set('c3', makeConn('c3', { invisible: true }));
+    snap = await stats.getStats();
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(1);
+    expect(snap.localConns).toBe(3);
+  });
+});
+
+describe('computeStatsSnapshot', () => {
+  it('counts opers separately from users (an oper still counts as a user)', () => {
+    const snap = computeStatsSnapshot([makeConn('c1'), makeConn('c2', { oper: true })], 0, 0);
+    expect(snap.users).toBe(2);
+    expect(snap.opers).toBe(1);
+  });
+
+  it('counts an oper who is also invisible under invisible + opers (not users)', () => {
+    const snap = computeStatsSnapshot([makeConn('c1', { oper: true, invisible: true })], 0, 0);
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    // users = visible registered (total registered − invisible).
+    expect(snap.users).toBe(0);
+  });
+
+  it('reports users as the visible-only count (total registered − invisible)', () => {
+    const snap = computeStatsSnapshot(
+      [
+        makeConn('c1'),
+        makeConn('c2'),
+        makeConn('c3', { invisible: true }),
+        makeConn('c4', { invisible: true }),
+      ],
+      0,
+      0,
+    );
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(2);
+    expect(snap.localConns).toBe(4);
+  });
+
+  it('defaults maxConns to the live count when seed omitted', () => {
+    const snap = computeStatsSnapshot([makeConn('c1'), makeConn('c2')], 0, 0);
+    expect(snap.maxLocalConns).toBe(2);
+    expect(snap.maxGlobalConns).toBe(2);
+  });
+
+  it('uses the FakeClock only for uptime (not in the snapshot)', async () => {
+    const clock = new FakeClock(99_000);
+    const stats = new InMemoryStats({
+      connections: new Map(),
+      channels: new Map(),
+      uptimeStartedAt: 1_000,
+      clock,
+    });
+    const snap = await stats.getStats();
+    expect(snap.uptimeStartedAt).toBe(1_000);
+  });
+});