@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -53,6 +53,12 @@ export class FileRefTooLargeError extends Error {
   }
 }
 
+export class FileStorageUnavailableError extends Error {
+  constructor() {
+    super("readFileRefContent: no file storage is available for the file's tenant");
+  }
+}
+
 // fileName of the row is never used: it is personal data and may be a PII ciphertext.
 export async function readFileRefContent(args: {
   readonly db: DbRunner | TenantDb;
@@ -82,7 +88,7 @@ export async function readFileRefContent(args: {
   }
   const files = args.filesForTenant(row.tenantId);
   if (files === undefined) {
-    throw new Error("readFileRefContent: no file storage is available for the file's tenant");
+    throw new FileStorageUnavailableError();
   }
   const content = await files.refFromFileRef(row).read();
   return { content, contentType: row.mimeType, tenantId: row.tenantId, size };

package/packages/bundled-features/src/file-provider-s3/env-named-feature.ts

@@ -13,8 +13,6 @@ export type NamedS3EnvProviderOptions = {
   readonly name: string;
   /** Env prefix of the credential set, e.g. `RELEASES_S3_`. */
   readonly envPrefix: string;
-  /** Tolerate missing credentials at boot; the provider then fails on its first file operation. */
-  readonly lazy?: boolean;
 };
 
 /** An additional S3 provider next to `"s3-env"`, reading its credentials from `<envPrefix>BUCKET` etc. */

package/packages/bundled-features/src/files/README.md

@@ -15,7 +15,7 @@ bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
 ## Was es NICHT macht
 
 - **Keine Upload-/Download-Routes** — die bleiben in
-  `framework/src/api/server.ts` via `options.files`-Bootstrap.
+  `framework/src/api/server-routes.ts` (`mountFileRoutes`).
   Multipart-Form-Body und Binary-Streaming passen nicht ins Write/Query-
   Handler-Pattern; ein Refactor zu `r.httpRoute` wäre orthogonal zu
   diesem Sprint.

package/packages/bundled-features/src/form-draft/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Encrypted drafts without a PII key service raise an error",
+    "detail": "Reading a ciphertext draft with no PII subject key service configured throws instead of returning an empty draft, so the stale-draft cleanup defers it and no longer releases its file refs as if it were empty."
+  },
   {
     "version": "0.379.0",
     "type": "breaking",

package/packages/bundled-features/src/form-draft/db/queries/cleanup.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { readStoredDraft } from "../../decrypt-draft.ts";
@@ -48,7 +48,7 @@ export async function selectStaleDraftsBatch(
      AND NOT ("id"::text = ANY($3::text[]))
      ORDER BY COALESCE("modified_at", "inserted_at") ASC
      LIMIT $2`,
-    [olderThanDays, batchSize, [...excludeIds]],
+    [olderThanDays, batchSize, toPostgresArrayLiteral([...excludeIds])],
   );
   return Promise.all(
     rows.map(async (row) => {

package/packages/bundled-features/src/form-draft/decrypt-draft.ts

@@ -4,6 +4,7 @@ import {
   decryptPiiFieldValues,
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { type FormDraftBlob, formDraftBlobSchema } from "./schemas.ts";
 
 // Raw reads (fetchOne/selectMany/SQL) return the stored column, which is
@@ -13,7 +14,9 @@ import { type FormDraftBlob, formDraftBlobSchema } from "./schemas.ts";
 export async function readStoredDraft(stored: unknown): Promise<FormDraftBlob | null> {
   let plain = stored;
   const kms = configuredPiiSubjectKms();
-  if (isPiiCiphertext(stored) && kms) {
+  if (isPiiCiphertext(stored)) {
+    // A silent null would make the stale-draft cleanup treat the draft as empty and leak its file refs.
+    if (!kms) throw new InternalError({ message: "form-draft: pii kms not configured" });
     const out = await decryptPiiFieldValues({ draft: stored }, ["draft"], kms, {
       requestId: requestContext.get()?.requestId ?? "form-draft:read",
     });

package/packages/bundled-features/src/host-routing/README.md

@@ -92,5 +92,5 @@ allowlists stay in the app: wrap the dispatch function and fall through to it.
 
 - `tenantBy: (host, db) => TenantId | null` resolves every host that is neither the apex nor a fixed host (profile subdomains, custom domains). The tenant must be enabled and active; null means 404 for pages and `tenant_required` for the API. `createHostTenantIdResolver(options, db)` exposes the same mapping for managed-pages' `resolveApexTenant`.
 - `tenantPathPrefix` is optional in host and resolver mode and serves `<prefix>/<key>` on the apex. The API half still takes the apex anchor there; an app that needs a path-named tenant on API calls resolves it itself.
-- `redirects: [{ from, to, host?, status? }]` run before host classification. `to` is configured, never derived from the request.
+- `redirects: [{ from, to, host?, status? }]` run before host classification inside hostDispatch, i.e. only for requests that reach the HTML fallback (no static file, no API route); a `from` that matches a static file or `/api/...` never fires. `to` is configured, never derived from the request.
 - `apexAnonymousQueryAllowlist: { "example.com": ["feature:query:x"] }` limits the anonymous apex anchor to the listed query types on that host, for `/api/query` and `/api/stream`; other paths keep the anchor. `example.com` and `www.example.com` share one entry (a host without its own uses the other's). Combined with `tenantBy: "path"` it throws at boot, because the client names its tenant there (X-Tenant wins over the resolver) and would bypass the allowlist.

package/packages/bundled-features/src/host-routing/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Redirects from /api paths fail at boot",
+    "detail": "Redirects run inside hostDispatch after static files and API routes, so a from of /api or /api/... was silently dead config. Boot validation now throws; the options and README already describe the HTML-fallback scope."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Redirects documented as hostDispatch-only",
+    "detail": "The redirects option and README state that redirects run inside hostDispatch, so only for requests that reach the HTML fallback; a from matching a static file or an API route never fires. The shared existence lookup of the host and resolver modes is one helper."
+  },
   {
     "version": "0.376.0",
     "type": "improvement",

package/packages/bundled-features/src/host-routing/dispatch.ts

@@ -30,33 +30,32 @@ export type HostRoutingDispatchFn = (
 
 const tenantKeyExistsResultSchema = z.object({ exists: z.boolean() });
 
-async function isTenantKeyKnown(systemQuery: PageHeadSystemQuery, key: string): Promise<boolean> {
+async function existsViaSystemQuery(
+  systemQuery: PageHeadSystemQuery,
+  queryType: string,
+  payload: Record<string, string>,
+): Promise<boolean> {
   let result: unknown;
   try {
-    result = await systemQuery(HostRoutingQueries.tenantKeyExists, { key }, SYSTEM_TENANT_ID);
+    result = await systemQuery(queryType, payload, SYSTEM_TENANT_ID);
   } catch (error) {
     if (error instanceof ValidationError) return false;
-    // Over the rate limit every key looks the same: serve the tenant shell,
-    // which leaks nothing; the API behind it still resolves the tenant itself.
+    // Over the rate limit every key looks the same: serve the shell, which
+    // leaks nothing. The API resolver is authoritative and answers
+    // tenant_required for unknown hosts, while a 404 would hit visitors
+    // behind a shared NAT under load.
     if (error instanceof RateLimitError) return true;
     throw error;
   }
   return tenantKeyExistsResultSchema.parse(result).exists;
 }
 
-async function isHostKnown(systemQuery: PageHeadSystemQuery, host: string): Promise<boolean> {
-  let result: unknown;
-  try {
-    result = await systemQuery(HostRoutingQueries.hostTenantExists, { host }, SYSTEM_TENANT_ID);
-  } catch (error) {
-    if (error instanceof ValidationError) return false;
-    // The shell is harmless: the API resolver is authoritative and answers
-    // tenant_required for unknown hosts, while a 404 would hit visitors behind
-    // a shared NAT under load.
-    if (error instanceof RateLimitError) return true;
-    throw error;
-  }
-  return tenantKeyExistsResultSchema.parse(result).exists;
+function isTenantKeyKnown(systemQuery: PageHeadSystemQuery, key: string): Promise<boolean> {
+  return existsViaSystemQuery(systemQuery, HostRoutingQueries.tenantKeyExists, { key });
+}
+
+function isHostKnown(systemQuery: PageHeadSystemQuery, host: string): Promise<boolean> {
+  return existsViaSystemQuery(systemQuery, HostRoutingQueries.hostTenantExists, { host });
 }
 
 function serve(

package/packages/bundled-features/src/host-routing/options.ts

@@ -81,6 +81,7 @@ export type HostRoutingOptions = HostRoutingTenantMode & {
   // Not allowed with tenantBy "path" (boot error): there the client's X-Tenant
   // wins over the resolver, so the allowlist would be ineffective.
   readonly apexAnonymousQueryAllowlist?: Readonly<Record<string, readonly string[]>>;
-  // Checked first, before any host classification.
+  // Checked first within hostDispatch, i.e. only for requests that reach the HTML
+  // fallback (no static file, no API route): a `from` matching either never fires.
   readonly redirects?: readonly HostRoutingRedirect[];
 };

package/packages/bundled-features/src/host-routing/validate-options.ts

@@ -16,6 +16,11 @@ function validateRedirects(options: HostRoutingOptions): void {
     if (!REDIRECT_PATH_PATTERN.test(rule.from)) {
       throw new Error(`host-routing: redirect from must be a path like "/old", got "${rule.from}"`);
     }
+    if (rule.from === "/api" || rule.from.startsWith("/api/")) {
+      throw new Error(
+        `host-routing: redirect from must not be an /api path, it would never fire, got "${rule.from}"`,
+      );
+    }
     if (!REDIRECT_TARGET_PATTERN.test(rule.to)) {
       throw new Error(
         `host-routing: redirect to must be a same-origin path or an https URL without query, got "${rule.to}"`,

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Undecryptable mail account no longer stops polling of other accounts",
+    "detail": "Any decryption failure of an account address (corrupt envelope, missing key, AAD mismatch) is logged by error class and the account is skipped; the other accounts keep polling."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Rename audit reason comes from the caller role",
+    "detail": "update-account records tenant_admin or system_admin from the caller's roles and honors a client-supplied reason only for the system identity, so a form call can no longer write system reasons such as watch_supervisor. The rename form no longer carries a reason field and the reason payload field is optional."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Seen-message lookup handles listings of any size",
+    "detail": "filterUnknownMessageIds queries the already seen provider message ids in chunks of 1000, so a full-mailbox listing no longer exceeds the Postgres bind parameter limit and aborts the account's poll."
+  },
   {
     "version": "0.378.0",
     "type": "fix",

package/packages/bundled-features/src/inbound-mail-foundation/feature.ts

@@ -103,6 +103,7 @@ export function createInboundMailFoundationFeature() {
   return defineFeature(
     INBOUND_MAIL_FOUNDATION_FEATURE,
     (r) => {
+      r.adoptsBundledLists();
       r.describe(
         "Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.",
       );

package/packages/bundled-features/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -3,7 +3,12 @@
 // the account after fixing its credentials. Full-snapshot event: loads the
 // latest state, merges the delta fields, and appends the new snapshot.
 
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import {
+  type SessionUser,
+  SYSTEM_USER_ID,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { InboundMailAccountStatuses } from "../constants.ts";
@@ -27,12 +32,19 @@ export const updateAccountSchema = z.object({
   /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
   watchState: z.string().max(100).optional(),
   displayName: z.string().max(200).optional(),
-  /** Audit reason for metadata.headers ("watch_supervisor",
-   *  "oauth_refresh", "tenant_admin"). */
-  reason: z.string().min(1).max(100),
+  /** Audit reason for metadata.headers, honored for the system identity only
+   *  ("watch_supervisor", "oauth_refresh"); user callers get a role-derived reason. */
+  reason: z.string().min(1).max(100).optional(),
 });
 type UpdateAccountPayload = z.infer<typeof updateAccountSchema>;
 
+const SYSTEM_FALLBACK_REASON = "system";
+
+function auditReasonFor(user: SessionUser, requestedReason: string | undefined): string {
+  if (user.id === SYSTEM_USER_ID) return requestedReason ?? SYSTEM_FALLBACK_REASON;
+  return user.roles.includes(ROLES.SystemAdmin) ? "system_admin" : "tenant_admin";
+}
+
 export const updateAccountHandler: WriteHandlerDef = {
   name: "update-account",
   schema: updateAccountSchema,
@@ -65,7 +77,7 @@ export const updateAccountHandler: WriteHandlerDef = {
     };
     const headers: MailAccountEventHeaders = {
       providerName: current.provider,
-      reason: payload.reason,
+      reason: auditReasonFor(event.user, payload.reason),
     };
     await ctx.unsafeAppendEvent({
       aggregateId: payload.accountId,

package/packages/bundled-features/src/inbound-mail-foundation/i18n.ts

@@ -38,5 +38,4 @@ export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en
   },
   [formFieldKey("accountId")]: { en: "Mailbox" },
   [formFieldKey("displayName")]: { en: "Name" },
-  [formFieldKey("reason")]: { en: "Reason" },
 };

package/packages/bundled-features/src/inbound-mail-foundation/screens.ts

@@ -77,8 +77,6 @@ export const mailAccountListScreen: ProjectionListScreenDefinition = {
   dormant: true,
 };
 
-// The reason is the audit label update-account requires; it is not in the
-// layout, so the default is what gets written.
 export const mailAccountEditScreen: ActionFormScreenDefinition = {
   id: MAIL_ACCOUNT_EDIT_SCREEN_ID,
   type: "actionForm",
@@ -87,7 +85,6 @@ export const mailAccountEditScreen: ActionFormScreenDefinition = {
   fields: {
     accountId: { type: "text", required: true },
     displayName: { type: "text", required: true, maxLength: 200 },
-    reason: { type: "text", default: "tenant_admin" },
   },
   layout: {
     sections: [{ fields: [{ field: "accountId", readOnly: true }, "displayName"] }],

package/packages/bundled-features/src/inbound-mail-foundation/types.ts

@@ -21,8 +21,9 @@ import { INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus } from "
  *   config   — tenant config reads (host/port/... of the plugins)
  *   registry — extension lookup in the factory (not plugin-internal)
  *   secrets  — tenant secret reads (IMAP password, OAuth refresh token)
- *   auditUserId  — audit identity for secret reads. Handler path: the dispatcher
- *              sets the caller user ID; worker path: system identity.
+ *   auditUserId  — audit identity for secret reads. Handler path: unset,
+ *              requireSecretsContext falls back to ctx.user.id; worker/provider
+ *              path: system identity set by the resolver.
  *   metricsFor — metrics handle of a feature by name, same behavior as
  *              HandlerContext.metricsFor: unregistered metrics are a silent
  *              no-op instead of a throw.
@@ -172,7 +173,7 @@ export type InboundMailProviderPlugin = {
        *  for password accounts and providers without an oauth flow. */
       readonly accessToken?: string;
       /** Batch lookup of the provider message ids not yet ingested for this
-       *  account (committed seen anchors, one query per call). Call it after
+       *  account (committed seen anchors; lists of any size are fine, queried in chunks). Call it after
        *  the listing/delta page and download MIME only for the returned ids.
        *  Ingest dedup stays the correctness anchor; this only saves downloads. */
       readonly filterUnknownMessageIds?: (

package/packages/bundled-features/src/inbound-mail-foundation/watch-supervisor.ts

@@ -88,6 +88,8 @@ const DEFAULT_WATCH_LEASE_TTL_SECONDS = 90;
  *  can add further scopes later without a schema change. */
 const CURSOR_SCOPE = "default";
 
+const SEEN_LOOKUP_CHUNK_SIZE = 1000;
+
 export type InboundMailSupervisorDeps = {
   /** Slim context for provider calls (`registry` is required; `secrets` is
    *  used for provider credential reads). */
@@ -223,11 +225,19 @@ export function createInboundMailSupervisor(
     const piiKms = configuredPiiSubjectKms();
     const records: MailAccountRecord[] = [];
     for (const row of rows) {
-      const decrypted = piiKms
-        ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
-            requestId: "inbound-mail-foundation:supervisor:list-accounts",
-          })
-        : row;
+      let decrypted: Record<string, unknown>;
+      try {
+        decrypted = piiKms
+          ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+              requestId: "inbound-mail-foundation:supervisor:list-accounts",
+            })
+          : row;
+      } catch (error) {
+        // Class name only: the message may carry ciphertext or key details.
+        const errorName = error instanceof Error ? error.name : "unknown error";
+        log(`inbound-mail: account ${row.id} skipped — address did not decrypt (${errorName})`);
+        continue;
+      }
       const decryptedAddress = decrypted["address"];
       // Falling back to row.address would hand the ciphertext to a provider.
       // One undecryptable account must not stop polling of every other tenant's accounts.
@@ -400,17 +410,23 @@ export function createInboundMailSupervisor(
   function unknownMessageIdsFilterFor(account: MailAccountRecord) {
     return async (providerMessageIds: readonly string[]): Promise<ReadonlySet<string>> => {
       if (providerMessageIds.length === 0) return new Set();
-      const seen = await selectMany<{ providerMessageId: string }>(
-        deps.db,
-        seenMessageTable,
-        {
-          tenantId: account.tenantId,
-          accountId: account.id,
-          providerMessageId: { in: providerMessageIds },
-        },
-        { fields: ["providerMessageId"] },
-      );
-      const seenIds = new Set(seen.map((row) => row.providerMessageId));
+      // One bind parameter per id: a full-mailbox listing would exceed Postgres' 65535 limit.
+      const seenIds = new Set<string>();
+      for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
+        const seen = await selectMany<{ providerMessageId: string }>(
+          deps.db,
+          seenMessageTable,
+          {
+            tenantId: account.tenantId,
+            accountId: account.id,
+            providerMessageId: {
+              in: providerMessageIds.slice(start, start + SEEN_LOOKUP_CHUNK_SIZE),
+            },
+          },
+          { fields: ["providerMessageId"] },
+        );
+        for (const row of seen) seenIds.add(row.providerMessageId);
+      }
       return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
     };
   }

package/packages/bundled-features/src/jobs/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "readRoles for tenant job status",
+    "detail": "`createJobsFeature({ readRoles: [\"PropertyManager\"] })` lets those app roles call `jobs:query:failures` and `jobs:query:tenant-runs` for their own tenant. They are added to the default `User`, `Editor` and admin roles, which stay. Before, a member who only holds app roles got access_denied.",
+    "migration": "Optional. Apps whose members hold only their own roles pass `createJobsFeature({ readRoles: [...] })`."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Deduplicated job add keeps the finished tenant run row",
+    "detail": "JobQueuedMeta carries the BullMQ creation time of the job. The queued hook only removes finished rows queued before that time (leftovers of a Redis reset), so re-announcing an already finished job no longer turns its row back into queued."
+  },
   {
     "version": "0.384.0",
     "type": "improvement",

package/packages/bundled-features/src/jobs/feature.ts

@@ -23,8 +23,8 @@ import {
   createStaleRunSweepJob,
   DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS,
 } from "./handlers/stale-run-sweep.job.ts";
-import { tenantFailuresQuery } from "./handlers/tenant-failures.query.ts";
-import { tenantRunsQuery } from "./handlers/tenant-runs.query.ts";
+import { createTenantFailuresQuery } from "./handlers/tenant-failures.query.ts";
+import { createTenantRunsQuery } from "./handlers/tenant-runs.query.ts";
 import { triggerWrite } from "./handlers/trigger.write.ts";
 import { jobRunLogsTableMeta, jobRunsTableMeta } from "./job-run-table.ts";
 import {
@@ -49,12 +49,23 @@ export type JobsFeatureOptions = {
   // it). Must clear any legitimately long-running job (reindexEntity,
   // projectionRebuild) — set high, not tight.
   readonly staleRunTimeoutHours?: number;
+  // Additional app roles that may read their own tenant's job status and
+  // failures (jobs:query:failures, jobs:query:tenant-runs). Added to the default
+  // User/Editor/admin roles, which stay; the scope stays the caller's own tenant.
+  readonly readRoles?: readonly string[];
 };
 
 export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefinition {
   const retentionDays = options.retentionDays ?? DEFAULT_JOB_RUN_RETENTION_DAYS;
   const staleRunTimeoutHours = options.staleRunTimeoutHours ?? DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS;
+  const readRoles = options.readRoles ?? [];
+  if (readRoles.includes("anonymous")) {
+    throw new Error(
+      `createJobsFeature: readRoles must not contain "anonymous" — job status and failures are only readable by members of the tenant.`,
+    );
+  }
   return defineFeature("jobs", (r) => {
+    r.adoptsBundledLists();
     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. 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). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops `queued` rows older than `retentionDays`.",
     );
@@ -137,8 +148,8 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       list: r.queryHandler(listQuery),
       detail: r.queryHandler(detailQuery),
       catalog: r.queryHandler(catalogQuery),
-      failures: r.queryHandler(tenantFailuresQuery),
-      tenantRuns: r.queryHandler(tenantRunsQuery),
+      failures: r.queryHandler(createTenantFailuresQuery(readRoles)),
+      tenantRuns: r.queryHandler(createTenantRunsQuery(readRoles)),
       consumers: r.queryHandler(consumersQuery),
       consumerDetails: r.queryHandler(consumerDetailQuery),
     };

package/packages/bundled-features/src/jobs/handlers/tenant-failures.query.ts

@@ -30,44 +30,49 @@ function parseSubject(stored: string | null): Record<string, unknown> | 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; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; 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().int().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())",
+export function createTenantFailuresQuery(readRoles: readonly string[]) {
+  return 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; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; 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().int().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: [...new Set([...access.roles("User", "Editor", ...access.admin), ...readRoles])],
+    },
+    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"] = serializeJobSubject(query.payload.subject);
+      const rows = await selectMany<TenantJobFailureRow>(db, tenantJobFailuresTable, where, {
+        orderBy: { col: "failedAt", direction: "desc" },
+        limit: query.payload.limit ?? DEFAULT_LIMIT,
       });
-    }
-    // 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"] = serializeJobSubject(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,
-    };
-  },
-});
+      return {
+        rows: ctx.systemDb.assertRowsTenant(rows, "tenantId").map((row) => ({
+          jobName: row.jobName,
+          subject: parseSubject(row.subject),
+          messageKey: row.messageKey,
+          failedAt: row.failedAt,
+        })),
+        nextCursor: null,
+      };
+    },
+  });
+}