@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/channel-email/email-channel.ts

@@ -1,17 +1,23 @@
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
-import type { DbRow } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 import {
+  type AttachmentOrigin,
+  type ChannelContext,
   type ChannelMessage,
   DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
   DELIVERY_UNSUBSCRIBE_PATH,
   type DeliveryChannel,
-  type NotificationRenderer,
+  EMAIL_CHANNEL_NAME,
+  type EmailAttachmentRef,
+  fileAttachmentRefSchema,
+  MAX_EMAIL_ATTACHMENTS,
   type RenderedMessage,
+  renderedPdfAttachmentRefSchema,
 } from "../delivery/index.js";
 import { decryptStoredPii } from "../shared/index.js";
 import { guardEmailMessage } from "./pii-guard.js";
-import type { EmailTransport } from "./types.js";
+import type { EmailAttachment, EmailTransport } from "./types.js";
 
 // Envelope (From / Reply-To / threading headers) rides on the channel data —
 // the notification's email template echoes it out of the notify() call, since
@@ -83,9 +89,80 @@ function emailEnvelopeFrom(data: Readonly<Record<string, unknown>> | undefined):
   };
 }
 
+const fileAttachmentsSchema = z
+  .array(z.discriminatedUnion("kind", [fileAttachmentRefSchema, renderedPdfAttachmentRefSchema]))
+  .max(MAX_EMAIL_ATTACHMENTS);
+
+// Only kinds "file" and "rendered-pdf" may come from notify data; inline images are created by the renderer alone.
+// Invalid input throws instead of dropping the attachment silently.
+export function fileAttachmentsFrom(
+  data: Readonly<Record<string, unknown>> | undefined,
+  messageLocale?: string,
+): readonly EmailAttachmentRef[] {
+  const raw = data?.["attachments"];
+  if (raw === undefined) return [];
+  return fileAttachmentsSchema
+    .parse(raw)
+    .map((ref) =>
+      ref.kind === "rendered-pdf" && ref.locale === undefined && messageLocale !== undefined
+        ? { ...ref, locale: messageLocale }
+        : ref,
+    );
+}
+
+const INLINE_EXTENSION_BY_CONTENT_TYPE: Readonly<Record<string, string>> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+};
+
+type AttachmentSource = { readonly ref: EmailAttachmentRef; readonly origin: AttachmentOrigin };
+
+async function resolveAttachments(
+  sources: readonly AttachmentSource[],
+  ctx: ChannelContext,
+): Promise<readonly EmailAttachment[]> {
+  if (sources.length === 0) return [];
+  if (ctx.readAttachment === undefined) {
+    throw new Error(
+      "email channel: the message has attachments but the channel context cannot read files",
+    );
+  }
+  const resolved: EmailAttachment[] = [];
+  for (const { ref, origin } of sources) {
+    const found = await ctx.readAttachment(ref, origin);
+    if (ref.kind === "rendered-pdf") {
+      if (found === null) {
+        throw new Error(`email channel: rendering attachment "${ref.fileName}" returned nothing`);
+      }
+      resolved.push({
+        kind: "rendered-pdf",
+        templateSlug: ref.templateSlug,
+        fileName: ref.fileName,
+        content: found.content,
+        contentType: found.contentType,
+      });
+      continue;
+    }
+    if (found === null) {
+      // A missing inline image only degrades the look; a missing file is content the recipient expects.
+      if (ref.kind === "inline") continue;
+      throw new Error(`email channel: attachment file ${ref.fileRefId} was not found`);
+    }
+    const fileName =
+      ref.kind === "file"
+        ? ref.fileName
+        : INLINE_EXTENSION_BY_CONTENT_TYPE[found.contentType]
+          ? `${ref.cid}.${INLINE_EXTENSION_BY_CONTENT_TYPE[found.contentType]}`
+          : ref.cid;
+    resolved.push({ ...ref, fileName, content: found.content, contentType: found.contentType });
+  }
+  return resolved;
+}
+
 export type EmailChannelOptions = {
   readonly transport: EmailTransport;
-  readonly renderer: NotificationRenderer;
   readonly resolveEmail: (
     userId: string,
     ctx: { db: unknown; tenantId: TenantId },
@@ -93,32 +170,38 @@ export type EmailChannelOptions = {
 };
 
 export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
-  const { transport, renderer, resolveEmail } = options;
+  const { transport, resolveEmail } = options;
 
-  // Render is the expensive step (template engine, possibly a remote service)
-  // and runs in the delivery.render job, decoupled from the SMTP send so each
-  // can retry independently. Extracted so the inline fallback (no job runner)
+  // Render runs in the delivery.render job, decoupled from the SMTP send so
+  // each can retry independently. Extracted so the inline path (no job runner)
   // can reuse it without going through the channel's own render() indirection.
-  async function renderMessage(message: ChannelMessage): Promise<RenderedMessage> {
-    // Build renderer input: per-channel template data (if any) or fall back
-    // to title/body from the message. Renderer handles both cases.
-    const variables = (message.data as DbRow) ?? {
-      title: message.title,
-      body: message.body,
-    };
-    const rendererInput = {
-      template: message.notificationType,
-      variables,
-      locale: message.locale,
-    };
-    const html = await renderer.render(rendererInput);
-    const text = renderer.renderText ? await renderer.renderText(rendererInput) : undefined;
-    const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
-    return { html, subject, ...(text !== undefined && { text }) };
+  async function renderMessage(
+    message: ChannelMessage,
+    ctx: ChannelContext,
+  ): Promise<RenderedMessage> {
+    const notificationType = message.notificationType;
+    if (ctx.registry.getAllNotifications().get(notificationType)?.template === undefined) {
+      throw new Error(
+        `email channel: notification "${notificationType}" has no mail template, declare template + meta on r.notification`,
+      );
+    }
+    if (ctx.renderMail === undefined) {
+      throw new Error(
+        `email channel: notification "${notificationType}" has a mail template but the channel context carries no renderMail`,
+      );
+    }
+    const unsubscribeUrl = message.data?.["unsubscribeUrl"];
+    const { subject, html, text, attachments } = await ctx.renderMail({
+      slug: notificationType,
+      locale: message.locale ?? "en",
+      variables: message.data ?? {},
+      ...(typeof unsubscribeUrl === "string" && { unsubscribeUrl }),
+    });
+    return { html, subject, text, ...(attachments !== undefined && { attachments }) };
   }
 
   return {
-    name: "email",
+    name: EMAIL_CHANNEL_NAME,
     mode: "queued",
 
     // resolveEmail typically returns the raw stored user.email, which is ciphertext under an active KMS.
@@ -129,13 +212,22 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
       return address === PII_ERASED_SENTINEL ? null : address;
     },
 
-    render(message, _ctx) {
-      return renderMessage(message);
+    render(message, ctx) {
+      return renderMessage(message, ctx);
     },
 
-    async send(address, message, _ctx, rendered) {
-      const { html, subject, text } = rendered ?? (await renderMessage(message));
+    async send(address, message, ctx, rendered) {
+      const { html, subject, text, attachments } = rendered ?? (await renderMessage(message, ctx));
       const envelope = emailEnvelopeFrom(message.data);
+      const resolvedAttachments = await resolveAttachments(
+        [
+          ...(attachments ?? []).map((ref): AttachmentSource => ({ ref, origin: "template" })),
+          ...fileAttachmentsFrom(message.data, message.locale).map(
+            (ref): AttachmentSource => ({ ref, origin: "message" }),
+          ),
+        ],
+        ctx,
+      );
       await transport.send(
         guardEmailMessage({
           to: address,
@@ -143,6 +235,7 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
           html,
           ...(text !== undefined && { text }),
           ...envelope,
+          ...(resolvedAttachments.length > 0 && { attachments: resolvedAttachments }),
         }),
       );
       return { status: "sent", address };

package/packages/bundled-features/src/channel-email/feature.ts

@@ -1,4 +1,7 @@
-import { DELIVERY_CHANNEL_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import {
+  DELIVERY_CHANNEL_EXTENSION,
+  EMAIL_CHANNEL_NAME,
+} from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { createEmailChannel, type EmailChannelOptions } from "./email-channel.js";
 
@@ -7,7 +10,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
 
   return defineFeature("channel-email", (r) => {
     r.describe(
-      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport`, a `renderer: NotificationRenderer` (e.g. backed by `renderer-simple`), and a `resolveEmail` function that maps a user ID to their email address.",
+      "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.",
     );
     r.uiHints({
       displayLabel: "Email Channel",
@@ -17,7 +20,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
     r.requires("delivery");
 
     r.translations({ keys: { "delivery.channel.email": { en: "Email" } } });
-    r.useExtension(DELIVERY_CHANNEL_EXTENSION, "email", {
+    r.useExtension(DELIVERY_CHANNEL_EXTENSION, EMAIL_CHANNEL_NAME, {
       mode: channel.mode,
       resolve: channel.resolve,
       render: channel.render,

package/packages/bundled-features/src/channel-email/index.ts

@@ -7,4 +7,10 @@ export {
   type SmtpEnv,
   type SmtpTransportOptions,
 } from "./smtp-transport.js";
-export { createInMemoryTransport, type EmailMessage, type EmailTransport } from "./types.js";
+export {
+  createInMemoryTransport,
+  type EmailAttachment,
+  type EmailAttachmentRef,
+  type EmailMessage,
+  type EmailTransport,
+} from "./types.js";

package/packages/bundled-features/src/channel-email/pii-guard.ts

@@ -11,6 +11,18 @@ const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
 // is always refused (the address is garbage — better no mail than a leaked
 // blob); ciphertext in subject/body fails loud in dev and is redacted+logged
 // in prod.
+function assertAttachmentNamesArePlain(message: EmailMessage): void {
+  for (const attachment of message.attachments ?? []) {
+    const fields = [attachment.fileName, attachment.kind === "inline" ? attachment.cid : undefined];
+    if (fields.some((field) => field?.includes(CIPHERTEXT_MARKER))) {
+      throw new Error(
+        `[channel-email] refusing to send: attachment file name is a PII ciphertext ` +
+          `("${PII_CIPHERTEXT_PREFIX}…") — decrypt the stored value before mailing (decryptStoredPii).`,
+      );
+    }
+  }
+}
+
 export function guardEmailMessage(message: EmailMessage): EmailMessage {
   // Every envelope address, not just `to`: a ciphertext From, From-Name or Reply-To is
   // the same garbage as a ciphertext recipient — refuse rather than mail it.
@@ -35,6 +47,7 @@ export function guardEmailMessage(message: EmailMessage): EmailMessage {
       );
     }
   }
+  assertAttachmentNamesArePlain(message);
   const leaking =
     message.subject.includes(CIPHERTEXT_MARKER) ||
     message.html.includes(CIPHERTEXT_MARKER) ||

package/packages/bundled-features/src/channel-email/smtp-transport.ts

@@ -18,7 +18,7 @@
 
 import { createTransport, type Transporter } from "nodemailer";
 import addressparser from "nodemailer/lib/addressparser";
-import type { EmailMessage, EmailTransport } from "./types.js";
+import type { EmailAttachment, EmailMessage, EmailTransport } from "./types.js";
 
 export type SmtpTransportOptions = {
   /** SMTP-Server-Host (z.B. "smtp.gmail.com", "in-v3.mailjet.com",
@@ -74,6 +74,17 @@ function fromHeader(
   return parsed?.address ? { name, address: parsed.address } : address;
 }
 
+function toNodemailerAttachment(attachment: EmailAttachment) {
+  const base = {
+    filename: attachment.fileName,
+    content: Buffer.from(attachment.content),
+    contentType: attachment.contentType,
+  };
+  return attachment.kind === "inline"
+    ? { ...base, cid: attachment.cid, contentDisposition: "inline" as const }
+    : base;
+}
+
 export function createSmtpTransport(options: SmtpTransportOptions): EmailTransport {
   const transporter: Transporter = createTransport({
     host: options.host,
@@ -95,6 +106,9 @@ export function createSmtpTransport(options: SmtpTransportOptions): EmailTranspo
         ...(message.text !== undefined && { text: message.text }),
         ...(message.replyTo && { replyTo: message.replyTo }),
         ...(message.headers && { headers: message.headers }),
+        ...(message.attachments && {
+          attachments: message.attachments.map(toNodemailerAttachment),
+        }),
       });
     },
   };

package/packages/bundled-features/src/channel-email/types.ts

@@ -1,3 +1,24 @@
+import type {
+  EmailAttachmentRef,
+  FileAttachmentRef,
+  InlineAttachmentRef,
+  RenderedPdfAttachmentRef,
+} from "../delivery/index.js";
+
+export type { EmailAttachmentRef };
+
+// What a transport receives: the reference plus the bytes the send job read. A rendered
+// PDF keeps no variables here, they may be personal data and the transport has no use for them.
+export type EmailAttachment = (
+  | InlineAttachmentRef
+  | FileAttachmentRef
+  | Pick<RenderedPdfAttachmentRef, "kind" | "templateSlug">
+) & {
+  readonly content: Uint8Array;
+  readonly contentType: string;
+  readonly fileName: string;
+};
+
 // Transport interface — SMTP in prod, InMemory in tests
 export type EmailMessage = {
   readonly to: string;
@@ -19,6 +40,8 @@ export type EmailMessage = {
   // Extra RFC-5322 headers — In-Reply-To / References thread a reply into the
   // conversation it answers.
   readonly headers?: Readonly<Record<string, string>>;
+  // Refs travel through jobs; the bytes are only read at send time.
+  readonly attachments?: readonly EmailAttachment[];
 };
 
 export type EmailTransport = {

package/packages/bundled-features/src/channel-in-app/handlers/mark-read.write.ts

@@ -20,7 +20,7 @@ export const markReadWrite = defineWriteHandler({
   description:
     "Marks one in-app message of the calling user as read by its numeric id, failing with not-found when no such message belongs to the caller; use it when a user opens a single notification.",
   handler: async (event, ctx) => {
-    const rows = await updateMany(
+    const rows = await updateMany<{ id: number }>(
       ctx.db,
       inAppMessagesTable,
       { isRead: true, readAt: Temporal.Now.instant() },
@@ -29,6 +29,6 @@ export const markReadWrite = defineWriteHandler({
     if (rows.length === 0) {
       return writeFailure(new NotFoundError("inAppMessage", event.payload.id));
     }
-    return { isSuccess: true, data: { id: (rows[0] as { id: number } | undefined)?.id } };
+    return { isSuccess: true, data: { id: rows[0]?.id } };
   },
 });

package/packages/bundled-features/src/config/handlers/set.write.ts

@@ -164,11 +164,7 @@ export const setWrite = defineWriteHandler({
         });
       }
       // scope="system" was already rejected above — narrow accordingly.
-      const subject = resolvePiiSubject(
-        scope as Exclude<typeof scope, "system">, // @cast-boundary runtime-checked above
-        tenantId,
-        userId,
-      );
+      const subject = resolvePiiSubject(scope as Exclude<typeof scope, "system">, tenantId, userId);
       const kmsCtx: KmsContext = {
         requestId: requestContext.get()?.requestId ?? "config:write:set",
         tenantId,

package/packages/bundled-features/src/custom-fields/db/queries/user-data-rights.ts

@@ -31,9 +31,9 @@ export async function selectFieldDefinitionsForEntity(
   entityName: string,
   tenantId: string,
 ): Promise<readonly { field_key: string; serialized_field: unknown }[]> {
-  return unsafeReadRetrying(
+  return unsafeReadRetrying<{ field_key: string; serialized_field: unknown }>(
     db,
     "SELECT field_key, serialized_field FROM read_custom_field_definitions WHERE entity_name = $1 AND tenant_id = $2",
     [entityName, tenantId],
-  ) as Promise<readonly { field_key: string; serialized_field: unknown }[]>;
+  );
 }

package/packages/bundled-features/src/custom-fields/lib/value-schema.ts

@@ -3,6 +3,7 @@ import {
   type FieldDefinition,
   fieldToZod,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type * as z from "zod";
 import { SUPPORTED_FIELD_TYPES } from "../constants.js";
 
@@ -38,9 +39,8 @@ const SUPPORTED_EMBEDDED_SUB_TYPES: ReadonlySet<string> = new Set([
 const CONSTRAINT_KEYS = ["required", "maxLength", "format", "default"] as const;
 
 export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny | null {
-  if (!parsedField || typeof parsedField !== "object") return null;
-  const obj = parsedField as Record<string, unknown>;
-  const rawType = obj["type"];
+  if (!isPlainObject(parsedField)) return null;
+  const rawType = parsedField["type"];
   if (typeof rawType !== "string") return null;
   if (!SUPPORTED_TYPES_SET.has(rawType)) return null;
 
@@ -54,35 +54,34 @@ export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny
   // drops everywhere else.
   let strippedSubSchema: Record<string, Record<string, unknown>> | undefined;
   if (rawType === "embedded") {
-    const schema = obj["schema"];
+    const schema = parsedField["schema"];
     if (!schema || typeof schema !== "object") return null;
     strippedSubSchema = {};
     for (const [subKey, sub] of Object.entries(schema)) {
-      if (!sub || typeof sub !== "object") return null;
-      const subObj = sub as Record<string, unknown>;
-      const subType = subObj["type"];
+      if (!isPlainObject(sub)) return null;
+      const subType = sub["type"];
       if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
         return null;
       }
-      const strippedSub = { ...subObj };
+      const strippedSub = { ...sub };
       for (const k of CONSTRAINT_KEYS) delete strippedSub[k];
       strippedSubSchema[subKey] = strippedSub;
     }
   }
 
-  const fieldDef: Record<string, unknown> = { ...obj };
+  const fieldDef: Record<string, unknown> = { ...parsedField };
   for (const k of CONSTRAINT_KEYS) delete fieldDef[k];
   if (strippedSubSchema !== undefined) fieldDef["schema"] = strippedSubSchema;
   if (rawType === "enum") {
     fieldDef["type"] = "select";
-    fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];
+    fieldDef["options"] = parsedField["values"] ?? parsedField["options"] ?? [];
   }
 
   // fieldToZod's money case validates `currency` against the passed list, not
   // a field-level key — so surface the field's own currency when it declares
   // one, else fall back to the framework defaults.
   const currencies =
-    typeof obj["currency"] === "string" ? [obj["currency"] as string] : DEFAULT_CURRENCIES;
+    typeof parsedField["currency"] === "string" ? [parsedField["currency"]] : DEFAULT_CURRENCIES;
 
   // @cast-boundary serialized-field is the dehydrated r.field.X() output =
   // a FieldDefinition; fieldToZod reads only its type-specific keys (the

package/packages/bundled-features/src/custom-fields/wire-user-data-rights.ts

@@ -3,6 +3,7 @@
 import { type DbRunner, extractTableName } from "@cosmicdrift/kumiko-framework/db";
 import type { UserDataExportSnippet, UserDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 import { EXT_USER_DATA, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { selectCustomFieldsHostRows } from "./db/queries/user-data-rights.js";
 
 export interface WireCustomFieldsUserDataRightsOptions {
@@ -17,14 +18,14 @@ interface CustomFieldsHostRow {
 }
 
 function asCustomFieldsHostRow(value: unknown): CustomFieldsHostRow | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  if (!("id" in value) || typeof value.id !== "string") return null;
-  const record = value as Record<string, unknown>;
-  const cf = record["custom_fields"] ?? record["customFields"];
+  if (!isPlainObject(value)) return null;
+  const id = value["id"];
+  if (typeof id !== "string") return null;
+  const cf = value["custom_fields"] ?? value["customFields"];
   if (cf === undefined) return null;
-  if (cf === null) return { id: value.id, customFields: null };
+  if (cf === null) return { id, customFields: null };
   if (!cf || typeof cf !== "object" || Array.isArray(cf)) return null;
-  return { id: value.id, customFields: Object.fromEntries(Object.entries(cf)) };
+  return { id, customFields: Object.fromEntries(Object.entries(cf)) };
 }
 
 // fw#2914 — selectCustomFieldsHostRows runs raw SQL against a dynamic host

package/packages/bundled-features/src/data-retention/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "data-retention exports computeCutoff",
+    "detail": "computeCutoff(keepFor, now) and its Instant type are exported from @cosmicdrift/kumiko-bundled-features/data-retention, so apps that compute a retention cutoff themselves (for example a backfill) use the same keepFor parsing as the cleanup job instead of a copy."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/data-retention/index.ts

@@ -18,3 +18,4 @@ export {
   tenantRetentionOverrideEntity,
   tenantRetentionOverrideTable,
 } from "./feature.js";
+export { computeCutoff, type Instant } from "./keep-for.js";

package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts

@@ -72,6 +72,7 @@ import {
   fileRefEntity,
   fileRefsTable,
 } from "@cosmicdrift/kumiko-framework/files";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { runInSubTransaction } from "../shared/index.js";
 import { computeCutoff, type Instant } from "./keep-for.js";
 import type { RetentionPresetKey } from "./presets.js";
@@ -347,10 +348,9 @@ function collectSingleFileHolders(registry: Registry): readonly SingleFileHolder
     if (!entity) continue;
     const { singleFields } = planFileFields(entity.fields);
     if (singleFields.length === 0) continue;
-    const table = proj.table as Record<string, unknown>; // @cast-boundary column-presence probe
     holders.push({
       table: proj.table,
-      tableHasTenantId: table["tenantId"] !== undefined,
+      tableHasTenantId: propertyOf(proj.table, "tenantId") !== undefined,
       singleFields,
     });
   }
@@ -699,11 +699,10 @@ export async function runRetentionCleanup(
     const entity = registry.getEntity(entityName);
     if (!entity) continue;
 
-    const table = proj.table as Record<string, unknown>; // @cast-boundary column-presence probe
     const declaredReference = policy.reference ?? DEFAULT_REFERENCE_FIELD;
     const referenceField = FRAMEWORK_REFERENCE_ALIAS[declaredReference] ?? declaredReference;
 
-    if (table[referenceField] === undefined) {
+    if (propertyOf(proj.table, referenceField) === undefined) {
       skipped.push({ entityName, reason: "missing_reference_column" });
       continue;
     }
@@ -713,7 +712,7 @@ export async function runRetentionCleanup(
     // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
     // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
     // anderen treffen.
-    if (table["tenantId"] !== undefined) {
+    if (propertyOf(proj.table, "tenantId") !== undefined) {
       where["tenantId"] = tenantId;
     }
 
@@ -762,7 +761,10 @@ export async function runRetentionCleanup(
         break;
       }
       case "softDelete": {
-        if (table["isDeleted"] === undefined || table["deletedAt"] === undefined) {
+        if (
+          propertyOf(proj.table, "isDeleted") === undefined ||
+          propertyOf(proj.table, "deletedAt") === undefined
+        ) {
           skipped.push({ entityName, reason: "missing_softdelete_columns" });
           break;
         }

package/packages/bundled-features/src/delivery/attachment-ref.ts

@@ -0,0 +1,84 @@
+import * as z from "zod";
+import type {
+  FileAttachmentRef,
+  InlineAttachmentRef,
+  RenderedPdfAttachmentRef,
+} from "../renderer-foundation/index.js";
+import { attachmentFileNameSchema } from "../shared/index.js";
+import { isDocumentResourceKey, templateSlugSchema } from "../template-resolver/index.js";
+
+export type { FileAttachmentRef, InlineAttachmentRef, RenderedPdfAttachmentRef };
+export type EmailAttachmentRef = InlineAttachmentRef | FileAttachmentRef | RenderedPdfAttachmentRef;
+
+export const MAX_EMAIL_ATTACHMENTS = 20;
+
+export const MAX_RENDERED_PDF_VARIABLES_BYTES = 64_000;
+
+const MAX_ID_LENGTH = 64;
+
+const fileRefIdSchema = z.string().min(1).max(MAX_ID_LENGTH);
+
+export const inlineAttachmentRefSchema = z
+  .object({
+    kind: z.literal("inline"),
+    cid: z.string().min(1).max(MAX_ID_LENGTH).refine(isDocumentResourceKey),
+    fileRefId: fileRefIdSchema,
+  })
+  .strict();
+
+export const fileAttachmentRefSchema = z
+  .object({
+    kind: z.literal("file"),
+    fileRefId: fileRefIdSchema,
+    fileName: attachmentFileNameSchema,
+  })
+  .strict();
+
+export const renderedPdfAttachmentRefSchema = z
+  .object({
+    kind: z.literal("rendered-pdf"),
+    templateSlug: templateSlugSchema,
+    variables: z
+      .record(z.string(), z.unknown())
+      .refine(
+        (value) => Buffer.byteLength(JSON.stringify(value)) <= MAX_RENDERED_PDF_VARIABLES_BYTES,
+        {
+          message: `variables must not exceed ${MAX_RENDERED_PDF_VARIABLES_BYTES} bytes as JSON`,
+        },
+      ),
+    fileName: attachmentFileNameSchema.refine((name) => name.toLowerCase().endsWith(".pdf"), {
+      message: "file name must end with .pdf",
+    }),
+    locale: z
+      .string()
+      .min(2)
+      .max(8)
+      .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "locale must be ISO 639-1 (e.g. de, en, en-us)")
+      .optional(),
+  })
+  .strict();
+
+export const emailAttachmentRefSchema = z.discriminatedUnion("kind", [
+  inlineAttachmentRefSchema,
+  fileAttachmentRefSchema,
+  renderedPdfAttachmentRefSchema,
+]);
+
+// Rebuilds only the contract fields so bytes a caller attached to a ref object
+// can never ride into a job payload.
+export function toAttachmentRef(ref: EmailAttachmentRef): EmailAttachmentRef {
+  switch (ref.kind) {
+    case "inline":
+      return { kind: "inline", cid: ref.cid, fileRefId: ref.fileRefId };
+    case "file":
+      return { kind: "file", fileRefId: ref.fileRefId, fileName: ref.fileName };
+    case "rendered-pdf":
+      return {
+        kind: "rendered-pdf",
+        templateSlug: ref.templateSlug,
+        variables: ref.variables,
+        fileName: ref.fileName,
+        ...(ref.locale !== undefined && { locale: ref.locale }),
+      };
+  }
+}