@celilo/cli 1.8.0 → 1.9.1

package/src/policy/capability-shape-baseline.ts

@@ -85,4 +85,12 @@ export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>
     version: '1.0.0',
     hash: 'e152f0738c88a7105b6057037f350ce0bbcbfc5c4ccbccc3af60f1cf3f1904af',
   },
+  web_routes: {
+    version: '1.0.0',
+    hash: 'bbf6435528a799e205270681e0ffc34f4007efbf04240138d4b69594a2515dbb',
+  },
+  firewall_registry: {
+    version: '2.0.0',
+    hash: 'db266155107b9eba88dbff576f979069e012e10a6dfb80de4544f809d1157bfb',
+  },
 };

package/src/policy/capability-shape.ts

@@ -65,7 +65,19 @@ export function capabilitySubjects(): Map<string, { typeName: string; file: stri
       const name = member.name.getText(source);
       const typeName = member.type.getText(source);
       const file = fileOfType.get(typeName);
-      if (file) subjects.set(name, { typeName, file });
+      if (!file) {
+        // LOUD, not skipped. A member whose type is not a bare imported
+        // identifier — an intersection, a generic, a locally-declared type —
+        // would otherwise drop out of coverage silently, and the gate would go
+        // green having checked one capability fewer. That is the same shape as
+        // the bugs this whole change kept finding: an absence that reads as a
+        // pass. If a registry member legitimately needs a composite type, teach
+        // this resolver about it rather than letting it vanish.
+        throw new Error(
+          `capability-shape: '${name}' has type '${typeName}', which is not a bare identifier imported into capability-registry.ts, so its shape cannot be hashed. Teach capabilitySubjects() how to resolve it.`,
+        );
+      }
+      subjects.set(name, { typeName, file });
     }
   }
   return subjects;

package/src/policy/module-business-baseline.ts

@@ -87,6 +87,42 @@ export interface ProviderLiteralRow {
 }
 
 export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'web_routes',
+    count: 2,
+    why: 'PERMANENT — a provider VIEW, not a module-provided capability. The name was registered so it stops being invisible to audits (celilo#1007); these references predate that and are framework plumbing, not core branching on a provider',
+  },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'firewall_registry',
+    count: 4,
+    why: 'PERMANENT — a provider VIEW, not a module-provided capability. The name was registered so it stops being invisible to audits (celilo#1007); these references predate that and are framework plumbing, not core branching on a provider',
+  },
+  {
+    file: 'apps/celilo/src/db/schema.ts',
+    capability: 'web_routes',
+    count: 1,
+    why: 'PERMANENT — the TABLE named web_routes, which predates the capability name entirely; the collision is nominal',
+  },
+  {
+    file: 'packages/capabilities/src/public-web.ts',
+    capability: 'web_routes',
+    count: 1,
+    why: 'PERMANENT — the public_web implementation naming its own table; the capability package doing its job',
+  },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'web_routes',
+    count: 1,
+    why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
+  },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'firewall_registry',
+    count: 1,
+    why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dhcp_server',

