@cosmicdrift/kumiko-bundled-features 0.3.0 → 0.4.0

package/src/template-resolver/api.ts

@@ -0,0 +1,189 @@
+// TemplateResolverApi — Cross-Feature-Schnittstelle. renderer-foundation
+// + delivery + Apps importieren NUR Types und holen die Implementation
+// runtime aus ctx.templateResolver. Pattern symmetrisch zu textContent
+// (siehe text-content/api.ts).
+
+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 { and, eq } from "drizzle-orm";
+import type { ContentFormat, RenderKind } from "./constants";
+import { FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "./constants";
+import { type TemplateResourceRow, templateResourcesTable } from "./table";
+
+// Public TemplateResource — was Konsumenten sehen. Versteckt DB-interne
+// Spalten (createdBy, internal id-type), behält Felder die zum Rendern
+// gebraucht werden.
+export type TemplateResource = {
+  readonly id: string;
+  readonly version: number;
+  readonly tenantId: string;
+  readonly slug: string;
+  readonly kind: RenderKind;
+  readonly locale: string;
+  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 updatedAt: Date;
+};
+
+export type ResolveRequest = {
+  readonly tenantId: TenantId;
+  readonly slug: string;
+  readonly kind: RenderKind;
+  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: RenderKind;
+    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: RenderKind,
+  locale: string,
+): Promise<TemplateResourceRow | null> {
+  const rows = await db
+    .select()
+    .from(templateResourcesTable)
+    .where(
+      and(
+        eq(templateResourcesTable["tenantId"], tenantId),
+        eq(templateResourcesTable["slug"], slug),
+        eq(templateResourcesTable["kind"], kind),
+        eq(templateResourcesTable["locale"], 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 {
+  return {
+    id: String(row.id),
+    version: row.version,
+    tenantId: row.tenantId,
+    slug: row.slug,
+    kind: row.kind as RenderKind,
+    locale: row.locale,
+    content: row.content ?? "",
+    contentFormat: row.contentFormat as ContentFormat,
+    variableSchema: parseJson(row.variableSchema),
+    linkedResources: parseJson(row.linkedResources) as Record<string, string>,
+    scope: row.scope as "system" | "tenant",
+    parentTemplateId: row.parentTemplateId,
+    status: row.status as "draft" | "active" | "archived",
+    updatedAt: row.updatedAt,
+  };
+}
+
+function parseJson(raw: string | null): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    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: RenderKind; 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/src/template-resolver/constants.ts

@@ -0,0 +1,28 @@
+// 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];
+
+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/src/template-resolver/feature.ts

@@ -0,0 +1,36 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { archiveWrite } from "./handlers/archive.write";
+import { findByIdQuery } from "./handlers/find-by-id.query";
+import { listQuery } from "./handlers/list.query";
+import { publishWrite } from "./handlers/publish.write";
+import { upsertSystemWrite } from "./handlers/upsert-system.write";
+import { upsertTenantWrite } from "./handlers/upsert-tenant.write";
+import { templateResourceEntity } from "./table";
+
+// template-resolver — strukturierter Template-Storage mit Tenant-
+// Override-Hierarchie, Locale-Fallback und Resource-Linking via
+// file-foundation. Plan-Doc: kumiko-platform/docs/plans/features/template-resolver.md
+//
+// Konsumtions-Pfade:
+//   - Render-Time: ctx.templateResolver.resolveTemplate(...) (siehe api.ts)
+//   - Admin-UI: write/query-handlers (upsertSystem, upsertTenant, publish, archive, findById, list)
+//   - Cross-Feature: requireTemplateResolver(ctx, callerName) — Pattern wie requireTextContent
+export function createTemplateResolverFeature() {
+  return defineFeature("template-resolver", (r) => {
+    r.entity("template-resource", templateResourceEntity);
+
+    const handlers = {
+      upsertSystem: r.writeHandler(upsertSystemWrite),
+      upsertTenant: r.writeHandler(upsertTenantWrite),
+      publish: r.writeHandler(publishWrite),
+      archive: r.writeHandler(archiveWrite),
+    };
+
+    const queries = {
+      findById: r.queryHandler(findByIdQuery),
+      list: r.queryHandler(listQuery),
+    };
+
+    return { handlers, queries };
+  });
+}

package/src/template-resolver/handlers/archive.write.ts

@@ -0,0 +1,42 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import type { TemplateResourceRow } from "../table";
+import { templateResourcesTable } from "../table";
+import { executor } from "./shared";
+
+// Setzt einen Template-Eintrag auf status='archived'. Resolver liefert
+// archivierte Templates nicht zurück — sie bleiben aber als Audit-Trail
+// in der DB (kein physisches Delete). Reaktivierung via publish.
+export const archiveWrite = defineWriteHandler({
+  name: "archive",
+  schema: z.object({ id: z.string().min(1) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const existing = await fetchOne<TemplateResourceRow>(
+      ctx.db,
+      templateResourcesTable,
+      eq(templateResourcesTable["id"], event.payload.id),
+    );
+    // ctx.db ist via createTenantDb tenant-scoped — existing ist null wenn
+    // das Template einem fremden Tenant gehört (SystemAdmin-Cross-Tenant
+    // braucht tenantIdOverride im Schema, M2-Erweiterung).
+    if (!existing) {
+      return writeFailure(new NotFoundError("template-resource", event.payload.id));
+    }
+
+    const result = await executor.update(
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: { status: "archived" as const },
+      },
+      event.user,
+      ctx.db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true as const, data: { id: String(existing.id), status: "archived" } };
+  },
+});

package/src/template-resolver/handlers/find-by-id.query.ts

@@ -0,0 +1,45 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { type TemplateResourceRow, templateResourcesTable } from "../table";
+
+// Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
+// archived Status. Tenant-Isolation: User sieht nur Templates des
+// eigenen Tenants oder SYSTEM_TENANT (system-defaults sind public-
+// readable). SystemAdmin sieht alle. Anonymous bleibt aus — Public-
+// Read geht über resolveTemplate aus der API, nicht hier.
+export const findByIdQuery = defineQueryHandler({
+  name: "find-by-id",
+  schema: z.object({ id: z.string().min(1) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin", "User"] },
+  handler: async (query, ctx) => {
+    const row = await fetchOne<TemplateResourceRow>(
+      ctx.db,
+      templateResourcesTable,
+      eq(templateResourcesTable["id"], query.payload.id),
+    );
+    if (!row) return null;
+    const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+    const isOwnTenant = row.tenantId === query.user.tenantId;
+    const isSystemTemplate = row.scope === "system";
+    if (!isSystemAdmin && !isOwnTenant && !isSystemTemplate) return null;
+
+    return {
+      id: String(row.id),
+      version: row.version,
+      tenantId: row.tenantId,
+      slug: row.slug,
+      kind: row.kind,
+      locale: row.locale,
+      content: row.content,
+      contentFormat: row.contentFormat,
+      variableSchema: row.variableSchema,
+      linkedResources: row.linkedResources,
+      scope: row.scope,
+      parentTemplateId: row.parentTemplateId,
+      status: row.status,
+      updatedAt: row.updatedAt,
+    };
+  },
+});

package/src/template-resolver/handlers/list.query.ts

@@ -0,0 +1,69 @@
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { and, eq, or, type SQL } from "drizzle-orm";
+import { z } from "zod";
+import { RENDER_KINDS, TEMPLATE_STATUSES } from "../constants";
+import { type TemplateResourceRow, templateResourcesTable } from "../table";
+
+// List für Admin-UI: filterbar nach kind / locale / status. Liefert
+// system-templates + tenant's eigene zusammen — Admin-UI rendert beide
+// Spalten mit scope-marker. SystemAdmin sieht alle (auch andere Tenants).
+export const listQuery = defineQueryHandler({
+  name: "list",
+  schema: z.object({
+    kind: z.enum(RENDER_KINDS).optional(),
+    locale: z.string().min(2).max(8).optional(),
+    status: z.enum(TEMPLATE_STATUSES).optional(),
+    includeSystem: z.boolean().default(true),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin", "User"] },
+  handler: async (query, ctx) => {
+    const isSystemAdmin = query.user.roles.includes("SystemAdmin");
+    const conditions: SQL<unknown>[] = [];
+
+    // Tenant-Scope: SystemAdmin sieht alles, andere nur eigener Tenant + System
+    if (!isSystemAdmin) {
+      if (query.payload.includeSystem) {
+        const scopeCondition = or(
+          eq(templateResourcesTable["tenantId"], query.user.tenantId),
+          eq(templateResourcesTable["tenantId"], SYSTEM_TENANT_ID),
+        );
+        if (scopeCondition) conditions.push(scopeCondition);
+      } else {
+        conditions.push(eq(templateResourcesTable["tenantId"], query.user.tenantId));
+      }
+    } else if (!query.payload.includeSystem) {
+      // SystemAdmin mit includeSystem=false → noch eigener Tenant only
+      conditions.push(eq(templateResourcesTable["tenantId"], query.user.tenantId));
+    }
+
+    if (query.payload.kind) {
+      conditions.push(eq(templateResourcesTable["kind"], query.payload.kind));
+    }
+    if (query.payload.locale) {
+      conditions.push(eq(templateResourcesTable["locale"], query.payload.locale));
+    }
+    if (query.payload.status) {
+      conditions.push(eq(templateResourcesTable["status"], query.payload.status));
+    }
+
+    const whereExpr = conditions.length > 0 ? and(...conditions) : undefined;
+
+    const rows = (await ctx.db
+      .select()
+      .from(templateResourcesTable)
+      .where(whereExpr)
+      .limit(500)) as TemplateResourceRow[];
+
+    return rows.map((row) => ({
+      id: String(row.id),
+      tenantId: row.tenantId,
+      slug: row.slug,
+      kind: row.kind,
+      locale: row.locale,
+      scope: row.scope,
+      status: row.status,
+      contentFormat: row.contentFormat,
+      updatedAt: row.updatedAt,
+    }));
+  },
+});

package/src/template-resolver/handlers/publish.write.ts

@@ -0,0 +1,45 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import type { TemplateResourceRow } from "../table";
+import { templateResourcesTable } from "../table";
+import { executor } from "./shared";
+
+// Setzt einen Template-Eintrag auf status='active'. Typischer Workflow:
+// User editiert ein Draft, ist zufrieden, drückt Publish.
+//
+// Tenant-Isolation: Template muss zum event.user.tenantId gehören
+// (oder zu SYSTEM_TENANT wenn SystemAdmin). Cross-Tenant-Publish-
+// Versuche → NotFound (Pattern aus row-level-security).
+export const publishWrite = defineWriteHandler({
+  name: "publish",
+  schema: z.object({ id: z.string().min(1) }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const existing = await fetchOne<TemplateResourceRow>(
+      ctx.db,
+      templateResourcesTable,
+      eq(templateResourcesTable["id"], event.payload.id),
+    );
+    // ctx.db ist via createTenantDb tenant-scoped — existing ist null wenn
+    // das Template einem fremden Tenant gehört (SystemAdmin-Cross-Tenant
+    // braucht tenantIdOverride im Schema, M2-Erweiterung).
+    if (!existing) {
+      return writeFailure(new NotFoundError("template-resource", event.payload.id));
+    }
+
+    const result = await executor.update(
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: { status: "active" as const },
+      },
+      event.user,
+      ctx.db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true as const, data: { id: String(existing.id), status: "active" } };
+  },
+});

package/src/template-resolver/handlers/shared.ts

@@ -0,0 +1,41 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { z } from "zod";
+import { CONTENT_FORMATS, RENDER_KINDS, TEMPLATE_STATUSES } from "../constants";
+import { templateResourceEntity, templateResourcesTable } from "../table";
+
+// Single executor pro Bundle — Pattern aus text-content. Wird von allen
+// 4 Handlers geteilt für create/update-Operationen mit Event-Store +
+// Optimistic-Lock.
+export const executor = createEventStoreExecutor(templateResourcesTable, templateResourceEntity, {
+  entityName: "template-resource",
+});
+
+// Slug-Regex symmetrisch zu text-content + plan-doc naming-convention.
+export const slugSchema = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(/^[a-z0-9][a-z0-9-]*$/, "slug must be kebab-case (lowercase, digits, dashes)");
+
+export const localeSchema = z
+  .string()
+  .min(2)
+  .max(8)
+  .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "locale must be ISO 639-1 (e.g. de, en, en-us)");
+
+export const kindSchema = z.enum(RENDER_KINDS);
+export const contentFormatSchema = z.enum(CONTENT_FORMATS);
+export const statusSchema = z.enum(TEMPLATE_STATUSES);
+
+// Common Upsert-Payload — geteilt zwischen upsertSystem + upsertTenant.
+// Unterschied: ACL + tenantId-Bestimmung, sonst identisch.
+export const upsertPayloadSchema = z.object({
+  slug: slugSchema,
+  kind: kindSchema,
+  locale: localeSchema,
+  content: z.string().max(200_000),
+  contentFormat: contentFormatSchema,
+  variableSchema: z.record(z.string(), z.unknown()).default({}),
+  linkedResources: z.record(z.string(), z.string()).default({}),
+  parentTemplateId: z.string().min(1).optional(),
+});

package/src/template-resolver/handlers/upsert-system.write.ts

@@ -0,0 +1,75 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import type { TemplateResourceRow } from "../table";
+import { templateResourcesTable } from "../table";
+import { executor, upsertPayloadSchema } from "./shared";
+
+// System-Template anlegen/updaten. Liegt unter SYSTEM_TENANT_ID,
+// scope='system'. Nur SystemAdmin (globale Rolle). TenantAdmin kann
+// keine System-Defaults überschreiben — der nutzt upsertTenant für
+// Overrides.
+export const upsertSystemWrite = defineWriteHandler({
+  name: "upsert-system",
+  schema: upsertPayloadSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+    const tenantId = SYSTEM_TENANT_ID as TenantId;
+    // executor-user muss SYSTEM_TENANT als tenantId haben, sonst sucht
+    // event-store stream unter user.tenantId statt SYSTEM_TENANT → conflict.
+    // Pattern symmetrisch zu text-content setWrite Override-Branch.
+    const executorUser = { ...event.user, tenantId };
+
+    const existing = await fetchOne<TemplateResourceRow>(
+      db,
+      templateResourcesTable,
+      eq(templateResourcesTable["tenantId"], tenantId),
+      eq(templateResourcesTable["slug"], event.payload.slug),
+      eq(templateResourcesTable["kind"], event.payload.kind),
+      eq(templateResourcesTable["locale"], event.payload.locale),
+    );
+
+    const fields = {
+      slug: event.payload.slug,
+      kind: event.payload.kind,
+      locale: event.payload.locale,
+      content: event.payload.content,
+      contentFormat: event.payload.contentFormat,
+      variableSchema: JSON.stringify(event.payload.variableSchema),
+      linkedResources: JSON.stringify(event.payload.linkedResources),
+      scope: "system" as const,
+      parentTemplateId: event.payload.parentTemplateId ?? null,
+      // System-Defaults sind sofort active (kein draft-Stage für seeds).
+      status: "active" as const,
+    };
+
+    if (existing) {
+      const result = await executor.update(
+        { id: existing.id, version: existing.version, changes: fields },
+        executorUser,
+        db,
+      );
+      if (!result.isSuccess) return result;
+      return {
+        isSuccess: true as const,
+        data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
+      };
+    }
+
+    const result = await executor.create({ ...fields, tenantId }, executorUser, db);
+    if (!result.isSuccess) return result;
+    return {
+      isSuccess: true as const,
+      data: {
+        id: String((result.data as { id: string | number }).id),
+        slug: event.payload.slug,
+        isNew: true,
+      },
+    };
+  },
+});

package/src/template-resolver/handlers/upsert-tenant.write.ts

@@ -0,0 +1,98 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import type { TemplateResourceRow } from "../table";
+import { templateResourcesTable } from "../table";
+import { executor, upsertPayloadSchema } from "./shared";
+
+// Tenant-Override anlegen/updaten. Liegt unter event.user.tenantId,
+// scope='tenant'. Default-Status='draft' — User publisht explizit
+// via publish-Handler. SystemAdmin kann via tenantIdOverride für
+// einen anderen Tenant schreiben (typisch: Plattform-Admin-UI das
+// Tenant-Templates kuratiert).
+export const upsertTenantWrite = defineWriteHandler({
+  name: "upsert-tenant",
+  schema: upsertPayloadSchema.extend({
+    tenantIdOverride: z.string().min(1).optional(),
+    status: z.enum(["draft", "active"]).default("draft"),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const db = ctx.db;
+    const override = event.payload.tenantIdOverride;
+    if (override !== undefined && !event.user.roles.includes("SystemAdmin")) {
+      return writeFailure(
+        new AccessDeniedError({
+          i18nKey: "templateResolver.errors.tenantOverrideRequiresSystemAdmin",
+          details: { reason: "tenant_override_requires_system_admin" },
+        }),
+      );
+    }
+    // upsertTenant erzeugt scope='tenant'. SYSTEM_TENANT_ID-Override würde
+    // scope='tenant' unter SYSTEM_TENANT_ID schreiben → inkonsistenter Zustand
+    // (Resolver-Logik trennt sauber zwischen system+tenant). SystemAdmin muss
+    // upsertSystem für System-Defaults nutzen.
+    if (override === SYSTEM_TENANT_ID) {
+      return writeFailure(
+        new AccessDeniedError({
+          i18nKey: "templateResolver.errors.useUpsertSystemForSystemTenant",
+          details: { reason: "system_tenant_override_not_allowed_use_upsert_system" },
+        }),
+      );
+    }
+    const tenantId = (override ?? event.user.tenantId) as TenantId;
+    const executorUser = override !== undefined ? { ...event.user, tenantId } : event.user;
+
+    const existing = await fetchOne<TemplateResourceRow>(
+      db,
+      templateResourcesTable,
+      eq(templateResourcesTable["tenantId"], tenantId),
+      eq(templateResourcesTable["slug"], event.payload.slug),
+      eq(templateResourcesTable["kind"], event.payload.kind),
+      eq(templateResourcesTable["locale"], event.payload.locale),
+    );
+
+    const fields = {
+      slug: event.payload.slug,
+      kind: event.payload.kind,
+      locale: event.payload.locale,
+      content: event.payload.content,
+      contentFormat: event.payload.contentFormat,
+      variableSchema: JSON.stringify(event.payload.variableSchema),
+      linkedResources: JSON.stringify(event.payload.linkedResources),
+      scope: "tenant" as const,
+      parentTemplateId: event.payload.parentTemplateId ?? null,
+      status: event.payload.status,
+    };
+
+    if (existing) {
+      const result = await executor.update(
+        { id: existing.id, version: existing.version, changes: fields },
+        executorUser,
+        db,
+      );
+      if (!result.isSuccess) return result;
+      return {
+        isSuccess: true as const,
+        data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
+      };
+    }
+
+    const result = await executor.create({ ...fields, tenantId }, executorUser, db);
+    if (!result.isSuccess) return result;
+    return {
+      isSuccess: true as const,
+      data: {
+        id: String((result.data as { id: string | number }).id),
+        slug: event.payload.slug,
+        isNew: true,
+      },
+    };
+  },
+});