@cosmicdrift/kumiko-framework 0.156.1 → 0.156.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.156.1",
+  "version": "0.156.3",
   "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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.156.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.156.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/entity-table-meta-source.test.ts

@@ -0,0 +1,50 @@
+// #1210: buildEntityTableMeta() hardcoded source: "managed", so unmanaged
+// direct-write stores (read_user_sessions, read_api_tokens, mail sync/seen
+// cursors) were misclassified as rebuildable event-sourced projections — a
+// destructive column change would DROP+rebuild-from-events tables that have
+// no events, wiping live data. The options.source escape hatch must produce
+// a byte-identical column/piiSubjectFields shape (only source differs), so
+// the migration diff for an existing table stays empty when flipping it.
+
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { buildEntityTableMeta } from "../entity-table-meta";
+import { diffSnapshots, snapshotFromMetas } from "../migrate-generator";
+
+const entity = createEntity({
+  table: "source-probe",
+  fields: {
+    userId: createTextField({ required: true }),
+    ip: createTextField({ userOwned: { ownerField: "userId" } }),
+  },
+});
+
+describe("buildEntityTableMeta — options.source (#1210)", () => {
+  test("defaults to managed when omitted", () => {
+    expect(buildEntityTableMeta("source-probe", entity).source).toBe("managed");
+  });
+
+  test("options.source: 'unmanaged' changes only source, columns + piiSubjectFields stay identical", () => {
+    const managed = buildEntityTableMeta("source-probe", entity);
+    const unmanaged = buildEntityTableMeta("source-probe", entity, { source: "unmanaged" });
+
+    expect(managed.source).toBe("managed");
+    expect(unmanaged.source).toBe("unmanaged");
+    expect(unmanaged.columns).toEqual(managed.columns);
+    expect(unmanaged.indexes).toEqual(managed.indexes);
+    expect(unmanaged.piiSubjectFields).toEqual(managed.piiSubjectFields);
+    expect(unmanaged.piiSubjectFields).toEqual(["ip"]);
+  });
+
+  test("flipping an existing table's meta to unmanaged produces an empty migration diff", () => {
+    const prevSnapshot = snapshotFromMetas([buildEntityTableMeta("source-probe", entity)]);
+    const nextSnapshot = snapshotFromMetas([
+      buildEntityTableMeta("source-probe", entity, { source: "unmanaged" }),
+    ]);
+
+    const diff = diffSnapshots(prevSnapshot, nextSnapshot);
+    expect(diff.newTables).toEqual([]);
+    expect(diff.droppedTables).toEqual([]);
+    expect(diff.changedTables).toEqual([]);
+  });
+});

package/src/db/entity-table-meta.ts

@@ -296,6 +296,7 @@ export function resolveTableName(
 export type BuildEntityTableMetaOptions = {
   readonly featureName?: string;
   readonly relations?: EntityRelations;
+  readonly source?: "managed" | "unmanaged";
 };
 
 export function buildEntityTableMeta(
@@ -415,7 +416,7 @@ export function buildEntityTableMeta(
     tableName,
     columns,
     indexes,
-    source: "managed",
+    source: options?.source ?? "managed",
     ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
   };
 }

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

@@ -1297,6 +1297,102 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- function-renderer check on the non-entityEdit/entityList screen
+  // types that share the same EditLayout/ListColumnSpec shapes
+  // (action-wiring.ts's validateEditLayoutNoFunctions/validateColumnsNoFunctions) ---
+  describe("function-renderer check on other EditLayout/columns screens", () => {
+    test("actionForm field renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.screen({
+            id: "restock",
+            type: "actionForm",
+            handler: "shop:write:restock",
+            fields: { qty: { type: "number" } } as never,
+            layout: {
+              sections: [
+                { fields: [{ field: "qty", renderer: (v: unknown) => String(v) }] as never },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(actionForm\) field "qty" renderer is a function/,
+      );
+    });
+
+    test("configEdit field renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.config({
+            keys: { "site-name": createTenantConfig("text", { default: "" }) },
+          });
+          r.screen({
+            id: "settings",
+            type: "configEdit",
+            scope: "tenant",
+            configKeys: { siteName: "shop:config:site-name" },
+            fields: { siteName: { type: "text" } } as never,
+            layout: {
+              sections: [
+                {
+                  fields: [{ field: "siteName", renderer: (v: unknown) => String(v) }] as never,
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(configEdit\) field "siteName" renderer is a function/,
+      );
+    });
+
+    test("projectionDetail field renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.screen({
+            id: "order-detail",
+            type: "projectionDetail",
+            query: "shop:query:order-detail",
+            layout: {
+              sections: [
+                { fields: [{ field: "total", renderer: (v: unknown) => String(v) }] as never },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(projectionDetail\) field "total" renderer is a function/,
+      );
+    });
+
+    test("dashboard list-panel column renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.screen({
+            id: "overview",
+            type: "dashboard",
+            panels: [
+              {
+                kind: "list",
+                id: "recent-orders",
+                label: "Recent Orders",
+                query: "shop:query:recent-orders",
+                columns: [{ field: "total", renderer: (v: unknown) => String(v) }] as never,
+              },
+            ],
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(dashboard-list\) column "total" renderer is a function/,
+      );
+    });
+  });
+
   // --- entityList virtual (labeled) columns ---
   // A column whose `field` is not an entity field is allowed IF it carries a
   // `label` — a presentational column drawn by a columnRenderer component (e.g.

