@cosmicdrift/kumiko-samples 0.377.0 → 0.379.0

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -21,7 +21,7 @@
     },
     {
       "name": "admin-shell",
-      "description": "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()`.",
+      "description": "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()`.",
       "toggleableDefault": null,
       "requires": [
         "user",
@@ -69,7 +69,7 @@
     },
     {
       "name": "audit",
-      "description": "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).",
+      "description": "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).",
       "toggleableDefault": null,
       "requires": [
         "tenant",
@@ -795,7 +795,7 @@
     },
     {
       "name": "document-designer",
-      "description": "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`.",
+      "description": "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.",
       "toggleableDefault": null,
       "requires": [
         "template-resolver"
@@ -2209,7 +2209,7 @@
     },
     {
       "name": "renderer-puppeteer-client",
-      "description": "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.",
+      "description": "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.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation"
@@ -2602,7 +2602,7 @@
     },
     {
       "name": "template-resolver",
-      "description": "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`).\n\nReading 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.\n\nText 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.\n\nHow 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).\n\nA 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.\n\n`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.\n\n`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.\n\nImages 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.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
+      "description": "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`).\n\nReading 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.\n\nEditing 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.\n\nText 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.\n\nHow 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).\n\nA 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.\n\n`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.\n\n`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.\n\nImages 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.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],

package/samples/apps/use-all-bundled/scripts/check-coverage.ts

@@ -28,7 +28,7 @@ const FRAMEWORK_ROOT = resolve(ROOT, "..", "..", "..");
 const EXPECTED_HELD_BACK = new Set([
   "foundation-shared", // utilities (requireDefined/requireNonEmpty), kein feature
   "page-render", // shared HTML render/cache helpers (legal/managed-pages), kein defineFeature
-  "presets", // deprecated feature-bundle helpers (dsgvoSelfServiceFeatures, securityBaselineFeatures), kein defineFeature
+  "presets", // deprecated feature-bundle helpers (securityBaselineFeatures), kein defineFeature
 ]);
 
 // Sub-paths in bundled-features's package.json exports (./tenant/seeding,

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -34,7 +34,9 @@ export const devAppOptions = {
   htmlPath: "./public/index.html",
   watchDirs: ["./src", "../../../packages/*/src"],
   anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
-  extraContext: ({ db }) => ({ templateResolver: createTemplateResolverApi(db) }),
+  extraContext: ({ db, registry }) => ({
+    templateResolver: createTemplateResolverApi(db, registry),
+  }),
   seeds: [seedScreenshotData],
   auth: {
     admin: {

package/samples/recipes/compose-stacks/README.md

@@ -18,8 +18,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/samples/recipes/delivery-notifications/README.md

@@ -8,7 +8,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.
 

package/samples/recipes/embedded/README.md

@@ -19,6 +19,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

package/samples/recipes/embedded/src/feature.ts

@@ -15,6 +15,9 @@
 //             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";
@@ -22,6 +25,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";
@@ -43,6 +48,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 });
@@ -55,4 +61,6 @@ export const embeddedFeature = defineFeature("contacts", (r) => {
       sections: [{ columns: 1, fields: ["customer", "lines"] }],
     },
   });
+
+  r.screen(invoiceReceiveScreen);
 });

package/samples/recipes/embedded/src/handlers/invoice-receive.write.ts

@@ -0,0 +1,37 @@
+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,
+    },
+  }),
+});

package/samples/recipes/embedded/src/screens/invoice-receive.screen.ts

@@ -0,0 +1,56 @@
+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/samples/recipes/legal-pages/README.md

@@ -73,7 +73,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),
   }),
 });
 ```
@@ -207,7 +207,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 |

package/samples/recipes/legal-pages/src/feature.ts

@@ -27,7 +27,7 @@
 //  - `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/samples/recipes/reference-data/src/feature.ts

@@ -1,7 +1,7 @@
 // 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({
@@ -13,12 +13,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/packages/bundled-features/src/admin-shell/i18n.ts

