@cosmicdrift/kumiko-framework 0.210.0 → 0.212.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.210.0",
+  "version": "0.212.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>",
@@ -159,6 +159,10 @@
       "types": "./src/consumer-cli.ts",
       "default": "./src/consumer-cli.ts"
     },
+    "./upgrade-cli": {
+      "types": "./src/upgrade-cli.ts",
+      "default": "./src/upgrade-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"
@@ -190,7 +194,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.210.0",
+    "@cosmicdrift/kumiko-types": "0.212.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -206,7 +210,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.210.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.212.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -0,0 +1,370 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveCodemodScript, runUpgradeCli, type UpgradeCliOut } from "../upgrade-cli";
+
+function makeSpyOutput(): {
+  readonly out: UpgradeCliOut;
+  readonly logs: string[];
+  readonly errs: string[];
+} {
+  const logs: string[] = [];
+  const errs: string[] = [];
+  return {
+    logs,
+    errs,
+    out: {
+      log: (m: string) => logs.push(m),
+      err: (m: string) => errs.push(m),
+    },
+  };
+}
+
+function makeTempCwd(files?: Record<string, string>): {
+  readonly cwd: string;
+  readonly cleanup: () => void;
+} {
+  const cwd = mkdtempSync(join(tmpdir(), "kumiko-upgrade-cli-"));
+  if (files) {
+    for (const [relPath, content] of Object.entries(files)) {
+      const full = join(cwd, relPath);
+      mkdirSync(join(full, ".."), { recursive: true });
+      writeFileSync(full, content, "utf-8");
+    }
+  }
+  return {
+    cwd,
+    cleanup: () => {
+      try {
+        rmSync(cwd, { recursive: true, force: true });
+      } catch {
+        // ignore — best-effort
+      }
+    },
+  };
+}
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+  for (const c of cleanups) c();
+  cleanups.length = 0;
+});
+
+const CORE_ENTRY = JSON.stringify([
+  {
+    version: "0.167.0",
+    type: "breaking",
+    title: "core helper moved",
+    migration: "import from /testing",
+  },
+]);
+
+const FEATURE_ENTRY = JSON.stringify([{ version: "0.166.0", type: "fix", title: "feature fix" }]);
+
+function tmp(files: Record<string, string>): string {
+  const t = makeTempCwd(files);
+  cleanups.push(t.cleanup);
+  return t.cwd;
+}
+
+async function runJson(cwd: string, from: string): Promise<{ pending: Array<{ title: string }> }> {
+  const spy = makeSpyOutput();
+  const exit = await runUpgradeCli(["--from", from, "--json"], cwd, spy.out);
+  expect(exit).toBe(0);
+  return JSON.parse(spy.logs.join("\n"));
+}
+
+describe("upgrade command — framework core changelog", () => {
+  test("collects core changes.json from the framework repo layout", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": CORE_ENTRY,
+      "packages/bundled-features/src/user/changes.json": FEATURE_ENTRY,
+    });
+
+    const result = await runJson(cwd, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["core helper moved", "feature fix"]);
+  });
+
+  test("finds core changes.json in hoisted node_modules from an app subdir", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-framework/src/changes.json": CORE_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["core helper moved"]);
+  });
+
+  test("repo file wins over node_modules — no duplicate entries", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": CORE_ENTRY,
+      "node_modules/@cosmicdrift/kumiko-framework/src/changes.json": CORE_ENTRY,
+    });
+
+    const result = await runJson(cwd, "0.165.0");
+
+    expect(result.pending).toHaveLength(1);
+  });
+
+  test("feature entries are not duplicated by the workspace symlink", async () => {
+    const cwd = tmp({
+      "packages/bundled-features/src/user/changes.json": FEATURE_ENTRY,
+      "node_modules/@cosmicdrift/kumiko-bundled-features/src/user/changes.json": FEATURE_ENTRY,
+    });
+
+    const result = await runJson(cwd, "0.165.0");
+
+    expect(result.pending).toHaveLength(1);
+  });
+
+  test("core entries older than the current version are filtered out", async () => {
+    const cwd = tmp({ "packages/framework/src/changes.json": CORE_ENTRY });
+
+    const result = await runJson(cwd, "0.167.0");
+
+    expect(result.pending).toEqual([]);
+  });
+
+  test("--from is rejected when it isn't a valid semver — no silent 'nothing new'", async () => {
+    const cwd = tmp({ "packages/framework/src/changes.json": CORE_ENTRY });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "latest", "--json"], cwd, spy.out);
+
+    expect(exit).toBe(1);
+    expect(spy.errs.join("\n")).toContain("Invalid version format");
+    expect(spy.logs).toEqual([]);
+  });
+});
+
+describe("upgrade command — enterprise package layout", () => {
+  // Layout is detected by presence of changes.json, not an "ai-" name
+  // prefix — the old heuristic silently dropped every enterprise package
+  // whose name didn't start with "ai-" (fw#1605).
+  test("collects changes.json from a package without an 'ai-' prefix", async () => {
+    const cwd = tmp({
+      "packages/billing-designer/src/changes.json": FEATURE_ENTRY,
+    });
+
+    const result = await runJson(cwd, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["feature fix"]);
+  });
+
+  test("flat layout (no src/ subdir) is also collected", async () => {
+    const cwd = tmp({
+      "packages/billing-designer/changes.json": FEATURE_ENTRY,
+    });
+
+    const result = await runJson(cwd, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["feature fix"]);
+  });
+});
+
+// The repo actually checked out on disk — scripts/codemod/ isn't published,
+// so --apply only ever works against a real local framework checkout.
+const REAL_REPO_ROOT = join(import.meta.dir, "../../../..");
+const REAL_CODEMOD = "scripts/codemod/crypto-shredding-testing-move.ts";
+
+function breakingEntryWithCodemod(codemod: string | undefined): string {
+  const entry: Record<string, unknown> = {
+    version: "0.167.0",
+    type: "breaking",
+    title: "helper moved",
+    migration: "import from /testing",
+  };
+  if (codemod !== undefined) entry["codemod"] = codemod;
+  return JSON.stringify([entry]);
+}
+
+const LEGACY_IMPORT_FIXTURE = [
+  'import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/crypto";',
+  "",
+  "resetPiiSubjectKmsForTests();",
+  "",
+].join("\n");
+
+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));
+  });
+
+  test("rejects an absolute path", () => {
+    expect(resolveCodemodScript(REAL_REPO_ROOT, "/etc/passwd.ts")).toBeNull();
+  });
+
+  test("rejects path traversal that escapes scripts/codemod/", () => {
+    expect(
+      resolveCodemodScript(REAL_REPO_ROOT, "scripts/codemod/../../package.json.ts"),
+    ).toBeNull();
+    expect(resolveCodemodScript(REAL_REPO_ROOT, "../outside/x.ts")).toBeNull();
+  });
+
+  test("rejects a non-.ts file", () => {
+    expect(resolveCodemodScript(REAL_REPO_ROOT, "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();
+  });
+
+  test("rejects an undefined codemod field", () => {
+    expect(resolveCodemodScript(REAL_REPO_ROOT, undefined)).toBeNull();
+  });
+});
+
+describe("upgrade command — --apply", () => {
+  test("runs the real codemod against a fixture file and writes the marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+      "legacy-test-helper.ts": LEGACY_IMPORT_FIXTURE,
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.165.0", "--apply"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(0);
+
+    const rewritten = readFileSync(join(cwd, "legacy-test-helper.ts"), "utf-8");
+    expect(rewritten).toContain('from "@cosmicdrift/kumiko-framework/testing"');
+    expect(rewritten).not.toContain('from "@cosmicdrift/kumiko-framework/crypto"');
+
+    const markerPath = join(cwd, ".kumiko/upgrade-state.json");
+    expect(existsSync(markerPath)).toBe(true);
+    const marker = JSON.parse(readFileSync(markerPath, "utf-8"));
+    expect(marker.version).toBe("0.167.0");
+    expect(typeof marker.appliedAt).toBe("string");
+    expect(marker.codemods).toEqual([
+      { version: "0.167.0", codemod: REAL_CODEMOD, title: "helper moved" },
+    ]);
+  });
+
+  test("--dry-run runs the codemod but changes nothing and writes no marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+      "legacy-test-helper.ts": LEGACY_IMPORT_FIXTURE,
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.165.0", "--apply", "--dry-run"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(0);
+    expect(readFileSync(join(cwd, "legacy-test-helper.ts"), "utf-8")).toBe(LEGACY_IMPORT_FIXTURE);
+    expect(existsSync(join(cwd, ".kumiko/upgrade-state.json"))).toBe(false);
+    expect(spy.logs.join("\n")).toContain("Touched 1 files, moved 1 import(s)");
+  });
+
+  test("rejects a path-traversal codemod field and writes no marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod("../../../etc/passwd.ts"),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.165.0", "--apply"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(1);
+    expect(spy.errs.join("\n")).toContain("invalid codemod path");
+    expect(existsSync(join(cwd, ".kumiko/upgrade-state.json"))).toBe(false);
+  });
+
+  test("fails when the codemod script doesn't exist, writes no marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(
+        "scripts/codemod/does-not-exist.ts",
+      ),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.165.0", "--apply"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(1);
+    expect(spy.errs.join("\n")).toContain("invalid codemod path");
+    expect(existsSync(join(cwd, ".kumiko/upgrade-state.json"))).toBe(false);
+  });
+
+  test("breaking changes without a codemod field are reported as manual, no marker written", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(undefined),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.165.0", "--apply"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("no codemod, manual migration required");
+    expect(existsSync(join(cwd, ".kumiko/upgrade-state.json"))).toBe(false);
+  });
+
+  test("nothing pending: reports up to date, still bootstraps the marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.170.0", "--apply"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("Nothing new since your version");
+
+    const markerPath = join(cwd, ".kumiko/upgrade-state.json");
+    expect(existsSync(markerPath)).toBe(true);
+    const marker = JSON.parse(readFileSync(markerPath, "utf-8"));
+    expect(marker.version).toBe("0.170.0");
+    expect(marker.codemods).toEqual([]);
+    expect(typeof marker.appliedAt).toBe("string");
+  });
+
+  test("nothing pending + --dry-run: reports up to date, writes no marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--from", "0.170.0", "--apply", "--dry-run"], cwd, spy.out, {
+      repoRoot: REAL_REPO_ROOT,
+    });
+
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("Nothing new since your version");
+    expect(existsSync(join(cwd, ".kumiko/upgrade-state.json"))).toBe(false);
+  });
+
+  test("--dir targets a different directory than cwd", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+    });
+    const target = tmp({ "legacy-test-helper.ts": LEGACY_IMPORT_FIXTURE });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(
+      ["--from", "0.165.0", "--apply", "--dir", target],
+      cwd,
+      spy.out,
+      {
+        repoRoot: REAL_REPO_ROOT,
+      },
+    );
+
+    expect(exit).toBe(0);
+    const rewritten = readFileSync(join(target, "legacy-test-helper.ts"), "utf-8");
+    expect(rewritten).toContain('from "@cosmicdrift/kumiko-framework/testing"');
+    expect(existsSync(join(target, ".kumiko/upgrade-state.json"))).toBe(true);
+  });
+});

