@cosmicdrift/kumiko-framework 0.213.0 → 0.215.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.213.0",
+  "version": "0.215.0",
   "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>",
@@ -194,7 +194,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.213.0",
+    "@cosmicdrift/kumiko-types": "0.215.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -210,7 +210,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.213.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.215.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -1,8 +1,21 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { resolveCodemodScript, runUpgradeCli, type UpgradeCliOut } from "../upgrade-cli";
+import {
+  findCodemodScriptsRoot,
+  resolveCodemodScript,
+  runUpgradeCli,
+  type UpgradeCliOut,
+} from "../upgrade-cli";
 
 function makeSpyOutput(): {
   readonly out: UpgradeCliOut;
@@ -165,9 +178,10 @@ describe("upgrade command — enterprise package layout", () => {
   });
 });
 
-// The repo actually checked out on disk — scripts/codemod/ isn't published,
-// so --apply only ever works against a real local framework checkout.
+// Codemod scripts ship inside packages/framework/src/scripts/codemod — the
+// published @cosmicdrift/kumiko-framework package (fw#2301).
 const REAL_REPO_ROOT = join(import.meta.dir, "../../../..");
+const REAL_FRAMEWORK_SRC = join(import.meta.dir, "..");
 const REAL_CODEMOD = "scripts/codemod/crypto-shredding-testing-move.ts";
 
 function breakingEntryWithCodemod(codemod: string | undefined): string {
@@ -190,31 +204,46 @@ const LEGACY_IMPORT_FIXTURE = [
 
 describe("resolveCodemodScript", () => {
   test("resolves a real script under scripts/codemod/", () => {
-    const resolved = resolveCodemodScript(REAL_REPO_ROOT, REAL_CODEMOD);
-    expect(resolved).toBe(join(REAL_REPO_ROOT, REAL_CODEMOD));
+    const resolved = resolveCodemodScript(REAL_FRAMEWORK_SRC, REAL_CODEMOD);
+    expect(resolved).toBe(join(REAL_FRAMEWORK_SRC, REAL_CODEMOD));
   });
 
   test("rejects an absolute path", () => {
-    expect(resolveCodemodScript(REAL_REPO_ROOT, "/etc/passwd.ts")).toBeNull();
+    expect(resolveCodemodScript(REAL_FRAMEWORK_SRC, "/etc/passwd.ts")).toBeNull();
   });
 
   test("rejects path traversal that escapes scripts/codemod/", () => {
     expect(
-      resolveCodemodScript(REAL_REPO_ROOT, "scripts/codemod/../../package.json.ts"),
+      resolveCodemodScript(REAL_FRAMEWORK_SRC, "scripts/codemod/../../package.json.ts"),
     ).toBeNull();
-    expect(resolveCodemodScript(REAL_REPO_ROOT, "../outside/x.ts")).toBeNull();
+    expect(resolveCodemodScript(REAL_FRAMEWORK_SRC, "../outside/x.ts")).toBeNull();
   });
 
   test("rejects a non-.ts file", () => {
-    expect(resolveCodemodScript(REAL_REPO_ROOT, "scripts/codemod/README.md")).toBeNull();
+    expect(resolveCodemodScript(REAL_FRAMEWORK_SRC, "scripts/codemod/README.md")).toBeNull();
   });
 
   test("rejects a script that doesn't exist", () => {
-    expect(resolveCodemodScript(REAL_REPO_ROOT, "scripts/codemod/does-not-exist.ts")).toBeNull();
+    expect(
+      resolveCodemodScript(REAL_FRAMEWORK_SRC, "scripts/codemod/does-not-exist.ts"),
+    ).toBeNull();
   });
 
   test("rejects an undefined codemod field", () => {
-    expect(resolveCodemodScript(REAL_REPO_ROOT, undefined)).toBeNull();
+    expect(resolveCodemodScript(REAL_FRAMEWORK_SRC, undefined)).toBeNull();
+  });
+
+  test("findCodemodScriptsRoot resolves through a hoisted node_modules symlink", () => {
+    const cwd = tmp({ "apps/web/package.json": "{}" });
+    const nmPkgDir = join(cwd, "node_modules/@cosmicdrift/kumiko-framework");
+    mkdirSync(join(nmPkgDir, ".."), { recursive: true });
+    symlinkSync(REAL_FRAMEWORK_SRC.replace(/\/src$/, ""), nmPkgDir, "dir");
+
+    const root = findCodemodScriptsRoot(join(cwd, "apps/web"));
+    expect(root).toBe(join(nmPkgDir, "src"));
+
+    const resolved = resolveCodemodScript(root!, REAL_CODEMOD);
+    expect(resolved).toBe(join(nmPkgDir, "src", REAL_CODEMOD));
   });
 });
 

package/src/api/__tests__/jwt.test.ts

@@ -94,6 +94,18 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
     const payload = await jwt.verify(await jwt.sign(user));
     expect(payload.timezone).toBeUndefined();
   });
+
+  // fw#2333 — SessionUser.locale must survive the sign/verify roundtrip,
+  // same contract as timezone above.
+  it("round-trips the locale claim when set", async () => {
+    const payload = await jwt.verify(await jwt.sign({ ...user, locale: "de-DE" }));
+    expect(payload.locale).toBe("de-DE");
+  });
+
+  it("omits the locale claim when unset", async () => {
+    const payload = await jwt.verify(await jwt.sign(user));
+    expect(payload.locale).toBeUndefined();
+  });
 });
 
 describe("createJwtHelper — keyring form", () => {

package/src/api/__tests__/request-locale.integration.test.ts

@@ -4,7 +4,7 @@
 // can't be exercised via createTestDispatcher, which skips the HTTP layer
 // entirely.
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
@@ -22,11 +22,15 @@ const localeProbe = defineFeature("locale-probe", (r) => {
   );
 });
 
-async function readLocale(stack: TestStack, headers: Record<string, string>): Promise<string> {
+async function readLocale(
+  stack: TestStack,
+  headers: Record<string, string>,
+  user: SessionUser = createTestUser({ id: 1 }),
+): Promise<string> {
   const res = await stack.http.writeWithHeaders(
     "locale-probe:write:read-locale",
     {},
-    createTestUser({ id: 1 }),
+    user,
     headers,
   );
   const body = (await res.json()) as { data: { locale: string } };
@@ -94,3 +98,49 @@ describe("ctx.locale falls back to the app's boot-configured defaultLocale", ()
     expect(locale).toBe("ja");
   });
 });
