@celilo/cli 1.8.0 → 1.9.0

package/src/hooks/hook-trespass.test.ts

@@ -0,0 +1,201 @@
+/**
+ * The recurrence gate for openspec/changes/hook-process-boundary (celilo#1001).
+ *
+ * Runs `modules/hello-trespass`'s hook through `executeHookScript` and asserts
+ * exactly what the stage that has landed claims, and nothing more.
+ *
+ * **Stage 1 claims the environment. It does not claim the filesystem and it
+ * does not claim the network.** So this file asserts the sensitive environment
+ * is empty, and asserts the other three trespasses STILL SUCCEED. A gate that
+ * claimed more than its stage delivers would go green for the wrong reason and
+ * would have to be rewritten — quietly weakening it — the first time somebody
+ * noticed. Stage 2 flips the two filesystem rows and stage 3 flips the SSH row;
+ * each stage edits the assertion it earns.
+ *
+ * `HOME` is redirected to a scratch directory holding a planted master key and
+ * a planted SSH key, so the trespasses are deterministic and the operator's
+ * real key is never read (CLAUDE.md: never test against live data). `HOME` is
+ * on design D5's allow-list, so the child resolves the same planted paths the
+ * parent planted — which is the point of D5's own caveat: removing
+ * `CELILO_DATA_DIR` does not hide a path a hook can compute.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { executeHookScript, hookChildEnv } from './executor';
+import { createCapturingLogger } from './logger';
+import type { HookContext } from './types';
+
+const TRESPASS_SCRIPT = resolve(
+  __dirname,
+  '../../../../modules/hello-trespass/scripts/trespass.ts',
+);
+
+interface TrespassOutcome {
+  attempted: boolean;
+  succeeded: boolean;
+  target: string;
+  detail: string;
+}
+
+interface TrespassReport {
+  master_key: TrespassOutcome;
+  sibling_write: TrespassOutcome;
+  ssh_key: TrespassOutcome;
+  remote_exec: TrespassOutcome;
+  sensitive_env: string[];
+}
+
+let scratchHome: string;
+let realHome: string | undefined;
+
+/**
+ * Install the fixture module's own dependencies if they are not there.
+ *
+ * A `modules/<id>/scripts` directory is a standalone package, deliberately
+ * outside the root workspace globs so that a module resolves the PUBLISHED
+ * `@celilo/capabilities` it will actually run on the fleet rather than the
+ * workspace copy. bun links workspace dependencies into each package's own
+ * `node_modules` and never into the repo root, so there is nothing here for
+ * the fixture to walk up to: with no install of its own the hook dies with
+ * `Cannot find module '@celilo/capabilities'`.
+ *
+ * `bun run setup` does this for every module, and CI does it in its
+ * check-modules step — which runs LAST on purpose, because twenty-two installs
+ * is the slowest thing in that job. This gate is the first test to reach into
+ * a module's script tree, so it prepares the one fixture it needs instead of
+ * making every PR pay for all of them up front.
+ *
+ * It installs rather than skipping. A gate that quietly does not run is the
+ * exact failure this whole change exists to make impossible.
+ */
+function ensureFixtureInstalled(): void {
+  const scriptsDir = dirname(TRESPASS_SCRIPT);
+  if (existsSync(join(scriptsDir, 'node_modules', '@celilo', 'capabilities'))) return;
+  // `process.execPath`, not `bun` on PATH: this is the bun already running the
+  // suite, so it works wherever the suite does.
+  execFileSync(process.execPath, ['install'], { cwd: scriptsDir, stdio: 'pipe' });
+}
+
+beforeAll(() => {
+  ensureFixtureInstalled();
+  scratchHome = mkdtempSync(join(tmpdir(), 'celilo-trespass-home-'));
+
+  // The master key at getMasterKeyPath()'s DEFAULT location for this platform.
+  // Both branches are planted rather than the current one only, so the fixture
+  // reads a planted key whichever host runs the suite.
+  for (const dir of [
+    join(scratchHome, 'Library', 'Application Support', 'celilo'),
+    join(scratchHome, '.local', 'share', 'celilo'),
+  ]) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'master.key'), 'not-the-real-key\n');
+  }
+
+  mkdirSync(join(scratchHome, '.ssh'), { recursive: true });
+  writeFileSync(join(scratchHome, '.ssh', 'id_ed25519'), 'not-a-real-key\n');
+
+  realHome = process.env.HOME;
+  process.env.HOME = scratchHome;
+});
+
+afterAll(() => {
+  if (realHome === undefined) delete process.env.HOME;
+  else process.env.HOME = realHome;
+  rmSync(scratchHome, { recursive: true, force: true });
+});
+
+async function runTrespass(): Promise<{ report: TrespassReport; lines: string[] }> {
+  const { logger, messages } = createCapturingLogger();
+  const context: HookContext = {
+    config: { sibling_module_id: 'hello-foo', other_system_ip: '' },
+    secrets: {},
+    systems: [],
+    logger,
+    debug: false,
+    screenshotDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
+    capabilities: {},
+  };
+
+  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, 60_000, 60_000);
+  return {
+    report: outputs as unknown as TrespassReport,
+    lines: messages.map((m) => m.message),
+  };
+}
+
+describe('the child environment is an allow-list', () => {
+  // The trespass gate below proves nothing sensitive gets through. This is the
+  // complement: the six things that MUST get through, because a hook with no
+  // `PATH` cannot spawn anything and one with no `HOME` breaks more than it
+  // protects.
+  test('forwards the allow-list and the channel, and nothing else', () => {
+    process.env.CELILO_TEST_SECRET = 'must-not-cross';
+    try {
+      const env = hookChildEnv('/tmp/celilo-hook-x/s');
+
+      expect(env.CELILO_HOOK_SOCKET).toBe('/tmp/celilo-hook-x/s');
+      expect(env.CELILO_HOOK_PROTOCOL_VERSION).toBe('1');
+      expect(env.PATH).toBe(process.env.PATH as string);
+      expect(env.HOME).toBe(process.env.HOME as string);
+      expect(env.CELILO_TEST_SECRET).toBeUndefined();
+
+      const allowed = new Set([
+        'PATH',
+        'HOME',
+        'LANG',
+        'TZ',
+        'TMPDIR',
+        'CELILO_DEBUG',
+        'CELILO_HOOK_SOCKET',
+        'CELILO_HOOK_PROTOCOL_VERSION',
+      ]);
+      expect(Object.keys(env).filter((name) => !allowed.has(name))).toEqual([]);
+    } finally {
+      delete process.env.CELILO_TEST_SECRET;
+    }
+  });
+
+  test('omits an allow-listed variable the parent does not have', () => {
+    const saved = process.env.TZ;
+    delete process.env.TZ;
+    try {
+      // Absent, not the string "undefined" — which is what a naive copy
+      // produces and what a shell then happily uses as a timezone.
+      expect('TZ' in hookChildEnv('/tmp/s')).toBe(false);
+    } finally {
+      if (saved !== undefined) process.env.TZ = saved;
+    }
+  });
+});
+
+describe('hook process boundary — hello-trespass gate', () => {
+  test('stage 1: the environment is clean, and nothing else has changed', async () => {
+    const { report, lines } = await runTrespass();
+
+    // The evidence, printed whether the assertions pass or fail. Without it a
+    // red run says which assertion broke and not what the hook actually saw.
+    console.log(['', 'hello-trespass:', ...lines.slice(1)].join('\n'));
+
+    // What stage 1 claims. Empty because the child's environment is an
+    // allow-list, not `...process.env` (design D5).
+    expect(report.sensitive_env).toEqual([]);
+
+    // What stage 1 deliberately does NOT claim. The master key is still
+    // readable, because the hook computes the default path rather than
+    // reading it out of the environment. Stage 2's mount set is what removes
+    // it, by not binding the data directory at all.
+    expect(report.master_key.succeeded).toBe(true);
+
+    // Nor the sibling's tree: the module store is still one `..` away.
+    expect(report.sibling_write.succeeded).toBe(true);
+
+    // Nor the SSH key, which is what scopes reachability in stage 3 (D12).
+    // `attempted: false` means the host has no private key at all — a bare CI
+    // runner — which is an absent precondition, not a refusal.
+    expect(report.ssh_key.attempted && !report.ssh_key.succeeded).toBe(false);
+  });
+});