package/src/policy/module-dep-reachability.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Every module's bundled `@celilo/*` range must be able to resolve the version
+ * the workspace is about to publish.
+ *
+ * The failure this exists to catch has no symptom. A module bundles its own
+ * copy of `@celilo/capabilities` and runs THAT copy (celilo#173), so when the
+ * workspace publishes a new major, a module still pinned to the old caret
+ * range keeps installing the old copy. Everything typechecks. Every test
+ * passes. The new export is simply unreachable to every module in the fleet,
+ * and nothing anywhere says so.
+ *
+ * That is not hypothetical. `firewall_registry` was registered in
+ * `CapabilityRegistry` and npm's published `@celilo/capabilities@2.6.0`
+ * contains zero occurrences of it. Every module bundled `^2.6.0`, and a caret
+ * range never crosses a major, so the registration reached nothing. It was
+ * found by a person reading the diff (celilo#1089), not by a gate.
+ *
+ * `npm-consumer-smoke` cannot see it: it installs from locally-packed tarballs
+ * and never consults a registry, which is exactly why this class drifts unseen.
+ * `check:modules` cannot see it either — it installs each module's DECLARED
+ * range and typechecks, so a module that does not yet USE the new export is
+ * perfectly happy on the old copy. Both gates are green while the thing is
+ * broken.
+ *
+ * ## THIS GATE IS DELIBERATELY NARROW. READ THIS BEFORE TRUSTING IT.
+ *
+ * Its name invites a stronger reading than it earns. It compares the WORKSPACE
+ * version against each module's range. It does NOT consult a registry, so it
+ * cannot see a gap between what is PUBLISHED and what a module bundles.
+ *
+ * Measured, not assumed: run against `00c12ec2^1` — the commit immediately
+ * before the Version Packages PR that shipped capabilities 3.0.0 — this gate
+ * passes 3/0. At that commit the workspace was 2.6.0 and every module was
+ * `^2.6.0`, which satisfies, while npm's published 2.6.0 contained zero
+ * occurrences of `firewall_registry`. **So it would not have caught
+ * celilo#1089, the bug it was written for.** Nor `hello-trespass` sitting at
+ * `^2.3.0`, because `satisfies('2.6.0', '^2.3.0')` is true: a caret crosses
+ * minors freely and stops only at a major.
+ *
+ * If you are here because a published export turned out to be unreachable and
+ * you are wondering why this was green: it never looked. That check needs a
+ * registry query, which is network-bound and therefore does not belong beside
+ * hermetic checks in `ci/validate` — a flaky gate gets disabled. Its home is
+ * the release pipeline or a scheduled job.
+ *
+ * And one limitation no in-repo gate can ever close, however it is written:
+ * out-of-repo modules. `lunacycle` lives outside this checkout and no sweep
+ * here can see its pin at all (lunacycle#64).
+ *
+ * What this DOES catch is a module whose pin is out of lockstep with the
+ * workspace, which happens when a module is added or edited outside the
+ * release sweep's window: the Version Packages PR is open with everything at
+ * `^3.0.0`, a new module merges to main at `^2.6.0`, the version PR merges,
+ * and nothing re-runs the sweep until the next release.
+ *
+ * `scripts/sync-consumer-pins.ts` is what normally keeps these aligned, and it
+ * runs inside the version-PR phase of `release.yml`. This gate is the check
+ * that it RAN and covered everything — a module added between releases carries
+ * whatever range its author typed until the next release sweeps it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot } from './capability-shape';
+
+interface PackageJson {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+function readJson(path: string): PackageJson {
+  return JSON.parse(readFileSync(path, 'utf-8')) as PackageJson;
+}
+
+/** `@celilo/*` package name → the version this checkout would publish. */
+function workspaceVersions(root: string): Map<string, string> {
+  const versions = new Map<string, string>();
+  for (const dir of ['packages', 'apps']) {
+    const base = join(root, dir);
+    if (!existsSync(base)) continue;
+    for (const entry of readdirSync(base)) {
+      const manifest = join(base, entry, 'package.json');
+      if (!existsSync(manifest)) continue;
+      const pkg = readJson(manifest);
+      if (pkg.name?.startsWith('@celilo/') && pkg.version) versions.set(pkg.name, pkg.version);
+    }
+  }
+  return versions;
+}
+
+interface ModuleDep {
+  module: string;
+  dep: string;
+  range: string;
+}
+
+/** Every `@celilo/*` dependency declared by any module's `scripts/` package. */
+function moduleDeps(root: string): ModuleDep[] {
+  const out: ModuleDep[] = [];
+  const modulesDir = join(root, 'modules');
+  for (const module of readdirSync(modulesDir)) {
+    const manifest = join(modulesDir, module, 'scripts', 'package.json');
+    if (!existsSync(manifest)) continue;
+    const pkg = readJson(manifest);
+    for (const [dep, range] of Object.entries({
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.devDependencies ?? {}),
+    })) {
+      if (dep.startsWith('@celilo/')) out.push({ module, dep, range });
+    }
+  }
+  return out;
+}
+
+describe('a module can reach what the workspace publishes', () => {
+  const root = repoRoot();
+  const versions = workspaceVersions(root);
+  const deps = moduleDeps(root);
+
+  test('the scan found the workspace packages and the module deps', () => {
+    // An empty scan passes every assertion below while checking nothing, which
+    // is the failure mode that makes a green gate worse than no gate.
+    expect(versions.size).toBeGreaterThan(0);
+    expect(deps.length).toBeGreaterThan(0);
+    expect(versions.has('@celilo/capabilities')).toBe(true);
+  });
+
+  test('every module range resolves the version this checkout would publish', () => {
+    const unreachable = deps
+      .filter(({ dep, range }) => {
+        const version = versions.get(dep);
+        // A dep on a package this checkout does not build is out of scope: it
+        // resolves from the registry like any third-party dependency.
+        if (!version) return false;
+        return !Bun.semver.satisfies(version, range);
+      })
+      .map(
+        ({ module, dep, range }) =>
+          `${module} pins ${dep}@${range}, which cannot resolve the workspace's ${versions.get(dep)}`,
+      )
+      .sort();
+
+    const guidance = [
+      'A module bundles its own copy and runs THAT copy (celilo#173). A range that',
+      'cannot reach the version about to be published means every export added',
+      'since is unreachable to that module, silently.',
+      '',
+      'Fix: bun scripts/sync-consumer-pins.ts   (then commit the rewritten pins)',
+      '',
+      ...unreachable,
+    ].join('\n');
+
+    expect(unreachable, guidance).toEqual([]);
+  });
+
+  test('PROVE IT FAILS: a caret range does not cross a major', () => {
+    // The exact shape of celilo#1089: modules on ^2.6.0, workspace at 3.0.0.
+    expect(Bun.semver.satisfies('3.0.0', '^2.6.0')).toBe(false);
+    // And the near-miss that makes it easy to believe you are covered: a caret
+    // DOES cross a minor, so a lagging pin looks harmless right up until the
+    // major.
+    expect(Bun.semver.satisfies('2.6.0', '^2.3.0')).toBe(true);
+  });
+});

package/src/services/alerting/ack.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { type Route, alerts, modules, monitors } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import { acknowledgeAlert, findLiveAlertByKey, resolveAlertManually, silenceAlert } from './ack';
 import { moduleCheckAlertKey } from './keys';
 import { createPerson, createRoute } from './people';
@@ -26,7 +26,7 @@ describe('ack / silence / resolve', () => {
     dir = mkdtempSync(join(tmpdir(), 'ack-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
 
     db.insert(modules)
       .values({

package/src/services/alerting/deferral.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Alert, type Route, alerts, modules, monitors } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import { moduleCheckAlertKey } from './keys';
 import { deliverDeferred } from './notifier';
 import { createPerson, createRoute } from './people';
@@ -35,7 +35,7 @@ describe('quiet-hours deferral', () => {
     dir = mkdtempSync(join(tmpdir(), 'deferral-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     sent.length = 0;
 
     db.insert(modules)

package/src/services/alerting/delivery-loop.test.ts

@@ -20,7 +20,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { type Alert, type Route, modules } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import type { EscalationStep, RouteForEscalation } from './escalation';
 import { interpretInbound } from './inbound';
 import {
@@ -217,7 +217,7 @@ describe('delivery loop against the signal-cli simulator', () => {
     dir = mkdtempSync(join(tmpdir(), 'delivery-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     await control('reset');
 
     db.insert(modules)

package/src/services/alerting/deploy-hooks.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { modules, monitors } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import {
   closeDeployWindows,
   ensureMonitorOnDeploy,
@@ -29,7 +29,7 @@ describe('deploy hooks', () => {
     dir = mkdtempSync(join(tmpdir(), 'deploy-hooks-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
   });
 
   afterEach(() => {

package/src/services/alerting/inbound-poller.test.ts

@@ -6,7 +6,7 @@ import type { InboundMessage } from '@celilo/capabilities';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Route, alerts, modules, monitors, notificationDeliveries } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import {
   type InboundPollDeps,
   type TransportReadRecord,
@@ -53,7 +53,7 @@ describe('pollInbound', () => {
     dir = mkdtempSync(join(tmpdir(), 'inbound-poll-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     cursors.clear();
 
     db.insert(modules)

package/src/services/alerting/inbound.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { type NotificationDelivery, modules, people, routes } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import { interpretInbound, parseInbound } from './inbound';
 import { mintDelivery } from './tokens';
 
@@ -83,7 +83,7 @@ describe('interpretInbound', () => {
     dir = mkdtempSync(join(tmpdir(), 'inbound-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     outstanding.length = 0;
 
     db.insert(modules)

package/src/services/alerting/notification-responder.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import type { DbClient } from '../../db/client';
 import { type Route, modules } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import {
   type NotificationResponderHandle,
   startNotificationResponder,
@@ -60,7 +60,7 @@ describe('notification responder', () => {
     const dbPath = join(dir, 'celilo.db');
     busPath = join(dir, 'events.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     sent = [];
     declined = [];
     sendFailures = [];

package/src/services/alerting/run-monitor.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Monitor, alerts, monitorRuns, monitors } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import type { HealthCheckResult } from '../health-runner';
 import { moduleAlertKey, moduleCheckAlertKey } from './keys';
 import { type MonitorRunDeps, runOneMonitor } from './run-monitor';
@@ -54,7 +54,7 @@ describe('runOneMonitor', () => {
     dir = mkdtempSync(join(tmpdir(), 'run-monitor-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     db.insert(monitors)
       .values({
         id: 'mon-1',

package/src/services/alerting/store.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { alerts, monitors } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import { moduleAlertKey, moduleCheckAlertKey } from './keys';
 import type { ReconcileAction } from './reconcile';
 import {
@@ -41,7 +41,7 @@ describe('alert store', () => {
     dir = mkdtempSync(join(tmpdir(), 'alert-store-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     db.insert(monitors)
       .values({
         id: MONITOR,

package/src/services/alerting/sweep-runner.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Alert, type Monitor, alerts, modules, monitors } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import type { HealthCheckResult } from '../health-runner';
 import { deleteModuleConfig, upsertModuleConfig } from '../module-config';
 import { HEALTH_CHECK_INTERVAL_CONFIG_KEY, reconcileModuleWatchState } from './health-cadence';
@@ -68,7 +68,7 @@ describe('runSweep', () => {
     dir = mkdtempSync(join(tmpdir(), 'sweep-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
     // The module row is load-bearing now: a `module_hook` monitor's cadence
     // resolves from the module's manifest and config, not from its own row.
     db.insert(modules)

package/src/services/alerting/tokens.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { modules, people, routes } from '../../db/schema';
-import { setupTestDatabase } from '../../test-utils/setup-test-db';
+import { setupTestDatabaseAt } from '../../test-utils/database';
 import {
   consumeDelivery,
   deliveriesForAlert,
@@ -56,7 +56,7 @@ describe('delivery records', () => {
     dir = mkdtempSync(join(tmpdir(), 'tokens-'));
     const dbPath = join(dir, 'celilo.db');
     process.env.CELILO_DB_PATH = dbPath;
-    db = await setupTestDatabase(dbPath);
+    db = await setupTestDatabaseAt(dbPath);
 
     db.insert(modules)
       .values({

package/src/services/capability-bindings.test.ts

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import type { DbClient } from '../db/client';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import {
+  listCapabilityBindings,
+  recordCapabilityBinding,
+  withBindingRecord,
+} from './capability-bindings';
+
+describe('withBindingRecord', () => {
+  test('reports once however many times the consumer calls', () => {
+    let calls = 0;
+    const iface = withBindingRecord({ a: () => 1, b: () => 2 }, () => {
+      calls++;
+    });
+
+    iface.a();
+    iface.a();
+    iface.b();
+
+    expect(calls).toBe(1);
+  });
+
+  test('reports nothing when no method is called', () => {
+    let calls = 0;
+    withBindingRecord({ publishStaticSite: () => 1 }, () => {
+      calls++;
+    });
+
+    expect(calls).toBe(0);
+  });
+
+  test('passes arguments and the return value through untouched', () => {
+    const iface = withBindingRecord({ add: (a: number, b: number) => a + b }, () => {});
+    expect(iface.add(2, 3)).toBe(5);
+  });
+
+  test('leaves a synchronous method synchronous', () => {
+    // Unlike `wrapWithLogging`, which awaits and therefore makes every method
+    // async. A capability's calling convention must not change because celilo
+    // decided to watch it.
+    const iface = withBindingRecord({ now: () => 'value' }, () => {});
+    expect(iface.now()).toBe('value');
+  });
+
+  test('passes non-function properties through, including the provider stamp', () => {
+    const iface = withBindingRecord({ providerModuleId: 'caddy', go: () => 1 }, () => {});
+    expect(iface.providerModuleId).toBe('caddy');
+  });
+});
+
+describe('recordCapabilityBinding', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    if (db) await cleanupTestDatabase(db);
+    db = await setupTestDatabase();
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('consumer', 'consumer', '1.0.0', '/tmp/consumer', '{}')`,
+    );
+  });
+
+  test('re-asserting the same binding keeps one row', () => {
+    recordCapabilityBinding(db, 'consumer', 'external_web', 'cpanel-host');
+    recordCapabilityBinding(db, 'consumer', 'external_web', 'cpanel-host');
+
+    expect(listCapabilityBindings(db, 'consumer')).toHaveLength(1);
+  });
+
+  test('a provider swap rewrites the row in place', () => {
+    recordCapabilityBinding(db, 'consumer', 'public_web', 'caddy');
+    recordCapabilityBinding(db, 'consumer', 'public_web', 'caddy-internal');
+
+    const bindings = listCapabilityBindings(db, 'consumer');
+    expect(bindings).toHaveLength(1);
+    expect(bindings[0].providerModuleId).toBe('caddy-internal');
+  });
+
+  test('boundAt is last-seen, not first-seen', () => {
+    // A binding last exercised forty deploys ago has to be a queryable fact
+    // rather than a silent lie, so the timestamp moves on every invocation.
+    recordCapabilityBinding(db, 'consumer', 'idp', 'authentik');
+    db.$client.run(
+      `UPDATE capability_bindings SET bound_at = 1000 WHERE consumer_module_id = 'consumer'`,
+    );
+
+    recordCapabilityBinding(db, 'consumer', 'idp', 'authentik');
+
+    expect(listCapabilityBindings(db, 'consumer')[0].boundAt.getTime()).toBeGreaterThan(
+      1000 * 1000,
+    );
+  });
+
+  test('bindings are scoped to the consumer that made them', () => {
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('other', 'other', '1.0.0', '/tmp/other', '{}')`,
+    );
+    recordCapabilityBinding(db, 'consumer', 'source_forge', 'forgejo');
+    recordCapabilityBinding(db, 'other', 'source_forge', 'forgejo');
+
+    expect(listCapabilityBindings(db, 'consumer')).toHaveLength(1);
+    expect(listCapabilityBindings(db, 'other')).toHaveLength(1);
+  });
+});

package/src/services/capability-bindings.ts

@@ -0,0 +1,107 @@
+/**
+ * Which provider a consumer actually resolved to (celilo#1072).
+ *
+ * `capabilities` is provider-side only, so celilo could answer "who could
+ * provide this" and never "who does this module actually use". Callers that
+ * needed the second question rebuilt the same approximation — the consumer's
+ * `requires` + `optional` crossed with `capabilities` — which names every
+ * provider a module MIGHT have bound to. `tango-nexus` declares four optional
+ * capabilities and is deployed against one host, so that approximation carries
+ * three edges that do not exist and nothing distinguishes them.
+ *
+ * The binding is the CALL, not the resolution. `loadCapabilityFunctions`
+ * injects every capability that has a registered provider, deliberately, and
+ * never reads the consumer's manifest — so what it resolves is a superset of
+ * even the permissive set. A consumer's hook invoking a method is the one event
+ * that separates the optional it uses from the three it does not.
+ *
+ * This runs BESIDE the permissive set, it does not replace it.
+ * `planConsumerCleanup` must still notify every provider that might hold minted
+ * state, including providers this table has no row for.
+ */
+
+import { desc, eq, sql } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilityBindings } from '../db/schema';
+
+export interface CapabilityBinding {
+  capabilityName: string;
+  providerModuleId: string;
+  /** Last time the consumer called into this provider. */
+  boundAt: Date;
+}
+
+/**
+ * Record that `consumer` called into `provider` for `capability`.
+ *
+ * Upsert on (consumer, capability): a redeploy re-asserts the row rather than
+ * duplicating it, and a provider swap rewrites the provider in place. `boundAt`
+ * carries last-seen semantics — it moves on every invocation, so a binding last
+ * exercised forty deploys ago is a queryable fact rather than a silent lie.
+ */
+export function recordCapabilityBinding(
+  db: DbClient,
+  consumerModuleId: string,
+  capabilityName: string,
+  providerModuleId: string,
+): void {
+  db.insert(capabilityBindings)
+    .values({ consumerModuleId, capabilityName, providerModuleId })
+    .onConflictDoUpdate({
+      target: [capabilityBindings.consumerModuleId, capabilityBindings.capabilityName],
+      set: { providerModuleId, boundAt: sql`(unixepoch())` },
+    })
+    .run();
+}
+
+/** Every provider this consumer has actually called into, most recent first. */
+export function listCapabilityBindings(
+  db: DbClient,
+  consumerModuleId: string,
+): CapabilityBinding[] {
+  return db
+    .select()
+    .from(capabilityBindings)
+    .where(eq(capabilityBindings.consumerModuleId, consumerModuleId))
+    .orderBy(desc(capabilityBindings.boundAt))
+    .all()
+    .map((row) => ({
+      capabilityName: row.capabilityName,
+      providerModuleId: row.providerModuleId,
+      boundAt: row.boundAt,
+    }));
+}
+
+/**
+ * Wrap a capability interface so the first method call reports the binding.
+ *
+ * Modelled on `wrapWithLogging`: a new object over the same prototype, every
+ * function replaced, everything else passed through. Unlike that wrapper this
+ * one does NOT make the method async — it records and then returns the original
+ * call untouched, so a synchronous capability method stays synchronous.
+ *
+ * `onUse` fires once per wrapped interface. A hook that calls a capability
+ * twenty times writes one row.
+ */
+export function withBindingRecord<T extends object>(iface: T, onUse: () => void): T {
+  let reported = false;
+  const wrapped = Object.create(Object.getPrototypeOf(iface));
+
+  for (const key of Reflect.ownKeys(iface)) {
+    const value = (iface as Record<string | symbol, unknown>)[key];
+    if (typeof value !== 'function') {
+      wrapped[key] = value;
+      continue;
+    }
+    const original = value as (...args: unknown[]) => unknown;
+    wrapped[key] = function (this: unknown, ...args: unknown[]): unknown {
+      if (!reported) {
+        reported = true;
+        onUse();
+      }
+      return original.apply(this, args);
+    };
+  }
+
+  return wrapped as T;
+}