@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/template-resolver/seeding.ts

@@ -1,13 +1,13 @@
-// Boot-/Seed-Helper für App-Authors. Schreibt System-Templates (tenantId=
-// SYSTEM_TENANT_ID, scope=system, status=active) idempotent in die DB —
-// gleicher Projection-Pfad wie upsertSystem-Handler, ohne Access-Check.
+// Boot/seed helper for app authors. Writes system templates (tenantId=
+// SYSTEM_TENANT_ID, scope=system, status=active) idempotently — same projection
+// path as the upsertSystem handler, without the access check.
 //
-// **Wann nutzen?** runProdApp-seeds / TenantCreated-Hooks die Welcome-,
-// Incident- oder Feature-Mail-Slugs installieren, damit renderer-simple
-// (oder mail-html) sie per template-resolver auflösen kann.
+// Use it from runProdApp seeds or TenantCreated hooks that install the welcome,
+// incident or feature mail slugs, so the mail renderer can resolve them
+// through the template-resolver.
 //
-// Default ifExists="skip". `createSystemUser(SYSTEM_TENANT_ID)` als Actor —
-// bewusst nicht TestUsers (Prod-Seeds ≠ Test-Utilities).
+// Default ifExists="skip". The actor is `createSystemUser(SYSTEM_TENANT_ID)`,
+// deliberately not TestUsers (prod seeds are not test utilities).
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -19,6 +19,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
+  type Registry,
   type SessionUser,
   SYSTEM_TENANT_ID,
   type TenantId,
