@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

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

@@ -1,5 +1,6 @@
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import * as z from "zod";
 import {
   type AttachmentOrigin,
@@ -15,7 +16,7 @@ import {
   type RenderedMessage,
   renderedPdfAttachmentRefSchema,
 } from "../delivery/index.js";
-import { decryptStoredPii } from "../shared/index.js";
+import { decryptStoredPii, extensionForResourceContentType } from "../shared/index.js";
 import { guardEmailMessage } from "./pii-guard.js";
 import type { EmailAttachment, EmailTransport } from "./types.js";
 
@@ -39,7 +40,8 @@ const UNSUBSCRIBE_HEADER_NAMES: ReadonlySet<string> = new Set([
   "list-unsubscribe-post",
 ]);
 
-// Only the framework's own unsubscribe route can honor a one-click POST.
+// Only the framework's own unsubscribe route can honor a one-click POST; an app's
+// own unsubscribe page still gets the plain List-Unsubscribe link (RFC 2369).
 function listUnsubscribeHeaders(
   data: Readonly<Record<string, unknown>> | undefined,
 ): Readonly<Record<string, string>> | undefined {
@@ -52,7 +54,9 @@ function listUnsubscribeHeaders(
     return undefined;
   }
   if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
-  if (url.pathname !== DELIVERY_UNSUBSCRIBE_PATH) return undefined;
+  if (url.pathname !== DELIVERY_UNSUBSCRIBE_PATH) {
+    return { "List-Unsubscribe": `<${url.toString()}>` };
+  }
   return {
     "List-Unsubscribe": `<${url.toString()}>`,
     "List-Unsubscribe-Post": DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
@@ -110,20 +114,22 @@ export function fileAttachmentsFrom(
     );
 }
 
-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 };
 
+function inlineFileName(cid: string, contentType: string): string {
+  const extension = extensionForResourceContentType(contentType);
+  return extension === undefined ? cid : `${cid}.${extension}`;
+}
+
+type ResolvedAttachments =
+  | { readonly kind: "resolved"; readonly attachments: readonly EmailAttachment[] }
+  | { readonly kind: "missing-file"; readonly fileRefId: string };
+
 async function resolveAttachments(
   sources: readonly AttachmentSource[],
   ctx: ChannelContext,
-): Promise<readonly EmailAttachment[]> {
-  if (sources.length === 0) return [];
+): Promise<ResolvedAttachments> {
+  if (sources.length === 0) return { kind: "resolved", attachments: [] };
   if (ctx.readAttachment === undefined) {
     throw new Error(
       "email channel: the message has attachments but the channel context cannot read files",
@@ -148,17 +154,13 @@ async function resolveAttachments(
     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`);
+      return { kind: "missing-file", fileRefId: ref.fileRefId };
     }
     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;
+      ref.kind === "file" ? ref.fileName : inlineFileName(ref.cid, found.contentType);
     resolved.push({ ...ref, fileName, content: found.content, contentType: found.contentType });
   }
-  return resolved;
+  return { kind: "resolved", attachments: resolved };
 }
 
 export type EmailChannelOptions = {
@@ -191,13 +193,20 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
       );
     }
     const unsubscribeUrl = message.data?.["unsubscribeUrl"];
-    const { subject, html, text, attachments } = await ctx.renderMail({
+    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, ...(attachments !== undefined && { attachments }) };
+    return {
+      html,
+      subject,
+      text,
+      ...(fromName !== undefined && { fromName }),
+      ...(replyTo !== undefined && { replyTo }),
+      ...(attachments !== undefined && { attachments }),
+    };
   }
 
   return {
@@ -217,9 +226,15 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
     },
 
     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(
+      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 resolution = await resolveAttachments(
         [
           ...(attachments ?? []).map((ref): AttachmentSource => ({ ref, origin: "template" })),
           ...fileAttachmentsFrom(message.data, message.locale).map(
@@ -228,6 +243,14 @@ export function createEmailChannel(options: EmailChannelOptions): DeliveryChanne
         ],
         ctx,
       );
+      if (resolution.kind === "missing-file") {
+        // A missing file is permanent, a retry cannot bring it back.
+        createFallbackLogger("delivery").warn("mail attachment file not found, send failed", {
+          fileRefId: resolution.fileRefId,
+        });
+        return { status: "failed", error: "send_failed", address };
+      }
+      const resolvedAttachments = resolution.attachments;
       await transport.send(
         guardEmailMessage({
           to: address,

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

@@ -54,11 +54,17 @@ function isControlCharacter(char: string): boolean {
   return code <= 0x1f || code === 0x7f;
 }
 
+// Mail clients often show only the display name: an embedded address ("<", ">", "@") would
+// pass for a foreign sender on the platform's own SPF/DKIM-signed domain.
+function isUnsafeDisplayNameCharacter(char: string): boolean {
+  return isControlCharacter(char) || char === "<" || char === ">" || char === "@";
+}
+
 // Control characters in a display name would let a caller inject headers.
 function sanitizedDisplayName(name: string | undefined): string | undefined {
   const cleaned = name
     ?.split("")
-    .map((char) => (isControlCharacter(char) ? " " : char))
+    .map((char) => (isUnsafeDisplayNameCharacter(char) ? " " : char))
     .join("")
     .trim();
   return cleaned === undefined || cleaned === "" ? undefined : cleaned;

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

@@ -7,9 +7,11 @@ import {
 
 export type SlackChannelOptions = ChatWebhookChannelOptions;
 
+const SLACK_WEBHOOK_PREFIX = "channel-slack:webhooks.";
+
 export const SLACK_SECRET_KEYS = {
-  webhookPrefix: "channel-slack:webhooks.",
-  webhookKeyFor: (connection: string) => `channel-slack:webhooks.${connection}`,
+  webhookPrefix: SLACK_WEBHOOK_PREFIX,
+  webhookKeyFor: (connection: string) => `${SLACK_WEBHOOK_PREFIX}${connection}`,
 } as const;
 
 export const SLACK_DEFAULT_ALLOWED_HOSTS = ["hooks.slack.com"] as const;

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

@@ -8,9 +8,11 @@ import {
 
 export type TeamsChannelOptions = ChatWebhookChannelOptions;
 
+const TEAMS_WEBHOOK_PREFIX = "channel-teams:webhooks.";
+
 export const TEAMS_SECRET_KEYS = {
-  webhookPrefix: "channel-teams:webhooks.",
-  webhookKeyFor: (connection: string) => `channel-teams:webhooks.${connection}`,
+  webhookPrefix: TEAMS_WEBHOOK_PREFIX,
+  webhookKeyFor: (connection: string) => `${TEAMS_WEBHOOK_PREFIX}${connection}`,
 } as const;
 
 export const TEAMS_DEFAULT_ALLOWED_HOSTS = [

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Config key validate() receives a db scoped to the written tenant",
+    "detail": "A SystemAdmin writing a config value for another tenant previously handed the validator a system-mode db that could read every tenant. `ConfigValidateContext.db` is now a `TenantDb` locked to the tenant the value is written for. The validator runs inside the write transaction, so a slow query there should set its own timeout."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

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

@@ -4,7 +4,7 @@ import {
   encryptPiiValueForSubject,
   type KmsContext,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { createEventStoreExecutor, scopeTenantDbToTenant } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   defineWriteHandler,
@@ -111,7 +111,7 @@ export const setWrite = defineWriteHandler({
           scope,
           tenantId,
           userId,
-          db,
+          db: scopeTenantDbToTenant(db, tenantId),
         });
       } catch (error) {
         if (isKumikoError(error)) return writeFailure(error);

package/packages/bundled-features/src/config/resolver.ts

@@ -119,6 +119,19 @@ async function decryptPiiEncrypted(raw: string, qualifiedKey: string): Promise<s
   return decryptPiiValueForSubject(kms, raw, kmsCtx, qualifiedKey);
 }
 
+// Plaintext form of a stored config_values.value for every read path (resolver,
+// bootstrap idempotency check).
+export async function decryptStoredValue(
+  raw: string,
+  keyDef: ConfigKeyDefinition,
+  cipher: EnvelopeCipher | undefined,
+  qualifiedKey: string,
+): Promise<string> {
+  if (keyDef.encrypted) return decryptEncrypted(cipher, raw, qualifiedKey);
+  if (keyDef.piiEncrypted) return decryptPiiEncrypted(raw, qualifiedKey);
+  return raw;
+}
+
 // backing="secrets" keys store their value in the secrets store (flat per
 // (tenant,key) at SYSTEM_TENANT_ID), not in config_values. Both read paths
 // (getWithSource + buildCascade) route the system rung here. Missing reader =
@@ -230,12 +243,7 @@ async function buildCascade(
 
     const row = await fetchRow(lookup.tenantId, lookup.userId);
     if (row?.value !== null && row?.value !== undefined) {
-      let raw = row.value;
-      if (keyDef.encrypted) {
-        raw = await decryptEncrypted(cipher, raw, qualifiedKey);
-      } else if (keyDef.piiEncrypted) {
-        raw = await decryptPiiEncrypted(raw, qualifiedKey);
-      }
+      const raw = await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey);
       if (activeIndex === -1) activeIndex = levels.length;
       levels.push({
         label: lookup.label,
@@ -409,12 +417,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       for (const lookup of lookups) {
         const row = await findRow(qualifiedKey, lookup.tenantId, lookup.userId, db);
         if (row?.value !== null && row?.value !== undefined) {
-          let raw = row.value;
-          if (keyDef.encrypted) {
-            raw = await decryptEncrypted(cipher, raw, qualifiedKey);
-          } else if (keyDef.piiEncrypted) {
-            raw = await decryptPiiEncrypted(raw, qualifiedKey);
-          }
+          const raw = await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey);
           return { value: deserializeValue(raw, keyDef.type), source: lookup.source };
         }
       }

package/packages/bundled-features/src/config/write-helpers.ts

@@ -28,8 +28,10 @@ import {
   type WriteFailure,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import { assertUnreachable } from "@cosmicdrift/kumiko-framework/utils";
 import { ConfigErrors } from "./constants.js";
+import { decryptStoredValue } from "./resolver.js";
 import { configValuesTable } from "./table.js";
 
 export type ConfigRowLookup = {
@@ -62,6 +64,27 @@ export async function findConfigRow(
   };
 }
 
+// Idempotency check for declarative writers: does the stored row already hold
+// `serializedValue` (JSON of the plaintext)? Encrypted rows are decrypted
+// first, since their ciphertext differs on every encrypt.
+export async function configRowHoldsValue(
+  row: ConfigRowLookup | null,
+  keyDef: ConfigKeyDefinition | undefined,
+  cipher: EnvelopeCipher | undefined,
+  qualifiedKey: string,
+  serializedValue: string,
+): Promise<boolean> {
+  if (row?.value === null || row?.value === undefined) return false;
+  if (!keyDef?.encrypted && !keyDef?.piiEncrypted) return row.value === serializedValue;
+  if (!keyDef) return false;
+  try {
+    return (await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey)) === serializedValue;
+  } catch {
+    // Unreadable (rotated key, missing cipher/KMS): the caller rewrites the row, which is the repair.
+    return false;
+  }
+}
+
 // Three-stage pre-write gate that set + reset both need: resolve the key
 // definition (404 when unknown), check the user's roles can write it (403),
 // and map the target scope to the (tenantId | null, userId | null) pair the

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "forget-subject keeps the user status flip and PAT revocation when the sweep fails",
+    "detail": "The user is set to Deleted and its personal access tokens are revoked right after the key erase, in their own transaction on the outside-transaction db. A failing blind-index or search sweep still makes the handler throw so the cleanup can be retried, but it no longer rolls the login door back. Without an outside-transaction db the previous in-transaction savepoint path is used. A failure while closing the login door of an existing user now fails the forget (retry is safe) instead of passing silently; subjects without a user row are skipped."
+  },
   {
     "version": "0.357.0",
     "type": "improvement",

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -1,6 +1,11 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import { runInSavepointIfSupported } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  fetchOne,
+  runInSavepointIfSupported,
+  runnerCanBeginTransaction,
+  transaction,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   computeBlindIndex,
   configuredBlindIndexKey,
@@ -16,6 +21,7 @@ import {
   recordRowExistsInTenant,
   recordRowOwningTenantId,
   subjectRowExistsInTenant,
+  WritePurposes,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
   defineWriteHandler,
@@ -42,7 +48,7 @@ import * as z from "zod";
 import { resolveRetentionPolicyForTenant } from "../../data-retention/index.js";
 import { eraseNoteBodiesReachingSubject } from "../../notes-history-user-data/index.js";
 import { revokeAllPatTokensForUser } from "../../personal-access-tokens/index.js";
-import { USER_STATUS } from "../../user/index.js";
+import { USER_STATUS, userTable } from "../../user/index.js";
 import {
   denyIfTargetOutsideAdminTenant,
   isSystemAdminActor,
@@ -337,25 +343,38 @@ async function sweepDerivedSubjectData(
   }
 }
 
-// Graceful fail: email-subscribers and other non-user entities may use
-// user-style subject keys without having an actual user row — the key erase is
-// the important part for GDPR compliance; the lifecycle update is best-effort for
-// real users. The savepoint confines the failure so the handler transaction
-// stays usable for the audit event.
-async function closeUserLoginDoorBestEffort(
+// Email subscribers and other non-user entities use user-style subject keys
+// without a read_users row — the key erase is the GDPR-relevant part, so no row
+// means nothing to close. For an existing row, failures propagate: the handler
+// throws and the retry re-runs the (idempotent) erase plus the door close. With
+// an outside-transaction runner that can open its own transaction, the door
+// closes there and stays committed when the handler throws afterwards (sweep
+// error). Otherwise a savepoint confines a failure to the handler transaction.
+async function closeUserLoginDoor(
   ctx: HandlerContext,
   userId: string,
-  lifecycleRunner: DbRunner,
+  outsideRunner: DbRunner | undefined,
+  handlerTxRunner: DbRunner,
 ): Promise<void> {
-  try {
-    await runInSavepointIfSupported(lifecycleRunner, async (userLifecycleRunner) => {
-      await updateUserLifecycle(userLifecycleRunner, userId, { status: USER_STATUS.Deleted });
-      if (ctx.registry.features.has("personal-access-tokens")) {
-        await revokeAllPatTokensForUser(userLifecycleRunner, userId);
-      }
-    });
-  } catch {
-    // skip: no user row for this subject key (e.g. email subscribers); key erase and sweeps already ran.
+  const userRow = await fetchOne(handlerTxRunner, userTable, { id: userId });
+  // skip: no user row for this subject key (e.g. email subscribers); there is no door to close.
+  if (!userRow) return;
+
+  const closeDoor = async (runner: DbRunner): Promise<void> => {
+    await updateUserLifecycle(
+      runner,
+      userId,
+      { status: USER_STATUS.Deleted },
+      { writePurpose: WritePurposes.erasure },
+    );
+    if (ctx.registry.features.has("personal-access-tokens")) {
+      await revokeAllPatTokensForUser(runner, userId);
+    }
+  };
+  if (outsideRunner && runnerCanBeginTransaction(outsideRunner)) {
+    await transaction(outsideRunner, closeDoor);
+  } else {
+    await runInSavepointIfSupported(handlerTxRunner, closeDoor);
   }
 }
 
@@ -490,14 +509,6 @@ export const forgetSubjectWrite = defineWriteHandler({
       eraseReason: event.payload.reason,
     });
 
-    const cleanupError = await sweepDerivedSubjectData(
-      ctx,
-      subject,
-      subjectKey,
-      ctx.db.unsafeRaw(),
-      { requestId, erasedBy: event.user.id },
-    );
-
     // User subject: close the login door. DEK-erase makes the passwordHash
     // ciphertext unreadable, but status + PATs are standalone credentials —
     // the PAT resolver only checks revokedAt/expiresAt, NOT user.status
@@ -513,10 +524,26 @@ export const forgetSubjectWrite = defineWriteHandler({
     // crash recovery is safe. User-feature guard: without the user feature
     // read_users doesn't exist (crypto-only stack). Tenant subjects have no
     // credentials.
+    // Runs before the sweep and in its own transaction: a failing sweep rolls the
+    // handler transaction back, and the handler tx holds no lock on this user's
+    // read_users row yet (only read gates ran), so there is no lock conflict.
     if (raw.kind === "user" && ctx.registry.features.has("user")) {
-      await closeUserLoginDoorBestEffort(ctx, raw.userId, ctx.db.unsafeRaw());
+      await closeUserLoginDoor(
+        ctx,
+        raw.userId,
+        ctx.dbOutsideTransaction?.unsafeRaw(),
+        ctx.db.unsafeRaw(),
+      );
     }
 
+    const cleanupError = await sweepDerivedSubjectData(
+      ctx,
+      subject,
+      subjectKey,
+      ctx.db.unsafeRaw(),
+      { requestId, erasedBy: event.user.id },
+    );
+
     await appendSubjectForgotten(
       ctx,
       event,

package/packages/bundled-features/src/custom-fields/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "update-tenant-field no longer hides `type` from the handler schema",
+    "detail": "The `type` field is part of the documented payload; the 422 check against changing the stored type remains the protection."
+  },
   {
     "version": "0.359.0",
     "type": "improvement",

package/packages/bundled-features/src/custom-fields/db/queries/retention.ts

@@ -1,5 +1,5 @@
 import { asRawClient, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectHostRowsWithCustomFields(
   db: DbRunner,
@@ -38,6 +38,6 @@ export async function applyRetentionRemovals(
        ELSE custom_fields
      END
      WHERE id = $3`,
-    [deleteKeys, anonymizeKeys, rowId],
+    [toPostgresArrayLiteral(deleteKeys), toPostgresArrayLiteral(anonymizeKeys), rowId],
   );
 }

package/packages/bundled-features/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -46,7 +46,6 @@ export function createUpdateTenantFieldHandler(
     access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
     description:
       "Replaces a tenant-owned custom-field definition with a complete new spec; serializedField.type may be omitted, in which case the stored type applies, and a different type is refused. Use it to relabel or re-constrain an existing field rather than to create or remove one.",
-    excludedFields: ["type"],
     handler: async (event, ctx) => {
       const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
       const tenantId = event.user.tenantId;

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

@@ -57,7 +57,7 @@ import {
   type WhereObject,
   WritePurposes,
 } from "@cosmicdrift/kumiko-framework/db";
-import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
+import { deleteFileRefBytes } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
   createSystemUser,
   type EntityDefinition,
@@ -386,11 +386,11 @@ async function isFileRefSharedByOtherRow(
 // not abort the whole tenant run.
 async function deleteFileFailingClosed(
   key: string,
-  store: Parameters<typeof deleteStoredFileAndDerivatives>[1],
+  files: FileContext,
   logContext: string,
 ): Promise<readonly string[]> {
   try {
-    return await deleteStoredFileAndDerivatives(key, store, "data-retention:hardDelete");
+    return await deleteFileRefBytes(files, { storageKey: key }, "data-retention:hardDelete");
   } catch (err) {
     // biome-ignore lint/suspicious/noConsole: operator-visibility for storage-cleanup failures
     console.warn(
@@ -477,7 +477,6 @@ async function purgeHardDeleteRowWithFiles(args: {
     return false;
   }
   const files = args.files;
-  const store = { list: files.list, delete: (key: string) => files.ref(key).delete() };
 
   let anyFailed = false;
   for (const fileRef of toDelete) {
@@ -485,7 +484,7 @@ async function purgeHardDeleteRowWithFiles(args: {
     if (typeof key !== "string" || key.length === 0) continue;
     const failedKeys = await deleteFileFailingClosed(
       key,
-      store,
+      files,
       `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`,
     );
     if (failedKeys.length > 0) {

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

@@ -14,6 +14,27 @@ export const MAX_EMAIL_ATTACHMENTS = 20;
 
 export const MAX_RENDERED_PDF_VARIABLES_BYTES = 64_000;
 
+// Channel-data keys that steer delivery itself (envelope, headers, attachments);
+// they are not document variables and must not be copied into attached PDF refs.
+export const DELIVERY_ENVELOPE_DATA_KEYS = [
+  "attachments",
+  "from",
+  "fromName",
+  "replyTo",
+  "headers",
+  "unsubscribeUrl",
+] as const;
+
+const DELIVERY_ENVELOPE_DATA_KEY_SET: ReadonlySet<string> = new Set(DELIVERY_ENVELOPE_DATA_KEYS);
+
+export function withoutDeliveryEnvelopeKeys(
+  variables: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(variables).filter(([key]) => !DELIVERY_ENVELOPE_DATA_KEY_SET.has(key)),
+  );
+}
+
 const MAX_ID_LENGTH = 64;
 
 const fileRefIdSchema = z.string().min(1).max(MAX_ID_LENGTH);
@@ -34,14 +55,31 @@ export const fileAttachmentRefSchema = z
   })
   .strict();
 
+// BigInt values and cycles make JSON.stringify throw; that must surface as a validation issue,
+// not a raw TypeError that a retrying job hits again on the same data.
+function isJsonSerializable(value: unknown): boolean {
+  try {
+    JSON.stringify(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function jsonByteLength(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+
 export const renderedPdfAttachmentRefSchema = z
   .object({
     kind: z.literal("rendered-pdf"),
     templateSlug: templateSlugSchema,
     variables: z
       .record(z.string(), z.unknown())
+      .refine(isJsonSerializable, { message: "variables must be JSON-serializable" })
       .refine(
-        (value) => Buffer.byteLength(JSON.stringify(value)) <= MAX_RENDERED_PDF_VARIABLES_BYTES,
+        (value) =>
+          !isJsonSerializable(value) || jsonByteLength(value) <= MAX_RENDERED_PDF_VARIABLES_BYTES,
         {
           message: `variables must not exceed ${MAX_RENDERED_PDF_VARIABLES_BYTES} bytes as JSON`,
         },

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

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Rendered-PDF attachment variables must be JSON-serializable",
+    "detail": "BigInt values or cycles in rendered-pdf variables now fail validation instead of throwing a TypeError that a retrying job hits again."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Delivery checks opt-outs for addresses resolved on the retry path and logs idempotency release failures",
+    "detail": "The kill switch, preference and rate-limit result per recipient channel is computed once in the prefetch and reused when delivering; the rate limit now runs before the address is resolved. When the prefetch resolve failed and the address is resolved again, the suppression list is reloaded for exactly that address, so an unsubscribed address no longer receives the mail. A failing idempotency-key release is logged and swallowed instead of masking the delivery outcome."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "A failed final delivery attempt frees the idempotency key",
+    "detail": "A soft send failure and any error thrown on the final render or send attempt release the idempotency key, so the caller's retry is not dropped as a duplicate."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "A mail without a readable inline image is sent without it",
+    "detail": "An inline image whose bytes could not be read (for example a system template logo while the job context has no provider resolver) failed the whole mail send. The attachment reader now logs a warning with the fileRef id and skips the image."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Delivery exports the envelope-key filter for mail variables",
+    "detail": "withoutDeliveryEnvelopeKeys strips reserved delivery keys from template variables."
+  },
   {
     "version": "0.363.0",
     "type": "breaking",