@cosmicdrift/kumiko-framework 0.270.0 → 0.274.0

package/src/pipeline/__tests__/projection-rebuild.integration.test.ts

@@ -938,3 +938,97 @@ describe("rebuildProjection — stale-registry column fence (#835)", () => {
     expect(await getCount(group)).toBe(1);
   });
 });
+
+describe("rebuildProjection — row level security guard (#2907)", () => {
+  test("aborts when the live table has RLS enabled — data and RLS survive", async () => {
+    const group = "00000000-0000-4000-8000-000000000051";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(1);
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" ENABLE ROW LEVEL SECURITY`);
+    try {
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/read_rebuild_items_per_group.*has row level security/);
+
+      // Live table untouched: row count AND the RLS flag itself survive.
+      expect(await getCount(group)).toBe(1);
+      const [pgClass] = await raw.unsafe<{ relrowsecurity: boolean }>(
+        `SELECT relrowsecurity FROM pg_class WHERE relname = 'read_rebuild_items_per_group'`,
+      );
+      expect(pgClass?.relrowsecurity).toBe(true);
+
+      const state = await getProjectionState(testDb.db, qualifiedProjectionName);
+      expect(state?.status).toBe("failed");
+    } finally {
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" DISABLE ROW LEVEL SECURITY`);
+    }
+
+    // RLS cleared again → rebuild works.
+    const result = await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(result.eventsProcessed).toBe(1);
+    expect(await getCount(group)).toBe(1);
+  });
+
+  test("aborts on a policy alone, without RLS enabled — policy count reported and survives", async () => {
+    const group = "00000000-0000-4000-8000-000000000052";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(
+      `CREATE POLICY rls_guard_probe ON "read_rebuild_items_per_group" USING (true)`,
+    );
+    try {
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/policies: 1/);
+
+      const [policyCount] = await raw.unsafe<{ n: number }>(
+        `SELECT count(*)::int AS n FROM pg_policy p
+         JOIN pg_class c ON c.oid = p.polrelid
+         WHERE c.relname = 'read_rebuild_items_per_group'`,
+      );
+      expect(policyCount?.n).toBe(1);
+    } finally {
+      await raw.unsafe(`DROP POLICY IF EXISTS rls_guard_probe ON "read_rebuild_items_per_group"`);
+    }
+  });
+
+  test("aborts on FORCE ROW LEVEL SECURITY alone, without ENABLE", async () => {
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" FORCE ROW LEVEL SECURITY`);
+    try {
+      await expect(
+        rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry }),
+      ).rejects.toThrow(/row level security/);
+    } finally {
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" NO FORCE ROW LEVEL SECURITY`);
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" DISABLE ROW LEVEL SECURITY`);
+    }
+  });
+
+  test("swapShadowIntoLive rejects directly when RLS is enabled — live table survives", async () => {
+    const group = "00000000-0000-4000-8000-000000000053";
+    await appendCreatedEvent(group, "item1");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(1);
+
+    const raw = asRawClient(testDb.db);
+    await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" ENABLE ROW LEVEL SECURITY`);
+    try {
+      const db = testDb.db as DbConnection; // @cast-boundary test-harness (TestDb.db is intentionally unknown)
+      await expect(
+        db.begin(async (tx: DbTx) => {
+          await swapShadowIntoLive(tx, "read_rebuild_items_per_group");
+        }),
+      ).rejects.toThrow(/shadow swap:.*row level security/);
+
+      expect(await getCount(group)).toBe(1);
+    } finally {
+      await raw.unsafe(`ALTER TABLE "read_rebuild_items_per_group" DISABLE ROW LEVEL SECURITY`);
+    }
+  });
+});

package/src/pipeline/__tests__/projections-runner-systemscope.integration.test.ts

