@cosmicdrift/kumiko-guards 0.378.0 → 0.379.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.378.0",
+  "version": "0.379.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": ">=0.366.0 <1.0.0"
+    "@cosmicdrift/kumiko-framework": "0.379.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.378.0"
+    "@cosmicdrift/kumiko-framework": "0.379.0"
   }
 }

package/src/_lib/guards-doc.ts

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const GUARDS_DOC_REL = "docs/reference/guards.md";
+export const GUARDS_SRC_REL = "packages/guards/src";
+
+const GUARD_FILE_RE = /^(guard|check)-.+\.ts$/;
+const IGNORE_KEY_RE = /kumiko-lint-ignore ([a-z][a-z0-9-]*)/g;
+const FRONT_MATTER_VERIFIED = "2026-10-20";
+
+function headerComment(source: string): string {
+  const lines = source.split("\n").filter((line) => !line.startsWith("#!"));
+  const body: string[] = [];
+  for (const line of lines) {
+    const text = line.trim();
+    if (text === "" && body.length === 0) continue;
+    if (
+      text.startsWith("/**") ||
+      text.startsWith("/*") ||
+      text.startsWith("*") ||
+      text.startsWith("//")
+    ) {
+      body.push(
+        text
+          .replace(/^(\/\*\*?|\*\/|\*|\/\/)\s?/, "")
+          .replace(/\*\/$/, "")
+          .trim(),
+      );
+      if (text.endsWith("*/")) break;
+      continue;
+    }
+    break;
+  }
+  return body.join("\n");
+}
+
+function purposeOf(source: string): string {
+  const paragraph = headerComment(source).split(/\n\s*\n/)[0] ?? "";
+  const flat = paragraph.replace(/\s+/g, " ").trim();
+  const sentenceEnd = flat.search(/\.(\s|$)/);
+  const sentence = sentenceEnd === -1 ? flat : flat.slice(0, sentenceEnd + 1);
+  return sentence.replace(/\|/g, "\\|") || "-";
+}
+
+function ignoreKeysOf(source: string): string[] {
+  return [...new Set([...source.matchAll(IGNORE_KEY_RE)].map((match) => match[1] ?? ""))].sort();
+}
+
+export function guardSourceFiles(frameworkRoot: string): string[] {
+  return readdirSync(join(frameworkRoot, GUARDS_SRC_REL))
+    .filter((file) => GUARD_FILE_RE.test(file))
+    .sort();
+}
+
+export function renderGuardsDoc(frameworkRoot: string): string {
+  const rows = guardSourceFiles(frameworkRoot).map((file) => {
+    const source = readFileSync(join(frameworkRoot, GUARDS_SRC_REL, file), "utf-8");
+    const keys = ignoreKeysOf(source);
+    const suppress =
+      keys.length === 0 ? "-" : keys.map((key) => `\`kumiko-lint-ignore ${key}\``).join(", ");
+    return `| \`${file.replace(/\.ts$/, "")}\` | ${purposeOf(source)} | ${suppress} |`;
+  });
+  return [
+    "---",
+    "status: reference",
+    `verified: ${FRONT_MATTER_VERIFIED}`,
+    `evidence: "generated from ${GUARDS_SRC_REL}/{guard,check}-*.ts by scripts/gen-guards-doc.ts; drift is enforced by the guards-doc-drift check"`,
+    "---",
+    "",
+    "# Guards",
+    "",
+    "Generated, do not edit. Run `bun run gen:guards-doc` after adding or changing a guard.",
+    "Purpose is the first sentence of the guard's header comment; the suppression column lists",
+    "the `kumiko-lint-ignore <key>` markers the guard honors (`-` = not suppressible inline).",
+    "",
+    "| Guard | Purpose | Suppression |",
+    "| --- | --- | --- |",
+    ...rows,
+    "",
+  ].join("\n");
+}
+
+export function writeGuardsDoc(frameworkRoot: string): void {
+  writeFileSync(join(frameworkRoot, GUARDS_DOC_REL), renderGuardsDoc(frameworkRoot), "utf-8");
+}
+
+export function hasGuardsSource(frameworkRoot: string): boolean {
+  return existsSync(join(frameworkRoot, GUARDS_SRC_REL));
+}

package/src/_lib/run-slots.ts

