@cosmicdrift/kumiko-bundled-features 0.2.3 → 0.4.0

package/src/renderer-foundation/types.ts

@@ -0,0 +1,109 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ContentFormat, RenderKind } from "./constants";
+
+// RenderRequest — Plugins erhalten das. Resource-Mode wählt der Caller
+// (renderer-foundation api) je nach kind oder explizit. Plugin selbst
+// entscheidet nicht — es bekommt eine schon aufgelöste Form.
+export type RenderRequest =
+  | { kind: "notification"; payload: NotificationPayload }
+  | { kind: "mail-html"; payload: MailHtmlPayload }
+  | { kind: "document-pdf"; payload: DocumentPayload; options?: PdfOptions }
+  | { kind: "image-snapshot"; payload: DocumentPayload; options?: ImageOptions };
+
+export type RenderResponse =
+  | { kind: "notification"; html: string }
+  | { kind: "mail-html"; html: string; text: string }
+  | { kind: "document-pdf"; pdfBytes: Uint8Array; pageCount: number; sizeBytes: number }
+  | {
+      kind: "image-snapshot";
+      imageBytes: Uint8Array;
+      format: "png" | "jpg";
+      width: number;
+      height: number;
+    };
+
+export type NotificationPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+export type MailHtmlPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+  readonly subject?: string;
+};
+
+export type DocumentPayload = {
+  readonly template?: string;
+  readonly content?: string;
+  readonly contentFormat?: ContentFormat;
+  readonly variables?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+export type PdfOptions = {
+  readonly format?: "A4" | "Letter";
+  readonly marginMm?: { top?: number; right?: number; bottom?: number; left?: number };
+  readonly headerTemplate?: string;
+  readonly footerTemplate?: string;
+  readonly printBackground?: boolean;
+  readonly displayHeaderFooter?: boolean;
+};
+
+export type ImageOptions = {
+  readonly width?: number;
+  readonly height?: number;
+  readonly format?: "png" | "jpg";
+  readonly quality?: number;
+};
+
+// RendererContext — schmale Surface (Kumiko-Style, matcht FileProviderContext
+// + ChannelContext). Plugins, die Service-Access brauchen, holen sich
+// templateResolver/etc. via direkten Bundle-Import + ctx.db (cross-feature-
+// public-API). KEIN extraContext-Pass-Through — Plugin importiert pure-
+// Function-Factories statt App-ctx zu casten.
+//
+// **Beispiel renderer-mail-html:**
+//   import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+//   const tplApi = createTemplateResolverApi(ctx.db);
+//   const layout = await tplApi.resolveTemplate({ tenantId: ctx.tenantId, slug, kind });
+export type RendererContext = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+};
+
+// RendererPlugin-Contract — pro Plugin (renderer-simple, renderer-mail-html,
+// renderer-puppeteer-client). Plugin deklariert welche kinds es bedienen
+// kann; Foundation-Resolver wählt basierend auf Tenant-Config + kind.
+//
+// **Plugin-Invarianten:**
+// - `kinds` muss min. 1 Element haben (sonst nie ausgewählt)
+// - `render(req, ctx)`-Response.kind MUSS req.kind matchen
+// - Plugin ist zustandslos: kein internal-state zwischen render-Calls
+// - Plugin wirft `RendererError` für domain-Fehler (nicht bare Error)
+// - `ctx` ist required. Plugins ohne Service-Deps (z.B. renderer-simple)
+//   ignorieren ihn einfach — TS function-arg variance erlaubt `(req) => ...`-
+//   Implementations weiterhin (Implementation-Args ≤ Contract-Args ist OK).
+export type RendererPlugin = {
+  readonly name: string;
+  readonly kinds: ReadonlyArray<RenderKind>;
+  render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+};
+
+export class RendererError extends Error {
+  constructor(
+    message: string,
+    public readonly code: "no_plugin_for_kind" | "invalid_payload" | "other",
+  ) {
+    super(message);
+    this.name = "RendererError";
+  }
+}

