@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/linked-resources.ts

@@ -0,0 +1,102 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import * as z from "zod";
+import type { FileAttachmentRef } from "../renderer-foundation/index.js";
+import { pdfAttachmentFileNamePatternSchema, templateSlugSchema } from "./template-meta.js";
+
+export const templatePdfAttachmentLinkSchema = z
+  .object({
+    kind: z.literal("rendered-pdf"),
+    templateSlug: templateSlugSchema,
+    fileName: pdfAttachmentFileNamePatternSchema,
+  })
+  .strict();
+
+// A PDF the mail renderer asks for at send time: the document template is rendered with the
+// mail's variables, so nothing is stored. `fileName` is a pattern that may hold {{placeholders}}.
+export type TemplatePdfAttachmentLink = z.infer<typeof templatePdfAttachmentLinkSchema>;
+
+// A string is an image the body embeds by key (the fileRef id); an object is a file attached to
+// the mail as-is or a PDF rendered from a document template. Images are the only thing a document
+// body can reference.
+export type LinkedResourceEntry = string | FileAttachmentRef | TemplatePdfAttachmentLink;
+
+export function isFileAttachmentEntry(entry: LinkedResourceEntry): entry is FileAttachmentRef {
+  return typeof entry !== "string" && entry.kind === "file";
+}
+
+export function isPdfAttachmentLink(
+  entry: LinkedResourceEntry,
+): entry is TemplatePdfAttachmentLink {
+  return typeof entry !== "string" && entry.kind === "rendered-pdf";
+}
+
+function toLinkedResourceEntry(raw: unknown): LinkedResourceEntry | null {
+  if (typeof raw === "string") return raw;
+  if (!isPlainObject(raw)) return null;
+  if (raw["kind"] === "rendered-pdf") {
+    const link = templatePdfAttachmentLinkSchema.safeParse(raw);
+    return link.success ? link.data : null;
+  }
+  const { fileRefId, fileName } = raw;
+  if (raw["kind"] !== "file" || typeof fileRefId !== "string" || typeof fileName !== "string") {
+    return null;
+  }
+  return { kind: "file", fileRefId, fileName };
+}
+
+export function parseLinkedResourceEntries(
+  raw: string | null,
+): Record<string, LinkedResourceEntry> {
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!isPlainObject(parsed)) return {};
+  const entries: Record<string, LinkedResourceEntry> = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    const entry = toLinkedResourceEntry(value);
+    if (entry !== null) entries[key] = entry;
+  }
+  return entries;
+}
+
+export function imageLinksOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): Record<string, string> {
+  const images: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(entries)) {
+    if (typeof entry === "string") images[key] = entry;
+  }
+  return images;
+}
+
+export function fileAttachmentsOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): FileAttachmentRef[] {
+  return Object.entries(entries)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([, entry]) => (isFileAttachmentEntry(entry) ? [entry] : []));
+}
+
+export function pdfAttachmentLinksOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): TemplatePdfAttachmentLink[] {
+  return Object.entries(entries)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .flatMap(([, entry]) => (isPdfAttachmentLink(entry) ? [entry] : []));
+}
+
+export function attachmentEntriesOf(
+  entries: Readonly<Record<string, LinkedResourceEntry>>,
+): [string, FileAttachmentRef | TemplatePdfAttachmentLink][] {
+  return Object.entries(entries).flatMap(([key, entry]) =>
+    typeof entry === "string" ? [] : [[key, entry]],
+  );
+}
+
+export function imageResourceKeysOf(raw: string | null): string[] {
+  return Object.keys(imageLinksOf(parseLinkedResourceEntries(raw)));
+}

package/packages/bundled-features/src/template-resolver/pdf-constants.ts

@@ -0,0 +1,12 @@
+// @runtime client
+// No imports: web/ re-exports these, and constants.ts pulls in the framework engine.
+export const PDF_PAGE_FORMATS = ["A4", "Letter"] as const;
+export type PdfPageFormat = (typeof PDF_PAGE_FORMATS)[number];
+
+export const PDF_ORIENTATIONS = ["portrait", "landscape"] as const;
+export type PdfOrientation = (typeof PDF_ORIENTATIONS)[number];
+
+// Page margins in mm; the header/footer values apply when the layout contributes that region and the template sets no margin itself.
+export const PDF_DEFAULT_MARGIN_MM = 15;
+export const PDF_HEADER_MARGIN_MM = 30;
+export const PDF_FOOTER_MARGIN_MM = 20;

