@cosmicdrift/kumiko-framework 0.24.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.24.1",
+  "version": "0.25.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>",

package/src/bun-db/__tests__/extract-table-info.test.ts

@@ -11,7 +11,7 @@
 
 import { describe, expect, test } from "bun:test";
 import { buildEntityTable } from "../../db/table-builder";
-import { extractTableInfo } from "../query";
+import { extractTableInfo, resolveConflictColumns } from "../query";
 
 describe("extractTableInfo — EntityTableMeta discriminator is shadow-proof", () => {
   test("an entity field named `source` does not shadow the discriminator", () => {
@@ -49,3 +49,24 @@ describe("extractTableInfo — EntityTableMeta discriminator is shadow-proof", (
     expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
   });
 });
+
+describe("resolveConflictColumns — shadow-proof PK inference", () => {
+  test("an entity field named `columns` does not shadow the inferred primary key", () => {
+    const table = buildEntityTable("thing", {
+      fields: { columns: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    // No explicit conflictKeys → infer the real PK (`id`) from the symbol-based
+    // meta. Reading `table.columns` directly would yield the `columns` field
+    // handle (the bug this guards), not the PK list.
+    expect(resolveConflictColumns(table, info, undefined)).toEqual(["id"]);
+  });
+
+  test("explicit conflictKeys are mapped through columnOf (control)", () => {
+    const table = buildEntityTable("thing", {
+      fields: { slug: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    expect(resolveConflictColumns(table, info, ["slug"])).toEqual(["slug"]);
+  });
+});

package/src/bun-db/query.ts

@@ -50,6 +50,7 @@ function isEntityTableMeta(v: unknown): v is EntityTableMeta {
     typeof v === "object" &&
     typeof (v as EntityTableMeta).tableName === "string" &&
     Array.isArray((v as EntityTableMeta).columns) &&
+    Array.isArray((v as EntityTableMeta).indexes) &&
     ((v as EntityTableMeta).source === "managed" || (v as EntityTableMeta).source === "unmanaged")
   );
 }
@@ -356,7 +357,7 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
     ) {
       // Bun.SQL / some drivers return int4 as bigint or numeric string.
       // Drizzle coerced to number for numberField columns — match that.
-      const n = typeof value === "bigint" ? Number(value) : Number(value);
+      const n = Number(value);
       if (!Number.isNaN(n)) coerced = n;
     }
     const fieldName = info.fieldOf(key);
@@ -693,7 +694,9 @@ function insertEntries(info: TableInfo, values: Record<string, unknown>): Insert
     });
 }
 
-function resolveConflictColumns(
+// Exported for the shadow-proof regression test — `table.columns` would be the
+// drizzle handle (not the PK list) when an entity has a field named `columns`.
+export function resolveConflictColumns(
   table: TableLike,
   info: TableInfo,
   conflictKeys: readonly string[] | undefined,

package/src/db/__tests__/source-shadow-create.integration.test.ts

@@ -0,0 +1,54 @@
+// End-to-end regression for the EntityTableMeta discriminator shadow.
+//
+// An entity field literally named `source` overwrote the `source:
+// "managed"|"unmanaged"` discriminator on the table-meta. extractTableInfo
+// then failed its meta check, fell into the dead drizzle branch, and typed the
+// timestamptz base-columns as "timestamp with time zone" (getSQLType spelling).
+// prepareValue only serializes Temporal.Instant for "timestamptz", so a raw
+// Temporal reached postgres-js → "Cannot use valueOf" on every create.
+//
+// extract-table-info.test.ts pins the proximate cause (pgTypeOf stays
+// "timestamptz"). This proves the actual create-path no longer crashes — the
+// integration proof the unit test cannot give.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertOne, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField } from "../../engine";
+import { setupTestStack, type TestStack, unsafeCreateEntityTable } from "../../stack";
+
+const sourceEntity = createEntity({
+  table: "ssc_source",
+  fields: {
+    // `source` collides with the EntityTableMeta discriminator key.
+    source: createTextField({ required: true }),
+  },
+});
+const sourceTable = buildEntityTable("source-row", sourceEntity);
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, sourceEntity, "source-row");
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("entity with a `source` field — create-path is shadow-proof", () => {
+  test("insertOne serializes the timestamptz inserted_at — no Temporal valueOf crash", async () => {
+    // Passing a real Temporal.Instant exercises the timestamptz serializer
+    // path that the shadow used to bypass. Pre-fix this threw "Cannot use
+    // valueOf"; post-fix the row persists and round-trips as a Temporal.Instant.
+    await insertOne(stack.db, sourceTable, {
+      source: "import",
+      tenantId: "00000000-0000-4000-8000-000000000001",
+      insertedAt: Temporal.Instant.from("2026-01-15T12:00:00Z"),
+    });
+
+    const rows = await selectMany(stack.db, sourceTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["source"]).toBe("import");
+    expect(rows[0]?.["insertedAt"]).toBeInstanceOf(Temporal.Instant);
+  });
+});

package/src/db/__tests__/sql-inventory.test.ts

@@ -1,5 +1,11 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { formatReport, isRawSqlAllowed, joinPath, scanRepo } from "../sql-inventory";
+import {
+  formatReport,
+  isRawSqlAllowed,
+  joinPath,
+  scanRepo,
+  toBaselineJson,
+} from "../sql-inventory";
 
 const cleanups: string[] = [];
 
@@ -53,4 +59,23 @@ describe("sql-inventory", () => {
     expect(report.summary.byBucket.disallowed).toBeGreaterThanOrEqual(1);
     expect(formatReport(report)).toContain("sql inventory");
   });
+
+  test("toBaselineJson normalizes machine-specific root + scannedAt, keeps the rest", async () => {
+    const root = await tempRepo({
+      "packages/framework/src/handlers/bad.ts": `export async function y(db: unknown) {
+  return asRawClient(db).unsafe("DELETE FROM read_users");
+}`,
+    });
+
+    const report = await scanRepo(root);
+    expect(report.root).toBe(root);
+    expect(report.scannedAt).not.toBe("");
+
+    const parsed = JSON.parse(toBaselineJson(report));
+    expect(parsed.root).toBe(".");
+    expect(parsed.scannedAt).toBe("");
+    expect(parsed.root).not.toContain(root);
+    expect(parsed.summary.disallowed).toBe(report.summary.disallowed);
+    expect(parsed.hits).toHaveLength(report.hits.length);
+  });
 });

package/src/db/__tests__/table-builder-indexes.test.ts

@@ -147,6 +147,21 @@ describe("validateBoot — entity.indexes", () => {
     expect(() => validateBoot([feature])).toThrow(/redundant/);
   });
 
+  test("single-column UNIQUE auf tenantId ist erlaubt (1:1-Constraint)", () => {
+    // Der `&& !def.unique`-Branch in entity-handler.ts: ein UNIQUE-Index auf
+    // tenantId allein ist kein redundanter Read-Index, sondern ein
+    // 1:1-Constraint (genau ein Row pro Tenant). Nur die NON-unique-Variante
+    // oben ist redundant — beide Hälften der Bedingung sind damit gepinnt,
+    // sonst fliegt der Branch beim nächsten Revert/Refactor stumm raus.
+    const feature = defineFeature("widgetFeature", (r) => {
+      r.entity("widget", {
+        fields: { title: createTextField({}) },
+        indexes: [{ unique: true, columns: ["tenantId"] }],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
   test("composite mit tenantId ist OK (z.B. für unique über 3 Cols)", () => {
     const feature = defineFeature("widgetFeature", (r) => {
       r.entity("widget", {

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { testTenantId } from "../../stack";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+// Tenant-isolation: a caller-supplied `where.tenantId` must NEVER override the
+// enforced tenant scope. These tests drive the real query-builder against a
+// recording fake runner and assert on the emitted SQL + bound values — no
+// Postgres needed because the bug lives entirely in the WHERE-object merge.
+
+const entity = createEntity({
+  table: "merge_items",
+  fields: { name: createTextField({ required: true }) },
+});
+const table = buildEntityTable("mergeItem", entity);
+
+const own = testTenantId(1);
+const foreign = testTenantId(2);
+
+type Captured = { sql: string; values: readonly unknown[] };
+
+function recordingDb(captured: Captured[]) {
+  return {
+    unsafe: async (sql: string, values: readonly unknown[]) => {
+      captured.push({ sql, values });
+      return [] as unknown[];
+    },
+  };
+}
+
+describe("tenant-db WHERE merge — caller cannot override tenant scope", () => {
+  test("selectMany ignores a foreign where.tenantId and keeps the IN-scope filter", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { tenantId: foreign });
+
+    expect(captured).toHaveLength(1);
+    // The enforced scope is an IN over [own, SYSTEM_TENANT_ID]; the foreign id
+    // must not appear as a sole-equality predicate (the pre-fix bug).
+    expect(captured[0]?.sql).toMatch(/tenant_id" IN /i);
+    expect(captured[0]?.values).toContain(own);
+    expect(captured[0]?.values).not.toContain(foreign);
+  });
+
+  test("updateMany forces own tenantId even when where.tenantId is foreign", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.updateMany(table, { name: "x" }, { tenantId: foreign });
+
+    const update = captured.find((c) => /UPDATE/i.test(c.sql));
+    expect(update).toBeDefined();
+    expect(update?.values).toContain(own);
+    expect(update?.values).not.toContain(foreign);
+  });
+
+  test("deleteMany forces own tenantId even when where.tenantId is foreign", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.deleteMany(table, { tenantId: foreign });
+
+    const del = captured.find((c) => /DELETE/i.test(c.sql));
+    expect(del).toBeDefined();
+    expect(del?.values).toContain(own);
+    expect(del?.values).not.toContain(foreign);
+  });
+
+  test("a non-tenantId where predicate is still applied alongside the scope", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { name: "needle" });
+
+    expect(captured[0]?.sql).toMatch(/tenant_id" IN /i);
+    expect(captured[0]?.values).toContain("needle");
+    expect(captured[0]?.values).toContain(own);
+  });
+});

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

@@ -253,7 +253,7 @@ function fieldToColumnMeta(
   }
 }
 
-function resolveTableName(
+export function resolveTableName(
   entityName: string,
   entity: EntityDefinition,
   featureName: string | undefined,

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

@@ -107,14 +107,9 @@ export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   return BigInt(raw);
 }
 
-/** Head event id for lag metrics — same aggregate as selectEventsHighWaterMark. */
+/** Head event id for lag metrics — alias for selectEventsHighWaterMark. */
 export async function selectEventsHeadId(db: AnyDb): Promise<bigint> {
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT COALESCE(MAX(id), 0)::bigint AS head FROM kumiko_events`,
-  )) as ReadonlyArray<{ head?: bigint | string | null }>;
-  const raw = rows[0]?.head;
-  if (typeof raw === "bigint") return raw;
-  return BigInt(raw ?? 0);
+  return selectEventsHighWaterMark(db);
 }
 
 export async function selectNextEventIdAfter(db: AnyDb, afterId: bigint): Promise<bigint | null> {

package/src/db/sql-inventory.ts

@@ -176,6 +176,15 @@ export async function scanRepo(repoRoot: string): Promise<SqlInventoryReport> {
   };
 }
 
+// Serialize for the checked-in baseline. `root` (absolute scan path) and
+// `scannedAt` (run timestamp) are machine-/run-specific noise that churned the
+// baseline on every regen; --compare-baseline reads only summary.disallowed.
+// Pin them to stable placeholders so the committed file is reproducible.
+export function toBaselineJson(report: SqlInventoryReport): string {
+  const stable: SqlInventoryReport = { ...report, root: ".", scannedAt: "" };
+  return `${JSON.stringify(stable, null, 2)}\n`;
+}
+
 export function formatReport(report: SqlInventoryReport): string {
   const lines: string[] = [
     "--- sql inventory ---",

package/src/db/tenant-db.ts

@@ -133,15 +133,18 @@ export function createTenantDb(
 
   // Reads see own-tenant rows + reference data (tenantId === SYSTEM_TENANT_ID).
   // Writes never touch reference rows — those are system-mode only.
+  // The tenant filter is spread LAST so a caller-supplied `where.tenantId`
+  // cannot override the enforced scope — overriding it would be a
+  // tenant-isolation bypass.
   function readWhere(table: Table, where?: WhereObject): WhereObject | undefined {
     if (!hasTenantColumn(table) || mode === "system") return where;
     const tenantFilter: WhereObject = { tenantId: [tenantId, SYSTEM_TENANT_ID] };
-    return where ? { ...tenantFilter, ...where } : tenantFilter;
+    return where ? { ...where, ...tenantFilter } : tenantFilter;
   }
 
   function writeWhere(table: Table, where: WhereObject): WhereObject {
     if (!hasTenantColumn(table) || mode === "system") return where;
-    return { tenantId, ...where };
+    return { ...where, tenantId };
   }
 
   function insertValues(table: Table, data: Record<string, unknown>): Record<string, unknown> {

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

@@ -235,6 +235,20 @@ describe("boot-validator", () => {
     expect(() => validateBoot([ext, consumer])).not.toThrow();
   });
 
+  test("passes when a feature provides AND uses its own extension (self-extension)", () => {
+    // tier-engine pattern: a feature defines an extension-point and ships a
+    // default plugin for it, so providerFeature === feature.name. Requiring
+    // the feature to requires(self) would be circular — the validator must
+    // skip the requires-check for self-provided extensions. The cross-feature
+    // tests above only exercise providerFeature !== feature.name.
+    const self = defineFeature("tier-stub", (r) => {
+      r.extendsRegistrar("tenantTierResolver", { onRegister: () => {} });
+      r.entity("dummy", createEntity({ table: "Dummies", fields: {} }));
+      r.useExtension("tenantTierResolver", "dummy");
+    });
+    expect(() => validateBoot([self])).not.toThrow();
+  });
+
   // --- FILE_STORAGE_PROVIDER ---
 
   test("throws when file fields exist but FILE_STORAGE_PROVIDER not set", () => {
@@ -1372,6 +1386,20 @@ describe("boot-validator", () => {
         /redirect "ghost-screen" does not resolve to a registered screen/,
       );
     });
+
+    test("extension section ohne component → Throw (Parität zu entityEdit)", () => {
+      // synthesizeActionFormScreen reicht die layout 1:1 an RenderEdit weiter —
+      // eine Extension-Section ohne react/native-Marker rendert sonst stumm leer.
+      const section = { kind: "extension", title: "Custom", component: {} };
+      expect(() => validateBoot([makeFeature({ sections: [section] as never })])).toThrow(
+        /\(actionForm\) extension section "Custom" has no component/,
+      );
+    });
+
+    test("extension section mit react component → kein Throw", () => {
+      const section = { kind: "extension", title: "Custom", component: { react: "Panel" } };
+      expect(() => validateBoot([makeFeature({ sections: [section] as never })])).not.toThrow();
+    });
   });
 
   // --- configEdit-Screen ---
@@ -1474,6 +1502,57 @@ describe("boot-validator", () => {
         ]),
       ).toThrow(/Config-Key "shop:config:typo-here" ist in keiner Feature-Registry deklariert/);
     });
+
+    test("extension section ohne component → Throw (Parität zu entityEdit)", () => {
+      // synthesizeConfigEditScreen reicht die layout 1:1 an RenderEdit weiter —
+      // eine Extension-Section ohne react/native-Marker rendert sonst stumm leer.
+      const section = { kind: "extension", title: "Custom", component: {} };
+      expect(() => validateBoot([makeFeature({ sections: [section] as never })])).toThrow(
+        /\(configEdit\) extension section "Custom" has no component/,
+      );
+    });
+
+    test("extension section mit react component → kein Throw", () => {
+      const section = { kind: "extension", title: "Custom", component: { react: "Panel" } };
+      expect(() => validateBoot([makeFeature({ sections: [section] as never })])).not.toThrow();
+    });
+  });
+
+  // --- entityEdit extension section ---
+  // Eine extension-Section delegiert das Rendering an eine feature-provided
+  // PlatformComponent (custom-fields-Panel etc.), die client-seitig per Name
+  // aufgelöst wird. Ohne react/native-Marker bliebe der Slot zur Laufzeit leer
+  // — Boot-Fail statt stummem Loch. Field-Sections bleiben davon unberührt.
+  describe("entityEdit extension section", () => {
+    function makeFeature(component: unknown) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: [
+              { kind: "extension", title: "Custom Fields", component: component as never },
+            ],
+          },
+        });
+      });
+    }
+
+    test("extension section ohne react/native component → Throw", () => {
+      expect(() => validateBoot([makeFeature({})])).toThrow(
+        /extension section "Custom Fields" has no component — declare a react\/native component marker/,
+      );
+    });
+
+    test("extension section mit react component → kein Throw", () => {
+      expect(() => validateBoot([makeFeature({ react: "CustomFieldsPanel" })])).not.toThrow();
+    });
+
+    test("extension section mit native component → kein Throw", () => {
+      expect(() => validateBoot([makeFeature({ native: "CustomFieldsPanel" })])).not.toThrow();
+    });
   });
 
   // --- Tier 2.7e-3: ReferenceFieldDef ---

package/src/engine/__tests__/post-query-hook.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, defineFeature } from "../index";
-import type { PostQueryHookFn } from "../types";
+import type { AppContext, PostQueryHookFn } from "../types";
+
+// The hooks under test never read context (they only transform rows), so a
+// stub at the cast-boundary is sufficient — no real db/redis/registry needed.
+const stubContext = {} as unknown as AppContext;
 
 // postQuery-Hook (F1) — feuert nach Query-Handler-Execute, vor Field-Access-
 // Read-Filter. Zwei Registrierungs-Pfade:
@@ -112,11 +116,7 @@ describe("Hook function semantics", () => {
     const hooks = registry.getEntityPostQueryHooks("thing");
     const inputRows: ReadonlyArray<Record<string, unknown>> = [{ id: "1" }, { id: "2" }];
     // Context shape is { user, db, ... } in real runtime; unit-tests stub.
-    const result = await hooks[0]?.(
-      { entityName: "thing", rows: inputRows },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      {} as never,
-    );
+    const result = await hooks[0]?.({ entityName: "thing", rows: inputRows }, stubContext);
     expect(result?.rows).toEqual([
       { id: "1", enriched: true },
       { id: "2", enriched: true },

package/src/engine/__tests__/registry.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { createRegistry } from "../registry";
+import type { FeatureDefinition } from "../types/feature";
+
+// Hand-built FeatureDefinition that bypasses defineFeature() — the latter
+// initializes every slot (entities, entityHooks, …) to an empty map. A
+// FeatureDefinition assembled off that path (cast at a system boundary) can
+// leave slots `undefined`, which the type forbids but createRegistry's
+// entity-iteration paths must survive: `Object.entries/values(undefined)`
+// throws. The double-cast is the deliberate type-violation that reproduces it.
+function bareFeature(overrides: Record<string, unknown> = {}): FeatureDefinition {
+  return {
+    name: "probe",
+    requires: [],
+    optionalRequires: [],
+    ...overrides,
+  } as unknown as FeatureDefinition;
+}
+
+describe("createRegistry slot robustness", () => {
+  // Regression for the hardening PRs (#95/#98/#210): the entity- and
+  // hook-iterating paths in createRegistry must not assume the optional
+  // `entities` / `entityHooks` slots are present. defineFeature masks this in
+  // every test that goes through the normal author API, so the gap only
+  // surfaced when a partial feature reached the boot path.
+
+  test("tolerates a hand-built feature with entities + entityHooks omitted", () => {
+    // Exercises the entity-iteration paths (allEntities loop + hasFieldAccessRules)
+    // — both crash on `Object.{keys,values}(undefined)` without the `?? {}` guard.
+    expect(() => createRegistry([bareFeature()])).not.toThrow();
+  });
+
+  test("tolerates entities: undefined (Object.keys/values guard)", () => {
+    expect(() => createRegistry([bareFeature({ entities: undefined })])).not.toThrow();
+  });
+
+  test("tolerates entityHooks with every slot undefined", () => {
+    expect(() =>
+      createRegistry([
+        bareFeature({
+          entities: {},
+          entityHooks: {
+            postSave: undefined,
+            preDelete: undefined,
+            postDelete: undefined,
+            postQuery: undefined,
+          },
+        }),
+      ]),
+    ).not.toThrow();
+  });
+
+  test("tolerates entityHooks map itself undefined", () => {
+    expect(() =>
+      createRegistry([bareFeature({ entities: {}, entityHooks: undefined })]),
+    ).not.toThrow();
+  });
+});

package/src/engine/__tests__/search-payload-extension.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, test } from "bun:test";
-import { createEntity, createRegistry, defineFeature } from "../index";
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import { buildSearchDocument } from "../../pipeline/system-hooks";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../index";
 import type { SearchPayloadContributorFn } from "../types";
 
 // F3 — Search-Payload-Extension registers per-entity contributors that
@@ -115,6 +116,36 @@ describe("effectiveFeatures filtering", () => {
   });
 });
 
+describe("buildSearchDocument — contributor precedence (base fields win)", () => {
+  const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  afterEach(() => warnSpy.mockClear());
+
+  function registryWith(contributor: SearchPayloadContributorFn) {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity(
+        "thing",
+        createEntity({ table: "things", fields: { title: createTextField({ searchable: true }) } }),
+      );
+      r.searchPayloadExtension(thing, contributor);
+    });
+    return createRegistry([feature]);
+  }
+
+  test("a contributor cannot overwrite an indexed Stammfield value", async () => {
+    const registry = registryWith(() => ({ title: "from-contributor" }));
+    const doc = await buildSearchDocument("thing", "t1", { title: "real-value" }, registry);
+    expect(doc?.fields["title"]).toBe("real-value");
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  test("a non-colliding contributor key is still merged in", async () => {
+    const registry = registryWith(() => ({ flatTags: "a,b" }));
+    const doc = await buildSearchDocument("thing", "t1", { title: "real-value" }, registry);
+    expect(doc?.fields).toMatchObject({ title: "real-value", flatTags: "a,b" });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
+
 describe("Boot-Validation", () => {
   test("rejects searchPayloadExtension on unknown entity-name (sibling to entity-hooks)", () => {
     expect(() =>
@@ -131,6 +162,21 @@ describe("Boot-Validation", () => {
         r.searchPayloadExtension("propery", noop);
       });
       createRegistry([feature]);
-    }).toThrow(/searchPayloadExtension.*"propery".*no entity/);
+    }).toThrow(/searchPayloadExtension extension targets entity "propery" but no entity/);
+  });
+
+  test("error message calls a searchPayloadExtension an 'extension', not a 'hook'", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension("propery", noop);
+    });
+    let message = "";
+    try {
+      createRegistry([feature]);
+    } catch (err) {
+      message = err instanceof Error ? err.message : String(err);
+    }
+    expect(message).toContain("searchPayloadExtension extension");
+    expect(message).not.toContain("searchPayloadExtension hook");
   });
 });

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -3,8 +3,9 @@
 // drizzle migrate-runner). See define-feature.ts / DX-4.
 
 import { describe, expect, test } from "bun:test";
-import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { defineUnmanagedTable, resolveTableName } from "../../db/entity-table-meta";
 import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../index";
 import { createRegistry } from "../registry";
 
 const probeMeta = defineUnmanagedTable({
@@ -95,4 +96,32 @@ describe("createRegistry — unmanagedTable aggregation", () => {
     });
     expect(() => createRegistry([featA, featB])).not.toThrow();
   });
+
+  test("rejects an unmanaged-table that collides with an entity's physical name", () => {
+    const widget = createEntity({ fields: { name: createTextField() } });
+    // resolveTableName mirrors the migrate-runner — pin the exact physical name.
+    const physical = resolveTableName("widget", widget, "shop");
+    const clashing = defineUnmanagedTable({
+      tableName: physical,
+      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+    });
+    const entityFeature = defineFeature("shop", (r) => {
+      r.entity("widget", widget);
+    });
+    const tableFeature = defineFeature("other", (r) => {
+      r.unmanagedTable(clashing, { reason: "clash" });
+    });
+
+    // Entity registered first, then the colliding unmanaged table.
+    expect(() => createRegistry([entityFeature, tableFeature])).toThrow(
+      new RegExp(
+        `Unmanaged-table "${physical}".*collides with the physical table of entity "widget"`,
+      ),
+    );
+
+    // Order-independent: unmanaged table registered first, then the entity.
+    expect(() => createRegistry([tableFeature, entityFeature])).toThrow(
+      new RegExp(`Entity "widget".*collides with r.unmanagedTable\\("${physical}"\\)`),
+    );
+  });
 });

package/src/engine/boot-validator/api-ext.ts

@@ -67,11 +67,7 @@ export function validateExtensionUsages(
       );
     }
 
-    // Self-extension (feature provides AND consumes the same extension)
-    // doesn't need requires(self) — that would be a circular declaration.
-    // tier-engine is the canonical case: defines + uses tenantTierResolver
-    // because it ships a default tier-resolver-plugin alongside the
-    // extension-point.
+    // self-extension is legitimate: requires(self) would be circular.
     if (providerFeature === feature.name) {
       continue;
     }

package/src/engine/boot-validator/screens-nav.ts

@@ -62,7 +62,15 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
-        if (isExtensionEditSection(section)) continue;
+        if (isExtensionEditSection(section)) {
+          if (section.component.react === undefined && section.component.native === undefined) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (configEdit) extension section ` +
+                `"${section.title}" has no component — declare a react/native component marker.`,
+            );
+          }
+          continue;
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -161,7 +169,15 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
-        if (isExtensionEditSection(section)) continue;
+        if (isExtensionEditSection(section)) {
+          if (section.component.react === undefined && section.component.native === undefined) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (actionForm) extension section ` +
+                `"${section.title}" has no component — declare a react/native component marker.`,
+            );
+          }
+          continue;
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +

package/src/engine/registry.ts

@@ -1,4 +1,5 @@
 import { applyEntityEvent } from "../db/apply-entity-event";
+import { resolveTableName } from "../db/entity-table-meta";
 import { buildEntityTable } from "../db/table-builder";
 import { buildMetricName, validateMetricName } from "../observability";
 import { type QnType, qualifyEntityName } from "./qualified-name";
@@ -174,6 +175,13 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // Cousin of rawTables: same uniqueness-by-tableName invariant, different
   // storage shape (post-drizzle migrate-runner consumes EntityTableMeta).
   const unmanagedTableMap = new Map<string, UnmanagedTableDef>();
+  // Final physical table names (entity-derived + unmanaged) → owner. Catches
+  // a collision between an r.unmanagedTable() tableName and an r.entity()
+  // physical name at boot instead of as a duplicate CREATE TABLE in migrate.
+  const physicalTableOwners = new Map<
+    string,
+    { kind: "entity" | "unmanaged"; owner: string; featureName: string }
+  >();
   // Auth-claims hooks — tagged with featureName so the login resolver can
   // auto-prefix each hook's returned keys with "<feature>:".
   const authClaimsHooks: AuthClaimsHookDef[] = [];
@@ -321,6 +329,16 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
         throw new Error(`Duplicate entity: "${name}" (registered by multiple features)`);
       }
       entityMap.set(name, entity);
+      const physical = resolveTableName(name, entity, feature.name);
+      const clash = physicalTableOwners.get(physical);
+      if (clash?.kind === "unmanaged") {
+        throw new Error(
+          `Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
+            `collides with r.unmanagedTable("${physical}") (feature "${clash.featureName}"). ` +
+            `Pick a different tableName — both would emit CREATE TABLE "${physical}".`,
+        );
+      }
+      physicalTableOwners.set(physical, { kind: "entity", owner: name, featureName: feature.name });
     }
 
     // Relations: entityName (not prefixed)
@@ -559,6 +577,19 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
             `"${feature.name}". Pick a feature-prefixed tableName to disambiguate.`,
         );
       }
+      const physicalClash = physicalTableOwners.get(umName);
+      if (physicalClash?.kind === "entity") {
+        throw new Error(
+          `Unmanaged-table "${umName}" (feature "${feature.name}") collides with the physical ` +
+            `table of entity "${physicalClash.owner}" (feature "${physicalClash.featureName}"). ` +
+            `Pick a different tableName — both would emit CREATE TABLE "${umName}".`,
+        );
+      }
+      physicalTableOwners.set(umName, {
+        kind: "unmanaged",
+        owner: umName,
+        featureName: feature.name,
+      });
       unmanagedTableMap.set(umName, { ...umDef, featureName: feature.name });
     }
 
@@ -870,7 +901,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     if (!hasFieldAccessRules(feature)) continue;
 
     // Write handlers: ALL must be entity-mapped (security-critical, writes need field-access checks)
-    for (const handlerName of Object.keys(feature.writeHandlers)) {
+    for (const handlerName of Object.keys(feature.writeHandlers ?? {})) {
       const qualified = qualify(feature.name, "write", handlerName);
       if (!handlerEntityMap.has(qualified)) {
         throw new Error(
@@ -882,7 +913,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
 
     // Query handlers: only those with a dash must resolve (typo protection).
     // No dash = standalone query (dashboard, stats) — intentionally not entity-bound.
-    for (const handlerName of Object.keys(feature.queryHandlers)) {
+    for (const handlerName of Object.keys(feature.queryHandlers ?? {})) {
       if (!handlerName.includes(":")) continue;
       const qualified = qualify(feature.name, "query", handlerName);
       if (!handlerEntityMap.has(qualified)) {
@@ -1131,23 +1162,23 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // postQuery-special.
   const allEntities = new Set<string>();
   for (const feature of features) {
-    for (const entityName of Object.keys(feature.entities)) {
+    for (const entityName of Object.keys(feature.entities ?? {})) {
       allEntities.add(entityName);
     }
   }
   const entityHookMaps = [
-    { map: entityPostSaveHooks, phase: "postSave (entityHook)" },
-    { map: entityPreDeleteHooks, phase: "preDelete (entityHook)" },
-    { map: entityPostDeleteHooks, phase: "postDelete (entityHook)" },
-    { map: entityPostQueryHooks, phase: "postQuery (entityHook)" },
-    { map: searchPayloadExtensions, phase: "searchPayloadExtension" },
+    { map: entityPostSaveHooks, phase: "postSave (entityHook)", kind: "hook" },
+    { map: entityPreDeleteHooks, phase: "preDelete (entityHook)", kind: "hook" },
+    { map: entityPostDeleteHooks, phase: "postDelete (entityHook)", kind: "hook" },
+    { map: entityPostQueryHooks, phase: "postQuery (entityHook)", kind: "hook" },
+    { map: searchPayloadExtensions, phase: "searchPayloadExtension", kind: "extension" },
   ] as const;
-  for (const { map, phase } of entityHookMaps) {
+  for (const { map, phase, kind } of entityHookMaps) {
     for (const entityName of map.keys()) {
       if (!allEntities.has(entityName)) {
         throw new Error(
-          `${phase} hook targets entity "${entityName}" but no entity with that name exists. ` +
-            `Check for typos — the hook will never fire.`,
+          `${phase} ${kind} targets entity "${entityName}" but no entity with that name exists. ` +
+            `Check for typos — the ${kind} will never fire.`,
         );
       }
     }
@@ -1492,7 +1523,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
 
 /** Returns true if any entity in the feature has field-level access rules (read or write). */
 function hasFieldAccessRules(feature: FeatureDefinition): boolean {
-  for (const entity of Object.values(feature.entities)) {
+  for (const entity of Object.values(feature.entities ?? {})) {
     for (const field of Object.values(entity.fields)) {
       if (field.access?.read?.length || field.access?.write?.length) {
         return true;

package/src/engine/types/fields.ts

@@ -484,7 +484,8 @@ export type TransitionMap = Readonly<Record<string, readonly string[]>>;
  *  vermeidet Migration-Churn beim Refactor.
  *
  *  Single-column indices über `tenantId` sind redundant (buildEntityTable
- *  legt die immer automatisch an); die Boot-Validation warnt. */
+ *  legt die immer automatisch an); die Boot-Validation warnt (außer
+ *  `{ unique: true }` — semantische 1:1-Constraint, kein Performance-Hint). */
 export type EntityIndexDef = {
   readonly columns: readonly [string, ...string[]];
   readonly unique?: boolean;

package/src/engine/types/handlers.ts

@@ -223,7 +223,7 @@ type SharedContextFields = {
   // set handler needs to encrypt on write, the resolver needs to decrypt
   // on read, and both reach for the same provider. Wired via extraContext.
   readonly configEncryption?: import("../../db").EncryptionProvider;
-  // Rate-limit resolver. Wired by the framework when the `rateLimiting`
+  // Rate-limit resolver. Wired by the framework when the `rate-limiting`
   // feature is loaded — pipeline reads handler.rateLimit and calls
   // .enforce() on this resolver before access-check. Absent when the
   // app didn't load the feature: handlers with rateLimit set are

package/src/engine/types/hooks.ts

@@ -84,7 +84,10 @@ export type PreQueryHookFn = (
 // on added fields (field-access-filter only knows entity's stammfields).
 export type PostQueryHookFn = (
   result: {
-    readonly entityName: string;
+    // undefined for standalone queries (no-colon handler names like
+    // "ns:dashboard") — those have no backing entity, but handler-keyed
+    // postQuery hooks still fire on them.
+    readonly entityName: string | undefined;
     readonly rows: ReadonlyArray<Record<string, unknown>>;
   },
   context: AppContext,

package/src/engine/validate-projection-allowlist.ts

@@ -55,13 +55,23 @@ function* walkAllSteps(steps: readonly StepInstance[]): Generator<StepInstance,
   }
 }
 
-// @cast-boundary drizzle-bridge — reads table name from drizzle Symbol
-// without importing drizzle-orm (bun-db pattern, see bun-db/query.ts).
+// @cast-boundary drizzle-bridge — reads table name from a Symbol without
+// importing drizzle-orm (bun-db pattern, see bun-db/query.ts).
 const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
+// table()/buildEntityTable spread column handles as enumerable props, so an
+// entity field named `tableName`/`source` would shadow the matching meta key —
+// the canonical meta under this symbol is the only collision-safe source.
+const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
 function resolveTableNameFromStep(table: unknown): string {
   if (typeof table === "object" && table !== null) {
-    // EntityTableMeta discriminator
+    // Canonical meta under the unshadowable symbol — preferred path.
+    const meta = (table as Record<symbol, unknown>)[KUMIKO_META_SYMBOL];
+    if (meta !== null && typeof meta === "object") {
+      const metaName = (meta as Record<string, unknown>)["tableName"];
+      if (typeof metaName === "string") return metaName;
+    }
+    // Plain meta (buildEntityTableMeta / defineUnmanagedTable — no handle-spread).
     if (
       "source" in table &&
       "tableName" in table &&

package/src/errors/__tests__/classes.test.ts

@@ -241,6 +241,11 @@ describe("NotFoundError", () => {
     const err = new NotFoundError("billing-period", 7);
     expect((err.details as { reason: string }).reason).toBe("billing_period_not_found");
   });
+
+  test("PascalCase entity name does not leak a leading underscore into the reason", () => {
+    const err = new NotFoundError("Invoice", 7);
+    expect((err.details as { reason: string }).reason).toBe("invoice_not_found");
+  });
 });
 
 describe("ConflictError + VersionConflictError", () => {

package/src/errors/classes.ts

@@ -83,8 +83,10 @@ export class NotFoundError extends KumikoError {
     const idStr = id !== undefined ? String(id) : undefined;
     // The reason string follows `<snake_entity>_not_found` — keeps a stable,
     // client-friendly tag that survives wire serialization even if the entity
-    // name is later renamed for display purposes.
-    const reason = `${toSnakeCase(entity)}_not_found`;
+    // name is later renamed for display purposes. Strip the leading underscore
+    // toSnakeCase emits for a PascalCase name ("Invoice" → "_invoice") so the
+    // wire tag stays "invoice_not_found", not "_invoice_not_found".
+    const reason = `${toSnakeCase(entity).replace(/^_/, "")}_not_found`;
     const details: NotFoundDetails & { reason: string } = { reason, entity, id: idStr };
     super({
       message: idStr !== undefined ? `${entity} ${idStr} not found` : `${entity} not found`,

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

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import type { ColumnMeta } from "../../db/entity-table-meta";
+import { fileRefsTable } from "../file-ref-table";
+
+// `fileRefsTable` is the live buildEntityTable() output the app boots with.
+// Its runtime shape is a SchemaTable (EntityTableMeta & drizzle table), so the
+// EntityTableMeta `columns` carry the resolved NOT NULL / DEFAULT per column —
+// the drizzle-facing static type (EntityTable<E>) hides them, hence the cast.
+// Importing fileRefEntity directly here would hit the engine↔file-ref-table
+// init cycle (biome sorts it before file-ref-table); going through the built
+// table sidesteps it and tests the exact object production uses.
+const columns = (fileRefsTable as unknown as { readonly columns: readonly ColumnMeta[] }).columns;
+const col = (name: string): readonly ColumnMeta[] => columns.filter((c) => c.name === name);
+
+describe("fileRefEntity base-column drift", () => {
+  // Regression: an earlier revision declared `insertedAt`/`insertedById` as
+  // entity fields. The field-column then OVERRODE the framework base column in
+  // the {...base, ...field} last-wins merge (entity-table-meta.ts), dropping
+  // its NOT NULL DEFAULT now() and making inserted_at silently nullable — a
+  // production INSERT could then leave it null. Re-adding either field shadows
+  // the base column again and turns these red.
+  test("inserted_at stays NOT NULL DEFAULT now() (base column, not field-shadowed)", () => {
+    const insertedAt = col("inserted_at");
+    expect(insertedAt).toHaveLength(1); // exactly one — not duplicated by a redeclared field
+    expect(insertedAt[0]?.notNull).toBe(true);
+    expect(insertedAt[0]?.defaultSql).toBe("now()");
+  });
+
+  test("inserted_by_id stays framework-managed nullable (not redeclared as a required field)", () => {
+    const insertedById = col("inserted_by_id");
+    expect(insertedById).toHaveLength(1);
+    expect(insertedById[0]?.notNull).toBe(false);
+  });
+});

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -159,6 +159,59 @@ describe("dispatcher.query", () => {
   });
 });
 
+// --- postQuery hooks on standalone (entity-less) queries ---
+
+describe("dispatcher.query postQuery hooks", () => {
+  test("handler-keyed postQuery hook fires on a standalone (no-colon) query", async () => {
+    // Standalone queries (name without colon, e.g. "dashboard") map to no
+    // entity. Handler-keyed postQuery hooks must still fire — gating the hook
+    // pass on entity-existence makes such a hook register silently + never run.
+    const feature = defineFeature("dash", (r) => {
+      r.queryHandler("dashboard", z.object({}), async () => ({ count: 1 }), {
+        access: { openToAll: true },
+      });
+      r.hook("postQuery", "dashboard", async ({ entityName, rows }) => {
+        expect(entityName).toBeUndefined();
+        return { rows: rows.map((row) => ({ ...row, enriched: true })) };
+      });
+    });
+
+    const dispatcher = createDispatcher(createRegistry([feature]), {});
+    const result = await dispatcher.query("dash:query:dashboard", {}, createTestUser());
+    expect(result).toEqual({ count: 1, enriched: true });
+  });
+
+  test("postQuery hook does not run for a result with rows:null (not an array)", async () => {
+    // `{ rows: null }` is a legitimate 'nothing found' shape — it must take the
+    // single-object branch, not the rows-list branch (which would crash on
+    // [...null]). The hook here returns the row unchanged so the shape survives.
+    const feature = defineFeature("nullrows", (r) => {
+      r.queryHandler("dashboard", z.object({}), async () => ({ rows: null, nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postQuery", "dashboard", async ({ rows }) => ({ rows }));
+    });
+
+    const dispatcher = createDispatcher(createRegistry([feature]), {});
+    const result = await dispatcher.query("nullrows:query:dashboard", {}, createTestUser());
+    expect(result).toEqual({ rows: null, nextCursor: null });
+  });
+
+  test("single-object postQuery hook returning ≠1 row throws", async () => {
+    const feature = defineFeature("multi", (r) => {
+      r.queryHandler("dashboard", z.object({}), async () => ({ count: 1 }), {
+        access: { openToAll: true },
+      });
+      r.hook("postQuery", "dashboard", async ({ rows }) => ({ rows: [...rows, ...rows] }));
+    });
+
+    const dispatcher = createDispatcher(createRegistry([feature]), {});
+    await expect(dispatcher.query("multi:query:dashboard", {}, createTestUser())).rejects.toThrow(
+      /must return exactly one row, got 2/,
+    );
+  });
+});
+
 // --- Dispatch: Command (fire-and-forget) ---
 
 describe("dispatcher.command", () => {

package/src/pipeline/dispatcher.ts

@@ -686,7 +686,7 @@ export function createDispatcher(
     if (!rateLimit) return;
     if (!context.rateLimit) {
       throw new InternalError({
-        message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rateLimiting feature or remove the option.`,
+        message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
       });
     }
     const reqCtx = requestContext.get();
@@ -776,66 +776,66 @@ export function createDispatcher(
     //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
     //      — feuern für ALLE query-handlers des entity
     const entityName = registry.getHandlerEntity(type);
-    if (entityName) {
-      const handlerHooks = registry.getPostQueryHooks(type);
-      const entityHooks = registry.getEntityPostQueryHooks(entityName);
-      const postQueryHooks = [...handlerHooks, ...entityHooks];
-      if (postQueryHooks.length > 0 && result && typeof result === "object") {
-        if (Array.isArray(result)) {
-          let rows = result as Record<string, unknown>[]; // @cast-boundary engine-payload
-          for (const hook of postQueryHooks) {
-            const out = await hook({ entityName, rows }, handlerContext);
-            rows = [...out.rows];
-          }
-          result = rows;
-        } else if ("rows" in result) {
-          // @cast-boundary engine-payload
-          const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null };
-          let rows = r.rows;
-          for (const hook of postQueryHooks) {
-            const out = await hook({ entityName, rows }, handlerContext);
-            rows = [...out.rows];
-          }
-          result = { ...r, rows };
-        } else {
-          let rows: Record<string, unknown>[] = [result as Record<string, unknown>]; // @cast-boundary engine-payload
-          for (const hook of postQueryHooks) {
-            const out = await hook({ entityName, rows }, handlerContext);
-            rows = [...out.rows];
-          }
-          // A single-object result carries exactly one row through the hook
-          // pipeline. Returning 0 rows (effect lost) or ≥2 rows (extras
-          // dropped) cannot be represented in the single-object response —
-          // surface it instead of silently falling back / truncating.
-          const [only, ...extra] = rows;
-          if (only === undefined || extra.length > 0) {
-            throw new Error(
-              `postQuery hook on single-object result for "${type}" must return exactly one row, got ${rows.length}`,
-            );
-          }
-          result = only;
+
+    // Handler-keyed postQuery hooks fire for any query (incl. entity-less
+    // standalone queries like "ns:dashboard"). Entity-keyed hooks only apply
+    // when the handler maps to an entity — so this block must NOT be gated on
+    // entityName, or hooks on standalone queries register silently and never fire.
+    const handlerHooks = registry.getPostQueryHooks(type);
+    const entityHooks = entityName ? registry.getEntityPostQueryHooks(entityName) : [];
+    const postQueryHooks = [...handlerHooks, ...entityHooks];
+    if (postQueryHooks.length > 0 && result && typeof result === "object") {
+      if (Array.isArray(result)) {
+        let rows = result as Record<string, unknown>[]; // @cast-boundary engine-payload
+        for (const hook of postQueryHooks) {
+          const out = await hook({ entityName, rows }, handlerContext);
+          rows = [...out.rows];
+        }
+        result = rows;
+      } else if (Array.isArray((result as { rows?: unknown }).rows)) {
+        // @cast-boundary engine-payload
+        const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null };
+        let rows = r.rows;
+        for (const hook of postQueryHooks) {
+          const out = await hook({ entityName, rows }, handlerContext);
+          rows = [...out.rows];
         }
+        result = { ...r, rows };
+      } else {
+        let rows: Record<string, unknown>[] = [result as Record<string, unknown>]; // @cast-boundary engine-payload
+        for (const hook of postQueryHooks) {
+          const out = await hook({ entityName, rows }, handlerContext);
+          rows = [...out.rows];
+        }
+        // A single-object result carries exactly one row through the hook
+        // pipeline. Returning 0 rows (effect lost) or ≥2 rows (extras
+        // dropped) cannot be represented in the single-object response —
+        // surface it instead of silently falling back / truncating.
+        if (rows.length !== 1) {
+          throw new Error(
+            `postQuery hook on single-object result for "${type}" must return exactly one row, got ${rows.length}`,
+          );
+        }
+        result = rows[0];
       }
+    }
 
-      // Field-level read filter
-      const entity = registry.getEntity(entityName);
-      if (entity && result && typeof result === "object") {
-        if (Array.isArray(result)) {
-          result = result.map((row: Record<string, unknown>) =>
-            filterReadFields(entity, row, user),
-          );
+    // Field-level read filter — only applies to entity-bound results.
+    const entity = entityName ? registry.getEntity(entityName) : undefined;
+    if (entity && result && typeof result === "object") {
+      if (Array.isArray(result)) {
+        result = result.map((row: Record<string, unknown>) => filterReadFields(entity, row, user));
+      } else {
+        const resultAsDbRow = result as DbRow; // @cast-boundary engine-payload
+        if (Array.isArray((resultAsDbRow as { rows?: unknown }).rows)) {
+          // generic handler-result shape narrow
+          const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null }; // @cast-boundary engine-payload
+          result = {
+            ...r,
+            rows: r.rows.map((row) => filterReadFields(entity, row, user)),
+          };
         } else {
-          const resultAsDbRow = result as DbRow; // @cast-boundary engine-payload
-          if ("rows" in resultAsDbRow) {
-            // generic handler-result shape narrow
-            const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null }; // @cast-boundary engine-payload
-            result = {
-              ...r,
-              rows: r.rows.map((row) => filterReadFields(entity, row, user)),
-            };
-          } else {
-            result = filterReadFields(entity, result as DbRow, user); // @cast-boundary engine-payload
-          }
+          result = filterReadFields(entity, result as DbRow, user); // @cast-boundary engine-payload
         }
       }
     }

package/src/pipeline/system-hooks.ts

@@ -98,7 +98,7 @@ function reconstructStateForSearch(
 // Build a SearchDocument from raw field-state. Parallel to the old
 // buildSearchDocument that took a SaveContext — same selector logic, just
 // a different input shape.
-async function buildSearchDocument(
+export async function buildSearchDocument(
   entityName: string,
   entityId: EntityId,
   state: Record<string, unknown>,
@@ -143,12 +143,24 @@ async function buildSearchDocument(
   // F3 — Search-Payload-Extensions: contributors merge flat fields into the
   // search-doc (customFields-bundle / tags / computed-counts / etc.).
   // Sequential await — extensions are expected sync or sub-millisecond async;
-  // sequential keeps the path simple and deterministic. If parallel ever
-  // matters, switch to Promise.all but bind contributor-output-precedence
-  // (last-wins vs. merge-conflict) explicitly.
+  // sequential keeps the path simple and deterministic.
+  //
+  // Precedence is base-fields-win: a contributor key that collides with a
+  // searchable Stammfield is dropped (not silently merged over the real value)
+  // and warned. A jsonb custom-field that happens to share a Stammfield name
+  // must not shadow the indexed Stammfield.
   for (const contribute of extensions) {
     const contributed = await contribute({ entityName, entityId, state });
-    Object.assign(fields, contributed);
+    for (const [key, value] of Object.entries(contributed)) {
+      if (Object.hasOwn(fields, key)) {
+        console.warn(
+          `[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
+            `Stammfield "${key}" — keeping the base field. Rename the contributor key.`,
+        );
+        continue;
+      }
+      fields[key] = value;
+    }
   }
 
   return {

package/src/stack/table-helpers.ts

@@ -60,8 +60,8 @@ function isMetaShape(v: unknown): v is EntityTableMeta {
     v !== null &&
     typeof (v as EntityTableMeta).tableName === "string" &&
     Array.isArray((v as EntityTableMeta).columns) &&
-    "indexes" in v &&
-    "source" in v
+    Array.isArray((v as EntityTableMeta).indexes) &&
+    ((v as EntityTableMeta).source === "managed" || (v as EntityTableMeta).source === "unmanaged")
   );
 }
 

package/src/stack/test-stack.ts

@@ -171,8 +171,8 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // everything registered via r.projection() — keeps tests from having to
   // know which projections a feature happens to declare. Two projections
   // backed by the same physical table (e.g. an alternative apply-shape for
-  // the same read-model in a test feature) are deduped by Drizzle-table
-  // reference so drizzle-kit doesn't emit duplicate CREATE TABLE statements.
+  // the same read-model in a test feature) are deduped by table reference so
+  // we emit only one CREATE TABLE per physical table.
   const projectionTables: Record<string, unknown> = {};
   const seenTables = new Set<unknown>();
   for (const feature of options.features) {
@@ -205,8 +205,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // unsafePushTables emits raw CREATE TABLE — fine for ephemeral test DBs but
     // collides on re-boot against a persistent DB whose projection tables
     // were created during a previous run. Filter out the ones that already
-    // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
-    // them again.
+    // exist so the re-boot doesn't fail on duplicate CREATE TABLE.
     const { tableExists } = await import("../db/schema-inspection");
     const missing: Record<string, unknown> = {};
     for (const [key, tbl] of Object.entries(projectionTables)) {

package/src/errors/__tests__/field-issue-compat.test.ts

@@ -1,16 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { FieldIssue as FrameworkFieldIssue } from "@cosmicdrift/kumiko-framework/errors";
-import type { FieldIssue as HeadlessFieldIssue } from "@cosmicdrift/kumiko-headless";
-
-describe("FieldIssue cross-package contract", () => {
-  test("framework and headless FieldIssue shapes are assignable", () => {
-    const frameworkIssue: FrameworkFieldIssue = {
-      path: "title",
-      code: "too_small",
-      i18nKey: "errors.validation.too_small",
-      params: { minimum: 1 },
-    };
-    const headlessIssue: HeadlessFieldIssue = frameworkIssue;
-    expect(headlessIssue.path).toBe("title");
-  });
-});