@@ -30,7 +31,12 @@ import {
 import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
 import { type ContentFormat, TEXT_BLOCK_KIND, type UpsertKind } from "./constants.js";
 import { executor } from "./handlers/shared.js";
+import { evaluateTemplateWrite } from "./handlers/template-gates.js";
+import { TEMPLATE_RESOLVER_FEATURE } from "./qualified-names.js";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+import type { TemplateBundle } from "./template-bundle.js";
+import { templateSlugSchema } from "./template-meta.js";
+import { variablesFromSchema } from "./template-validation.js";
 
 /** Drop projection orphans (no events anywhere) so boot seeds can recreate. */
 async function resolveExistingForEventStoreSeed(
@@ -65,7 +71,10 @@ export type SeedSystemTemplateOptions = {
   readonly content: string;
   readonly contentFormat: ContentFormat;
   readonly variableSchema?: Record<string, unknown>;
+  /** Omitted: links on an existing row stay untouched, so a re-seed on boot keeps images a
+   *  system admin uploaded through resource-upload. */
   readonly linkedResources?: Record<string, string>;
+  readonly meta?: unknown;
   readonly parentTemplateId?: string | null;
   readonly by?: SessionUser;
   readonly ifExists?: SeedIfExists;
@@ -75,10 +84,29 @@ export async function seedSystemTemplate(
   db: DbConnection,
   opts: SeedSystemTemplateOptions,
 ): Promise<{ id: string }> {
-  const tenantId = SYSTEM_TENANT_ID as TenantId;
+  const tenantId = SYSTEM_TENANT_ID;
   const by = opts.by ?? createSystemUser(tenantId);
   const tdb = createTenantDb(db, tenantId, "system");
 
+  const label = `seedSystemTemplate ${opts.slug}/${opts.kind}/${opts.locale}`;
+  const slug = templateSlugSchema.safeParse(opts.slug);
+  if (!slug.success) throw new Error(`${label} rejected: ${slug.error.issues[0]?.message}`);
+  const evaluated = evaluateTemplateWrite({
+    kind: opts.kind,
+    scope: "system",
+    contentFormat: opts.contentFormat,
+    content: opts.content,
+    rawMeta: opts.meta,
+    variables: variablesFromSchema(opts.variableSchema ?? {}),
+    resourceKeys: Object.keys(opts.linkedResources ?? {}),
+  });
+  const issues = evaluated.ok ? evaluated.publishIssues : evaluated.issues;
+  if (!evaluated.ok || issues.length > 0) {
+    throw new Error(
+      `${label} rejected: ${issues.map((issue) => `${issue.code} (${issue.params?.["detail"] ?? issue.path})`).join("; ")}`,
+    );
+  }
+
   const existingRow = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
     tenantId,
     slug: opts.slug,
@@ -93,17 +121,20 @@ export async function seedSystemTemplate(
   );
 
   const variableSchema = JSON.stringify(opts.variableSchema ?? {});
-  const linkedResources = JSON.stringify(opts.linkedResources ?? {});
+  const meta = evaluated.metaJson;
+  const linkedResources =
+    opts.linkedResources === undefined ? undefined : JSON.stringify(opts.linkedResources);
   const parentTemplateId = opts.parentTemplateId ?? null;
 
   const rowFields = {
     slug: opts.slug,
     kind: opts.kind,
     locale: opts.locale,
-    content: opts.content,
+    content: evaluated.content,
     contentFormat: opts.contentFormat,
     variableSchema,
-    linkedResources,
+    ...(linkedResources !== undefined && { linkedResources }),
+    meta,
     title: null,
     folder: null,
     scope: "system" as const,
@@ -111,7 +142,22 @@ export async function seedSystemTemplate(
     status: "active" as const,
   };
 
-  const applyUpdate = async (row: { id: string; version: number }): Promise<{ id: string }> => {
+  const applyUpdate = async (
+    row: { id: string; version: number },
+    current: TemplateResourceRow | null | undefined,
+  ): Promise<{ id: string }> => {
+    // Skip no-op updates so re-seeding on every pod boot does not bump
+    // version/modifiedAt or grow the event store.
+    if (
+      current?.content === rowFields.content &&
+      current?.contentFormat === rowFields.contentFormat &&
+      current?.title === rowFields.title &&
+      current?.variableSchema === rowFields.variableSchema &&
+      current?.meta === rowFields.meta &&
+      (linkedResources === undefined || current?.linkedResources === linkedResources)
+    ) {
+      return { id: String(row.id) };
+    }
     const result = await executor.update(
       { id: row.id, version: row.version, changes: rowFields },
       by,
@@ -127,7 +173,11 @@ export async function seedSystemTemplate(
     existing,
     ifExists: opts.ifExists,
     create: async () => {
-      const result = await executor.create({ ...rowFields, tenantId }, by, tdb);
+      const result = await executor.create(
+        { ...rowFields, linkedResources: linkedResources ?? "{}", tenantId },
+        by,
+        tdb,
+      );
       if (!result.isSuccess) {
         // Parallel boot pods can both delete the orphan and race on create —
         // unique on (tenantId, slug, kind, locale) → resolve winner and update.
@@ -152,7 +202,7 @@ export async function seedSystemTemplate(
             existing: resolved,
             ifExists: opts.ifExists,
             create: () => Promise.reject(new Error("seedSystemTemplate: unreachable create")),
-            update: applyUpdate,
+            update: (row) => applyUpdate(row, again),
           });
         }
         throw new Error(`seedSystemTemplate create failed: ${JSON.stringify(result)}`);
@@ -163,10 +213,90 @@ export async function seedSystemTemplate(
       }
       return { id: String(data.id) };
     },
-    update: applyUpdate,
+    update: (row) => applyUpdate(row, existingRow),
   });
 }
 
+export type SeedSystemTemplateBundleOptions = {
+  readonly by?: SessionUser;
+  readonly ifExists?: SeedIfExists;
+};
+
+// Seeds one system row per bundle locale. Bundled resources need a file
+// provider and the system tenant's file space, which a boot seed does not
+// have, so those go through the import-bundle-system write instead.
+export async function seedSystemTemplateBundle(
+  db: DbConnection,
+  bundle: TemplateBundle,
+  opts: SeedSystemTemplateBundleOptions = {},
+): Promise<{ ids: Record<string, string> }> {
+  if (Object.keys(bundle.resources).length > 0) {
+    throw new Error(
+      `seedSystemTemplateBundle ${bundle.slug}/${bundle.kind}: bundles with resources cannot be seeded; use the import-bundle-system write`,
+    );
+  }
+  const ids: Record<string, string> = {};
+  for (const [locale, entry] of Object.entries(bundle.locales)) {
+    const seeded = await seedSystemTemplate(db, {
+      slug: bundle.slug,
+      kind: bundle.kind,
+      locale,
+      content: entry.body,
+      contentFormat: bundle.contentFormat,
+      variableSchema: bundle.variableSchema ?? {},
+      meta: entry.meta,
+      ...(opts.by !== undefined ? { by: opts.by } : {}),
+      ...(opts.ifExists !== undefined ? { ifExists: opts.ifExists } : {}),
+    });
+    ids[locale] = seeded.id;
+  }
+  return { ids };
+}
+
+export function hasNotificationTemplates(registry: Registry): boolean {
+  return Array.from(registry.getAllNotifications().values()).some(
+    (notification) => notification.template !== undefined,
+  );
+}
+
+// Boot seed for notifications that ship their mail text with the code
+// (`r.notification({ template, meta, variables })`). The code is authoritative,
+// so existing system rows are updated; tenant overrides are untouched.
+export async function seedNotificationTemplates(
+  db: DbConnection,
+  registry: Registry,
+): Promise<void> {
+  const hasTemplates = hasNotificationTemplates(registry);
+  if (hasTemplates && registry.getFeature(TEMPLATE_RESOLVER_FEATURE) === undefined) {
+    throw new Error(
+      `Notifications declare a mail template but the "${TEMPLATE_RESOLVER_FEATURE}" feature is not mounted`,
+    );
+  }
+  if (hasTemplates) {
+    // Dynamic: renderer-foundation imports this feature's barrel, a static import would cycle.
+    const { collectRendererPlugins } = await import("../renderer-foundation/index.js");
+    if (!collectRendererPlugins(registry).some((plugin) => plugin.kinds.includes("mail"))) {
+      throw new Error(
+        'Notifications declare a mail template but no renderer plugin for kind "mail" is registered (mount renderer-foundation and @cosmicdrift/kumiko-renderer-mail-html)',
+      );
+    }
+  }
+  for (const [slug, notification] of registry.getAllNotifications()) {
+    for (const [locale, { body }] of Object.entries(notification.template ?? {})) {
+      await seedSystemTemplate(db, {
+        slug,
+        kind: "mail",
+        locale,
+        content: body,
+        contentFormat: "html",
+        meta: notification.meta?.[locale],
+        variableSchema: notification.variables,
+        ifExists: "update",
+      });
+    }
+  }
+}
+
 export type SeedTextBlockOptions = {
   readonly tenantId: TenantId;
   readonly slug: string;
@@ -306,7 +436,7 @@ export async function seedLegalContentFromJson(
   blocks: readonly LegalContentBlock[],
   opts: { readonly tenantId?: TenantId; readonly by?: SessionUser } = {},
 ): Promise<void> {
-  const tenantId = opts.tenantId ?? (SYSTEM_TENANT_ID as TenantId);
+  const tenantId = opts.tenantId ?? SYSTEM_TENANT_ID;
   const by = opts.by ?? createSystemUser(tenantId);
   for (const block of blocks) {
     await seedTextBlock(db, {

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

@@ -0,0 +1,416 @@
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  ConfigAccessor,
+  HandlerContext,
+  Registry,
+  SessionUser,
+  TenantId,
+  WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  NotFoundError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { createFileRefFromBytes } from "@cosmicdrift/kumiko-framework/files";
+import { fileContextForTenant } from "../file-foundation/index.js";
+import type { FileAttachmentRef } from "../renderer-foundation/index.js";
+import { requireForTenant } from "../shared/index.js";
+import { SYSTEM_TENANT_ID } from "./constants.js";
+import {
+  DEFAULT_RESOURCE_MAX_BYTES,
+  MAX_FILE_ATTACHMENTS_PER_TEMPLATE,
+  RESOURCE_MAX_BYTES_CONFIG_KEY,
+} from "./handlers/resource-shared.js";
+import { executor } from "./handlers/shared.js";
+import {
+  attachmentEntriesOf,
+  type LinkedResourceEntry,
+  parseLinkedResourceEntries,
+  templatePdfAttachmentLinkSchema,
+} from "./linked-resources.js";
+import { TemplateResolverErrors } from "./qualified-names.js";
+import { normalizeResourceImage } from "./resource-image.js";
+import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+
+const EXTENSION_BY_CONTENT_TYPE: Readonly<Record<string, string>> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+};
+
+export async function readTemplateResourceMaxBytes(
+  config: ConfigAccessor | undefined,
+  registry: Registry,
+): Promise<number> {
+  if (config === undefined || registry.getConfigKey(RESOURCE_MAX_BYTES_CONFIG_KEY) === undefined) {
+    return DEFAULT_RESOURCE_MAX_BYTES;
+  }
+  const value = await config(RESOURCE_MAX_BYTES_CONFIG_KEY);
+  return typeof value === "number" ? value : DEFAULT_RESOURCE_MAX_BYTES;
+}
+
+export type StoredTemplateResource = {
+  readonly fileRefId: string;
+  readonly key?: string;
+  readonly contentType: string;
+  readonly width: number;
+  readonly height: number;
+  readonly size: number;
+};
+
+// Normalizes the image, stores it as a file ref of the target tenant and, with templateId + key,
+// links it into that tenant's template. The caller is responsible for authorization; the function trusts tenantId.
+export async function storeTemplateResource(args: {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly bytes: Uint8Array;
+  readonly maxBytes: number;
+  readonly templateId?: string;
+  readonly key?: string;
+}): Promise<WriteResult<StoredTemplateResource>> {
+  const { ctx, user, tenantId, bytes, maxBytes, templateId, key } = args;
+  if (bytes.length > maxBytes) {
+    return writeFailure(
+      new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
+        i18nKey: "templateResolver.errors.resource.tooLarge",
+        details: { maxBytes, size: bytes.length },
+      }),
+    );
+  }
+  let image: Awaited<ReturnType<typeof normalizeResourceImage>>;
+  try {
+    image = await normalizeResourceImage(Buffer.from(bytes));
+  } catch (cause) {
+    return writeFailure(
+      new UnprocessableError(TemplateResolverErrors.resourceUnsupportedImage, {
+        i18nKey: "templateResolver.errors.resource.unsupportedImage",
+        cause: cause instanceof Error ? cause : undefined,
+      }),
+    );
+  }
+
+  const { db, streamTenantId } = requireForTenant(ctx, tenantId);
+  let row: TemplateResourceRow | undefined;
+  if (templateId !== undefined) {
+    row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+      tenantId,
+      id: templateId,
+    });
+    if (row === undefined) return writeFailure(new NotFoundError("template-resource", templateId));
+  }
+
+  const created = await createFileRefFromBytes(
+    {
+      db,
+      files: fileContextForTenant(ctx, tenantId),
+      registry: ctx.registry,
+      user: { ...user, tenantId },
+    },
+    {
+      // Neutral name: the source's file name may be personal data.
+      fileName: `${key ?? "resource"}.${EXTENSION_BY_CONTENT_TYPE[image.contentType] ?? "bin"}`,
+      mimeType: image.contentType,
+      data: image.data,
+    },
+  );
+  if (!created.isSuccess) return created;
+
+  if (row !== undefined && key !== undefined) {
+    // The replaced FileRef stays: copy-locale and tenant overrides can share ids and
+    // there is no reference count to tell when the last user is gone.
+    const linkedResources = {
+      ...parseLinkedResourceEntries(row.linkedResources),
+      [key]: created.data.id,
+    };
+    const updated = await executor.update(
+      {
+        id: row.id,
+        version: row.version,
+        changes: { linkedResources: JSON.stringify(linkedResources) },
+      },
+      user,
+      db,
+      { streamTenantId },
+    );
+    if (!updated.isSuccess) return updated;
+  }
+
+  return {
+    isSuccess: true as const,
+    data: {
+      fileRefId: created.data.id,
+      ...(key !== undefined && { key }),
+      contentType: image.contentType,
+      width: image.width,
+      height: image.height,
+      size: image.data.length,
+    },
+  };
+}
+
+const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46, 0x2d] as const;
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const;
+const JPEG_MAGIC = [0xff, 0xd8, 0xff] as const;
+
+const ATTACHMENT_TYPES = [
+  { contentType: "application/pdf", extension: "pdf", magic: PDF_MAGIC },
+  { contentType: "image/png", extension: "png", magic: PNG_MAGIC },
+  { contentType: "image/jpeg", extension: "jpg", magic: JPEG_MAGIC },
+] as const;
+
+function detectAttachmentType(bytes: Uint8Array) {
+  return ATTACHMENT_TYPES.find(({ magic }) => magic.every((byte, index) => bytes[index] === byte));
+}
+
+export type StoredTemplateAttachment = {
+  readonly fileRefId: string;
+  readonly key: string;
+  readonly fileName: string;
+  readonly contentType: string;
+  readonly size: number;
+};
+
+type AttachmentType = NonNullable<ReturnType<typeof detectAttachmentType>>;
+
+export function attachmentNeedsMailTemplate(): WriteResult<never> {
+  return writeFailure(
+    new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+      i18nKey: "templateResolver.errors.attachment.invalid",
+      details: { code: "mail_only" },
+    }),
+  );
+}
+
+export function attachmentLimitFailure(): WriteResult<never> {
+  return writeFailure(
+    new UnprocessableError(TemplateResolverErrors.attachmentLimit, {
+      i18nKey: "templateResolver.errors.attachment.limit",
+      i18nParams: { max: MAX_FILE_ATTACHMENTS_PER_TEMPLATE },
+      details: { max: MAX_FILE_ATTACHMENTS_PER_TEMPLATE },
+    }),
+  );
+}
+
+// Files and rendered PDFs share one cap; the entry being replaced under `key` does not count.
+export function otherAttachmentCount(
+  linked: Readonly<Record<string, LinkedResourceEntry>>,
+  key: string,
+): number {
+  return attachmentEntriesOf(linked).filter(([linkedKey]) => linkedKey !== key).length;
+}
+
+function inspectAttachmentBytes(
+  bytes: Uint8Array,
+  maxBytes: number,
+): { readonly failure: WriteResult<never> } | { readonly type: AttachmentType } {
+  if (bytes.length > maxBytes) {
+    return {
+      failure: writeFailure(
+        new UnprocessableError(TemplateResolverErrors.resourceTooLarge, {
+          details: { maxBytes, size: bytes.length },
+        }),
+      ),
+    };
+  }
+  const type = detectAttachmentType(bytes);
+  if (type === undefined) {
+    return {
+      failure: writeFailure(
+        new UnprocessableError(TemplateResolverErrors.attachmentUnsupportedType, {
+          i18nKey: "templateResolver.errors.attachment.unsupportedType",
+        }),
+      ),
+    };
+  }
+  return { type };
+}
+
+// Stores the bytes unchanged as a file of the target tenant, without linking it anywhere.
+async function createAttachmentFileRef(args: {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly bytes: Uint8Array;
+  readonly key: string;
+  readonly type: AttachmentType;
+}): Promise<WriteResult<{ readonly id: string }>> {
+  const { ctx, user, tenantId, bytes, key, type } = args;
+  const { db } = requireForTenant(ctx, tenantId);
+  const created = await createFileRefFromBytes(
+    {
+      db,
+      files: fileContextForTenant(ctx, tenantId),
+      registry: ctx.registry,
+      user: { ...user, tenantId },
+    },
+    {
+      // Neutral stored name: the admin's file name may be personal data and lives in the link entry.
+      fileName: `${key}.${type.extension}`,
+      mimeType: type.contentType,
+      data: bytes,
+    },
+  );
+  return created.isSuccess ? { isSuccess: true, data: { id: created.data.id } } : created;
+}
+
+// Stores a PDF/PNG/JPEG for a bundle import: validated like an upload, linked later by the importer.
+export async function storeBundleAttachment(args: {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly bytes: Uint8Array;
+  readonly maxBytes: number;
+  readonly key: string;
+  readonly fileName: string;
+}): Promise<WriteResult<FileAttachmentRef>> {
+  const inspected = inspectAttachmentBytes(args.bytes, args.maxBytes);
+  if ("failure" in inspected) return inspected.failure;
+  const created = await createAttachmentFileRef({ ...args, type: inspected.type });
+  if (!created.isSuccess) return created;
+  return {
+    isSuccess: true,
+    data: { kind: "file", fileRefId: created.data.id, fileName: args.fileName },
+  };
+}
+
+// Stores a PDF/PNG/JPEG byte-for-byte (no re-encoding, the recipient gets what the admin uploaded)
+// and links it under `key` in a mail template of the target tenant. The caller authorizes tenantId.
+export async function storeTemplateAttachment(args: {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly bytes: Uint8Array;
+  readonly maxBytes: number;
+  readonly templateId: string;
+  readonly key: string;
+  readonly fileName: string;
+}): Promise<WriteResult<StoredTemplateAttachment>> {
+  const { ctx, user, tenantId, bytes, maxBytes, templateId, key, fileName } = args;
+  const inspected = inspectAttachmentBytes(bytes, maxBytes);
+  if ("failure" in inspected) return inspected.failure;
+  const { type } = inspected;
+
+  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));
+  if (row.kind !== "mail") return attachmentNeedsMailTemplate();
+
+  const linked = parseLinkedResourceEntries(row.linkedResources);
+  if (otherAttachmentCount(linked, key) >= MAX_FILE_ATTACHMENTS_PER_TEMPLATE) {
+    return attachmentLimitFailure();
+  }
+
+  const created = await createAttachmentFileRef({ ctx, user, tenantId, bytes, key, type });
+  if (!created.isSuccess) return created;
+
+  const entry: LinkedResourceEntry = { kind: "file", fileRefId: created.data.id, fileName };
+  const updated = await executor.update(
+    {
+      id: row.id,
+      version: row.version,
+      changes: { linkedResources: JSON.stringify({ ...linked, [key]: entry }) },
+    },
+    user,
+    db,
+    { streamTenantId },
+  );
+  if (!updated.isSuccess) return updated;
+
+  return {
+    isSuccess: true as const,
+    data: {
+      fileRefId: created.data.id,
+      key,
+      fileName,
+      contentType: type.contentType,
+      size: bytes.length,
+    },
+  };
+}
+
+export type LinkedTemplatePdfAttachment = {
+  readonly key: string;
+  readonly templateSlug: string;
+  readonly fileName: string;
+};
+
+function pdfAttachmentInvalid(code: string): WriteResult<never> {
+  return writeFailure(
+    new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+      i18nKey: "templateResolver.errors.attachment.invalid",
+      details: { code },
+    }),
+  );
+}
+
+// Links a PDF that is rendered from a document template at send time into a mail template of the
+// target tenant. Nothing is stored besides the link entry. The caller authorizes tenantId.
+export async function linkTemplatePdfAttachment(args: {
+  readonly ctx: HandlerContext;
+  readonly user: SessionUser;
+  readonly tenantId: TenantId;
+  readonly templateId: string;
+  readonly key: string;
+  readonly templateSlug: string;
+  readonly fileName: string;
+}): Promise<WriteResult<LinkedTemplatePdfAttachment>> {
+  const { ctx, user, tenantId, templateId, key } = args;
+  const link = templatePdfAttachmentLinkSchema.safeParse({
+    kind: "rendered-pdf",
+    templateSlug: args.templateSlug,
+    fileName: args.fileName,
+  });
+  if (!link.success) return pdfAttachmentInvalid("invalid_pdf_link");
+
+  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));
+  if (row.kind !== "mail") return attachmentNeedsMailTemplate();
+
+  const linked = parseLinkedResourceEntries(row.linkedResources);
+  if (otherAttachmentCount(linked, key) >= MAX_FILE_ATTACHMENTS_PER_TEMPLATE) {
+    return attachmentLimitFailure();
+  }
+
+  const visibleTemplates = await selectMany<TemplateResourceRow>(
+    db,
+    templateResourcesTable,
+    { tenantId: [tenantId, SYSTEM_TENANT_ID], slug: link.data.templateSlug, kind: "document-pdf" },
+    { limit: 1 },
+  );
+  if (visibleTemplates.length === 0) {
+    return writeFailure(
+      new UnprocessableError(TemplateResolverErrors.attachmentPdfTemplateMissing, {
+        i18nKey: "templateResolver.errors.attachment.pdfTemplateMissing",
+        i18nParams: { slug: link.data.templateSlug },
+        details: { templateSlug: link.data.templateSlug },
+      }),
+    );
+  }
+
+  const updated = await executor.update(
+    {
+      id: row.id,
+      version: row.version,
+      changes: { linkedResources: JSON.stringify({ ...linked, [key]: link.data }) },
+    },
+    user,
+    db,
+    { streamTenantId },
+  );
+  if (!updated.isSuccess) return updated;
+
+  return {
+    isSuccess: true as const,
+    data: { key, templateSlug: link.data.templateSlug, fileName: link.data.fileName },
+  };
+}