@celilo/cli 1.8.0 → 1.9.1

package/src/hooks/mount-set.ts

@@ -0,0 +1,234 @@
+/**
+ * The hook jail's mount set (openspec/changes/hook-process-boundary, D9).
+ *
+ * A jailed hook sees exactly the paths listed here and nothing else. Not
+ * "denied" — ABSENT. A hook reaching for celilo's master key gets `ENOENT`,
+ * because inside the jail there is no such file. That is the acceptance
+ * criterion, and it is satisfied by absence rather than by a check.
+ *
+ * The set is DERIVED, never declared by the module. A module cannot ask for
+ * more, which is the whole point.
+ *
+ * This file is pure. It computes a description of a filesystem view and
+ * touches nothing. That is what lets `bwrap` is never in the mount set be a
+ * hermetic test rather than an integration one, and what lets the unjailed
+ * advisory lint (task 4.7) consume the same computation instead of a second
+ * one that can drift from it.
+ */
+
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import type { PathAccess } from '@celilo/capabilities';
+
+/**
+ * `tmpfs` is not an access level, it is "put a fresh empty filesystem here".
+ * It has to be its own mode because ORDER matters and a tmpfs erases whatever
+ * the jail would otherwise see at that path.
+ */
+export type MountMode = 'ro' | 'rw' | 'tmpfs';
+
+export interface MountEntry {
+  /**
+   * The path, IDENTICAL inside and outside the jail. Never remapped.
+   *
+   * Paths cross the capability boundary as strings: a hook hands the broker a
+   * path it wrote to, and the broker has to be able to read it. A remapped
+   * mount would make those two names disagree and the failure would look like
+   * a missing file rather than a translation bug.
+   */
+  readonly path: string;
+  readonly mode: MountMode;
+  /** Why this row exists. Surfaced by the unjailed lint and by `system doctor`. */
+  readonly reason: string;
+}
+
+export interface MountSet {
+  /**
+   * ORDER IS SEMANTIC. bubblewrap applies these in sequence and a later entry
+   * wins over an earlier one, which is what lets a read-write directory sit
+   * inside a read-only tree. Do not sort this list.
+   */
+  readonly entries: readonly MountEntry[];
+  /**
+   * The jail's working directory.
+   *
+   * The spawn does not set `cwd`, so a hook child inherits celilo's — whatever
+   * directory the operator's shell happened to be in. Inside the jail that
+   * directory usually does not exist, and bubblewrap fails on a path nobody
+   * chose. So the jail names one explicitly.
+   */
+  readonly chdir: string;
+}
+
+/** A path input the contract declared, paired with the value the framework resolved. */
+export interface DeclaredPathInput {
+  readonly name: string;
+  readonly value: string;
+  readonly access: PathAccess;
+}
+
+export interface MountSetRequest {
+  /**
+   * The module's own tree. Comes from the DB as `module.sourcePath`, which is
+   * NOT guaranteed to sit under the module store — a restored database carries
+   * the absolute paths of the box it was taken from (ISS-0052). Resolved below
+   * before it becomes a bind-mount argument.
+   */
+  readonly modulePath: string;
+  /** `<module>/state`, celilo#1000's sanctioned writable directory. */
+  readonly stateDir: string;
+  /** `<module>/screenshots/<run>`, this run only. Absent when the hook takes none. */
+  readonly screenshotDir?: string;
+  /** The directory holding the broker's unix socket. */
+  readonly socketDir: string;
+  /** The interpreter celilo spawns (`process.execPath`). */
+  readonly runtimePath: string;
+  /** The runner shim, which lives in celilo's tree rather than the module's. */
+  readonly runnerPath: string;
+  /** Contract-declared path inputs, already resolved to values. */
+  readonly pathInputs: readonly DeclaredPathInput[];
+  /**
+   * The operator's `~/.ssh`, read-only, STAGE 2 ONLY.
+   *
+   * `remote.ts` still runs inside the hook and needs the key. Stage 3 brokers
+   * those calls and drops this row, which is what turns D12's target check
+   * from a convention into a boundary. Dropping it before stage 3 lands
+   * hardens nothing — it just stops every hook reaching its own systems.
+   */
+  readonly sshDir?: string;
+}
+
+/** Directories whose contents the runtime needs in order to start at all. */
+const RUNTIME_SUPPORT_DIRS = ['/usr/lib', '/lib', '/lib64', '/etc/ssl'] as const;
+
+/**
+ * Paths that must NEVER appear in a mount set, whatever asks for them.
+ *
+ * `bwrap` is the load-bearing entry and the reason this list exists rather
+ * than being a comment. celilo ships an AppArmor profile granting `userns` to
+ * `/usr/bin/bwrap` so the jail can be built at all, and that grant applies to
+ * anyone on the box who runs it. A jailed hook that could exec `bwrap` would
+ * get a namespace of its own, be uid 0 inside it with `CAP_SYS_ADMIN`, and
+ * reach kernel surface an unprivileged user cannot otherwise touch — which is
+ * the entire reason Ubuntu restricts unprivileged user namespaces.
+ *
+ * `bwrap` runs OUTSIDE the jail because it is what creates the jail. It does
+ * not need to exist inside one, so leaving it out costs nothing.
+ *
+ * Task 4.10 already predicts how this gets undone: a browser hook fails with
+ * `bwrap: command not found`, a developer reads a missing binary and adds it,
+ * the suite goes green, and the escape path is open with nothing to read. The
+ * test on this constant is that missing thing to read.
+ */
+const NEVER_MOUNT = ['/usr/bin/bwrap', '/usr/local/bin/bwrap', '/bin/bwrap'] as const;
+
+function entry(path: string, mode: MountMode, reason: string): MountEntry {
+  return { path, mode, reason };
+}
+
+/**
+ * Compute the filesystem view a hook gets.
+ *
+ * Pure: resolves paths lexically and reads nothing from disk. `resolve` is not
+ * `realpath` — it cannot follow a symlink, because following one is I/O. The
+ * caller supplies already-real paths; on macOS that distinction is the
+ * difference between a rule that applies and one that silently does not
+ * (task 4.8), so the caller's `realpath` is not optional.
+ */
+export function deriveMountSet(request: MountSetRequest): MountSet {
+  const modulePath = resolve(request.modulePath);
+  const entries: MountEntry[] = [];
+
+  // 1. A private /tmp FIRST, because it erases everything beneath it.
+  //
+  // This has to lead. The broker's socket directory is an `mkdtemp` under
+  // `os.tmpdir()`, and every staged contract input (backup_dir, restore_dir,
+  // the cross-module roots) comes from `stagingDirFor`, also under
+  // `os.tmpdir()`. Bind those first and the tmpfs wipes them.
+  //
+  // The failure that causes is not a crash. A hook whose `backup_dir` is
+  // silently an empty tmpfs directory writes into it, returns success, and
+  // produces a backup containing NOTHING. It is found at restore. So the gate
+  // on this asserts the artifact is non-empty, never that the hook exited zero.
+  entries.push(entry('/tmp', 'tmpfs', 'private scratch, per run'));
+
+  // 2. The runtime. Without it nothing runs, so it is not really a policy row.
+  entries.push(entry(request.runtimePath, 'ro', 'the interpreter'));
+  entries.push(entry(dirname(request.runnerPath), 'ro', 'the runner shim celilo spawns'));
+  for (const dir of RUNTIME_SUPPORT_DIRS) {
+    entries.push(entry(dir, 'ro', 'shared libraries and trust store'));
+  }
+
+  // 3. The module's own tree, read-only, then its writable directories carved
+  //    on top. bubblewrap resolves that in the right order, which is why the
+  //    order here is not cosmetic.
+  //
+  //    D9 says "the module's own tree is bound read-only". These are the
+  //    carved exceptions to that sentence, and there are three of them rather
+  //    than the one D9's prose implies.
+  entries.push(entry(modulePath, 'ro', "the module's own tree"));
+  entries.push(
+    entry(resolve(request.stateDir), 'rw', 'ctx.stateDir, the sanctioned writable directory'),
+  );
+  entries.push(
+    entry(join(modulePath, 'generated'), 'rw', "celilo's generated output the hook may amend"),
+  );
+  if (request.screenshotDir) {
+    entries.push(entry(resolve(request.screenshotDir), 'rw', 'ctx.screenshotDir, this run only'));
+  }
+
+  // 4. The broker channel. Bound AFTER the tmpfs, per the note above.
+  entries.push(entry(resolve(request.socketDir), 'rw', 'the capability broker socket'));
+
+  // 5. Contract-declared path inputs, at the access the contract declares.
+  //    Never inferred from the name — see ContractField.path.
+  for (const input of request.pathInputs) {
+    entries.push(
+      entry(
+        resolve(input.value),
+        input.access === 'write' ? 'rw' : 'ro',
+        `contract input '${input.name}' (${input.access})`,
+      ),
+    );
+  }
+
+  // 6. Stage 2 only. See MountSetRequest.sshDir.
+  if (request.sshDir) {
+    entries.push(
+      entry(
+        resolve(request.sshDir),
+        'ro',
+        'remote.ts needs the key until the broker holds it (D12)',
+      ),
+    );
+  }
+
+  return {
+    entries: entries.filter((e) => !isForbidden(e.path)),
+    // The module's own tree is the only directory guaranteed to exist inside
+    // the jail and to mean something to the hook.
+    chdir: modulePath,
+  };
+}
+
+/** Is this path one nothing may ever mount? See NEVER_MOUNT. */
+export function isForbidden(path: string): boolean {
+  const resolved = isAbsolute(path) ? resolve(path) : path;
+  return NEVER_MOUNT.some((forbidden) => resolved === forbidden);
+}
+
+/** The forbidden list, for the test that asserts it is honoured. */
+export function forbiddenPaths(): readonly string[] {
+  return NEVER_MOUNT;
+}
+
+/** Render a mount set as bubblewrap arguments, in order. */
+export function toBwrapArgs(set: MountSet): string[] {
+  const args: string[] = [];
+  for (const e of set.entries) {
+    if (e.mode === 'tmpfs') args.push('--tmpfs', e.path);
+    else if (e.mode === 'rw') args.push('--bind', e.path, e.path);
+    else args.push('--ro-bind', e.path, e.path);
+  }
+  args.push('--chdir', set.chdir);
+  return args;
+}

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/contracts/v1.ts

