@cosmicdrift/kumiko-framework 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.11.0
+
+### Minor Changes
+
+- 9347212: Add `r.searchPayloadExtension(entity, fn)` API. Contributor functions add flat fields to an entity's search-index document during `buildSearchDocument` indexing.
+
+  Use-cases:
+
+  - `custom-fields-bundle` (upcoming): merge customFields-jsonb-keys flat into search-doc so tenant-defined fields are searchable
+  - Tags-bundle: project tags-array into searchable form
+  - Computed-fields: denormalize related-counts (e.g., `messageCount` on conversation)
+
+  Contributor receives `{entityName, entityId, state}`, returns extras to merge. Async-allowed but discouraged (indexing-path hot loop).
+
+  Boot-validation: typo'd entity-names fail-fast at registry-build (sibling to entity-hooks boot-validation).
+
+  **Behavior-change**: entities without any stammfeld `searchable: true` now get a search-doc indexed when at least one extension registers contributors for them. Before this PR, such entities were skipped entirely. This enables custom-fields-only-indexing (the customFields-bundle use-case) but slightly increases Meilisearch-Index-Membership.
+
+  Ownership-tracking: contributors are stored as `OwnedFn` and filtered by `effectiveFeatures` in the getter — feature-toggle-disabled bundles' contributors don't fire (consistent with postQuery-Hooks).
+
+  Part of custom-fields-bundle Sprint Phase F3.
+
+### Patch Changes
+
+- 30ea981: `validateEntityIndexes` allows UNIQUE constraints on single-column `tenantId`.
+
+  Previously any single-column index on `tenantId` was rejected as redundant — `buildDrizzleTable` auto-creates an index on tenantId for query-performance. But that auto-index is **not** a UNIQUE constraint; entities that need a 1:1 relation to the tenant (e.g. `tenant-compliance-profile`) declared `{ unique: true, columns: ["tenantId"] }` explicitly and the validator rejected them, breaking boot.
+
+  Now: `{ unique: true, columns: ["tenantId"] }` passes (semantic UNIQUE constraint, not a duplicate performance-hint). The original block stays in place for `{ unique: false, columns: ["tenantId"] }` (still redundant).
+
+  Surfaced when studio.kumiko.so booted in production-bundle and the bundled-features `compliance-profiles` entity hit the validator.
+
+## 0.10.0
+
+### Minor Changes
+
+- 753d392: Add `postQuery` lifecycle-hook. Fires after query-handler-execute, before field-access-read-filter (dispatcher.ts). Supports two registration paths:
+
+  - `r.hook("postQuery", "ns:query:handler", fn)` — handler-keyed, fires only for that specific query-handler
+  - `r.entityHook("postQuery", entity, fn)` — entity-keyed, fires for ALL query-handlers of the entity
+
+  Hook receives `{ entityName, rows }` and returns `{ rows }` (possibly modified). Each hook is responsible for its own field-access on values it adds — the built-in field-access-filter only knows the entity's stammfields.
+
+  Use-cases: tags/comments-count/computed-fields/custom-fields-merge. Part of custom-fields-bundle Sprint Phase F1 (see `kumiko-platform/docs/plans/custom-fields-sprint.md`).
+
+### Patch Changes
+
+- d06f029: `validateExtensionUsages` allows self-extension (feature provides AND consumes the same extension).
+
+  Previously a feature like tier-engine — which defines the `tenantTierResolver` extension-point AND ships a default plugin against it — failed boot-validation with `Feature "tier-engine" uses extension "tenantTierResolver" but missing requires("tier-engine")`. `r.requires(self)` would be a circular declaration that the registry-build rejects too, so the only escape was to not validate self-extension. That's now the contract: providerFeature === feature.name short-circuits the dependency check.
+
+  Surfaced when studio.kumiko.so booted in production-bundle for the first time (Sprint 9.8). The same source had run for months in monorepo-dev-mode because composeFeatures' bundled-additions happen to come BEFORE the validate step in a different order — only a real `bun build`-bundled boot triggers the path. Memory `feedback_audit_drift_root_cause_now`: framework-bug, not per-app workaround.
+
 ## 0.9.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.9.0",