package/src/arg-parser.ts

@@ -0,0 +1,66 @@
+// Small arg parser for CLI commands. Not as feature-rich as commander or
+// yargs — just:
+//   - Positional args:  cmd "value1" "value2"
+//   - Flags:            --flag (boolean) / --key value
+//   - Negatable:        --no-flag
+//
+// Copy of bin/commands/arg-parser.ts — registry-free, but upgrade-cli.ts
+// lives in the published @cosmicdrift/kumiko-framework package and can't
+// import from bin/commands/ (outside the package's export surface).
+
+export type ParsedArgs = {
+  readonly positional: ReadonlyArray<string>;
+  readonly flags: ReadonlyMap<string, string | boolean>;
+};
+
+export function parseArgs(argv: ReadonlyArray<string>): ParsedArgs {
+  const positional: string[] = [];
+  const flags = new Map<string, string | boolean>();
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a) continue;
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      // `--no-foo` form
+      if (key.startsWith("no-")) {
+        flags.set(key.slice(3), false);
+        continue;
+      }
+      // `--key=value` inline form
+      const eq = key.indexOf("=");
+      if (eq !== -1) {
+        flags.set(key.slice(0, eq), key.slice(eq + 1));
+        continue;
+      }
+      // `--key value` if next isn't a flag, else boolean
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags.set(key, next);
+        i++;
+      } else {
+        flags.set(key, true);
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+
+  return { positional, flags };
+}
+
+export function getFlag(args: ParsedArgs, name: string): boolean {
+  return args.flags.get(name) === true;
+}
+
+export function getStringFlag(args: ParsedArgs, name: string): string | undefined {
+  const v = args.flags.get(name);
+  return typeof v === "string" ? v : undefined;
+}
+
+export function getNumberFlag(args: ParsedArgs, name: string): number | undefined {
+  const v = args.flags.get(name);
+  if (typeof v !== "string") return undefined;
+  const n = Number.parseInt(v, 10);
+  return Number.isNaN(n) ? undefined : n;
+}

