@cosmicdrift/kumiko-guards 0.387.0 → 0.389.0

package/src/dependency-license-exceptions.json

@@ -41,30 +41,6 @@
       "reviewedBy": "Marc, 2026-05-06",
       "expires": "2027-05-06"
     },
-    {
-      "package": "@cosmicdriftgamestudio/*",
-      "version": "*",
-      "license": "UNLICENSED",
-      "reason": "Eigene private CDGS-Workspace-Packages (kumiko-guards, später kumiko-ai-*, kumiko-designer etc.). UNLICENSED = proprietary, kein Public-License-Risk weil intern in der Org bleibt (GH-Packages access:restricted).",
-      "reviewedBy": "Marc, 2026-05-06",
-      "expires": "2030-05-06"
-    },
-    {
-      "package": "@cosmicdrift/*",
-      "version": "*",
-      "license": "BUSL-1.1",
-      "reason": "Eigene Public-Workspace-Packages (kumiko-framework + 6 weitere). Wir sind der Licensor — BUSL-1.1 ist unser eigener Lizenz-Choice für die public NPM-Pakete. Der License-Check denied BUSL-1.1 als generic-Pattern (für Third-Party-Deps korrekt), aber für eigene Packages ist's der designierte Lizenz.",
-      "reviewedBy": "Marc, 2026-05-06",
-      "expires": "2030-05-06"
-    },
-    {
-      "package": "create-kumiko-app",
-      "version": "*",
-      "license": "BUSL-1.1",
-      "reason": "Unscoped Workspace-Paket — `bun create kumiko-app` resolved zu `bunx create-kumiko-app`, daher KEIN @cosmicdrift/-Scope möglich. Analog zur @cosmicdrift/*-Exception unser eigener Lizenz-Choice; eigene Eintrag weil Wildcard-Pattern unscoped Pakete nicht matched.",
-      "reviewedBy": "Marc, 2026-06-21",
-      "expires": "2030-06-21"
-    },
     {
       "package": "khroma",
       "version": "*",

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

@@ -116,6 +116,8 @@ function checkCustomScreens(sf: SourceFile, violations: GuardViolation[]): void
 const DIRECTIVE_HEAD_CHARS = 600;
 const FEATURE_RELATIVE_PATH = /(?:src\/features|packages\/bundled-features\/src)\/[^/]+\/(.+)$/;
 
+const PATH_IMPLIED_RUNTIME_DIRS = ["dev/", "scripts/"];
+
 // 4. runtime-client marker instead of the path
 function clientMarkerViolation(sf: SourceFile): GuardViolation | undefined {
   const filePath = sf.getFilePath();
@@ -125,13 +127,13 @@ function clientMarkerViolation(sf: SourceFile): GuardViolation | 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)",
-  };
+  const runtimeFromPath = PATH_IMPLIED_RUNTIME_DIRS.some((dir) => featureRelative.startsWith(dir));
+  const message = underWeb
+    ? "redundant @runtime client marker — files under web/ are client by path"
+    : runtimeFromPath
+      ? "@runtime client marker under dev/ or scripts/ — the path already sets the runtime; remove the marker (bun kumiko codemod feature-layout . --write)"
+      : "client code outside web/ — move it under web/ (bun kumiko codemod feature-layout . --write)";
+  return { file: filePath, line: 1, message };
 }
 
 export const guard: AstGuard = {

package/src/guard-comment-issue-ref-only.ts

@@ -42,11 +42,13 @@ const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
 
 // `fw#12`, `#1234`, `kumiko-framework#3`, `oven-sh/bun#5`; `'` is an HTML entity.
 const REFERENCE_RE = /(?<!&)[\w./-]*#\d+(?![\w])/g;
+// Not preceded by a path/word character and not followed by `/`, `-` or `.ext`, so file names such
+// as `round2.ts` or `phase1.sql` are not planning labels, while a sentence-final "Phase 2." is.
 const PLANNING_WORD_RE =
-  /\b(?:phase|round|welle|wave|sprint)[- ]?\d+(?:\.\d+)*[a-z]?\b|\bbug-bash(?:[- ]\d+)?\b/gi;
+  /(?<![\w./-])(?:phase|round|welle|wave|sprint)[- ]?\d+(?:\.\d+)*[a-z]?(?![\w/-]|\.\w)|(?<![\w./-])bug-bash(?:[- ]\d+)?(?![\w/-]|\.\w)/gi;
 // Dotted plan labels such as S2.H1, T1.5c, B1.5. Case-sensitive and without V so
 // that version numbers (v1.2, V20.1) never count.
-const DOTTED_LABEL_RE = /\b[A-UW-Z]\d{1,2}(?:\.(?:\d+[a-z]?|[A-Z]\d+))+\b/g;
+const DOTTED_LABEL_RE = /(?<![\w./-])[A-UW-Z]\d{1,2}(?:\.(?:\d+[a-z]?|[A-Z]\d+))+\b/g;
 const WORD_RE = /[\p{L}_$][\p{L}\p{N}_$'-]*/gu;
 const MIN_EXPLANATORY_WORD_LENGTH = 3;
 

package/src/guard-comment-lang.ts

@@ -1,3 +1,9 @@
+// Comment-language ratchet: no new German comments in product code. No NLP —
+// German markers are common function words or umlaut characters in the comment text.
+// Baseline mode compares per-file counts against a frozen file (more than the
+// baseline fails, fewer is allowed but does not rewrite it); `--touched` fails
+// on any German comment that overlaps a line added since `--base`.
+
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { scanCommentTrivia } from "./_lib/comment-trivia";
@@ -8,12 +14,6 @@ import { resolvePushRepoRoot } from "./_lib/push-root";
 import { resolveRepoRoots } from "./_lib/roots";
 import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
 
-// Comment-language ratchet: no new German comments in product code. No NLP —
-// German markers are common function words or umlaut characters in the comment text.
-// Baseline mode compares per-file counts against a frozen file (more than the
-// baseline fails, fewer is allowed but does not rewrite it); `--touched` fails
-// on any German comment that overlaps a line added since `--base`.
-
 export const COMMENT_LANG_FLAGS: readonly string[] = [
   "--touched",
   "--list",

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

@@ -206,10 +206,7 @@ function entityRegistrationOf(call: CallExpression): EntityRegistration | undefi
     return undefined;
   }
   const definition = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
-  const nameProp = definition?.getProperty("name");
-  if (!definition || nameProp?.getKind() !== SyntaxKind.PropertyAssignment) return undefined;
-  const nameValue = nameProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
-  if (nameValue?.getKind() !== SyntaxKind.StringLiteral) return undefined;
+  if (!definition?.getProperty("name")) return undefined;
   return {
     entityDid: spreadEntityDefinitionId(definition),
     overrideTableDid: entityTableOverrideId(definition),
@@ -601,7 +598,7 @@ function deriveCatalogs(
 }
 
 const REWRITE_CATALOGS_COMMAND =
-  'bun packages/guards/src/run-guards.ts --write-baseline --guard="Direct-Entity-Writes Guard"';
+  'bunx kumiko-guards guards --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> {
@@ -670,6 +667,13 @@ function writeCatalogs(files: readonly SourceFile[], esTables: ReadonlySet<Table
   }
 }
 
+const MAX_RECEIVER_TEXT_LENGTH = 60;
+
+// Function-form receivers are arbitrary expressions; keep the message on one greppable line.
+function compactReceiverText(node: Node): string {
+  return node.getText().replace(/\s+/g, "").slice(0, MAX_RECEIVER_TEXT_LENGTH);
+}
+
 export function scanDirectWrites(
   sf: SourceFile,
   esTables: ReadonlySet<TableId>,
@@ -706,7 +710,7 @@ export function scanDirectWrites(
       if (isInsideProjectionApply(call)) continue;
       out.push({
         line: call.getStartLineNumber(),
-        receiver: w.receiver.getText(),
+        receiver: compactReceiverText(w.receiver),
         op: w.op,
         table: w.tableArg.getText(),
         snippet: call.getText().slice(0, 120),
@@ -717,7 +721,7 @@ export function scanDirectWrites(
 
     out.push({
       line: call.getStartLineNumber(),
-      receiver: w.receiver.getText(),
+      receiver: compactReceiverText(w.receiver),
       op: w.op,
       table: w.tableArg.getText(),
       snippet: call.getText().slice(0, 120),
@@ -727,6 +731,13 @@ export function scanDirectWrites(
   return out;
 }
 
+type DirectWriteViolation = {
+  file: string;
+  line: number;
+  message: string;
+  neverFrozen?: boolean;
+};
+
 export const guard: AstGuard = {
   name: "Direct-Entity-Writes Guard",
   scan: SCAN,
@@ -738,40 +749,18 @@ export const guard: AstGuard = {
     // 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.
-      if (!hasAnyTableWriteOrDeclaration(files)) return { violations: [] };
-      return {
-        violations: [
-          {
-            file: "<scan>",
-            line: 0,
-            message:
-              "BLOCKED: guard found table writes or table declarations but no createEventStoreExecutor or r.entity projection tables — scan is probably misconfigured.",
-          },
-        ],
-      };
-    }
-
-    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 };
 
+    const writeViolations: DirectWriteViolation[] = [];
     for (const sf of files) {
       const file = sf.getFilePath();
       if (EXCLUDE.test(file)) continue;
 
       for (const hit of scanDirectWrites(sf, esTables, externalEsTables)) {
-        violations.push({
+        writeViolations.push({
           file: path.relative(ROOT, file),
           line: hit.line,
           message: `[${hit.kind}] ${hit.receiver}.${hit.op}(${hit.table}) — ${hit.snippet}`,
@@ -779,6 +768,29 @@ export const guard: AstGuard = {
       }
     }
 
+    if (esTables.size === 0) {
+      // Writes on catalog tables of installed packages are real findings even without own ES tables.
+      if (writeViolations.length > 0) return { violations: writeViolations };
+      // 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.
+      if (!hasAnyTableWriteOrDeclaration(files)) return { violations: [] };
+      return {
+        violations: [
+          {
+            file: "<scan>",
+            line: 0,
+            message:
+              "BLOCKED: guard found table writes or table declarations but no createEventStoreExecutor or r.entity projection tables — scan is probably misconfigured.",
+          },
+        ],
+      };
+    }
+
+    const violations: DirectWriteViolation[] = [
+      ...catalogViolations(files, esTables),
+      ...writeViolations,
+    ];
+
     return { violations };
   },
   writeBaseline(files) {

package/src/guard-file-size.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * File Size Guard — production files above 2000 lines are frozen in
+ * File Size Guard — production files above 1200 lines are frozen in
  * `.kumiko-file-size-baseline.json` (key = file, value = line count) and may
  * not grow; a new file above the threshold is a violation. Without a baseline
  * file (consumer repos) it only warns.
@@ -31,7 +31,7 @@ const SCAN: ScanSpec = {
   frameworkWithin: ["packages/*/src/**"],
 };
 
-export const MAX_FILE_LINES = 2000;
+export const MAX_FILE_LINES = 1200;
 
 const EXCLUDE =
   /(__tests__|\.test\.(ts|tsx)$|\.integration\.(ts|tsx)$|\.d\.(ts|tsx)$|\.generated\.(ts|tsx)$|\/generated\/|\/locale-[^/]+\/src\/strings\.ts$)/;

package/src/guard-import-extensions.ts

@@ -14,7 +14,8 @@
  * Exit 1 on violations, 0 when clean.
  */
 
-import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { dirname, resolve } from "node:path";
+import { Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
 const SCAN: ScanSpec = {
@@ -23,7 +24,7 @@ const SCAN: ScanSpec = {
 };
 
 const EXCLUDE = /(\.d\.ts$|\/fixtures\/)/;
-const RELATIVE_JS_SPECIFIER = /^\.{1,2}\/.*\.jsx?$/;
+const RELATIVE_JS_SPECIFIER = /^(\.{1,2}\/.*)\.(jsx?)$/;
 // A published bin that imports its own build output (`../dist/cli.js`) has no
 // `.ts` sibling to name; the `.js` there is the only file that exists.
 const BUILD_OUTPUT_SEGMENT = /(^|\/)dist\//;
@@ -33,17 +34,34 @@ interface Finding {
   readonly specifier: string;
 }
 
-function relativeJsSpecifier(node: Node | undefined): string | undefined {
-  const literal = node?.asKind(SyntaxKind.StringLiteral);
-  const value = literal?.getLiteralValue();
-  if (value === undefined || !RELATIVE_JS_SPECIFIER.test(value)) return undefined;
-  return BUILD_OUTPUT_SEGMENT.test(value) ? undefined : value;
+// Mirrors the import-extensions codemod: only a specifier with a `.ts`/`.tsx` sibling is fixable.
+// A genuine `.js` file (generated or vendored) has nothing to rename to and must not fail the guard.
+function hasSourceSibling(sf: SourceFile, base: string, extension: string): boolean {
+  const candidates = extension === "jsx" ? ["tsx"] : ["ts", "tsx"];
+  const project = sf.getProject();
+  return candidates.some((candidate) => {
+    const path = resolve(dirname(sf.getFilePath()), `${base}.${candidate}`);
+    return (
+      project.getSourceFile(path) !== undefined || project.getFileSystem().fileExistsSync(path)
+    );
+  });
+}
+
+function relativeJsSpecifier(sf: SourceFile, node: Node | undefined): string | undefined {
+  const value =
+    node !== undefined && (Node.isStringLiteral(node) || Node.isNoSubstitutionTemplateLiteral(node))
+      ? node.getLiteralValue()
+      : undefined;
+  if (value === undefined || BUILD_OUTPUT_SEGMENT.test(value)) return undefined;
+  const [, base = "", extension = ""] = RELATIVE_JS_SPECIFIER.exec(value) ?? [];
+  if (base === "" || !hasSourceSibling(sf, base, extension)) return undefined;
+  return value;
 }
 
 function findJsSpecifiers(sf: SourceFile): Finding[] {
   const findings: Finding[] = [];
   const add = (node: Node | undefined): void => {
-    const specifier = relativeJsSpecifier(node);
+    const specifier = relativeJsSpecifier(sf, node);
     if (node !== undefined && specifier !== undefined) {
       findings.push({ line: node.getStartLineNumber(), specifier });
     }
@@ -51,8 +69,15 @@ function findJsSpecifiers(sf: SourceFile): Finding[] {
   for (const declaration of [...sf.getImportDeclarations(), ...sf.getExportDeclarations()]) {
     add(declaration.getModuleSpecifier());
   }
+  for (const importType of sf.getDescendantsOfKind(SyntaxKind.ImportType)) {
+    const argument = importType.getArgument();
+    if (Node.isLiteralTypeNode(argument)) add(argument.getLiteral());
+  }
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    if (call.getExpression().getKind() === SyntaxKind.ImportKeyword) add(call.getArguments()[0]);
+    const callee = call.getExpression();
+    if (callee.getKind() === SyntaxKind.ImportKeyword || callee.getText() === "mock.module") {
+      add(call.getArguments()[0]);
+    }
   }
   return findings;
 }

package/src/guard-no-date-api.ts

@@ -101,13 +101,13 @@ const ALLOWLIST = [
   // Number.isNaN(d.getTime()) as a validity check.
   /packages\/framework\/src\/pipeline\/entity-cache\.ts$/,
   // Event-store insertSubsequentEvent: raw SQL row.created_at can be Date|string
-  // (postgres-js driver-config dependent), normalised to Temporal.Instant via
+  // (driver-config dependent), normalised to Temporal.Instant via
   // .getTime() bridge.
   /packages\/framework\/src\/event-store\/event-store\.ts$/,
   // HTTP Last-Modified/ETag header: Bun/Node Response API expects a native
   // Date object from fs.Stats.mtimeMs — wire boundary, not a Temporal format.
   /packages\/server-runtime\/src\/run-prod-app-static-files\.ts$/,
-  // postgres-js timestamptz columns arrive as native Date (driver wire format,
+  // timestamptz columns arrive as native Date (driver wire format,
   // same reason as packages/framework/src/db/ above).
   /packages\/publish\/src\/rollback\.ts$/,
 ];

package/src/guard-no-direct-fs.ts

@@ -90,7 +90,7 @@ const ALLOWLIST: readonly AllowEntry[] = [
   // Framework: migrations/schema tooling, DB codegen, boot validator —
   // CLI/build time, no request input.
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/migrations\/kumiko-drift\.ts$/ },
-  { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/schema-cli\.ts$/ },
+  { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/schema-cli(\.ts|\/[^/]+\.ts)$/ },
   // same CLI-tooling pattern as schema-cli.ts — repo-tree/node_modules walking for the upgrade command, not app-level file storage
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/upgrade-cli\.ts$/ },
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/es-ops\/runner\.ts$/ },
@@ -115,6 +115,12 @@ const ALLOWLIST: readonly AllowEntry[] = [
     repo: "kumiko-framework",
     pattern: /^packages\/server-runtime\/src\/run-prod-app-static-files\.ts$/,
   },
+  // Package lookup for the build and the dev server: existence check for
+  // node_modules/<pkg>/package.json above a directory, no request input as a path.
+  {
+    repo: "kumiko-framework",
+    pattern: /^packages\/server-runtime\/src\/resolve-installed-package\.ts$/,
+  },
 
   // create-kumiko-app: Scaffolding-CLI.
   { repo: "kumiko-framework", pattern: /^packages\/create-kumiko-app\/src\/manifest\.ts$/ },

package/src/guard-public-exports-changelog.ts

@@ -1,11 +1,3 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { Project } from "ts-morph";
-import { cliFlagsError, type GuardViolation, reportResults } from "./_lib/guard-kit";
-import { frameworkTsConfigPath, resolveRepoRoots } from "./_lib/roots";
-
 // Public exports of packages/framework and packages/bundled-features must not
 // disappear (rename/removal) without a breaking changelog entry.
 //
@@ -30,6 +22,14 @@ import { frameworkTsConfigPath, resolveRepoRoots } from "./_lib/roots";
 // has ONE changelog (src/changes.json); packages/bundled-features has one PER
 // FEATURE (src/<feature>/changes.json, feature = first export-key segment).
 
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Project } from "ts-morph";
+import { cliFlagsError, type GuardViolation, reportResults } from "./_lib/guard-kit";
+import { frameworkTsConfigPath, resolveRepoRoots } from "./_lib/roots";
+
 export const PUBLIC_EXPORTS_CHANGELOG_FLAGS: readonly string[] = [
   "--write-baseline",
   "--no-baseline",

package/src/guard-renderer-boundaries.ts

@@ -11,6 +11,9 @@
  * emits SVG strings and the live dispatcher is a fetch client, so the symbol and JSX-tag rules would be noise there. They stay free
  * of react-dom, jsdom and any import of `src/web`.
  *
+ * `headless` additionally may not import react, the renderer root or anything outside its own
+ * folder (server/mail bundles import it); the shared layer may not import `live`.
+ *
  * Deliberately simple: a regex scan over the source text. False positives
  * (e.g. "window" in a string literal) are possible but rare — the guard is a
  * maintenance alarm, not a semantic proof.
@@ -41,6 +44,24 @@ const FORBIDDEN_IMPORTS = [
   /from ["']@cosmicdrift\/kumiko-dispatcher-live["']/,
 ];
 
+// `headless` is consumed server-side (prod bundle, mail HTML): it must stay free of React and of
+// the shared layer, so it may only import itself and third-party packages other than react.
+const HEADLESS_FORBIDDEN_IMPORTS = [
+  /from ["']react(?:\/.*)?["']/,
+  /from ["']@cosmicdrift\/kumiko-renderer(?:\/(?!headless(?:["'/]))[^"']*)?["']/,
+];
+
+// The fetch/document.cookie dispatcher client belongs to consumers of `live`, not the shared layer.
+const SHARED_FORBIDDEN_IMPORTS = [
+  /from ["'](?:\.\.?\/)+live(?:\/.*)?["']/,
+  /from ["']@cosmicdrift\/kumiko-renderer\/live(?:\/.*)?["']/,
+];
+
+// dev-console.ts is a dependency-free console wrapper, safe in server bundles.
+const HEADLESS_ALLOWED_LEAF = /(?:^|\/)dev-console(?:\.ts)?$/;
+
+const RELATIVE_SPECIFIER = /from ["'](\.\.?\/[^"']*)["']/;
+
 // Runtime symbols that mean DOM/browser. `\b` prevents substring matches
 // (e.g. "origin" not matched as "origin.foo"). This is a coarse guard — a
 // ts-morph-based check would be more precise, but not worth the effort here.
@@ -82,6 +103,34 @@ type Violation = {
   readonly excerpt: string;
 };
 
+const RENDERER_SRC = `${path.sep}packages${path.sep}renderer${path.sep}src${path.sep}`;
+
+// Absolute path of `packages/renderer/src/<dir>` containing `file`, or "" when it is elsewhere.
+function rendererSrcSubdir(file: string, dir: string): string {
+  const marker = `${RENDERER_SRC}${dir}${path.sep}`;
+  const index = file.indexOf(marker);
+  return index === -1 ? "" : file.slice(0, index + marker.length - 1);
+}
+
+function isInside(dir: string, target: string): boolean {
+  return target === dir || target.startsWith(dir + path.sep);
+}
+
+function escapesHeadless(file: string, line: string): boolean {
+  const headlessDir = rendererSrcSubdir(file, "headless");
+  const specifier = RELATIVE_SPECIFIER.exec(line)?.[1];
+  if (headlessDir === "" || specifier === undefined) return false;
+  if (HEADLESS_ALLOWED_LEAF.test(specifier)) return false;
+  return !isInside(headlessDir, path.resolve(path.dirname(file), specifier));
+}
+
+function isSharedLayer(file: string): boolean {
+  return (
+    file.includes(RENDERER_SRC) &&
+    ["headless", "live", "web"].every((dir) => rendererSrcSubdir(file, dir) === "")
+  );
+}
+
 function walk(dir: string, skippedDirs: readonly string[] = []): string[] {
   const out: string[] = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
@@ -111,15 +160,18 @@ export function findViolations(file: string, root: string, importRulesOnly = fal
     const trimmed = line.trim();
     if (trimmed.startsWith("//") || trimmed.startsWith("*")) continue;
 
-    for (const pattern of FORBIDDEN_IMPORTS) {
-      if (pattern.test(line)) {
-        violations.push({
-          file: path.relative(root, file),
-          line: i + 1,
-          rule: "forbidden-import",
-          excerpt: trimmed,
-        });
-      }
+    const importPatterns = [
+      ...FORBIDDEN_IMPORTS,
+      ...(rendererSrcSubdir(file, "headless") !== "" ? HEADLESS_FORBIDDEN_IMPORTS : []),
+      ...(isSharedLayer(file) ? SHARED_FORBIDDEN_IMPORTS : []),
+    ];
+    if (importPatterns.some((pattern) => pattern.test(line)) || escapesHeadless(file, line)) {
+      violations.push({
+        file: path.relative(root, file),
+        line: i + 1,
+        rule: "forbidden-import",
+        excerpt: trimmed,
+      });
     }
     if (importRulesOnly) continue;
     for (const pattern of FORBIDDEN_SYMBOLS) {

package/src/guard-restricted-symbols.ts

@@ -52,6 +52,8 @@ const ALLOWLIST = [
   /^packages\/framework\/src\/event-store\/index\.ts$/,
   /^packages\/framework\/src\/event-store\/tenant-db-append\.ts$/,
   /^packages\/bundled-features\/src\/cap-counter\/cap-reservation\.ts$/,
+  // Catch-up of a missing terminal extract event in the caller tenant's own stream; JobContext has no appendEvent.
+  /^packages\/bundled-features\/src\/document-ingest-foundation\/append-missing-extract-event\.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$/,

package/src/guard-test-es-fixtures.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * Guard: tests seed event-sourced state through the event store, not through
+ * hand-written SQL. Flags, in test files, string/template literals with
+ *   (a) INSERT INTO / UPDATE against kumiko_events (use append / runSeedWritesAt)
+ *   (b) CREATE TABLE ... read_tenant_memberships (use unsafeCreateEntityTable with
+ *       tenantMembershipEntity and seedRow, so the schema cannot drift from the entity)
+ *
+ * Usage:
+ *   bun packages/guards/src/guard-test-es-fixtures.ts
+ */
+import type { SourceFile } from "ts-morph";
+import { SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+
+const SCAN: ScanSpec = { scope: "tests", extensions: ["ts"] };
+
+// Bulk seeding of thousands of events through append() would take minutes; these
+// perf tests measure the read path on a finished stream, not the seed phase.
+// The concurrent-commit ordering tests hold a transaction open and need explicit event
+// ids/versions, which append() does not expose.
+// The guards' own tests carry the forbidden SQL as fixture strings.
+const ALLOWLIST: readonly RegExp[] = [
+  /^packages\/framework\/src\/event-store\/__tests__\/perf\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/perf-rebuild\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/event-dispatcher-commit-order\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/event-dispatcher-start-from\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/msp-rebuild\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/projection-rebuild\.integration\.test\.ts$/,
+  /^packages\/guards\/src\/__tests__\//,
+];
+
+const EVENT_WRITE_RE = /\b(INSERT\s+INTO|UPDATE)\s+["`]?kumiko_events\b/i;
+const MEMBERSHIP_DDL_RE = /\bCREATE\s+TABLE\b[^;]*?\bread_tenant_memberships\b/i;
+
+const LITERAL_KINDS = [
+  SyntaxKind.StringLiteral,
+  SyntaxKind.NoSubstitutionTemplateLiteral,
+  SyntaxKind.TemplateExpression,
+];
+
+function violationMessage(text: string): string | undefined {
+  const write = EVENT_WRITE_RE.exec(text);
+  if (write)
+    return `raw ${write[0].replace(/\s+/g, " ")} in a test: seed via append() or runSeedWritesAt()`;
+  if (MEMBERSHIP_DDL_RE.test(text)) {
+    return "hand-written read_tenant_memberships DDL in a test: use unsafeCreateEntityTable(db, tenantMembershipEntity)";
+  }
+  return undefined;
+}
+
+function collect(sourceFile: SourceFile, roots: readonly RepoRoot[]): GuardViolation[] {
+  const file = relFromRepoRoot(sourceFile.getFilePath(), roots);
+  if (ALLOWLIST.some((re) => re.test(file))) return [];
+  const violations: GuardViolation[] = [];
+  for (const kind of LITERAL_KINDS) {
+    for (const node of sourceFile.getDescendantsOfKind(kind)) {
+      const message = violationMessage(node.getText());
+      if (message) violations.push({ file, line: node.getStartLineNumber(), message });
+    }
+  }
+  return violations;
+}
+
+export const guard: AstGuard = {
+  name: "Test-ES-Fixtures Guard",
+  scan: SCAN,
+  hint:
+    "Seed events with append() (runSeedWritesAt for backdating) and membership rows with " +
+    "seedRow on a table made by unsafeCreateEntityTable; bulk perf seeds belong in the guard allowlist with a Why.",
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
+    return { violations: files.flatMap((sf) => collect(sf, roots)) };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-test-timeouts.ts

@@ -32,7 +32,7 @@
  * Consumer (via the published `kumiko-guards` CLI):
  *   kumiko-guards guards --guard=test-timeouts
  */
-import { type CallExpression, Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { type CallExpression, Node, type SourceFile, SyntaxKind, type Type } from "ts-morph";
 import {
   type AstGuard,
   type GuardOutcome,
@@ -182,12 +182,20 @@ function declarationBaseCallee(callee: Node): Node {
 }
 
 // An identifier can be the Playwright test body (`test(title, details, body)`) or an options
-// variable like `{ retry: 2 }`, so it only counts when its type is a number or carries `timeout`.
+// variable like `{ retry: 2 }`, so only its type decides. Every other non-function expression
+// (conditional, member access, call) is treated as a timeout so a union or untyped value cannot hide one.
 function isTimeoutArgument(arg: Node): boolean {
   if (Node.isObjectLiteralExpression(arg)) return hasTimeoutProperty(arg);
   if (Node.isArrowFunction(arg) || Node.isFunctionExpression(arg)) return false;
+  if (!Node.isIdentifier(arg)) return true;
   const type = arg.getType();
-  return type.isNumber() || type.isNumberLiteral() || type.getProperty("timeout") !== undefined;
+  if (type.isAny() || type.isUnknown()) return true;
+  const carriesNumber = (t: Type): boolean => t.isNumber() || t.isNumberLiteral();
+  return (
+    carriesNumber(type) ||
+    (type.isUnion() && type.getUnionTypes().some(carriesNumber)) ||
+    type.getProperty("timeout") !== undefined
+  );
 }
 
 function declarationTimeoutReason(