@cosmicdrift/kumiko-guards 0.354.1 → 0.355.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.354.1",
+  "version": "0.355.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>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.354.1",
+    "@cosmicdrift/kumiko-repo-manifest": "0.355.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/guard-kit.ts

@@ -24,7 +24,7 @@ import {
   type RootResolution,
   resolveRepoRoots,
 } from "./roots";
-import { type RootScan, type ScanSpec, scanFiles, scanRoots } from "./scan-scope";
+import { type RootScan, type ScanOptions, type ScanSpec, scanFiles, scanRoots } from "./scan-scope";
 import {
   applySecurityBaseline,
   loadSecurityBaseline,
@@ -63,6 +63,10 @@ export function isSecurityGuard(guard: Pick<AstGuard, "security">): boolean {
   return guard.security === true;
 }
 
+function scanOptionsFor(guard: Pick<AstGuard, "security">): ScanOptions {
+  return { security: isSecurityGuard(guard) };
+}
+
 // Followers call the predicate per import hop; findLocalRepo re-reads
 // package.json and the manifest each time.
 const localRepoRootByCwd = new Map<string, string | undefined>();
@@ -126,7 +130,7 @@ export function buildSharedProject(
     ...new Set(
       guards.flatMap((guard) => {
         try {
-          return scanFiles(guard.scan, roots);
+          return scanFiles(guard.scan, roots, scanOptionsFor(guard));
         } catch {
           return [];
         }
@@ -143,7 +147,7 @@ export function filesForGuard(
   guard: AstGuard,
   roots: readonly RepoRoot[] = resolveRepoRoots(),
 ): SourceFile[] {
-  return scanFiles(guard.scan, roots).map(
+  return scanFiles(guard.scan, roots, scanOptionsFor(guard)).map(
     (path) => project.getSourceFile(path) ?? project.addSourceFileAtPath(path),
   );
 }
@@ -366,7 +370,9 @@ export function runGuards(
 ): RunResult[] {
   const results: RunResult[] = [];
   const scan =
-    deps.scan ?? ((guard: AstGuard, roots: readonly RepoRoot[]) => scanRoots(guard.scan, roots));
+    deps.scan ??
+    ((guard: AstGuard, roots: readonly RepoRoot[]) =>
+      scanRoots(guard.scan, roots, scanOptionsFor(guard)));
   const roots = deps.roots ?? resolveRepoRoots();
 
   for (const guard of guards) {
@@ -505,7 +511,9 @@ export function explainGuards(
   deps: ExplainGuardsDeps = {},
 ): string[] {
   const scan =
-    deps.scan ?? ((guard: AstGuard, roots: readonly RepoRoot[]) => scanRoots(guard.scan, roots));
+    deps.scan ??
+    ((guard: AstGuard, roots: readonly RepoRoot[]) =>
+      scanRoots(guard.scan, roots, scanOptionsFor(guard)));
   const { roots } = deps.resolution ?? explainRepoRoots();
   const lines = [
     `Repo: ${roots[0]?.root.absPath ?? "— none found (no package.json with kumiko.json/src layout above cwd)"}`,

package/src/_lib/roots.ts

@@ -24,6 +24,9 @@ export type { RepoKind } from "@cosmicdrift/kumiko-repo-manifest";
 
 import type { RepoKind } from "@cosmicdrift/kumiko-repo-manifest";
 
+// Worktrees (`.wt/kumiko-framework-*`) keep this package name, so it is stable across checkouts.
+const FRAMEWORK_PACKAGE_NAME = "kumiko-framework";
+
 export type RepoRoot = {
   /** Repo identifier — the package.json `name`. */
   readonly name: string;
@@ -150,6 +153,11 @@ function repoAt(dir: string): RepoRoot | undefined {
   const name = pkg.name;
   if (typeof name !== "string") return undefined;
   const loaded = manifestRootAt(dir);
+  if (loaded?.manifest.kind === "framework" && name !== FRAMEWORK_PACKAGE_NAME) {
+    throw new Error(
+      `${join(dir, "kumiko.json")}: kind "framework" is reserved for the ${FRAMEWORK_PACKAGE_NAME} repo (package name is "${name}"); it narrows scans via frameworkWithin and must not be self-declared`,
+    );
+  }
   return loaded ? rootFrom(name, dir, loaded) : undefined;
 }
 

package/src/_lib/scan-scope.ts

@@ -124,6 +124,27 @@ function extraHits(root: RepoRoot, globs: readonly string[] | undefined): Hit[]
   return [...byRepoRel.values()];
 }
 
+// Security guards honour only these: a repo manifest must not be able to switch a security scan off for its own files.
+export const SECURITY_GUARD_HONORED_EXCLUDES: readonly string[] = [
+  "**/node_modules/**",
+  "**/dist/**",
+];
+
+export type ScanOptions = {
+  /** Security guards ignore manifest excludes beyond SECURITY_GUARD_HONORED_EXCLUDES. */
+  readonly security?: boolean;
+};
+
+function effectiveExcludes(
+  root: RepoRoot,
+  options: ScanOptions | undefined,
+): readonly string[] | undefined {
+  if (options?.security !== true) return root.manifest.excludes;
+  return (root.manifest.excludes ?? []).filter((pattern) =>
+    SECURITY_GUARD_HONORED_EXCLUDES.includes(pattern),
+  );
+}
+
 function afterExcludes(hits: readonly Hit[], excludes: readonly string[] | undefined): Hit[] {
   if (!excludes || excludes.length === 0) return [...hits];
   return hits.filter((hit) => !matchesAny(hit.repoRel, excludes));
@@ -144,9 +165,10 @@ function keepForSpec(hit: Hit, root: RepoRoot, spec: ScanSpec): boolean {
   return true;
 }
 
-function scanRoot(spec: ScanSpec, root: RepoRoot): RootScan {
-  const sourceSurfaceHits = afterExcludes(sourceHits(root), root.manifest.excludes);
-  const testSurfaceHits = () => afterExcludes(testHits(root), root.manifest.excludes);
+function scanRoot(spec: ScanSpec, root: RepoRoot, options?: ScanOptions): RootScan {
+  const excludes = effectiveExcludes(root, options);
+  const sourceSurfaceHits = afterExcludes(sourceHits(root), excludes);
+  const testSurfaceHits = () => afterExcludes(testHits(root), excludes);
   const scopeHits =
     spec.scope === "source"
       ? sourceSurfaceHits
@@ -159,7 +181,7 @@ function scanRoot(spec: ScanSpec, root: RepoRoot): RootScan {
     seen.add(hit.repoRel);
     return true;
   });
-  const additionalHits = afterExcludes(extraHits(root, spec.extraGlobs), root.manifest.excludes);
+  const additionalHits = afterExcludes(extraHits(root, spec.extraGlobs), excludes);
   const files = [...uniqueScopeHits, ...additionalHits.filter((hit) => !seen.has(hit.repoRel))]
     .filter((hit) => keepForSpec(hit, root, spec))
     .map((hit) => join(root.absPath, hit.repoRel))
@@ -172,10 +194,20 @@ export function keepsRootKind(spec: ScanSpec, root: RepoRoot): boolean {
   return root.kind !== "tooling";
 }
 
-export function scanRoots(spec: ScanSpec, roots: readonly RepoRoot[]): RootScan[] {
-  return roots.filter((root) => keepsRootKind(spec, root)).map((root) => scanRoot(spec, root));
+export function scanRoots(
+  spec: ScanSpec,
+  roots: readonly RepoRoot[],
+  options?: ScanOptions,
+): RootScan[] {
+  return roots
+    .filter((root) => keepsRootKind(spec, root))
+    .map((root) => scanRoot(spec, root, options));
 }
 
-export function scanFiles(spec: ScanSpec, roots: readonly RepoRoot[]): string[] {
-  return [...new Set(scanRoots(spec, roots).flatMap((rootScan) => rootScan.files))].sort();
+export function scanFiles(
+  spec: ScanSpec,
+  roots: readonly RepoRoot[],
+  options?: ScanOptions,
+): string[] {
+  return [...new Set(scanRoots(spec, roots, options).flatMap((rootScan) => rootScan.files))].sort();
 }

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.355.0",
+    "type": "breaking",
+    "title": "Security guards ignore kumiko.json excludes beyond node_modules and dist; kind framework is reserved for kumiko-framework",
+    "migration": "Security guards (No-Direct-Fs, Direct-Entity-Writes, Direct-Fetch, Tenant-Escalation, Admin-API, Access-Denied-Test, Open-To-All-Reason, Escape-Hatch-Declared) now scan files matched by your kumiko.json excludes; fix the findings or add a precise guard allowlist entry. A kumiko.json with kind framework outside the kumiko-framework package now fails root resolution; use library or app. Direct-Entity-Writes now sees table arguments behind casts (`table as T`, parentheses, non-null), so a cast no longer hides a direct write. i18n-Locale-Mount handles conditional spreads, alias depth and circular constants."
+  },
+  {
+    "version": "0.355.0",
+    "type": "breaking",
+    "title": "test-timeouts guard flags timeout arguments on test(), it() and describe()",
+    "migration": "Remove the timeout argument from test/it/describe calls (test(name, fn, 30_000), test(name, fn, { timeout }), also via .skip/.only/.if()/.each()) and fix the cause: poll with waitFor/expect.poll, shrink the data set, share expensive setup in beforeAll. setDefaultTimeout and describe.configure through renamed or namespace bun:test imports are flagged too. A justified remainder gets '// @timeout-exception: #<issue> <reason>' on the line above the call."
+  },
   {
     "version": "0.354.0",
     "type": "improvement",

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

@@ -44,13 +44,7 @@
  */
 
 import * as path from "node:path";
-import {
-  type CallExpression,
-  type Identifier,
-  type Node,
-  type SourceFile,
-  SyntaxKind,
-} from "ts-morph";
+import { type CallExpression, type Identifier, Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
 const ROOT = process.cwd();
@@ -94,6 +88,61 @@ 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 reason: string;
+};
+
+const DIRECT_WRITE_EXCEPTIONS: readonly DirectWriteException[] = [
+  {
+    file: /(^|\/)packages\/bundled-features\/src\/template-resolver\/seeding\.ts$/,
+    functionName: "resolveExistingForEventStoreSeed",
+    table: "templateResourcesTable",
+    reason: "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;
+  while (
+    Node.isAsExpression(current) ||
+    Node.isSatisfiesExpression(current) ||
+    Node.isParenthesizedExpression(current) ||
+    Node.isNonNullExpression(current) ||
+    Node.isTypeAssertion(current)
+  ) {
+    current = current.getExpression();
+  }
+  return current;
+}
+
 // Identity of a table declaration: absolute file path + identifier name.
 // Text-only names collide across samples (currencies-global.invoiceTable vs.
 // beammycar.invoiceTable would look the same); resolving to the underlying
@@ -118,9 +167,9 @@ export function collectEsTables(files: readonly SourceFile[]): Set<TableId> {
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       const expr = call.getExpression();
       if (expr.getText() !== "createEventStoreExecutor") continue;
-      const tableArg = call.getArguments()[0];
-      if (!tableArg || tableArg.getKind() !== SyntaxKind.Identifier) continue;
-      const id = tableArg.asKindOrThrow(SyntaxKind.Identifier);
+      const firstArg = call.getArguments()[0];
+      const id = firstArg && unwrapTableExpression(firstArg).asKind(SyntaxKind.Identifier);
+      if (!id) continue;
 
       // Repo convention: projection-tables follow `<name>Table`. Secondary
       // filter that catches factory-of-factory pass-throughs even if
@@ -149,9 +198,10 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
       const args = call.getArguments();
       if (!args[0] || args[0].getKind() !== SyntaxKind.StringLiteral) continue;
 
-      const entityArg = args[1];
-      if (entityArg?.getKind() === SyntaxKind.Identifier) {
-        const did = declIdOf(entityArg.asKindOrThrow(SyntaxKind.Identifier));
+      const entityIdentifier =
+        args[1] && unwrapTableExpression(args[1]).asKind(SyntaxKind.Identifier);
+      if (entityIdentifier) {
+        const did = declIdOf(entityIdentifier);
         if (did) rebuildableEntities.add(did);
       }
 
@@ -162,8 +212,9 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
           .getProperty("table");
         if (tableProp?.getKind() === SyntaxKind.PropertyAssignment) {
           const init = tableProp.asKindOrThrow(SyntaxKind.PropertyAssignment).getInitializer();
-          if (init?.getKind() === SyntaxKind.Identifier) {
-            const did = declIdOf(init.asKindOrThrow(SyntaxKind.Identifier));
+          const tableIdentifier = init && unwrapTableExpression(init).asKind(SyntaxKind.Identifier);
+          if (tableIdentifier) {
+            const did = declIdOf(tableIdentifier);
             if (did) tables.add(did);
           }
         }
@@ -177,8 +228,10 @@ export function collectEntityProjectionTables(files: readonly SourceFile[]): Set
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
       if (call.getExpression().getText() !== "buildEntityTable") continue;
       const entityArg = call.getArguments()[1];
-      if (entityArg?.getKind() !== SyntaxKind.Identifier) continue;
-      const entityDid = declIdOf(entityArg.asKindOrThrow(SyntaxKind.Identifier));
+      const entityIdentifier =
+        entityArg && unwrapTableExpression(entityArg).asKind(SyntaxKind.Identifier);
+      if (!entityIdentifier) continue;
+      const entityDid = declIdOf(entityIdentifier);
       if (!entityDid || !rebuildableEntities.has(entityDid)) continue;
 
       const varDecl = call.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
@@ -253,9 +306,9 @@ function isInsideProjectionApply(callNode: Node): boolean {
 
 // Extracts (table identifier, db/receiver expression, op) from a write
 // call — both forms: the Drizzle method `<recv>.insert(table)` and the
-// bun-db function `updateMany(db, table, ...)`. undefined for non-writes or
-// when the table arg isn't a plain identifier (not resolvable → skip, never
-// a false block).
+// bun-db function `updateMany(db, table, ...)`. Casts around the table arg are
+// unwrapped; undefined for non-writes or when the table arg is still no plain
+// identifier (computed tables are not resolvable → skip, never a false block).
 function resolveWrite(
   call: CallExpression,
 ): { tableArg: Identifier; receiver: Node; op: "insert" | "update" | "delete" } | undefined {
@@ -266,23 +319,17 @@ function resolveWrite(
     const pa = expr.asKindOrThrow(SyntaxKind.PropertyAccessExpression);
     const m = pa.getName();
     if (m !== "insert" && m !== "update" && m !== "delete") return undefined;
-    if (args[0]?.getKind() !== SyntaxKind.Identifier) return undefined;
-    return {
-      tableArg: args[0].asKindOrThrow(SyntaxKind.Identifier),
-      receiver: pa.getExpression(),
-      op: m,
-    };
+    const tableArg = args[0] && unwrapTableExpression(args[0]).asKind(SyntaxKind.Identifier);
+    if (!tableArg) return undefined;
+    return { tableArg, receiver: pa.getExpression(), op: m };
   }
 
   if (expr.getKind() === SyntaxKind.Identifier) {
     const op = FN_WRITE_HELPERS.get(expr.getText());
     if (!op) return undefined;
-    if (!args[0] || args[1]?.getKind() !== SyntaxKind.Identifier) return undefined;
-    return {
-      tableArg: args[1].asKindOrThrow(SyntaxKind.Identifier),
-      receiver: args[0],
-      op,
-    };
+    const tableArg = args[1] && unwrapTableExpression(args[1]).asKind(SyntaxKind.Identifier);
+    if (!args[0] || !tableArg) return undefined;
+    return { tableArg, receiver: args[0], op };
   }
 
   return undefined;
@@ -355,9 +402,6 @@ export function scanDirectWrites(
     const w = resolveWrite(call);
     if (!w) continue;
 
-    const did = declIdOf(w.tableArg);
-    if (!did || !esTables.has(did)) continue;
-
     // Walk the receiver chain down to its leftmost identifier. For `db.insert`
     // that's `db`; for `ctx.db.raw` (function-form arg0) that's `ctx`; for
     // `tx` that's `tx`. Checked against the TX-receiver-Set.
@@ -367,6 +411,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 (TX_RECEIVER_NAMES.has(receiverName)) {
       // A tx receiver is only legitimate when the write actually sits
       // inside a projection-apply callback. A sub-tx pattern like

package/src/guard-i18n-locale-mount.ts

@@ -99,7 +99,14 @@ function localeDeClientRef(node: Node): boolean {
 // through the specifier's own name to get there.
 function resolveDeclaration(identifier: Identifier, depth = 0): Node | undefined {
   if (depth > 3) return undefined;
-  const def = identifier.getDefinitionNodes()[0];
+  // With a contextual type (e.g. a declared options type) the first definition
+  // can be the property signature, not the binding — pick the binding.
+  const def = identifier
+    .getDefinitionNodes()
+    .find(
+      (node) =>
+        node.isKind(SyntaxKind.VariableDeclaration) || node.isKind(SyntaxKind.ImportSpecifier),
+    );
   if (def === undefined) return undefined;
   if (def.isKind(SyntaxKind.VariableDeclaration)) return def;
   if (def.isKind(SyntaxKind.ImportSpecifier)) {
@@ -113,9 +120,14 @@ function resolveDeclaration(identifier: Identifier, depth = 0): Node | undefined
 
 // `as const` and `as const satisfies T[]` (both in active use, e.g.
 // kumiko-studio's run-config.ts) wrap the array literal in an AsExpression
-// and/or SatisfiesExpression — unwrap either so callers see the literal underneath.
+// and/or SatisfiesExpression, and `(X as T)` adds a ParenthesizedExpression —
+// unwrap all of them so callers see the literal underneath.
 function unwrapAsExpression(node: Node): Node {
-  if (node.isKind(SyntaxKind.AsExpression) || node.isKind(SyntaxKind.SatisfiesExpression)) {
+  if (
+    node.isKind(SyntaxKind.AsExpression) ||
+    node.isKind(SyntaxKind.SatisfiesExpression) ||
+    node.isKind(SyntaxKind.ParenthesizedExpression)
+  ) {
     return unwrapAsExpression(node.getExpression());
   }
   return node;
@@ -137,37 +149,44 @@ function resolveSameRepoInitializer(identifier: Identifier): Node | undefined {
   return init === undefined ? undefined : unwrapAsExpression(init);
 }
 
+// Bounds every alias/spread chain the guard follows; circular constants
+// (`const a = [...b]; const b = [...a]`) parse fine and must end in a verdict,
+// not a stack overflow.
+const MAX_ALIAS_DEPTH = 5;
+
 // Resolves an array-shaped value node down to its elements, whether it's a
 // literal right there or an identifier pointing at a same-repo constant
 // (`const CONST = [...]`, `... as const` included).
-function arrayElementsOf(value: Node | undefined): Node[] | undefined {
-  if (value === undefined) return undefined;
+function arrayElementsOf(value: Node | undefined, depth = 0): Node[] | undefined {
+  if (value === undefined || depth > MAX_ALIAS_DEPTH) return undefined;
   if (value.isKind(SyntaxKind.ArrayLiteralExpression)) return value.getElements();
   if (value.isKind(SyntaxKind.Identifier)) {
-    return arrayElementsOf(resolveSameRepoInitializer(value));
+    return arrayElementsOf(resolveSameRepoInitializer(value), depth + 1);
   }
   return undefined;
 }
 
-function elementRegistersGerman(el: Node): boolean {
+// Past the depth bound the answer is "no German found" (fail-closed).
+function elementRegistersGerman(el: Node, depth = 0): boolean {
+  if (depth > MAX_ALIAS_DEPTH) return false;
   if (el.isKind(SyntaxKind.SpreadElement)) {
     const expr = el.getExpression();
     if (expr.isKind(SyntaxKind.Identifier)) {
       const init = resolveSameRepoInitializer(expr);
-      if (init !== undefined) return elementRegistersGerman(init);
+      if (init !== undefined) return elementRegistersGerman(init, depth + 1);
       // Unresolvable or cross-repo identifier spread — fail-open rather than risk a false alarm.
       // Safe here: clientFeatures is already known to exist as an array, this only concerns
       // one of its elements — other elements are still checked.
       return true;
     }
-    return elementRegistersGerman(expr);
+    return elementRegistersGerman(expr, depth + 1);
   }
   if (el.isKind(SyntaxKind.ArrayLiteralExpression)) {
-    return el.getElements().some(elementRegistersGerman);
+    return el.getElements().some((element) => elementRegistersGerman(element, depth + 1));
   }
   // localeDeClient().translations (kumiko-studio auth-mount shape)
   if (el.isKind(SyntaxKind.PropertyAccessExpression)) {
-    return localeDeClientRef(el) || elementRegistersGerman(el.getExpression());
+    return localeDeClientRef(el) || elementRegistersGerman(el.getExpression(), depth + 1);
   }
   if (el.isKind(SyntaxKind.CallExpression)) {
     return localeDeClientRef(el.getExpression());
@@ -198,42 +217,90 @@ function clientFeaturesElements(prop: Node | undefined): Node[] | undefined {
   return arrayElementsOf(value);
 }
 
-const MAX_OPTIONS_SPREAD_DEPTH = 5;
-
-// Determines whether the mount call's options object — a literal right there,
-// or an identifier pointing at a same-repo constant (offlot's `APP_OPTIONS`
-// shape) — carries a `clientFeatures` property that registers German. Follows
-// `{ ...OTHER_OPTIONS, clientFeatures: [...] }` object spreads the same way
-// arrayElementsOf follows array spreads, so `clientFeatures` no longer has to
-// stay a literal at the call site to satisfy this guard (infra#734).
-//
-// Fail-closed (not fail-open) on an unresolvable/cross-repo spread source:
-// unlike a single array element, a whole unresolved options object could be
-// the only place `clientFeatures` lives — silently passing it would make the
-// guard blind again, exactly the risk infra#734 called out.
-function objectRegistersGermanClientFeatures(value: Node | undefined, depth = 0): boolean {
-  if (value === undefined || depth > MAX_OPTIONS_SPREAD_DEPTH) return false;
-  if (value.isKind(SyntaxKind.Identifier)) {
-    return objectRegistersGermanClientFeatures(resolveSameRepoInitializer(value), depth + 1);
+type ClientFeaturesLookup =
+  | { readonly found: false }
+  | { readonly found: true; readonly registersGerman: boolean };
+
+const CLIENT_FEATURES_ABSENT: ClientFeaturesLookup = { found: false };
+// An options source the guard cannot see into could hold (or override) clientFeatures —
+// unlike a single array element, treating it as "German registered" would blind the guard.
+const CLIENT_FEATURES_UNRESOLVABLE: ClientFeaturesLookup = { found: true, registersGerman: false };
+
+// `cond && {…}` and `cond ? {…} : {…}` spread one of their object branches (or nothing).
+function conditionalBranches(node: Node): Node[] | undefined {
+  if (node.isKind(SyntaxKind.ConditionalExpression))
+    return [node.getWhenTrue(), node.getWhenFalse()];
+  if (
+    node.isKind(SyntaxKind.BinaryExpression) &&
+    node.getOperatorToken().getKind() === SyntaxKind.AmpersandAmpersandToken
+  ) {
+    return [node.getRight()];
   }
-  if (!value.isKind(SyntaxKind.ObjectLiteralExpression)) return false;
-  const direct = value
-    .getProperties()
-    .find(
-      (p) =>
-        (p.isKind(SyntaxKind.PropertyAssignment) ||
-          p.isKind(SyntaxKind.ShorthandPropertyAssignment)) &&
-        p.getNameNode().getText() === "clientFeatures",
-    );
-  if (direct !== undefined)
-    return clientFeaturesElements(direct)?.some(elementRegistersGerman) ?? false;
-  return value
-    .getProperties()
-    .some(
-      (p) =>
-        p.isKind(SyntaxKind.SpreadAssignment) &&
-        objectRegistersGermanClientFeatures(p.getExpression(), depth + 1),
-    );
+  return undefined;
+}
+
+// Spreading these contributes no properties.
+function isNothingLiteral(node: Node): boolean {
+  return (
+    node.isKind(SyntaxKind.NullKeyword) ||
+    node.isKind(SyntaxKind.FalseKeyword) ||
+    (node.isKind(SyntaxKind.Identifier) && node.getText() === "undefined")
+  );
+}
+
+// Finds the clientFeatures property that wins at runtime in the mount call's
+// options — a literal right there, or an identifier pointing at a same-repo
+// constant (offlot's `APP_OPTIONS` shape). Properties are walked last to
+// first, mirroring object-spread override semantics: the last property or
+// spread that sets `clientFeatures` decides. Resolvable spreads without
+// `clientFeatures` are skipped; unresolvable/cross-repo ones are fail-closed.
+function lookupClientFeatures(value: Node | undefined, depth = 0): ClientFeaturesLookup {
+  if (value === undefined) return CLIENT_FEATURES_ABSENT;
+  if (depth > MAX_ALIAS_DEPTH) return CLIENT_FEATURES_UNRESOLVABLE;
+  const unwrapped = unwrapAsExpression(value);
+  if (unwrapped.isKind(SyntaxKind.Identifier)) {
+    const init = resolveSameRepoInitializer(unwrapped);
+    return init === undefined
+      ? CLIENT_FEATURES_UNRESOLVABLE
+      : lookupClientFeatures(init, depth + 1);
+  }
+  const branches = conditionalBranches(unwrapped);
+  if (branches !== undefined) {
+    const found = branches
+      .map((branch) => lookupClientFeatures(branch, depth + 1))
+      .filter((lookup) => lookup.found);
+    if (found.length === 0) return CLIENT_FEATURES_ABSENT;
+    // Which branch runs is unknown statically: German must be registered in every branch that sets clientFeatures.
+    return {
+      found: true,
+      registersGerman: found.every((lookup) => lookup.found && lookup.registersGerman),
+    };
+  }
+  if (isNothingLiteral(unwrapped)) return CLIENT_FEATURES_ABSENT;
+  if (!unwrapped.isKind(SyntaxKind.ObjectLiteralExpression)) return CLIENT_FEATURES_UNRESOLVABLE;
+  for (const prop of [...unwrapped.getProperties()].reverse()) {
+    if (
+      (prop.isKind(SyntaxKind.PropertyAssignment) ||
+        prop.isKind(SyntaxKind.ShorthandPropertyAssignment)) &&
+      prop.getNameNode().getText() === "clientFeatures"
+    ) {
+      return {
+        found: true,
+        registersGerman:
+          clientFeaturesElements(prop)?.some((el) => elementRegistersGerman(el)) ?? false,
+      };
+    }
+    if (prop.isKind(SyntaxKind.SpreadAssignment)) {
+      const spread = lookupClientFeatures(prop.getExpression(), depth + 1);
+      if (spread.found) return spread;
+    }
+  }
+  return CLIENT_FEATURES_ABSENT;
+}
+
+function objectRegistersGermanClientFeatures(value: Node | undefined): boolean {
+  const lookup = lookupClientFeatures(value);
+  return lookup.found && lookup.registersGerman;
 }
 
 function clientMountViolations(sf: SourceFile): GuardViolation[] {
@@ -258,7 +325,7 @@ function clientMountViolations(sf: SourceFile): GuardViolation[] {
     const init = attr.getInitializer();
     const expr = init?.isKind(SyntaxKind.JsxExpression) ? init.getExpression() : undefined;
     const elements = arrayElementsOf(expr);
-    const registered = elements?.some(elementRegistersGerman) ?? false;
+    const registered = elements?.some((el) => elementRegistersGerman(el)) ?? false;
     if (!registered) {
       violations.push({
         file: sf.getFilePath(),

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

@@ -64,8 +64,12 @@ const EXCLUDE =
 
 const FS_MODULES = new Set(["fs", "node:fs", "fs/promises", "node:fs/promises"]);
 
-type AllowEntry = {
-  readonly repo: string | "*";
+// Closed union (not `string | "*"`, which collapses to `string`): a typo in an
+// allowlist repo name must fail to compile instead of silently never matching.
+export type AllowlistRepoName = "kumiko-framework" | "kumiko-enterprise";
+
+export type AllowEntry = {
+  readonly repo: AllowlistRepoName | "*";
   readonly pattern: RegExp;
 };
 
@@ -77,6 +81,10 @@ const ALLOWLIST: readonly AllowEntry[] = [
   // machine, no request input as a path.
   { repo: "kumiko-framework", pattern: /^packages\/dev-server\/src\// },
 
+  // Guard runner + repo-manifest loader: read the scanned repo tree at dev/CI time, no request input as path.
+  { repo: "kumiko-framework", pattern: /^packages\/guards\/src\// },
+  { repo: "kumiko-framework", pattern: /^packages\/repo-manifest\/src\// },
+
   // CLI (@cosmicdrift/kumiko-cli): local dev/CI tooling reading the repo tree, no request input as path.
   { repo: "kumiko-framework", pattern: /^packages\/cli\/src\// },
 

package/src/guard-tenant-escalation.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * Guard: tenant / privilege-escalation safety. Four complementary checks.
+ * Guard: tenant / privilege-escalation safety. Three complementary checks.
  *
  *   A) **Role-input write handlers need an escalation test.** Any
  *      `defineWriteHandler` whose Zod schema takes a `role`/`roles` field lets
@@ -12,13 +12,8 @@
  *      because a feature's escalation test legitimately lives in another
  *      feature's __tests__ (e.g. user:update is covered by auth's multi-roles).
  *
- *   B) **tenantIdOverride handlers must use crossTenantOverrideDenied.** A
- *      payload `tenantIdOverride` on a TenantAdmin-reachable handler is the
- *      cross-tenant escape hatch; the SystemAdmin gate must go through the
- *      shared framework helper, not an inline `roles.includes("SystemAdmin")`
- *      check that the next handler forgets.
  *
- *   C) **Membership-derived JWT mints must strip reserved roles.** Command-time
+ *   B) **Membership-derived JWT mints must strip reserved roles.** Command-time
  *      validation rejects reserved roles from a membership, but a projection
  *      rebuild replays stored membership events through the apply path, not the
  *      handler — so a forbidden role can be resurrected into the projection. Any
@@ -27,7 +22,7 @@
  *      `invitationRole`) MUST call `stripForbiddenMembershipRoles`, the
  *      read-time backstop.
  *
- *   D) **TenantAdmin-reachable writes on a global user row need a membership
+ *   C) **TenantAdmin-reachable writes on a global user row need a membership
  *      check.** A `ctx.db.raw` read deliberately bypasses the auto-tenant-
  *      filter because User status is global. Combined with `access.admin`
  *      (which includes the tenant-scoped TenantAdmin) and a `userId` payload,
@@ -36,7 +31,7 @@
  *      isSystemAdminActor + tenantMembershipsTable shape lift-restriction.
  *      write.ts uses. restrict-account.write.ts shipped without it.
  *
- * All four are tripwires: false-negatives (a weak name match) are tolerated, a
+ * All three are tripwires: false-negatives (a weak name match) are tolerated, a
  * false-positive on the clean repo is not. Detection stays conservative.
  *
  * Usage:
@@ -128,32 +123,6 @@ export function findUntestedRoleHandlers(files: readonly SourceFile[]): RoleHand
   });
 }
 
-type OverrideHandler = { file: string; line: number };
-
-export function findOverrideHandlersMissingHelper(files: readonly SourceFile[]): OverrideHandler[] {
-  const out: OverrideHandler[] = [];
-  for (const sf of files) {
-    if (TEST_FILE_RE.test(sf.getFilePath())) continue;
-    for (const pa of sf.getDescendantsOfKind(SyntaxKind.PropertyAssignment)) {
-      if (pa.getName() !== "tenantIdOverride") continue;
-      if (pa.getInitializer()?.getText().startsWith("z.") !== true) continue;
-      // Scope the check to the enclosing defineWriteHandler(...) call, not
-      // the whole file — a file with two override handlers where only one
-      // calls crossTenantOverrideDenied must still flag the other.
-      const handlerCall = pa.getFirstAncestor(
-        (a) =>
-          a.getKind() === SyntaxKind.CallExpression &&
-          a.asKindOrThrow(SyntaxKind.CallExpression).getExpression().getText() ===
-            "defineWriteHandler",
-      );
-      const scopeText = handlerCall?.getText() ?? sf.getFullText();
-      if (scopeText.includes("crossTenantOverrideDenied")) continue;
-      out.push({ file: sf.getFilePath(), line: pa.getStartLineNumber() });
-    }
-  }
-  return out;
-}
-
 // A session built for a JWT — either the auth-session result shape or a typed
 // SessionUser literal.
 const SESSION_MINT = /kind:\s*"auth-session"|:\s*SessionUser\s*=\s*\{/;
@@ -232,7 +201,7 @@ export function findGlobalUserWritesMissingMembershipCheck(
       // `name` is only used for the violation message, not the security
       // check itself — a factory-built handler with a non-literal name
       // expression (`name: enable ? "enable" : "disable"`) must not skip
-      // Check D just because literalStringOf() can't resolve it.
+      // Check C just because literalStringOf() can't resolve it.
       const name = literalStringOf(obj.getProperty("name"));
       const schema = obj.getProperty("schema");
       const accessProp = obj.getProperty("access");
@@ -267,7 +236,7 @@ export const guard: AstGuard = {
   name: "Tenant-Escalation Guard",
   scan: SCAN,
   security: true,
-  hint: "Role-input handlers need an escalation test (assert a reserved role is rejected); tenantIdOverride handlers must call crossTenantOverrideDenied; membership-derived JWT mints must call stripForbiddenMembershipRoles; TenantAdmin-reachable ctx.db.raw user writes must check the target's membership.",
+  hint: "Role-input handlers need an escalation test (assert a reserved role is rejected); membership-derived JWT mints must call stripForbiddenMembershipRoles; TenantAdmin-reachable ctx.db.raw user writes must check the target's membership.",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 
@@ -279,15 +248,6 @@ export const guard: AstGuard = {
       });
     }
 
-    for (const o of findOverrideHandlersMissingHelper(files)) {
-      violations.push({
-        file: path.relative(ROOT, o.file),
-        line: o.line,
-        message:
-          "handler exposes tenantIdOverride but never calls crossTenantOverrideDenied — route the SystemAdmin gate through the shared helper.",
-      });
-    }
-
     for (const m of findMembershipMintsMissingStrip(files)) {
       violations.push({
         file: path.relative(ROOT, m.file),

package/src/guard-test-timeouts.ts

@@ -3,8 +3,11 @@
  * Guard: tests wait for a condition, not for time. Flags, in test files and
  * Playwright specs/helpers:
  *   (a) `test.setTimeout(...)`, `test.slow(...)`, `setDefaultTimeout(...)`,
- *       `*.describe.configure({ timeout })` — raising a timeout hides the
- *       cause of a slow or flaky test
+ *       `*.describe.configure({ timeout })`, and a timeout argument on
+ *       `test`/`it`/`describe` calls (`test(name, fn, 30_000)`,
+ *       `test(name, fn, { timeout })`, also via `.skip/.only/.if()/.each()()`
+ *       and renamed/namespace `bun:test` imports) — raising a timeout hides
+ *       the cause of a slow or flaky test
  *   (b) `<page>.waitForTimeout(...)` — a fixed sleep instead of a condition
  *   (c) sleep loops — a `while`/`do`/`for`/`for…of`/`for…in` whose body calls
  *       `sleep(...)`/`Bun.sleep(...)` or awaits a `new Promise` that only
@@ -70,6 +73,9 @@ const TIMEOUT_RAISING_CALLEES: ReadonlySet<string> = new Set(["test.setTimeout",
 const SET_TIMEOUT_CALLEE = /(^|\.)setTimeout$/;
 const SET_DEFAULT_TIMEOUT_CALLEE = /(^|\.)setDefaultTimeout$/;
 const DESCRIBE_CONFIGURE_CALLEE = /(^|\.)describe\.configure$/;
+const TEST_FRAMEWORK_MODULES: ReadonlySet<string> = new Set(["bun:test", "@playwright/test"]);
+const TEST_DECLARATION_CALLEE =
+  /^(test|it|describe)(\.(skip|only|todo|if|each|failing|concurrent|serial|skipIf|runIf|todoIf))*$/;
 
 export interface Finding {
   file: string;
@@ -143,9 +149,58 @@ function hasTimeoutProperty(node: Node | undefined): boolean {
   );
 }
 
-function raisedTimeoutReason(call: CallExpression): string | undefined {
+// Maps local names imported from the test framework to their exported name;
+// "" marks a namespace import (`import * as bt`), whose member access is stripped.
+function testFrameworkAliases(sf: SourceFile): ReadonlyMap<string, string> {
+  const aliases = new Map<string, string>();
+  for (const decl of sf.getImportDeclarations()) {
+    if (!TEST_FRAMEWORK_MODULES.has(decl.getModuleSpecifierValue())) continue;
+    const namespaceImport = decl.getNamespaceImport();
+    if (namespaceImport !== undefined) aliases.set(namespaceImport.getText(), "");
+    for (const named of decl.getNamedImports()) {
+      const alias = named.getAliasNode();
+      if (alias !== undefined) aliases.set(alias.getText(), named.getName());
+    }
+  }
+  return aliases;
+}
+
+function canonicalCalleeText(text: string, aliases: ReadonlyMap<string, string>): string {
+  const [head = "", ...rest] = text.split(".");
+  const imported = aliases.get(head);
+  if (imported === undefined) return text;
+  return (imported === "" ? rest : [imported, ...rest]).join(".");
+}
+
+// `test.each(rows)(…)` and `test.if(cond)(…)` call the result of a call.
+function declarationBaseCallee(callee: Node): Node {
+  return Node.isCallExpression(callee) ? declarationBaseCallee(callee.getExpression()) : callee;
+}
+
+function isTimeoutArgument(arg: Node): boolean {
+  if (Node.isObjectLiteralExpression(arg)) return hasTimeoutProperty(arg);
+  return !Node.isArrowFunction(arg) && !Node.isFunctionExpression(arg);
+}
+
+function declarationTimeoutReason(
+  call: CallExpression,
+  aliases: ReadonlyMap<string, string>,
+): string | undefined {
+  const base = canonicalCalleeText(declarationBaseCallee(call.getExpression()).getText(), aliases);
+  if (!TEST_DECLARATION_CALLEE.test(base)) return undefined;
+  const [, , ...extra] = call.getArguments();
+  if (!extra.some(isTimeoutArgument)) return undefined;
+  return `${base}(…, timeout) raises the timeout instead of fixing the cause`;
+}
+
+function raisedTimeoutReason(
+  call: CallExpression,
+  aliases: ReadonlyMap<string, string>,
+): string | undefined {
   const callee = call.getExpression();
-  const calleeText = callee.getText();
+  const calleeText = canonicalCalleeText(callee.getText(), aliases);
+  const declarationReason = declarationTimeoutReason(call, aliases);
+  if (declarationReason !== undefined) return declarationReason;
   if (TIMEOUT_RAISING_CALLEES.has(calleeText) || SET_DEFAULT_TIMEOUT_CALLEE.test(calleeText)) {
     return `${calleeText}(…) raises the timeout instead of fixing the cause`;
   }
@@ -178,8 +233,9 @@ export function scanTimeouts(
     if (reported === undefined) return;
     findings.push({ file, line: node.getStartLineNumber(), message: reported });
   };
+  const aliases = testFrameworkAliases(sf);
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const reason = raisedTimeoutReason(call);
+    const reason = raisedTimeoutReason(call, aliases);
     if (reason !== undefined) add(call, reason);
   }
   for (const [kind, label] of LOOP_LABELS) {