@cosmicdrift/kumiko-samples 0.364.0 → 0.365.1

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

@@ -1,5 +1,6 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type {
+  BeforeTransactionResult,
   HandlerContext,
   SessionUser,
   TenantId,
@@ -16,9 +17,13 @@ import type { LinkedResourceEntry } from "../linked-resources.js";
 import {
   attachmentLimitFailure,
   attachmentNeedsMailTemplate,
+  createPreparedBundleResourceEntry,
+  type PreparedTemplateFile,
+  prepareTemplateAttachmentBeforeTransaction,
+  prepareTemplateResourceBeforeTransaction,
+  type Release,
   readTemplateResourceMaxBytes,
-  storeBundleAttachment,
-  storeTemplateResource,
+  releaseAll,
 } from "../store-template-resource.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 import type { TemplateBundle } from "../template-bundle.js";
@@ -92,64 +97,101 @@ async function collectBundleIssues(
   return issues;
 }
 
-async function storeBundleResources(
-  args: BundleImport,
-): Promise<WriteResult<Record<string, LinkedResourceEntry>>> {
-  const linked: Record<string, LinkedResourceEntry> = {};
-  const pdfLinks = Object.entries(args.bundle.pdfAttachments);
+export type PreparedBundleResources = ReadonlyMap<string, PreparedTemplateFile>;
+
+function checkBundleAttachments(bundle: TemplateBundle): WriteResult<null> {
   const attachmentCount =
-    Object.values(args.bundle.resources).filter((resource) => resource.purpose === "attachment")
-      .length + pdfLinks.length;
-  if (attachmentCount > 0 && args.bundle.kind !== "mail") return attachmentNeedsMailTemplate();
+    Object.values(bundle.resources).filter((resource) => resource.purpose === "attachment").length +
+    Object.keys(bundle.pdfAttachments).length;
+  if (attachmentCount > 0 && bundle.kind !== "mail") return attachmentNeedsMailTemplate();
   if (attachmentCount > MAX_FILE_ATTACHMENTS_PER_TEMPLATE) return attachmentLimitFailure();
-  // The document template is not looked up: a bundle may carry it later than the mail.
-  for (const [key, link] of pdfLinks) linked[key] = { kind: "rendered-pdf", ...link };
+  return { isSuccess: true, data: null };
+}
+
+// beforeTransaction half: validates the bundle and uploads every resource file to the target
+// tenant's storage. A failed or throwing upload releases the ones before it.
+export async function prepareTemplateBundleBeforeTransaction(
+  args: BundleImport & { readonly status: BundleImportStatus },
+): Promise<BeforeTransactionResult<PreparedBundleResources>> {
+  const refused = refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId);
+  if (refused !== null) return refused;
+  const issues = await collectBundleIssues(args, args.status);
+  if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));
+  const attachmentCheck = checkBundleAttachments(args.bundle);
+  if (!attachmentCheck.isSuccess) return attachmentCheck;
+
   const maxBytes = await readTemplateResourceMaxBytes(args.ctx.config, args.ctx.registry);
