@cosmicdrift/kumiko-framework 0.201.0 → 0.203.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.201.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>",
@@ -87,6 +87,10 @@
       "types": "./src/i18n/index.ts",
       "default": "./src/i18n/index.ts"
     },
+    "./http": {
+      "types": "./src/http/index.ts",
+      "default": "./src/http/index.ts"
+    },
     "./auth": {
       "types": "./src/auth/index.ts",
       "default": "./src/auth/index.ts"
@@ -186,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.201.0",
+    "@cosmicdrift/kumiko-types": "0.203.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.201.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.203.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/api-constants-completeness.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS, Routes } from "../api-constants";
+
+// PUBLIC_API_PATHS is an allowlist: a missing entry (typo, forgotten route)
+// fails CLOSED — the route stays behind auth, never accidentally public.
+// But the classification itself must be total, or a route silently falls
+// into a third, unchecked state that nobody notices until it's either
+// exploited (should've been non-public) or reported broken by a client
+// (should've been public). This test forces every `Routes` entry into
+// exactly one of the two sets, in both directions:
+//   - every Routes entry has a classification (no silent gap)
+//   - every classified path still corresponds to a real Routes entry (no
+//     stale/typo'd literal drifting out of sync with Routes)
+function classifyRoutes(routes: Record<string, string>): {
+  unclassified: string[];
+  classifiedInBoth: string[];
+} {
+  const unclassified: string[] = [];
+  const classifiedInBoth: string[] = [];
+
+  for (const routePath of Object.values(routes)) {
+    const apiPath = `/api${routePath}`;
+    const isPublic = PUBLIC_API_PATHS.has(apiPath);
+    const isNonPublic = NON_PUBLIC_API_PATHS.has(apiPath);
+    if (isPublic && isNonPublic) classifiedInBoth.push(apiPath);
+    else if (!isPublic && !isNonPublic) unclassified.push(apiPath);
+  }
+
+  return { unclassified, classifiedInBoth };
+}
+
+describe("Routes / PUBLIC_API_PATHS classification completeness", () => {
+  test("every Routes entry is classified as exactly public XOR non-public", () => {
+    const { unclassified, classifiedInBoth } = classifyRoutes(Routes);
+
+    expect(unclassified).toEqual([]);
+    expect(classifiedInBoth).toEqual([]);
+  });
+
+  test("every PUBLIC_API_PATHS / NON_PUBLIC_API_PATHS entry maps back to a real Routes value", () => {
+    const knownApiPaths = new Set(Object.values(Routes).map((routePath) => `/api${routePath}`));
+
+    const stalePublic = [...PUBLIC_API_PATHS].filter((path) => !knownApiPaths.has(path));
+    const staleNonPublic = [...NON_PUBLIC_API_PATHS].filter((path) => !knownApiPaths.has(path));
+
+    expect(stalePublic).toEqual([]);
+    expect(staleNonPublic).toEqual([]);
+  });
+
+  // Regression guard for the mechanism itself: proves the completeness
+  // check actually fails when a route is added without a classification,
+  // rather than the two tests above being vacuously true by construction.
+  test("regression: an unclassified route is detected", () => {
+    const routesWithGap = {
+      ...Routes,
+      newFeature: "/new-feature-without-classification",
+    };
+
+    const { unclassified } = classifyRoutes(routesWithGap);
+
+    expect(unclassified).toEqual(["/api/new-feature-without-classification"]);
+  });
+});

package/src/api/__tests__/body-limit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "../api-constants";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -86,10 +87,12 @@ describe("request body limit", () => {
     expect(res.status).toBe(401); // passes body-limit, reaches auth
   });
 
-  // Security regression (2026-08-13 audit, Finding 2): /api/stream was
-  // missing from BODY_LIMIT_PATHS, so it dispatched to the dispatcher
-  // without ever hitting the same 1MB cap /api/write enforces. Mirrors the
-  // /api/write cases above.
+  // Security regression (2026-08-13 audit, Finding 2): /api/stream used to be
+  // missing from the old BODY_LIMIT_PATHS allowlist, so it dispatched to the
+  // dispatcher without ever hitting the same 1MB cap /api/write enforces.
+  // Mirrors the /api/write cases above. Now covered structurally (see
+  // "default coverage sweep" below), kept as its own test for the historical
+  // regression it documents.
   test("rejects POST /api/stream with body larger than maxRequestBytes with 413 (mirrors /api/write)", async () => {
     const app = buildApp(1024);
     const res = await postJson(app, "/api/stream", 2048);
@@ -102,3 +105,74 @@ describe("request body limit", () => {
     expect(res.status).toBe(401); // no JWT → 401, but size is fine
   });
 });
+
+// fw#2145: BODY_LIMIT_PATHS inverted from an opt-in allowlist to an opt-out
+// list — registerBodyLimit now mounts on /api/* by construction, and only
+// BODY_LIMIT_OPT_OUT_PATHS (api-constants.ts) escapes it. These tests prove
+// that inversion rather than re-testing individual paths.
+describe("body-limit opt-out completeness", () => {
+  test("every opt-out entry resolves to a real Routes constant (no stale/typo'd paths)", () => {
+    for (const optOutPath of BODY_LIMIT_OPT_OUT_PATHS) {
+      const matchesKnownRoute = Object.values(Routes).some(
+        (route) => `/api${route}` === optOutPath,
+      );
+      expect(matchesKnownRoute).toBe(true);
+    }
+  });
+
+  test("the opt-out list is pinned to its reviewed members — a new exception must touch this test", () => {
+    expect([...BODY_LIMIT_OPT_OUT_PATHS]).toEqual([`/api${Routes.files}`]);
+  });
+});
+
+describe("default coverage sweep — proves the default, not a hand-maintained list", () => {
+  const OVERSIZED_BYTES = 2_000_000; // exceeds the default 1 MiB cap
+
+  // Derived from Routes itself (minus opt-out) rather than a hand-picked
+  // list — a route added to Routes tomorrow lands in this sweep
+  // automatically, with no test file to remember to update. Includes routes
+  // this test app never mounts (e.g. authLogin, no `auth` option passed to
+  // buildServer) and routes whose GET handler is mounted outside /api/*
+  // (health, healthReady, version — registerHealthRoutes/registerVersionRoute
+  // mount at the bare path, not under /api). Both still 413 on an oversized
+  // POST here: the /api/* body-limit middleware matches on path prefix
+  // before Hono resolves a handler, so it runs whether or not a route
+  // answers underneath. Verified directly: `POST /api/health` 413s even
+  // though the only real handler lives at `GET /health`.
+  const defaultLimitedRoutes = Object.values(Routes).filter(
+    (route) => !BODY_LIMIT_OPT_OUT_PATHS.has(`/api${route}`),
+  );
+
+  for (const route of defaultLimitedRoutes) {
+    test(`POST /api${route} 413s on an oversized body without needing its own list entry`, async () => {
+      const app = buildApp();
+      const res = await postJson(app, `/api${route}`, OVERSIZED_BYTES);
+      expect(res.status).toBe(413);
+    });
+  }
+
+  test("POST /api/files does not 413 on an oversized JSON body (explicit opt-out)", async () => {
+    const app = buildApp();
+    const res = await postJson(app, "/api/files", OVERSIZED_BYTES);
+    expect(res.status).not.toBe(413);
+  });
+
+  // Regression for the DoD: "neue Route ohne Eintrag in irgendeiner Liste
+  // bekommt automatisch ein Limit". Mounts a route the same way an app-owner's
+  // `extraRoutes` callback would — after buildServer, with zero Routes/
+  // opt-out entries — and proves it inherits the cap AND still serves a
+  // small body correctly (not an accidental always-413).
+  test("a route mounted after buildServer with no list entry anywhere still inherits the default limit", async () => {
+    const app = buildApp();
+    app.post("/api/totally-new-route-nobody-listed", async (c) => c.json({ ok: true }));
+
+    const oversized = await postJson(app, "/api/totally-new-route-nobody-listed", OVERSIZED_BYTES);
+    expect(oversized.status).toBe(413);
+
+    // Small body passes the size cap and reaches the auth guard (401, no
+    // JWT) — proves the 413 above is the size cap doing its job, not the
+    // route being unreachable for some unrelated reason.
+    const small = await postJson(app, "/api/totally-new-route-nobody-listed", 10);
+    expect(small.status).toBe(401);
+  });
+});

package/src/api/__tests__/server-jwt-ttl.test.ts

@@ -21,7 +21,7 @@ describe("buildServer — jwtTtl default depends on sessionChecker wiring", () =
     expect(jwt.ttlSeconds).toBe(60 * 60);
   });
 
