@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.363.0

package/dist/template-resolver/handlers/template-write.js

@@ -0,0 +1,109 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError, ValidationError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { requireForTenant } from "../../shared/index.js";
+import { templateResourcesTable } from "../table.js";
+import { executor } from "./shared.js";
+import { evaluateTemplateWrite, } from "./template-gates.js";
+// The tenant-scope-under-system-tenant ban lives here so no write path can
+// create the inconsistent state the resolver does not model.
+export function refuseTenantScopeUnderSystemTenant(scope, tenantId) {
+    if (scope !== "tenant" || tenantId !== SYSTEM_TENANT_ID)
+        return null;
+    return writeFailure(new AccessDeniedError({
+        i18nKey: "templateResolver.errors.useUpsertSystemForSystemTenant",
+        details: { reason: "system_tenant_override_not_allowed_use_upsert_system" },
+    }));
+}
+// Evaluation plus the publish rule: a row that goes active must not carry
+// publish issues, a draft may.
+export function gateTemplateWrite(input, status) {
+    const evaluated = evaluateTemplateWrite(input);
+    if (!evaluated.ok) {
+        return {
+            ok: false,
+            failure: writeFailure(new ValidationError({ fields: [...evaluated.issues] })),
+        };
+    }
+    if (status === "active" && evaluated.publishIssues.length > 0) {
+        return {
+            ok: false,
+            failure: writeFailure(new ValidationError({ fields: [...evaluated.publishIssues] })),
+        };
+    }
+    return { ok: true, evaluated };
+}
+// Shared by every template write: validate through the one pipeline, then
+// create or update the (tenant, slug, kind, locale) row via the event-store
+// executor. linkedResources is never part of an update; resources are attached
+// separately.
+export async function writeTemplateRow(args) {
+    const { ctx, user, tenantId, scope, status, payload } = args;
+    const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
+    if (refused !== null)
+        return refused;
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+    const gated = gateTemplateWrite({
+        kind: payload.kind,
+        scope,
+        contentFormat: payload.contentFormat,
+        content: payload.content,
+        rawMeta: payload.meta,
+        variables: args.variables,
+    }, status);
+    if (!gated.ok)
+        return gated.failure;
+    const { evaluated } = gated;
+    const existing = await fetchOne(db, templateResourcesTable, {
+        tenantId,
+        slug: payload.slug,
+        kind: payload.kind,
+        locale: payload.locale,
+    });
+    const fields = {
+        slug: payload.slug,
+        kind: payload.kind,
+        locale: payload.locale,
+        content: evaluated.content,
+        contentFormat: payload.contentFormat,
+        variableSchema: JSON.stringify(payload.variableSchema),
+        meta: evaluated.metaJson,
+        title: payload.title ?? null,
+        folder: payload.folder ?? null,
+        scope,
+        parentTemplateId: payload.parentTemplateId ?? null,
+        status,
+    };
+    if (existing) {
+        const result = await executor.update({ id: existing.id, version: existing.version, changes: fields }, user, db, { streamTenantId });
+        if (!result.isSuccess)
+            return result;
+        return {
+            isSuccess: true,
+            data: {
+                id: String(existing.id),
+                slug: payload.slug,
+                isNew: false,
+                validation: evaluated.validation,
+            },
+        };
+    }
+    const result = await executor.create({ ...fields, linkedResources: "{}", tenantId }, user, db, {
+        streamTenantId,
+    });
+    if (!result.isSuccess)
+        return result;
+    // @cast-boundary db-row — executor.create returnt Record-row aus
+    // INSERT RETURNING; shape { id } ist garantiert weil PK in der
+    // Returning-Klausel ist.
+    const createdRow = result.data;
+    return {
+        isSuccess: true,
+        data: {
+            id: String(createdRow.id),
+            slug: payload.slug,
+            isNew: true,
+            validation: evaluated.validation,
+        },
+    };
+}