-  // A bundle is untrusted input like an upload: the same re-encoding decides the stored
-  // content type, so a declared image/png can't smuggle SVG or HTML into a mail or PDF.
-  for (const [key, resource] of Object.entries(args.bundle.resources)) {
-    const bytes = Uint8Array.from(Buffer.from(resource.base64, "base64"));
-    if (resource.purpose === "attachment") {
-      const attachment = await storeBundleAttachment({
+  const prepared = new Map<string, PreparedTemplateFile>();
+  const releases: Release[] = [];
+  try {
+    // A bundle is untrusted input like an upload: the same re-encoding decides the stored
+    // content type, so a declared image/png can't smuggle SVG or HTML into a mail or PDF.
+    for (const [key, resource] of Object.entries(args.bundle.resources)) {
+      const bytes = Uint8Array.from(Buffer.from(resource.base64, "base64"));
+      const common = {
         ctx: args.ctx,
         user: args.user,
         tenantId: args.tenantId,
         bytes,
         maxBytes,
         key,
-        fileName: resource.fileName,
-      });
-      if (!attachment.isSuccess) return attachment;
-      linked[key] = attachment.data;
-      continue;
+      };
+      const result =
+        resource.purpose === "attachment"
+          ? await prepareTemplateAttachmentBeforeTransaction({
+              ...common,
+              fileName: resource.fileName,
+            })
+          : await prepareTemplateResourceBeforeTransaction(common);
+      if (!result.isSuccess) {
+        await releaseAll(releases);
+        return result;
+      }
+      if (result.release) releases.push(result.release);
+      prepared.set(key, result.data);
     }
-    const stored = await storeTemplateResource({
-      ctx: args.ctx,
-      user: args.user,
-      tenantId: args.tenantId,
-      bytes,
-      maxBytes,
-      key,
-    });
-    if (!stored.isSuccess) return stored;
-    linked[key] = stored.data.fileRefId;
+  } catch (cause) {
+    await releaseAll(releases);
+    throw cause;
+  }
+  return { isSuccess: true, data: prepared, release: () => releaseAll(releases) };
+}
+
+async function linkPreparedBundleResources(
+  args: BundleImport,
+  prepared: PreparedBundleResources,
+): Promise<WriteResult<Record<string, LinkedResourceEntry>>> {
+  const linked: Record<string, LinkedResourceEntry> = {};
+  // The document template is not looked up: a bundle may carry it later than the mail.
+  for (const [key, link] of Object.entries(args.bundle.pdfAttachments)) {
+    linked[key] = { kind: "rendered-pdf", ...link };
+  }
+  for (const [key, file] of prepared) {
+    const entry = await createPreparedBundleResourceEntry(
+      { ctx: args.ctx, user: args.user, tenantId: args.tenantId },
+      file,
+    );
+    if (!entry.isSuccess) return entry;
+    linked[key] = entry.data;
   }
   return { isSuccess: true, data: linked };
 }
 
-// Validates every locale first, stores the resource files, then writes one row
-// per locale, so a bad locale never leaves files or half a bundle behind. An image
-// that fails re-encoding stops the import before any row is written; files stored
-// for the resources before it stay as unlinked FileRefs, like a replaced upload.
+// Validates every locale first, so a bad locale is refused before anything is written.
+// The resource files are uploaded in the beforeTransaction phase; a rolled-back transaction
+// releases them there. A crash between the upload and the commit leaves the binaries unreferenced.
 export async function importTemplateBundle(
-  args: BundleImport & { readonly status: BundleImportStatus },
+  args: BundleImport & {
+    readonly status: BundleImportStatus;
+    readonly prepared: PreparedBundleResources;
+  },
 ): Promise<WriteResult<{ ids: Record<string, string> }>> {
   const refused = refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId);
   if (refused !== null) return refused;
   const issues = await collectBundleIssues(args, args.status);
   if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));
 
-  const linked = await storeBundleResources(args);
+  const linked = await linkPreparedBundleResources(args, args.prepared);
   if (!linked.isSuccess) return linked;
 
   const variableSchema = args.bundle.variableSchema ?? {};

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