package/src/engine/__tests__/build-app-schema.test.ts

@@ -216,6 +216,27 @@ describe("buildAppSchema", () => {
     expect(fields["name"]?.["filterable"]).toBeUndefined();
   });
 
+  test("searchable kommt ins Client-Schema (steuert den EntityList-Default, #1194)", () => {
+    const entity = {
+      fields: {
+        title: { type: "text", searchable: true },
+        name: { type: "text" },
+      },
+    } as unknown as EntityDefinition;
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]?.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+    expect(fields["title"]?.["searchable"]).toBe(true);
+    // Fields without searchable don't carry the key (no false-litter).
+    expect(fields["name"]?.["searchable"]).toBeUndefined();
+  });
+
   test("AppSchema ist via JSON.stringify roundtrip-sicher", () => {
     // Echter Smoke-Test des Vertrags — wenn jemand in den project-
     // Helper eine Function reinschmuggelt, würde das hier brennen.

package/src/engine/boot-validator/action-wiring.ts

@@ -1,4 +1,11 @@
-import type { EditFieldSpec, FeatureDefinition, RowAction, ToolbarAction } from "../types";
+import type {
+  EditFieldSpec,
+  EditLayout,
+  FeatureDefinition,
+  ListColumnSpec,
+  RowAction,
+  ToolbarAction,
+} from "../types";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 const FUNCTION_DROPPED_HINT =
@@ -55,6 +62,7 @@ const EDIT_FIELD_FUNCTION_FIELDS = ["visible", "readOnly", "required"] as const;
 function validateEditFieldNoFunctions(
   featureName: string,
   screenId: string,
+  screenType: string,
   fieldSpec: EditFieldSpec,
 ): void {
   const normalized = normalizeEditField(fieldSpec);
@@ -62,37 +70,79 @@ function validateEditFieldNoFunctions(
   for (const key of EDIT_FIELD_FUNCTION_FIELDS) {
     throwIfFunction(
       record[key],
-      `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}" ` +
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
         `${key} is a function — ${FUNCTION_DROPPED_HINT} Use a FieldCondition ` +
         `(boolean or { field, eq }/{ field, ne }) instead.`,
     );
   }
   throwIfFunction(
     normalized.renderer,
-    `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}" ` +
+    `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
       `renderer is a function — ${FUNCTION_DROPPED_HINT} Use a FormatSpec ({ format: "..." }) instead.`,
   );
 }
 
+function validateColumnsNoFunctions(
+  featureName: string,
+  screenId: string,
+  screenType: string,
+  columns: readonly ListColumnSpec[],
+): void {
+  for (const col of columns) {
+    const normalized = normalizeListColumn(col);
+    throwIfFunction(
+      normalized.renderer,
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) column ` +
+        `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
+        `Use a FormatSpec ({ format: "..." }) instead.`,
+    );
+  }
+}
+
+function validateEditLayoutNoFunctions(
+  featureName: string,
+  screenId: string,
+  screenType: string,
+  layout: EditLayout,
+): void {
+  for (const section of layout.sections) {
+    if (isExtensionEditSection(section)) continue;
+    for (const fieldSpec of section.fields) {
+      validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
+    }
+  }
+}
+
+// Screen types that carry an EditLayout (entityEdit's layout shape, reused
+// verbatim by actionForm/configEdit/projectionDetail) vs. ones that carry
+// ListColumnSpec[] (entityList/projectionList, plus dashboard "list" panels)
+// both funnel through the same two checks below — a function literal in
+// either shape is dropped by JSON.stringify regardless of which screen type
+// hosts it.
 export function validateFieldWiring(feature: FeatureDefinition): void {
   for (const screen of Object.values(feature.screens)) {
     if (screen.type === "entityList" || screen.type === "projectionList") {
-      for (const col of screen.columns) {
-        const normalized = normalizeListColumn(col);
-        throwIfFunction(
-          normalized.renderer,
-          `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) column ` +
-            `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
-            `Use a FormatSpec ({ format: "..." }) instead.`,
-        );
-      }
+      validateColumnsNoFunctions(feature.name, screen.id, screen.type, screen.columns);
       continue;
     }
-    if (screen.type !== "entityEdit") continue;
-    for (const section of screen.layout.sections) {
-      if (isExtensionEditSection(section)) continue;
-      for (const fieldSpec of section.fields) {
-        validateEditFieldNoFunctions(feature.name, screen.id, fieldSpec);
+    if (
+      screen.type === "entityEdit" ||
+      screen.type === "actionForm" ||
+      screen.type === "configEdit" ||
+      screen.type === "projectionDetail"
+    ) {
+      validateEditLayoutNoFunctions(feature.name, screen.id, screen.type, screen.layout);
+      continue;
+    }
+    if (screen.type === "dashboard") {
+      for (const panel of screen.panels) {
+        if (panel.kind !== "list") continue;
+        validateColumnsNoFunctions(
+          feature.name,
+          `${screen.id}:${panel.id}`,
+          "dashboard-list",
+          panel.columns,
+        );
       }
     }
   }

package/src/engine/build-app-schema.ts

@@ -348,6 +348,7 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   // filterable steuert die Faceted-Filter-Dropdowns im Renderer (select/
   // boolean) — muss daher ins Client-Schema.
   if (typeof def["filterable"] === "boolean") out["filterable"] = def["filterable"];
+  if (typeof def["searchable"] === "boolean") out["searchable"] = def["searchable"];
   if (isLiteral(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];

package/src/engine/feature-ui-extensions.ts

@@ -89,6 +89,28 @@ export function buildUiExtensionsMethods<TName extends string>(
   state: FeatureBuilderState,
   name: TName,
 ) {
+  // Shared by r.nav() and r.screen()'s inline nav-sugar path — one place
+  // for id-validation + collision checks so future registration-time
+  // checks (e.g. parent-format, reserved ids) apply to both call sites
+  // instead of only the standalone r.nav() one.
+  function registerNav(navDefinition: NavDefinition): void {
+    if (!isKebabSegment(navDefinition.id)) {
+      throw new Error(
+        `[Feature ${name}] Nav id "${navDefinition.id}" must be kebab-case ` +
+          `(lowercase letters, digits, dashes; start with a letter). ` +
+          `Got "${navDefinition.id}" — try "${toKebab(navDefinition.id).replace(/_/g, "-")}".`,
+      );
+    }
+    if (state.navs[navDefinition.id]) {
+      throw new Error(
+        `[Feature ${name}] Nav entry "${navDefinition.id}" already registered. ` +
+          `Nav ids must be unique per feature — remove the standalone ` +
+          `r.nav("${navDefinition.id}", ...) call or the screen's inline nav.`,
+      );
+    }
+    state.navs[navDefinition.id] = navDefinition;
+  }
+
   return {
     hook(
       type: LifecycleHookType | "validation",
@@ -334,42 +356,18 @@ export function buildUiExtensionsMethods<TName extends string>(
         // Sugar for the common "one nav entry pointing at this screen"
         // case — synthesizes id/screen from the screen's own id. Beyond
         // label/icon/parent/order, declare a standalone r.nav() instead.
-        if (state.navs[definition.id]) {
-          throw new Error(
-            `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
-              `Nav ids must be unique per feature — remove the standalone ` +
-              `r.nav("${definition.id}", ...) call or the screen's inline nav.`,
-          );
-        }
-        const navDefinition: NavDefinition = {
+        registerNav({
           id: definition.id,
           label: definition.nav.label,
           icon: definition.nav.icon,
           parent: definition.nav.parent,
           order: definition.nav.order,
           screen: `${name}:screen:${definition.id}`,
-        };
-        state.navs[definition.id] = navDefinition;
+        });
       }
     },
     nav(definition: NavDefinition): void {
-      // Reject kebab-drift at registration-time so the stack trace points at
-      // the feature file, not at registry-boot. Same guard pattern as
-      // r.projection / r.multiStreamProjection / r.screen.
-      if (!isKebabSegment(definition.id)) {
-        throw new Error(
-          `[Feature ${name}] Nav id "${definition.id}" must be kebab-case ` +
-            `(lowercase letters, digits, dashes; start with a letter). ` +
-            `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`,
-        );
-      }
-      if (state.navs[definition.id]) {
-        throw new Error(
-          `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
-            `Nav ids must be unique per feature.`,
-        );
-      }
-      state.navs[definition.id] = definition;
+      registerNav(definition);
     },
     workspace(definition: WorkspaceDefinition): void {
       // Same kebab guard as r.screen / r.nav so authoring-time mistakes

package/src/files/__tests__/file-ref-entity.test.ts

@@ -32,3 +32,11 @@ describe("fileRefEntity base-column drift", () => {
     expect(insertedById[0]?.notNull).toBe(false);
   });
 });
+
+describe("fileRefEntity — DDL (#1205 regression)", () => {
+  test("size column is bigint, not double precision", () => {
+    const size = col("size");
+    expect(size).toHaveLength(1);
+    expect(size[0]?.pgType).toBe("bigint");
+  });
+});

package/src/files/file-ref-entity.ts

@@ -1,4 +1,4 @@
-import { createEntity, createNumberField, createTextField } from "../engine";
+import { createBigIntField, createEntity, createTextField } from "../engine";
 
 // fileRef — das File-Metadata-Entity. Ganz normales ES-Entity: Upload/Delete
 // laufen über den Standard-Executor (file-routes.ts), die Tabelle `file_refs`
@@ -25,7 +25,7 @@ export const fileRefEntity = createEntity({
     storageKey: createTextField({ required: true }),
     fileName: createTextField({ required: true, pii: true }),
     mimeType: createTextField({ required: true }),
-    size: createNumberField({ required: true }),
+    size: createBigIntField({ required: true }),
     entityType: createTextField(),
     entityId: createTextField(),
     fieldName: createTextField(),

package/src/search/__tests__/reindex-entity.integration.test.ts

@@ -0,0 +1,121 @@
+// reindexEntity — Integration Test
+// Proves: rows written before a search consumer ever indexed them (the
+// #1206 scenario — searchable:true added retroactively) become findable
+// after a backfill run, soft-deleted rows stay excluded, and dryRun writes
+// nothing.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { reindexEntity } from "@cosmicdrift/kumiko-framework/search";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+
+const widgetEntity = createEntity({
+  table: "read_reindex_widgets",
+  softDelete: true,
+  fields: {
+    name: createTextField({ required: true, searchable: true }),
+  },
+});
+
+const widgetTable = buildEntityTable("widget", widgetEntity);
+
+const widgetFeature = defineFeature("reindex-test", (r) => {
+  r.entity("widget", widgetEntity);
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [widgetFeature] });
+  await unsafeCreateEntityTable(stack.db, widgetEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function seedExecutor() {
+  return createEventStoreExecutor(widgetTable, widgetEntity, { entityName: "widget" });
+}
+
+function tenantDb() {
+  return createTenantDb(stack.db, admin.tenantId, "system");
+}
+
+describe("reindexEntity", () => {
+  test("indexes rows that were never drained through the search consumer", async () => {
+    const executor = seedExecutor();
+    const created = await executor.create({ name: "Backfillable Widget" }, admin, tenantDb());
+    if (!created.isSuccess) throw new Error("seed failed");
+
+    // No stack.eventDispatcher.runOnce() call — simulates rows that existed
+    // before search indexing ever ran for this entity.
+    const preResults = await stack.search.search(admin.tenantId, "backfillable", {
+      filterType: "widget",
+    });
+    expect(preResults).toHaveLength(0);
+
+    const result = await reindexEntity(
+      stack.db,
+      stack.registry,
+      stack.search,
+      "widget",
+      admin.tenantId,
+    );
+    expect(result.indexedRows).toBe(1);
+    expect(result.failures).toHaveLength(0);
+
+    const postResults = await stack.search.search(admin.tenantId, "backfillable", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
+  });
+
+  test("skips soft-deleted rows", async () => {
+    const executor = seedExecutor();
+    const created = await executor.create({ name: "Erased Widget" }, admin, tenantDb());
+    if (!created.isSuccess) throw new Error("seed failed");
+    const deleted = await executor.delete({ id: created.data.id }, admin, tenantDb());
+    if (!deleted.isSuccess) throw new Error("delete failed");
+
+    await reindexEntity(stack.db, stack.registry, stack.search, "widget", admin.tenantId);
+
+    const postResults = await stack.search.search(admin.tenantId, "erased", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(false);
+  });
+
+  test("dryRun scans without writing to the index", async () => {
+    const executor = seedExecutor();
+    await executor.create({ name: "DryRun Widget" }, admin, tenantDb());
+
+    const result = await reindexEntity(
+      stack.db,
+      stack.registry,
+      stack.search,
+      "widget",
+      admin.tenantId,
+      { dryRun: true },
+    );
+    expect(result.indexedRows).toBeGreaterThan(0);
+
+    const postResults = await stack.search.search(admin.tenantId, "dryrun", {
+      filterType: "widget",
+    });
+    expect(postResults).toHaveLength(0);
+  });
+});

package/src/search/index.ts

@@ -3,6 +3,12 @@
 // von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
 // Client-Code nicht mit rein.
 export { createInMemorySearchAdapter } from "./in-memory-adapter";
+export type {
+  ReindexEntityFailure,
+  ReindexEntityOptions,
+  ReindexEntityResult,
+} from "./reindex-entity";
+export { reindexEntity } from "./reindex-entity";
 export type {
   SearchAdapter,
   SearchAdapterConfig,

package/src/search/reindex-entity.ts

@@ -0,0 +1,148 @@
+// One-time backfill for entities that only got `searchable: true` after rows
+// already existed (#1206). buildSearchDocument() only runs on the write path
+// (createSearchEventConsumer, system-hooks.ts) — pre-existing rows never
+// pass through it, so they stay unfindable until their next write. This
+// re-derives a SearchDocument straight from the read-table row for every
+// existing row and indexes it, same as a live write would.
+
+import type { DbRunner } from "../db/connection";
+import { resolveTableName } from "../db/entity-table-meta";
+import { executeRawQuery } from "../db/queries/raw-sql";
+import type { Registry, TenantId } from "../engine/types";
+import { buildSearchDocument } from "../pipeline/system-hooks";
+import { toSnakeCase } from "../utils/case";
+import type { SearchAdapter, SearchDocument } from "./types";
+
+export type ReindexEntityFailure = {
+  readonly entityId: string;
+  readonly reason: string;
+};
+
+export type ReindexEntityResult = {
+  readonly scannedRows: number;
+  readonly indexedRows: number;
+  readonly failures: readonly ReindexEntityFailure[];
+};
+
+export type ReindexEntityOptions = {
+  readonly batchSize?: number;
+  // Scan + build docs, write nothing.
+  readonly dryRun?: boolean;
+};
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+// Read-table state, forward-mapped from entity.fields (fieldName →
+// toSnakeCase(fieldName)). SELECT * + forward-map instead of building an
+// explicit column list: some field types (files/images) emit no column at
+// all, others (locatedTimestamp, money) emit companion columns under a
+// different name — an explicit alias list breaks on those. Missing columns
+// are just skipped, matching what a `.created` event payload would carry.
+function rowToState(
+  row: Record<string, unknown>,
+  fieldNames: readonly string[],
+): Record<string, unknown> {
+  const state: Record<string, unknown> = {};
+  for (const fieldName of fieldNames) {
+    const column = toSnakeCase(fieldName);
+    if (Object.hasOwn(row, column)) state[fieldName] = row[column];
+  }
+  return state;
+}
+
+export async function reindexEntity(
+  db: DbRunner,
+  registry: Registry,
+  searchAdapter: SearchAdapter,
+  entityName: string,
+  tenantId: TenantId,
+  options: ReindexEntityOptions = {},
+): Promise<ReindexEntityResult> {
+  const entity = registry.getEntity(entityName);
+  if (!entity) {
+    throw new Error(`reindexEntity: unknown entity "${entityName}"`);
+  }
+  const searchableFields = registry.getSearchableFields(entityName);
+  const extensions = registry.getSearchPayloadExtensions(entityName);
+  if (searchableFields.length === 0 && extensions.length === 0) {
+    throw new Error(
+      `reindexEntity: entity "${entityName}" has no searchable fields and no search-payload ` +
+        `extensions — nothing to index.`,
+    );
+  }
+
+  const batchSize = options.batchSize ?? 500;
+  const tableName = resolveTableName(entityName, entity, undefined);
+  const fieldNames = Object.keys(entity.fields);
+  // Soft-deleted rows already left the live index (the .deleted consumer
+  // calls searchAdapter.remove()) — resurrecting them here would make
+  // erased entities findable again.
+  const deletedFilter =
+    entity.softDelete === true ? `AND ${quoteIdent("is_deleted")} IS NOT TRUE` : "";
+
+  const result = { scannedRows: 0, indexedRows: 0, failures: [] as ReindexEntityFailure[] };
+
+  let offset = 0;
+  for (;;) {
+    // ponytail: LIMIT/OFFSET, not a keyset cursor — id can be uuid or
+    // serial depending on the entity, and a uniform cursor comparison
+    // across both types needs a text cast that breaks integer ordering.
+    // This is a one-time backfill over existing rows, not a live hot path;
+    // switch to keyset if it ever needs to run against a churning table.
+    const rows = await executeRawQuery<Record<string, unknown>>(
+      db,
+      `SELECT * FROM ${quoteIdent(tableName)}
+        WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter}
+        ORDER BY ${quoteIdent("id")} ASC
+        LIMIT $2 OFFSET $3`,
+      [tenantId, batchSize, offset],
+    );
+    if (rows.length === 0) break;
+
+    const docs: Array<{ entityId: string; doc: SearchDocument }> = [];
+    for (const row of rows) {
+      result.scannedRows++;
+      const entityId = String(row["id"]);
+      try {
+        const state = rowToState(row, fieldNames);
+        const doc = await buildSearchDocument(entityName, entityId, state, registry);
+        if (doc) docs.push({ entityId, doc });
+      } catch (e) {
+        result.failures.push({ entityId, reason: e instanceof Error ? e.message : String(e) });
+      }
+    }
+
+    if (!options.dryRun && docs.length > 0) {
+      if (searchAdapter.indexBatch) {
+        try {
+          await searchAdapter.indexBatch(
+            tenantId,
+            docs.map((d) => d.doc),
+          );
+          result.indexedRows += docs.length;
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          for (const { entityId } of docs) result.failures.push({ entityId, reason });
+        }
+      } else {
+        for (const { entityId, doc } of docs) {
+          try {
+            await searchAdapter.index(tenantId, doc);
+            result.indexedRows++;
+          } catch (e) {
+            result.failures.push({ entityId, reason: e instanceof Error ? e.message : String(e) });
+          }
+        }
+      }
+    } else if (options.dryRun) {
+      result.indexedRows += docs.length;
+    }
+
+    offset += rows.length;
+    if (rows.length < batchSize) break;
+  }
+
+  return result;
+}