@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

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

@@ -0,0 +1,108 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { collectChannels, createEmailAttachmentReader, EMAIL_CHANNEL_NAME, } from "../../delivery/index.js";
+import { fileContextForTenant } from "../../file-foundation/index.js";
+import { TEST_MAIL_NOTIFICATION_TYPE, TEST_MAIL_SUBJECT_PREFIX } from "../constants.js";
+import { TemplateResolverErrors } from "../qualified-names.js";
+import { renderTemplatePreview } from "../template-preview.js";
+import { localeSchema, templateSlugSchema } from "./shared.js";
+const TEST_MAIL_RATE_LIMIT = { limit: 10, windowSeconds: 3600 };
+function emailChannelOf(registry) {
+    return collectChannels(registry).find((channel) => channel.name === EMAIL_CHANNEL_NAME);
+}
+// Transport errors can carry provider responses or the address, so the client only gets a fixed code.
+function testMailFailed(code) {
+    return writeFailure(new UnprocessableError(TemplateResolverErrors.testMailFailed, {
+        i18nKey: "templateResolver.errors.testMail.failed",
+        details: { code },
+    }));
+}
+function errorCodeOf(error) {
+    const code = error instanceof Error ? Reflect.get(error, "code") : undefined;
+    return typeof code === "string" ? code : undefined;
+}
+// The only recipient is the caller's own address, resolved server-side, so the handler can never mail a third party.
+export const sendTestWrite = defineWriteHandler({
+    name: "send-test",
+    schema: z.object({
+        slug: templateSlugSchema,
+        locale: localeSchema,
+        content: z.string().max(200_000).optional(),
+        meta: z.unknown().optional(),
+        variableSchema: z.record(z.string(), z.unknown()).default({}),
+        includeAttachments: z.boolean().default(true),
+        prefixSubject: z.boolean().default(true),
+    }),
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
+    description: "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples, and a draft that fails the write rules is rejected without sending.",
+    handler: async (event, ctx) => {
+        const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
+        const outcome = await renderTemplatePreview(ctx, event.user, {
+            ...previewPayload,
+            kind: "mail",
+        });
+        if (!outcome.ok)
+            return writeFailure(outcome.error);
+        const { preview, sender } = outcome;
+        const mailAttachments = includeAttachments
+            ? outcome.mailAttachments
+            : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
+        const channel = emailChannelOf(ctx.registry);
+        if (channel === undefined) {
+            return writeFailure(new UnprocessableError(TemplateResolverErrors.testMailNoChannel, {
+                i18nKey: "templateResolver.errors.testMail.noChannel",
+            }));
+        }
+        const channelContext = {
+            db: ctx.db,
+            registry: ctx.registry,
+            sseBroker: undefined,
+            tenantId: event.user.tenantId,
+            secrets: ctx.secrets,
+            readAttachment: createEmailAttachmentReader(ctx.db, ctx.registry, event.user.tenantId, ctx.config, (tenantId) => fileContextForTenant(ctx, ctx.user.tenantId, tenantId)),
+        };
+        const address = (await channel.resolve?.(event.user.id, channelContext)) ?? null;
+        if (address === null) {
+            return writeFailure(new UnprocessableError(TemplateResolverErrors.testMailNoAddress, {
+                i18nKey: "templateResolver.errors.testMail.noAddress",
+            }));
+        }
+        const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
+        let sentStatus;
+        try {
+            const result = await channel.send(address, {
+                notificationType: TEST_MAIL_NOTIFICATION_TYPE,
+                title: subject,
+                body: undefined,
+                data: undefined,
+                locale: event.payload.locale,
+            }, channelContext, {
+                subject,
+                html: preview.html,
+                text: preview.text ?? "",
+                ...sender,
+                attachments: mailAttachments,
+            });
+            sentStatus = result.status;
+        }
+        catch (error) {
+            // Class and code only: the message can carry the address or a provider response body.
+            ctx.log?.warn("template test mail: channel threw", {
+                tenantId: event.user.tenantId,
+                errorClass: error instanceof Error ? error.name : typeof error,
+                errorCode: errorCodeOf(error),
+            });
+            return testMailFailed("channel_error");
+        }
+        if (sentStatus !== "sent") {
+            ctx.log?.warn("template test mail: channel did not send", {
+                tenantId: event.user.tenantId,
+                status: sentStatus,
+            });
+            return testMailFailed("not_sent");
+        }
+        return { isSuccess: true, data: { subject, checks: preview.checks } };
+    },
+});

