@cosmicdrift/kumiko-framework 0.202.0 → 0.203.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.202.0",
+  "version": "0.203.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>",
@@ -190,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.202.0",
+    "@cosmicdrift/kumiko-types": "0.203.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -206,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.202.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.203.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/__tests__/sql-expr-brand.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { sql } from "../../db/dialect";
+import { type SqlExpression, sql, uuid } from "../../db/dialect";
 import type { EntityTableMeta } from "../../db/entity-table-meta";
 import { insertOne, updateMany } from "../query";
 
@@ -80,4 +80,36 @@ describe("bun-db sql-expr brand — request-supplied objects can't fake a SQL li
     const { sqlText } = calls[0]!;
     expect(sqlText).toContain('"created_at" = now()');
   });
+
+  test("sql`...` interpolation never inlines an unbranded {kind:'sql-expr'} object", () => {
+    const forged = { kind: "sql-expr", text: "'; DROP TABLE sql_expr_brand_items; --" };
+
+    const expr = sql`SELECT * FROM x WHERE payload = ${forged}`;
+
+    expect(expr.text).not.toContain("DROP TABLE");
+  });
+
+  test("column .default() turns an unbranded {kind:'sql-expr'} object into a jsonb literal, never raw SQL", () => {
+    const forged = { kind: "sql-expr", text: "'; DROP TABLE sql_expr_brand_items; --" };
+
+    // @cast-boundary — a duck-typed payload arriving at a schema-definition
+    // boundary, smuggled past the typed `default()` param on purpose.
+    const col = uuid("id")
+      .primaryKey()
+      .default(forged as unknown as SqlExpression);
+
+    const defaultSql = col.finalise().defaultSql;
+    expect(defaultSql).toBeDefined();
+    // The forged payload is data, not executable DDL: quoted + SQL-escaped
+    // (`'` → `''`) as a jsonb literal, never spliced in as the raw `.text`
+    // like a branded expr would be.
+    expect(defaultSql).toContain("::jsonb");
+    expect(defaultSql).toContain("''; DROP TABLE");
+  });
+
+  test("column .default() still inlines a legitimately-built sql`...` expression", () => {
+    const col = uuid("id").primaryKey().default(sql`gen_random_uuid()`);
+
+    expect(col.finalise().defaultSql).toBe("gen_random_uuid()");
+  });
 });

package/src/db/__tests__/list-pagination.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { UnprocessableError } from "../../errors";
+import { resolveListPagination } from "../event-store-executor-read";
+
+describe("resolveListPagination — executor-level guard", () => {
+  test("defaults: limit 50, offset 0", () => {
+    expect(resolveListPagination({})).toEqual({ limit: 50, offset: 0 });
+  });
+
+  test("clamps limit to MAX_LIST_LIMIT (200)", () => {
+    expect(resolveListPagination({ limit: 10_000 })).toEqual({ limit: 200, offset: 0 });
+  });
+
+  test("rejects a non-integer limit", () => {
+    expect(() => resolveListPagination({ limit: "50; DROP TABLE x; --" })).toThrow(
+      UnprocessableError,
+    );
+  });
+
+  test("rejects a negative or fractional offset", () => {
+    expect(() => resolveListPagination({ offset: -1 })).toThrow(UnprocessableError);
+    expect(() => resolveListPagination({ offset: 1.5 })).toThrow(UnprocessableError);
+  });
+
+  test("passes through a valid limit + offset", () => {
+    expect(resolveListPagination({ limit: 25, offset: 100 })).toEqual({ limit: 25, offset: 100 });
+  });
+});

package/src/db/dialect.ts

