@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

package/src/engine/__tests__/screen.test.ts

@@ -4,6 +4,7 @@ import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
 import { validateBoot as validateBootRaw } from "../boot-validator";
 import { createTenantConfig } from "../config-helpers";
 import { defineFeature } from "../define-feature";
+import { defineEntityListHandler } from "../entity-handlers";
 import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 import type { ScreenDefinition } from "../types/screen";
@@ -555,6 +556,155 @@ describe("r.screen() — registration", () => {
     });
   });
 
+  describe("relatedList parentFilter", () => {
+    test("rejects parentFilter combined with parentParam on the same section", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ filter: z.unknown().optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  parentParam: "orderId",
+                  parentFilter: { field: "orderId" },
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/declares both parentFilter and parentParam/);
+    });
+
+    test("rejects parentFilter when the bound query's schema has no filter parameter", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  parentFilter: { field: "orderId" },
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /declares parentFilter but query.*no "filter" parameter/,
+      );
+    });
+
+    test("rejects parentFilter.field that is not a declared field on the entity behind the query", () => {
+      const orderEntity = createEntity({
+        table: "orders",
+        fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+      });
+      const features = [
+        defineFeature("app", (r) => {
+          r.entity("order", orderEntity);
+          r.queryHandler(
+            defineEntityListHandler("order", orderEntity, {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            }),
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:order:list",
+                  columns: ["name"],
+                  parentFilter: { field: "unknownField" },
+                },
+              ],
+            },
+          });
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /parentFilter\.field "unknownField" is not a declared field/,
+      );
+    });
+
+    test("accepts a valid parentFilter whose field is a real entity field and the query accepts filter", () => {
+      const orderEntity = createEntity({
+        table: "orders",
+        fields: {
+          name: createTextField({ personal: false, reason: "test_fixture" }),
+          orderId: createTextField({ personal: false, reason: "test_fixture" }),
+        },
+      });
+      const features = [
+        defineFeature("app", (r) => {
+          r.entity("order", orderEntity);
+          r.queryHandler(
+            defineEntityListHandler("order", orderEntity, {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            }),
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:order:list",
+                  columns: ["name"],
+                  parentFilter: { field: "orderId" },
+                },
+              ],
+            },
+          });
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+  });
+
   test("validateBoot rejects a relatedList section on entityEdit (fw#2166)", () => {
     const features = [
       defineFeature("shop", (r) => {

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -58,7 +58,6 @@ function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): JobContext
   // to this recorder instead of trying to extract real table metadata.
   const fakeDb = {
     tenantId: "t1",
-    raw: { unsafe: async () => [] },
     selectMany: async () => [],
     fetchOne: async () => undefined,
     insertOne: async () => undefined,

package/src/engine/__tests__/steps-read.test.ts

@@ -1,8 +1,14 @@
 import { beforeEach, describe, expect, it, mock } from "bun:test";
+import type { EscapeHatchReporter } from "@cosmicdrift/kumiko-types/handlers";
+import type { DbRunner } from "../../db/connection";
 import { table, text, uuid } from "../../db/dialect";
+import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../../db/tenant-db";
+import { AccessDeniedError } from "../../errors";
+import { testTenantId } from "../../stack";
 import { getStep } from "../define-step";
 import { buildReadFindManyStep } from "../steps/read-find-many";
 import { buildReadFindOneStep } from "../steps/read-find-one";
+import { SYSTEM_TENANT_ID } from "../types/identifiers";
 import type { PipelineCtx } from "../types/step";
 
 const testTable = table("test_read", {
@@ -11,14 +17,16 @@ const testTable = table("test_read", {
   label: text("label"),
 });
 
-// bun-db path: read-find-many/one call selectMany(ctx.db.raw, table, where, opts)
-// which goes through asRawClient(ctx.db.raw).unsafe(sqlText, params).
-// Mock the .unsafe() return value to feed back rows.
+// fw#2914: read-find-many/one now call selectMany(ctx.db, table, where, opts) —
+// ctx.db is a TenantDb, so selectMany's tenantDbDelegate branch runs
+// TenantDb.selectMany (applies the tenant filter) instead of raw SQL. Mock
+// .unsafe() to feed back rows once the (tenant-filtered) query reaches it.
 const unsafeMock = mock(
   async (_sqlText: string, _params: unknown[]): Promise<Record<string, unknown>[]> => [],
 );
-const rawDb = { unsafe: unsafeMock, begin: mock() };
-const ctxDb = { raw: rawDb };
+const rawDb = { unsafe: unsafeMock, begin: mock() } as DbRunner;
+const ownTenantId = testTenantId(1);
+const ctxDb = createTenantDb(rawDb, ownTenantId);
 
 const mockCtx = {
   db: ctxDb,
@@ -27,6 +35,21 @@ const mockCtx = {
   scope: {},
 } as unknown as PipelineCtx;
 
+const reportCalls: Array<{ kind: string; reason: string }> = [];
+const recordingReport: EscapeHatchReporter = (kind, reason) => {
+  reportCalls.push({ kind, reason });
+};
+const grantedDb = createTenantDb(rawDb, ownTenantId, "tenant", undefined, undefined, undefined, {
+  unsafeRaw: { reason: "fw#2914 unit test — declared cross-tenant read" },
+  report: recordingReport,
+});
+const grantedCtx = {
+  db: grantedDb,
+  event: { type: "test", payload: {} },
+  steps: {},
+  scope: {},
+} as unknown as PipelineCtx;
+
 describe("buildReadFindOneStep", () => {
   it("returns a StepInstance with kind read.findOne", () => {
     const step = buildReadFindOneStep("myLookup", {
@@ -51,6 +74,7 @@ describe("read.findOne run", () => {
   beforeEach(() => {
     mock.clearAllMocks();
     unsafeMock.mockResolvedValue([]);
+    reportCalls.length = 0;
   });
 
   it("returns null when no row is found", async () => {
@@ -78,7 +102,19 @@ describe("read.findOne run", () => {
     expect(result).toEqual(row);
   });
 
-  it("resolves a function where-clause before querying", async () => {
+  it("filters by the caller's own tenant + SYSTEM_TENANT_ID by default", async () => {
+    const stepDef = getStep("read.findOne");
+    unsafeMock.mockResolvedValueOnce([]);
+
+    await stepDef!.run({ name: "lookup", table: testTable, where: { id: "x" } }, mockCtx);
+
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText, params] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).toMatch(/"tenant_id" IN \(\$\d, \$\d\)/);
+    expect(params).toEqual(expect.arrayContaining([ownTenantId, SYSTEM_TENANT_ID]));
+  });
+
+  it("narrows a foreign where.tenantId to the caller's own scope", async () => {
     const stepDef = getStep("read.findOne");
     const whereFn = mock(() => ({ tenantId: "dyn-tenant" }));
     unsafeMock.mockResolvedValueOnce([]);
@@ -89,8 +125,42 @@ describe("read.findOne run", () => {
     expect(unsafeMock).toHaveBeenCalledTimes(1);
     const [sqlText, params] = unsafeMock.mock.calls[0]!;
     expect(sqlText).toMatch(/SELECT \* FROM "test_read"/);
-    expect(sqlText).toMatch(/"tenant_id" = \$1/);
-    expect(params).toEqual(["dyn-tenant"]);
+    expect(sqlText).toMatch(/"tenant_id" IN \(\$1, \$2\)/);
+    expect(params).toEqual([ownTenantId, SYSTEM_TENANT_ID]);
+  });
+
+  it("rejects unsafeAllTenants without a grant, without ever calling unsafe()", async () => {
+    const stepDef = getStep("read.findOne");
+
+    await expect(
+      stepDef!.run(
+        {
+          name: "lookup",
+          table: testTable,
+          where: { id: "x" },
+          unsafeAllTenants: { reason: "fw#2914 unit test — no grant" },
+        },
+        mockCtx,
+      ),
+    ).rejects.toThrow(AccessDeniedError);
+
+    expect(unsafeMock).not.toHaveBeenCalled();
+  });
+
+  it("unsafeAllTenants with a grant skips the tenant filter and reports unsafe-raw", async () => {
+    const stepDef = getStep("read.findOne");
+    unsafeMock.mockResolvedValueOnce([]);
+    const reason = "fw#2914 unit test — declared cross-tenant read";
+
+    await stepDef!.run(
+      { name: "lookup", table: testTable, where: { id: "x" }, unsafeAllTenants: { reason } },
+      grantedCtx,
+    );
+
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).not.toMatch(/tenant_id/);
+    expect(reportCalls).toEqual([{ kind: "unsafe-raw", reason }]);
   });
 });
 
@@ -105,12 +175,23 @@ describe("buildReadFindManyStep", () => {
     const step = buildReadFindManyStep("myList", { table: testTable, limit: 10 });
     expect((step.args as { limit: number }).limit).toBe(10);
   });
+
+  it("stores unsafeAllTenants on step.args and rejects a boolean at the type level", () => {
+    const reason = "fw#2914 unit test — unsafeAllTenants stored on step.args";
+    const step = buildReadFindManyStep("x", { table: testTable, unsafeAllTenants: { reason } });
+    expect(step.args).toMatchObject({ unsafeAllTenants: { reason } });
+
+    // @ts-expect-error unsafeAllTenants requires { reason: string }, not a boolean
+    const rejected = buildReadFindManyStep("x", { table: testTable, unsafeAllTenants: true });
+    expect(rejected.args).toMatchObject({ unsafeAllTenants: true });
+  });
 });
 
 describe("read.findMany run", () => {
   beforeEach(() => {
     mock.clearAllMocks();
     unsafeMock.mockResolvedValue([]);
+    reportCalls.length = 0;
   });
 
   it("returns an empty array when no rows exist", async () => {
@@ -133,4 +214,119 @@ describe("read.findMany run", () => {
     const [sqlText] = unsafeMock.mock.calls[0]!;
     expect(sqlText).toMatch(/LIMIT 2/);
   });
+
+  it("filters by the caller's own tenant + SYSTEM_TENANT_ID by default", async () => {
+    const stepDef = getStep("read.findMany");
+    unsafeMock.mockResolvedValueOnce([]);
+
+    await stepDef!.run({ name: "list", table: testTable }, mockCtx);
+
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText, params] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).toMatch(/"tenant_id" IN \(\$1, \$2\)/);
+    expect(params).toEqual([ownTenantId, SYSTEM_TENANT_ID]);
+  });
+
+  it("rejects unsafeAllTenants without a grant, without ever calling unsafe()", async () => {
+    const stepDef = getStep("read.findMany");
+
+    await expect(
+      stepDef!.run(
+        {
+          name: "list",
+          table: testTable,
+          unsafeAllTenants: { reason: "fw#2914 unit test — no grant" },
+        },
+        mockCtx,
+      ),
+    ).rejects.toThrow(AccessDeniedError);
+
+    expect(unsafeMock).not.toHaveBeenCalled();
+  });
+
+  it("unsafeAllTenants with a grant skips the tenant filter and reports unsafe-raw", async () => {
+    const stepDef = getStep("read.findMany");
+    unsafeMock.mockResolvedValueOnce([]);
+    const reason = "fw#2914 unit test — declared cross-tenant read";
+
+    await stepDef!.run(
+      { name: "list", table: testTable, unsafeAllTenants: { reason } },
+      grantedCtx,
+    );
+
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).not.toMatch(/tenant_id/);
+    expect(reportCalls).toEqual([{ kind: "unsafe-raw", reason }]);
+  });
+});
+
+describe("read steps in a systemScope handler", () => {
+  const systemScopeReportCalls: Array<{ kind: string; reason: string }> = [];
+  const systemScopeReporter: EscapeHatchReporter = (kind, reason) => {
+    systemScopeReportCalls.push({ kind, reason });
+  };
+  // Mirrors createSystemScopedDbGuard (pipeline/dispatch-shared.ts) — a
+  // systemScope() handler's ctx.db is a Proxy that throws on first touch.
+  const throwingDb = new Proxy({} as TenantDb, {
+    get(_target, prop) {
+      throw new Error(`ctx.db is unavailable in a systemScope() handler (read "${String(prop)}")`);
+    },
+  });
+  const systemScopeCtx = {
+    db: throwingDb,
+    systemDb: createUncheckedSystemDb(
+      createTenantDb(rawDb, testTenantId(1), "system"),
+      undefined,
+      systemScopeReporter,
+    ),
+    event: { type: "test", payload: {} },
+    steps: {},
+    scope: {},
+  } as unknown as PipelineCtx;
+
+  beforeEach(() => {
+    mock.clearAllMocks();
+    unsafeMock.mockResolvedValue([]);
+    systemScopeReportCalls.length = 0;
+  });
+
+  it("findMany with unsafeAllTenants reads through ctx.systemDb, skips the tenant filter, and reports unsafe-raw", async () => {
+    const stepDef = getStep("read.findMany");
+    unsafeMock.mockResolvedValueOnce([]);
+    const reason = "fw#2914 unit test — system-wide read step";
+
+    await stepDef!.run(
+      { name: "list", table: testTable, unsafeAllTenants: { reason } },
+      systemScopeCtx,
+    );
+
+    expect(unsafeMock).toHaveBeenCalledTimes(1);
+    const [sqlText] = unsafeMock.mock.calls[0]!;
+    expect(sqlText).not.toMatch(/tenant_id/);
+    expect(systemScopeReportCalls).toEqual([{ kind: "unsafe-raw", reason }]);
+  });
+
+  it("findMany without unsafeAllTenants falls through to the throwing ctx.db proxy", async () => {
+    const stepDef = getStep("read.findMany");
+
+    await expect(
+      stepDef!.run({ name: "list", table: testTable }, systemScopeCtx),
+    ).rejects.toThrow();
+
+    expect(unsafeMock).not.toHaveBeenCalled();
+  });
+
+  it("findMany with a whitespace-only reason is rejected by systemDb.unsafeRaw before any query runs", async () => {
+    const stepDef = getStep("read.findMany");
+
+    await expect(
+      stepDef!.run(
+        { name: "list", table: testTable, unsafeAllTenants: { reason: "  " } },
+        systemScopeCtx,
+      ),
+    ).rejects.toThrow("non-empty reason");
+
+    expect(unsafeMock).not.toHaveBeenCalled();
+  });
 });

package/src/engine/__tests__/steps-unsafe-projection-delete.test.ts

@@ -1,5 +1,8 @@
 import { beforeEach, describe, expect, it, mock } from "bun:test";
+import type { DbRunner } from "../../db/connection";
 import { table, text, uuid } from "../../db/dialect";
+import { createTenantDb } from "../../db/tenant-db";
+import { testTenantId } from "../../stack";
 import { getStep } from "../define-step";
 import { buildUnsafeProjectionDeleteStep } from "../steps/unsafe-projection-delete";
 import type { PipelineCtx } from "../types/step";
@@ -10,11 +13,11 @@ const testTable = table("test_projection", {
   label: text("label"),
 });
 
-// bun-db path: step calls deleteMany(ctx.db.raw, table, where) which lands on
-// asRawClient(ctx.db.raw).unsafe(sqlText, params).
+// bun-db path: step calls deleteMany(tenantDbRunner(ctx.db), table, where) which
+// lands on asRawClient(runner).unsafe(sqlText, params).
 const unsafeMock = mock(async (_sqlText: string, _params: unknown[]): Promise<unknown[]> => []);
-const rawDb = { unsafe: unsafeMock, begin: mock() };
-const ctxDb = { raw: rawDb };
+const rawDb = { unsafe: unsafeMock, begin: mock() } as DbRunner;
+const ctxDb = createTenantDb(rawDb, testTenantId(1));
 
 const mockCtx = {
   db: ctxDb,

package/src/engine/__tests__/steps-unsafe-projection-upsert.test.ts

@@ -1,5 +1,8 @@
 import { beforeEach, describe, expect, it, mock } from "bun:test";
+import type { DbRunner } from "../../db/connection";
 import { table, text, uuid } from "../../db/dialect";
+import { createTenantDb } from "../../db/tenant-db";
+import { testTenantId } from "../../stack";
 import { getStep } from "../define-step";
 import { buildUnsafeProjectionUpsertStep } from "../steps/unsafe-projection-upsert";
 import type { PipelineCtx } from "../types/step";
@@ -11,13 +14,13 @@ const testTable = table("test_projection", {
   label: text("label"),
 });
 
-// New bun-db path: step uses asRawClient(ctx.db.raw).unsafe(sqlText, params).
+// New bun-db path: step uses asRawClient(tenantDbRunner(ctx.db)).unsafe(sqlText, params).
 // Capture the raw SQL string + params per call instead of the old
 // insert/values/onConflictDoUpdate chain.
 const unsafeMock = mock(async (_sqlText: string, _params: unknown[]) => []);
 const beginMock = mock(async (fn: (tx: unknown) => Promise<unknown>) => fn({}));
-const rawDb = { unsafe: unsafeMock, begin: beginMock };
-const ctxDb = { raw: rawDb };
+const rawDb = { unsafe: unsafeMock, begin: beginMock } as DbRunner;
+const ctxDb = createTenantDb(rawDb, testTenantId(1));
 
 const mockCtx = {
   db: ctxDb,

package/src/engine/boot-validator/__tests__/global-tenancy.test.ts

@@ -30,7 +30,21 @@ describe("validateGlobalTenancyEntities", () => {
     expect(() => validateGlobalTenancyEntities([feature])).toThrow(/systemStream/);
   });
 
-  test("a tenancy: 'global' entity WITH systemStream: true passes", () => {
+  test("a tenancy: 'global' entity WITH systemStream: true but WITHOUT r.systemScope() throws", () => {
+    const entity = createEntity({
+      table: "read_fw2860_global_no_scope",
+      tenancy: "global",
+      systemStream: true,
+      fields: { name: textField() },
+    });
+    const feature = defineFeature("fw2860-global-no-scope", (r) => {
+      r.entity("fw2860GlobalNoScope", entity);
+    });
+
+    expect(() => validateGlobalTenancyEntities([feature])).toThrow(/systemScope/);
+  });
+
+  test("a tenancy: 'global' entity WITH systemStream: true AND r.systemScope() passes", () => {
     const entity = createEntity({
       table: "read_fw2858_global_with_stream",
       tenancy: "global",
@@ -38,6 +52,7 @@ describe("validateGlobalTenancyEntities", () => {
       fields: { name: textField() },
     });
     const feature = defineFeature("fw2858-global-with-stream", (r) => {
+      r.systemScope();
       r.entity("fw2858GlobalWithStream", entity);
     });
 

package/src/engine/boot-validator/__tests__/rate-limit-disabled-reason.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../define-feature";
+import { validateHandlerAccess } from "../entity-handler";
+
+describe("validateHandlerAccess — rateLimit: { disabled: true } reason", () => {
+  test("an empty reason throws, naming the handler", () => {
+    const feature = defineFeature("rl-guard", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["Admin"] },
+          rateLimit: { disabled: true, reason: "" },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).toThrow(/rl-guard:write:note:create/);
+    expect(() => validateHandlerAccess(feature)).toThrow(/rateLimit: \{ disabled: true \}/);
+  });
+
+  test("a non-empty reason boots fine", () => {
+    const feature = defineFeature("rl-guard", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["Admin"] },
+          rateLimit: { disabled: true, reason: "ops replay path" },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+});

package/src/engine/boot-validator/entity-handler.ts

@@ -1,4 +1,5 @@
 import type { BlurRegion, VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { isRateLimitDisabled } from "@cosmicdrift/kumiko-types/handlers";
 import { VARIANT_NAME_PATTERN } from "../../derivatives/variant-key";
 import { parseRefTarget } from "../parse-ref-target";
 import type {
@@ -147,10 +148,28 @@ export function validateHandlerAccess(feature: FeatureDefinition): void {
         );
       }
       validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);
+      validateRateLimitDisabledReason(feature.name, kind, name, handler.rateLimit);
     }
   }
 }
 
+export function validateRateLimitDisabledReason(
+  featureName: string,
+  kind: "write" | "query" | "stream",
+  handlerName: string,
+  rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"],
+): void {
+  // skip: rate limit isn't disabled, so no reason is required
+  if (!isRateLimitDisabled(rateLimit)) return;
+  if (rateLimit.reason.trim().length === 0) {
+    throw new Error(
+      `${kind} handler "${featureName}:${kind}:${handlerName}" declares rateLimit: { disabled: true } ` +
+        `without a reason. Provide { disabled: true, reason: "..." } explaining why this handler must not ` +
+        `be rate-limited.`,
+    );
+  }
+}
+
 export function validateAnonymousRateLimit(
   featureName: string,
   kind: "write" | "query" | "stream",
@@ -160,6 +179,8 @@ export function validateAnonymousRateLimit(
 ): void {
   // skip: handler doesn't opt into rate-limit, no user-bucket risk
   if (!rateLimit) return;
+  // skip: disabled declarations carry no `.per` to bucket on
+  if (isRateLimitDisabled(rateLimit)) return;
   // skip: openToAll handlers don't allow anonymous (hasAccess rejects), so
   // the user-bucket footgun doesn't apply
   if (!("roles" in access)) return;

package/src/engine/boot-validator/global-tenancy.ts

@@ -2,16 +2,28 @@ import type { FeatureDefinition } from "../types";
 
 // Boot-time twin of event-store-executor-context.ts's buildExecutorContext check —
 // surfaces the systemStream invariant once across all features before any dispatch.
+//
+// A "global" entity also requires r.systemScope() — otherwise convention writes
+// dispatch in tenant-mode and a global row could carry the creating tenant's id.
 export function validateGlobalTenancyEntities(features: readonly FeatureDefinition[]): void {
   for (const feature of features) {
     for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
-      if (entity.tenancy === "global" && entity.systemStream !== true) {
+      if (entity.tenancy !== "global") continue;
+      if (entity.systemStream !== true) {
         throw new Error(
           `Feature "${feature.name}" entity "${entityName}": tenancy: "global" entities must ` +
             "also declare systemStream: true — a global aggregate's event stream must live on " +
             "the system tenant, not the creating tenant's.",
         );
       }
+      if (!feature.systemScope) {
+        throw new Error(
+          `Feature "${feature.name}" entity "${entityName}": tenancy: "global" entities require ` +
+            "their owning feature to declare r.systemScope() — without it, convention writes run " +
+            "in tenant-mode and a global row could end up carrying the creating tenant's id " +
+            "instead of the system tenant's.",
+        );
+      }
     }
   }
 }

package/src/engine/boot-validator/parent-ref.ts

@@ -11,7 +11,7 @@ import type { EntityDefinition, FeatureDefinition, QueryHandlerDef } from "../ty
 // framework-internal detail() call that doesn't wire it, so the enforcement
 // has to happen loudly here instead, once, at boot.
 
-function findEntity(
+export function findEntity(
   featureMap: ReadonlyMap<string, FeatureDefinition>,
   entityName: string,
 ): EntityDefinition | undefined {