@@ -1,54 +0,0 @@
-// @runtime client
-// Pure-Data i18n keys for admin-shell (server r.translations + client pivot).
-// Without these keys nav labels and workspace tabs render raw QNs in the shell.
-
-type LocalizedString = { readonly en: string };
-
-export const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>> = {
-  "screen:tenant-overview.title": { en: "Overview" },
-  "screen:platform-overview.title": { en: "Overview" },
-  "admin-shell.screen.tenant-overview.subtitle": {
-    en: "Activity, failed jobs and deliveries, quotas and open admin tasks of this tenant.",
-  },
-  "admin-shell.screen.platform-overview.subtitle": {
-    en: "Tenant, user, job and delivery health across the whole installation.",
-  },
-  "admin-shell:workspace.tenant": { en: "Administration" },
-  "admin-shell:workspace.platform": { en: "Platform" },
-  "admin-shell:nav.tenantOverview": { en: "Overview" },
-  "admin-shell:nav.platformOverview": { en: "Overview" },
-  "admin-shell:nav.tenants": { en: "Tenants" },
-  "admin-shell:nav.tierAdmin": { en: "Assign tier" },
-  "admin-shell:nav.myCaps": { en: "Plans & Caps" },
-  "admin-shell:nav.tenantCaps": { en: "Plans & Caps" },
-  "admin-shell:overview.kpi.activeTenants": { en: "Active tenants" },
-  "admin-shell:overview.kpi.activeUsers7d": { en: "Active users, 7 days" },
-  "admin-shell:overview.kpi.activeMembers7d": { en: "Active members, 7 days" },
-  "admin-shell:overview.kpi.failedJobs24h": { en: "Failed jobs, 24 h" },
-  "admin-shell:overview.kpi.failedDeliveries24h": { en: "Failed deliveries, 24 h" },
-  "admin-shell:overview.chart.jobRunsByStatus": { en: "Job runs by status" },
-  "admin-shell:overview.chart.deliveriesByChannel": { en: "Deliveries by channel" },
-  "admin-shell:overview.chart.auditWrites": { en: "Changes per day" },
-  "admin-shell:overview.chart.auditWritesSubtitle": { en: "Audit log, 14 days" },
-  "admin-shell:overview.list.recentFailures": { en: "Recent failures" },
-  "admin-shell:overview.list.recentFailuresEmpty": { en: "No failed jobs" },
-  "admin-shell:overview.list.quotas": { en: "Quotas" },
-  "admin-shell:overview.list.quotasEmpty": { en: "No quotas configured" },
-  "admin-shell:overview.col.job": { en: "Job" },
-  "admin-shell:overview.col.startedAt": { en: "Started" },
-  "admin-shell:overview.col.failedAt": { en: "Failed at" },
-  "admin-shell:overview.col.reason": { en: "Reason" },
-  "admin-shell:overview.col.quota": { en: "Quota" },
-  "admin-shell:overview.col.used": { en: "Used" },
-  "admin-shell:overview.col.limit": { en: "Limit" },
-  "admin-shell:overview.col.usage": { en: "Usage" },
-  "admin-shell:overview.range.24h": { en: "24 hours" },
-  "admin-shell:overview.range.7d": { en: "7 days" },
-  "admin-shell:overview.range.30d": { en: "30 days" },
-  "admin-shell:overview.scope.badge": { en: "All tenants" },
-  "admin-shell:overview.scope.notice": {
-    en: "You are viewing data of all tenants. Cross-tenant queries are recorded in the audit log.",
-  },
-  "admin-shell:overview.filter.tenant": { en: "Tenant" },
-  "admin-shell:overview.filter.allTenants": { en: "All tenants" },
-};

package/packages/bundled-features/src/audit/i18n.ts

@@ -1,25 +0,0 @@
-// @runtime client
-// Server + client i18n for audit (nav labels + audit-log/-detail screens).
-
-type LocalizedString = { readonly en: string };
-
-export const AUDIT_I18N: Readonly<Record<string, LocalizedString>> = {
-  "screen:audit-log.title": { en: "Audit log" },
-  "screen:audit-log-detail.title": { en: "Event" },
-  "audit.log.detail.subtitle": {
-    en: "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
-  },
-  "audit.errors.systemScopeRequiresSystemAdmin": {
-    en: "Only SystemAdmin may read system events.",
-  },
-  "audit:nav.auditLog": { en: "Audit" },
-  "audit.log.col.when": { en: "When" },
-  "audit.log.col.type": { en: "Event" },
-  "audit.log.col.aggregateType": { en: "Aggregate type" },
-  "audit.log.col.aggregateId": { en: "Aggregate ID" },
-  "audit.log.col.actor": { en: "Actor" },
-  "audit.log.details": { en: "Details" },
-  "audit.log.detail.payload": { en: "Event payload" },
-  "audit.log.detail.metadata": { en: "Metadata" },
-  "audit.log.detail.field.id": { en: "Event ID" },
-};

