@cosmicdrift/kumiko-bundled-features 0.240.0 → 0.241.0

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 }),
+    };
   },
 });

package/src/jobs/handlers/trigger.write.ts

@@ -17,7 +17,7 @@ export const triggerWrite = defineWriteHandler({
     "Starts one manually-triggerable job with the given payload after validating it against the job's schema; use it to run a maintenance or import job on demand.",
   schema: z.object({
     jobName: z.string(),
-    payload: z.record(z.string(), z.unknown()).optional(),
+    payload: z.union([z.record(z.string(), z.unknown()), z.string()]).optional(),
   }),
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
@@ -43,8 +43,21 @@ export const triggerWrite = defineWriteHandler({
       );
     }
 
-    const rawPayload = event.payload.payload ?? {};
-    let payload: DbRow = rawPayload as DbRow;
+    let rawPayload: DbRow = {};
+    if (typeof event.payload.payload === "string" && event.payload.payload.trim() !== "") {
+      try {
+        const parsed: unknown = JSON.parse(event.payload.payload);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+          return writeFailure(new UnprocessableError(JobErrors.notManual));
+        }
+        rawPayload = parsed as DbRow;
+      } catch {
+        return writeFailure(new UnprocessableError(JobErrors.notManual));
+      }
+    } else if (event.payload.payload !== undefined) {
+      rawPayload = event.payload.payload as DbRow;
+    }
+    let payload: DbRow = rawPayload;
     if (jobDef.schema !== undefined) {
       const parsed = jobDef.schema.safeParse(rawPayload);
       if (!parsed.success) {

package/src/jobs/i18n.ts

@@ -6,13 +6,12 @@ type LocalizedString = { readonly en: string };
 export const JOBS_I18N: Readonly<Record<string, LocalizedString>> = {
   "screen:job-runs.title": { en: "Job runs" },
   "screen:job-run-detail.title": { en: "Job run" },
+  "screen:job-trigger.title": { en: "Trigger job" },
+  "jobs:entity:__action-form__:field:jobName": { en: "Job name" },
+  "jobs:entity:__action-form__:field:payload": { en: "JSON payload" },
   "jobs:nav.jobRuns": { en: "Jobs" },
-  "jobs.runs.title": { en: "Job runs" },
-  "jobs.runs.loading": { en: "Loading runs…" },
-  "jobs.runs.empty": { en: "No job runs." },
   "jobs.runs.open": { en: "Details" },
   "jobs.runs.filter.status": { en: "Status" },
-  "jobs.runs.filter.all": { en: "All" },
   "jobs.runs.filter.completed": { en: "Completed" },
   "jobs.runs.filter.failed": { en: "Failed" },
   "jobs.runs.filter.running": { en: "Running" },
@@ -21,8 +20,6 @@ export const JOBS_I18N: Readonly<Record<string, LocalizedString>> = {
   "jobs.runs.col.status": { en: "Status" },
   "jobs.runs.col.started": { en: "Started" },
   "jobs.runs.col.duration": { en: "Duration (ms)" },
-  "jobs.detail.loading": { en: "Loading details…" },
-  "jobs.detail.missing": { en: "Run not found." },
   "jobs.detail.field.job": { en: "Job" },
   "jobs.detail.field.status": { en: "Status" },
   "jobs.detail.field.id": { en: "Run ID" },
@@ -31,28 +28,9 @@ export const JOBS_I18N: Readonly<Record<string, LocalizedString>> = {
   "jobs.detail.field.duration": { en: "Duration (ms)" },
   "jobs.detail.field.error": { en: "Error" },
   "jobs.detail.logs": { en: "Logs" },
-  "jobs.detail.logs.empty": { en: "No log lines." },
   "jobs.detail.retry": { en: "Retry" },
-  "jobs.detail.retrying": { en: "Retrying…" },
   "jobs.trigger.title": { en: "Run a job" },
-  "jobs.trigger.explainer": {
-    en: "Only manually triggerable jobs. After starting, the run appears in the history below.",
-  },
-  "jobs.trigger.job": { en: "Job" },
-  "jobs.trigger.payload": { en: "Payload (JSON)" },
-  "jobs.trigger.payload.hint": { en: "Schema hint" },
-  "jobs.trigger.payload.invalidJson": {
-    en: "Payload is not a valid JSON object.",
-  },
   "jobs.trigger.submit": { en: "Run" },
-  "jobs.trigger.submitting": { en: "Starting…" },
-  "jobs.trigger.success": { en: "Job started." },
-  "jobs.trigger.empty": {
-    en: "No manually triggerable jobs are registered.",
-  },
-  "jobs.trigger.perTenant": {
-    en: "Runs once per active tenant.",
-  },
   "jobs.errors.unknownJob": { en: "Unknown job." },
   "jobs.errors.notManual": {
     en: "This job cannot be triggered manually.",

package/src/jobs/index.ts

@@ -1,3 +1,4 @@
+export { JOBS_FEATURE, JobErrors, JobHandlers, JobQueries } from "./constants";
 export { createJobsFeature, type JobsFeatureOptions } from "./feature";
 export type { JobRunLoggerCallbacks } from "./job-run-logger";
 export { createJobRunLogger } from "./job-run-logger";

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

@@ -1,10 +1,8 @@
 // @runtime client
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
-import { JOB_RUN_DETAIL_SCREEN_ID, JOB_RUNS_SCREEN_ID, JOBS_FEATURE } from "../constants";
+import { JOBS_FEATURE } from "../constants";
 import { defaultTranslations } from "./i18n";
-import { JobRunDetailScreen } from "./job-run-detail-screen";
-import { JobRunsScreen } from "./job-runs-screen";
 
 export type JobsClientOptions = {
   readonly translations?: TranslationsByLocale;
@@ -14,9 +12,5 @@ export function jobsClient(options?: JobsClientOptions): ClientFeatureDefinition
   return {
     name: JOBS_FEATURE,
     translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
-    components: {
-      [JOB_RUNS_SCREEN_ID]: JobRunsScreen,
-      [JOB_RUN_DETAIL_SCREEN_ID]: JobRunDetailScreen,
-    },
   };
 }

package/src/jobs/web/index.ts

@@ -1,4 +1,2 @@
 // @runtime client
 export { type JobsClientOptions, jobsClient } from "./client-plugin";
-export { JobRunDetailScreen } from "./job-run-detail-screen";
-export { JobRunsScreen } from "./job-runs-screen";

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

@@ -190,6 +190,38 @@ describe("scenario 5: tenant.list", () => {
       "SystemAdmin",
     ]);
   });
+
+  test("without totalCount the shape carries no total field (fw#2312)", async () => {
+    const result = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      nextCursor: string | null;
+      total?: number;
+    }>(TenantQueries.list, {}, systemAdmin);
+    expect(result.total).toBeUndefined();
+  });
+
+  test("total reflects the full match count, not capped by limit (fw#2312)", async () => {
+    await stack.http.writeOk(
+      TenantHandlers.create,
+      { key: "gamma", name: "Gamma LLC" },
+      systemAdmin,
+    );
+
+    const unpaged = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      TenantQueries.list,
+      {},
+      systemAdmin,
+    );
+    const expectedTotal = unpaged.rows.length;
+    expect(expectedTotal).toBeGreaterThanOrEqual(3);
+
+    const paged = await stack.http.queryOk<{
+      rows: Record<string, unknown>[];
+      total?: number;
+    }>(TenantQueries.list, { limit: 1, totalCount: true }, systemAdmin);
+    expect(paged.rows.length).toBe(1);
+    expect(paged.total).toBe(expectedTotal);
+  });
 });
 
 // --- Scenario 6: Config integration ---

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

@@ -12,6 +12,7 @@ export const listQuery = defineQueryHandler({
     cursor: z.string().optional(),
     limit: z.number().optional(),
     search: z.string().optional(),
+    totalCount: z.boolean().optional(),
   }),
   access: { roles: ["SystemAdmin"] },
   description:

package/src/tier-engine/__tests__/drift.test.ts

@@ -18,7 +18,7 @@ describe("tier-engine drift pins", () => {
     expect(TierEngineHandlers.update).toBe("tier-engine:write:tier-assignment:update");
     expect(TierEngineQueries.list).toBe("tier-engine:query:tier-assignment:list");
     expect(TierEngineQueries.getActiveTier).toBe("tier-engine:query:get-active-tier");
-    // Screen↔Handler-Contract: der TierAdminScreen dispatcht exakt diese QNs.
+    // Screen↔Handler-Contract: the tier-admin actionForm dispatches exactly these QNs.
     expect(TierEngineHandlers.setTenantTier).toBe("tier-engine:write:set-tenant-tier");
     expect(TierEngineQueries.getTenantTier).toBe("tier-engine:query:get-tenant-tier");
     expect(TierEngineQueries.tierOptions).toBe("tier-engine:query:tier-options");

package/src/tier-engine/__tests__/tier-engine-screens.boot.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import type { TierMap } from "../compose-app";
+import { TIER_ADMIN_SCREEN_ID } from "../constants";
+import { createTierEngineFeature } from "../feature";
+
+const SYSTEM_ADMIN_ROLES = ["SystemAdmin"] as const;
+
+type TestCaps = { readonly maxItems: number };
+const TEST_TIER_MAP: TierMap<TestCaps> = {
+  free: { features: [], caps: { maxItems: 1 } },
+  pro: { features: ["feat-pro"], caps: { maxItems: 5 } },
+};
+
+describe("tier-engine tier-admin screen + handler access alignment", () => {
+  test("boot-validates with the tier-admin actionForm registered (tierMap configured)", () => {
+    const features = [
+      createConfigFeature(),
+      createTenantFeature(),
+      createTierEngineFeature({ tierMap: TEST_TIER_MAP }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("boot-validates in storage-only mode with tier-admin screen showing the no-tiers message (no tierMap)", () => {
+    const features = [createConfigFeature(), createTenantFeature(), createTierEngineFeature()];
+    expect(() => validateBoot(features)).not.toThrow();
+    const tierEngine = createTierEngineFeature();
+    const screen = tierEngine.screens[TIER_ADMIN_SCREEN_ID];
+    expect(screen).toBeDefined();
+    if (screen && "layout" in screen) {
+      expect(screen.layout.sections[0]).toMatchObject({ description: "tier-admin.error.noTiers" });
+    }
+    if (screen && "fields" in screen) {
+      expect(screen.fields["tier"]).toEqual({ type: "select", options: [], required: true });
+    }
+  });
+
+  test("tier-admin is a SystemAdmin-gated actionForm dispatching set-tenant-tier", () => {
+    const tierEngine = createTierEngineFeature({ tierMap: TEST_TIER_MAP });
+    const screen = tierEngine.screens[TIER_ADMIN_SCREEN_ID];
+    expect(screen?.type).toBe("actionForm");
+    if (screen && "handler" in screen) {
+      expect(screen.handler).toBe("tier-engine:write:set-tenant-tier");
+    }
+    if (screen && "access" in screen && screen.access && "roles" in screen.access) {
+      expect(screen.access.roles).toEqual(SYSTEM_ADMIN_ROLES);
+    }
+    if (screen && "layout" in screen) {
+      expect(screen.layout.sections[0]).toMatchObject({ description: "tier-admin.explainer" });
+    }
+  });
+
+  test("tier-admin's tier field options come from the tierMap", () => {
+    const tierEngine = createTierEngineFeature({ tierMap: TEST_TIER_MAP });
+    const screen = tierEngine.screens[TIER_ADMIN_SCREEN_ID];
+    if (screen && "fields" in screen) {
+      expect(screen.fields["tier"]).toEqual({
+        type: "select",
+        options: ["free", "pro"],
+        required: true,
+      });
+      expect(screen.fields["tenantId"]).toEqual({
+        type: "reference",
+        entity: "tenant:tenant",
+        labelField: "name",
+        required: true,
+      });
+    }
+  });
+
+  test("set-tenant-tier write + get-tenant-tier/tier-options reads stay SystemAdmin-only", () => {
+    const tierEngine = createTierEngineFeature({ tierMap: TEST_TIER_MAP });
+    const roles = [...SYSTEM_ADMIN_ROLES];
+    expect(rolesOf(tierEngine.writeHandlers["set-tenant-tier"]?.access)).toEqual(roles);
+    expect(rolesOf(tierEngine.queryHandlers["get-tenant-tier"]?.access)).toEqual(roles);
+    expect(rolesOf(tierEngine.queryHandlers["tier-options"]?.access)).toEqual(roles);
+  });
+});

package/src/tier-engine/changes.json

@@ -1 +1,9 @@
-[]
+[
+  {
+    "version": "0.241.0",
+    "type": "breaking",
+    "title": "TierAdminScreen removed; tier-admin is now a declarative actionForm (fw#2312).",
+    "detail": "`tier-engine:screen:tier-admin` is now a declarative `actionForm` (a `reference` field for the tenant, a `select` field for the tier) instead of a custom React component: it dispatches `set-tenant-tier` directly, so the renderer's generic form handles tenant lookup, validation and submit. Two behaviors are intentionally not carried over: the current tier of the selected tenant is no longer shown before submit (declarative forms have no dependent-query support), and the success state no longer names the newly assigned tier (a generic actionForm success doesn't surface write-response data). Both are visible again after a page reload / re-navigation — the assignment itself is unchanged.",
+    "migration": "Breaking only if you imported `TierAdminScreen` directly (no shipped consumer app did — all reference the screen by its qualified id `tier-engine:screen:tier-admin`). Remove `import { TierAdminScreen } from \"@cosmicdrift/kumiko-bundled-features/tier-engine/web\"` and any `components: { TierAdminScreen: ... }` entry in your renderer setup — the bundled feature registers the `tier-admin` screen itself now, nothing left for an app to wire."
+  }
+]

package/src/tier-engine/constants.ts

@@ -1,9 +1,9 @@
 // @runtime client
-// Pure string-literal QNs/ids — von Server (feature.ts) UND Client
-// (web/tier-admin-screen, client-plugin) importiert. Als `client` markiert,
-// die im kumiko-Isolation-Modell permissivste Kategorie (runtime darf
-// client importieren, client nur client) — sonst wirft der Runtime-
-// Isolation-Guard auf den Client-Imports. Muster wie text-content/constants.
+// Pure string-literal QNs/ids — imported by both server (feature.ts) and
+// client (web/client-plugin.tsx). Marked `client`, the most permissive
+// category in the kumiko isolation model (runtime may import client, client
+// may only import client) — otherwise the runtime isolation guard throws on
+// the client imports. Same pattern as text-content/constants.
 // Feature name
 export const TIER_ENGINE_FEATURE = "tier-engine" as const;