package/packages/bundled-features/src/template-resolver/preview-display-html.ts

@@ -0,0 +1,36 @@
+import type { InlineAttachmentRef } from "../renderer-foundation/index.js";
+
+export const PREVIEW_IMAGE_BUDGET_BYTES = 5 * 1024 * 1024;
+
+const DISPLAYABLE_IMAGE_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+]);
+
+export type PreviewAttachmentReader = (
+  ref: InlineAttachmentRef,
+) => Promise<{ readonly content: Uint8Array; readonly contentType: string } | null>;
+
+// The preview shows images the mail client would resolve by Content-ID; a browser cannot, so each
+// resolved image becomes a data URI. `html` itself stays untouched because the send path needs the cids.
+export async function buildDisplayHtml(
+  html: string,
+  inline: readonly InlineAttachmentRef[],
+  readAttachment: PreviewAttachmentReader,
+): Promise<string> {
+  let displayHtml = html;
+  let usedBytes = 0;
+  for (const ref of inline) {
+    const needle = `src="cid:${ref.cid}"`;
+    if (!displayHtml.includes(needle)) continue;
+    const found = await readAttachment(ref);
+    if (found === null || !DISPLAYABLE_IMAGE_TYPES.has(found.contentType)) continue;
+    if (usedBytes + found.content.length > PREVIEW_IMAGE_BUDGET_BYTES) continue;
+    usedBytes += found.content.length;
+    const dataUri = `src="data:${found.contentType};base64,${Buffer.from(found.content).toString("base64")}"`;
+    displayHtml = displayHtml.replaceAll(needle, () => dataUri);
+  }
+  return displayHtml;
+}

package/packages/bundled-features/src/template-resolver/print-document.ts

