@celilo/cli 1.12.0 → 1.13.0

package/src/manifest/validate.test.ts

@@ -7,6 +7,8 @@ import {
   validateHookContract,
   validateManifest,
   validateProvidesNoCrossCapabilityRefs,
+  validateSubmoduleDeclaration,
+  validateSubmoduleManifest,
   validateVariableSources,
 } from './validate';
 
@@ -1531,3 +1533,143 @@ base_module_aspect:
     expect(result.success).toBe(false);
   });
 });
+
+describe('submodules (openspec/changes/submodules D1, D9)', () => {
+  const parent = (over: Record<string, unknown> = {}) => ({
+    celilo_contract: '1.0' as const,
+    id: 'forgejo',
+    name: 'Forgejo',
+    version: '1.0.0',
+    requires: { capabilities: [] },
+    provides: { capabilities: [] },
+    variables: { owns: [], imports: [] },
+    ...over,
+  });
+
+  const submodule = (over: Record<string, unknown> = {}) => ({
+    celilo_contract: '1.0' as const,
+    id: 'runner',
+    name: 'Forgejo Runner',
+    version: '1.0.0',
+    requires: { capabilities: [] },
+    provides: { capabilities: [] },
+    variables: { owns: [], imports: [] },
+    ...over,
+  });
+
+  describe('validateSubmoduleDeclaration', () => {
+    test('a module declaring no submodules is unaffected', () => {
+      expect(validateSubmoduleDeclaration(parent())).toBeNull();
+    });
+
+    test('accepts a plain list of names', () => {
+      expect(validateSubmoduleDeclaration(parent({ submodules: ['runner'] }))).toBeNull();
+    });
+
+    test('rejects a duplicate name', () => {
+      const result = validateSubmoduleDeclaration(parent({ submodules: ['runner', 'runner'] }));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('more than once');
+    });
+
+    test('rejects a submodule sharing its parent id', () => {
+      const result = validateSubmoduleDeclaration(parent({ submodules: ['forgejo'] }));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain("parent module's id");
+    });
+  });
+
+  describe('validateSubmoduleManifest', () => {
+    test('accepts an ordinary submodule manifest', () => {
+      expect(validateSubmoduleManifest(parent(), 'runner', submodule())).toBeNull();
+    });
+
+    test('rejects an id that disagrees with its directory', () => {
+      const result = validateSubmoduleManifest(parent(), 'runner', submodule({ id: 'builder' }));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('does not match its directory');
+    });
+
+    // D9: a capability resolves to ONE provider, and celilo's two bespoke
+    // multi-provider rules RESOLVE rather than fail, so N instances would bind
+    // a consumer to whichever was created first — silently.
+    test('rejects a submodule that provides a capability', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({
+          provides: { capabilities: [{ name: 'source_forge', version: '1.0.0', data: {} }] },
+        }),
+      );
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('may not provide a capability');
+      expect(result?.errors[0]?.message).toContain('source_forge');
+    });
+
+    test('a submodule may still REQUIRE capabilities', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({ requires: { capabilities: [{ name: 'source_forge', version: '1.0.0' }] } }),
+      );
+      expect(result).toBeNull();
+    });
+
+    test('rejects nesting — ownership is one level deep', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({ submodules: ['nested'] }),
+      );
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('may not declare submodules of its own');
+    });
+
+    test('reports every problem at once rather than stopping at the first', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({
+          id: 'builder',
+          provides: { capabilities: [{ name: 'source_forge', version: '1.0.0', data: {} }] },
+          submodules: ['nested'],
+        }),
+      );
+      expect(result?.errors).toHaveLength(3);
+    });
+  });
+
+  describe('schema', () => {
+    test('parses a manifest declaring submodules', () => {
+      const yaml = `
+celilo_contract: "1.0"
+id: forgejo
+name: Forgejo
+version: 1.0.0
+submodules:
+  - runner
+requires:
+  capabilities: []
+`;
+      const result = validateManifest(yaml);
+      expect(result.success).toBe(true);
+      if (result.success) expect(result.data.submodules).toEqual(['runner']);
+    });
+
+    test('rejects a non-kebab-case submodule name', () => {
+      const yaml = `
+celilo_contract: "1.0"
+id: forgejo
+name: Forgejo
+version: 1.0.0
+submodules:
+  - Runner_One
+requires:
+  capabilities: []
+`;
+      const result = validateManifest(yaml);
+      expect(result.success).toBe(false);
+      if (!result.success) expect(result.errors[0]?.message).toContain('kebab-case');
+    });
+  });
+});

