@cosmicdrift/kumiko-framework 0.393.0 → 0.395.0

package/AGENTS.md

@@ -267,7 +267,7 @@ produces code that compiles and then fails in production.
 
 - Integration tests run against the real stack over real HTTP. In an app:
   `setupAppTestStack([feature])` plus `seedTenant(stack)` from
-  `@cosmicdrift/kumiko-testing`, then `tenant.api.writeOk` and
+  `@cosmicdrift/kumiko-dev-server/testing`, then `tenant.api.writeOk` and
   `tenant.api.queryOk`. Never assemble a dispatcher yourself
   (`createTestDispatcher` or similar); it skips the production wiring.
 - Every test seeds its own tenant. No shared tenant, no global fixtures.

package/agents/examples/cross-feature-events.md

@@ -34,6 +34,13 @@ Three building blocks:
   external system). With `table`, the apply materializes a persistent
   read model.
 
+- **`r.job(name, { trigger: { on: event.name, catchUp: true } }, run)`**
+  runs a job per stored event. With `catchUp` the job owns its own
+  consumer cursor (`job:<jobQn>`) that starts at the beginning of the
+  event store, so a job added to a running app also processes the
+  events from before its deploy. Each event enqueues at most one run.
+  Without `catchUp` a job only sees events appended after it went live.
+
 ## Flow
 
 ```
@@ -69,9 +76,75 @@ The integration test pins three guarantees:
 ```bash
 bun kumiko test integration samples/cross-feature-events
 ```
+4. **Catch-up job** — `catch-up-job.integration.test.ts` places orders
+   before the first dispatcher pass and checks that the `catchUp` job
+   invoices each of them exactly once.
 
 ## Source files
 
+### src/__tests__/catch-up-job.integration.test.ts
+
+```ts
+// The invoice-order job is triggered by the order-placed event with catchUp: it runs once per
+// stored event, including orders that were placed before the dispatcher ever looked at the store.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createTestUser } from "@cosmicdrift/kumiko-framework/seeding";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { waitFor } from "@cosmicdrift/kumiko-testing/helpers";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-testing/stack";
+import { invoicedOrderIds, orderEntity, pubsubOrderFeature } from "../feature";
+
+let stack: TestStack;
+
+const customer = createTestUser({ roles: ["Customer"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [pubsubOrderFeature],
+    jobs: { consumerLane: "worker", queueNamePrefix: `cross-feature-events-${generateId()}` },
+  });
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function placeOrder(customerName: string): Promise<string> {
+  const data = await stack.http.writeOk(
+    "pubsub-orders:write:order:place",
+    { customer: customerName, product: "Widget" },
+    customer,
+  );
+  return String(data["id"]);
+}
+
+describe("r.job with trigger catchUp", () => {
+  test("invoices every placed order exactly once, older ones included", async () => {
+    const earlier = [await placeOrder("Erin"), await placeOrder("Frank")];
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      await stack.drainJobs();
+      expect(invoicedOrderIds.slice().sort()).toEqual(earlier.slice().sort());
+    });
+
+    const later = await placeOrder("Grace");
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      await stack.drainJobs();
+      expect(invoicedOrderIds).toContain(later);
+    });
+    expect(invoicedOrderIds).toHaveLength(3);
+  });
+});
+```
+
 ### src/__tests__/feature.integration.test.ts
 
 ```ts
@@ -254,6 +327,7 @@ export type CapturedEvent = {
   readonly tenantId: string;
 };
 export const capturedEvents: CapturedEvent[] = [];
+export const invoicedOrderIds: string[] = [];
 
 // --- Feature ---
 
@@ -297,6 +371,19 @@ export const pubsubOrderFeature = defineFeature("pubsubOrders", (r) => {
     access: { roles: ["Admin", "Customer"] },
   });
 
+  // A job can react to the same event. `catchUp: true` gives the job its own
+  // consumer cursor that starts at the beginning of the event store, so a job
+  // added to a running app also processes the orders placed before it existed.
+  // Without catchUp the job only sees events appended after its deploy.
+  r.job(
+    "invoice-order",
+    { trigger: { on: orderPlaced.name, catchUp: true }, runIn: "worker" },
+    async (payload) => {
+      const order = orderPlaced.schema.parse(payload);
+      invoicedOrderIds.push(order.id);
+    },
+  );
+
   // Async consumer — Marten-style. Fires after commit, via the event-
   // dispatcher. No `table` means this MSP is pure side-effect (no state
   // persisted). Delivery is at-least-once and ordered per consumer.