@@ -0,0 +1,58 @@
+// Server-only (happy-dom). Prepares a rendered document body for the browser
+// that prints it: repeating table headers become real <thead> rows, and
+// everything that would make the browser fetch something external is removed.
+
+import type { Element as ScanElement } from "happy-dom";
+import { withParsedDocument } from "./document-sanitizer.js";
+
+const REPEAT_HEADER_ATTRIBUTE = "data-repeat-header";
+const FETCHING_ELEMENTS =
+  "script, link, iframe, object, embed, video, audio, source, meta, base, style";
+const FETCHING_ATTRIBUTES = ["src", "srcset", "poster", "background", "data"] as const;
+// Anchors only navigate; on svg image/use/feImage an href fetches.
+const HREF_ATTRIBUTES = ["href", "xlink:href"] as const;
+const EXTERNAL_STYLE_REFERENCE = /url\(|@import/i;
+
+function isEmbeddedValue(value: string): boolean {
+  return value.trim().toLowerCase().startsWith("data:");
+}
+
+function moveRepeatHeadersIntoThead(table: ScanElement): void {
+  const rows = Array.from(table.querySelectorAll("tr")).filter(
+    (row) => row.closest("table") === table,
+  );
+  const leading: ScanElement[] = [];
+  for (const row of rows) {
+    if (!row.hasAttribute(REPEAT_HEADER_ATTRIBUTE)) break;
+    leading.push(row);
+  }
+  // skip: a table without leading repeat-header rows keeps its structure as written
+  if (leading.length === 0) return;
+  const thead = table.ownerDocument.createElement("thead");
+  for (const row of leading) {
+    row.removeAttribute(REPEAT_HEADER_ATTRIBUTE);
+    thead.appendChild(row);
+  }
+  table.insertBefore(thead, table.firstChild);
+}
+
+export function prepareDocumentForPrint(html: string): string {
+  return withParsedDocument(html, (body) => {
+    for (const table of Array.from(body.querySelectorAll("table"))) {
+      moveRepeatHeadersIntoThead(table);
+    }
+    for (const element of Array.from(body.querySelectorAll(FETCHING_ELEMENTS))) element.remove();
+    for (const element of Array.from(body.querySelectorAll("*"))) {
+      for (const name of FETCHING_ATTRIBUTES) {
+        const value = element.getAttribute(name);
+        if (value !== null && !isEmbeddedValue(value)) element.removeAttribute(name);
+      }
+      if (element.tagName.toLowerCase() !== "a") {
+        for (const name of HREF_ATTRIBUTES) element.removeAttribute(name);
+      }
+      const style = element.getAttribute("style");
+      if (style !== null && EXTERNAL_STYLE_REFERENCE.test(style)) element.removeAttribute("style");
+    }
+    return body.innerHTML;
+  });
+}

package/packages/bundled-features/src/template-resolver/qualified-names.ts

@@ -7,12 +7,32 @@ export const TemplateResolverHandlers = {
   upsertTenant: "template-resolver:write:upsert-tenant",
   publish: "template-resolver:write:publish",
   archive: "template-resolver:write:archive",
+  publishSystem: "template-resolver:write:publish-system",
+  archiveSystem: "template-resolver:write:archive-system",
+  discardDraft: "template-resolver:write:discard-draft",
+  discardDraftSystem: "template-resolver:write:discard-draft-system",
+  resetToSystem: "template-resolver:write:reset-to-system",
   set: "template-resolver:write:set",
+  importBundle: "template-resolver:write:import-bundle",
+  importBundleSystem: "template-resolver:write:import-bundle-system",
+  copyLocale: "template-resolver:write:copy-locale",
+  resourceUpload: "template-resolver:write:resource-upload",
+  resourceRemove: "template-resolver:write:resource-remove",
+  resourceLinkPdf: "template-resolver:write:resource-link-pdf",
+  sendTest: "template-resolver:write:send-test",
 } as const;
 
 export const TemplateResolverQueries = {
   findById: "template-resolver:query:find-by-id",
   list: "template-resolver:query:list",
+  usage: "template-resolver:query:usage",
+  overview: "template-resolver:query:overview",
+  layoutSource: "template-resolver:query:layout-source",
+  tenantOverrides: "template-resolver:query:tenant-overrides",
+  diffToSystem: "template-resolver:query:diff-to-system",
+  validate: "template-resolver:query:validate",
+  preview: "template-resolver:query:preview",
+  exportBundle: "template-resolver:query:export-bundle",
   // Public pair — anonymous-reachable, kind pinned to text-block.
   bySlug: "template-resolver:query:by-slug",
   byTenant: "template-resolver:query:by-tenant",
@@ -35,6 +55,20 @@ export const TemplateResolverErrors = {
   invalidSlug: "invalid_slug",
   invalidLocale: "invalid_locale",
   systemAdminRequired: "system_admin_required",
+  noDraft: "no_draft",
   alreadyActive: "template_already_active",
   alreadyArchived: "template_already_archived",
+  targetExists: "target_exists",
+  systemResourcesNeedSystemTenant: "system_resources_need_system_tenant",
+  bundleLocalesDiffer: "bundle_locales_differ",
+  resourceTooLarge: "template_resource_too_large",
+  resourceUnsupportedImage: "template_resource_unsupported_image",
+  attachmentUnsupportedType: "template_attachment_unsupported_type",
+  attachmentLimit: "template_attachment_limit",
+  attachmentInvalid: "template_attachment_invalid",
+  attachmentPdfTemplateMissing: "template_attachment_pdf_template_missing",
+  previewRenderFailed: "template_preview_render_failed",
+  testMailNoChannel: "template_test_mail_no_channel",
+  testMailNoAddress: "template_test_mail_no_address",
+  testMailFailed: "template_test_mail_failed",
 } as const;

package/packages/bundled-features/src/template-resolver/record-mapping.ts

@@ -0,0 +1,26 @@
+import type { NotificationRecordMapping } from "@cosmicdrift/kumiko-framework/engine";
+
+function readPath(row: Readonly<Record<string, unknown>>, path: string): unknown {
+  let current: unknown = row;
+  for (const segment of path.split(".")) {
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, segment)) {
+      return undefined;
+    }
+    current = Object.getOwnPropertyDescriptor(current, segment)?.value;
+  }
+  return current;
+}
+
+// Variables whose path is missing on the row are left out, so the template
+// renders them empty instead of printing "undefined".
+export function mapRecordToVariables(
+  mapping: NotificationRecordMapping,
+  row: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const variables: Record<string, unknown> = {};
+  for (const [variable, path] of Object.entries(mapping.map)) {
+    const value = readPath(row, path);
+    if (value !== undefined) variables[variable] = value;
+  }
+  return variables;
+}

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