package/src/manifest/validate.ts

@@ -1,6 +1,7 @@
 import { KNOWN_CAPABILITY_NAMES, isProviderView } from '@celilo/capabilities';
 import { parse as parseYaml } from 'yaml';
 import type { ZodError } from 'zod';
+import { SUBMODULES_DIR } from '../module/packaging/package-rules';
 import { validateModuleZoneRequirements } from '../services/zone-policy';
 import { resolveContract, supportedContractVersions } from './contracts';
 import { ModuleManifestSchema, getSingularSystemSpec } from './schema';
@@ -495,3 +496,103 @@ export function validateProvidesNoCrossCapabilityRefs(
 
   return null;
 }
+
+/**
+ * The directory a parent's submodules live in, relative to the parent's own
+ * source root. Re-exported rather than redefined: the packaging rules need the
+ * same name and `package-rules.ts` is deliberately dependency-free (the
+ * registry server imports it), so it owns the definition and everything
+ * manifest-facing reads it from here.
+ */
+export { SUBMODULES_DIR };
+
+/**
+ * Validate a PARENT's `submodules` declaration.
+ *
+ * Policy function - checks the declaration itself, not the submodules it names.
+ * Reading those is I/O and belongs to the caller.
+ *
+ * @param manifest - Validated manifest of the parent
+ * @returns Validation errors if any, null if clean
+ */
+export function validateSubmoduleDeclaration(manifest: ModuleManifest): ValidationError | null {
+  const declared = manifest.submodules ?? [];
+  if (declared.length === 0) return null;
+
+  const errors: Array<{ path: string; message: string }> = [];
+  const seen = new Set<string>();
+
+  for (const [index, name] of declared.entries()) {
+    if (seen.has(name)) {
+      errors.push({
+        path: `submodules.${index}`,
+        message: `Submodule '${name}' is declared more than once`,
+      });
+    }
+    seen.add(name);
+
+    // The derived id of an instance is built from the parent and the submodule
+    // name, so a submodule sharing its parent's id yields an instance id that
+    // reads as the parent's own. Cheap to refuse, confusing to debug.
+    if (name === manifest.id) {
+      errors.push({
+        path: `submodules.${index}`,
+        message: `Submodule '${name}' cannot share its parent module's id`,
+      });
+    }
+  }
+
+  return errors.length > 0 ? { success: false, errors } : null;
+}
+
+/**
+ * Validate that a SUBMODULE's own manifest is legal as a submodule.
+ *
+ * Policy function - the caller has already read and schema-validated the
+ * submodule's manifest; this decides whether it may be one.
+ *
+ * @param parent - The declaring parent's manifest
+ * @param submoduleName - The name the parent declared, i.e. its directory
+ * @param submodule - The submodule's own validated manifest
+ * @returns Validation errors if any, null if clean
+ */
+export function validateSubmoduleManifest(
+  parent: ModuleManifest,
+  submoduleName: string,
+  submodule: ModuleManifest,
+): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+  const where = `${SUBMODULES_DIR}/${submoduleName}/manifest.yml`;
+
+  if (submodule.id !== submoduleName) {
+    errors.push({
+      path: `${where}#id`,
+      message: `Submodule id '${submodule.id}' does not match its directory '${submoduleName}'. A submodule is addressed by the name its parent declares, so the two must agree.`,
+    });
+  }
+
+  // D9: celilo has no general rule for resolving a capability name to one of
+  // several providers. The two bespoke rules that exist RESOLVE rather than
+  // fail — `firewall` builds a chain, `dns_registrar` takes the first row — so
+  // N instances registering one capability would silently bind a consumer to
+  // whichever was created first. Refused here rather than discovered there.
+  if ((submodule.provides?.capabilities ?? []).length > 0) {
+    const names = submodule.provides.capabilities.map((c) => c.name).join(', ');
+    errors.push({
+      path: `${where}#provides.capabilities`,
+      message: `A submodule may not provide a capability (declares: ${names}). A capability resolves to ONE provider, and a submodule exists as many instances, so a consumer would bind to whichever instance happened to be created first. Move the capability to '${parent.id}'.`,
+    });
+  }
+
+  // One level only. D4's instance layout puts every instance flat under
+  // `modules/`, and nesting would make a derived id ambiguous about which
+  // ancestor owns it.
+  if ((submodule.submodules ?? []).length > 0) {
+    errors.push({
+      path: `${where}#submodules`,
+      message: `A submodule may not declare submodules of its own. Ownership is one level deep: '${parent.id}' owns '${submoduleName}', and nothing owns anything below that.`,
+    });
+  }
+
+  return errors.length > 0 ? { success: false, errors } : null;
+}

