@celilo/cli 1.7.0 → 1.9.0

package/src/manifest/validate.ts

@@ -1,4 +1,4 @@
-import { KNOWN_CAPABILITY_NAMES } from '@celilo/capabilities';
+import { KNOWN_CAPABILITY_NAMES, isProviderView } from '@celilo/capabilities';
 import { parse as parseYaml } from 'yaml';
 import type { ZodError } from 'zod';
 import { validateModuleZoneRequirements } from '../services/zone-policy';
@@ -146,24 +146,31 @@ export function validateCapabilityRequirements(
  */
 export function validateCapabilityNames(manifest: ModuleManifest): ValidationError | null {
   const errors: Array<{ path: string; message: string }> = [];
-  const knownNames: readonly string[] = KNOWN_CAPABILITY_NAMES;
+  // Provider views are registry entries, so a bare membership test would accept
+  // them. They are framework-injected into the PROVIDER's own hooks and no
+  // module can ask for one, so requiring one is always a mistake, and a silent
+  // one: the manifest would validate and the capability would simply never
+  // arrive. Excluded from the suggestion list too, for the same reason.
+  const requirableNames: readonly string[] = KNOWN_CAPABILITY_NAMES.filter(
+    (name) => !isProviderView(name),
+  );
+
+  const checkName = (name: string, path: string): void => {
+    if (requirableNames.includes(name)) return;
+    errors.push({
+      path,
+      message: isProviderView(name)
+        ? `'${name}' is a provider view, not a capability a module can declare. celilo injects it into the hooks of the module that PROVIDES the paired capability. Remove this declaration.`
+        : `Unknown capability '${name}'. Known capabilities: ${requirableNames.join(', ')}.`,
+    });
+  };
 
   for (const required of manifest.requires.capabilities) {
-    if (!knownNames.includes(required.name)) {
-      errors.push({
-        path: `requires.capabilities.${required.name}`,
-        message: `Unknown capability '${required.name}'. Known capabilities: ${knownNames.join(', ')}.`,
-      });
-    }
+    checkName(required.name, `requires.capabilities.${required.name}`);
   }
 
   for (const opt of manifest.optional?.capabilities ?? []) {
-    if (!knownNames.includes(opt.name)) {
-      errors.push({
-        path: `optional.capabilities.${opt.name}`,
-        message: `Unknown capability '${opt.name}'. Known capabilities: ${knownNames.join(', ')}.`,
-      });
-    }
+    checkName(opt.name, `optional.capabilities.${opt.name}`);
   }
 
   if (errors.length > 0) {

package/src/module/import.ts

@@ -607,7 +607,25 @@ export async function importModule(options: ModuleImportOptions): Promise<Module
     // Execution: Validate capability access if module requires capabilities
     if (manifest.requires?.capabilities && manifest.requires.capabilities.length > 0) {
       const { validateCapabilityAccess } = await import('../capabilities/validation');
-      const accessResult = await validateCapabilityAccess(manifest, db.$client);
+      // Templates are where CLAUDE.md's Definition of Done tells module authors
+      // to put `$capability:` references, so the import-time gate has to see
+      // them (celilo#854, celilo#1027).
+      //
+      // This adds no parser. `validateModuleTemplates` above already reads and
+      // parses every `.tpl` on every import, roughly 25 lines before the gate
+      // runs — it was discarding the references it saw. So there is no new file
+      // walk, no new failure mode and no new ordering question: the data is
+      // already in scope and the gate simply was not looking at it.
+      //
+      // Fail-closed by that same ordering. An unreadable template makes
+      // `validateModuleTemplates` return success:false with no references, and
+      // the early return above fires BEFORE this check, so an empty reference
+      // set can never reach the gate as a silent pass.
+      const accessResult = await validateCapabilityAccess(
+        manifest,
+        db.$client,
+        templateValidation.capabilityReferences,
+      );
 
       if (!accessResult.success) {
         if (tempDir) await cleanupTempDir(tempDir);

package/src/module/packaging/module-state-directory.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { moduleIntegrity, modules } from '../../db/schema';
+import { cleanupTestDatabase, setupTestDatabase } from '../../test-utils/database';
+import { auditModule } from './audit';
+import { classifyModulePath } from './package-rules';
+
+/**
+ * The recurrence gate for celilo#1000: a hook has a sanctioned place to write,
+ * and what it writes there never becomes a `module audit` finding.
+ *
+ * **The names below are generated, deliberately.** The failure this gate exists
+ * for is not "we forgot to allow `state/cursor.json`". It is that the allow-list
+ * was a list of literals (`screenshots/`, `cookies.json`) patched in one at a
+ * time after each one bit someone, so it could only ever cover filenames
+ * somebody had already been surprised by. A test asserting a literal filename
+ * reproduces exactly that weakness. A hook writes what it needs to write, and
+ * the framework does not get to know the name in advance.
+ */
+
+/** A name nothing in the codebase anticipates, and that no allow-list can hold. */
+function unanticipatedName(seed: number): string {
+  return `${seed.toString(36)}-${(seed * 7919).toString(36)}.dat`;
+}
+
+describe('celilo#1000: state/ is the hook-writable directory', () => {
+  test('any name a hook invents under state/ is derived, at any depth', () => {
+    for (let seed = 1; seed <= 25; seed++) {
+      const name = unanticipatedName(seed);
+      for (const path of [`state/${name}`, `state/nested/${name}`, `state/a/b/c/${name}`]) {
+        expect(`${path} => ${classifyModulePath(path)}`).toBe(`${path} => derived`);
+      }
+    }
+  });
+
+  /**
+   * The contrast is the point, and `package` rather than `unknown` is what the
+   * contrast actually is. `classifyModulePath` defaults to `package`, meaning
+   * "this belongs to the module and must match `checksums.json`", so the same
+   * name one directory up is scanned, found absent from the checksums, and
+   * reported. That is the reporting this change exempts `state/` from, and
+   * exempts nothing else from. If this half ever goes green alongside the half
+   * above, the fix widened rather than named.
+   */
+  test('the same names outside state/ are still checksum-bearing', () => {
+    for (let seed = 1; seed <= 25; seed++) {
+      const name = unanticipatedName(seed);
+      expect(`${name} => ${classifyModulePath(name)}`).toBe(`${name} => package`);
+      expect(`lib/${name} => ${classifyModulePath(`lib/${name}`)}`).toBe(`lib/${name} => package`);
+    }
+  });
+
+  test('a hook writing into state/ leaves module audit clean', async () => {
+    const db = await setupTestDatabase();
+    const root = mkdtempSync(join(tmpdir(), 'celilo-state-gate-'));
+    try {
+      // A minimal installed tree: one packaged file, recorded in checksums.
+      writeFileSync(join(root, 'manifest.yml'), 'id: state-gate\nversion: 1.0.0\n');
+      db.insert(modules)
+        .values({
+          id: 'state-gate',
+          name: 'state-gate',
+          version: '1.0.0',
+          sourcePath: root,
+          manifestData: { id: 'state-gate', version: '1.0.0' },
+        })
+        .run();
+      db.insert(moduleIntegrity)
+        .values({
+          moduleId: 'state-gate',
+          checksums: { 'manifest.yml': await xxhashOf(join(root, 'manifest.yml')) },
+          version: '1.0.0',
+        })
+        .run();
+
+      const before = await auditModule('state-gate', db);
+      expect(before.violations).toEqual([]);
+
+      // Now a hook runs and writes something nobody declared.
+      mkdirSync(join(root, 'state'), { recursive: true });
+      writeFileSync(join(root, 'state', unanticipatedName(42)), 'whatever the hook needed');
+
+      const after = await auditModule('state-gate', db);
+      expect(after.violations).toEqual([]);
+      expect(after.success).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+      await cleanupTestDatabase(db);
+    }
+  });
+});
+
+/** The audit's own hash, so the fixture's checksum is right by construction. */
+async function xxhashOf(path: string): Promise<string> {
+  const { readFileSync } = await import('node:fs');
+  return Bun.hash.xxHash64(readFileSync(path)).toString(16);
+}

package/src/module/packaging/package-rules.ts

@@ -94,8 +94,16 @@ export function classifyModulePath(relPath: string): ModulePathClass {
   if (name === 'tsconfig.json') return 'unknown';
   if (name.endsWith('.netapp') || name.endsWith('.test.ts')) return 'unknown';
 
-  // Celilo's own output under the module's install root.
-  if (segments[0] === 'generated' || segments[0] === 'screenshots') return 'derived';
+  // Celilo's own output under the module's install root, plus the one directory
+  // a MODULE may write to. `state/` is celilo#1000: hooks had nowhere sanctioned
+  // to put anything, so whatever they wrote surfaced as an `extra` finding, and
+  // the two entries beside it here (`screenshots/`, `cookies.json`) are what
+  // that looked like being solved one filename at a time. `derived` already
+  // means exactly what a scratch location needs (writable, survives `module
+  // update`, not audited, not pruned), so this names a directory rather than
+  // adding machinery.
+  if (segments[0] === 'generated' || segments[0] === 'screenshots' || segments[0] === 'state')
+    return 'derived';
   // A checksum manifest cannot list itself, nor the signature over it.
   if (relPath === 'checksums.json' || relPath === 'signature.sig') return 'derived';
   // Regenerated by `module import` from the manifest (HOOK_API_V2 Phase 2).

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

@@ -0,0 +1,96 @@
+/**
+ * Expected shape hashes per capability — the fixture behind
+ * `capability-shape-drift.test.ts`.
+ *
+ * `CAPABILITY_CONTRACT_VERSIONS` is bumped BY HAND, so the whole scheme rests on
+ * a human remembering. `capability-contract.ts` used to claim that risk was
+ * "mitigated by a CI check that compares interface AST hashes against an
+ * expected fixture". No such check existed. It was designed in the retired
+ * `apps/celilo/designs/CELILO_UPDATE.md` and never built, and three design
+ * documents reasoned from it anyway (celilo#1042). This is that check.
+ *
+ * Changing a capability's interface OR its table declaration changes its hash.
+ * The test then fails until BOTH the contract version and the entry below move,
+ * in the same commit — which is the whole point, because the version is what
+ * `compareProviderToRuntime` and `celilo system audit` compare against.
+ *
+ * Comments and formatting do NOT change a hash. The interface is re-printed from
+ * its AST with comments removed before hashing, so a doc-only edit stays a patch
+ * (the bump rule `capability-contract.ts` already states).
+ *
+ * WHY THIS LIVES IN apps/celilo AND NOT NEXT TO THE CONTRACT. It needs the
+ * TypeScript compiler API to parse, and `db/schema.ts` to check a declaration
+ * against the real table. `@celilo/capabilities` is bundled into every module
+ * (celilo#173), so adding a `typescript` dependency there to serve a test would
+ * be paid for by every module on the fleet. apps/celilo already depends on both.
+ */
+
+export interface CapabilityShape {
+  /** The contract version this hash was recorded at. */
+  readonly version: string;
+  /** sha256 of the printed interface plus the capability's table declaration. */
+  readonly hash: string;
+}
+
+export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>> = {
+  public_web: {
+    version: '3.2.0',
+    hash: 'a353bf184552f1ed82e5d97c9b4609dc243718c20051a9446d8dc7174561db50',
+  },
+  idp: {
+    version: '1.2.0',
+    hash: '99eee190ed670f53595554335f23e1745b872e3226dc9ffdb1d0bf6397d6013a',
+  },
+  dns_registrar: {
+    version: '4.0.0',
+    hash: 'f5d02196a3394ec71d865beb45825160103800baf632293a769a6e72dc76236a',
+  },
+  firewall: {
+    version: '1.1.0',
+    hash: '564a83ebf8ca937faf955afc4f7bf4278fe9ed01694f0237bfbc38e2eff38408',
+  },
+  source_forge: {
+    version: '1.0.0',
+    hash: '3bc797cf8c2990c61723fb680299f6a1d4b99ac42fd0371dd9dc64d05c588991',
+  },
+  registry_publish: {
+    version: '1.0.0',
+    hash: '693e7d08e9f105acd90dd00f8f9282ab3508def16e48237b47bc0ccba7885679',
+  },
+  dhcp_server: {
+    version: '1.0.0',
+    hash: '291a247d98bc11b18ab34d40b520bec679b95a031cbd674d513b313559fa3288',
+  },
+  dns_internal: {
+    version: '1.1.0',
+    hash: 'af72e861a23f6c81fe9a1a679121b7d3ea87ac5e8167efa20d5d6323010e5fef',
+  },
+  external_web: {
+    version: '1.0.0',
+    hash: '7396028ace76938f4e892e6ef8a53450183cdbcf8dff3ce767724bd9b2276dae',
+  },
+  notification: {
+    version: '1.0.0',
+    hash: '40629722b397a314d65a448a618d600fc8560c4aae0767dd7324d497d4cc9d41',
+  },
+  control_plane_vpn: {
+    version: '1.0.0',
+    hash: '2f7f81d0b3ecb2ab6822dbc9bf837a933b25e0e157eb94d0b9b8e801417f8f14',
+  },
+  private_web: {
+    version: '1.0.0',
+    hash: '0eddb82f821fe3c7fbd503d55a24c3d5a22369af8b22de06570a371d5f485c03',
+  },
+  cross_module_read: {
+    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-drift.test.ts

@@ -0,0 +1,162 @@
+/**
+ * The gate `capability-contract.ts` claimed for months and did not have.
+ *
+ * Two independent failures are caught here, and they are different enough to be
+ * worth naming separately.
+ *
+ * SCAN A — a declaration that disagrees with the real table. This is the failure
+ * mode `openspec/changes/capability-owned-tables` design D4 warns is *worse than
+ * today's*: a capability whose declared shape does not match the database, where
+ * the version check still passes, "because versions live in files and the table
+ * lives in the database". A missing migration at least says `no such table`.
+ * Nothing else in the tree compares the two.
+ *
+ * SCAN B — an interface or declaration that changed with no version bump.
+ * `CAPABILITY_CONTRACT_VERSIONS` is hand-maintained, and `compareProviderToRuntime`
+ * plus `celilo system audit` both trust it. A silently-changed shape makes both
+ * of them confidently wrong. Comments and formatting are excluded, so a doc-only
+ * edit stays a patch.
+ *
+ * The subject list is DERIVED from `CapabilityRegistry` rather than written out,
+ * so a new capability is covered the day it is added rather than the day someone
+ * remembers to add it here.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { CAPABILITY_CONTRACT_VERSIONS } from '@celilo/capabilities';
+import { is } from 'drizzle-orm';
+import { SQLiteTable, getTableConfig } from 'drizzle-orm/sqlite-core';
+import * as dbSchema from '../db/schema';
+import { capabilitySubjects, shapeHash, tablesOf } from './capability-shape';
+import { CAPABILITY_SHAPE_BASELINE } from './capability-shape-baseline';
+
+/** Physical table name → the drizzle table the running code declares. */
+function drizzleTables(): Map<string, ReturnType<typeof getTableConfig>> {
+  const out = new Map<string, ReturnType<typeof getTableConfig>>();
+  for (const value of Object.values(dbSchema)) {
+    if (!is(value, SQLiteTable)) continue;
+    const config = getTableConfig(value);
+    out.set(config.name, config);
+  }
+  return out;
+}
+
+const DRIZZLE_TYPE_TO_DECLARED: Record<string, string> = {
+  SQLiteText: 'text',
+  SQLiteInteger: 'integer',
+  SQLiteBoolean: 'boolean',
+  SQLiteTimestamp: 'timestamp',
+};
+
+describe('Scan A — a declared table matches the real one', () => {
+  test('every declared table exists in db/schema.ts', async () => {
+    const tables = drizzleTables();
+    const missing: string[] = [];
+    for (const [capability, subject] of capabilitySubjects()) {
+      for (const [key, decl] of Object.entries(await tablesOf(subject.file))) {
+        if (!tables.has(decl.table)) missing.push(`${capability}.${key} → ${decl.table}`);
+      }
+    }
+    expect(missing).toEqual([]);
+  });
+
+  test('every declared column exists on the real table, claim included', async () => {
+    const tables = drizzleTables();
+    const missing: string[] = [];
+    for (const [capability, subject] of capabilitySubjects()) {
+      for (const [key, decl] of Object.entries(await tablesOf(subject.file))) {
+        const config = tables.get(decl.table);
+        if (!config) continue;
+        const present = new Set(config.columns.map((c) => c.name));
+        for (const column of [decl.claim.column, ...Object.keys(decl.columns)]) {
+          if (!present.has(column)) missing.push(`${capability}.${key}: ${decl.table}.${column}`);
+        }
+      }
+    }
+    expect(missing).toEqual([]);
+  });
+
+  /**
+   * The half that catches a rename or a retype rather than an absence. A column
+   * declared `text` that is really an integer reads as present to the check
+   * above, and every consumer of the declaration would then be typed wrong.
+   */
+  test('every declared column has the declared type and nullability', async () => {
+    const tables = drizzleTables();
+    const wrong: string[] = [];
+    for (const [capability, subject] of capabilitySubjects()) {
+      for (const [key, decl] of Object.entries(await tablesOf(subject.file))) {
+        const config = tables.get(decl.table);
+        if (!config) continue;
+        for (const [column, declared] of Object.entries(decl.columns)) {
+          const actual = config.columns.find((c) => c.name === column);
+          if (!actual) continue;
+          const base = DRIZZLE_TYPE_TO_DECLARED[actual.columnType] ?? actual.columnType;
+          const expected = declared.endsWith('?') ? declared.slice(0, -1) : declared;
+          const nullableDeclared = declared.endsWith('?');
+          if (base !== expected) {
+            wrong.push(
+              `${capability}.${key}: ${decl.table}.${column} is ${base}, declared ${expected}`,
+            );
+          }
+          if (nullableDeclared === actual.notNull) {
+            wrong.push(
+              `${capability}.${key}: ${decl.table}.${column} nullability disagrees (declared ${declared}, notNull=${actual.notNull})`,
+            );
+          }
+        }
+      }
+    }
+    expect(wrong).toEqual([]);
+  });
+});
+
+describe('Scan B — a shape change carries a version bump', () => {
+  test('every capability in the registry has a baseline entry', async () => {
+    const missing = [...capabilitySubjects().keys()].filter(
+      (name) => !(name in CAPABILITY_SHAPE_BASELINE),
+    );
+    expect(missing).toEqual([]);
+  });
+
+  /**
+   * The fixture records the version its hash was taken at. If the contract has
+   * moved since, the baseline describes a shape nobody re-measured — which is
+   * how a bump lands without the regenerate that is supposed to accompany it.
+   *
+   * This does NOT catch the reverse (regenerating without bumping), and cannot:
+   * telling a deliberate shape change from an accidental one needs history the
+   * gate does not have. That case shows in review as a hash moving while a
+   * version stands still, which is why the generator reads versions from the
+   * contract rather than inventing them.
+   */
+  test('every baseline entry was taken at the CURRENT contract version', () => {
+    const versions = CAPABILITY_CONTRACT_VERSIONS as Record<string, string>;
+    const stale: string[] = [];
+    for (const capability of capabilitySubjects().keys()) {
+      const recorded = CAPABILITY_SHAPE_BASELINE[capability];
+      if (!recorded) continue;
+      if (recorded.version !== versions[capability]) {
+        stale.push(
+          `${capability}: baseline recorded at ${recorded.version}, contract is now ${versions[capability]}. Re-run bun run apps/celilo/scripts/regenerate-capability-shape-baseline.ts`,
+        );
+      }
+    }
+    expect(stale).toEqual([]);
+  });
+
+  test('no capability changed shape without moving its baseline', async () => {
+    const drifted: string[] = [];
+    for (const capability of capabilitySubjects().keys()) {
+      const recorded = CAPABILITY_SHAPE_BASELINE[capability];
+      if (!recorded) continue;
+      const actual = await shapeHash(capability);
+      if (actual !== recorded.hash) {
+        drifted.push(
+          `${capability}: shape changed. Bump CAPABILITY_CONTRACT_VERSIONS.${capability} (currently recorded at ${recorded.version}) and set its baseline hash to ${actual}.`,
+        );
+      }
+    }
+    expect(drifted).toEqual([]);
+  });
+});

package/src/policy/capability-shape.ts

@@ -0,0 +1,129 @@
+/**
+ * Reading a capability's SHAPE: its interface, and the tables it declares.
+ *
+ * Extracted from `capability-shape-drift.test.ts` so the gate and the tool that
+ * regenerates its fixture compute the same hash from the same code. Two
+ * implementations of "what is this capability's shape" would drift, and the one
+ * in the GENERATOR drifting is indistinguishable from the gate passing.
+ *
+ * Same split as `module-script-scan.ts` / `no-hand-built-ssh.test.ts` in this
+ * directory, for the same reason.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { CapabilityTableDeclaration, CapabilityTables } from '@celilo/capabilities';
+import ts from 'typescript';
+
+/** Walk up to the repo root (the dir holding both modules/ and apps/). */
+export 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 (no ancestor with modules/ + apps/)');
+}
+
+const CAPABILITIES_SRC = join(repoRoot(), 'packages', 'capabilities', 'src');
+
+function parse(file: string): ts.SourceFile {
+  return ts.createSourceFile(file, readFileSync(file, 'utf8'), ts.ScriptTarget.Latest, true);
+}
+
+/**
+ * capability name → { interface type name, source file }, read out of
+ * `capability-registry.ts` itself.
+ */
+export function capabilitySubjects(): Map<string, { typeName: string; file: string }> {
+  const registryFile = join(CAPABILITIES_SRC, 'capability-registry.ts');
+  const source = parse(registryFile);
+
+  // `import type { XCapability } from './x'` → XCapability lives in ./x.ts
+  const fileOfType = new Map<string, string>();
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    const specifier = (statement.moduleSpecifier as ts.StringLiteral).text;
+    for (const element of bindings.elements) {
+      fileOfType.set(
+        element.name.text,
+        join(CAPABILITIES_SRC, `${specifier.replace('./', '')}.ts`),
+      );
+    }
+  }
+
+  const subjects = new Map<string, { typeName: string; file: string }>();
+  for (const statement of source.statements) {
+    if (!ts.isInterfaceDeclaration(statement) || statement.name.text !== 'CapabilityRegistry') {
+      continue;
+    }
+    for (const member of statement.members) {
+      if (!ts.isPropertySignature(member) || !member.name || !member.type) continue;
+      const name = member.name.getText(source);
+      const typeName = member.type.getText(source);
+      const file = fileOfType.get(typeName);
+      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;
+}
+
+/** The interface, re-printed from its AST with comments dropped. */
+function printedInterface(file: string, typeName: string): string {
+  const source = parse(file);
+  const printer = ts.createPrinter({ removeComments: true });
+  for (const statement of source.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName) {
+      return printer.printNode(ts.EmitHint.Unspecified, statement, source);
+    }
+  }
+  throw new Error(`${typeName} not found in ${file}`);
+}
+
+/** Every `* satisfies CapabilityTables` const exported from a capability's module. */
+export async function tablesOf(file: string): Promise<CapabilityTables> {
+  const loaded = (await import(file)) as Record<string, unknown>;
+  const out: Record<string, CapabilityTableDeclaration> = {};
+  for (const [exportName, value] of Object.entries(loaded)) {
+    if (!exportName.endsWith('_TABLES') || typeof value !== 'object' || value === null) continue;
+    for (const [key, decl] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = decl as CapabilityTableDeclaration;
+    }
+  }
+  return out;
+}
+
+/** Order-independent so a reordered literal is not a shape change. */
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .map(([k, v]) => `${k}:${canonical(v)}`)
+      .sort();
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export async function shapeHash(capability: string): Promise<string> {
+  const subject = capabilitySubjects().get(capability);
+  if (!subject) throw new Error(`${capability} is not in CapabilityRegistry`);
+  const iface = printedInterface(subject.file, subject.typeName);
+  const tables = canonical(await tablesOf(subject.file));
+  return createHash('sha256').update(`${iface}\n--tables--\n${tables}`).digest('hex');
+}