@cosmicdrift/kumiko-framework 0.377.0 → 0.379.0

package/AGENTS.md

@@ -195,7 +195,10 @@ produces code that compiles and then fails in production.
 - Never `INSERT`, `UPDATE` or `DELETE` on an entity table or the events
   table, and never call a raw database client for it. Write through a
   handler: `r.crud`, the `defineEntity*Handler` helpers, the executor from
-  `createEntityExecutor`, or `emitEvent` / `ctx.appendEvent`.
+  `createEntityExecutor`, or `emitEvent` / `ctx.appendEvent`. The query
+  helpers and `ctx.db` throw `AccessDeniedError` on such a write, also
+  through `ctx.db.unsafeRaw()`. Test seeds use `seedRow` / `deleteRows` from
+  `@cosmicdrift/kumiko-testing`.
 - Never store a value that can be computed. Derive it in a query or a
   projection.
 - Never hand-write SQL for reads that an executor `list` or `detail` covers.

package/agents/examples/compose-stacks.md

@@ -26,8 +26,7 @@ the option.
   `securityBaselineFeatures()`.
 - **`composeGdprStack({ tenantLifecycle, selfService })`**: `data-retention`
   and `compliance-profiles`, optionally `tenant-lifecycle`. `selfService` adds
-  `sessions`, `user-data-rights` and `user-profile` (needs `mail`) and
-  replaces `dsgvoSelfServiceFeatures()`.
+  `sessions`, `user-data-rights` and `user-profile` (needs `mail`).
 - **`composeSaasStack({ billing, tiers, caps, waitlist })`**:
   `billing-foundation` and `tier-engine`, plus `cap-counter`/`cap-overview`
   and `waitlist` when configured. `billing: "stripe"` leaves

package/agents/examples/currencies-global.md

@@ -59,7 +59,7 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { currencyEntity, currencyTable } from "../entities/currency";
+import { currencyEntity } from "../entities/currency";
 import { invoiceEntity } from "../entities/invoice";
 import { tenantCurrencyEntity } from "../entities/tenant-currency";
 import { currenciesGlobalFeature } from "../feature";
@@ -84,8 +84,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, invoiceEntity);
 
   // Seed global currency table — same as r.referenceData() does at boot
-  const tables = new Map([["currency", currencyTable]]);
-  await seedReferenceData(currenciesGlobalFeature.referenceData, tables, stack.db);
+  await seedReferenceData(currenciesGlobalFeature.referenceData, stack.registry, stack.db);
 
   // --- Assign currencies to tenant 1: EUR, USD (standard) + BHD, XYZ (custom) ---
   for (const currencyCode of ["EUR", "USD", "BHD", "XYZ"]) {

package/agents/examples/delivery-notifications.md

@@ -16,7 +16,7 @@ Shows how a feature sends notifications to multiple channels (InApp + Email + Pu
 
 **Mail text is stored data:** The boot seed (`seedNotificationTemplates`) writes the declared `template` and `meta` into the template store as system templates. The email channel renders them with `renderer-mail-html`. A notification routed to email without `template` and `meta` fails its delivery.
 
-**Tenant override:** A tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`). The next mail for that tenant uses the override; the system text stays for everyone else.
+**Tenant override:** Only a SystemAdmin edits templates unless the app unlocks them. The app lists the mail in `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug, access: { roles: ["TenantAdmin"] } }] })`; then a tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`) and every other template is refused with 403. The next mail for that tenant uses the override; the system text stays for everyone else.
 
 **Sending:** The write handler calls `ctx.notify(type, { to, data })`. The `data` keys are the template variables; sending fails loudly when a required variable is missing.
 