+
+// fw#2333 — SessionUser.locale (persisted at login) sits between the
+// request-layer signal and the boot default: no live request signal falls
+// back to it, but a live signal still wins over it.
+describe("ctx.locale falls back to SessionUser.locale ahead of the boot default", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [localeProbe],
+      extraContext: { defaultLocale: "ja" },
+    });
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("no header signal falls back to the persisted SessionUser.locale", async () => {
+    const locale = await readLocale(stack, {}, createTestUser({ id: 1, locale: "de-DE" }));
+    expect(locale).toBe("de-DE");
+  });
+
+  test("X-Locale header still wins over a persisted SessionUser.locale", async () => {
+    const locale = await readLocale(
+      stack,
+      { [LOCALE_HEADER_NAME]: "fr-FR" },
+      createTestUser({ id: 1, locale: "de-DE" }),
+    );
+    expect(locale).toBe("fr-FR");
+  });
+
+  test("a forged/malformed SessionUser.locale falls through to the boot default", async () => {
+    const locale = await readLocale(
+      stack,
+      {},
+      createTestUser({ id: 1, locale: "<script>alert(1)</script>" }),
+    );
+    expect(locale).toBe("ja");
+  });
+
+  test("no SessionUser.locale set falls through to the boot default", async () => {
+    const locale = await readLocale(stack, {}, createTestUser({ id: 1 }));
+    expect(locale).toBe("ja");
+  });
+});

package/src/api/auth-middleware.ts

@@ -324,6 +324,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       tenantId: payload.tenantId,
       roles: derivedRoles ?? payload.roles,
       ...(payload.timezone ? { timezone: payload.timezone } : {}),
+      ...(payload.locale ? { locale: payload.locale } : {}),
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };

package/src/api/jwt.ts

@@ -13,6 +13,9 @@ export type JwtPayload = {
   // IANA zone from user.timezone, set at login — see SessionUser.timezone
   // (fw#1636). Absent → ctx.tz.user falls back to ctx.tz.tenant.
   timezone?: string;
+  // BCP-47 tag from user.locale, set at login — see SessionUser.locale
+  // (fw#2333). Absent → ctx.locale falls back further down the chain.
+  locale?: string;
   // Optional — present when a feature has registered auth claims via the
   // `r.authClaims()` hook system. Absent for stateless-JWT deployments
   // without auth-claims wiring.
@@ -110,6 +113,7 @@ export function createJwtHelper(
         roles: [...user.roles],
       };
       if (user.timezone) body.timezone = user.timezone;
+      if (user.locale) body.locale = user.locale;
       if (user.claims) body.claims = { ...user.claims };
 
       const header: jose.JWTHeaderParameters = keyring.signKid
@@ -162,6 +166,9 @@ export function createJwtHelper(
       if (typeof payload["timezone"] === "string") {
         result.timezone = payload["timezone"];
       }
+      if (typeof payload["locale"] === "string") {
+        result.locale = payload["locale"];
+      }
       const claims = payload["claims"];
       if (claims && typeof claims === "object") {
         result.claims = claims as DbRow;

package/src/db/queries/__tests__/unsafe-read-retrying.test.ts

@@ -0,0 +1,108 @@
+// #2323: event-store.ts's and projection-rebuild.ts's plain SELECT helpers
+// read via asRawClient(db).unsafe() directly, bypassing the #1163
+// closed-connection retry that only covered bun-db/query.ts's own
+// selectMany/countWhere. Routed the non-locking read call sites through
+// unsafeReadRetrying instead — this test mirrors
+// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
+// the retry now fires. Writes (insertSubsequentEventRow, upsertSnapshot,
+// markProjectionRebuilding, ...) stay unretried per #1358, and the
+// FOR UPDATE / FOR UPDATE SKIP LOCKED reads in event-consumer.ts are always
+// called inside transaction() (verified against their only call sites) — the
+// retry guard there is a no-op, so those are left as asRawClient calls too.
+
+import { describe, expect, test } from "bun:test";
+import {
+  selectAggregateMaxVersion,
+  selectEventsHighWaterMark,
+  selectNextEventIdAfter,
+  selectStreamMaxVersion,
+} from "../event-store";
+import {
+  countSubscribedEvents,
+  selectEventsForProjectionRebuildBatch,
+} from "../projection-rebuild";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], row: Record<string, unknown>): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [row];
+    },
+    begin: () => {
+      throw new Error("not used in test");
+    },
+  };
+  return client;
+}
+
+describe("framework db/queries — closed-connection retry (#2323)", () => {
+  test("selectStreamMaxVersion retries once and returns the version", async () => {
+    const db = fakeClient([closedConnectionError()], { v: 5 });
+    const result = await selectStreamMaxVersion(db as never, "agg1", "t1");
+    expect(result).toBe(5);
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectAggregateMaxVersion retries once and returns the version", async () => {
+    const db = fakeClient([closedConnectionError()], { v: 7 });
+    const result = await selectAggregateMaxVersion(db as never, "agg1");
+    expect(result).toBe(7);
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectEventsHighWaterMark retries once and returns the max id", async () => {
+    const db = fakeClient([closedConnectionError()], { max: 42n });
+    const result = await selectEventsHighWaterMark(db as never);
+    expect(result).toBe(42n);
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectNextEventIdAfter retries once and returns the next id", async () => {
+    const db = fakeClient([closedConnectionError()], { id: 43n });
+    const result = await selectNextEventIdAfter(db as never, 42n);
+    expect(result).toBe(43n);
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectEventsForProjectionRebuildBatch retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()], { id: "1", type: "created" });
+    const rows = await selectEventsForProjectionRebuildBatch(
+      db as never,
+      ["user"],
+      ["user:created"],
+      0n,
+      100,
+    );
+    expect(rows).toHaveLength(1);
+    expect(db.calls).toBe(2);
+  });
+
+  test("countSubscribedEvents retries once and returns the count", async () => {
+    const db = fakeClient([closedConnectionError()], { n: 12n });
+    const result = await countSubscribedEvents(db as never, ["user"], ["user:created"]);
+    expect(result).toBe(12n);
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()], { v: 5 });
+    await expect(selectStreamMaxVersion(db as never, "agg1", "t1")).rejects.toThrow(
+      "connection was closed",
+    );
+    expect(db.calls).toBe(2);
+  });
+});

