@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

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__/access-declarations.test.ts

@@ -55,7 +55,8 @@ describe("validateAccessDeclarations", () => {
   });
 
   // 1b. malformed openToAll (from untyped sources) counts as invalid, not a crash.
-  test.each([{ openToAll: false }, { openToAll: {} }])(
+  // `{ openToAll: true }` (deprecated) must fail boot too — it never grants access per isOpenToAllGranted.
+  test.each([{ openToAll: false }, { openToAll: {} }, { openToAll: true }])(
     "malformed openToAll %p throws, naming the handler",
     (access) => {
       const feature = defineFeature("notes", (r) => {
@@ -259,9 +260,9 @@ describe("validateAccessDeclarations", () => {
     expect(() => validateAccessDeclarations(feature)).toThrow(/"email"/);
   });
 
-  test("the deprecated openToAll: true form cannot carry personalData", () => {
-    // @ts-expect-error personalData lives only on the { reason } object form
-    const access: AccessRule = { openToAll: true, personalData: "tenant-members" };
+  test("the deprecated openToAll: true form no longer type-checks against AccessRule", () => {
+    // @ts-expect-error `openToAll: true` was removed from AccessRule — see #2858
+    const access: AccessRule = { openToAll: true };
     expect(access).toBeDefined();
   });
 

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__/parent-ref.test.ts

@@ -52,8 +52,16 @@ describe("validateParentRefs", () => {
     const entity = joinEntity(validRef);
     const feature = defineFeature("joins", (r) => {
       r.entity("join", entity);
-      r.queryHandler(defineEntityListHandler("join", entity, { access: { openToAll: true } }));
-      r.queryHandler(defineEntityDetailHandler("join", entity, { access: { openToAll: true } }));
+      r.queryHandler(
+        defineEntityListHandler("join", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
+      r.queryHandler(
+        defineEntityDetailHandler("join", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
     });
     expect(() => validate(feature)).not.toThrow();
   });
@@ -65,7 +73,7 @@ describe("validateParentRefs", () => {
         name: "host:list",
         schema: z.object({}),
         handler: async () => ({ rows: [], nextCursor: null }),
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => validate(feature)).not.toThrow();
@@ -99,7 +107,11 @@ describe("validateParentRefs", () => {
     const entity = joinEntity({ ...validRef, allowedTypes: ["host"] });
     const feature = defineFeature("joins", (r) => {
       r.entity("join", entity);
-      r.queryHandler(defineEntityListHandler("join", entity, { access: { openToAll: true } }));
+      r.queryHandler(
+        defineEntityListHandler("join", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
     });
     expect(() => validate(feature, [hosts])).not.toThrow();
   });
@@ -121,7 +133,7 @@ describe("validateParentRefs", () => {
         name: "join:list",
         schema: z.object({}),
         handler: async () => ({ rows: [], nextCursor: null }),
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => validate(feature)).toThrow(/join:list/);
@@ -134,7 +146,7 @@ describe("validateParentRefs", () => {
         name: "join:detail",
         schema: z.object({ id: z.uuid() }),
         handler: async () => null,
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => validate(feature)).toThrow(/join:detail/);

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/access-declarations.ts

@@ -88,12 +88,10 @@ function candidatePersonalFieldNames(
   return names;
 }
 
-// A value that is neither `true` nor an object with a non-empty string `reason`
-// counts as "empty" — catches malformed openToAll from untyped sources too.
+// Not an object with a non-empty string `reason` (incl. deprecated `openToAll: true`) counts as "empty".
 function openToAllReasonIsEmpty(access: AccessRule): boolean {
   if (!("openToAll" in access)) return false;
   const openToAll: unknown = access.openToAll;
-  if (openToAll === true) return false;
   if (typeof openToAll !== "object" || openToAll === null) return true;
   if (!("reason" in openToAll) || typeof openToAll.reason !== "string") return true;
   return openToAll.reason.trim().length === 0;
@@ -125,8 +123,8 @@ function validateOpenToAllReason(
   if (!openToAllReasonIsEmpty(access)) return;
   throw new Error(
     `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
-      '{ openToAll: ... } — must be `true` or { reason: "<non-empty explanation>" } ' +
-      "for why any authenticated user may call this handler.",
+      '{ openToAll: ... } — must be { reason: "<non-empty explanation>" } for why any ' +
+      "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.",
   );
 }
 

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/nav.ts

@@ -4,6 +4,7 @@
 
 import { qualifyEntityName } from "../qualified-name";
 import type { AccessRule, FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import { isOpenToAllGranted } from "../types";
 
 export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
   const set = new Set<string>();
@@ -135,10 +136,10 @@ export function validateNavCycles(
   }
 }
 
-// undefined access or `{ openToAll: true }` both mean "visible to everyone"
-// — neither has a role-set an inversion check could compare against.
+// undefined or granted openToAll means visible to everyone (no role-set to compare); malformed/denied openToAll returns `[]`, same as an explicit `roles: []`.
 function navViewerRoles(access: AccessRule | undefined): readonly string[] | undefined {
-  if (access === undefined || "openToAll" in access) return undefined;
+  if (access === undefined) return undefined;
+  if ("openToAll" in access) return isOpenToAllGranted(access) ? undefined : [];
   return access.roles;
 }
 

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 {