@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,255 @@
+# 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`).
+
+**Plan-Doc:** [`kumiko-platform/docs/plans/features/template-resolver.md`](../../../../../../kumiko-platform/docs/plans/features/template-resolver.md)
+
+**Status (2026-05-19):** 45 Integration-Tests grün, typecheck grün, self+advisor-reviewed. Implementierungs-Erkenntnisse im Plan-Doc.
+
+## Mount
+
+```typescript
+// App-Bootstrap
+import {
+  createTemplateResolverApi,
+  createTemplateResolverFeature,
+} from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+
+const features = [
+  createTemplateResolverFeature(),
+  // ... weitere Features
+];
+
+const app = createKumikoApp({
+  features,
+  extraContext: ({ db }) => ({
+    templateResolver: createTemplateResolverApi(db),
+  }),
+});
+```
+
+## Konsumtion (in Feature-Handlern)
+
+```typescript
+import { requireTemplateResolver } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+
+async function someHandler(ctx) {
+  const templateResolver = requireTemplateResolver(ctx, "someHandler");
+  const template = await templateResolver.resolveTemplate({
+    tenantId: ctx.user.tenantId,
+    slug: "nka-versand",
+    kind: "mail-html",
+    locale: "de",
+  });
+  // template.content + template.variableSchema + template.linkedResources verwenden
+  // ...
+}
+```
+
+## Resolver-Reihenfolge (4-Stufen-Fallback)
+
+1. `tenantId` + requested locale
+2. `SYSTEM_TENANT_ID` + requested locale
+3. `tenantId` + `FALLBACK_LOCALE` (default "de")
+4. `SYSTEM_TENANT_ID` + `FALLBACK_LOCALE`
+
+Wenn nichts gefunden → `TemplateNotFoundError`.
+
+## Boot-Seeding (System-Templates)
+
+```typescript
+import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+
+// runProdApp seeds — idempotent, default skip if slug exists
+await seedSystemTemplate(db, {
+  slug: "welcome-email",
+  kind: "notification",
+  locale: "de",
+  content: JSON.stringify({ header: "Willkommen", sections: [{ text: "…" }] }),
+  contentFormat: "plain",
+});
+```
+
+`ifExists: "update"` für autoritative Re-Seeds (z.B. nach Template-Content-Release).
+
+## Admin-Workflows (Write-Handlers + Queries)
+
+| Handler | QN | Wer | Was |
+|---|---|---|---|
+| `TemplateResolverHandlers.upsertSystem` | `template-resolver:write:upsert-system` | SystemAdmin | Erstellt/Updated System-Default-Templates (`SYSTEM_TENANT_ID`, scope='system', status='active') |
+| `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) |
+| `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 |
+
+**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.
+
+## Status-Lifecycle
+
+```
+upsertSystem  ──┐
+                ├──► status: "active" (System-Default sofort aktiv)
+upsertTenant  ──┴──► status: "draft" (Default) | "active" (explizit)
+
+publish ───────► status: "active"
+archive ───────► status: "archived"
+```
+
+Resolver returnt **nur** Templates mit `status: "active"`. draft/archived werden ignoriert.
+
+## Consumer Conformance
+
+Plugins and features that call `resolveTemplate` can verify correct edge-case handling:
+
+```typescript
+import { describe, test } from "bun:test";
+import { runTemplateConsumerConformance } from "@cosmicdrift/kumiko-bundled-features/template-resolver/testing";
+
+describe("my-mail-renderer :: template-resolver conformance", () => {
+  runTemplateConsumerConformance(
+    test,
+    {
+      resolve: (args) => templateResolver.resolveTemplate(args),
+      resolveResources: async (template) => resolveLinkedResources(ctx, template),
+    },
+    { getDb: () => db, tenantId: ctx.user.tenantId },
+  );
+});
+```
+
+The harness checks `TemplateNotFoundError` propagation, locale-fallback, and (when `resolveResources` is provided) missing resource keys.
+
+## Text-Blöcke (`kind: "text-block"`)
+
+Marketing-, FAQ- und Legal-Texte laufen über denselben Store, aber über einen
+eigenen Write-Pfad: `set.write` trägt `title` + `folder` (Content-Tree) und
+kennt keinen draft-Status — Speichern veröffentlicht.
+
+| Handler | QN | Wer | Was |
+|---|---|---|---|
+| `TemplateResolverHandlers.set` | `template-resolver:write:set` | TenantAdmin + SystemAdmin (via `tenantIdOverride` auch auf `SYSTEM_TENANT_ID`) | Upsert einer Ressource pro `(tenantId, slug, kind, locale)` |
+| `TemplateResolverQueries.bySlug` | `template-resolver:query:by-slug` | anonymous + User + Admins | Ein Text-Block — der Public-Read für Landing-/Legal-Pages |
+| `TemplateResolverQueries.byTenant` | `template-resolver:query:by-tenant` | anonymous + User + Admins | Alle Text-Blöcke eines Tenants für den Content-Tree |
+| `<collection>-list` / `-item` / `-set` | `template-resolver:query:<id>-list` … | wie deklariert | Pro Content-Collection, siehe unten |
+
+Die beiden Public-Queries sind fest auf `kind: "text-block"` verdrahtet und
+nehmen **keinen** kind-Parameter. Mail-Templates und AI-Prompts liegen in
+derselben Tabelle und laufen über die Handler ihrer Collection. So kann ein
+neuer kind nicht versehentlich öffentlich lesbar werden.
+
+Seed-Helper: `seedTextBlock` / `seedLegalContentFromJson` aus
+`@cosmicdrift/kumiko-bundled-features/template-resolver/seeding`.
+
+Content-Tree + Editor (Desktop-Web):
+
+```typescript
+import { textBlocksClient } from "@cosmicdrift/kumiko-bundled-features/template-resolver/web";
+
+createKumikoApp({
+  clientFeatures: [textBlocksClient({ navId: "myapp:nav:content", tenantId: SYSTEM_TENANT_ID })],
+});
+```
+
+## Content-Collections
+
+Eine Sammlung erscheint dort in der Nav, wo sie fachlich hingehört — statt alles
+in einen zentralen "Content"-Bereich zu kippen. Deklariert wird sie **beim
+Mounten**, nicht im Feature:
+
+```typescript
+createTemplateResolverFeature({
+  collections: [
+    {
+      id: "reply-snippets",
+      kind: "mail-html",
+      access: { roles: ["Agent", "TenantAdmin"] },
+      nav: { label: "mail:nav.snippets", parent: "mail:nav:root" },
+    },
+    {
+      id: "ai-prompts",
+      kind: "ai-prompt",
+      access: { roles: ["PromptEngineer"] },
+      nav: { label: "mail:nav.prompts", parent: "mail:nav:root" },
+    },
+  ],
+});
+```
+
+`access` gehört an den Mount, weil ein bundled-feature das Rollenvokabular der
+App nicht kennen kann — dasselbe Muster wie die `access`-Option von
+`tags`/`folders`/`ledger`. Ohne Angabe gilt TenantAdmin + SystemAdmin.
+
+Jede Collection bekommt **eigene Handler** — `<id>-list`, `<id>-item`,
+`<id>-set` — die je die Access-Regel ihrer Collection tragen. Deshalb setzt der
+Dispatcher die Trennung durch: wer Snippets pflegen darf, kommt an den
+AI-Prompts nicht vorbei. Ein gemeinsamer Handler mit `kind`-Parameter müsste
+die Vereinigung aller Rollen zulassen und im Body sortieren.
+
+Der Payload trägt entsprechend **keinen** `kind` — `kind`, `ownership` und
+`access` stammen aus der Deklaration. Zwei Collections dürfen denselben `kind`
+mit unterschiedlichen Regeln führen.
+
+`textBlocksClient()` bedient jede deklarierte Collection automatisch: ein
+Folder-Tree pro Collection inklusive SSE-Refresh, Editor-Ziel mit der
+`collectionId`. Die App reicht dafür nichts durch.
+
+`nav.parent` darf auf ein fremdes Feature zeigen. Der Boot-Validator lehnt
+dangling Refs ab — eine Collection unter einem nicht gemounteten Feature lässt
+den Boot scheitern statt still aus der Sidebar zu verschwinden. Die
+Sichtbarkeit des Knotens folgt `access`, sofern `nav.access` nichts anderes
+sagt.
+
+Ein "+" am Knoten braucht ein explizites `nav.createAction` (Ziel ist
+üblicherweise `treeHandle.create`); ohne das listet die Collection nur, was
+schon existiert. `nav.actions` setzt Hover-Actions auf die Zeile.
+
+Speichern **veröffentlicht sofort** — Status `active`, leeres `variableSchema`.
+Wer eine Draft-Stufe oder ein Variablen-Schema braucht, nimmt
+`upsertSystem`/`upsertTenant` + `publish`.
+
+### ownership: user vs. tenant
+
+`ownership: "tenant"` (Default) heißt: ein Satz, den alle im Tenant teilen —
+kuratierte Bausteine, AI-Prompts. `ownership: "user"` heißt: jeder Enduser
+pflegt seine eigenen Einträge — Mail-Signaturen, persönliche Antwort-Bausteine.
+
+User-owned Collections liegen in einer **eigenen Tabelle**
+(`read_user_content_entries`, Entity `user-content-entry`) mit `ownerId NOT
+NULL` und Unique-Index `(tenantId, ownerId, slug, kind, locale)`. Zwei Agents
+können damit beide eine Signatur `standard` haben.
+
+Warum nicht eine Tabelle mit nullbarer `ownerId`: das `content`-Feld dort
+trägt `userOwned` (Name, Telefonnummer, Anschrift → crypto-shredding). Diese
+Annotation wird **pro Entity** aufgelöst, nicht pro Zeile, und
+`resolveSubjectForField` wirft, wenn die Owner-Spalte leer ist — jede
+tenant-weite Mail-Template-Zeile würde beim Schreiben scheitern.
+
+Beim Mounten einer user-owned Collection sind zwei Dinge Pflicht:
+
+1. **Migration.** Die Entity kommt nur in den Schema-Diff, wenn mindestens eine
+   user-owned Collection deklariert ist. Danach in der App
+   `bunx kumiko-schema generate add-user-content` + `apply` — ohne die Tabelle
+   antwortet der Handler in Prod mit 500.
+2. **`template-resolver-user-data` mitmounten.** Die Entity trägt Subject-Daten;
+   ohne den EXT_USER_DATA-Hook verweigert der Boot-Guard den Start. Das Feature
+   liefert den Art.-20-Export; die Löschung (Art. 17) läuft über
+   crypto-shredding, nicht über einen physischen DELETE — der wäre bei einer
+   event-sourced Entity nicht replay-fest.
+
+Der Locale-Fallback von `resolveTemplate` gilt für user-owned Einträge **nicht**:
+sie werden gelistet und editiert, nie als Tenant/System-Override aufgelöst. Wer
+im Client eigene *und* geteilte Bausteine zeigen will, mountet zwei Collections
+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.
+
+## Out-of-Scope
+
+- Rendering (Markdown/MJML → HTML/PDF) — siehe `renderer-foundation`
+- Resource-URL-Substitution (signed-URL vs. data-URI) — Caller-Verantwortung je nach kind
+- Visual Template-Editor — `designer`-Bundle (geplant)
+- A/B-Testing — eigenes Bundle wenn Bedarf real
+
+