package/src/db/queries/event-store.ts

@@ -5,7 +5,7 @@ import {
   isUniqueViolation,
 } from "../pg-error";
 import type { AnyDb } from "../query";
-import { asRawClient } from "../query";
+import { asRawClient, unsafeReadRetrying } from "../query";
 
 /** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
 export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void> {
@@ -175,7 +175,8 @@ export async function selectStreamMaxVersion(
   aggregateId: string,
   tenantId: string,
 ): Promise<number> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`,
     [aggregateId, tenantId],
   )) as ReadonlyArray<{ v: number | null }>;
@@ -184,7 +185,8 @@ export async function selectStreamMaxVersion(
 
 /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
 export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`,
     [aggregateId],
   )) as ReadonlyArray<{ v: number | null }>;
@@ -192,8 +194,10 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
 }
 
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,
+    [],
   )) as ReadonlyArray<{ max: bigint | string | number | null }>;
   const raw = rows[0]?.max;
   if (typeof raw === "bigint") return raw;
@@ -208,7 +212,8 @@ export async function selectEventsHeadId(db: AnyDb): Promise<bigint> {
 }
 
 export async function selectNextEventIdAfter(db: AnyDb, afterId: bigint): Promise<bigint | null> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT "id" FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT 1`,
     [afterId],
   )) as ReadonlyArray<{ id: string | bigint }>;

package/src/db/queries/projection-rebuild.ts

@@ -1,5 +1,5 @@
 import type { AnyDb } from "../query";
-import { asRawClient } from "../query";
+import { asRawClient, unsafeReadRetrying } from "../query";
 
 export async function markProjectionRebuilding(db: AnyDb, projectionName: string): Promise<void> {
   await asRawClient(db).unsafe(
@@ -26,7 +26,8 @@ export async function selectEventsForProjectionRebuildBatch(
   // Archived streams don't replay (Marten-aligned): their aggregates are
   // frozen ops-tombstones — replaying them would resurrect rows (or, for
   // stranded duplicate-aggregates like fw#832, collide on unique indexes).
-  return (await asRawClient(db).unsafe(
+  return (await unsafeReadRetrying(
+    db,
     `SELECT * FROM "kumiko_events" e
      WHERE e."aggregate_type" = ANY($1::text[])
        AND e."type" = ANY($2::text[])
@@ -53,7 +54,8 @@ export async function countSubscribedEvents(
   // Same archived-streams exclusion as the batch query — the #443 recompute
   // compares this count against applied events; a filter mismatch would make
   // every rebuild with an archived stream loop the full-re-replay forever.
-  const rows = (await asRawClient(db).unsafe(
+  const rows = (await unsafeReadRetrying(
+    db,
     `SELECT count(*)::bigint AS n FROM "kumiko_events" e
      WHERE e."aggregate_type" = ANY($1::text[])
        AND e."type" = ANY($2::text[])

package/src/db/query.ts

@@ -24,6 +24,7 @@ export {
   type TableInfo,
   transaction,
   type UpsertOnConflictOptions,
+  unsafeReadRetrying,
   updateMany,
   upsertByPk,
   upsertOnConflict,

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -700,7 +700,7 @@ describe("validateBoot — retention", () => {
     expect(matchingWarn).toBeUndefined();
   });
 
-  test("blockDelete with only a subjectRef-only field and no anonymize warns (#1645)", () => {
+  test("blockDelete with only a subjectRef-only field and no anonymize stays silent (#1645, narrowed by #2336)", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
         "lease",
@@ -718,6 +718,31 @@ describe("validateBoot — retention", () => {
     const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
       String(args[0]).includes('strategy="blockDelete" but no field has an anonymize-function'),
     );
+    expect(matchingWarn).toBeUndefined();
+  });
+
+  test("blockDelete with a subjectRef field plus an anonymizable subject field and no anonymize still warns (#2336)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "lease",
+        createEntity({
+          fields: {
+            authorId: createTextField({
+              personal: "ref",
+            }),
+            customerName: createTextField({
+              personal: "self",
+              find: "none",
+            }),
+          },
+          retention: { keepFor: "10y", strategy: "blockDelete" },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes('strategy="blockDelete" but no field has an anonymize-function'),
+    );
     expect(matchingWarn).toBeDefined();
   });
 

package/src/engine/boot-validator/pii-retention.ts

@@ -21,11 +21,10 @@ const FRAMEWORK_TIMESTAMP_FIELDS: ReadonlySet<string> = new Set([
 // werden statt erst beim ersten Cleanup-Run.
 const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 
-// A field carries a subject binding — pii/userOwned/tenantOwned mark
-// annotated content, subjectRef marks a bare FK into `user` with no
-// annotated content of its own but the same Art.17 obligations (#1645).
-function hasSubjectAnnotation(annot: ResolvedPiiFlags): boolean {
-  return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.subjectRef);
+// Excludes subjectRef: its `personal: "ref"` union member structurally
+// forbids `anonymize` (packages/types/src/fields.ts) — #2336.
+function hasAnonymizableSubjectField(annot: ResolvedPiiFlags): boolean {
+  return Boolean(annot.pii || annot.userOwned || annot.tenantOwned);
 }
 
 // --- PII / Subject-Key Annotations + Retention validation ---
@@ -222,7 +221,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         // blockDelete on an entity with no subject field is the correct
         // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
         const hasSubjectField = Object.values(fieldsByName).some(
-          (f) => hasSubjectAnnotation(f as ResolvedPiiFlags), // @cast-boundary schema-walk
+          (f) => hasAnonymizableSubjectField(f as ResolvedPiiFlags), // @cast-boundary schema-walk
         );
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
           const a = f as ResolvedPiiFlags; // @cast-boundary schema-walk

package/src/engine/feature-changelog.ts

@@ -15,7 +15,7 @@ export type ChangelogEntry = {
   readonly detail?: string;
   /** Required when type=breaking. Shown in `kumiko upgrade` output. */
   readonly migration?: string;
