@cosmicdrift/kumiko-guards 0.377.0 → 0.379.0

package/README.md

@@ -67,8 +67,9 @@ drops it.
 A POSIX-sh pre-push hook, wired by copying the package's `hooks/pre-push`
 shim to `.husky/pre-push`. The shim execs the nearest executable
 `node_modules/.bin/kumiko-pre-push` from the repo root upwards (so worktrees
-without their own `node_modules` resolve via the parent install) and fails
-closed with a `bun install` hint when none exists. Inside
+without their own `node_modules` resolve via the parent install, up to and
+including `$HOME`, skipping ancestors owned by another user or writable by
+group/others) and fails closed with a `bun install` hint when none exists. Inside
 the cosmicdriftgamestudio parent workspace it runs a scoped `bun check` for
 the pushing repo only; in a standalone clone it runs the repo's own
 `package.json` `test` script. From a `.wt/<name>` worktree under the parent

package/hooks/pre-push

@@ -8,15 +8,35 @@ fi
 # Walk up so a worktree without its own node_modules resolves via the parent
 # install, but not past an enclosing repository: a bin above that boundary
 # belongs to another project. `[ -x ]` also skips a broken (uninstalled) symlink.
+# A bin in an ancestor that is owned by someone else or group/world-writable
+# (/tmp, /Users/Shared) is attacker-plantable and must never be exec'd, and
+# $HOME is the upper trust boundary (inclusive), compared by physical path
+# because git prints REPO_ROOT resolved: a trailing slash or a symlinked home
+# would otherwise never match and the walk would continue to /.
+HOME_BOUND=""
+if [ -n "$HOME" ] && [ -d "$HOME" ]; then
+  HOME_BOUND="$(cd "$HOME" 2>/dev/null && pwd -P)"
+fi
 BIN=""
 DIR="$REPO_ROOT"
 while true; do
-  CANDIDATE="$DIR/node_modules/.bin/kumiko-pre-push"
-  if [ -x "$CANDIDATE" ]; then
-    BIN="$CANDIDATE"
-    break
+  TRUSTED=1
+  if [ "$DIR" != "$REPO_ROOT" ]; then
+    if [ ! -O "$DIR" ] || [ -n "$(find "$DIR" -maxdepth 0 \( -perm -0020 -o -perm -0002 \) -print 2>/dev/null)" ]; then
+      TRUSTED=0
+    fi
+  fi
+  if [ "$TRUSTED" = 1 ]; then
+    BIN_DIR="$DIR/node_modules/.bin"
+    CANDIDATE="$BIN_DIR/kumiko-pre-push"
+    # The bin dir itself must be user-owned and not group/world-writable, or a
+    # planted entry could replace the real bin.
+    if [ -x "$CANDIDATE" ] && [ -O "$BIN_DIR" ] && [ -z "$(find "$BIN_DIR" -maxdepth 0 \( -perm -0020 -o -perm -0002 \) -print 2>/dev/null)" ]; then
+      BIN="$CANDIDATE"
+      break
+    fi
   fi