-  test("auth with sessionChecker → session-backed default (24h)", () => {
+  test("auth with sessionChecker → session-backed default (8h)", () => {
     const { jwt } = buildServer({
       registry,
       context: {},
@@ -31,7 +31,7 @@ describe("buildServer — jwtTtl default depends on sessionChecker wiring", () =
         sessionChecker: async () => "live",
       },
     });
-    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+    expect(jwt.ttlSeconds).toBe(8 * 60 * 60);
   });
 
   test("explicit jwtTtl wins regardless of sessionChecker wiring", () => {

package/src/api/api-constants.ts

@@ -27,10 +27,10 @@ export const Routes = {
   authConfirmAccountUnlock: "/auth/confirm-account-unlock",
   authSignupRequest: "/auth/signup-request",
   authSignupConfirm: "/auth/signup-confirm",
-  // Tenant-Invite (Magic-Link): 3 separate accept-Endpoints für klare
-  // Branch-Separation. Plus invite-info als public-readable details
-  // damit das Frontend "Du wirst eingeladen zu Tenant X als Role Y"
-  // anzeigen kann bevor der User submitted.
+  // Tenant invite (magic link): 3 separate accept endpoints for clear
+  // branch separation. Plus invite-info as public-readable details so
+  // the frontend can show "You're invited to tenant X as role Y" before
+  // the user submits.
   authInviteAccept: "/auth/invite-accept",
   authInviteAcceptWithLogin: "/auth/invite-accept-with-login",
   authInviteSignupComplete: "/auth/invite-signup-complete",
@@ -53,9 +53,9 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authConfirmAccountUnlock}`,
   `/api${Routes.authSignupRequest}`,
   `/api${Routes.authSignupConfirm}`,
-  // invite-accept braucht JWT (logged-in User, Branch 1) — NICHT public.
-  // invite-accept-with-login (Branch 2) und invite-signup-complete
-  // (Branch 3) sind anonymous, brauchen public-skip.
+  // invite-accept requires a JWT (logged-in user, branch 1) — NOT public.
+  // invite-accept-with-login (branch 2) and invite-signup-complete
+  // (branch 3) are anonymous and need the public skip.
   `/api${Routes.authInviteAcceptWithLogin}`,
   `/api${Routes.authInviteSignupComplete}`,
   `/api${Routes.authInviteInfo}`,
@@ -64,6 +64,43 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.version}`,
 ]);
 
+// Every other route in `Routes` — explicit, so a route can never fall
+// through to "public" by simply being absent from PUBLIC_API_PATHS. A
+// completeness test checks every `Routes` entry against the union of this
+// set and PUBLIC_API_PATHS, so a new route with neither entry fails CI
+// instead of shipping open.
+export const NON_PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
+  `/api${Routes.write}`,
+  `/api${Routes.batch}`,
+  `/api${Routes.query}`,
+  `/api${Routes.command}`,
+  `/api${Routes.sse}`,
+  `/api${Routes.stream}`,
+  // Namespace prefix used only for body-limit registration
+  // (`/api/auth/*` in route-registrars.ts) — never dispatched as its own
+  // route, so it carries no auth bypass either way. Classified non-public
+  // to keep the completeness check total.
+  `/api${Routes.auth}`,
+  `/api${Routes.authLogout}`,
+  `/api${Routes.authTenants}`,
+  `/api${Routes.authSwitchTenant}`,
+  // invite-accept requires a JWT (Branch 1, see PUBLIC_API_PATHS above).
+  `/api${Routes.authInviteAccept}`,
+  `/api${Routes.files}`,
+]);
+
+// Opt-out from the default request-body-size cap (registerBodyLimit applies
+// it to all of /api/* by construction — a new route needs no entry here to
+// be covered). Only routes with their own, deliberately different size
+// contract belong on this list; forgetting an entry is safe (over-limited,
+// not unlimited), so keep it as short as the actual exceptions.
+export const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string> = new Set([
+  // Multipart uploads validate size against `maxUploadSize`/field `maxSize`
+  // (often >1 MiB) after Hono's multipart parse, not before — the generic
+  // JSON cap would reject legitimate uploads before that check ever runs.
+  `/api${Routes.files}`,
+]);
+
 // Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
 // CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
 export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([

package/src/api/auth-middleware.ts

@@ -35,6 +35,17 @@ export type AuthTransport = "cookie" | "bearer";
 // can't keep a locked account authenticated.
 export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "blocked";
 
+// A "live" result may additionally carry roles re-derived fresh from the DB
+// (global user roles + tenant-membership roles, composed via
+// buildSessionRoles) instead of trusting the JWT's roles claim, which was
+// frozen at login/mint time. Bare "live" (no roles) is the fail-open path —
+// a DB throw during role derivation must not turn into a lockout — and the
+// case where no sessionChecker is wired at all; the middleware falls back to
+// payload.roles in both.
+export type AuthSessionCheckResult =
+  | AuthSessionStatus
+  | { readonly status: "live"; readonly roles: readonly string[] };
+
 // Called by the middleware after JWT-verify. Gets the sid AND the expected
 // userId from the JWT's `sub` — the checker MUST confirm the session row
 // both exists + is live AND belongs to expectedUserId. Without the userId
@@ -45,7 +56,7 @@ export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "bl
 export type AuthSessionChecker = (
   sid: string,
   expectedUserId: string,
-) => Promise<AuthSessionStatus>;
+) => Promise<AuthSessionCheckResult>;
 
 // Resolves a raw bearer token into a SessionUser, or null when no registered
 // provider claims it (or the claiming provider rejects it as unknown/revoked/
@@ -276,12 +287,17 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     // token carries a sid.
     // A checker wired without a sid on the token means the token predates
     // session tracking (or the JWT was forged) — reject.
+    let derivedRoles: readonly string[] | undefined;
     if (sessionChecker) {
       if (payload.jti) {
-        const status = await sessionChecker(payload.jti, payload.sub);
+        const result = await sessionChecker(payload.jti, payload.sub);
+        const status = typeof result === "string" ? result : result.status;
         if (status !== "live") {
           return sessionInvalid(c, status);
         }
+        if (typeof result === "object") {
+          derivedRoles = result.roles;
+        }
       } else {
         return sessionInvalid(c, "no_sid");
       }
@@ -306,7 +322,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     const user: SessionUser = {
       id: payload.sub,
       tenantId: payload.tenantId,
-      roles: payload.roles,
+      roles: derivedRoles ?? payload.roles,
       ...(payload.timezone ? { timezone: payload.timezone } : {}),
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),

package/src/api/index.ts

@@ -5,6 +5,7 @@ export type {
   AnonymousAccessResolved,
   AuthMiddlewareOptions,
   AuthSessionChecker,
+  AuthSessionCheckResult,
   AuthSessionStatus,
   TenantExists,
   TenantLifecycleStatusResolver,

package/src/api/route-registrars.ts

@@ -11,7 +11,7 @@ import type { Lifecycle } from "../lifecycle";
 import type { Meter, PrometheusMeter } from "../observability";
 import { serializeOpenMetrics } from "../observability";
 import type { EventConsumer } from "../pipeline/event-dispatcher";
-import { Routes } from "./api-constants";
+import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "./api-constants";
 import {
   createReadinessProbe,
   dbPingCheck,
@@ -22,28 +22,26 @@ import {
 
 // --- Body size limit ------------------------------------------------------
 
-const BODY_LIMIT_PATHS = [
-  `/api${Routes.write}`,
-  `/api${Routes.batch}`,
-  `/api${Routes.query}`,
-  `/api${Routes.command}`,
-  `/api${Routes.stream}`,
-  `/api${Routes.auth}/*`,
-] as const;
-
 export const DEFAULT_MAX_REQUEST_BYTES = 1_048_576;
 
-// Cap JSON bodies on /api/write + /api/batch + /api/query + /api/command
-// + /api/stream + /api/auth/*. File uploads keep their own per-field
-// maxSize. `0` disables the limit entirely — only useful when a
-// reverse-proxy caps upstream or tests want raw passthrough.
+// Cap every /api/* request body by default — a new route needs no entry
+// anywhere to be covered, it inherits the limit from being registered under
+// /api at all. Routes with their own size contract (currently just uploads)
+// opt out explicitly via BODY_LIMIT_OPT_OUT_PATHS in api-constants.ts;
+// forgetting an opt-out entry only over-limits a route, forgetting to add a
+// new route to an allowlist used to leave it unlimited — that inversion is
+// the point. `maxBytes <= 0` disables the limit entirely — only useful when
+// a reverse-proxy caps upstream or tests want raw passthrough.
 export function registerBodyLimit(app: Hono, maxBytes: number): void {
   // skip: opt-out path — caller passed `maxBytes: 0`, so no middleware
   // is attached (upstream cap via reverse-proxy is expected). Not a bug
   // suppression, an intentional disable.
   if (maxBytes <= 0) return;
   const limit = bodyLimit({ maxSize: maxBytes });
-  for (const path of BODY_LIMIT_PATHS) app.use(path, limit);
+  app.use("/api/*", async (c, next) => {
+    if (BODY_LIMIT_OPT_OUT_PATHS.has(c.req.path)) return next();
+    return limit(c, next);
+  });
 }
 
 // --- /metrics (Prometheus scrape) -----------------------------------------
@@ -101,14 +99,13 @@ export function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRo
 
 // --- /version ---------------------------------------------------------------
 
-// Anonymous endpoint that returns build-identity. Used by ops-tooling
-// (prod-version.sh) und Telegram-deploy-Notification damit man nicht
-// kubectl + crictl auf den Master braucht um die deployed-Version zu
-// sehen.
+// Anonymous endpoint that returns build-identity. Used by ops tooling
+// (prod-version.sh) and the Telegram deploy notification so nobody needs
+// kubectl + crictl on the master to see the deployed version.
 //
-// BUILD_VERSION + BUILD_TIME werden vom Dockerfile (ARG → ENV)
-// durchgereicht — fallen zurück auf "dev" / "unknown" wenn lokal ohne
-// Build-args gebaut.
+// BUILD_VERSION + BUILD_TIME are passed through from the Dockerfile
+// (ARG → ENV) — fall back to "dev" / "unknown" when built locally
+// without build-args.
 export function registerVersionRoute(app: Hono): void {
   const version = process.env["BUILD_VERSION"] ?? "dev";
   const buildTime = process.env["BUILD_TIME"] ?? "unknown";

package/src/api/server.ts

@@ -310,7 +310,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
   // TTL than session-backed ones, since a leaked stateless token can't be
   // revoked and stays valid until it expires. Explicit jwtTtl always wins.
-  const defaultJwtTtl = options.auth?.sessionChecker ? 24 * 60 * 60 : 60 * 60;
+  const defaultJwtTtl = options.auth?.sessionChecker ? 8 * 60 * 60 : 60 * 60;
   const jwt = createJwtHelper(
     options.jwtSecret,
     options.jwtIssuer,

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() } }));