@@ -22,7 +22,7 @@
  * change and requires a v2.0 contract.
  */
 
-import type { HookName } from '@celilo/capabilities';
+import type { HookName, PathAccess } from '@celilo/capabilities';
 
 /**
  * Per-input/output metadata.
@@ -33,6 +33,21 @@ import type { HookName } from '@celilo/capabilities';
  */
 export interface ContractField {
   required: boolean;
+  /**
+   * Set when the framework supplies a filesystem path in this field, and the
+   * access the hook is given to it. Absent means "not a path".
+   *
+   * The hook jail derives its bind mounts from this (design D9). Path-ness is
+   * NEVER inferred from the field name at runtime: a name heuristic silently
+   * changes behaviour the day somebody adds an input called `workspace`, and
+   * the symptom is an ENOENT on a path that visibly exists on the box.
+   *
+   * A field carrying a path-shaped value with no annotation here is a defect.
+   * `db_path` was one for months — passed by `backup-create.ts` and declared
+   * nowhere, so anything reasoning from this table was wrong about what a
+   * backup hook receives.
+   */
+  path?: { access: PathAccess };
 }
 
 /**
@@ -112,7 +127,7 @@ export const V1_HOOKS: ContractHooks = {
   },
   on_backup: {
     inputs: {
-      backup_dir: { required: true },
+      backup_dir: { required: true, path: { access: 'write' } },
       /**
        * Path to a directory containing read-only mirrors of OTHER modules'
        * `generated/terraform/` trees, plus an `index.json` enumerating
@@ -136,7 +151,7 @@ export const V1_HOOKS: ContractHooks = {
        *           terraform.tfstate
        *           terraform.tfstate.backup
        */