@@ -137,7 +137,9 @@ const assignee = createTestUser({ id: 5, roles: ["Support"] });
 const features = [
   createConfigFeature(),
   createTenantFeature(),
-  createTemplateResolverFeature(),
+  createTemplateResolverFeature({
+    tenantEditable: [{ kind: "mail", slug: TICKET_ASSIGNED, access: { roles: ["TenantAdmin"] } }],
+  }),
   createRendererFoundationFeature(),
   createRendererMailHtmlFeature(),
   createDeliveryFeature(),
@@ -275,6 +277,27 @@ describe("delivery-notifications sample", () => {
     expect(email?.html).toContain("Tenant text: Printer on fire");
   });
 
+  test("a tenant admin may not override a mail the app did not list in tenantEditable", async () => {
+    const tenantAdmin = { ...admin, roles: ["TenantAdmin"] };
+
+    const error = await stack.http.writeErr(
+      TemplateResolverHandlers.upsertTenant,
+      {
+        slug: "support:notify:ticket-closed",
+        kind: "mail",
+        locale: "en",
+        content: "<p>Closed</p>",
+        contentFormat: "html",
+        meta: { subject: "Closed" },
+        variableSchema: {},
+      },
+      tenantAdmin,
+    );
+
+    expect(error.code).toBe("access_denied");
+    expect(error.i18nKey).toBe("templateResolver.errors.templateNotTenantEditable");
+  });
+
   test("ticket without assignee skips notification (recipient returns null)", async () => {
     emailTransport.sent.length = 0;
     pushTransport.sent.length = 0;

package/agents/examples/embedded.md

@@ -27,6 +27,14 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
   `createEmbeddedListField`; its renderer receives `embeddedListCells`, so no
   custom screen component is required.
 
+- **Derived head totals** (`src/screens/invoice-receive.screen.ts`): an
+  `actionForm` declares `derive` so net, VAT, and gross follow the lines
+  (`listSum`); the list requires at least one line (`minItems: 1`), so there
+  is no lineless input to cover. The head totals are not laid out; the lines footer shows Net, VAT, and Gross through labelled `totals`
+  entries (`{ label, from }`). The handler wraps its schema with
+  `withFormDerivations(schema, screen)` (`src/handlers/invoice-receive.write.ts`),
+  so totals sent by the client are replaced on the server.
+
 ## When to reach for it
 
 Use an embedded field or list when the nested data is created, changed, and
@@ -397,6 +405,64 @@ describe("invoice line items with select/reference/derived/totals metadata", ()
     expect(error).toBeDefined();
   });
 });
