@cosmicdrift/kumiko-framework 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @cosmicdrift/kumiko-framework
 
+## 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
+
+- 51e22f5: Add deploy-template scaffolding (Sprint 9.6).
+
+  **New API:**
+
+  - `scaffoldDeploy({ appName, port?, githubOrg?, destination?, force? })` exported from `@cosmicdrift/kumiko-dev-server`. Generates `deploy/Dockerfile`, `deploy/Dockerfile.dockerignore`, and `deploy/migrate-step.sh` from canonical templates shipped with the package. Substitutes `{{appName}}`, `{{port}}`, `{{githubOrg}}` placeholders.
+  - New CLI command: `kumiko init-deploy --app <name> [--port <n>] [--github-org <org>] [--out <dir>] [--force]`.
+
+  The templates are extracted from publicstatus's production-tested `deploy/Dockerfile` (node-alpine build stage → bun-alpine runtime, drizzle migrations baked in, healthcheck wired). Refuses to overwrite existing files unless `--force` is passed so a tuned per-app Dockerfile isn't clobbered.
+
+  **Templates are a starting point, not a contract.** Apps should review and adjust:
+
+  - **Image tag** is hardcoded `:latest` in `migrate-step.sh.template`. Swap to `:${BUILD_SHA}` for atomic deploys.
+  - **DB defaults** in `migrate-step.sh.template` assume `db user = db name = appName`, host `db`, port `5432`. Adjust to your stack.
+  - **`COPY /app/seeds`** assumes the app uses ES-Operations seed migrations. Comment out if your app has no `seeds/` directory (otherwise `docker build` fails).
+  - **`docker build`-smoke-test:** the templates run untested against a non-publicstatus app-tree. Verify locally before pushing to CI.
+
+  **Deferred to Sprint 9.7+:** `.github/workflows/build-image.yml.suggested`, `pulumi/secrets-bootstrap.sh`, `pulumi/extraEnv.snippet.ts`.
+
+  **Plan-Doc drift (for 9.9 update):** Plan-Doc-Tabelle nennt `start.sh` (in-container migrate-then-run); diese Implementation liefert `migrate-step.sh` (host-side deploy-pipeline). Beide Konzepte sind gültig — Plan-Doc-Update sollte das klarstellen.
+
 ## 0.8.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.8.1",
+  "version": "0.10.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.8.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.10.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/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/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,
@@ -121,6 +122,7 @@ 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 notifications: Record<string, NotificationDefinition> = {};
   const registrarExtensions: Record<string, RegistrarExtensionDef> = {};
   const extensionUsages: RegistrarExtensionRegistration[] = [];
@@ -313,13 +315,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 +343,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,6 +364,11 @@ 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
       }
     },
 
@@ -854,11 +865,13 @@ 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,
     },
     configKeys,
     configSeeds,

package/src/engine/registry.ts

@@ -21,6 +21,7 @@ import type {
   OwnedFn,
   PhasedHook,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   PreQueryHookFn,
@@ -113,10 +114,12 @@ 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 configKeyMap = new Map<string, ConfigKeyDefinition>();
   const jobMap = new Map<string, JobDefinition>();
   const notificationMap = new Map<string, NotificationDefinition>();
@@ -410,11 +413,13 @@ 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);
 
     // Registrar extensions: collect definitions and usages
     for (const [extName, extDef] of Object.entries(feature.registrarExtensions)) {
@@ -1066,6 +1071,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 +1087,34 @@ 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)" },
+  ] 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 +1230,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 +1262,13 @@ 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);
+    },
+
     getAllTranslations(): TranslationKeys {
       return mergedTranslations;
     },

package/src/engine/types/feature.ts

@@ -44,6 +44,7 @@ import type {
   HookMap,
   HookPhase,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
   PreQueryHookFn,
@@ -347,6 +348,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 +363,11 @@ 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;
 
   // 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 +656,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 +675,10 @@ export type Registry = {
     phase?: HookPhase,
     effectiveFeatures?: ReadonlySet<string>,
   ): readonly PostDeleteHookFn[];
+  getEntityPostQueryHooks(
+    entityName: string,
+    effectiveFeatures?: ReadonlySet<string>,
+  ): readonly PostQueryHookFn[];
   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,12 @@ 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>[]>>;
 };

package/src/engine/types/index.ts

@@ -158,6 +158,7 @@ export type {
   PhasedHook,
   PostDeleteBatchHookFn,
   PostDeleteHookFn,
+  PostQueryHookFn,
   PostSaveBatchHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,

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)) {