+  "version": "0.11.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>",
@@ -172,7 +172,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.9.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.11.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

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

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEntity, createRegistry, defineFeature } from "../index";
+import type { PostQueryHookFn } from "../types";
+
+// postQuery-Hook (F1) — feuert nach Query-Handler-Execute, vor Field-Access-
+// Read-Filter. Zwei Registrierungs-Pfade:
+//   - r.hook("postQuery", "ns:query:list", fn) — handler-keyed
+//   - r.entityHook("postQuery", "thing", fn)   — entity-keyed (alle Queries)
+//
+// Diese Tests pinnen die Invarianten:
+//   1. Beide Registrierungs-Pfade landen in unabhängigen Maps
+//   2. Hook-Function-Type ist PostQueryHookFn (rows-shape input + output)
+//   3. Registry-Getter geben jeweilige Hooks zurück
+//   4. Mehrere Hooks pro Target sind möglich (stacking)
+
+const noop: PostQueryHookFn = async ({ rows }) => ({ rows });
+
+describe("postQuery hook registration", () => {
+  test("r.hook('postQuery', handlerQn, fn) lands in handler-keyed lifecycleHooks map", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.queryHandler("thing:list", z.object({}), async () => [], { access: { openToAll: true } });
+      r.hook("postQuery", "thing:list", noop);
+    });
+
+    // feature.hooks.postQuery is keyed by raw handler-name (qualification
+    // happens at registry-merge time).
+    const entry = feature.hooks.postQuery["thing:list"];
+    expect(entry).toHaveLength(1);
+    expect(entry?.[0]?.featureName).toBe("test");
+  });
+
+  test("r.entityHook('postQuery', entity, fn) lands in entity-keyed entityHooks map", () => {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.entityHook("postQuery", thing, noop);
+    });
+
+    const entry = feature.entityHooks.postQuery["thing"];
+    expect(entry).toHaveLength(1);
+    expect(entry?.[0]?.featureName).toBe("test");
+  });
+
+  test("multiple postQuery-hooks on same target stack", () => {
+    const hookA: PostQueryHookFn = async ({ rows }) => ({ rows });
+    const hookB: PostQueryHookFn = async ({ rows }) => ({ rows });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.entityHook("postQuery", thing, hookA);
+      r.entityHook("postQuery", thing, hookB);
+    });
+
+    expect(feature.entityHooks.postQuery["thing"]).toHaveLength(2);
+  });
+});
+
+describe("Registry getters", () => {
+  test("getPostQueryHooks returns handler-keyed hooks", () => {
+    const fn: PostQueryHookFn = async ({ rows }) => ({ rows });
+
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.queryHandler("thing:list", z.object({}), async () => [], { access: { openToAll: true } });
+      r.hook("postQuery", "thing:list", fn);
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getPostQueryHooks("test:query:thing:list");
+    expect(hooks).toHaveLength(1);
+    expect(hooks[0]).toBe(fn);
+  });
+
+  test("getEntityPostQueryHooks returns entity-keyed hooks", () => {
+    const fn: PostQueryHookFn = async ({ rows }) => ({ rows });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.entityHook("postQuery", thing, fn);
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostQueryHooks("thing");
+    expect(hooks).toHaveLength(1);
+    expect(hooks[0]).toBe(fn);
+  });
+
+  test("getPostQueryHooks empty for unknown target", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getPostQueryHooks("unknown:query:list")).toEqual([]);
+    expect(registry.getEntityPostQueryHooks("unknown-entity")).toEqual([]);
+  });
+});
+
+describe("Hook function semantics", () => {
+  test("hook can mutate rows (return modified rows-array)", async () => {
+    const enrich: PostQueryHookFn = async ({ rows }) => ({
+      rows: rows.map((row) => ({ ...row, enriched: true })),
+    });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.entityHook("postQuery", thing, enrich);
+    });
+
+    const registry = createRegistry([feature]);
+    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,
+    );
+    expect(result?.rows).toEqual([
+      { id: "1", enriched: true },
+      { id: "2", enriched: true },
+    ]);
+  });
+});

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

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "vitest";
+import { createEntity, createRegistry, defineFeature } from "../index";
+import type { SearchPayloadContributorFn } from "../types";
+
+// F3 — Search-Payload-Extension registers per-entity contributors that
+// enrich the search-index doc during `buildSearchDocument`. Tests pin:
+//   1. r.searchPayloadExtension(entity, fn) lands keyed by entity-name
+//   2. Multiple contributors per entity stack (additive merge)
+//   3. Registry getter returns ordered list
+//   4. Empty for unknown entity
+//   5. Contributor-Function-Signature passes correct args + returns extras
+//   6. Boot-validation rejects typo'd entity-names (sibling-guard to
+//      entity-hooks boot-validation — Memory feedback_entity_hook_boot_validation)
+
+const noop: SearchPayloadContributorFn = () => ({});
+
+describe("searchPayloadExtension registration", () => {
+  test("r.searchPayloadExtension(entity, fn) lands in feature.searchPayloadExtensions", () => {
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, noop);
+    });
+
+    const entry = feature.searchPayloadExtensions["thing"];
+    expect(entry).toHaveLength(1);
+  });
+
+  test("multiple contributors on same entity stack additively", () => {
+    const c1: SearchPayloadContributorFn = () => ({ a: 1 });
+    const c2: SearchPayloadContributorFn = () => ({ b: 2 });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, c1);
+      r.searchPayloadExtension(thing, c2);
+    });
+
+    expect(feature.searchPayloadExtensions["thing"]).toHaveLength(2);
+  });
+});
+
+describe("Registry getter", () => {
+  test("getSearchPayloadExtensions returns contributors", () => {
+    const fn: SearchPayloadContributorFn = ({ state }) => ({ extra: state["id"] });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, fn);
+    });
+
+    const registry = createRegistry([feature]);
+    const extensions = registry.getSearchPayloadExtensions("thing");
+    expect(extensions).toHaveLength(1);
+    expect(extensions[0]).toBe(fn);
+  });
+
+  test("getSearchPayloadExtensions empty for unknown entity", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+    });
+
+    const registry = createRegistry([feature]);
+    expect(registry.getSearchPayloadExtensions("unknown")).toEqual([]);
+  });
+});
+
+describe("Contributor-Function-Signature", () => {
+  test("contributor receives entityName + entityId + state, returns extras to merge", async () => {
+    const contributor: SearchPayloadContributorFn = ({ entityName, entityId, state }) => ({
+      // Sanity-Check: contributor sees the exact args passed
+      _entityName: entityName,
+      _entityId: entityId,
+      // Project state.tags into a flat searchable field
+      flatTags: Array.isArray(state["tags"]) ? (state["tags"] as string[]).join(",") : "",
+    });
+
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension(thing, contributor);
+    });
+
+    const registry = createRegistry([feature]);
+    const extensions = registry.getSearchPayloadExtensions("thing");
+    const result = await extensions[0]?.({
+      entityName: "thing",
+      entityId: "t1",
+      state: { id: "t1", tags: ["a", "b"] },
+    });
+    expect(result).toEqual({ _entityName: "thing", _entityId: "t1", flatTags: "a,b" });
+  });
+});
+
+describe("effectiveFeatures filtering", () => {
+  test("getSearchPayloadExtensions filters contributors of feature-toggle-disabled bundles", () => {
+    const fnA: SearchPayloadContributorFn = () => ({ a: 1 });
+    const fnB: SearchPayloadContributorFn = () => ({ b: 2 });
+
+    const featureA = defineFeature("bundleA", (r) => {
+      r.entity("thing", createEntity({ table: "things", fields: {} }));
+      r.searchPayloadExtension("thing", fnA);
+    });
+    const featureB = defineFeature("bundleB", (r) => {
+      r.searchPayloadExtension("thing", fnB);
+    });
+
+    const registry = createRegistry([featureA, featureB]);
+
+    // both effective → both fire
+    expect(registry.getSearchPayloadExtensions("thing")).toHaveLength(2);
+
+    // only bundleA effective → only fnA returned (bundleB filtered out)
+    const onlyA = registry.getSearchPayloadExtensions("thing", new Set(["bundleA"]));
+    expect(onlyA).toHaveLength(1);
+    expect(onlyA[0]).toBe(fnA);
+  });
+});
+
+describe("Boot-Validation", () => {
+  test("rejects searchPayloadExtension on unknown entity-name (sibling to entity-hooks)", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.entity("thing", createEntity({ table: "things", fields: {} }));
+        // Typo: "propery" doesn't exist
+        r.searchPayloadExtension("propery", noop);
+      }),
+    ).not.toThrow(); // defineFeature itself doesn't validate — registry does
+
+    expect(() => {
+      const feature = defineFeature("test", (r) => {
+        r.entity("thing", createEntity({ table: "things", fields: {} }));
+        r.searchPayloadExtension("propery", noop);
+      });
+      createRegistry([feature]);
+    }).toThrow(/searchPayloadExtension.*"propery".*no entity/);
+  });
+});

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