package/dist/template-resolver/handlers/tenant-overrides.query.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+export declare const tenantOverridesQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"tenant-overrides", z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        "ai-prompt": "ai-prompt";
+        "document-pdf": "document-pdf";
+        "image-snapshot": "image-snapshot";
+        mail: "mail";
+        "mail-layout": "mail-layout";
+        "pdf-layout": "pdf-layout";
+    }>;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    activeOverrides: number;
+    draftOverrides: number;
+    totalTenants: number | null;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/tenant-overrides.query.js

@@ -0,0 +1,48 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { TenantQueries } from "../../tenant/index.js";
+import { templateResourcesTable } from "../table.js";
+import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
+const TENANT_OVERRIDES_REASON = "SystemAdmin template overview counts how many tenants override one system template; it reads tenant-scope template rows of every tenant and returns only counts, never tenant ids or content";
+const tenantIdsSchema = z.array(z.string());
+export const tenantOverridesQuery = defineQueryHandler({
+    name: "tenant-overrides",
+    schema: z.object({
+        slug: templateSlugSchema,
+        kind: kindSchema,
+        locale: localeSchema.optional(),
+    }),
+    access: { roles: ["SystemAdmin"] },
+    description: "Counts how many enabled tenants override one template with an active or a draft version, next to the number of enabled tenants; use it before changing a system template to see how many tenants keep their own copy. Returns counts only, no tenant ids.",
+    escapeHatch: { grants: ["unsafeRaw"], reason: TENANT_OVERRIDES_REASON },
+    handler: async (query, ctx) => {
+        const { slug, kind, locale } = query.payload;
+        const rows = await selectMany(ctx.db.unsafeRaw(), templateResourcesTable, {
+            slug,
+            kind,
+            scope: "tenant",
+            ...(locale === undefined ? {} : { locale }),
+        });
+        const hasTenantFeature = ctx.registry.getQueryHandler(TenantQueries.activeTenantIds) !== undefined;
+        const enabledTenantIds = hasTenantFeature
+            ? new Set(tenantIdsSchema.parse(await ctx.query(TenantQueries.activeTenantIds, {})))
+            : null;
+        const statusByTenant = new Map();
+        for (const row of rows) {
+            if (row.tenantId === SYSTEM_TENANT_ID || row.status === "archived")
+                continue;
+            if (enabledTenantIds !== null && !enabledTenantIds.has(row.tenantId))
+                continue;
+            if (statusByTenant.get(row.tenantId) === "active")
+                continue;
+            statusByTenant.set(row.tenantId, row.status === "active" ? "active" : "draft");
+        }
+        const statuses = [...statusByTenant.values()];
+        return {
+            activeOverrides: statuses.filter((status) => status === "active").length,
+            draftOverrides: statuses.filter((status) => status === "draft").length,
+            totalTenants: enabledTenantIds === null ? null : enabledTenantIds.size,
+        };
+    },
+});

package/dist/template-resolver/handlers/toggle-status.write.d.ts

