@cosmicdrift/kumiko-framework 0.364.0 → 0.365.0

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

@@ -2,7 +2,7 @@
 
 # pdf-audit-export
 
-Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and stores the bytes as a FileRef via createFileRefFromBytes.
+Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and uploads the bytes before the transaction (uploadFileBytesBeforeTransaction) and stores them as a FileRef (createFileRefFromUploadedBytes).
 
 ## README
 
@@ -13,7 +13,8 @@ A write handler exports tenant data as a PDF and keeps it as a FileRef.
 ## What it shows
 
 - `renderTablePdf` (`@cosmicdrift/kumiko-bundled-features/renderer-pdf`) draws a table document in pure JavaScript: repeating header, weighted columns, page footer. The handler passes ready-formatted strings.
-- `createFileRefFromBytes` (`@cosmicdrift/kumiko-framework/files`) stores the bytes like an upload (validation, tenant-prefixed storage key, `fileRef.created` event); the tenant comes from the caller.
+- The export is a `beforeTransaction` handler: it reads the rows (reads work in that phase), renders the PDF and calls `uploadFileBytesBeforeTransaction` (`@cosmicdrift/kumiko-framework/files`), which validates the bytes and writes them to the tenant-prefixed storage key. The upload runs before the transaction because storage I/O inside it would hold a pool connection for as long as the upload takes.
+- The handler itself calls `createFileRefFromUploadedBytes(ctx, event.prepared)` and creates the `file_refs` row and the `fileRef.created` event in the transaction. If the transaction does not commit, the phase's `release` deletes the uploaded bytes again (only when no row exists for the storage key). A crash between upload and commit leaves the bytes in storage; nothing sweeps them.
 - The result is a normal FileRef: `GET /api/files/:id` serves it with `Content-Type: application/pdf`, other tenants get 404.
 
 ## Source
@@ -147,6 +148,21 @@ describe("export-audit", () => {
     const { text } = await extractText(proxy, { mergePages: true });
     expect(text).toContain("Keine Prüfungen im Zeitraum");
   });
+
+  test("a period with more inspections than the export holds is rejected instead of cut off", async () => {
+    const assetName = "Großanlage";
+    for (let day = 0; day < 101; day += 1) {
+      const inspectedOn = new Date(Date.UTC(2025, 0, 1 + day)).toISOString().slice(0, 10);
+      await addInspection(inspectedOn, "ok", `Prüfer-${day}`, assetName);
+    }
+
+    const err = await stack.http.writeErr(
+      "pdf-audit-export:write:export-audit",
+      { assetName, from: "2025-01-01", to: "2025-12-31" },
+      userA,
+    );
+    expect(err.httpStatus).toBe(422);
+  });
 });
 ```
 
@@ -156,9 +172,10 @@ describe("export-audit", () => {
 // PDF Audit Export Sample
 //
 // A write handler turns tenant data into a PDF and keeps it as a regular
-// FileRef: renderTablePdf draws the table (pure JS, no browser), then
-// createFileRefFromBytes stores the bytes through the same validation,
-// storage layout and fileRef.created event as an upload.
+// 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.
 
 import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
 import {
@@ -168,8 +185,13 @@ import {
   createSelectField,
   createTextField,
   defineFeature,
+  defineWriteHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { createFileRefFromBytes } from "@cosmicdrift/kumiko-framework/files";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  createFileRefFromUploadedBytes,
+  uploadFileBytesBeforeTransaction,
+} from "@cosmicdrift/kumiko-framework/files";
 import * as z from "zod";
 
 export const INSPECTION_RESULTS = ["ok", "defect"] as const;
@@ -199,7 +221,8 @@ function toFileNameSegment(text: string): string {
   return text.replaceAll(/[^A-Za-z0-9_-]+/g, "-");
 }
 
-const AUDIT_ROW_LIMIT = 200;
+// One row above the limit tells "exactly full" from "cut off"; entity lists cap at 200 rows.
+const AUDIT_ROW_LIMIT = 100;
 
 const access = { access: { roles: ["Admin", "User"] } } as const;
 
@@ -220,51 +243,64 @@ export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
   );
 
   r.writeHandler(
-    "export-audit",
-    z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
-    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 },
+    defineWriteHandler({
+      name: "export-audit",
+      schema: z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
+      access: access.access,
+      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) },
           ],
-          sort: "inspectedOn",
-          sortDirection: "asc",
-          limit: AUDIT_ROW_LIMIT,
-        },
-        event.user,
-        ctx.db,
-      );
-
-      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}",
-      });
-
-      const created = await createFileRefFromBytes(ctx, {
-        fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
-        mimeType: "application/pdf",
-        data: pdfBytes,
-      });
-      if (!created.isSuccess) return created;
-      return { isSuccess: true as const, data: { fileRefId: created.data.id } };
-    },
-    access,
+          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,
+        });
+      },
+      handler: async (event, ctx) => {
+        const created = await createFileRefFromUploadedBytes(ctx, event.prepared);
+        if (!created.isSuccess) return created;
+        return { isSuccess: true as const, data: { fileRefId: created.data.id } };
+      },
+    }),
   );
 });
 ```