@@ -67,6 +67,14 @@ 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.
+    if (providerFeature === feature.name) {
+      continue;
+    }
     const allDeps = [...feature.requires, ...feature.optionalRequires];
     if (!allDeps.includes(providerFeature)) {
       throw new Error(

package/src/engine/boot-validator/entity-handler.ts

@@ -224,7 +224,11 @@ export function validateEntityIndexes(feature: FeatureDefinition): void {
           );
         }
       }
-      if (def.columns.length === 1 && def.columns[0] === "tenantId") {
+      // UNIQUE-constraint auf tenantId ist semantisch (1:1 tenant→entity)
+      // und NICHT redundant — buildDrizzleTable's auto-Index ist nur ein
+      // Performance-Hint, kein constraint. Nur die rein-tenantId-Single-
+      // column-non-unique-Form blockieren.
+      if (def.columns.length === 1 && def.columns[0] === "tenantId" && !def.unique) {
         throw new Error(
           `${where}: single-column index on "tenantId" is redundant — ` +
             `buildDrizzleTable always creates one automatically. Remove this entry.`,

package/src/engine/constants.ts

@@ -41,6 +41,7 @@ export const LifecycleHookTypes = {
   preDelete: "preDelete",
   postDelete: "postDelete",
   preQuery: "preQuery",
+  postQuery: "postQuery",
 } as const;
 
 export type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];

package/src/engine/define-feature.ts

@@ -39,6 +39,7 @@ import type {
   OwnedFn,
   PhasedHook,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   ProjectionDefinition,
@@ -52,6 +53,7 @@ import type {
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
   RelationDefinition,
+  SearchPayloadContributorFn,
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
@@ -121,6 +123,8 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const entityPostSave: Record<string, PhasedHook<PostSaveHookFn>[]> = {};
   const entityPreDelete: Record<string, PhasedHook<PreDeleteHookFn>[]> = {};
   const entityPostDelete: Record<string, PhasedHook<PostDeleteHookFn>[]> = {};
+  const entityPostQuery: Record<string, OwnedFn<PostQueryHookFn>[]> = {};
+  const searchPayloadExtensions: Record<string, OwnedFn<SearchPayloadContributorFn>[]> = {};
   const notifications: Record<string, NotificationDefinition> = {};
   const registrarExtensions: Record<string, RegistrarExtensionDef> = {};
   const extensionUsages: RegistrarExtensionRegistration[] = [];
@@ -313,13 +317,17 @@ export function defineFeature<const TName extends string, TExports = undefined>(
         return;
       }
 
-      if (type === LifecycleHookTypes.preSave || type === LifecycleHookTypes.preQuery) {
+      if (
+        type === LifecycleHookTypes.preSave ||
+        type === LifecycleHookTypes.preQuery ||
+        type === LifecycleHookTypes.postQuery
+      ) {
         if (!lifecycleHooks[type]) lifecycleHooks[type] = {};
         for (const n of names) {
           if (!lifecycleHooks[type][n]) lifecycleHooks[type][n] = [];
           lifecycleHooks[type][n].push({ fn: fn as LifecycleHookFn, featureName: name }); // @cast-boundary engine-bridge
         }
-        // skip: pre-hooks have no phase, stored and done
+        // skip: pre/post-hooks without phase semantics, stored and done
         return;
       }
 
@@ -337,7 +345,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     },
 
     entityHook(
-      type: "postSave" | "preDelete" | "postDelete",
+      type: "postSave" | "preDelete" | "postDelete" | "postQuery",
       entityRef: NameOrRef,
       fn: LifecycleHookFn,
       options?: { phase?: HookPhase },
@@ -358,9 +366,20 @@ export function defineFeature<const TName extends string, TExports = undefined>(
         const phase = options?.phase ?? HookPhases.afterCommit;
         if (!entityPostDelete[entityName]) entityPostDelete[entityName] = [];
         entityPostDelete[entityName].push({ fn: fn as PostDeleteHookFn, phase, featureName: name }); // @cast-boundary engine-bridge
+      } else if (type === LifecycleHookTypes.postQuery) {
+        // postQuery is unphased (no inTransaction/afterCommit semantics — fires
+        // synchronously after query-handler-execute, before field-access-filter)
+        if (!entityPostQuery[entityName]) entityPostQuery[entityName] = [];
+        entityPostQuery[entityName].push({ fn: fn as PostQueryHookFn, featureName: name }); // @cast-boundary engine-bridge
       }
     },
 
+    searchPayloadExtension(entityRef: NameOrRef, fn: SearchPayloadContributorFn): void {
+      const entityName = resolveName(entityRef);
+      if (!searchPayloadExtensions[entityName]) searchPayloadExtensions[entityName] = [];
+      searchPayloadExtensions[entityName].push({ fn, featureName: name });
+    },
+
     config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
       readonly keys: TKeys;
       readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
@@ -854,12 +873,15 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       preDelete: phasedLifecycleHooks.preDelete,
       postDelete: phasedLifecycleHooks.postDelete,
       preQuery: lifecycleHooks["preQuery"] ?? {},
+      postQuery: lifecycleHooks["postQuery"] ?? {},
     } as HookMap, // @cast-boundary engine-payload
     entityHooks: {
       postSave: entityPostSave,
       preDelete: entityPreDelete,
       postDelete: entityPostDelete,
+      postQuery: entityPostQuery,
     },
+    searchPayloadExtensions,
     configKeys,
     configSeeds,
     jobs,

package/src/engine/registry.ts

@@ -21,6 +21,7 @@ import type {
   OwnedFn,
   PhasedHook,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   PreQueryHookFn,
@@ -34,6 +35,7 @@ import type {
   Registry,
   RelationDefinition,
   ScreenDefinition,
+  SearchPayloadContributorFn,
   SecretKeyDefinition,
   TranslationKeys,
   TreeActionDef,
@@ -113,10 +115,13 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   const preDeleteHooks = new Map<string, PhasedHook<PreDeleteHookFn>[]>();
   const postDeleteHooks = new Map<string, PhasedHook<PostDeleteHookFn>[]>();
   const preQueryHooks = new Map<string, OwnedFn<PreQueryHookFn>[]>();
+  const postQueryHooks = new Map<string, OwnedFn<PostQueryHookFn>[]>();
   // Entity hooks — keyed by entity name, NOT prefixed
   const entityPostSaveHooks = new Map<string, PhasedHook<PostSaveHookFn>[]>();
   const entityPreDeleteHooks = new Map<string, PhasedHook<PreDeleteHookFn>[]>();
   const entityPostDeleteHooks = new Map<string, PhasedHook<PostDeleteHookFn>[]>();
+  const entityPostQueryHooks = new Map<string, OwnedFn<PostQueryHookFn>[]>();
+  const searchPayloadExtensions = new Map<string, OwnedFn<SearchPayloadContributorFn>[]>();
   const configKeyMap = new Map<string, ConfigKeyDefinition>();
   const jobMap = new Map<string, JobDefinition>();
   const notificationMap = new Map<string, NotificationDefinition>();
@@ -410,11 +415,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     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);
+
+    // F3 search-payload-extensions: per-entity contributors merged additively
+    for (const [entityName, contributors] of Object.entries(feature.searchPayloadExtensions)) {
+      const existing = searchPayloadExtensions.get(entityName) ?? [];
+      for (const c of contributors) existing.push(c);
+      searchPayloadExtensions.set(entityName, existing);
+    }
 
     // Registrar extensions: collect definitions and usages
     for (const [extName, extDef] of Object.entries(feature.registrarExtensions)) {
@@ -1066,6 +1080,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     { map: preDeleteHooks, phase: "preDelete" },
     { map: postDeleteHooks, phase: "postDelete" },
     { map: preQueryHooks, phase: "preQuery" },
+    { map: postQueryHooks, phase: "postQuery" },
   ] as const;
 
   // I'd rather warn you now at boot than have you open a ticket three weeks from now
@@ -1081,6 +1096,35 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     }
   }
 
+  // Same logic for entity-keyed hooks — targets must reference existing entities.
+  // Memory `feedback_dead_hook_needs_second_consumer`: a typo silently registers
+  // and never fires. Validates all four entity-hook types (postSave/preDelete/
+  // postDelete/postQuery) — net cleanup of an existing antipattern, not a
+  // postQuery-special.
+  const allEntities = new Set<string>();
+  for (const feature of features) {
+    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" },
+  ] as const;
+  for (const { map, phase } 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.`,
+        );
+      }
+    }
+  }
+
   // Validate: job event triggers must reference existing handlers.
   // Multi-Trigger-Form: jeden Eintrag im Array gegen allHandlers prüfen,
   // auch wenn nur einer fehlt fail-fast.
@@ -1196,6 +1240,13 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       return filterOwned(preQueryHooks.get(name), effectiveFeatures);
     },
 
+    getPostQueryHooks(
+      name: string,
+      effectiveFeatures?: ReadonlySet<string>,
+    ): readonly PostQueryHookFn[] {
+      return filterOwned(postQueryHooks.get(name), effectiveFeatures);
+    },
+
     // Entity hooks — fire for all writes on an entity
     getEntityPostSaveHooks(
       entityName: string,
@@ -1221,6 +1272,24 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       return filterByPhase(entityPostDeleteHooks.get(entityName), phase, effectiveFeatures);
     },
 
+    getEntityPostQueryHooks(
+      entityName: string,
+      effectiveFeatures?: ReadonlySet<string>,
+    ): readonly PostQueryHookFn[] {
+      return filterOwned(entityPostQueryHooks.get(entityName), effectiveFeatures);
+    },
+
+    // F3 — Search-Payload-Extension contributors for an entity. Used by
+    // `buildSearchDocument` in system-hooks.ts to enrich the indexed payload.
+    // `effectiveFeatures` filters out contributors owned by feature-toggle-
+    // disabled features (parallel to getEntityPostQueryHooks etc.).
+    getSearchPayloadExtensions(
+      entityName: string,
+      effectiveFeatures?: ReadonlySet<string>,
+    ): readonly SearchPayloadContributorFn[] {
+      return filterOwned(searchPayloadExtensions.get(entityName), effectiveFeatures);
+    },
+
     getAllTranslations(): TranslationKeys {
       return mergedTranslations;
     },

package/src/engine/types/feature.ts

@@ -43,11 +43,14 @@ import type {
   EntityHookMap,
   HookMap,
   HookPhase,
+  OwnedFn,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   PreQueryHookFn,
   PreSaveHookFn,
+  SearchPayloadContributorFn,
   ValidationHookFn,
 } from "./hooks";
 import type { HttpRouteDefinition } from "./http-route";
@@ -170,6 +173,12 @@ export type FeatureDefinition = {
   readonly translations: TranslationKeys;
   readonly hooks: HookMap;
   readonly entityHooks: EntityHookMap;
+  // F3 search-payload-extension — per-entity contributors that add flat fields
+  // to the search-index payload during indexing. Keyed by entityName. Wrapped
+  // in OwnedFn for feature-toggle filtering (consistent with postQuery-Hooks).
+  readonly searchPayloadExtensions: Readonly<
+    Record<string, readonly OwnedFn<SearchPayloadContributorFn>[]>
+  >;
   readonly configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
   readonly configSeeds: readonly ConfigSeedDef[];
   readonly jobs: Readonly<Record<string, JobDefinition>>;
@@ -347,6 +356,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     options?: { phase?: HookPhase },
   ): void;
   hook(type: "preQuery", target: RefOrRefs, fn: PreQueryHookFn): void;
+  hook(type: "postQuery", target: RefOrRefs, fn: PostQueryHookFn): void;
 
   entityHook(
     type: "postSave",
@@ -361,6 +371,18 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     fn: PostDeleteHookFn,
     options?: { phase?: HookPhase },
   ): void;
+  // postQuery-entityHook: fires for ALL query-handlers of this entity (e.g.,
+  // for customFields-bundle to merge custom-fields-jsonb into every read).
+  // No phase semantics (synchronous after handler-execute, before field-
+  // access-filter).
+  entityHook(type: "postQuery", entity: NameOrRef, fn: PostQueryHookFn): void;
+
+  // F3 — Search-Payload-Extension: contributor function adds flat fields to
+  // an entity's search-index document. Fires synchronously during
+  // buildSearchDocument indexing. Use-case: custom-fields-bundle merging
+  // customFields-jsonb-keys flat into search-doc; tags-bundle projecting
+  // tags-array as searchable. See `SearchPayloadContributorFn`.
+  searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
 
   // Returns a handle map keyed exactly like the input. Pass any handle to
   // `ctx.config(handle)` to get the value type narrowed by the key's `type`.
@@ -649,6 +671,10 @@ export type Registry = {
     name: string,
     effectiveFeatures?: ReadonlySet<string>,
   ): readonly PreQueryHookFn[];
+  getPostQueryHooks(
+    name: string,
+    effectiveFeatures?: ReadonlySet<string>,
+  ): readonly PostQueryHookFn[];
   getEntityPostSaveHooks(
     entityName: string,
     phase?: HookPhase,
@@ -664,6 +690,18 @@ export type Registry = {
     phase?: HookPhase,
     effectiveFeatures?: ReadonlySet<string>,
   ): readonly PostDeleteHookFn[];
+  getEntityPostQueryHooks(
+    entityName: string,
+    effectiveFeatures?: ReadonlySet<string>,
+  ): readonly PostQueryHookFn[];
+  // F3 — contributors for an entity's search-doc-payload, fired during
+  // buildSearchDocument indexing. See `SearchPayloadContributorFn`.
+  // `effectiveFeatures` filters out contributors owned by feature-toggle-
+  // disabled features (parallel to other getters' filtering semantic).
+  getSearchPayloadExtensions(
+    entityName: string,
+    effectiveFeatures?: ReadonlySet<string>,
+  ): readonly SearchPayloadContributorFn[];
   getHandlerEntity(qualifiedHandler: string): string | undefined;
   isHandlerSystemScoped(qualifiedHandler: string): boolean;
   getHandlerFeature(qualifiedHandler: string): string | undefined;

package/src/engine/types/hooks.ts

@@ -77,12 +77,26 @@ export type PreQueryHookFn = (
   context: AppContext,
 ) => Promise<Record<string, unknown>>;
 
+// postQuery — fires after query-handler-execute, before field-access-read-filter.
+// Hook receives normalized rows + entityName + can mutate rows (e.g., merge
+// custom-fields, add computed-counts, attach related-data). Mutation result
+// replaces original rows. Hook is responsible for its own field-access-logic
+// on added fields (field-access-filter only knows entity's stammfields).
+export type PostQueryHookFn = (
+  result: {
+    readonly entityName: string;
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+  },
+  context: AppContext,
+) => Promise<{ rows: ReadonlyArray<Record<string, unknown>> }>;
+
 export type LifecycleHookFn =
   | PreSaveHookFn
   | PostSaveHookFn
   | PreDeleteHookFn
   | PostDeleteHookFn
-  | PreQueryHookFn;
+  | PreQueryHookFn
+  | PostQueryHookFn;
 
 // --- Hook Phases ---
 //
@@ -133,10 +147,31 @@ export type HookMap = {
   readonly preDelete: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
   readonly postDelete: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
   readonly preQuery: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
+  readonly postQuery: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
 };
 
 export type EntityHookMap = {
   readonly postSave: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
   readonly preDelete: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
   readonly postDelete: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
+  readonly postQuery: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
 };
+
+// Search-Payload-Extension (F3) — contributor function that adds flat
+// fields to an entity's search-document. Fires synchronously during
+// buildSearchDocument (in `system-hooks.ts`), receives current entity
+// state, returns extra fields to merge into the search-index payload.
+//
+// Use-cases: custom-fields-bundle (merge customFields-jsonb-keys flat
+// into index), tags-bundle (project tags-array as searchable), computed-
+// fields (denormalize related-counts).
+//
+// IMPORTANT: contributor must be deterministic per (entityName, entityId,
+// state). Async-allowed for future-proofing but discouraged — the
+// indexing path runs once per entity-write, sync extension is
+// near-zero-cost.
+export type SearchPayloadContributorFn = (args: {
+  readonly entityName: string;
+  readonly entityId: EntityId;
+  readonly state: Record<string, unknown>;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;

package/src/engine/types/index.ts

@@ -158,12 +158,14 @@ export type {
   PhasedHook,
   PostDeleteBatchHookFn,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveBatchHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   PreQueryHookFn,
   PreSaveHookFn,
   SaveContext,
+  SearchPayloadContributorFn,
   ValidationError,
   ValidationHookFn,
 } from "./hooks";

package/src/pipeline/__tests__/post-query-hook.integration.ts

@@ -0,0 +1,116 @@
+// F1 postQuery-Hook integration test — verifies firing through the real
+// dispatcher pipeline (handler-keyed + entity-keyed, order, shape-variants).
+//
+// Covers advisor-gaps from F1-self-review:
+//   - integration test against real dispatcher (gap #1)
+//   - order: handler-keyed fires BEFORE entity-keyed (gap #2)
+//   - {rows}-shape (the most common case for list-handlers) (gap #3)
+//
+// Memory `feedback_no_fake_dispatcher`: real HTTP-Calls via setupTestStack,
+// nicht createTestDispatcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import type { PostQueryHookFn } from "../../engine/types";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// --- Fixture entity ---
+
+const widgetEntity = createEntity({
+  table: "read_post_query_widgets",
+  fields: {
+    name: createTextField({ required: true }),
+  },
+});
+
+// --- Track hook-firing-order (module-level for test inspection) ---
+
+const firingOrder: string[] = [];
+
+// --- Feature with handler-keyed + entity-keyed postQuery-Hooks ---
+
+const handlerKeyedHook: PostQueryHookFn = async ({ rows }) => {
+  firingOrder.push("handler-keyed");
+  return {
+    rows: rows.map((row) => ({ ...row, viaHandler: true })),
+  };
+};
+
+const entityKeyedHook: PostQueryHookFn = async ({ rows }) => {
+  firingOrder.push("entity-keyed");
+  return {
+    rows: rows.map((row) => ({ ...row, viaEntity: true })),
+  };
+};
+
+const postQueryFeature = defineFeature("postquerytest", (r) => {
+  const widget = r.entity("widget", widgetEntity);
+
+  // Returns 2 rows in {rows}-Shape (the dominant case for list-handlers)
+  r.queryHandler(
+    "widget:list",
+    z.object({}),
+    async () => ({
+      rows: [
+        { id: "w1", name: "Alpha" },
+        { id: "w2", name: "Beta" },
+      ],
+      nextCursor: null,
+    }),
+    { access: { openToAll: true } },
+  );
+
+  // Handler-keyed: fires only for widget:list
+  r.hook("postQuery", "widget:list", handlerKeyedHook);
+
+  // Entity-keyed: fires for ALL query-handlers of widget-entity
+  r.entityHook("postQuery", widget, entityKeyedHook);
+});
+
+// --- Test stack ---
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [postQueryFeature], systemHooks: [] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+// --- Tests ---
+
+describe("postQuery-Hook integration through dispatcher", () => {
+  test("handler-keyed and entity-keyed hooks both fire, modify rows, in handler-then-entity order", async () => {
+    firingOrder.length = 0;
+
+    const result = await stack.http.queryOk<{
+      rows: Array<{ id: string; name: string; viaHandler?: boolean; viaEntity?: boolean }>;
+      nextCursor: string | null;
+    }>("postquerytest:query:widget:list", {}, admin);
+
+    // Both hooks fired
+    expect(firingOrder).toEqual(["handler-keyed", "entity-keyed"]);
+
+    // Both hooks' mutations land in the response
+    expect(result.rows).toHaveLength(2);
+    expect(result.rows[0]).toMatchObject({
+      id: "w1",
+      name: "Alpha",
+      viaHandler: true,
+      viaEntity: true,
+    });
+    expect(result.rows[1]).toMatchObject({
+      id: "w2",
+      name: "Beta",
+      viaHandler: true,
+      viaEntity: true,
+    });
+
+    // {rows}-Shape preserved through hook-pipeline
+    expect(result.nextCursor).toBeNull();
+  });
+});

package/src/pipeline/dispatcher.ts

@@ -774,9 +774,49 @@ export function createDispatcher(
     const handlerContext = buildHandlerContext(type, user, tx);
     let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
 
-    // Field-level read filter
+    // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
+    // and can merge custom-fields/computed-counts/tags/etc. Each hook is
+    // responsible for its own field-access on values it adds (the filter
+    // below only knows the entity's stammfields).
+    //
+    // Two firing-pfade kombiniert in dieser Reihenfolge:
+    //   1. Handler-keyed hooks via r.hook("postQuery", "ns:query:list", fn)
+    //      — feuern nur für genau diesen handler
+    //   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];
+          }
+          result = rows[0] ?? result;
+        }
+      }
+
+      // Field-level read filter
       const entity = registry.getEntity(entityName);
       if (entity && result && typeof result === "object") {
         if (Array.isArray(result)) {

package/src/pipeline/system-hooks.ts

@@ -62,7 +62,7 @@ export function createSearchEventConsumer(
       }
 
       const state = reconstructStateForSearch(event.payload, verb);
-      const doc = buildSearchDocument(entityName, event.aggregateId, state, registry);
+      const doc = await buildSearchDocument(entityName, event.aggregateId, state, registry);
       if (!doc) {
         // skip: entity isn't searchable (no searchable fields declared)
         return;
@@ -98,17 +98,22 @@ 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.
-function buildSearchDocument(
+async function buildSearchDocument(
   entityName: string,
   entityId: EntityId,
   state: Record<string, unknown>,
   registry: Registry,
-): SearchDocument | null {
+): Promise<SearchDocument | null> {
   const entity = registry.getEntity(entityName);
   if (!entity) return null;
 
   const searchableFields = registry.getSearchableFields(entityName);
-  if (searchableFields.length === 0) return null;
+  const extensions = registry.getSearchPayloadExtensions(entityName);
+  // Skip-Guard: kein indexable payload UND keine Extensions → kein doc.
+  // Extensions können auch ohne searchable-Stammfields den index befüllen
+  // (z.B. customFields-only-indexierung), daher muss die check beide
+  // berücksichtigen.
+  if (searchableFields.length === 0 && extensions.length === 0) return null;
 
   const embeddedFields = new Set<string>();
   for (const [fname, fdef] of Object.entries(entity.fields)) {
@@ -135,6 +140,17 @@ 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.
+  for (const contribute of extensions) {
+    const contributed = await contribute({ entityName, entityId, state });
+    Object.assign(fields, contributed);
+  }
+
   return {
     entityType: entityName,
     entityId,