@@ -7,7 +7,7 @@ import {
 import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.js";
-import { COLLECTION_REFUSED_KINDS } from "../constants.js";
+import { isCollectionRefusedKind } from "../constants.js";
 import { documentViolationsToFieldIssues, sanitizeTemplateBody } from "../document-sanitizer.js";
 import {
   type CollectionEntryRow,
@@ -43,12 +43,13 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
         ? `Creates or overwrites the caller's own "${collection.id}" entry at a slug and locale, live on save with no draft stage; it always writes the acting user's entry, never another user's.`
         : `Creates or overwrites the tenant-wide "${collection.id}" entry at a slug and locale, live on save with no draft stage; the change is visible to everyone who may reach this shared collection.`,
     handler: async (event, ctx) => {
-      if (COLLECTION_REFUSED_KINDS.includes(collection.kind)) {
+      // Defense in depth: createTemplateResolverFeature already refuses these kinds at mount.
+      if (isCollectionRefusedKind(collection.kind)) {
         return writeFailure(
           new ValidationError({
             fields: [
               {
-                path: "kind",
+                path: "",
                 code: "kind_not_allowed",
                 i18nKey: "templateResolver.errors.collection.kindNotAllowed",
                 params: { detail: collection.kind },

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

@@ -2,7 +2,10 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   defineWriteHandler,
   type HandlerContext,
+  type SessionUser,
   SYSTEM_TENANT_ID,
+  type TenantId,
+  type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   AccessDeniedError,
@@ -13,12 +16,16 @@ import {
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.js";
-import { CONTENT_FORMATS } from "../constants.js";
-import { parseLinkedResourceEntries } from "../linked-resources.js";
+import { CONTENT_FORMATS, type ContentFormat } from "../constants.js";
+import { type LinkedResourceEntry, parseLinkedResourceEntries } from "../linked-resources.js";
 import { TemplateResolverErrors } from "../qualified-names.js";
+import {
+  createLinkedResourceCopies,
+  prepareLinkedResourceCopiesBeforeTransaction,
+} from "../store-template-resource.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
-import { toWorkingRow } from "../template-draft.js";
-import { attachTemplateResources, duplicateLinkedResourceFiles } from "../template-resources.js";
+import { toWorkingRow, type WorkingRow } from "../template-draft.js";
+import { attachTemplateResources } from "../template-resources.js";
 import { resolveTemplateVariables } from "../template-validation.js";
 import { targetExistsIssue } from "./bundle-import.js";
 import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
@@ -62,58 +69,109 @@ async function findCopySource(
   });
 }
 
-export const copyLocaleWrite = defineWriteHandler({
-  name: "copy-locale",
-  schema: z.object({
-    slug: templateSlugSchema,
-    kind: kindSchema,
-    fromLocale: localeSchema,
-    toLocale: localeSchema,
-    overwrite: z.boolean().default(false),
-    /** "system" copies between system-default rows; SystemAdmin only. */
-    scope: z.enum(["tenant", "system"]).default("tenant"),
-  }),
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Copies the text of one locale of a template into another locale as a draft override of the caller's tenant, taking the tenant's own row or else the system default as the source; use it as the starting point for a translation. It refuses an existing target unless overwrite is set. With scope system (SystemAdmin only) both source and target are system-default rows and the target lands as a system draft; any other caller gets a 403.",
-  handler: async (event, ctx) => {
-    const { slug, kind, fromLocale, toLocale, overwrite, scope } = event.payload;
-    if (scope === "system" && !event.user.roles.includes("SystemAdmin")) {
-      return writeFailure(
-        new AccessDeniedError({
-          i18nKey: "errors.access.denied",
-          details: { reason: TemplateResolverErrors.systemAdminRequired },
-        }),
-      );
-    }
-    const tenantId = scope === "system" ? SYSTEM_TENANT_ID : event.user.tenantId;
-    const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
-    if (refused !== null) return refused;
+const copyLocaleSchema = z.object({
+  slug: templateSlugSchema,
+  kind: kindSchema,
+  fromLocale: localeSchema,
+  toLocale: localeSchema,
+  overwrite: z.boolean().default(false),
+  /** "system" copies between system-default rows; SystemAdmin only. */
+  scope: z.enum(["tenant", "system"]).default("tenant"),
+});
 
-    const readDb = readDbFor(ctx, scope);
-    const storedSource = await findCopySource(ctx, {
-      scope,
+type CopyRequest = {
+  readonly scope: CopyScope;
+  readonly tenantId: TenantId;
+  readonly source: WorkingRow;
+  readonly contentFormat: ContentFormat;
+  readonly sourceResources: Readonly<Record<string, LinkedResourceEntry>>;
+  // A system source's files belong to the system tenant: the tenant gets its own copies so
+  // previews, exports and the tenant's override keep working independent of the system row.
+  readonly sourceIsForeign: boolean;
+};
+
+// Runs before the upload (reject early, store nothing) and again in the transaction on the fresh rows.
+async function checkCopyRequest(
+  ctx: WriteCtx,
+  event: {
+    readonly user: SessionUser;
+    readonly payload: z.infer<typeof copyLocaleSchema>;
+  },
+): Promise<WriteResult<CopyRequest>> {
+  const { slug, kind, fromLocale, toLocale, overwrite, scope } = event.payload;
+  if (scope === "system" && !event.user.roles.includes("SystemAdmin")) {
+    return writeFailure(
+      new AccessDeniedError({
+        i18nKey: "errors.access.denied",
+        details: { reason: TemplateResolverErrors.systemAdminRequired },
+      }),
+    );
+  }
+  const tenantId = scope === "system" ? SYSTEM_TENANT_ID : event.user.tenantId;
+  const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
+  if (refused !== null) return refused;
+
+  const readDb = readDbFor(ctx, scope);
+  const storedSource = await findCopySource(ctx, {
+    scope,
+    tenantId,
+    slug,
+    kind,
+    locale: fromLocale,
+  });
+  const source = storedSource && toWorkingRow(storedSource, tenantId);
+  const contentFormat = source?.contentFormat;
+  if (!source || !isOneOf(CONTENT_FORMATS, contentFormat)) {
+    return writeFailure(new NotFoundError("template-resource", `${slug}/${fromLocale}`));
+  }
+
+  if (!overwrite) {
+    const target = await fetchOne<TemplateResourceRow>(readDb, templateResourcesTable, {
       tenantId,
       slug,
       kind,
-      locale: fromLocale,
+      locale: toLocale,
     });
-    const source = storedSource && toWorkingRow(storedSource, tenantId);
-    if (!source || !isOneOf(CONTENT_FORMATS, source.contentFormat)) {
-      return writeFailure(new NotFoundError("template-resource", `${slug}/${fromLocale}`));
+    if (target) {
+      return writeFailure(new ValidationError({ fields: [targetExistsIssue(toLocale)] }));
     }
+  }
+  return {
+    isSuccess: true,
+    data: {
+      scope,
+      tenantId,
+      source,
+      contentFormat,
+      sourceResources: parseLinkedResourceEntries(source.linkedResources),
+      sourceIsForeign: source.tenantId !== tenantId,
+    },
+  };
+}
 
-    if (!overwrite) {
-      const target = await fetchOne<TemplateResourceRow>(readDb, templateResourcesTable, {
-        tenantId,
-        slug,
-        kind,
-        locale: toLocale,
-      });
-      if (target) {
-        return writeFailure(new ValidationError({ fields: [targetExistsIssue(toLocale)] }));
-      }
-    }
+export const copyLocaleWrite = defineWriteHandler({
+  name: "copy-locale",
+  schema: copyLocaleSchema,
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Copies the text of one locale of a template into another locale as a draft override of the caller's tenant, taking the tenant's own row or else the system default as the source; use it as the starting point for a translation. It refuses an existing target unless overwrite is set. With scope system (SystemAdmin only) both source and target are system-default rows and the target lands as a system draft; any other caller gets a 403.",
+  beforeTransaction: async (event, ctx) => {
+    const request = await checkCopyRequest(ctx, event);
+    if (!request.isSuccess) return request;
+    if (!request.data.sourceIsForeign) return { isSuccess: true, data: [] };
+    return prepareLinkedResourceCopiesBeforeTransaction({
+      ctx,
+      user: event.user,
+      tenantId: request.data.tenantId,
+      resources: request.data.sourceResources,
+    });
+  },
+  handler: async (event, ctx) => {
+    const { slug, kind, toLocale } = event.payload;
+    const request = await checkCopyRequest(ctx, event);
+    if (!request.isSuccess) return request;
+    const { scope, tenantId, source, contentFormat, sourceResources, sourceIsForeign } =
+      request.data;
 
     const variableSchema = storedRecord(source.variableSchema);
     const written = await writeTemplateRow({
@@ -128,7 +186,7 @@ export const copyLocaleWrite = defineWriteHandler({
         kind,
         locale: toLocale,
         content: source.content,
-        contentFormat: source.contentFormat,
+        contentFormat,
         variableSchema,
         meta: parseStoredJson(source.meta),
         title: source.title,
@@ -136,17 +194,9 @@ export const copyLocaleWrite = defineWriteHandler({
       },
     });
     if (!written.isSuccess) return written;
-    const sourceResources = parseLinkedResourceEntries(source.linkedResources);
-    // A system source's files belong to the system tenant: the tenant gets its own copies so
-    // previews, exports and the tenant's override keep working independent of the system row.
-    const resources =
-      source.tenantId === tenantId
-        ? { isSuccess: true as const, data: sourceResources }
-        : await duplicateLinkedResourceFiles(ctx, {
-            user: event.user,
-            tenantId,
-            resources: sourceResources,
-          });
+    const resources = sourceIsForeign
+      ? await createLinkedResourceCopies({ ctx, user: event.user, tenantId }, event.prepared)
+      : { isSuccess: true as const, data: sourceResources };
     if (!resources.isSuccess) return resources;
     const attached = await attachTemplateResources(ctx, {
       user: event.user,

package/packages/bundled-features/src/template-resolver/handlers/diff-to-system.query.ts

@@ -24,6 +24,7 @@ export const diffToSystemQuery = defineQueryHandler({
       slug: tenantRow.slug,
       kind: tenantRow.kind,
       locale: tenantRow.locale,
+      status: "active",
     });
     if (!systemRow || isHiddenSystemDraft(query.user, systemRow))
       throw new NotFoundError("template-resource", tenantRow.slug);

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

@@ -2,7 +2,7 @@ import { defineWriteHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framew
 import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { templateBundleSchema } from "../template-bundle.js";
-import { importTemplateBundle } from "./bundle-import.js";
+import { importTemplateBundle, prepareTemplateBundleBeforeTransaction } from "./bundle-import.js";
 
 export const importBundleSystemWrite = defineWriteHandler({
   name: "import-bundle-system",
@@ -12,24 +12,23 @@ export const importBundleSystemWrite = defineWriteHandler({
   agent: { risk: "high" as const },
   description:
     "Imports a template bundle as system-default templates, active straight away and overwriting existing system rows; SystemAdmin only. Bundles with resource files need a caller in the system tenant, because the files are stored in the caller's file space.",
-  handler: (event, ctx) => {
+  beforeTransaction: async (event, ctx) => {
     const { bundle } = event.payload;
+    // Must run before any upload.
     if (Object.keys(bundle.resources).length > 0 && event.user.tenantId !== SYSTEM_TENANT_ID) {
-      return Promise.resolve(
-        writeFailure(
-          new ValidationError({
-            fields: [
-              {
-                path: "bundle.resources",
-                code: "system_resources_need_system_tenant",
-                i18nKey: "templateResolver.errors.template.systemResourcesNeedSystemTenant",
-              },
-            ],
-          }),
-        ),
+      return writeFailure(
+        new ValidationError({
+          fields: [
+            {
+              path: "bundle.resources",
+              code: "system_resources_need_system_tenant",
+              i18nKey: "templateResolver.errors.template.systemResourcesNeedSystemTenant",
+            },
+          ],
+        }),
       );
     }
-    return importTemplateBundle({
+    return prepareTemplateBundleBeforeTransaction({
       ctx,
       user: event.user,
       tenantId: SYSTEM_TENANT_ID,
@@ -39,4 +38,15 @@ export const importBundleSystemWrite = defineWriteHandler({
       overwrite: true,
     });
   },
+  handler: (event, ctx) =>
+    importTemplateBundle({
+      ctx,
+      user: event.user,
+      tenantId: SYSTEM_TENANT_ID,
+      scope: "system",
+      status: "active",
+      bundle: event.payload.bundle,
+      overwrite: true,
+      prepared: event.prepared,
+    }),
 });

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

@@ -1,7 +1,7 @@
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { templateBundleSchema } from "../template-bundle.js";
-import { importTemplateBundle } from "./bundle-import.js";
+import { importTemplateBundle, prepareTemplateBundleBeforeTransaction } from "./bundle-import.js";
 
 export const importBundleWrite = defineWriteHandler({
   name: "import-bundle",
@@ -9,6 +9,16 @@ export const importBundleWrite = defineWriteHandler({
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
     "Imports a template bundle (all locales plus resource files, as produced by export-bundle) into the caller's tenant as drafts; it refuses a locale that already has an override unless overwrite is set, and publish makes the drafts live.",
+  beforeTransaction: (event, ctx) =>
+    prepareTemplateBundleBeforeTransaction({
+      ctx,
+      user: event.user,
+      tenantId: event.user.tenantId,
+      scope: "tenant",
+      status: "draft",
+      bundle: event.payload.bundle,
+      overwrite: event.payload.overwrite,
+    }),
   handler: (event, ctx) =>
     importTemplateBundle({
       ctx,
@@ -18,5 +28,6 @@ export const importBundleWrite = defineWriteHandler({
       status: "draft",
       bundle: event.payload.bundle,
       overwrite: event.payload.overwrite,
+      prepared: event.prepared,
     }),
 });

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

@@ -52,6 +52,8 @@ export type OverviewResponse = {
   readonly rows: readonly OverviewRow[];
   readonly nextCursor: null;
   readonly total: number;
+  /** True when the tenant has more template rows than the overview reads; rows and total are then incomplete. */
+  readonly truncated: boolean;
 };
 
 const SORT_FIELDS = ["title", "slug", "kind", "origin", "status", "modifiedAt"] as const;
@@ -285,12 +287,19 @@ export const overviewQuery = defineQueryHandler({
     "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; use it to browse and filter all templates at a glance.",
   handler: async (query, ctx) => {
     const payload = query.payload;
-    const rows = await selectMany<TemplateResourceRow>(
+    const fetchedRows = await selectMany<TemplateResourceRow>(
       ctx.db,
       templateResourcesTable,
       { kind: { in: [...OVERVIEW_KINDS] } },
-      { limit: OVERVIEW_ROW_LIMIT },
+      { orderBy: { col: "id", direction: "asc" }, limit: OVERVIEW_ROW_LIMIT + 1 },
     );
+    const truncated = fetchedRows.length > OVERVIEW_ROW_LIMIT;
+    const rows = truncated ? fetchedRows.slice(0, OVERVIEW_ROW_LIMIT) : fetchedRows;
+    if (truncated) {
+      ctx.log?.warn("template overview: row limit reached, result is incomplete", {
+        limit: OVERVIEW_ROW_LIMIT,
+      });
+    }
 
     const visibleRows = rows.filter((row) => !isHiddenSystemDraft(query.user, row));
     const { drafts, layoutSlugByDocument } = buildDrafts(
@@ -318,6 +327,7 @@ export const overviewQuery = defineQueryHandler({
       rows: filtered.slice(offset, offset + payload.limit),
       nextCursor: null,
       total: filtered.length,
+      truncated,
     } satisfies OverviewResponse;
   },
 });

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

@@ -1,4 +1,8 @@
-import { defineWriteHandler, type WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type BeforeTransactionResult,
+  defineWriteHandler,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   NotFoundError,
   UnprocessableError,
@@ -13,11 +17,14 @@ import {
 import { attachmentFileNameSchema } from "../../shared/index.js";
 import { TemplateResolverErrors } from "../qualified-names.js";
 import {
+  type PreparedTemplateFile,
+  prepareTemplateAttachmentBeforeTransaction,
+  prepareTemplateResourceBeforeTransaction,
   readTemplateResourceMaxBytes,
   type StoredTemplateAttachment,
   type StoredTemplateResource,
-  storeTemplateAttachment,
-  storeTemplateResource,
+  storePreparedTemplateAttachment,
+  storePreparedTemplateResource,
 } from "../store-template-resource.js";
 import { RESOURCE_PURPOSES, resourceKeySchema, resourceTargetTenantId } from "./resource-shared.js";
 
@@ -66,10 +73,7 @@ export const resourceUploadWrite = defineWriteHandler({
   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>> => {
+  beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<PreparedTemplateFile>> => {
     const { templateId, key, sourceFileRefId, purpose, fileName } = event.payload;
     const attachmentTarget =
       purpose === "attachment" ? attachmentTargetOf({ templateId, key, fileName }) : null;
@@ -113,7 +117,7 @@ export const resourceUploadWrite = defineWriteHandler({
     // 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({
+      return prepareTemplateAttachmentBeforeTransaction({
         ctx,
         user: event.user,
         tenantId,
@@ -122,7 +126,7 @@ export const resourceUploadWrite = defineWriteHandler({
         ...attachmentTarget,
       });
     }
-    return storeTemplateResource({
+    return prepareTemplateResourceBeforeTransaction({
       ctx,
       user: event.user,
       tenantId,
@@ -132,4 +136,39 @@ export const resourceUploadWrite = defineWriteHandler({
       ...(key !== undefined && { key }),
     });
   },
+  handler: async (
+    event,
+    ctx,
+  ): Promise<WriteResult<StoredTemplateResource | StoredTemplateAttachment>> => {
+    const { templateId, key } = event.payload;
+    const tenantId = resourceTargetTenantId(event.payload.tenantIdOverride, event.user.tenantId);
+    const { prepared } = event;
+    if (prepared.kind === "attachment") {
+      // The phase accepts attachments only with a complete target, so these are set.
+      if (templateId === undefined || key === undefined) {
+        return writeFailure(
+          new UnprocessableError(TemplateResolverErrors.attachmentInvalid, {
+            i18nKey: "templateResolver.errors.attachment.invalid",
+            details: { code: "target_required" },
+          }),
+        );
+      }
+      return storePreparedTemplateAttachment({
+        ctx,
+        user: event.user,
+        tenantId,
+        prepared,
+        templateId,
+        key,
+      });
+    }
+    return storePreparedTemplateResource({
+      ctx,
+      user: event.user,
+      tenantId,
+      prepared,
+      ...(templateId !== undefined && { templateId }),
+      ...(key !== undefined && { key }),
+    });
+  },
 });