package/src/module/import.test.ts

@@ -171,6 +171,122 @@ version: 1.0.0
     });
   });
 
+  describe('submodules (openspec/changes/submodules D1)', () => {
+    const PARENT = `
+celilo_contract: "1.0"
+id: forgejo
+name: Forgejo
+version: 1.0.0
+submodules:
+  - runner
+`;
+    const SUBMODULE = `
+celilo_contract: "1.0"
+id: runner
+name: Forgejo Runner
+version: 1.0.0
+`;
+
+    async function writeParent(dirName: string, parent: string, submodule?: string) {
+      const moduleDir = join(TEST_FIXTURES_DIR, dirName);
+      await mkdir(moduleDir, { recursive: true });
+      await writeFile(join(moduleDir, 'manifest.yml'), parent);
+      if (submodule !== undefined) {
+        const subDir = join(moduleDir, 'submodules', 'runner');
+        await mkdir(subDir, { recursive: true });
+        await writeFile(join(subDir, 'manifest.yml'), submodule);
+      }
+      return moduleDir;
+    }
+
+    test('accepts a parent whose declared submodule is present and legal', async () => {
+      const dir = await writeParent('forgejo-ok', PARENT, SUBMODULE);
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(true);
+      if (result.success) expect(result.manifest.submodules).toEqual(['runner']);
+    });
+
+    // The point of validating at PARENT import: an instantiation happens with
+    // no operator present, which is the worst moment to learn a manifest is
+    // broken.
+    test('rejects a parent declaring a submodule that does not exist', async () => {
+      const dir = await writeParent('forgejo-missing', PARENT);
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain('submodules/runner/manifest.yml does not exist');
+      }
+    });
+
+    test('rejects a parent whose submodule provides a capability', async () => {
+      const dir = await writeParent(
+        'forgejo-provides',
+        PARENT,
+        `${SUBMODULE}
+provides:
+  capabilities:
+    - name: source_forge
+      version: 1.0.0
+      data: {}
+`,
+      );
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(false);
+      if (!result.success) expect(result.error).toContain('may not provide a capability');
+    });
+
+    test('rejects a submodule whose id disagrees with its directory', async () => {
+      const dir = await writeParent(
+        'forgejo-mismatch',
+        PARENT,
+        SUBMODULE.replace('id: runner', 'id: builder'),
+      );
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(false);
+      if (!result.success) expect(result.error).toContain('does not match its directory');
+    });
+
+    test('a module declaring no submodules is unaffected', async () => {
+      const dir = await writeParent(
+        'plain-module',
+        `
+celilo_contract: "1.0"
+id: plain
+name: Plain
+version: 1.0.0
+`,
+      );
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(true);
+    });
+
+    // A submodule reaches the fleet inside its parent's package. The registry
+    // path is already closed (submodules are never published separately), so a
+    // local path is the only open door and this is what shuts it.
+    test('refuses to import a submodule directory on its own, naming the parent', async () => {
+      await writeParent('forgejo-direct', PARENT, SUBMODULE);
+      const submodulePath = join(TEST_FIXTURES_DIR, 'forgejo-direct', 'submodules', 'runner');
+
+      const error = validateModuleDirectory(submodulePath);
+
+      expect(error).not.toBeNull();
+      expect(error).toContain("is a submodule of 'forgejo-direct'");
+      expect(error).toContain('Import');
+    });
+
+    test('a trailing slash does not defeat the submodule refusal', async () => {
+      await writeParent('forgejo-slash', PARENT, SUBMODULE);
+      const submodulePath = `${join(TEST_FIXTURES_DIR, 'forgejo-slash', 'submodules', 'runner')}/`;
+
+      expect(validateModuleDirectory(submodulePath)).toContain('is a submodule of');
+    });
+
+    test('an ordinary module directory is still importable', async () => {
+      const dir = await writeParent('ordinary', PARENT, SUBMODULE);
+      expect(validateModuleDirectory(dir)).toBeNull();
+    });
+  });
+
   describe('copyModuleFiles', () => {
     test('should copy all files from source to target', async () => {
       const sourceDir = join(TEST_FIXTURES_DIR, 'source');

package/src/module/import.ts

@@ -1,7 +1,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, statSync, writeFileSync } from 'node:fs';
 import { copyFile, mkdir, readFile, readdir } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { z } from 'zod';
 import { getWellKnownCapability, isWellKnown } from '../capabilities/well-known';
@@ -12,12 +12,15 @@ import { capabilities, moduleIntegrity, modules } from '../db/schema';
 import type { NewModule, NewModuleIntegrity } from '../db/schema';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import {
+  SUBMODULES_DIR,
   validateCapabilityNames,
   validateDeriveFromSources,
   validateHookContract,
   validateManifest,
   validatePrivilegedCapabilities,
   validateProvidesNoCrossCapabilityRefs,
+  validateSubmoduleDeclaration,
+  validateSubmoduleManifest,
   validateVariableSources,
   validateZoneRequirements,
 } from '../manifest/validate';
@@ -93,6 +96,17 @@ export function validateModuleDirectory(sourcePath: string): string | null {
     return `Module directory does not exist: ${sourcePath}`;
   }
 
+  // A submodule is not a module (design D1). It reaches the fleet inside its
+  // parent's package and exists only as instances the parent creates, so
+  // importing one on its own would produce a top-level module that was never
+  // written to be singular. The registry path is already closed — submodules
+  // are never published separately — so a local path is the only open door.
+  const parentDir = dirname(sourcePath.replace(/\/+$/, ''));
+  if (basename(parentDir) === SUBMODULES_DIR) {
+    const owner = basename(dirname(parentDir));
+    return `'${basename(sourcePath)}' is a submodule of '${owner}', not a module. Import '${owner}' instead — its package carries this submodule, and only '${owner}' can instantiate it.`;
+  }
+
   // Check it's a directory
   const stats = statSync(sourcePath);
   if (!stats.isDirectory()) {
@@ -208,12 +222,70 @@ export async function readModuleManifest(
     };
   }
 
+  const submoduleCheck = await validateDeclaredSubmodules(sourcePath, validationResult.data);
+  if (submoduleCheck) {
+    return { success: false, error: submoduleCheck };
+  }
+
   return {
     success: true,
     manifest: validationResult.data,
   };
 }
 
+/**
+ * Read and validate every submodule a parent declares.
+ *
+ * Runs at PARENT IMPORT so a broken submodule fails the parent, rather than
+ * surfacing at the first instantiation — which happens with no operator
+ * present and is the worst possible moment to learn a manifest is wrong
+ * (design D1).
+ *
+ * @param sourcePath - The parent's module directory
+ * @param parent - The parent's validated manifest
+ * @returns An error message if any submodule is missing or illegal, null if clean
+ */
+async function validateDeclaredSubmodules(
+  sourcePath: string,
+  parent: ModuleManifest,
+): Promise<string | null> {
+  const declarationCheck = validateSubmoduleDeclaration(parent);
+  if (declarationCheck) {
+    const errorMessages = declarationCheck.errors.map((e) => `${e.path}: ${e.message}`).join('\n');
+    return `Submodule declaration validation failed:\n${errorMessages}`;
+  }
+
+  for (const name of parent.submodules ?? []) {
+    const submodulePath = join(sourcePath, SUBMODULES_DIR, name);
+    const manifestPath = join(submodulePath, 'manifest.yml');
+
+    if (!existsSync(manifestPath)) {
+      return `Module '${parent.id}' declares submodule '${name}', but ${SUBMODULES_DIR}/${name}/manifest.yml does not exist.`;
+    }
+
+    let yamlContent: string;
+    try {
+      yamlContent = await readFile(manifestPath, 'utf-8');
+    } catch (error) {
+      return `Failed to read ${SUBMODULES_DIR}/${name}/manifest.yml: ${error instanceof Error ? error.message : 'Unknown error'}`;
+    }
+
+    const parsed = validateManifest(yamlContent);
+    if (!parsed.success) {
+      const errorMessages = parsed.errors.map((e) => `${e.path}: ${e.message}`).join(', ');
+      return `Submodule '${name}' has an invalid manifest: ${errorMessages}`;
+    }
+
+    const submoduleCheck = validateSubmoduleManifest(parent, name, parsed.data);
+    if (submoduleCheck) {
+      const errorMessages = submoduleCheck.errors.map((e) => `${e.path}: ${e.message}`).join('\n');
+      return `Submodule '${name}' validation failed:\n${errorMessages}`;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Copy module files to target directory
  *

package/src/module/packaging/audit.ts

@@ -2,9 +2,15 @@ import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { getDb } from '../../db/client';
+import { type DbClient, getDb } from '../../db/client';
 import { moduleIntegrity, modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
+import {
+  type InstanceRecord,
+  loadInstance,
+  submoduleSourcePath,
+  verifyInstanceLinks,
+} from '../../services/module-instances';
 import { computeFileChecksum } from './checksum';
 import type { IntegrityViolation } from './extract';
 import { compareVerbatimRoleAssets, readVerbatimRoleAssets } from './generated-plane';
@@ -49,6 +55,21 @@ async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
     const fullPath = join(dir, entry.name);
     const relativePath = relative(baseDir, fullPath);
 
+    // A symlink is SKIPPED, deliberately and in writing.
+    //
+    // An instance's authored source is symlinked in from its parent's
+    // `submodules/` tree (openspec/changes/submodules D4), so those bytes are
+    // the PARENT's and are covered by the parent's baseline. This module has no
+    // claim to make over them, and following the link would have it claim
+    // integrity over bytes whose checksums belong to somebody else.
+    //
+    // This already happened, by accident: `Dirent.isDirectory()` and
+    // `isFile()` are BOTH false for a symlink, so links fell through both
+    // branches below and vanished. Right answer, no reason. Stating it here
+    // means a later change that makes the walk follow links has to decide
+    // about instances on purpose rather than reverse this silently.
+    if (entry.isSymbolicLink()) continue;
+
     if (entry.isDirectory()) {
       // Prune whole derived subtrees rather than walking them. `generated/`
       // alone carries terraform provider binaries.
@@ -91,6 +112,18 @@ export async function auditModule(
       };
     }
 
+    // An instance has no integrity row of its own and never will
+    // (openspec/changes/submodules D4). Its authored bytes are its
+    // submodule's, its submodule's are its parent's, and the parent already
+    // carries a baseline covering `submodules/**`. So it resolves THROUGH to
+    // that rather than being excluded: excluding it would report nothing for
+    // forty rows, and erroring would report `No integrity data found` forty
+    // times for a fleet that is entirely healthy.
+    const instance = loadInstance(moduleId, db);
+    if (instance) {
+      return await auditInstance(instance, module.sourcePath, db, options);
+    }
+
     // Get integrity data
     const integrity = db
       .select()
@@ -242,3 +275,72 @@ export async function auditModule(
     };
   }
 }
+
+/**
+ * Audit an instance.
+ *
+ * Two questions, and only the second is the instance's own.
+ *
+ * Its BYTES belong to its parent, so the integrity verdict is the parent's:
+ * `submodules/**` classifies `package`, so the parent's baseline already covers
+ * every file an instance runs. Re-checksumming them here would be asking the
+ * same question a second time and inventing a second answer that can disagree.
+ *
+ * Its LINKS are its own, and nothing else in celilo checks them. A link
+ * repointed at another module's source is an instance running somebody else's
+ * code while every checksum in the fleet still reconciles, which is exactly the
+ * kind of quiet wrong answer the integrity plane exists to prevent.
+ */
+async function auditInstance(
+  instance: InstanceRecord,
+  instancePath: string,
+  db: DbClient,
+  options: AuditOptions,
+): Promise<AuditResult> {
+  const violations: IntegrityViolation[] = [];
+
+  const parent = db.select().from(modules).where(eq(modules.id, instance.parentId)).get();
+  if (!parent) {
+    // The FK makes this unreachable through SQL, so reaching it means the row
+    // was written around the schema. Reported rather than assumed away.
+    return {
+      success: false,
+      moduleId: instance.moduleId,
+      violations,
+      error: `Instance '${instance.moduleId}' names parent '${instance.parentId}', which does not exist.`,
+    };
+  }
+
+  const submodulePath = submoduleSourcePath(parent.sourcePath, instance.submodule);
+  for (const link of await verifyInstanceLinks({ instancePath, submodulePath })) {
+    violations.push({
+      type: 'modified',
+      path: link.entry,
+      message:
+        link.actual === null
+          ? `Link '${link.entry}' is missing or is not a link. It should point at ${link.expected}. Redeploy this instance to rebuild its links.`
+          : `Link '${link.entry}' points at ${link.actual}, not at ${link.expected}. This instance is running source it does not own.`,
+    });
+  }
+
+  // The parent's verdict, carried rather than recomputed. A parent whose
+  // baseline is stale or whose files are modified means every instance under it
+  // is running unverified code, and saying so here is what stops an operator
+  // reading a clean instance row as evidence.
+  const parentResult = await auditModule(instance.parentId, db, options);
+  if (!parentResult.success) {
+    violations.push({
+      type: 'stale-baseline',
+      path: `${instance.parentId}`,
+      message: `The bytes this instance runs belong to '${instance.parentId}', whose own audit is not clean (${parentResult.violations.length} violation(s)${parentResult.error ? `: ${parentResult.error}` : ''}). Fix the parent; this instance cannot be verified independently.`,
+    });
+  }
+
+  return {
+    success: violations.length === 0,
+    moduleId: instance.moduleId,
+    violations,
+    moduleVersion: parent.version,
+    baselineVersion: parentResult.baselineVersion,
+  };
+}

package/src/module/packaging/classify-module-path.test.ts

@@ -102,3 +102,39 @@ describe('classifyModulePath: composes with includeNodeModulesPath', () => {
     expect(classifyModulePath('node_modules/@celilo/cli/index.js')).toBe('unknown');
   });
 });
+
+describe('a submodule tree obeys the same rules as a module tree', () => {
+  // openspec/changes/submodules D1: a submodule declares everything an ordinary
+  // module declares, so it must be CLASSIFIED like one too. Every rule keys on
+  // segments[0], so without the recursion a nested tree gets different answers
+  // than the same file one level up.
+  test('authored source under a submodule is package', () => {
+    expect(classifyModulePath('submodules/runner/manifest.yml')).toBe('package');
+    expect(classifyModulePath('submodules/runner/ansible/site.yml')).toBe('package');
+    expect(classifyModulePath('submodules/runner/scripts/hook.ts')).toBe('package');
+  });
+
+  test("a submodule's e2e tree is excluded, exactly as a module's is", () => {
+    expect(classifyModulePath('e2e/thing.ts')).toBe('unknown');
+    expect(classifyModulePath('submodules/runner/e2e/thing.ts')).toBe('unknown');
+  });
+
+  test("a submodule's derived paths are derived", () => {
+    expect(classifyModulePath('submodules/runner/generated/terraform/x.tfstate')).toBe('derived');
+    expect(classifyModulePath('submodules/runner/celilo/types.d.ts')).toBe('derived');
+    expect(classifyModulePath('submodules/runner/cookies.json')).toBe('derived');
+    expect(classifyModulePath('submodules/runner/screenshots/a.png')).toBe('derived');
+  });
+
+  test('source-tree noise under a submodule is still a finding', () => {
+    expect(classifyModulePath('submodules/runner/.DS_Store')).toBe('unknown');
+    expect(classifyModulePath('submodules/runner/tsconfig.json')).toBe('unknown');
+    expect(classifyModulePath('submodules/runner/a.test.ts')).toBe('unknown');
+  });
+
+  // The directories themselves are shipped bytes and belong in the baseline.
+  test('the submodules directory itself is package', () => {
+    expect(classifyModulePath('submodules')).toBe('package');
+    expect(classifyModulePath('submodules/runner')).toBe('package');
+  });
+});