@cosmicdrift/kumiko-framework 0.225.0 → 0.227.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.225.0",
+  "version": "0.227.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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.225.0",
+    "@cosmicdrift/kumiko-types": "0.227.0",
     "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.225.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.227.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/query.ts

@@ -589,6 +589,28 @@ function buildWhereClause(
   const conditions: string[] = [];
   const values: unknown[] = [];
   let idx = startIndex;
+  // multiSelect (and any other jsonb-array-of-scalars column) stores an
+  // array — a filter value is one option, not the whole array, so eq/ne/in
+  // must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
+  // against the jsonb column, which Postgres rejects outright (fw#2490).
+  // Mirrors event-store-executor-read.ts's applyFilter — keep in lock-step.
+  function jsonbContainsAny(col: string, candidates: readonly unknown[]): string {
+    if (candidates.length === 0) return "FALSE";
+    const parts: string[] = [];
+    for (const v of candidates) {
+      const p = prepareJsonbValue([v]);
+      // prepareJsonbValue never returns kind:"literal" (only prepareValue's
+      // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
+      if (p && p.kind === "param") {
+        parts.push(`${quoteIdent(col)} @> $${idx++}${p.sql}`);
+        values.push(p.bound);
+      }
+    }
+    return parts.length > 0 ? `(${parts.join(" OR ")})` : "FALSE";
+  }
+  function isJsonbScalar(value: unknown): boolean {
+    return value !== null && typeof value !== "object";
+  }
   for (const [field, value] of Object.entries(where)) {
     const col = info.columnOf(field);
     const pgType = info.pgTypeOf(col);
@@ -597,6 +619,8 @@ function buildWhereClause(
     } else if (Array.isArray(value)) {
       if (value.length === 0) {
         conditions.push("FALSE");
+      } else if (pgType === "jsonb") {
+        conditions.push(jsonbContainsAny(col, value));
       } else {
         const parts: string[] = [];
         for (const v of value) {
@@ -626,6 +650,14 @@ function buildWhereClause(
       for (const [opKey, opSym] of Object.entries(opMap)) {
         const opVal = (value as Record<string, unknown>)[opKey];
         if (opVal === undefined) continue;
+        if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
+          const p = prepareJsonbValue([opVal]);
+          if (p && p.kind === "param") {
+            conditions.push(`NOT (${quoteIdent(col)} @> $${idx++}${p.sql})`);
+            values.push(p.bound);
+            continue;
+          }
+        }
         const p = prepareValue(opVal, pgType);
         if (p.kind === "literal") {
           conditions.push(`${quoteIdent(col)} ${opSym} ${p.literal}`);
@@ -636,7 +668,9 @@ function buildWhereClause(
       }
       const inVal = (value as Record<string, unknown>)["in"];
       if (Array.isArray(inVal)) {
-        if (inVal.length === 0) {
+        if (pgType === "jsonb") {
+          conditions.push(jsonbContainsAny(col, inVal));
+        } else if (inVal.length === 0) {
           conditions.push("FALSE");
         } else {
           const parts: string[] = [];
@@ -652,6 +686,8 @@ function buildWhereClause(
           conditions.push(`${quoteIdent(col)} IN (${parts.join(", ")})`);
         }
       }
+    } else if (pgType === "jsonb" && isJsonbScalar(value)) {
+      conditions.push(jsonbContainsAny(col, [value]));
     } else {
       const p = prepareValue(value, pgType);
       if (p.kind === "literal") {

package/src/db/__tests__/migrate-generator.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import type { EntityTableMeta } from "../entity-table-meta";
+import type { EntityTableMeta, IndexMeta } from "../entity-table-meta";
 import {
   assertValidMigrationName,
   diffSnapshots,
@@ -24,6 +24,19 @@ function meta(
   };
 }
 
+function metaWithIndexes(
+  tableName: string,
+  indexes: readonly IndexMeta[],
+  source: EntityTableMeta["source"] = "unmanaged",
+): EntityTableMeta {
+  return {
+    tableName,
+    source,
+    indexes,
+    columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
+  };
+}
+
 describe("snapshotFromMetas", () => {
   test("sorts tables by name for stable snapshots", () => {
     const snap = snapshotFromMetas([meta("zebras"), meta("apples")]);
@@ -199,6 +212,165 @@ describe("renderMigrationSql — managed recreate vs unmanaged in-place", () =>
   });
 });
 
+describe("renderMigrationSql — changed index predicates (kumiko-framework#2492)", () => {
+  test("diffSnapshots surfaces a whereSql-only change as a changed table (not silently dropped)", () => {
+    // Regression for the exact offlot#65 scenario: an index keeps its name
+    // and columns, only its partial-index predicate widens (framework#2464
+    // adding the soft-delete guard). Before the fix diffOneTable returned
+    // null here — the table never reached changedTables at all.
+    const prev = snapshotFromMetas([
+      metaWithIndexes("read_users", [
+        {
+          name: "read_users_email_bidx",
+          columns: ["email_bidx"],
+          unique: true,
+          whereSql: '"email_bidx" IS NOT NULL',
+        },
+      ]),
+    ]);
+    const next = snapshotFromMetas([
+      metaWithIndexes("read_users", [
+        {
+          name: "read_users_email_bidx",
+          columns: ["email_bidx"],
+          unique: true,
+          whereSql: '"email_bidx" IS NOT NULL AND "is_deleted" = false',
+        },
+      ]),
+    ]);
+    const diff = diffSnapshots(prev, next);
+    expect(diff.changedTables).toHaveLength(1);
+    expect(diff.changedTables[0]?.changedIndexes).toEqual([
+      {
+        name: "read_users_email_bidx",
+        whereSqlChanged: {
+          from: '"email_bidx" IS NOT NULL',
+          to: '"email_bidx" IS NOT NULL AND "is_deleted" = false',
+        },
+      },
+    ]);
+  });
+
+  test("emits DROP INDEX + CREATE INDEX with the new predicate", () => {
+    const prev = snapshotFromMetas([
+      metaWithIndexes("read_users", [
+        {
+          name: "read_users_email_bidx",
+          columns: ["email_bidx"],
+          unique: true,
+          whereSql: '"email_bidx" IS NOT NULL',
+        },
+      ]),
+    ]);
+    const next = snapshotFromMetas([
+      metaWithIndexes("read_users", [
+        {
+          name: "read_users_email_bidx",
+          columns: ["email_bidx"],
+          unique: true,
+          whereSql: '"email_bidx" IS NOT NULL AND "is_deleted" = false',
+        },
+      ]),
+    ]);
+    const sql = renderMigrationSql(diffSnapshots(prev, next), {
+      name: "predicate",
+      sequenceNumber: 9,
+    });
+    expect(sql).toContain('DROP INDEX IF EXISTS "read_users_email_bidx";');
+    expect(sql).toContain(
+      'CREATE UNIQUE INDEX IF NOT EXISTS "read_users_email_bidx" ON "read_users" ("email_bidx") WHERE "email_bidx" IS NOT NULL AND "is_deleted" = false;',
+    );
+    expect(sql).toContain("changed (where");
+  });
+
+  test("emits DROP INDEX + CREATE INDEX when only the column list changes", () => {
+    const prev = snapshotFromMetas([
+      metaWithIndexes("read_orders", [{ name: "read_orders_status_idx", columns: ["status"] }]),
+    ]);
+    const next = snapshotFromMetas([
+      metaWithIndexes("read_orders", [
+        { name: "read_orders_status_idx", columns: ["status", "tenant_id"] },
+      ]),
+    ]);
+    const sql = renderMigrationSql(diffSnapshots(prev, next), { name: "cols", sequenceNumber: 10 });
+    expect(sql).toContain('DROP INDEX IF EXISTS "read_orders_status_idx";');
+    expect(sql).toContain(
+      'CREATE INDEX IF NOT EXISTS "read_orders_status_idx" ON "read_orders" ("status", "tenant_id");',
+    );
+  });
+
+  test("emits DROP INDEX + CREATE UNIQUE INDEX when uniqueness changes on an existing index", () => {
+    const prev = snapshotFromMetas([
+      metaWithIndexes("read_orders", [{ name: "read_orders_ref_idx", columns: ["ref"] }]),
+    ]);
+    const next = snapshotFromMetas([
+      metaWithIndexes("read_orders", [
+        { name: "read_orders_ref_idx", columns: ["ref"], unique: true },
+      ]),
+    ]);
+    const sql = renderMigrationSql(diffSnapshots(prev, next), {
+      name: "unique",
+      sequenceNumber: 11,
+    });
+    expect(sql).toContain('DROP INDEX IF EXISTS "read_orders_ref_idx";');
+    expect(sql).toContain('CREATE UNIQUE INDEX IF NOT EXISTS "read_orders_ref_idx"');
+  });
+
+  test("needsManualWhere: keeps both DROP and CREATE commented out — never drops a live index with no executable replacement", () => {
+    const prev = snapshotFromMetas([
+      metaWithIndexes("read_widgets", [
+        { name: "read_widgets_active_idx", columns: ["status"], whereSql: "status = 'active'" },
+      ]),
+    ]);
+    const next = snapshotFromMetas([
+      metaWithIndexes("read_widgets", [
+        { name: "read_widgets_active_idx", columns: ["status"], needsManualWhere: true },
+      ]),
+    ]);
+    const sql = renderMigrationSql(diffSnapshots(prev, next), {
+      name: "manual",
+      sequenceNumber: 12,
+    });
+    expect(sql).toContain('-- (review) DROP INDEX IF EXISTS "read_widgets_active_idx";');
+    expect(sql).not.toMatch(/^DROP INDEX IF EXISTS "read_widgets_active_idx";$/m);
+    expect(sql).toContain('-- CREATE INDEX IF NOT EXISTS "read_widgets_active_idx"');
+    expect(sql).not.toMatch(/^CREATE INDEX IF NOT EXISTS "read_widgets_active_idx"/m);
+  });
+
+  test("unchanged index (same name/columns/unique/whereSql) produces no diff at all", () => {
+    const idx: IndexMeta = {
+      name: "read_a_status_idx",
+      columns: ["status"],
+      whereSql: "status IS NOT NULL",
+    };
+    const prev = snapshotFromMetas([metaWithIndexes("read_a", [idx])]);
+    const next = snapshotFromMetas([metaWithIndexes("read_a", [{ ...idx }])]);
+    expect(diffSnapshots(prev, next).changedTables).toEqual([]);
+  });
+
+  test("new index with needsManualWhere is rendered commented-out, not silently as a bare CREATE INDEX (render-ddl consolidation)", () => {
+    // migrate-generator.ts used to carry its own renderIndex() copy that
+    // didn't check needsManualWhere — a new partial index with an
+    // unrenderable WHERE was emitted as a plain, uncommented CREATE INDEX
+    // with the predicate silently dropped. Now it shares render-ddl.ts's
+    // renderIndex, which comments the statement out for manual review.
+    const prev = snapshotFromMetas([meta("read_c", undefined, "unmanaged")]);
+    const next = snapshotFromMetas([
+      metaWithIndexes(
+        "read_c",
+        [{ name: "read_c_status_idx", columns: ["status"], needsManualWhere: true }],
+        "unmanaged",
+      ),
+    ]);
+    const sql = renderMigrationSql(diffSnapshots(prev, next), {
+      name: "newpartial",
+      sequenceNumber: 13,
+    });
+    expect(sql).toContain('-- CREATE INDEX IF NOT EXISTS "read_c_status_idx"');
+    expect(sql).not.toMatch(/^CREATE INDEX IF NOT EXISTS "read_c_status_idx"/m);
+  });
+});
+
 describe("assertValidMigrationName", () => {
   test("accepts alphanumeric hyphenated names", () => {
     expect(() => assertValidMigrationName("add-user-table")).not.toThrow();

package/src/db/event-store-executor-read.ts

@@ -10,7 +10,7 @@ import { getStreamVersion } from "../event-store";
 import { rehydrateCompoundTypes } from "./compound-types";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor";
 import type { EventStoreExecutor } from "./event-store-executor";
-import { buildFilterWhere, type ExecutorContext } from "./event-store-executor-context";
+import { buildFilterWhere, type ExecutorContext, type Table } from "./event-store-executor-context";
 import { toSnakeCase } from "./table-builder";
 
 // The two read verbs (list/detail) of the event-store-executor. Split out
@@ -91,6 +91,115 @@ function keysetBoundarySql(
     : `(${sortCol} IS NULL OR ${beyond} OR ${tie})`;
 }
 
+type ListFilter = {
+  readonly field: string;
+  readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+  readonly value: unknown;
+};
+
+// multiSelect stores its options as a jsonb array — a filter value is one
+// option, not the whole array, so eq/ne/in must check array containment
+// (`@>`) instead of scalar `=`/`<>`/`IN` against the jsonb column (fw#2490).
+// lt/gt have no containment analogue; the boot-validator already blocks them
+// for screen-declared filters (screen-filter-ops.ts EQUALITY_ONLY), but a
+// client-supplied facet filter reaches here unvalidated, so treat it as
+// unsatisfiable rather than emitting SQL Postgres would reject.
+function applyMultiSelectFilter(
+  colSql: (field: string) => string,
+  whereSql: string[],
+  params: unknown[],
+  f: ListFilter,
+): void {
+  if (f.op === "lt" || f.op === "gt") {
+    whereSql.push("FALSE");
+    // skip: lt/gt is unsatisfiable on a multiSelect column
+    return;
+  }
+  if (f.op === "in") {
+    if (!Array.isArray(f.value) || f.value.length === 0) {
+      whereSql.push("FALSE");
+      // skip: empty/non-array `in` is unsatisfiable, mirrors buildFilterWhere's "in" short-circuit
+      return;
+    }
+    const parts = f.value.map((v) => {
+      params.push([v]);
+      return `${colSql(f.field)} @> $${params.length}::jsonb`;
+    });
+    whereSql.push(`(${parts.join(" OR ")})`);
+    // skip: containment condition already pushed — don't fall through to the eq/ne branch below
+    return;
+  }
+  // Bind a JS array, not JSON.stringify(value) — postgres.js double-encodes
+  // a stringified array through an `::jsonb` cast, so `@>` would never match
+  // (see update-roles.ts:67-68). An array value means "contains all of
+  // these" (the natural `@>` reading).
+  params.push(Array.isArray(f.value) ? f.value : [f.value]);
+  const containment = `${colSql(f.field)} @> $${params.length}::jsonb`;
+  whereSql.push(f.op === "ne" ? `NOT (${containment})` : containment);
+}
+
+// Falls through to the screen-filter WHERE builder shared with
+// screen-declared filters — buildFilterWhere flattens the op into a
+// WhereObject, which this then lowers to raw SQL fragments.
+function applyScreenFilter(
+  table: Table,
+  colSql: (field: string) => string,
+  whereSql: string[],
+  params: unknown[],
+  f: ListFilter,
+): void {
+  const screen = buildFilterWhere(f.field, f.op, f.value);
+  if (screen === null) {
+    whereSql.push("FALSE");
+    // skip: filter is unsatisfiable → emit FALSE, no params to bind
+    return;
+  }
+  for (const [field, value] of Object.entries(screen)) {
+    // #2015: `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in bun-db/query.ts.
+    if (value === null) {
+      whereSql.push(`${colSql(field)} IS NULL`);
+    } else if (Array.isArray(value)) {
+      const placeholders = value.map((v) => {
+        params.push(v);
+        return `$${params.length}`;
+      });
+      whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
+    } else if (typeof value === "object") {
+      const valueObj = value as Record<string, unknown>;
+      if (valueObj["ne"] === null && Object.keys(valueObj).length === 1) {
+        whereSql.push(`${colSql(field)} IS NOT NULL`);
+        continue;
+      }
+      const opMap: Record<string, string> = {
+        gt: ">",
+        gte: ">=",
+        lt: "<",
+        lte: "<=",
+        ne: "<>",
+      };
+      for (const [opKey, opSym] of Object.entries(opMap)) {
+        if (!(opKey in value)) continue;
+        params.push((value as Record<string, unknown>)[opKey]);
+        whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
+      }
+    } else {
+      // Blind-Index-OR-Rewrite (#818), lock-step mit buildWhereClause
+      // in bun-db/query.ts — Equality auf lookupable-Feldern matcht
+      // Klartext-Arm ODER HMAC-Arm.
+      const bidxKey = configuredBlindIndexKey();
+      if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
+        params.push(value, computeBlindIndex(bidxKey, value));
+        whereSql.push(
+          `(${colSql(field)} = $${params.length - 1} OR ${colSql(`${field}Bidx`)} = $${params.length})`,
+        );
+      } else {
+        params.push(value);
+        whereSql.push(`${colSql(field)} = $${params.length}`);
+      }
+    }
+  }
+}
+
 export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail"> {
   const {
     table,
@@ -203,65 +312,17 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         whereSql.push(shifted.sqlText);
         for (const p of shifted.params) params.push(p);
       }
-      const applyFilter = (f: {
-        readonly field: string;
-        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
-        readonly value: unknown;
-      }): void => {
+      const applyFilter = (f: ListFilter): void => {
         if (table[f.field] === undefined) {
           // skip: unknown field — not a real column, drop the filter (injection guard)
           return;
         }
-        const screen = buildFilterWhere(f.field, f.op, f.value);
-        if (screen === null) {
-          whereSql.push("FALSE");
-          // skip: filter is unsatisfiable → emit FALSE, no params to bind
+        if (entity.fields[f.field]?.type === "multiSelect") {
+          applyMultiSelectFilter(colSql, whereSql, params, f);
+          // skip: multiSelect already handled — don't fall through to applyScreenFilter
           return;
         }
-        for (const [field, value] of Object.entries(screen)) {
-          // #2015: `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in bun-db/query.ts.
-          if (value === null) {
-            whereSql.push(`${colSql(field)} IS NULL`);
-          } else if (Array.isArray(value)) {
-            const placeholders = value.map((v) => {
-              params.push(v);
-              return `$${params.length}`;
-            });
-            whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
-          } else if (typeof value === "object") {
-            const valueObj = value as Record<string, unknown>;
-            if (valueObj["ne"] === null && Object.keys(valueObj).length === 1) {
-              whereSql.push(`${colSql(field)} IS NOT NULL`);
-              continue;
-            }
-            const opMap: Record<string, string> = {
-              gt: ">",
-              gte: ">=",
-              lt: "<",
-              lte: "<=",
-              ne: "<>",
-            };
-            for (const [opKey, opSym] of Object.entries(opMap)) {
-              if (!(opKey in value)) continue;
-              params.push((value as Record<string, unknown>)[opKey]);
-              whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
-            }
-          } else {
-            // Blind-Index-OR-Rewrite (#818), lock-step mit buildWhereClause
-            // in bun-db/query.ts — Equality auf lookupable-Feldern matcht
-            // Klartext-Arm ODER HMAC-Arm.
-            const bidxKey = configuredBlindIndexKey();
-            if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
-              params.push(value, computeBlindIndex(bidxKey, value));
-              whereSql.push(
-                `(${colSql(field)} = $${params.length - 1} OR ${colSql(`${field}Bidx`)} = $${params.length})`,
-              );
-            } else {
-              params.push(value);
-              whereSql.push(`${colSql(field)} = $${params.length}`);
-            }
-          }
-        }
+        applyScreenFilter(table, colSql, whereSql, params, f);
       };
       if (payload.filter !== undefined) applyFilter(payload.filter);
       if (payload.filters !== undefined) for (const f of payload.filters) applyFilter(f);

package/src/db/migrate-generator.ts

@@ -19,7 +19,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 
 import { compareByCodepoint } from "../utils";
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta";
-import { renderTableDdl } from "./render-ddl";
+import { renderIndex, renderTableDdl } from "./render-ddl";
 
 const SNAPSHOT_VERSION = 1 as const;
 
@@ -36,6 +36,14 @@ export type ColumnChange = {
   readonly typeChanged?: { readonly from: string; readonly to: string };
 };
 
+export type IndexChange = {
+  readonly name: string;
+  readonly columnsChanged?: { readonly from: readonly string[]; readonly to: readonly string[] };
+  readonly uniqueChanged?: { readonly from: boolean; readonly to: boolean };
+  readonly whereSqlChanged?: { readonly from: string | undefined; readonly to: string | undefined };
+  readonly needsManualWhereChanged?: { readonly from: boolean; readonly to: boolean };
+};
+
 export type TableDiff = {
   readonly tableName: string;
   readonly newColumns: readonly ColumnMeta[];
@@ -43,6 +51,10 @@ export type TableDiff = {
   readonly changedColumns: readonly ColumnChange[];
   readonly newIndexes: readonly IndexMeta[];
   readonly droppedIndexes: readonly string[];
+  // Same-named index whose shape (columns/unique/whereSql/needsManualWhere)
+  // changed — recreated via DROP+CREATE rather than silently absorbed into
+  // the new snapshot with no emitted DDL (kumiko-framework#2492).
+  readonly changedIndexes: readonly IndexChange[];
   // Full target meta — carried so the renderer can emit DROP+CREATE for a
   // managed projection whose change cannot apply in-place (see
   // managedChangeRequiresRecreate). Source-discriminator reached via nextMeta.source.
@@ -94,6 +106,10 @@ function indexMetaKey(idx: IndexMeta): string {
   return idx.name;
 }
 
+function indexColumnsEqual(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((col, i) => col === b[i]);
+}
+
 function columnsByName(meta: EntityTableMeta): Map<string, ColumnMeta> {
   const m = new Map<string, ColumnMeta>();
   for (const c of meta.columns) m.set(c.name, c);
@@ -148,8 +164,45 @@ function diffOneTable(prev: EntityTableMeta, next: EntityTableMeta): TableDiff |
   const nextIdx = indexesByName(next);
   const newIndexes: IndexMeta[] = [];
   const droppedIndexes: string[] = [];
+  const changedIndexes: IndexChange[] = [];
   for (const [name, idx] of nextIdx) {
-    if (!prevIdx.has(name)) newIndexes.push(idx);
+    const prevI = prevIdx.get(name);
+    if (!prevI) {
+      newIndexes.push(idx);
+      continue;
+    }
+    const change: IndexChange = { name };
+    if (!indexColumnsEqual(prevI.columns, idx.columns)) {
+      Object.assign(change, {
+        columnsChanged: { from: prevI.columns, to: idx.columns },
+      });
+    }
+    if ((prevI.unique ?? false) !== (idx.unique ?? false)) {
+      Object.assign(change, {
+        uniqueChanged: { from: prevI.unique ?? false, to: idx.unique ?? false },
+      });
+    }
+    if (prevI.whereSql !== idx.whereSql) {
+      Object.assign(change, {
+        whereSqlChanged: { from: prevI.whereSql, to: idx.whereSql },
+      });
+    }
+    if ((prevI.needsManualWhere ?? false) !== (idx.needsManualWhere ?? false)) {
+      Object.assign(change, {
+        needsManualWhereChanged: {
+          from: prevI.needsManualWhere ?? false,
+          to: idx.needsManualWhere ?? false,
+        },
+      });
+    }
+    if (
+      change.columnsChanged ||
+      change.uniqueChanged ||
+      change.whereSqlChanged ||
+      change.needsManualWhereChanged
+    ) {
+      changedIndexes.push(change);
+    }
   }
   for (const name of prevIdx.keys()) {
     if (!nextIdx.has(name)) droppedIndexes.push(name);
@@ -160,7 +213,8 @@ function diffOneTable(prev: EntityTableMeta, next: EntityTableMeta): TableDiff |
     droppedColumns.length === 0 &&
     changedColumns.length === 0 &&
     newIndexes.length === 0 &&
-    droppedIndexes.length === 0;
+    droppedIndexes.length === 0 &&
+    changedIndexes.length === 0;
   if (isEmpty) return null;
   return {
     tableName: prev.tableName,
@@ -169,6 +223,7 @@ function diffOneTable(prev: EntityTableMeta, next: EntityTableMeta): TableDiff |
     changedColumns,
     newIndexes,
     droppedIndexes,
+    changedIndexes,
     nextMeta: next,
   };
 }
@@ -305,11 +360,38 @@ function renderColumnChange(tableName: string, change: ColumnChange): readonly s
   return out;
 }
 
-function renderIndex(tableName: string, idx: IndexMeta): string {
-  const kind = idx.unique === true ? "UNIQUE INDEX" : "INDEX";
-  const colList = idx.columns.map(quoteIdent).join(", ");
-  const where = idx.whereSql !== undefined ? ` WHERE ${idx.whereSql}` : "";
-  return `CREATE ${kind} IF NOT EXISTS ${quoteIdent(idx.name)} ON ${quoteIdent(tableName)} (${colList})${where};`;
+// Collapses whitespace so a multi-line whereSql (e.g. a two-condition
+// drizzle sql`…` predicate) can't inject a newline into this `--` comment
+// line and escape into the executable body of the generated migration.
+function toSingleLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function describeIndexChange(change: IndexChange): string {
+  const parts: string[] = [];
+  if (change.columnsChanged) {
+    parts.push(
+      `columns (${change.columnsChanged.from.join(", ")}) → (${change.columnsChanged.to.join(", ")})`,
+    );
+  }
+  if (change.uniqueChanged) {
+    parts.push(`unique ${change.uniqueChanged.from} → ${change.uniqueChanged.to}`);
+  }
+  if (change.whereSqlChanged) {
+    const from =
+      change.whereSqlChanged.from !== undefined
+        ? toSingleLine(change.whereSqlChanged.from)
+        : "<none>";
+    const to =
+      change.whereSqlChanged.to !== undefined ? toSingleLine(change.whereSqlChanged.to) : "<none>";
+    parts.push(`where ${from} → ${to}`);
+  }
+  if (change.needsManualWhereChanged) {
+    parts.push(
+      `needs-manual-where ${change.needsManualWhereChanged.from} → ${change.needsManualWhereChanged.to}`,
+    );
+  }
+  return parts.join("; ");
 }
 
 // Render the diff as a SQL-file content with header-comment + grouped
@@ -366,6 +448,27 @@ export function renderMigrationSql(
       for (const idx of td.newIndexes) {
         lines.push(renderIndex(td.tableName, idx));
       }
+      for (const idxChange of td.changedIndexes) {
+        const nextIdxMeta = td.nextMeta.indexes.find((i) => i.name === idxChange.name);
+        if (!nextIdxMeta) {
+          throw new Error(
+            `Index "${idxChange.name}" changed but is missing from the next table meta — generator bug in diffOneTable.`,
+          );
+        }
+        lines.push(
+          `-- index ${quoteIdent(idxChange.name)} changed (${describeIndexChange(idxChange)}) — recreated`,
+        );
+        // needsManualWhere renders CREATE as a commented WARN (renderIndex),
+        // since the generator can't express the new WHERE — the DROP has to
+        // stay commented too, or the live index gets dropped with no
+        // executable replacement (kumiko-framework#2492 review).
+        lines.push(
+          nextIdxMeta.needsManualWhere === true
+            ? `-- (review) DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`
+            : `DROP INDEX IF EXISTS ${quoteIdent(idxChange.name)};`,
+        );
+        lines.push(renderIndex(td.tableName, nextIdxMeta));
+      }
       for (const name of td.droppedIndexes) {
         lines.push(`-- (review) DROP INDEX IF EXISTS ${quoteIdent(name)};`);
       }

package/src/db/render-ddl.ts

@@ -23,7 +23,7 @@ function renderColumn(col: ColumnMeta): string {
   return parts.join(" ");
 }
 
-function renderIndex(tableName: string, idx: IndexMeta): string {
+export function renderIndex(tableName: string, idx: IndexMeta): string {
   const kind = idx.unique === true ? "UNIQUE INDEX" : "INDEX";
   const colList = idx.columns.map(quoteIdent).join(", ");
   if (idx.needsManualWhere === true) {