@cosmicdrift/kumiko-framework 0.269.0 → 0.269.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.269.0",
+  "version": "0.269.2",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.269.0",
+    "@cosmicdrift/kumiko-types": "0.269.2",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.269.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.269.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/fixtures/migrate-db-raw/global-fetch.expected.ts

@@ -0,0 +1,9 @@
+import { userTable } from "./entities/user";
+
+export const userDetail = defineQueryHandler({
+  name: "user:detail",
+  handler: async (query, ctx) => {
+    const row = await ctx.db.global(userTable).fetchOne<UserRow>({ id: query.payload.id });
+    return row ?? null;
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/global-fetch.input.ts

@@ -0,0 +1,10 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { userTable } from "./entities/user";
+
+export const userDetail = defineQueryHandler({
+  name: "user:detail",
+  handler: async (query, ctx) => {
+    const row = await fetchOne<UserRow>(ctx.db.raw, userTable, { id: query.payload.id });
+    return row ?? null;
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/global-select.expected.ts

@@ -0,0 +1,6 @@
+import { globalFeatureStateTable } from "./entities/global-feature-state";
+
+export async function loadFlags(ctx: Ctx) {
+  const rows = await ctx.db.global(globalFeatureStateTable).selectMany<FlagRow>({ key: "beta" }, { limit: 10 });
+  return rows;
+}

package/src/__tests__/fixtures/migrate-db-raw/global-select.input.ts

@@ -0,0 +1,12 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { globalFeatureStateTable } from "./entities/global-feature-state";
+
+export async function loadFlags(ctx: Ctx) {
+  const rows = await selectMany<FlagRow>(
+    ctx.db.raw,
+    globalFeatureStateTable,
+    { key: "beta" },
+    { limit: 10 },
+  );
+  return rows;
+}

package/src/__tests__/fixtures/migrate-db-raw/import-pruning.expected.ts

@@ -0,0 +1,12 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { userTable } from "./entities/user";
+
+export const userDetail = defineQueryHandler({
+  name: "user:detail",
+  handler: async (query, ctx) => {
+    const row = await ctx.db.global(userTable).fetchOne<UserRow>({ id: query.payload.id });
+    return row ?? null;
+  },
+});
+
+export const selectManyHelper = selectMany;

package/src/__tests__/fixtures/migrate-db-raw/import-pruning.input.ts

@@ -0,0 +1,12 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { userTable } from "./entities/user";
+
+export const userDetail = defineQueryHandler({
+  name: "user:detail",
+  handler: async (query, ctx) => {
+    const row = await fetchOne<UserRow>(ctx.db.raw, userTable, { id: query.payload.id });
+    return row ?? null;
+  },
+});
+
+export const selectManyHelper = selectMany;

package/src/__tests__/fixtures/migrate-db-raw/manual-only.expected.ts

@@ -0,0 +1,26 @@
+import { countWhere, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { auditTable, invoiceTable } from "./entities";
+
+export const auditWrite = defineWriteHandler({
+  name: "audit:write",
+  handler: async (event, ctx) => {
+    const tenantId = event.payload.tenantId;
+    await insertOne(ctx.db.raw, auditTable, { tenantId, action: event.payload.action });
+    const total = await countWhere(ctx.db.raw, invoiceTable, { status: "open" });
+    return { total };
+  },
+});
+
+export function bootstrapSystemDb(ctx: Ctx, x: unknown) {
+  return createTenantDb(ctx.db.raw, x, "system");
+}
+
+export const crossTenantAck = defineWriteHandler({
+  name: "cross-tenant:ack",
+  handler: async (event, ctx) => {
+    const r = { id: event.payload.id };
+    const acked = ctx.systemDb.acknowledgeCrossTenant(r).raw;
+    return { acked };
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/manual-only.input.ts

@@ -0,0 +1,26 @@
+import { countWhere, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { auditTable, invoiceTable } from "./entities";
+
+export const auditWrite = defineWriteHandler({
+  name: "audit:write",
+  handler: async (event, ctx) => {
+    const tenantId = event.payload.tenantId;
+    await insertOne(ctx.db.raw, auditTable, { tenantId, action: event.payload.action });
+    const total = await countWhere(ctx.db.raw, invoiceTable, { status: "open" });
+    return { total };
+  },
+});
+
+export function bootstrapSystemDb(ctx: Ctx, x: unknown) {
+  return createTenantDb(ctx.db.raw, x, "system");
+}
+
+export const crossTenantAck = defineWriteHandler({
+  name: "cross-tenant:ack",
+  handler: async (event, ctx) => {
+    const r = { id: event.payload.id };
+    const acked = ctx.systemDb.acknowledgeCrossTenant(r).raw;
+    return { acked };
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/own-tenant-const-shorthand.expected.ts

@@ -0,0 +1,10 @@
+import { invoiceTable } from "./entities/invoice";
+
+export const invoiceDetailQuery = defineQueryHandler({
+  name: "invoice:detail",
+  handler: async (query, ctx) => {
+    const tenantId = query.user.tenantId;
+    const row = await ctx.db.fetchOne<InvoiceRow>(invoiceTable, { id: query.payload.id, tenantId });
+    return row ?? null;
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/own-tenant-const-shorthand.input.ts

@@ -0,0 +1,11 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { invoiceTable } from "./entities/invoice";
+
+export const invoiceDetailQuery = defineQueryHandler({
+  name: "invoice:detail",
+  handler: async (query, ctx) => {
+    const tenantId = query.user.tenantId;
+    const row = await fetchOne<InvoiceRow>(ctx.db.raw, invoiceTable, { id: query.payload.id, tenantId });
+    return row ?? null;
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/own-tenant-event.expected.ts

@@ -0,0 +1,9 @@
+import { invoiceTable } from "./entities/invoice";
+
+export const invoiceListWrite = defineWriteHandler({
+  name: "invoice:list",
+  handler: async (event, ctx) => {
+    const rows = await ctx.db.selectMany(invoiceTable, { tenantId: event.user.tenantId, status: "open" }, { limit: 20 });
+    return rows;
+  },
+});

package/src/__tests__/fixtures/migrate-db-raw/own-tenant-event.input.ts

@@ -0,0 +1,15 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { invoiceTable } from "./entities/invoice";
+
+export const invoiceListWrite = defineWriteHandler({
+  name: "invoice:list",
+  handler: async (event, ctx) => {
+    const rows = await selectMany(
+      ctx.db.raw,
+      invoiceTable,
+      { tenantId: event.user.tenantId, status: "open" },
+      { limit: 20 },
+    );
+    return rows;
+  },
+});

package/src/__tests__/migrate-db-raw-codemod.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { migrateDbRawSource } from "../scripts/codemod/migrate-db-raw";
+
+const FIXTURES_DIR = join(import.meta.dir, "fixtures", "migrate-db-raw");
+const DEFAULT_GLOBAL_TABLES = new Set(["userTable", "globalFeatureStateTable"]);
+
+function readFixture(name: string): { input: string; expected: string } {
+  return {
+    input: readFileSync(join(FIXTURES_DIR, `${name}.input.ts`), "utf8"),
+    expected: readFileSync(join(FIXTURES_DIR, `${name}.expected.ts`), "utf8"),
+  };
+}
+
+describe("migrateDbRawSource", () => {
+  it("rewrites a global fetchOne with type args to db.global().fetchOne()", () => {
+    const { input, expected } = readFixture("global-fetch");
+    const result = migrateDbRawSource(input, "global-fetch.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(1);
+    expect(result.rewrites[0]?.rule).toBe("global-table");
+    expect(result.rewrites[0]?.line).toBe(7);
+    expect(result.manual).toHaveLength(0);
+  });
+
+  it("rewrites a global selectMany with options to db.global().selectMany()", () => {
+    const { input, expected } = readFixture("global-select");
+    const result = migrateDbRawSource(input, "global-select.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(1);
+    expect(result.rewrites[0]?.rule).toBe("global-table");
+    expect(result.manual).toHaveLength(0);
+  });
+
+  it("rewrites own-tenant filtering via event.user.tenantId", () => {
+    const { input, expected } = readFixture("own-tenant-event");
+    const result = migrateDbRawSource(input, "own-tenant-event.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(1);
+    expect(result.rewrites[0]?.rule).toBe("own-tenant");
+    expect(result.manual).toHaveLength(0);
+  });
+
+  it("rewrites own-tenant filtering via a const tenantId shorthand binding", () => {
+    const { input, expected } = readFixture("own-tenant-const-shorthand");
+    const result = migrateDbRawSource(input, "own-tenant-const-shorthand.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(1);
+    expect(result.rewrites[0]?.rule).toBe("own-tenant");
+    expect(result.manual).toHaveLength(0);
+  });
+
+  it("leaves unsafe call sites untouched and reports them as manual", () => {
+    const { input, expected } = readFixture("manual-only");
+    const result = migrateDbRawSource(input, "manual-only.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.rewrites).toHaveLength(0);
+    expect(result.manual).toHaveLength(4);
+
+    const byText = new Map(result.manual.map((m) => [m.text, m]));
+
+    const insertOneSite = byText.get(
+      "insertOne(ctx.db.raw, auditTable, { tenantId, action: event.payload.action })",
+    );
+    expect(insertOneSite).toBeDefined();
+    expect(insertOneSite?.line).toBe(9);
+    expect(insertOneSite?.enclosing).toBe("handler");
+
+    const countWhereSite = byText.get('countWhere(ctx.db.raw, invoiceTable, { status: "open" })');
+    expect(countWhereSite).toBeDefined();
+    expect(countWhereSite?.line).toBe(10);
+
+    const createTenantDbSite = byText.get('createTenantDb(ctx.db.raw, x, "system")');
+    expect(createTenantDbSite).toBeDefined();
+    expect(createTenantDbSite?.line).toBe(16);
+    expect(createTenantDbSite?.enclosing).toBe("bootstrapSystemDb");
+
+    const systemDbSite = byText.get("ctx.systemDb.acknowledgeCrossTenant(r).raw");
+    expect(systemDbSite).toBeDefined();
+    expect(systemDbSite?.line).toBe(23);
+  });
+
+  it("does not rewrite when tenantId comes from a non-user-scope source (payload/token)", () => {
+    const { input } = readFixture("manual-only");
+    const result = migrateDbRawSource(input, "manual-only.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toContain("await insertOne(ctx.db.raw, auditTable");
+  });
+
+  it("prunes an unused free-function import after rewriting its only call site", () => {
+    const { input, expected } = readFixture("global-fetch");
+    const result = migrateDbRawSource(input, "global-fetch.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).not.toContain(
+      'import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";',
+    );
+    expect(result.output).toBe(expected);
+  });
+
+  it("keeps a still-referenced sibling import while pruning the rewritten one", () => {
+    const { input, expected } = readFixture("import-pruning");
+    const result = migrateDbRawSource(input, "import-pruning.ts", {
+      globalTables: DEFAULT_GLOBAL_TABLES,
+    });
+
+    expect(result.output).toBe(expected);
+    expect(result.output).toContain(
+      'import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";',
+    );
+    expect(result.output.split("\n")[0]).not.toContain("fetchOne");
+  });
+});

package/src/__tests__/upgrade-cli.test.ts

@@ -3,8 +3,10 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
   rmSync,
+  statSync,
   symlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -12,6 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   findCodemodScriptsRoot,
+  findCoreChangelogFile,
+  findFeaturesDirs,
   resolveCodemodScript,
   runUpgradeCli,
   type UpgradeCliOut,
@@ -592,3 +596,53 @@ describe("upgrade command — filter baseline is the marker, not the installed v
     expect(result.pending.map((e) => e.title)).toEqual(["explicit-from-test-entry"]);
   });
 });
+
+describe("changes.json codemod fields resolve to real published scripts", () => {
+  function findChangesJsonFiles(dir: string): string[] {
+    const found: string[] = [];
+    for (const name of readdirSync(dir)) {
+      if (name === "node_modules") continue;
+      const full = join(dir, name);
+      if (statSync(full).isDirectory()) {
+        found.push(...findChangesJsonFiles(full));
+      } else if (name === "changes.json") {
+        found.push(full);
+      }
+    }
+    return found;
+  }
+
+  test("every codemod field is a scripts/codemod/*.ts path that resolves to an existing published script", () => {
+    const coreChangelog = findCoreChangelogFile(REAL_REPO_ROOT);
+    const changesJsonFiles = [
+      ...(coreChangelog ? [coreChangelog] : []),
+      ...findFeaturesDirs(REAL_REPO_ROOT).flatMap((dir) => findChangesJsonFiles(dir)),
+    ];
+    expect(changesJsonFiles.length).toBeGreaterThan(0);
+
+    const offenders: string[] = [];
+    for (const file of changesJsonFiles) {
+      const entries = JSON.parse(readFileSync(file, "utf-8")) as ReadonlyArray<{
+        readonly version: string;
+        readonly title: string;
+        readonly codemod?: string;
+      }>;
+      for (const entry of entries) {
+        if (typeof entry.codemod !== "string") continue;
+        if (/\s/.test(entry.codemod)) {
+          offenders.push(
+            `${file} · ${entry.version} "${entry.title}": codemod is a shell command, not a path: "${entry.codemod}"`,
+          );
+          continue;
+        }
+        if (resolveCodemodScript(REAL_REPO_ROOT, entry.codemod) === null) {
+          offenders.push(
+            `${file} · ${entry.version} "${entry.title}": codemod path does not resolve: "${entry.codemod}"`,
+          );
+        }
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/changes.json

@@ -17,8 +17,8 @@
     "type": "breaking",
     "title": "ctx.db.unsafeRaw(reason) gated by escapeHatch, tenancy: \"global\" invariants, bundled features migrated off ctx.db.raw (fw#2858).",
     "detail": "`TenantDb.unsafeRaw(reason)` returns the unfiltered `DbRunner` only when the calling write or query handler declares `escapeHatch: { reason }` (lifecycle hooks: `r.hook(..., { escapeHatch })`; a hook no longer inherits the handler's grant, same as the #2859 SYSTEM identity-switch gate). Without a declaration it throws `AccessDeniedError`; an empty reason throws `Error`. `r.systemScope()` features keep using `ctx.systemDb.unsafeRaw(reason)`. `TenantDb.raw` stays deprecated until fw#2860. `createTenantDb`'s 7th parameter changed from an `EscapeHatchDeclaration` to `TenantDbGrants` `{ globalWrites?, unsafeRaw? }`; `withUnsafeRawGrant(tenantDb, grant)` rebinds the unsafeRaw grant. `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant` are renamed to `bindHookEscapeHatchGrant`/`withHookEscapeHatchGrant`. Global tenancy: a `tenancy: \"global\"` entity must declare `systemStream: true` (boot validator + executor) and its create/update payloads may not carry a non-SYSTEM `tenantId`; tenant-mode `insertOne` into a global table with a `tenant_id` column and `db.global(table)` writes with a non-SYSTEM `tenantId` are rejected; `defineUnmanagedTable({ tenancy: \"global\" })` rejects a `tenant_id` column; new `declareGlobalTenancy(table)` declares a plain `table()` store without `tenant_id` as global. Bundled features: `userEntity` is `tenancy: \"global\"`, `store_global_feature_state` is declared global, and every bundled `ctx.db.raw` call site now uses `ctx.db.global(table)`, a filtered `ctx.db` method, or `ctx.db.unsafeRaw(reason)` with an `escapeHatch` on the handler. Handlers that call the auth-mfa `mfaStatusChecker`/MFA code verifier callbacks, handlers wrapped by cap-counter `withStockCap` (declares it automatically) and callers of the custom-fields quota/field-access query helpers now need that declaration.",
-    "migration": "Replace each `ctx.db.raw` use: reads of a `tenancy: \"global\"` table → `ctx.db.global(table).selectMany/fetchOne(...)`; reads/inserts whose where/values only use the caller's own tenantId → `ctx.db.selectMany/fetchOne/insertOne(table, ...)` (method form); everything else → `ctx.db.unsafeRaw(\"<what is read/written and why the tenant filter cannot apply>\")` plus `escapeHatch: { reason }` on the write/query handler definition or in the `r.hook` options. Generic reasons (todo, legacy, migration) fail infra#788. `bun scripts/migrate-db-raw.ts --dry-run <paths>` rewrites the global-table and own-tenant cases and lists the remaining sites; drop `--dry-run` to apply. Custom handlers calling `mfaStatusChecker`/the MFA code verifier or the custom-fields query helpers must declare `escapeHatch`. Direct `createTenantDb(..., escapeHatch)` calls pass `{ globalWrites: escapeHatch }` (and `unsafeRaw` if needed). Rename imports of `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant`. `defineUnmanagedTable({ tenancy: \"global\" })` definitions must drop their `tenant_id` column; `tenancy: \"global\"` entities must add `systemStream: true`.",
-    "codemod": "bun scripts/migrate-db-raw.ts --dry-run <paths>"
+    "migration": "Replace each `ctx.db.raw` use: reads of a `tenancy: \"global\"` table → `ctx.db.global(table).selectMany/fetchOne(...)`; reads/inserts whose where/values only use the caller's own tenantId → `ctx.db.selectMany/fetchOne/insertOne(table, ...)` (method form); everything else → `ctx.db.unsafeRaw(\"<what is read/written and why the tenant filter cannot apply>\")` plus `escapeHatch: { reason }` on the write/query handler definition or in the `r.hook` options. Generic reasons (todo, legacy, migration) fail infra#788. `kumiko-upgrade --apply` runs the migrate-db-raw codemod automatically, rewriting the global-table and own-tenant cases and listing the remaining sites for manual review. Custom handlers calling `mfaStatusChecker`/the MFA code verifier or the custom-fields query helpers must declare `escapeHatch`. Direct `createTenantDb(..., escapeHatch)` calls pass `{ globalWrites: escapeHatch }` (and `unsafeRaw` if needed). Rename imports of `bindHookIdentitySwitchGrant`/`withHookIdentitySwitchGrant`. `defineUnmanagedTable({ tenancy: \"global\" })` definitions must drop their `tenant_id` column; `tenancy: \"global\"` entities must add `systemStream: true`.",
+    "codemod": "scripts/codemod/migrate-db-raw.ts"
   },
   {
     "version": "0.267.0",

package/src/scripts/codemod/migrate-db-raw.ts

@@ -0,0 +1,397 @@
+#!/usr/bin/env bun
+// migrate-db-raw — rewrites standalone bun-db helper calls that manually pass
+// ctx.db.raw to their TenantDb method-form equivalent (db.global(table)... /
+// db.selectMany|fetchOne|insertOne(...)) wherever the rewrite is provably
+// safe, and reports every remaining ctx.db.raw-ish access for manual review.
+//
+// Usage:
+//   bun scripts/codemod/migrate-db-raw.ts [--dry-run] [--global-tables a,b] <path...>
+
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Node, Project, type SourceFile, SyntaxKind, VariableDeclarationKind } from "ts-morph";
+
+const DEFAULT_GLOBAL_TABLES: ReadonlySet<string> = new Set([
+  "userTable",
+  "globalFeatureStateTable",
+]);
+const PRUNABLE_FN_NAMES: ReadonlySet<string> = new Set(["selectMany", "fetchOne", "insertOne"]);
+const OWN_TENANT_FN_NAMES: ReadonlySet<string> = new Set(["selectMany", "fetchOne", "insertOne"]);
+const GLOBAL_TABLE_FN_NAMES: ReadonlySet<string> = new Set(["selectMany", "fetchOne"]);
+const TENANT_ID_SOURCES: ReadonlySet<string> = new Set([
+  "event.user.tenantId",
+  "query.user.tenantId",
+  "ctx.user.tenantId",
+]);
+const RAW_RECEIVER_IDENTIFIERS: ReadonlySet<string> = new Set([
+  "db",
+  "tdb",
+  "scopedDb",
+  "outsideTx",
+]);
+const MANUAL_TEXT_LIMIT = 100;
+
+export type RewriteRule = "global-table" | "own-tenant";
+
+export interface Rewrite {
+  readonly file: string;
+  readonly line: number;
+  readonly rule: RewriteRule;
+  readonly before: string;
+  readonly after: string;
+}
+
+export interface ManualSite {
+  readonly file: string;
+  readonly line: number;
+  readonly enclosing: string;
+  readonly text: string;
+}
+
+export interface MigrateDbRawResult {
+  readonly output: string;
+  readonly rewrites: Rewrite[];
+  readonly manual: ManualSite[];
+}
+
+function isRawOnCtxDb(argExpr: Node): boolean {
+  return argExpr.getText() === "ctx.db.raw";
+}
+
+function enclosingFunctionScope(node: Node): Node {
+  return (
+    node.getFirstAncestor(
+      (n) =>
+        Node.isFunctionDeclaration(n) ||
+        Node.isArrowFunction(n) ||
+        Node.isFunctionExpression(n) ||
+        Node.isMethodDeclaration(n),
+    ) ?? node.getSourceFile()
+  );
+}
+
+function isConstTenantIdBinding(scope: Node, varName: string): boolean {
+  return scope.getDescendantsOfKind(SyntaxKind.VariableDeclaration).some((decl) => {
+    if (decl.getName() !== varName) return false;
+    const statement = decl.getVariableStatement();
+    if (!statement || statement.getDeclarationKind() !== VariableDeclarationKind.Const)
+      return false;
+    const initializer = decl.getInitializer();
+    return initializer !== undefined && TENANT_ID_SOURCES.has(initializer.getText());
+  });
+}
+
+function isValidOwnTenantIdValue(valueNode: Node): boolean {
+  if (TENANT_ID_SOURCES.has(valueNode.getText())) return true;
+  if (!Node.isIdentifier(valueNode)) return false;
+  return isConstTenantIdBinding(enclosingFunctionScope(valueNode), valueNode.getText());
+}
+
+function objectHasValidOwnTenantId(obj: Node): boolean {
+  if (!Node.isObjectLiteralExpression(obj)) return false;
+  for (const prop of obj.getProperties()) {
+    if (Node.isPropertyAssignment(prop) && prop.getName() === "tenantId") {
+      const init = prop.getInitializer();
+      return init !== undefined && isValidOwnTenantIdValue(init);
+    }
+    if (Node.isShorthandPropertyAssignment(prop) && prop.getName() === "tenantId") {
+      return isConstTenantIdBinding(enclosingFunctionScope(prop), "tenantId");
+    }
+  }
+  return false;
+}
+
+interface PendingRewrite {
+  readonly callExpr: Node;
+  readonly rule: RewriteRule;
+  readonly before: string;
+  readonly after: string;
+  readonly line: number;
+}
+
+function planRewrite(
+  callExpr: Node,
+  globalTables: ReadonlySet<string>,
+): PendingRewrite | undefined {
+  if (!Node.isCallExpression(callExpr)) return undefined;
+  const calleeExpr = callExpr.getExpression();
+  if (!Node.isIdentifier(calleeExpr)) return undefined;
+  const fnName = calleeExpr.getText();
+  const args = callExpr.getArguments();
+  if (args.length === 0 || !isRawOnCtxDb(args[0]!)) return undefined;
+
+  const typeArgs = callExpr.getTypeArguments();
+  const typeArgsText =
+    typeArgs.length > 0 ? `<${typeArgs.map((t) => t.getText()).join(", ")}>` : "";
+
+  if (GLOBAL_TABLE_FN_NAMES.has(fnName) && args.length >= 2) {
+    const tableArg = args[1]!;
+    if (Node.isIdentifier(tableArg) && globalTables.has(tableArg.getText())) {
+      const rest = args.slice(2).map((a) => a.getText());
+      const after = `ctx.db.global(${tableArg.getText()}).${fnName}${typeArgsText}(${rest.join(", ")})`;
+      return {
+        callExpr,
+        rule: "global-table",
+        before: callExpr.getText(),
+        after,
+        line: callExpr.getStartLineNumber(),
+      };
+    }
+  }
+
+  if (OWN_TENANT_FN_NAMES.has(fnName) && args.length >= 3) {
+    const objArg = args[2]!;
+    if (objectHasValidOwnTenantId(objArg)) {
+      const rest = [args[1]!, objArg, ...args.slice(3)].map((a) => a.getText());
+      const after = `ctx.db.${fnName}${typeArgsText}(${rest.join(", ")})`;
+      return {
+        callExpr,
+        rule: "own-tenant",
+        before: callExpr.getText(),
+        after,
+        line: callExpr.getStartLineNumber(),
+      };
+    }
+  }
+
+  return undefined;
+}
+
+function isTenantDbRawAccess(pae: Node): boolean {
+  if (!Node.isPropertyAccessExpression(pae)) return false;
+  if (pae.getName() !== "raw") return false;
+  const receiver = pae.getExpression();
+  if (receiver.getText().endsWith(".db")) return true;
+  if (Node.isIdentifier(receiver) && RAW_RECEIVER_IDENTIFIERS.has(receiver.getText())) return true;
+  if (
+    Node.isCallExpression(receiver) &&
+    receiver.getExpression().getText().startsWith("ctx.systemDb.")
+  )
+    return true;
+  return false;
+}
+
+function enclosingName(node: Node): string {
+  let current: Node | undefined = node.getParent();
+  while (current) {
+    if (Node.isFunctionDeclaration(current) && current.getName()) return current.getName()!;
+    if (Node.isMethodDeclaration(current)) return current.getName();
+    if (Node.isPropertyAssignment(current)) return current.getName();
+    if (Node.isVariableDeclaration(current)) return current.getName();
+    current = current.getParent();
+  }
+  return "<module>";
+}
+
+function truncate(text: string, limit: number): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > limit ? `${collapsed.slice(0, limit)}…` : collapsed;
+}
+
+function directArgumentCall(pae: Node): Node | undefined {
+  const parent = pae.getParent();
+  if (parent && Node.isCallExpression(parent) && parent.getArguments().some((a) => a === pae)) {
+    return parent;
+  }
+  return undefined;
+}
+
+function collectManualSite(pae: Node, fileName: string): ManualSite {
+  const reportNode = directArgumentCall(pae) ?? pae;
+  return {
+    file: fileName,
+    line: reportNode.getStartLineNumber(),
+    enclosing: enclosingName(pae),
+    text: truncate(reportNode.getText(), MANUAL_TEXT_LIMIT),
+  };
+}
+
+function isPropertyAccessName(id: Node): boolean {
+  const parent = id.getParent();
+  return Node.isPropertyAccessExpression(parent) && parent.getNameNode() === id;
+}
+
+function pruneUnusedDbImports(sourceFile: SourceFile): void {
+  for (const importDecl of sourceFile.getImportDeclarations()) {
+    for (const spec of [...importDecl.getNamedImports()]) {
+      if (!PRUNABLE_FN_NAMES.has(spec.getName())) continue;
+      const localName = spec.getAliasNode()?.getText() ?? spec.getName();
+      const nameNode = spec.getAliasNode() ?? spec.getNameNode();
+      const stillUsed = sourceFile
+        .getDescendantsOfKind(SyntaxKind.Identifier)
+        .some((id) => id !== nameNode && id.getText() === localName && !isPropertyAccessName(id));
+      if (!stillUsed) spec.remove();
+    }
+    if (
+      importDecl.getNamedImports().length === 0 &&
+      !importDecl.getDefaultImport() &&
+      !importDecl.getNamespaceImport()
+    ) {
+      importDecl.remove();
+    }
+  }
+}
+
+export function migrateDbRawSource(
+  source: string,
+  fileName: string,
+  opts: { globalTables: ReadonlySet<string> },
+): MigrateDbRawResult {
+  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+  const sourceFile = project.createSourceFile(fileName, source);
+
+  const pending: PendingRewrite[] = [];
+  for (const callExpr of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const plan = planRewrite(callExpr, opts.globalTables);
+    if (plan) pending.push(plan);
+  }
+
+  const rewrites: Rewrite[] = [];
+  for (const plan of pending) {
+    if (plan.callExpr.wasForgotten()) continue;
+    plan.callExpr.replaceWithText(plan.after);
+    rewrites.push({
+      file: fileName,
+      line: plan.line,
+      rule: plan.rule,
+      before: plan.before,
+      after: plan.after,
+    });
+  }
+
+  pruneUnusedDbImports(sourceFile);
+
+  const manual: ManualSite[] = [];
+  for (const pae of sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+    if (isTenantDbRawAccess(pae)) manual.push(collectManualSite(pae, fileName));
+  }
+
+  return { output: sourceFile.getFullText(), rewrites, manual };
+}
+
+class CliError extends Error {}
+
+interface CliOptions {
+  readonly dryRun: boolean;
+  readonly globalTables: ReadonlySet<string>;
+  readonly paths: string[];
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let dryRun = false;
+  let globalTables: ReadonlySet<string> = DEFAULT_GLOBAL_TABLES;
+  const paths: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--global-tables") {
+      const value = argv[++i];
+      if (!value) throw new CliError("--global-tables requires a comma-separated value");
+      globalTables = new Set(
+        value
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s) => s.length > 0),
+      );
+      continue;
+    }
+    if (arg.startsWith("--")) throw new CliError(`unknown flag: ${arg}`);
+    paths.push(arg);
+  }
+
+  if (paths.length === 0) throw new CliError("at least one path is required");
+  return { dryRun, globalTables, paths };
+}
+
+function isMigratableFile(name: string): boolean {
+  if (!/\.(ts|tsx)$/.test(name)) return false;
+  if (name.endsWith(".test.ts") || name.endsWith(".test.tsx")) return false;
+  return true;
+}
+
+function walkDir(dir: string, out: string[]): void {
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name === "__tests__") continue;
+    const full = join(dir, name);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      walkDir(full, out);
+      continue;
+    }
+    if (isMigratableFile(name)) out.push(full);
+  }
+}
+
+function collectFiles(paths: string[]): string[] {
+  const files: string[] = [];
+  for (const p of paths) {
+    const abs = resolve(p);
+    const stat = statSync(abs);
+    if (stat.isDirectory()) walkDir(abs, files);
+    else if (isMigratableFile(abs)) files.push(abs);
+  }
+  return files;
+}
+
+async function main(): Promise<void> {
+  let options: CliOptions;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof CliError) {
+      console.error(`[migrate-db-raw] ${err.message}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  const files = collectFiles(options.paths);
+  const allRewrites: Rewrite[] = [];
+  const allManual: ManualSite[] = [];
+  let filesChanged = 0;
+
+  for (const file of files) {
+    const before = readFileSync(file, "utf8");
+    const result = migrateDbRawSource(before, file, { globalTables: options.globalTables });
+    allRewrites.push(...result.rewrites);
+    allManual.push(...result.manual);
+
+    if (result.rewrites.length === 0) continue;
+    filesChanged += 1;
+
+    if (options.dryRun) {
+      console.log(`\n=== ${file} (${result.rewrites.length} rewrite(s)) ===`);
+      for (const r of result.rewrites) {
+        console.log(`${file}:${r.line} [${r.rule}]`);
+        console.log(`- ${r.before}`);
+        console.log(`+ ${r.after}`);
+      }
+    } else {
+      writeFileSync(file, result.output);
+    }
+  }
+
+  const globalCount = allRewrites.filter((r) => r.rule === "global-table").length;
+  const ownTenantCount = allRewrites.filter((r) => r.rule === "own-tenant").length;
+  console.log(
+    `\n[migrate-db-raw] ${options.dryRun ? "would change" : "changed"} ${filesChanged} file(s); ` +
+      `rewrites: global-table=${globalCount}, own-tenant=${ownTenantCount}`,
+  );
+
+  if (allManual.length > 0) {
+    console.log(`\n[migrate-db-raw] manual review needed (${allManual.length}):`);
+    for (const m of allManual) {
+      console.log(`${m.file}:${m.line}  ${m.enclosing}  ${m.text}`);
+    }
+  }
+
+  process.exit(0);
+}
+
+if (import.meta.main) {
+  await main();
+}