package/src/hooks/injected-capabilities.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Every name the loader can put in `ctx.capabilities` must be a registered
+ * capability.
+ *
+ * This is the gate for the class of bug, not for its instances. Twice now a
+ * capability has been injected under a literal name that appeared in no
+ * registry and, in one case, had no declared type anywhere:
+ *
+ *   - `web_routes`, whose two methods were synchronous. The hook process
+ *     boundary's D2 measured the hook-facing surface as uniformly async by
+ *     reading `CapabilityRegistry`, so it never saw them. caddy's `on_install`
+ *     died on `{} is not iterable` when the async proxy handed it a Promise.
+ *   - `firewall_registry`, which had no `FirewallRegistryCapability` type, no
+ *     registry entry, and no contract version. It happens to be async, so it
+ *     broke nothing, which is exactly why nobody found it.
+ *
+ * `type-invariants.test.ts` proves every REGISTERED capability's methods are
+ * async. That proof is only worth as much as the registry's completeness, and
+ * completeness is what this file checks. Together they close the loop: the
+ * registry names everything injected, and everything named is async.
+ *
+ * It reads the loader's source because the property is about what the code can
+ * assign, not about what one run happens to produce. A runtime test would need
+ * every provider deployed in every combination to see all the branches.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KNOWN_CAPABILITY_NAMES } from '@celilo/capabilities';
+
+const LOADER = join(__dirname, 'capability-loader.ts');
+
+/**
+ * Literal names assigned into the capability map, e.g. `result.web_routes =`.
+ *
+ * Computed assignments (`result[capName] =`) are deliberately not matched:
+ * `capName` is already a registry name, since it comes from the capability
+ * table keyed by the same list.
+ */
+function injectedCapabilityNames(source: string): string[] {
+  const names = new Set<string>();
+  for (const match of source.matchAll(/^\s*result\.([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)) {
+    names.add(match[1]);
+  }
+  return [...names].sort();
+}
+
+describe('capabilities injected into the hook context', () => {
+  test('every literally-named injection is a registered capability', () => {
+    const injected = injectedCapabilityNames(readFileSync(LOADER, 'utf-8'));
+
+    // If this is empty the regex has drifted and the gate is checking nothing,
+    // which is the failure mode that makes a green test worse than no test.
+    expect(injected.length).toBeGreaterThan(0);
+
+    const known: readonly string[] = KNOWN_CAPABILITY_NAMES;
+    const unregistered = injected.filter((name) => !known.includes(name));
+
+    expect(unregistered).toEqual([]);
+  });
+
+  test('PROVE IT FAILS: an unregistered name is caught', () => {
+    const withNewInjection = `
+      result.public_web = createPublicWeb({});
+      result.brand_new_view = somethingUndeclared;
+    `;
+    const known: readonly string[] = KNOWN_CAPABILITY_NAMES;
+    const unregistered = injectedCapabilityNames(withNewInjection).filter(
+      (name) => !known.includes(name),
+    );
+
+    expect(unregistered).toEqual(['brand_new_view']);
+  });
+});

package/src/hooks/test-fixtures/capability-calling-hook.ts

@@ -0,0 +1,79 @@
+/**
+ * Test fixture: a hook that exercises every shape a capability call can take
+ * across the process boundary.
+ *
+ * One test per SHAPE rather than per method: the broker is generic, so a
+ * per-method suite would prove the same thing thirty-seven times and drift the
+ * moment a capability gained a method.
+ */
+
+import { defineHook, isMissingProviderInputError } from '@celilo/capabilities';
+
+interface DemoCapability {
+  providerModuleId?: string;
+  version?: string;
+  echo(request: Record<string, unknown>): Promise<unknown>;
+  boom(request: Record<string, unknown>): Promise<unknown>;
+  missingInput(request: Record<string, unknown>): Promise<unknown>;
+  returnsNothing(request: Record<string, unknown>): Promise<unknown>;
+  /** Never implemented by this provider — the absent-optional-method case. */
+  sometimesAbsent?(request: Record<string, unknown>): Promise<unknown>;
+}
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    // `demo` is a fixture capability, not a registry entry, so the typed
+    // capability map does not know it. The broker is generic and does not care.
+    const demo = (ctx.capabilities as unknown as Record<string, DemoCapability>).demo;
+    const outputs: Record<string, unknown> = {};
+
+    // Non-function properties are copied verbatim, which is what keeps
+    // `providerModuleId` readable — a hook names the provider in its errors.
+    outputs.providerModuleId = demo.providerModuleId;
+    outputs.version = demo.version;
+
+    // An optional method the provider did not implement must be ABSENT, not a
+    // proxy that throws, or `if (cap.registerTrustedSource)` answers wrongly.
+    outputs.optionalMethodAbsent = demo.sometimesAbsent === undefined;
+
+    outputs.returned = await demo.echo({ x: 1, nested: { y: [2, 3] } });
+    outputs.undefinedBecomesNull = await demo.returnsNothing({});
+
+    try {
+      await demo.boom({});
+      outputs.plainThrow = 'did not throw';
+    } catch (error) {
+      outputs.plainThrow = {
+        isError: error instanceof Error,
+        name: (error as Error).name,
+        message: (error as Error).message,
+        hasStack: typeof (error as Error).stack === 'string',
+      };
+    }
+
+    try {
+      await demo.missingInput({});
+      outputs.missingProviderInput = 'did not throw';
+    } catch (error) {
+      const e = error as Record<string, unknown>;
+      outputs.missingProviderInput = {
+        recognised: isMissingProviderInputError(error),
+        providerModuleId: e.providerModuleId,
+        ensureId: e.ensureId,
+        value: e.value,
+        humanContext: e.humanContext,
+      };
+    }
+
+    try {
+      await (demo as unknown as { nope(): Promise<unknown> }).nope();
+      outputs.unknownMethod = 'did not throw';
+    } catch (error) {
+      outputs.unknownMethod = (error as Error).message;
+    }
+
+    return outputs;
+  },
+});