@@ -0,0 +1,101 @@
+// Pins the in-transaction inline-projection path over real HTTP for an
+// r.systemScope() feature — the tenant-mode path is covered by domain-events-projections.integration.test.ts.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import {
+  integer as pgInteger,
+  table as pgTable,
+  text as pgText,
+  uuid as pgUuid,
+} from "../../db/dialect";
+import { insertOne, selectMany } from "../../db/query";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../../engine";
+import {
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "../../stack";
+
+const sysItemEntity = createEntity({
+  table: "read_sysproj_items",
+  fields: { label: createTextField({ personal: false, reason: "test_fixture", required: true }) },
+});
+
+// No tenant_id column — mirrors the "system-scoped projection" table in
+// query-projection.integration.test.ts, but fed by dispatch-write's
+// in-transaction runProjections (r.projection) rather than a query handler.
+const auditTable = pgTable("read_sysproj_item_audit", {
+  itemId: pgUuid("item_id").primaryKey(),
+  tenantId: pgUuid("tenant_id").notNull(),
+  label: pgText("label").notNull(),
+  hits: pgInteger("hits").notNull().default(1),
+});
+
+const sysProjFeature = defineFeature("sysproj", (r) => {
+  r.systemScope();
+  r.entity("sysproj-item", sysItemEntity);
+
+  r.projection({
+    name: "item-audit",
+    source: "sysproj-item",
+    table: auditTable,
+    apply: {
+      "sysproj-item.created": async (event, tx) => {
+        const p = event.payload as { label?: string };
+        await insertOne(tx, auditTable, {
+          itemId: event.aggregateId,
+          tenantId: event.tenantId,
+          label: p.label ?? "?",
+        });
+      },
+    },
+  });
+
+  r.writeHandler(
+    defineEntityCreateHandler("sysproj-item", sysItemEntity, {
+      access: { roles: ["SystemAdmin"] },
+    }),
+  );
+});
+
+let stack: TestStack;
+const systemAdmin = TestUsers.systemAdmin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [sysProjFeature], systemHooks: [] });
+  await unsafeCreateEntityTable(stack.db, sysItemEntity, "sysproj-item");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["read_sysproj_items", "read_sysproj_item_audit"]);
+});
+
+describe("inline r.projection fires in-transaction for an r.systemScope() feature", () => {
+  test("HTTP write lands both the entity row and the projection row", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      "sysproj:write:sysproj-item:create",
+      { label: "widget-a" },
+      systemAdmin,
+    );
+
+    const auditRows = await selectMany<{ itemId: string; label: string; tenantId: string }>(
+      stack.db,
+      auditTable,
+      { itemId: created.id },
+    );
+    expect(auditRows).toHaveLength(1);
+    expect(auditRows[0]?.label).toBe("widget-a");
+    expect(auditRows[0]?.tenantId).toBe(systemAdmin.tenantId);
+  });
+});

package/src/pipeline/__tests__/query-projection.integration.test.ts

@@ -1,7 +1,8 @@
-// C1 — ctx.queryProjection: read projection tables by qualified name.
+// C1/fw#2913 — ctx.queryProjection: read projection tables by qualified name.
 // Framework-level read surface so features don't have to import projection
 // drizzle-tables directly. Auto-filters by tenant_id when the projection
-// table carries that column.
+// table carries that column; { unsafeAllTenants: true } opts out but needs a
+// grant — r.systemScope() or a declared escapeHatch on the handler.
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { z } from "zod";
@@ -11,10 +12,12 @@ import {
   text as pgText,
   uuid as pgUuid,
 } from "../../db/dialect";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { insertOne } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