package/packages/bundled-features/src/template-resolver/api.ts

@@ -0,0 +1,202 @@
+// TemplateResolverApi — cross-feature interface. renderer-foundation,
+// delivery and apps import types ONLY and take the implementation from
+// ctx.templateResolver at runtime.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { Temporal } from "temporal-polyfill";
+import type { ContentFormat, TemplateKind } from "./constants.js";
+import { FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "./constants.js";
+import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+
+// Public TemplateResource: what consumers see. Hides DB-internal columns
+// (insertedById, internal id-type) but keeps the fields needed for rendering.
+export type TemplateResource = {
+  readonly id: string;
+  readonly version: number;
+  readonly tenantId: string;
+  readonly slug: string;
+  readonly kind: TemplateKind;
+  readonly locale: string;
+  readonly title: string | null;
+  readonly folder: string | null;
+  readonly content: string;
+  readonly contentFormat: ContentFormat;
+  readonly variableSchema: Record<string, unknown>;
+  readonly linkedResources: Record<string, string>;
+  readonly scope: "system" | "tenant";
+  readonly parentTemplateId: string | null;
+  readonly status: "draft" | "active" | "archived";
+  readonly modifiedAt: Temporal.Instant | null;
+};
+
+export type ResolveRequest = {
+  readonly tenantId: TenantId;
+  readonly slug: string;
+  readonly kind: TemplateKind;
+  readonly locale: string;
+};
+
+export type TemplateResolverApi = {
+  /**
+   * Findet ein konkretes Template by (tenantId, slug, kind, locale).
+   * Kein Locale-Fallback, keine Override-Hierarchie — Raw-Lookup für
+   * Admin-UI-Edits und Konformitäts-Tests. Für Render-Aufrufe immer
+   * `resolveTemplate` nutzen.
+   *
+   * `scope: "system"` zwingt Lookup gegen SYSTEM_TENANT_ID (ignoriert
+   * den übergebenen tenantId). Default = Lookup gegen den übergebenen
+   * tenantId direkt (Caller wählt entweder Tenant oder System per
+   * tenantId).
+   */
+  readonly findExact: (args: {
+    readonly tenantId: TenantId;
+    readonly slug: string;
+    readonly kind: TemplateKind;
+    readonly locale: string;
+    readonly scope?: "system";
+  }) => Promise<TemplateResource | null>;
+
+  /**
+   * Resolver mit 4-Stufen-Fallback (siehe template-resolver.md):
+   *   1. tenant + requested-locale
+   *   2. system + requested-locale
+   *   3. tenant + FALLBACK_LOCALE
+   *   4. system + FALLBACK_LOCALE
+   * Resource-Substitution wird hier NICHT ausgeführt — das macht der
+   * Caller (renderer-foundation-Plugin) je nach kind-passendem Modus
+   * (inline-base64 vs. signed-url). API liefert TemplateResource pur.
+   *
+   * **Caller-Invariante:** `tenantId` MUSS vom Server kommen (typisch
+   * `ctx.user.tenantId`). Niemals direkt aus User-Input — sonst kann
+   * User cross-tenant Templates abfragen (Tenant-Isolation gebrochen).
+   */
+  readonly resolveTemplate: (args: ResolveRequest) => Promise<TemplateResource>;
+};
+
+export function createTemplateResolverApi(db: DbConnection): TemplateResolverApi {
+  return {
+    findExact: async ({ tenantId, slug, kind, locale, scope }) => {
+      const effectiveTenantId = scope === "system" ? SYSTEM_TENANT_ID : tenantId;
+      const row = await fetchTemplate(db, effectiveTenantId, slug, kind, locale);
+      return row ? toPublic(row) : null;
+    },
+
+    resolveTemplate: async ({ tenantId, slug, kind, locale }) => {
+      // Fallback-Chain — finde erste passende Variante
+      const candidates: ReadonlyArray<{ tid: string; loc: string }> = [
+        { tid: tenantId, loc: locale },
+        { tid: SYSTEM_TENANT_ID, loc: locale },
+        ...(locale !== FALLBACK_LOCALE
+          ? [
+              { tid: tenantId, loc: FALLBACK_LOCALE },
+              { tid: SYSTEM_TENANT_ID, loc: FALLBACK_LOCALE },
+            ]
+          : []),
+      ];
+      for (const c of candidates) {
+        const row = await fetchTemplate(db, c.tid, slug, kind, c.loc);
+        if (row && row.status === "active") return toPublic(row);
+      }
+      throw new TemplateNotFoundError({ slug, kind, locale });
+    },
+  };
+}
+
+async function fetchTemplate(
+  db: DbConnection,
+  tenantId: string,
+  slug: string,
+  kind: TemplateKind,
+  locale: string,
+): Promise<TemplateResourceRow | null> {
+  const rows = await selectMany(
+    db,
+    templateResourcesTable,
+    { tenantId, slug, kind, locale },
+    { limit: 1 },
+  );
+  // @cast-boundary db-row — db.select returnt unbenanntes unknown[],
+  // Row-Shape ist via templateResourcesTable + buildBaseColumns garantiert.
+  return (rows[0] as TemplateResourceRow | undefined) ?? null;
+}
+
+function toPublic(row: TemplateResourceRow): TemplateResource {
+  // @cast-boundary db-row — Drizzle-Schema typisiert kind/contentFormat/
+  // scope/status als generic text. CHECK-Constraints in der DB schränken
+  // sie auf die Union-Types ein; Cast assertet das Schema-Wissen.
+  // linkedResources ist ein text-column mit JSON-payload (string→string map).
+  const kind = row.kind as TemplateKind;
+  // @cast-boundary db-row — siehe kind.
+  const contentFormat = row.contentFormat as ContentFormat;
+  // @cast-boundary db-row — siehe kind.
+  const scope = row.scope as "system" | "tenant";
+  // @cast-boundary db-row — siehe kind.
+  const status = row.status as "draft" | "active" | "archived";
+  // @cast-boundary db-row — parseJson returnt Record<string, unknown>;
+  // linkedResources-Spalte enthält per Schema {key: signedUrl}-Map.
+  const linkedResources = parseJson(row.linkedResources) as Record<string, string>;
+  return {
+    id: String(row.id),
+    version: row.version,
+    tenantId: row.tenantId,
+    slug: row.slug,
+    kind,
+    locale: row.locale,
+    title: row.title,
+    folder: row.folder,
+    content: row.content ?? "",
+    contentFormat,
+    variableSchema: parseJson(row.variableSchema),
+    linkedResources,
+    scope,
+    parentTemplateId: row.parentTemplateId,
+    status,
+    modifiedAt: row.modifiedAt,
+  };
+}
+
+function parseJson(raw: string | null): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    // @cast-boundary engine-payload — JSON.parse returnt unknown, typeof-Guard
+    // grenzt auf object ein; Record<string, unknown> ist der minimale common-shape.
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export class TemplateNotFoundError extends Error {
+  constructor(public readonly query: { slug: string; kind: TemplateKind; locale: string }) {
+    super(
+      `[template-resolver] no template found for slug="${query.slug}" kind="${query.kind}" locale="${query.locale}" (checked tenant + system, requested + fallback locale)`,
+    );
+    this.name = "TemplateNotFoundError";
+  }
+}
+
+// Single point of truth für "dieser Handler braucht template-resolver".
+// Pattern symmetrisch zu requireTextContent.
+export function requireTemplateResolver(
+  ctx: { readonly templateResolver?: TemplateResolverApi } | object,
+  callerName: string,
+): TemplateResolverApi {
+  // @cast-boundary engine-bridge — templateResolver kommt per extraContext
+  // aus App-Bootstrap, Framework-Container kennt das Feld nicht von sich aus.
+  const api = (ctx as { templateResolver?: TemplateResolverApi }).templateResolver;
+  if (!api) {
+    throw new InternalError({
+      message:
+        `[${callerName}] ctx.templateResolver missing — App-Bootstrap muss ` +
+        `extraContext: { templateResolver: createTemplateResolverApi(db) } setzen ` +
+        `(siehe template-resolver/README.md).`,
+    });
+  }
+  return api;
+}
+
+export type { SessionUser };

package/packages/bundled-features/src/template-resolver/changes.json

@@ -0,0 +1,16 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "TemplateResource and text-block/collection query outputs expose modifiedAt instead of updatedAt",
+    "detail": "Review round 2 fixes across the feature AST, codemods, the template-resolver and the renderer router.\n- feature-ast: handler lookup falls back to the header when the body carries no match, a `zod` namespace import (`import * as z`) is recognised, and patch edits no longer overlap.\n- Codemods: the PII heuristic matches segment-aligned names, the open-to-all codemod sets its exit code, and `failUnprocessable` calls are migrated.\n- template-resolver: the row types and the public output now use the real base columns. `by-slug`, `by-tenant`, `list`, `find-by-id` and the `TemplateResource` API return `modifiedAt` (null until the first edit) instead of `updatedAt`, which was always undefined at runtime. The user-content export reads `modifiedAt` too.\n- renderer: `formatPath` and `parsePath` encode and decode every path segment, so an entity id like `foo/bar` or `ä b` survives a round trip. A malformed percent-escape in the URL resolves to no route.",
+    "migration": "Rename reads of `updatedAt` to `modifiedAt` on TemplateResource, the by-slug, by-tenant, list, find-by-id and collection queries, and the template-resolver web BlockSummary. The old field was never populated at runtime; the new one is an ISO timestamp, or null for a row that was never edited."
+  },
+  {
+    "version": "0.195.0",
+    "type": "breaking",
+    "title": "ContentEditorProps gains a required id (fw#2001).",
+    "detail": "TextBlockEditor's Field wrapping a registered \"rich\"/\"plain\" editor pointed its htmlFor at the fixed CONTENT_EDITOR_ELEMENT_ID, which only the never-mounted textarea fallback actually used — the label was disconnected from the real input as soon as a collection declared contentFormat: \"rich\" or \"plain\". TextBlockEditor now generates a per-instance id via useId() and passes it to both the Field and the ContentEditor, so the label stays correctly associated and two editors mounted on the same page no longer collide on a shared DOM id.",
+    "migration": "A custom-registered content editor component now needs to accept and use this id prop, rendering it onto its own focusable root element. Consumers that don't touch the DOM id directly are unaffected. CONTENT_EDITOR_ELEMENT_ID stays exported as a default value for callers that don't need their own generated id."
+  }
+]

