@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/secrets/feature.ts

@@ -83,21 +83,22 @@ export function requireSecretsContext(
         "createSecretsContext({db, masterKeyProvider, registry}) via extraContext.secrets at boot.",
     });
   }
-  const raw = ctx.secrets;
   const userId = ctx._userId;
   if (!userId) {
     throw new InternalError({
       message: `[${handlerName}] ctx._userId missing — cannot audit secret reads without a caller identity.`,
     });
   }
-  return {
+  const withAudit = (raw: SecretsContext): SecretsContext => ({
+    withRunner: (runner) => withAudit(raw.withRunner(runner)),
     get: (tenantId, key, overrideAudit) =>
       raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
     // No audit injection: has() is metadata-only and never logs a read.
     has: raw.has.bind(raw),
     set: raw.set.bind(raw),
     delete: raw.delete.bind(raw),
-  };
+  });
+  return withAudit(ctx.secrets);
 }
 
 export type SecretsFeatureOptions = {

package/packages/bundled-features/src/secrets/secrets-context.ts

@@ -17,6 +17,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbConnection,
+  type DbRunner,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, type WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
@@ -91,8 +92,20 @@ function resolveKey(keyOrHandle: string | { readonly name: string }): string {
 }
 
 export function createSecretsContext(opts: SecretsContextOptions): SecretsContext {
-  const { db, masterKeyProvider } = opts;
+  const { masterKeyProvider } = opts;
   const provider = withDekCache(masterKeyProvider, opts.dekCache ?? createDekCache());
+  return buildSecretsContext(opts, provider, opts.db, false);
+}
+
+// `runnerIsTransaction`: the runner is a caller-owned transaction, so audited reads join it
+// instead of opening a second connection (which would deadlock a small pool).
+function buildSecretsContext(
+  opts: SecretsContextOptions,
+  provider: MasterKeyProvider,
+  db: DbRunner,
+  runnerIsTransaction: boolean,
+): SecretsContext {
+  const { masterKeyProvider } = opts;
 
   type SecretLookupRow = {
     readonly id: string;
@@ -105,6 +118,10 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
   }
 
   return {
+    withRunner(runner) {
+      return buildSecretsContext(opts, provider, runner, true);
+    },
+
     async get(tenantId, keyOrHandle, auditCtx) {
       const key = resolveKey(keyOrHandle);
       // Atomic audit + read: a decrypt that "escaped" the audit trail
@@ -120,7 +137,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
         return createSecret(plaintext);
       }
 
-      const plaintext = await transaction(db, async (tx) => {
+      const readAndAudit = async (tx: DbRunner): Promise<string | undefined> => {
         // Inline select inside the TX via raw client — fetchOne's connection
         // type doesn't widen to the transaction object cleanly.
         const envelope = await selectTenantSecretEnvelope(tx, tenantId, key);
@@ -154,7 +171,10 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
           metadata,
         });
         return pt;
-      });
+      };
+      const plaintext = runnerIsTransaction
+        ? await readAndAudit(db)
+        : await transaction(db, readAndAudit);
 
       if (plaintext === undefined) return undefined;
       // Brand the plaintext only after audit committed. The response

package/packages/bundled-features/src/sessions/db/queries/cleanup.ts

@@ -6,7 +6,7 @@ export async function deleteStaleSessionsBatch(
   olderThanDays: number,
   batchSize: number,
 ): Promise<number> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = await asRawClient(db).unsafe<{ id: string }>(
     `DELETE FROM "store_user_sessions"
      WHERE "id" IN (
        SELECT "id" FROM "store_user_sessions"
@@ -16,6 +16,6 @@ export async function deleteStaleSessionsBatch(
      )
      RETURNING "id"`,
     [olderThanDays, batchSize],
-  )) as readonly { id: string }[];
+  );
   return rows.length;
 }

package/packages/bundled-features/src/sessions/feature.ts

@@ -71,11 +71,9 @@ export function bindAutoRevokeFromFeature(
 ): BindAutoRevokeOnPasswordChange | 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 BindAutoRevokeOnPasswordChange;
     }
   }

package/packages/bundled-features/src/sessions/handlers/list.query.ts

