@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -1,8 +1,9 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { filterDeliveredTo } from "../api.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
-import { deliveryPolicyOf, isRowServedTo } from "../template-delivery-policy.ts";
+import { deliveryPolicyOf } from "../template-delivery-policy.ts";
 import { isHiddenSystemDraft } from "../template-draft.ts";
 import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.ts";
 import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../web/constants.ts";
@@ -40,30 +41,28 @@ export const listQuery = defineQueryHandler({
       where["status"] = query.payload.status;
     }
 
-    // @cast-boundary db-row — selectMany returnt unknown[]; Row-Shape ist
+    // @cast-boundary db-row — selectMany returns unknown[]; Row shape is
     // durch templateResourcesTable + buildBaseColumns garantiert.
     const rows = (await selectMany(ctx.db, templateResourcesTable, where, {
       limit: 500,
     })) as TemplateResourceRow[];
 
     const deliveryPolicy = deliveryPolicyOf(ctx.registry);
-    return rows
-      .filter(
-        (row) =>
-          !isHiddenSystemDraft(query.user, row) &&
-          !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row) &&
-          isRowServedTo(deliveryPolicy, query.user, row),
-      )
-      .map((row) => ({
-        id: String(row.id),
-        tenantId: row.tenantId,
-        slug: row.slug,
-        kind: row.kind,
-        locale: row.locale,
-        scope: row.scope,
-        status: row.status,
-        contentFormat: row.contentFormat,
-        modifiedAt: row.modifiedAt,
-      }));
+    const candidates = rows.filter(
+      (row) =>
+        !isHiddenSystemDraft(query.user, row) &&
+        !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row),
+    );
+    return (await filterDeliveredTo(ctx.db, deliveryPolicy, query.user, candidates)).map((row) => ({
+      id: String(row.id),
+      tenantId: row.tenantId,
+      slug: row.slug,
+      kind: row.kind,
+      locale: row.locale,
+      scope: row.scope,
+      status: row.status,
+      contentFormat: row.contentFormat,
+      modifiedAt: row.modifiedAt,
+    }));
   },
 });

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

@@ -155,6 +155,19 @@ function effectiveRowsOf(
     : null;
 }
 
+export function isRowVisibleToCaller(
+  policy: TemplateEditPolicy,
+  user: Parameters<typeof isHiddenSystemDraft>[0],
+  registry: Parameters<typeof isSystemOnlyTemplateHiddenFrom>[1],
+  row: TemplateResourceRow,
+): boolean {
+  return (
+    !isHiddenSystemDraft(user, row) &&
+    !isSystemOnlyTemplateHiddenFrom(user, registry, row) &&
+    mayEditTemplate(policy, user, row)
+  );
+}
+
 export function effectiveMailLayoutSlugs(
   rows: readonly TemplateResourceRow[],
   policy: TemplateDeliveryPolicy,
@@ -385,11 +398,8 @@ export function makeOverviewQuery(policy: TemplateEditPolicy) {
         });
       }
 
