@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/jobs/handlers/stale-run-sweep.job.ts

@@ -13,7 +13,10 @@ import { markStaleJobRunsFailed } from "../db/queries/stale-run-sweep.js";
 // Configurable per-app via JobsFeatureOptions.staleRunTimeoutHours.
 export const DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS = 24;
 
-export function createStaleRunSweepJob(timeoutHours: number): JobHandlerFn {
+export function createStaleRunSweepJob(
+  timeoutHours: number,
+  queuedRetentionDays: number,
+): JobHandlerFn {
   return async (_payload, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({
@@ -24,7 +27,7 @@ export function createStaleRunSweepJob(timeoutHours: number): JobHandlerFn {
     const db = ctx.systemDb.unsafeRaw(
       "stale-run sweep marks stuck runs of every tenant as failed",
     ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
-    const result = await markStaleJobRunsFailed(db, timeoutHours);
+    const result = await markStaleJobRunsFailed(db, timeoutHours, queuedRetentionDays);
     ctx.log?.info?.(`[jobs:stale-run-sweep] complete: ${JSON.stringify(result)}`);
   };
 }

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -19,6 +19,7 @@ import {
 import { acquireNamespacedAdvisoryLock, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import type {
+  JobDroppedMeta,
   JobLogEntry,
   JobMeta,
   JobOutcomeMeta,
@@ -169,6 +170,7 @@ async function encryptStartedPayload(
 const TENANT_JOB_FAILURE_LOCK_NAMESPACE = 0x746a666c;
 // 'tjrl': serialises the finished-row write + prune per tenant run key.
 const TENANT_JOB_RUN_LOCK_NAMESPACE = 0x746a726c;
+const TENANT_RUN_CONFLICT_KEYS = ["tenantId", "jobName", "bullJobId"] as const;
 
 // fw#3079 — which row the tenant-visible failure record lives in: one per
 // (tenant, job, subject), so the next outcome of the same work replaces or
@@ -227,8 +229,11 @@ async function clearTenantJobFailure(
 }
 
 // fw#3616 — tenant-visible run state. One row per BullMQ job in
-// store_tenant_job_runs; the writes below only ever touch rows of the same
-// bullJobId, except pruning older finished rows of the same key.
+// store_tenant_job_runs, addressed by (tenant, job name, bullJobId): BullMQ
+// ids are only unique per queue (api and worker lane both count from 1) and
+// restart after a Redis reset, so the id alone must never pick a row. The
+// writes below only touch rows of that triple, except pruning older finished
+// rows of the same key.
 type TenantRunKey = {
   readonly tenantId: string;
   readonly jobName: string;
@@ -255,14 +260,27 @@ async function recordTenantRunQueued(
   // skip: system-tenant run, no tenant-scoped query reads it
   if (!key) return;
   const now = Temporal.Now.instant();
-  // DO NOTHING: a fast worker can report the start before this enqueue hook
-  // returns, and a repeated jobId (debounce, fan-out dedup) is the same job.
-  await insertOnConflictDoNothing(
-    db,
-    tenantJobRunsTable,
-    { ...key, bullJobId, status: "queued", queuedAt: now, updatedAt: now },
-    { conflictKeys: ["bullJobId"] },
-  );
+  await transaction(db, async (tx) => {
+    // A finished row under the same id is left over from before a Redis reset
+    // (ids restart at 1), not this job. Only rows that went through this hook
+    // (queuedAt set) qualify: a fast worker can finish before the hook runs,
+    // and that row is this job's own and must stay.
+    await deleteMany(tx, tenantJobRunsTable, {
+      tenantId: key.tenantId,
+      jobName,
+      bullJobId,
+      status: { in: ["completed", "failed"] },
+      queuedAt: { gt: Temporal.Instant.fromEpochMilliseconds(0) },
+    });
+    // DO NOTHING: a fast worker can report the start before this enqueue hook
+    // returns, and a repeated jobId (debounce, fan-out dedup) is the same job.
+    await insertOnConflictDoNothing(
+      tx,
+      tenantJobRunsTable,
+      { ...key, bullJobId, status: "queued", queuedAt: now, updatedAt: now },
+      { conflictKeys: [...TENANT_RUN_CONFLICT_KEYS] },
+    );
+  });
 }
 
 async function recordTenantRunStarted(
@@ -282,7 +300,7 @@ async function recordTenantRunStarted(
     tenantJobRunsTable,
     { ...key, bullJobId, status: "running", startedAt: now, updatedAt: now },
     {
-      conflictKeys: ["bullJobId"],
+      conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
       update: { status: "running", startedAt: now, finishedAt: null, updatedAt: now },
     },
   );
@@ -308,7 +326,7 @@ async function recordTenantRunOutcome(
       db,
       tenantJobRunsTable,
       { status: "queued", startedAt: null, finishedAt: null, updatedAt: now },
-      { bullJobId },
+      { tenantId: key.tenantId, jobName, bullJobId },
     );
     // skip: retry pending, the row stays active until the final attempt
     return;
@@ -327,7 +345,10 @@ async function recordTenantRunOutcome(
       tx,
       tenantJobRunsTable,
       { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
-      { conflictKeys: ["bullJobId"], update: { status: result, finishedAt: now, updatedAt: now } },
+      {
+        conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
+        update: { status: result, finishedAt: now, updatedAt: now },
+      },
     );
     await deleteMany(tx, tenantJobRunsTable, {
       ...key,
@@ -337,8 +358,18 @@ async function recordTenantRunOutcome(
   });
 }
 
-async function dropTenantRunQueued(db: DbConnection, bullJobId: string): Promise<void> {
-  await deleteMany(db, tenantJobRunsTable, { bullJobId, status: "queued" });
+async function dropTenantRunQueued(
+  db: DbConnection,
+  jobName: string,
+  bullJobId: string,
+  meta: JobDroppedMeta,
+): Promise<void> {
+  await deleteMany(db, tenantJobRunsTable, {
+    tenantId: meta.tenantId,
+    jobName,
+    bullJobId,
+    status: "queued",
+  });
 }
 
 const log = createFallbackLogger("job-run-logger");
@@ -458,8 +489,12 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       );
     },
 
-    onJobDropped: async (jobName: string, bullJobId: string) => {
-      await isolateTenantRunWrite(() => dropTenantRunQueued(db, bullJobId), jobName, bullJobId);
+    onJobDropped: async (jobName: string, bullJobId: string, meta: JobDroppedMeta) => {
+      await isolateTenantRunWrite(
+        () => dropTenantRunQueued(db, jobName, bullJobId, meta),
+        jobName,
+        bullJobId,
+      );
     },
 
     onJobStart: async (jobName: string, bullJobId: string, meta: JobMeta) => {

package/packages/bundled-features/src/jobs/tenant-job-run-table.ts

@@ -21,7 +21,7 @@ export type TenantJobRunStatus = "queued" | "running" | "completed" | "failed";
 // job is invisible there. This table holds no payload, error text or logs by
 // design — the tenant learns only that work is waiting, running or finished.
 //
-// One row per BullMQ job. Active rows (queued/running) are kept as they are;
+// One row per BullMQ job and (tenant, job name). Active rows (queued/running) are kept as they are;
 // a finished row replaces earlier finished rows of the same (tenant, job,
 // subject), so only the latest outcome stays. `subject` is the canonical JSON
 // of the job's declared subjectFields, or NULL for none — stored in clear, so
@@ -41,7 +41,12 @@ export const tenantJobRunsTable = pgTable(
     updatedAt: instant("updated_at").default(sql`now()`).notNull(),
   },
   (t) => [
-    uniqueIndex("store_tenant_job_runs_bull_job_id_unique").on(t.bullJobId),
+    // BullMQ ids are unique per queue only; the id alone would let two tenants collide.
+    uniqueIndex("store_tenant_job_runs_tenant_job_bull_job_id_unique").on(
+      t.tenantId,
+      t.jobName,
+      t.bullJobId,
+    ),
     // Finishing a run prunes older outcomes by this key; the tenant query reads by it.
     index("store_tenant_job_runs_tenant_job_subject_idx").on(t.tenantId, t.jobName, t.subject),
     // Stale sweep and retention filter on age alone.

package/packages/bundled-features/src/ledger/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Document the duplicate check required before the (tenant_id, source_ref) unique index",
+    "detail": "The unique index on read_ledger_schedules (tenant_id, source_ref) is created in place and fails on existing duplicate pairs, and a projection rebuild over duplicate events fails the same way. Replay handling for duplicate events is not part of this change.",
+    "migration": "Before upgrading, check each database for duplicates and clean them up: SELECT tenant_id, source_ref, count(*) FROM read_ledger_schedules WHERE source_ref IS NOT NULL GROUP BY 1, 2 HAVING count(*) > 1; Any row returned makes the unique index migration abort."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

package/packages/bundled-features/src/ledger/entity.ts

@@ -176,7 +176,9 @@ export const scheduleEntity = createEntity({
   },
   // Find-then-create by sourceRef races across tabs/devices; only the DB closes
   // that gap. Partial because sourceRef is optional. A new name (not the old
-  // non-unique default) keeps the migration an in-place CREATE UNIQUE INDEX.
+  // non-unique default) keeps the migration an in-place CREATE UNIQUE INDEX;
+  // that statement, like a projection rebuild, fails on existing duplicate
+  // (tenant_id, source_ref) pairs, so duplicates must be cleaned up beforehand.
   indexes: [
     { columns: ["tenantId", "subjectType", "subjectId"] },
     {

package/packages/bundled-features/src/ledger/recurring.ts

@@ -63,9 +63,7 @@ export function findReversedIds(
 ): Set<string> {
   const ids = new Set(rows.map((r) => r.id));
   return new Set(
-    rows
-      .filter((r) => r.reference !== null && ids.has(r.reference))
-      .map((r) => r.reference as string),
+    rows.flatMap((r) => (r.reference !== null && ids.has(r.reference) ? [r.reference] : [])),
   );
 }
 

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

@@ -50,6 +50,11 @@ const DESCRIPTION_PATTERN = { regex: "^[\\s\\S]{0,500}$" } as const;
 // there.
 const CUSTOM_CSS_PATTERN = { regex: "^[\\s\\S]{0,8000}$" } as const;
 
+// Empty or a FileRef id (UUID); the upload UI that fills it ships separately.
+const FILE_REF_ID_PATTERN = {
+  regex: "^$|^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+} as const;
+
 export const LAYOUT_PRESETS = ["minimal", "centered", "wide"] as const;
 
 // Companion toggle feature name. managed-pages reads ctx.hasFeature() against it
@@ -91,6 +96,12 @@ export const BRANDING_KEYS = {
     pattern: HTTPS_PATTERN,
     write: BRANDING_WRITE,
   }),
+  // Ownership is checked where it is read (renderer-mail-html: FileRef must belong to the rendering tenant).
+  brandingLogoFile: createTenantConfig("text", {
+    default: "",
+    pattern: FILE_REF_ID_PATTERN,
+    write: BRANDING_WRITE,
+  }),
   brandingLayoutPreset: createTenantConfig("select", {
     default: "centered",
     options: LAYOUT_PRESETS,
@@ -112,6 +123,7 @@ export const BRANDING_QN = {
   siteUrl: "managed-pages:config:branding-site-url",
   accentColor: "managed-pages:config:branding-accent-color",
   logoUrl: "managed-pages:config:branding-logo-url",
+  logoFile: "managed-pages:config:branding-logo-file",
   layoutPreset: "managed-pages:config:branding-layout-preset",
   customCss: "managed-pages:config:branding-custom-css",
 } as const;
@@ -129,17 +141,28 @@ async function readText(config: ConfigAccessor, qualifiedKey: string): Promise<s
 // publicstatus' branding read), not a crash.
 export async function readBranding(config: ConfigAccessor | undefined): Promise<BrandingTokens> {
   if (!config) return EMPTY_BRANDING;
-  const [title, description, siteUrl, accentColor, logoUrl, layoutPreset] = await Promise.all([
-    readText(config, BRANDING_QN.title),
-    readText(config, BRANDING_QN.description),
-    readText(config, BRANDING_QN.siteUrl),
-    readText(config, BRANDING_QN.accentColor),
-    readText(config, BRANDING_QN.logoUrl),
-    readText(config, BRANDING_QN.layoutPreset),
-  ]);
+  const [title, description, siteUrl, accentColor, logoUrl, logoFile, layoutPreset] =
+    await Promise.all([
+      readText(config, BRANDING_QN.title),
+      readText(config, BRANDING_QN.description),
+      readText(config, BRANDING_QN.siteUrl),
+      readText(config, BRANDING_QN.accentColor),
+      readText(config, BRANDING_QN.logoUrl),
+      readText(config, BRANDING_QN.logoFile),
+      readText(config, BRANDING_QN.layoutPreset),
+    ]);
   // customCss stays "" here — it is gated (allowCustomCss + per-tenant toggle)
   // and read separately by the branding query via readCustomCss.
-  return { title, description, siteUrl, accentColor, logoUrl, layoutPreset, customCss: "" };
+  return {
+    title,
+    description,
+    siteUrl,
+    accentColor,
+    logoUrl,
+    logoFile,
+    layoutPreset,
+    customCss: "",
+  };
 }
 
 // Read the raw, untrusted custom CSS for the request's tenant. The caller (the
@@ -167,6 +190,7 @@ export function coerceBranding(value: unknown): BrandingTokens {
     siteUrl: stringField(source, "siteUrl"),
     accentColor: stringField(source, "accentColor"),
     logoUrl: stringField(source, "logoUrl"),
+    logoFile: stringField(source, "logoFile"),
     layoutPreset: stringField(source, "layoutPreset"),
     customCss: stringField(source, "customCss"),
   };

package/packages/bundled-features/src/managed-pages/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Branding screen edits the logo file and readBranding returns logoFile",
+    "detail": "The branding settings screen has a logo upload for managed-pages:config:branding-logo-file, and readBranding and the branding query include logoFile next to logoUrl. The template resource errors template_resource_too_large and template_resource_unsupported_image have German and Spanish texts."
+  },
   {
     "version": "0.353.0",
     "type": "fix",

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

@@ -47,6 +47,7 @@ function brandingRevisionSeed(branding: BrandingTokens): string {
     branding.siteUrl,
     branding.accentColor,
     branding.logoUrl,
+    branding.logoFile,
     branding.layoutPreset,
     branding.customCss,
   ]);

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

@@ -42,6 +42,7 @@ export const MANAGED_PAGES_I18N: Readonly<Record<string, LocalizedString>> = {
     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

package/packages/bundled-features/src/managed-pages/screens/branding-screen.ts

@@ -1,5 +1,6 @@
 import {
   type ConfigEditScreenDefinition,
+  createImageField,
   createSelectField,
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -35,6 +36,7 @@ export function createBrandingSettingsScreen(opts: {
       siteUrl: BRANDING_QN.siteUrl,
       accentColor: BRANDING_QN.accentColor,
       logoUrl: BRANDING_QN.logoUrl,
+      logoFile: BRANDING_QN.logoFile,
       layoutPreset: BRANDING_QN.layoutPreset,
     },
     fields: {
@@ -62,6 +64,11 @@ export function createBrandingSettingsScreen(opts: {
         personal: false,
         reason: "is_business_data",
       }),
+      logoFile: createImageField({
+        accept: ["image/png", "image/jpeg", "image/webp"],
+        personal: false,
+        reason: "is_business_data",
+      }),
       layoutPreset: createSelectField({ options: LAYOUT_PRESETS }),
     },
     layout: {
@@ -75,6 +82,7 @@ export function createBrandingSettingsScreen(opts: {
             { field: "description", span: 2 },
             { field: "siteUrl", span: 1 },
             { field: "logoUrl", span: 1 },
+            { field: "logoFile", span: 1 },
             { field: "accentColor", span: 1 },
           ],
         },

package/packages/bundled-features/src/page-render/branding.ts

@@ -13,6 +13,8 @@ export type BrandingTokens = {
   readonly siteUrl: string;
   readonly accentColor: string;
   readonly logoUrl: string;
+  // FileRef id of an uploaded logo ("" = none); the renderer resolves it, tenant ownership is checked there.
+  readonly logoFile: string;
   readonly layoutPreset: string;
   // RAW, untrusted tenant CSS — "" unless the custom-css capability is gated on
   // (managed-pages allowCustomCss + the per-tenant toggle). It is NOT pre-
@@ -29,6 +31,7 @@ export const EMPTY_BRANDING: BrandingTokens = {
   siteUrl: "",
   accentColor: "",
   logoUrl: "",
+  logoFile: "",
   layoutPreset: "",
   customCss: "",
 };

package/packages/bundled-features/src/page-render/markdown.ts

@@ -25,7 +25,7 @@ safeRenderer.use({
 });
 
 export function renderSafeMarkdown(markdown: string): string {
-  // @cast-boundary marked.parse return-type ist `string | Promise<string>`;
+  // @cast-boundary third-party-type-gap marked.parse return-type ist `string | Promise<string>`;
   // `{ async: false }` garantiert sync (string) — Cast nur API-Vertragsfix.
   return safeRenderer.parse(markdown, { async: false }) as string;
 }

package/packages/bundled-features/src/personal-access-tokens/feature.ts

@@ -42,11 +42,9 @@ export function bindPatAutoRevokeOnPasswordChangeFromFeature(
 ): BindPatAutoRevokeOnPasswordChange | undefined {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
-    const { bindAutoRevokeOnPasswordChange } = exports as {
-      bindAutoRevokeOnPasswordChange: unknown;
-    };
+    const { bindAutoRevokeOnPasswordChange } = exports;
     if (typeof bindAutoRevokeOnPasswordChange === "function") {
-      // @cast-boundary exports-walk — feature.exports is untyped by design
+      // @cast-boundary feature-exports — feature.exports is untyped by design
       return bindAutoRevokeOnPasswordChange as BindPatAutoRevokeOnPasswordChange;
     }
   }

package/packages/bundled-features/src/personal-access-tokens/handlers/list.query.ts

@@ -1,5 +1,6 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { definePagedQueryHandler, MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.js";
 import { isExpiredAt } from "../expiry.js";
@@ -13,7 +14,7 @@ const SORTABLE_COLUMNS = ["id", "name", "createdAt", "expiresAt", "revokedAt"] a
 type SortableColumn = (typeof SORTABLE_COLUMNS)[number];
 
 function isSortableColumn(value: string): value is SortableColumn {
-  return (SORTABLE_COLUMNS as readonly string[]).includes(value);
+  return isOneOf(SORTABLE_COLUMNS, value);
 }
 
 type PatStatus = "active" | "revoked" | "expired";

package/packages/bundled-features/src/personal-access-tokens/index.ts

@@ -29,7 +29,7 @@ export { expandScopes } from "./scopes.js";
 export function patRateLimitFromFeature(feature: FeatureDefinition): PatRateLimit {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "rateLimit" in exports) {
-    const { rateLimit } = exports as { rateLimit: unknown };
+    const { rateLimit } = exports;
     if (
       rateLimit &&
       typeof rateLimit === "object" &&

package/packages/bundled-features/src/personal-access-tokens/revoke-for-user.ts

@@ -4,6 +4,7 @@ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { append } from "@cosmicdrift/kumiko-framework/event-store";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import {
   PAT_REVOKED_AGGREGATE_TYPE,
   PAT_REVOKED_EVENT_QN,
@@ -13,7 +14,7 @@ import { apiTokenTable } from "./schema/api-token.js";
 
 // A pool has begin(); a tx/savepoint handle does not and is already atomic.
 function canBeginTransaction(db: DbRunner): boolean {
-  return typeof (db as { begin?: unknown }).begin === "function"; // @cast-boundary driver-handle-probe
+  return typeof propertyOf(db, "begin") === "function";
 }
 
 // Cross-tenant revoke: password-change and MFA-enable/disable are account-

package/packages/bundled-features/src/renderer-foundation/README.md

@@ -1,6 +1,6 @@
 # renderer-foundation
 
-Plugin-Foundation für Renderer (Notification, HTML-Mail, PDF, Image). Plugins (`renderer-simple`, `renderer-mail-html`, `renderer-puppeteer-client`) registrieren sich via `r.useExtension("renderer", "<name>", { kinds, render })`.
+Plugin-Foundation für Renderer (HTML-Mail, PDF, Image). Plugins (`renderer-mail-html`, `renderer-puppeteer-client`) registrieren sich via `r.useExtension("renderer", "<name>", { kinds, render })`.
 
 **Plan-Doc:** [`kumiko-platform/docs/plans/features/renderer-foundation.md`](../../../../../../kumiko-platform/docs/plans/features/renderer-foundation.md)
 
@@ -16,8 +16,7 @@ import {
 const features = [
   createTemplateResolverFeature(),
   createRendererFoundationFeature(),
-  createRendererSimpleFeature(),   // Plugin
-  createRendererMailHtmlFeature(), // Plugin (enterprise)
+  createRendererMailHtmlFeature(), // Plugin: kind "mail"
   // weitere Plugins...
 ];
 
@@ -38,23 +37,25 @@ import { requireRendererFoundation } from "@cosmicdrift/kumiko-bundled-features/
 
 async function sendMail(ctx, tenantId) {
   const foundation = requireRendererFoundation(ctx, "sendMail");
-  const renderer = foundation.createRendererForTenant({ tenantId, kind: "mail-html" });
+  const renderer = foundation.createRendererForTenant({ tenantId, kind: "mail" });
   const result = await renderer.render(
     {
-      kind: "mail-html",
-      payload: { content: "Hello {{name}}", contentFormat: "markdown", variables: { name: "Frau Schmidt" } },
+      kind: "mail",
+      payload: { slug: "billing:notify:invoice-ready", locale: "de", variables: { name: "Frau Schmidt" } },
     },
-    { db: ctx.db, registry: ctx.registry, tenantId },
+    { db: ctx.db, registry: ctx.registry, tenantId, config: ctx.config },
   );
-  // result.html, result.text
+  // result.subject, result.html, result.text, result.previewText
 }
 ```
 
-Plugins ohne Service-Deps (`renderer-simple`) ignorieren den zweiten `ctx`-Parameter.
+Plugins ohne Service-Deps ignorieren den zweiten `ctx`-Parameter.
+
+Mails einer `r.notification` rendert die Delivery selbst: `template` + `meta` an der Notification werden beim Boot gesät (`seedNotificationTemplates`) und über kind `"mail"` gerendert. Ohne `template` + `meta` scheitert der Versand über den Email-Channel.
 
 ## Plugin-Auswahl-Reihenfolge
 
-1. Tenant-Override (Config-Key `rendererPluginByKind`, z.B. `{ "mail-html": "mail-html" }`)
+1. Tenant-Override (Config-Key `rendererPluginByKind`, z.B. `{ "mail": "mail-html" }`)
 2. `DEFAULT_PLUGIN_BY_KIND` aus constants
 3. Erstes Plugin im Pool das das kind bedient
 4. `RendererError("no_plugin_for_kind")` wenn nichts passt

package/packages/bundled-features/src/renderer-foundation/api.ts

@@ -10,21 +10,21 @@ import { RendererError, type RendererPlugin } from "./types.js";
 
 export type RendererFoundationApi = {
   /**
-   * Wählt + returnt ein RendererPlugin für (tenantId × kind). Caller
-   * rufen anschließend `plugin.render(req, ctx)`.
+   * Selects + returns a RendererPlugin for (tenantId × kind). Callers
+   * then invoke `plugin.render(req, ctx)`.
    *
-   * **Auswahl-Reihenfolge:**
-   *   1. Tenant-spezifische Config (config-Bundle: `rendererPluginByKind`)
-   *   2. DEFAULT_PLUGIN_BY_KIND aus constants
-   *   3. Erstes Plugin im Pool das das kind bedient
-   *   4. `RendererError("no_plugin_for_kind")` wenn nichts passt
+   * **Selection order:**
+   *   1. Tenant-specific config (config bundle: `rendererPluginByKind`)
+   *   2. DEFAULT_PLUGIN_BY_KIND from constants
+   *   3. First plugin in the pool that serves the kind
+   *   4. `RendererError("no_plugin_for_kind")` if nothing matches
    *
-   * **Caller-Pattern:** `tenantId` MUSS vom Server kommen (typisch
-   * `ctx.user.tenantId`). Plugins, die Service-Access brauchen (z.B.
-   * `renderer-mail-html` für Layout-Resolve via `template-resolver`),
-   * erhalten `RendererContext` als zweites Argument zu `render()` —
-   * matcht das Pattern von `DeliveryChannel.send(addr, msg, ctx)`.
-   * Plugins ohne Service-Deps (z.B. `renderer-simple`) ignorieren ctx.
+   * **Caller pattern:** `tenantId` MUST come from the server (typically
+   * `ctx.user.tenantId`). Plugins that need service access (e.g.
+   * `@cosmicdrift/kumiko-renderer-mail-html` for layout resolution via `template-resolver`)
+   * receive `RendererContext` as the second argument to `render()` —
+   * matches the pattern of `DeliveryChannel.send(addr, msg, ctx)`.
+   * Plugins without service deps ignore ctx.
    */
   readonly createRendererForTenant: (args: {
     readonly tenantId: TenantId;
@@ -66,7 +66,7 @@ export function createRendererFoundationApi(
 
       // 4. Kein Plugin → Error
       throw new RendererError(
-        `[renderer-foundation] no plugin registered for kind="${kind}". Mount at least one plugin (renderer-simple, renderer-mail-html, renderer-puppeteer-client) for this kind.`,
+        `[renderer-foundation] no plugin registered for kind="${kind}". Mount at least one plugin (renderer-mail-html, renderer-puppeteer-client) for this kind.`,
         "no_plugin_for_kind",
       );
     },

package/packages/bundled-features/src/renderer-foundation/changes.json

@@ -1,4 +1,43 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "document-pdf requests name a template, the response carries fileName",
+    "detail": "The document-pdf payload is { slug, locale, variables } instead of ready HTML in content. The response has a fileName, RendererContext gets an optional filesForTenant (file access per tenant) and RendererError has the new code unavailable for a renderer backend that cannot be reached.",
+    "migration": "Callers that sent `payload: { content }` switch to a document-pdf template and pass slug, locale and variables (money-horse credit-schedule-pdf follows in #621); renderer-pdf callers pass slug and locale too. The enterprise package @cosmicdriftgamestudio/kumiko-renderer-puppeteer-client no longer builds against these types and is replaced by @cosmicdrift/kumiko-renderer-puppeteer-client."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "renderer plugins can preview a document",
+    "detail": "RendererPlugin gets the optional capability previewDocument(req, ctx), which returns the filled-in body and layout regions without calling the print service. template-resolver:query:preview with kind document-pdf uses it, so the editor shows replaced placeholders and the resource and required-placeholder checks; without such a plugin the preview keeps returning the body and raw layout."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "PdfOptions has landscape",
+    "detail": "The document-pdf options gain landscape, which the puppeteer-service passes to Chromium."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "RenderRequest kind mail replaces mail-html",
+    "detail": "RenderRequest and RenderResponse use kind mail with a MailPayload ({ slug, locale, variables, unsubscribeUrl? }) and a response of { subject, html, text, previewText? }. The export MailHtmlPayload is removed; use MailPayload. The default plugin name for kind mail stays mail-html. RendererContext gains an optional config accessor that plugins use for tenant locale, currency and branding.",
+    "migration": "Replace kind mail-html with mail in createRendererForTenant and render calls, pass { slug, locale, variables } instead of content/contentFormat, and read the subject from the response instead of building it yourself. Pass ctx.config in the RendererContext to get tenant locale, currency and branding."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "renderer-simple, MailBranding and renderer kind \"notification\" are removed",
+    "detail": "Every mail is a stored template rendered by renderer-mail-html now. renderer-simple (createRendererSimpleFeature, simpleRenderer, createSimpleRenderer, RendererSimpleOptions, mail blocks with LocalizedText, MailBadge, MailChip, MailStage, MailStageState and MailTone), the MailBranding type, the renderer kind \"notification\" and AuthMailContent are gone. NotificationRenderer and RendererInput are removed from delivery, and createChannelEmailFeature no longer takes a renderer option. The type NotificationPayload is removed from renderer-foundation. The template-resolver keeps \"notification\" only as a stored kind so legacy rows stay readable; RENDER_KINDS is mail, document-pdf and image-snapshot.",
+    "migration": "Remove createRendererSimpleFeature() and any renderer or mailBranding option from your feature list and createChannelEmailFeature call. An r.notification that is sent by email needs template + meta (or localizedTemplate) and variables; the sections/header/footer data it carried is replaced by template variables. Branding (logo, footer) now comes from the tenant branding config and the mail layout of renderer-mail-html. Mount template-resolver, renderer-foundation and @cosmicdrift/kumiko-renderer-mail-html (composeRendererStack() mounts all of them) and run seedNotificationTemplates at boot. Existing template rows with kind \"notification\" are no longer rendered; re-create them as kind \"mail\" or archive them."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "MailPayload.draft renders an unsaved mail template; RendererContext.db also accepts a TenantDb",
+    "detail": "MailDraft (content, meta, variableSchema) replaces the stored body and subject of the template with the payload's slug and keeps its stored images; a slug without a stored template renders as a tenant draft. The renderer sanitizes the draft body and validates its meta again, and the response carries no template provenance. RendererContext.db is widened from DbConnection to DbRunner | TenantDb."
+  },
   {
     "version": "0.306.0",
     "type": "breaking",

package/packages/bundled-features/src/renderer-foundation/constants.ts

@@ -1,11 +1,10 @@
-// Re-export aus template-resolver — gleiche RenderKind-Domäne. Beide
-// Bundles teilen sich die Enum, damit Plugins (renderer-mail-html etc.)
-// nicht zwei Quellen importieren müssen. Cross-feature-Imports gehen
-// über das Barrel (../template-resolver), nicht via deep-import.
+// Re-export from template-resolver — same RenderKind domain. Both
+// bundles share the enum so plugins (@cosmicdrift/kumiko-renderer-mail-html etc.)
+// do not have to import two sources. Cross-feature imports go
+// through the barrel (../template-resolver), not via deep import.
 import type { RenderKind as RenderKindLocal } from "../template-resolver/index.js";
 
-// Extension-point name for renderer plugins (renderer-simple,
-// renderer-mail-html, renderer-puppeteer-client, ...).
+// Extension-point name for renderer plugins (@cosmicdrift/kumiko-renderer-mail-html, @cosmicdrift/kumiko-renderer-puppeteer-client, ...).
 export const RENDERER_EXTENSION = "renderer" as const;
 
 export {
@@ -18,8 +17,7 @@ export {
 // Standard-Default-Plugin pro Kind, wenn Tenant keine explizite Config
 // gesetzt hat. App-Bootstrap kann das via TenantConfigKey überschreiben.
 export const DEFAULT_PLUGIN_BY_KIND: Readonly<Record<RenderKindLocal, string>> = {
-  notification: "simple",
-  "mail-html": "mail-html",
+  mail: "mail-html",
   "document-pdf": "puppeteer",
   "image-snapshot": "puppeteer",
 };