package/agents/examples/dashboard-stats.md

@@ -28,6 +28,14 @@ query and the fields to read, the query does the counting.
   `list` with `filter`, `limit: 1` and `totalCount: true`. The total is counted
   over the whole WHERE clause, so no rows are loaded just to be counted.
 - **Labels are translation keys**: declared with `r.translations`.
+- **Record-bound dashboard**: `ticket-record-dashboard` binds to a record with `record`
+  and embeds the `ticket-card` projectionDetail as a screen panel; the record id
+  becomes its entityId.
+- **Gated toolbar button**: `visibleWhen` on a toolbar action asks a flat
+  capability query; the button is hidden while it loads or fails.
+- **Fallback by reason**: `fallback: { forbidden, notFound }` renders a screen on
+  403/404 of the gate query; other reasons get the default notice or an error
+  banner with retry.
 
 ## When to reach for it
 
@@ -63,7 +71,12 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { TICKET_STATS_QUERY, ticketEntity, ticketFeature } from "../feature";
+import {
+  TICKET_CAPABILITIES_QUERY,
+  TICKET_STATS_QUERY,
+  ticketEntity,
+  ticketFeature,
+} from "../feature";
 
 let stack: TestStack;
 
@@ -116,6 +129,42 @@ describe("ticket:stats", () => {
     expect(result).toEqual({ open: 3, closed: 2, total: 5 });
   });
 });
+
+describe("record-bound dashboard with a gated detail panel", () => {
+  test("the dashboard embeds the detail screen and the gate answers per role", async () => {
+    const dashboard = ticketFeature.screens["ticket-record-dashboard"];
+    if (dashboard?.type !== "dashboard") throw new Error("ticket-record-dashboard missing");
+    expect(dashboard.record).toEqual({ param: "ticketId", payloadKey: "id" });
+    expect(dashboard.panels.map((panel) => panel.kind)).toEqual(["screen"]);
+
+    const card = ticketFeature.screens["ticket-card"];
+    expect(card?.fallback).toEqual({ forbidden: "ticket-list", notFound: "ticket-list" });
+
+    const adminGate = await stack.http.queryOk<{ canClose: boolean }>(
+      TICKET_CAPABILITIES_QUERY,
+      {},
+      admin,
+    );
+    expect(adminGate.canClose).toBe(true);
+    const user = createTestUser({ roles: ["User"], tenantId: testTenantId(31) });
+    const userGate = await stack.http.queryOk<{ canClose: boolean }>(
+      TICKET_CAPABILITIES_QUERY,
+      {},
+      user,
+    );
+    expect(userGate.canClose).toBe(false);
+  });
+
+  test("the toolbar button carries the same gate", () => {
+    const list = ticketFeature.screens["ticket-list"];
+    if (list?.type !== "projectionList") throw new Error("ticket-list missing");
+    expect(list.toolbarActions?.[0]?.visibleWhen).toEqual({
+      query: TICKET_CAPABILITIES_QUERY,
+      field: "canClose",
+      eq: true,
+    });
+  });
+});
 ```
 
 ### src/feature.ts
@@ -123,7 +172,9 @@ describe("ticket:stats", () => {
 ```ts
 // Dashboard Stats Sample
 // Shows: a dashboard screen with a stat-group and a single stat, backed by one
