@cosmicdrift/kumiko-bundled-features 0.290.0 → 0.291.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.290.0",
+  "version": "0.291.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.290.0",
-    "@cosmicdrift/kumiko-framework": "0.290.0",
-    "@cosmicdrift/kumiko-headless": "0.290.0",
-    "@cosmicdrift/kumiko-renderer": "0.290.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.290.0",
-    "@cosmicdrift/kumiko-types": "0.290.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.291.0",
+    "@cosmicdrift/kumiko-framework": "0.291.0",
+    "@cosmicdrift/kumiko-headless": "0.291.0",
+    "@cosmicdrift/kumiko-renderer": "0.291.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.291.0",
+    "@cosmicdrift/kumiko-types": "0.291.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.290.0",
-    "@cosmicdrift/kumiko-locale-es": "0.290.0",
+    "@cosmicdrift/kumiko-locale-de": "0.291.0",
+    "@cosmicdrift/kumiko-locale-es": "0.291.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "loggedInHref callbacks on SignupCompleteScreen and InviteAcceptScreen now receive the roles granted by the flow",
+    "detail": "Apps can route a freshly activated user to a screen their role can actually open, instead of a fixed path that may render Access denied. The string form of loggedInHref is unchanged; the function form gains a roles field next to the existing tenantKey/tenantId."
+  },
   {
     "version": "0.286.0",
     "type": "improvement",

package/src/auth-email-password/web/__tests__/auth-form-logic.test.ts

@@ -34,11 +34,40 @@ describe("retryAfterMinutes", () => {
 });
 
 describe("resolveLoggedInHref", () => {
+  type SignupArgs = { tenantKey: string; roles: readonly string[] };
+
   test("string href returned as-is", () => {
-    expect(resolveLoggedInHref("/", "acme")).toBe("/");
+    expect(resolveLoggedInHref<SignupArgs>("/", { tenantKey: "acme", roles: ["User"] })).toBe("/");
   });
 
   test("function href receives tenantKey", () => {
-    expect(resolveLoggedInHref(({ tenantKey }) => `/${tenantKey}/`, "acme")).toBe("/acme/");
+    expect(
+      resolveLoggedInHref<SignupArgs>(({ tenantKey }) => `/${tenantKey}/`, {
+        tenantKey: "acme",
+        roles: [],
+      }),
+    ).toBe("/acme/");
+  });
+
+  test("function href can route on the roles the server returned", () => {
+    const byRole = ({ tenantKey, roles }: SignupArgs): string =>
+      roles.includes("SystemAdmin") ? "/a/waitlist-list" : `/${tenantKey}/vehicle-start`;
+
+    expect(resolveLoggedInHref(byRole, { tenantKey: "acme", roles: ["Dealer"] })).toBe(
+      "/acme/vehicle-start",
+    );
+    expect(resolveLoggedInHref(byRole, { tenantKey: "acme", roles: ["SystemAdmin"] })).toBe(
+      "/a/waitlist-list",
+    );
+  });
+
+  test("args object shape is per-screen — invite passes tenantId", () => {
+    expect(
+      resolveLoggedInHref(
+        ({ tenantId, roles }: { tenantId: string; roles: readonly string[] }) =>
+          `/${tenantId}/${roles[0] ?? "none"}`,
+        { tenantId: "t1", roles: ["Editor"] },
+      ),
+    ).toBe("/t1/Editor");
   });
 });

package/src/auth-email-password/web/__tests__/invite-accept-screen.test.tsx

@@ -91,6 +91,53 @@ describe("InviteAcceptScreen — logged-in branch", () => {
     });
   });
 
