@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/handlers/resource-link-pdf.write.ts

@@ -0,0 +1,34 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { linkTemplatePdfAttachment } from "../store-template-resource.js";
+import { resourceKeySchema, resourceTargetTenantId } from "./resource-shared.js";
+
+export const resourceLinkPdfWrite = defineWriteHandler({
+  name: "resource-link-pdf",
+  schema: z.object({
+    templateId: z.string().min(1),
+    key: resourceKeySchema,
+    /** Slug of a document-pdf template of the tenant or the system. */
+    templateSlug: z.string().min(1),
+    /** Name pattern of the attached PDF; may hold {{placeholders}}, must end with .pdf. */
+    fileName: z.string().min(1),
+    /** Cross-tenant target — SystemAdmin only. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Links a PDF rendered from a document-pdf template into a mail template under the key. Every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale; nothing is uploaded or stored. fileName is a pattern that may use the mail's {{placeholders}} and must end with .pdf. The document template must exist for the tenant or the system. Counts toward the 10 attachments per mail template together with uploaded files.",
+  handler: async (event, ctx) => {
+    const { templateId, key, templateSlug, fileName } = event.payload;
+    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+    return linkTemplatePdfAttachment({
+      ctx,
+      user: event.user,
+      tenantId,
+      templateId,
+      key,
+      templateSlug,
+      fileName,
+    });
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/resource-remove.write.ts

@@ -0,0 +1,50 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { requireForTenant } from "../../shared/index.js";
+import { parseLinkedResourceEntries } from "../linked-resources.js";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { resourceKeySchema, resourceTargetTenantId } from "./resource-shared.js";
+import { executor } from "./shared.js";
+
+// The FileRef itself stays: copy-locale and tenant overrides can share ids and there is
+// no reference count to tell when the last user is gone.
+export const resourceRemoveWrite = defineWriteHandler({
+  name: "resource-remove",
+  schema: z.object({
+    templateId: z.string().min(1),
+    key: resourceKeySchema,
+    /** Cross-tenant target — SystemAdmin only. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Unlinks a resource key from a template, whether it holds an image, an attached file or a linked PDF template; removing a key the template does not have succeeds without a change.",
+  handler: async (event, ctx) => {
+    const { templateId, key } = event.payload;
+    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+    const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+    const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+      tenantId,
+      id: templateId,
+    });
+    if (row === undefined) return writeFailure(new NotFoundError("template-resource", templateId));
+
+    const { [key]: removed, ...remaining } = parseLinkedResourceEntries(row.linkedResources);
+    if (removed === undefined) return { isSuccess: true as const, data: { key, removed: false } };
+
+    const updated = await executor.update(
+      {
+        id: row.id,
+        version: row.version,
+        changes: { linkedResources: JSON.stringify(remaining) },
+      },
+      event.user,
+      db,
+      { streamTenantId },
+    );
+    if (!updated.isSuccess) return updated;
+    return { isSuccess: true as const, data: { key, removed: true } };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/resource-shared.ts

@@ -0,0 +1,24 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { isDocumentResourceKey } from "../document-schema.js";
+
+export const RESOURCE_MAX_BYTES_CONFIG_KEY = "template-resolver:config:resource-max-bytes";
+export const DEFAULT_RESOURCE_MAX_BYTES = 2 * 1024 * 1024;
+
+export const resourceKeySchema = z.string().min(1).max(64).refine(isDocumentResourceKey, {
+  message: "resource key must be letters, digits, dot, dash or underscore",
+});
+
+export const RESOURCE_PURPOSES = ["image", "attachment"] as const;
+export type ResourcePurpose = (typeof RESOURCE_PURPOSES)[number];
+
+export const MAX_FILE_ATTACHMENTS_PER_TEMPLATE = 10;
+
+export function resourceTargetTenantId(
+  tenantIdOverride: string | undefined,
+  sessionTenantId: TenantId,
+): TenantId {
+  // @cast-boundary engine-payload — override is a zod-validated string; forTenant
+  // rejects it for non-SystemAdmins.
+  return (tenantIdOverride ?? sessionTenantId) as TenantId;
+}

package/packages/bundled-features/src/template-resolver/handlers/resource-upload.write.ts

@@ -0,0 +1,135 @@
+import { defineWriteHandler, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  NotFoundError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import {
+  FileRefTooLargeError,
+  fileContextForTenant,
+  readFileRefContent,
+} from "../../file-foundation/index.js";
+import { attachmentFileNameSchema } from "../../shared/index.js";
+import { TemplateResolverErrors } from "../qualified-names.js";
+import {
+  readTemplateResourceMaxBytes,
+  type StoredTemplateAttachment,
+  type StoredTemplateResource,
+  storeTemplateAttachment,
+  storeTemplateResource,
+} from "../store-template-resource.js";
+import { RESOURCE_PURPOSES, resourceKeySchema, resourceTargetTenantId } from "./resource-shared.js";
+
+type AttachmentTarget = {
+  readonly templateId: string;
+  readonly key: string;
+  readonly fileName: string;
+};
+
+function attachmentTargetOf(input: {
+  readonly templateId: string | undefined;
+  readonly key: string | undefined;
+  readonly fileName: string | undefined;
+}): AttachmentTarget | null {
+  const { templateId, key, fileName } = input;
+  if (templateId === undefined || key === undefined || fileName === undefined) return null;
+  const parsedName = attachmentFileNameSchema.safeParse(fileName);
+  return parsedName.success ? { templateId, key, fileName: parsedName.data } : null;
+}
+
+// Purpose "image": stores a re-encoded image as a FileRef and, with templateId + key, links it into
+// the template; without templateId it only creates the FileRef (the branding logo upload path).
+// Purpose "attachment": stores the file as uploaded and links it as a mail attachment.
+export const resourceUploadWrite = defineWriteHandler({
+  name: "resource-upload",
+  schema: z
+    .object({
+      templateId: z.string().min(1).optional(),
+      key: resourceKeySchema.optional(),
+      /** An unclaimed upload of the caller (POST /api/files without entityType). */
+      sourceFileRefId: z.uuid(),
+      /** Cross-tenant target — SystemAdmin only. */
+      tenantIdOverride: z.string().min(1).optional(),
+      /** "attachment" links a PDF/PNG/JPEG as a file attached to every mail of the template. */
+      purpose: z.enum(RESOURCE_PURPOSES).default("image"),
+      /** Name the recipient sees; required for purpose "attachment". */
+      fileName: z.string().optional(),
+    })
+    .refine(
+      (p) => p.purpose === "attachment" || (p.templateId === undefined) === (p.key === undefined),
+      {
+        message: "templateId and key must be given together",
+        path: ["key"],
+      },
+    ),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Turns a file uploaded via POST /api/files (multipart, no entityType) into a template resource. With purpose image (default) the upload is checked against the resource-max-bytes cap, re-encoded to a supported image format and stored as a new file; with templateId and key it is linked into that template under the key, without them only the file is created. With purpose attachment, templateId, key and fileName are required: a PDF, PNG or JPEG is stored unchanged and linked into a mail template as a file attached to every mail sent from it, at most 10 per template. A cap above the files route's maxUploadSize has no effect.",
+  handler: async (
+    event,
+    ctx,
+  ): Promise<WriteResult<StoredTemplateResource | StoredTemplateAttachment>> => {
+    const { templateId, key, sourceFileRefId, purpose, fileName } = event.payload;
+    const attachmentTarget =
+      purpose === "attachment" ? attachmentTargetOf({ templateId, key, fileName }) : null;
+    if (purpose === "attachment" && attachmentTarget === null) {
+      return writeFailure(
+        new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+          i18nKey: "templateResolver.errors.attachment.invalid",
+          details: { code: "target_required" },
+        }),
+      );
+    }
+    const maxBytes = await readTemplateResourceMaxBytes(ctx.config, ctx.registry);
+
+    // The source is read from the session tenant only: with tenantIdOverride the upload
+    // sits in the admin's own tenant while the normalized file lands in the target tenant.
+    // Only the caller's own unclaimed upload qualifies, so a record-attached image of
+    // someone else cannot be copied into a template.
+    let source: Awaited<ReturnType<typeof readFileRefContent>>;
+    try {
+      source = await readFileRefContent({
+        db: ctx.db,
+        filesForTenant: (tid) => fileContextForTenant(ctx, ctx.user.tenantId, tid),
+        fileRefId: sourceFileRefId,
+        allowedTenantIds: [event.user.tenantId],
+        unclaimedUploadOf: event.user.id,
+        maxBytes,
+      });
+    } catch (cause) {
+      if (cause instanceof FileRefTooLargeError) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
+            i18nKey: "templateResolver.errors.resource.tooLarge",
+            details: { maxBytes, size: cause.size },
+          }),
+        );
+      }
+      throw cause;
+    }
+    if (source === null) return writeFailure(new NotFoundError("file-ref", sourceFileRefId));
+
+    // The source upload stays as an unclaimed file: bundled-features cannot reach the fileRef executor to delete it.
+    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+    if (attachmentTarget !== null) {
+      return storeTemplateAttachment({
+        ctx,
+        user: event.user,
+        tenantId,
+        bytes: source.content,
+        maxBytes,
+        ...attachmentTarget,
+      });
+    }
+    return storeTemplateResource({
+      ctx,
+      user: event.user,
+      tenantId,
+      bytes: source.content,
+      maxBytes,
+      ...(templateId !== undefined && { templateId }),
+      ...(key !== undefined && { key }),
+    });
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/send-test.write.ts

