@cosmicdrift/kumiko-guards 0.388.0 → 0.390.0

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

@@ -92,7 +92,7 @@ const ALLOWLIST: readonly AllowEntry[] = [
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/migrations\/kumiko-drift\.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\/upgrade-cli(-internals)?\.ts$/ },
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/es-ops\/runner\.ts$/ },
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/db\/migrate-generator\.ts$/ },
   { repo: "kumiko-framework", pattern: /^packages\/framework\/src\/db\/migrate-runner\.ts$/ },
@@ -103,7 +103,7 @@ const ALLOWLIST: readonly AllowEntry[] = [
   },
   {
     repo: "kumiko-framework",
-    pattern: /^packages\/framework\/src\/engine\/codemod\/pipeline-codemod\.ts$/,
+    pattern: /^packages\/feature-ast\/src\/codemod\/pipeline-codemod\.ts$/,
   },
 
   // server-runtime: prod bundle build + static asset delivery from the
@@ -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-restricted-symbols.ts

@@ -37,7 +37,7 @@ const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 const RESTRICTED_SYMBOLS = new Set([
   "getUnscopedAggregateStreamMaxVersion",
   "getUnscopedAggregateStreamTenant",
-  // Appends any event type without the feature-ownership check of ctx.appendEvent and without
+  // Appends any event type without the feature-ownership check of ctx.events.append and without
   // an audited unsafeRaw escape hatch, so new callers need an explicit allowlist entry.
   "appendEventInTenantDb",
   "getStreamVersionInTenantDb",
@@ -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 events.unsafeAppend.
+  /^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$/,
@@ -128,7 +130,7 @@ function findRestrictedSymbolReferences(sf: SourceFile): Violation[] {
 export const guard: AstGuard = {
   name: "Restricted-Symbols Guard",
   scan: SCAN,
-  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.appendEvent — only framework-internal coordination code may use them. createTenantDataDestroyDb grants direct writes on event-fed tables and belongs to the tenant-destroy stage only. withExecutorManagedWritesForTests is the test-seed seam behind seedRow/deleteRows and must not reach runtime code. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
+  hint: 'getUnscopedAggregateStream{MaxVersion,Tenant} is an existence oracle for foreign tenants — only seed-/system-internal code may reference them. appendEventInTenantDb/getStreamVersionInTenantDb bypass the feature-ownership check of ctx.events.append — only framework-internal coordination code may use them. createTenantDataDestroyDb grants direct writes on event-fed tables and belongs to the tenant-destroy stage only. withExecutorManagedWritesForTests is the test-seed seam behind seedRow/deleteRows and must not reach runtime code. New caller needed? Extend the allowlist in guard-restricted-symbols.ts, with a reason. Known gap: `export * from "...event-store"` is not detected (named imports, re-exports, and namespace property access are covered).',
   run(files, roots = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-rls-session-settings.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env bun
+/**
+ * Guard: row-level-security settings are transaction-local and written in one place.
+ *
+ * The scope lives in the `kumiko.*` settings that `packages/framework/src/db/queries/rls-scope.ts`
+ * sets per statement transaction. A session-level setting survives on a pooled connection and leaks
+ * one request's scope into the next, so in every source and test string:
+ *
+ * 1. `SET kumiko.…` / `SET SESSION kumiko.…` is flagged (use `SET LOCAL`).
+ * 2. Every `set_config` passes the literal `true` as is_local.
+ * 3. Outside rls-scope.ts, non-test code writes no `kumiko.*` setting at all, and a `set_config`
+ *    with a dynamic setting name is flagged because it cannot be proven to leave `kumiko.*` alone.
+ *
+ * `.sql` files (consumer migrations) are checked statement by statement under the same rules.
+ *
+ * Usage:
+ *   bun guards/guard-rls-session-settings.ts
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { Glob } from "bun";
+import { Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  isAllowlisted,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+import { TEST_FILE_RE } from "./_lib/test-file";
+
+const SCAN: ScanSpec = {
+  kinds: ALL_REPO_KINDS,
+  scope: "source+tests",
+  extensions: ["ts", "tsx"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+
+const SCOPE_WRITER = [/^packages\/framework\/src\/db\/queries\/rls-scope\.ts$/];
+
+// The assignment tail separates SQL from prose such as "Set kumiko.deploy.infraRef to an infra tag".
+const ASSIGNMENT = String.raw`"?kumiko\.[\w.]+"?\s*(?:=|TO\s+['"$\d])`;
+const SESSION_SET_RE = new RegExp(String.raw`\bSET\s+(?:SESSION\s+)?${ASSIGNMENT}`, "i");
+const LOCAL_SET_RE = new RegExp(String.raw`\bSET\s+LOCAL\s+${ASSIGNMENT}`, "i");
+const SET_CONFIG_CALL_RE = /\bset_config\s*\(/gi;
+
+function isTestFile(rel: string): boolean {
+  return rel.split("/").includes("__tests__") || TEST_FILE_RE.test(rel);
+}
+
+const QUOTES = "'\"`";
+const OPENERS = "([{";
+const CLOSERS = ")]}";
+
+// Top-level comma-separated arguments of the call whose "(" ends right before `from`.
+function callArguments(text: string, from: number): string[] {
+  const args: string[] = [];
+  let depth = 0;
+  let quote: string | undefined;
+  let current = "";
+  for (let i = from; i < text.length; i++) {
+    const c = text.charAt(i);
+    if (quote !== undefined) {
+      current += c;
+      if (c === quote) quote = undefined;
+      continue;
+    }
+    if (QUOTES.includes(c)) quote = c;
+    else if (OPENERS.includes(c)) depth++;
+    else if (CLOSERS.includes(c)) {
+      if (depth === 0) break;
+      depth--;
+    } else if (c === "," && depth === 0) {
+      args.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += c;
+  }
+  args.push(current.trim());
+  return args;
+}
+
+function setConfigCalls(text: string): string[][] {
+  return [...text.matchAll(SET_CONFIG_CALL_RE)].map((m) =>
+    callArguments(text, m.index + m[0].length).map((arg) => arg.toLowerCase()),
+  );
+}
+
+function isKumikoLiteral(arg: string | undefined): boolean {
+  return arg !== undefined && /^['"`]kumiko\./.test(arg);
+}
+
+function isStringLiteralArgument(arg: string | undefined): boolean {
+  return arg !== undefined && /^['"`]/.test(arg);
+}
+
+function setConfigMessages(text: string, isScopeWriter: boolean, isTest: boolean): string[] {
+  const calls = setConfigCalls(text);
+  const messages: string[] = [];
+  if (calls.some((args) => args[2] !== "true")) {
+    messages.push(
+      "set_config must pass the literal true as is_local, anything else can be session-level",
+    );
+  }
+  if (isScopeWriter || isTest) return messages;
+  if (calls.some((args) => isKumikoLiteral(args[0]))) {
+    messages.push("only rls-scope.ts may write a kumiko.* setting");
+  }
+  if (calls.some((args) => !isStringLiteralArgument(args[0]))) {
+    messages.push(
+      "set_config with a dynamic setting name cannot be proven to leave kumiko.* alone",
+    );
+  }
+  return messages;
+}
+
+function violationsInText(text: string, rel: string): string[] {
+  const isScopeWriter = isAllowlisted(rel, SCOPE_WRITER);
+  const isTest = isTestFile(rel);
+  const messages: string[] = [];
+  if (SESSION_SET_RE.test(text)) {
+    messages.push("SET / SET SESSION on a kumiko.* setting is session-level; use SET LOCAL");
+  }
+  if (!isScopeWriter && !isTest && LOCAL_SET_RE.test(text)) {
+    messages.push("only rls-scope.ts may write a kumiko.* setting");
+  }
+  return [...messages, ...setConfigMessages(text, isScopeWriter, isTest)];
+}
+
+function isStringLike(node: Node): boolean {
+  return (
+    Node.isStringLiteral(node) ||
+    Node.isNoSubstitutionTemplateLiteral(node) ||
+    Node.isTemplateExpression(node)
+  );
+}
+
+function findSessionSettings(sf: SourceFile, rel: string) {
+  const found: Array<{ line: number; message: string }> = [];
+  for (const node of sf.getDescendants()) {
+    if (!isStringLike(node)) continue;
+    // A template's own spans are visited as separate nodes; its full text is checked once here.
+    if (node.getParent()?.getKind() === SyntaxKind.TemplateSpan) continue;
+    for (const message of violationsInText(node.getText(), rel)) {
+      found.push({ line: node.getStartLineNumber(), message: `[rls-session-setting] ${message}` });
+    }
+  }
+  return found;
+}
+
+const SQL_IGNORED_DIRS = /(^|\/)(node_modules|\.wt|\.git|dist)(\/|$)/;
+
+// Statements split on ";" with their start line; "--" comment lines are blanked so prose in them never matches.
+export function findSqlSessionSettings(sql: string, rel: string) {
+  const found: Array<{ line: number; message: string }> = [];
+  const code = sql.replace(/^\s*--.*$/gm, "");
+  let line = 1;
+  for (const statement of code.split(";")) {
+    const startLine =
+      line + countNewlines(statement.slice(0, statement.length - statement.trimStart().length));
+    for (const message of violationsInText(statement, rel)) {
+      found.push({ line: startLine, message: `[rls-session-setting] ${message}` });
+    }
+    line += countNewlines(statement);
+  }
+  return found;
+}
+
+function countNewlines(text: string): number {
+  return text.split("\n").length - 1;
+}
+
+function sqlFilesOf(rootDir: string): string[] {
+  // skip: in-memory roots of guard tests have no directory
+  if (!existsSync(rootDir)) return [];
+  return [...new Glob("**/*.sql").scanSync({ cwd: rootDir })].filter(
+    (file) => !SQL_IGNORED_DIRS.test(file),
+  );
+}
+
+export const guard: AstGuard = {
+  name: "RLS-Session-Settings Guard",
+  scan: SCAN,
+  hint: "Row-level-security settings must be transaction-local: use SET LOCAL or pass true as the third set_config argument. Only packages/framework/src/db/queries/rls-scope.ts writes the kumiko.* scope; tests may use SET LOCAL.",
+  run(files, roots = resolveRepoRoots()) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+    for (const sf of files) {
+      const rel = relFromRepoRoot(sf.getFilePath(), roots);
+      for (const f of findSessionSettings(sf, rel)) violations.push({ file: rel, ...f });
+    }
+    for (const root of roots) {
+      for (const file of sqlFilesOf(root.absPath)) {
+        const sql = readFileSync(`${root.absPath}/${file}`, "utf8");
+        for (const f of findSqlSessionSettings(sql, file)) violations.push({ file, ...f });
+      }
+    }
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

package/src/guard-schema-cli-features.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env bun
+/**
+ * Guard: a consumer's `runSchemaCli(...)` call must pass `features: FEATURES` imported from `kumiko/schema`.
+ *
+ * `allAppFeatures(config)` is raw (no bundled foundation: config, user, tenant, auth-email-password).
+ * Only the managed `kumiko/schema.ts` composes it. With a raw or hand-built list the projection rebuild
+ * after the migrations fails at deploy with "Feature X requires feature Y". Repos without
+ * `kumiko/schema.ts` and the framework repo are not applicable. `composeEnvSchema` inputs are not checked.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { Node, Project, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
+import type { RepoRoot } from "./_lib/roots";
+import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
+
+const SCAN: ScanSpec = { scope: "source", extensions: ["ts"], kinds: ["app", "library"] };
+
+const SCHEMA_MODULE_REL = "kumiko/schema.ts";
+const SCHEMA_MODULE_SPECIFIER = /(^|\/)kumiko\/schema(\.ts)?$/;
+const SCHEMA_CLI_CALL = "runSchemaCli";
+const OPTIONS_ARG_INDEX = 3;
+const FEATURES_EXPORT = "FEATURES";
+const FOUND_SNIPPET_MAX = 60;
+
+const FIX_HINT =
+  'Fix: `import { FEATURES } from "../kumiko/schema";` and pass `features: FEATURES`. ' +
+  "allAppFeatures() is raw and a locally composed list drifts from kumiko/schema, which fails the rebuild at deploy.";
+
+export type SchemaCliFinding = {
+  readonly line: number;
+  readonly message: string;
+};
+
+function importOf(sf: SourceFile, localName: string): { name: string; module: string } | undefined {
+  for (const imp of sf.getImportDeclarations()) {
+    for (const spec of imp.getNamedImports()) {
+      if ((spec.getAliasNode()?.getText() ?? spec.getName()) === localName) {
+        return { name: spec.getName(), module: imp.getModuleSpecifierValue() };
+      }
+    }
+  }
+  return undefined;
+}
+
+function isSchemaFeaturesImport(sf: SourceFile, localName: string): boolean {
+  const imported = importOf(sf, localName);
+  return (
+    imported !== undefined &&
+    imported.name === FEATURES_EXPORT &&
+    SCHEMA_MODULE_SPECIFIER.test(imported.module)
+  );
+}
+
+function snippet(node: Node): string {
+  const flat = node.getText().replace(/\s+/g, " ");
+  return flat.length > FOUND_SNIPPET_MAX ? `${flat.slice(0, FOUND_SNIPPET_MAX)}...` : flat;
+}
+
+function featuresValueOf(options: Node): Node | undefined | "no-literal" {
+  if (!Node.isObjectLiteralExpression(options)) return "no-literal";
+  const property = options.getProperty("features");
+  if (property === undefined) return undefined;
+  if (Node.isPropertyAssignment(property)) return property.getInitializer();
+  if (Node.isShorthandPropertyAssignment(property)) return property.getNameNode();
+  return "no-literal";
+}
+
+function isRunSchemaCliCall(sf: SourceFile, callee: Node): boolean {
+  if (!Node.isIdentifier(callee)) return false;
+  const localName = callee.getText();
+  return (importOf(sf, localName)?.name ?? localName) === SCHEMA_CLI_CALL;
+}
+
+function problemOf(sf: SourceFile, optionsArg: Node | undefined): string | undefined {
+  if (optionsArg === undefined) {
+    return `${SCHEMA_CLI_CALL} has no options argument, so the projection rebuild is skipped`;
+  }
+  const value = featuresValueOf(optionsArg);
+  if (value === "no-literal") {
+    return `${SCHEMA_CLI_CALL} options are not an object literal with a \`features\` property`;
+  }
+  if (value === undefined) return `${SCHEMA_CLI_CALL} options have no \`features\` property`;
+  if (Node.isIdentifier(value) && isSchemaFeaturesImport(sf, value.getText())) return undefined;
+  return `${SCHEMA_CLI_CALL} gets \`features: ${snippet(value)}\`, not ${FEATURES_EXPORT} from kumiko/schema`;
+}
+
+export function findSchemaCliFeatureProblems(sf: SourceFile): SchemaCliFinding[] {
+  const findings: SchemaCliFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (!isRunSchemaCliCall(sf, call.getExpression())) continue;
+    const problem = problemOf(sf, call.getArguments()[OPTIONS_ARG_INDEX]);
+    if (problem !== undefined) {
+      findings.push({ line: call.getStartLineNumber(), message: `${problem}. ${FIX_HINT}` });
+    }
+  }
+  return findings;
+}
+
+function hasSchemaModule(root: RepoRoot): boolean {
+  return existsSync(join(root.absPath, SCHEMA_MODULE_REL));
+}
+
+export const check: RepoCheck = {
+  name: "Schema CLI Features Guard",
+  hint:
+    "Pass `features: FEATURES` imported from kumiko/schema to runSchemaCli; allAppFeatures() is raw " +
+    "and breaks the projection rebuild at deploy.",
+  run(roots) {
+    const applicable = roots.filter((root) => root.kind !== "framework" && hasSchemaModule(root));
+    if (applicable.length === 0) return { violations: [], matchedFiles: 0, notApplicable: true };
+
+    // Manifest excludes must not hide bin/kumiko.ts: kumiko-studio and phronexsis exclude it from other guards.
+    const paths = scanFiles(SCAN, applicable, { security: true });
+    const project = new Project({ skipAddingFilesFromTsConfig: true, useInMemoryFileSystem: true });
+    const violations: GuardViolation[] = [];
+    for (const absPath of paths) {
+      const text = readFileSync(absPath, "utf-8");
+      if (!text.includes(SCHEMA_CLI_CALL)) continue;
+      const sf = project.createSourceFile(absPath, text, { overwrite: true });
+      for (const finding of findSchemaCliFeatureProblems(sf)) {
+        violations.push({
+          file: relative(process.cwd(), absPath),
+          line: finding.line,
+          message: finding.message,
+        });
+      }
+    }
+    return { violations, matchedFiles: paths.length, notApplicable: false };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/guard-silent-skip.ts

@@ -118,7 +118,7 @@ function classifyEnclosing(_ret: ReturnStatement, fn: Node): SkipSite["enclosing
  * Policy: a bare `return;` needs one of the following markers right before it
  * — otherwise it is flagged.
  *
- *   (a) Log call:     ctx.log?.debug(...), logger.debug(...), context.log?.info(...)
+ *   (a) Log call:     ctx.obs.log.debug(...), logger.debug(...), context.log?.info(...)
  *   (b) Skip comment: // skip: <reason>
  *   (c) Throw escape: preceded by a throw (the return is dead code, should go)
  *

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-es-row-writes.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+/**
+ * Guard: framework tests do not write event-sourced rows through the seed bypass.
+ * Flags calls to updateRows/deleteRows imported from kumiko-testing/helpers, seedRow on
+ * an entity table the file builds itself, and raw DELETE/UPDATE SQL on read_ tables,
+ * kumiko_events or such an entity table: they change the projection only, so the event
+ * log drifts from it and a rebuild undoes the write.
+ *
+ * Usage:
+ *   bun packages/guards/src/guard-test-es-row-writes.ts
+ */
+import type { SourceFile } from "ts-morph";
+import { Node, SyntaxKind } from "ts-morph";
+import {
+  type AstGuard,
+  type GuardViolation,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
+import { findRawSqlWrites, findSeedRowOnEntityTables } from "./_lib/test-es-raw-writes";
+
+// Framework repo only: the consumer repos still call updateRows/deleteRows in their
+// tests, so rolling this out there needs a migration of those call sites first.
+const SCAN: ScanSpec = { scope: "tests", extensions: ["ts"], kinds: ["framework"] };
+
+const ALLOWLIST: readonly RegExp[] = [
+  // Home of the helpers.
+  /^packages\/testing\/src\//,
+  // The guard's own fixtures.
+  /^packages\/guards\/src\/__tests__\//,
+  // Simulates event-less legacy rows for the backfill.
+  /^packages\/bundled-features\/src\/user-data-rights\/__tests__\/read-users-rebuild-survives-lifecycle\.integration\.test\.ts$/,
+  // Stands in for the handover move, which itself writes directly.
+  /^packages\/bundled-features\/src\/files-tenant-data\/__tests__\/hooks\.integration\.test\.ts$/,
+  // Corrupts ciphertext on the projection to exercise the skip path.
+  /^packages\/bundled-features\/src\/inbound-mail-foundation\/__tests__\/watch-supervisor\.integration\.test\.ts$/,
+  // Primitive test of the TenantDb where-merge.
+  /^packages\/framework\/src\/db\/__tests__\/tenant-db-where-merge\.integration\.test\.ts$/,
+  // The entity cache is invalidated on the helper path, so only a projection-only write leaves it stale.
+  /^packages\/framework\/src\/__tests__\/full-stack\.integration\.test\.ts$/,
+  // Corrupt, drift or poison a projection row on purpose to exercise the read, repair or skip path.
+  /^packages\/bundled-features\/src\/auth-mfa\/__tests__\/reencrypt-job\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/config\/__tests__\/config\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/custom-fields\/__tests__\/custom-fields\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/custom-fields\/__tests__\/field-access\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/inbound-mail-foundation\/__tests__\/inbound-mail-foundation\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/event-store-executor\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/event-store-executor-write-verbs\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/event-store\/__tests__\/backfill-pii\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/search-consumer-named-events\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/search\/__tests__\/search-pii-derived-index\.integration\.test\.ts$/,
+  // Seed an event-less legacy row that the code under test must adopt or upcast.
+  /^packages\/framework\/src\/__tests__\/reference-data\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/load-aggregate-query\.integration\.test\.ts$/,
+  // Backdate timestamps that no command can set, to drive retention and cleanup crons.
+  /^packages\/bundled-features\/src\/custom-fields\/__tests__\/retention\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/form-draft\/__tests__\/cleanup\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/form-draft\/__tests__\/feature-optional-config\.integration\.test\.ts$/,
+  /^packages\/server-runtime\/src\/__tests__\/bundled\/tier-engine-resolver\.integration\.test\.ts$/,
+  /^samples\/recipes\/public-share-token\/src\/__tests__\/feature\.integration\.test\.ts$/,
+  // App user-data delete hooks and probes that stand in for app code deleting its own rows.
+  /^packages\/bundled-features\/src\/custom-fields\/__tests__\/user-data-rights\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/crypto-shredding\/__tests__\/forget-subject-record\.integration\.test\.ts$/,
+  /^packages\/bundled-features\/src\/user-data-rights\/__tests__\/forget-cleanup-search-purge-ordering\.integration\.test\.ts$/,
+  // Rebuild scenarios wipe the projection while the events stay.
+  /^packages\/bundled-features\/src\/jobs\/__tests__\/projection-rebuild-job\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/pipeline\/__tests__\/projection-rebuild\.integration\.test\.ts$/,
+  // Deletes rows between pages or batches to simulate concurrent removal for the pager and reindex.
+  /^packages\/framework\/src\/db\/__tests__\/event-store-executor-list\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/search\/__tests__\/reindex-entity\.integration\.test\.ts$/,
+  // Plants projection rows without events because detecting them is the behavior under test.
+  /^packages\/framework\/src\/db\/__tests__\/assert-no-unreachable-live-rows\.integration\.test\.ts$/,
+  // Primitive db tests of the write lock, inserts, codecs and migrations below the executor.
+  /^packages\/framework\/src\/db\/__tests__\/executor-managed-write-lock\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/multi-row-insert\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/number-field-fractional\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/query\/write-brand\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/schema-migration\.integration\.test\.ts$/,
+  /^packages\/framework\/src\/db\/__tests__\/source-shadow-create\.integration\.test\.ts$/,
+  // A hook writes a marker row through its TenantDb, which the event-store helpers do not take.
+  /^packages\/bundled-features\/src\/feature-toggles\/__tests__\/feature-toggles\.integration\.test\.ts$/,
+];
+
+const BYPASS_NAMES: ReadonlySet<string> = new Set(["updateRows", "deleteRows"]);
+const SEED_ROW_NAMES: ReadonlySet<string> = new Set(["seedRow"]);
+const TESTING_HELPERS_RE =
+  /^@cosmicdrift\/kumiko-testing\/helpers$|(^|\/)testing\/src\/helpers(\/|$)/;
+const MESSAGE =
+  "updateRows/deleteRows bypass the event store: use the real command, seedUser, " +
+  "updateRowViaEventStore/deleteRowViaEventStore, or updateMany/deleteMany on a Writable table";
+
+type HelperBindings = {
+  readonly wanted: ReadonlySet<string>;
+  readonly names: Set<string>;
+  readonly namespaces: Set<string>;
+};
+
+function helperBindings(sourceFile: SourceFile, wanted: ReadonlySet<string>): HelperBindings {
+  const names = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const decl of sourceFile.getImportDeclarations()) {
+    if (!TESTING_HELPERS_RE.test(decl.getModuleSpecifierValue())) continue;
+    for (const spec of decl.getNamedImports()) {
+      if (wanted.has(spec.getName())) names.add(spec.getAliasNode()?.getText() ?? spec.getName());
+    }
+    const namespace = decl.getNamespaceImport();
+    if (namespace) namespaces.add(namespace.getText());
+  }
+  return { wanted, names, namespaces };
+}
+
+function isHelperCallee(callee: Node, bindings: HelperBindings): boolean {
+  if (Node.isIdentifier(callee)) return bindings.names.has(callee.getText());
+  if (!Node.isPropertyAccessExpression(callee)) return false;
+  const target = callee.getExpression();
+  return (
+    bindings.wanted.has(callee.getName()) &&
+    Node.isIdentifier(target) &&
+    bindings.namespaces.has(target.getText())
+  );
+}
+
+function collect(sourceFile: SourceFile, roots: readonly RepoRoot[]): GuardViolation[] {
+  const file = relFromRepoRoot(sourceFile.getFilePath(), roots);
+  if (ALLOWLIST.some((re) => re.test(file))) return [];
+  const bypass = helperBindings(sourceFile, BYPASS_NAMES);
+  const seedRow = helperBindings(sourceFile, SEED_ROW_NAMES);
+  const bypassCalls = sourceFile
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .filter((call) => isHelperCallee(call.getExpression(), bypass))
+    .map((call) => ({ line: call.getStartLineNumber(), message: MESSAGE }));
+  return [
+    ...bypassCalls,
+    ...findSeedRowOnEntityTables(sourceFile, (callee) => isHelperCallee(callee, seedRow)),
+    ...findRawSqlWrites(sourceFile),
+  ].map((finding) => ({ file, ...finding }));
+}
+
+export const guard: AstGuard = {
+  name: "Test-ES-Row-Writes Guard",
+  scan: SCAN,
+  hint:
+    "Change event-sourced rows through the real command, seedUser({...}), seedRowViaEventStore or " +
+    "updateRowViaEventStore/deleteRowViaEventStore, reset them with resetTestTables plus eventsTable; " +
+    "use updateMany/deleteMany for non-event-sourced tables.",
+  run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
+    return { violations: files.flatMap((sf) => collect(sf, roots)) };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);