package/src/hooks/test-fixtures/runaway-hook.ts

@@ -0,0 +1,26 @@
+/**
+ * Test fixture: a hook that outruns its total timeout and then writes a file.
+ *
+ * The marker is the harm, not the mechanism. `Promise.race` in the old
+ * executor rejected at the bound and cancelled nothing, so the hook kept its
+ * capability objects and went on doing work — registering DNS, opening ports —
+ * minutes after celilo reported the deploy failed. A test that only asserts
+ * the rejection cannot see that; it passed throughout (celilo#1003).
+ *
+ * The marker is written AFTER the sleep, so its existence after the bound is
+ * proof the hook was abandoned rather than killed.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    ctx.logger.info('runaway hook starting');
+    await new Promise((r) => setTimeout(r, Number(ctx.config.sleep_ms ?? 2000)));
+    writeFileSync(String(ctx.config.marker_path), 'the hook kept running\n');
+    return {};
+  },
+});

package/src/hooks/test-fixtures/sigterm-ignoring-hook.ts

@@ -0,0 +1,22 @@
+/**
+ * Test fixture: a hook that traps SIGTERM and keeps going.
+ *
+ * SIGTERM is a request. This is the case that makes the grace period load
+ * bearing: without the SIGKILL that follows it, a hook can decline to die and
+ * the boundary buys nothing over the promise race it replaced.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    process.on('SIGTERM', () => ctx.logger.info('declining to die'));
+    ctx.logger.info('sigterm-ignoring hook starting');
+    await new Promise((r) => setTimeout(r, Number(ctx.config.sleep_ms ?? 20_000)));
+    writeFileSync(String(ctx.config.marker_path), 'survived SIGTERM\n');
+    return {};
+  },
+});

package/src/manifest/validate-provider-views.test.ts

@@ -0,0 +1,61 @@
+/**
+ * A module may not declare a provider view.
+ *
+ * `web_routes` and `firewall_registry` are in `KNOWN_CAPABILITY_NAMES`, so the
+ * name check that asks only "is this known?" accepts them. celilo injects both
+ * into the hooks of the module that PROVIDES the paired capability and never
+ * to a consumer, so a module requiring one would validate, publish, deploy, and
+ * then find the capability simply absent at hook time — with a pre-flight error
+ * naming a missing provider that was never going to exist.
+ *
+ * Registering the two names (celilo#1007) is what created this opening. They
+ * were invisible to every check before that, which was its own, worse problem.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { PROVIDER_VIEW_CAPABILITIES } from '@celilo/capabilities';
+import type { ModuleManifest } from './schema';
+import { validateCapabilityNames } from './validate';
+
+function manifestRequiring(name: string): ModuleManifest {
+  return {
+    requires: { capabilities: [{ name, version: '1.0.0' }] },
+  } as unknown as ModuleManifest;
+}
+
+function manifestOptionally(name: string): ModuleManifest {
+  return {
+    requires: { capabilities: [] },
+    optional: { capabilities: [{ name, version: '1.0.0' }] },
+  } as unknown as ModuleManifest;
+}
+
+describe('provider views are not declarable', () => {
+  for (const view of PROVIDER_VIEW_CAPABILITIES) {
+    test(`requires.capabilities rejects '${view}'`, () => {
+      const result = validateCapabilityNames(manifestRequiring(view));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0].message).toContain('provider view');
+    });
+
+    test(`optional.capabilities rejects '${view}' too`, () => {
+      // The optional path is checked for the same reason the privileged-
+      // capability check covers it: otherwise the declaration is smuggled in
+      // through the soft-require door.
+      const result = validateCapabilityNames(manifestOptionally(view));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0].message).toContain('provider view');
+    });
+
+    test(`'${view}' is not offered in the suggestion list`, () => {
+      // The message for a genuine typo lists what an author CAN require, so a
+      // view must not appear there either.
+      const result = validateCapabilityNames(manifestRequiring('definitely_not_a_capability'));
+      expect(result?.errors[0].message).not.toContain(view);
+    });
+  }
+
+  test('a real capability still validates', () => {
+    expect(validateCapabilityNames(manifestRequiring('public_web'))).toBeNull();
+  });
+});

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/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

@@ -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;