+  test("branch 1: loggedInHref-Function bekommt die Rolle aus der invite-accept-Response", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({ tenantId: "tenant-new", role: "Dealer", alreadyMember: false }),
+          { status: 200 },
+        ),
+    ) as unknown as typeof fetch;
+    const assign = mock<(url: string) => void>();
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { href: originalLocation.href, search: originalLocation.search, assign },
+    });
+
+    renderWithProviders(
+      <InviteAcceptScreen
+        token="tok-123"
+        loggedInHref={({ tenantId, roles }) =>
+          roles.includes("SystemAdmin") ? "/a/waitlist-list" : `/${tenantId}/vehicle-start`
+        }
+      />,
+      { session: makeSessionApi({ status: "authenticated" }) },
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Accept" }));
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith("/tenant-new/vehicle-start");
+    });
+  });
+
+  test("String-Form bleibt unverändert gültig", async () => {
+    const assign = mock<(url: string) => void>();
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { href: originalLocation.href, search: originalLocation.search, assign },
+    });
+
+    renderWithProviders(<InviteAcceptScreen token="tok-123" loggedInHref="/fixed-landing" />, {
+      session: makeSessionApi({ status: "authenticated" }),
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Accept" }));
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith("/fixed-landing");
+    });
+  });
+
   test("accept logged-in failure shows invalidInviteToken banner", async () => {
     globalThis.fetch = mock(
       async () => new Response(null, { status: 422 }),
@@ -154,6 +201,79 @@ describe("InviteAcceptScreen — anonymous branches", () => {
     });
   });
 
+  test("branch 2/3: die Session-Rollen aus user.roles schlagen die Invitation-Rolle", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({
+            token: "jwt",
+            user: { id: "u1", tenantId: "t1", roles: ["Dealer"] },
+            tenantId: "t1",
+            role: "SystemAdmin",
+          }),
+          { status: 200 },
+        ),
+    ) as unknown as typeof fetch;
+    const assign = mock<(url: string) => void>();
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { href: originalLocation.href, search: originalLocation.search, assign },
+    });
+
+    render(
+      <PrimitivesProvider value={defaultPrimitives}>
+        <LocaleProvider resolver={resolver} fallbackBundles={[defaultTranslations]}>
+          <InviteAcceptScreen
+            token="tok-123"
+            loggedInHref={({ tenantId, roles }) => `/${tenantId}/${roles.join("+")}`}
+          />
+        </LocaleProvider>
+      </PrimitivesProvider>,
+    );
+    fireEvent.change(screen.getByLabelText(/^Email/), { target: { value: "a@example.com" } });
+    fireEvent.change(screen.getByLabelText(/^Password/), { target: { value: "secret123" } });
+    fireEvent.click(screen.getByRole("button", { name: "Accept + sign in" }));
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith("/t1/Dealer");
+    });
+  });
+
+  test("MFA-Challenge (200 ohne Rollen) liefert eine leere Rollenliste statt undefined", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(JSON.stringify({ mfaRequired: true, challengeToken: "ch" }), { status: 200 }),
+    ) as unknown as typeof fetch;
+    const assign = mock<(url: string) => void>();
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      writable: true,
+      value: { href: originalLocation.href, search: originalLocation.search, assign },
+    });
+    const seen: (readonly string[])[] = [];
+
+    render(
+      <PrimitivesProvider value={defaultPrimitives}>
+        <LocaleProvider resolver={resolver} fallbackBundles={[defaultTranslations]}>
+          <InviteAcceptScreen
+            token="tok-123"
+            loggedInHref={({ roles }) => {
+              seen.push(roles);
+              return "/";
+            }}
+          />
+        </LocaleProvider>
+      </PrimitivesProvider>,
+    );
+    fireEvent.change(screen.getByLabelText(/^Email/), { target: { value: "a@example.com" } });
+    fireEvent.change(screen.getByLabelText(/^Password/), { target: { value: "secret123" } });
+    fireEvent.click(screen.getByRole("button", { name: "Accept + sign in" }));
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalled();
+    });
+    expect(seen).toEqual([[]]);
+  });
+
   test("anon failure shows invalidInviteToken banner", async () => {
     globalThis.fetch = mock(
       async () => new Response(null, { status: 422 }),

package/src/auth-email-password/web/__tests__/signup-complete-screen.test.tsx

@@ -107,6 +107,78 @@ describe("SignupCompleteScreen", () => {
     }
   });
 
+  test("loggedInHref-Function bekommt die Rollen aus der signup-confirm-Response", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({
+            user: { id: "u1", tenantId: "t1", roles: ["Dealer"] },
+            tenantKey: "acme",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+    ) as unknown as typeof fetch;
+
+    renderWithProviders(
+      <SignupCompleteScreen
+        token="abc-token"
+        loggedInHref={({ tenantKey, roles }) =>
+          roles.includes("SystemAdmin") ? "/a/waitlist-list" : `/${tenantKey}/vehicle-start`
+        }
+      />,
+    );
+    fillPasswords("validpass1", "validpass1");
+    fireEvent.click(screen.getByRole("button", { name: "Activate account" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("link", { name: "Continue" }).getAttribute("href")).toBe(
+        "/acme/vehicle-start",
+      );
+    });
+  });
+
+  test("gleiche Function, SystemAdmin-Rolle → anderes Ziel", async () => {
+    globalThis.fetch = mock(
+      async () =>
+        new Response(
+          JSON.stringify({
+            user: { id: "u1", tenantId: "t1", roles: ["SystemAdmin"] },
+            tenantKey: "acme",
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } },
+        ),
+    ) as unknown as typeof fetch;
+
+    renderWithProviders(
+      <SignupCompleteScreen
+        token="abc-token"
+        loggedInHref={({ tenantKey, roles }) =>
+          roles.includes("SystemAdmin") ? "/a/waitlist-list" : `/${tenantKey}/vehicle-start`
+        }
+      />,
+    );
+    fillPasswords("validpass1", "validpass1");
+    fireEvent.click(screen.getByRole("button", { name: "Activate account" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("link", { name: "Continue" }).getAttribute("href")).toBe(
+        "/a/waitlist-list",
+      );
+    });
+  });
+
+  test("String-Form bleibt unverändert gültig und ignoriert die Rollen", async () => {
+    renderWithProviders(<SignupCompleteScreen token="abc-token" loggedInHref="/fixed-landing" />);
+    fillPasswords("validpass1", "validpass1");
+    fireEvent.click(screen.getByRole("button", { name: "Activate account" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("link", { name: "Continue" }).getAttribute("href")).toBe(
+        "/fixed-landing",
+      );
+    });
+  });
+
   test("mismatch → client-side error, kein fetch-Call", async () => {
     const fetchMock = mock(async () => new Response(null, { status: 200 }));
     globalThis.fetch = fetchMock as unknown as typeof fetch;

package/src/auth-email-password/web/auth-form-logic.ts

@@ -21,10 +21,10 @@ export function retryAfterMinutes(retryAfterSeconds?: number): number | undefine
   return Math.ceil(retryAfterSeconds / 60);
 }
 
-/** Resolves post-login redirect: string template or function of tenantKey. */
-export function resolveLoggedInHref(
-  href: string | ((args: { readonly tenantKey: string }) => string),
-  tenantKey: string,
+/** Resolves post-login redirect: string template or function of the screen's args. */
+export function resolveLoggedInHref<Args>(
+  href: string | ((args: Args) => string),
+  args: Args,
 ): string {
-  return typeof href === "function" ? href({ tenantKey }) : href;
+  return typeof href === "function" ? href(args) : href;
 }

package/src/auth-email-password/web/invite-accept-screen.tsx

@@ -19,21 +19,40 @@
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useContext, useState } from "react";
 import { csrfHeader } from "./auth-client";
+import { resolveLoggedInHref } from "./auth-form-logic";
 import { AuthCard, useUrlToken } from "./auth-form-primitives";
 import { SessionContext, UNAUTHENTICATED } from "./session";
 
 export type InviteAcceptScreenProps = {
   readonly title?: string;
   readonly token?: string;
-  /** Where to redirect on success. Default "/" — Apps mit Multi-Tenant-
-   *  Routing können `(data) => "/${data.tenantId}/"` setzen. */
-  readonly loggedInHref?: string | ((args: { tenantId: string }) => string);
+  /** Where to redirect on success. Default "/" — multi-tenant apps can pass
+   *  `(data) => "/${data.tenantId}/"`. Function-form receives the roles this
+   *  flow grants in the target tenant; branch 1 reports the invitation's
+   *  role, which for an existing member is not their full role set there. */
+  readonly loggedInHref?:
+    | string
+    | ((args: { tenantId: string; roles: readonly string[] }) => string);
   /** Login-Href für "Mit anderem Account anmelden". Default "/login". */
   readonly loginHref?: string;
 };
 
 type Mode = "loggedin" | "anon-existing" | "anon-new";
 
+// All three accept routes answer 200 with tenantId + the invitation role;
+// the two session-minting branches additionally carry the stripped session
+// roles. An MFA challenge is also a 200 and carries none of them.
+type InviteAcceptResponse = {
+  readonly tenantId: string;
+  readonly role?: string;
+  readonly user?: { readonly roles?: readonly string[] };
+};
+
+function grantedRoles(data: InviteAcceptResponse): readonly string[] {
+  if (data.user?.roles !== undefined) return data.user.roles;
+  return data.role === undefined ? [] : [data.role];
+}
+
 export function InviteAcceptScreen({
   title,
   token: tokenProp,
@@ -70,12 +89,14 @@ export function InviteAcceptScreen({
     });
     setSubmitting(false);
     if (res.ok) {
-      const data = (await res.json()) as { tenantId: string };
-      const target =
-        typeof loggedInHref === "function"
-          ? loggedInHref({ tenantId: data.tenantId })
-          : loggedInHref;
-      window.location.assign(target);
+      // @cast-boundary engine-payload — auth route JSON
+      const data = (await res.json()) as InviteAcceptResponse;
+      window.location.assign(
+        resolveLoggedInHref(loggedInHref, {
+          tenantId: data.tenantId,
+          roles: grantedRoles(data),
+        }),
+      );
       return;
     }
     setError(t("auth.errors.invalidInviteToken"));
@@ -93,12 +114,14 @@ export function InviteAcceptScreen({
     });
     setSubmitting(false);
     if (res.ok) {
-      const data = (await res.json()) as { tenantId: string };
-      const target =
-        typeof loggedInHref === "function"
-          ? loggedInHref({ tenantId: data.tenantId })
-          : loggedInHref;
-      window.location.assign(target);
+      // @cast-boundary engine-payload — auth route JSON
+      const data = (await res.json()) as InviteAcceptResponse;
+      window.location.assign(
+        resolveLoggedInHref(loggedInHref, {
+          tenantId: data.tenantId,
+          roles: grantedRoles(data),
+        }),
+      );
       return;
     }
     setError(t("auth.errors.invalidInviteToken"));
@@ -116,12 +139,14 @@ export function InviteAcceptScreen({
     });
     setSubmitting(false);
     if (res.ok) {
-      const data = (await res.json()) as { tenantId: string };
-      const target =
-        typeof loggedInHref === "function"
-          ? loggedInHref({ tenantId: data.tenantId })
-          : loggedInHref;
-      window.location.assign(target);
+      // @cast-boundary engine-payload — auth route JSON
+      const data = (await res.json()) as InviteAcceptResponse;
+      window.location.assign(
+        resolveLoggedInHref(loggedInHref, {
+          tenantId: data.tenantId,
+          roles: grantedRoles(data),
+        }),
+      );
       return;
     }
     setError(t("auth.errors.invalidInviteToken"));

package/src/auth-email-password/web/signup-complete-screen.tsx

@@ -25,8 +25,11 @@ export type SignupCompleteScreenProps = {
   readonly title?: string;
   /** Override for the URL token — server-rendered apps can pass it. Default: `?token=...`. */
   readonly token?: string;
-  /** Where to send the user after activation. Function-form receives the tenantKey. Default "/". */
-  readonly loggedInHref?: string | ((args: { tenantKey: string }) => string);
+  /** Where to send the user after activation. Function-form receives the tenantKey and the
+   *  roles granted by this flow in that tenant — for role-dependent landing targets. Default "/". */
+  readonly loggedInHref?:
+    | string
+    | ((args: { tenantKey: string; roles: readonly string[] }) => string);
   /** Href for the "already have an account?" link when the token is missing. Default "/login". */
   readonly loginHref?: string;
 };
@@ -64,7 +67,12 @@ export function SignupCompleteScreen({
       // Cookies are already set (auto-login). Show a confirmation with an
       // explicit continue button instead of navigating away silently —
       // the user otherwise gets no signal that activation worked.
-      setContinueHref(resolveLoggedInHref(loggedInHref, res.data.tenantKey));
+      setContinueHref(
+        resolveLoggedInHref(loggedInHref, {
+          tenantKey: res.data.tenantKey,
+          roles: res.data.user.roles,
+        }),
+      );
       return;
     }
     if (res.error.reason === "invalid_signup_token") {

package/src/delivery/feature.ts

@@ -64,8 +64,13 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     // apply-key is a registered domain-event (DELIVERY_ATTEMPT_EVENT).
     // recipientAddress is the real PII (email address); recipientId stays
     // plaintext — pseudonymous fk, same line as config.userId (#821).
+    // recipientId is nullable (system-triggered sends to non-users), so the
+    // address falls back to the tenant key instead of the plaintext it used
+    // to be — still shreddable, one tenant wide (fw#2776).
     r.defineEvent("attempt", deliveryAttemptSchema, {
-      piiFields: { recipientAddress: { personal: { of: "recipientId" } } },
+      piiFields: {
+        recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },
+      },
     });
 
     // Inline projection that materialises every delivery attempt into

package/src/jobs/__tests__/tenant-job-failures.integration.test.ts

@@ -0,0 +1,275 @@
+// Tenant-visible job failures (fw#3079) end to end: a write triggers a job,
+// the job fails, and the triggering tenant reads the failure back through
+// `jobs:query:failures` — over real HTTP, a real BullMQ worker and a real
+// Postgres, with the real createJobRunLogger callbacks wired in.
+//
+// Not setupTestStack: that helper builds a JobRunner but wires none of the
+// bundled run-logger callbacks (test-stack.ts), which are the write path
+// under test here. Same buildServer + createJobRunner + createJobRunLogger
+// harness the neighbouring jobs integration tests use.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { buildServer, type JwtHelper } from "@cosmicdrift/kumiko-framework/api";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createRegistry,
+  defineFeature,
+  defineWriteHandler,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import {
+  createTestDb,
+  createTestRedis,
+  createTestUser,
+  type TestDb,
+  type TestRedis,
+  testTenantId,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { sleep } from "@cosmicdrift/kumiko-framework/testing";
+import type { Hono } from "hono";
+import { z } from "zod";
+import { JobQueries } from "../constants";
+import { createJobsFeature } from "../feature";
+import { createJobRunLogger } from "../job-run-logger";
+import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
+import { tenantJobFailuresTable } from "../tenant-job-failure-table";
+
+const JWT_SECRET = "tenant-job-failures-integration-secret-key-0123456789";
+const DECLARED_KEY = "app:errors.generationFailed";
+const BUDGET_KEY = "app:errors.budgetExceeded";
+// A provider message that must never reach the tenant.
+const PROVIDER_MESSAGE = "openai 429: prompt 'Herr Schmidt, Kennzeichen B-XY-123' rejected";
+
+const tenantA = testTenantId(1);
+const tenantB = testTenantId(2);
+const userA = createTestUser({ id: 1, tenantId: tenantA, roles: ["Admin"] });
+const userB = createTestUser({ id: 2, tenantId: tenantB, roles: ["Admin"] });
+const systemAdmin = createTestUser({ id: 3, tenantId: tenantA, roles: ["SystemAdmin"] });
+
+const generateWrite = defineWriteHandler({
+  name: "generate",
+  description: "Test-only: starts the text generation for one campaign.",
+  schema: z.object({ campaignId: z.string(), mode: z.enum(["fail", "budget", "succeed"]) }),
+  access: { roles: ["Admin"] },
+  handler: async (event) => ({ isSuccess: true as const, data: { ...event.payload } }),
+});
+
+const retryWrite = defineWriteHandler({
+  name: "startFlaky",
+  description: "Test-only: starts a job that fails on every attempt.",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async () => ({ isSuccess: true as const, data: {} }),
+});
+
+const appFeature = defineFeature("app", (r) => {
+  r.writeHandler(generateWrite);
+  r.writeHandler(retryWrite);
+
+  r.job(
+    "generateTexts",
+    {
+      trigger: { on: "app:write:generate" },
+      tenantVisibleFailure: { messageKey: DECLARED_KEY, subjectFields: ["campaignId"] },
+    },
+    async (payload) => {
+      if (payload["mode"] === "budget") {
+        throw new UnprocessableError("budget_exceeded", { i18nKey: BUDGET_KEY });
+      }
+      if (payload["mode"] === "fail") throw new Error(PROVIDER_MESSAGE);
+    },
+  );
+
+  // retries: 1 — two attempts, both failing. Only the last one may record.
+  r.job(
+    "flaky",
+    {
+      trigger: { on: "app:write:start-flaky" },
+      retries: 1,
+      tenantVisibleFailure: { messageKey: DECLARED_KEY },
+    },
+    async () => {
+      throw new Error(PROVIDER_MESSAGE);
+    },
+  );
+});
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+let db: DbConnection;
+let app: Hono;
+let jwt: JwtHelper;
+let jobRunner: JobRunner;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  db = testDb.db;
+
+  const registry = createRegistry([appFeature, createJobsFeature()]);
+  await unsafePushTables(db, { jobRunsTable, jobRunLogsTable, tenantJobFailuresTable });
+  await createEventsTable(db);
+
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+  jobRunner = createJobRunner({
+    registry,
+    context: { db },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-tenant-job-failures-${Date.now()}`,
+    ...createJobRunLogger({ db, registry }),
+  });
+
+  const server = buildServer({
+    registry,
+    context: { db, registry, jobRunner },
+    jwtSecret: JWT_SECRET,
+    // Event-triggered jobs enqueue from dispatch-write's afterCommit hooks,
+    // which read the runner off the dispatcher — not off the AppContext.
+    dispatcherOptions: { jobRunner },
+  });
+  app = server.app;
+  jwt = server.jwt;
+
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+async function post(path: string, user: SessionUser, body: unknown): Promise<Response> {
+  const token = await jwt.sign(user);
+  return app.request(path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  });
+}
+
+type FailureRow = {
+  readonly jobName: string;
+  readonly subject: Record<string, unknown> | null;
+  readonly messageKey: string;
+};
+
+async function generate(
+  user: SessionUser,
+  campaignId: string,
+  mode: "fail" | "budget" | "succeed",
+): Promise<void> {
+  const res = await post("/api/write", user, {
+    type: "app:write:generate",
+    payload: { campaignId, mode },
+  });
+  expect((await res.json()).isSuccess).toBe(true);
+  await sleep(1500);
+}
+
+async function failures(user: SessionUser, payload: unknown = {}): Promise<FailureRow[]> {
+  const res = await post("/api/query", user, { type: JobQueries.failures, payload });
+  const body = await res.json();
+  expect(res.status, JSON.stringify(body)).toBe(200);
+  return body.data.rows;
+}
+
+describe("jobs:query:failures (fw#3079)", () => {
+  test("the triggering tenant reads its own failed job, scoped by subject", async () => {
+    await generate(userA, "campaign-1", "fail");
+    await generate(userA, "campaign-2", "budget");
+
+    const rows = await failures(userA);
+    expect(rows).toHaveLength(2);
+    const byCampaign = new Map(rows.map((row) => [row.subject?.["campaignId"], row]));
+    expect(byCampaign.get("campaign-1")?.jobName).toBe("app:job:generate-texts");
+    // Plain Error → the key declared at the job.
+    expect(byCampaign.get("campaign-1")?.messageKey).toBe(DECLARED_KEY);
+    // KumikoError → its own i18nKey wins over the declared fallback.
+    expect(byCampaign.get("campaign-2")?.messageKey).toBe(BUDGET_KEY);
+  });
+
+  test("another tenant sees none of them, and only its own", async () => {
+    expect(await failures(userB)).toHaveLength(0);
+
+    await generate(userB, "campaign-1", "fail");
+
+    const rowsB = await failures(userB);
+    expect(rowsB).toHaveLength(1);
+    expect(rowsB[0]?.subject?.["campaignId"]).toBe("campaign-1");
+    // Tenant A's two records are untouched by B's own run of the same job
+    // and the same campaign id.
+    expect(await failures(userA)).toHaveLength(2);
+  });
+
+  test("no provider message reaches the tenant", async () => {
+    const res = await post("/api/query", userA, { type: JobQueries.failures, payload: {} });
+    const raw = await res.text();
+    expect(raw).toContain(DECLARED_KEY);
+    expect(raw).not.toContain(PROVIDER_MESSAGE);
+    expect(raw).not.toContain("openai");
+  });
+
+  test("a later successful run of the same subject clears the record", async () => {
+    await generate(userA, "campaign-1", "succeed");
+
+    const rows = await failures(userA);
+    expect(rows.map((row) => row.subject?.["campaignId"])).toEqual(["campaign-2"]);
+  });
+
+  test("only the final attempt records — a retried job leaves one record", async () => {
+    const res = await post("/api/write", userB, { type: "app:write:start-flaky", payload: {} });
+    expect((await res.json()).isSuccess).toBe(true);
+    await sleep(2500);
+
+    const rows = await failures(userB, { jobName: "app:job:flaky" });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.subject).toBeNull();
+
+    // Both attempts did land as their own failed run — the single record
+    // above is the final-attempt gate, not a missing second attempt.
+    const runs = await selectMany(db, jobRunsTable, { jobName: "app:job:flaky" });
+    expect(runs).toHaveLength(2);
+  });
+
+  test("the subject filter selects one record", async () => {
+    const rows = await failures(userA, { subject: { campaignId: "campaign-2" } });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.messageKey).toBe(BUDGET_KEY);
+
+    expect(await failures(userA, { subject: { campaignId: "campaign-unknown" } })).toHaveLength(0);
+  });
+
+  test("SystemAdmin still sees every tenant's run with its provider message", async () => {
+    const res = await post("/api/query", systemAdmin, {
+      type: JobQueries.list,
+      payload: { jobName: "app:job:generate-texts", status: "failed" },
+    });
+    const raw = await res.text();
+    expect(res.status, raw).toBe(200);
+
+    // Both of tenant A's failures plus tenant B's — the tenant-visible record
+    // is an addition, it takes nothing away from the SystemAdmin view.
+    expect(JSON.parse(raw).data.rows).toHaveLength(3);
+    expect(raw).toContain(PROVIDER_MESSAGE);
+  });
+  test("a corrupt stored subject degrades to null instead of failing the list", async () => {
+    await insertOne(db, tenantJobFailuresTable, {
+      tenantId: tenantB,
+      jobName: "app:job:corrupt",
+      subject: '{"campaignId":"not-an-entry-array"}',
+      messageKey: DECLARED_KEY,
+      failedAt: Temporal.Now.instant(),
+    });
+
+    const rows = await failures(userB, { jobName: "app:job:corrupt" });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.subject).toBeNull();
+  });
+});

package/src/jobs/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Tenant-visible job failures: `r.job({ tenantVisibleFailure })` plus `jobs:query:failures` (fw#3079)",
+    "detail": "A fire-and-forget job that fails left the tenant's screen on a spinner that never ends — `jobs:query:list` is SystemAdmin and reads cross-tenant over `systemDb.unsafeRaw`, so a tenant could not see its own job failing. Apps worked around it with their own failure entity written in the job's catch.\nA job now opts in declaratively: `r.job(\"generateTexts\", { trigger: …, tenantVisibleFailure: { messageKey: \"app:errors.generationFailed\", subjectFields: [\"campaignId\"] } }, handler)`. When its last attempt fails, the run-logger records one row per tenant, job and subject in the new `store_tenant_job_failures` table, and the tenant reads it back through `jobs:query:failures` (every membership rank, own tenant only).\nOnly a translation key travels to the tenant: the thrown error's own `i18nKey` when it carries one, otherwise the declared `messageKey`. The provider's message stays on `store_job_runs.error` and in the run log, both SystemAdmin-only. Records are scoped to the run's tenant — a tenant-less run (cron, `SYSTEM_TENANT_ID`) records nothing.\nLifetime and retries: a record lives until the next successful run of the same job and subject deletes it; there is no acknowledgement step (tenant job administration stays out of scope). Only the final attempt records, so a job with `retries` that succeeds on a later attempt never shows the tenant a failure. The daily `retention-cleanup` job purges leftovers past `retentionDays`.\n`jobs:query:list`, `jobs:query:details` and `jobs:query:retry` are unchanged. `JobRunnerOptions.onJobComplete`/`onJobFailed` gained an optional fifth `outcome` argument — existing four-argument callbacks keep working.",
+    "migration": "New store table. Run `kumiko migrate generate` and apply the migration — `store_tenant_job_failures` is created empty and stays empty until a job declares `tenantVisibleFailure`. No change needed for apps that do not opt in."
+  },
   {
     "version": "0.241.0",
     "type": "breaking",

package/src/jobs/constants.ts

@@ -13,6 +13,7 @@ export const JobQueries = {
   list: "jobs:query:list",
   details: "jobs:query:details",
   catalog: "jobs:query:catalog",
+  failures: "jobs:query:failures",
 } as const;
 
 // Error codes

package/src/jobs/db/queries/retention.ts

@@ -13,12 +13,14 @@
 import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { jobRunLogsTable, jobRunsTable } from "../../job-run-table";
+import { tenantJobFailuresTable } from "../../tenant-job-failure-table";
 
 const RETENTION_DELETE_BATCH_SIZE = 500;
 
 export type JobRunRetentionResult = {
   readonly runsDeleted: number;
   readonly logsDeleted: number;
+  readonly tenantFailuresDeleted: number;
 };
 
 export async function deleteStaleJobRuns(
@@ -40,5 +42,19 @@ export async function deleteStaleJobRuns(
     { limit: RETENTION_DELETE_BATCH_SIZE },
   );
 
-  return { runsDeleted: runsResult.deleted, logsDeleted: logsResult.deleted };
+  // Same window for the tenant-visible failure records (fw#3079): the run
+  // they point at is gone by now, and a job whose subject never ran again
+  // would otherwise keep its record forever.
+  const tenantFailuresResult = await deleteManyBatched(
+    db,
+    tenantJobFailuresTable,
+    { failedAt: { lt: cutoff } },
+    { limit: RETENTION_DELETE_BATCH_SIZE },
+  );
+
+  return {
+    runsDeleted: runsResult.deleted,
+    logsDeleted: logsResult.deleted,
+    tenantFailuresDeleted: tenantFailuresResult.deleted,
+  };
 }

package/src/jobs/feature.ts

@@ -21,9 +21,11 @@ import {
   createStaleRunSweepJob,
   DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS,
 } from "./handlers/stale-run-sweep.job";
+import { tenantFailuresQuery } from "./handlers/tenant-failures.query";
 import { triggerWrite } from "./handlers/trigger.write";
 import { JOBS_I18N } from "./i18n";
 import { jobRunLogsTableMeta, jobRunsTableMeta } from "./job-run-table";
+import { tenantJobFailuresTableMeta } from "./tenant-job-failure-table";
 
 export type JobsFeatureOptions = {
   // How long a job run (and its logs) stays in store_job_runs/
@@ -42,7 +44,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
   const staleRunTimeoutHours = options.staleRunTimeoutHours ?? DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS;
   return defineFeature("jobs", (r) => {
     r.describe(
-      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI.",
+      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079).",
     );
     r.uiHints({
       displayLabel: "Jobs · Audit & Operator UI",
@@ -61,6 +63,9 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     r.storeTable(jobRunLogsTableMeta, {
       reason: "read_side.job_run_logs",
     });
+    r.storeTable(tenantJobFailuresTableMeta, {
+      reason: "direct_write.tenant_job_failures",
+    });
 
     // Framework-provided rebuild job — available whenever `jobs` is composed; enqueueProjectionRebuild dispatches it.
     r.job(
@@ -112,6 +117,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       list: r.queryHandler(listQuery),
       detail: r.queryHandler(detailQuery),
       catalog: r.queryHandler(catalogQuery),
+      failures: r.queryHandler(tenantFailuresQuery),
     };
 
     const systemAdminAccess = { roles: ["SystemAdmin"] as const };

package/src/jobs/handlers/tenant-failures.query.ts

@@ -0,0 +1,82 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import { z } from "zod";
+import { tenantJobFailuresTable } from "../tenant-job-failure-table";
+
+type TenantJobFailureRow = {
+  readonly tenantId: string;
+  readonly jobName: string;
+  readonly subject: string | null;
+  readonly messageKey: string;
+  readonly failedAt: Temporal.Instant;
+};
+
+const DEFAULT_LIMIT = 50;
+
+// Mirrors job-runner.ts's jobSubjectKey: sorted field names, so a caller that
+// passes the same subject values gets the same string the writer stored.
+function subjectKey(subject: Record<string, string | number | boolean | null>): string {
+  return JSON.stringify(
+    Object.keys(subject)
+      .sort()
+      .map((field) => [field, subject[field] ?? null]),
+  );
+}
+
+function isSubjectEntry(value: unknown): value is [string, unknown] {
+  return Array.isArray(value) && typeof value[0] === "string";
+}
+
+function parseSubject(stored: string | null): Record<string, unknown> | null {
+  if (stored === null) return null;
+  // A corrupt subject must not fail the whole list — the record still tells
+  // the tenant which job failed and why. parseJsonSafe only survives a
+  // SyntaxError, so the shape needs its own check.
+  const parsed = parseJsonSafe<unknown>(stored, null);
+  if (!Array.isArray(parsed)) return null;
+  return Object.fromEntries(parsed.filter(isSubjectEntry));
+}
+
+export const tenantFailuresQuery = defineQueryHandler({
+  name: "failures",
+  description:
+    "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
+  schema: z.object({
+    jobName: z.string().optional(),
+    subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    limit: z.number().min(1).max(200).optional(),
+  }),
+  // Every membership rank: a failure record carries a job name and a
+  // translation key, nothing a team member of the tenant may not see.
+  access: { roles: access.roles("User", "Editor", ...access.admin) },
+  handler: async (query, ctx) => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message: "jobs:query:failures requires ctx.systemDb (feature must declare r.systemScope())",
+      });
+    }
+    // assertTenantMatch is a self-check on the caller and returns the same
+    // unfiltered system-mode db (tenant-db.ts) — the explicit tenantId below
+    // is the filter, assertRowsTenant the second net. There is no
+    // cross-tenant mode here: SystemAdmin reads runs via jobs:query:list.
+    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+    const where: Record<string, unknown> = { tenantId: [query.user.tenantId] };
+    if (query.payload.jobName) where["jobName"] = query.payload.jobName;
+    if (query.payload.subject) where["subject"] = subjectKey(query.payload.subject);
+    const rows = await selectMany<TenantJobFailureRow>(db, tenantJobFailuresTable, where, {
+      orderBy: { col: "failedAt", direction: "desc" },
+      limit: query.payload.limit ?? DEFAULT_LIMIT,
+    });
+    return {
+      rows: ctx.systemDb.assertRowsTenant(rows, "tenantId").map((row) => ({
+        jobName: row.jobName,
+        subject: parseSubject(row.subject),
+        messageKey: row.messageKey,
+        failedAt: row.failedAt,
+      })),
+      nextCursor: null,
+    };
+  },
+});

package/src/jobs/index.ts

@@ -4,3 +4,4 @@ export type { JobRunLoggerCallbacks } from "./job-run-logger";
 export { createJobRunLogger } from "./job-run-logger";
 export type { JobLogLevel, JobRunStatus } from "./job-run-table";
 export { jobRunLogsTable, jobRunsTable } from "./job-run-table";
+export { tenantJobFailuresTable } from "./tenant-job-failure-table";

package/src/jobs/job-run-logger.ts

@@ -1,4 +1,10 @@
-import { fetchOne, insertMany, insertOne, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  deleteMany,
+  fetchOne,
+  insertMany,
+  insertOne,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   configuredPiiSubjectKms,
   encryptPiiValueForSubject,
@@ -8,12 +14,18 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
-import type { JobLogEntry, JobMeta, JobRunnerOptions } from "@cosmicdrift/kumiko-framework/jobs";
+import type {
+  JobLogEntry,
+  JobMeta,
+  JobOutcomeMeta,
+  JobRunnerOptions,
+} from "@cosmicdrift/kumiko-framework/jobs";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { mapWithConcurrency } from "../shared";
 import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events";
 import { parseJobInstant } from "./job-instant";
 import { jobRunLogsTable, jobRunsTable } from "./job-run-table";
+import { tenantJobFailuresTable } from "./tenant-job-failure-table";
 
 // Matches PgKmsAdapter's default pool size (see tenant/handlers/*.query.ts) —
 // bounds concurrent getOrCreateDek calls so a large log batch doesn't claim
@@ -138,6 +150,54 @@ async function encryptStartedPayload(
   return encryptOrSentinel(kms, triggeredById, payload, "payload");
 }
 
+// fw#3079 — which row the tenant-visible failure record lives in: one per
+// (tenant, job, subject), so the next outcome of the same work replaces or
+// clears it. `subject` is null for a job that declares no subjectFields.
+// Null target = nothing to write or clear: the job did not opt in, the run
+// was tenant-less (cron resolves to SYSTEM_TENANT_ID, where no tenant-scoped
+// query could ever read the row), or the caller predates fw#3079 and passes
+// no outcome at all.
+function tenantJobFailureTarget(
+  jobName: string,
+  outcome: JobOutcomeMeta | undefined,
+): Record<string, unknown> | null {
+  if (!outcome?.tenantVisible || outcome.tenantId === SYSTEM_TENANT_ID) return null;
+  return { tenantId: outcome.tenantId, jobName, subject: outcome.tenantVisible.subject };
+}
+
+async function recordTenantJobFailure(
+  db: DbConnection,
+  jobName: string,
+  outcome: JobOutcomeMeta | undefined,
+): Promise<void> {
+  const where = tenantJobFailureTarget(jobName, outcome);
+  const messageKey = outcome?.tenantVisible?.messageKey;
+  // skip: no tenant-visible target, or an attempt BullMQ may still retry — a
+  // non-final failure must not show the tenant a failure the next attempt
+  // may still resolve.
+  if (!where || !messageKey || outcome?.finalAttempt !== true) return;
+  // ponytail: delete-then-insert instead of an upsert — two runs of the same
+  // key finishing at once can leave two rows, and the query returns the
+  // newest. Add a unique index + ON CONFLICT if that ever matters.
+  await deleteMany(db, tenantJobFailuresTable, where);
+  await insertOne(db, tenantJobFailuresTable, {
+    ...where,
+    messageKey,
+    failedAt: Temporal.Now.instant(),
+  });
+}
+
+async function clearTenantJobFailure(
+  db: DbConnection,
+  jobName: string,
+  outcome: JobOutcomeMeta | undefined,
+): Promise<void> {
+  const where = tenantJobFailureTarget(jobName, outcome);
+  // skip: no tenant-visible target — nothing was ever recorded
+  if (!where) return;
+  await deleteMany(db, tenantJobFailuresTable, where);
+}
+
 export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallbacks {
   const { db } = opts;
 
@@ -241,11 +301,16 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
     },
 
     onJobComplete: async (
-      _jobName: string,
+      jobName: string,
       bullJobId: string,
       duration: number,
       logs: JobLogEntry[],
+      outcome?: JobOutcomeMeta,
     ) => {
+      // Before the run-row write and independent of it: a successful run
+      // clears the tenant's failure record even when the run row itself is
+      // unreachable (the state-loss return below).
+      await clearTenantJobFailure(db, jobName, outcome);
       const resolved = await resolveRun(bullJobId);
       // skip: state loss between start + complete (worker restart, cache
       // evicted AND DB has no matching bull_job_id). Rare edge case; we
@@ -297,11 +362,15 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
     },
 
     onJobFailed: async (
-      _jobName: string,
+      jobName: string,
       bullJobId: string,
       error: string,
       logs: JobLogEntry[],
+      outcome?: JobOutcomeMeta,
     ) => {
+      // Mirror of onJobComplete: recorded independently of the run row, so a
+      // tenant still learns their job failed if the row is unreachable.
+      await recordTenantJobFailure(db, jobName, outcome);
       const resolved = await resolveRun(bullJobId);
       // skip: same rare state-loss case as in onJobComplete — drop the
       // failure write rather than forge a run row from scratch.

package/src/jobs/tenant-job-failure-table.ts

@@ -0,0 +1,39 @@
+import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  type EntityTableMeta,
+  instant,
+  table as pgTable,
+  serial,
+  sql,
+  text,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+
+// The tenant's own view of a failed job (fw#3079). Direct-write store like
+// store_job_runs: job-run-logger.ts writes it from the BullMQ callbacks,
+// outside any dispatcher transaction.
+//
+// Deliberately holds no error text. `message_key` is a translation key
+// (the thrown KumikoError's i18nKey or the one declared at the job), so a
+// provider message can never reach the tenant through this table — it stays
+// on store_job_runs.error and in store_job_run_logs, both SystemAdmin-only.
+//
+// One row per (tenant, job, subject): a later final-attempt failure replaces
+// it, a later successful run of the same key deletes it. `subject` is the
+// canonical JSON of the job's declared subjectFields, or NULL for a job that
+// declares none — stored in clear, so a job must not declare a PII field
+// as its subject.
+export const tenantJobFailuresTable = pgTable("store_tenant_job_failures", {
+  id: serial("id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  jobName: text("job_name").notNull(),
+  subject: text("subject"),
+  messageKey: text("message_key").notNull(),
+  failedAt: instant("failed_at").default(sql`now()`).notNull(),
+});
+
+const derivedTenantJobFailuresTableMeta = asEntityTableMeta(tenantJobFailuresTable);
+if (!derivedTenantJobFailuresTableMeta) {
+  throw new Error("tenantJobFailuresTable: table carries no EntityTableMeta — built via table()?");
+}
+export const tenantJobFailuresTableMeta: EntityTableMeta = derivedTenantJobFailuresTableMeta;

package/src/rate-limiting/__tests__/rate-limiting.integration.test.ts

@@ -7,7 +7,12 @@
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+} from "@cosmicdrift/kumiko-framework/stack";
 import { z } from "zod";
 import { createRateLimitingFeature } from "../feature";
 
@@ -93,3 +98,66 @@ describe("rate-limiting feature — status query", () => {
     expect(res.status).toBe(403);
   });
 });
+
+// The bucket key is caller-supplied, so the tenant boundary has to be drawn
+// on it server-side. i18nKey is asserted alongside the code because a plain
+// 403 could also come from tenant resolution and would pass either way.
+const OUTSIDE_TENANT_KEY = "rateLimiting.errors.bucketOutsideTenant";
+
+describe("rate-limiting feature — bucket tenant scope", () => {
+  test("denies an admin the bucket of another tenant", async () => {
+    const err = await stack.http.queryErr(
+      "rate-limiting:query:status",
+      { bucket: `tenant:${testTenantId(2)}`, limit: 5, windowSeconds: 60 },
+      admin,
+    );
+    expect(err.code).toBe("access_denied");
+    expect(err.i18nKey).toBe(OUTSIDE_TENANT_KEY);
+    expect(err.httpStatus).toBe(403);
+  });
+
+  test("denies a key that only starts with the caller's tenant id", async () => {
+    const err = await stack.http.queryErr(
+      "rate-limiting:query:status",
+      { bucket: `tenant:${admin.tenantId}-other`, limit: 5, windowSeconds: 60 },
+      admin,
+    );
+    expect(err.i18nKey).toBe(OUTSIDE_TENANT_KEY);
+  });
+
+  test("denies another user's bucket and the global IP buckets", async () => {
+    for (const bucket of [`user:${TestUsers.user.id}`, "l1:203.0.113.5", "ip:203.0.113.5"]) {
+      const err = await stack.http.queryErr(
+        "rate-limiting:query:status",
+        { bucket, limit: 5, windowSeconds: 60 },
+        admin,
+      );
+      expect(err.i18nKey).toBe(OUTSIDE_TENANT_KEY);
+    }
+  });
+
+  test("allows the caller's own tenant and handler-scoped buckets", async () => {
+    for (const bucket of [
+      `tenant:${admin.tenantId}`,
+      `tenant+handler:${admin.tenantId}:rl-probe:query:ping`,
+      `user+handler:${admin.id}:rl-probe:query:ping`,
+    ]) {
+      const status = await stack.http.queryOk<{ bucket: string; remaining: number }>(
+        "rate-limiting:query:status",
+        { bucket, limit: 5, windowSeconds: 60 },
+        admin,
+      );
+      expect(status.bucket).toBe(bucket);
+      expect(status.remaining).toBe(5);
+    }
+  });
+
+  test("leaves SystemAdmin access to foreign buckets untouched", async () => {
+    const status = await stack.http.queryOk<{ bucket: string }>(
+      "rate-limiting:query:status",
+      { bucket: `tenant:${testTenantId(2)}`, limit: 5, windowSeconds: 60 },
+      TestUsers.systemAdmin,
+    );
+    expect(status.bucket).toBe(`tenant:${testTenantId(2)}`);
+  });
+});

package/src/rate-limiting/changes.json

@@ -1 +1,9 @@
-[]
+[
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "`rate-limiting:query:status` only peeks buckets of the calling tenant (fw#3076)",
+    "detail": "The handler took an arbitrary bucket key and peeked it, so a tenant Admin who knew or guessed another tenant's key could read that bucket's counter. The key is now matched segment-exact against the caller: `tenant:`/`tenant+handler:` must carry the caller's own tenant id, `user:`/`user+handler:` the caller's own user id. Everything else — other tenants, other users, the global `ip:`, `l1:` and `l2:` middleware buckets, malformed keys — is `access_denied` (`bucket_outside_tenant`) unless the caller is SystemAdmin, whose access is unchanged. The check runs before the resolver-wiring check, so a denied caller learns nothing about the mount either.",
+    "migration": "Only affects non-SystemAdmin callers of `rate-limiting:query:status`. A tenant\nAdmin keeps `tenant:<own>`, `tenant+handler:<own>:<handler>`, `user:<self>` and\n`user+handler:<self>:<handler>`. Two reads it had before now need SystemAdmin:\nanother user's bucket inside the same tenant (the tenant is not part of a\n`user:` key, so it cannot be verified without a membership lookup) and the\nglobal `ip:`/`l1:`/`l2:` buckets, which are not tenant-owned. Ops tooling that\npeeks those from a tenant Admin session has to run as SystemAdmin."
+  }
+]

package/src/rate-limiting/constants.ts

@@ -6,4 +6,5 @@ export const RateLimitQueries = {
 
 export const RateLimitErrors = {
   resolverUnavailable: "rate_limit_resolver_unavailable",
+  bucketOutsideTenant: "bucket_outside_tenant",
 } as const;

package/src/rate-limiting/handlers/bucket-access.ts

@@ -0,0 +1,39 @@
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { RateLimitErrors } from "../constants";
+
+// Bucket keys are `<dimension>:<subject>[:<handler>]` (framework
+// rate-limit/bucket.ts) — only `tenant*` and `user*` carry a subject the
+// caller can own. `l1:`/`l2:` (middleware.ts) and every `ip*` bucket are
+// global, so they stay SystemAdmin-only.
+type BucketCaller = {
+  readonly id: string;
+  readonly tenantId: string;
+  readonly roles: readonly string[];
+};
+
+function ownsBucket(bucket: string, caller: BucketCaller): boolean {
+  const [dimension, subject, ...handler] = bucket.split(":");
+  if (dimension === undefined) return false;
+  const owner =
+    dimension === "tenant" || dimension === "tenant+handler"
+      ? caller.tenantId
+      : dimension === "user" || dimension === "user+handler"
+        ? caller.id
+        : undefined;
+  if (owner === undefined) return false;
+  // Segment-exact: a startsWith check would pass `tenant:<own-id>-other`.
+  if (subject !== owner) return false;
+  return dimension.endsWith("+handler") ? handler.length > 0 : handler.length === 0;
+}
+
+export function bucketAccessDenied(
+  bucket: string,
+  caller: BucketCaller,
+): AccessDeniedError | undefined {
+  if (caller.roles.includes("SystemAdmin")) return undefined;
+  if (ownsBucket(bucket, caller)) return undefined;
+  return new AccessDeniedError({
+    i18nKey: "rateLimiting.errors.bucketOutsideTenant",
+    details: { reason: RateLimitErrors.bucketOutsideTenant },
+  });
+}

package/src/rate-limiting/handlers/status.query.ts

@@ -2,6 +2,7 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { RateLimitErrors } from "../constants";
+import { bucketAccessDenied } from "./bucket-access";
 
 // Ops-side bucket inspection. Pass the bucket key (e.g. "user:42",
 // "user+handler:42:orders:write:order:create") plus the limit/window the bucket
@@ -16,14 +17,15 @@ import { RateLimitErrors } from "../constants";
 // Bucket key format is owned by the framework (see rate-limit/bucket.ts);
 // callers pass the constructed key directly. We don't synthesize from
 // (per, user, handler) here — peeking is a low-level op, the lookup
-// surface stays small.
+// surface stays small. Because the key is caller-supplied, bucket-access.ts
+// restricts it to the caller's own tenant/user unless they are SystemAdmin.
 export const rateLimitStatus = defineQueryHandler({
   // Short name — the registry qualifies this to `rate-limiting:query:status`
   // when the feature is registered. Passing the qualified form here would
   // double-prefix it and the handler wouldn't be reachable.
   name: "status",
   description:
-    "Peeks at one rate-limit bucket and returns its remaining tokens, window and next reset without consuming a token; use it to explain why a caller is being throttled.",
+    "Peeks at one rate-limit bucket and returns its remaining tokens, window and next reset without consuming a token; use it to explain why a caller is being throttled. Non-SystemAdmin callers may only peek their own tenant's buckets (`tenant:`/`tenant+handler:`) and their own user buckets (`user:`/`user+handler:`); every other key, including the global `ip:`/`l1:`/`l2:` buckets, requires SystemAdmin.",
   schema: z.object({
     bucket: z.string().min(1),
     limit: z.number().int().positive(),
@@ -31,6 +33,10 @@ export const rateLimitStatus = defineQueryHandler({
   }),
   access: { roles: ["Admin", "SystemAdmin"] },
   handler: async (query, ctx) => {
+    // Before the resolver check, so a foreign-tenant caller learns nothing
+    // about the wiring either.
+    const denied = bucketAccessDenied(query.payload.bucket, ctx.user);
+    if (denied) throw denied;
     if (!ctx.rateLimit) {
       throw new UnprocessableError(RateLimitErrors.resolverUnavailable, {
         i18nKey: "rateLimiting.errors.resolverUnavailable",