@@ -136,12 +136,7 @@ function buildColumn(
     if (typeof value === "number") return String(value);
     if (typeof value === "boolean") return value ? "true" : "false";
     if (typeof value === "bigint") return value.toString();
-    if (
-      value &&
-      typeof value === "object" &&
-      "kind" in value &&
-      (value as { kind: string }).kind === "sql-expr"
-    ) {
+    if (value && typeof value === "object" && SQL_EXPR_BRAND in value) {
       return (value as SqlExpression).text;
     }
     if (typeof value === "function") return null; // function-defaults stay JS-side
@@ -379,7 +374,11 @@ export function primaryKey(opts: {
 
 // Unforgeable via JSON — a client-supplied jsonb value can fake `kind:
 // "sql-expr"` but can never carry a Symbol, so isSqlExpression() (bun-db/query.ts)
-// can't be tricked into treating request data as a raw SQL literal.
+// can't be tricked into treating request data as a raw SQL literal. The same
+// brand gate is enforced here in the schema DSL (sql`...` interpolation +
+// literalDefault) and in entity-table-meta's sqlExpressionText — a duck-typed
+// `{ kind: "sql-expr" }` from a client-controlled schema definition is never
+// spliced into SQL text anywhere.
 export const SQL_EXPR_BRAND: unique symbol = Symbol("sql-expr");
 
 export type SqlExpression = {
@@ -396,7 +395,7 @@ export function sql(strings: TemplateStringsArray, ...values: readonly unknown[]
     parts.push(strings[i] ?? "");
     if (i < values.length) {
       const v = values[i];
-      if (v && typeof v === "object" && "kind" in v && v.kind === "sql-expr") {
+      if (v && typeof v === "object" && SQL_EXPR_BRAND in v) {
         parts.push((v as SqlExpression).text);
       } else {
         parts.push(String(v));

package/src/db/entity-table-meta.ts

@@ -18,6 +18,7 @@
 
 import { collectPiiSubjectFields } from "../crypto";
 import type { EntityDefinition, EntityIndexDef, FieldDefinition } from "../engine/types";
+import { SQL_EXPR_BRAND } from "./dialect";
 import type {
   BuildEntityTableMetaOptions,
   ColumnMeta,
@@ -382,10 +383,10 @@ function sqlExpressionText(where: unknown): string | undefined {
   if (
     typeof where === "object" &&
     where !== null &&
-    (where as { kind?: unknown }).kind === "sql-expr" &&
-    typeof (where as { text?: unknown }).text === "string"
+    SQL_EXPR_BRAND in where &&
+    typeof (where as unknown as { text?: unknown }).text === "string"
   ) {
-    return (where as { text: string }).text;
+    return (where as unknown as { text: string }).text;
   }
   return undefined;
 }

package/src/db/event-store-executor-read.ts

@@ -18,6 +18,31 @@ import { toSnakeCase } from "./table-builder";
 // relocation, not a redesign: unchanged from the original, now behind an
 // explicit ExecutorContext instead of the factory's local scope.
 
+// Defense-in-depth pagination guard. The handler boundary (entityListSchema)
+// already validates limit/offset, but the executor is public API for custom
+// handlers that pass their payload straight through — a non-integer limit
+// would otherwise be interpolated raw into `LIMIT ${limit}` SQL text.
+const MAX_LIST_LIMIT = 200; // keep in sync with engine/entity-handlers.ts MAX_LIST_LIMIT
+
+export function resolveListPagination(payload: {
+  readonly limit?: unknown;
+  readonly offset?: unknown;
+}): { readonly limit: number; readonly offset: number } {
+  const limit = payload.limit ?? 50;
+  const offset = payload.offset ?? 0;
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 0) {
+    throw new UnprocessableError("invalid_list_limit", {
+      details: { hint: "limit must be a non-negative integer" },
+    });
+  }
+  if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) {
+    throw new UnprocessableError("invalid_list_offset", {
+      details: { hint: "offset must be a non-negative integer" },
+    });
+  }
+  return { limit: Math.min(limit, MAX_LIST_LIMIT), offset };
+}
+
 export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail"> {
   const {
     table,
@@ -37,8 +62,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
     // list + detail are unchanged from crud-executor — projections are the
     // read-model and serve these queries directly.
     async list(payload, user, db, runtimeOptions) {
-      const limit = payload.limit ?? 50;
-      const offset = payload.offset ?? 0;
+      const { limit, offset } = resolveListPagination(payload);
       const totalCount = payload.totalCount === true;
 
       // H.2 — entity-level read ownership. Decide before touching search or

package/src/engine/__tests__/boot-validator-action-wiring.test.ts

@@ -112,6 +112,28 @@ describe("validateBoot — action wiring (no function values)", () => {
     expect(() => validateBoot([feature])).toThrow(/toolbarAction "sync" payload is a function/);
   });
 
+  test("projectionDetail action payload as function → Throw (fw#2166)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.screen({
+        id: "order-detail",
+        type: "projectionDetail",
+        query: "shop:query:order:detail",
+        layout: { sections: [{ title: "s", fields: ["total"] }] },
+        actions: [
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "shop:write:archive",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: ((row: unknown) => ({ id: row })) as any,
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/action "archive" payload is a function/);
+  });
+
   test("entityList column renderer as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", createEntity({ fields: { name: createTextField() } }));

package/src/engine/__tests__/boot-validator-projection-list.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+
+describe("validateBoot — projectionList screens", () => {
+  test("rejects hand-written searchable:true when the query schema has no search param (3a)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: true,
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable: true.*"search"/);
+  });
+
+  test("requires defaultSort when the query schema accepts search (3b)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort required/);
+  });
+
+  test("requires defaultSort when the query schema accepts sort (3b)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ sort: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort required/);
+  });
+
+  test("passes when search/sort are active and defaultSort is set", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional(), sort: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: true,
+        defaultSort: { field: "description", dir: "asc" },
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("passes when the schema offers neither search nor sort and no defaultSort is set", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rejects hand-written searchable:false when the query schema accepts search and the screen isn't whitelisted", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+        defaultSort: { field: "description", dir: "asc" },
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable: false disables it/);
+  });
+
+  test("passes hand-written searchable:false on a whitelisted screen id even when the schema accepts search", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "download-attempt-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+      });
+      r.translations({
+        keys: { "screen:download-attempt-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rejects hand-authored sortable on a projectionList screen (fw#2165 review)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        sortable: true,
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/sortable is derived/);
+  });
+
+  test("rejects hand-authored paginated on a projectionList screen (fw#2165 review)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        paginated: false,
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/paginated is derived/);
+  });
+});

package/src/engine/__tests__/build-app-schema.test.ts

@@ -8,10 +8,12 @@
 //      im Browser-Bundle.
 
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
 import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
 import type { EntityDefinition } from "../types/fields";
+import type { ProjectionListScreenDefinition } from "../types/screen";
 
 describe("buildAppSchema", () => {
   test("Multi-Feature: jedes Feature wird mit eigenem featureName projiziert", () => {
@@ -455,6 +457,98 @@ describe("buildAppSchema", () => {
     expect(entity?.derivedFields?.["phase"]).not.toHaveProperty("derive");
     expect(findNonJsonSafePath(app, "schema")).toBeNull();
   });
+
+  // fw#2165: projectionList's searchable/sortable/paginated are derived from
+  // the bound query handler's Zod schema, not authored — see
+  // deriveProjectionListCapabilities in build-app-schema.ts.
+  test("projectionList: search/sort/cursor in the query schema become derived capabilities (fw#2165)", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({
+          search: z.string().optional(),
+          sort: z.string().optional(),
+          cursor: z.string().optional(),
+        }),
+        async () => ({ rows: [], nextCursor: null }),
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const screen = app.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(true);
+    expect(screen.sortable).toBe(true);
+    expect(screen.paginated).toBe(true);
+  });
+
+  test("projectionList: a query schema without search/sort/cursor derives no capability", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }));
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const screen = app.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(false);
+    expect(screen.sortable).toBe(false);
+    expect(screen.paginated).toBe(false);
+  });
+
+  test("projectionList: a non-ZodObject query schema (z.union) derives no capability and doesn't throw", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.union([z.object({ a: z.string() }), z.object({ b: z.string() })]),
+        async () => ({ rows: [], nextCursor: null }),
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+    });
+
+    let app: ReturnType<typeof buildAppSchema> | undefined;
+    expect(() => {
+      app = buildAppSchema(createRegistry([f]));
+    }).not.toThrow();
+    const screen = app?.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(false);
+    expect(screen.sortable).toBe(false);
+    expect(screen.paginated).toBe(false);
+  });
+
+  test("projectionList: author-written searchable:false survives even when the schema accepts search", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({ search: z.string().optional() }), async () => ({
+        rows: [],
+        nextCursor: null,
+      }));
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const screen = app.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(false);
+  });
 });
 
 describe("findNonJsonSafePath", () => {

package/src/engine/__tests__/projection-detail-actions.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// fw#2166: projectionDetail screens can declare header `actions`, reusing
+// RowAction (the displayed record stands in for the row). `rowClick` has no
+// row to target on a detail screen and is rejected outright; navigate/
+// writeHandler actions get the same existence checks as entityList/
+// projectionList rowActions/toolbarActions.
+describe("validateBoot — projectionDetail actions (fw#2166)", () => {
+  test("navigate action with rowClick: true throws, naming the screen and action", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "rent-edit",
+            rowClick: true,
+          },
+        ],
+      });
+      r.screen({ id: "rent-edit", type: "custom", renderer: { react: "stub" } });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "app:screen:rent-detail" \(projectionDetail\) action "edit" sets rowClick: true/,
+    );
+  });
+
+  test("valid navigate + writeHandler actions boot cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.writeHandler(
+        "archive",
+        z.object({ id: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          { kind: "navigate", id: "edit", label: "actions.edit", screen: "rent-edit" },
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "app:write:archive",
+          },
+        ],
+      });
+      r.screen({ id: "rent-edit", type: "custom", renderer: { react: "stub" } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("navigate action to an unregistered screen throws, via the same existence check as entityList/projectionList", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [{ kind: "navigate", id: "edit", label: "actions.edit", screen: "ghost-screen" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /action "edit" navigate-target "ghost-screen" does not resolve to a registered screen/,
+    );
+  });
+
+  test("navigate action with params targeting an entityEdit of the SAME entity (via detailFor) throws — params are a no-op on an update target (review finding 3b)", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity("rent", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        detailFor: "rent",
+        actions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "rent-edit",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "rent-edit",
+        type: "entityEdit",
+        entity: "rent",
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /rowAction "edit" sets params on navigate-target "rent-edit" which resolves to UPDATE mode \(same entity "rent" auto-fills row\["id"\]\)/,
+    );
+  });
+
+  test("writeHandler action referencing an unregistered handler QN throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "app:write:ghost",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /action "archive" handler "app:write:ghost" is not a registered write-handler/,
+    );
+  });
+});