@@ -4,6 +4,7 @@ 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 { userSessionTable } from "../schema/user-session.js";
@@ -17,7 +18,7 @@ const SORTABLE_COLUMNS = ["id", "userId", "createdAt", "expiresAt", "revokedAt"]
 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);
 }
 
 // Admin view of every session in the active tenant. ctx.db (TenantDb)

package/packages/bundled-features/src/shared/attachment-file-name.ts

@@ -0,0 +1,39 @@
+import * as z from "zod";
+
+const MAX_FILE_NAME_LENGTH = 255;
+
+function hasControlCharacter(value: string): boolean {
+  return value.split("").some((char) => {
+    const code = char.charCodeAt(0);
+    return code <= 0x1f || code === 0x7f;
+  });
+}
+
+export const attachmentFileNameSchema = z
+  .string()
+  .min(1)
+  .max(MAX_FILE_NAME_LENGTH)
+  .refine((name) => !name.includes("/") && !name.includes("\\") && !hasControlCharacter(name), {
+    message: "file name must not contain path separators or control characters",
+  });
+
+const PDF_FILE_NAME_MAX_LENGTH = 200;
+const PDF_EXTENSION = ".pdf";
+
+// Shared by everything that names a rendered PDF, so a mail attachment and a download of the same
+// template get the same name. The cut leaves room for the extension: the attachment schema caps
+// rendered-pdf names, and a name that only fits without ".pdf" would fail it.
+export function sanitizePdfAttachmentFileName(raw: string, templateSlug: string): string {
+  const cleaned = raw
+    .split("")
+    .filter((char) => !hasControlCharacter(char))
+    .join("")
+    .replace(/[/\\";]/g, "-")
+    .replaceAll("..", "-")
+    .trim()
+    .slice(0, PDF_FILE_NAME_MAX_LENGTH - PDF_EXTENSION.length)
+    .trim();
+  const lastSegment = templateSlug.split(":").pop() ?? templateSlug;
+  if (cleaned === "") return `${lastSegment}${PDF_EXTENSION}`;
+  return cleaned.toLowerCase().endsWith(PDF_EXTENSION) ? cleaned : `${cleaned}${PDF_EXTENSION}`;
+}

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "Mail template body helpers exported as `./shared/mail-template-body`",
+    "detail": "Apps that register their own notification templates can build the body with the same helpers the framework uses: `mailParagraph`, `mailHeading`, `mailRepeatedRows`, `mailTextWithSlotsHtml`, plus the new `mailButton`, `mailParagraphWithLink` and `mailSubject`. The subpath only depends on kumiko-headless and is safe on the server. Apps that copied these helpers can import them instead."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/shared/chunked-entity-migration.ts

@@ -33,6 +33,9 @@ export type ChunkedMigrationOptions<Row> = {
   readonly maxFailures: number;
   // Epoch ms; Number.POSITIVE_INFINITY for no time bound.
   readonly deadlineAt: number;
+  // Batches processed even when the deadline already passed. Callers whose setup before the
+  // loop can eat the whole budget set 1, so every run makes progress instead of timing out empty.
+  readonly minBatches?: number;
   readonly signal?: AbortSignal | undefined;
   readonly onRowError?: (row: Row, err: unknown) => void;
 };
@@ -51,7 +54,7 @@ export async function runChunkedMigration<Row>(
       stoppedReason = "signal";
       break;
     }
-    if (Date.now() >= opts.deadlineAt) {
+    if (batchesProcessed >= (opts.minBatches ?? 0) && Date.now() >= opts.deadlineAt) {
       stoppedReason = "timeout";
       break;
     }

package/packages/bundled-features/src/shared/index.ts

@@ -1,5 +1,9 @@
 export { collectErasureFailure, throwIfErasureFailed } from "./assert-erased.js";
 export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-ownership-write.js";
+export {
+  attachmentFileNameSchema,
+  sanitizePdfAttachmentFileName,
+} from "./attachment-file-name.js";
 export {
   type ChunkedMigrationOptions,
   type ChunkedMigrationResult,
@@ -18,6 +22,7 @@ export { isWithinGracePeriod } from "./grace-period.js";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
 export { isTenantDb } from "./is-tenant-db.js";
 export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter.js";
+export { mailHeading, mailParagraph, mailRepeatedRows } from "./mail-template-body.js";
 export { mapWithConcurrency } from "./map-with-concurrency.js";
 export {
   denyUnlessJoinRowParentVisible,
@@ -43,6 +48,7 @@ export {
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
 export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";
 export { sessionTimezoneField } from "./session-timezone-field.js";
+export { assertNotSvg, MAX_INPUT_PIXELS, SHARP_INPUT_OPTIONS } from "./sharp-input-limits.js";
 export {
   peekTokenSubject,
   signToken,

package/packages/bundled-features/src/shared/is-tenant-db.ts

@@ -5,5 +5,5 @@ import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 // Shared so retention/compliance-profile resolvers that accept either (bulk cron
 // vs. per-hook TenantDb) branch through one predicate instead of duplicating it.
 export function isTenantDb(db: DbRunner | TenantDb): db is TenantDb {
-  return typeof (db as Partial<TenantDb>).unsafeRaw === "function";
+  return "unsafeRaw" in db && typeof db.unsafeRaw === "function";
 }

package/packages/bundled-features/src/shared/mail-template-body.ts

@@ -0,0 +1,42 @@
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+
+const SLOT_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+// Author text uses `{name}` slots. The text is escaped first and the slots are
+// swapped for variable nodes afterwards, so a slot can never smuggle markup.
+export function mailTextWithSlotsHtml(text: string): string {
+  return escapeHtml(text).replace(
+    SLOT_PATTERN,
+    (_, name: string) => `<span data-variable="${escapeHtmlAttr(name)}"></span>`,
+  );
+}
+
+export function mailParagraph(text: string): string {
+  return `<p>${mailTextWithSlotsHtml(text)}</p>`;
+}
+
+export function mailHeading(text: string): string {
+  return `<h2>${mailTextWithSlotsHtml(text)}</h2>`;
+}
+
+export function mailButton(label: string, linkVariable: string): string {
+  return `<p><a data-button href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(label)}</a></p>`;
+}
+
+export function mailParagraphWithLink(
+  text: string,
+  linkLabel: string,
+  linkVariable: string,
+): string {
+  return `<p>${mailTextWithSlotsHtml(text)} <a href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(linkLabel)}</a></p>`;
+}
+
+// One table row per list entry; the cell shows the entry's `field`.
+export function mailRepeatedRows(listName: string, field: string): string {
+  return `<table><tbody><tr data-each="${escapeHtmlAttr(listName)}"><td><p><span data-variable="${escapeHtmlAttr(field)}"></span></p></td></tr></tbody></table>`;
+}
+
+// Subjects are Handlebars text, so the same `{name}` slots become `{{name}}`.
+export function mailSubject(text: string): string {
+  return text.replace(SLOT_PATTERN, "{{$1}}");
+}

package/packages/bundled-features/src/shared/sharp-input-limits.ts

@@ -0,0 +1,26 @@
+// Sharp-free so callers can import the limits without loading the native binding.
+
+// Above this, a decoded pixel buffer runs into hundreds of MB before any
+// resize even happens — sharp's own default (~268MP) is still large enough
+// to be an OOM primitive for a single request.
+export const MAX_INPUT_PIXELS = 100_000_000;
+// sequentialRead trades random pixel access for lower peak memory on
+// streamed formats — applied at every decode entry point below since none
+// of them need non-sequential access to the *original* bytes (extract runs
+// against a single already-buffered region per call).
+export const SHARP_INPUT_OPTIONS = {
+  limitInputPixels: MAX_INPUT_PIXELS,
+  sequentialRead: true,
+} as const;
+
+// Shared trust boundary for every image byte source this renderer decodes —
+// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
+// alike: a base64 string in a field declaration isn't more trustworthy than
+// an upload just because it came from app code.
+export function assertNotSvg(format: string | undefined): void {
+  if (format === "svg") {
+    throw new Error(
+      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
+    );
+  }
+}

package/packages/bundled-features/src/shared/signup-handover.ts

@@ -13,6 +13,7 @@
 
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 
 export const EXT_SIGNUP_HANDOVER = "signupHandover" as const;
 
@@ -46,10 +47,9 @@ export type SignupHandoverProvider = {
 
 export function isSignupHandoverProvider(options: unknown): options is SignupHandoverProvider {
   return (
-    typeof options === "object" &&
-    options !== null &&
-    typeof (options as Record<string, unknown>)["verifyGrant"] === "function" &&
-    typeof (options as Record<string, unknown>)["mintClaim"] === "function"
+    isPlainObject(options) &&
+    typeof options["verifyGrant"] === "function" &&
+    typeof options["mintClaim"] === "function"
   );
 }
 

package/packages/bundled-features/src/subscription-stripe/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "A stale Stripe customer id no longer turns the customer portal into a 500",
+    "detail": "createPortalSession now maps Stripe's \"No such customer\" rejection (account switch, customer deleted in the dashboard) to an UnprocessableError with the i18n key billing-foundation.errors.providerCustomerUnknown, translated in German and Spanish, instead of letting the raw Stripe error surface as a server error."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -109,12 +109,10 @@ export function mapAppLocaleToStripeLocale(
   return knownLocales.find((known) => known === language) ?? "auto";
 }
 
-function isUnknownCustomerStripeError(error: unknown): boolean {
-  return (
-    isResourceMissingStripeError(error) &&
-    error instanceof Stripe.errors.StripeInvalidRequestError &&
-    error.param === "customer"
-  );
+function isUnknownCustomerStripeError(
+  error: unknown,
+): error is Stripe.errors.StripeInvalidRequestError {
+  return isResourceMissingStripeError(error) && error.param === "customer";
 }
 
 export function createStripeCheckoutSession(
@@ -203,11 +201,21 @@ export type StripePortalOptions = Parameters<
 export function createStripePortalSession(runtime: StripeCtxRuntime) {
   return async (ctx: HandlerContext, options: StripePortalOptions): Promise<{ url: string }> => {
     const stripe = await runtime.clientForCtx(ctx);
-    const session = await stripe.billingPortal.sessions.create({
-      customer: options.providerCustomerId,
-      return_url: options.returnUrl,
-    });
-    return { url: session.url };
+    try {
+      const session = await stripe.billingPortal.sessions.create({
+        customer: options.providerCustomerId,
+        return_url: options.returnUrl,
+      });
+      return { url: session.url };
+    } catch (error) {
+      // A portal needs an existing customer, so unlike checkout there is no retry without one.
+      if (!isUnknownCustomerStripeError(error)) throw error;
+      throw new UnprocessableError("provider_customer_unknown", {
+        i18nKey: "billing-foundation.errors.providerCustomerUnknown",
+        message: `subscription-stripe: Stripe does not know customer "${options.providerCustomerId}" (account switch or customer deleted).`,
+        cause: error,
+      });
+    }
   };
 }
 

package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts

@@ -54,7 +54,9 @@ import type { StripeWebhookRuntime } from "./runtime.js";
 
 const log = createFallbackLogger("subscription-stripe");
 
-export function isResourceMissingStripeError(error: unknown): boolean {
+export function isResourceMissingStripeError(
+  error: unknown,
+): error is Stripe.errors.StripeInvalidRequestError {
   return (
     error instanceof Stripe.errors.StripeInvalidRequestError && error.code === "resource_missing"
   );

package/packages/bundled-features/src/tags/handlers/assign-tag.write.ts

@@ -1,5 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
 import { tagAssignmentAggregateId } from "../aggregate-id.js";
 import { DEFAULT_TAG_ACCESS } from "../constants.js";
@@ -67,7 +68,10 @@ export function createAssignTagHandler(
       // above and this restore() call, so restore() correctly refuses with
       // "not_deleted" — but the desired end state is already true. Converge
       // like the create() race below instead of surfacing a spurious error.
-      if ((restored.error.details as { reason?: string } | undefined)?.reason === "not_deleted") {
+      if (
+        isPlainObject(restored.error.details) &&
+        restored.error.details["reason"] === "not_deleted"
+      ) {
         return { isSuccess: true as const, data: { id } };
       }
       if (restored.error.code !== "not_found") return restored;

package/packages/bundled-features/src/tags/web/tag-chip.tsx

@@ -21,7 +21,8 @@ export function contrastText(color: string): "#000000" | "#ffffff" | null {
 function hexToRgb(color: string): { r: number; g: number; b: number } | null {
   const match = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(color.trim());
   if (match === null) return null;
-  const short = match[1] as string;
+  const short = match[1];
+  if (short === undefined) return null;
   const hex =
     short.length === 3
       ? `${short[0]}${short[0]}${short[1]}${short[1]}${short[2]}${short[2]}`

package/packages/bundled-features/src/template-resolver/README.md

@@ -1,6 +1,6 @@
 # template-resolver
 
-Strukturierter Content-Storage mit Tenant-Override-Hierarchie, Locale-Fallback und Resource-Linking via `file-foundation`. Eine Entity (`template-resource`) für alle Content-Arten — Render-Templates (`mail-html`, `document-pdf`, `notification`, `image-snapshot`), Markdown-Textblöcke (`text-block`, ex `text-content`-Feature) und AI-Prompts (`ai-prompt`).
+Strukturierter Content-Storage mit Tenant-Override-Hierarchie, Locale-Fallback und Resource-Linking via `file-foundation`. Eine Entity (`template-resource`) für alle Content-Arten — Render-Templates (`mail`, `document-pdf`, `notification`, `image-snapshot`), Rahmen (`mail-layout`, `pdf-layout`), Markdown-Textblöcke (`text-block`, ex `text-content`-Feature) und AI-Prompts (`ai-prompt`).
 
 **Plan-Doc:** [`kumiko-platform/docs/plans/features/template-resolver.md`](../../../../../../kumiko-platform/docs/plans/features/template-resolver.md)
 
@@ -38,14 +38,51 @@ async function someHandler(ctx) {
   const template = await templateResolver.resolveTemplate({
     tenantId: ctx.user.tenantId,
     slug: "nka-versand",
-    kind: "mail-html",
+    kind: "mail",
     locale: "de",
   });
-  // template.content + template.variableSchema + template.linkedResources verwenden
+  // template.content + template.meta + template.variableSchema + template.linkedResources verwenden
   // ...
 }
 ```
 
+## Kinds, Format und Meta
+
+| kind | contentFormat | meta |
+|---|---|---|
+| `mail` | `html` (Dokument-Schema, wird serverseitig neu aufgebaut) | Pflicht: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `senderName`, `replyTo` |
+| `mail-layout` | `mjml` | leer (`{}`) oder fehlend |
+| `pdf-layout` | `html` | leer (`{}`) oder fehlend |
+| `document-pdf` | `html` | fehlt |
+| übrige | frei | fehlt |
+
+`meta` liegt als JSON in der Spalte `meta` und wird beim Schreiben pro kind gegen
+`template-meta.ts` geprüft (Fehler als Field-Issues auf `meta.*`). Subject und
+Preview-Text erlauben nur einfache Platzhalter (`{{name}}`, `{{name.feld}}`), keine
+Zeilenumbrüche.
+
+Slugs sind kebab-Segmente, mit `:` verbunden (`templateSlugSchema`); Notification-Templates
+liegen unter ihrem qualifizierten Namen `feature:notify:name`.
+
+## Platzhalter-Validierung (kind `mail`)
+
+Die Variablen kommen aus der Notification mit gleichem qualifiziertem Namen
+(`r.notification({ variables })`), sonst aus `variableSchema` der Zeile. Systemplatzhalter
+(`tenantName`, `signature`, `imprint`, `unsubscribeUrl`) und der Resource-Key `logo` sind immer erlaubt.
+
+- `upsertSystem` und `upsertTenant` lehnen unbekannte Platzhalter ab (Field-Issue auf `content`).
+- `upsertSystem` und `upsertTenant` mit `status: "active"` verlangen zusätzlich, dass jede `required`-Variable benutzt wird. Ein Tenant-Draft darf unvollständig sein und liefert `validation` zurück.
+- `publish` prüft die gespeicherte Zeile erneut.
+- `seedSystemTemplate` wirft bei beiden Problemen.
+
+## Notification-Templates seeden
+
+`r.notification({ variables, template, meta })` bringt Text und Meta mit dem Code mit.
+`seedNotificationTemplates(db, registry)` (aus `.../template-resolver/seeding`) schreibt sie
+pro Locale als System-Template; `applyBootSeeds` ruft das beim Boot auf. Der Code ist
+maßgeblich: geänderte Texte aktualisieren die Zeile, unveränderte erzeugen kein Event.
+Tenant-Overrides bleiben unberührt.
+
 ## Resolver-Reihenfolge (4-Stufen-Fallback)
 
 1. `tenantId` + requested locale
@@ -63,10 +100,10 @@ import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/templat
 // runProdApp seeds — idempotent, default skip if slug exists
 await seedSystemTemplate(db, {
   slug: "welcome-email",
-  kind: "notification",
+  kind: "mail",
   locale: "de",
-  content: JSON.stringify({ header: "Willkommen", sections: [{ text: "…" }] }),
-  contentFormat: "plain",
+  content: '<p>Willkommen, <span data-variable="name"></span></p>',
+  contentFormat: "html",
 });
 ```
 
@@ -80,8 +117,16 @@ await seedSystemTemplate(db, {
 | `TemplateResolverHandlers.upsertTenant` | `template-resolver:write:upsert-tenant` | TenantAdmin (eigener Tenant) + SystemAdmin via `tenantIdOverride` | Erstellt/Updated Tenant-Overrides (scope='tenant'), default-status='draft' |
 | `TemplateResolverHandlers.publish` | `template-resolver:write:publish` | TenantAdmin (eigener Tenant) | Setzt status='active' |
 | `TemplateResolverHandlers.archive` | `template-resolver:write:archive` | TenantAdmin (eigener Tenant) | Setzt status='archived' (Resolver ignoriert es danach) |
+| `TemplateResolverHandlers.publishSystem` | `template-resolver:write:publish-system` | SystemAdmin | Setzt status='active' auf einem System-Default (gleiche Mail-Prüfung wie `publish`) |
+| `TemplateResolverHandlers.archiveSystem` | `template-resolver:write:archive-system` | SystemAdmin | Setzt status='archived' auf einem System-Default; Tenants ohne Override fallen durch |
+| `TemplateResolverHandlers.resetToSystem` | `template-resolver:write:reset-to-system` | TenantAdmin (eigener Tenant) | Archiviert den eigenen Override, sodass wieder die aktive System-Vorlage greift; ohne aktive System-Vorlage `no_system_template` |
 | `TemplateResolverQueries.findById` | `template-resolver:query:find-by-id` | TenantAdmin + User (eigener Tenant + system-templates sichtbar) | Raw-Lookup für Edit-UI |
 | `TemplateResolverQueries.list` | `template-resolver:query:list` | gleich | Filter nach kind/locale/status, optional includeSystem |
+| `TemplateResolverQueries.usage` | `template-resolver:query:usage` | TenantAdmin | Welche Notifications eine Mail-Vorlage bzw. ein Mail-Layout verwenden (aus der Registry) |
+| `TemplateResolverQueries.overview` | `template-resolver:query:overview` | TenantAdmin + SystemAdmin | Eine Zeile je Slug und Art (Mail, PDF, Layouts) mit Herkunft, Sprachen, Status, Version, Layout und Verwendung; durchsuch-, filter-, sortier- und seitenweise lesbar |
+| `TemplateResolverQueries.layoutSource` | `template-resolver:query:layout-source` | TenantAdmin + SystemAdmin | Eigene und System-Fassung eines Layouts, Kopf/Signatur/Fuß-Bereiche der wirksamen html-Fassung, Speicher-Locale; MJML-Quelle nur für SystemAdmin |
+| `TemplateResolverQueries.tenantOverrides` | `template-resolver:query:tenant-overrides` | SystemAdmin | Anzahl aktiver/Entwurf-Overrides einer System-Vorlage und aktive Tenants gesamt, nur Zahlen |
+| `TemplateResolverQueries.diffToSystem` | `template-resolver:query:diff-to-system` | TenantAdmin (eigener Tenant) | Block- und Meta-Vergleich eines Tenant-Overrides mit der System-Vorlage |
 
 **SystemAdmin-Cross-Tenant für publish/archive/findById:** deferred (Task 8) — `upsertTenant` hat `tenantIdOverride` bereits; publish/archive brauchen das erst wenn ein Sysadmin-Panel fremde Tenant-Templates kuratiert. `ctx.db` ist tenant-scoped, fremde IDs → NotFound ohne Override.
 
@@ -92,10 +137,12 @@ upsertSystem  ──┐
                 ├──► status: "active" (System-Default sofort aktiv)
 upsertTenant  ──┴──► status: "draft" (Default) | "active" (explizit)
 
-publish ───────► status: "active"
+publish ───────► status: "active" (übernimmt einen offenen Entwurf)
 archive ───────► status: "archived"
+discardDraft ──► verwirft den Entwurf neben der aktiven Fassung
 ```
 
+Ein Entwurf über einer aktiven Zeile (`upsertTenant` ohne `status`, `copy-locale`, `import-bundle`) liegt als JSON in `draft` neben der Zeile; die Hauptfelder bleiben die ausgelieferte Fassung. `find-by-id` und `layout-source` liefern die Arbeitsfassung (Entwurf, sonst gespeichert) mit `active { version, since }`.
 Resolver returnt **nur** Templates mit `status: "active"`. draft/archived werden ignoriert.
 
 ## Consumer Conformance
@@ -162,7 +209,7 @@ createTemplateResolverFeature({
   collections: [
     {
       id: "reply-snippets",
-      kind: "mail-html",
+      kind: "mail",
       access: { roles: ["Agent", "TenantAdmin"] },
       nav: { label: "mail:nav.snippets", parent: "mail:nav:root" },
     },
@@ -245,6 +292,17 @@ nebeneinander und führt sie in der UI zusammen.
 Unter `tenantIdOverride` (SystemAdmin) bleibt die Zeile die **eigene** des
 Aufrufers im fremden Tenant — ein Admin editiert nie die Signatur eines anderen.
 
+## Validierung, Layouts, Bundles
+
+- `validate` (Query) trocken-läuft die Schreib-Pipeline: `canSave`, `canPublish`, verwendete/unbekannte/fehlende Platzhalter, verfügbare Variablen. `mail`, `document-pdf`, `pdf-layout` und `mail-layout` laufen durch dasselbe Platzhalter-Gate; `page`/`pages` gibt es nur in `document-pdf` und `pdf-layout`.
+- `preview` (Query, TenantAdmin/SystemAdmin) rendert einen Entwurf oder, ohne `content`, die gespeicherte Vorlage mit Beispielwerten aus dem `example` jeder deklarierten Variable (Listen: zwei Zeilen, ohne `example` feste Ersatzwerte). Der Entwurf läuft durch dieselben Gates wie ein Speichern, eine Mail durch den echten Mail-Renderer. Antwort: Betreff, HTML, `displayHtml` (nur Mail: `cid:`-Bilder als Data-URI für den Editor, 5 MiB Budget), Text, Anhänge (`kind: "inline"` mit `cid` oder `kind: "file"`, jeweils mit Größe) und `checks` (`resources_resolved`, `text_present`, `size_under_cap` mit 10 MiB, `required_placeholders`). `document-pdf` liefert den bereinigten Body und die Layout-Regionen, kein PDF.
+- `send-test` (Write, TenantAdmin/SystemAdmin) schickt die gerenderte Mail nur an die eigene Adresse des Aufrufers, Betreff mit `[TEST] `, höchstens 10 pro Nutzer und Stunde. Es gibt keine Empfänger-Eingabe. Braucht `delivery`, `channel-email` und `renderer-mail-html`.
+- Layouts: Tenant-`mail-layout` und `pdf-layout` sind strukturiertes HTML mit `data-content`-Slot und Regionen (Header, Signatur, Footer). Rohes MJML mit `{{{content}}}` genau einmal darf nur das System schreiben.
+- `export-bundle`, `import-bundle`, `import-bundle-system`: ein Template mit allen Locales und Ressourcen-Dateien (base64) als eigenständiges Bundle; bestehende Ziele nur mit `overwrite`. Systemimport mit Ressourcen braucht einen Caller im System-Tenant.
+- `copy-locale`: Startpunkt für Übersetzungen, kopiert als Tenant-Draft. Mit `scope: "system"` (nur SystemAdmin) wird eine Systemvorlage als System-Draft kopiert; andere Aufrufer bekommen 403.
+- Mail-Anhänge: `resource-upload` mit `purpose: "attachment"` und `fileName` legt eine PDF-, PNG- oder JPEG-Datei (geprüft am Inhalt, Originalbytes, höchstens 10 pro Mail-Vorlage) neben den Inline-Bildern ab. `resource-remove`, `copy-locale` und die Bundles tragen sie mit (Bundle-Eintrag `purpose: "attachment"`). Der Mail-Renderer hängt sie nach den Inline-Bildern an.
+- `r.notification(..., { record: { entity, map } })` mappt eine Entity-Zeile auf die deklarierten Variablen (`mapRecordToVariables`); Boot prüft Entity, Variablen und Feldpfade.
+
 ## Out-of-Scope
 
 - Rendering (Markdown/MJML → HTML/PDF) — siehe `renderer-foundation`