@cosmicdrift/kumiko-guards 0.389.0 → 0.390.1

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-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);

package/src/guard-unsafe-array-param.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env bun
+/**
+ * Warns when a `.unsafe(sql, [...])` parameter list holds a JS array (or a spread).
+ *
+ * Bun.SQL binds a JS array parameter as "a,b" on Linux, so `ANY($n)` fails with a
+ * malformed array literal in CI while the same call passes on macOS. Pass
+ * `toPostgresArrayLiteral(values)` (from `@cosmicdrift/kumiko-framework/db`) and cast the
+ * placeholder (`$1::text[]`).
+ *
+ * Heuristic without type info: only array literals and spreads directly inside the
+ * parameter-list literal are reported; array-typed variables pass unnoticed. Warning only.
+ */
+
+import { readFileSync } from "node:fs";
+import { 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 ScanSpec, scanFiles } from "./_lib/scan-scope";
+
+const SCAN: ScanSpec = { scope: "source+tests", extensions: ["ts", "tsx"] };
+
+const UNSAFE_CALL_MARKER = ".unsafe";
+const UNSAFE_PARAMS_ARG_INDEX = 1;
+
+const FIX_HINT =
+  "pass toPostgresArrayLiteral(values) from @cosmicdrift/kumiko-framework/db and cast the placeholder, e.g. ANY($1::text[])";
+
+export type UnsafeArrayParamFinding = {
+  readonly line: number;
+  readonly message: string;
+};
+
+function unwrapExpression(node: Node): Node {
+  let current = node;
+  while (
+    Node.isAsExpression(current) ||
+    Node.isSatisfiesExpression(current) ||
+    Node.isParenthesizedExpression(current)
+  ) {
+    current = current.getExpression();
+  }
+  return current;
+}
+
+export function findUnsafeArrayParams(sf: SourceFile): UnsafeArrayParamFinding[] {
+  const findings: UnsafeArrayParamFinding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) || callee.getName() !== "unsafe") continue;
+    const params = call.getArguments()[UNSAFE_PARAMS_ARG_INDEX];
+    if (params === undefined) continue;
+    const paramList = unwrapExpression(params);
+    if (!Node.isArrayLiteralExpression(paramList)) continue;
+    for (const element of paramList.getElements()) {
+      const value = unwrapExpression(element);
+      if (Node.isArrayLiteralExpression(value)) {
+        findings.push({
+          line: element.getStartLineNumber(),
+          message: `array literal as an unsafe() parameter binds as "a,b" on Linux; ${FIX_HINT}`,
+        });
+      } else if (Node.isSpreadElement(element)) {
+        findings.push({
+          line: element.getStartLineNumber(),
+          message: `spread in the unsafe() parameter list; if it feeds ANY($n), ${FIX_HINT}`,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+export const check: RepoCheck = {
+  name: "Unsafe Array Param Guard",
+  hint:
+    "Bun.SQL binds a JS array parameter as 'a,b' on Linux (CI) but not on macOS. " +
+    "Use toPostgresArrayLiteral(values) with a $n::type[] cast in unsafe() calls.",
+  run(roots) {
+    const paths = scanFiles(SCAN, roots);
+    const project = new Project({ skipAddingFilesFromTsConfig: true, useInMemoryFileSystem: true });
+    const warnings: GuardViolation[] = [];
+    for (const absPath of paths) {
+      const text = readFileSync(absPath, "utf-8");
+      if (!text.includes(UNSAFE_CALL_MARKER)) continue;
+      const sf = project.createSourceFile(absPath, text, { overwrite: true });
+      for (const finding of findUnsafeArrayParams(sf)) {
+        warnings.push({
+          file: relative(process.cwd(), absPath),
+          line: finding.line,
+          message: finding.message,
+        });
+      }
+    }
+    return {
+      violations: [],
+      warnings: warnings.length > 0 ? warnings : undefined,
+      matchedFiles: paths.length,
+      notApplicable: false,
+    };
+  },
+};
+
+if (import.meta.main) {
+  const failed = reportResults(await runRepoChecks([check]));
+  process.exit(failed > 0 ? 1 : 0);
+}

package/src/run-guards.ts

@@ -38,16 +38,19 @@ import { guard as i18nKeys } from "./guard-i18n-keys";
 import { guard as i18nLocaleMount } from "./guard-i18n-locale-mount";
 import { guard as i18nLocaleTerminology } from "./guard-i18n-locale-terminology";
 import { guard as importExtensions } from "./guard-import-extensions";
+import { guard as internalSubpathImports } from "./guard-internal-subpath-imports";
 import { guard as libTestCoverage } from "./guard-lib-test-coverage";
 import { guard as noDateApi } from "./guard-no-date-api";
 import { guard as noDirectFs } from "./guard-no-direct-fs";
 import { guard as noLogicInViews } from "./guard-no-logic-in-views";
 import { guard as noTemporalPolyfillImport } from "./guard-no-temporal-polyfill-import";
 import { guard as restrictedSymbols } from "./guard-restricted-symbols";
+import { guard as rlsSessionSettings } from "./guard-rls-session-settings";
 import { guard as screenConventions } from "./guard-screen-conventions";
 import { guard as silentSkip } from "./guard-silent-skip";
 import { guard as tenantEscalation } from "./guard-tenant-escalation";
 import { guard as testEsFixtures } from "./guard-test-es-fixtures";
+import { guard as testEsRowWrites } from "./guard-test-es-row-writes";
 import { guard as testTemplateDrift } from "./guard-test-template-drift";
 import { guard as testTimeouts } from "./guard-test-timeouts";
 import { guard as unsafeJsonParse } from "./guard-unsafe-json-parse";
@@ -67,6 +70,8 @@ export const GUARDS = [
   noDateApi,
   noTemporalPolyfillImport,
   restrictedSymbols,
+  internalSubpathImports,
+  rlsSessionSettings,
   fakeTests,
   noLogicInViews,
   errorReasons,
@@ -83,6 +88,7 @@ export const GUARDS = [
   libTestCoverage,
   testTimeouts,
   testEsFixtures,
+  testEsRowWrites,
   testTemplateDrift,
   fileSize,
   commentIssueRefOnly,

package/src/run-repo-checks.ts

@@ -15,8 +15,10 @@ import { check as noDirectProcessEnv } from "./guard-no-direct-process-env";
 import { check as primitivesDiscipline } from "./guard-primitives-discipline";
 import { check as rawSql } from "./guard-raw-sql";
 import { check as rendererBoundaries } from "./guard-renderer-boundaries";
+import { check as schemaCliFeatures } from "./guard-schema-cli-features";
 import { check as testStackDrift } from "./guard-test-stack-drift";
 import { check as thinWrappers } from "./guard-thin-wrappers";
+import { check as unsafeArrayParam } from "./guard-unsafe-array-param";
 import { check as upgradeState } from "./guard-upgrade-state";
 
 export const REPO_CHECKS = [
@@ -35,6 +37,8 @@ export const REPO_CHECKS = [
   agentDocsDrift,
   subpathExports,
   guardsDocDrift,
+  unsafeArrayParam,
+  schemaCliFeatures,
 ];
 
 export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];