@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

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

@@ -0,0 +1,49 @@
+import * as z from "zod";
+type OverrideStatus = "active" | "draft";
+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>;
+    diffTenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    activeOverrides: number;
+    draftOverrides: number;
+    totalTenants: number | null;
+    rows: {
+        tenantId: string;
+        tenantName: string;
+        templateId: string;
+        locale: string;
+        status: OverrideStatus;
+        version: number;
+        changedAt: string;
+        changedBy: string | null;
+    }[];
+    diff: {
+        tenant: {
+            templateId: string;
+            templateVersion: number;
+            contentFormat: string;
+        };
+        system: {
+            templateId: string;
+            templateVersion: number;
+            contentFormat: string;
+        };
+        identical: boolean;
+        blocks: import("../template-diff.js").TemplateDiffBlock[];
+        meta: {
+            key: string;
+            tenant: unknown;
+            system: unknown;
+        }[];
+    } | null;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export {};

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

@@ -0,0 +1,112 @@
+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 { servedVersionOf } from "../template-draft.js";
+import { buildOverrideDiff } from "./override-diff.js";
+import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
+const TENANT_OVERRIDES_REASON = "SystemAdmin template overview lists which tenants override one system template; it reads tenant-scope template rows of every tenant (and the system row for the optional per-tenant diff), which the tenant-scoped db cannot reach";
+const tenantIdsSchema = z.array(z.string());
+const directorySchema = z.object({
+    rows: z.array(z.object({ id: z.string(), label: z.string() })),
+});
+function labelsOf(raw) {
+    return new Map(directorySchema.parse(raw).rows.map((row) => [row.id, row.label]));
+}
+// One row per tenant: its active override wins over a draft, then the newest version.
+function isBetterRow(candidate, current) {
+    if ((candidate.status === "active") !== (current.status === "active")) {
+        return candidate.status === "active";
+    }
+    return candidate.version > current.version;
+}
+function statusOf(row) {
+    return row.status === "active" ? "active" : "draft";
+}
+function isCountedTenantRow(row, enabledTenantIds) {
+    if (row.tenantId === SYSTEM_TENANT_ID || row.status === "archived")
+        return false;
+    return enabledTenantIds === null || enabledTenantIds.has(row.tenantId);
+}
+function pickBestRowPerTenant(found, enabledTenantIds) {
+    const bestByTenant = new Map();
+    for (const row of found) {
+        if (!isCountedTenantRow(row, enabledTenantIds))
+            continue;
+        const current = bestByTenant.get(row.tenantId);
+        if (current === undefined || isBetterRow(row, current))
+            bestByTenant.set(row.tenantId, row);
+    }
+    return bestByTenant;
+}
+function toOverrideRow(row, tenantLabels, userLabels) {
+    const changedById = row.modifiedById ?? row.insertedById;
+    return {
+        tenantId: row.tenantId,
+        tenantName: tenantLabels.get(row.tenantId) ?? row.tenantId,
+        templateId: String(row.id),
+        locale: row.locale,
+        status: statusOf(row),
+        version: servedVersionOf(row),
+        changedAt: (row.modifiedAt ?? row.insertedAt).toString(),
+        changedBy: changedById === null ? null : (userLabels.get(changedById) ?? null),
+    };
+}
+export const tenantOverridesQuery = defineQueryHandler({
+    name: "tenant-overrides",
+    schema: z.object({
+        slug: templateSlugSchema,
+        kind: kindSchema,
+        locale: localeSchema.optional(),
+        /** Adds the block diff of this tenant's override against the system template. */
+        diffTenantId: z.string().min(1).optional(),
+    }),
+    access: { roles: ["SystemAdmin"] },
+    description: "Lists the enabled tenants that override one template with an active or a draft version (tenant name, status, version, last change and who made it), next to the counts and the number of enabled tenants; use it before changing a system template to see who keeps their own copy. With diffTenantId it also returns the block diff of that tenant's override against the system template.",
+    escapeHatch: { grants: ["unsafeRaw"], reason: TENANT_OVERRIDES_REASON },
+    handler: async (query, ctx) => {
+        const { slug, kind, locale, diffTenantId } = query.payload;
+        const raw = ctx.db.unsafeRaw();
+        const found = await selectMany(raw, 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 bestByTenant = pickBestRowPerTenant(found, enabledTenantIds);
+        const best = [...bestByTenant.values()];
+        const tenantLabels = hasTenantFeature
+            ? labelsOf(await ctx.query(TenantQueries.tenantDirectory, {}))
+            : new Map();
+        const userLabels = hasTenantFeature
+            ? labelsOf(await ctx.query(TenantQueries.memberDirectory, {}))
+            : new Map();
+        const rows = best
+            .map((row) => toOverrideRow(row, tenantLabels, userLabels))
+            .sort((a, b) => a.tenantName.localeCompare(b.tenantName));
+        let diff = null;
+        const diffRow = diffTenantId === undefined ? undefined : bestByTenant.get(diffTenantId);
+        if (diffRow !== undefined) {
+            const [systemRow] = await selectMany(raw, templateResourcesTable, {
+                tenantId: SYSTEM_TENANT_ID,
+                slug,
+                kind,
+                locale: diffRow.locale,
+            });
+            if (systemRow !== undefined)
+                diff = buildOverrideDiff(diffRow, systemRow);
+        }
+        return {
+            activeOverrides: best.filter((row) => row.status === "active").length,
+            draftOverrides: best.filter((row) => row.status !== "active").length,
+            totalTenants: enabledTenantIds === null ? null : enabledTenantIds.size,
+            rows,
+            diff,
+        };
+    },
+});

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

@@ -1,15 +1,40 @@
+import { type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import type { TemplateResourceRow } from "../table.js";
 type TemplateStatus = "active" | "archived";
+export type StatusTarget = "own" | "system";
+export declare function writeAccessFor(target: StatusTarget): {
+    roles: string[];
+};
+export declare function loadTargetRow(ctx: HandlerContext, target: StatusTarget, user: {
+    readonly tenantId: string;
+}, id: string): Promise<{
+    db: import("@cosmicdrift/kumiko-types/tenant-db-types").TenantDb;
+    scoped: import("@cosmicdrift/kumiko-types/handlers").TenantWriteTarget | null;
+    row: TemplateResourceRow | null;
+}>;
 export declare const archiveWrite: 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>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
 export declare const publishWrite: 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>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;
+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, undefined>;
+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, undefined>;
 export {};

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

@@ -1,30 +1,62 @@
 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 { activationChanges, parseTemplateDraft, toWorkingRow } from "../template-draft.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";
+}
+export function writeAccessFor(target) {
+    return { roles: target === "system" ? ["SystemAdmin"] : ["TenantAdmin", "SystemAdmin"] };
+}
+// 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.
+export async function loadTargetRow(ctx, target, user, id) {
+    const scoped = target === "system" ? requireForTenant(ctx, SYSTEM_TENANT_ID) : null;
+    const db = scoped?.db ?? ctx.db;
+    const row = await fetchOne(db, templateResourcesTable, { id });
+    return { db, scoped, row: row && isRowOfTarget(row, target, user.tenantId) ? row : null };
+}
+// Publishing promotes an open draft (gated as the version that goes live); a row
+// without one is activated as stored. Archiving leaves the draft standing.
+function planStatusChange(ctx, row, status) {
+    if (status === "archived")
+        return { ok: true, changes: { status } };
+    const issues = publishGateIssues(ctx.registry, toWorkingRow(row, row.tenantId));
+    if (issues.length > 0) {
+        return { ok: false, failure: writeFailure(new ValidationError({ fields: [...issues] })) };
+    }
+    return { ok: true, changes: { ...parseTemplateDraft(row.draft), ...activationChanges(row) } };
+}
+function createStatusUpdateHandler(name, target, status, description) {
     return defineWriteHandler({
         name,
         schema: z.object({ id: z.string().min(1) }),
-        access: { roles: ["TenantAdmin", "SystemAdmin"] },
+        access: writeAccessFor(target),
+        // 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, {
-                id: event.payload.id,
-            });
-            if (!existing) {
+            const { db, scoped, row } = await loadTargetRow(ctx, target, event.user, event.payload.id);
+            if (!row)
                 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 plan = planStatusChange(ctx, row, status);
+            if (!plan.ok)
+                return plan.failure;
+            const result = await executor.update({ id: row.id, version: row.version, changes: plan.changes }, event.user, db, scoped ? { streamTenantId: scoped.streamTenantId } : undefined);
             if (!result.isSuccess)
                 return result;
-            return { isSuccess: true, data: { id: String(existing.id), status } };
+            return { isSuccess: true, data: { id: String(row.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. An open draft stays.");
+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 (a draft saved beside an active version replaces it), or to bring an archived template back; a version with unknown placeholders or unused required variables is refused and the served version stays.");
+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; an open draft beside the active version replaces it; SystemAdmin only, a version with unknown placeholders or unused required variables is refused.");

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, undefined>;

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, undefined>;

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
@@ -17,69 +15,20 @@ export const upsertTenantWrite = defineWriteHandler({
         status: z.enum(["draft", "active"]).default("draft"),
     }),
     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.",
+    description: "Creates or overwrites a tenant-scoped template override with its variable schema, landing as a draft that only publish makes live (over an active override the draft is stored beside it, the active version keeps being served until publish); 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,24 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { TEMPLATE_KINDS } from "../constants.js";
+import { templateResourcesTable } from "../table.js";
+import { templateSlugSchema } from "../template-meta.js";
+import { collectTemplateUsage } from "../template-usage.js";
+import { effectiveMailLayoutSlugs } from "./overview.query.js";
+const MAIL_ROW_LIMIT = 5000;
+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 and that has a code template, a mail layout by every mail notification whose effective template (own override, else system) names it, or whose code meta does when no stored template exists, or that 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;
+        if (kind !== "mail-layout")
+            return { usedBy: collectTemplateUsage(ctx.registry, slug, kind) };
+        const mailRows = await selectMany(ctx.db, templateResourcesTable, { kind: "mail" }, { limit: MAIL_ROW_LIMIT });
+        return {
+            usedBy: collectTemplateUsage(ctx.registry, slug, kind, effectiveMailLayoutSlugs(mailRows)),
+        };
+    },
+});

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 {};