+import type { EscapeHatchUseEvent, ProjectionTable } from "../../engine/types";
 import {
   resetEventStore,
   setupTestStack,
@@ -43,6 +46,19 @@ const systemScopedTable = pgTable("read_qp_widget_audit", {
   label: pgText("label").notNull(),
 });
 
+// Plain EntityTableMeta table (no SchemaTable symbols) — exercises
+// hasTenantColumn's meta-fallback branch instead of the drizzle-symbol path.
+const entityMetaWidgetTable = defineUnmanagedTable({
+  tableName: "store_qp_widget_meta",
+  columns: [
+    { name: "widget_id", pgType: "uuid", notNull: true, primaryKey: true },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "label", pgType: "text", notNull: true },
+  ],
+});
+
+const UNSAFE_ALL_TENANTS_REASON = "fw#2913 test — cross-tenant widget sweep";
+
 const qpFeature = defineFeature("qp", (r) => {
   r.entity("qp-widget", widgetEntity);
 
@@ -77,6 +93,24 @@ const qpFeature = defineFeature("qp", (r) => {
     },
   });
 
+  r.projection({
+    name: "widget-count-entitymeta",
+    source: "qp-widget",
+    // @cast-boundary test-fixture — a plain EntityTableMeta lacks SchemaTable's
+    // drizzle symbols; asEntityTableMeta()'s fallback branch reads it directly.
+    table: entityMetaWidgetTable as unknown as ProjectionTable,
+    apply: {
+      "qp-widget.created": async (event, tx) => {
+        const p = event.payload as { name?: string };
+        await insertOne(tx, entityMetaWidgetTable, {
+          widgetId: event.aggregateId,
+          tenantId: event.tenantId,
+          label: p.name ?? "?",
+        });
+      },
+    },
+  });
+
   const executor = createEventStoreExecutor(widgetTable, widgetEntity, {
     entityName: "qp-widget",
   });
@@ -111,6 +145,48 @@ const qpFeature = defineFeature("qp", (r) => {
     async (_query, ctx) => ctx.queryProjection("qp:projection:does-not-exist"),
     { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
+
+  r.queryHandler(
+    "widget:list-tenant-escape-hatch",
+    z.object({}),
+    async (_query, ctx) =>
+      ctx.queryProjection("qp:projection:widget-count-tenant", { unsafeAllTenants: true }),
+    {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      escapeHatch: { reason: UNSAFE_ALL_TENANTS_REASON },
+    },
+  );
+
+  r.queryHandler(
+    "widget:list-entitymeta",
+    z.object({}),
+    async (_query, ctx) => ctx.queryProjection("qp:projection:widget-count-entitymeta"),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+
+  r.queryHandler(
+    "widget:list-tenant-untyped-payload",
+    z.object({ unsafeAllTenants: z.unknown() }),
+    async (query, ctx) =>
+      ctx.queryProjection("qp:projection:widget-count-tenant", {
+        // @cast-boundary test-fixture — deliberately not the literal boolean `true`,
+        // proving a truthy-but-not-strictly-true value still tenant-filters.
+        unsafeAllTenants: query.payload.unsafeAllTenants as boolean,
+      }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+});
+
+const qpSystemFeature = defineFeature("qp-system", (r) => {
+  r.systemScope();
+
+  r.queryHandler(
+    "widget:list-tenant-systemscope",
+    z.object({}),
+    async (_query, ctx) =>
+      ctx.queryProjection("qp:projection:widget-count-tenant", { unsafeAllTenants: true }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
 });
 
 let stack: TestStack;
@@ -120,8 +196,25 @@ const otherTenantAdmin = {
   tenantId: "00000000-0000-4000-8000-0000000000b0" as const,
 };
 
+function errorReason(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || !("reason" in details)) return undefined;
+  return typeof details.reason === "string" ? details.reason : undefined;
+}
+
+function recordingSink(events: EscapeHatchUseEvent[]) {
+  return async (event: EscapeHatchUseEvent) => {
+    events.push(event);
+  };
+}
+
+const escapeHatchEvents: EscapeHatchUseEvent[] = [];
+
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [qpFeature], systemHooks: [] });
+  stack = await setupTestStack({
+    features: [qpFeature, qpSystemFeature],
+    systemHooks: [],
+    extraContext: { _escapeHatchAuditSink: recordingSink(escapeHatchEvents) },
+  });
   await unsafeCreateEntityTable(stack.db, widgetEntity, "qp-widget");
 });
 
@@ -130,10 +223,12 @@ afterAll(async () => {
 });
 
 afterEach(async () => {
+  escapeHatchEvents.length = 0;
   await resetEventStore(stack, [
     "read_qp_widgets",
     "read_qp_widget_count_tenant",
     "read_qp_widget_audit",
+    "store_qp_widget_meta",
   ]);
 });
 
@@ -173,24 +268,18 @@ describe("ctx.queryProjection", () => {
     expect(rows.map((r) => r.label).sort()).toEqual(["X", "Y"]);
   });
 
-  test("unsafeAllTenants=true bypasses tenant filter on tenant-scoped projection", async () => {
-    // Repurpose list-system by passing unsafeAllTenants=true — but list-system is
-    // already no-tenant-column. The semantic matters when a projection HAS
-    // tenant_id but the handler wants a cross-tenant sweep (audit). We
-    // exercise that contract via a direct queryProjection call here.
+  test("unsafeAllTenants=true without a grant is denied — no cross-tenant read", async () => {
     await stack.http.writeOk("qp:write:widget:create", { name: "AA" }, admin);
     await stack.http.writeOk("qp:write:widget:create", { name: "BB" }, otherTenantAdmin);
 
-    // The server exposes list-tenant with no opt-out, so assert the raw
-    // helper path via a one-shot handler:
-    // (We could add an "override" handler instead, but keeping the feature
-    //  surface small — assert against the two query handlers we have.)
-    const sys = await stack.http.queryOk<Array<{ label: string }>>(
+    const err = await stack.http.queryErr(
       "qp:query:widget:list-system",
       { unsafeAllTenants: true },
       admin,
     );
-    expect(sys).toHaveLength(2);
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("unsafe_all_tenants_denied");
   });
 
   test("unknown projection name throws with a helpful error", async () => {
@@ -199,4 +288,70 @@ describe("ctx.queryProjection", () => {
     const body = (await res.json()) as { error?: { message?: string } };
     expect(body.error?.message).toMatch(/projection not registered|does-not-exist/);
   });
+
+  test("escapeHatch grant lets unsafeAllTenants=true read cross-tenant, reporting exactly one unsafe-all-tenants event", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "AA" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "BB" }, otherTenantAdmin);
+
+    const rows = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-tenant-escape-hatch",
+      {},
+      admin,
+    );
+    expect(rows.map((r) => r.label).sort()).toEqual(["AA", "BB"]);
+
+    const matches = escapeHatchEvents.filter((e) => e.kind === "unsafe-all-tenants");
+    expect(matches).toEqual([
+      {
+        handler: "qp:query:widget:list-tenant-escape-hatch",
+        kind: "unsafe-all-tenants",
+        reason: UNSAFE_ALL_TENANTS_REASON,
+        tenantId: admin.tenantId,
+        actor: admin.id,
+      },
+    ]);
+  });
+
+  test("r.systemScope() grants unsafeAllTenants=true without a declared escapeHatch", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "CC" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "DD" }, otherTenantAdmin);
+
+    const rows = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp-system:query:widget:list-tenant-systemscope",
+      {},
+      admin,
+    );
+    expect(rows.map((r) => r.label).sort()).toEqual(["CC", "DD"]);
+  });
+
+  test("a plain EntityTableMeta projection table is tenant-filtered without unsafeAllTenants", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "EE" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "FF" }, otherTenantAdmin);
+
+    const forAdmin = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-entitymeta",
+      {},
+      admin,
+    );
+    expect(forAdmin.map((r) => r.label)).toEqual(["EE"]);
+
+    const forOther = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-entitymeta",
+      {},
+      otherTenantAdmin,
+    );
+    expect(forOther.map((r) => r.label)).toEqual(["FF"]);
+  });
+
+  test("a truthy-but-not-true unsafeAllTenants payload still tenant-filters (no bypass, no grant)", async () => {
+    await stack.http.writeOk("qp:write:widget:create", { name: "GG" }, admin);
+    await stack.http.writeOk("qp:write:widget:create", { name: "HH" }, otherTenantAdmin);
+
+    const rows = await stack.http.queryOk<Array<{ label: string }>>(
+      "qp:query:widget:list-tenant-untyped-payload",
+      { unsafeAllTenants: "yes" },
+      admin,
+    );
+    expect(rows.map((r) => r.label)).toEqual(["GG"]);
+  });
 });

