@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

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/webhook-step.md

@@ -68,7 +68,7 @@ bun test
 ```ts
 // webhook-step integration test — drives r.step.webhook.send end-to-end:
 // handler appends step.dispatch-requested in TX, dispatcher subscription
-// drains after COMMIT and calls the (stubbed) fetch, follow-up
+// enqueues a delivery job after COMMIT, the job calls the (stubbed) fetch, follow-up
 // step.dispatched / step.dispatch-failed events land on the same stream.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
@@ -140,6 +140,7 @@ beforeAll(async () => {
   stack = await setupTestStack({
     features: [createStepDispatcherFeature(), createSecretsFeature(), webhookDemoFeature],
     systemHooks: [],
+    jobs: { consumerLane: "worker" },
     extraContext: ({ db, registry }) => ({
       secrets: createSecretsContext({ db, masterKeyProvider, registry }),
     }),
@@ -184,6 +185,7 @@ describe("webhook-step Sample", () => {
 
     // Drain dispatcher (MSP runs async via runOnce in test mode)
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [calledUrl, init] = fetchMock.mock.calls[0]!;
@@ -202,6 +204,7 @@ describe("webhook-step Sample", () => {
     expect(id).toMatch(/^[0-9a-f-]{36}$/);
 
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(mailMock).toHaveBeenCalledTimes(1);
     expect(mailMock).toHaveBeenCalledWith(
@@ -231,6 +234,7 @@ describe("webhook-step Sample", () => {
 
     // And the inner handler's webhook fired
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 
@@ -243,6 +247,7 @@ describe("webhook-step Sample", () => {
     expect(res.status).toBe(500);
 
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).not.toHaveBeenCalled();
     const rows = await selectMany(stack.db, incidentTable);
@@ -261,6 +266,7 @@ describe("access-denied — role-restricted handlers", () => {
     );
     expect(error.code).toBe("access_denied");
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
     expect(mailMock).not.toHaveBeenCalled();
   });
 
@@ -287,6 +293,7 @@ describe("access-denied — role-restricted handlers", () => {
     );
     expect(error.code).toBe("access_denied");
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
@@ -317,6 +324,7 @@ describe("incident:open-authenticated — tenant-owned webhook auth secret", ()
       adminB,
     );
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).toHaveBeenCalledTimes(1);
     const [, init] = fetchMock.mock.calls[0]!;
@@ -348,6 +356,7 @@ describe("incident:open-authenticated — tenant-owned webhook auth secret", ()
       adminA,
     );
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).not.toHaveBeenCalled();
 
@@ -378,6 +387,7 @@ describe("incident:open-authenticated — tenant-owned webhook auth secret", ()
       adminC,
     );
     await stack.eventDispatcher?.runOnce();
+    await stack.drainJobs();
 
     expect(fetchMock).not.toHaveBeenCalled();
     const failedEvents = await selectMany(stack.db, eventsTable, {

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`
 
@@ -594,7 +594,7 @@ Exposes APIs: `sessions.revokeAllForUser`
 
 ## step-dispatcher
 
-Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.
+Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. An `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event enqueues one `step-dispatcher:job:deliver` BullMQ job per dispatch (Redis carries only the stream id and tenant, never the request payload). The job performs the actual HTTP or mail delivery and appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream, so the outcome is recorded in the event log without a separate status table. Transient failures (network error, timeout, 5xx, 408, 429, any mail adapter failure) are retried 3 times with exponential backoff; the outcome is recorded after the final attempt and the payload key is erased only then. Permanent failures (invalid url, blocked host, other 4xx, unavailable auth secret) are recorded immediately. At most 2 deliveries per tenant run at once (`maxPerTenant` with `onLimit: "defer"`), so a slow receiver of one tenant does not delay other tenants. Requires a job runner (Redis) and a worker consuming the job's default `worker` lane; without a job runner the projection fails loudly. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across retries and redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.
 
 Category: infrastructure
 
@@ -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>;