package/src/changes.json

@@ -1,4 +1,60 @@
 [
+  {
+    "version": "0.209.1",
+    "type": "breaking",
+    "title": "Job runs no longer go through the event store; read_job_runs table renamed to store_job_runs (fw#2243).",
+    "detail": "Job runs (jobRun) no longer go through the event store. Every job execution used to append a run-started + run-completed/run-failed event replayed through two inline projections — in the busiest apps this was ~99% of all events ever written, for data nothing else replays or subscribes to. onJobStart/onJobComplete/onJobFailed now write straight into the (renamed) store_job_runs / store_job_run_logs tables, with a new daily jobs:job:retention-cleanup job (retentionDays, default 30) purging old rows so the tables don't grow forever.",
+    "migration": "Breaking for raw-SQL consumers: the table is renamed read_job_runs → store_job_runs (store_job_run_logs is unchanged). The migration drops read_job_runs outright — old run history is not preserved, it was operational/debug data, not a system of record. Apps that only use the shipped job-runs-screen/jobs:query:* handlers are unaffected; apps with a raw SQL dependency on read_job_runs need a follow-up on their side."
+  },
+  {
+    "version": "0.201.0",
+    "type": "breaking",
+    "title": "IdempotencyGuard.check()/.store() gain a discriminated result + token param on top of the 0.198.0 signature (fw#2139).",
+    "detail": "Fixes two idempotency-lock races that could let a duplicate request re-run a write handler or silently overwrite a fresher cached result. `waitTimeoutMs` (how long a duplicate request waits for the in-flight one) is now clamped to always exceed `pendingTtlSeconds` (the in-progress lock's own TTL) — previously the defaults (30s lock vs. 25s wait) let a retry give up and re-execute the handler while the original call was still legitimately running. `IdempotencyGuard.store()` now does an atomic compare-and-swap against the exact lock token the calling run acquired (Redis EVAL) instead of an unconditional SET, so a stale, slow-finishing run can no longer stomp the result a reclaiming run already persisted after the lock expired. `IdempotencyGuard.check()` now returns a discriminated `{ status: \"cached\", result }` / `{ status: \"acquired\", token }` union instead of `string | null`, and `store()` takes the acquired token as a new parameter.",
+    "migration": "Layered on top of the 0.198.0 signature change: check() is now check(tenantId, userId, requestId) returning { status: \"cached\", result } | { status: \"acquired\", token }; store() is now store(tenantId, userId, requestId, token). Both call sites in this repo (dispatch-batch.ts, the dispatcher test mock) are already updated; any code outside this repo calling IdempotencyGuard directly needs the same update."
+  },
+  {
+    "version": "0.201.0",
+    "type": "breaking",
+    "title": "GET /files/:id now sniffs bytes and serves svg/txt/csv/json/md as application/octet-stream instead of inline (fw#2140).",
+    "detail": "GET /files/:id served the stored mimeType as Content-Type without verifying it against the file's actual bytes — a client can declare any MIME at upload time, so an attacker could upload real HTML/SVG content and have it served back with a trusted-looking Content-Type from the app origin, enabling stored XSS. Uploads themselves are still accepted regardless of declared MIME (this is unchanged); the fix hardens serving instead. The download route now sniffs the file's magic bytes and only serves the sniffed Content-Type inline when it matches a known-safe binary signature (png/jpeg/gif/webp/pdf) AND matches the declared MIME from upload. Anything else — including a genuine mismatch, or file types with no reliable binary signature such as svg/txt/csv/json/md — is now served as application/octet-stream. This also adds X-Content-Type-Options: nosniff to GET /files/:id, which previously had none.",
+    "migration": "Breaking for consumers that render uploaded svg/txt/csv/json/md files inline (e.g. an <img src> pointing at GET /files/:id): those now download as application/octet-stream instead of rendering. Route such content through a purpose-built safe viewer if inline rendering is required."
+  },
+  {
+    "version": "0.198.0",
+    "type": "breaking",
+    "title": "IdempotencyGuard.check/.store signature changed to (tenantId, userId, requestId); SqlExpression is branded (fw#2049).",
+    "detail": "Security hardening (audit \"Welle 2\"): closes a request-supplied-JSON-can-forge-raw-SQL path and a cross-tenant idempotency-cache collision. `SqlExpression` is now branded — only the `sql` template tag and `sql.raw(...)` produce a value the query layer recognizes as raw SQL; an object literal built by hand (`{ kind: \"sql-expr\", sql: ..., params: ... }`) is no longer treated as raw SQL and gets bound as an ordinary JSON parameter instead, surfacing as a broken query rather than a silent vulnerability. `IdempotencyGuard.check`/`.store` moved from `(requestId)` to `(tenantId, userId, requestId)` so the idempotency cache can no longer be hit across tenants/users by an attacker who guesses or replays a requestId; the Redis key format changed from `${prefix}${requestId}` to `${prefix}${tenantId}:${userId}:${requestId}` with no compatibility shim.",
+    "migration": "Replace any hand-built SqlExpression object literal with the `sql` tag or `sql.raw(...)`. Any custom IdempotencyGuard implementation, or code calling `.check`/`.store` directly (outside the dispatcher's own runBatch, which already updated), needs the new (tenantId, userId, requestId) signature. On deploy, in-flight idempotent retries older than the request's own retry window may execute a second time — same as a first-ever request, not a correctness issue, just not a cache hit."
+  },
+  {
+    "version": "0.198.0",
+    "type": "breaking",
+    "title": "event-store-executor.list() now throws 422 search_adapter_not_wired instead of returning unfiltered results (fw#2032).",
+    "detail": "event-store-executor.list() silently dropped payload.search when no SearchAdapter was wired (neither at build time via options.searchAdapter nor at runtime via runtimeOptions.searchAdapter) — the list came back unfiltered, indistinguishable from a real search result. Now throws UnprocessableError (code: \"unprocessable\", details.reason: \"search_adapter_not_wired\", details.entity) instead.",
+    "migration": "Breaking for consumers whose entities are searchable but have no SearchAdapter wired: a search request that used to silently no-op now returns a 422. Wire a SearchAdapter (e.g. Meilisearch) for the entity, or stop marking the field/screen searchable."
+  },
+  {
+    "version": "0.198.0",
+    "type": "breaking",
+    "title": "NavIconKey closed union replaces icon?: string on nav/config-mask definitions (fw#2055).",
+    "detail": "NavDefinition.icon, ContentCollectionDefinition.nav.icon, ScreenNavSugar.icon and ConfigMask.icon were all icon?: string — any typo (icon: \"seting\") compiled fine and silently fell back to a dot in the sidebar. New NavIconKey union (@cosmicdrift/kumiko-types/nav-icon, re-exported from @cosmicdrift/kumiko-framework/{engine,ui-types}) types all four against the closed set of keys the web renderer actually registers, so an unregistered icon key is now a compile error at the r.nav()/r.screen({ nav })/config-mask call site instead of a missing icon at runtime. packages/renderer-web's NAV_ICONS map is checked against the same union via `as const satisfies Record<NavIconKey, …>`, so the type and the map can no longer drift.",
+    "migration": "Breaking for any app that passes an icon key outside the vocabulary in packages/types/src/nav-icon.ts — such a call site will fail to compile after this bump. Fix the typo or add the missing key to both NavIconKey and renderer-web's NAV_ICONS map in the same change."
+  },
+  {
+    "version": "0.193.0",
+    "type": "breaking",
+    "title": "Image fields get named derived variants; ImageFieldDef/ImagesFieldDef.thumbnails removed (fw#1973).",
+    "detail": "createImageField now accepts variants: Record<string, VariantSpec> — boot-validated named derived-image specs, served via GET /api/files/:id/variant/:name behind the same tenant + access guard as the download. A request carries only a NAME, never a spec, so no caller can drive an arbitrary render. The edit-form preview loads the first declared variant instead of the original.",
+    "migration": "ImageFieldDef.thumbnails / ImagesFieldDef.thumbnails are removed — the flag was never read by anything. Replace any reliance on it with a declared variants entry."
+  },
+  {
+    "version": "0.189.0",
+    "type": "breaking",
+    "title": "createDateField now backs a real Postgres DATE column, round-trips as Temporal.PlainDate (fw#1924).",
+    "detail": "type:\"date\" fields were silently aliased onto the same instant()/TIMESTAMPTZ column as type:\"timestamp\": reads returned a full ISO instant (\"2026-03-15T00:00:00Z\"), writes expected a bare \"yyyy-mm-dd\" string bound to a timestamptz column through the session's TimeZone — both directions were timezone-dependent for what is meant to be a pure calendar-day value. A date field now serializes as \"2026-03-15\" (Temporal.PlainDate's own toJSON()); a non-form client that Instant-parses a date field's JSON value now throws. Write shape is unchanged (bare \"yyyy-mm-dd\").",
+    "migration": "Managed (event-sourced projection) tables: the generator emits DROP TABLE + CREATE TABLE and replays from the event log automatically — factor in replay cost for entities with a large event history. Unmanaged (store_*, direct-write) tables: the generator emits an in-place ALTER TABLE … ALTER COLUMN … TYPE date USING (col AT TIME ZONE 'UTC')::date, anchored explicitly at UTC — do not hand-write a bare ALTER COLUMN … TYPE date without USING, which falls back to Postgres's session-TimeZone-dependent implicit cast."
+  },
   {
     "version": "0.177.0",
     "type": "breaking",

package/src/db/queries/backfill-pii.ts

@@ -41,7 +41,7 @@ import { asRawClient } from "../../bun-db";
 import { quoteIdent } from "../../crypto/ciphertext-pattern";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii";
 import type { KmsContext, LocalKeyKmsAdapter, SubjectId } from "../../crypto/kms-adapter";
-import { KeyErasedError } from "../../crypto/kms-adapter";
+import { KeyErasedError, KeyNotFoundError } from "../../crypto/kms-adapter";
 import {
   configuredPiiSubjectKms,
   encryptPiiValueForSubject,
@@ -83,7 +83,8 @@ export type PiiBackfillResult = {
 
 export type PiiBackfillOptions = {
   readonly batchSize?: number;
-  // Scan + count only, write nothing.
+  // Scan + count only, write nothing — including the subject KMS: outcomes
+  // are predicted from a read-only kms.getKey probe, never kms.createKey.
   readonly dryRun?: boolean;
   // Stage 2: fall back to the entity's projection row (by aggregate_id)
   // when a lifecycle event's payload doesn't name the owner field.
@@ -350,6 +351,7 @@ export async function backfillEventPiiEncryption(
         section[field] = PII_ERASED_SENTINEL;
         return "erased";
       }
+      if (options.dryRun) return predictEncryptOutcome(subject);
       try {
         section[field] = await encryptPiiValueForSubject(
           kms as LocalKeyKmsAdapter,
@@ -367,6 +369,21 @@ export async function backfillEventPiiEncryption(
         throw e;
       }
     }
+
+    // getKey alone never mints (unlike getOrCreateDek → createKey on the real
+    // path) — a real run's outcome is fully determined by whether a key
+    // already exists, so probing it read-only predicts the outcome without
+    // writing to the subject-keys store.
+    async function predictEncryptOutcome(subject: SubjectId): Promise<FieldOutcome> {
+      try {
+        await (kms as LocalKeyKmsAdapter).getKey(subject, kmsCtx);
+        return "encrypted";
+      } catch (e) {
+        if (e instanceof KeyErasedError) return "erased";
+        if (e instanceof KeyNotFoundError) return "encrypted";
+        throw e;
+      }
+    }
   }
 
   function isForgottenSubject(subject: SubjectId, aggregateId: string): boolean {