package/packages/bundled-features/src/auth-mfa/web/qrcode-browser.d.ts

@@ -1,11 +0,0 @@
-// @types/qrcode only declares the main "qrcode" entry, not the browser-only
-// subpath (see mfa-setup-preauth-screen.tsx's import — the main entry pulls
-// in Node-only deps like yargs/pngjs via qrcode's own package.json#browser
-// remap, which Metro doesn't honor). Same runtime shape, just re-typed.
-// `export *` never re-exports a default — `import QRCode from "..."`
-// resolving here relies on the consuming app's esModuleInterop/
-// allowSyntheticDefaultImports (which synthesizes a default from the
-// namespace); without it, the default import comes back undefined.
-declare module "qrcode/lib/browser.js" {
-  export * from "qrcode";
-}

package/packages/bundled-features/src/jobs/i18n.ts

@@ -1,55 +0,0 @@
-// @runtime client
-// Server + client i18n for jobs operator screens.
-
-type LocalizedString = { readonly en: string };
-
-export const JOBS_I18N: Readonly<Record<string, LocalizedString>> = {
-  "screen:job-runs.title": { en: "Job runs" },
-  "screen:job-run-detail.title": { en: "Job run" },
-  "screen:job-trigger.title": { en: "Trigger job" },
-  "jobs.screen.job-trigger.subtitle": {
-    en: "Start a job manually by name, with an optional JSON payload.",
-  },
-  "jobs.screen.job-run-detail.subtitle": {
-    en: "Status, timings, error and log lines of one job run.",
-  },
-  "jobs:entity:__action-form__:field:jobName": { en: "Job name" },
-  "jobs:entity:__action-form__:field:payload": { en: "JSON payload" },
-  "jobs:nav.jobRuns": { en: "Jobs" },
-  "jobs.runs.open": { en: "Details" },
-  "jobs.runs.filter.status": { en: "Status" },
-  "jobs.runs.filter.completed": { en: "Completed" },
-  "jobs.runs.filter.failed": { en: "Failed" },
-  "jobs.runs.filter.running": { en: "Running" },
-  "jobs.runs.filter.queued": { en: "Queued" },
-  "jobs.runs.col.job": { en: "Job" },
-  "jobs.runs.col.status": { en: "Status" },
-  "jobs.runs.col.started": { en: "Started" },
-  "jobs.runs.col.duration": { en: "Duration (ms)" },
-  "jobs.detail.field.job": { en: "Job" },
-  "jobs.detail.field.status": { en: "Status" },
-  "jobs.detail.field.id": { en: "Run ID" },
-  "jobs.detail.field.started": { en: "Started" },
-  "jobs.detail.field.finished": { en: "Finished" },
-  "jobs.detail.field.duration": { en: "Duration (ms)" },
-  "jobs.detail.field.error": { en: "Error" },
-  "jobs.detail.logs": { en: "Logs" },
-  "jobs.detail.retry": { en: "Retry" },
-  "jobs.trigger.title": { en: "Run a job" },
-  "jobs.errors.invalidCursor": { en: "The pagination cursor is invalid." },
-  "jobs.trigger.submit": { en: "Run" },
-  "jobs.errors.unknownJob": { en: "Unknown job." },
-  "jobs.errors.notManual": {
-    en: "This job cannot be triggered manually.",
-  },
-  "jobs.errors.invalidPayload": {
-    en: "The payload must be a valid JSON object.",
-  },
-  "jobs.errors.notFound": { en: "Not found." },
-  "jobs.errors.onlyFailedCanRetry": {
-    en: "Only failed runs can be retried.",
-  },
-  "jobs.errors.payloadErased": {
-    en: "This run's payload can no longer be read — the triggering user's data was erased.",
-  },
-};

package/packages/bundled-features/src/managed-pages/i18n.ts