@@ -12,4 +12,16 @@ export declare const publishWrite: import("@cosmicdrift/kumiko-types/define-hand
     id: string;
     status: TemplateStatus;
 }, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export declare const archiveSystemWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<string, z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, {
+    id: string;
+    status: TemplateStatus;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export declare const publishSystemWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<string, z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>, {
+    id: string;
+    status: TemplateStatus;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
 export {};

package/dist/template-resolver/handlers/toggle-status.write.js

@@ -1,30 +1,46 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { defineWriteHandler, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, ValidationError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
 import { templateResourcesTable } from "../table.js";
 import { executor } from "./shared.js";
-function createStatusUpdateHandler(name, status, description) {
+import { publishGateIssues } from "./template-gates.js";
+function isRowOfTarget(row, target, callerTenantId) {
+    return target === "system"
+        ? row.tenantId === SYSTEM_TENANT_ID && row.scope === "system"
+        : row.tenantId === callerTenantId && row.scope === "tenant";
+}
+function createStatusUpdateHandler(name, target, status, description, gate) {
     return defineWriteHandler({
         name,
         schema: z.object({ id: z.string().min(1) }),
-        access: { roles: ["TenantAdmin", "SystemAdmin"] },
+        access: { roles: target === "system" ? ["SystemAdmin"] : ["TenantAdmin", "SystemAdmin"] },
+        // A system template change reaches every tenant without an override.
+        ...(target === "system" ? { agent: { risk: "high" } } : {}),
         description,
         handler: async (event, ctx) => {
-            // ctx.db is tenant-scoped: a foreign tenant's id reads as absent → NotFound.
-            // Cross-tenant toggling needs SystemAdmin with tenantIdOverride.
-            const existing = await fetchOne(ctx.db, templateResourcesTable, {
+            const scoped = target === "system" ? requireForTenant(ctx, SYSTEM_TENANT_ID) : null;
+            const db = scoped?.db ?? ctx.db;
+            // The tenant db also reads system rows; the row's own tenant must match
+            // the target or the executor would append to a foreign event stream.
+            const existing = await fetchOne(db, templateResourcesTable, {
                 id: event.payload.id,
             });
-            if (!existing) {
+            if (!existing || !isRowOfTarget(existing, target, event.user.tenantId)) {
                 return writeFailure(new NotFoundError("template-resource", event.payload.id));
             }
-            const result = await executor.update({ id: existing.id, version: existing.version, changes: { status } }, event.user, ctx.db);
+            const issues = gate?.(ctx.registry, existing) ?? [];
+            if (issues.length > 0)
+                return writeFailure(new ValidationError({ fields: [...issues] }));
+            const result = await executor.update({ id: existing.id, version: existing.version, changes: { status } }, event.user, db, scoped ? { streamTenantId: scoped.streamTenantId } : undefined);
             if (!result.isSuccess)
                 return result;
             return { isSuccess: true, data: { id: String(existing.id), status } };
         },
     });
 }
-export const archiveWrite = createStatusUpdateHandler("archive", "archived", "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it.");
-export const publishWrite = createStatusUpdateHandler("publish", "active", "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant, or to bring an archived template back.");
+export const archiveWrite = createStatusUpdateHandler("archive", "own", "archived", "Sets one template resource of the caller's tenant to archived so the resolver stops serving it while the row and its content survive; use it to retire a template reversibly instead of deleting it.");
+export const publishWrite = createStatusUpdateHandler("publish", "own", "active", "Sets one template resource of the caller's tenant to active so the resolver starts serving it; use it to release a draft written by upsert-tenant, or to bring an archived template back; a mail template with unknown placeholders or unused required variables is refused.", publishGateIssues);
+export const archiveSystemWrite = createStatusUpdateHandler("archive-system", "system", "archived", "Sets one system-default template to archived so the resolver stops serving it to every tenant that has no override; SystemAdmin only, reversible with publish-system.");
+export const publishSystemWrite = createStatusUpdateHandler("publish-system", "system", "active", "Sets one system-default template to active so the resolver serves it again to every tenant that has no override; SystemAdmin only, a mail template with unknown placeholders or unused required variables is refused.", publishGateIssues);

package/dist/template-resolver/handlers/upsert-system.write.d.ts

@@ -4,8 +4,9 @@ export declare const upsertSystemWrite: import("@cosmicdrift/kumiko-types/define
         "ai-prompt": "ai-prompt";
         "document-pdf": "document-pdf";
         "image-snapshot": "image-snapshot";
-        "mail-html": "mail-html";
-        notification: "notification";
+        mail: "mail";
+        "mail-layout": "mail-layout";
+        "pdf-layout": "pdf-layout";
     }>;
     locale: import("zod").ZodString;
     content: import("zod").ZodString;
@@ -16,12 +17,8 @@ export declare const upsertSystemWrite: import("@cosmicdrift/kumiko-types/define
         plain: "plain";
     }>;
     variableSchema: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
-    linkedResources: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
+    meta: import("zod").ZodOptional<import("zod").ZodUnknown>;
     parentTemplateId: import("zod").ZodOptional<import("zod").ZodString>;
     title: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
     folder: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
-}, import("zod/v4/core").$strip>, {
-    id: string;
-    slug: string;
-    isNew: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("zod/v4/core").$strip>, import("./template-write.js").WrittenTemplateRow, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/upsert-system.write.js

@@ -1,8 +1,7 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
-import { requireForTenant } from "../../shared/index.js";
-import { templateResourcesTable } from "../table.js";
-import { executor, upsertPayloadSchema } from "./shared.js";
+import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { upsertPayloadSchema } from "./shared.js";
+import { writeTemplateRow } from "./template-write.js";
 // 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
@@ -11,58 +10,14 @@ export const upsertSystemWrite = defineWriteHandler({
     name: "upsert-system",
     schema: upsertPayloadSchema,
     access: { roles: ["SystemAdmin"] },
-    description: "Creates or overwrites a system-default template under the system tenant with its full variable schema and linked resources, active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
-    handler: async (event, ctx) => {
-        // @cast-boundary engine-payload — SYSTEM_TENANT_ID is a UUID literal,
-        // asserted to the branded TenantId (parseTenantId equivalent).
-        const tenantId = SYSTEM_TENANT_ID;
-        const { db, streamTenantId } = requireForTenant(ctx, tenantId);
-        const existing = await fetchOne(db, templateResourcesTable, {
-            tenantId,
-            slug: event.payload.slug,
-            kind: event.payload.kind,
-            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),
-            title: event.payload.title ?? null,
-            folder: event.payload.folder ?? null,
-            scope: "system",
-            parentTemplateId: event.payload.parentTemplateId ?? null,
-            // System-Defaults sind sofort active (kein draft-Stage für seeds).
-            status: "active",
-        };
-        if (existing) {
-            const result = await executor.update({ id: existing.id, version: existing.version, changes: fields }, event.user, db, { streamTenantId });
-            if (!result.isSuccess)
-                return result;
-            return {
-                isSuccess: true,
-                data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
-            };
-        }
-        const result = await executor.create({ ...fields, tenantId }, event.user, db, {
-            streamTenantId,
-        });
-        if (!result.isSuccess)
-            return result;
-        // @cast-boundary db-row — executor.create returnt Record-row aus
-        // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-        // Returning-Klausel ist.
-        const createdRow = result.data;
-        return {
-            isSuccess: true,
-            data: {
-                id: String(createdRow.id),
-                slug: event.payload.slug,
-                isNew: true,
-            },
-        };
-    },
+    description: "Creates or overwrites a system-default template under the system tenant with its full variable schema (resource files go through the resource upload), active straight away with no draft stage; SystemAdmin only, since tenants shadow these defaults through upsert-tenant instead.",
+    handler: (event, ctx) => writeTemplateRow({
+        ctx,
+        user: event.user,
+        tenantId: SYSTEM_TENANT_ID,
+        scope: "system",
+        status: "active",
+        variables: resolveTemplateVariables(ctx.registry, event.payload.slug, event.payload.variableSchema),
+        payload: event.payload,
+    }),
 });

package/dist/template-resolver/handlers/upsert-tenant.write.d.ts

@@ -5,8 +5,9 @@ export declare const upsertTenantWrite: import("@cosmicdrift/kumiko-types/define
         "ai-prompt": "ai-prompt";
         "document-pdf": "document-pdf";
         "image-snapshot": "image-snapshot";
-        "mail-html": "mail-html";
-        notification: "notification";
+        mail: "mail";
+        "mail-layout": "mail-layout";
+        "pdf-layout": "pdf-layout";
     }>;
     locale: z.ZodString;
     content: z.ZodString;
@@ -17,7 +18,7 @@ export declare const upsertTenantWrite: import("@cosmicdrift/kumiko-types/define
         plain: "plain";
     }>;
     variableSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    linkedResources: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    meta: z.ZodOptional<z.ZodUnknown>;
     parentTemplateId: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     folder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -26,8 +27,4 @@ export declare const upsertTenantWrite: import("@cosmicdrift/kumiko-types/define
         active: "active";
         draft: "draft";
     }>>;
-}, z.core.$strip>, {
-    id: string;
-    slug: string;
-    isNew: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, z.core.$strip>, import("./template-write.js").WrittenTemplateRow, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/upsert-tenant.write.js

@@ -1,10 +1,8 @@
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { defineWriteHandler, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
-import { AccessDeniedError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { requireForTenant } from "../../shared/index.js";
-import { templateResourcesTable } from "../table.js";
-import { executor, upsertPayloadSchema } from "./shared.js";
+import { resolveTemplateVariables } from "../template-validation.js";
+import { upsertPayloadSchema } from "./shared.js";
+import { writeTemplateRow } from "./template-write.js";
 // 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
@@ -19,67 +17,18 @@ export const upsertTenantWrite = defineWriteHandler({
     access: { roles: ["TenantAdmin", "SystemAdmin"] },
     description: "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live; it refuses a system-tenant target, which is what upsert-system is for.",
     handler: async (event, ctx) => {
-        const override = event.payload.tenantIdOverride;
-        // 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" },
-            }));
-        }
         // @cast-boundary engine-payload — override aus Zod-parsed string,
         // event.user.tenantId schon TenantId-branded; union als TenantId casten
         // ist legit (override ist UUID-Format-validiert in schema).
-        const tenantId = (override ?? event.user.tenantId);
-        const { db, streamTenantId } = requireForTenant(ctx, tenantId);
-        const existing = await fetchOne(db, templateResourcesTable, {
+        const tenantId = (event.payload.tenantIdOverride ?? event.user.tenantId);
+        return writeTemplateRow({
+            ctx,
+            user: event.user,
             tenantId,
-            slug: event.payload.slug,
-            kind: event.payload.kind,
-            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),
-            title: event.payload.title ?? null,
-            folder: event.payload.folder ?? null,
             scope: "tenant",
-            parentTemplateId: event.payload.parentTemplateId ?? null,
             status: event.payload.status,
-        };
-        if (existing) {
-            const result = await executor.update({ id: existing.id, version: existing.version, changes: fields }, event.user, db, { streamTenantId });
-            if (!result.isSuccess)
-                return result;
-            return {
-                isSuccess: true,
-                data: { id: String(existing.id), slug: event.payload.slug, isNew: false },
-            };
-        }
-        const result = await executor.create({ ...fields, tenantId }, event.user, db, {
-            streamTenantId,
+            variables: resolveTemplateVariables(ctx.registry, event.payload.slug, event.payload.variableSchema),
+            payload: event.payload,
         });
-        if (!result.isSuccess)
-            return result;
-        // @cast-boundary db-row — executor.create returnt Record-row aus
-        // INSERT RETURNING; shape { id } ist garantiert weil PK in der
-        // Returning-Klausel ist.
-        const createdRow = result.data;
-        return {
-            isSuccess: true,
-            data: {
-                id: String(createdRow.id),
-                slug: event.payload.slug,
-                isNew: true,
-            },
-        };
     },
 });

package/dist/template-resolver/handlers/usage.query.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+export declare const usageQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"usage", z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        "ai-prompt": "ai-prompt";
+        "document-pdf": "document-pdf";
+        "image-snapshot": "image-snapshot";
+        mail: "mail";
+        "mail-layout": "mail-layout";
+        notification: "notification";
+        "pdf-layout": "pdf-layout";
+        snippet: "snippet";
+        "text-block": "text-block";
+    }>;
+}, z.core.$strip>, {
+    usedBy: import("../template-usage.js").TemplateUsageEntry[];
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/template-resolver/handlers/usage.query.js

@@ -0,0 +1,15 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { TEMPLATE_KINDS } from "../constants.js";
+import { templateSlugSchema } from "../template-meta.js";
+import { collectTemplateUsage } from "../template-usage.js";
+export const usageQuery = defineQueryHandler({
+    name: "usage",
+    schema: z.object({ slug: templateSlugSchema, kind: z.enum(TEMPLATE_KINDS) }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    description: "Lists the code-registered notifications that use one template: a mail template is used by the notification whose qualified name is its slug, a mail layout by every mail notification that names it in its meta or falls back to the default layout; use it to show what a change to a template affects.",
+    handler: async (query, ctx) => {
+        const { slug, kind } = query.payload;
+        return { usedBy: collectTemplateUsage(ctx.registry, slug, kind) };
+    },
+});

package/dist/template-resolver/handlers/validate.query.d.ts

@@ -0,0 +1,74 @@
+import { type HandlerContext, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { ContentFormat, UpsertKind } from "../constants.js";
+import type { TemplateWriteScope } from "../layout-regions.js";
+type TemplateDraftInput = {
+    readonly slug: string;
+    readonly kind: UpsertKind;
+    readonly contentFormat: ContentFormat;
+    readonly content: string;
+    readonly meta?: unknown;
+    readonly variableSchema: Readonly<Record<string, unknown>>;
+    readonly locale?: string | undefined;
+    readonly scope: TemplateWriteScope;
+};
+export declare function validateTemplateDraft(ctx: HandlerContext, user: SessionUser, payload: TemplateDraftInput): Promise<{
+    response: {
+        canSave: boolean;
+        canPublish: boolean;
+        issues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
+        publishIssues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
+        used: string[];
+        unknown: string[];
+        missingRequired: string[];
+        warnings: {
+            code: "resource_not_uploaded";
+            detail: string;
+            i18nKey: "templateResolver.warnings.resourceNotUploaded";
+        }[];
+        variables: Readonly<Record<string, import("@cosmicdrift/kumiko-types/config").TemplateVariableDef>>;
+        systemPlaceholders: string[];
+    };
+    evaluation: import("./template-gates.js").TemplateWriteResult;
+}>;
+export declare const validateQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"validate", z.ZodObject<{
+    slug: z.ZodString;
+    kind: z.ZodEnum<{
+        "ai-prompt": "ai-prompt";
+        "document-pdf": "document-pdf";
+        "image-snapshot": "image-snapshot";
+        mail: "mail";
+        "mail-layout": "mail-layout";
+        "pdf-layout": "pdf-layout";
+    }>;
+    contentFormat: z.ZodEnum<{
+        html: "html";
+        markdown: "markdown";
+        mjml: "mjml";
+        plain: "plain";
+    }>;
+    content: z.ZodString;
+    meta: z.ZodOptional<z.ZodUnknown>;
+    variableSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    locale: z.ZodOptional<z.ZodString>;
+    scope: z.ZodDefault<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
+}, z.core.$strip>, {
+    canSave: boolean;
+    canPublish: boolean;
+    issues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
+    publishIssues: import("@cosmicdrift/kumiko-headless").FieldIssue[];
+    used: string[];
+    unknown: string[];
+    missingRequired: string[];
+    warnings: {
+        code: "resource_not_uploaded";
+        detail: string;
+        i18nKey: "templateResolver.warnings.resourceNotUploaded";
+    }[];
+    variables: Readonly<Record<string, import("@cosmicdrift/kumiko-types/config").TemplateVariableDef>>;
+    systemPlaceholders: string[];
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export {};