@cosmicdrift/kumiko-guards 0.389.0 → 0.390.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.389.0",
+  "version": "0.390.1",
   "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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "ts-morph": "^28.0.0",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.389.0"
+    "@cosmicdrift/kumiko-framework": "0.390.1"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.389.0"
+    "@cosmicdrift/kumiko-framework": "0.390.1"
   }
 }

package/src/_lib/sql-inventory.ts

@@ -81,7 +81,7 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
   /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
   /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
-  /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
+  /\/bundled-features\/src\/shared\/stream-tenant-backfill\.ts$/,
   /\/packages\/framework\/src\/engine\/steps\/unsafe-projection-/,
   /(^|\/)samples\/(apps|recipes)\/[^/]+\/src\/db\/queries\//,
   /\/bin\/commands\//,

package/src/_lib/test-es-raw-writes.ts

@@ -0,0 +1,88 @@
+// Static detection of projection-only writes on event-sourced tables in tests. Without
+// types the guard knows a table is event-sourced only when the file builds it itself
+// (buildEntityTable) or names it by its reserved read_ prefix; imported tables in
+// template SQL stay invisible.
+import type { SourceFile } from "ts-morph";
+import { Node, SyntaxKind } from "ts-morph";
+
+export type RawWriteFinding = { readonly line: number; readonly message: string };
+
+const EVENTS_TABLE_NAME = "eventsTable";
+
+export const SEED_ROW_MESSAGE =
+  "seedRow on an event-sourced entity table writes the projection without its event: use seedRowViaEventStore";
+
+export const RAW_SQL_MESSAGE =
+  "raw DELETE/UPDATE on an event-sourced table in a test: reset with resetTestTables(db, [table, eventsTable]), " +
+  "change rows through the real command or updateRowViaEventStore/deleteRowViaEventStore";
+
+// kumiko_events UPDATEs are reported by the test-es-fixtures guard already.
+const LITERAL_WRITE_RE =
+  /\b(?:DELETE\s+FROM\s+"?(?:read_\w+|kumiko_events)|UPDATE\s+"?read_\w+)\b/i;
+const TEMPLATE_WRITE_RE = /\b(?:DELETE\s+FROM|UPDATE)\s+"?\$\{\s*(\w+)(?:\.tableName)?\s*\}/gi;
+
+function entityTableBindings(sourceFile: SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const decl of sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+    const init = decl.getInitializer();
+    if (
+      init &&
+      Node.isCallExpression(init) &&
+      init.getExpression().getText() === "buildEntityTable"
+    ) {
+      names.add(decl.getName());
+    }
+  }
+  return names;
+}
+
+function isEventSourcedBinding(name: string, entityTables: ReadonlySet<string>): boolean {
+  return name === EVENTS_TABLE_NAME || entityTables.has(name);
+}
+
+function writesEventSourcedTable(node: Node, entityTables: ReadonlySet<string>): boolean {
+  const text = node.getText();
+  if (LITERAL_WRITE_RE.test(text)) return true;
+  if (!Node.isTemplateExpression(node)) return false;
+  for (const match of text.matchAll(TEMPLATE_WRITE_RE)) {
+    if (isEventSourcedBinding(match[1] ?? "", entityTables)) return true;
+  }
+  return false;
+}
+
+export function findRawSqlWrites(sourceFile: SourceFile): RawWriteFinding[] {
+  const entityTables = entityTableBindings(sourceFile);
+  const findings: RawWriteFinding[] = [];
+  for (const kind of [
+    SyntaxKind.StringLiteral,
+    SyntaxKind.NoSubstitutionTemplateLiteral,
+    SyntaxKind.TemplateExpression,
+  ]) {
+    for (const node of sourceFile.getDescendantsOfKind(kind)) {
+      if (writesEventSourcedTable(node, entityTables)) {
+        findings.push({ line: node.getStartLineNumber(), message: RAW_SQL_MESSAGE });
+      }
+    }
+  }
+  return findings;
+}
+
+export function findSeedRowOnEntityTables(
+  sourceFile: SourceFile,
+  isSeedRowCallee: (callee: Node) => boolean,
+): RawWriteFinding[] {
+  const entityTables = entityTableBindings(sourceFile);
+  if (entityTables.size === 0) return [];
+  return sourceFile
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .filter((call) => {
+      const table = call.getArguments()[1];
+      return (
+        isSeedRowCallee(call.getExpression()) &&
+        table !== undefined &&
+        Node.isIdentifier(table) &&
+        entityTables.has(table.getText())
+      );
+    })
+    .map((call) => ({ line: call.getStartLineNumber(), message: SEED_ROW_MESSAGE }));
+}