@@ -0,0 +1,47 @@
+import { assertNotSvg, SHARP_INPUT_OPTIONS } from "../shared/index.js";
+
+const MAX_RESOURCE_WIDTH = 1200;
+
+const CONTENT_TYPE_BY_FORMAT = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+} as const;
+
+type ResourceImageFormat = keyof typeof CONTENT_TYPE_BY_FORMAT;
+
+export type NormalizedResourceImage = {
+  readonly data: Uint8Array;
+  readonly contentType: (typeof CONTENT_TYPE_BY_FORMAT)[ResourceImageFormat];
+  readonly width: number;
+  readonly height: number;
+};
+
+function isResourceImageFormat(format: string | undefined): format is ResourceImageFormat {
+  return format !== undefined && Object.hasOwn(CONTENT_TYPE_BY_FORMAT, format);
+}
+
+// Re-encodes an uploaded image: the stored content type comes from the decoded format, never
+// from the client, and re-encoding drops metadata and anything appended to the file.
+// sharp is imported lazily because every app loads template-resolver, few of them need an image decoder.
+export async function normalizeResourceImage(data: Uint8Array): Promise<NormalizedResourceImage> {
+  const { default: sharp } = await import("sharp");
+  const metadata = await sharp(data, SHARP_INPUT_OPTIONS).metadata();
+  assertNotSvg(metadata.format);
+  if (!isResourceImageFormat(metadata.format)) {
+    throw new Error(`unsupported image format "${metadata.format ?? "unknown"}"`);
+  }
+  const format = metadata.format;
+  const pipeline = sharp(data, SHARP_INPUT_OPTIONS)
+    .rotate()
+    .resize({ width: MAX_RESOURCE_WIDTH, withoutEnlargement: true })
+    .toFormat(format);
+  const { data: output, info } = await pipeline.toBuffer({ resolveWithObject: true });
+  return {
+    data: new Uint8Array(output),
+    contentType: CONTENT_TYPE_BY_FORMAT[format],
+    width: info.width,
+    height: info.height,
+  };
+}

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,13 @@ 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 { activeStampChanges, servedStampChanges } from "./template-draft.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 +72,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 +85,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 +122,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,9 +143,28 @@ 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 },
+      {
+        id: row.id,
+        version: row.version,
+        changes: { ...rowFields, ...activeStampChanges(row) },
+      },
       by,
       tdb,
     );
@@ -127,7 +178,17 @@ 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,
+          ...activeStampChanges(null),
+          draft: null,
+          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 +213,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 +224,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;
@@ -236,7 +377,13 @@ export async function seedTextBlock(
       {
         id: row.id,
         version: row.version,
-        changes: { title: fields.title, content: fields.content, folder: fields.folder },
+        changes: {
+          title: fields.title,
+          content: fields.content,
+          folder: fields.folder,
+          // A re-seed must not revive an archived block; only a served one gets a new served version.
+          ...(current?.status === "active" && servedStampChanges(row)),
+        },
       },
       by,
       tdb,
@@ -251,7 +398,11 @@ export async function seedTextBlock(
     existing,
     ifExists: opts.ifExists,
     create: async () => {
-      const result = await executor.create({ ...fields, tenantId: opts.tenantId }, by, tdb);
+      const result = await executor.create(
+        { ...fields, ...activeStampChanges(null), draft: null, tenantId: opts.tenantId },
+        by,
+        tdb,
+      );
       if (!result.isSuccess) {
         if (result.error?.code === "unique_violation") {
           const again = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
@@ -306,7 +457,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, {