-  if [ "$DIR" = "/" ]; then
+  if [ "$DIR" = "/" ] || { [ -n "$HOME_BOUND" ] && [ "$DIR" = "$HOME_BOUND" ]; }; then
     break
   fi
   if [ "$DIR" != "$REPO_ROOT" ] && [ -e "$DIR/.git" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.377.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.377.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,59 @@
 [
+  {
+    "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",
+    "title": "Direct-entity-writes guard catches imported event-store tables",
+    "detail": "Table identifiers are resolved through import aliases to their definition, so direct insert/update/delete on an event-store table imported from another file of the scanned repo is no longer missed. Findings now show the full receiver (ctx.db). Existing consumers can get new findings that were previously hidden."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Faster, leaner guard run",
+    "detail": "Four AST guards skip files that cannot contain their anchor names before walking every node, and Direct-Entity-Writes only resolves symbols for table arguments named like an event-sourced table. Findings are identical."
+  },
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Pre-push shim skips untrusted ancestors and stops at $HOME",
+    "detail": "The shim walked up to / and could exec a kumiko-pre-push planted in /tmp or another shared directory. The walk now ends at $HOME and skips ancestors that another user owns or that group or others can write to."
+  },
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Pre-push shim also vets node_modules/.bin",
+    "detail": "The shim now requires node_modules/.bin itself to be owned by the user and not group or world writable before executing kumiko-pre-push from it, in the guards hook and the dev-server husky template."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",

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-api-object-form.ts

@@ -41,6 +41,8 @@ const REGISTRAR_TYPE_MARKER = "FeatureRegistrar";
 const FEATURE_FACTORY_NAME = "defineFeature";
 const REGISTRAR_RECEIVER_NAMES: ReadonlySet<string> = new Set(["r", "registrar"]);
 const EXCLUDED_PATH = /(\/__tests__\/fixtures\/|\.d\.ts$)/;
+// Cheap text superset of what positionalCallMethod can match; skips the AST walk for most files.
+const REGISTRAR_METHOD_ACCESS = new RegExp(`\\.\\s*(?:${REGISTRAR_METHODS.join("|")})\\b`);
 const UPGRADE_HINT = "run `bun kumiko-upgrade --apply` (codemod object-form)";
 
 type ReceiverResolution = "registrar" | "other" | "unresolved";
@@ -145,39 +147,51 @@ function positionalCallMethod(call: CallExpression): RegistrarMethod | undefined
 
 export type ObjectFormFinding = { file: string; line: number; message: string };
 
+function positionalCallFindings(sf: SourceFile, file: string): ObjectFormFinding[] {
+  if (!REGISTRAR_METHOD_ACCESS.test(sf.getFullText())) return [];
+  const out: ObjectFormFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const method = positionalCallMethod(call);
+    if (method === undefined) continue;
+    out.push({
+      file,
+      line: call.getStartLineNumber(),
+      message: `positional r.${method}(…) removed in 0.366 — ${UPGRADE_HINT}`,
+    });
+  }
+  return out;
+}
+
+function crudFindings(sf: SourceFile, file: string): ObjectFormFinding[] {
+  // Every crud local name is CRUD_FUNCTION_NAME itself or an import alias of it.
+  if (!sf.getFullText().includes(CRUD_FUNCTION_NAME)) return [];
+  const crudNames = crudLocalNames(sf);
+  const out: ObjectFormFinding[] = [];
+  for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
+    if (!crudNames.has(id.getText())) continue;
+    const parent = id.getParent();
+    const isCall = Node.isCallExpression(parent) && parent.getExpression() === id;
+    const isImportOrExport =
+      Node.isImportSpecifier(parent) ||
+      Node.isExportSpecifier(parent) ||
+      id.getFirstAncestorByKind(SyntaxKind.ImportDeclaration) !== undefined;
+    if (!isCall && !isImportOrExport) continue;
+    if (Node.isImportSpecifier(parent) && parent.getAliasNode() === id) continue;
+    out.push({
+      file,
+      line: id.getStartLineNumber(),
+      message: `registerEntityCrud removed in 0.366 — use r.crud(…); ${UPGRADE_HINT}`,
+    });
+  }
+  return out;
+}
+
 export function findPositionalRegistrarCalls(files: readonly SourceFile[]): ObjectFormFinding[] {
   const out: ObjectFormFinding[] = [];
   for (const sf of files) {
     if (EXCLUDED_PATH.test(sf.getFilePath())) continue;
     const file = relativeToCwd(sf.getFilePath());
-    const crudNames = crudLocalNames(sf);
-
-    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      const method = positionalCallMethod(call);
-      if (method === undefined) continue;
-      out.push({
-        file,
-        line: call.getStartLineNumber(),
-        message: `positional r.${method}(…) removed in 0.366 — ${UPGRADE_HINT}`,
-      });
-    }
-
-    for (const id of sf.getDescendantsOfKind(SyntaxKind.Identifier)) {
-      if (!crudNames.has(id.getText())) continue;
-      const parent = id.getParent();
-      const isCall = Node.isCallExpression(parent) && parent.getExpression() === id;
-      const isImportOrExport =
-        Node.isImportSpecifier(parent) ||
-        Node.isExportSpecifier(parent) ||
-        id.getFirstAncestorByKind(SyntaxKind.ImportDeclaration) !== undefined;
-      if (!isCall && !isImportOrExport) continue;
-      if (Node.isImportSpecifier(parent) && parent.getAliasNode() === id) continue;
-      out.push({
-        file,
-        line: id.getStartLineNumber(),
-        message: `registerEntityCrud removed in 0.366 — use r.crud(…); ${UPGRADE_HINT}`,
-      });
-    }
+    out.push(...positionalCallFindings(sf, file), ...crudFindings(sf, file));
   }
   return out;
 }

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 };
   },