-// query handler that counts in the database.
+// query handler that counts in the database. A second, record-bound dashboard embeds a
+// projectionDetail as a panel, hides a toolbar button behind a capability query, and picks its
+// fallback screen by the reason the gate closed.
 
 import {
   createEntity,
@@ -145,6 +196,7 @@ export const ticketEntity = createEntity({
 });
 
 export const TICKET_STATS_QUERY = "tickets:query:ticket:stats";
+export const TICKET_CAPABILITIES_QUERY = "tickets:query:ticket:capabilities";
 
 const readerRoles = { roles: ["Admin", "User"] } as const;
 
@@ -180,8 +232,51 @@ export const ticketFeature = defineFeature("tickets", (r) => {
     access: readerRoles,
   });
 
+  // Gate for the screens below: a flat answer with one boolean the screens test with `eq`.
+  r.queryHandler({
+    name: "ticket:capabilities",
+    schema: z.object({}),
+    outputSchema: z.object({ canClose: z.boolean() }),
+    handler: async (query) => ({ canClose: query.user.roles.includes("Admin") }),
+    access: readerRoles,
+  });
+
+  r.queryHandler({
+    name: "ticket:card",
+    schema: z.object({ id: z.string() }),
+    handler: async (query, ctx) => {
+      const page = await ticketExecutor.list(
+        { filter: { field: "id", op: "eq", value: query.payload.id }, limit: 1 },
+        query.user,
+        ctx.db,
+      );
+      const ticket = page.rows[0];
+      return { id: query.payload.id, title: ticket?.title ?? "", status: ticket?.status ?? "" };
+    },
+    access: readerRoles,
+  });
+
+  r.queryHandler({
+    name: "ticket:rows",
+    schema: z.object({}),
+    handler: async (query, ctx) => {
+      const page = await ticketExecutor.list({ limit: 50 }, query.user, ctx.db);
+      return { rows: page.rows, nextCursor: null };
+    },
+    access: readerRoles,
+  });
+
   r.translations({
     keys: {
+      "screen:ticket-list.title": { en: "Tickets" },
+      "screen:ticket-card.title": { en: "Ticket" },
+      "screen:ticket-record-dashboard.title": { en: "Ticket overview" },
+      "entity:ticket:field:title": { en: "Title" },
+      "entity:ticket:field:status": { en: "Status" },
+      "entity:__projection-detail__:field:title": { en: "Title" },
+      "entity:__projection-detail__:field:status": { en: "Status" },
+      "tickets.toolbar.close": { en: "Close all done" },
+      "tickets.dashboard.card": { en: "Ticket" },
       "tickets.dashboard.group": { en: "Tickets by status" },
       "tickets.dashboard.open": { en: "Open" },
       "tickets.dashboard.closed": { en: "Closed" },
@@ -224,5 +319,49 @@ export const ticketFeature = defineFeature("tickets", (r) => {
     ],
     access: readerRoles,
   });
+
+  // Three additions: a projectionDetail embedded in a record-bound dashboard, a gated toolbar
+  // button, and a fallback chosen by reason.
+  const gate = { query: TICKET_CAPABILITIES_QUERY, field: "canClose", eq: true } as const;
+
+  // The list doubles as the fallback target: it has no visibleWhen of its own.
+  r.screen({
+    id: "ticket-list",
+    type: "projectionList",
+    query: "tickets:query:ticket:rows",
+    columns: ["title", "status"],
+    access: readerRoles,
+    toolbarActions: [
+      {
+        kind: "writeHandler",
+        id: "close-done",
+        label: "tickets.toolbar.close",
+        handler: "tickets:write:ticket:update",
+        // Live and fail-closed: hidden while the query loads and when it fails.
+        visibleWhen: gate,
+      },
+    ],
+  });
+
+  r.screen({
+    id: "ticket-card",
+    type: "projectionDetail",
+    query: "tickets:query:ticket:card",
+    layout: { sections: [{ title: "tickets.dashboard.card", fields: ["title", "status"] }] },
+    access: readerRoles,
+    visibleWhen: gate,
+    // 403 and 404 on the gate query get their own screen; an unmet condition keeps the
+    // default notice and any other failure shows an error banner with retry.
+    fallback: { forbidden: "ticket-list", notFound: "ticket-list" },
+  });
+
+  // `record` reads the id from the URL; the embedded projectionDetail receives it as its entityId.
+  r.screen({
+    id: "ticket-record-dashboard",
+    type: "dashboard",
+    record: { param: "ticketId", payloadKey: "id" },
+    panels: [{ kind: "screen", id: "card", screen: "ticket-card" }],
+    access: readerRoles,
+  });
 });
 ```

package/agents/examples/env-composition.md

@@ -18,7 +18,7 @@ instead of keeping a hand-written copy of every feature's variables.
   `kmsEnvSchema` and `s3EnvSchema`. `composeEnvSchema` collects them and
   records which feature declared each variable.
 - **App-level blocks in `extend`**: `buildInfoEnvSchema`, `demoAdminEnvSchema`,
-  `stripeEnvSchema({ prices })`, `dodoEnvSchema({ prices })` and
+  `stripeEnvSchema({ prices })`, `paddleEnvSchema({ prices })` and
   `createS3EnvSchema({ prefix })` for a
   second bucket. These belong to no mounted feature, so the app adds them.
 - **Typed result**: `parseEnv(composed.schema, …)` returns the merged type,
@@ -35,7 +35,7 @@ instead of keeping a hand-written copy of every feature's variables.
 | `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
 | `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
 | `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
-| `dodoEnvSchema({ prices })` | `subscription-dodo` | app (`extend`); the feature registers the bridge keys |
+| `paddleEnvSchema({ prices })` | `subscription-paddle` | app (`extend`); the feature registers the bridge keys |
 | `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
 | `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
 | `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |
@@ -197,7 +197,7 @@ describe("env composition", () => {
     expect(sources["S3_BUCKET"]).toBe("file-provider-s3-env");
     expect(sources["RELEASES_S3_BUCKET"]).toBe("app");
     expect(sources["STRIPE_PRICE_PRO"]).toBe("app");
-    expect(sources["DODO_PRODUCT_PRO"]).toBe("app");
+    expect(sources["PADDLE_PRICE_PRO"]).toBe("app");
   });
 
   test("parses into a typed env", () => {
@@ -206,7 +206,7 @@ describe("env composition", () => {
       ...minimalValidValues,
       S3_BUCKET: "uploads",
       STRIPE_PRICE_PRO: "price_pro",
-      DODO_PRODUCT_PRO: "pdt_pro",
+      PADDLE_PRICE_PRO: "pri_pro",
     });
 
     const bucket: string | undefined = parsed.S3_BUCKET;
@@ -214,7 +214,7 @@ describe("env composition", () => {
     expect(bucket).toBe("uploads");
     expect(publicUrl).toBe("https://app.example.com");
     expect(parsed.KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION).toBe("1");
-    expect(parsed.DODO_PRODUCT_PRO).toBe("pdt_pro");
+    expect(parsed.PADDLE_PRICE_PRO).toBe("pri_pro");
   });
 
   test("reports every missing required variable with its source", () => {
@@ -270,7 +270,7 @@ import {
   demoAdminEnvSchema,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import { dodoEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-dodo";
+import { paddleEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-paddle";
 import { stripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
 import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
 import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
@@ -292,7 +292,7 @@ const appEnvSchema = z.object({
   ...buildInfoEnvSchema.shape,
   ...demoAdminEnvSchema.shape,
   ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
-  ...dodoEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...paddleEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
   ...createS3EnvSchema({ prefix: "RELEASES_S3_" }).shape,
   APP_PUBLIC_URL: z.url().describe("Public origin of the app, used in mail links."),
 });

package/agents/examples/inbound-mail-triage.md

@@ -36,6 +36,14 @@ mail-triage  ← this sample                                  (the app-side cons
 
 When the provider rejects the stored login, the supervisor sets the account to `auth_error` and stops fetching. With `inbound-provider-imap` mounted, the mail accounts list offers **Reconnect** on that row: the form `mail-account-reconnect-imap` is prefilled with the stored server settings (never the password), `inbound-provider-imap:write:reconnect-mailbox` checks the new login and puts the same account back to `active`. Threads, sync cursor and seen messages stay, so the next poll continues where the account stopped instead of ingesting the mailbox again. The cases are covered in `inbound-provider-imap/__tests__/reconnect-mailbox.integration.test.ts`; they need greenmail, which this sample's in-memory provider does not.
 
+## Mail content, quarantine and status
+
+Every ingested mail now carries its full text (`bodyText`, at most 32,000 characters, flagged by `bodyTextTruncated`), the original (`.eml`, or `.html` for HTML-only mails) and its attachments as file references; `inbound-mail-foundation:query:message:content` returns them, while `message:list` stays light and never carries the body. Retention removes the mail row but keeps the attachment files. Needs file storage in the app; without it the mail is still imported and the mailbox shows **Unterbrochen** (`file_storage_unavailable`).
+
+A mail the provider cannot parse is set aside in quarantine instead of blocking the mailbox: the rest imports, the sync cursor moves on, the account shows `degraded` with `lastError: message_quarantined` and the count, and `acknowledge-quarantine` clears it. Three failed polls in a row (`connection_failed`, `rate_limited`) also mark the mailbox `degraded` until the next success.
+
+A disconnected mailbox keeps its account id: `reactivate-account` (or connecting the same OAuth address again) puts it back to `active` with its cursor, so nothing is imported twice, and the mail arrives right away instead of at the next poll. Connecting an address that is already connected is refused with 409.
+
 ## Tests
 
 - E2E through `createAllInOneEntrypoint` (HTTP → dispatcher → BullMQ worker lane, no framework-internal shortcuts): connect → ingest → triage item appears.
@@ -70,8 +78,10 @@ import {
   createInboundMailFoundationFeature,
   InboundMailFoundationHandlers,
   inboundMessageEntity,
+  ingestFailureEntity,
   mailAccountEntity,
   mailThreadEntity,
+  quarantineEntity,
   seenMessageEntity,
   syncCursorEntity,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
@@ -116,6 +126,8 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(testDb.db, mailThreadEntity);
   await unsafeCreateEntityTable(testDb.db, syncCursorEntity);
   await unsafeCreateEntityTable(testDb.db, seenMessageEntity);
+  await unsafeCreateEntityTable(testDb.db, quarantineEntity);
+  await unsafeCreateEntityTable(testDb.db, ingestFailureEntity);
 });
 
 afterAll(async () => {

package/agents/examples/pdf-audit-export.md

@@ -42,7 +42,7 @@ bun test
 // and its text contains exactly the inspections of the requested period.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createFilesFeature,
   createInMemoryFileProvider,
@@ -54,8 +54,22 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
 import { extractText, getDocumentProxy } from "unpdf";
+import * as z from "zod";
 import { inspectionEntity, pdfAuditExportFeature } from "../feature";
 
+const EXPORT_AUDIT = "pdf-audit-export:write:export-audit";
+
+// Another command calling export-audit runs it nested: no beforeTransaction phase of its own.
+const nestedExportFeature = defineFeature("nested-export", (r) => {
+  r.requires({ features: ["pdf-audit-export"] });
+  r.writeHandler({
+    name: "run",
+    schema: z.object({ assetName: z.string(), from: z.string(), to: z.string() }),
+    access: { roles: ["Admin"] },
+    handler: async (event, ctx) => ctx.dispatch.write(EXPORT_AUDIT, event.payload),
+  });
+});
+
 let stack: TestStack;
 
 const userA = createTestUser({ id: 1, tenantId: testTenantId(1), roles: ["Admin"] });
@@ -63,7 +77,7 @@ const userB = createTestUser({ id: 2, tenantId: testTenantId(2), roles: ["Admin"
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createFilesFeature(), pdfAuditExportFeature],
+    features: [createFilesFeature(), pdfAuditExportFeature, nestedExportFeature],
     files: { storageProvider: createInMemoryFileProvider() },
   });
   await unsafeCreateEntityTable(stack.db, inspectionEntity);
@@ -163,6 +177,22 @@ describe("export-audit", () => {
     );
     expect(err.httpStatus).toBe(422);
   });
+
+  test("called from another handler it renders and stores inside the caller's transaction", async () => {
+    await addInspection("2026-02-05", "defect", "Zeile-verschachtelt", "Kessel 9");
+
+    const { fileRefId } = await stack.http.writeOk<{ fileRefId: string }>(
+      "nested-export:write:run",
+      { assetName: "Kessel 9", from: "2026-02-01", to: "2026-03-31" },
+      userA,
+    );
+
+    const res = await download(userA, fileRefId);
+    expect(res.status).toBe(200);
+    const proxy = await getDocumentProxy(new Uint8Array(await res.arrayBuffer()));
+    const { text } = await extractText(proxy, { mergePages: true });
+    expect(text).toContain("Zeile-verschachtelt");
+  });
 });
 ```
 
@@ -175,7 +205,9 @@ describe("export-audit", () => {
 // FileRef: renderTablePdf draws the table (pure JS, no browser). The storage
 // write runs in the beforeTransaction phase, so the transaction holds no pool
 // connection while the bytes upload; the handler then only creates the
-// fileRef row from event.prepared.
+// fileRef row from event.prepared. Called from another handler (a nested
+// write) there is no such phase, so the handler renders and stores inside the
+// caller's transaction instead.
 
 import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
 import {
@@ -190,6 +222,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import {
+  createFileRefFromBytes,
   createFileRefFromUploadedBytes,
   uploadFileBytesBeforeTransaction,
 } from "@cosmicdrift/kumiko-framework/files";
@@ -231,6 +264,62 @@ export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
   r.entity({ name: "inspection", ...inspectionEntity });
   const { executor: inspectionExecutor } = createEntityExecutor("inspection", inspectionEntity);
 
+  type AuditPayload = { assetName: string; from: string; to: string };
+  type ExecutorUser = Parameters<typeof inspectionExecutor.list>[1];
+  type ExecutorDb = Parameters<typeof inspectionExecutor.list>[2];
+
+  async function renderAudit(payload: AuditPayload, user: ExecutorUser, db: ExecutorDb) {
+    const { assetName, from, to } = payload;
+    const inspections = await inspectionExecutor.list(
+      {
+        filters: [
+          { field: "assetName", op: "eq", value: assetName },
+          { field: "inspectedOn", op: "gte", value: from },
+          { field: "inspectedOn", op: "lte", value: to },
+        ],
+        sort: "inspectedOn",
+        sortDirection: "asc",
+        limit: AUDIT_ROW_LIMIT + 1,
+      },
+      user,
+      db,
+    );
+    // A protocol that silently drops inspections would look complete.
+    if (inspections.rows.length > AUDIT_ROW_LIMIT) {
+      return writeFailure(
+        new UnprocessableError("audit_period_too_large", {
+          details: { limit: AUDIT_ROW_LIMIT },
+        }),
+      );
+    }
+
+    const { pdfBytes } = await renderTablePdf({
+      title: `Prüfprotokoll ${assetName}`,
+      meta: [
+        { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
+        { label: "Prüfungen", value: String(inspections.rows.length) },
+      ],
+      columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
+      rows: inspections.rows.map((row) => [
+        formatGermanDate(String(row["inspectedOn"])),
+        RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
+        String(row["inspector"] ?? ""),
+      ]),
+      emptyText: "Keine Prüfungen im Zeitraum",
+      footerText: `Prüfbericht ${assetName}`,
+      pageLabel: "Seite {page} von {pages}",
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
+        mimeType: "application/pdf",
+        data: pdfBytes,
+      },
+    };
+  }
+
   r.writeHandler({
     name: "inspection:create",
     schema: z.object({
@@ -248,56 +337,20 @@ export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
       name: "export-audit",
       schema: z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
       access: access.access,
+      // Nested in another command there is no phase of its own; the handler then does this work itself.
+      beforeTransactionWhenNested: "skip",
       beforeTransaction: async (event, ctx) => {
-        const { assetName, from, to } = event.payload;
-        const inspections = await inspectionExecutor.list(
-          {
-            filters: [
-              { field: "assetName", op: "eq", value: assetName },
-              { field: "inspectedOn", op: "gte", value: from },
-              { field: "inspectedOn", op: "lte", value: to },
-            ],
-            sort: "inspectedOn",
-            sortDirection: "asc",
-            limit: AUDIT_ROW_LIMIT + 1,
-          },
-          event.user,
-          ctx.db,
-        );
-        // A protocol that silently drops inspections would look complete.
-        if (inspections.rows.length > AUDIT_ROW_LIMIT) {
-          return writeFailure(
-            new UnprocessableError("audit_period_too_large", {
-              details: { limit: AUDIT_ROW_LIMIT },
-            }),
-          );
-        }
-
-        const { pdfBytes } = await renderTablePdf({
-          title: `Prüfprotokoll ${assetName}`,
-          meta: [
-            { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
-            { label: "Prüfungen", value: String(inspections.rows.length) },
-          ],
-          columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
-          rows: inspections.rows.map((row) => [
-            formatGermanDate(String(row["inspectedOn"])),
-            RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
-            String(row["inspector"] ?? ""),
-          ]),
-          emptyText: "Keine Prüfungen im Zeitraum",
-          footerText: `Prüfbericht ${assetName}`,
-          pageLabel: "Seite {page} von {pages}",
-        });
-
-        return uploadFileBytesBeforeTransaction(ctx, {
-          fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
-          mimeType: "application/pdf",
-          data: pdfBytes,
-        });
+        const rendered = await renderAudit(event.payload, event.user, ctx.db);
+        if (!rendered.isSuccess) return rendered;
+        return uploadFileBytesBeforeTransaction(ctx, rendered.data);
       },
       handler: async (event, ctx) => {
-        const created = await createFileRefFromUploadedBytes(ctx, event.prepared);
+        const created =
+          event.prepared !== undefined
+            ? await createFileRefFromUploadedBytes(ctx, event.prepared)
+            : await renderAudit(event.payload, event.user, ctx.db).then((rendered) =>
+                rendered.isSuccess ? createFileRefFromBytes(ctx, rendered.data) : rendered,
+              );
         if (!created.isSuccess) return created;
         return { isSuccess: true as const, data: { fileRefId: created.data.id } };
       },