-  /** Path (repo-root-relative, under scripts/codemod/) run by `kumiko upgrade --apply`. */
+  /** Path (relative to packages/framework/src/, under scripts/codemod/) run by `kumiko upgrade --apply`. */
   readonly codemod?: string;
 };
 

package/src/pipeline/dispatch-shared.ts

@@ -51,7 +51,7 @@ import {
 } from "../event-store/snapshot";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster";
 import { createFileContext } from "../files/file-handle";
-import { DEFAULT_LOCALE } from "../i18n/request-locale";
+import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale";
 import {
   createMetricsHandle,
   createNoopMetricsHandle,
@@ -623,9 +623,13 @@ export async function buildHandlerContext(
 
   // ctx.locale — request-layer signal (X-Locale header → Accept-Language,
   // resolved once at the HTTP boundary by request-id-middleware.ts) wins;
-  // falls back to the app's boot-configured defaultLocale, then
-  // DEFAULT_LOCALE. Mirrors ctx.tz's Request → Boot-Default chain above.
-  const locale = reqCtx?.locale ?? context.defaultLocale ?? DEFAULT_LOCALE;
+  // then SessionUser.locale (set at login, see fw#2333 — stale until
+  // re-login, same tradeoff as ctx.tz.user); falls back to the app's
+  // boot-configured defaultLocale, then DEFAULT_LOCALE. Mirrors ctx.tz's
+  // Request → Session → Boot-Default chain above.
+  const safeUserLocale =
+    user.locale !== undefined && isValidLocaleTag(user.locale) ? user.locale : undefined;
+  const locale = reqCtx?.locale ?? safeUserLocale ?? context.defaultLocale ?? DEFAULT_LOCALE;
 
   return {
     ...context,

package/src/scripts/codemod/README.md

@@ -0,0 +1,36 @@
+# consumer-facing codemods
+
+This directory holds the codemod scripts `kumiko upgrade --apply` runs for
+consumers of `@cosmicdrift/kumiko-framework`. It ships as part of the
+published package (under `src/`), unlike `scripts/codemod/` at the repo
+root, which is internal bun-cutover tooling for this repo's own migration
+and never gets published.
+
+`crypto-shredding-testing-move.ts` rewrites the moved
+`resetPiiSubjectKmsForTests` import path; it's wired into
+`packages/bundled-features/src/crypto-shredding/changes.json`'s `codemod`
+field and runs automatically via `kumiko upgrade --apply`.
+
+## pii-personal-migration.ts
+
+Migrates `create*Field(...)` calls from the old flag-based PII API (`pii`,
+`userOwned`, `tenantOwned`, `subjectRef`, `allowPlaintext`, `lookupable`,
+`searchable`, `sensitive`) to the author-facing `personal`/`find` API
+(kumiko-framework#2250). Idempotent — safe to re-run against already
+migrated code (no-ops on fields carrying `personal`).
+
+`createTenantConfig`/`createUserConfig`/etc. are out of scope by
+construction (name doesn't match `create*Field`).
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/pii-personal-migration.ts <targetDir> [--dry-run]
+```
+
+Anything it can't map mechanically (two subject flags on one field,
+`sensitive` + `lookupable`/`searchable` together, `piiEncrypted` on an
+entity field, a raw object literal with subject flags outside a
+`create*Field(...)` call) is reported with file:line instead of guessed
+at — fix those by hand. The report also lists every field that newly
+gains `lookupable` (searchable-only fields resolving to `find: "fuzzy"`)
+— each of those needs a `_bidx` column migration, which this script does
+not write.

package/src/scripts/codemod/crypto-shredding-testing-move.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+// Rewrites `import { resetPiiSubjectKmsForTests, resetBlindIndexKeyForTests }
+// from "@cosmicdrift/kumiko-framework/crypto"` to import both names from
+// "@cosmicdrift/kumiko-framework/testing" instead (fw#1631). Only the
+// package barrel specifier is rewritten — relative deep-imports of the
+// defining module are left untouched, per the changes.json migration note.
+// Idempotent: an already-migrated file has nothing left to move.
+//
+// Usage: bun scripts/codemod/crypto-shredding-testing-move.ts <targetDir> [--dry-run]
+
+import { resolve } from "node:path";
+import { Glob } from "bun";
+import { Project } from "ts-morph";
+
+const OLD_SPECIFIER = "@cosmicdrift/kumiko-framework/crypto";
+const NEW_SPECIFIER = "@cosmicdrift/kumiko-framework/testing";
+const MOVED_NAMES = new Set(["resetPiiSubjectKmsForTests", "resetBlindIndexKeyForTests"]);
+
+function findTargetFiles(rootDir: string): string[] {
+  const glob = new Glob("**/*.{ts,tsx}");
+  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
+  const files: string[] = [];
+  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
+    const abs = resolve(rootDir, file);
+    if (EXCLUDE.some((p) => abs.includes(p))) continue;
+    files.push(abs);
+  }
+  return files.sort();
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const dryRun = process.argv.includes("--dry-run");
+  const rootDir = resolve(positional[0] ?? process.cwd());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  let movedNames = 0;
+
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const oldImport = sourceFile
+      .getImportDeclarations()
+      .find((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER);
+    if (!oldImport) continue;
+
+    const movedHere = oldImport.getNamedImports().filter((spec) => MOVED_NAMES.has(spec.getName()));
+    if (movedHere.length === 0) continue;
+
+    const names = movedHere.map((spec) => spec.getName());
+
+    const existingNewImport = sourceFile
+      .getImportDeclarations()
+      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER);
+    if (existingNewImport) {
+      const already = new Set(existingNewImport.getNamedImports().map((s) => s.getName()));
+      for (const name of names) {
+        if (!already.has(name)) existingNewImport.addNamedImport(name);
+      }
+    } else {
+      sourceFile.addImportDeclaration({ moduleSpecifier: NEW_SPECIFIER, namedImports: names });
+    }
+
+    for (const spec of movedHere) spec.remove();
+    const remaining =
+      oldImport.getNamedImports().length > 0 ||
+      !!oldImport.getDefaultImport() ||
+      !!oldImport.getNamespaceImport();
+    if (!remaining) oldImport.remove();
+
+    touchedFiles++;
+    movedNames += names.length;
+    if (!dryRun) sourceFile.saveSync();
+  }
+
+  console.log(`\nScanned ${files.length} files under ${rootDir}${dryRun ? " (dry-run)" : ""}.`);
+  console.log(
+    `Touched ${touchedFiles} files, moved ${movedNames} import(s) from "${OLD_SPECIFIER}" to "${NEW_SPECIFIER}".\n`,
+  );
+}
+
+await main();

package/src/scripts/codemod/pii-personal-migration.ts

@@ -0,0 +1,464 @@
+#!/usr/bin/env bun
+// Migrates create*Field(...) calls from the old flag-based PII API (pii,
+// userOwned, tenantOwned, subjectRef, allowPlaintext, lookupable,
+// searchable, sensitive) to the author-facing personal/find API
+// (kumiko-framework#2250). Idempotent — re-running is a no-op on already
+// migrated fields (skipped once a `personal` property is present).
+//
+// Mapping table (exact):
+//   pii: true                           -> personal: "self"
+//   userOwned: { ownerField: "x" }      -> personal: { of: "x" }
+//   tenantOwned: true                   -> personal: "tenant"
+//   subjectRef: true                    -> personal: "ref"
+//   allowPlaintext: "R"                 -> personal: false, reason: "<R, normalized to snake_case>"
+//   lookupable: true (alone)            -> find: "exact"
+//   lookupable: true + searchable: true -> find: "fuzzy"
+//   searchable: true (alone)            -> find: "fuzzy"
+//   sensitive: true                     -> find: "secret"
+//   none of the above                   -> find: "none"
+// `find` only applies to text/longText fields, and only when the subject
+// is neither "ref" nor `personal: false` (see PersonalAnnotations in
+// packages/types/src/fields.ts). Never guesses: anything outside this
+// table is reported (file:line) instead of transformed.
+//
+// Usage: bun scripts/codemod/pii-personal-migration.ts <targetDir> [--dry-run]
+
+import { relative, resolve } from "node:path";
+import { Glob } from "bun";
+import {
+  Node,
+  type ObjectLiteralExpression,
+  Project,
+  type PropertyAssignment,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+
+const SUBJECT_FLAG_NAMES = [
+  "pii",
+  "userOwned",
+  "tenantOwned",
+  "subjectRef",
+  "allowPlaintext",
+] as const;
+type SubjectFlagName = (typeof SUBJECT_FLAG_NAMES)[number];
+
+// `create*Field` factories that accept `find` (text/longText) — see
+// packages/framework/src/engine/factories.ts.
+const TEXT_FIND_FACTORIES = new Set(["createTextField"]);
+const LONGTEXT_FIND_FACTORIES = new Set(["createLongTextField"]);
+// Accept `personal` but never `find` (PersonalAnnotationsNoFind).
+const NO_FIND_FACTORIES = new Set([
+  "createSelectField",
+  "createMultiSelectField",
+  "createNumberField",
+  "createBigIntField",
+  "createDecimalField",
+  "createEmbeddedField",
+  "createEmbeddedListField",
+  "createJsonbField",
+  "createDateField",
+  "createTimestampField",
+  "createTzField",
+  "createLocatedTimestampField",
+]);
+// No personal-annotation support at all — a subject flag here is a bug.
+const NO_PERSONAL_FACTORIES = new Set([
+  "createBooleanField",
+  "createMoneyField",
+  "createFileField",
+  "createImageField",
+  "createFilesField",
+  "createImagesField",
+  "createDerivedField",
+]);
+// Overrides live in argument position 1, not 0.
+const OVERRIDES_ARG_INDEX_1 = new Set(["createEmbeddedField", "createEmbeddedListField"]);
+
+const FIELD_FACTORY_RE = /^create\w*Field$/;
+
+type ReportEntry = { readonly file: string; readonly line: number; readonly reason: string };
+type FindBucket = "exact" | "fuzzy" | "none" | "secret" | "ref" | "personal-false" | "no-find";
+
+const reports: ReportEntry[] = [];
+const newLookupableSites: ReportEntry[] = [];
+const counts: Record<FindBucket, number> = {
+  exact: 0,
+  fuzzy: 0,
+  none: 0,
+  secret: 0,
+  ref: 0,
+  "personal-false": 0,
+  "no-find": 0,
+};
+
+function report(node: Node, reason: string): void {
+  reports.push({
+    file: node.getSourceFile().getFilePath(),
+    line: node.getStartLineNumber(),
+    reason,
+  });
+}
+
+function isTrueLiteral(node: Node | undefined): boolean {
+  return !!node && node.getKind() === SyntaxKind.TrueKeyword;
+}
+
+function findProp(obj: ObjectLiteralExpression, name: string): PropertyAssignment | undefined {
+  const p = obj.getProperty(name);
+  return p && Node.isPropertyAssignment(p) ? p : undefined;
+}
+
+// Reason-string convention (infra/guards/guard-error-reasons.ts):
+// ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$ — lowercase snake_case, optional
+// dot-namespacing. Old allowPlaintext values are free-form kebab-case.
+function normalizeReasonSlug(raw: string): string {
+  const slug = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9.]+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^[._]+|[._]+$/g, "");
+  return /^[0-9]/.test(slug) ? `_${slug}` : slug;
+}
+
+type FieldCall = { readonly name: string; readonly objArg: ObjectLiteralExpression };
+
+function collectFieldCalls(sourceFile: SourceFile): FieldCall[] {
+  const calls: FieldCall[] = [];
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const exprNode = call.getExpression();
+    if (!Node.isIdentifier(exprNode)) continue;
+    const name = exprNode.getText();
+    // `createTenantConfig`/`createUserConfig`/etc. never match — they
+    // don't end in "Field", so they're out of scope by construction.
+    if (!FIELD_FACTORY_RE.test(name)) continue;
+
+    const argIndex = OVERRIDES_ARG_INDEX_1.has(name) ? 1 : 0;
+    const objArg = call.getArguments()[argIndex];
+    if (objArg && Node.isObjectLiteralExpression(objArg)) {
+      calls.push({ name, objArg });
+    }
+  }
+  return calls;
+}
+
+function reportRawSubjectLiterals(
+  sourceFile: SourceFile,
+  handled: ReadonlySet<ObjectLiteralExpression>,
+): void {
+  for (const objLit of sourceFile.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+    if (handled.has(objLit)) continue;
+    const found = [...SUBJECT_FLAG_NAMES, "piiEncrypted"].filter((n) => objLit.getProperty(n));
+    if (found.length > 0) {
+      report(
+        objLit,
+        `subject flag(s) [${found.join(", ")}] on an object literal that is not a create*Field(...) call`,
+      );
+    }
+  }
+}
+
+// kumiko-lint-ignore complexity-budget migration codemod, one-time script — splitting would add risk without benefit
+function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string): void {
+  // skip: field already carries `personal` — already migrated, idempotent no-op
+  if (obj.getProperty("personal")) return;
+
+  const piiEncryptedProp = obj.getProperty("piiEncrypted");
+  if (piiEncryptedProp) {
+    report(
+      piiEncryptedProp,
+      "piiEncrypted: true on an entity field (removed from the type system) — needs a human decision, not a mechanical mapping",
+    );
+    // skip: reported above — piiEncrypted needs a human decision, not a mechanical mapping
+    return;
+  }
+
+  const subjectProps = SUBJECT_FLAG_NAMES.map((n) => ({ name: n, prop: findProp(obj, n) })).filter(
+    (x): x is { name: SubjectFlagName; prop: PropertyAssignment } => !!x.prop,
+  );
+  const lookupableProp = findProp(obj, "lookupable");
+  const searchableProp = findProp(obj, "searchable");
+  const sensitiveProp = findProp(obj, "sensitive");
+  const anonymizeProp = obj.getProperty("anonymize");
+
+  if (subjectProps.length === 0) {
+    // `searchable`/`sensitive` alone remain valid, unrelated FieldDef
+    // properties — left untouched. `lookupable` alone can never compile
+    // (always an excess property without a `personal` to attach `find`
+    // to). `anonymize` alone has no PersonalAnnotations arm to live on.
+    if (lookupableProp) {
+      report(
+        lookupableProp,
+        "lookupable without any subject annotation — no `personal` to attach `find` to",
+      );
+    }
+    if (anonymizeProp) {
+      report(
+        anonymizeProp,
+        "anonymize without any subject annotation — no PersonalAnnotations arm accepts anonymize alone",
+      );
+    }
+    // skip: no subject flag on this field — stray lookupable/anonymize already reported above if present
+    return;
+  }
+
+  if (subjectProps.length > 1) {
+    report(
+      subjectProps[0]!.prop,
+      `multiple subject annotations on one field (${subjectProps.map((s) => s.name).join(", ")}) — needs a human decision on which subject is correct`,
+    );
+    // skip: reported above — multiple subject annotations need a human call on which one wins
+    return;
+  }
+
+  const subject = subjectProps[0]!;
+
+  if (NO_PERSONAL_FACTORIES.has(factoryName)) {
+    report(
+      subject.prop,
+      `${factoryName} has no personal-annotation support — subject flag "${subject.name}" cannot be expressed here`,
+    );
+    // skip: reported above — this factory has no personal-annotation support to migrate into
+    return;
+  }
+  const isTextFind = TEXT_FIND_FACTORIES.has(factoryName);
+  const isLongTextFind = LONGTEXT_FIND_FACTORIES.has(factoryName);
+  const isNoFind = NO_FIND_FACTORIES.has(factoryName);
+  if (!isTextFind && !isLongTextFind && !isNoFind) {
+    report(
+      subject.prop,
+      `unrecognized field factory "${factoryName}" — cannot verify its PersonalAnnotations shape`,
+    );
+    // skip: reported above — unknown factory shape, cannot verify safely
+    return;
+  }
+
+  let personalInit: string;
+  let reasonInit: string | undefined;
+  if (subject.name === "pii") {
+    if (!isTrueLiteral(subject.prop.getInitializer())) {
+      report(subject.prop, "pii is set to a non-`true` value — cannot infer intent");
+      // skip: reported above — non-`true` pii value, can't infer intent
+      return;
+    }
+    personalInit = `"self"`;
+  } else if (subject.name === "tenantOwned") {
+    if (!isTrueLiteral(subject.prop.getInitializer())) {
+      report(subject.prop, "tenantOwned is set to a non-`true` value — cannot infer intent");
+      // skip: reported above — non-`true` tenantOwned value, can't infer intent
+      return;
+    }
+    personalInit = `"tenant"`;
+  } else if (subject.name === "subjectRef") {
+    if (!isTrueLiteral(subject.prop.getInitializer())) {
+      report(subject.prop, "subjectRef is set to a non-`true` value — cannot infer intent");
+      // skip: reported above — non-`true` subjectRef value, can't infer intent
+      return;
+    }
+    personalInit = `"ref"`;
+  } else if (subject.name === "allowPlaintext") {
+    const init = subject.prop.getInitializer();
+    if (!init) {
+      report(subject.prop, "allowPlaintext has no value");
+      // skip: reported above — allowPlaintext has no value to migrate
+      return;
+    }
+    personalInit = "false";
+    reasonInit = Node.isStringLiteral(init)
+      ? `"${normalizeReasonSlug(init.getLiteralText())}"`
+      : init.getText();
+  } else {
+    const init = subject.prop.getInitializer();
+    if (!init || !Node.isObjectLiteralExpression(init)) {
+      report(subject.prop, "userOwned value is not an object literal — cannot extract ownerField");
+      // skip: reported above — userOwned value isn't an object literal, can't extract ownerField
+      return;
+    }
+    const ownerFieldProp = findProp(init, "ownerField");
+    if (!ownerFieldProp?.getInitializer()) {
+      report(subject.prop, 'userOwned is missing an "ownerField" property');
+      // skip: reported above — userOwned is missing its ownerField property
+      return;
+    }
+    personalInit = `{ of: ${ownerFieldProp.getInitializer()!.getText()} }`;
+  }
+
+  const subjectIsRefOrPlaintext =
+    subject.name === "subjectRef" || subject.name === "allowPlaintext";
+
+  if (subjectIsRefOrPlaintext) {
+    // These PersonalAnnotations arms carry no `find` field at all.
+    if (lookupableProp) {
+      report(
+        lookupableProp,
+        `lookupable combined with personal:${subject.name === "subjectRef" ? '"ref"' : "false"} — findability doesn't apply to this subject, table has no mapping`,
+      );
+      // skip: reported above — lookupable doesn't apply to this subject, no mapping to migrate
+      return;
+    }
+    applyTransform(obj, [subject.prop], {
+      personal: personalInit,
+      reason: reasonInit,
+      find: undefined,
+    });
+    counts[subject.name === "subjectRef" ? "ref" : "personal-false"]++;
+    // skip: already transformed above — nothing left to check for this subject
+    return;
+  }
+
+  if (isNoFind) {
+    const stray = lookupableProp ?? searchableProp ?? sensitiveProp;
+    if (stray) {
+      report(
+        stray,
+        `${factoryName} has no \`find\` in its PersonalAnnotations — findability flag present on a non-text field`,
+      );
+      // skip: reported above — findability flag on a non-text field, no valid find to attach
+      return;
+    }
+    applyTransform(obj, [subject.prop], {
+      personal: personalInit,
+      reason: undefined,
+      find: undefined,
+    });
+    counts["no-find"]++;
+    // skip: already transformed above — no-find factory has nothing further to check
+    return;
+  }
+
+  const hasLookupable = !!lookupableProp;
+  const hasSearchable = !!searchableProp;
+  const hasSensitive = !!sensitiveProp;
+
+  if (hasSensitive && (hasLookupable || hasSearchable)) {
+    report(
+      sensitiveProp!,
+      'sensitive combined with lookupable/searchable — two find values ("secret" vs "exact"/"fuzzy"), needs a human decision',
+    );
+    // skip: reported above — sensitive plus lookupable/searchable is an ambiguous find value
+    return;
+  }
+
+  let find: "exact" | "fuzzy" | "none" | "secret";
+  if (hasSensitive) find = "secret";
+  else if (hasLookupable && hasSearchable) find = "fuzzy";
+  else if (hasLookupable) find = "exact";
+  else if (hasSearchable) find = "fuzzy";
+  else find = "none";
+
+  if (isLongTextFind && (find === "exact" || find === "fuzzy")) {
+    report(
+      (lookupableProp ?? searchableProp)!,
+      'lookupable/searchable on createLongTextField — only "none"/"secret" are valid find values on longText',
+    );
+    // skip: reported above — exact/fuzzy find isn't valid on createLongTextField
+    return;
+  }
+
+  // searchable-alone -> "fuzzy" makes expandPersonalAnnotations add
+  // `lookupable: true`, which the field didn't carry before — that's a
+  // new `_bidx` column (DDL migration), tracked separately for the report.
+  if (hasSearchable && !hasLookupable) {
+    newLookupableSites.push({
+      file: obj.getSourceFile().getFilePath(),
+      line: subject.prop.getStartLineNumber(),
+      // find: "fuzzy" newly adds lookupable (was searchable-only) — needs a _bidx column migration
+      reason: "fuzzy_search_needs_bidx_migration",
+    });
+  }
+
+  const removedProps = [subject.prop, lookupableProp, searchableProp, sensitiveProp].filter(
+    (p): p is PropertyAssignment => !!p,
+  );
+  applyTransform(obj, removedProps, { personal: personalInit, reason: undefined, find });
+  counts[find]++;
+}
+
+function applyTransform(
+  obj: ObjectLiteralExpression,
+  removedProps: readonly PropertyAssignment[],
+  next: { personal: string; reason: string | undefined; find: string | undefined },
+): void {
+  const properties = obj.getProperties();
+  const anchor = removedProps[0]!;
+  const anchorIndex = properties.indexOf(anchor);
+  const removedSet = new Set<PropertyAssignment>(removedProps);
+  let insertIndex = 0;
+  for (let i = 0; i < anchorIndex; i++) {
+    if (!removedSet.has(properties[i] as PropertyAssignment)) insertIndex++;
+  }
+
+  for (const p of removedProps) p.remove();
+
+  const newProps: { name: string; initializer: string }[] = [
+    { name: "personal", initializer: next.personal },
+  ];
+  if (next.find) newProps.push({ name: "find", initializer: `"${next.find}"` });
+  if (next.reason !== undefined) newProps.push({ name: "reason", initializer: next.reason });
+
+  obj.insertPropertyAssignments(insertIndex, newProps);
+}
+
+function findTargetFiles(rootDir: string): string[] {
+  const glob = new Glob("**/*.{ts,tsx}");
+  // engine/factories.ts constructs raw ResolvedPiiFlags literals as the
+  // *implementation* of expandPersonalAnnotations (personal -> flags) —
+  // not an authored override, so it's not a migration target.
+  const EXCLUDE = ["/node_modules/", "/dist/", "/build/", "/engine/factories.ts"];
+  const files: string[] = [];
+  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
+    const abs = resolve(rootDir, file);
+    if (EXCLUDE.some((p) => abs.includes(p))) continue;
+    files.push(abs);
+  }
+  return files.sort();
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const dryRun = process.argv.includes("--dry-run");
+  const rootDir = resolve(positional[0] ?? process.cwd());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const calls = collectFieldCalls(sourceFile);
+    const handled = new Set(calls.map((c) => c.objArg));
+    reportRawSubjectLiterals(sourceFile, handled);
+
+    const countsBefore = { ...counts };
+    for (const { name, objArg } of calls) processObjectLiteral(objArg, name);
+    const changed = (Object.keys(counts) as FindBucket[]).some(
+      (k) => counts[k] !== countsBefore[k],
+    );
+
+    if (changed) {
+      touchedFiles++;
+      if (!dryRun) sourceFile.saveSync();
+    }
+  }
+
+  console.log(`\nScanned ${files.length} files under ${rootDir}${dryRun ? " (dry-run)" : ""}.`);
+  console.log(`Touched ${touchedFiles} files.\n`);
+  console.log("Transformed, by find/personal bucket:");
+  for (const [bucket, n] of Object.entries(counts)) {
+    if (n > 0) console.log(`  ${bucket}: ${n}`);
+  }
+  console.log(`\nNewly gains lookupable (needs a _bidx migration): ${newLookupableSites.length}`);
+  for (const r of newLookupableSites) {
+    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.reason}`);
+  }
+  console.log(`\nReported (not transformed): ${reports.length}`);
+  for (const r of reports) {
+    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.reason}`);
+  }
+}
+
+await main();