@@ -1,63 +0,0 @@
-// @runtime client
-// Pure-Data (i18n-Keys) — client-marked, damit das web/-Bundle sie in den
-// Browser-Store pivotieren darf; feature.ts (server) importiert sie ebenso
-// (server darf client-safe Pure-Data importieren, wie PAT constants.ts).
-//
-// Übersetzungs-Bundle für die managed-pages Admin-Screens. Ohne diese Keys
-// rendert die UI die Roh-i18n-Keys (screen:*.title, entity:*:field:*, Section-
-// Header). Der Boot-Validator (required-surface-keys) verlangt — sobald ein
-// Feature r.translations ruft — den KOMPLETTEN Required-Surface-Satz in de+en;
-// diese Datei deckt jeden Screen/Feld/Section-Key ab, den managed-pages
-// registriert. Die zwei customCss-Keys werden unconditional geliefert (schaden
-// bei allowCustomCss:false nicht, sind aber Pflicht für Consumer die es aktivieren).
-
-type LocalizedString = { readonly en: string };
-
-export const MANAGED_PAGES_I18N: Readonly<Record<string, LocalizedString>> = {
-  // Screen-Titel (global/unpräfixiert — screenTitleKey = screen:<id>.title)
-  "screen:page-list.title": { en: "Pages" },
-  "screen:page-edit.title": { en: "Edit page" },
-  "screen:branding-settings.title": { en: "Branding" },
-
-  // Page-Entity Feld-Labels (managed-pages:entity:page:field:*)
-  "managed-pages:entity:page:field:slug": { en: "Slug" },
-  "managed-pages:entity:page:field:lang": { en: "Language" },
-  "managed-pages:entity:page:field:title": { en: "Title" },
-  "managed-pages:entity:page:field:published": { en: "Published" },
-  "managed-pages:entity:page:field:published:option:true": {
-    en: "Published",
-  },
-  "managed-pages:entity:page:field:published:option:false": { en: "Draft" },
-  "managed-pages:entity:page:field:description": { en: "Description" },
-  "managed-pages:entity:page:field:ogImage": { en: "OG image" },
-  "managed-pages:entity:page:field:body": { en: "Content" },
-
-  // Config-Edit Feld-Labels (managed-pages:entity:__config-edit__:field:*, camelCase Form-Keys)
-  "managed-pages:entity:__config-edit__:field:title": { en: "Site title" },
-  "managed-pages:entity:__config-edit__:field:description": {
-    en: "Description",
-  },
-  "managed-pages:entity:__config-edit__:field:siteUrl": { en: "Site URL" },
-  "managed-pages:entity:__config-edit__:field:accentColor": {
-    en: "Accent color",
-  },
-  "managed-pages:entity:__config-edit__:field:logoUrl": { en: "Logo URL" },
-  "managed-pages:entity:__config-edit__:field:logoFile": { en: "Logo file" },
-  "managed-pages:entity:__config-edit__:field:layoutPreset": { en: "Layout" },
-
-  // Section-Header
-  "managed-pages:section.meta": { en: "Metadata" },
-  "managed-pages:section.body": { en: "Content" },
-  "managed-pages:branding.section.identity": { en: "Identity" },
-
-  // Row-Actions + Confirm (pageListScreen)
-  "managed-pages:actions.edit": { en: "Edit" },
-  "managed-pages:actions.delete": { en: "Delete" },
-  "managed-pages:confirms.page-delete": {
-    en: "Delete this page?",
-  },
-
-  // Nur bei allowCustomCss:true im Screen — unconditional geliefert
-  "managed-pages:entity:__config-edit__:field:customCss": { en: "Custom CSS" },
-  "managed-pages:branding.section.custom-css": { en: "Custom CSS" },
-};

package/packages/bundled-features/src/presets/dsgvo-self-service.ts