package/src/renderer-simple/__tests__/adapter.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { RendererError } from "../../renderer-foundation";
+import { adaptToFoundation } from "../feature";
+
+describe("renderer-simple :: adaptToFoundation", () => {
+  test("kind='notification' rendert via simpleRenderer und gibt RenderResponse zurück", async () => {
+    const res = await adaptToFoundation({
+      kind: "notification",
+      payload: {
+        template: "welcome",
+        variables: { title: "Welcome!", body: "Hello there" },
+      },
+    });
+    expect(res.kind).toBe("notification");
+    if (res.kind === "notification") {
+      // simpleRenderer baut HTML mit title als header + body als section
+      expect(res.html).toContain("Welcome!");
+      expect(res.html).toContain("Hello there");
+      expect(res.html).toContain("<!DOCTYPE html>");
+    }
+  });
+
+  test("leere variables → leerer body, kein crash", async () => {
+    const res = await adaptToFoundation({
+      kind: "notification",
+      payload: { template: "", variables: {} },
+    });
+    expect(res.kind).toBe("notification");
+  });
+
+  test("non-notification kind → RendererError mit code 'invalid_payload'", async () => {
+    await expect(
+      adaptToFoundation({
+        kind: "mail-html",
+        payload: { content: "test", contentFormat: "markdown" },
+      }),
+    ).rejects.toThrow(RendererError);
+
+    try {
+      await adaptToFoundation({
+        kind: "document-pdf",
+        payload: { content: "test", contentFormat: "markdown" },
+      });
+      expect.fail("expected RendererError");
+    } catch (e) {
+      expect(e).toBeInstanceOf(RendererError);
+      expect((e as RendererError).code).toBe("invalid_payload");
+    }
+  });
+});

package/src/renderer-simple/feature.ts

@@ -1,12 +1,37 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { RendererError, type RenderRequest, type RenderResponse } from "../renderer-foundation";
 import { simpleRenderer } from "./simple-renderer";
 
+// Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
+// NotificationRenderer-Contract), renderer-foundation erwartet
+// `Promise<RenderResponse>` mit discriminated union. Mapper bewahrt
+// die simpleRenderer-Implementierung (Template-Strings → HTML mit
+// Inline-CSS) und packt sie in den RendererPlugin-Contract.
+//
+// Exported damit der Adapter-Pfad direkt testbar ist (unit-test).
+export async function adaptToFoundation(req: RenderRequest): Promise<RenderResponse> {
+  if (req.kind !== "notification") {
+    // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
+    // dieser Pfad sollte unter normalen Umständen nie erreicht werden.
+    throw new RendererError(
+      `renderer-simple supports only kind="notification", got "${req.kind}"`,
+      "invalid_payload",
+    );
+  }
+  const html = await simpleRenderer.render({
+    template: req.payload.template ?? "",
+    variables: req.payload.variables ?? {},
+  });
+  return { kind: "notification", html };
+}
+
 export function createRendererSimpleFeature(): FeatureDefinition {
   return defineFeature("rendererSimple", (r) => {
-    r.requires("delivery");
+    r.requires("renderer-foundation");
 
-    r.useExtension("notificationRenderer", "simple", {
-      render: simpleRenderer.render,
+    r.useExtension("renderer", "simple", {
+      kinds: ["notification"] as const,
+      render: adaptToFoundation,
     });
   });
 }

package/src/renderer-simple/simple-renderer.ts

@@ -38,7 +38,7 @@ export const simpleRenderer: NotificationRenderer = {
   name: "simple",
 
   async render(input) {
-    const data = input.variables as EmailTemplateData;
+    const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
 
     // Fallback: if no structured fields, use title + body as header + single text section
     const header = data.header ?? data.title;

package/src/secrets/handlers/rotate.job.ts

@@ -51,7 +51,7 @@ export type RotateJobResult = {
 };
 
 export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
-  const payload = rawPayload as RotateJobPayload;
+  const payload = rawPayload as RotateJobPayload; // @cast-boundary engine-payload
   if (!ctx.masterKeyProvider) {
     throw new InternalError({
       message:
@@ -64,7 +64,7 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
       message: "[secrets:rotate] ctx.db missing — job context requires a database connection.",
     });
   }
-  const db = ctx.db as DbConnection;
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
   const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
   const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
   const deadline = payload.maxDurationMs

package/src/sessions/handlers/cleanup.job.ts

@@ -39,13 +39,13 @@ export type SessionCleanupResult = {
 };
 
 export const cleanupJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
-  const payload = rawPayload as SessionCleanupPayload;
+  const payload = rawPayload as SessionCleanupPayload; // @cast-boundary engine-payload
   if (!ctx.db) {
     throw new InternalError({
       message: "[sessions:cleanup] ctx.db missing — job context requires a database connection.",
     });
   }
-  const db = ctx.db as DbConnection;
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
 
   // Coerce-and-validate: BullMQ payloads arrive as opaque JSON, so TS types
   // don't survive. Guard before the value is interpolated into SQL.

package/src/step-dispatcher/feature.ts

@@ -0,0 +1,62 @@
+// step-dispatcher — bundled-feature that drains deferred Tier-2 step
+// requests (webhook.send, mail.send, ...) after their TX commits.
+//
+// Listens on the `kumiko:system:step.dispatch-requested` system event
+// (registry-bypassed, see append-event-core.ts SYSTEM_EVENT_PREFIX).
+// Performs the side-effect and emits `kumiko:system:step.dispatched`
+// or `kumiko:system:step.dispatch-failed` back onto the same stream so
+// the audit trail lives in the event log only — no separate status table.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type MailSpec, performMailDispatch } from "./mail-runner";
+import { performWebhookDispatch, type WebhookSpec } from "./webhook-runner";
+
+export const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
+export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
+export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
+export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+
+type DispatchRequestedPayload =
+  | {
+      readonly stepKind: "webhook.send";
+      readonly spec: WebhookSpec;
+      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
+    }
+  | {
+      readonly stepKind: "mail.send";
+      readonly spec: MailSpec;
+    };
+
+export function createStepDispatcherFeature(): FeatureDefinition {
+  return defineFeature("step-dispatcher", (r) => {
+    r.systemScope();
+
+    r.multiStreamProjection({
+      name: "step-dispatcher",
+      apply: {
+        [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
+          const payload = event.payload as DispatchRequestedPayload;
+          const result =
+            payload.stepKind === "webhook.send"
+              ? await performWebhookDispatch(payload.spec)
+              : await performMailDispatch(payload.spec);
+          if (result.ok) {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCHED_TYPE,
+              payload: { stepKind: payload.stepKind, status: result.status },
+            });
+          } else {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCH_FAILED_TYPE,
+              payload: { stepKind: payload.stepKind, error: result.error, attempt: 1 },
+            });
+          }
+        },
+      },
+    });
+  });
+}

