@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/core/__tests__/catalog-revision.test.ts

@@ -0,0 +1,190 @@
+import express from 'express';
+import type { AddressInfo } from 'node:net';
+import type { Server } from 'node:http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { SkillSummary } from '../../modules/skills/skills.contract.js';
+import { catalogRevision, createCatalogRevisionRoutes } from '../catalog-revision.js';
+
+/**
+ * The fingerprint a long-lived client polls to learn that the released catalog
+ * moved under it.
+ *
+ * What it must get right is narrow but exact: change when the catalog changed,
+ * and NOT otherwise. A digest that flaps re-registers an MCP session on every
+ * connected laptop for nothing; a digest that misses a change leaves a tool
+ * the author just wrote invisible until someone restarts the process — the bug
+ * this exists to close.
+ */
+
+/**
+ * A manual's line as `IToolManualService.catalogFingerprints` renders it:
+ * identity plus a digest of the file it was parsed from. Opaque here on
+ * purpose — what goes into one is the tool catalog's business, and
+ * `tool-manuals.service.test.ts` is where the fields that move it are pinned.
+ */
+const manualLine = (name: string, source = 'src-1'): string =>
+  [name, name, `Plugins/Everyone/${name}.tool`, 'http', 'remote', 'Web search.', source].join('\u0000');
+
+const skill = (over: Partial<SkillSummary> = {}): SkillSummary => ({
+  name: 'rfi',
+  description: 'Answers RFIs.',
+  path: 'Skills/Ops/rfi',
+  ...over,
+});
+
+describe('catalogRevision', () => {
+  it('is stable for the same catalog', () => {
+    expect(catalogRevision([manualLine('serper')], [skill()])).toBe(
+      catalogRevision([manualLine('serper')], [skill()]),
+    );
+  });
+
+  it('does not change when the same set arrives in another order', () => {
+    const x = skill({ name: 'x' });
+    const y = skill({ name: 'y' });
+    expect(catalogRevision([manualLine('a'), manualLine('b')], [x, y])).toBe(
+      catalogRevision([manualLine('b'), manualLine('a')], [y, x]),
+    );
+  });
+
+  describe('a manual added, changed or removed', () => {
+    const base = catalogRevision([manualLine('serper')], []);
+
+    it('changes when one is added', () => {
+      expect(catalogRevision([manualLine('serper'), manualLine('other')], [])).not.toBe(base);
+    });
+
+    it('changes when one is removed', () => {
+      expect(catalogRevision([], [])).not.toBe(base);
+    });
+
+    /**
+     * The line moved without the set changing size: a manual whose file was
+     * edited in place — a new `url`, a new header, another inline tool — is a
+     * different callable thing under the same name, and a client holding the
+     * old one has to be told.
+     */
+    it('changes when a manual line moves but the set does not', () => {
+      expect(catalogRevision([manualLine('serper', 'src-2')], [])).not.toBe(base);
+    });
+  });
+
+  describe('a skill added, changed or removed', () => {
+    const base = catalogRevision([], [skill()]);
+
+    it('changes when one is added', () => {
+      expect(catalogRevision([], [skill(), skill({ name: 'triage' })])).not.toBe(base);
+    });
+
+    it('changes when one is removed', () => {
+      expect(catalogRevision([], [])).not.toBe(base);
+    });
+
+    it.each([
+      ['its name', skill({ name: 'renamed' })],
+      ['its folder', skill({ path: 'Plugins/Ops/rfi' })],
+      ['its description', skill({ description: 'Something else.' })],
+      ['its version', skill({ version: '2.0.0' })],
+    ])('changes when %s changes', (_what, changed) => {
+      expect(catalogRevision([], [changed])).not.toBe(base);
+    });
+  });
+
+  /**
+   * A manual and a skill are different things even when they read alike: one
+   * of each, rendering to the same text, must not hash to the same catalog —
+   * otherwise renaming a skill to a departing tool's name would look like no
+   * change at all.
+   */
+  it('keeps the two catalogs apart', () => {
+    const line = 'rfi\u0000Skills/Ops/rfi\u0000\u0000\u0000Answers RFIs.';
+    expect(catalogRevision([line], [])).not.toBe(catalogRevision([], [skill()]));
+  });
+});
+
+describe('GET /agent/catalog-revision', () => {
+  let http: Server | null = null;
+
+  afterEach(async () => {
+    if (http) await new Promise<void>((resolve) => http!.close(() => resolve()));
+    http = null;
+  });
+
+  async function mount(deps: {
+    manuals: string[];
+    skills: SkillSummary[];
+    userId?: string | undefined;
+    resolveUserEmail?: (userId: string) => Promise<string | undefined>;
+  }): Promise<{
+    url: string;
+    catalogFingerprints: ReturnType<typeof vi.fn>;
+    listSkills: ReturnType<typeof vi.fn>;
+  }> {
+    const catalogFingerprints = vi.fn(async () => deps.manuals);
+    const listSkills = vi.fn(async () => deps.skills);
+    const app = express();
+    app.use(
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints } as never,
+        skills: { listSkills } as never,
+        manualAuth: (req, _res, next) => {
+          if (deps.userId !== undefined) req.toolAuth = { userId: deps.userId } as never;
+          next();
+        },
+        resolveUserEmail: deps.resolveUserEmail ?? (async () => 'someone@example.com'),
+      }),
+    );
+    http = app.listen(0);
+    await new Promise<void>((resolve) => http!.once('listening', resolve));
+    return {
+      url: `http://127.0.0.1:${(http.address() as AddressInfo).port}`,
+      catalogFingerprints,
+      listSkills,
+    };
+  }
+
+  it("answers the caller's own fingerprint, with the counts behind it", async () => {
+    const { url, catalogFingerprints, listSkills } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [skill()],
+      userId: 'u1',
+    });
+    const body = await (await fetch(`${url}/agent/catalog-revision`)).json();
+
+    expect(body).toEqual({
+      revision: catalogRevision([manualLine('serper')], [skill()]),
+      tools: 1,
+      skills: 1,
+    });
+    // Per-caller and ACL-filtered by the services themselves: the route adds
+    // no second read model that could show a tool the listing hides.
+    expect(catalogFingerprints).toHaveBeenCalledWith('someone@example.com');
+    expect(listSkills).toHaveBeenCalledWith('someone@example.com');
+  });
+
+  it('answers an unresolvable caller the empty catalog, as both listings do', async () => {
+    const { url, catalogFingerprints } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [skill()],
+      userId: undefined,
+    });
+    const body = await (await fetch(`${url}/agent/catalog-revision`)).json();
+
+    expect(body).toEqual({ revision: catalogRevision([], []), tools: 0, skills: 0 });
+    expect(catalogFingerprints).not.toHaveBeenCalled();
+  });
+
+  it('does not fail the request when the email lookup throws', async () => {
+    const { url } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [],
+      userId: 'u1',
+      resolveUserEmail: async () => {
+        throw new Error('database is asleep');
+      },
+    });
+    const res = await fetch(`${url}/agent/catalog-revision`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ revision: catalogRevision([], []), tools: 0, skills: 0 });
+  });
+});

