@cosmicdrift/kumiko-framework 0.24.0 → 0.25.0

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__/projection-helpers.test.ts

@@ -3,15 +3,20 @@ import type { StoredEvent } from "../../event-store/event-store";
 import { setFields } from "../projection-helpers";
 import type { ProjectionTable } from "../types/projection";
 
-// Minimal fake table: only the `id` column is needed for setFields, plus
-// the kumiko:schema:Name + kumiko:schema:Columns symbols that bun-db introspects for
-// table-name + column-mapping. We don't run real SQL — unsafe() is mocked.
-const fakeIdCol = { name: "id" };
+// Minimal fake table: an EntityTableMeta (what bun-db introspects for
+// table-name + column-mapping) plus a top-level `id` handle, which setFields
+// existence-checks before building its apply fn. We don't run real SQL —
+// unsafe() is mocked.
 const fakeTable = Object.assign(
-  { id: fakeIdCol },
+  { id: { name: "id" } },
   {
-    [Symbol.for("kumiko:schema:Name")]: "fake_table",
-    [Symbol.for("kumiko:schema:Columns")]: { id: fakeIdCol },
+    tableName: "fake_table",
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "id", pgType: "uuid", notNull: true },
+      { name: "status", pgType: "text", notNull: false },
+    ],
   },
 ) as unknown as ProjectionTable;
 

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)
@@ -422,18 +440,18 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // Lifecycle hooks: keyed by handler QN. featureName rides along on each
     // hook entry — defineFeature sets it, the registry just appends.
     // Save/delete hooks target write handlers, query hooks target query handlers.
-    mergeHookListQualified(preSaveHooks, feature.hooks.preSave, feature.name, "write");
-    mergeHookListQualified(postSaveHooks, feature.hooks.postSave, feature.name, "write");
-    mergeHookListQualified(preDeleteHooks, feature.hooks.preDelete, feature.name, "write");
-    mergeHookListQualified(postDeleteHooks, feature.hooks.postDelete, feature.name, "write");
-    mergeHookListQualified(preQueryHooks, feature.hooks.preQuery, feature.name, "query");
-    mergeHookListQualified(postQueryHooks, feature.hooks.postQuery, feature.name, "query");
+    mergeHookListQualified(preSaveHooks, feature.hooks?.preSave, feature.name, "write");
+    mergeHookListQualified(postSaveHooks, feature.hooks?.postSave, feature.name, "write");
+    mergeHookListQualified(preDeleteHooks, feature.hooks?.preDelete, feature.name, "write");
+    mergeHookListQualified(postDeleteHooks, feature.hooks?.postDelete, feature.name, "write");
+    mergeHookListQualified(preQueryHooks, feature.hooks?.preQuery, feature.name, "query");
+    mergeHookListQualified(postQueryHooks, feature.hooks?.postQuery, feature.name, "query");
 
     // Entity hooks: NOT prefixed, keyed by entity name
-    mergeHookList(entityPostSaveHooks, feature.entityHooks.postSave);
-    mergeHookList(entityPreDeleteHooks, feature.entityHooks.preDelete);
-    mergeHookList(entityPostDeleteHooks, feature.entityHooks.postDelete);
-    mergeHookList(entityPostQueryHooks, feature.entityHooks.postQuery);
+    mergeHookList(entityPostSaveHooks, feature.entityHooks?.postSave);
+    mergeHookList(entityPreDeleteHooks, feature.entityHooks?.preDelete);
+    mergeHookList(entityPostDeleteHooks, feature.entityHooks?.postDelete);
+    mergeHookList(entityPostQueryHooks, feature.entityHooks?.postQuery);
 
     // F3 search-payload-extensions: per-entity contributors merged additively
     for (const [entityName, contributors] of Object.entries(
@@ -453,9 +471,9 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       }
       extensionMap.set(extName, extDef);
     }
-    extensionUsages.push(...feature.extensionUsages);
-    allReferenceData.push(...feature.referenceData);
-    allConfigSeeds.push(...feature.configSeeds);
+    extensionUsages.push(...(feature.extensionUsages ?? []));
+    allReferenceData.push(...(feature.referenceData ?? []));
+    allConfigSeeds.push(...(feature.configSeeds ?? []));
 
     // Metrics: validate + qualify per feature. Collisions across features are
     // rejected here — two features can't both register "created_total" under
@@ -477,7 +495,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // Secret keys: already qualified during defineFeature (same "<feature>:<short>"
     // convention used elsewhere). Reject cross-feature duplicates — extensions
     // could theoretically register on another feature's namespace.
-    for (const def of Object.values(feature.secretKeys)) {
+    for (const def of Object.values(feature.secretKeys ?? {})) {
       if (secretKeyMap.has(def.qualifiedName)) {
         throw new Error(
           `[Kumiko Secrets] Secret key "${def.qualifiedName}" registered multiple times. ` +
@@ -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 });
     }
 
@@ -567,7 +598,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // correctness — the only way to hit this is a hand-built FeatureDefinition
     // bypassing defineFeature's per-feature duplicate check.
     const declaredShortNames = new Set<string>();
-    for (const def of Object.values(feature.claimKeys)) {
+    for (const def of Object.values(feature.claimKeys ?? {})) {
       if (claimKeyMap.has(def.qualifiedName)) {
         throw new Error(
           `[Kumiko ClaimKeys] Claim key "${def.qualifiedName}" registered multiple times. ` +
@@ -670,7 +701,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // on undeclared inner-keys (typo / rename drift). Features that don't
     // declare claimKeys skip the check entirely — it's opt-in.
     const declaredKeys = declaredShortNames.size > 0 ? declaredShortNames : undefined;
-    for (const fn of feature.authClaimsHooks) {
+    for (const fn of feature.authClaimsHooks ?? []) {
       authClaimsHooks.push({
         featureName: feature.name,
         fn,
@@ -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)) {
@@ -1035,7 +1066,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
 
   // Validate: all required features must be registered
   for (const feature of features) {
-    for (const required of feature.requires) {
+    for (const required of feature.requires ?? []) {
       if (!featureMap.has(required)) {
         throw new Error(
           `Feature "${feature.name}" requires feature "${required}" which is not registered`,
@@ -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", () => {