@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

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/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);
@@ -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/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,
@@ -42,7 +47,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 +342,33 @@ 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 });
+    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 +503,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 +518,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/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/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/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,105 @@
+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;
+
+// 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);
+
+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 }),
+      };
+  }
+}