@cosmicdrift/kumiko-bundled-features 0.240.0 → 0.242.0

package/src/audit/__tests__/audit-screens.boot.test.ts

@@ -5,6 +5,7 @@ import { createConfigFeature } from "../../config/feature";
 import { createTenantFeature } from "../../tenant/feature";
 import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "../constants";
 import { createAuditFeature } from "../feature";
+import { AUDIT_I18N } from "../i18n";
 
 describe("audit log screen + handler access alignment", () => {
   const features = [createConfigFeature(), createTenantFeature(), createAuditFeature()];
@@ -13,11 +14,13 @@ describe("audit log screen + handler access alignment", () => {
     expect(() => validateBoot(features)).not.toThrow();
   });
 
-  test("audit-log screen is custom, access.admin-gated", () => {
+  test("audit-log screen is declarative, access.admin-gated", () => {
     const audit = createAuditFeature();
     const screen = audit.screens[AUDIT_LOG_SCREEN_ID];
-    if (screen?.type !== "custom") {
-      throw new Error(`expected a custom screen for ${AUDIT_LOG_SCREEN_ID}, got ${screen?.type}`);
+    if (screen?.type !== "projectionList") {
+      throw new Error(
+        `expected a projectionList screen for ${AUDIT_LOG_SCREEN_ID}, got ${screen?.type}`,
+      );
     }
     if (!("access" in screen) || !screen.access || !("roles" in screen.access)) {
       throw new Error(`expected role-gated access on ${AUDIT_LOG_SCREEN_ID}`);
@@ -25,12 +28,12 @@ describe("audit log screen + handler access alignment", () => {
     expect(screen.access.roles).toEqual(access.admin);
   });
 
-  test("audit-log-detail screen is custom, admin-gated, breadcrumb-linked to list", () => {
+  test("audit-log-detail screen is declarative, admin-gated, breadcrumb-linked to list", () => {
     const audit = createAuditFeature();
     const screen = audit.screens[AUDIT_LOG_DETAIL_SCREEN_ID];
-    if (screen?.type !== "custom") {
+    if (screen?.type !== "projectionDetail") {
       throw new Error(
-        `expected a custom screen for ${AUDIT_LOG_DETAIL_SCREEN_ID}, got ${screen?.type}`,
+        `expected a projectionDetail screen for ${AUDIT_LOG_DETAIL_SCREEN_ID}, got ${screen?.type}`,
       );
     }
     if (!("listScreenId" in screen)) {
@@ -43,6 +46,23 @@ describe("audit log screen + handler access alignment", () => {
     expect(screen.access.roles).toEqual(access.admin);
   });
 
+  test("audit-log-detail: aggregate type and aggregate id resolve to distinct labels", () => {
+    const audit = createAuditFeature();
+    const screen = audit.screens[AUDIT_LOG_DETAIL_SCREEN_ID];
+    if (screen?.type !== "projectionDetail") {
+      throw new Error(
+        `expected a projectionDetail screen for ${AUDIT_LOG_DETAIL_SCREEN_ID}, got ${screen?.type}`,
+      );
+    }
+    const aggregateTypeKey = screen.fieldLabels?.["aggregateType"];
+    const aggregateIdKey = screen.fieldLabels?.["aggregateId"];
+    if (aggregateTypeKey === undefined || aggregateIdKey === undefined) {
+      throw new Error("expected fieldLabels for both aggregateType and aggregateId");
+    }
+    expect(aggregateTypeKey).not.toBe(aggregateIdKey);
+    expect(AUDIT_I18N[aggregateTypeKey]?.en).not.toBe(AUDIT_I18N[aggregateIdKey]?.en);
+  });
+
   test("audit queries use access.admin (screen ⊆ handler)", () => {
     const audit = createAuditFeature();
     expect(rolesOf(audit.queryHandlers["list"]?.access)).toEqual([...access.admin]);

package/src/audit/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.241.0",
+    "type": "breaking",
+    "title": "AuditLogScreen and AuditLogDetailScreen removed; audit-log/audit-log-detail are now declarative screens (fw#2312).",
+    "detail": "`audit-log` and `audit-log-detail` render through the generic renderer (`projectionList`/`projectionDetail`) instead of custom React components — the renderer selects a screen by its `screen.type`, not a client component registry, so `AuditLogScreen`/`AuditLogDetailScreen` were dead exports the moment the screen definitions switched. The `payload`/`metadata` fields now use the `format: \"json\"` field-renderer (see framework changelog) instead of a raw escaped-string dump.",
+    "migration": "Breaking only if you imported these components directly (no shipped consumer app did). Remove `import { AuditLogScreen, AuditLogDetailScreen } from \"@cosmicdrift/kumiko-bundled-features/audit/web\"` and any `components: { AuditLogScreen: ..., AuditLogDetailScreen: ... }` entry in your `auditClient()`/renderer setup — the bundled feature registers its own `audit-log`/`audit-log-detail` screens now, nothing left for an app to wire."
+  },
   {
     "version": "0.127.0",
     "type": "improvement",

package/src/audit/feature.ts

@@ -3,7 +3,7 @@ import {
   defineFeature,
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID } from "./constants";
+import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "./constants";
 import { detailsQuery } from "./handlers/details.query";
 import { listQuery } from "./handlers/list.query";
 import { AUDIT_I18N } from "./i18n";
@@ -39,20 +39,70 @@ export function createAuditFeature(): FeatureDefinition {
       details: r.queryHandler(detailsQuery),
     };
 
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: AUDIT_LOG_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "AuditLogScreen" } },
+      type: "projectionList",
+      query: AuditQueries.list,
+      columns: [
+        { field: "createdAt", label: "audit.log.col.when", renderer: { format: "timestamp" } },
+        { field: "type", label: "audit.log.col.type" },
+        { field: "createdBy", label: "audit.log.col.actor" },
+      ],
+      searchable: true,
+      defaultSort: { field: "createdAt", dir: "desc" },
+      rowActions: [
+        {
+          kind: "navigate",
+          id: "details",
+          label: "audit.log.details",
+          screen: AUDIT_LOG_DETAIL_SCREEN_ID,
+          entityId: "id",
+          rowClick: true,
+        },
+      ],
+      pagination: "infinite",
       description:
         "Admin table of the tenant's audit-trail events with actor names and event-type/date filters; open it to browse recent changes and drill into a single event.",
       access: { roles: access.admin },
     });
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: AUDIT_LOG_DETAIL_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "AuditLogDetailScreen" } },
+      type: "projectionDetail",
+      query: AuditQueries.details,
+      idParam: "id",
+      fieldLabels: {
+        type: "audit.log.col.type",
+        createdAt: "audit.log.col.when",
+        aggregateType: "audit.log.col.aggregateType",
+        aggregateId: "audit.log.col.aggregateId",
+        createdBy: "audit.log.col.actor",
+        id: "audit.log.detail.field.id",
+        payload: "audit.log.detail.payload",
+        metadata: "audit.log.detail.metadata",
+      },
+      layout: {
+        sections: [
+          {
+            fields: [
+              "type",
+              { field: "createdAt", renderer: { format: "timestamp" } },
+              "aggregateType",
+              "aggregateId",
+              "createdBy",
+              "id",
+            ],
+          },
+          // No section `title` here (fw#2312 label-dedup fix): each section
+          // holds exactly one field, so a title would repeat the field's own
+          // label (rendered by RenderField as the Field's heading) verbatim.
+          {
+            fields: [{ field: "payload", renderer: { format: "json" } }],
+          },
+          {
+            fields: [{ field: "metadata", renderer: { format: "json" } }],
+          },
+        ],
+      },
       description:
         "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
       listScreenId: AUDIT_LOG_SCREEN_ID,

package/src/audit/handlers/list.query.ts

@@ -19,18 +19,60 @@ import { z } from "zod";
 
 const MAX_LIMIT = 100;
 
+function buildDateRange(
+  from: string | undefined,
+  to: string | undefined,
+): { gte?: unknown; lte?: unknown } | null {
+  if (!from && !to) return null;
+  const range: { gte?: unknown; lte?: unknown } = {};
+  if (from) range.gte = Temporal.Instant.from(from);
+  if (to) range.lte = Temporal.Instant.from(to);
+  return range;
+}
+
+function buildAuditWhere(
+  tenantId: string,
+  p: {
+    aggregateType?: string;
+    aggregateId?: string;
+    eventType?: string;
+    search?: string;
+    userId?: string;
+    from?: string;
+    to?: string;
+    cursor?: string;
+    before?: string;
+  },
+): WhereObject {
+  const where: WhereObject = { tenantId };
+  if (p.aggregateType) where["aggregateType"] = p.aggregateType;
+  if (p.aggregateId) where["aggregateId"] = p.aggregateId;
+  const type = p.eventType ?? p.search;
+  if (type) where["type"] = type;
+  if (p.userId) where["createdBy"] = p.userId;
+  const range = buildDateRange(p.from, p.to);
+  if (range) where["createdAt"] = range;
+  const cursor = p.cursor ?? p.before;
+  if (cursor) where["id"] = { lt: BigInt(cursor) };
+  return where;
+}
+
 export const listQuery = defineQueryHandler({
   name: "list",
   description:
     "Lists the tenant's audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when.",
   schema: z
     .object({
+      cursor: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
       before: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
+      search: z.string().trim().optional(),
       limit: z.number().int().min(1).max(MAX_LIMIT).default(50),
       aggregateType: z.string().optional(),
       aggregateId: z.uuid().optional(),
       eventType: z.string().optional(),
       userId: z.string().optional(),
+      sort: z.enum(["createdAt", "type"]).optional(),
+      sortDirection: z.enum(["asc", "desc"]).optional(),
       from: z.iso.datetime().optional(),
       to: z.iso.datetime().optional(),
     })
@@ -41,18 +83,7 @@ export const listQuery = defineQueryHandler({
   access: { roles: access.admin },
   handler: async (query, ctx) => {
     const p = query.payload;
-    const where: WhereObject = { tenantId: query.user.tenantId };
-    if (p.aggregateType) where["aggregateType"] = p.aggregateType;
-    if (p.aggregateId) where["aggregateId"] = p.aggregateId;
-    if (p.eventType) where["type"] = p.eventType;
-    if (p.userId) where["createdBy"] = p.userId;
-    if (p.from || p.to) {
-      const range: { gte?: unknown; lte?: unknown } = {};
-      if (p.from) range.gte = Temporal.Instant.from(p.from);
-      if (p.to) range.lte = Temporal.Instant.from(p.to);
-      where["createdAt"] = range;
-    }
-    if (p.before) where["id"] = { lt: BigInt(p.before) };
+    const where = buildAuditWhere(query.user.tenantId, p);
 
     const rows = await selectMany<{
       id: bigint;
@@ -65,7 +96,10 @@ export const listQuery = defineQueryHandler({
       createdAt: unknown;
       createdBy: string;
     }>(ctx.db, eventsTable, where, {
-      orderBy: { col: "id", direction: "desc" },
+      orderBy: {
+        col: query.payload.sort === "type" ? "type" : "createdAt",
+        direction: query.payload.sortDirection ?? "desc",
+      },
       limit: p.limit,
     });
 
@@ -81,9 +115,11 @@ export const listQuery = defineQueryHandler({
       createdBy: r.createdBy,
     }));
     const last = serialised[serialised.length - 1];
+    const nextId = serialised.length === p.limit && last ? last.id : null;
     return {
       rows: serialised,
-      nextBefore: serialised.length === p.limit && last ? last.id : null,
+      nextCursor: nextId,
+      nextBefore: nextId,
     };
   },
 });

package/src/audit/i18n.ts

@@ -1,5 +1,5 @@
 // @runtime client
-// Server + client i18n for audit (nav labels + AuditLogScreen).
+// Server + client i18n for audit (nav labels + audit-log/-detail screens).
 
 type LocalizedString = { readonly en: string };
 
@@ -7,27 +7,12 @@ export const AUDIT_I18N: Readonly<Record<string, LocalizedString>> = {
   "screen:audit-log.title": { en: "Audit log" },
   "screen:audit-log-detail.title": { en: "Event" },
   "audit:nav.auditLog": { en: "Audit" },
-  "audit.log.title": { en: "Audit log" },
-  "audit.log.loading": { en: "Loading events…" },
-  "audit.log.empty": { en: "No events." },
-  "audit.log.newest": { en: "Newest" },
-  "audit.log.older": { en: "Load older" },
   "audit.log.col.when": { en: "When" },
   "audit.log.col.type": { en: "Event" },
-  "audit.log.col.aggregate": { en: "Aggregate" },
+  "audit.log.col.aggregateType": { en: "Aggregate type" },
+  "audit.log.col.aggregateId": { en: "Aggregate ID" },
   "audit.log.col.actor": { en: "Actor" },
-  "audit.log.actor.system": { en: "System" },
-  "audit.log.actor.anonymous": { en: "Anonymous" },
-  "audit.log.actor.unknown": { en: "Unknown actor" },
-  "audit.log.filter.eventType": { en: "Event type" },
-  "audit.log.filter.aggregateType": { en: "Aggregate type" },
-  "audit.log.filter.from": { en: "From" },
-  "audit.log.filter.to": { en: "To" },
-  "audit.log.filter.apply": { en: "Filter" },
-  "audit.log.filter.reset": { en: "Reset" },
   "audit.log.details": { en: "Details" },
-  "audit.log.detail.loading": { en: "Loading event…" },
-  "audit.log.detail.missing": { en: "Event not found." },
   "audit.log.detail.payload": { en: "Event payload" },
   "audit.log.detail.metadata": { en: "Metadata" },
   "audit.log.detail.field.id": { en: "Event ID" },

package/src/audit/web/client-plugin.tsx

@@ -1,9 +1,7 @@
 // @runtime client
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
-import { AUDIT_FEATURE, AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID } from "../constants";
-import { AuditLogDetailScreen } from "./audit-log-detail-screen";
-import { AuditLogScreen } from "./audit-log-screen";
+import { AUDIT_FEATURE } from "../constants";
 import { defaultTranslations } from "./i18n";
 
 export type AuditClientOptions = {
@@ -14,9 +12,5 @@ export function auditClient(options?: AuditClientOptions): ClientFeatureDefiniti
   return {
     name: AUDIT_FEATURE,
     translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
-    components: {
-      [AUDIT_LOG_SCREEN_ID]: AuditLogScreen,
-      [AUDIT_LOG_DETAIL_SCREEN_ID]: AuditLogDetailScreen,
-    },
   };
 }

package/src/audit/web/index.ts

@@ -1,5 +1,3 @@
 // @runtime client
 
-export { AuditLogDetailScreen } from "./audit-log-detail-screen";
-export { AuditLogScreen } from "./audit-log-screen";
 export { type AuditClientOptions, auditClient } from "./client-plugin";

package/src/config/__tests__/config.integration.test.ts

@@ -939,6 +939,37 @@ describe("config.readiness query handler", () => {
     expect(keys).not.toContain("orders:config:max-order-count");
   });
 
+  type MissingWithSummary = Missing & { missingCount: number; missingTone: "default" | "warn" };
+
+  test("missingCount matches missing.length and missingTone is warn while something is missing (fw#2312)", async () => {
+    const result = await stack.http.queryOk<MissingWithSummary>(
+      ConfigQueries.readiness,
+      {},
+      readinessAdminFor(6),
+    );
+
+    expect(result.missingCount).toBe(result.missing.length);
+    expect(result.missingCount).toBeGreaterThan(0);
+    expect(result.missingTone).toBe("warn");
+  });
+
+  test("missingCount is 0 and missingTone is default once every required key is set (fw#2312)", async () => {
+    const admin = readinessAdminFor(7);
+    for (const [key, value] of [
+      ["transport:config:smtp-host", "smtp.example.com"],
+      ["transport:config:api-url", "https://api.example.com"],
+      ["transport:config:webhook-url", "https://webhook.example.com"],
+      ["transport:config:timeout", 30],
+    ] as const) {
+      await stack.http.writeOk(ConfigHandlers.set, { key, value }, admin);
+    }
+
+    const result = await stack.http.queryOk<MissingWithSummary>(ConfigQueries.readiness, {}, admin);
+    expect(result.missing).toEqual([]);
+    expect(result.missingCount).toBe(0);
+    expect(result.missingTone).toBe("default");
+  });
+
   test("whitespace-only text value still counts as missing (requireNonEmpty-Parität)", async () => {
     const admin = readinessAdminFor(2);
     await stack.http.writeOk(

package/src/config/handlers/readiness.query.ts

@@ -140,6 +140,13 @@ export const readinessQuery = defineQueryHandler({
       query.user,
       db,
     );
-    return { missing };
+    // Additive, display-ready fields for the admin-shell dashboard stat
+    // panel (fw#2312) — `missing` itself stays untouched for existing
+    // consumers that read the array directly.
+    return {
+      missing,
+      missingCount: missing.length,
+      missingTone: missing.length > 0 ? "warn" : "default",
+    };
   },
 });

package/src/jobs/__tests__/jobs-screens.boot.test.ts

@@ -16,9 +16,14 @@ describe("jobs screens + handler access alignment", () => {
 
   test("job-runs screens are SystemAdmin-gated", () => {
     const jobs = createJobsFeature();
-    for (const id of [JOB_RUNS_SCREEN_ID, JOB_RUN_DETAIL_SCREEN_ID] as const) {
+    const expectedTypeById = {
+      [JOB_RUNS_SCREEN_ID]: "projectionList",
+      [JOB_RUN_DETAIL_SCREEN_ID]: "projectionDetail",
+      "job-trigger": "actionForm",
+    } as const;
+    for (const id of Object.keys(expectedTypeById) as (keyof typeof expectedTypeById)[]) {
       const screen = jobs.screens[id];
-      expect(screen?.type).toBe("custom");
+      expect(screen?.type).toBe(expectedTypeById[id]);
       if (screen && "access" in screen && screen.access && "roles" in screen.access) {
         expect(screen.access.roles).toEqual(SYSTEM_ADMIN_ROLES);
       }

package/src/jobs/__tests__/jobs-security.integration.test.ts

@@ -2,7 +2,12 @@
 // Real HTTP via setupTestStack — no mocks.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { defineFeature, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { sql } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
@@ -10,7 +15,7 @@ import {
   TestUsers,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { rolesOf, seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { createConfigFeature } from "../../config/feature";
 import {
   JOB_RUN_DETAIL_SCREEN_ID,
@@ -108,3 +113,37 @@ describe("SystemAdmin can use jobs queries", () => {
     expect(Array.isArray(res.rows)).toBe(true);
   });
 });
+
+describe("jobs:query:list totalCount (fw#2312)", () => {
+  test("without totalCount the shape carries no total field", async () => {
+    const res = await stack.http.queryOk<{ rows: readonly unknown[]; total?: number }>(
+      JobQueries.list,
+      { jobName: "jobs-sec-app:job:total-count-shape" },
+      systemAdmin,
+    );
+    expect(res.total).toBeUndefined();
+  });
+
+  test("total reflects the full match count, not capped by limit", async () => {
+    const jobName = "jobs-sec-app:job:total-count-probe";
+    for (let i = 0; i < 6; i++) {
+      await seedRow(stack.db, jobRunsTable, {
+        id: crypto.randomUUID(),
+        tenantId: SYSTEM_TENANT_ID,
+        jobName,
+        bullJobId: `total-count-${i}`,
+        status: "completed",
+        attempt: 1,
+        startedAt: sql`now()`,
+      });
+    }
+
+    const res = await stack.http.queryOk<{ rows: readonly unknown[]; total?: number }>(
+      JobQueries.list,
+      { jobName, limit: 2, totalCount: true },
+      systemAdmin,
+    );
+    expect(res.rows.length).toBe(2);
+    expect(res.total).toBe(6);
+  });
+});

package/src/jobs/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.241.0",
+    "type": "breaking",
+    "title": "JobRunsScreen and JobRunDetailScreen removed; job-runs/job-run-detail are now declarative screens (fw#2312).",
+    "detail": "`job-runs`/`job-run-detail` render through the generic renderer (`projectionList`/`projectionDetail`) instead of custom React components — the renderer selects a screen by its `screen.type`, not a client component registry, so `JobRunsScreen`/`JobRunDetailScreen` were dead exports the moment the screen definitions switched. Job triggering moved from an inline control on the old custom screen to a new `job-trigger` `actionForm`, opened via a `kind: \"drawer\"` `toolbarAction` on `job-runs`. `job-run-detail`'s `logs` field now uses the `format: \"json\"` field-renderer (see framework changelog) instead of a raw escaped-string dump.",
+    "migration": "Breaking only if you imported these components directly (no shipped consumer app did). Remove `import { JobRunsScreen, JobRunDetailScreen } from \"@cosmicdrift/kumiko-bundled-features/jobs/web\"` and any `components: { JobRunsScreen: ..., JobRunDetailScreen: ... }` entry in your `jobsClient()`/renderer setup — the bundled feature registers its own `job-runs`/`job-run-detail`/`job-trigger` screens now, nothing left for an app to wire."
+  },
   {
     "version": "0.120.0",
     "type": "improvement",

package/src/jobs/feature.ts

@@ -1,5 +1,5 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { JOB_RUN_DETAIL_SCREEN_ID, JOB_RUNS_SCREEN_ID } from "./constants";
+import { JOB_RUN_DETAIL_SCREEN_ID, JOB_RUNS_SCREEN_ID, JobHandlers, JobQueries } from "./constants";
 import { catalogQuery } from "./handlers/catalog.query";
 import { detailQuery } from "./handlers/detail.query";
 import { listQuery } from "./handlers/list.query";
@@ -109,20 +109,112 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
 
     r.translations({ keys: JOBS_I18N });
 
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: JOB_RUNS_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "JobRunsScreen" } },
-      description:
-        "Operator table of recent job runs with status filters, plus a panel to trigger a manual job with a payload; open it to monitor background jobs and start one.",
+      type: "projectionList",
+      query: JobQueries.list,
+      columns: [
+        { field: "jobName", label: "jobs.runs.col.job" },
+        { field: "status", label: "jobs.runs.col.status" },
+        { field: "startedAt", label: "jobs.runs.col.started", renderer: { format: "timestamp" } },
+        { field: "duration", label: "jobs.runs.col.duration" },
+      ],
+      defaultSort: { field: "startedAt", dir: "desc" },
+      facets: [
+        {
+          field: "status",
+          type: "select",
+          label: "jobs.runs.filter.status",
+          options: [
+            { value: "queued", label: "jobs.runs.filter.queued" },
+            { value: "running", label: "jobs.runs.filter.running" },
+            { value: "completed", label: "jobs.runs.filter.completed" },
+            { value: "failed", label: "jobs.runs.filter.failed" },
+          ],
+        },
+      ],
+      rowActions: [
+        {
+          kind: "navigate",
+          id: "open",
+          label: "jobs.runs.open",
+          screen: JOB_RUN_DETAIL_SCREEN_ID,
+          entityId: "id",
+          rowClick: true,
+        },
+      ],
+      toolbarActions: [
+        {
+          kind: "drawer",
+          id: "trigger",
+          label: "jobs.trigger.title",
+          screen: "job-trigger",
+          style: "primary",
+        },
+      ],
+      pagination: "infinite",
       access: systemAdminAccess,
     });
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
+    r.screen({
+      id: "job-trigger",
+      type: "actionForm",
+      handler: JobHandlers.trigger,
+      fields: {
+        jobName: { type: "text", required: true },
+        payload: { type: "longText", multiline: true, default: "{}" },
+      },
+      layout: { sections: [{ fields: ["jobName", "payload"] }] },
+      submitLabel: "jobs.trigger.submit",
+      access: systemAdminAccess,
+      description: "Manually trigger a job by name with an optional JSON object payload.",
+    });
     r.screen({
       id: JOB_RUN_DETAIL_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "JobRunDetailScreen" } },
+      type: "projectionDetail",
+      query: JobQueries.details,
+      idParam: "runId",
+      fieldLabels: {
+        jobName: "jobs.detail.field.job",
+        status: "jobs.detail.field.status",
+        id: "jobs.detail.field.id",
+        startedAt: "jobs.detail.field.started",
+        finishedAt: "jobs.detail.field.finished",
+        duration: "jobs.detail.field.duration",
+        error: "jobs.detail.field.error",
+        logs: "jobs.detail.logs",
+      },
+      layout: {
+        sections: [
+          {
+            fields: [
+              "jobName",
+              "status",
+              "id",
+              { field: "startedAt", renderer: { format: "timestamp" } },
+              { field: "finishedAt", renderer: { format: "timestamp" } },
+              "duration",
+              "error",
+            ],
+          },
+          // No section `title` here (fw#2312 label-dedup fix): the section
+          // holds exactly one field, so a title would repeat the field's own
+          // label (rendered by RenderField as the Field's heading) verbatim.
+          {
+            fields: [{ field: "logs", renderer: { format: "json" } }],
+          },
+        ],
+      },
+      actions: [
+        {
+          kind: "writeHandler",
+          id: "retry",
+          label: "jobs.detail.retry",
+          handler: JobHandlers.retry,
+          payload: { map: { runId: "id" } },
+          visible: { field: "status", eq: "failed" },
+          style: "primary",
+        },
+      ],
       description:
         "Detail view of one job run with status, timings, error and log lines, and a retry action for failed runs; reached from a row of the job-runs list.",
       listScreenId: JOB_RUNS_SCREEN_ID,

package/src/jobs/handlers/list.query.ts

@@ -1,4 +1,4 @@
-import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
+import { countWhere, selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
@@ -28,7 +28,13 @@ export const listQuery = defineQueryHandler({
   schema: z.object({
     jobName: z.string().optional(),
     status: z.enum(["queued", "running", "completed", "failed"]).optional(),
+    filters: z
+      .array(z.object({ field: z.string(), op: z.literal("in"), value: z.array(z.string()) }))
+      .optional(),
+    sort: z.enum(["jobName", "status", "startedAt", "duration"]).optional(),
+    sortDirection: z.enum(["asc", "desc"]).optional(),
     limit: z.number().optional(),
+    totalCount: z.boolean().optional(),
   }),
   access: { roles: ["SystemAdmin"] },
   handler: async (query, ctx) => {
@@ -40,12 +46,23 @@ export const listQuery = defineQueryHandler({
     const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
     const where: WhereObject = {};
     if (query.payload.jobName) where["jobName"] = query.payload.jobName;
-    if (query.payload.status) where["status"] = query.payload.status;
+    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];
+    const sortColumn = query.payload.sort ?? "startedAt";
     const rows = await selectMany(db, jobRunsTable, where, {
-      orderBy: { col: "id", direction: "desc" },
+      orderBy: { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },
       limit: query.payload.limit ?? 50,
     });
+    // countWhere reruns the SAME `where` without the limit — `rows.length` is
+    // capped at the page size and would silently undercount the total.
+    const total =
+      query.payload.totalCount === true ? await countWhere(db, jobRunsTable, where) : undefined;
     // payload/error are stored encrypted under the triggering user's DEK (#799, #2307).
-    return { rows: await mapWithConcurrency(rows, KMS_POOL_CONCURRENCY, decryptRunRow) };
+    return {
+      rows: await mapWithConcurrency(rows, KMS_POOL_CONCURRENCY, decryptRunRow),
+      nextCursor: null,
+      ...(total !== undefined && { total }),
+    };
   },
 });