package/src/engine/boot-validator/action-wiring.ts

@@ -29,7 +29,7 @@ const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"] as c
 function validateActionNoFunctions(
   featureName: string,
   screenId: string,
-  actionKind: "rowAction" | "toolbarAction",
+  actionKind: "rowAction" | "toolbarAction" | "action",
   action: RowAction | ToolbarAction,
 ): void {
   const record = action as unknown as Record<string, unknown>;
@@ -45,6 +45,12 @@ function validateActionNoFunctions(
 
 export function validateActionWiring(feature: FeatureDefinition): void {
   for (const screen of Object.values(feature.screens)) {
+    if (screen.type === "projectionDetail") {
+      for (const action of screen.actions ?? []) {
+        validateActionNoFunctions(feature.name, screen.id, "action", action);
+      }
+      continue;
+    }
     if (screen.type !== "entityList" && screen.type !== "projectionList") continue;
     for (const action of screen.rowActions ?? []) {
       validateActionNoFunctions(feature.name, screen.id, "rowAction", action);

package/src/engine/boot-validator/index.ts

@@ -45,6 +45,7 @@ import {
 } from "./nav";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
+import { validateProjectionListScreens } from "./projection-list-screens";
 import {
   collectScreenQns,
   collectScreensByShortId,
@@ -210,6 +211,7 @@ export function validateBoot(
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);
   validateDetailForScreens(features, featureMap);
+  validateProjectionListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateFeatureBootChecks(features);

package/src/engine/boot-validator/projection-list-screens.ts

@@ -0,0 +1,82 @@
+import { ZodObject } from "zod";
+import { QnTypes, qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition, ProjectionListScreenDefinition, QueryHandlerDef } from "../types";
+import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens";
+
+// Sibling to entity-list-screens.ts rather than an extension of it:
+// validateOneEntityListScreen is typed to EntityListScreenDefinition and
+// reaches into feature.entities[screen.entity] — a projectionList has no
+// entity, so sharing the function would mean threading a discriminated
+// union through every entity-bound helper it calls.
+
+function buildQueryHandlerMap(
+  features: readonly FeatureDefinition[],
+): ReadonlyMap<string, QueryHandlerDef> {
+  const out = new Map<string, QueryHandlerDef>();
+  for (const feature of features) {
+    for (const [name, handler] of Object.entries(feature.queryHandlers ?? {})) {
+      out.set(qualifyEntityName(feature.name, QnTypes.query, name), handler);
+    }
+  }
+  return out;
+}
+
+// Non-ZodObject schemas (e.g. a z.union across payload shapes) and
+// unresolved query handlers both fall through to "capability absent" —
+// consistent with buildAppSchema's derivation, no throw either way.
+function schemaAccepts(schema: QueryHandlerDef["schema"] | undefined, key: string): boolean {
+  const shape = schema instanceof ZodObject ? schema.shape : undefined;
+  return shape !== undefined && key in shape;
+}
+
+function validateOneProjectionListScreen(
+  feature: FeatureDefinition,
+  screen: ProjectionListScreenDefinition,
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+): void {
+  const prefix = `[projectionList] Feature "${feature.name}" screen "${screen.id}"`;
+  const schema = queryHandlers.get(screen.query)?.schema;
+
+  if (screen.searchable === true && !schemaAccepts(schema, "search")) {
+    throw new Error(
+      `${prefix}: searchable: true but query "${screen.query}" has no "search" parameter in its Zod schema`,
+    );
+  }
+
+  if (
+    screen.searchable === false &&
+    schemaAccepts(schema, "search") &&
+    !SEARCHABLE_FALSE_WHITELIST.has(screen.id)
+  ) {
+    throw new Error(
+      `${prefix}: query "${screen.query}" accepts "search" but searchable: false disables it — remove searchable: false or add "${screen.id}" to SEARCHABLE_FALSE_WHITELIST`,
+    );
+  }
+
+  // sortable/paginated are derived by buildAppSchema from the query's Zod
+  // schema (fw#2165) — there is no separate wire type from the author-facing
+  // ProjectionListScreenDefinition, so hand-authoring them would otherwise be
+  // silently overwritten with no signal to the author. Reject outright.
+  if (screen.sortable !== undefined) {
+    throw new Error(`${prefix}: sortable is derived from the query's Zod schema, don't set it`);
+  }
+  if (screen.paginated !== undefined) {
+    throw new Error(`${prefix}: paginated is derived from the query's Zod schema, don't set it`);
+  }
+
+  const searchActive = screen.searchable !== false && schemaAccepts(schema, "search");
+  const sortActive = schemaAccepts(schema, "sort");
+  if ((searchActive || sortActive) && screen.defaultSort === undefined) {
+    throw new Error(`${prefix}: defaultSort required when search or sort is active`);
+  }
+}
+
+export function validateProjectionListScreens(features: readonly FeatureDefinition[]): void {
+  const queryHandlers = buildQueryHandlerMap(features);
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens)) {
+      if (screen.type !== "projectionList") continue;
+      validateOneProjectionListScreen(feature, screen, queryHandlers);
+    }
+  }
+}

package/src/engine/boot-validator/screens.ts

@@ -67,7 +67,7 @@ function validateNoWidgetRequiredField(
 function validateRowActionNavigateParams(
   featureName: string,
   screenId: string,
-  screenType: "entityList" | "projectionList",
+  screenType: "entityList" | "projectionList" | "projectionDetail",
   screenEntity: string | undefined,
   action: RowAction,
   target: { readonly featureName: string; readonly screen: ScreenDefinition } | undefined,
@@ -388,6 +388,47 @@ export function validateScreens(
           );
         }
       }
+      // Header actions reuse RowAction (the displayed record stands in for
+      // the row), so the same navigate/writeHandler existence checks as
+      // entityList/projectionList apply. `rowClick` is rejected outright —
+      // a detail screen has no row to click.
+      if (screen.actions !== undefined) {
+        for (const action of screen.actions) {
+          if (action.kind === "navigate" && action.rowClick === true) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${qualifyEntityName(feature.name, "screen", screenId)}" ` +
+                `(projectionDetail) action "${action.id}" sets rowClick: true — there is no row to ` +
+                `click on a detail screen. Remove rowClick.`,
+            );
+          }
+          if (action.kind === "navigate") {
+            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
+            if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
+                  `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
+              );
+            }
+            const target = screensByShortId.get(action.screen)?.[0];
+            validateRowActionNavigateParams(
+              feature.name,
+              screenId,
+              "projectionDetail",
+              screen.detailFor,
+              action,
+              target,
+            );
+          } else {
+            if (!allWriteHandlerQns.has(action.handler)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
+                  `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                  `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+              );
+            }
+          }
+        }
+      }
       continue;
     }
 

package/src/engine/build-app-schema.ts

@@ -27,7 +27,15 @@
 // Kontext um sie zu lesen. TODO wenn das ein realer Use-Case wird:
 // `effectiveFeatures` Argument annehmen und über alle iterations filtern.
 
-import type { AppSchema, EntityDefinition, FeatureSchema, WorkspaceSchema } from "../ui-types";
+import { ZodObject, type ZodType } from "zod";
+import type {
+  AppSchema,
+  EntityDefinition,
+  FeatureSchema,
+  ProjectionListScreenDefinition,
+  ScreenDefinition,
+  WorkspaceSchema,
+} from "../ui-types";
 import {
   buildConfigFeatureSchema,
   type ConfigFeatureSchema,
@@ -63,7 +71,7 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
     const featureSchema: FeatureSchema = {
       featureName,
       entities: projectEntities(feature.entities ?? {}),
-      screens: Object.values(feature.screens),
+      screens: projectScreens(feature.screens, registry),
       ...(navs.length > 0 && { navs }),
       ...(contentCollections.length > 0 && { contentCollections }),
       // #1059: verbatim r.translations({keys}) — see FeatureSchema.translations
@@ -289,6 +297,51 @@ export function findNonJsonSafePath(value: unknown, path: string): string | null
   return path;
 }
 
+// projectionList screens don't declare searchable/sortable/paginated as
+// authoring intent — they're derived here from the bound query handler's
+// Zod schema, the source of truth for what parameters it actually accepts
+// (fw#2165). A hand-written `searchable: true` still wins over the derived
+// default (screen.searchable ?? derived); the boot-validator (3a) rejects
+// one that contradicts the schema.
+function projectScreens(
+  screens: Readonly<Record<string, ScreenDefinition>>,
+  registry: Registry,
+): ScreenDefinition[] {
+  return Object.values(screens).map((screen) =>
+    screen.type === "projectionList" ? projectProjectionListScreen(screen, registry) : screen,
+  );
+}
+
+function projectProjectionListScreen(
+  screen: ProjectionListScreenDefinition,
+  registry: Registry,
+): ProjectionListScreenDefinition {
+  const schema = registry.getQueryHandler(screen.query)?.schema;
+  const capabilities = deriveProjectionListCapabilities(schema);
+  return {
+    ...screen,
+    searchable: screen.searchable ?? capabilities.searchable,
+    sortable: capabilities.sortable,
+    paginated: capabilities.paginated,
+  };
+}
+
+// Zod v4: a ZodObject's param names live on `.shape`. A schema that isn't a
+// ZodObject (e.g. a z.union across payload shapes) yields no capability
+// instead of throwing — same as a missing/unresolved query handler.
+function deriveProjectionListCapabilities(schema: ZodType | undefined): {
+  searchable: boolean;
+  sortable: boolean;
+  paginated: boolean;
+} {
+  const shape = schema instanceof ZodObject ? schema.shape : undefined;
+  return {
+    searchable: shape !== undefined && "search" in shape,
+    sortable: shape !== undefined && "sort" in shape,
+    paginated: shape !== undefined && ("cursor" in shape || "offset" in shape),
+  };
+}
+
 function projectEntities(
   entities: Readonly<Record<string, EntityDefinition>>,
 ): Readonly<Record<string, EntityDefinition>> {