@@ -0,0 +1,181 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_SLOTS = 2;
+const POLL_INTERVAL_MS = 1000;
+const PIDLESS_ORPHAN_AGE_MS = 60_000;
+// Upper bound against pid reuse after SIGKILL/OOM: a reused pid would otherwise hold the slot forever.
+const MAX_SLOT_AGE_MS = 15 * 60_000;
+const PID_FILE = "pid";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+export type GuardRunSlotOptions = {
+  readonly slotsDir?: string;
+  readonly environment?: Environment;
+  readonly pid?: number;
+  readonly isPidAlive?: (pid: number) => boolean;
+  readonly sleep?: (ms: number) => void;
+  readonly now?: () => number;
+  readonly log?: (line: string) => void;
+  // Test seam: real process hooks would intercept signals of the test runner.
+  readonly installProcessHooks?: boolean;
+};
+
+// 0 = unlimited. CI runners are isolated, so slots only matter on a shared dev machine.
+export function resolveGuardSlotCount(environment: Environment): number {
+  const ci = environment["CI"];
+  if (ci !== undefined && ci !== "") return 0;
+  const raw = environment["KUMIKO_GUARD_SLOTS"];
+  if (raw === undefined || !/^\d+$/.test(raw)) return DEFAULT_SLOTS;
+  return Number(raw);
+}
+
+function defaultIsPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+}
+
+// Sync on purpose: runGuardsCli is sync and shared by the fw entry, the guards CLI and `kumiko check`.
+function defaultSleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function readSlotPid(slotPath: string): number | undefined {
+  try {
+    const parsed = Number(readFileSync(join(slotPath, PID_FILE), "utf8").trim());
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isOrphanedSlot(
+  slotPath: string,
+  isPidAlive: (pid: number) => boolean,
+  nowMs: number,
+): boolean {
+  let ageMs: number;
+  try {
+    ageMs = nowMs - statSync(slotPath).mtimeMs;
+  } catch {
+    return false;
+  }
+  if (ageMs > MAX_SLOT_AGE_MS) return true;
+  const ownerPid = readSlotPid(slotPath);
+  if (ownerPid !== undefined) return !isPidAlive(ownerPid);
+  // No pid file: the owner is either between mkdir and writeFile or died in that gap.
+  return ageMs > PIDLESS_ORPHAN_AGE_MS;
+}
+
+function errorCode(error: unknown): string {
+  return error instanceof Error && "code" in error && typeof error.code === "string"
+    ? error.code
+    : "unknown";
+}
+
+function tryClaimSlot(slotPath: string, pid: number): boolean {
+  try {
+    mkdirSync(slotPath);
+  } catch (error) {
+    if (errorCode(error) === "EEXIST") return false;
+    throw error;
+  }
+  writeFileSync(join(slotPath, PID_FILE), String(pid));
+  return true;
+}
+
+// ponytail: two waiters judging the same orphan at once can let the slower one move the faster
+// one's fresh claim aside, so N+1 runs overlap once. Acceptable for a memory throttle; a per-slot
+// generation token would close it if it ever matters.
+function removeOrphan(slotPath: string, pid: number): void {
+  // rename is atomic, so of several waiters only one deletes the orphan; mkdir stays the decider.
+  const graveyard = `${slotPath}.orphan-${pid}-${Math.random().toString(36).slice(2)}`;
+  try {
+    renameSync(slotPath, graveyard);
+  } catch {
+    // skip: another waiter already moved the orphan away
+    return;
+  }
+  rmSync(graveyard, { recursive: true, force: true });
+}
+
+function createRelease(slotPath: string, pid: number, hooks: boolean): () => void {
+  let released = false;
+  const release = (): void => {
+    // skip: finally and the exit hook both call release
+    if (released) return;
+    released = true;
+    if (hooks) {
+      process.off("exit", release);
+    }
+    // A taken-over slot belongs to someone else by now; never delete theirs.
+    if (readSlotPid(slotPath) === pid) rmSync(slotPath, { recursive: true, force: true });
+  };
+  // No signal handlers: they would suppress default termination, and a signal death is
+  // reclaimed by the next run through the dead pid.
+  if (hooks) {
+    process.on("exit", release);
+  }
+  return release;
+}
+
+function claimFreeSlot(
+  slotsDir: string,
+  slotCount: number,
+  pid: number,
+  isPidAlive: (pid: number) => boolean,
+  now: () => number,
+): string | undefined {
+  for (let index = 0; index < slotCount; index++) {
+    const slotPath = join(slotsDir, `slot-${index}`);
+    if (tryClaimSlot(slotPath, pid)) return slotPath;
+    if (!isOrphanedSlot(slotPath, isPidAlive, now())) continue;
+    removeOrphan(slotPath, pid);
+    if (tryClaimSlot(slotPath, pid)) return slotPath;
+  }
+  return undefined;
+}
+
+// Fixed path, not os.tmpdir(): sandboxed sessions may have a different TMPDIR and would not share slots.
+function defaultSlotsDir(): string {
+  const uid = process.getuid?.();
+  return uid === undefined ? "/tmp/kumiko-guard-slots" : `/tmp/kumiko-guard-slots-${uid}`;
+}
+
+export function acquireGuardRunSlot(options: GuardRunSlotOptions = {}): () => void {
+  const slotCount = resolveGuardSlotCount(options.environment ?? process.env);
+  if (slotCount === 0) return () => {};
+
+  const slotsDir = options.slotsDir ?? defaultSlotsDir();
+  const pid = options.pid ?? process.pid;
+  const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const log = options.log ?? ((line: string) => console.error(line));
+  const hooks = options.installProcessHooks ?? true;
+
+  let announced = false;
+  for (;;) {
+    let slotPath: string | undefined;
+    try {
+      mkdirSync(slotsDir, { recursive: true });
+      slotPath = claimFreeSlot(slotsDir, slotCount, pid, isPidAlive, now);
+    } catch (error) {
+      // A throttle must never block the push: fail open.
+      log(`→ guard slots unavailable (${errorCode(error)}), running without limit`);
+      return () => {};
+    }
+    if (slotPath !== undefined) return createRelease(slotPath, pid, hooks);
+    if (!announced) {
+      announced = true;
+      log(`→ waiting for a free guard slot (${slotCount} in use)`);
+    }
+    sleep(POLL_INTERVAL_MS);
+  }
+}

package/src/changes.json

@@ -1,4 +1,35 @@
 [
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "App-feature-structure guard flags runtime-client markers",
+    "detail": "The guard reports a runtime-client marker in a feature file, outside web/ as client code in the server tree and inside web/ as redundant. dev/ is classified as the dev runtime by path."
+  },
+  {
+    "version": "0.379.0",
+    "type": "fix",
+    "title": "Direct-entity-writes guard catches external and projection event-store tables",
+    "detail": "Published packages list their event-store tables in kumiko-es-tables.json, which the guard checks for staleness in the owning repo and reads in consumers. r.projection tables are now guarded as well. Existing consumers can get new findings that were previously hidden."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Guard runs queue for a free local slot",
+    "detail": "At most two full guard runs per machine run at the same time (KUMIKO_GUARD_SLOTS, default 2, 0 disables, unset in CI). Further runs print a waiting line and start when a slot frees up; slots of crashed runs are taken over automatically."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "direct-fetch guard uses kumiko-lint-ignore",
+    "detail": "The guard-allow direct-fetch marker is no longer parsed. The guard now honors kumiko-lint-ignore direct-fetch with a specific reason, like the other guards.",
+    "migration": "Replace guard-allow direct-fetch comments with kumiko-lint-ignore direct-fetch followed by the reason."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Subpath-exports and guards-doc-drift checks",
+    "detail": "The subpath-exports check fails when a published package ships src/<feature>/web.ts without the matching exports key. The guards-doc-drift check keeps docs/reference/guards.md in sync with the guard sources, and a registry test fails when a guard file is not registered."
+  },
   {
     "version": "0.378.0",
     "type": "fix",

package/src/check-subpath-exports.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env bun
+/**
+ * A published package that ships `src/<feature>/web.ts` must list `./<feature>/web` in its
+ * package.json `exports`; otherwise every standalone app build fails with "Could not resolve".
+ * Only "web" is checked: seeding/testing/constants subpaths are often internal on purpose.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+
+const SUBPATH_NAMES = ["web"] as const;
+
+function readPublishedExportKeys(pkgDir: string): ReadonlySet<string> | undefined {
+  const pkgJsonPath = join(pkgDir, "package.json");
+  if (!existsSync(pkgJsonPath)) return undefined;
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+  } catch (error) {
+    throw new Error(`${pkgJsonPath}: invalid JSON`, { cause: error });
+  }
+  // Without publishConfig.registry the package is never shipped, so subpath drift does not apply.
+  const registry = propertyOf(propertyOf(manifest, "publishConfig"), "registry");
+  if (typeof registry !== "string") return undefined;
+  const exportsMap = propertyOf(manifest, "exports");
+  return new Set(isPlainObject(exportsMap) ? Object.keys(exportsMap) : []);
+}
+
+export const check: RepoCheck = {
+  name: "Subpath Exports",
+  hint:
+    "Add the missing subpath key to the package.json `exports` field, otherwise every " +
+    'standalone app build fails with "Could not resolve" on that import.',
+  run(roots: readonly RepoRoot[]) {
+    const violations: { file: string; line: number; message: string }[] = [];
+    let matchedFiles = 0;
+    for (const root of roots) {
+      const packagesDir = join(root.absPath, "packages");
+      if (!existsSync(packagesDir)) continue;
+      for (const entry of readdirSync(packagesDir)) {
+        const pkgDir = join(packagesDir, entry);
+        if (!statSync(pkgDir).isDirectory()) continue;
+        const exportKeys = readPublishedExportKeys(pkgDir);
+        const srcDir = join(pkgDir, "src");
+        if (exportKeys === undefined || !existsSync(srcDir)) continue;
+        matchedFiles++;
+        for (const feature of readdirSync(srcDir)) {
+          if (feature.startsWith("_")) continue;
+          // An unpublished feature folder needs no subpath exports either.
+          if (!statSync(join(srcDir, feature)).isDirectory()) continue;
+          if (!exportKeys.has(`./${feature}`)) continue;
+          for (const sub of SUBPATH_NAMES) {
+            const file = `packages/${entry}/src/${feature}/${sub}.ts`;
+            if (!existsSync(join(root.absPath, file)) || exportKeys.has(`./${feature}/${sub}`)) {
+              continue;
+            }
+            violations.push({
+              file,
+              line: 1,
+              message: `"./${feature}/${sub}" is missing in packages/${entry}/package.json exports`,
+            });
+          }
+        }
+      }
+    }
+    return { violations, matchedFiles, notApplicable: matchedFiles === 0 };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check], resolveRepoRoots()));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-app-feature-structure.ts

@@ -1,11 +1,14 @@
 #!/usr/bin/env bun
 // App features follow the bundled-features convention (reference: tenant/):
 // feature.ts = registration only, screens under web/, handlers under handlers/.
-// This guard flags the three most expensive deviations:
+// A feature file's runtime follows from its path (web/** is client, the rest is server or
+// isomorphic), so a runtime-client marker is never needed: outside web/ it hides client code
+// in the server tree, inside web/ it is redundant. This guard flags the four most expensive deviations:
 //   1. web.tsx/web.ts monolith or JSX screens directly at the feature root
 //   2. feature.ts as a logic dump (> MAX_FEATURE_TS_LINES lines)
 //   3. r.screen({ type: "custom" }) without an allowlist tag — declarative
 //      screen types (entityList/dashboard/data-table) are the default.
+//   4. a runtime-client marker instead of the web/ path.
 //
 // ponytail: the handler file convention (*.query.ts/*.write.ts under handlers/)
 // is not enforced yet — add it once the registration API shapes are
@@ -17,6 +20,7 @@ import * as path from "node:path";
 import { type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, type GuardViolation, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 import { hasIgnoreTag } from "./_lib/ignore-tag";
+import { directiveInHead } from "./runtime-isolation-classify";
 
 const SCAN: ScanSpec = {
   scope: "source",
@@ -111,6 +115,27 @@ function checkCustomScreens(sf: SourceFile, violations: GuardViolation[]): void
   }
 }
 
+const DIRECTIVE_HEAD_CHARS = 600;
+const FEATURE_RELATIVE_PATH = /(?:src\/features|packages\/bundled-features\/src)\/[^/]+\/(.+)$/;
+
+// 4. runtime-client marker instead of the path
+function clientMarkerViolation(sf: SourceFile): GuardViolation | undefined {
+  const filePath = sf.getFilePath();
+  const featureRelative = FEATURE_RELATIVE_PATH.exec(filePath)?.[1];
+  const hasClientMarker =
+    featureRelative !== undefined &&
+    directiveInHead(sf.getFullText().slice(0, DIRECTIVE_HEAD_CHARS)) === "client";
+  if (!hasClientMarker || isIgnoredFile(sf)) return undefined;
+  const underWeb = featureRelative.startsWith("web/") || /^web\.tsx?$/.test(featureRelative);
+  return {
+    file: filePath,
+    line: 1,
+    message: underWeb
+      ? "redundant @runtime client marker — files under web/ are client by path"
+      : "client code outside web/ — move it under web/ (bun kumiko codemod feature-layout . --write)",
+  };
+}
+
 export const guard: AstGuard = {
   name: "App-Feature-Structure Guard (App-Repos)",
   scan: SCAN,
@@ -127,6 +152,8 @@ export const guard: AstGuard = {
       checkRootJsx(sf, base, violations);
       checkFeatureTsSize(sf, base, violations);
       checkCustomScreens(sf, violations);
+      const markerViolation = clientMarkerViolation(sf);
+      if (markerViolation !== undefined) violations.push(markerViolation);
     }
     return { violations };
   },

package/src/guard-direct-entity-writes.ts

@@ -18,6 +18,11 @@
  *         (dash vs. underscore) but share the `ent` symbol. Plus an explicit
  *         `backingTable` override. Tables that are NOT statically resolvable
  *         are skipped (a miss is preferable to a false block).
+ *      c) Tables of external packages (node_modules, workspace links), read from the
+ *         `kumiko-es-tables.json` catalog each published package ships; a package whose
+ *         sources live in the checked repo must keep that catalog current (checked here,
+ *         rewritten with `--write-baseline --guard=<name>`).
+ *      d) `r.projection({ table })` tables: event-fed read models, only the apply may write.
  *
  *   2. **Find direct writes.** Two forms:
  *      - Method form `<receiver>.insert(<tableIdent>)` / `.update` / `.delete`.
@@ -46,13 +51,21 @@
 import * as path from "node:path";
 import {
   type CallExpression,
+  type FileSystemHost,
   type Identifier,
   Node,
   type ObjectLiteralExpression,
+  type Project,
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
-import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  isExternalSourcePath,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
 
 const ROOT = process.cwd();
 
@@ -95,46 +108,6 @@ const FN_WRITE_HELPERS = new Map<string, "insert" | "update" | "delete">([
   ["deleteManyBatched", "delete"],
 ]);
 
-// Writes that are deliberately outside the event-store executor. Match on file + enclosing function + table so the exception cannot widen silently.
-type DirectWriteException = {
-  readonly file: RegExp;
-  readonly functionName: string;
-  readonly table: string;
-  readonly justification: string;
-};
-
-const DIRECT_WRITE_EXCEPTIONS: readonly DirectWriteException[] = [
-  {
-    file: /(^|\/)packages\/bundled-features\/src\/template-resolver\/seeding\.ts$/,
-    functionName: "resolveExistingForEventStoreSeed",
-    table: "templateResourcesTable",
-    justification: "Orphan projection row without events, no event-store verb possible",
-  },
-];
-
-// First named container: `function f`, `const f = () =>`, or `run: () =>` in an object literal.
-function enclosingFunctionName(node: Node): string | undefined {
-  for (const ancestor of node.getAncestors()) {
-    if (Node.isFunctionDeclaration(ancestor)) return ancestor.getName();
-    if (Node.isVariableDeclaration(ancestor) || Node.isPropertyAssignment(ancestor)) {
-      return ancestor.getName();
-    }
-  }
-  return undefined;
-}
-
-function isDirectWriteException(call: CallExpression, table: string): boolean {
-  const functionName = enclosingFunctionName(call);
-  if (functionName === undefined) return false;
-  const file = call.getSourceFile().getFilePath();
-  return DIRECT_WRITE_EXCEPTIONS.some(
-    (exception) =>
-      exception.file.test(file) &&
-      exception.functionName === functionName &&
-      exception.table === table,
-  );
-}
-
 // `table as EntityTableMeta`, `(table)`, `table!`, `<T>table`, `table satisfies T` all name the same table.
 export function unwrapTableExpression(node: Node): Node {
   let current = node;
@@ -288,6 +261,39 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
   return tables;
 }
 
+const PROJECTION_METHOD_ACCESS = /\.\s*projection\b/;
+
+// The `table` of `r.projection({ table, apply })`: an event-fed read model, so only its apply
+// (tx receiver) may write it. Shorthand `{ table }` is a name-only reference to the same symbol.
+export function collectProjectionTables(files: readonly SourceFile[]): Set<TableId> {
+  const tables = new Set<TableId>();
+  for (const sf of files) {
+    if (!PROJECTION_METHOD_ACCESS.test(sf.getFullText())) continue;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      const callee = call.getExpression().asKind(SyntaxKind.PropertyAccessExpression);
+      if (callee?.getName() !== "projection") continue;
+      const definition = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+      const property = definition?.getProperty("table");
+      const identifier =
+        property?.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getNameNode() ??
+        unwrapTableExpression(
+          property?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer() ?? call,
+        ).asKind(SyntaxKind.Identifier);
+      const did = identifier && declIdOf(identifier);
+      if (did) tables.add(did);
+    }
+  }
+  return tables;
+}
+
+function collectScopeEsTables(files: readonly SourceFile[]): Set<TableId> {
+  return new Set<TableId>([
+    ...collectEsTables(files),
+    ...collectEntityProjectionTables(files),
+    ...collectProjectionTables(files),
+  ]);
+}
+
 type Violation = {
   file: string;
   line: number;
@@ -456,9 +462,218 @@ function importedBindingNames(sf: SourceFile): Set<string> {
   return names;
 }
 
+const ES_TABLE_CATALOG_FILE = "kumiko-es-tables.json";
+
+type CatalogEntry = { readonly module: string; readonly export: string };
+
+function tableIdFilePath(tableId: TableId): string {
+  return tableId.slice(0, tableId.lastIndexOf("::"));
+}
+
+function tableIdName(tableId: TableId): string {
+  return tableId.slice(tableId.lastIndexOf("::") + 2);
+}
+
+function packageRootOf(host: FileSystemHost, filePath: string): string | undefined {
+  let dir = path.dirname(filePath);
+  while (dir !== path.dirname(dir)) {
+    if (host.fileExistsSync(path.join(dir, "package.json"))) return dir;
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+// Source (`src/x.ts`, workspace link) and published (`dist/x.d.ts`) layouts must yield one key.
+function moduleOf(packageRoot: string, filePath: string): string {
+  return path
+    .relative(packageRoot, filePath)
+    .split(path.sep)
+    .join("/")
+    .replace(/^(src|dist)\//, "")
+    .replace(/\.d\.ts$|\.(ts|tsx|js)$/, "");
+}
+
+function catalogKey(module: string, exportName: string): string {
+  return `${module}::${exportName}`;
+}
+
+function isCatalogEntry(value: unknown): value is CatalogEntry {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "module" in value &&
+    "export" in value &&
+    typeof value.module === "string" &&
+    typeof value.export === "string"
+  );
+}
+
+function parseCatalog(text: string): CatalogEntry[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return Array.isArray(parsed) && parsed.every(isCatalogEntry) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readCatalogKeys(host: FileSystemHost, packageRoot: string): Set<string> {
+  const catalogPath = path.join(packageRoot, ES_TABLE_CATALOG_FILE);
+  if (!host.fileExistsSync(catalogPath)) return new Set();
+  const entries = parseCatalog(host.readFileSync(catalogPath)) ?? [];
+  return new Set(entries.map((entry) => catalogKey(entry.module, entry.export)));
+}
+
+export type ExternalEsTables = { has(tableId: TableId): boolean };
+
+// A published package ships `kumiko-es-tables.json` (module + export of its ES tables), because
+// its sources are not on disk in a consumer (only dist/*.d.ts). Missing catalog: no ES tables.
+export function createExternalEsTables(project: Project): ExternalEsTables {
+  const host = project.getFileSystem();
+  const keysByPackageRoot = new Map<string, ReadonlySet<string>>();
+  return {
+    has(tableId) {
+      const filePath = tableIdFilePath(tableId);
+      const root = packageRootOf(host, filePath);
+      if (root === undefined) return false;
+      let keys = keysByPackageRoot.get(root);
+      if (!keys) {
+        keys = readCatalogKeys(host, root);
+        keysByPackageRoot.set(root, keys);
+      }
+      return keys.has(catalogKey(moduleOf(root, filePath), tableIdName(tableId)));
+    },
+  };
+}
+
+function isPublishedPackage(host: FileSystemHost, packageRoot: string): boolean {
+  try {
+    const manifest: unknown = JSON.parse(host.readFileSync(path.join(packageRoot, "package.json")));
+    return !(
+      typeof manifest === "object" &&
+      manifest !== null &&
+      "private" in manifest &&
+      manifest.private === true
+    );
+  } catch {
+    return false;
+  }
+}
+
+// Owner side: the exported scope ES tables of every published package, grouped by package root.
+function deriveCatalogs(
+  files: readonly SourceFile[],
+  esTables: ReadonlySet<TableId>,
+): Map<string, CatalogEntry[]> {
+  const catalogs = new Map<string, CatalogEntry[]>();
+  const firstFile = files[0];
+  if (!firstFile) return catalogs;
+  const project = firstFile.getProject();
+  const host = project.getFileSystem();
+  const scopePaths = new Set<string>(files.map((file) => file.getFilePath()));
+  const publishedByRoot = new Map<string, boolean>();
+  for (const tableId of esTables) {
+    const filePath = tableIdFilePath(tableId);
+    if (!scopePaths.has(filePath) || EXCLUDE.test(filePath)) continue;
+    const name = tableIdName(tableId);
+    if (!project.getSourceFile(filePath)?.getVariableDeclaration(name)?.isExported()) continue;
+    const root = packageRootOf(host, filePath);
+    if (root === undefined) continue;
+    let published = publishedByRoot.get(root);
+    if (published === undefined) {
+      published = isPublishedPackage(host, root);
+      publishedByRoot.set(root, published);
+    }
+    if (!published) continue;
+    const entries = catalogs.get(root) ?? [];
+    entries.push({ module: moduleOf(root, filePath), export: name });
+    catalogs.set(root, entries);
+  }
+  for (const [root, entries] of catalogs) {
+    entries.sort(
+      (a, b) => a.module.localeCompare(b.module, "en") || a.export.localeCompare(b.export, "en"),
+    );
+    catalogs.set(root, [
+      ...new Map(entries.map((e) => [catalogKey(e.module, e.export), e])).values(),
+    ]);
+  }
+  return catalogs;
+}
+
+const REWRITE_CATALOGS_COMMAND =
+  'bun packages/guards/src/run-guards.ts --write-baseline --guard="Direct-Entity-Writes Guard"';
+
+// Published packages whose catalog exists on disk although they define no ES table any more.
+function publishedRootsWithCatalog(files: readonly SourceFile[]): Set<string> {
+  const roots = new Set<string>();
+  const firstFile = files[0];
+  if (!firstFile) return roots;
+  const host = firstFile.getProject().getFileSystem();
+  const rootByDir = new Map<string, string | undefined>();
+  for (const sf of files) {
+    const dir = path.dirname(sf.getFilePath());
+    if (!rootByDir.has(dir)) rootByDir.set(dir, packageRootOf(host, dir));
+    const root = rootByDir.get(dir);
+    if (root !== undefined && host.fileExistsSync(path.join(root, ES_TABLE_CATALOG_FILE))) {
+      roots.add(root);
+    }
+  }
+  return roots;
+}
+
+function catalogViolations(
+  files: readonly SourceFile[],
+  esTables: ReadonlySet<TableId>,
+): { file: string; line: number; message: string; neverFrozen: boolean }[] {
+  const firstFile = files[0];
+  if (!firstFile) return [];
+  const host = firstFile.getProject().getFileSystem();
+  const expected = deriveCatalogs(files, esTables);
+  const roots = new Set([...expected.keys(), ...publishedRootsWithCatalog(files)]);
+  const violations: { file: string; line: number; message: string; neverFrozen: boolean }[] = [];
+  for (const root of roots) {
+    const wanted = new Set((expected.get(root) ?? []).map((e) => catalogKey(e.module, e.export)));
+    const actual = readCatalogKeys(host, root);
+    const missing = [...wanted].filter((key) => !actual.has(key));
+    const surplus = [...actual].filter((key) => !wanted.has(key));
+    if (missing.length === 0 && surplus.length === 0) continue;
+    const catalogPath = path.join(root, ES_TABLE_CATALOG_FILE);
+    const detail = [
+      missing.length > 0 ? `missing: ${missing.join(", ")}` : "",
+      surplus.length > 0 ? `surplus: ${surplus.join(", ")}` : "",
+    ]
+      .filter(Boolean)
+      .join("; ");
+    violations.push({
+      file: path.relative(ROOT, catalogPath),
+      line: 0,
+      message: `ES table catalog out of date (${detail}). Rewrite it: ${REWRITE_CATALOGS_COMMAND}`,
+      neverFrozen: true,
+    });
+  }
+  return violations;
+}
+
+function writeCatalogs(files: readonly SourceFile[], esTables: ReadonlySet<TableId>): void {
+  const firstFile = files[0];
+  if (!firstFile) throw new Error("No scanned files: refusing to rewrite ES table catalogs");
+  const host = firstFile.getProject().getFileSystem();
+  const expected = deriveCatalogs(files, esTables);
+  for (const root of publishedRootsWithCatalog(files)) {
+    if (!expected.has(root)) host.deleteSync(path.join(root, ES_TABLE_CATALOG_FILE));
+  }
+  for (const [root, entries] of expected) {
+    host.writeFileSync(
+      path.join(root, ES_TABLE_CATALOG_FILE),
+      `${JSON.stringify(entries, null, 2)}\n`,
+    );
+  }
+}
+
 export function scanDirectWrites(
   sf: SourceFile,
   esTables: ReadonlySet<TableId>,
+  externalEsTables: ExternalEsTables = createExternalEsTables(sf.getProject()),
 ): Omit<Violation, "file">[] {
   const out: Omit<Violation, "file">[] = [];
   // Superset of every name a write may use for an ES table: definition names plus import bindings.
@@ -478,8 +693,10 @@ export function scanDirectWrites(
     const receiverName = receiver.getText();
 
     const did = declIdOf(w.tableArg);
-    if (!did || !esTables.has(did)) continue;
-    if (isDirectWriteException(call, w.tableArg.getText())) continue;
+    if (!did) continue;
+    if (!esTables.has(did)) {
+      if (!isExternalSourcePath(tableIdFilePath(did)) || !externalEsTables.has(did)) continue;
+    }
 
     if (TX_RECEIVER_NAMES.has(receiverName)) {
       // A tx receiver is only legitimate when the write actually sits
@@ -518,14 +735,9 @@ export const guard: AstGuard = {
     "Write ES-entity tables through the entity write handlers / event-store executor or inside an r.projection apply (tx receiver); a direct insert/update/delete lets the projection row drift from the event stream. " +
     "For a BLOCKED scan, check that the scan still covers the files declaring r.entity / createEventStoreExecutor.",
   run(files) {
-    // Merge both collections BEFORE the empty-set check — otherwise a repo
-    // that only uses r.entity (no createEventStoreExecutor anymore) would
-    // skip every scan: the canary violation fires falsely, and writes on
-    // entity tables go undetected.
-    const esTables = new Set<TableId>([
-      ...collectEsTables(files),
-      ...collectEntityProjectionTables(files),
-    ]);
+    // Merge all collections BEFORE the empty-set check — otherwise a repo that only uses r.entity
+    // would skip every scan: the canary fires falsely and writes on entity tables go undetected.
+    const esTables = collectScopeEsTables(files);
     if (esTables.size === 0) {
       // An empty set means either the repo has no event store at all, or the
       // scan lost the ES definitions while table writes are still present.
@@ -542,13 +754,23 @@ export const guard: AstGuard = {
       };
     }
 
-    const violations: Array<{ file: string; line: number; message: string }> = [];
+    const violations: Array<{
+      file: string;
+      line: number;
+      message: string;
+      neverFrozen?: boolean;
+    }> = catalogViolations(files, esTables);
+
+    const firstFile = files[0];
+    const externalEsTables = firstFile
+      ? createExternalEsTables(firstFile.getProject())
+      : { has: () => false };
 
     for (const sf of files) {
       const file = sf.getFilePath();
       if (EXCLUDE.test(file)) continue;
 
-      for (const hit of scanDirectWrites(sf, esTables)) {
+      for (const hit of scanDirectWrites(sf, esTables, externalEsTables)) {
         violations.push({
           file: path.relative(ROOT, file),
           line: hit.line,
@@ -559,6 +781,9 @@ export const guard: AstGuard = {
 
     return { violations };
   },
+  writeBaseline(files) {
+    writeCatalogs(files, collectScopeEsTables(files));
+  },
 };
 
 // Run only when invoked as a script — tests import the helpers without

package/src/guard-direct-fetch.ts

@@ -31,6 +31,7 @@ import {
   runStandalone,
   type ScanSpec,
 } from "./_lib/guard-kit";
+import { lineHasIgnoreTag } from "./_lib/ignore-tag";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 
 const SCAN: ScanSpec = {
@@ -48,7 +49,9 @@ const EXCLUDE =
 
 // packages/framework/src/http/egress.ts IS the egress() implementation.
 const ALLOWLIST = [/^kumiko-framework\/packages\/framework\/src\/http\/egress\.ts$/];
-const ALLOW_MARKER = "guard-allow: same-origin fetch";
+const IGNORE_TAG = "kumiko-lint-ignore direct-fetch";
+const IGNORE_TAG_WITH_REASON_RE =
+  /kumiko-lint-ignore\s+(?:[\w-]+,)*direct-fetch(?:,[\w-]+)*(?=\s|$)(.*)$/;
 
 interface Violation {
   line: number;
@@ -61,14 +64,12 @@ const GLOBAL_FETCH_RECEIVERS = new Set(["globalThis", "window"]);
 
 // The marker is a per-line skip for a security guard, so it only counts with a
 // non-generic reason after it — a bare marker still reports the finding.
-function hasAllowMarkerWithReason(sf: SourceFile, line: number): boolean {
+function hasIgnoreTagWithReason(sf: SourceFile, line: number): boolean {
   const lines = sf.getFullText().split("\n");
   const idx = line - 1;
   return [lines[idx] ?? "", lines[idx - 1] ?? ""].some((text) => {
-    const markerAt = text.indexOf(ALLOW_MARKER);
-    if (markerAt < 0) return false;
-    const reason = text
-      .slice(markerAt + ALLOW_MARKER.length)
+    if (!lineHasIgnoreTag(text, IGNORE_TAG)) return false;
+    const reason = (IGNORE_TAG_WITH_REASON_RE.exec(text)?.[1] ?? "")
       .replace(/^\s*(?:—|–|-|:)\s*/, "")
       .trim();
     return !isGenericReason(reason);
@@ -127,7 +128,7 @@ export const guard: AstGuard = {
   security: true,
   hint:
     "Replace raw fetch(...) with egress(policy)(...) from @cosmicdrift/kumiko-framework/http (framework#2147). " +
-    'Same-origin path literal (`"/api/..."`) is allowed; otherwise put `// guard-allow: same-origin fetch — <specific reason>` on the line above (a bare marker does not count). ' +
+    'Same-origin path literal (`"/api/..."`) is allowed; otherwise put `// kumiko-lint-ignore direct-fetch <specific reason>` on the line above (a bare marker does not count). ' +
     "Local bindings named fetch are flagged (false positive — unblock via that marker). " +
     'Known gap: bracket access (globalThis["fetch"](...)).',
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
@@ -142,7 +143,7 @@ export const guard: AstGuard = {
         root === undefined ? undefined : `${root.name}/${pathRelative(root.absPath, file)}`;
       if (key !== undefined && isAllowlisted(key, ALLOWLIST)) continue;
       for (const v of findRawFetchCalls(sf)) {
-        if (hasAllowMarkerWithReason(sf, v.line)) continue;
+        if (hasIgnoreTagWithReason(sf, v.line)) continue;
         violations.push({
           // cwd-relative, not repo-relative `rel` — the security baseline
           // needs an unambiguous path to resolve back to (repo, relPath).

package/src/guard-guards-doc-drift.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+/**
+ * Fails when docs/reference/guards.md differs from what the generator renders from the guard sources.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import {
+  GUARDS_DOC_REL,
+  GUARDS_SRC_REL,
+  hasGuardsSource,
+  renderGuardsDoc,
+} from "./_lib/guards-doc";
+
+const REGENERATE_HINT = "run `bun run gen:guards-doc` and commit the result";
+
+export const check: RepoCheck = {
+  name: "guards-doc-drift",
+  hint: "Run `bun run gen:guards-doc` and commit docs/reference/guards.md.",
+  run(roots) {
+    const frameworkRoots = roots.filter((root) => hasGuardsSource(root.absPath));
+    const violations: { file: string; line: number; message: string }[] = [];
+    for (const root of frameworkRoots) {
+      const docPath = join(root.absPath, GUARDS_DOC_REL);
+      const expected = renderGuardsDoc(root.absPath);
+      if (!existsSync(docPath)) {
+        violations.push({ file: GUARDS_DOC_REL, line: 1, message: `missing; ${REGENERATE_HINT}` });
+      } else if (readFileSync(docPath, "utf-8") !== expected) {
+        violations.push({
+          file: GUARDS_DOC_REL,
+          line: 1,
+          message: `differs from the generated output (sources in ${GUARDS_SRC_REL}); ${REGENERATE_HINT}`,
+        });
+      }
+    }
+    return {
+      violations,
+      matchedFiles: frameworkRoots.length,
+      notApplicable: frameworkRoots.length === 0,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-restricted-symbols.ts

@@ -42,6 +42,10 @@ const RESTRICTED_SYMBOLS = new Set([
   // an audited unsafeRaw escape hatch, so new callers need an explicit allowlist entry.
   "appendEventInTenantDb",
   "getStreamVersionInTenantDb",
+  // Grants the ES-write capability on the tenant being destroyed; only the destroy stage and its definition may use it.
+  "createTenantDataDestroyDb",
+  // Test seam that writes event-fed tables without events; runtime code importing it would be a back door.
+  "withExecutorManagedWritesForTests",
 ]);
 
 const ALLOWLIST = [
@@ -50,6 +54,10 @@ const ALLOWLIST = [
   /^packages\/framework\/src\/event-store\/tenant-db-append\.ts$/,
   /^packages\/bundled-features\/src\/cap-counter\/cap-reservation\.ts$/,
   /^packages\/bundled-features\/src\/user-data-rights-defaults\/hooks\/delivery-attempt\.userdata-hook\.ts$/,
+  /^packages\/framework\/src\/db\/tenant-db\.ts$/,
+  /^packages\/framework\/src\/db\/index\.ts$/,
+  /^packages\/bundled-features\/src\/tenant-lifecycle\/stages\.ts$/,
+  /^packages\/testing\/src\/helpers\/(seed|db-cleanup)\.ts$/,
   /^packages\/bundled-features\/src\/tenant\/seeding\.ts$/,
   /^packages\/bundled-features\/src\/tier-engine\/feature\.ts$/,
 ];
@@ -121,7 +129,7 @@ function findRestrictedSymbolReferences(sf: SourceFile): Violation[] {
 export const guard: AstGuard = {
   name: "Restricted-Symbols Guard",
   scan: SCAN,
-  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.appendEvent — only framework-internal coordination code may use them. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
+  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.appendEvent — only framework-internal coordination code may use them. createTenantDataDestroyDb grants direct writes on event-fed tables and belongs to the tenant-destroy stage only. withExecutorManagedWritesForTests is the test-seed seam behind seedRow/deleteRows and must not reach runtime code. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
   run(files, roots = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/index.ts

@@ -21,6 +21,7 @@ export {
   type ScanSpec,
   type SuiteInventory,
 } from "./_lib/guard-kit";
+export { GUARDS_DOC_REL, renderGuardsDoc, writeGuardsDoc } from "./_lib/guards-doc";
 export { findLocalRepo, type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 export { type RootScan, type ScanOptions, scanFiles, scanRoots } from "./_lib/scan-scope";
 export {

package/src/run-guards.ts

@@ -18,6 +18,7 @@ import {
   runGuards,
 } from "./_lib/guard-kit";
 import type { RepoRoot } from "./_lib/roots";
+import { acquireGuardRunSlot } from "./_lib/run-slots";
 import { writeSecurityBaselines } from "./_lib/security-baseline-cli";
 import { guard as asCasts } from "./check-as-casts";
 import { guard as complexity } from "./check-complexity";
@@ -176,9 +177,15 @@ export function runGuardsCli(argv: readonly string[], deps: RunGuardsCliDeps = {
   }
   const strictSecurityBaseline = flags.includes("--strict-security-baseline");
   const guards = strictSecurityBaseline ? GUARDS.filter(isSecurityGuard) : GUARDS;
-  const project = buildSharedProject(guards);
-  printGuardKitBanner(guards.length, project);
-  return reportResults(runGuards(guards, project, { strictSecurityBaseline }));
+  // Taken before the ts-morph project is built: that is where the memory goes.
+  const releaseSlot = acquireGuardRunSlot();
+  try {
+    const project = buildSharedProject(guards);
+    printGuardKitBanner(guards.length, project);
+    return reportResults(runGuards(guards, project, { strictSecurityBaseline }));
+  } finally {
+    releaseSlot();
+  }
 }
 
 // Only run on direct invocation — otherwise `import { GUARDS }` would kick

package/src/run-repo-checks.ts

@@ -7,8 +7,10 @@ import { check as realProviderIsolation } from "./check-real-provider-isolation"
 import { check as runtimeIsolation } from "./check-runtime-isolation";
 import { check as secretLiterals } from "./check-secret-literals";
 import { check as singleRuntimeInstance } from "./check-single-runtime-instance";
+import { check as subpathExports } from "./check-subpath-exports";
 import { check as agentDocsDrift } from "./guard-agent-docs-drift";
 import { check as featureIntegrationTests } from "./guard-feature-integration-tests";
+import { check as guardsDocDrift } from "./guard-guards-doc-drift";
 import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
 import { check as primitivesDiscipline } from "./guard-primitives-discipline";
 import { check as rawSql } from "./guard-raw-sql";
@@ -31,6 +33,8 @@ export const REPO_CHECKS = [
   realProviderIsolation,
   singleRuntimeInstance,
   agentDocsDrift,
+  subpathExports,
+  guardsDocDrift,
 ];
 
 export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];

package/src/runtime-isolation-classify.ts

@@ -49,6 +49,7 @@ const PATH_RULES: readonly (readonly [RegExp, Runtime])[] = [
   // sample and import kumiko-testing/e2e; without this rule they read as
   // runtime code importing the test tier. Deliberately not any nested e2e/.
   [/^(?:e2e|packages\/[^/]+\/e2e|samples\/(?:.+\/)?e2e)\//, "test"],
+  [/(?:^|\/)dev\//, "dev"],
   [/(?:^|\/)scripts\//, "tooling"],
   [/(?:^|\/)bin\//, "tooling"],
   [/\/drizzle\/[^/]+\.ts$/, "tooling"],
@@ -347,7 +348,10 @@ export function classifyByDirective(
   readHead: HeadReader = readFileHead,
 ): Runtime | null {
   const head = readHead(filePath);
-  if (head === null) return null;
+  return head === null ? null : directiveInHead(head);
+}
+
+export function directiveInHead(head: string): Runtime | null {
   for (const line of head.split("\n").slice(0, DIRECTIVE_HEAD_LINES)) {
     const m = line.match(/\/\/\s*@runtime\s+(\w+)/);
     const declared = m?.[1];