@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

package/packages/bundled-features/src/files-tenant-data/hooks.ts

@@ -55,6 +55,7 @@ import {
   type StorageProviderHookCtx,
   type TenantDataDestroyHook,
   type TenantDataHookCtx,
+  type TenantDestroyHookResult,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -64,6 +65,7 @@ import {
   storageKeyStemPrefix,
   tenantStoragePrefixes,
 } from "@cosmicdrift/kumiko-framework/files";
+import { type ChunkedMigrationResult, runChunkedMigration } from "../shared/index.js";
 
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 
@@ -72,6 +74,8 @@ const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName
 // or a single unbounded array for a tenant with a huge prefix.
 const SURVIVOR_CHECK_BATCH_SIZE = 500;
 
+const DESTROY_CHUNK_SIZE = 500;
+
 function chunk<T>(items: readonly T[], size: number): T[][] {
   const chunks: T[][] = [];
   for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
@@ -82,27 +86,54 @@ function isUnderOwnPrefix(storageKey: string, prefixes: readonly string[]): bool
   return prefixes.some((prefix) => storageKey.startsWith(prefix));
 }
 
+function toDestroyHookResult(
+  result: ChunkedMigrationResult,
+  failureMessage: () => string | undefined,
+): TenantDestroyHookResult {
+  // A failure on the last item ends the run as "done" (nothing left to batch),
+  // so the failed count, not the stop reason, decides fail-closed.
+  if (result.failed > 0) {
+    throw new Error(failureMessage() ?? "files-tenant-data: destroy chunk failed");
+  }
+  return { done: result.stoppedReason === "done", processed: result.migrated };
+}
+
 export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
-  const rows = await ctx.db.selectMany<{ id: string; storageKey: string }>(fileRefsTable, {
-    tenantId: ctx.tenantId,
-  });
   const ownPrefixes = tenantStoragePrefixes(ctx.tenantId);
   const user = createSystemUser(ctx.tenantId);
-  for (const row of rows) {
-    if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
-      await deleteHandedOverBinary(ctx, row.storageKey);
-    }
-    const result = await crud.forget({ id: row.id }, user, ctx.db);
-    // Executor writes return {isSuccess:false} instead of throwing — a
-    // discarded result would report this destroy stage "succeeded" while the
-    // row (and its PII fileName) survives. Throw so the pipeline's
-    // retry/abandon handling sees it.
-    if (!result.isSuccess) {
-      throw new Error(
-        `files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${result.error.message}`,
-      );
-    }
-  }
+  let firstFailure: string | undefined;
+  // Converges without a cursor: forget() hard-deletes, so each batch query
+  // returns the next rows.
+  const result = await runChunkedMigration<{ id: string; storageKey: string }>({
+    nextBatch: () =>
+      ctx.db.selectMany<{ id: string; storageKey: string }>(
+        fileRefsTable,
+        { tenantId: ctx.tenantId },
+        { limit: DESTROY_CHUNK_SIZE },
+      ),
+    migrateRow: async (row) => {
+      if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
+        await deleteHandedOverBinary(ctx, row.storageKey);
+      }
+      const forgotten = await crud.forget({ id: row.id }, user, ctx.db);
+      // Executor writes return {isSuccess:false} instead of throwing — a
+      // discarded result would report this destroy stage "succeeded" while the
+      // row (and its PII fileName) survives. Throw so the pipeline's
+      // retry/abandon handling sees it.
+      if (!forgotten.isSuccess) {
+        throw new Error(
+          `files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${forgotten.error.message}`,
+        );
+      }
+      return "migrated";
+    },
+    maxFailures: 1,
+    deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+    onRowError: (_row, err) => {
+      firstFailure = err instanceof Error ? err.message : String(err);
+    },
+  });
+  return toDestroyHookResult(result, () => firstFailure);
 };
 
 // The bytes live under the tenant that uploaded them (`<tenantId>/…` or
@@ -173,15 +204,33 @@ export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async
   // it and retries up to the stage's attempt cap before abandoning the destroy
   // (list+delete are idempotent, so a retry converges rather than
   // double-deleting or erroring on a missing key).
+  let processed = 0;
   for (const prefix of tenantStoragePrefixes(tenantId)) {
     const keys = await provider.list(prefix);
     const keptStemPrefixes = await survivorStemPrefixes(ctx.db, keys);
-    for (const key of keys) {
-      if (keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix))) continue;
-      assertSafeStorageKey(key);
-      await provider.delete(key);
-    }
+    const deletableKeys = keys.filter(
+      (key) => !keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix)),
+    );
+    const pending = [...deletableKeys];
+    let firstFailure: string | undefined;
+    const result = await runChunkedMigration<string>({
+      nextBatch: async () => pending.splice(0, DESTROY_CHUNK_SIZE),
+      migrateRow: async (key) => {
+        assertSafeStorageKey(key);
+        await provider.delete(key);
+        return "migrated";
+      },
+      maxFailures: 1,
+      deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+      onRowError: (_key, err) => {
+        firstFailure = err instanceof Error ? err.message : String(err);
+      },
+    });
+    const hookResult = toDestroyHookResult(result, () => firstFailure);
+    processed += result.migrated;
+    if (!hookResult.done) return { done: false, processed };
   }
+  return { done: true, processed };
 };
 
 // Any listed key that is itself a surviving row's exact storageKey means a

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "folder:delete removes assignments whose host entity is gone instead of refusing forever",
+    "detail": "An assignment pointing at a hard-deleted, soft-deleted or unregistered host blocked folder:delete permanently with folder_has_assignments, because clear-folder needs a visible host and could not remove it. folder:delete now removes such assignments through the event-store executor (normal delete events) before the check, without the caller's read gate. Assignments of live hosts, including ones the caller cannot see, still block with folder_has_assignments. A refused delete removes nothing. The cleanup runs lazily at folder:delete, not in a host-delete hook, so restoring a soft-deleted host before then keeps its folder."
+  },
   {
     "version": "0.246.0",
     "type": "improvement",

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/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

@@ -68,7 +68,7 @@ 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(),
   }),

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

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