@cosmicdrift/kumiko-samples 0.363.0 → 0.364.0

package/packages/bundled-features/src/renderer-pdf/render-table-pdf.ts

@@ -1,52 +1,56 @@
 import { PDFDocument, type PDFFont, type PDFPage, rgb, StandardFonts } from "pdf-lib";
 import * as z from "zod";
 import { RendererError } from "../renderer-foundation/index.js";
-
-export const pdfTableDocumentSchema = z.object({
-  title: z.string(),
-  subtitle: z.string().optional(),
-  meta: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
-  columns: z
-    .array(
-      z.object({
-        header: z.string(),
-        weight: z.number().positive().optional(),
-        align: z.enum(["left", "right"]).optional(),
-      }),
-    )
-    .min(1),
-  rows: z.array(z.array(z.string())),
-  emptyText: z.string().optional(),
-  footerText: z.string().optional(),
-  pageLabel: z.string().optional(),
-});
-
-export type PdfTableColumn = {
-  readonly header: string;
-  readonly weight?: number;
-  readonly align?: "left" | "right";
-};
-
-export type PdfTableDocument = {
-  readonly title: string;
-  readonly subtitle?: string;
-  readonly meta?: readonly { readonly label: string; readonly value: string }[];
-  readonly columns: readonly PdfTableColumn[];
-  readonly rows: readonly (readonly string[])[];
-  readonly emptyText?: string;
-  readonly footerText?: string;
-  /** Template with `{page}` and `{pages}`; default `"{page} / {pages}"`. */
-  readonly pageLabel?: string;
-};
+import type { PdfPageFormat } from "../template-resolver/index.js";
+
+// Upper bounds keep a hostile or runaway payload from exhausting memory and CPU in layout.
+const PDF_TABLE_MAX_ROWS = 10_000;
+const PDF_TABLE_MAX_COLUMNS = 30;
+const PDF_TABLE_MAX_CELL_LENGTH = 5_000;
+
+const pdfTableColumnSchema = z
+  .object({
+    header: z.string(),
+    weight: z.number().positive().optional(),
+    align: z.enum(["left", "right"]).optional(),
+  })
+  .readonly();
+
+export const pdfTableDocumentSchema = z
+  .object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z
+      .array(z.object({ label: z.string(), value: z.string() }).readonly())
+      .readonly()
+      .optional(),
+    columns: z.array(pdfTableColumnSchema).min(1).max(PDF_TABLE_MAX_COLUMNS).readonly(),
+    rows: z
+      .array(z.array(z.string().max(PDF_TABLE_MAX_CELL_LENGTH)).readonly())
+      .max(PDF_TABLE_MAX_ROWS)
+      .readonly(),
+    emptyText: z.string().optional(),
+    footerText: z.string().optional(),
+    // Template with `{page}` and `{pages}`; default `"{page} / {pages}"`.
+    pageLabel: z.string().optional(),
+  })
+  .readonly();
+
+export type PdfTableColumn = z.infer<typeof pdfTableColumnSchema>;
+export type PdfTableDocument = z.infer<typeof pdfTableDocumentSchema>;
+
+const marginMmSchema = z
+  .object({
+    top: z.number().nonnegative().optional(),
+    right: z.number().nonnegative().optional(),
+    bottom: z.number().nonnegative().optional(),
+    left: z.number().nonnegative().optional(),
+  })
+  .readonly();
 
 export type PdfTableOptions = {
-  readonly format?: "A4" | "Letter";
-  readonly marginMm?: {
-    readonly top?: number;
-    readonly right?: number;
-    readonly bottom?: number;
-    readonly left?: number;
-  };
+  readonly format?: PdfPageFormat;
+  readonly marginMm?: z.input<typeof marginMmSchema>;
 };
 
 export type PdfTableResult = { readonly pdfBytes: Uint8Array; readonly pageCount: number };
