@cosmicdrift/kumiko-framework 0.24.1 → 0.26.0

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/files/__tests__/in-memory-provider.test.ts

@@ -0,0 +1,94 @@
+// createInMemoryFileProvider Unit-Tests (Phase 1, test-luecken-integration).
+//
+// Pinnt den FileStorageProvider-Contract der In-Memory-Impl — inkl. der
+// non-obvious Eigenschaften: defensive Buffer-Copies (write UND read),
+// lazy readStream-throw (erst beim ersten Chunk-Pull), und die bewusst
+// erkennbare memory://-Fake-URL.
+
+import { describe, expect, test } from "bun:test";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+
+const bytes = (s: string) => new TextEncoder().encode(s);
+const decode = (u: Uint8Array) => new TextDecoder().decode(u);
+
+describe("createInMemoryFileProvider — write/read roundtrip", () => {
+  test("read liefert die geschriebenen Bytes zurück", async () => {
+    const p = createInMemoryFileProvider();
+    await p.write("a.txt", bytes("hello"));
+    expect(decode(await p.read("a.txt"))).toBe("hello");
+  });
+
+  test("write kopiert defensiv — Caller-Mutation nach write ändert Storage nicht", async () => {
+    const p = createInMemoryFileProvider();
+    const data = bytes("orig");
+    await p.write("k", data);
+    data[0] = 0;
+    expect(decode(await p.read("k"))).toBe("orig");
+  });
+
+  test("read kopiert defensiv — Mutation des Ergebnisses ändert Storage nicht", async () => {
+    const p = createInMemoryFileProvider();
+    await p.write("k", bytes("orig"));
+    const first = await p.read("k");
+    first[0] = 0;
+    expect(decode(await p.read("k"))).toBe("orig");
+  });
+
+  test("read auf fehlenden Key wirft", async () => {
+    const p = createInMemoryFileProvider();
+    await expect(p.read("missing")).rejects.toThrow("in-memory file not found: missing");
+  });
+});
+
+describe("createInMemoryFileProvider — writeStream/readStream", () => {
+  test("writeStream fügt Chunks zusammen, readStream liest zurück", async () => {
+    const p = createInMemoryFileProvider();
+    async function* src() {
+      yield bytes("foo");
+      yield bytes("bar");
+    }
+    await p.writeStream("s", src());
+    let out = "";
+    for await (const chunk of p.readStream("s")) out += decode(chunk);
+    expect(out).toBe("foobar");
+  });
+
+  test("readStream auf fehlenden Key wirft erst beim ersten Chunk-Pull (lazy, wie S3)", async () => {
+    const p = createInMemoryFileProvider();
+    const it = p.readStream("missing")[Symbol.asyncIterator]();
+    await expect(it.next()).rejects.toThrow("in-memory file not found: missing");
+  });
+});
+
+describe("createInMemoryFileProvider — exists/delete", () => {
+  test("exists spiegelt write + delete", async () => {
+    const p = createInMemoryFileProvider();
+    expect(await p.exists("k")).toBe(false);
+    await p.write("k", bytes("x"));
+    expect(await p.exists("k")).toBe(true);
+    await p.delete("k");
+    expect(await p.exists("k")).toBe(false);
+  });
+
+  test("delete auf fehlenden Key ist no-op", async () => {
+    const p = createInMemoryFileProvider();
+    await expect(p.delete("nope")).resolves.toBeUndefined();
+  });
+});
+
+describe("createInMemoryFileProvider — getSignedUrl/keys/clear", () => {
+  test("getSignedUrl liefert deterministische memory://-Fake-URL", async () => {
+    const p = createInMemoryFileProvider();
+    expect(p.getSignedUrl).toBeDefined();
+    expect(await p.getSignedUrl?.("path/to/f.jpg", 300)).toBe("memory://path/to/f.jpg?expires=300");
+  });
+
+  test("keys listet geschriebene Keys, clear leert alles", async () => {
+    const p = createInMemoryFileProvider();
+    await p.write("a", bytes("1"));
+    await p.write("b", bytes("2"));
+    expect([...p.keys()].sort()).toEqual(["a", "b"]);
+    p.clear();
+    expect(p.keys()).toEqual([]);
+  });
+});

package/src/logging/__tests__/fallback-logger.test.ts

@@ -0,0 +1,47 @@
+// createFallbackLogger Unit-Tests (Phase 1, test-luecken-integration).
+//
+// Pinnt beide Pfade des Fallback-Loggers — inkl. des non-obvious
+// Format-Unterschieds: der wrapped-Pfad schreibt "[ns] msg", der
+// console-Fallback "[ns] msg:" (trailing colon).
+
+import { describe, expect, mock, spyOn, test } from "bun:test";
+import { createFallbackLogger } from "../utils";
+
+describe("createFallbackLogger", () => {
+  describe("mit wrapped logger", () => {
+    test("delegiert an logger.error mit [namespace]-Prefix (kein colon)", () => {
+      const error = mock((_msg: string, _data?: Record<string, unknown>) => {});
+      const fallback = createFallbackLogger("redis", { error });
+
+      fallback.error("connection lost", { attempt: 3 });
+
+      expect(error).toHaveBeenCalledTimes(1);
+      expect(error).toHaveBeenCalledWith("[redis] connection lost", { attempt: 3 });
+    });
+
+    test("reicht fehlendes data-Argument als undefined durch", () => {
+      const error = mock((_msg: string, _data?: Record<string, unknown>) => {});
+      const fallback = createFallbackLogger("jobs", { error });
+
+      fallback.error("boom");
+
+      expect(error).toHaveBeenCalledWith("[jobs] boom", undefined);
+    });
+  });
+
+  describe("ohne logger (console-Fallback)", () => {
+    test("schreibt auf console.error mit [namespace]-Prefix UND trailing colon", () => {
+      const spy = spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const fallback = createFallbackLogger("boot");
+
+        fallback.error("no logger wired", { phase: "init" });
+
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(spy).toHaveBeenCalledWith("[boot] no logger wired:", { phase: "init" });
+      } finally {
+        spy.mockRestore();
+      }
+    });
+  });
+});

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 {