+
+// --- actionForm derive ---
+
+describe("invoice receive form derives its totals on the server", () => {
+  type ReceiveTotals = {
+    netTotal: { amount: number; currency: string };
+    vatTotal: { amount: number; currency: string };
+    grossTotal: { amount: number; currency: string };
+  };
+  const eur = (amount: number) => ({ amount, currency: "EUR" });
+  const head = { supplier: "Papier AG", invoiceNumber: "RE-2026-0042" };
+
+  test("with lines, manipulated client totals are replaced by the line sums", async () => {
+    const totals = await stack.http.writeOk<ReceiveTotals>(
+      "contacts:write:invoice:receive",
+      {
+        ...head,
+        lines: [
+          { description: "Paper", amount: 1005, vatRate: 19, vatAmount: 5 },
+          { description: "Toner", amount: 2000, vatRate: 7 },
+        ],
+        netTotal: eur(1),
+        vatTotal: eur(2),
+        grossTotal: eur(3),
+      },
+      admin,
+    );
+    expect(totals).toEqual({
+      netTotal: eur(30.05),
+      vatTotal: eur(3.31),
+      grossTotal: eur(33.36),
+    });
+  });
+
+  test("an invoice without lines is rejected, the totals have nothing to derive from", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:receive",
+      { ...head, lines: [], netTotal: eur(100), vatTotal: eur(0), grossTotal: eur(0) },
+      admin,
+    );
+    expect(error.code).toBe("validation_error");
+  });
+
+  test("a caller without the Admin role is rejected", async () => {
+    const error = await stack.http.writeErr(
+      "contacts:write:invoice:receive",
+      {
+        ...head,
+        lines: [{ description: "Paper", amount: 1005, vatRate: 19 }],
+        netTotal: eur(0),
+        vatTotal: eur(0),
+        grossTotal: eur(0),
+      },
+      viewer,
+    );
+    expect(error.code).toBe("access_denied");
+  });
+});
 ```
 
 ### src/entities/contact.ts
@@ -529,6 +595,9 @@ export const productTable = buildEntityTable("product", productEntity);
 //             on its `lines` sub-fields (Issue #1835), plus a declarative
 //             entityEdit screen that renders the list end-to-end via
 //             EmbeddedListField, no custom-screen code required
+//   invoice-receive — actionForm whose net/VAT/gross head fields are derived
+//             from the lines (`derive`); the handler recomputes them with
+//             `withFormDerivations`, so client-sent totals are never trusted
 
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { contactEntity } from "./entities/contact";
@@ -536,6 +605,8 @@ import { invoiceEntity } from "./entities/invoice";
 import { productEntity } from "./entities/product";
 import { contactCreate } from "./handlers/contact-create.write";
 import { contactDetail } from "./handlers/contact-detail.query";
+import { invoiceReceive } from "./handlers/invoice-receive.write";
+import { invoiceReceiveScreen } from "./screens/invoice-receive.screen";
 
 export { contactEntity } from "./entities/contact";
 export { invoiceEntity } from "./entities/invoice";
@@ -557,6 +628,7 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
 
   r.writeHandler(contactCreate);
   r.queryHandler(contactDetail);
+  r.writeHandler(invoiceReceive);
 
   r.crud("product", productEntity, { write: adminWrite, read: openRead });
   r.crud("invoice", invoiceEntity, { write: adminWrite, read: openRead });
@@ -569,6 +641,8 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
       sections: [{ columns: 1, fields: ["customer", "lines"] }],
     },
   });
+
+  r.screen(invoiceReceiveScreen);
 });
 ```
 
