@cosmicdrift/kumiko-samples 0.352.0 → 0.354.0

package/packages/bundled-features/src/folders/handlers/delete-folder.write.ts

@@ -1,6 +1,7 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { hostRowIsGone } from "../../shared/index.js";
 import { DEFAULT_FOLDER_ACCESS } from "../constants.js";
 import { folderAssignmentExecutor, folderExecutor } from "../executor.js";
 
@@ -13,6 +14,12 @@ const deleteFolderPayloadSchema = z.object({ id: z.uuid() });
 // see 658/1). Block server-side instead: this is the same "referential
 // integrity has no FK here" reasoning set-folder.write.ts already applies to
 // folderId on assignment-creation.
+//
+// Assignments whose host is gone (hard-deleted, soft-deleted or unregistered)
+// are cleaned up here instead of blocking forever: clear-folder can't reach
+// them (it requires a visible host). A host-delete hook would break restore,
+// so the cleanup runs lazily at folder:delete.
+const ASSIGNMENT_PAGE_SIZE = 200;
 export function createDeleteFolderHandler(
   access: AccessRule = DEFAULT_FOLDER_ACCESS,
 ): WriteHandlerDef {
@@ -21,19 +28,44 @@ export function createDeleteFolderHandler(
     schema: deleteFolderPayloadSchema,
     access,
     description:
-      "Deletes a folder from the tenant catalog and refuses while any entity is still filed in it; use it once that folder's contents have been unfiled or moved elsewhere.",
+      "Deletes a folder from the tenant catalog and refuses while any live entity is still filed in it (assignments of deleted hosts are cleaned up); use it once that folder's contents have been unfiled or moved elsewhere.",
     agent: { risk: "high" },
     handler: async (event, ctx) => {
       const payload = event.payload as { id: string }; // @cast-boundary engine-payload
-      const assigned = await folderAssignmentExecutor.list(
-        { filter: { field: "folderId", op: "eq", value: payload.id }, limit: 1 },
-        event.user,
-        ctx.db,
-      );
-      if (assigned.rows.length > 0) {
-        return writeFailure(
-          new UnprocessableError("folder_has_assignments", { details: { folderId: payload.id } }),
+      const orphanAssignmentIds: string[] = [];
+      let cursor: string | undefined;
+      do {
+        const page = await folderAssignmentExecutor.list(
+          {
+            filter: { field: "folderId", op: "eq", value: payload.id },
+            limit: ASSIGNMENT_PAGE_SIZE,
+            cursor,
+          },
+          event.user,
+          ctx.db,
         );
+        for (const row of page.rows) {
+          const gone = await hostRowIsGone(
+            ctx.registry,
+            String(row["entityType"]),
+            String(row["entityId"]),
+            ctx.db,
+          );
+          if (!gone) {
+            return writeFailure(
+              new UnprocessableError("folder_has_assignments", {
+                details: { folderId: payload.id },
+              }),
+            );
+          }
+          orphanAssignmentIds.push(String(row["id"]));
+        }
+        cursor = page.nextCursor ?? undefined;
+      } while (cursor !== undefined);
+
+      for (const id of orphanAssignmentIds) {
+        const removed = await folderAssignmentExecutor.delete({ id }, event.user, ctx.db);
+        if (!removed.isSuccess) return removed;
       }
       return folderExecutor.delete({ id: payload.id }, event.user, ctx.db);
     },

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

@@ -1 +1,7 @@
-[]
+[
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "The stale-draft cleanup keeps sweeping when a whole batch was re-saved in the meantime"
+  }
+]

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

@@ -57,6 +57,7 @@ export async function selectStaleDraftsBatch(
 /** Re-check staleness after the select→release window so a freshly saved draft is not deleted. */
 export async function isDraftStillStale(
   db: DbConnection,
+  tenantId: TenantId,
   id: string,
   olderThanDays: number,
 ): Promise<boolean> {
@@ -64,9 +65,10 @@ export async function isDraftStillStale(
     db,
     `SELECT 1 FROM "read_form_drafts"
      WHERE "id" = $1
-       AND COALESCE("modified_at", "inserted_at") < now() - ($2::int * interval '1 day')
+       AND "tenant_id" = $2
+       AND COALESCE("modified_at", "inserted_at") < now() - ($3::int * interval '1 day')
      LIMIT 1`,
-    [id, olderThanDays],
+    [id, tenantId, olderThanDays],
   )) as readonly unknown[];
   return rows.length > 0;
 }

package/packages/bundled-features/src/form-draft/handlers/cleanup.job.ts

@@ -121,20 +121,24 @@ export function groupStaleDraftIdsByTenant(
 // resurrects, PII included. formDraftExecutor.delete() is the event-sourced
 // path; it needs a tenant-scoped db + a SessionUser, so rows are grouped by
 // tenant first (see groupStaleDraftIdsByTenant above).
-async function deleteStaleDraftsBatch(
+export async function deleteStaleDraftsBatch(
   batch: readonly StaleDraftRow[],
   db: DbConnection,
   retentionDays: number,
   log: AppContext["log"],
-): Promise<readonly StaleDraftRow[]> {
+): Promise<{ readonly deletedRows: readonly StaleDraftRow[]; readonly skippedCount: number }> {
   const deletedRows: StaleDraftRow[] = [];
+  let skippedCount = 0;
   const byId = new Map(batch.map((row) => [row.id, row]));
   for (const [tenantId, ids] of groupStaleDraftIdsByTenant(batch)) {
     const systemUser = createSystemUser(tenantId);
     const tenantDb = createTenantDb(db, tenantId, "system");
     for (const id of ids) {
       // Race: user may have saved between select and here — skip if no longer stale.
-      if (!(await isDraftStillStale(db, id, retentionDays))) continue;
+      if (!(await isDraftStillStale(db, tenantId, id, retentionDays))) {
+        skippedCount++;
+        continue;
+      }
       const result = await formDraftExecutor.delete({ id }, systemUser, tenantDb);
       if (result.isSuccess) {
         const row = byId.get(id);
@@ -146,7 +150,7 @@ async function deleteStaleDraftsBatch(
       }
     }
   }
-  return deletedRows;
+  return { deletedRows, skippedCount };
 }
 
 export async function cleanupDraftsJob(
@@ -189,12 +193,20 @@ export async function cleanupDraftsJob(
     // entirely for rows with no FileRefs in the blob, the common case.
     // Delete first (with staleness re-check), then release binaries from rows
     // that actually disappeared — never release a draft the user just saved.
-    const deletedRows = await deleteStaleDraftsBatch(batch, db, retentionDays, ctx.log);
+    const { deletedRows, skippedCount } = await deleteStaleDraftsBatch(
+      batch,
+      db,
+      retentionDays,
+      ctx.log,
+    );
     for (const row of deletedRows) {
       await releaseRowFileRefs(row, db, fileProviderResolver, ctx.log);
     }
     deleted += deletedRows.length;
-    if (deletedRows.length === 0 || batch.length < DEFAULT_BATCH_SIZE) break;
+    // A skipped row is no longer stale, so the next select drops it — a fully
+    // skipped batch still makes progress. Only a batch with neither deletes nor
+    // skips (all failed) would reselect the same rows forever.
+    if (deletedRows.length + skippedCount === 0 || batch.length < DEFAULT_BATCH_SIZE) break;
   }
   ctx.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
 }

package/packages/bundled-features/src/foundation-shared/index.ts

@@ -9,6 +9,7 @@ export {
   MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
   type MailConnectTarget,
   type MailHostGuardOptions,
+  mailAllowedPrivateHostsEnvSchema,
   readAllowedPrivateMailHostsFromEnv,
   resolveMailConnectTarget,
 } from "./mail-host-policy.js";

package/packages/bundled-features/src/foundation-shared/mail-host-policy.ts

@@ -10,18 +10,30 @@
 // internal relay or a dev/test server (mailpit, greenmail) — deliberately
 // an operator env var (KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, read via
 // readAllowedPrivateMailHostsFromEnv), never a tenant-config key, so a
-// tenant can never grant themselves the bypass. Shared by both features
-// since a deploy commonly mounts both; declared once in mail-transport-
-// smtp's envSchema (see its feature.ts) to avoid the framework's env-var-
-// conflict check tripping when both features are mounted together.
+// tenant can never grant themselves the bypass. Both features register the
+// shared mailAllowedPrivateHostsEnvSchema below.
 
 import type { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
 import { resolvePublicHostname } from "@cosmicdrift/kumiko-framework/http";
+import * as z from "zod";
 import { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
 
 export const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
 
+// One schema instance, registered by every feature that reads the variable:
+// composeEnvSchema accepts the same field instance from several features, so
+// an app mounting only one of them still gets the variable validated and
+// documented.
+export const mailAllowedPrivateHostsEnvSchema = z.object({
+  [MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
+    .string()
+    .optional()
+    .describe(
+      "Comma-separated operator allowlist of private/internal hosts (e.g. a local mailpit/greenmail dev server) that bypass the public-address check for SMTP and IMAP host config. Shared by mail-transport-smtp and inbound-provider-imap — never a tenant-config value.",
+    ),
+});
+
 export function readAllowedPrivateMailHostsFromEnv(
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): readonly string[] {

package/packages/bundled-features/src/inbound-provider-imap/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "inbound-provider-imap declares the MAIL_ALLOWED_PRIVATE_HOSTS env schema",
+    "migration": "No action needed. An app that mounts both mail-transport-smtp and inbound-provider-imap now composes one shared field."
+  },
   {
     "version": "0.320.0",
     "type": "breaking",

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -23,6 +23,7 @@
 // (credential-document.ts) — kein Tenant-Config, weil mehrere Accounts
 // pro Tenant verschiedene Hosts haben.
 
+import { mailAllowedPrivateHostsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   INBOUND_MAIL_PROVIDER_EXTENSION,
   InboundAuthError,
@@ -282,5 +283,6 @@ export const inboundProviderImapFeature = defineFeature(FEATURE_NAME, (r) => {
   });
   r.requires("inbound-mail-foundation");
   r.requires("secrets");
+  r.envSchema(mailAllowedPrivateHostsEnvSchema);
   r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
 });

package/packages/bundled-features/src/inbound-provider-imap/imap-client.ts

@@ -39,10 +39,9 @@ const IMAP_HOST_UNREACHABLE_MESSAGE = "IMAP host is not reachable or not allowed
 
 // Operator escape hatch for an internal relay or a dev/test IMAP server
 // (greenmail): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, the same operator env
-// var mail-transport-smtp declares (see its envSchema — composeEnvSchema
-// rejects two features declaring the same key, so this feature reads it
-// without redeclaring it), never a tenant-config value, so a tenant can
-// never grant themselves the private-host bypass.
+// var mail-transport-smtp registers (both share one schema instance, see
+// foundation-shared), never a tenant-config value, so a tenant can never
+// grant themselves the private-host bypass.
 //
 // mailHostLookup is a test-only DNS seam — production leaves it undefined,
 // so resolveMailConnectTarget uses the real resolver. Module-global state:

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

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "jobs: store_tenant_job_failures holds at most one row per (tenant, job, subject)",
+    "migration": "store_tenant_job_failures now enforces one row per (tenant_id, job_name, subject) through two partial unique indexes; parallel final failures serialize on an advisory lock. kumiko schema generate does NOT produce the dedup, and the unique index would fail on existing duplicates, so hand-edit the generated migration to contain exactly: DELETE FROM \"store_tenant_job_failures\" a USING \"store_tenant_job_failures\" b WHERE a.\"tenant_id\" = b.\"tenant_id\" AND a.\"job_name\" = b.\"job_name\" AND a.\"subject\" IS NOT DISTINCT FROM b.\"subject\" AND (a.\"failed_at\", a.\"id\") < (b.\"failed_at\", b.\"id\"); CREATE UNIQUE INDEX IF NOT EXISTS \"store_tenant_job_failures_tenant_job_subject_uidx\" ON \"store_tenant_job_failures\" (\"tenant_id\", \"job_name\", \"subject\") WHERE subject IS NOT NULL; CREATE UNIQUE INDEX IF NOT EXISTS \"store_tenant_job_failures_tenant_job_null_subject_uidx\" ON \"store_tenant_job_failures\" (\"tenant_id\", \"job_name\") WHERE subject IS NULL; DROP INDEX IF EXISTS \"store_tenant_job_failures_tenant_job_subject_idx\"; The DELETE keeps the newest row per key (by failed_at, then id)."
+  },
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "Tenant-visible job run state: r.job({ tenantVisibleRun }) plus jobs:query:tenant-runs",
+    "detail": "A job that declares `tenantVisibleRun` keeps its queued, running, completed and failed state per tenant and subject in the new table `store_tenant_job_runs`, and the tenant reads it through `jobs:query:tenant-runs` (payload `{ jobName?, subject?, limit? }`, own tenant only). Each row is `{ jobName, subject, status, queuedAt, startedAt, finishedAt }`: every queued or running run plus the latest completed or failed one per job and subject, active runs first. No payload, error text or log ever reaches the tenant. A failed attempt that is retried shows as `queued` again. The stale-run sweep and `retention-cleanup` also cover the new table. `JobRunnerOptions` gains `onJobQueued` and `onJobDropped`.",
+    "migration": "New store table. Run `kumiko-schema generate <name>` and apply the migration with `kumiko-schema apply` - `store_tenant_job_runs` is created empty and stays empty until a job declares `tenantVisibleRun`. No change needed for apps that do not opt in."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "jobs:query:list and jobs:query:failures reject a fractional limit, and migration hints name `kumiko-schema generate`",
+    "detail": "Migration hints name the real `kumiko-schema generate` command, and the jobs list queries reject fractional `limit` values\nThe generated migration header and the recipe READMEs pointed at a non-existent `kumiko migrate generate`. `jobs:query:list` and `jobs:query:failures` now validate `limit` as an integer (at least 1), so `limit: 2.5` fails validation instead of reaching the database query."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "store_tenant_job_failures gets three indexes and jobs:query:failures lists one record per job and subject",
+    "migration": "Run `kumiko schema generate`; it emits in-place CREATE INDEX statements with no DROP and no rebuild."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "The job worker starts consuming only after the boot gates passed"
+  },
   {
     "version": "0.343.0",
     "type": "improvement",

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

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

package/packages/bundled-features/src/jobs/db/queries/retention.ts

@@ -14,6 +14,7 @@ import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { jobRunLogsTable, jobRunsTable } from "../../job-run-table.js";
 import { tenantJobFailuresTable } from "../../tenant-job-failure-table.js";
+import { tenantJobRunsTable } from "../../tenant-job-run-table.js";
 
 const RETENTION_DELETE_BATCH_SIZE = 500;
 
@@ -21,6 +22,7 @@ export type JobRunRetentionResult = {
   readonly runsDeleted: number;
   readonly logsDeleted: number;
   readonly tenantFailuresDeleted: number;
+  readonly tenantRunsDeleted: number;
 };
 
 export async function deleteStaleJobRuns(
@@ -52,9 +54,19 @@ export async function deleteStaleJobRuns(
     { limit: RETENTION_DELETE_BATCH_SIZE },
   );
 
+  // Only finished rows: active ones are the stale sweep's business, and a
+  // still-running job older than the window must not vanish from the tenant.
+  const tenantRunsResult = await deleteManyBatched(
+    db,
+    tenantJobRunsTable,
+    { status: { in: ["completed", "failed"] }, updatedAt: { lt: cutoff } },
+    { limit: RETENTION_DELETE_BATCH_SIZE },
+  );
+
   return {
     runsDeleted: runsResult.deleted,
     logsDeleted: logsResult.deleted,
     tenantFailuresDeleted: tenantFailuresResult.deleted,
+    tenantRunsDeleted: tenantRunsResult.deleted,
   };
 }

package/packages/bundled-features/src/jobs/db/queries/stale-run-sweep.ts

@@ -12,19 +12,23 @@
 // the run becomes retriable via the existing jobs:write:retry gate
 // (retry.write.ts only allows retry from "failed").
 
-import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { deleteManyBatched, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { mapWithConcurrency } from "../../../shared/index.js";
 import { encryptFailureError } from "../../job-run-logger.js";
 import { jobRunsTable } from "../../job-run-table.js";
+import { tenantJobRunsTable } from "../../tenant-job-run-table.js";
 
 const KMS_POOL_CONCURRENCY = 4;
+const STALE_DELETE_BATCH_SIZE = 500;
 
 export const STALE_JOB_RUN_ERROR =
   "job run exceeded the stale-run timeout without a completion signal (likely a crashed worker process)";
 
 export type StaleRunSweepResult = {
   readonly runsMarkedFailed: number;
+  readonly tenantRunsMarkedFailed: number;
+  readonly tenantQueuedDropped: number;
 };
 
 export async function markStaleJobRunsFailed(
@@ -80,5 +84,25 @@ export async function markStaleJobRunsFailed(
   );
   const runsMarkedFailed = updatedPerSubject.reduce((sum, count) => sum + count, 0);
 
-  return { runsMarkedFailed };
+  // Tenant-visible run state follows the same clock: a running row whose
+  // worker died is a failure, a queued row that never started (job lost from
+  // Redis, enqueue hook without a run) would otherwise show "waiting" forever.
+  const tenantRunsFailed = await updateMany(
+    db,
+    tenantJobRunsTable,
+    { status: "failed", finishedAt: now, updatedAt: now },
+    { status: "running", startedAt: { lt: cutoff } },
+  );
+  const tenantQueuedStale = await deleteManyBatched(
+    db,
+    tenantJobRunsTable,
+    { status: "queued", updatedAt: { lt: cutoff } },
+    { limit: STALE_DELETE_BATCH_SIZE },
+  );
+
+  return {
+    runsMarkedFailed,
+    tenantRunsMarkedFailed: tenantRunsFailed.length,
+    tenantQueuedDropped: tenantQueuedStale.deleted,
+  };
 }

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

@@ -27,10 +27,12 @@ import {
   DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS,
 } from "./handlers/stale-run-sweep.job.js";
 import { tenantFailuresQuery } from "./handlers/tenant-failures.query.js";
+import { tenantRunsQuery } from "./handlers/tenant-runs.query.js";
 import { triggerWrite } from "./handlers/trigger.write.js";
 import { JOBS_I18N } from "./i18n.js";
 import { jobRunLogsTableMeta, jobRunsTableMeta } from "./job-run-table.js";
 import { tenantJobFailuresTableMeta } from "./tenant-job-failure-table.js";
+import { tenantJobRunsTableMeta } from "./tenant-job-run-table.js";
 
 export type JobsFeatureOptions = {
   // How long a job run (and its logs) stays in store_job_runs/
@@ -49,7 +51,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. 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).",
+      "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 its stuck `queued` rows.",
     );
     r.uiHints({
       displayLabel: "Jobs · Audit & Operator UI",
@@ -71,6 +73,9 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     r.storeTable(tenantJobFailuresTableMeta, {
       reason: "direct_write.tenant_job_failures",
     });
+    r.storeTable(tenantJobRunsTableMeta, {
+      reason: "direct_write.tenant_job_runs",
+    });
 
     // Framework-provided rebuild job — available whenever `jobs` is composed; enqueueProjectionRebuild dispatches it.
     r.job(
@@ -123,6 +128,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       detail: r.queryHandler(detailQuery),
       catalog: r.queryHandler(catalogQuery),
       failures: r.queryHandler(tenantFailuresQuery),
+      tenantRuns: r.queryHandler(tenantRunsQuery),
     };
 
     const systemAdminAccess = { roles: ["SystemAdmin"] as const };

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

@@ -1,11 +1,13 @@
 import { countWhere, selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import { decodeCursor, encodeCursor } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.js";
 import { jobRunsTable } from "../job-run-table.js";
 
 const KMS_POOL_CONCURRENCY = 4;
+const DEFAULT_PAGE_SIZE = 50;
 
 const jobRunStatusSchema = z.enum(["queued", "running", "completed", "failed"]);
 
@@ -23,6 +25,31 @@ async function decryptRunRow<T extends Record<string, unknown>>(row: T): Promise
   return result;
 }
 
+type JobRunStatus = z.infer<typeof jobRunStatusSchema>;
+
+function buildListWhere(payload: {
+  readonly jobName?: string | undefined;
+  readonly status?: JobRunStatus | undefined;
+  readonly filters?: readonly { readonly value: readonly JobRunStatus[] }[] | undefined;
+}): WhereObject {
+  const where: WhereObject = {};
+  if (payload.jobName) where["jobName"] = payload.jobName;
+  const statuses = payload.filters?.[0]?.value ?? (payload.status ? [payload.status] : []);
+  if (statuses.length === 1) where["status"] = statuses[0];
+  else if (statuses.length > 1) where["status"] = { in: statuses };
+  return where;
+}
+
+function parseOffsetCursor(cursor: string | undefined): number {
+  const offset = cursor ? Number(decodeCursor(cursor)) : 0;
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new ValidationError({
+      fields: [{ path: "cursor", code: "invalid_cursor", i18nKey: "jobs.errors.invalidCursor" }],
+    });
+  }
+  return offset;
+}
+
 export const listQuery = defineQueryHandler({
   name: "list",
   description:
@@ -41,7 +68,8 @@ export const listQuery = defineQueryHandler({
       .optional(),
     sort: z.enum(["jobName", "status", "startedAt", "duration"]).optional(),
     sortDirection: z.enum(["asc", "desc"]).optional(),
-    limit: z.number().optional(),
+    limit: z.number().int().min(1).optional(),
+    cursor: z.string().optional(),
     totalCount: z.boolean().optional(),
   }),
   access: { roles: ["SystemAdmin"] },
@@ -54,17 +82,22 @@ export const listQuery = defineQueryHandler({
     const db = ctx.systemDb.unsafeRaw(
       "cross-tenant job monitoring: SystemAdmin lists job runs of every tenant",
     );
-    const where: WhereObject = {};
-    if (query.payload.jobName) where["jobName"] = query.payload.jobName;
-    const statusFilter = query.payload.filters?.find((filter) => filter.field === "status");
-    const statuses = statusFilter?.value ?? (query.payload.status ? [query.payload.status] : []);
-    if (statuses.length === 1) where["status"] = statuses[0];
-    else if (statuses.length > 1) where["status"] = { in: statuses };
+    const where = buildListWhere(query.payload);
     const sortColumn = query.payload.sort ?? "startedAt";
-    const rows = await selectMany(db, jobRunsTable, where, {
-      orderBy: { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },
-      limit: query.payload.limit ?? 50,
+    const limit = query.payload.limit ?? DEFAULT_PAGE_SIZE;
+    const offset = parseOffsetCursor(query.payload.cursor);
+    const direction = query.payload.sortDirection ?? "desc";
+    // selectMany has no OFFSET: read through the end of the page plus one probe
+    // row, then slice. `id` as tiebreaker keeps pages stable for non-unique sorts.
+    const fetched = await selectMany(db, jobRunsTable, where, {
+      orderBy: [
+        { col: sortColumn, direction },
+        { col: "id", direction },
+      ],
+      limit: offset + limit + 1,
     });
+    const hasMore = fetched.length > offset + limit;
+    const rows = fetched.slice(offset, offset + limit);
     // countWhere reruns the SAME `where` without the limit — `rows.length` is
     // capped at the page size and would silently undercount the total.
     const total =
@@ -72,7 +105,7 @@ export const listQuery = defineQueryHandler({
     // payload/error are stored encrypted under the triggering user's DEK (#799, #2307).
     return {
       rows: await mapWithConcurrency(rows, KMS_POOL_CONCURRENCY, decryptRunRow),
-      nextCursor: null,
+      nextCursor: hasMore ? encodeCursor(String(offset + limit)) : null,
       ...(total !== undefined && { total }),
     };
   },

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

@@ -37,7 +37,7 @@ export const tenantFailuresQuery = defineQueryHandler({
   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(),
+    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.

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

@@ -0,0 +1,94 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { serializeJobSubject } from "@cosmicdrift/kumiko-framework/jobs";
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { type TenantJobRunStatus, tenantJobRunsTable } from "../tenant-job-run-table.js";
+
+type TenantJobRunRow = {
+  readonly tenantId: string;
+  readonly jobName: string;
+  readonly subject: string | null;
+  readonly status: TenantJobRunStatus;
+  readonly queuedAt: Temporal.Instant | null;
+  readonly startedAt: Temporal.Instant | null;
+  readonly finishedAt: Temporal.Instant | null;
+  readonly updatedAt: Temporal.Instant;
+};
+
+const DEFAULT_LIMIT = 50;
+
+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; 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 tenantRunsQuery = defineQueryHandler({
+  name: "tenant-runs",
+  description:
+    "Lists the calling tenant's own job runs that opted in via tenantVisibleRun — per job and subject every queued or running run plus the latest completed or failed one, active runs first, then newest first; each row carries only status and queuedAt/startedAt/finishedAt, never payloads, error text or logs; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to show whether work for a subject is waiting, running or done, and to tell a failed run from a finished one.",
+  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 run state carries a job name, a status and
+  // times, 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:tenant-runs requires ctx.systemDb (feature must declare r.systemScope())",
+      });
+    }
+    // assertTenantMatch returns the same unfiltered system-mode db — the
+    // explicit tenantId below is the filter, assertRowsTenant the second net.
+    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 limit = query.payload.limit ?? DEFAULT_LIMIT;
+    const newestFirst = { col: "updatedAt", direction: "desc" } as const;
+    const activeRows = await selectMany<TenantJobRunRow>(
+      db,
+      tenantJobRunsTable,
+      { ...where, status: { in: ["queued", "running"] } },
+      { orderBy: newestFirst, limit },
+    );
+    const finishedRows = await selectMany<TenantJobRunRow>(
+      db,
+      tenantJobRunsTable,
+      { ...where, status: { in: ["completed", "failed"] } },
+      { orderBy: newestFirst, limit },
+    );
+    const seenFinishedKeys = new Set<string>();
+    const finishedNewestPerKey = finishedRows.filter((row) => {
+      const key = JSON.stringify([row.jobName, row.subject]);
+      if (seenFinishedKeys.has(key)) return false;
+      seenFinishedKeys.add(key);
+      return true;
+    });
+    const activeFirst = [...activeRows, ...finishedNewestPerKey];
+    return {
+      rows: ctx.systemDb.assertRowsTenant(activeFirst.slice(0, limit), "tenantId").map((row) => ({
+        jobName: row.jobName,
+        subject: parseSubject(row.subject),
+        status: row.status,
+        queuedAt: row.queuedAt,
+        startedAt: row.startedAt,
+        finishedAt: row.finishedAt,
+      })),
+      nextCursor: null,
+    };
+  },
+});

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

@@ -36,6 +36,7 @@ export const JOBS_I18N: Readonly<Record<string, LocalizedString>> = {
   "jobs.detail.logs": { en: "Logs" },
   "jobs.detail.retry": { en: "Retry" },
   "jobs.trigger.title": { en: "Run a job" },
+  "jobs.errors.invalidCursor": { en: "The pagination cursor is invalid." },
   "jobs.trigger.submit": { en: "Run" },
   "jobs.errors.unknownJob": { en: "Unknown job." },
   "jobs.errors.notManual": {