@@ -0,0 +1,135 @@
+import { defineWriteHandler, type Registry } 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 } as const;
+
+function emailChannelOf(registry: 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: "channel_error" | "not_sent") {
+  return writeFailure(
+    new UnprocessableError(TemplateResolverErrors.testMailFailed, {
+      i18nKey: "templateResolver.errors.testMail.failed",
+      details: { code },
+    }),
+  );
+}
+
+function errorCodeOf(error: unknown): string | undefined {
+  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: string;
+    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 as const, data: { subject, checks: preview.checks } };
+  },
+});

package/packages/bundled-features/src/template-resolver/handlers/set.write.ts

@@ -4,11 +4,15 @@ import {
   SYSTEM_TENANT_ID,
   type TenantId,
 } 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 { type TemplateResourceRow, 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
@@ -26,6 +30,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({
@@ -63,17 +70,39 @@ export const setWrite = defineWriteHandler({
       locale: event.payload.locale,
     });
 
+    const scope = tenantId === SYSTEM_TENANT_ID ? ("system" as const) : ("tenant" as const);
+    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" as const) : ("tenant" as const),
+      scope,
       parentTemplateId: null,
       // Text blocks have no draft stage — saving publishes, so resolveTemplate
       // (which only returns active rows) finds them.

package/packages/bundled-features/src/template-resolver/handlers/shared.ts

@@ -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.
@@ -16,6 +17,8 @@ export const slugSchema = z
   .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)
@@ -38,13 +41,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/packages/bundled-features/src/template-resolver/handlers/template-gates.ts

@@ -0,0 +1,196 @@
+import type { Registry, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import type { FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import {
+  CONTENT_FORMATS,
+  type ContentFormat,
+  TEMPLATE_KINDS,
+  type TemplateKind,
+} from "../constants.js";
+import { documentViolationsToFieldIssues } from "../document-sanitizer.js";
+import { sanitizeTemplateWriteBody, type TemplateWriteScope } from "../layout-regions.js";
+import { imageResourceKeysOf } from "../linked-resources.js";
+import type { TemplateResourceRow } from "../table.js";
+import { parseTemplateMeta, type TemplateMetaIssue } from "../template-meta.js";
+import {
+  resolveTemplateVariables,
+  type TemplateValidation,
+  validateTemplatePlaceholders,
+} from "../template-validation.js";
+
+const PLACEHOLDER_VALIDATED_KINDS: ReadonlySet<TemplateKind> = 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: ReadonlySet<string> = new Set([
+  "subject",
+  "previewText",
+  "senderName",
+  "replyTo",
+  "layoutSlug",
+  "fileName",
+]);
+
+function metaIssueToFieldIssue(issue: TemplateMetaIssue): FieldIssue {
+  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: TemplateValidation,
+  opts: { readonly requireAllRequired: boolean },
+): FieldIssue[] {
+  const issues: FieldIssue[] = [];
+  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;
+}
+
+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;
+    };
+
+const NO_PUBLISH_ISSUES: readonly FieldIssue[] = [];
+
+function isPlaceholderValidated(kind: TemplateKind, contentFormat: ContentFormat): boolean {
+  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: TemplateWriteInput): TemplateWriteResult {
+  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: string): kind is TemplateKind {
+  return isOneOf(TEMPLATE_KINDS, kind);
+}
+
+export function parseStoredJson(raw: string | null): unknown {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function isGatedKind(kind: string): kind is TemplateKind {
+  return isTemplateKind(kind) && (kind === "mail-layout" || PLACEHOLDER_VALIDATED_KINDS.has(kind));
+}
+
+export function storedRecord(raw: string | null): Readonly<Record<string, unknown>> {
+  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: Registry,
+  row: TemplateResourceRow,
+): readonly FieldIssue[] {
+  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;
+}