package/dist/template-resolver/handlers/set.write.d.ts

@@ -6,8 +6,11 @@ export declare const setWrite: import("@cosmicdrift/kumiko-types/define-handler"
         "ai-prompt": "ai-prompt";
         "document-pdf": "document-pdf";
         "image-snapshot": "image-snapshot";
-        "mail-html": "mail-html";
+        mail: "mail";
+        "mail-layout": "mail-layout";
         notification: "notification";
+        "pdf-layout": "pdf-layout";
+        snippet: "snippet";
         "text-block": "text-block";
     }>>;
     title: z.ZodString;
@@ -24,4 +27,4 @@ export declare const setWrite: import("@cosmicdrift/kumiko-types/define-handler"
     slug: string;
     locale: string;
     isNew: boolean;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

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

@@ -1,10 +1,14 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineWriteHandler, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.js";
-import { TEMPLATE_KINDS, TEXT_BLOCK_KIND } from "../constants.js";
+import { TEMPLATE_KINDS, TEXT_BLOCK_KIND, UPSERT_KINDS } from "../constants.js";
 import { templateResourcesTable } from "../table.js";
+import { resolveTemplateVariables } from "../template-validation.js";
 import { contentFormatSchema, executor, folderSchema, localeSchema, slugSchema } from "./shared.js";
+import { parseStoredJson, storedRecord } from "./template-gates.js";
+import { gateTemplateWrite } from "./template-write.js";
 // Upsert of a single resource, one operation per (tenantId, slug, kind,
 // locale). This is the content-tree authoring path: unlike upsertTenant it
 // takes a title and a folder, has no draft stage (saving publishes) and it may
@@ -21,6 +25,9 @@ import { contentFormatSchema, executor, folderSchema, localeSchema, slugSchema }
 // upsertTenant → publish draft stage. That is the deliberate split between
 // the two authoring routes — use upsertSystem/upsertTenant when a template
 // needs a draft or a variable schema.
+//
+// Kinds that upsertSystem/upsertTenant also write run the same validation
+// pipeline here, and because saving publishes, publish issues reject too.
 export const setWrite = defineWriteHandler({
     name: "set",
     schema: z.object({
@@ -55,17 +62,32 @@ export const setWrite = defineWriteHandler({
             kind,
             locale: event.payload.locale,
         });
+        const scope = tenantId === SYSTEM_TENANT_ID ? "system" : "tenant";
+        let content = event.payload.content;
+        if (isOneOf(UPSERT_KINDS, kind)) {
+            const gated = gateTemplateWrite({
+                kind,
+                scope,
+                contentFormat: event.payload.contentFormat,
+                content,
+                rawMeta: parseStoredJson(existing?.meta ?? null),
+                variables: resolveTemplateVariables(ctx.registry, event.payload.slug, storedRecord(existing?.variableSchema ?? null)),
+            }, "active");
+            if (!gated.ok)
+                return gated.failure;
+            content = gated.evaluated.content;
+        }
         const fields = {
             slug: event.payload.slug,
             kind,
             locale: event.payload.locale,
             title: event.payload.title,
-            content: event.payload.content,
+            content,
             contentFormat: event.payload.contentFormat,
             folder: event.payload.folder ?? null,
             variableSchema: "{}",
             linkedResources: "{}",
-            scope: tenantId === SYSTEM_TENANT_ID ? "system" : "tenant",
+            scope,
             parentTemplateId: null,
             // Text blocks have no draft stage — saving publishes, so resolveTemplate
             // (which only returns active rows) finds them.

package/dist/template-resolver/handlers/shared.d.ts

@@ -1,13 +1,16 @@
 import * as z from "zod";
+import { templateSlugSchema } from "../template-meta.js";
 export declare const executor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
 export declare const slugSchema: z.ZodString;
+export { templateSlugSchema };
 export declare const localeSchema: z.ZodString;
 export declare const kindSchema: z.ZodEnum<{
     "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";
 }>;
 export declare const folderSchema: z.ZodString;
 export declare const titleSchema: z.ZodString;
@@ -28,8 +31,9 @@ export declare const upsertPayloadSchema: z.ZodObject<{
         "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;
@@ -40,7 +44,7 @@ export declare const upsertPayloadSchema: z.ZodObject<{
         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>>;

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

@@ -2,6 +2,7 @@ import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import * as z from "zod";
 import { CONTENT_FORMATS, TEMPLATE_STATUSES, UPSERT_KINDS } from "../constants.js";
 import { templateResourceEntity, templateResourcesTable } from "../table.js";
+import { templateSlugSchema } from "../template-meta.js";
 // One executor per bundle, shared by all four handlers for create/update via
 // event store + optimistic lock.
 export const executor = createEventStoreExecutor(templateResourcesTable, templateResourceEntity, {
@@ -13,6 +14,7 @@ export const slugSchema = z
     .min(1)
     .max(80)
     .regex(/^[a-z0-9][a-z0-9-]*$/, "slug must be kebab-case (lowercase, digits, dashes)");
+export { templateSlugSchema };
 export const localeSchema = z
     .string()
     .min(2)
@@ -31,13 +33,15 @@ 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,
+    slug: templateSlugSchema,
     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({}),
+    // Shape depends on kind; validated against template-meta.ts in the handler so
+    // problems surface as field issues on `meta.*`.
+    meta: z.unknown().optional(),
     parentTemplateId: z.string().min(1).optional(),
     title: titleSchema.nullable().optional(),
     folder: folderSchema.nullable().optional(),

package/dist/template-resolver/handlers/template-gates.d.ts

@@ -0,0 +1,36 @@
+import type { Registry, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import type { FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import { type ContentFormat, type TemplateKind } from "../constants.js";
+import { type TemplateWriteScope } from "../layout-regions.js";
+import type { TemplateResourceRow } from "../table.js";
+import { type TemplateValidation } from "../template-validation.js";
+export declare function placeholderIssues(validation: TemplateValidation, opts: {
+    readonly requireAllRequired: boolean;
+}): FieldIssue[];
+export type TemplateWriteInput = {
+    readonly kind: TemplateKind;
+    readonly scope: TemplateWriteScope;
+    readonly contentFormat: ContentFormat;
+    readonly content: string | null;
+    readonly rawMeta: unknown;
+    readonly variables: TemplateVariables;
+    /** Keys with an uploaded file besides the built-in `logo`; only feeds the unknownResources warning. */
+    readonly resourceKeys?: readonly string[];
+};
+export type TemplateWriteResult = {
+    readonly ok: true;
+    readonly content: string | null;
+    readonly metaJson: string | null;
+    readonly validation: TemplateValidation | null;
+    /** Problems that still allow a draft but block publishing. */
+    readonly publishIssues: readonly FieldIssue[];
+} | {
+    readonly ok: false;
+    readonly issues: readonly FieldIssue[];
+    /** Set when the placeholder scan ran, so callers can still list what it found. */
+    readonly validation: TemplateValidation | null;
+};
+export declare function evaluateTemplateWrite(input: TemplateWriteInput): TemplateWriteResult;
+export declare function parseStoredJson(raw: string | null): unknown;
+export declare function storedRecord(raw: string | null): Readonly<Record<string, unknown>>;
+export declare function publishGateIssues(registry: Registry, row: TemplateResourceRow): readonly FieldIssue[];

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

@@ -0,0 +1,142 @@
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { CONTENT_FORMATS, TEMPLATE_KINDS, } from "../constants.js";
+import { documentViolationsToFieldIssues } from "../document-sanitizer.js";
+import { sanitizeTemplateWriteBody } from "../layout-regions.js";
+import { imageResourceKeysOf } from "../linked-resources.js";
+import { parseTemplateMeta } from "../template-meta.js";
+import { resolveTemplateVariables, validateTemplatePlaceholders, } from "../template-validation.js";
+const PLACEHOLDER_VALIDATED_KINDS = new Set([
+    "mail",
+    "document-pdf",
+    "pdf-layout",
+]);
+// The parser's wording is English and meant for logs; the UI gets a key per setting instead.
+const META_FIELDS_WITH_MESSAGES = new Set([
+    "subject",
+    "previewText",
+    "senderName",
+    "replyTo",
+    "layoutSlug",
+    "fileName",
+]);
+function metaIssueToFieldIssue(issue) {
+    const hasMessage = META_FIELDS_WITH_MESSAGES.has(issue.field);
+    return {
+        path: issue.path,
+        code: "invalid_meta",
+        i18nKey: hasMessage
+            ? `templateResolver.errors.template.meta.${issue.field}.${issue.missing ? "required" : "invalid"}`
+            : "templateResolver.errors.template.invalidMeta",
+    };
+}
+export function placeholderIssues(validation, opts) {
+    const issues = [];
+    if (validation.unknown.length > 0) {
+        issues.push({
+            path: "content",
+            code: "unknown_placeholder",
+            i18nKey: "templateResolver.errors.template.unknownPlaceholders",
+            params: { detail: validation.unknown.join(", ") },
+        });
+    }
+    if (opts.requireAllRequired && validation.missingRequired.length > 0) {
+        issues.push({
+            path: "content",
+            code: "missing_required_placeholder",
+            i18nKey: "templateResolver.errors.template.missingRequiredPlaceholders",
+            params: { detail: validation.missingRequired.join(", ") },
+        });
+    }
+    return issues;
+}
+const NO_PUBLISH_ISSUES = [];
+function isPlaceholderValidated(kind, contentFormat) {
+    if (kind === "mail-layout")
+        return contentFormat === "html";
+    return PLACEHOLDER_VALIDATED_KINDS.has(kind);
+}
+// The single validation pipeline of every template write: sanitize and layout
+// rules, then meta, then placeholders.
+export function evaluateTemplateWrite(input) {
+    const body = sanitizeTemplateWriteBody({
+        kind: input.kind,
+        scope: input.scope,
+        contentFormat: input.contentFormat,
+        content: input.content,
+    });
+    if (!body.ok)
+        return {
+            ok: false,
+            issues: documentViolationsToFieldIssues(body.violations),
+            validation: null,
+        };
+    const parsedMeta = parseTemplateMeta(input.kind, input.rawMeta);
+    if (!parsedMeta.ok) {
+        return { ok: false, issues: parsedMeta.issues.map(metaIssueToFieldIssue), validation: null };
+    }
+    const metaJson = parsedMeta.meta === null ? null : JSON.stringify(parsedMeta.meta);
+    if (!isPlaceholderValidated(input.kind, input.contentFormat)) {
+        return {
+            ok: true,
+            content: body.content,
+            metaJson,
+            validation: null,
+            publishIssues: NO_PUBLISH_ISSUES,
+        };
+    }
+    const validation = validateTemplatePlaceholders({
+        kind: input.kind,
+        body: body.content ?? "",
+        meta: parsedMeta.meta,
+        variables: input.variables,
+        resourceKeys: input.resourceKeys,
+    });
+    const issues = placeholderIssues(validation, { requireAllRequired: false });
+    if (issues.length > 0)
+        return { ok: false, issues, validation };
+    return {
+        ok: true,
+        content: body.content,
+        metaJson,
+        validation,
+        publishIssues: placeholderIssues(validation, { requireAllRequired: true }),
+    };
+}
+function isTemplateKind(kind) {
+    return isOneOf(TEMPLATE_KINDS, kind);
+}
+export function parseStoredJson(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isGatedKind(kind) {
+    return isTemplateKind(kind) && (kind === "mail-layout" || PLACEHOLDER_VALIDATED_KINDS.has(kind));
+}
+export function storedRecord(raw) {
+    const parsed = parseStoredJson(raw);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? Object.fromEntries(Object.entries(parsed))
+        : {};
+}
+// Publishing makes a row servable, so a stored row must pass the same pipeline
+// as an active write would have.
+export function publishGateIssues(registry, row) {
+    if (!isGatedKind(row.kind) || !isOneOf(CONTENT_FORMATS, row.contentFormat))
+        return [];
+    const result = evaluateTemplateWrite({
+        kind: row.kind,
+        scope: row.scope === "system" ? "system" : "tenant",
+        contentFormat: row.contentFormat,
+        content: row.content,
+        rawMeta: parseStoredJson(row.meta),
+        variables: resolveTemplateVariables(registry, row.slug, storedRecord(row.variableSchema)),
+        resourceKeys: imageResourceKeysOf(row.linkedResources),
+    });
+    return result.ok ? result.publishIssues : result.issues;
+}

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

@@ -0,0 +1,45 @@
+import { type HandlerContext, type SessionUser, type TemplateVariables, type TenantId, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { ContentFormat, TemplateKind } from "../constants.js";
+import type { TemplateWriteScope } from "../layout-regions.js";
+import type { TemplateValidation } from "../template-validation.js";
+import { type TemplateWriteInput, type TemplateWriteResult } from "./template-gates.js";
+export type TemplateRowPayload = {
+    readonly slug: string;
+    readonly kind: TemplateKind;
+    readonly locale: string;
+    readonly content: string | null;
+    readonly contentFormat: ContentFormat;
+    readonly variableSchema: Readonly<Record<string, unknown>>;
+    readonly meta?: unknown;
+    readonly title?: string | null | undefined;
+    readonly folder?: string | null | undefined;
+    readonly parentTemplateId?: string | null | undefined;
+};
+export type WrittenTemplateRow = {
+    readonly id: string;
+    readonly slug: string;
+    readonly isNew: boolean;
+    readonly validation: TemplateValidation | null;
+};
+export type TemplateRowWrite = {
+    readonly ctx: HandlerContext;
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly scope: TemplateWriteScope;
+    readonly status: "draft" | "active";
+    readonly variables: TemplateVariables;
+    readonly payload: TemplateRowPayload;
+};
+export declare function refuseTenantScopeUnderSystemTenant(scope: TemplateWriteScope, tenantId: string): WriteResult<never> | null;
+export type GatedTemplateWrite = {
+    readonly ok: true;
+    readonly evaluated: Extract<TemplateWriteResult, {
+        ok: true;
+    }>;
+} | {
+    readonly ok: false;
+    readonly failure: WriteFailure;
+};
+export declare function gateTemplateWrite(input: TemplateWriteInput, status: "draft" | "active"): GatedTemplateWrite;
+export declare function writeTemplateRow(args: TemplateRowWrite): Promise<WriteResult<WrittenTemplateRow>>;

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

@@ -0,0 +1,141 @@
+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 { activationChanges, serializeTemplateDraft } from "../template-draft.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 };
+}
+// A draft over an active row is stored beside it; every other write replaces the main fields.
+function updateChanges(existing, status, fields) {
+    if (status === "active")
+        return { ...fields, ...activationChanges(existing) };
+    if (existing.status !== "active")
+        return { ...fields, status, draft: null };
+    const draft = serializeTemplateDraft({
+        content: fields.content,
+        contentFormat: fields.contentFormat,
+        variableSchema: fields.variableSchema,
+        meta: fields.meta,
+        title: fields.title,
+        folder: fields.folder,
+        parentTemplateId: fields.parentTemplateId,
+    });
+    return existing.activeVersion === null
+        ? {
+            draft,
+            activeVersion: existing.version,
+            activeSince: existing.modifiedAt ?? existing.insertedAt,
+        }
+        : { draft };
+}
+// 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: updateChanges(existing, status, 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,
+        draft: null,
+        ...(status === "active" ? activationChanges(null) : {}),
+    }, 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,
+        },
+    };
+}