package/src/pipeline/__tests__/rate-limit-default.integration.test.ts

@@ -0,0 +1,118 @@
+// fw#2861 — systemScope handlers get a default per-tenant rate limit unless
+// they declare their own or opt out. Full-stack proof via setupTestStack +
+// real HTTP (stack.http.write) — never createTestDispatcher. Modelled on
+// rate-limit/__tests__/dispatcher-l3.integration.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createSystemUser, defineFeature } from "../../engine";
+import type { RateLimitConfig, RateLimitDecision, RateLimitResolver } from "../../rate-limit";
+import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
+
+function fakeResolver(): {
+  readonly resolver: RateLimitResolver;
+  readonly calls: Array<{ bucket: string; config: RateLimitConfig }>;
+} {
+  const calls: Array<{ bucket: string; config: RateLimitConfig }> = [];
+  const decision = (config: RateLimitConfig): RateLimitDecision => ({
+    allowed: true,
+    limit: config.limit,
+    remaining: config.limit - 1,
+    retryAfterSeconds: 0,
+    windowSeconds: config.windowSeconds,
+    // @cast-boundary test-fixture — resetAt is never read by the assertions below
+    resetAt: undefined as unknown as RateLimitDecision["resetAt"],
+  });
+  const resolver: RateLimitResolver = {
+    check: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return decision(config);
+    },
+    enforce: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return decision(config);
+    },
+    peek: async (bucket, config) => {
+      calls.push({ bucket, config: { ...config } });
+      return decision({ ...config, cost: undefined });
+    },
+  };
+  return { resolver, calls };
+}
+
+const rlDefaultFeature = defineFeature("rl-default", (r) => {
+  r.systemScope();
+
+  r.writeHandler("explicit", z.object({}), async () => ({ isSuccess: true as const, data: {} }), {
+    access: { roles: ["Admin"] },
+    rateLimit: { per: "tenant", limit: 2, windowSeconds: 60 },
+  });
+
+  r.writeHandler(
+    "implicit-default",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    {
+      access: { roles: ["Admin"] },
+    },
+  );
+
+  r.writeHandler(
+    "as-system-probe",
+    z.object({}),
+    async (event, ctx) => {
+      const sysUser = createSystemUser(event.user.tenantId);
+      const res = await ctx.writeAs(sysUser, "rl-default:write:implicit-default", {});
+      return { isSuccess: true as const, data: res };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+let calls: Array<{ bucket: string; config: RateLimitConfig }>;
+const TENANT = testTenantId(9201);
+const admin = createTestUser({ tenantId: TENANT, roles: ["Admin"] });
+
+beforeAll(async () => {
+  const { resolver, calls: recorded } = fakeResolver();
+  calls = recorded;
+  stack = await setupTestStack({
+    features: [rlDefaultFeature],
+    extraContext: { rateLimit: resolver },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("systemScope default rate limit (fw#2861)", () => {
+  test("explicit rateLimit still wins over the systemScope default", async () => {
+    calls.length = 0;
+    const res = await stack.http.write("rl-default:write:explicit", {}, admin);
+    expect(res.status).toBe(200);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant:${TENANT}`);
+    expect(calls[0]?.config).toEqual({ limit: 2, windowSeconds: 60, cost: undefined });
+  });
+
+  test("no declared rateLimit on a systemScope handler -> the default {per:tenant+handler,limit:600,windowSeconds:60} fires", async () => {
+    calls.length = 0;
+    const res = await stack.http.write("rl-default:write:implicit-default", {}, admin);
+    expect(res.status).toBe(200);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant+handler:${TENANT}:rl-default:write:implicit-default`);
+    expect(calls[0]?.config).toEqual({ limit: 600, windowSeconds: 60, cost: undefined });
+  });
+
+  test("a SYSTEM-identity caller (ctx.writeAs) never touches the resolver", async () => {
+    calls.length = 0;
+    const res = await stack.http.write("rl-default:write:as-system-probe", {}, admin);
+    expect(res.status).toBe(200);
+    // One call for the probe handler's own dispatch (bucket = admin's tenant+handler),
+    // NONE for the inner SYSTEM-identity writeAs to implicit-default.
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant+handler:${TENANT}:rl-default:write:as-system-probe`);
+  });
+});

package/src/pipeline/__tests__/rate-limit-default.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import type { Temporal } from "temporal-polyfill";
+import { createSystemUser } from "../../engine";
+import type { RateLimitConfig, RateLimitDecision, RateLimitResolver } from "../../rate-limit";
+import { createTestUser, testTenantId } from "../../stack";
+import type { DispatchContext } from "../dispatch-shared";
+import { enforceRateLimit } from "../dispatch-shared";
+
+const TENANT = testTenantId(9001);
+
+function fakeResolver(): {
+  readonly resolver: RateLimitResolver;
+  readonly calls: Array<{ bucket: string; config: RateLimitConfig }>;
+} {
+  const calls: Array<{ bucket: string; config: RateLimitConfig }> = [];
+  const decision: RateLimitDecision = {
+    allowed: true,
+    limit: 0,
+    remaining: 0,
+    retryAfterSeconds: 0,
+    windowSeconds: 0,
+    resetAt: {} as Temporal.Instant,
+  };
+  const resolver: RateLimitResolver = {
+    check: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return { ...decision, limit: config.limit, windowSeconds: config.windowSeconds };
+    },
+    enforce: async (bucket, config) => {
+      calls.push({ bucket, config });
+      return { ...decision, limit: config.limit, windowSeconds: config.windowSeconds };
+    },
+    peek: async (bucket, config) => {
+      calls.push({ bucket, config: { ...config } });
+      return { ...decision, limit: config.limit, windowSeconds: config.windowSeconds };
+    },
+  };
+  return { resolver, calls };
+}
+
+function fakeCtx(rateLimit: RateLimitResolver | undefined): DispatchContext {
+  return {
+    appContext: { rateLimit },
+  } as unknown as DispatchContext; // @cast-boundary test-fixture — enforceRateLimit only reads ctx.appContext
+}
+
+describe("enforceRateLimit — systemScope default", () => {
+  test("systemScope handler, no declared rateLimit, resolver configured, regular user -> enforces the default per-tenant+handler limit", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await enforceRateLimit(fakeCtx(resolver), undefined, "some:write:handler", user, true);
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`tenant+handler:${TENANT}:some:write:handler`);
+    expect(calls[0]?.config).toEqual({ limit: 600, windowSeconds: 60, cost: undefined });
+  });
+
+  test("systemScope handler, SYSTEM-identity caller -> never touches the resolver", async () => {
+    const { resolver, calls } = fakeResolver();
+    const systemUser = createSystemUser(TENANT);
+
+    await enforceRateLimit(fakeCtx(resolver), undefined, "some:write:handler", systemUser, true);
+
+    expect(calls).toHaveLength(0);
+  });
+
+  test("systemScope handler, no resolver configured -> no-op, no throw", async () => {
+    const user = createTestUser({ tenantId: TENANT });
+
+    await expect(
+      enforceRateLimit(fakeCtx(undefined), undefined, "some:write:handler", user, true),
+    ).resolves.toBeUndefined();
+  });
+
+  test("systemScope handler with an explicit rateLimit -> that option is enforced, not the default", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await enforceRateLimit(
+      fakeCtx(resolver),
+      { per: "user", limit: 3, windowSeconds: 10 },
+      "some:write:handler",
+      user,
+      true,
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.bucket).toBe(`user:${user.id}`);
+    expect(calls[0]?.config).toEqual({ limit: 3, windowSeconds: 10, cost: undefined });
+  });
+
+  test("systemScope handler with rateLimit: { disabled: true, reason } -> never enforced, no error", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await expect(
+      enforceRateLimit(
+        fakeCtx(resolver),
+        { disabled: true, reason: "ops replay path" },
+        "some:write:handler",
+        user,
+        true,
+      ),
+    ).resolves.toBeUndefined();
+    expect(calls).toHaveLength(0);
+  });
+
+  test("non-systemScope handler, no declared rateLimit -> never enforced (unchanged baseline behavior)", async () => {
+    const { resolver, calls } = fakeResolver();
+    const user = createTestUser({ tenantId: TENANT });
+
+    await enforceRateLimit(fakeCtx(resolver), undefined, "some:write:handler", user, false);
+
+    expect(calls).toHaveLength(0);
+  });
+});