@celilo/cli 1.7.0 → 1.9.0

package/src/policy/dns-aspect-coverage.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The declared coverage and the aspect that does the covering must agree.
+ *
+ * `lxc-dns-at-birth` splits ownership: terraform owns birth DNS, the
+ * base-module aspect owns ongoing DNS. Terraform injects
+ * `lifecycle { ignore_changes = [nameserver] }`, so it can never correct the
+ * birth value — a zone the aspect does not cover has NO owner for ongoing DNS
+ * and its birth list is permanent. That is why the nameserver composition only
+ * strips the public resolvers for a zone the deployed provider's aspect covers
+ * (design D5d).
+ *
+ * Core reads that coverage from the provider's CAPABILITY DATA rather than
+ * looking up the provider's manifest, because core naming a capability to find
+ * its provider is what the module-business gate exists to stop. The cost of
+ * that choice is two lists in one manifest instead of one, and drift between
+ * them is not cosmetic: a zone listed as covered but absent from the aspect
+ * loses its public resolvers with nothing owning what replaces them.
+ *
+ * So this test is the thing that makes the choice safe. It is the reason the
+ * duplication is acceptable.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse } from 'yaml';
+
+function repoRoot(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'modules')) && existsSync(join(dir, 'apps'))) return dir;
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root');
+}
+
+interface ProviderManifest {
+  provides?: {
+    capabilities?: { name: string; data?: { aspect?: { covered_zones?: string[] } } }[];
+  };
+  base_module_aspect?: { applicable_zones?: string[] };
+}
+
+/** Every module declaring a `dns_internal` capability, with its manifest. */
+function dnsInternalProviders(): { id: string; manifest: ProviderManifest }[] {
+  const modulesDir = join(repoRoot(), 'modules');
+  const found: { id: string; manifest: ProviderManifest }[] = [];
+  for (const id of readdirSync(modulesDir)) {
+    const path = join(modulesDir, id, 'manifest.yml');
+    if (!existsSync(path)) continue;
+    let manifest: ProviderManifest;
+    try {
+      manifest = parse(readFileSync(path, 'utf-8')) as ProviderManifest;
+    } catch {
+      continue;
+    }
+    if (manifest.provides?.capabilities?.some((c) => c.name === 'dns_internal')) {
+      found.push({ id, manifest });
+    }
+  }
+  return found;
+}
+
+describe('dns_internal providers declare the coverage their aspect actually has', () => {
+  const providers = dnsInternalProviders();
+
+  test('the scan found the providers (sanity — it actually ran)', () => {
+    // knot-unbound-internal and technitium. A scan that silently found nothing
+    // would make every assertion below vacuously true.
+    expect(providers.map((p) => p.id).sort()).toEqual(['knot-unbound-internal', 'technitium']);
+  });
+
+  test.each(dnsInternalProviders().map((p) => [p.id, p] as const))(
+    '%s: declared covered_zones equals base_module_aspect.applicable_zones',
+    (_id, provider) => {
+      const capability = provider.manifest.provides?.capabilities?.find(
+        (c) => c.name === 'dns_internal',
+      );
+      const declared = capability?.data?.aspect?.covered_zones;
+      const applicable = provider.manifest.base_module_aspect?.applicable_zones;
+
+      expect(declared, 'dns_internal.data.aspect.covered_zones is missing').toBeDefined();
+      expect(applicable, 'base_module_aspect.applicable_zones is missing').toBeDefined();
+      expect([...(declared ?? [])].sort()).toEqual([...(applicable ?? [])].sort());
+    },
+  );
+
+  test('no provider claims to cover `external`', () => {
+    // An `external` system is a cloud VPS outside the perimeter with no route
+    // to a dmz-resident resolver. Its public resolvers are the only working
+    // configuration, not a fallback that might mask a split-horizon error, so
+    // claiming coverage there would strip the only addresses it can reach.
+    for (const provider of providers) {
+      const declared =
+        provider.manifest.provides?.capabilities?.find((c) => c.name === 'dns_internal')?.data
+          ?.aspect?.covered_zones ?? [];
+      expect(declared, `${provider.id} claims to cover external`).not.toContain('external');
+    }
+  });
+});

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

@@ -33,21 +33,28 @@
  *     never go away.
  */
 
+import { allDeclaredTables } from '@celilo/capabilities';
+
 /**
  * Tables tagged `@owner capability:*` in `db/schema.ts`, and the capability
  * each belongs to. Scan A asserts the tagged set EQUALS this map — not that it
- * is empty. These four exist today (audit T1, T2, T3, T6) and Phase 1 migrates
+ * is empty.
+ *
+ * DERIVED from the capability declarations, not hand-written
+ * (openspec/changes/capability-owned-tables task 2.7). It used to be a literal,
+ * which made `@owner capability:public_web` a comment checked against another
+ * comment. Now the tag is checked against the thing that actually governs the
+ * table, so a declared table that nobody tagged and a tagged table nobody
+ * declared BOTH fail, and the map cannot drift from the declarations because it
+ * no longer exists apart from them. These four exist today (audit T1, T2, T3, T6) and Phase 1 migrates
  * nothing; an assertion that core holds none would be red the day it landed.
  *
  * Tracked by #939. Migrating them keeps the ownership CLAIM in core — dropping
  * it is the mistake that made `dns_registration_consumers` necessary (#626).
  */
-export const CAPABILITY_OWNED_TABLES: Readonly<Record<string, string>> = {
-  web_routes: 'public_web',
-  port_forwards: 'firewall',
-  trusted_sources: 'firewall',
-  dns_internal_records: 'dns_internal',
-};
+export const CAPABILITY_OWNED_TABLES: Readonly<Record<string, string>> = Object.fromEntries(
+  allDeclaredTables().map(({ capability, declaration }) => [declaration.table, capability]),
+);
 
 /** One `{file, capability}` pair and how many times core names it. */
 export interface CapabilityNameRow {
@@ -80,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',
@@ -266,6 +309,24 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'X3 — reaches capabilitiesMap.dns_internal by name; should read a declared field (X4 is the model) (#945)',
   },
+  {
+    file: 'packages/capabilities/src/declared-tables.ts',
+    capability: 'dns_internal',
+    count: 1,
+    why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
+  },
+  {
+    file: 'packages/capabilities/src/declared-tables.ts',
+    capability: 'firewall',
+    count: 1,
+    why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
+  },
+  {
+    file: 'packages/capabilities/src/declared-tables.ts',
+    capability: 'public_web',
+    count: 1,
+    why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
+  },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
     capability: 'control_plane_vpn',

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;
+}