-      const visibleRows = rows.filter(
-        (row) =>
-          !isHiddenSystemDraft(query.user, row) &&
-          !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row) &&
-          mayEditTemplate(policy, query.user, row),
+      const visibleRows = rows.filter((row) =>
+        isRowVisibleToCaller(policy, query.user, ctx.registry, row),
       );
       const deliveryPolicy = deliveryPolicyOf(ctx.registry);
       const { drafts, layoutSlugByDocument } = buildDrafts(

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

@@ -38,8 +38,8 @@ export const titleSchema = z.string().min(1).max(200);
 export const contentFormatSchema = z.enum(CONTENT_FORMATS);
 export const statusSchema = z.enum(TEMPLATE_STATUSES);
 
-// Common Upsert-Payload — geteilt zwischen upsertSystem + upsertTenant.
-// Unterschied: ACL + tenantId-Bestimmung, sonst identisch.
+// Common upsert payload shared by upsertSystem and upsertTenant.
+// Only ACL and tenantId determination differ.
 export const upsertPayloadSchema = z.object({
   slug: templateSlugSchema,
   kind: kindSchema,

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

@@ -258,9 +258,9 @@ export async function writeTemplateRow(
     { 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.
+  // @cast-boundary db-row — executor.create returns a row from
+  // INSERT RETURNING; the { id } shape is guaranteed because the primary key is in the
+  // RETURNING clause.
   const createdRow = result.data as { id: string | number };
   return {
     isSuccess: true,

package/packages/bundled-features/src/template-resolver/handlers/tenant-override-counts.query.ts

@@ -8,6 +8,11 @@ import {
   TENANT_OVERRIDES_REASON,
 } from "./tenant-override-selection.ts";
 
+type OverrideCountRow = Pick<
+  TemplateResourceRow,
+  "tenantId" | "slug" | "kind" | "status" | "version"
+>;
+
 export const tenantOverrideCountsResultSchema = z.object({
   totalTenants: z.number().nullable(),
   counts: z.array(z.object({ slug: z.string(), kind: z.string(), activeOverrides: z.number() })),
@@ -21,18 +26,17 @@ export const tenantOverrideCountsQuery = defineQueryHandler({
     "Counts, per template slug and kind, the enabled tenants that override it with an active version, next to the number of enabled tenants; one query for the whole template overview instead of one tenant-overrides call per row.",
   escapeHatch: { grants: ["unsafeRaw"], reason: TENANT_OVERRIDES_REASON },
   handler: async (_query, ctx) => {
-    const found = await selectMany<TemplateResourceRow>(
+    const found = await selectMany<OverrideCountRow>(
       ctx.db.unsafeRaw(),
       templateResourcesTable,
-      {
-        scope: "tenant",
-      },
+      { scope: "tenant" },
+      { fields: ["tenantId", "slug", "kind", "status", "version"] },
     );
     const enabledTenantIds = await loadEnabledTenantIds(ctx);
 
     const rowsBySlugAndKind = new Map<
       string,
-      { slug: string; kind: string; rows: TemplateResourceRow[] }
+      { slug: string; kind: string; rows: OverrideCountRow[] }
     >();
     for (const row of found) {
       const key = `${row.kind}|${row.slug}`;

package/packages/bundled-features/src/template-resolver/handlers/tenant-override-selection.ts

@@ -21,8 +21,10 @@ export async function loadEnabledTenantIds(
   return new Set(tenantIdsSchema.parse(await ctx.query(TenantQueries.activeTenantIds, {})));
 }
 
+export type OverrideCandidate = Pick<TemplateResourceRow, "tenantId" | "status" | "version">;
+
 // One row per tenant: its active override wins over a draft, then the newest version.
-function isBetterRow(candidate: TemplateResourceRow, current: TemplateResourceRow): boolean {
+function isBetterRow(candidate: OverrideCandidate, current: OverrideCandidate): boolean {
   if ((candidate.status === "active") !== (current.status === "active")) {
     return candidate.status === "active";
   }
@@ -30,18 +32,18 @@ function isBetterRow(candidate: TemplateResourceRow, current: TemplateResourceRo
 }
 
 function isCountedTenantRow(
-  row: TemplateResourceRow,
+  row: OverrideCandidate,
   enabledTenantIds: ReadonlySet<string> | null,
 ): boolean {
   if (row.tenantId === SYSTEM_TENANT_ID || row.status === "archived") return false;
   return enabledTenantIds === null || enabledTenantIds.has(row.tenantId);
 }
 
-export function pickBestRowPerTenant(
-  found: readonly TemplateResourceRow[],
+export function pickBestRowPerTenant<TRow extends OverrideCandidate>(
+  found: readonly TRow[],
   enabledTenantIds: ReadonlySet<string> | null,
-): Map<string, TemplateResourceRow> {
-  const bestByTenant = new Map<string, TemplateResourceRow>();
+): Map<string, TRow> {
+  const bestByTenant = new Map<string, TRow>();
   for (const row of found) {
     if (!isCountedTenantRow(row, enabledTenantIds)) continue;
     const current = bestByTenant.get(row.tenantId);

package/packages/bundled-features/src/template-resolver/handlers/tenant-overrides.query.ts

@@ -1,5 +1,9 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
-import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  defineQueryHandler,
+  MAX_LIST_LIMIT,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { TenantQueries } from "../../tenant/index.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
@@ -18,8 +22,39 @@ const directorySchema = z.object({
 
 type OverrideStatus = "active" | "draft";
 
-function labelsOf(raw: unknown): ReadonlyMap<string, string> {
-  return new Map(directorySchema.parse(raw).rows.map((row) => [row.id, row.label]));
+function chunksOf<T>(items: readonly T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let start = 0; start < items.length; start += size) {
+    chunks.push(items.slice(start, start + size));
+  }
+  return chunks;
+}
+
+type DirectoryQueryContext = {
+  readonly query: (name: string, payload: { ids: string[] }) => Promise<unknown>;
+};
+
+// Looks up only the ids the overrides need, so labels never depend on the directory's default cap.
+async function labelsFor(
+  ctx: DirectoryQueryContext,
+  queryName: string,
+  ids: ReadonlySet<string>,
+): Promise<ReadonlyMap<string, string>> {
+  const labels = new Map<string, string>();
+  for (const chunk of chunksOf([...ids], MAX_LIST_LIMIT)) {
+    const raw = await ctx.query(queryName, { ids: chunk });
+    for (const row of directorySchema.parse(raw).rows) labels.set(row.id, row.label);
+  }
+  return labels;
+}
+
+function changerIdsOf(rows: readonly TemplateResourceRow[]): ReadonlySet<string> {
+  const ids = new Set<string>();
+  for (const row of rows) {
+    const changedById = row.modifiedById ?? row.insertedById;
+    if (changedById !== null) ids.add(changedById);
+  }
+  return ids;
 }
 
 function statusOf(row: TemplateResourceRow): OverrideStatus {
@@ -73,10 +108,14 @@ export const tenantOverridesQuery = defineQueryHandler({
     const bestByTenant = pickBestRowPerTenant(found, enabledTenantIds);
     const best = [...bestByTenant.values()];
     const tenantLabels = hasTenantFeature
-      ? labelsOf(await ctx.query(TenantQueries.tenantDirectory, {}))
+      ? await labelsFor(
+          ctx,
+          TenantQueries.tenantDirectory,
+          new Set(best.map((row) => row.tenantId)),
+        )
       : new Map<string, string>();
     const userLabels = hasTenantFeature
-      ? labelsOf(await ctx.query(TenantQueries.memberDirectory, {}))
+      ? await labelsFor(ctx, TenantQueries.memberDirectory, changerIdsOf(best))
       : new Map<string, string>();
 
     const rows = best

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

@@ -3,10 +3,9 @@ import { resolveTemplateVariables } from "../template-validation.ts";
 import { upsertPayloadSchema } from "./shared.ts";
 import { writeTemplateRow } from "./template-write.ts";
 
-// 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
-// Overrides.
+// Creates or updates a system template under SYSTEM_TENANT_ID with
+// scope='system'. Only SystemAdmin can change these global defaults;
+// TenantAdmin uses upsertTenant for overrides instead.
 export const upsertSystemWrite = defineWriteHandler({
   name: "upsert-system",
   schema: upsertPayloadSchema,

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

@@ -9,11 +9,10 @@ import { resolveTemplateVariables } from "../template-validation.ts";
 import { upsertPayloadSchema } from "./shared.ts";
 import { writeTemplateRow } from "./template-write.ts";
 
-// 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
-// einen anderen Tenant schreiben (typisch: Plattform-Admin-UI das
-// Tenant-Templates kuratiert).
+// Creates or updates a tenant override under event.user.tenantId with scope='tenant'.
+// The default status is 'draft'; users must publish explicitly via the publish handler.
+// SystemAdmin can write for another tenant through tenantIdOverride, typically to
+// curate tenant templates from a platform admin UI.
 export function makeUpsertTenantWrite(policy: TemplateEditPolicy) {
   return defineWriteHandler({
     name: "upsert-tenant",

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

@@ -3,35 +3,46 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
 import { deliveryPolicyOf } from "../template-delivery-policy.ts";
+import type { TemplateEditPolicy } from "../template-edit-policy.ts";
 import { templateSlugSchema } from "../template-meta.ts";
 import { collectTemplateUsage } from "../template-usage.ts";
 import { TEMPLATE_KINDS } from "../web/constants.ts";
-import { effectiveMailLayoutSlugs } from "./overview.query.ts";
+import { effectiveMailLayoutSlugs, isRowVisibleToCaller } from "./overview.query.ts";
 
 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<TemplateResourceRow>(
-      ctx.db,
-      templateResourcesTable,
-      { kind: "mail" },
-      { limit: MAIL_ROW_LIMIT },
-    );
-    return {
-      usedBy: collectTemplateUsage(
-        ctx.registry,
-        slug,
-        kind,
-        effectiveMailLayoutSlugs(mailRows, deliveryPolicyOf(ctx.registry)),
-      ),
-    };
-  },
-});
+export function makeUsageQuery(policy: TemplateEditPolicy) {
+  return 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 fetchedRows = await selectMany<TemplateResourceRow>(
+        ctx.db,
+        templateResourcesTable,
+        { kind: "mail" },
+        { orderBy: { col: "id", direction: "asc" }, limit: MAIL_ROW_LIMIT + 1 },
+      );
+      if (fetchedRows.length > MAIL_ROW_LIMIT) {
+        ctx.log?.warn("template usage: row limit reached, result is incomplete", {
+          limit: MAIL_ROW_LIMIT,
+        });
+      }
+      const visibleRows = fetchedRows
+        .slice(0, MAIL_ROW_LIMIT)
+        .filter((row) => isRowVisibleToCaller(policy, query.user, ctx.registry, row));
+      return {
+        usedBy: collectTemplateUsage(
+          ctx.registry,
+          slug,
+          kind,
+          effectiveMailLayoutSlugs(visibleRows, deliveryPolicyOf(ctx.registry)),
+        ),
+      };
+    },
+  });
+}

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

@@ -6,10 +6,11 @@ import {
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { isRowDeliveredTo } from "../api.ts";
 import type { TemplateWriteScope } from "../layout-regions.ts";
 import { imageResourceKeysOf } from "../linked-resources.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
-import { deliveryPolicyOf, isRowServedTo } from "../template-delivery-policy.ts";
+import { deliveryPolicyOf } from "../template-delivery-policy.ts";
 import { isSystemAdmin } from "../template-draft.ts";
 import { resolveTemplateVariables, systemPlaceholdersFor } from "../template-validation.ts";
 import type { ContentFormat, UpsertKind } from "../web/constants.ts";
@@ -69,7 +70,11 @@ export async function knownResourceKeysFor(
       locale,
     })),
     ...(scope === "tenant" &&
-    isRowServedTo(deliveryPolicyOf(ctx.registry), user, { tenantId: user.tenantId, kind, slug })
+    (await isRowDeliveredTo(ctx.db, deliveryPolicyOf(ctx.registry), user, {
+      tenantId: user.tenantId,
+      kind,
+      slug,
+    }))
       ? await knownResourceKeys(ctx.db, { tenantId: user.tenantId, slug, kind, scope, locale })
       : []),
   ];

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

@@ -29,7 +29,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/event-store";
 import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
 import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { executor } from "./handlers/shared.ts";
 import { evaluateTemplateWrite } from "./handlers/template-gates.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.ts";
@@ -85,10 +85,19 @@ export type SeedSystemTemplateOptions = {
   readonly ifExists?: SeedIfExists;
 };
 
+// Namespace prefix plus path, no whitespace: keeps free text from passing as a key that the UI
+// would then show raw.
+const I18N_KEY_FORMAT = /^[^\s:]+:\S+$/;
+
 function seedTitleColumn(opts: SeedSystemTemplateOptions, label: string): string | null {
   if (opts.title !== undefined && opts.titleI18nKey !== undefined) {
     throw new Error(`${label} rejected: set either title or titleI18nKey, not both`);
   }
+  if (opts.titleI18nKey !== undefined && !I18N_KEY_FORMAT.test(opts.titleI18nKey)) {
+    throw new Error(
+      `${label} rejected: titleI18nKey "${opts.titleI18nKey}" is not a "namespace:key" i18n key`,
+    );
+  }
   return opts.titleI18nKey ?? opts.title ?? null;
 }
 
@@ -167,21 +176,20 @@ export async function seedSystemTemplate(
       current?.title === rowFields.title &&
       current?.variableSchema === rowFields.variableSchema &&
       current?.meta === rowFields.meta &&
-      current?.status === rowFields.status &&
       current?.parentTemplateId === rowFields.parentTemplateId &&
       (linkedResources === undefined || current?.linkedResources === linkedResources)
     ) {
       return { id: String(row.id) };
     }
-    const result = await executor.update(
-      {
-        id: row.id,
-        version: row.version,
-        changes: { ...rowFields, ...activeStampChanges(row) },
-      },
-      by,
-      tdb,
-    );
+    // An archived system row is a SystemAdmin decision (reversible with publish-system) that a
+    // pod-boot re-seed must not undo; content still follows the code. The seed replaces the
+    // content, so an open draft on the old content is dropped with it.
+    const { status: _status, ...contentFields } = rowFields;
+    const changes =
+      current?.status === "archived"
+        ? { ...contentFields, status: "archived" as const, draft: null }
+        : { ...rowFields, ...activeStampChanges(row), draft: null };
+    const result = await executor.update({ id: row.id, version: row.version, changes }, by, tdb);
     if (!result.isSuccess) {
       throw new Error(`seedSystemTemplate update failed: ${JSON.stringify(result)}`);
     }
@@ -232,11 +240,11 @@ export async function seedSystemTemplate(
         }
         throw new Error(`seedSystemTemplate create failed: ${JSON.stringify(result)}`);
       }
-      const data = result.data as Partial<TemplateResourceRow>;
-      if (data.id === undefined) {
+      const createdId = propertyOf(result.data, "id");
+      if (createdId === undefined) {
         throw new Error("seedSystemTemplate: executor.create did not return an id");
       }
-      return { id: String(data.id) };
+      return { id: String(createdId) };
     },
     update: (row) => applyUpdate(row, existingRow),
   });
@@ -292,8 +300,10 @@ async function seedSystemTemplateBundleWithResources(
       `${label}: bundles with resources need a file provider; pass opts.dispatcher (the dispatcher of the seed deps) so the files are stored through the import-bundle-system write`,
     );
   }
-  if ((opts.ifExists ?? "skip") === "skip") {
-    const existingIds: Record<string, string> = {};
+  const skipExisting = (opts.ifExists ?? "skip") === "skip";
+  const existingIds: Record<string, string> = {};
+  let bundleToImport = bundle;
+  if (skipExisting) {
     for (const locale of Object.keys(bundle.locales)) {
       const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
         tenantId: SYSTEM_TENANT_ID,
@@ -306,16 +316,24 @@ async function seedSystemTemplateBundleWithResources(
     if (Object.keys(existingIds).length === Object.keys(bundle.locales).length) {
       return { ids: existingIds };
     }
+    // import-bundle-system always overwrites, so only the missing locales go in: a
+    // hand-edited system row of an already seeded locale must survive the new-locale boot.
+    bundleToImport = {
+      ...bundle,
+      locales: Object.fromEntries(
+        Object.entries(bundle.locales).filter(([locale]) => !(locale in existingIds)),
+      ),
+    };
   }
   const result = await dispatcher.write(
     TemplateResolverHandlers.importBundleSystem,
-    { bundle },
+    { bundle: bundleToImport },
     opts.by ?? createSystemUser(SYSTEM_TENANT_ID, ["SystemAdmin"]),
   );
   if (!result.isSuccess) {
     throw new Error(`${label} failed: ${result.error.code}: ${result.error.message}`);
   }
-  return { ids: importedIds(result.data) };
+  return { ids: { ...existingIds, ...importedIds(result.data) } };
 }
 
 function importedIds(data: unknown): Record<string, string> {

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

@@ -87,6 +87,10 @@ function keyInUse(): WriteResult<never> {
   );
 }
 
+function isImageKey(links: Readonly<Record<string, LinkedResourceEntry>>, key: string) {
+  return typeof links[key] === "string";
+}
+
 function isAttachmentKey(links: Readonly<Record<string, LinkedResourceEntry>>, key: string) {
   const occupant = links[key];
   return occupant !== undefined && typeof occupant !== "string";
@@ -265,6 +269,20 @@ export async function releaseAll(releases: readonly Release[]): Promise<void> {
   if (rejected?.status === "rejected") throw rejected.reason;
 }
 
+// Failure paths: a failing release must not replace the upload error the caller needs to see.
+export async function releaseAfterFailure(
+  ctx: HandlerContext,
+  releases: readonly Release[],
+): Promise<void> {
+  try {
+    await releaseAll(releases);
+  } catch (releaseError) {
+    ctx.log?.warn("template upload rollback: releasing stored files failed", {
+      error: releaseError instanceof Error ? releaseError.message : String(releaseError),
+    });
+  }
+}
+
 // `upload` is absent for a rendered-PDF link, which carries no file.
 export type PreparedLinkedResourceCopy = {
   readonly key: string;
@@ -301,14 +319,14 @@ export async function prepareLinkedResourceCopiesBeforeTransaction(args: {
         { fileName: file.fileName, mimeType: file.contentType, data: file.bytes },
       );
       if (!uploaded.isSuccess) {
-        await releaseAll(releases);
+        await releaseAfterFailure(ctx, releases);
         return uploaded;
       }
       if (uploaded.release) releases.push(uploaded.release);
       copies.push({ key, entry, upload: uploaded.data });
     }
   } catch (cause) {
-    await releaseAll(releases);
+    await releaseAfterFailure(ctx, releases);
     throw cause;
   }
   return { isSuccess: true, data: copies, release: () => releaseAll(releases) };
@@ -481,8 +499,7 @@ async function checkAttachmentTarget(args: {
   if (otherAttachmentCount(linked, key) >= MAX_FILE_ATTACHMENTS_PER_TEMPLATE) {
     return attachmentLimitFailure();
   }
-  const occupant = linked[key];
-  if (occupant !== undefined && typeof occupant === "string") return keyInUse();
+  if (isImageKey(linked, key)) return keyInUse();
   return { isSuccess: true, data: { row, linked } };
 }
 
@@ -638,6 +655,7 @@ export async function linkTemplatePdfAttachment(args: {
   if (row.kind !== "mail") return attachmentNeedsMailTemplate();
 
   const linked = parseLinkedResourceEntries(row.linkedResources);
+  if (isImageKey(linked, key)) return keyInUse();
   if (otherAttachmentCount(linked, key) >= MAX_FILE_ATTACHMENTS_PER_TEMPLATE) {
     return attachmentLimitFailure();
   }

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

@@ -23,16 +23,15 @@ const renameMailHtmlKind: EntityEventMigration = {
   transform: (fields) => (fields["kind"] === "mail-html" ? { ...fields, kind: "mail" } : fields),
 };
 
-// TemplateResource — strukturierte Template-Definition mit Tenant-
-// Override-Hierarchie, Locale-Fallback und Resource-Linking via
-// file-foundation. Pro (tenantId, slug, kind, locale) genau eine Row;
-// scope/status/version differenzieren Lifecycle. Der Entwurf neben einer
-// aktiven Fassung liegt in `draft`; die Hauptfelder bleiben die ausgelieferte
-// Fassung.
+// TemplateResource — structured template definition with tenant override
+// hierarchy, locale fallback, and resource linking via file-foundation. Exactly
+// one row per (tenantId, slug, kind, locale); scope/status/version distinguish
+// lifecycle states. The draft alongside an active revision is stored in `draft`;
+// the main fields remain the served revision.
 //
-// `variableSchema` + `linkedResources` sind JSON-Strings in longText
-// (Pattern aus compliance-profiles — kein dedizierter jsonbField im
-// createEntity-DSL). App-Layer parsed JSON, persistiert wieder als String.
+// `variableSchema` + `linkedResources` are JSON strings in longText
+// (following compliance-profiles because the createEntity DSL has no dedicated
+// jsonbField). The application layer parses the JSON and persists it as a string.
 export const templateResourceEntity = createEntity({
   table: "read_template_resources",
   fields: {
@@ -47,8 +46,8 @@ export const templateResourceEntity = createEntity({
     // Folder path for the content tree, `/`-separated ("page/marketing").
     // null = root node.
     folder: createTextField({ personal: false, reason: "technical_reference" }),
-    // Template-body is authored by TenantAdmin/Operator (email-templates etc.),
-    // business data — kein end-user UGC.
+    // Template body is authored by TenantAdmin/Operator (email-templates, etc.),
+    // and is business data—not end-user UGC.
     content: createLongTextField({
       personal: false,
       reason: "is_business_data",
@@ -90,9 +89,9 @@ export type EntityAuditColumns = {
   readonly modifiedById: string | null;
 };
 
-// Concrete Row-Type — single-source dafür dass die unknown-Werte die
-// Drizzle aus `Record<string, unknown>` liefert genau einmal benannt
-// werden (statt 12× `row["x"] as Y` Casts in Handlern + Resolver).
+// Concrete row type—the single source of truth for naming the unknown values
+// returned by Drizzle from `Record<string, unknown>` (instead of 12×
+// `row["x"] as Y` casts in handlers and resolvers).
 export type TemplateResourceRow = {
   readonly id: string | number;
   readonly version: number;