package/packages/bundled-features/src/template-resolver/constants.ts

@@ -0,0 +1,54 @@
+// @runtime client
+// Plain data, no imports — the content tree in web/ needs TEXT_BLOCK_KIND to
+// pick between the public and the admin query.
+//
+// RenderKind identifiziert die Konsumenten-Klasse eines Templates.
+// Plugin-Renderer in `renderer-foundation` matchen auf kind; der
+// Resolver hier ist kind-agnostisch — er lädt nur, das Content-Format
+// (markdown/mjml/html) entscheidet wer's rendert.
+export const RENDER_KINDS = [
+  "notification",
+  "mail-html",
+  "document-pdf",
+  "image-snapshot",
+] as const;
+export type RenderKind = (typeof RENDER_KINDS)[number];
+
+// Kinds without a renderer plugin: `text-block` is the Markdown text store
+// (ex text-content feature), `ai-prompt` holds LLM prompts. Both are read,
+// not rendered — keeping them out of RENDER_KINDS is what stops
+// DEFAULT_PLUGIN_BY_KIND from demanding a plugin for them.
+export const NON_RENDER_KINDS = ["text-block", "ai-prompt"] as const;
+export type NonRenderKind = (typeof NON_RENDER_KINDS)[number];
+
+// Full kind domain of the entity; RENDER_KINDS is the renderer-foundation subset.
+export const TEMPLATE_KINDS = [...RENDER_KINDS, ...NON_RENDER_KINDS] as const;
+export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
+
+// Kinds written through upsertSystem/upsertTenant. `text-block` is absent on
+// purpose: it goes through set.write (title + folder tree); two write paths
+// onto the same row would drift apart.
+export const UPSERT_KINDS = [...RENDER_KINDS, "ai-prompt"] as const;
+export type UpsertKind = (typeof UPSERT_KINDS)[number];
+
+// The only kind served by the anonymous-capable by-slug/by-tenant queries and
+// by set.write — mail templates and AI prompts are operational internals and
+// must not leak through the anonymous path.
+export const TEXT_BLOCK_KIND = "text-block" as const;
+
+export const CONTENT_FORMATS = ["markdown", "mjml", "html", "plain"] as const;
+export type ContentFormat = (typeof CONTENT_FORMATS)[number];
+
+export const TEMPLATE_SCOPES = ["system", "tenant"] as const;
+export type TemplateScope = (typeof TEMPLATE_SCOPES)[number];
+
+export const TEMPLATE_STATUSES = ["draft", "active", "archived"] as const;
+export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
+
+// System-Templates leben unter der canonical SYSTEM_TENANT_ID-Sentinel-UUID.
+// Re-Export aus framework — single source of truth, vermeidet Drift.
+export { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+// Default-Locale wenn Tenant keinen eigenen Default konfiguriert. Resolver
+// fällt darauf zurück wenn requested locale + tenant-default fehlen.
+export const FALLBACK_LOCALE = "de";

package/packages/bundled-features/src/template-resolver/feature.ts

@@ -0,0 +1,99 @@
+import {
+  type ContentCollectionDefinition,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { bySlugQuery } from "./handlers/by-slug.query.js";
+import { byTenantQuery } from "./handlers/by-tenant.query.js";
+import { makeCollectionItemQuery } from "./handlers/collection-item.query.js";
+import { makeCollectionListQuery } from "./handlers/collection-list.query.js";
+import { makeCollectionSetWrite } from "./handlers/collection-set.write.js";
+import { findByIdQuery } from "./handlers/find-by-id.query.js";
+import { listQuery } from "./handlers/list.query.js";
+import { setWrite } from "./handlers/set.write.js";
+import { archiveWrite, publishWrite } from "./handlers/toggle-status.write.js";
+import { upsertSystemWrite } from "./handlers/upsert-system.write.js";
+import { upsertTenantWrite } from "./handlers/upsert-tenant.write.js";
+import { templateResourceEntity } from "./table.js";
+import { userContentEntryEntity } from "./user-content-table.js";
+
+// template-resolver — structured template storage with tenant-override
+// hierarchy, locale fallback and resource linking via file-foundation.
+// Plan doc: kumiko-platform/docs/plans/features/template-resolver.md
+//
+// Consumption paths:
+//   - Render time: ctx.templateResolver.resolveTemplate(...) (see api.ts)
+//   - Admin UI: write/query handlers (upsertSystem, upsertTenant, publish, archive, findById, list)
+//   - Cross-feature: requireTemplateResolver(ctx, callerName)
+export type TemplateResolverOptions = {
+  /** Content collections this app mounts. Declared here rather than inside the
+   *  feature because `access` needs the host's role vocabulary — a bundled
+   *  feature cannot know that an app calls its support staff "Agent". Same
+   *  reasoning as the `access` option on tags/folders/ledger.
+   *
+   *  Each collection gets its own list/item/set handlers named
+   *  `<id>-list` / `<id>-item` / `<id>-set`, each carrying that collection's
+   *  access rule, so the dispatcher enforces the separation instead of a
+   *  branch in a shared handler. */
+  readonly collections?: readonly ContentCollectionDefinition[];
+};
+
+export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}) {
+  const collections = opts.collections ?? [];
+  const hasUserOwned = collections.some((c) => c.ownership === "user");
+  return defineFeature("template-resolver", (r) => {
+    r.describe(
+      [
+        "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-html`, `document-pdf`, `ai-prompt`, `text-block`, `image-snapshot`).",
+        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers.",
+        "Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.",
+        "How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).",
+        'A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.',
+        "Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
+      ].join("\n\n"),
+    );
+    r.uiHints({
+      displayLabel: "Template Resolver",
+      category: "notifications",
+      recommended: false,
+    });
+    r.entity("template-resource", templateResourceEntity);
+    // Only when the app actually mounts a user-owned collection: the entity's
+    // `content` is `userOwned`, which makes it subject data — the boot guard
+    // then requires an EXT_USER_DATA hook (mount `template-resolver-user-data`).
+    // Registering it unconditionally would impose that on every app.
+    if (hasUserOwned) r.entity("user-content-entry", userContentEntryEntity);
+
+    const handlers = {
+      upsertSystem: r.writeHandler(upsertSystemWrite),
+      upsertTenant: r.writeHandler(upsertTenantWrite),
+      publish: r.writeHandler(publishWrite),
+      archive: r.writeHandler(archiveWrite),
+      set: r.writeHandler(setWrite),
+    };
+
+    const queries = {
+      findById: r.queryHandler(findByIdQuery),
+      list: r.queryHandler(listQuery),
+      bySlug: r.queryHandler(bySlugQuery),
+      byTenant: r.queryHandler(byTenantQuery),
+    };
+
+    for (const collection of collections) {
+      r.contentCollection(collection);
+      r.queryHandler(makeCollectionListQuery(collection));
+      r.queryHandler(makeCollectionItemQuery(collection));
+      r.writeHandler(makeCollectionSetWrite(collection));
+    }
+
+    // Visual-tree actions for the text-block content tree. The handle is
+    // propagated through the setup export so other features can build
+    // compile-time-typed cross-feature edit targets.
+    const treeHandle = r.treeActions({
+      edit: { args: { slug: "" as string, locale: "" as string } },
+      list: {},
+      create: { args: { folder: "" as string } },
+    });
+
+    return { handlers, queries, treeHandle };
+  });
+}