@cosmicdrift/kumiko-samples 0.390.1 → 0.391.0

package/packages/bundled-features/src/mail-foundation/probe.ts

@@ -0,0 +1,81 @@
+import {
+  createSystemUser,
+  type FeatureRegistrar,
+  type ProbeContext,
+  ProbeFailure,
+  SETTINGS_HUB_FEATURE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { HostResolutionError } from "@cosmicdrift/kumiko-framework/http";
+import { createConfigAccessor } from "../config/index.ts";
+import { tenantMailTransport } from "./feature.ts";
+import { MAIL_PROBE_KEYS } from "./i18n.ts";
+
+const PROBE_SUBJECT = "Kumiko system check";
+const PROBE_TEXT = "This message was sent by the system check. No action is needed.";
+const MAIL_SETTINGS_SCREEN_QN = `${SETTINGS_HUB_FEATURE}:screen:mail-foundation-tenant`;
+
+// The raw error stays in the server log: it can name hosts, users or the recipient.
+function probeFailure(ctx: ProbeContext, error: unknown, key: string): ProbeFailure {
+  ctx.obs.log.warn("mail probe failed", {
+    error: error instanceof Error ? error.message : String(error),
+  });
+  return new ProbeFailure({ key });
+}
+
+function transportFailureKey(error: unknown): string {
+  if (error instanceof HostResolutionError) return MAIL_PROBE_KEYS.hostNotFound;
+  return error instanceof UnconfiguredError
+    ? MAIL_PROBE_KEYS.setupIncomplete
+    : MAIL_PROBE_KEYS.setupFailed;
+}
+
+// The mail goes to whoever started the check; the address never appears in the stored result.
+export function registerMailProbe(r: FeatureRegistrar<"mail-foundation">): void {
+  r.probe({
+    name: "send-test-mail",
+    scope: "tenant",
+    cost: "free",
+    area: MAIL_PROBE_KEYS.area,
+    label: MAIL_PROBE_KEYS.label,
+    fixScreen: MAIL_SETTINGS_SCREEN_QN,
+    run: async (ctx) => {
+      const { configResolver, secrets } = ctx.services;
+      if (!configResolver) {
+        return { status: "skipped", message: { key: MAIL_PROBE_KEYS.notConfigured } };
+      }
+      const config = createConfigAccessor(
+        ctx.registry,
+        configResolver,
+        ctx.tenantId,
+        createSystemUser(ctx.tenantId).id,
+        ctx.db,
+      );
+      const transport = await tenantMailTransport({
+        tenantId: ctx.tenantId,
+        config,
+        registry: ctx.registry,
+        secrets,
+      }).catch((error: unknown) => {
+        throw probeFailure(ctx, error, transportFailureKey(error));
+      });
+      if (transport === null) {
+        return { status: "skipped", message: { key: MAIL_PROBE_KEYS.notConfigured } };
+      }
+      if (ctx.triggeredByEmail === undefined) {
+        return { status: "skipped", message: { key: MAIL_PROBE_KEYS.noRecipient } };
+      }
+      await transport
+        .send({
+          to: ctx.triggeredByEmail,
+          subject: PROBE_SUBJECT,
+          text: PROBE_TEXT,
+          html: `<p>${PROBE_TEXT}</p>`,
+        })
+        .catch((error: unknown) => {
+          throw probeFailure(ctx, error, MAIL_PROBE_KEYS.sendRejected);
+        });
+      return { status: "ok", message: { key: MAIL_PROBE_KEYS.accepted } };
+    },
+  });
+}

package/packages/bundled-features/src/readiness/built-in-probes.ts

@@ -0,0 +1,58 @@
+import type { FeatureRegistrar, ProbeContext } from "@cosmicdrift/kumiko-framework/engine";
+import { ProbeTextKeys } from "./constants.ts";
+import { probeRunsTable } from "./schema/probe-run.ts";
+
+export const BuiltInProbeKeys = {
+  areaInfrastructure: "readiness.area.infrastructure",
+  databaseLabel: "readiness.probe.database.label",
+  databaseOk: "readiness.probe.database.ok",
+  cacheLabel: "readiness.probe.cache.label",
+  cacheOk: "readiness.probe.cache.ok",
+  searchLabel: "readiness.probe.search.label",
+  searchOk: "readiness.probe.search.ok",
+} as const;
+
+export function registerBuiltInProbes(r: FeatureRegistrar<"readiness">): void {
+  r.probe({
+    name: "database",
+    scope: "system",
+    cost: "free",
+    area: BuiltInProbeKeys.areaInfrastructure,
+    label: BuiltInProbeKeys.databaseLabel,
+    run: async (ctx: ProbeContext) => {
+      await ctx.db.fetchOne(probeRunsTable, { id: ctx.probeRunId });
+      return { status: "ok", message: { key: BuiltInProbeKeys.databaseOk } };
+    },
+  });
+
+  r.probe({
+    name: "cache",
+    scope: "system",
+    cost: "free",
+    area: BuiltInProbeKeys.areaInfrastructure,
+    label: BuiltInProbeKeys.cacheLabel,
+    run: async (ctx: ProbeContext) => {
+      const { redis } = ctx.services;
+      if (!redis) return { status: "skipped", message: { key: ProbeTextKeys.notConfigured } };
+      const reply = await redis.ping();
+      if (reply !== "PONG") throw new Error(`unexpected PING reply: ${reply}`);
+      return { status: "ok", message: { key: BuiltInProbeKeys.cacheOk } };
+    },
+  });
+
+  r.probe({
+    name: "search",
+    scope: "system",
+    cost: "free",
+    area: BuiltInProbeKeys.areaInfrastructure,
+    label: BuiltInProbeKeys.searchLabel,
+    run: async (ctx: ProbeContext) => {
+      const { searchAdapter } = ctx.services;
+      if (!searchAdapter) {
+        return { status: "skipped", message: { key: ProbeTextKeys.notConfigured } };
+      }
+      await searchAdapter.search(ctx.tenantId, "readiness-probe", { limit: 1 });
+      return { status: "ok", message: { key: BuiltInProbeKeys.searchOk } };
+    },
+  });
+}

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.391.0",
+    "type": "improvement",
+    "title": "Probe runs and the system-check screen",
+    "detail": "The new readiness:write:run-probes starts a run as a worker job; includePaid also runs paid probes. A run only writes its own probe-run events, the probes read through adapters and fixtures and never write domain data. New queries return the latest run with its summary, the run history with the starter's name, and one run with its results. Probe texts arrive as { i18nKey, i18nParams }, and failed rows carry the QN of the screen that fixes the problem; the boot validator checks that QN against the feature screens and the generated settings screens. A probe that reports itself skipped shows no duration. createReadinessFeature({ nav: { order?, parent?, workspaces? } }) adds the system-check screen to the nav (workspace apps list the workspaces, a parent's membership does not carry over): start buttons (the paid one only when paid probes exist), the latest results with a fix link on failed rows, and the history that opens each run. Standard probes cover database, cache, search, mail sending, file storage, inbound mailboxes and the PDF service.",
+    "migration": "New table read_readiness_probe_runs. Apps that mount readiness run `kumiko schema generate` and apply the migration before deploying. Without a nav option the screen stays dormant; pass createReadinessFeature({ nav: {} }) or a parent nav QN to show it."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/readiness/collect-probes.ts

@@ -0,0 +1,47 @@
+import type { ProbeDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  DEFAULT_PROBE_TIMEOUT_MS,
+  MIN_STALE_RUN_AFTER_MS,
+  STALE_RUN_TIMEOUT_FACTOR,
+} from "./constants.ts";
+
+export type CollectProbesOptions = {
+  readonly includeSystemProbes: boolean;
+  // Feature names enabled for the tenant; undefined = every mounted feature.
+  readonly enabledFeatures: ReadonlySet<string> | undefined;
+};
+
+export function collectProbes(
+  registry: Registry,
+  options: CollectProbesOptions,
+): readonly ProbeDefinition[] {
+  const collected: ProbeDefinition[] = [];
+  for (const feature of registry.features.values()) {
+    if (options.enabledFeatures !== undefined && !options.enabledFeatures.has(feature.name)) {
+      continue;
+    }
+    for (const probe of Object.values(feature.probes ?? {})) {
+      if (probe.scope === "system" && !options.includeSystemProbes) continue;
+      collected.push(probe);
+    }
+  }
+  return collected;
+}
+
+export function hasPaidProbes(registry: Registry, options: CollectProbesOptions): boolean {
+  return collectProbes(registry, options).some((probe) => probe.cost === "paid");
+}
+
+export function probeTimeoutMs(probe: ProbeDefinition): number {
+  return probe.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+}
+
+export function staleRunAfterMs(registry: Registry): number {
+  let longestTimeoutMs = 0;
+  for (const feature of registry.features.values()) {
+    for (const probe of Object.values(feature.probes ?? {})) {
+      longestTimeoutMs = Math.max(longestTimeoutMs, probeTimeoutMs(probe));
+    }
+  }
+  return Math.max(MIN_STALE_RUN_AFTER_MS, longestTimeoutMs * STALE_RUN_TIMEOUT_FACTOR);
+}

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

@@ -4,4 +4,29 @@ export const READINESS_FEATURE = "readiness" as const;
 // Qualified query handler names (QN format: scope:type:name)
 export const ReadinessQueries = {
   status: "readiness:query:status",
+  latestResults: "readiness:query:probe-run:latest-results",
+  latestSummary: "readiness:query:probe-run:latest-summary",
+  runList: "readiness:query:probe-run:list",
+  runDetail: "readiness:query:probe-run:detail",
+  runResults: "readiness:query:probe-run:results",
+} as const;
+
+export const ReadinessWrites = {
+  runProbes: "readiness:write:run-probes",
+} as const;
+
+export const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
+
+// An active run older than this is treated as dead (worker crash) and may be replaced.
+export const MIN_STALE_RUN_AFTER_MS = 10 * 60_000;
+export const STALE_RUN_TIMEOUT_FACTOR = 3;
+
+// Translation keys of the runner's own result texts.
+export const ProbeTextKeys = {
+  paidNotRequested: "readiness.probe.paid-not-requested",
+  noTargets: "readiness.probe.no-targets",
+  timeout: "readiness.probe.timeout",
+  failed: "readiness.probe.failed",
+  runCrashed: "readiness.probe.run-crashed",
+  notConfigured: "readiness.probe.not-configured",
 } as const;

package/packages/bundled-features/src/readiness/execute-probes.ts

@@ -0,0 +1,116 @@
+import { runWithTimeout } from "@cosmicdrift/kumiko-framework/api";
+import {
+  type ProbeContext,
+  type ProbeDefinition,
+  ProbeFailure,
+  type ProbeTarget,
+  type ProbeText,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { probeTimeoutMs } from "./collect-probes.ts";
+import { ProbeTextKeys } from "./constants.ts";
+import type { ProbeResultRow } from "./schema/probe-run.ts";
+
+type RunOutcome = Pick<ProbeResultRow, "status" | "durationMs" | "message">;
+
+function baseRow(probe: ProbeDefinition, target: ProbeTarget | undefined) {
+  return {
+    probe: probe.qualifiedName,
+    scope: probe.scope,
+    area: probe.area,
+    label: target ? target.label : { key: probe.label },
+    ...(target && { targetId: target.id }),
+    ...(target?.ownerUserId !== undefined && { ownerUserId: target.ownerUserId }),
+    ...(probe.fixScreen !== undefined && { fixScreen: probe.fixScreen }),
+  };
+}
+
+function rowOf(
+  probe: ProbeDefinition,
+  target: ProbeTarget | undefined,
+  outcome: RunOutcome,
+): ProbeResultRow {
+  return { ...baseRow(probe, target), ...outcome };
+}
+
+// Raw error messages can carry secrets or addresses, so only ProbeFailure texts reach the run.
+function failureText(
+  ctx: ProbeContext,
+  probe: ProbeDefinition,
+  failure: { readonly error: unknown; readonly timedOut: boolean },
+): ProbeText {
+  if (failure.timedOut) {
+    return { key: ProbeTextKeys.timeout, params: { seconds: probeTimeoutMs(probe) / 1000 } };
+  }
+  if (failure.error instanceof ProbeFailure) return failure.error.text;
+  ctx.obs.log.warn("readiness probe failed", {
+    probe: probe.qualifiedName,
+    error: failure.error instanceof Error ? failure.error.message : String(failure.error),
+  });
+  return { key: ProbeTextKeys.failed };
+}
+
+async function runOne(
+  ctx: ProbeContext,
+  probe: ProbeDefinition,
+  target: ProbeTarget | undefined,
+): Promise<ProbeResultRow> {
+  const result = await runWithTimeout(() => probe.run(ctx, target), probeTimeoutMs(probe));
+  if (result.ok) {
+    // A skipped probe did not run, so its row shows no duration like the runner's own skips.
+    return rowOf(probe, target, {
+      status: result.value.status,
+      durationMs: result.value.status === "skipped" ? null : result.latencyMs,
+      message: result.value.message,
+    });
+  }
+  return rowOf(probe, target, {
+    status: "failed",
+    durationMs: result.latencyMs,
+    message: failureText(ctx, probe, result),
+  });
+}
+
+function skippedRow(probe: ProbeDefinition, messageKey: string): ProbeResultRow {
+  return rowOf(probe, undefined, {
+    status: "skipped",
+    durationMs: null,
+    message: { key: messageKey },
+  });
+}
+
+async function runProbe(
+  ctx: ProbeContext,
+  probe: ProbeDefinition,
+  includePaid: boolean,
+): Promise<readonly ProbeResultRow[]> {
+  if (probe.cost === "paid" && !includePaid) {
+    return [skippedRow(probe, ProbeTextKeys.paidNotRequested)];
+  }
+  const { targets } = probe;
+  if (targets === undefined) return [await runOne(ctx, probe, undefined)];
+
+  const resolved = await runWithTimeout(() => targets(ctx), probeTimeoutMs(probe));
+  if (!resolved.ok) {
+    return [
+      rowOf(probe, undefined, {
+        status: "failed",
+        durationMs: resolved.latencyMs,
+        message: failureText(ctx, probe, resolved),
+      }),
+    ];
+  }
+  const ownTargets = resolved.value.filter(
+    (target) => target.ownerUserId === undefined || target.ownerUserId === ctx.triggeredByUserId,
+  );
+  if (ownTargets.length === 0) return [skippedRow(probe, ProbeTextKeys.noTargets)];
+  return Promise.all(ownTargets.map((target) => runOne(ctx, probe, target)));
+}
+
+export async function executeProbes(
+  ctx: ProbeContext,
+  probes: readonly ProbeDefinition[],
+  includePaid: boolean,
+): Promise<readonly ProbeResultRow[]> {
+  const perProbe = await Promise.all(probes.map((probe) => runProbe(ctx, probe, includePaid)));
+  return perProbe.flat();
+}

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

@@ -9,14 +9,48 @@
 // `ready` boolean — the settings-checklist call for admin UIs.
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { registerBuiltInProbes } from "./built-in-probes.ts";
+import { ReadinessWrites } from "./constants.ts";
+import { latestResultsQuery } from "./handlers/latest-results.query.ts";
+import { latestSummaryQuery } from "./handlers/latest-summary.query.ts";
+import { runDetailQuery } from "./handlers/run-detail.query.ts";
+import { runListQuery } from "./handlers/run-list.query.ts";
+import { runProbesWrite } from "./handlers/run-probes.write.ts";
+import { runResultsQuery } from "./handlers/run-results.query.ts";
 import { statusQuery } from "./handlers/status.query.ts";
+import { READINESS_I18N } from "./i18n.ts";
+import { validateProbeTranslations } from "./probe-boot-check.ts";
+import { runProbesJob } from "./run-probes-job.ts";
+import { probeRunEntity } from "./schema/probe-run.ts";
+import {
+  SYSTEM_CHECK_NAV_LABEL,
+  SYSTEM_CHECK_SCREEN_ID,
+  SYSTEM_CHECK_SCREEN_QN,
+  systemCheckRunScreen,
+  systemCheckScreen,
+} from "./screens.ts";
 
-export function createReadinessFeature() {
+export interface ReadinessNavOptions {
+  readonly order?: number;
+  readonly parent?: string;
+  // Workspace apps need it: a nav belongs only to the workspaces it names, a parent's do not carry over.
+  readonly workspaces?: readonly string[];
+}
+
+export interface ReadinessFeatureOptions {
+  // Without a nav entry the system-check screen stays dormant; apps link it themselves.
+  readonly nav?: ReadinessNavOptions;
+}
+
+const DEFAULT_NAV_ORDER = 90;
+
+export function createReadinessFeature(options: ReadinessFeatureOptions = {}) {
+  const { nav } = options;
   return defineFeature(
     "readiness",
     (r) => {
       r.describe(
-        "One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`.",
+        "One-call tenant-onboarding probe: `readiness:query:status` rolls up every config key and secret declared `required: true` across all mounted features and reports which still lack a usable value for the calling tenant, plus a single `ready` boolean. Provider-features under an `r.extensionSelector`-declared extension point count only while their provider is the selected one — a tenant on the inmemory mail transport is not blocked by unset SMTP keys. Mount it (together with `config` and `secrets`) when an admin UI needs a settings checklist before the first mail-send or file-write; the per-concern lists stay available via `config:query:readiness` and `secrets:query:list`. `readiness:write:run-probes` runs the live probes features register with `r.probe` (mail, files, mailboxes, PDF service and more) as a job; the system-check screen shows the latest run and the history once `nav` is passed.",
       );
       r.uiHints({
         displayLabel: "Readiness · Onboarding Probe",
@@ -25,13 +59,67 @@ export function createReadinessFeature() {
       });
       r.requires({ features: ["config"] });
       r.requires({ features: ["secrets"] });
+      r.optionalRequires("user");
+      r.adoptsBundledLists();
+
+      r.translations({ keys: READINESS_I18N });
+      r.entity({ name: "probe-run", ...probeRunEntity });
+      r.writeHandler(runProbesWrite);
+      r.job({
+        name: "run-probes",
+        trigger: { on: ReadinessWrites.runProbes },
+        runIn: "worker",
+        retries: 0,
+        escapeHatch: {
+          reason: "looks up the run starter's address via the system-only user auth lookup",
+          grants: ["systemIdentity"],
+        },
+        // Inline so the feature-AST reader can parse the job; the logic lives in run-probes-job.ts.
+        handler: (payload, ctx) => runProbesJob(payload, ctx),
+      });
+      registerBuiltInProbes(r);
+      r.bootCheck(({ features }) => validateProbeTranslations(features));
+
+      r.screen(systemCheckScreen(nav === undefined));
+      r.screen(systemCheckRunScreen);
+      if (nav !== undefined) {
+        // Explicit property assignments: the feature-AST parser reads neither `??`, shorthand
+        // properties nor a conditional spread, and the boot validator treats `parent: undefined`
+        // as a top-level entry.
+        const {
+          order: navOrder = DEFAULT_NAV_ORDER,
+          parent: navParent,
+          workspaces: navWorkspaces,
+        } = nav;
+        r.nav({
+          id: SYSTEM_CHECK_SCREEN_ID,
+          label: SYSTEM_CHECK_NAV_LABEL,
+          icon: "shield-check",
+          screen: SYSTEM_CHECK_SCREEN_QN,
+          order: navOrder,
+          parent: navParent,
+          workspaces: navWorkspaces,
+        });
+      }
 
       const queries = {
         status: r.queryHandler(statusQuery),
+        latestResults: r.queryHandler(latestResultsQuery),
+        latestSummary: r.queryHandler(latestSummaryQuery),
+        runList: r.queryHandler(runListQuery),
+        runDetail: r.queryHandler(runDetailQuery),
+        runResults: r.queryHandler(runResultsQuery),
       };
 
       return { queries };
     },
-    { dedupeOptions: {} },
+    {
+      dedupeOptions: {
+        hasNav: nav !== undefined,
+        navOrder: nav?.order ?? DEFAULT_NAV_ORDER,
+        navParent: nav?.parent ?? "",
+        navWorkspaces: nav?.workspaces?.join(",") ?? "",
+      },
+    },
   );
 }

package/packages/bundled-features/src/readiness/handlers/latest-results.query.ts

@@ -0,0 +1,15 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { fetchLatestRun, viewRun } from "../run-view.ts";
+
+export const latestResultsQuery = defineQueryHandler({
+  name: "probe-run:latest-results",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Returns the per-probe results of the tenant's latest system-check run (finished or still running) that the caller may see: system probes only for SystemAdmin, personal mailboxes only for their owner. Empty rows while the run is still working or when no run exists.",
+  handler: async (query, ctx) => {
+    const latest = await fetchLatestRun(ctx.db);
+    return { rows: latest ? viewRun(latest, query.user).results : [], nextCursor: null };
+  },
+});

package/packages/bundled-features/src/readiness/handlers/latest-summary.query.ts

@@ -0,0 +1,53 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { hasPaidProbes } from "../collect-probes.ts";
+import { fetchLatestRun, viewRun } from "../run-view.ts";
+import { countResults } from "../visible-results.ts";
+import { toneOf } from "./run-tone.ts";
+
+export const SUMMARY_TEXT_KEY = "readiness.summary.ok-of-total";
+export const SUMMARY_RUNNING_TEXT_KEY = "readiness.summary.running";
+export const SUMMARY_NO_RUN_TEXT_KEY = "readiness.summary.no-run";
+
+export const latestSummaryQuery = defineQueryHandler({
+  name: "probe-run:latest-summary",
+  schema: z.object({}),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Returns the one-line summary of the tenant's latest system-check run (when it started, how many of the checks the caller may see passed, a tone and a ready-made translatable text) and whether the caller's check has paid probes. Zero counts and runId null when no run exists yet.",
+  handler: async (query, ctx) => {
+    const paid = hasPaidProbes(ctx.registry, {
+      includeSystemProbes: query.user.roles.includes("SystemAdmin"),
+      enabledFeatures: ctx.services.effectiveFeatures?.(query.user.tenantId),
+    });
+    const latest = await fetchLatestRun(ctx.db);
+    if (!latest) {
+      return {
+        // The system-check screen's record id only gates its sections; their queries ignore it.
+        id: query.user.tenantId,
+        runId: null,
+        hasPaidProbes: paid,
+        ...countResults([]),
+        text: { i18nKey: SUMMARY_NO_RUN_TEXT_KEY },
+      };
+    }
+    const { counts, outcome } = viewRun(latest, query.user);
+    return {
+      id: latest.id,
+      runId: latest.id,
+      hasPaidProbes: paid,
+      requestedAt: latest.requestedAt.toString(),
+      status: latest.status,
+      ...counts,
+      outcome,
+      tone: toneOf(outcome),
+      text:
+        outcome === "running"
+          ? { i18nKey: SUMMARY_RUNNING_TEXT_KEY }
+          : {
+              i18nKey: SUMMARY_TEXT_KEY,
+              i18nParams: { ok: counts.okCount, total: counts.totalCount },
+            },
+    };
+  },
+});

package/packages/bundled-features/src/readiness/handlers/run-detail.query.ts

@@ -0,0 +1,31 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { type RunRow, viewRun } from "../run-view.ts";
+import { probeRunsTable } from "../schema/probe-run.ts";
+import { toneOf } from "./run-tone.ts";
+
+export const runDetailQuery = defineQueryHandler({
+  name: "probe-run:detail",
+  schema: z.object({ runId: z.uuid() }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Returns the header of one system-check run of the caller's tenant: status, timing, starter and the outcome counts of the results the caller may see.",
+  handler: async (query, ctx) => {
+    const run = await ctx.db.fetchOne<RunRow>(probeRunsTable, { id: query.payload.runId });
+    if (!run) throw new NotFoundError("probe-run", query.payload.runId);
+    const { counts, outcome } = viewRun(run, query.user);
+    return {
+      id: run.id,
+      status: run.status,
+      requestedAt: run.requestedAt.toString(),
+      startedAt: run.startedAt?.toString() ?? null,
+      finishedAt: run.finishedAt?.toString() ?? null,
+      triggeredByUserId: run.triggeredByUserId,
+      durationMs: run.durationMs,
+      ...counts,
+      outcome,
+      tone: toneOf(outcome),
+    };
+  },
+});

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

@@ -0,0 +1,48 @@
+import {
+  defineQueryHandler,
+  pagedListSchema,
+  pageRows,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { resolveUserDisplayNames, USER_FEATURE } from "../../user/index.ts";
+import { HISTORY_LIMIT, type RunRow, viewRun } from "../run-view.ts";
+import { probeRunsTable } from "../schema/probe-run.ts";
+
+const SORT_FIELDS = ["requestedAt"] as const;
+
+export const runListQuery = defineQueryHandler({
+  name: "probe-run:list",
+  schema: pagedListSchema(SORT_FIELDS),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description: `Lists the tenant's most recent system-check runs (up to ${HISTORY_LIMIT}), newest first, with starter (display name when the user feature is mounted), status, duration and the outcome counts of the results the caller may see.`,
+  handler: async (query, ctx) => {
+    const runs = await ctx.db.selectMany<RunRow>(
+      probeRunsTable,
+      {},
+      { limit: HISTORY_LIMIT, orderBy: { col: "requestedAt", direction: "desc" } },
+    );
+    const starterIds = [...new Set(runs.map((run) => run.triggeredByUserId))];
+    const starterNames =
+      ctx.registry.getFeature(USER_FEATURE) === undefined
+        ? new Map<string, string>()
+        : await resolveUserDisplayNames(ctx.db, starterIds);
+    const rows = runs.map((run) => {
+      const { counts, outcome } = viewRun(run, query.user);
+      return {
+        id: run.id,
+        requestedAt: run.requestedAt.toString(),
+        triggeredByUserId: run.triggeredByUserId,
+        triggeredByName: starterNames.get(run.triggeredByUserId) ?? run.triggeredByUserId,
+        status: run.status,
+        okCount: counts.okCount,
+        failedCount: counts.failedCount,
+        durationMs: run.durationMs,
+        outcome,
+      };
+    });
+    return pageRows(
+      rows,
+      { ...query.payload, sortDirection: query.payload.sortDirection ?? "desc" },
+      { searchFields: ["requestedAt"], defaultSort: "requestedAt" },
+    );
+  },
+});