@cosmicdrift/kumiko-framework 0.24.1 → 0.26.0

package/package.json

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