@cosmicdrift/kumiko-framework 0.378.0 → 0.380.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/embedded.md

@@ -29,11 +29,11 @@ object and an embedded list rendered by a declarative `entityEdit` screen.
 
 - **Derived head totals** (`src/screens/invoice-receive.screen.ts`): an
   `actionForm` declares `derive` so net, VAT, and gross follow the lines
-  (`listSum`), or follow a typed net and VAT rate while the list is empty
-  (`whenEmpty`, `percent`). The renderer shows them read-only and live; 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.
+  (`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
 
@@ -439,35 +439,25 @@ describe("invoice receive form derives its totals on the server", () => {
     });
   });
 
-  test("without lines, the typed net stays and VAT and gross are computed from the rate", async () => {
-    const totals = await stack.http.writeOk<ReceiveTotals>(
+  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), vatRate: 19, vatTotal: eur(0), grossTotal: eur(0) },
+      { ...head, lines: [], netTotal: eur(100), vatTotal: eur(0), grossTotal: eur(0) },
       admin,
     );
-    expect(totals).toEqual({ netTotal: eur(100), vatTotal: eur(19), grossTotal: eur(119) });
+    expect(error.code).toBe("validation_error");
   });
 
-  test("a stale gross total is overwritten", async () => {
-    const totals = await stack.http.writeOk<ReceiveTotals>(
+  test("a caller without the Admin role is rejected", async () => {
+    const error = await stack.http.writeErr(
       "contacts:write:invoice:receive",
       {
         ...head,
-        lines: [],
-        netTotal: eur(50),
-        vatRate: 20,
+        lines: [{ description: "Paper", amount: 1005, vatRate: 19 }],
+        netTotal: eur(0),
         vatTotal: eur(0),
-        grossTotal: eur(999),
+        grossTotal: eur(0),
       },
-      admin,
-    );
-    expect(totals.grossTotal).toEqual(eur(60));
-  });
-
-  test("a caller without the Admin role is rejected", async () => {
-    const error = await stack.http.writeErr(
-      "contacts:write:invoice:receive",
-      { ...head, lines: [], netTotal: eur(50), vatRate: 20, vatTotal: eur(0), grossTotal: eur(0) },
       viewer,
     );
     expect(error.code).toBe("access_denied");
@@ -752,7 +742,6 @@ const receiveInput = withFormDerivations(
     invoiceNumber: z.string().min(1),
     lines: fieldToZod(invoiceReceiveLines, ["EUR"]),
     netTotal: moneyPayload,
-    vatRate: z.number().optional(),
     vatTotal: moneyPayload,
     grossTotal: moneyPayload,
   }),
@@ -779,7 +768,6 @@ export const invoiceReceive = defineWriteHandler({
 ```ts
 import {
   type ActionFormScreenDefinition,
-  createDecimalField,
   createEmbeddedListField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -794,13 +782,18 @@ export const invoiceReceiveLines = createEmbeddedListField(
     vatAmount: { type: "money" },
   },
   {
+    minItems: 1,
     derived: { vatAmount: { op: "percent", from: ["amount", "vatRate"] } },
-    totals: ["amount", "vatAmount"],
+    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: with line items they are the sum of the lines,
-// without lines the net amount and the VAT rate are typed and VAT/gross follow.
+// 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",
@@ -814,25 +807,18 @@ export const invoiceReceiveScreen: ActionFormScreenDefinition = {
     }),
     lines: invoiceReceiveLines,
     netTotal: { type: "money", currency: euro },
-    vatRate: createDecimalField({ precision: 5, scale: 2 }),
     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",
-      whenEmpty: { op: "percent", from: ["netTotal", "vatRate"] },
-    },
+    vatTotal: { op: "listSum", list: "lines", cell: "vatAmount" },
     grossTotal: { op: "sum", from: ["netTotal", "vatTotal"] },
   },
   layout: {
     sections: [
       { columns: 2, fields: ["supplier", "invoiceNumber"] },
       { columns: 1, fields: ["lines"] },
-      { columns: 2, fields: ["netTotal", "vatRate", "vatTotal", "grossTotal"] },
     ],
   },
 };

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
 
