@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/billing-foundation/subscription-tier-sync.ts

@@ -14,6 +14,7 @@ import type {
   SignatureExtraRouteDeps,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { subscriptionAggregateId } from "./aggregate-id.js";
 import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.js";
 import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
@@ -37,6 +38,10 @@ export type SubscriptionTierSyncDeps<TTier extends string> = {
   readonly onSyncError?: "log" | "fail-webhook";
 };
 
+// A manual grant that differs from what billing would assign is reported with this
+// code but never fails the webhook: a provider retry cannot resolve it.
+export const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
+
 export function effectiveTierFromSubscription<TTier extends string>(
   status: string | undefined,
   tier: string | undefined,
@@ -52,12 +57,8 @@ export function effectiveTierFromSubscription<TTier extends string>(
 // (handler bug, or the handlerQn resolving to a non-list query) fails
 // loudly instead of crashing on `.find` against `undefined`.
 function asRows(result: unknown): ReadonlyArray<Record<string, unknown>> {
-  if (
-    typeof result === "object" &&
-    result !== null &&
-    Array.isArray((result as { rows?: unknown }).rows)
-  ) {
-    return (result as { rows: ReadonlyArray<Record<string, unknown>> }).rows;
+  if (isPlainObject(result) && Array.isArray(result["rows"])) {
+    return result["rows"];
   }
   throw new Error("expected a { rows: [...] } list-query result");
 }
@@ -85,7 +86,7 @@ export function createSubscriptionTierSync<TTier extends string>(
 ) {
   async function syncTierFromSubscription(
     tenantId: TenantId,
-    routeDeps: SignatureExtraRouteDeps,
+    routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">,
   ): Promise<{ code: string; message: string } | null> {
     try {
       const subscriptionId = subscriptionAggregateId(tenantId);
@@ -132,8 +133,13 @@ export function createSubscriptionTierSync<TTier extends string>(
         }
         return null;
       }
-      if (assignment.source === TierAssignmentSources.manual) return null;
       if (assignment.tier === effective) return null;
+      if (assignment.source === TierAssignmentSources.manual) {
+        return {
+          code: TIER_SYNC_MANUAL_GRANT_SKIPPED,
+          message: `manual tier grant "${String(assignment.tier)}" kept although the subscription yields "${effective}"`,
+        };
+      }
 
       const result = await routeDeps.dispatchSystemWrite({
         handlerQn: TierEngineHandlers.update,
@@ -172,9 +178,12 @@ export function createSubscriptionTierSync<TTier extends string>(
         if (syncError) {
           // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
           console.warn(
-            `[subscription-tier-sync] tier sync failed for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
+            `[subscription-tier-sync] tier sync for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
           );
-          if (deps.onSyncError === "fail-webhook") {
+          if (
+            deps.onSyncError === "fail-webhook" &&
+            syncError.code !== TIER_SYNC_MANUAL_GRANT_SKIPPED
+          ) {
             return {
               isSuccess: false,
               error: {
@@ -191,5 +200,5 @@ export function createSubscriptionTierSync<TTier extends string>(
     });
   }
 
-  return { createWebhookRoute };
+  return { createWebhookRoute, syncTierFromSubscription };
 }

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -396,7 +396,10 @@ export function isLegalLinkSet(
 
 /** Consumer-protection consent gate (§ 312j / § 356 BGB style). When set,
  *  `start-plan-checkout` and `create-checkout-session` require a `consent`
- *  payload and record it as an event before the buyer reaches the provider. */
+ *  payload and record it as an event before the buyer reaches the provider.
+ *  Every provider used with `create-checkout-session` must implement
+ *  `retrievePrices`: the live price is part of the consent record, and a
+ *  provider without it fails the checkout with an InternalError. */
 export type ConsumerProtectionOptions = {
   /** Slug of the template-resolver `text-block` holding the terms text; its
    *  content hash is stored with every recorded consent. */
@@ -411,7 +414,9 @@ export type ConsumerProtectionOptions = {
   readonly terminationScope?: TerminationScope;
   /** Names the item of a one-off payment (mode "payment") for the consent record
    *  and the confirmation mail; the label key is resolved through the registry
-   *  i18n, so it must be qualified with the registering feature. */
+   *  i18n, so it must be qualified with the registering feature. The label key
+   *  is 1-200 characters, string params at most 100; a violation fails the
+   *  checkout with an InternalError before the provider session is created. */
   readonly oneOffItemLabel?: (
     ctx: HandlerContext,
     priceId: string,

package/packages/bundled-features/src/cap-counter/calendar-cap-usage-reservation.ts

@@ -44,6 +44,8 @@ export async function reserveEnforcedCalendarCap(
       profile: cap.profile,
       notify: cap.notify,
       amount: cap.amount,
+      ...(cap.periodEndIso !== undefined && { periodEndIso: cap.periodEndIso }),
+      ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
       markSoftWarnedOutsideTransaction: outsideTransaction,
     });
   }

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "breaking",
+    "title": "CapExceededError carries resetAt and retryAfterSeconds, API sets Retry-After",
+    "migration": "Periodic caps no longer need RateLimitError({ windowSeconds: 0, ... }). Where you catch CapExceededError from enforceCap and rethrow it as RateLimitError, drop the catch and let CapExceededError pass: the response stays 429 with a correct Retry-After, error.code becomes cap_exceeded instead of rate_limited, and error.details carries resetAt and retryAfterSeconds. Keep a feature-specific message with enforceCap({ ..., i18nKey }) and pass a period end other than the calendar month with periodEndIso (e.g. a budget's resetsAtIso). Clients matching on rate_limited for these caps must also accept cap_exceeded. Any KumikoError with retryAfterSeconds (including RateLimitError thrown in a handler) now gets a Retry-After header from /api/write, /api/batch and /api/query."
+  },
   {
     "version": "0.361.0",
     "type": "improvement",

package/packages/bundled-features/src/cap-counter/enforce-cap.ts

@@ -66,14 +66,38 @@ export function assertBelowHardCap(
     readonly capName: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
+    // Rolling caps have no fixed period, so they pass neither period field.
+    readonly periodStartIso?: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
   },
 ): void {
   const tolerance = CAP_TOLERANCES[cap.profile];
   if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
-    throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+    const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
+    throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance, {
+      ...(resetAt !== undefined && { resetAt }),
+      ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
+    });
   }
 }
 
+function resolvePeriodEndIso(
+  periodStartIso: string | undefined,
+  periodEndIso: string | undefined,
+): string | undefined {
+  if (periodStartIso === undefined) return periodEndIso;
+  if (periodEndIso === undefined) return calendarMonthPeriodEndIso(periodStartIso);
+  const start = Temporal.Instant.from(periodStartIso);
+  const end = Temporal.Instant.from(periodEndIso);
+  if (Temporal.Instant.compare(end, start) <= 0) {
+    throw new Error(
+      `cap-counter: periodEndIso (${periodEndIso}) must be after periodStartIso (${periodStartIso})`,
+    );
+  }
+  return end.toString();
+}
+
 // =============================================================================
 // Enforce-Cap helper
 // =============================================================================
@@ -109,6 +133,9 @@ export async function enforceCap(
     // Units the caller is about to book in one go (default 1), checked with
     // the same outcome as booking them one by one.
     readonly amount?: number;
+    // Default: end of the calendar month that starts at periodStartIso.
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
   },
 ): Promise<EnforceCapResult> {
   const { user, readDb } = resolveCapCounterScope(ctx, false);
@@ -211,23 +238,54 @@ export async function enforceRollingCap(
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export class CapExceededError extends KumikoError {
   readonly code = "cap_exceeded" as const;
   readonly httpStatus = 429;
+  readonly resetAt: string | undefined;
 
   constructor(
     readonly capName: string,
     readonly limit: number,
     readonly currentValue: number,
     readonly tolerance: CapToleranceProfile,
+    options?: {
+      readonly resetAt?: string;
+      readonly i18nKey?: string;
+      readonly cause?: Error;
+      // Deterministic tests only.
+      readonly now?: Temporal.Instant;
+    },
   ) {
+    const resetAt = options?.resetAt;
+    const retryAfterSeconds =
+      resetAt === undefined
+        ? undefined
+        : Math.max(
+            0,
+            Math.ceil(
+              Temporal.Instant.from(resetAt).epochMilliseconds / 1000 -
+                (options?.now ?? Temporal.Now.instant()).epochMilliseconds / 1000,
+            ),
+          );
     super({
-      message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.`,
-      i18nKey: "errors.cap.exceeded",
-      i18nParams: { capName, limit, currentValue },
-      details: { capName, limit, currentValue, tolerance },
+      message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.${resetAt === undefined ? "" : ` Resets at ${resetAt}.`}`,
+      i18nKey: options?.i18nKey ?? "errors.cap.exceeded",
+      i18nParams: { capName, limit, currentValue, ...(resetAt !== undefined && { resetAt }) },
+      details: {
+        capName,
+        limit,
+        currentValue,
+        tolerance,
+        ...(resetAt !== undefined && { resetAt, retryAfterSeconds }),
+      },
+      ...(retryAfterSeconds !== undefined && { retryAfterSeconds }),
+      ...(options?.cause && { cause: options.cause }),
     });
+    this.resetAt = resetAt;
   }
 }
 
@@ -257,6 +315,14 @@ export function currentCalendarMonthStartIso(
   return start.toInstant().toString();
 }
 
+export function calendarMonthPeriodEndIso(periodStartIso: string): string {
+  return Temporal.Instant.from(periodStartIso)
+    .toZonedDateTimeISO("UTC")
+    .add({ months: 1 })
+    .toInstant()
+    .toString();
+}
+
 // =============================================================================
 // Notification-Wiring helpers — convenience-wrapper für enforceCap +
 // enforceRollingCap, die einen Caller-supplied delivery-emit beim
@@ -299,6 +365,8 @@ export async function enforceCapAndMaybeNotify(
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly markSoftWarnedOutsideTransaction?: boolean;
   },
 ): Promise<EnforceCapResult> {
@@ -308,6 +376,8 @@ export async function enforceCapAndMaybeNotify(
     limit: options.limit,
     profile: options.profile,
     ...(options.amount !== undefined && { amount: options.amount }),
+    ...(options.periodEndIso !== undefined && { periodEndIso: options.periodEndIso }),
+    ...(options.i18nKey !== undefined && { i18nKey: options.i18nKey }),
   });
 
   if (result.state === "soft-hit" && result.crossed) {

package/packages/bundled-features/src/cap-counter/index.ts

@@ -29,6 +29,7 @@ export {
   CapExceededError,
   type CapToleranceProfile,
   type CapToleranceProfileName,
+  calendarMonthPeriodEndIso,
   currentCalendarMonthStartIso,
   type EnforceCapResult,
   enforceCap,

package/packages/bundled-features/src/cap-counter/with-cap-enforcement.ts

@@ -53,6 +53,9 @@ import { chainReservations } from "./reservation-chain.js";
 export type CalendarCapDef = {
   readonly capName: string;
   readonly periodStartIso: string;
+  // Default: end of the calendar month that starts at periodStartIso.
+  readonly periodEndIso?: string;
+  readonly i18nKey?: string;
   readonly limit: number;
   readonly profile: CapToleranceProfileName;
   /** Increment-amount post-success. Default 1. */

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -7,6 +7,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { subscriptionsProjectionTable } from "../../billing-foundation/index.js";
 import type { CapLimitContext } from "../../cap-counter/index.js";
@@ -79,7 +80,7 @@ async function resolveLimitsByTenantAndCap(
 }
 
 function isSortableField(field: string): field is SortableField {
-  return (SORTABLE_FIELDS as readonly string[]).includes(field);
+  return isOneOf(SORTABLE_FIELDS, field);
 }
 
 // tier is a plain string with no defined ordering — lt/gt have no meaning

package/packages/bundled-features/src/cap-overview/web/cap-usage-cell.tsx

@@ -1,17 +1,19 @@
 // @runtime client
+
 import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { ReactNode } from "react";
 import type { CapUsage } from "../types.js";
 import { CapUsageBar } from "./cap-usage-bar.js";
 
 function isCapUsage(value: unknown): value is CapUsage {
-  if (typeof value !== "object" || value === null) return false;
-  const used = (value as { used?: unknown }).used;
-  const limit = (value as { limit?: unknown }).limit;
+  if (!isPlainObject(value)) return false;
+  const used = value["used"];
+  const limit = value["limit"];
   return (
     (typeof used === "number" || used === null) &&
     (typeof limit === "number" || limit === null) &&
-    typeof (value as { fraction?: unknown }).fraction === "number"
+    typeof value["fraction"] === "number"
   );
 }
 

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "A notification without a mail template fails on the email channel",
+    "detail": "The renderer option of createChannelEmailFeature is removed. A notification routed to the email channel without template + meta fails its delivery permanently with \"has no mail template, declare template + meta on r.notification\". r.notification declares no channels, so this is not checked at boot; an app's own mail tests over the inmemory transport catch it.",
+    "migration": "Drop the renderer option. Declare template + meta (or localizedTemplate) and variables on every r.notification that reaches the email channel, or accept that its email delivery fails. Run the app's notification tests after the bump: every email notification without a template now fails there."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Email channel sends rendered-pdf attachments",
+    "detail": "The channel resolves rendered-pdf entries from notify data next to file entries; without a locale the message locale is used. A render failure fails the send job, so the retry runs it again."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Email channel sends file attachments and inline cid images",
+    "detail": "EmailMessage.attachments is sent through the SMTP transport (inline images with Content-ID). notify data.attachments with kind file entries are resolved through the file store; the PII guard rejects ciphertext file names."
+  },
   {
     "version": "0.350.0",
     "type": "improvement",

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,45 @@ 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,
+  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, fromName, replyTo } = await ctx.renderMail({
+      slug: notificationType,
+      locale: message.locale ?? "en",
+      variables: message.data ?? {},
+      ...(typeof unsubscribeUrl === "string" && { unsubscribeUrl }),
+    });
+    return {
+      html,
+      subject,
+      text,
+      ...(fromName !== undefined && { fromName }),
+      ...(replyTo !== undefined && { replyTo }),
+      ...(attachments !== undefined && { attachments }),
     };
-    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 }) };
   }
 
   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 +219,28 @@ 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));
-      const envelope = emailEnvelopeFrom(message.data);
+    async send(address, message, ctx, rendered) {
+      const { html, subject, text, attachments, fromName, replyTo } =
+        rendered ?? (await renderMessage(message, ctx));
+      // Template-level sender defaults; notify data wins.
+      const envelope = {
+        ...(fromName && { fromName }),
+        ...(replyTo && { replyTo }),
+        ...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 +248,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) ||