@@ -646,3 +720,106 @@ export const contactDetail = defineQueryHandler({
   },
 });
 ```
+
+### src/handlers/invoice-receive.write.ts
+
+```ts
+import {
+  defineWriteHandler,
+  fieldToZod,
+  withFormDerivations,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { invoiceReceiveLines, invoiceReceiveScreen } from "../screens/invoice-receive.screen";
+
+const moneyPayload = z.object({ amount: z.number(), currency: z.string().min(1) });
+
+// The preprocess recomputes net/VAT/gross before validation: totals sent by the
+// client never reach the handler.
+const receiveInput = withFormDerivations(
+  z.object({
+    supplier: z.string().min(1),
+    invoiceNumber: z.string().min(1),
+    lines: fieldToZod(invoiceReceiveLines, ["EUR"]),
+    netTotal: moneyPayload,
+    vatTotal: moneyPayload,
+    grossTotal: moneyPayload,
+  }),
+  invoiceReceiveScreen,
+);
+
+export const invoiceReceive = defineWriteHandler({
+  name: "invoice:receive",
+  schema: receiveInput,
+  access: { roles: ["Admin"] },
+  handler: async (event) => ({
+    isSuccess: true,
+    data: {
+      netTotal: event.payload.netTotal,
+      vatTotal: event.payload.vatTotal,
+      grossTotal: event.payload.grossTotal,
+    },
+  }),
+});
+```
+
+### src/screens/invoice-receive.screen.ts
+
+```ts
+import {
+  type ActionFormScreenDefinition,
+  createEmbeddedListField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+const euro = { kind: "literal", code: "EUR" } as const;
+
+export const invoiceReceiveLines = createEmbeddedListField(
+  {
+    description: { type: "text", required: true },
+    amount: { type: "money", required: true },
+    vatRate: { type: "decimal", scale: 2, required: true },
+    vatAmount: { type: "money" },
+  },
+  {
+    minItems: 1,
+    derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
+    totals: [
+      { label: "invoice.total.net", from: ["amount"] },
+      { label: "invoice.total.vat", from: ["vatAmount"] },
+      { label: "invoice.total.gross", from: ["amount", "vatAmount"] },
+    ],
+  },
+);
+
+// Net/VAT/gross are derived on the server from the lines (at least one is required)
+// and shown only in the list footer, so the head totals are declared but not laid out.
+export const invoiceReceiveScreen: ActionFormScreenDefinition = {
+  id: "invoice-receive",
+  type: "actionForm",
+  handler: "contacts:write:invoice:receive",
+  fields: {
+    supplier: createTextField({ required: true, personal: "tenant", find: "none" }),
+    invoiceNumber: createTextField({
+      required: true,
+      personal: false,
+      reason: "is_business_data",
+    }),
+    lines: invoiceReceiveLines,
+    netTotal: { type: "money", currency: euro },
+    vatTotal: { type: "money", currency: euro },
+    grossTotal: { type: "money", currency: euro },
+  },
+  derive: {
+    netTotal: { op: "listSum", list: "lines", cell: "amount" },
+    vatTotal: { op: "listSum", list: "lines", cell: "vatAmount" },
+    grossTotal: { op: "sum", from: ["netTotal", "vatTotal"] },
+  },
+  layout: {
+    sections: [
+      { columns: 2, fields: ["supplier", "invoiceNumber"] },
+      { columns: 1, fields: ["lines"] },
+    ],
+  },
+};
+```

package/agents/examples/event-sourcing.md

@@ -97,7 +97,7 @@ Six integration tests pin everything at once:
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import type { DbTx } from "@cosmicdrift/kumiko-framework/db";
-import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   append,
   loadAggregate as loadAggregateRaw,
@@ -107,6 +107,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/event-store";
 import { getAllProjectionProgress } from "@cosmicdrift/kumiko-framework/pipeline";
 import { createTestUser } from "@cosmicdrift/kumiko-framework/seeding";
+import { seedRow } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   resetEventStore,
   setupTestStack,
@@ -270,7 +271,7 @@ describe("Event Sourcing Showcase", () => {
     // on disk today — the upcaster walks them to v2 on read.
     const invoiceId = "00000000-0000-4000-8000-00000000f001";
     await stack.db.begin(async (tx: DbTx) => {
-      await insertOne(tx, invoiceDetailTable, {
+      await seedRow(tx, invoiceDetailTable, {
         invoiceId,
         tenantId: admin.tenantId,
         customer: "Legacy Co",
@@ -388,7 +389,7 @@ describe("Event Sourcing Showcase", () => {
     // Seed only v1-shaped events directly to prove upcasting walks delta.
     const invoiceId = "00000000-0000-4000-8000-00000000f002";
     await stack.db.begin(async (tx: DbTx) => {
-      await insertOne(tx, invoiceDetailTable, {
+      await seedRow(tx, invoiceDetailTable, {
         invoiceId,
         tenantId: admin.tenantId,
         customer: "Upcast Co",
@@ -528,7 +529,7 @@ describe("Event Sourcing Showcase", () => {
 
   test("async upcaster: invoice-acknowledged v1 enriches via directory DB lookup at read time", async () => {
     // Seed the directory so the async upcaster can find a name.
-    await insertOne(stack.db, approverDirectoryTable, {
+    await seedRow(stack.db, approverDirectoryTable, {
       approverId: "u-42",
       displayName: "Quincy Acknowledger",
     });
@@ -539,7 +540,7 @@ describe("Event Sourcing Showcase", () => {
     // shape via the raw event-store.
     const invoiceId = "00000000-0000-4000-8000-00000000ac01";
     await stack.db.begin(async (tx: DbTx) => {
-      await insertOne(tx, invoiceDetailTable, {
+      await seedRow(tx, invoiceDetailTable, {
         invoiceId,
         tenantId: admin.tenantId,
         customer: "AckCo",

package/agents/examples/legal-pages.md

@@ -81,7 +81,7 @@ await runProdApp({
   anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
   // Required (2): boot check + internal lookup use ctx.templateResolver
   extraContext: ({ db }) => ({
-    templateResolver: createTemplateResolverApi(db),
+    templateResolver: createTemplateResolverApi(db, registry),
   }),
 });
 ```
@@ -215,7 +215,7 @@ from SYSTEM_TENANT:
 | Symptom | Cause | Fix |
 |---|---|---|
 | Route returns `503 legal page unavailable` | `anonymousAccess` not configured in `runProdApp` | Set `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` |
-| Boot check throws `ctx.templateResolver missing` | `extraContext.templateResolver` not wired | Set `extraContext: ({ db }) => ({ templateResolver: createTemplateResolverApi(db) })` |
+| Boot check throws `ctx.templateResolver missing` | `extraContext.templateResolver` not wired | Set `extraContext: ({ db, registry }) => ({ templateResolver: createTemplateResolverApi(db, registry) })` |
 | Route returns `404 not configured` | Required block doesn't exist or has `content=null` | `seedTextBlock` with a content string |
 | Multi-tenant app: tenant subdomain shows an empty page | (Bug regression?) Routes should ALWAYS show SYSTEM_TENANT texts | The `legal-pages.integration.test.ts` test "SYSTEM_TENANT routing" covers this — should be green |
 | `<script>` tags in a Markdown body land 1:1 in the HTML | Deliberately accepted right now — see [legal-pages/README.md XSS section](../../../packages/bundled-features/src/legal-pages/README.md#xss--currently-not-secured-by-design) | DOMPurify is a Phase 2 once a multi-author setup arrives |
@@ -259,8 +259,8 @@ beforeAll(async () => {
   stack = await setupTestStack({
     features: [templateResolverFeature, legalPagesFeature],
     anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
-    extraContext: ({ db }) => ({
-      templateResolver: createTemplateResolverApi(db),
+    extraContext: ({ db, registry }) => ({
+      templateResolver: createTemplateResolverApi(db, registry),
     }),
   });
   db = stack.db;
@@ -407,7 +407,7 @@ describe("legal-pages sample", () => {
 //  - `anonymousAccess` muss in runProdApp/runDevApp konfiguriert sein
 //    (defaultTenantId = SYSTEM_TENANT_ID), sonst antworten die
 //    legal-pages-Routes mit 503
-//  - `extraContext.templateResolver = createTemplateResolverApi(db)` muss
+//  - `extraContext.templateResolver = createTemplateResolverApi(db, registry)` muss
 //    gewired sein, sonst wirft der Boot-Check mit Wiring-Hinweis
 //  - Beim ersten Boot müssen die TextBlocks geseedet sein —
 //    template-resolver/seeding `seedTextBlock` oder via API

package/agents/examples/reference-data.md

@@ -40,33 +40,35 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 
 import { seedReferenceData, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import type { ReferenceDataDef } from "@cosmicdrift/kumiko-framework/engine";
-import { createTestDb, type TestDb, unsafePushTables } from "@cosmicdrift/kumiko-testing/stack";
-import { categoryFeature, categoryTable } from "../feature";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-testing/stack";
+import { categoryEntity, categoryFeature, categoryTable } from "../feature";
 
-let testDb: TestDb;
+let stack: TestStack;
 
 beforeAll(async () => {
-  testDb = await createTestDb();
-  await unsafePushTables(testDb.db, { categoryTable });
+  stack = await setupTestStack({ features: [categoryFeature] });
+  await unsafeCreateEntityTable(stack.db, categoryEntity, "category");
 });
 
 afterAll(async () => {
-  await testDb?.cleanup();
+  await stack?.cleanup();
 });
 
 type CategoryRow = { code: string; name: string; description: string | null };
 
 async function readCategories(): Promise<CategoryRow[]> {
-  const rows = await selectMany(testDb.db, categoryTable);
+  const rows = await selectMany(stack.db, categoryTable);
   return [...rows].sort((a: CategoryRow, b: CategoryRow) => a.code.localeCompare(b.code));
 }
 
 describe("reference data seeding", () => {
   test("inserts initial seed data", async () => {
-    const tables = new Map([["category", categoryTable]]);
-
-    // seedReferenceData(defs, tables, db)
-    await seedReferenceData(categoryFeature.referenceData, tables, testDb.db);
+    await seedReferenceData(categoryFeature.referenceData, stack.registry, stack.db);
 
     const rows = await readCategories();
     expect(rows).toHaveLength(4);
@@ -77,8 +79,6 @@ describe("reference data seeding", () => {
   });
 
   test("upsert updates existing rows without duplicating", async () => {
-    const tables = new Map([["category", categoryTable]]);
-
     // Modified seed data: changed name for "books", added new category
     const updatedDefs: ReferenceDataDef[] = [
       {
@@ -94,7 +94,7 @@ describe("reference data seeding", () => {
       },
     ];
 
-    await seedReferenceData(updatedDefs, tables, testDb.db);
+    await seedReferenceData(updatedDefs, stack.registry, stack.db);
 
     const rows = await readCategories();
     expect(rows).toHaveLength(5);
@@ -104,6 +104,15 @@ describe("reference data seeding", () => {
 
     const sports = rows.find((r: CategoryRow) => r.code === "sports");
     expect(sports?.name).toBe("Sports");
+
+    // Seeded rows are event-sourced: a projection rebuild keeps them.
+    await rebuildProjection("catalog:projection:category-entity", {
+      db: stack.db,
+      registry: stack.registry,
+    });
+    const rebuilt = await readCategories();
+    expect(rebuilt).toHaveLength(5);
+    expect(rebuilt.find((r: CategoryRow) => r.code === "books")?.name).toBe("Books & Media");
   });
 });
 ```
@@ -114,7 +123,7 @@ describe("reference data seeding", () => {
 // Reference Data Sample
 // Shows: r.referenceData() for static seed data with upsert logic
 
-import { table, text } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 export const categoryEntity = createEntity({
@@ -126,12 +135,8 @@ export const categoryEntity = createEntity({
   },
 });
 
-// Drizzle table for direct DB queries in tests
-export const categoryTable = table("read_sample_categories", {
-  code: text("code").notNull(),
-  name: text("name").notNull(),
-  description: text("description"),
-});
+// Read-model table for direct DB queries in tests
+export const categoryTable = buildEntityTable("category", categoryEntity);
 
 export const categoryFeature = defineFeature("catalog", (r) => {
   r.entity({ name: "category", ...categoryEntity });

package/agents/examples/relations.md

@@ -37,6 +37,7 @@ bun test
 // Proves: hasMany relations, cascade delete, restrict delete
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { createCascadeDeleteHook } from "@cosmicdrift/kumiko-framework/pipeline";
@@ -177,7 +178,7 @@ describe("cascade: deleting member removes tasks", () => {
         entityName: "member",
         event: createTestStoredEvent(),
       },
-      { db: stack.db },
+      { db: createTenantDb({ db: stack.db, tenantId: admin.tenantId }) },
     );
 
     // Tasks should be gone

package/agents/features.md

@@ -10,7 +10,7 @@ Requires: `sessions`, `auth-mfa`
 
 ## admin-shell
 
-Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.
+Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.
 
 Category: operations
 
@@ -24,7 +24,7 @@ Category: ai
 
 ## audit
 
-Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: "system"` to read the app-instance system events such as `app.started`. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).
+Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: "system"` to read the app-instance system events such as `app.started`, and reads the events of every tenant (system tenant excluded) through `audit:query:list-all-tenants` and the `audit-log-all-tenants` screen. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).
 
 Category: compliance
 
@@ -228,7 +228,7 @@ Requires: `file-derivatives`
 
 ## document-designer
 
-Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`.
+Template overview and layout editor: lists the mail, PDF and layout templates of a tenant (platform admins see the system templates and how many tenants customised each) and edits the mail layout and the PDF letterhead in the browser. Mount after template-resolver and, for the branding rail, managed-pages. Client: `documentDesignerClient()`; admin-shell lists the navs with `includeDocumentDesigner`. The tenant overview and the editors are for SystemAdmin only; the `access` option adds roles (normally `templateEditAccess(tenantEditable)` of the template-resolver mount), and the server still enforces per template which of them may save.
 
 Category: content
 
@@ -564,7 +564,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`, 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.
+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 502, 503 and network errors with exponential backoff (default 3 retries); 4xx, other 5xx and client timeouts fail at once, because the render has already run. The feature adds the `rendered_pdfs` table, so apps that mount it need a schema migration.
 
 Requires: `renderer-foundation`
 
@@ -644,7 +644,7 @@ Category: data
 
 ## template-resolver
 
-Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`). Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away. Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation. How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning). A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side. `validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only. `preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10. Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.
+Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`). Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away. Editing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug: "status-update", access: { roles: ["TenantAdmin"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. The same list decides delivery: a tenant override is served (mail, PDF, layouts, text blocks) only while its template is listed in tenantEditable; otherwise the system version is served. A locked override stays stored, a SystemAdmin sees it in the overview marked as not delivered, and listing the template makes it effective again. Tenant rows of a collection mounted with `access` are always served. A collection mounted without `access` is SystemAdmin only. Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation. How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning). A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side. `validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only. `preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address. Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10. Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.
 
 Category: notifications
 

package/agents/widgets.md

@@ -55,6 +55,7 @@ Value exports of `@cosmicdrift/kumiko-renderer/web`.
 | `NavTree` |  |
 | `NumberField` | Zahlenfeld = Field + Input(kind:"number") in einem — nimmt der Screen die wiederholte id/name/value/onChange-Verdrahtung ab. |
 | `PageSection` |  |
+| `PdfPreview` |  |
 | `PercentField` |  |
 | `PhotoSlots` | Guided photo capture: one tile per requested shot in a two-column grid, each its own camera/gallery picker, filled tiles show the thumbnail. |
 | `PlainContentEditor` |  |

package/dist/api/entity-read-access.d.ts

@@ -0,0 +1,2 @@
+import type { AccessRule, Registry } from "../engine/types/index.ts";
+export declare function collectEntityReadAccess(registry: Registry): ReadonlyMap<string, readonly AccessRule[]>;

package/dist/api/entity-read-access.js

@@ -0,0 +1,27 @@
+// Access rules of the query handlers that let a role read an entity (the
+// handler's own entity or one it declares via liveEntities). A live signal
+// carries the id of every row of the entity, so a signed-in connection gets it
+// only when one of these rules grants its roles. An aggregate type without a
+// reading query has no entry and is never put on the tenant channel.
+function toKebabCase(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+export function collectEntityReadAccess(registry) {
+    const rulesByEntity = new Map();
+    for (const [handlerName, handler] of registry.getAllQueryHandlers()) {
+        const entities = new Set(handler.liveEntities ?? []);
+        const ownEntity = registry.getHandlerEntity(handlerName);
+        if (ownEntity !== undefined)
+            entities.add(ownEntity);
+        for (const entityName of entities) {
+            // Executors may write under the kebab-case form of the camelCase r.entity() name
+            // (document-extract for documentExtract); the signal carries that aggregate type.
+            for (const aggregateType of new Set([entityName, toKebabCase(entityName)])) {
+                const rules = rulesByEntity.get(aggregateType) ?? [];
+                rules.push(handler.access);
+                rulesByEntity.set(aggregateType, rules);
+            }
+        }
+    }
+    return rulesByEntity;
+}

package/dist/api/index.d.ts

@@ -1,3 +1,4 @@
+export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.ts";
 export type { SetTenantCookieOptions } from "./anonymous-cookie.ts";
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.ts";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.ts";

package/dist/api/index.js

@@ -1,3 +1,4 @@
+export { DEFAULT_GLOBAL_RATE_LIMIT } from "../rate-limit/middleware.js";
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.js";
 export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";