package/src/step-dispatcher/index.ts

@@ -0,0 +1,16 @@
+export { createStepDispatcherFeature, STEP_DISPATCH_AGGREGATE_TYPE } from "./feature";
+export {
+  type MailDispatchResult,
+  type MailSpec,
+  mailSpecSchema,
+  performMailDispatch,
+  setMailRunner,
+} from "./mail-runner";
+export {
+  performWebhookDispatch,
+  setWebhookFetch,
+  setWebhookSecretResolver,
+  type WebhookDispatchResult,
+  type WebhookSpec,
+  webhookSpecSchema,
+} from "./webhook-runner";

package/src/step-dispatcher/mail-runner.ts

@@ -0,0 +1,32 @@
+// Mail execution logic — separated from feature.ts and tests-injectable.
+// Production wiring (mail-foundation transport) is a follow-up; the
+// default impl throws so a missing setMailRunner is loud, not silent.
+
+import { z } from "zod";
+
+export const mailSpecSchema = z.object({
+  to: z.union([z.string(), z.array(z.string())]),
+  subject: z.string(),
+  body: z.string(),
+  from: z.string().optional(),
+});
+
+export type MailSpec = z.infer<typeof mailSpecSchema>;
+
+export type MailDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+let mailRunner: (spec: MailSpec) => Promise<MailDispatchResult> = async () => ({
+  ok: false,
+  error:
+    "no mail-runner configured — call setMailRunner() with a mail-foundation transport adapter",
+});
+
+export function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult>): void {
+  mailRunner = fn;
+}
+
+export async function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult> {
+  return mailRunner(spec);
+}

package/src/step-dispatcher/webhook-runner.ts

