@cosmicdrift/kumiko-framework 0.202.0 → 0.204.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.202.0",
+  "version": "0.204.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.204.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.204.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/db/sql-inventory.ts

@@ -48,7 +48,22 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /\/packages\/framework\/src\/db\/sql-inventory\.ts$/,
   /\/packages\/framework\/src\/bun-db\/query\.ts$/,
   /\/packages\/framework\/src\/testing\//,
-  /\/packages\/bundled-features\/src\/[^/]+\/db\/queries\//,
+  // ponytail: explicit enumeration — blanket regex auto-allowed any new .unsafe()
+  /\/bundled-features\/src\/billing-foundation\/db\/queries\/subscription-projection\.ts$/,
+  /\/bundled-features\/src\/config\/db\/queries\/resolver\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/field-access\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/projection\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/quota\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/retention\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/user-data-rights\.ts$/,
+  /\/bundled-features\/src\/delivery\/db\/queries\/preferences\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/cleanup\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/draft-count\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
+  /\/bundled-features\/src\/inbound-mail-foundation\/db\/queries\/inbound-projections\.ts$/,
+  /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
+  /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
+  /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
   /\/packages\/framework\/src\/engine\/steps\/unsafe-projection-/,
   /\/samples\/(apps|recipes)\/[^/]+\/src\/db\/queries\//,
   /\/bin\/commands\//,

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() } }));
@@ -218,6 +240,30 @@ describe("validateBoot — action wiring (no function values)", () => {
     expect(() => validateBoot([feature])).toThrow(/column "amount" renderer is a function/);
   });
 
+  test("projectionDetail relatedList column renderer as function → Throw (fw#2166)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.screen({
+        id: "order-detail",
+        type: "projectionDetail",
+        query: "shop:query:order:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Payments",
+              query: "shop:query:order:payments",
+              columns: [
+                // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+                { field: "amount", renderer: ((v: unknown) => String(v)) as any },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/column "amount" renderer is a function/);
+  });
+
   test("projectionList rowAction payload as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
       r.screen({

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", () => {