package/src/changes.json

@@ -1,4 +1,54 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Complexity guard covers .tsx with the hard cap of 40",
+    "detail": "The Complexity Check scans .tsx files next to .ts (.test.tsx stays excluded), and conditional JSX counts as a branch. A .tsx function above complexity 40 fails in the repo's own files, regardless of baseline or complexity-budget tag.",
+    "migration": "Run `kumiko-guards guards --write-baseline --guard=\"Complexity Check\"` once on the bump to freeze the .tsx hotspots between 15 and 40, and split every .tsx function above 40 before the bump; the complexity-budget tag and the baseline do not cover it. Measured on 2026-10-23 (function, complexity / lines): offlot-app ComposerWorkspace 129/597 (campaign-composer-screen.tsx) and ComposerPostText 47/289 (composer-post-drawer.tsx); kumiko-enterprise AgentPanelBody 74/634 (agent-panel-body.tsx); phronexsis WorkbenchDashboardScreen 64/653 (workbench-dashboard-screen.tsx); money-horse CreditCalculatorScreen 60/468 (credit-calculator-screen.tsx); solon CockpitDetail 58/462 (inbox-cockpit-screen.tsx). publicstatus, show-pony, kumiko-studio and kumiko-platform have no .tsx function above 40."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Guard for the runSchemaCli feature list",
+    "detail": "The Schema CLI Features guard fails when a consumer's `runSchemaCli` call does not get `features: FEATURES` imported from `kumiko/schema`. `allAppFeatures()` is raw, without the bundled foundation, so the projection rebuild after the migrations failed at deploy with \"Feature X requires feature Y\" (kumiko-studio, 2026-10-22). The message names the fix. Repos without `kumiko/schema.ts` are skipped, and a manifest exclude cannot hide `bin/kumiko.ts`.",
+    "migration": "Run `bun kumiko check` once on the bump. Measured on 2026-10-23: only show-pony fails (bin/kumiko.ts composes its own list); import `FEATURES` from `../kumiko/schema` there. publicstatus, offlot-app, solon, money-horse, phronexsis and kumiko-studio are clean."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Guard against projection-only writes in framework tests",
+    "detail": "The Test-ES-Row-Writes guard flags updateRows and deleteRows from the testing helpers in framework tests, because they change the projection but not the event log. It only runs in the framework repo; consumer repos are not affected."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Guard against array parameters in .unsafe()",
+    "detail": "The Unsafe Array Param guard warns when a `.unsafe(sql, [...])` parameter list holds an array literal or a spread. Bun.SQL binds such an array as \"a,b\" on Linux, so `ANY($n)` fails only in CI and passes on macOS; pass `toPostgresArrayLiteral(values)` with a `$n::text[]` cast. It is a warning and cannot see array-typed variables. Measured on 2026-10-23: no hit in any consumer repo."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "test-es-row-writes guard covers seedRow and raw SQL on event-sourced tables",
+    "detail": "Besides updateRows/deleteRows, the guard now reports seedRow on an entity table the test file builds with buildEntityTable, and raw DELETE or UPDATE statements on read_ tables, DELETE on kumiko_events and template SQL on eventsTable or such an entity table. Tests that corrupt projections, backdate timestamps or plant legacy rows on purpose are allowlisted per file with a reason. The guard runs in the framework repo only; nothing changes for apps."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "New guard rls-session-settings",
+    "detail": "Flags SET and SET SESSION on kumiko.* settings and set_config with is_local false in any source or test string, kumiko.* writes outside rls-scope.ts in non-test code, and a set_config in rls-scope.ts without literal true. A session-level setting survives on a pooled connection and leaks one request's scope into the next."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "rls-session-settings also scans .sql files",
+    "detail": "Consumer migrations are checked statement by statement for session-level SET kumiko.*, set_config with is_local false and any kumiko.* write."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "New guard internal-subpath-imports",
+    "detail": "Flags kumiko-framework/internal/* imports outside the framework repo, row level security scope helpers from kumiko-testing/helpers in non-test code, and system scope calls without a literal reason."
+  },
   {
     "version": "0.389.0",
     "type": "improvement",

package/src/check-as-casts.ts

@@ -329,7 +329,7 @@ const FILE_DEFAULT_REASONS: ReadonlyArray<{
   {
     // Feature-AST extractors cast erased ts-morph parse results to typed feature definitions
     // (EntityDefinition, RelationDef, NavDef, ConfigKeys, …), so every cast is a schema walk.
-    pattern: /\/engine\/feature-ast\//,
+    pattern: /(^|\/)packages\/feature-ast\/src\/(?!scripts\/|codemod\/|pattern-library\/)/,
     boundaryReason: "schema-walk",
   },
 ];
@@ -362,7 +362,7 @@ export function collect(sf: SourceFile): Site[] {
     if (isBridgeOuter(cast)) continue;
     const category = categorize(cast);
     // TypingLossMarker casts (e.g. `as DbRow`) and FileDefault casts
-    // (e.g. feature-ast/extractors.ts → "schema-walk") are boundaries by type
+    // (e.g. feature-ast/src/extractors/*.ts → "schema-walk") are boundaries by type
     // definition / convention — synthetic reason so the unknown-reason check
     // does not fail on them.
     const reason =

package/src/check-complexity.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env bun
 /**
- * Complexity check for handler hotspots with a baseline regression guard.
+ * Complexity check for .ts and .tsx hotspots with a hard cap and a baseline regression guard.
  *
  * Computes cyclomatic complexity per function/method (base 1, +1 per decision
  * point: if, for, while, case, catch, &&, ||, ??, ternary). Above the
- * threshold -> hotspot.
+ * threshold -> hotspot. In .tsx, conditional JSX (`cond && <X/>`, ternaries)
+ * counts like any other branch.
  *
  * Baseline regression guard like guard-comment-lang.ts: `.kumiko-complexity-
  * baseline.json` in the repo root pins the frozen hotspot count per file.
@@ -52,11 +53,11 @@ const ROOT = process.cwd();
 
 const SCAN: ScanSpec = {
   scope: "source",
-  extensions: ["ts"],
+  extensions: ["ts", "tsx"],
   frameworkWithin: ["packages/*/src/**"],
 };
 
-const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
+const EXCLUDE = /(__tests__|\.test\.(ts|tsx)$|\.integration\.(ts|tsx)$|\.d\.ts$)/;
 
 const COMPLEXITY_THRESHOLD = 15;
 const MAX_REPORTED = 30;

package/src/guard-admin-api.ts

@@ -115,7 +115,7 @@ export const guard: AstGuard = {
   scan: SCAN,
   // App repos are not exempt — appendRaw/appendRawBatch bypasses the pipeline.
   security: true,
-  hint: "Admin API (appendRaw/appendRawBatch) bypasses the pipeline — only allowed in samples/*/migration/ or scripts/migrations/. For domain events: ctx.appendEvent / write handler.",
+  hint: "Admin API (appendRaw/appendRawBatch) bypasses the pipeline — only allowed in samples/*/migration/ or scripts/migrations/. For domain events: ctx.events.append / write handler.",
   run(files, roots: readonly RepoRoot[] = resolveRepoRoots()) {
     const violations: Array<{ file: string; line: number; message: string }> = [];
 

package/src/guard-error-reasons.ts

@@ -20,7 +20,8 @@
  *      (FrameworkReasons.*, <Anything>Reasons.*, TenantErrors.*, etc.).
  *   2. `failUnprocessable(X, ...)` — same rule.
  *   3. Object literals containing `reason: "X"` — same rule for the X.
- *      Skips `openToAll: { reason: "..." }` / `escapeHatch: { reason: "..." }`
+ *      Skips `openToAll: { reason: "..." }` / `escapeHatch: { reason: "..." }` /
+ *      `grants: { unsafeRaw: { reason: "..." } }` (every escape-hatch grant)
  *      and `declareEscapeHatch({ reason: "..." })` — those are prose
  *      access-declaration justifications, enforced instead by
  *      the boot validator and the runtime reasonProblem check.
@@ -34,6 +35,7 @@
  */
 
 import * as path from "node:path";
+import { ESCAPE_HATCH_GRANTS } from "@cosmicdrift/kumiko-types/handlers";
 import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
 import { type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
 
@@ -58,11 +60,22 @@ const UNPROC_CALL_NAMES = new Set(["UnprocessableError", "failUnprocessable"]);
 
 // Property names whose `{ reason: "..." }` is a prose access-declaration
 // justification, not an error-reason code.
-const ACCESS_DECLARATION_NAMES = new Set(["openToAll", "escapeHatch"]);
+// `grants: { <grant>: { reason } }` carries the grant names of EscapeHatchDeclaration; deriving them
+// keeps a new grant from being reported as an error code.
+const ACCESS_DECLARATION_NAMES = new Set<string>([
+  "openToAll",
+  "escapeHatch",
+  "unsafeAllTenants",
+  ...ESCAPE_HATCH_GRANTS,
+]);
 
 // Calls whose object-literal argument carries a prose `reason` for an
-// access grant / escape hatch.
-const ACCESS_DECLARATION_CALLS = new Set(["declareEscapeHatch", "withUnsafeRawGrant"]);
+// access grant / escape hatch / system-mode TenantDb.
+const ACCESS_DECLARATION_CALLS = new Set([
+  "declareEscapeHatch",
+  "withUnsafeRawGrant",
+  "createTenantDb",
+]);
 
 interface Violation {
   readonly file: string;

package/src/guard-event-store-writes.ts

@@ -38,14 +38,14 @@ const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 //     call (event-store.ts, event-store-admin.ts, event-store-transfer.ts).
 //   - db/queries/backfill-pii.ts — the one-time pre-KMS plaintext backfill;
 //     rewrites payload/deletes stale snapshots in place, framework-owned.
-//   - user/db/queries/stream-tenant-backfill.ts — a one-time stream-ownership
+//   - shared/stream-tenant-backfill.ts — a one-time stream-ownership
 //     migration that predates this guard; already carries its own
 //     RAW_SQL_ALLOWLIST entry, kept here for the same reason.
 const ALLOWLIST: readonly RegExp[] = [
   /^packages\/framework\/src\/event-store\//,
   /^packages\/framework\/src\/db\/queries\/event-store.*\.ts$/,
   /^packages\/framework\/src\/db\/queries\/backfill-pii\.ts$/,
-  /^packages\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
+  /^packages\/bundled-features\/src\/shared\/stream-tenant-backfill\.ts$/,
 ];
 
 const ES_TABLES = "kumiko_events|kumiko_snapshots|kumiko_archived_streams";

package/src/guard-import-extensions.ts

@@ -87,7 +87,7 @@ export const guard: AstGuard = {
   scan: SCAN,
   hint:
     "Relative imports name the source file: `./foo.js` -> `./foo.ts`, `./Comp.jsx` -> `./Comp.tsx`. " +
-    "Run the import-extensions codemod: `bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/import-extensions.ts . --write`. " +
+    "Run the import-extensions codemod: `bun node_modules/@cosmicdrift/kumiko-feature-ast/src/scripts/codemod/import-extensions.ts . --write`. " +
     "The tsconfig needs `allowImportingTsExtensions` (and `rewriteRelativeImportExtensions` when tsc emits).",
   run(files) {
     const violations: Array<{ file: string; line: number; message: string }> = [];

package/src/guard-internal-subpath-imports.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env bun
+/**
+ * Guard: keeps the row-level-security escape hatches out of consumer code.
+ *
+ * 1. Outside the framework repo nothing may import `@cosmicdrift/kumiko-framework/internal/*`.
+ * 2. `runInRowLevelSecurityScope`, `runInSystemRowLevelSecurityScope` and
+ *    `tenantRowLevelSecurityScope` from `@cosmicdrift/kumiko-testing/helpers` are test-only.
+ * 3. `runInSystemRowLevelSecurityScope` and `systemScopedRunner` take a non-empty string literal
+ *    reason, so every system-scope entry stays greppable; `SYSTEM_ROW_LEVEL_SECURITY_SCOPE` is
+ *    framework-internal and only used by an allowlist. An object literal passed to
+ *    `createTenantDb` with `mode: "system"` carries the same kind of `reason`.
+ *
+ * Usage:
+ *   bun guards/guard-internal-subpath-imports.ts
+ *
+ * Exit 1 on violations, 0 when clean.
+ */
+
+import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { findRepoRootFor } from "./_lib/baseline-compare";
+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 INTERNAL_PREFIX = "@cosmicdrift/kumiko-framework/internal/";
+const TESTING_HELPERS = "@cosmicdrift/kumiko-testing/helpers";
+
+const TEST_ONLY_SCOPE_SYMBOLS = new Set([
+  "runInRowLevelSecurityScope",
+  "runInSystemRowLevelSecurityScope",
+  "tenantRowLevelSecurityScope",
+]);
+
+// Position of the reason argument per call.
+const REASON_ARG_INDEX: Record<string, number> = {
+  runInSystemRowLevelSecurityScope: 0,
+  systemScopedRunner: 1,
+};
+
+const FIXED_SCOPE_SYMBOL = "SYSTEM_ROW_LEVEL_SECURITY_SCOPE";
+
+const FIXED_SCOPE_ALLOWLIST = [
+  /^packages\/framework\/src\/db\/row-level-security-scope\.ts$/,
+  /^packages\/framework\/src\/pipeline\/dispatch-scope\.ts$/,
+  /^packages\/framework\/src\/db\/migrate-runner\.ts$/,
+];
+
+// Exercises the empty-reason rejection, so it passes empty literals on purpose.
+const REASON_RULE_EXEMPT = [
+  /^packages\/framework\/src\/db\/__tests__\/row-level-security-scope\.test\.ts$/,
+];
+
+// These forward a reason their own caller already supplied as a literal.
+const FORWARDED_TENANT_DB_REASON_ALLOWLIST = [
+  /^packages\/framework\/src\/db\/tenant-db\.ts$/,
+  /^packages\/framework\/src\/db\/cross-tenant-reads\.ts$/,
+];
+
+type Finding = { line: number; message: string };
+
+function isTestFile(rel: string): boolean {
+  return rel.split("/").includes("__tests__") || TEST_FILE_RE.test(rel);
+}
+
+function isInternalSpecifier(specifier: string): boolean {
+  return specifier.startsWith(INTERNAL_PREFIX);
+}
+
+// Literal text of a string argument; for a template with substitutions only its static head.
+function staticSpecifierHead(arg: Node): string | undefined {
+  const kind = arg.getKind();
+  if (kind === SyntaxKind.StringLiteral || kind === SyntaxKind.NoSubstitutionTemplateLiteral) {
+    return arg.getText().slice(1, -1);
+  }
+  if (kind === SyntaxKind.TemplateExpression) {
+    return arg.asKindOrThrow(SyntaxKind.TemplateExpression).getHead().getLiteralText();
+  }
+  return undefined;
+}
+
+function findInternalImports(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  const report = (line: number, specifier: string): void => {
+    findings.push({
+      line,
+      message: `[internal-import] "${specifier}" is framework-internal; consumer code must not import it`,
+    });
+  };
+  for (const decl of [...sf.getImportDeclarations(), ...sf.getExportDeclarations()]) {
+    const specifier = decl.getModuleSpecifierValue();
+    if (specifier !== undefined && isInternalSpecifier(specifier)) {
+      report(decl.getStartLineNumber(), specifier);
+    }
+  }
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    const isDynamicImport = callee.getKind() === SyntaxKind.ImportKeyword;
+    const isRequire = callee.getKind() === SyntaxKind.Identifier && callee.getText() === "require";
+    if (!isDynamicImport && !isRequire) continue;
+    const arg = call.getArguments()[0];
+    if (arg === undefined) continue;
+    const specifier = staticSpecifierHead(arg);
+    if (specifier !== undefined && isInternalSpecifier(specifier)) {
+      report(call.getStartLineNumber(), specifier);
+    }
+  }
+  return findings;
+}
+
+function findTestOnlyScopeImports(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  const decls = [
+    ...sf.getImportDeclarations(),
+    ...sf.getExportDeclarations().filter((d) => d.getModuleSpecifier() !== undefined),
+  ];
+  for (const decl of decls) {
+    if (decl.getModuleSpecifierValue() !== TESTING_HELPERS) continue;
+    const named =
+      "getNamedImports" in decl
+        ? decl.getNamedImports().map((n) => n.getName())
+        : decl.getNamedExports().map((n) => n.getName());
+    for (const name of named) {
+      if (!TEST_ONLY_SCOPE_SYMBOLS.has(name)) continue;
+      findings.push({
+        line: decl.getStartLineNumber(),
+        message: `[test-only-scope] ${name} from ${TESTING_HELPERS} is allowed in test files only`,
+      });
+    }
+  }
+  const namespaces = new Set<string>();
+  for (const decl of sf.getImportDeclarations()) {
+    if (decl.getModuleSpecifierValue() !== TESTING_HELPERS) continue;
+    const ns = decl.getNamespaceImport();
+    if (ns !== undefined) namespaces.add(ns.getText());
+  }
+  if (namespaces.size > 0) {
+    for (const access of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+      const name = access.getName();
+      if (!TEST_ONLY_SCOPE_SYMBOLS.has(name)) continue;
+      if (!namespaces.has(access.getExpression().getText())) continue;
+      findings.push({
+        line: access.getStartLineNumber(),
+        message: `[test-only-scope] ${name} from ${TESTING_HELPERS} is allowed in test files only`,
+      });
+    }
+  }
+  return findings;
+}
+
+// Maps local binding names (aliases included) to the symbol they import.
+function localNamesOf(sf: SourceFile, symbols: ReadonlySet<string>): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const decl of sf.getImportDeclarations()) {
+    for (const named of decl.getNamedImports()) {
+      const original = named.getName();
+      if (symbols.has(original)) names.set(named.getAliasNode()?.getText() ?? original, original);
+    }
+  }
+  for (const symbol of symbols) {
+    if (!names.has(symbol)) names.set(symbol, symbol);
+  }
+  return names;
+}
+
+function isNonEmptyStringLiteral(node: { getKind(): SyntaxKind; getText(): string }): boolean {
+  const kind = node.getKind();
+  if (kind !== SyntaxKind.StringLiteral && kind !== SyntaxKind.NoSubstitutionTemplateLiteral) {
+    return false;
+  }
+  return node.getText().slice(1, -1).trim() !== "";
+}
+
+// `fn(...)` through a local binding (aliases included) or `<namespace>.fn(...)` by property name.
+function reasonSymbolOf(callee: Node, locals: ReadonlyMap<string, string>): string | undefined {
+  if (callee.getKind() === SyntaxKind.Identifier) return locals.get(callee.getText());
+  if (callee.getKind() === SyntaxKind.PropertyAccessExpression) {
+    const name = callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName();
+    return Object.hasOwn(REASON_ARG_INDEX, name) ? name : undefined;
+  }
+  return undefined;
+}
+
+function findReasonViolations(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  const locals = localNamesOf(sf, new Set(Object.keys(REASON_ARG_INDEX)));
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    const symbol = reasonSymbolOf(callee, locals);
+    if (symbol === undefined) continue;
+    const reasonArg = call.getArguments()[REASON_ARG_INDEX[symbol] ?? 0];
+    if (reasonArg !== undefined && isNonEmptyStringLiteral(reasonArg)) continue;
+    findings.push({
+      line: call.getStartLineNumber(),
+      message: `[system-scope-reason] ${symbol} needs a non-empty string literal reason as argument ${(REASON_ARG_INDEX[symbol] ?? 0) + 1}`,
+    });
+  }
+  return findings;
+}
+
+function isSystemModeProperty(prop: Node): boolean {
+  if (prop.getKind() !== SyntaxKind.PropertyAssignment) return false;
+  const assignment = prop.asKindOrThrow(SyntaxKind.PropertyAssignment);
+  return assignment.getName() === "mode" && assignment.getInitializer()?.getText() === '"system"';
+}
+
+function findTenantDbReasonViolations(sf: SourceFile): Finding[] {
+  const findings: Finding[] = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    const calleeName =
+      callee.getKind() === SyntaxKind.PropertyAccessExpression
+        ? callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName()
+        : callee.getText();
+    if (calleeName !== "createTenantDb") continue;
+    const options = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
+    if (options === undefined || !options.getProperties().some(isSystemModeProperty)) continue;
+    const reason = options.getProperty("reason")?.asKind(SyntaxKind.PropertyAssignment);
+    const initializer = reason?.getInitializer();
+    if (initializer !== undefined && isNonEmptyStringLiteral(initializer)) continue;
+    findings.push({
+      line: call.getStartLineNumber(),
+      message:
+        '[tenant-db-system-reason] createTenantDb({ mode: "system" }) needs a non-empty string literal `reason`',
+    });
+  }
+  return findings;
+}
+
+function findFixedScopeUses(sf: SourceFile): Finding[] {
+  return sf
+    .getDescendantsOfKind(SyntaxKind.Identifier)
+    .filter((id) => id.getText() === FIXED_SCOPE_SYMBOL)
+    .map((id) => ({
+      line: id.getStartLineNumber(),
+      message: `[fixed-system-scope] ${FIXED_SCOPE_SYMBOL} carries no call-site reason; use runInSystemRowLevelSecurityScope(reason, fn)`,
+    }));
+}
+
+export const guard: AstGuard = {
+  name: "Internal-Subpath-Imports Guard",
+  scan: SCAN,
+  hint: "Consumer repos use the public subpaths only; `@cosmicdrift/kumiko-framework/internal/*` is for framework packages. Scope helpers from kumiko-testing/helpers belong in tests. Every system-scope entry, including createTenantDb with mode system, passes a specific string-literal reason (why it needs cross-tenant access). SYSTEM_ROW_LEVEL_SECURITY_SCOPE is limited to row-level-security-scope.ts, dispatch-scope.ts and migrate-runner.ts; extend that allowlist in guard-internal-subpath-imports.ts with a reason.",
+  run(files, roots = resolveRepoRoots()) {
+    const violations: Array<{ file: string; line: number; message: string }> = [];
+
+    for (const sf of files) {
+      const file = sf.getFilePath();
+      const rel = relFromRepoRoot(file, roots);
+      const isFrameworkRepo = findRepoRootFor(file, roots)?.kind === "framework";
+      const findings: Finding[] = [];
+      if (!isFrameworkRepo) findings.push(...findInternalImports(sf));
+      if (!isTestFile(rel)) findings.push(...findTestOnlyScopeImports(sf));
+      if (!isAllowlisted(rel, REASON_RULE_EXEMPT)) findings.push(...findReasonViolations(sf));
+      if (!isAllowlisted(rel, FORWARDED_TENANT_DB_REASON_ALLOWLIST)) {
+        findings.push(...findTenantDbReasonViolations(sf));
+      }
+      if (!isAllowlisted(rel, FIXED_SCOPE_ALLOWLIST)) findings.push(...findFixedScopeUses(sf));
+      for (const f of findings) violations.push({ file: rel, ...f });
+    }
+
+    return { violations };
+  },
+};
+
+if (import.meta.main) runStandalone(guard);

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

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