@@ -55,7 +59,7 @@ const POINTS_PER_MM = 72 / 25.4;
 const PAGE_SIZE_POINTS = {
   A4: { width: 595.28, height: 841.89 },
   Letter: { width: 612, height: 792 },
-} as const;
+} as const satisfies Record<PdfPageFormat, { readonly width: number; readonly height: number }>;
 const DEFAULT_MARGIN_MM = { top: 18, right: 15, bottom: 18, left: 15 } as const;
 
 const TITLE_SIZE = 16;
@@ -66,6 +70,7 @@ const LINE_HEIGHT_FACTOR = 1.3;
 const CELL_PADDING_X = 4;
 const CELL_PADDING_Y = 3;
 const FOOTER_RESERVE = 16;
+const MIN_COLUMN_WIDTH = 20;
 const META_LABEL_GAP = 10;
 const BLOCK_GAP = 10;
 const REPLACEMENT_CHAR = "?";
@@ -86,7 +91,7 @@ function createEncodableText(font: PDFFont): (text: string) => string {
   const supported = new Set(font.getCharacterSet());
   return (text) => {
     let result = "";
-    for (const char of text.replace(/\t/g, " ")) {
+    for (const char of text.replace(/\r\n?/g, "\n").replace(/\t/g, " ")) {
       const codePoint = char.codePointAt(0) ?? 0;
       result += codePoint === 0x0a || supported.has(codePoint) ? char : REPLACEMENT_CHAR;
     }
@@ -157,30 +162,43 @@ function assertRowShape(doc: PdfTableDocument): void {
   });
 }
 
-export async function renderTablePdf(
-  doc: PdfTableDocument,
-  options?: PdfTableOptions,
-): Promise<PdfTableResult> {
-  if (doc.columns.length === 0) {
-    throw new RendererError("table needs at least one column", "invalid_payload");
-  }
-  assertRowShape(doc);
-
-  const pdf = await PDFDocument.create({ updateMetadata: false });
-  const fonts: Fonts = {
-    regular: await pdf.embedFont(StandardFonts.Helvetica),
-    bold: await pdf.embedFont(StandardFonts.HelveticaBold),
+type TableLayout = {
+  readonly pageSize: { readonly width: number; readonly height: number };
+  readonly margin: {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
   };
-  const clean = createEncodableText(fonts.regular);
+  readonly contentWidth: number;
+  readonly contentBottom: number;
+  readonly columnWidths: readonly number[];
+  readonly bodyLineHeight: number;
+  readonly headerLines: readonly (readonly string[])[];
+  readonly headerHeight: number;
+};
 
+function resolveTableLayout(
+  doc: PdfTableDocument,
+  options: PdfTableOptions | undefined,
+  fonts: Fonts,
+  clean: (text: string) => string,
+): TableLayout {
+  const marginMm = marginMmSchema.safeParse(options?.marginMm ?? {});
+  if (!marginMm.success) {
+    throw new RendererError("margins must be non-negative numbers", "invalid_payload");
+  }
   const pageSize = PAGE_SIZE_POINTS[options?.format ?? "A4"];
   const margin = {
-    top: (options?.marginMm?.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
-    right: (options?.marginMm?.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
-    bottom: (options?.marginMm?.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
-    left: (options?.marginMm?.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
+    top: (marginMm.data.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
+    right: (marginMm.data.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
+    bottom: (marginMm.data.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
+    left: (marginMm.data.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
   };
   const contentWidth = pageSize.width - margin.left - margin.right;
+  if (contentWidth < MIN_COLUMN_WIDTH * doc.columns.length) {
+    throw new RendererError("margins leave no room for table columns", "invalid_payload");
+  }
   const contentBottom = margin.bottom + FOOTER_RESERVE;
   const columnWidths = resolveColumnWidths(doc.columns, contentWidth);
   const bodyLineHeight = lineHeightFor(BODY_SIZE);
@@ -200,6 +218,48 @@ export async function renderTablePdf(
   );
   const headerHeight =
     Math.max(...headerLines.map((lines) => lines.length)) * bodyLineHeight + 2 * CELL_PADDING_Y;
+  // A header this tall would leave every continuation page without room for a row.
+  if (rowSpaceOnEmptyPage - headerHeight < bodyLineHeight + 2 * CELL_PADDING_Y) {
+    throw new RendererError("table header leaves no room for rows", "invalid_payload");
+  }
+  return {
+    pageSize,
+    margin,
+    contentWidth,
+    contentBottom,
+    columnWidths,
+    bodyLineHeight,
+    headerLines,
+    headerHeight,
+  };
+}
+
+export async function renderTablePdf(
+  doc: PdfTableDocument,
+  options?: PdfTableOptions,
+): Promise<PdfTableResult> {
+  if (doc.columns.length === 0) {
+    throw new RendererError("table needs at least one column", "invalid_payload");
+  }
+  assertRowShape(doc);
+
+  const pdf = await PDFDocument.create({ updateMetadata: false });
+  const fonts: Fonts = {
+    regular: await pdf.embedFont(StandardFonts.Helvetica),
+    bold: await pdf.embedFont(StandardFonts.HelveticaBold),
+  };
+  const clean = createEncodableText(fonts.regular);
+
+  const {
+    pageSize,
+    margin,
+    contentWidth,
+    contentBottom,
+    columnWidths,
+    bodyLineHeight,
+    headerLines,
+    headerHeight,
+  } = resolveTableLayout(doc, options, fonts, clean);
 
   let page: PDFPage = pdf.addPage([pageSize.width, pageSize.height]);
   let cursorY = pageSize.height - margin.top;
@@ -227,29 +287,50 @@ export async function renderTablePdf(
     });
   }
 
+  function startBlankPage(): void {
+    page = pdf.addPage([pageSize.width, pageSize.height]);
+    cursorY = pageSize.height - margin.top;
+  }
+
+  function ensureRoom(height: number): void {
+    if (cursorY - height < contentBottom) startBlankPage();
+  }
+
+  // Line by line, so a block taller than one page continues on the next.
+  function flowLines(
+    lines: readonly string[],
+    font: PDFFont,
+    size: number,
+    left: number,
+    width: number,
+    color = TEXT_COLOR,
+  ): void {
+    const lineHeight = lineHeightFor(size);
+    for (const line of lines) {
+      ensureRoom(lineHeight);
+      drawLines([line], font, size, left, width, cursorY, "left", color);
+      cursorY -= lineHeight;
+    }
+  }
+
   function drawIntroBlock(): void {
-    const titleLines = wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth);
-    drawLines(titleLines, fonts.bold, TITLE_SIZE, margin.left, contentWidth, cursorY, "left");
-    cursorY -= titleLines.length * lineHeightFor(TITLE_SIZE);
+    flowLines(
+      wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth),
+      fonts.bold,
+      TITLE_SIZE,
+      margin.left,
+      contentWidth,
+    );
 
     if (doc.subtitle !== undefined) {
-      const subtitleLines = wrapText(
-        clean(doc.subtitle),
-        fonts.regular,
-        SUBTITLE_SIZE,
-        contentWidth,
-      );
-      drawLines(
-        subtitleLines,
+      flowLines(
+        wrapText(clean(doc.subtitle), fonts.regular, SUBTITLE_SIZE, contentWidth),
         fonts.regular,
         SUBTITLE_SIZE,
         margin.left,
         contentWidth,
-        cursorY,
-        "left",
         MUTED_COLOR,
       );
-      cursorY -= subtitleLines.length * lineHeightFor(SUBTITLE_SIZE);
     }
 
     const meta = doc.meta ?? [];
@@ -266,6 +347,7 @@ export async function renderTablePdf(
           BODY_SIZE,
           contentWidth - labelWidth,
         );
+        ensureRoom(bodyLineHeight);
         drawLines(
           [labels[index] ?? ""],
           fonts.bold,
@@ -275,16 +357,13 @@ export async function renderTablePdf(
           cursorY,
           "left",
         );
-        drawLines(
+        flowLines(
           valueLines,
           fonts.regular,
           BODY_SIZE,
           margin.left + labelWidth,
           contentWidth - labelWidth,
-          cursorY,
-          "left",
         );
-        cursorY -= valueLines.length * bodyLineHeight;
       });
     }
     cursorY -= BLOCK_GAP;
@@ -372,6 +451,7 @@ export async function renderTablePdf(
   }
 
   drawIntroBlock();
+  ensureRoom(headerHeight + bodyLineHeight + 2 * CELL_PADDING_Y);
   drawTableHeader();
 
   if (doc.rows.length === 0 && doc.emptyText !== undefined) {

package/packages/bundled-features/src/secrets/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "SecretsContext.withRunner(tx) runs secret access on a given transaction",
+    "detail": "The OAuth refresh now reads and writes the refresh token on its advisory-lock transaction, so a refresh holds one pool connection instead of two and parallel refreshes cannot starve the pool. Custom SecretsContext implementations need a `withRunner` method."
+  },
   {
     "version": "0.343.0",
     "type": "improvement",

package/packages/bundled-features/src/secrets/feature.ts

@@ -83,21 +83,22 @@ export function requireSecretsContext(
         "createSecretsContext({db, masterKeyProvider, registry}) via extraContext.secrets at boot.",
     });
   }
-  const raw = ctx.secrets;
   const userId = ctx._userId;
   if (!userId) {
     throw new InternalError({
       message: `[${handlerName}] ctx._userId missing — cannot audit secret reads without a caller identity.`,
     });
   }
-  return {
+  const withAudit = (raw: SecretsContext): SecretsContext => ({
+    withRunner: (runner) => withAudit(raw.withRunner(runner)),
     get: (tenantId, key, overrideAudit) =>
       raw.get(tenantId, key, overrideAudit ?? { userId, handlerName }),
     // No audit injection: has() is metadata-only and never logs a read.
     has: raw.has.bind(raw),
     set: raw.set.bind(raw),
     delete: raw.delete.bind(raw),
-  };
+  });
+  return withAudit(ctx.secrets);
 }
 
 export type SecretsFeatureOptions = {

package/packages/bundled-features/src/secrets/secrets-context.ts

@@ -17,6 +17,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbConnection,
+  type DbRunner,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, type WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
@@ -91,8 +92,20 @@ function resolveKey(keyOrHandle: string | { readonly name: string }): string {
 }
 
 export function createSecretsContext(opts: SecretsContextOptions): SecretsContext {
-  const { db, masterKeyProvider } = opts;
+  const { masterKeyProvider } = opts;
   const provider = withDekCache(masterKeyProvider, opts.dekCache ?? createDekCache());
+  return buildSecretsContext(opts, provider, opts.db, false);
+}
+
+// `runnerIsTransaction`: the runner is a caller-owned transaction, so audited reads join it
+// instead of opening a second connection (which would deadlock a small pool).
+function buildSecretsContext(
+  opts: SecretsContextOptions,
+  provider: MasterKeyProvider,
+  db: DbRunner,
+  runnerIsTransaction: boolean,
+): SecretsContext {
+  const { masterKeyProvider } = opts;
 
   type SecretLookupRow = {
     readonly id: string;
@@ -105,6 +118,10 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
   }
 
   return {
+    withRunner(runner) {
+      return buildSecretsContext(opts, provider, runner, true);
+    },
+
     async get(tenantId, keyOrHandle, auditCtx) {
       const key = resolveKey(keyOrHandle);
       // Atomic audit + read: a decrypt that "escaped" the audit trail
@@ -120,7 +137,7 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
         return createSecret(plaintext);
       }
 
-      const plaintext = await transaction(db, async (tx) => {
+      const readAndAudit = async (tx: DbRunner): Promise<string | undefined> => {
         // Inline select inside the TX via raw client — fetchOne's connection
         // type doesn't widen to the transaction object cleanly.
         const envelope = await selectTenantSecretEnvelope(tx, tenantId, key);
@@ -154,7 +171,10 @@ export function createSecretsContext(opts: SecretsContextOptions): SecretsContex
           metadata,
         });
         return pt;
-      });
+      };
+      const plaintext = runnerIsTransaction
+        ? await readAndAudit(db)
+        : await transaction(db, readAndAudit);
 
       if (plaintext === undefined) return undefined;
       // Brand the plaintext only after audit committed. The response

package/packages/bundled-features/src/shared/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "Mail template body helpers exported as `./shared/mail-template-body`",
+    "detail": "Apps that register their own notification templates can build the body with the same helpers the framework uses: `mailParagraph`, `mailHeading`, `mailRepeatedRows`, `mailTextWithSlotsHtml`, plus the new `mailButton`, `mailParagraphWithLink` and `mailSubject`. The subpath only depends on kumiko-headless and is safe on the server. Apps that copied these helpers can import them instead."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/shared/chunked-entity-migration.ts

@@ -33,6 +33,9 @@ export type ChunkedMigrationOptions<Row> = {
   readonly maxFailures: number;
   // Epoch ms; Number.POSITIVE_INFINITY for no time bound.
   readonly deadlineAt: number;
+  // Batches processed even when the deadline already passed. Callers whose setup before the
+  // loop can eat the whole budget set 1, so every run makes progress instead of timing out empty.
+  readonly minBatches?: number;
   readonly signal?: AbortSignal | undefined;
   readonly onRowError?: (row: Row, err: unknown) => void;
 };
@@ -51,7 +54,7 @@ export async function runChunkedMigration<Row>(
       stoppedReason = "signal";
       break;
     }
-    if (Date.now() >= opts.deadlineAt) {
+    if (batchesProcessed >= (opts.minBatches ?? 0) && Date.now() >= opts.deadlineAt) {
       stoppedReason = "timeout";
       break;
     }

package/packages/bundled-features/src/shared/mail-template-body.ts

@@ -19,7 +19,24 @@ export function mailHeading(text: string): string {
   return `<h2>${mailTextWithSlotsHtml(text)}</h2>`;
 }
 
+export function mailButton(label: string, linkVariable: string): string {
+  return `<p><a data-button href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(label)}</a></p>`;
+}
+
+export function mailParagraphWithLink(
+  text: string,
+  linkLabel: string,
+  linkVariable: string,
+): string {
+  return `<p>${mailTextWithSlotsHtml(text)} <a href="{{${escapeHtmlAttr(linkVariable)}}}">${escapeHtml(linkLabel)}</a></p>`;
+}
+
 // One table row per list entry; the cell shows the entry's `field`.
 export function mailRepeatedRows(listName: string, field: string): string {
   return `<table><tbody><tr data-each="${escapeHtmlAttr(listName)}"><td><p><span data-variable="${escapeHtmlAttr(field)}"></span></p></td></tr></tbody></table>`;
 }
+
+// Subjects are Handlebars text, so the same `{name}` slots become `{{name}}`.
+export function mailSubject(text: string): string {
+  return text.replace(SLOT_PATTERN, "{{$1}}");
+}

package/packages/bundled-features/src/subscription-stripe/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "A stale Stripe customer id no longer turns the customer portal into a 500",
+    "detail": "createPortalSession now maps Stripe's \"No such customer\" rejection (account switch, customer deleted in the dashboard) to an UnprocessableError with the i18n key billing-foundation.errors.providerCustomerUnknown, translated in German and Spanish, instead of letting the raw Stripe error surface as a server error."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -109,12 +109,10 @@ export function mapAppLocaleToStripeLocale(
   return knownLocales.find((known) => known === language) ?? "auto";
 }
 
-function isUnknownCustomerStripeError(error: unknown): boolean {
-  return (
-    isResourceMissingStripeError(error) &&
-    error instanceof Stripe.errors.StripeInvalidRequestError &&
-    error.param === "customer"
-  );
+function isUnknownCustomerStripeError(
+  error: unknown,
+): error is Stripe.errors.StripeInvalidRequestError {
+  return isResourceMissingStripeError(error) && error.param === "customer";
 }
 
 export function createStripeCheckoutSession(
@@ -203,11 +201,21 @@ export type StripePortalOptions = Parameters<
 export function createStripePortalSession(runtime: StripeCtxRuntime) {
   return async (ctx: HandlerContext, options: StripePortalOptions): Promise<{ url: string }> => {
     const stripe = await runtime.clientForCtx(ctx);
-    const session = await stripe.billingPortal.sessions.create({
-      customer: options.providerCustomerId,
-      return_url: options.returnUrl,
-    });
-    return { url: session.url };
+    try {
+      const session = await stripe.billingPortal.sessions.create({
+        customer: options.providerCustomerId,
+        return_url: options.returnUrl,
+      });
+      return { url: session.url };
+    } catch (error) {
+      // A portal needs an existing customer, so unlike checkout there is no retry without one.
+      if (!isUnknownCustomerStripeError(error)) throw error;
+      throw new UnprocessableError("provider_customer_unknown", {
+        i18nKey: "billing-foundation.errors.providerCustomerUnknown",
+        message: `subscription-stripe: Stripe does not know customer "${options.providerCustomerId}" (account switch or customer deleted).`,
+        cause: error,
+      });
+    }
   };
 }
 

package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts

@@ -54,7 +54,9 @@ import type { StripeWebhookRuntime } from "./runtime.js";
 
 const log = createFallbackLogger("subscription-stripe");
 
-export function isResourceMissingStripeError(error: unknown): boolean {
+export function isResourceMissingStripeError(
+  error: unknown,
+): error is Stripe.errors.StripeInvalidRequestError {
   return (
     error instanceof Stripe.errors.StripeInvalidRequestError && error.code === "resource_missing"
   );

package/packages/bundled-features/src/template-resolver/README.md

@@ -50,7 +50,7 @@ async function someHandler(ctx) {
 
 | kind | contentFormat | meta |
 |---|---|---|
-| `mail` | `html` (Dokument-Schema, wird serverseitig neu aufgebaut) | Pflicht: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `sender` |
+| `mail` | `html` (Dokument-Schema, wird serverseitig neu aufgebaut) | Pflicht: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `senderName`, `replyTo` |
 | `mail-layout` | `mjml` | leer (`{}`) oder fehlend |
 | `pdf-layout` | `html` | leer (`{}`) oder fehlend |
 | `document-pdf` | `html` | fehlt |
@@ -137,10 +137,12 @@ upsertSystem  ──┐
                 ├──► status: "active" (System-Default sofort aktiv)
 upsertTenant  ──┴──► status: "draft" (Default) | "active" (explizit)
 
-publish ───────► status: "active"
+publish ───────► status: "active" (übernimmt einen offenen Entwurf)
 archive ───────► status: "archived"
+discardDraft ──► verwirft den Entwurf neben der aktiven Fassung
 ```
 
+Ein Entwurf über einer aktiven Zeile (`upsertTenant` ohne `status`, `copy-locale`, `import-bundle`) liegt als JSON in `draft` neben der Zeile; die Hauptfelder bleiben die ausgelieferte Fassung. `find-by-id` und `layout-source` liefern die Arbeitsfassung (Entwurf, sonst gespeichert) mit `active { version, since }`.
 Resolver returnt **nur** Templates mit `status: "active"`. draft/archived werden ignoriert.
 
 ## Consumer Conformance

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

@@ -18,6 +18,7 @@ import {
   type TemplatePdfAttachmentLink,
 } from "./linked-resources.js";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+import { activeVersionOf, servedVersionOf } from "./template-draft.js";
 import { parseTemplateMeta, type TemplateMeta } from "./template-meta.js";
 
 // Public TemplateResource: what consumers see. Hides DB-internal columns
@@ -161,7 +162,7 @@ function pickActiveLayoutRow(
 ): TemplateResourceRow | null {
   const active = rows
     .filter((row) => row.status === "active")
-    .sort((a, b) => b.version - a.version || a.locale.localeCompare(b.locale));
+    .sort((a, b) => activeVersionOf(b) - activeVersionOf(a) || a.locale.localeCompare(b.locale));
   return (
     active.find((row) => row.locale === locale) ??
     active.find((row) => row.locale === FALLBACK_LOCALE) ??
@@ -202,7 +203,7 @@ function toPublic(row: TemplateResourceRow): TemplateResource {
   const linkedEntries = parseLinkedResourceEntries(row.linkedResources);
   return {
     id: String(row.id),
-    version: row.version,
+    version: servedVersionOf(row),
     tenantId: row.tenantId,
     slug: row.slug,
     kind,