@@ -1,35 +0,0 @@
-import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { createComplianceProfilesFeature } from "../compliance-profiles/index.ts";
-import { createDataRetentionFeature } from "../data-retention/index.ts";
-import { createSessionsFeature } from "../sessions/index.ts";
-import {
-  createUserDataRightsFeature,
-  type UserDataRightsOptions,
-} from "../user-data-rights/index.ts";
-import { createUserProfileFeature } from "../user-profile/index.ts";
-
-export type DsgvoSelfServiceOptions = {
-  /** Passed through to createUserDataRightsFeature — export/deletion mail
-   *  callbacks + Apex deletion HMAC. Default {} (no-op mail side). */
-  readonly userDataRights?: UserDataRightsOptions;
-};
-
-// DSGVO + account self-service chain every Kumiko SaaS app mounts (privacy
-// center, account deletion Art. 17, export Art. 20, sessions). Order is
-// load-bearing (require-order): user-data-rights needs data-retention +
-// compliance-profiles + sessions, user-profile needs user-data-rights. This
-// exact order used to be hand-copied into every app with an explainer
-// comment. text-content + legal-pages stay out deliberately — legal-pages
-// has an app-specific wrapLayout, text-content is a standalone foundation;
-// both are spread in by the app itself.
-/** @deprecated Removed in the next release. Use `composeGdprStack({ selfService: { userDataRights } })`
- *  from `@cosmicdrift/kumiko-dev-server/compose-stacks`. */
-export function dsgvoSelfServiceFeatures(opts: DsgvoSelfServiceOptions = {}): FeatureDefinition[] {
-  return [
-    createDataRetentionFeature(),
-    createComplianceProfilesFeature(),
-    createSessionsFeature(),
-    createUserDataRightsFeature(opts.userDataRights ?? {}),
-    createUserProfileFeature(),
-  ];
-}

package/packages/bundled-features/src/user-data-rights/i18n.ts

@@ -1,44 +0,0 @@
-// @runtime client
-// Server + client i18n for user-data-rights (operator screens + nav). Pure
-// data, importable from the web bundle (web/i18n.ts derives the client keys).
-type LocalizedString = { readonly en: string };
-
-export const USER_DATA_RIGHTS_I18N: Readonly<Record<string, LocalizedString>> = {
-  "user-data-rights:feature.label": { en: "Privacy" },
-  "user-data-rights:notify.export-ready.label": { en: "Data export ready" },
-  "user-data-rights:notify.export-failed.label": { en: "Data export failed" },
-  "user-data-rights:notify.deletion-requested.label": { en: "Deletion requested" },
-  "user-data-rights:notify.deletion-executed.label": { en: "Deletion completed" },
-  "user-data-rights:nav.exportJobs": { en: "GDPR exports" },
-  "screen:export-job-list.title": { en: "GDPR exports" },
-  "screen:export-job-detail.title": { en: "Export job" },
-  "screen:download-attempt-list.title": { en: "Download attempts" },
-  "screen:privacy-center.title": { en: "Privacy" },
-  "userDataRights.privacyCenter.subtitle": {
-    en: "Logged-in GDPR self-service page where a user requests and downloads a data export (Art. 20), restricts processing of their account (Art. 18) and requests its deletion (Art. 17).",
-  },
-  "user-data-rights:entity:export-job:field:userId": { en: "User" },
-  "user-data-rights:entity:export-job:field:status": { en: "Status" },
-  "user-data-rights:entity:export-job:field:requestedAt": { en: "Requested" },
-  "user-data-rights:entity:export-job:field:completedAt": { en: "Completed" },
-  "user-data-rights:entity:export-job:field:expiresAt": { en: "Expires" },
-  "user-data-rights:entity:export-job:field:requestedFromTenantId": {
-    en: "Tenant",
-  },
-  "user-data-rights:entity:export-job:field:startedAt": { en: "Started" },
-  "user-data-rights:entity:export-job:field:downloadStorageKey": {
-    en: "Storage key",
-  },
-  "user-data-rights:entity:export-job:field:bytesWritten": { en: "Bytes" },
-  "user-data-rights:entity:export-job:field:errorMessage": { en: "Error" },
-  "user-data-rights:entity:download-attempt:field:attemptedAt": {
-    en: "Attempted at",
-  },
-  "user-data-rights:entity:download-attempt:field:result": { en: "Result" },
-  "user-data-rights:entity:download-attempt:field:via": { en: "Via" },
-  "user-data-rights:entity:download-attempt:field:ip": { en: "IP" },
-  "user-data-rights:entity:download-attempt:field:attemptedByUserId": {
-    en: "User",
-  },
-  "user-data-rights:entity:download-attempt:field:jobId": { en: "Job" },
-};