@@ -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. 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. Reading and delivery do not depend on it: a tenant override that exists is 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`.
+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/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";

package/dist/api/server.js

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { ROLES } from "../auth/roles.js";
-import { createProjectingTenantDb } from "../db/tenant-db.js";
+import { createProjectingTenantDb, withExecutorManagedWrites } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { buildAppSchema } from "../engine/build-app-schema.js";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
@@ -35,6 +35,7 @@ import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.
 import { assertSessionCallbacksPaired, createAuthRoutes, } from "./auth-routes.js";
 import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
 import { csrfMiddleware } from "./csrf-middleware.js";
+import { collectEntityReadAccess } from "./entity-read-access.js";
 import { ExtraRouteEntries, ExtraRouteRejection, } from "./extra-route.js";
 import { computeStrongEtag, etagMatches } from "./http-cache.js";
 import { createJwtHelper } from "./jwt.js";
@@ -392,9 +393,10 @@ export function buildServer(options) {
             const mspFiles = fileProviderResolver
                 ? createTenantFileContext(fileProviderResolver, event.tenantId)
                 : undefined;
+            const mspDb = withExecutorManagedWrites(baseDb);
             const applyCtx = createMultiStreamApplyContext({
                 registry: options.registry,
-                db: baseDb,
+                db: mspDb,
                 tenantId: event.tenantId,
                 userId: event.metadata.userId,
                 ...(mspOwner && { callerFeature: mspOwner }),
@@ -410,7 +412,7 @@ export function buildServer(options) {
                     }),
                 }),
             });
-            await applyFn(event, baseDb, applyCtx);
+            await applyFn(event, mspDb, applyCtx);
             // Keep ctx reachable to satisfy the EventConsumerHandler signature.
             void ctx;
         },
@@ -480,6 +482,10 @@ export function buildServer(options) {
     if (options.metrics) {
         registerMetricsRoute(app, observability.meter, options.metrics);
     }
+    else if (process.env["NODE_ENV"] === "production") {
+        console.warn("[kumiko:boot] /metrics is off: no `metrics` option, so nothing is measured or scraped. " +
+            "Set PROMETHEUS_METRICS_TOKEN (min 32 chars) and spread resolveObservabilityWiring(token) into the server options.");
+    }
     app.use("/api/*", requestIdMiddleware({
         resolver: clientIpResolver,
         ...(options.errorDocs && { errorDocs: options.errorDocs }),
@@ -662,6 +668,7 @@ export function buildServer(options) {
     }));
     app.route("/api", createSseRoute(sseBroker, {
         anonymousLiveEntities: collectAnonymousLiveEntities(options.registry),
+        entityReadAccess: collectEntityReadAccess(options.registry),
     }));
     // GET /api/schema — the only way a client obtains the AppSchema. Behind
     // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user

package/dist/api/sse-route.d.ts

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import type { AccessRule } from "../engine/types/index.ts";
 import { type SseBroker } from "./sse-broker.ts";
 /**
  * Heartbeat-Cadence für SSE-Streams.
@@ -21,7 +22,11 @@ import { type SseBroker } from "./sse-broker.ts";
  * gegen versehentliches Hochsetzen.
  */
 export declare const SSE_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const SSE_STALLED_CLIENT_TIMEOUT_MS = 15000;
+export declare const SSE_MAX_PENDING_WRITES_PER_CLIENT = 10000;
 export type SseRouteOptions = {
     readonly anonymousLiveEntities: ReadonlySet<string>;
+    readonly entityReadAccess: ReadonlyMap<string, readonly AccessRule[]>;
+    readonly now?: () => number;
 };
 export declare function createSseRoute(broker: SseBroker, options: SseRouteOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;