package/agents/examples/session-revocation.md

@@ -67,7 +67,7 @@ const server = buildServer({
 // real HTTP + DB + Redis. If a reader copies the buildServer({...}) block
 // verbatim, the resulting app behaves like this test asserts.
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import {
   AuthHandlers,
   createAuthEmailPasswordFeature,
@@ -81,7 +81,6 @@ import {
 import {
   type SessionCallbacks,
   userSessionEntity,
-  userSessionTable,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import {
   sessionCallbacksFromLateBound,
@@ -97,9 +96,7 @@ import {
   createUserFeature,
   UserHandlers,
   userEntity,
-  userTable,
 } from "@cosmicdrift/kumiko-bundled-features/user";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -147,12 +144,6 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${userSessionTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
-});
-
 describe("session-revocation sample wiring", () => {
   test("end-to-end: login, use, logout, reject", async () => {
     const hash = await hashPassword("super-long-password");

package/agents/examples/tags-basic.md

@@ -130,18 +130,20 @@ import {
   tagAssignmentEntity,
   tagEntity,
 } from "@cosmicdrift/kumiko-bundled-features/tags";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
+  testTenantId,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { noteEntity, noteFeature } from "../feature";
 import { type TagClient, tagFlow } from "../usage";
 
-const admin = createTestUser({ roles: ["TenantAdmin"] });
+// Each test runs in its own tenant, so rows from other tests never show up.
+let admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(1) });
+let nextTenant = 1;
 
 // Adapt the test stack to the host-facing TagClient the docs embed uses.
 const tagClient: TagClient = {
@@ -164,11 +166,9 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_sample_tags_notes");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_tags");
-  await asRawClient(stack.db).unsafe("DELETE FROM read_tag_assignments");
+beforeEach(() => {
+  nextTenant += 1;
+  admin = createTestUser({ roles: ["TenantAdmin"], tenantId: testTenantId(nextTenant) });
 });
 
 async function createNote(id: string, title: string) {

package/agents/examples/user-data-rights.md

@@ -144,7 +144,7 @@ import {
   runForgetCleanup,
   runUserExport,
 } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
-import { asRawClient, insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -157,9 +157,13 @@ import { noteEntity, notesFeature, notesTable } from "../feature";
 
 let stack: TestStack;
 
-const TENANT_A = "00000000-0000-4000-8000-00000000000a";
 const TENANT_SYSTEM = "00000000-0000-4000-8000-000000000001";
-const ALICE_ID = "11111111-1111-4111-8111-000000000001";
+
+// Each test gets its own tenant and user, so rows from other tests never show up.
+let testNumber = 0;
+let TENANT_A = "";
+let ALICE_ID = "";
+let ALICE_EMAIL = "";
 
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 const NOW = (): Instant => getTemporal().Now.instant();
@@ -204,17 +208,23 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(`DELETE FROM store_notes`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
-  await asRawClient(stack.db).unsafe(`DELETE FROM read_tenant_memberships`);
+beforeEach(() => {
+  testNumber += 1;
+  const suffix = String(testNumber).padStart(12, "0");
+  TENANT_A = `00000000-0000-4000-8000-${suffix}`;
+  ALICE_ID = `11111111-1111-4111-8111-${suffix}`;
+  ALICE_EMAIL = `alice-${testNumber}@recipe.test`;
 });
 
+function noteId(index: number): string {
+  return `aaaaaaaa-aaaa-4aaa-8aaa-${String(testNumber * 10 + index).padStart(12, "0")}`;
+}
+
 async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {}): Promise<void> {
   await seedRow(stack.db, userTable, {
     id: ALICE_ID,
     tenantId: TENANT_SYSTEM,
-    email: "alice@recipe.test",
+    email: ALICE_EMAIL,
     passwordHash: "h",
     displayName: "Alice",
     locale: "de",
@@ -246,8 +256,8 @@ async function seedNote(id: string, title: string): Promise<void> {
 describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domain", () => {
   test("Export-Bundle enthaelt Note-Snippet via Hook", async () => {
     await seedAlice();
-    await seedNote("aaaaaaaa-aaaa-4aaa-8aaa-000000000001", "first");
-    await seedNote("aaaaaaaa-aaaa-4aaa-8aaa-000000000002", "second");
+    await seedNote(noteId(1), "first");
+    await seedNote(noteId(2), "second");
 
     const bundle = await runUserExport({
       db: stack.db,
@@ -267,7 +277,7 @@ describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domai
 
   test("Forget-Cron strategy=delete entfernt Notes (Default-Pfad)", async () => {
     await seedAlice({ status: USER_STATUS.DeletionRequested, gracePeriodEnd: PAST() });
-    await seedNote("aaaaaaaa-aaaa-4aaa-8aaa-000000000003", "to-delete");
+    await seedNote(noteId(1), "to-delete");
 
     const result = await runForgetCleanup({
       db: stack.db,
@@ -276,13 +286,13 @@ describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domai
     });
     expect(result.processedUserIds).toContain(ALICE_ID);
 
-    const remaining = await asRawClient(stack.db).unsafe(`SELECT id FROM store_notes`);
+    const remaining = await selectMany(stack.db, notesTable, { tenantId: TENANT_A });
     expect(remaining.length).toBe(0);
   });
 
   test("Strategy=anonymize: authorId=null, Row bleibt (HR-Compliance-Pfad)", async () => {
     await seedAlice();
-    await seedNote("aaaaaaaa-aaaa-4aaa-8aaa-000000000004", "stays-anonymous");
+    await seedNote(noteId(1), "stays-anonymous");
 
     const usage = stack.registry
       .getExtensionUsages(EXT_USER_DATA)
@@ -297,11 +307,9 @@ describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domai
       | undefined;
     await hooks?.delete?.({ db: stack.db, tenantId: TENANT_A, userId: ALICE_ID }, "anonymize");
 
-    const after = (await asRawClient(stack.db).unsafe(
-      `SELECT title, author_id FROM store_notes`,
-    )) as Array<{ title: string; author_id: string | null }>;
+    const after = await selectMany(stack.db, notesTable, { tenantId: TENANT_A });
     expect(after).toHaveLength(1);
-    expect(after[0]?.author_id).toBeNull();
+    expect(after[0]?.authorId).toBeNull();
     expect(after[0]?.title).toBe("stays-anonymous");
   });
 });

package/agents/examples/workflow-engine.md

@@ -983,7 +983,7 @@ export function startCronScheduler(
 
 ```ts
 import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectExpiredSuspensionEvents(
   db: DbRunner,
@@ -993,7 +993,7 @@ export async function selectExpiredSuspensionEvents(
     `SELECT * FROM "kumiko_events"
        WHERE "type" = ANY($1::text[])
        AND (("payload"->>'wakeAt')::timestamptz < now() OR ("payload"->>'timeoutAt')::timestamptz < now())`,
-    [eventTypes as unknown as string[]],
+    [toPostgresArrayLiteral(eventTypes)],
   )) as Record<string, unknown>[];
 }
 ```

package/agents/examples.md

@@ -23,6 +23,7 @@
 | `currencies-per-tenant` | Tenant-scoped money fields. Commas matter. | `examples/currencies-per-tenant.md` |
 | `custom-fields-basic` | Tenant-defined extra fields on an entity without writing migrations. | `examples/custom-fields-basic.md` |
 | `custom-handlers` | Beyond CRUD — when your domain refuses to fit a table. | `examples/custom-handlers.md` |
+| `dashboard-stats` | Key figures on a dashboard: stat panels backed by one counting query. | `examples/dashboard-stats.md` |
 | `delivery-notifications` | Delivery flows plus notifications. Package tracking, minus the tracking. | `examples/delivery-notifications.md` |
 | `designer-demo` | Kumiko sample feature — scaffolded by `bun kumiko create` | `examples/designer-demo.md` |
 | `e2e-generator` | generateE2ESpec + withBootValidatorFixture — Registry → JSON-Specs für externen Playwright-Worker. Zeigt die 4 Test-Kinds, Feldtyp→Interaktion-Mapping und welche Feldtypen heute noch nicht generisch unterstützt sind. | `examples/e2e-generator.md` |
@@ -46,7 +47,7 @@
 | `managed-pages` | Tenant-editable, server-rendered public pages with per-tenant branding + tier-gated sanitized custom CSS — managed-pages wired up with config + anonymousAccess. | `examples/managed-pages.md` |
 | `notes-history-basic` | Append-only note history — who wrote what, when — attached to any entity without changing it. | `examples/notes-history-basic.md` |
 | `ownership` | Entity- and Field-level Row-Ownership: from() helper, Straddle-safe multi-role checks, Field-level Read/Write filtering. | `examples/ownership.md` |
-| `pdf-audit-export` | Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and stores the bytes as a FileRef via createFileRefFromBytes. | `examples/pdf-audit-export.md` |
+| `pdf-audit-export` | Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and uploads the bytes before the transaction (uploadFileBytesBeforeTransaction) and stores them as a FileRef (createFileRefFromUploadedBytes). | `examples/pdf-audit-export.md` |
 | `pipeline-basics` | M.1 Tier-1 step-vocabulary showcase: every step in one inventory-management feature (aggregate.{create,update,appendEvent}, read.{findOne,findMany}, branch, forEach, compute, return, unsafeProjection{Upsert,Delete}). | `examples/pipeline-basics.md` |
 | `public-share-token` | Generic share-token entity: mint hash-stored token, anonymous read-by-token with IP rate-limit. | `examples/public-share-token.md` |
 | `rate-limiting` | End-to-end rate limiting: L1 global-IP + L2 auth-endpoints + L3 handler opt-in. | `examples/rate-limiting.md` |

package/agents/features.md

@@ -538,7 +538,7 @@ Requires: `template-resolver`
 
 ## renderer-mail-html
 
-A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, in-code `DEFAULT_MAIL_LAYOUT_MJML` as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
+A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
 
 Requires: `renderer-foundation`, `template-resolver`
 
@@ -552,7 +552,7 @@ Requires: `renderer-foundation`
 
 ## renderer-puppeteer-client
 
-A `renderer-foundation` plugin that prints documents to PDF through a separately deployed `puppeteer-service`. A `document-pdf` request names a stored template (`{ slug, locale, variables }`): the plugin resolves the template and its `pdf-layout` (header, signature and footer regions), embeds every image as a data URI, turns repeating table header rows into a real table head and sends the finished HTML to the service, which performs no network fetches itself. The page format, margins, file name pattern and title come from the template meta. A write handler renders with `renderPdfBeforeTransaction(ctx, { slug, locale, variables })` as its `beforeTransaction` phase, so the print service call holds no database connection, and stores the result with `storeRenderedPdf(ctx, event.prepared)` in the handler: a file plus a `rendered-pdf` record that keeps the template and layout version, so a stored document can always be traced to the text it was created from. The `puppeteer-status` query tells a TenantAdmin whether the service answers; while it does not, rendering fails with a `puppeteer_unavailable` error (HTTP 503) and no PDF is created. `image-snapshot` requests still take ready HTML in `payload.content`. Configure the endpoint and token with `PUPPETEER_SERVICE_URL` and `PUPPETEER_AUTH_TOKEN`; the client retries 5xx and network errors with exponential backoff (default 3 retries), 4xx fails at once. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.
+A `renderer-foundation` plugin that prints documents to PDF through a separately deployed `puppeteer-service`. A `document-pdf` request names a stored template (`{ slug, locale, variables }`): the plugin resolves the template and its `pdf-layout` (header, signature and footer regions), embeds every image as a data URI, turns repeating table header rows into a real table head and sends the finished HTML to the service, which performs no network fetches itself. The page format, margins, file name pattern and title come from the template meta. A write handler renders with `renderPdfBeforeTransaction(ctx, { slug, locale, variables })` as its `beforeTransaction` phase, so the print service call holds no database connection, and stores the result with `storeRenderedPdf(ctx, event.prepared)` in the handler: a file plus a `rendered-pdf` record that keeps the template and layout version, so a stored document can always be traced to the text it was created from. The `puppeteer-status` query tells a TenantAdmin whether the service answers; while it does not, rendering fails with a `puppeteer_unavailable` error (HTTP 503) and no PDF is created. `image-snapshot` requests still take ready HTML in `payload.content`, which must embed all resources as data: URIs because the service fetches no http(s) resources. Configure the endpoint and token with `PUPPETEER_SERVICE_URL` and `PUPPETEER_AUTH_TOKEN`; the client retries 5xx and network errors with exponential backoff (default 3 retries), 4xx fails at once. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.
 
 Requires: `renderer-foundation`
 
@@ -755,7 +755,7 @@ Requires: `user`, `auth-email-password`, `user-data-rights`, `user-data-rights-d
 
 ## waitlist
 
-Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response never reveals whether an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.
+Public waitlist: an anonymous, rate-limited `submit` handler collects name, email and optional company, portfolio and message (a honeypot field and per-email dedupe keep bots and repeat submits out, and the response body is identical whether or not an address was already listed), and mails the submitter a confirmation. SystemAdmins review entries in a list screen and invite or reject them; an invite creates the entrant's own tenant (or joins one shared tenant) and mails an accept link with the configured membership role, never a global role. Entries are platform-wide, their personal data is crypto-shredding-ready, and the EXT_USER_DATA hooks export and erase entries matching a user's email.
 
 Category: data
 

package/dist/api/auth-routes.d.ts

@@ -6,7 +6,6 @@ import { type AuthSessionChecker, type AuthSessionStatus, type TokenVerifier } f
 import { type ClientIpResolver } from "./client-ip.js";
 import type { JwtHelper } from "./jwt.js";
 import type { PostAuthLandingResolver } from "./post-auth-landing.js";
-export declare function assertRetiredCookieDomains(retiredCookieDomains: readonly string[] | undefined, cookieDomain: string | undefined): void;
 export type LoginRateLimiter = {
     check(key: string): Promise<boolean>;
     reset(key: string): Promise<void>;

package/dist/api/auth-routes.js

@@ -61,7 +61,7 @@ function normalizeCookieDomain(domain) {
 }
 // A malformed entry would corrupt the Set-Cookie header; an entry equal to the
 // current cookieDomain would make login delete the cookie it just sets.
-export function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
+function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
     const current = cookieDomain === undefined ? undefined : normalizeCookieDomain(cookieDomain);
     for (const entry of retiredCookieDomains ?? []) {
         if (entry === "" || normalizeCookieDomain(entry) === "") {
@@ -322,6 +322,10 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         retiredCookieDomains: config.retiredCookieDomains,
     });
     assertRetiredCookieDomains(config.retiredCookieDomains, cookieDomain);
+    if (config.mfaVerifyHandler && !config.switchTenantMfaGateHandler) {
+        throw new Error("createAuthRoutes: mfaVerifyHandler is set but switchTenantMfaGateHandler is not; " +
+            "POST /auth/switch-tenant would mint admin sessions without the second factor");
+    }
     const retiredCookieDomains = config.retiredCookieDomains ?? [];
     // Single hop-count-aware IP getter for every rate-limit call site below —
     // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
@@ -330,19 +334,45 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     // shared "unknown" bucket.
     const clientIpResolver = config.resolver ?? createClientIpResolver(config.trustedProxyHops ?? 0, "createAuthRoutes");
     const getClientIp = (c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
-    async function switchTenantMfaGateResponse(c, user, targetTenantId) {
+    // undefined = no gate wired (setup without MFA). "clearedRoles" are the roles the gate decided on,
+    // so the minted session cannot differ from what the gate checked.
+    async function switchTenantMfaGate(c, user, targetTenantId) {
         if (!config.switchTenantMfaGateHandler)
             return undefined;
         const gate = await dispatcher.write(config.switchTenantMfaGateHandler, { userId: user.id, tenantId: targetTenantId }, createSystemUser(user.tenantId));
         if (!gate.isSuccess) {
             const status = gate.error.httpStatus; // @cast-boundary engine-payload
-            return c.json({ isSuccess: false, error: gate.error }, status);
+            return { response: c.json({ isSuccess: false, error: gate.error }, status) };
         }
         // @cast-boundary engine-payload — the gate handler's three-shape result
         const gateData = gate.data;
         if (gateData.kind === "mfa-gate-clear")
-            return undefined;
-        return pendingMfaStepResponse(c, gateData);
+            return { clearedRoles: gateData.roles };
+        return { response: pendingMfaStepResponse(c, gateData) };
+    }
+    // Global roles (SystemAdmin etc.) come from the user feature when userQuery is wired, so they survive
+    // the tenant switch. buildSessionRoles calls stripForbiddenMembershipRoles on the membership side only — a backstop
+    // for a role a projection rebuild resurrected past command-time validation (engine/membership-roles).
+    async function resolveSwitchTenantRoles(user, membership) {
+        let globalRoles = [];
+        if (config.userQuery) {
+            try {
+                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
+                // Per the AuthUserRow contract, userQuery returns a row with a roles column.
+                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
+                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
+                // JSON-encoded text from pre-0.217.0 rows.
+                globalRoles = parseRoles(userRow?.roles ?? null);
+            }
+            catch (e) {
+                // Non-fatal: when global roles cannot be resolved the switch continues with tenant roles
+                // only. A server error carrying just the cause would hurt the UX more than a switch without
+                // SystemAdmin, which the user notices and reports.
+                if (!isUnknownHandlerError(e))
+                    throw e;
+            }
+        }
+        return buildSessionRoles(globalRoles, membership.roles);
     }
     // Shared tail of every route that ends a request logged-in: create the
     // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
@@ -711,13 +741,13 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             }
             // Session creation + JWT sign + cookies — see mintSessionAndRespond.
             const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "signup",
+            const signupOutcome = {
                 roles: data.session.roles,
                 tenantId: data.session.tenantId,
                 tenantKey: data.tenantKey,
                 ...(data.handover !== undefined && { handover: data.handover }),
-            });
+            };
+            const landingPath = landingPathFragment({ flow: "signup", ...signupOutcome });
             return c.json({
                 isSuccess: true,
                 token,
@@ -962,49 +992,20 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             return switchTenantRejectionResponse(c, activeMembership.reason);
         }
         const membership = activeMembership.membership;
-        // Globale Rollen aus user-feature lesen wenn userQuery wired —
-        // tenant-unabhängige Rollen (SystemAdmin etc.) überleben so den
-        // tenant-switch. `parseRoles` liegt utils-side, hier inline-deserialize
-        // damit das Framework keine bundled-features-Imports kriegt.
-        let globalRoles = [];
-        if (config.userQuery) {
-            try {
-                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
-                // userQuery liefert per AuthUserRow-Contract eine row mit roles-spalte.
-                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
-                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
-                // JSON-encoded text from pre-0.217.0 rows.
-                globalRoles = parseRoles(userRow?.roles ?? null);
-            }
-            catch (e) {
-                // Non-fatal: globale Rollen kann nicht aufgelöst werden → switch
-                // läuft weiter mit nur tenant-rollen. Server-error mit nur dem
-                // Cause ohne Stack hochwerfen wäre für die UX schlimmer als ein
-                // Tenant-Switch ohne SystemAdmin (User merkt's und meldet's). Log
-                // it via the dispatcher so Ops sieht's.
-                if (!isUnknownHandlerError(e))
-                    throw e;
-            }
-        }
+        const gate = await switchTenantMfaGate(c, user, targetTenantId);
+        if (gate !== undefined && "response" in gate)
+            return gate.response;
+        const sessionRoles = gate !== undefined ? gate.clearedRoles : await resolveSwitchTenantRoles(user, membership);
         // Issue new JWT with the target tenant and its roles. Claims MUST be
         // recomputed for the new tenant — stale claims from the previous
         // tenant would leak identity facts across tenancies (e.g. teamId from
         // tenant A accidentally surviving into tenant B's session). The
         // resolver runs each feature's r.authClaims() hook under the new
         // TenantDb scope.
-        // buildSessionRoles calls stripForbiddenMembershipRoles internally and
-        // strips reserved roles from the membership side only — globalRoles
-        // (where SystemAdmin legitimately lives) is never filtered. Backstop for a
-        // membership role that a projection rebuild resurrected past command-time
-        // validation (see engine/membership-roles).
-        const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
-        const pendingMfaStep = await switchTenantMfaGateResponse(c, user, targetTenantId);
-        if (pendingMfaStep !== undefined)
-            return pendingMfaStep;
         const targetSession = {
             id: user.id,
             tenantId: targetTenantId,
-            roles: mergedRoles,
+            roles: sessionRoles,
             // Tenant-independent prefs must survive the switch (fw#2343).
             ...tenantIndependentPrefs(user),
         };
@@ -1023,7 +1024,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         // fresh csrfToken is minted (inside the helper) so a compromised csrf-
         // value can't cross a tenant boundary.
         const newToken = await mintSessionAndRespond(c, sessionForJwt);
-        return c.json({ token: newToken, tenantId: targetTenantId, roles: mergedRoles });
+        return c.json({ token: newToken, tenantId: targetTenantId, roles: sessionRoles });
     });
     return api;
 }

package/dist/api/index.d.ts

@@ -26,7 +26,7 @@ export type { MetricsRouteOptions } from "./route-registrars.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export type { KumikoServer, ServerOptions } from "./server.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server.js";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
 export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker.js";

package/dist/api/index.js

@@ -15,7 +15,7 @@ export { readonlyRequestContext as requestContext, } from "./request-context.js"
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server.js";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";