@@ -0,0 +1,67 @@
+// Webhook execution logic — separated from feature.ts so tests can stub
+// the fetch without touching the MSP wiring.
+
+import { z } from "zod";
+
+export const webhookSpecSchema = z.object({
+  url: z.string(),
+  method: z.enum(["POST", "PUT", "PATCH"]),
+  headers: z.record(z.string(), z.string()),
+  body: z.unknown().optional(),
+  auth: z
+    .union([
+      z.object({ kind: z.literal("bearer"), secretRef: z.string() }),
+      z.object({ kind: z.literal("header"), name: z.string(), secretRef: z.string() }),
+    ])
+    .optional(),
+});
+
+export type WebhookSpec = z.infer<typeof webhookSpecSchema>;
+
+export type WebhookDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+// Resolves a secretRef via the test-injectable secret-store. Default
+// implementation reads from process.env at the prefix WEBHOOK_SECRET_.
+// Tests pass a custom resolver via setWebhookSecretResolver.
+let secretResolver: (ref: string) => string | undefined = (ref) =>
+  process.env[`WEBHOOK_SECRET_${ref}`];
+
+export function setWebhookSecretResolver(fn: (ref: string) => string | undefined): void {
+  secretResolver = fn;
+}
+
+let fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis);
+
+export function setWebhookFetch(fn: typeof fetch): void {
+  fetchImpl = fn;
+}
+
+export async function performWebhookDispatch(spec: WebhookSpec): Promise<WebhookDispatchResult> {
+  const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  if (spec.auth) {
+    const secret = secretResolver(spec.auth.secretRef);
+    if (!secret) {
+      return { ok: false, error: `secret "${spec.auth.secretRef}" not configured` };
+    }
+    if (spec.auth.kind === "bearer") {
+      headers["authorization"] = `Bearer ${secret}`;
+    } else {
+      headers[spec.auth.name] = secret;
+    }
+  }
+  try {
+    const res = await fetchImpl(spec.url, {
+      method: spec.method,
+      headers,
+      body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/subscription-mollie/plugin-methods.ts

@@ -66,7 +66,7 @@ export function createMollieCheckoutSession(
         tenantId: options.tenantId,
         priceId: options.priceId,
       },
-    }) as Promise<Payment>)) satisfies Payment;
+    }) as Promise<Payment>)) satisfies Payment; // @cast-boundary engine-bridge
 
     const checkoutHref = payment.getCheckoutUrl();
     if (!checkoutHref) {

package/src/subscription-mollie/verify-webhook.ts

@@ -102,7 +102,7 @@ export function verifyAndParseMollieWebhook(
       return null;
     }
 
-    const metadata = (subscription.metadata as Record<string, string> | null) ?? {};
+    const metadata = (subscription.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
     const tenantId = metadata["tenantId"];
     if (!tenantId || tenantId.length === 0) return null;
     const priceId = metadata["priceId"];
@@ -153,7 +153,7 @@ async function ensureSubscriptionForMandate(
 ): Promise<MollieSubscription | null> {
   const customerId = payment.customerId;
   if (!customerId) return null;
-  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {};
+  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
   const tenantId = paymentMetadata["tenantId"];
   const priceId = paymentMetadata["priceId"];
   if (!tenantId || !priceId) return null;
@@ -163,7 +163,7 @@ async function ensureSubscriptionForMandate(
   const existing = await client.customerSubscriptions.list(customerId);
   const matchingExisting = existing.find(
     (sub) =>
-      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId &&
+      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId && // @cast-boundary engine-bridge
       (sub.status === "active" || sub.status === "pending"),
   );
   if (matchingExisting) return matchingExisting;
@@ -185,8 +185,12 @@ export function extractMollieId(rawBody: string, headers: Record<string, string>
   const contentType = headers["content-type"] ?? "";
   if (contentType.includes("application/json")) {
     try {
-      const parsed = JSON.parse(rawBody) as { id?: unknown };
-      return typeof parsed.id === "string" ? parsed.id : null;
+      const parsed: unknown = JSON.parse(rawBody);
+      const id =
+        typeof parsed === "object" && parsed !== null && "id" in parsed
+          ? (parsed as Record<string, unknown>)["id"] // @cast-boundary engine-payload
+          : undefined;
+      return typeof id === "string" ? id : null;
     } catch {
       return null;
     }

package/src/subscription-stripe/verify-webhook.ts

@@ -203,15 +203,15 @@ async function extractSubscriptionFromEvent(
     case StripeEventTypes.customerSubscriptionCreated:
     case StripeEventTypes.customerSubscriptionUpdated:
     case StripeEventTypes.customerSubscriptionDeleted:
-      return event.data.object as Stripe.Subscription;
+      return event.data.object as Stripe.Subscription; // @cast-boundary engine-bridge
     case StripeEventTypes.invoicePaid:
     case StripeEventTypes.invoicePaymentFailed: {
       // Lazy-fetch der subscription. invoice.subscription ist eine
       // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
       // full subscription-Object damit der downstream-mapping
       // (status, tier via priceId, period-end) konsistent funktioniert.
-      const invoice = event.data.object as Stripe.Invoice;
-      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null })
+      const invoice = event.data.object as Stripe.Invoice; // @cast-boundary engine-bridge
+      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null }) // @cast-boundary engine-payload
         .subscription;
       if (!subRef) {
         // Invoice ohne subscription-reference (= one-shot-invoice, nicht

package/src/template-resolver/README.md

@@ -0,0 +1,89 @@
+# 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`](../../../../../../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`.
+
+## 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:** aktuell nicht implementiert. `ctx.db` ist tenant-scoped (createTenantDb in dispatcher), SystemAdmin sieht ohne explicit `tenantIdOverride` keine fremden Tenants. Wenn Admin-UI das fordert: Schema-Erweiterung in einer M2-Iteration.
+
+## 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.
+
+## 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