package/src/upgrade-cli.ts

@@ -164,19 +164,39 @@ export function findFeaturesDirs(cwd: string): string[] {
   return dirs;
 }
 
+// Consumer-facing codemod scripts ship inside the published
+// @cosmicdrift/kumiko-framework package (src/scripts/codemod), not at the
+// git repo root — only the installed package path exists in a consumer's
+// node_modules after a plain npm/bun install (fw#2301).
+export function findCodemodScriptsRoot(repoRoot: string): string | null {
+  const local = join(repoRoot, "packages/framework/src");
+  if (existsSync(join(local, CODEMOD_SUBDIR))) return local;
+
+  let dir = repoRoot;
+  for (let i = 0; i < 10; i++) {
+    const nmSrc = join(dir, "node_modules/@cosmicdrift/kumiko-framework/src");
+    if (existsSync(join(nmSrc, CODEMOD_SUBDIR))) return nmSrc;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
 // Resolves a changes.json `codemod` field to an absolute script path,
 // refusing anything that would escape scripts/codemod/ (path traversal,
 // absolute paths, symlinks pointing outward) or that isn't a real .ts file.
 export function resolveCodemodScript(
-  repoRoot: string,
+  codemodScriptsRoot: string,
   codemodField: string | undefined,
 ): string | null {
   if (!codemodField) return null;
   if (codemodField.includes("\0") || codemodField.startsWith("/") || !codemodField.endsWith(".ts"))
     return null;
 
-  const scriptsRoot = join(repoRoot, CODEMOD_SUBDIR);
-  const resolved = join(repoRoot, codemodField);
+  const scriptsRoot = join(codemodScriptsRoot, CODEMOD_SUBDIR);
+  const resolved = join(codemodScriptsRoot, codemodField);
   const rel = relative(scriptsRoot, resolved);
   if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
   if (!existsSync(resolved)) return null;
@@ -279,9 +299,12 @@ async function applyCodemods(
     return 0;
   }
 
+  const codemodScriptsRoot = findCodemodScriptsRoot(repoRoot);
   const ran: UpgradeMarkerCodemod[] = [];
   for (const e of codemodEntries) {
-    const scriptPath = resolveCodemodScript(repoRoot, e.codemod);
+    const scriptPath = codemodScriptsRoot
+      ? resolveCodemodScript(codemodScriptsRoot, e.codemod)
+      : null;
     if (!scriptPath) {
       out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
       return 1;