-      cross_module_root: { required: false },
+      cross_module_root: { required: false, path: { access: 'read' } },
     },
     outputs: {
       artifact_count: { required: true },
@@ -146,7 +161,7 @@ export const V1_HOOKS: ContractHooks = {
   },
   on_backup_analyze: {
     inputs: {
-      artifact_path: { required: true },
+      artifact_path: { required: true, path: { access: 'read' } },
     },
     outputs: {
       artifact_count: { required: true },
@@ -156,7 +171,7 @@ export const V1_HOOKS: ContractHooks = {
   },
   on_restore: {
     inputs: {
-      restore_dir: { required: true },
+      restore_dir: { required: true, path: { access: 'read' } },
       schema_version: { required: true },
       /**
        * Path to a writable staging directory the framework atomically
@@ -170,7 +185,7 @@ export const V1_HOOKS: ContractHooks = {
        * a single rename + cleanup of any stale files, so a partial
        * write (hook crashed mid-restore) leaves the live state intact.
        */
-      cross_module_write_root: { required: false },
+      cross_module_write_root: { required: false, path: { access: 'write' } },
     },
     outputs: {
       restored_items: { required: true },

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,105 @@
+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 { moduleStateDir } from '@celilo/capabilities';
+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. The path comes
+      // from the framework, NOT from this test: a gate that hand-rolls
+      // `join(root, 'state')` proves the audit tolerates a directory while
+      // saying nothing about whether a module can find it, which is exactly
+      // how the surface half of celilo#1000 shipped missing.
+      const stateDir = moduleStateDir(root);
+      mkdirSync(stateDir, { recursive: true });
+      writeFileSync(join(stateDir, 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).