package/src/core/__tests__/lifecycle.test.ts

@@ -0,0 +1,369 @@
+import { describe, it, expect } from 'vitest';
+import { createShutdown, holdCommitWorkerLease, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import type { AdvisoryLease } from '../../modules/database/advisory-lock.js';
+
+/** A lease the suite scripts: what each `tryAcquire` answers, and a way to lose it. */
+function fakeLease(answers: boolean[]) {
+  let held = false;
+  let lost: (() => void) | null = null;
+  const record = { asked: 0, released: 0 };
+  const lease = {
+    get held() {
+      return held;
+    },
+    onLost(cb: () => void) {
+      lost = cb;
+    },
+    async tryAcquire() {
+      if (held) return true;
+      record.asked += 1;
+      held = answers.shift() ?? false;
+      return held;
+    },
+    async release() {
+      record.released += 1;
+      held = false;
+    },
+  } as unknown as AdvisoryLease;
+  return {
+    lease,
+    record,
+    lose() {
+      held = false;
+      lost?.();
+    },
+  };
+}
+
+/** A worker that records its transitions, and can hold its stop open. */
+function fakeWorker() {
+  const events: string[] = [];
+  let releaseStop: (() => void) | null = null;
+  const worker: LeasedWorker = {
+    start() {
+      events.push('start');
+    },
+    stop() {
+      events.push('stop');
+      return new Promise<void>((resolve) => {
+        releaseStop = resolve;
+      });
+    },
+  };
+  return { worker, events, finishStop: () => releaseStop?.() };
+}
+
+/** A sleep the suite steps by hand, so nothing here waits on a clock. */
+function manualSleep() {
+  const pending: Array<() => void> = [];
+  return {
+    sleep: () =>
+      new Promise<void>((resolve) => {
+        pending.push(resolve);
+      }),
+    // Resolves EVERY sleep started so far: a loop woken early leaves its
+    // sleep's resolver behind, and a tick that only served the oldest one
+    // would wake that stale sleep and leave the live one waiting.
+    tick: async () => {
+      for (const wake of pending.splice(0)) wake();
+      await Promise.resolve();
+      await Promise.resolve();
+    },
+  };
+}
+
+const settle = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+describe('holdCommitWorkerLease', () => {
+  it('starts the worker only once the lease is held, and not before', async () => {
+    const { lease, record } = fakeLease([false, false, true]);
+    const { worker, events, finishStop } = fakeWorker();
+    const clock = manualSleep();
+
+    const handle = holdCommitWorkerLease(lease, worker, { sleep: clock.sleep, log: () => undefined });
+    await settle();
+    expect(events).toEqual([]);
+    expect(handle.held).toBe(false);
+
+    await clock.tick();
+    await settle();
+    expect(events).toEqual([]);
+
+    await clock.tick();
+    await settle();
+    expect(events).toEqual(['start']);
+    expect(handle.held).toBe(true);
+    expect(record.asked).toBe(3);
+
+    // The handle's stop waits for the worker's, which this fake holds open.
+    const stopping = handle.stop();
+    await settle();
+    finishStop();
+    await stopping;
+  });
+
+  it('stops the worker when the lease is lost, and starts it again once re-held', async () => {
+    const { lease, lose } = fakeLease([true, true]);
+    const { worker, events, finishStop } = fakeWorker();
+    const clock = manualSleep();
+
+    const handle = holdCommitWorkerLease(lease, worker, { sleep: clock.sleep, log: () => undefined });
+    await settle();
+    expect(events).toEqual(['start']);
+
+    lose();
+    await settle();
+    expect(events).toEqual(['start', 'stop']);
+    expect(handle.held).toBe(false);
+
+    // Re-acquired while the old stop is still in flight: no second start yet.
+    await clock.tick();
+    await settle();
+    expect(events).toEqual(['start', 'stop']);
+
+    // Once the stop finishes, the next pass re-takes the lease and restarts.
+    finishStop();
+    await settle();
+    await clock.tick();
+    await settle();
+    expect(events).toEqual(['start', 'stop', 'start']);
+
+    // Same as above: release the worker's stop only once the handle has asked for it.
+    const stopping = handle.stop();
+    await settle();
+    finishStop();
+    await stopping;
+  });
+
+  it('stop() ends the worker, then releases the lease, and is idempotent', async () => {
+    const { lease, record } = fakeLease([true]);
+    const { worker, events, finishStop } = fakeWorker();
+    const clock = manualSleep();
+
+    const handle = holdCommitWorkerLease(lease, worker, { sleep: clock.sleep, log: () => undefined });
+    await settle();
+
+    const stopping = handle.stop();
+    await settle();
+    // The lease is still held while the in-flight commit finishes: releasing
+    // first would let the replacement start draining the same clone.
+    expect(events).toEqual(['start', 'stop']);
+    expect(record.released).toBe(0);
+
+    finishStop();
+    await stopping;
+    expect(record.released).toBe(1);
+
+    await handle.stop();
+    expect(record.released).toBe(1);
+  });
+});
+
+describe('withStartupTask', () => {
+  it('runs the task to completion before the worker starts, and a stop meanwhile waits for both', async () => {
+    const events: string[] = [];
+    let finishTask: () => void = () => undefined;
+    const worker: LeasedWorker = {
+      start: () => void events.push('start'),
+      stop: async () => void events.push('stop'),
+    };
+    const leased = withStartupTask(
+      worker,
+      () =>
+        new Promise<void>((resolve) => {
+          events.push('task');
+          finishTask = resolve;
+        }),
+    );
+
+    leased.start();
+    await settle();
+    expect(events).toEqual(['task']);
+
+    const stopping = leased.stop();
+    await settle();
+    expect(events).toEqual(['task']);
+    finishTask();
+    await stopping;
+    expect(events).toEqual(['task', 'start', 'stop']);
+  });
+
+  it('starts the worker even when the task fails, and says so', async () => {
+    const events: string[] = [];
+    const logged: string[] = [];
+    const leased = withStartupTask(
+      { start: () => void events.push('start'), stop: async () => undefined },
+      async () => {
+        throw new Error('reconcile broke');
+      },
+      (m) => logged.push(m),
+    );
+    leased.start();
+    await settle();
+    expect(events).toEqual(['start']);
+    expect(logged).toEqual(['startup task failed; the worker starts regardless: Error: reconcile broke']);
+  });
+});
+
+describe('createShutdown', () => {
+  function deps() {
+    const order: string[] = [];
+    let closeCallback: (() => void) | null = null;
+    return {
+      order,
+      finishClose: () => closeCallback?.(),
+      deps: {
+        server: {
+          close(cb?: () => void) {
+            order.push('server.close');
+            closeCallback = cb ?? null;
+            return this as never;
+          },
+          closeAllConnections() {
+            order.push('server.closeAllConnections');
+          },
+        },
+        commitWorker: {
+          async stop() {
+            order.push('commitWorker.stop');
+          },
+        },
+        backgroundJobs: {
+          stopSweeping() {
+            order.push('backgroundJobs.stopSweeping');
+          },
+          async drain() {
+            order.push('backgroundJobs.drain');
+          },
+        },
+        db: {
+          $client: {
+            async end() {
+              order.push('db.end');
+            },
+          },
+        },
+        log: () => undefined,
+      },
+    };
+  }
+
+  it('lets go in order: stop accepting, drop connections, finish the worker, end the pool', async () => {
+    const d = deps();
+    const shutdown = createShutdown(d.deps as never);
+
+    const done = shutdown('SIGTERM');
+    await settle();
+    // The server's close waits for its callback; nothing further has run.
+    expect(d.order).toEqual(['server.close', 'server.closeAllConnections']);
+
+    d.finishClose();
+    await done;
+    expect(d.order).toEqual([
+      'server.close',
+      'server.closeAllConnections',
+      'backgroundJobs.stopSweeping',
+      'backgroundJobs.drain',
+      'commitWorker.stop',
+      'db.end',
+    ]);
+  });
+
+  it('waits for the jobs a tick already started before the pool goes, within the budget', async () => {
+    const d = deps();
+    let release: () => void = () => undefined;
+    d.deps.backgroundJobs!.drain = () => {
+      d.order.push('backgroundJobs.drain');
+      return new Promise<void>((resolve) => {
+        release = resolve;
+      });
+    };
+    const shutdown = createShutdown(d.deps as never);
+    const done = shutdown('SIGTERM');
+    await settle();
+    d.finishClose();
+    await settle();
+    // The jobs are still running: nothing after them has run.
+    expect(d.order).toEqual(['server.close', 'server.closeAllConnections', 'backgroundJobs.stopSweeping', 'backgroundJobs.drain']);
+    release();
+    await done;
+    expect(d.order.slice(-2)).toEqual(['commitWorker.stop', 'db.end']);
+  });
+
+  it('stops the background sweep before anything it could outlive', async () => {
+    const d = deps();
+    const shutdown = createShutdown(d.deps as never);
+    const done = shutdown('SIGTERM');
+    await settle();
+    d.finishClose();
+    await done;
+
+    // Order is the point, not just presence, in BOTH directions. A tick that
+    // fired after `db.end` would query a client that is gone; a tick during
+    // `commitWorker.stop` — which awaits an in-flight commit and can take
+    // most of the shutdown budget — would start fresh clone/commit/push work
+    // that the process exit immediately after kills mid-git.
+    const stopped = d.order.indexOf('backgroundJobs.stopSweeping');
+    expect(stopped).toBeGreaterThanOrEqual(0);
+    expect(stopped).toBeLessThan(d.order.indexOf('commitWorker.stop'));
+    expect(stopped).toBeLessThan(d.order.indexOf('db.end'));
+  });
+
+  it('shuts down cleanly when no background jobs were built yet', async () => {
+    const d = deps();
+    // A stop that lands mid-boot: the services exist, the jobs do not.
+    delete (d.deps as { backgroundJobs?: unknown }).backgroundJobs;
+    const shutdown = createShutdown(d.deps as never);
+    const done = shutdown('SIGTERM');
+    await settle();
+    d.finishClose();
+    await expect(done).resolves.toBeUndefined();
+    expect(d.order).toEqual([
+      'server.close',
+      'server.closeAllConnections',
+      'commitWorker.stop',
+      'db.end',
+    ]);
+  });
+
+  it('does not wait past the budget for jobs that never finish, and still ends the pool', async () => {
+    const d = deps();
+    d.deps.backgroundJobs!.drain = () => {
+      d.order.push('backgroundJobs.drain');
+      return new Promise<void>(() => undefined); // a clone that never returns
+    };
+    const shutdown = createShutdown(d.deps as never, { deadlineMs: 60 });
+    const done = shutdown('SIGTERM');
+    await settle();
+    d.finishClose();
+    await done;
+    expect(d.order.slice(-3)).toEqual(['backgroundJobs.drain', 'commitWorker.stop', 'db.end']);
+  });
+
+  it('does not hang on a step that never finishes, and still runs the rest', async () => {
+    const d = deps();
+    // A server whose close callback never comes — a connection that will not drain.
+    const shutdown = createShutdown(d.deps as never, { deadlineMs: 60 });
+
+    await shutdown('SIGTERM');
+    expect(d.order).toEqual([
+      'server.close',
+      'server.closeAllConnections',
+      'backgroundJobs.stopSweeping',
+      'backgroundJobs.drain',
+      'commitWorker.stop',
+      'db.end',
+    ]);
+  });
+
+  it('runs once: a second signal joins the sequence already under way', async () => {
+    const d = deps();
+    const shutdown = createShutdown(d.deps as never);
+
+    const first = shutdown('SIGTERM');
+    const second = shutdown('SIGINT');
+    d.finishClose();
+    await Promise.all([first, second]);
+    expect(d.order.filter((step) => step === 'db.end')).toHaveLength(1);
+  });
+});

package/src/core/__tests__/public-config.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { publicConfig } from '../public-config.js';
+
+describe('GET /api/config payload', () => {
+  const body = publicConfig({ marketplaceGitUrl: 'https://kb.acme.com/git/marketplace.git', mcpUrl: 'https://kb.acme.com/api/mcp' });
+
+  it('advertises the agent-instructions capability, which the local bridge keys on', () => {
+    expect(body.agentInstructions).toBe(true);
+  });
+
+  /**
+   * The local bridge polls `/api/agent/catalog-revision` to notice a manual or
+   * a skill changing under a live connection — but only when this says the
+   * route is there. It must never probe: an unknown `/api/*` path falls
+   * through to the JWT mounts and answers 401, which the bridge reads as a
+   * rejected credential.
+   */
+  it('advertises the catalog-revision capability, on the same terms', () => {
+    expect(body.catalogRevision).toBe(true);
+  });
+
+  it('carries the branch model and the two addresses it was handed', () => {
+    expect(body.branchModel.defaultBranch).toBe(DEFAULT_BRANCH);
+    expect(body.branchModel.protectedBranches).toContain(DEFAULT_BRANCH);
+    expect(body.mcpUrl).toBe('https://kb.acme.com/api/mcp');
+    expect(body.marketplaceGitUrl).toBe('https://kb.acme.com/git/marketplace.git');
+    expect(body.kbLayout).toBeDefined();
+  });
+});

package/src/core/__tests__/readiness.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createReadiness,
+  DISK_FREE_DEGRADED_BYTES,
+  QUEUE_AGE_DEGRADED_MS,
+  type ReadinessDeps,
+} from '../readiness.js';
+
+const NOW = new Date('2026-09-15T12:00:00Z').getTime();
+
+/** A healthy deployment, which each case then breaks in exactly one place. */
+function healthy(overrides: Partial<ReadinessDeps> = {}): ReadinessDeps {
+  return {
+    db: { execute: async () => [] as never },
+    oldestQueuedAt: async () => null,
+    drains: () => true,
+    lastRemoteContact: () => ({ at: NOW - 30_000, ok: true }),
+    freeBytes: async () => 50 * DISK_FREE_DEGRADED_BYTES,
+    now: () => NOW,
+    ...overrides,
+  };
+}
+
+describe('createReadiness', () => {
+  it('reports ok when every fact is fine, with the numbers an alert would read', async () => {
+    const report = await createReadiness(healthy())();
+    expect(report.status).toBe('ok');
+    expect(report.checks.commitQueue).toEqual({ ok: true, oldestPendingSeconds: null, draining: true });
+    expect(report.checks.gitRemote).toEqual({ ok: true, lastContactSeconds: 30 });
+    expect(report.checks.disk.ok).toBe(true);
+    expect(report.timestamp).toBe(NOW);
+  });
+
+  it('is unavailable, and only then, when the database cannot be reached', async () => {
+    const report = await createReadiness(
+      healthy({
+        db: {
+          execute: async () => {
+            throw new Error('connection refused');
+          },
+        },
+      }),
+    )();
+    expect(report.status).toBe('unavailable');
+    expect(report.checks.database.ok).toBe(false);
+  });
+
+  it('degrades on a commit that has waited longer than the threshold, and says how long', async () => {
+    const queuedAt = new Date(NOW - QUEUE_AGE_DEGRADED_MS - 1000);
+    const report = await createReadiness(healthy({ oldestQueuedAt: async () => queuedAt }))();
+    expect(report.status).toBe('degraded');
+    expect(report.checks.commitQueue.ok).toBe(false);
+    expect(report.checks.commitQueue.oldestPendingSeconds).toBe(QUEUE_AGE_DEGRADED_MS / 1000 + 1);
+  });
+
+  it('a recent backlog is not a degradation', async () => {
+    const report = await createReadiness(healthy({ oldestQueuedAt: async () => new Date(NOW - 5_000) }))();
+    expect(report.status).toBe('ok');
+    expect(report.checks.commitQueue.oldestPendingSeconds).toBe(5);
+  });
+
+  it('a standby that does not hold the lease is healthy, and says it is not draining', async () => {
+    // During a redeploy the replacement serves requests without the lease. That
+    // is the designed state, not a fault — a probe that failed it would have an
+    // orchestrator restart the healthy replacement.
+    const report = await createReadiness(healthy({ drains: () => false }))();
+    expect(report.status).toBe('ok');
+    expect(report.checks.commitQueue.draining).toBe(false);
+  });
+
+  it('degrades when the last attempt to reach the remote failed', async () => {
+    const report = await createReadiness(healthy({ lastRemoteContact: () => ({ at: NOW - 60_000, ok: false }) }))();
+    expect(report.status).toBe('degraded');
+    expect(report.checks.gitRemote).toEqual({ ok: false, lastContactSeconds: 60 });
+  });
+
+  it('a process that has not yet reached the remote is not degraded by that', async () => {
+    const report = await createReadiness(healthy({ lastRemoteContact: () => null }))();
+    expect(report.status).toBe('ok');
+    expect(report.checks.gitRemote).toEqual({ ok: true, lastContactSeconds: null });
+  });
+
+  it('degrades when the volume is nearly full, and stays ok when it cannot say', async () => {
+    const full = await createReadiness(healthy({ freeBytes: async () => DISK_FREE_DEGRADED_BYTES - 1 }))();
+    expect(full.status).toBe('degraded');
+    expect(full.checks.disk.ok).toBe(false);
+
+    const unknown = await createReadiness(healthy({ freeBytes: async () => null }))();
+    expect(unknown.status).toBe('ok');
+    expect(unknown.checks.disk).toEqual({ ok: true, freeBytes: null });
+  });
+
+  it('a fact that throws counts against itself alone', async () => {
+    const report = await createReadiness(
+      healthy({
+        oldestQueuedAt: async () => {
+          throw new Error('relation missing');
+        },
+        freeBytes: async () => {
+          throw new Error('statfs unsupported');
+        },
+      }),
+    )();
+    // Neither could answer; neither is known bad; the rest is untouched.
+    expect(report.status).toBe('ok');
+    expect(report.checks.commitQueue.oldestPendingSeconds).toBeNull();
+    expect(report.checks.disk.freeBytes).toBeNull();
+  });
+});