@cosmicdrift/kumiko-framework 0.200.0 → 0.201.0

package/package.json

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

package/src/__tests__/entity-list-limits.integration.test.ts

@@ -0,0 +1,84 @@
+// Security regression (2026-08-13 audit, Finding 3): entityListSchema's
+// `limit`/`offset` used to accept fractional/oversized numbers, which flowed
+// unvalidated into a raw `LIMIT ${limit} OFFSET ${offset}` SQL string
+// (event-store-executor-read.ts) — a non-integer literal 500s, and an
+// unbounded limit forces a full-table materialisation.
+//
+// Bun.SQL-only setup via setupTestStack.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineFeature,
+  MAX_LIST_LIMIT,
+} from "../engine";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
+
+const widgetEntity = createEntity({
+  table: "limit_widgets",
+  fields: { name: createTextField({ required: true }) },
+});
+
+const widgetFeature = defineFeature("limitwidgets", (r) => {
+  r.entity("widget", widgetEntity);
+  r.writeHandler(
+    defineEntityCreateHandler("widget", widgetEntity, { access: { roles: ["Admin"] } }),
+  );
+  r.queryHandler(defineEntityListHandler("widget", widgetEntity, { access: { roles: ["Admin"] } }));
+});
+
+describe("entity list limit/offset validation", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [widgetFeature] });
+    await unsafeCreateEntityTable(stack.db, widgetEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("fractional limit is rejected with 400, not a 500 from the raw SQL LIMIT", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { limit: 99999.5 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+
+  test("negative offset is rejected with 400, not a 500 from the raw SQL OFFSET", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { offset: -1 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+
+  test("limit above MAX_LIST_LIMIT is rejected with 400", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { limit: MAX_LIST_LIMIT + 1 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+
+  test("limit at MAX_LIST_LIMIT and a valid offset succeed", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { limit: MAX_LIST_LIMIT, offset: 0 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+  });
+});

package/src/api/__tests__/api.test.ts

@@ -12,7 +12,7 @@ import {
 import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
 import { createTestUser, TestUsers } from "../../stack";
 import { waitFor } from "../../testing";
-import { createApiRoutes, pumpStream, StreamFrame } from "../routes";
+import { createApiRoutes, MAX_PAYLOAD_DEPTH, pumpStream, StreamFrame } from "../routes";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -236,6 +236,121 @@ describe("POST /api/command", () => {
   });
 });
 
+// --- Payload depth cap (security, 2026-08-13 audit Finding 1) ---
+//
+// A byte-limit on the body doesn't stop an attacker from nesting deeply
+// enough to blow the stack during recursive Zod validation — a minified
+// payload with thousands of nested wrappers stays well under 1MB. The
+// depth-cap in routes.ts walks the parsed object BEFORE it reaches any
+// handler's Zod schema, so it applies independently of what that schema
+// actually expects.
+
+function nestedPayload(depth: number): unknown {
+  let value: unknown = "leaf";
+  for (let i = 0; i < depth; i++) value = { nested: value };
+  return value;
+}
+
+describe("payload depth cap", () => {
+  test("rejects /api/write payload nested past MAX_PAYLOAD_DEPTH with 400 payload_too_deep", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("validation_error");
+    expect(body.error.details.fields[0]).toMatchObject({
+      path: "payload",
+      code: "too_deep",
+      i18nKey: "errors.validation.payload_too_deep",
+    });
+  });
+
+  test("a payload nested exactly at MAX_PAYLOAD_DEPTH clears the cap (fails ordinary schema validation instead)", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH) },
+      headers,
+    );
+
+    // Still 400 — "name" is missing from this payload — but NOT via the
+    // depth cap. Proves the cap's boundary is exactly MAX_PAYLOAD_DEPTH.
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields.some((f: { code: string }) => f.code === "too_deep")).toBe(
+      false,
+    );
+  });
+
+  test("rejects /api/query payload nested past MAX_PAYLOAD_DEPTH with 400", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/query",
+      { type: "test:query:item:list", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+
+  test("rejects /api/command payload nested past MAX_PAYLOAD_DEPTH with 400", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/command",
+      { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+
+  test("rejects an /api/batch command payload nested past MAX_PAYLOAD_DEPTH with 400", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/batch",
+      {
+        commands: [
+          { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+        ],
+      },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+
+  test("rejects /api/stream payload nested past MAX_PAYLOAD_DEPTH with 400, not an SSE error frame", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+});
+
 // --- pumpStream (SSE pull loop) ---
 
 function fakeSseWriter() {

package/src/api/__tests__/batch.integration.test.ts

@@ -50,6 +50,9 @@ const afterCommitHookLog: Array<{ id: EntityId; name: string }> = [];
 let afterCommitShouldThrow = false;
 const afterCommitThirdHookRan: string[] = [];
 
+// Delay injected into item:create-slow — reset per test.
+let slowHandlerDelayMs = 0;
+
 const itemFeature = defineFeature("batch", (r) => {
   const item = r.entity("item", itemEntity);
 
@@ -81,6 +84,21 @@ const itemFeature = defineFeature("batch", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  // Handler with a controllable delay — used to simulate a slow in-flight
+  // handler for the parallel-idempotency race test.
+  r.writeHandler(
+    "item:create-slow",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      if (slowHandlerDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, slowHandlerDelayMs));
+      }
+      const crud = createEventStoreExecutor(itemTable, itemEntity, { entityName: "item" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // Entity hook: inTransaction — records in memory
   r.hook(
     "postSave",
@@ -405,6 +423,41 @@ describe("POST /api/batch", () => {
     expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
   });
 
+  test("idempotency: parallel writes with the same requestId — second waits for the first instead of re-executing", async () => {
+    slowHandlerDelayMs = 250;
+    const requestId = "batch-rid-parallel-slow";
+    const commands = [{ type: "batch:write:item:create-slow", payload: { name: "parallel-once" } }];
+
+    try {
+      const [first, second] = await Promise.all([
+        stack.http.batch(commands, admin, requestId),
+        (async () => {
+          // Give request #1 a head start so it wins the lock acquisition —
+          // the race being tested is "#2 waits", not "who acquires first".
+          await new Promise((resolve) => setTimeout(resolve, 50));
+          return stack.http.batch(commands, admin, requestId);
+        })(),
+      ]);
+
+      const firstBody = await first.json();
+      const secondBody = await second.json();
+
+      expect(firstBody.isSuccess).toBe(true);
+      expect(secondBody.isSuccess).toBe(true);
+      // Same cached response, not a fresh execution.
+      expect(secondBody.results).toEqual(firstBody.results);
+
+      // Exactly one row and one hook run — the second call did not re-run
+      // the handler and create a duplicate side effect.
+      const rows = await selectMany(stack.db, itemTable);
+      expect(rows).toHaveLength(1);
+      expect(inTxHookLog).toHaveLength(1);
+      expect(afterCommitHookLog).toHaveLength(1);
+    } finally {
+      slowHandlerDelayMs = 0;
+    }
+  });
+
   test("idempotency: corrupted cache entry is treated as miss and re-runs", async () => {
     const requestId = "batch-rid-corrupt";
     const cacheKey = `${RedisKeys.idempotency}${admin.tenantId}:${admin.id}:${requestId}`;

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

@@ -85,4 +85,20 @@ describe("request body limit", () => {
     const res = await postJson(app, "/api/write", 50_000);
     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.
+  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);
+    expect(res.status).toBe(413);
+  });
+
+  test("accepts POST /api/stream with body within the limit (reaches auth layer, not 413)", async () => {
+    const app = buildApp(10_000);
+    const res = await postJson(app, "/api/stream", 100);
+    expect(res.status).toBe(401); // no JWT → 401, but size is fine
+  });
 });

package/src/api/route-registrars.ts

@@ -27,15 +27,16 @@ const BODY_LIMIT_PATHS = [
   `/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/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.
+// + /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.
 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

package/src/api/routes.ts

@@ -45,6 +45,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown; requestId?: string }>();
 
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
       const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
       if (!result.isSuccess) {
@@ -83,6 +84,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     }
 
     try {
+      for (const cmd of body.commands) assertPayloadDepthAllowed(cmd.payload);
       if (user.pat) {
         for (const cmd of body.commands) assertPatAllowed(user, cmd.type);
       }
@@ -120,6 +122,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
       const result = await dispatcher.query(body.type, body.payload, user);
       return jsonResponse(c, { data: result });
@@ -133,6 +136,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown }>();
 
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
       await dispatcher.command(body.type, body.payload, user);
       return c.json({ ok: true }, 202);
@@ -156,9 +160,11 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
     const body = await c.req.json<{ type: string; payload: unknown }>();
     const requestId = requestContext.get()?.requestId;
 
-    const generator = dispatcher.stream(body.type, body.payload, user);
+    let generator: AsyncGenerator<unknown>;
     try {
+      assertPayloadDepthAllowed(body.payload);
       assertPatAllowed(user, body.type);
+      generator = dispatcher.stream(body.type, body.payload, user);
     } catch (e) {
       return queryErrorResponse(c, toKumiko(e), body.type);
     }
@@ -274,6 +280,46 @@ function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode =
 
 const toKumiko = toKumikoError;
 
+// Nesting cap for request payloads — an object-walk, not a string/byte
+// check, since an attacker fully controls whitespace/formatting and a
+// minified deeply-nested payload can stay well under the byte limit while
+// still blowing the stack on recursive Zod parsing / jsonb serialization.
+export const MAX_PAYLOAD_DEPTH = 20;
+
+function payloadDepth(value: unknown, depth: number): number {
+  if (depth > MAX_PAYLOAD_DEPTH || value === null || typeof value !== "object") {
+    return depth;
+  }
+  const children = Array.isArray(value) ? value : Object.values(value);
+  let max = depth;
+  for (const child of children) {
+    const childDepth = payloadDepth(child, depth + 1);
+    if (childDepth > max) max = childDepth;
+    if (max > MAX_PAYLOAD_DEPTH) break;
+  }
+  return max;
+}
+
+// Rejects payloads nested deeper than MAX_PAYLOAD_DEPTH before they reach
+// per-handler Zod validation — recursive Zod parsing (and any downstream
+// jsonb serialization of custom-fields payloads) walks the same object
+// graph an attacker controls, so an uncapped depth is a stack-overflow /
+// CPU-DoS vector even under the 1MB body-byte limit.
+function assertPayloadDepthAllowed(payload: unknown): void {
+  if (payloadDepth(payload, 0) > MAX_PAYLOAD_DEPTH) {
+    throw new ValidationError({
+      fields: [
+        {
+          path: "payload",
+          code: "too_deep",
+          i18nKey: "errors.validation.payload_too_deep",
+          params: { maxDepth: MAX_PAYLOAD_DEPTH },
+        },
+      ],
+    });
+  }
+}
+
 // PAT scope enforcement at the API boundary. No-op for cookie/JWT users
 // (user.pat undefined → unrestricted). For a PAT-authenticated request the
 // dispatch type must match one of the token's granted-scope QN globs, else

package/src/db/__tests__/unchecked-system-db.test.ts

@@ -114,4 +114,70 @@ describe("createUncheckedSystemDb", () => {
       expect(() => unchecked.acknowledgeCrossTenant("   ")).toThrow(/non-empty reason/);
     });
   });
+
+  describe("outsideTransaction", () => {
+    describe("assertTenantMatch", () => {
+      test("returns the outside-transaction TenantDb, not the in-tx one, when the tenantId matches", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        const result = unchecked.outsideTransaction.assertTenantMatch(own);
+        expect(result).toBe(outsideTxDb);
+        expect(result).not.toBe(systemDb);
+      });
+
+      test("throws AccessDeniedError when the tenantId doesn't match", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        expect(() => unchecked.outsideTransaction.assertTenantMatch(foreign)).toThrow(
+          /outsideTransaction tenant self-check failed/,
+        );
+      });
+
+      test("throws when no outside-transaction db was configured, even for a matching tenantId", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb);
+
+        expect(() => unchecked.outsideTransaction.assertTenantMatch(own)).toThrow(
+          /no outside-transaction database source is configured/,
+        );
+      });
+    });
+
+    describe("acknowledgeCrossTenant", () => {
+      test("returns the outside-transaction TenantDb without comparing tenants when given a reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        const result = unchecked.outsideTransaction.acknowledgeCrossTenant(
+          "durability write is cross-tenant by design",
+        );
+        expect(result).toBe(outsideTxDb);
+        expect(result).not.toBe(systemDb);
+      });
+
+      test("throws on an empty reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const outsideTxDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb, outsideTxDb);
+
+        expect(() => unchecked.outsideTransaction.acknowledgeCrossTenant("")).toThrow(
+          /non-empty reason/,
+        );
+      });
+
+      test("throws when no outside-transaction db was configured, even with a valid reason", () => {
+        const systemDb = createTenantDb(unusedRunner(), own, "system");
+        const unchecked = createUncheckedSystemDb(systemDb);
+
+        expect(() => unchecked.outsideTransaction.acknowledgeCrossTenant("valid reason")).toThrow(
+          /no outside-transaction database source is configured/,
+        );
+      });
+    });
+  });
 });

package/src/db/tenant-db.ts

@@ -17,7 +17,7 @@ import {
   type WhereObject,
 } from "../db/query";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
-import { AccessDeniedError } from "../errors";
+import { AccessDeniedError, InternalError } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 
@@ -32,9 +32,35 @@ export {
 
 // buildHandlerContext (pipeline/dispatch-shared.ts) always builds "system"
 // mode from the caller's own tenantId, never a foreign one.
-export function createUncheckedSystemDb(db: TenantDb): UncheckedSystemDb {
+//
+// dbOutsideTransaction is optional so every existing single-arg call site
+// (jobs, tests, delivery-service.ts) keeps compiling — those callers have no
+// outside-tx source to hand in and never needed one. Only
+// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
+// is reachable through `ctx.systemDb`.
+export function createUncheckedSystemDb(
+  db: TenantDb,
+  dbOutsideTransaction?: TenantDb,
+): UncheckedSystemDb {
   const allowedTenantIds: readonly TenantId[] = [db.tenantId, SYSTEM_TENANT_ID];
 
+  // Fails closed instead of falling back to the in-tx `db` — a silent
+  // fallback would defeat the point of a durability write that must survive
+  // a rollback of the handler's own transaction. InternalError (not
+  // AccessDeniedError) because this is a dispatch wiring fault, not a
+  // tenant-access denial — mirrors the "no database connection configured"
+  // case in dispatch-shared.ts's appendDomainEvent.
+  function requireOutsideTransactionDb(): TenantDb {
+    if (!dbOutsideTransaction) {
+      throw new InternalError({
+        message:
+          "systemScope() outsideTransaction check failed: no outside-transaction database " +
+          "source is configured for this dispatch.",
+      });
+    }
+    return dbOutsideTransaction;
+  }
+
   return {
     [SYSTEM_SCOPE_CHECK_BRAND]: true,
 
@@ -68,6 +94,24 @@ export function createUncheckedSystemDb(db: TenantDb): UncheckedSystemDb {
       }
       return db;
     },
+
+    outsideTransaction: {
+      assertTenantMatch(tenantId) {
+        if (tenantId !== db.tenantId) {
+          throw new AccessDeniedError({
+            message: `systemScope() outsideTransaction tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
+          });
+        }
+        return requireOutsideTransactionDb();
+      },
+
+      acknowledgeCrossTenant(reason) {
+        if (reason.trim().length === 0) {
+          throw new Error("acknowledgeCrossTenant requires a non-empty reason");
+        }
+        return requireOutsideTransactionDb();
+      },
+    },
   };
 }
 

package/src/engine/entity-handlers.ts

@@ -102,9 +102,16 @@ type ListPayload = {
 };
 
 const idSchema = z.object({ id: z.uuid() });
+
+// Upper bound on entity-list `limit`: unbounded/fractional values ran
+// straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
+// read.ts), letting a client demand a full-table materialisation or trip a
+// Postgres syntax error on a non-integer literal.
+export const MAX_LIST_LIMIT = 200;
+
 export const entityListSchema = z.object({
   cursor: z.string().optional(),
-  limit: z.number().optional(),
+  limit: z.number().int().nonnegative().max(MAX_LIST_LIMIT).optional(),
   search: z.string().optional(),
   sort: z.string().optional(),
   sortDirection: z.enum(["asc", "desc"]).optional(),

package/src/engine/feature-ast/__tests__/fixtures/cross-file-patch-const/constants.ts

@@ -0,0 +1,2 @@
+export const EXT_TENANT_DATA = "tenant-data" as const;
+export const ENTITY_ITEM = "item" as const;

package/src/engine/feature-ast/__tests__/fixtures/cross-file-patch-const/feature.ts

@@ -0,0 +1,8 @@
+import { ENTITY_ITEM, EXT_TENANT_DATA } from "./constants";
+
+// biome-ignore lint/suspicious/noExplicitAny: structural parser test fixture, never executed or type-checked at runtime
+declare function defineFeature(name: string, setup: (r: any) => void): void;
+
+defineFeature("cross-file-patch-const", (r) => {
+  r.useExtension(EXT_TENANT_DATA, ENTITY_ITEM);
+});