pgserve 1.2.0 → 2.0.1

package/tests/fingerprint.test.js

@@ -0,0 +1,249 @@
+/**
+ * Tests for src/fingerprint.js — kernel-rooted peer identity.
+ *
+ * Coverage:
+ *  - getPeerCred() returns the calling process's pid/uid/gid via SO_PEERCRED
+ *  - findNearestPackageJson() walks upward; deepest match wins (monorepo)
+ *  - derivePackageFingerprint() is stable across cwd changes in the same project
+ *  - same name + different paths → different fingerprints
+ *  - same path + different uid → different fingerprints
+ *  - script fallback triggers when no package.json above cwd
+ *  - end-to-end: handleControlAccept() emits a connection_routed audit entry
+ */
+
+import { test, expect, beforeAll, beforeEach, afterEach } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import net from 'net';
+import {
+  initFingerprintFfi,
+  getPeerCred,
+  findNearestPackageJson,
+  readPackageName,
+  derivePackageFingerprint,
+  deriveScriptFingerprint,
+  fingerprintFromCred,
+  handleControlAccept,
+  _setPeerCredImpl,
+} from '../src/fingerprint.js';
+import { configureAudit, AUDIT_EVENTS } from '../src/audit.js';
+
+let scratch;
+
+beforeAll(async () => {
+  await initFingerprintFfi();
+});
+
+beforeEach(() => {
+  scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-fp-test-'));
+  configureAudit({
+    logFile: path.join(scratch, 'audit.log'),
+    target: 'file',
+  });
+});
+
+afterEach(() => {
+  _setPeerCredImpl(null);
+  try { fs.rmSync(scratch, { recursive: true, force: true }); } catch { /* noop */ }
+});
+
+// ---------------------------------------------------------------------------
+// SO_PEERCRED smoke — proves the FFI path works end-to-end on this kernel.
+// ---------------------------------------------------------------------------
+
+test('getPeerCred reads kernel-attested pid/uid/gid via Unix socket pair', async () => {
+  const sockPath = path.join(scratch, 'peer.sock');
+  const expectedUid = process.getuid();
+  const expectedGid = process.getgid();
+  const expectedPid = process.pid;
+
+  const cred = await new Promise((resolve, reject) => {
+    const server = net.createServer((socket) => {
+      try {
+        const c = getPeerCred(socket);
+        socket.end();
+        server.close(() => resolve(c));
+      } catch (err) {
+        server.close(() => reject(err));
+      }
+    });
+    server.on('error', reject);
+    server.listen(sockPath, () => {
+      const client = net.createConnection(sockPath);
+      client.on('error', reject);
+    });
+  });
+
+  expect(cred.pid).toBe(expectedPid);
+  expect(cred.uid).toBe(expectedUid);
+  expect(cred.gid).toBe(expectedGid);
+});
+
+// ---------------------------------------------------------------------------
+// Pure-function tests on derivation surface
+// ---------------------------------------------------------------------------
+
+test('fingerprint stable across cwd change in the same project', () => {
+  // Layout:
+  //   <scratch>/proj/package.json (name=alpha)
+  //   <scratch>/proj/sub/deep/
+  // Same project → same fingerprint regardless of starting cwd.
+  const proj = path.join(scratch, 'proj');
+  fs.mkdirSync(path.join(proj, 'sub', 'deep'), { recursive: true });
+  fs.writeFileSync(path.join(proj, 'package.json'), JSON.stringify({ name: 'alpha' }));
+
+  const root = findNearestPackageJson(proj);
+  const fromSub = findNearestPackageJson(path.join(proj, 'sub'));
+  const fromDeep = findNearestPackageJson(path.join(proj, 'sub', 'deep'));
+
+  expect(root).not.toBeNull();
+  expect(fromSub).toBe(root);
+  expect(fromDeep).toBe(root);
+
+  const fp1 = derivePackageFingerprint({ packageRealpath: root, name: 'alpha', uid: 1000 });
+  const fp2 = derivePackageFingerprint({ packageRealpath: fromSub, name: 'alpha', uid: 1000 });
+  const fp3 = derivePackageFingerprint({ packageRealpath: fromDeep, name: 'alpha', uid: 1000 });
+  expect(fp1).toBe(fp2);
+  expect(fp2).toBe(fp3);
+  expect(fp1).toMatch(/^[0-9a-f]{12}$/);
+});
+
+test('two projects with the same name but different paths get different fingerprints', () => {
+  const a = path.join(scratch, 'a-project');
+  const b = path.join(scratch, 'b-project');
+  fs.mkdirSync(a);
+  fs.mkdirSync(b);
+  fs.writeFileSync(path.join(a, 'package.json'), JSON.stringify({ name: 'shared' }));
+  fs.writeFileSync(path.join(b, 'package.json'), JSON.stringify({ name: 'shared' }));
+
+  const pa = findNearestPackageJson(a);
+  const pb = findNearestPackageJson(b);
+  expect(pa).not.toBe(pb);
+
+  const fpa = derivePackageFingerprint({ packageRealpath: pa, name: 'shared', uid: 1000 });
+  const fpb = derivePackageFingerprint({ packageRealpath: pb, name: 'shared', uid: 1000 });
+  expect(fpa).not.toBe(fpb);
+});
+
+test('same path + different uid → different fingerprints', () => {
+  const proj = path.join(scratch, 'multi-user');
+  fs.mkdirSync(proj);
+  fs.writeFileSync(path.join(proj, 'package.json'), JSON.stringify({ name: 'multi' }));
+  const realpath = findNearestPackageJson(proj);
+
+  const fp1000 = derivePackageFingerprint({ packageRealpath: realpath, name: 'multi', uid: 1000 });
+  const fp1001 = derivePackageFingerprint({ packageRealpath: realpath, name: 'multi', uid: 1001 });
+  expect(fp1000).not.toBe(fp1001);
+});
+
+test('script fallback triggered when no package.json above cwd', () => {
+  // Build an isolated path tree under scratch with no package.json anywhere.
+  // We point fingerprintFromCred at an override cwd inside scratch so the
+  // upward walk hits the filesystem root (no package.json in /tmp/.. either,
+  // because we use a deliberately ephemeral dir tree owned by the test).
+  const isolated = path.join(scratch, 'isolated', 'deep');
+  fs.mkdirSync(isolated, { recursive: true });
+
+  // Sanity: walking up from `isolated` finds no package.json (until at least
+  // /tmp/... or higher; we trust the host doesn't have one in /tmp).
+  // If the host *does* have one above /tmp, the result would still be deterministic
+  // and correct (mode='package'), but we want to test the script-fallback branch
+  // here. Mock findNearestPackageJson by passing a cwdOverride beneath a fake
+  // chroot — the easiest way is to walk to a path that we control: use an
+  // empty subtree under scratch and pretend the walk has hit the root.
+  const sentinelFile = findNearestPackageJson(isolated);
+  // If the host has no package.json anywhere up to /, sentinelFile is null.
+  // If it does, this assertion would falsely target the host's package.json.
+  // To make the test deterministic, we drive the script branch directly via
+  // deriveScriptFingerprint; the integration of "no package.json found" is
+  // covered by fingerprintFromCred's branch logic with cmdlineOverride.
+
+  const fp = deriveScriptFingerprint({
+    uid: 1000,
+    cwd: '/some/orphan/dir',
+    cmdline1: '/usr/local/bin/foo.js',
+  });
+  expect(fp).toMatch(/^[0-9a-f]{12}$/);
+
+  // Also verify fingerprintFromCred picks the script branch when cwdOverride
+  // points at a path with no ancestor package.json — we use a path under
+  // scratch since scratch itself has no package.json, and we pass cmdlineOverride.
+  const info = fingerprintFromCred(
+    { pid: 9999, uid: 1000, gid: 1000 },
+    {
+      cwdOverride: isolated,
+      cmdlineOverride: ['/usr/local/bin/bun', '/some/orphan/dir/foo.js'],
+    },
+  );
+  // sentinelFile may be null (script mode) or non-null (if host has /package.json upstream).
+  if (sentinelFile === null) {
+    expect(info.mode).toBe('script');
+    expect(info.fingerprint).toMatch(/^[0-9a-f]{12}$/);
+    expect(info.packageRealpath).toBeNull();
+  } else {
+    // Host has an ancestor package.json. Still verify that derivation produces
+    // a 12-hex value and that the 'package' branch was chosen — the
+    // script-fallback behavior is independently exercised by deriveScriptFingerprint above.
+    expect(info.mode).toBe('package');
+    expect(info.fingerprint).toMatch(/^[0-9a-f]{12}$/);
+  }
+});
+
+test('monorepo: nested package.json wins (deepest match)', () => {
+  // Layout:
+  //   <scratch>/mono/package.json           (name=workspace-root)
+  //   <scratch>/mono/packages/api/package.json (name=api)
+  //   <scratch>/mono/packages/api/src/
+  // Walking up from src/ must find the api package.json, not the workspace root.
+  const root = path.join(scratch, 'mono');
+  const api = path.join(root, 'packages', 'api');
+  const apiSrc = path.join(api, 'src');
+  fs.mkdirSync(apiSrc, { recursive: true });
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'workspace-root' }));
+  fs.writeFileSync(path.join(api, 'package.json'), JSON.stringify({ name: 'api' }));
+
+  const found = findNearestPackageJson(apiSrc);
+  expect(found).toBe(fs.realpathSync(path.join(api, 'package.json')));
+  expect(readPackageName(found)).toBe('api');
+
+  const info = fingerprintFromCred(
+    { pid: 9999, uid: 1000, gid: 1000 },
+    { cwdOverride: apiSrc, cmdlineOverride: ['bun', 'src/index.js'] },
+  );
+  expect(info.mode).toBe('package');
+  expect(info.name).toBe('api');
+  expect(info.packageRealpath).toBe(found);
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end: handleControlAccept emits connection_routed
+// ---------------------------------------------------------------------------
+
+test('handleControlAccept emits a connection_routed audit event with 12-hex fingerprint', () => {
+  const proj = path.join(scratch, 'audit-target');
+  fs.mkdirSync(proj);
+  fs.writeFileSync(path.join(proj, 'package.json'), JSON.stringify({ name: 'audit-app' }));
+
+  // Stub peer-cred impl so we don't need a real socket.
+  _setPeerCredImpl(() => ({ pid: 4242, uid: 1000, gid: 1000 }));
+
+  const info = handleControlAccept(
+    { /* fake socket */ },
+    { cwdOverride: proj, cmdlineOverride: ['bun', 'index.js'] },
+  );
+
+  expect(info.fingerprint).toMatch(/^[0-9a-f]{12}$/);
+  expect(info.mode).toBe('package');
+  expect(info.name).toBe('audit-app');
+
+  const logFile = path.join(scratch, 'audit.log');
+  const lines = fs.readFileSync(logFile, 'utf8').trim().split('\n').filter(Boolean);
+  expect(lines.length).toBe(1);
+  const entry = JSON.parse(lines[0]);
+  expect(entry.event).toBe(AUDIT_EVENTS.CONNECTION_ROUTED);
+  expect(entry.fingerprint).toBe(info.fingerprint);
+  expect(entry.peer_pid).toBe(4242);
+  expect(entry.peer_uid).toBe(1000);
+  expect(entry.mode).toBe('package');
+});

package/tests/fixtures/240-orphan-seed.sql

@@ -0,0 +1,30 @@
+-- Group 5 — synthetic orphan fixture.
+--
+-- Seeds 240 rows in `pgserve_meta` with stale `last_connection_at`
+-- (48 hours old, well past the 24h TTL) and a dead `liveness_pid`. Half
+-- the rows use a guaranteed-out-of-range PID (2147483646, far above
+-- Linux's pid_max ≤ 2^22 ≈ 4M); the other half use NULL so the sweep
+-- exercises both audit code paths (`db_reaped_liveness` vs `db_reaped_ttl`).
+--
+-- The accompanying harness `tests/orphan-cleanup.test.js` runs this file
+-- and then `CREATE DATABASE`s each row's `database_name` so the sweep
+-- actually has something to DROP.
+
+INSERT INTO pgserve_meta (
+  database_name,
+  fingerprint,
+  peer_uid,
+  package_realpath,
+  last_connection_at,
+  liveness_pid,
+  persist
+)
+SELECT
+  format('app_orphan_%s', lpad(to_hex(i), 12, '0')),
+  lpad(to_hex(i), 12, '0'),
+  1000,
+  NULL,
+  now() - interval '48 hours',
+  CASE WHEN i % 2 = 0 THEN 2147483646 ELSE NULL END,
+  false
+FROM generate_series(1, 240) AS i;

package/tests/orphan-cleanup.test.js

@@ -0,0 +1,390 @@
+/**
+ * Group 5 — orphan cleanup harness.
+ *
+ * Boots a real pgserve daemon (no GC triggers — we drive sweeps manually so
+ * we can assert exact counts and latency), applies the 240-orphan SQL
+ * fixture, creates 240 matching empty databases, runs one `gcSweep`, then
+ * asserts:
+ *   - all 240 rows gone from pgserve_meta
+ *   - all 240 user databases gone from pg_database
+ *   - audit log emitted 240 `db_reaped_*` events
+ *
+ * Plus the auxiliary cases the wish demands:
+ *   - persist=true row is exempt (audited as db_persist_honored, never reaped)
+ *   - live liveness_pid + stale last_connection_at slides the window forward
+ *     instead of reaping
+ *   - on-connect sweep listener returns under 50ms P99 (sweep is detached;
+ *     accept must not block on it)
+ */
+
+import {
+  describe,
+  test,
+  expect,
+  beforeAll,
+  afterAll,
+  beforeEach,
+} from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import {
+  PgserveDaemon,
+  resolveControlSocketPath,
+  resolvePidLockPath,
+  resolveLibpqCompatPath,
+} from '../src/daemon.js';
+import { _setPeerCredImpl, initFingerprintFfi } from '../src/fingerprint.js';
+import { configureAudit, AUDIT_EVENTS } from '../src/audit.js';
+import { gcSweep, installSweepTriggers } from '../src/gc.js';
+import { createLogger } from '../src/logger.js';
+
+const FIXTURE_PATH = path.join(__dirname, 'fixtures', '240-orphan-seed.sql');
+const ORPHAN_COUNT = 240;
+
+let scratchDir;
+let auditFile;
+let savedAuditDefaults;
+let daemon;
+let adminClient;
+
+beforeAll(async () => {
+  await initFingerprintFfi();
+  _setPeerCredImpl(() => ({
+    pid: process.pid,
+    uid: process.getuid(),
+    gid: process.getgid(),
+  }));
+
+  scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-gc-test-'));
+  const controlSocketDir = path.join(scratchDir, 'sock');
+  fs.mkdirSync(controlSocketDir, { recursive: true });
+  auditFile = path.join(scratchDir, 'audit.log');
+
+  savedAuditDefaults = {
+    logFile: path.join(os.homedir(), '.pgserve', 'audit.log'),
+    target: process.env.PGSERVE_AUDIT_TARGET || 'file',
+  };
+
+  daemon = new PgserveDaemon({
+    controlSocketDir,
+    controlSocketPath: resolveControlSocketPath(controlSocketDir),
+    pidLockPath: resolvePidLockPath(controlSocketDir),
+    libpqCompatPath: resolveLibpqCompatPath(controlSocketDir, 5432),
+    auditLogFile: auditFile,
+    auditTarget: 'file',
+    pgPort: 16720,
+    logger: createLogger({ level: process.env.LOG_LEVEL || 'warn' }),
+    // Tests drive sweeps explicitly — disable the auto-installed boot
+    // sweep + hourly timer + on-connect listener.
+    gcEnabled: false,
+  });
+  await daemon.start();
+  adminClient = daemon._adminClient;
+}, 90_000);
+
+afterAll(async () => {
+  try {
+    if (adminClient) {
+      const r = await adminClient.query(`
+        SELECT datname FROM pg_database
+        WHERE datname LIKE 'app_%' AND datistemplate = false
+      `);
+      for (const row of r.rows) {
+        try {
+          await adminClient.query(
+            `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1`,
+            [row.datname],
+          );
+          await adminClient.query(`DROP DATABASE IF EXISTS "${row.datname}"`);
+        } catch { /* swallow */ }
+      }
+    }
+  } catch { /* swallow */ }
+  try { await daemon?.stop(); } catch { /* swallow */ }
+  _setPeerCredImpl(null);
+  if (savedAuditDefaults) configureAudit(savedAuditDefaults);
+  try { fs.rmSync(scratchDir, { recursive: true, force: true }); } catch { /* swallow */ }
+});
+
+beforeEach(async () => {
+  // Reset audit log so each test sees only its own events.
+  try { fs.writeFileSync(auditFile, '', { mode: 0o600 }); } catch { /* swallow */ }
+  // Reset pgserve_meta + drop any leftover app_* DBs from prior tests.
+  await adminClient.query('TRUNCATE pgserve_meta');
+  const r = await adminClient.query(`
+    SELECT datname FROM pg_database
+    WHERE datname LIKE 'app_%' AND datistemplate = false
+  `);
+  for (const row of r.rows) {
+    try {
+      await adminClient.query(
+        `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1`,
+        [row.datname],
+      );
+      await adminClient.query(`DROP DATABASE IF EXISTS "${row.datname}"`);
+    } catch { /* swallow */ }
+  }
+});
+
+function readAudit() {
+  if (!fs.existsSync(auditFile)) return [];
+  return fs.readFileSync(auditFile, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+}
+
+async function applyFixture() {
+  const sql = fs.readFileSync(FIXTURE_PATH, 'utf8');
+  await adminClient.query(sql);
+}
+
+async function createSeededDatabases() {
+  // The fixture writes 240 deterministic database_name values. Read them
+  // back and materialise the matching empty databases. Run in batches so
+  // the embedded PG admin pool isn't swamped (default max=2).
+  const r = await adminClient.query(
+    `SELECT database_name FROM pgserve_meta ORDER BY database_name`,
+  );
+  const names = r.rows.map((row) => row.database_name);
+  const batchSize = 8;
+  for (let i = 0; i < names.length; i += batchSize) {
+    const slice = names.slice(i, i + batchSize);
+    await Promise.all(slice.map((dbName) =>
+      adminClient.query(`CREATE DATABASE "${dbName}"`).catch((err) => {
+        // 42P04 = duplicate_database — tolerated, the DB already exists
+        // from a prior test run that bailed before cleanup.
+        if (!(err?.code === '42P04' || /already exists/i.test(err?.message || ''))) {
+          throw err;
+        }
+      }),
+    ));
+  }
+  return names;
+}
+
+async function countMetaRows() {
+  const r = await adminClient.query(`SELECT count(*)::int AS n FROM pgserve_meta`);
+  return r.rows[0].n;
+}
+
+async function countUserDatabases() {
+  const r = await adminClient.query(`
+    SELECT count(*)::int AS n FROM pg_database
+    WHERE datname LIKE 'app_orphan_%' AND datistemplate = false
+  `);
+  return r.rows[0].n;
+}
+
+describe('gcSweep: 240-orphan fixture', () => {
+  test('one sweep reaps all 240 ephemeral orphans', async () => {
+    await applyFixture();
+    await createSeededDatabases();
+
+    expect(await countMetaRows()).toBe(ORPHAN_COUNT);
+    expect(await countUserDatabases()).toBe(ORPHAN_COUNT);
+
+    const result = await gcSweep({
+      adminClient,
+      pgManager: daemon.pgManager,
+      now: new Date(),
+      logger: daemon.logger,
+    });
+
+    expect(result.examined).toBe(ORPHAN_COUNT);
+    expect(result.reaped).toBe(ORPHAN_COUNT);
+    expect(result.kept).toBe(0);
+
+    // pgserve_meta empty.
+    expect(await countMetaRows()).toBe(0);
+    // pg_database has no app_orphan_* rows left.
+    expect(await countUserDatabases()).toBe(0);
+
+    const events = readAudit();
+    const reapEvents = events.filter(
+      (e) => e.event === AUDIT_EVENTS.DB_REAPED_TTL ||
+             e.event === AUDIT_EVENTS.DB_REAPED_LIVENESS,
+    );
+    expect(reapEvents.length).toBe(ORPHAN_COUNT);
+
+    // Fixture splits 50/50 between liveness_pid=NULL and a dead pid →
+    // both audit code paths fire.
+    const ttl = events.filter((e) => e.event === AUDIT_EVENTS.DB_REAPED_TTL);
+    const liveness = events.filter((e) => e.event === AUDIT_EVENTS.DB_REAPED_LIVENESS);
+    expect(ttl.length).toBe(120);
+    expect(liveness.length).toBe(120);
+  }, 120_000);
+});
+
+describe('gcSweep: persist + liveness exemptions', () => {
+  test('persist=true row is never reaped, even past TTL', async () => {
+    // Seed one persist=true row past TTL plus one ephemeral past TTL.
+    await adminClient.query(`
+      INSERT INTO pgserve_meta (
+        database_name, fingerprint, peer_uid, last_connection_at, liveness_pid, persist
+      ) VALUES
+        ('app_persist_aaaaaaaaaaaa', 'aaaaaaaaaaaa', 1000, now() - interval '48 hours', NULL, true),
+        ('app_orphan_bbbbbbbbbbbb',  'bbbbbbbbbbbb', 1000, now() - interval '48 hours', NULL, false)
+    `);
+    await adminClient.query(`CREATE DATABASE "app_persist_aaaaaaaaaaaa"`);
+    await adminClient.query(`CREATE DATABASE "app_orphan_bbbbbbbbbbbb"`);
+
+    const result = await gcSweep({
+      adminClient,
+      pgManager: daemon.pgManager,
+      now: new Date(),
+      logger: daemon.logger,
+    });
+
+    // The persist=true row never appears via forEachReapable (the SQL
+    // filter excludes it), so result.examined == 1 (only the orphan).
+    expect(result.reaped).toBe(1);
+    expect(result.reapedNames).toEqual(['app_orphan_bbbbbbbbbbbb']);
+
+    const remaining = await adminClient.query(
+      `SELECT database_name, persist FROM pgserve_meta ORDER BY database_name`,
+    );
+    expect(remaining.rows).toEqual([
+      { database_name: 'app_persist_aaaaaaaaaaaa', persist: true },
+    ]);
+
+    const persistDb = await adminClient.query(
+      `SELECT 1 FROM pg_database WHERE datname = 'app_persist_aaaaaaaaaaaa'`,
+    );
+    expect(persistDb.rows.length).toBe(1);
+  }, 60_000);
+
+  test('live liveness_pid + stale last_connection_at slides window, no reap', async () => {
+    const livePid = process.pid; // self — guaranteed alive
+    await adminClient.query(`
+      INSERT INTO pgserve_meta (
+        database_name, fingerprint, peer_uid, last_connection_at, liveness_pid, persist
+      ) VALUES
+        ('app_live_cccccccccccc', 'cccccccccccc', 1000, now() - interval '48 hours', $1, false)
+    `, [livePid]);
+    await adminClient.query(`CREATE DATABASE "app_live_cccccccccccc"`);
+
+    const before = await adminClient.query(
+      `SELECT last_connection_at FROM pgserve_meta WHERE database_name = $1`,
+      ['app_live_cccccccccccc'],
+    );
+    const beforeMs = before.rows[0].last_connection_at.getTime();
+
+    const result = await gcSweep({
+      adminClient,
+      pgManager: daemon.pgManager,
+      now: new Date(),
+      logger: daemon.logger,
+    });
+
+    expect(result.reaped).toBe(0);
+    expect(result.aliveSkipped).toBe(1);
+
+    const after = await adminClient.query(
+      `SELECT last_connection_at FROM pgserve_meta WHERE database_name = $1`,
+      ['app_live_cccccccccccc'],
+    );
+    expect(after.rows.length).toBe(1);
+    const afterMs = after.rows[0].last_connection_at.getTime();
+    // Slid forward: new timestamp > old by at least the staleness gap.
+    expect(afterMs).toBeGreaterThan(beforeMs + 24 * 60 * 60 * 1000);
+  }, 60_000);
+});
+
+describe('installSweepTriggers: on-connect sweep is non-blocking', () => {
+  test('emit("accept") returns under 50ms P99 even with always-sample rate', async () => {
+    // Use a stub admin client that simulates a slow GC (artificially long
+    // pgserve_meta query). If the listener weren't detached, every emit()
+    // would wait on this — the test would time out at 200ms × N samples.
+    let sweepCount = 0;
+    const slowAdmin = {
+      async query(_text, _params) {
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        sweepCount += 1;
+        return { rows: [], rowCount: 0 };
+      },
+    };
+    // Force "always sample" by passing getDbCount = 1 (so N = max(1,1/10) = 1)
+    // and dbCount low enough that the rate is 1/1 = always.
+    const handle = installSweepTriggers(daemon, {
+      adminClient: slowAdmin,
+      intervalMs: 0,
+      bootSweep: false,
+      getDbCount: () => 1,
+    });
+    try {
+      const samples = [];
+      for (let i = 0; i < 100; i++) {
+        const t0 = process.hrtime.bigint();
+        daemon.emit('accept', { fingerprint: 'aaaaaaaaaaaa', socket: {} });
+        const t1 = process.hrtime.bigint();
+        samples.push(Number(t1 - t0) / 1e6); // ns → ms
+      }
+      samples.sort((a, b) => a - b);
+      const p99 = samples[Math.floor(samples.length * 0.99) - 1];
+      expect(p99).toBeLessThan(50);
+    } finally {
+      await handle.stop();
+    }
+    // Sanity: at least the boot=false branch ran, so sweepCount may be 0
+    // if the rate decided not to sample, but the latency check is the
+    // load-bearing assertion.
+    expect(sweepCount).toBeGreaterThanOrEqual(0);
+  }, 60_000);
+});
+
+describe('installSweepTriggers: boot sweep logs summary', () => {
+  test('boot sweep runs once and reports counts via logger.info', async () => {
+    // Seed three rows: two reapable, one persist.
+    await adminClient.query(`
+      INSERT INTO pgserve_meta (
+        database_name, fingerprint, peer_uid, last_connection_at, liveness_pid, persist
+      ) VALUES
+        ('app_boot_aaaaaaaaaaaa', 'aaaaaaaaaaaa', 1000, now() - interval '48 hours', NULL, false),
+        ('app_boot_bbbbbbbbbbbb', 'bbbbbbbbbbbb', 1000, now() - interval '48 hours', NULL, false),
+        ('app_boot_cccccccccccc', 'cccccccccccc', 1000, now() - interval '48 hours', NULL, true)
+    `);
+    await adminClient.query(`CREATE DATABASE "app_boot_aaaaaaaaaaaa"`);
+    await adminClient.query(`CREATE DATABASE "app_boot_bbbbbbbbbbbb"`);
+    await adminClient.query(`CREATE DATABASE "app_boot_cccccccccccc"`);
+
+    const calls = [];
+    const captureLogger = {
+      info: (...args) => calls.push({ level: 'info', args }),
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    };
+    const stubDaemon = Object.assign(Object.create(daemon), {
+      logger: captureLogger,
+    });
+    // Object.create copies prototype, so emitter methods are inherited.
+
+    const handle = installSweepTriggers(stubDaemon, {
+      adminClient,
+      intervalMs: 0,
+      bootSweep: true,
+    });
+    try {
+      // Wait for setImmediate-scheduled boot sweep.
+      const deadline = Date.now() + 5000;
+      while (Date.now() < deadline) {
+        const summary = calls.find((c) =>
+          typeof c.args[1] === 'string' && c.args[1].includes('boot sweep complete'),
+        );
+        if (summary) break;
+        await new Promise((r) => setTimeout(r, 50));
+      }
+      const summary = calls.find((c) =>
+        typeof c.args[1] === 'string' && c.args[1].includes('boot sweep complete'),
+      );
+      expect(summary).toBeDefined();
+      expect(summary.args[0].reaped).toBe(2);
+      expect(summary.args[0].persist_skipped).toBe(0); // forEachReapable filter excludes persist=true rows from `examined` entirely
+    } finally {
+      await handle.stop();
+    }
+  }, 60_000);
+});