@cosmicdrift/kumiko-samples 0.338.0 → 0.339.0

package/packages/bundled-features/src/renderer-simple/simple-renderer.ts

@@ -1,6 +1,62 @@
-import { escapeHtml } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { NotificationRenderer } from "../delivery/index.js";
 
+export type MailBranding = {
+  /** Shown as text when there is no logo, and as the logo alt text. */
+  readonly productName?: string;
+  /** Hex color (#rgb, #rrggbb, #rrggbbaa); used for buttons and the header accent. */
+  readonly primaryColor?: string;
+  /** Absolute http(s) URL; anything else is dropped. */
+  readonly logoUrl?: string;
+  readonly footerText?: string;
+  /** Absolute http(s) URLs only; other entries are dropped. */
+  readonly footerLinks?: readonly { readonly label: string; readonly url: string }[];
+};
+
+const DEFAULT_PRIMARY_COLOR = "#2563eb";
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function resolvePrimaryColor(branding: MailBranding | undefined): string {
+  const color = branding?.primaryColor;
+  return color && HEX_COLOR_PATTERN.test(color) ? color : DEFAULT_PRIMARY_COLOR;
+}
+
+function renderBrandingHeader(branding: MailBranding | undefined, primaryColor: string): string {
+  if (!branding) return "";
+  const logoUrl = branding.logoUrl && isHttpUrl(branding.logoUrl) ? branding.logoUrl : undefined;
+  if (!logoUrl && !branding.productName) return "";
+  const logo = logoUrl
+    ? `<img src="${escapeHtmlAttr(logoUrl)}" alt="${escapeHtmlAttr(branding.productName ?? "")}" style="display:block;max-height:40px;max-width:200px;border:0" />`
+    : `<span style="font-size:18px;font-weight:700;color:${escapeHtmlAttr(primaryColor)}">${escapeHtml(branding.productName ?? "")}</span>`;
+  return `<div style="margin:0 0 24px;padding:0 0 16px;border-bottom:3px solid ${escapeHtmlAttr(primaryColor)}">${logo}</div>`;
+}
+
+function renderBrandingFooter(branding: MailBranding | undefined): string {
+  if (!branding) return "";
+  const links = (branding.footerLinks ?? [])
+    .filter((link) => isHttpUrl(link.url))
+    .map(
+      (link) =>
+        `<a href="${escapeHtmlAttr(link.url)}" style="color:#999">${escapeHtml(link.label)}</a>`,
+    );
+  const footerPartsHtml = [
+    branding.footerText ? escapeHtml(branding.footerText) : "",
+    links.join(" · "),
+  ].filter((part) => part !== "");
+  if (footerPartsHtml.length === 0) return "";
+  const footerHtml = footerPartsHtml.join("<br />");
+  return `<p style="margin:16px 0 0;color:#999;font-size:12px">${footerHtml}</p>`;
+}
+
 type Section =
   | { readonly text: string }
   | { readonly button: { readonly label: string; readonly url: string } };
@@ -15,51 +71,58 @@ type EmailTemplateData = {
   readonly body?: string;
 };
 
-function renderSection(section: Section): string {
+function renderSection(section: Section, primaryColor: string): string {
   if ("text" in section) {
     return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
   }
   if ("button" in section) {
-    return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
+    return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
   }
   return "";
 }
 
 // Simple Renderer: turns structured email template data into HTML with inline CSS.
 // No external dependencies, no template engine — just string concatenation.
-export const simpleRenderer: NotificationRenderer = {
-  name: "simple",
+export function createSimpleRenderer(branding?: MailBranding): NotificationRenderer {
+  const primaryColor = resolvePrimaryColor(branding);
+  return {
+    name: "simple",
+
+    async render(input) {
+      const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
 
-  async render(input) {
-    const data = input.variables as EmailTemplateData; // @cast-boundary render-helper
+      // Fallback: if no structured fields, use title + body as header + single text section
+      const header = data.header ?? data.title;
+      const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
 
-    // Fallback: if no structured fields, use title + body as header + single text section
-    const header = data.header ?? data.title;
-    const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
+      const parts: string[] = [];
+      parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
+      parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+      parts.push(renderBrandingHeader(branding, primaryColor));
 
-    const parts: string[] = [];
-    parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
-    parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+      if (header) {
+        parts.push(
+          `<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`,
+        );
+      }
 
-    if (header) {
-      parts.push(
-        `<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`,
-      );
-    }
+      if (sections) {
+        for (const section of sections) {
+          parts.push(renderSection(section, primaryColor));
+        }
+      }
 
-    if (sections) {
-      for (const section of sections) {
-        parts.push(renderSection(section));
+      if (data.footer) {
+        parts.push(
+          `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
+        );
       }
-    }
 
-    if (data.footer) {
-      parts.push(
-        `<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`,
-      );
-    }
+      parts.push(renderBrandingFooter(branding));
+      parts.push("</div></body></html>");
+      return parts.join("");
+    },
+  };
+}
 
-    parts.push("</div></body></html>");
-    return parts.join("");
-  },
-};
+export const simpleRenderer: NotificationRenderer = createSimpleRenderer();

package/packages/bundled-features/src/secrets/feature.ts

@@ -183,7 +183,7 @@ export function createSecretsFeature(opts: SecretsFeatureOptions = {}): FeatureD
         rotateJob(
           payload,
           ctx,
-          ctx.db.unsafeRaw(ROTATE_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
         ),
     });
 

package/packages/bundled-features/src/sessions/feature.ts

@@ -177,7 +177,7 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
           cleanupJob(
             payload,
             ctx,
-            ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON) as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+            ctx.db.unsafeRaw() as DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
           ),
       });
 

package/packages/bundled-features/src/sessions/handlers/revoke-all-for-user.write.ts

@@ -49,7 +49,7 @@ export const revokeAllForUserWrite = defineWriteHandler({
     reason: REVOKE_ALL_SESSIONS_REASON,
   },
   handler: async (event, ctx) => {
-    const runner = ctx.db.unsafeRaw(REVOKE_ALL_SESSIONS_REASON);
+    const runner = ctx.db.unsafeRaw();
     const updated = await updateMany<{ id: string }>(
       runner,
       userSessionTable,

package/packages/bundled-features/src/tenant-handover/handlers/claim.write.ts

@@ -51,10 +51,7 @@ export function createClaimTenantHandoverHandler(opts: ClaimTenantHandoverOption
     agent: { expose: false },
     rateLimit: { per: "user", limit: 10, windowSeconds: 60 },
     handler: async (event, ctx) => {
-      const db = ctx.db.unsafeRaw(
-        "tenant-handover claim: cross-tenant read + ownership write, legitimized by the " +
-          "row-bound grant redeemed below",
-      );
+      const db = ctx.db.unsafeRaw();
       const rootLocation = resolveRootAnchorLocation(ctx.registry, db, event.payload.entityType);
       if (!rootLocation) return notTransferable(event.payload.entityType);
       const { rootTableName, rootIdCol, rootTenantCol, loadAnchor } = rootLocation;

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -126,9 +126,7 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
         }
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
         await runTenantDestructionSweep({
-          db: ctx.db.unsafeRaw(
-            RUN_TENANT_DESTRUCTION_REASON,
-          ) as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
+          db: ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
           registry: ctx.registry,
           now: T.Now.instant(),
           log: (message) => ctx.log?.warn(message),

package/packages/bundled-features/src/tenant-lifecycle/handlers/cancel-destruction.write.ts

@@ -30,11 +30,9 @@ export const cancelDestructionWrite = defineWriteHandler({
   },
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
-    const row = await fetchOne<TenantLifecycleRow>(
-      ctx.db.unsafeRaw(CANCEL_DESTRUCTION_TENANT_ROW_REASON),
-      tenantTable,
-      { id: tenantId },
-    );
+    const row = await fetchOne<TenantLifecycleRow>(ctx.db.unsafeRaw(), tenantTable, {
+      id: tenantId,
+    });
     if (!row) {
       return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));
     }

package/packages/bundled-features/src/tenant-lifecycle/handlers/request-destruction.write.ts

@@ -34,7 +34,7 @@ export const requestDestructionWrite = defineWriteHandler({
   },
   handler: async (event, ctx) => {
     const tenantId = event.user.tenantId;
-    const runner = ctx.db.unsafeRaw(REQUEST_DESTRUCTION_TENANT_ROW_REASON);
+    const runner = ctx.db.unsafeRaw();
     const row = await fetchOne<TenantLifecycleRow>(runner, tenantTable, { id: tenantId });
     if (!row) {
       return writeFailure(new UnprocessableError("tenant_not_found", { details: { tenantId } }));

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -399,7 +399,7 @@ export function createTierEngineFeature<
           const rawDb = ctx.systemDb
             ? ctx.systemDb.unsafeRaw(autoDefaultTierHookReason)
             : ctx.db && "unsafeRaw" in ctx.db
-              ? ctx.db.unsafeRaw(autoDefaultTierHookReason)
+              ? ctx.db.unsafeRaw()
               : undefined;
           // skip: defensive — inTransaction phase always sets db, but AppContext's
           // type makes it optional. Throwing would be overreach (lifecycle

package/packages/bundled-features/src/tier-engine/handlers/get-tenant-tier.query.ts

@@ -25,7 +25,7 @@ export const getTenantTierQuery = defineQueryHandler({
   },
   handler: async (query, ctx) => {
     const tenantId = query.payload.tenantId as TenantId; // @cast-boundary engine-bridge
-    const tdb = createTenantDb(ctx.db.unsafeRaw(GET_TENANT_TIER_REASON), tenantId, "system");
+    const tdb = createTenantDb(ctx.db.unsafeRaw(), tenantId, "system");
     const row = await fetchOne<TierAssignmentRow>(tdb, tierAssignmentTable, { tenantId });
     return row ?? null;
   },

package/packages/bundled-features/src/tier-engine/handlers/set-tenant-tier.write.ts

@@ -73,7 +73,7 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
     },
     handler: async (event, ctx) => {
       const tenantId = event.payload.tenantId as TenantId; // @cast-boundary engine-bridge
-      const rawDb = ctx.db.unsafeRaw(SET_TENANT_TIER_REASON);
+      const rawDb = ctx.db.unsafeRaw();
       const tdb = createTenantDb(rawDb, tenantId, "system");
       const systemUser = { ...event.user, tenantId };
       const tier = event.payload.tier;

package/packages/bundled-features/src/user-data-rights/feature.ts

@@ -588,9 +588,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         // Discriminator wird via handlerName="user-data-rights:run-export-
         // jobs" im Secret-Read-Audit erfasst.
         const exportUserId = ctx._userId ?? SYSTEM_USER_ID;
-        const exportDb = ctx.db.unsafeRaw(
-          RUN_EXPORT_JOBS_REASON,
-        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const exportDb =
+          ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const exportRegistry = ctx.registry;
         // JobContext carries ctx.meter (raw), not ctx.metrics — that bound
         // handle only exists on HandlerContext (built per write/query call
@@ -684,9 +683,8 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
         }
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
         const forgetUserId = ctx._userId ?? SYSTEM_USER_ID;
-        const forgetDb = ctx.db.unsafeRaw(
-          RUN_FORGET_CLEANUP_REASON,
-        ) as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+        const forgetDb =
+          ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
         const forgetRegistry = ctx.registry;
         const tenantModel = await resolveAppTenantModel({
           registry: forgetRegistry,

package/packages/bundled-features/src/user-data-rights/handlers/cancel-deletion.write.ts

@@ -61,7 +61,7 @@ export const cancelDeletionWrite = defineWriteHandler({
       return writeFailure(new UnprocessableError("grace_period_expired"));
     }
 
-    await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), event.user.id, {
+    await updateUserLifecycle(ctx.db.unsafeRaw(), event.user.id, {
       status: USER_STATUS.Active,
       gracePeriodEnd: null,
       // #354/1: closes the replay-after-cancel window — a still-TTL-valid email

package/packages/bundled-features/src/user-data-rights/handlers/confirm-deletion-by-token.write.ts

@@ -83,9 +83,7 @@ export function createConfirmDeletionByTokenHandler(opts: ConfirmDeletionByToken
             ctx,
             userId,
             () => resolveGracePeriod(ctx, event.user.tenantId),
-            ctx.db.unsafeRaw(
-              "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream",
-            ),
+            ctx.db.unsafeRaw(),
             { pendingDeletionRequestId: requestId },
           );
           if (!res.ok) return false;

package/packages/bundled-features/src/user-data-rights/handlers/download-by-job.query.ts

@@ -87,7 +87,7 @@ export const downloadByJobQuery = defineQueryHandler({
     // Wert (603/2).
     const auditIp = requestContext.get()?.ip ?? null;
     const auditUa = requestContext.get()?.userAgent ?? null;
-    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_JOB_REASON);
+    const runner = ctx.db.unsafeRaw();
 
     // Step 1-2: job-lookup + cross-user-isolation
     const jobRow = await fetchOne<JobRow>(runner, exportJobsTable, { id: jobId });

package/packages/bundled-features/src/user-data-rights/handlers/download-by-token.query.ts

@@ -92,7 +92,7 @@ export const downloadByTokenQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const T = getTemporal();
     const now = T.Now.instant();
-    const runner = ctx.db.unsafeRaw(DOWNLOAD_BY_TOKEN_REASON);
+    const runner = ctx.db.unsafeRaw();
 
     // Step 1: hash + lookup
     const hash = await hashDownloadToken(query.payload.token);

package/packages/bundled-features/src/user-data-rights/handlers/export-status.query.ts

@@ -50,7 +50,7 @@ export const exportStatusQuery = defineQueryHandler({
   },
   handler: async (query, ctx) => {
     const rows = await selectMany<ExportJobRow>(
-      ctx.db.unsafeRaw(EXPORT_STATUS_REASON),
+      ctx.db.unsafeRaw(),
       exportJobsTable,
       { userId: query.user.id },
       { limit: 1, orderBy: { col: "requestedAt", direction: "desc" } },

package/packages/bundled-features/src/user-data-rights/handlers/lift-restriction.write.ts

@@ -7,10 +7,6 @@ import { updateUserLifecycle } from "../lib/update-user-lifecycle.js";
 
 const LIFT_RESTRICTION_ESCAPE_HATCH_REASON =
   "checks the target user's membership in the admin's tenant and appends the user lifecycle status change on the SYSTEM_TENANT_ID user stream, both via DbRunner helpers outside the admin's own tenant scope.";
-const CHECK_TARGET_MEMBERSHIP_REASON =
-  "checks the target user's membership in the admin's tenant via the DbRunner helper";
-const APPEND_LIFECYCLE_EVENT_REASON =
-  "appends the user lifecycle event on the SYSTEM_TENANT_ID user stream";
 
 // POST /api/user/lift-restriction (S2.U6) — DSGVO Art. 18 Reverse.
 //
@@ -46,7 +42,7 @@ export const liftRestrictionWrite = defineWriteHandler({
     const targetUserId = event.payload.userId;
 
     const outside = await denyIfTargetOutsideAdminTenant(
-      ctx.db.unsafeRaw(CHECK_TARGET_MEMBERSHIP_REASON),
+      ctx.db.unsafeRaw(),
       event.user,
       targetUserId,
     );
@@ -73,7 +69,7 @@ export const liftRestrictionWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), targetUserId, {
+    await updateUserLifecycle(ctx.db.unsafeRaw(), targetUserId, {
       status: USER_STATUS.Active,
     });
 

package/packages/bundled-features/src/user-data-rights/handlers/my-audit-log.query.ts

@@ -64,7 +64,7 @@ export const myAuditLogQuery = defineQueryHandler({
       type: string;
       payload: Record<string, unknown>;
       created_at: unknown;
-    }>(ctx.db.unsafeRaw(MY_AUDIT_LOG_REASON), eventsTable, where, {
+    }>(ctx.db.unsafeRaw(), eventsTable, where, {
       orderBy: { col: "id", direction: "desc" },
       limit: p.limit,
     });

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion-by-email.write.ts

@@ -92,7 +92,7 @@ export function createRequestDeletionByEmailHandler(opts: RequestDeletionByEmail
       // user-Row landet und in die Token-HMAC-Purpose gefaltet wird. cancel
       // nullt sie → ein nach Cancel nachgespieltes Token verifiziert nicht mehr.
       const requestId = crypto.randomUUID();
-      await updateUserLifecycle(ctx.db.unsafeRaw(APPEND_LIFECYCLE_EVENT_REASON), userRow["id"], {
+      await updateUserLifecycle(ctx.db.unsafeRaw(), userRow["id"], {
         pendingDeletionRequestId: requestId,
       });
 

package/packages/bundled-features/src/user-data-rights/handlers/request-deletion.write.ts

@@ -65,7 +65,7 @@ export function createRequestDeletionHandler(opts: RequestDeletionOptions = {})
         ctx,
         event.user.id,
         () => resolveGracePeriod(ctx, event.user.tenantId),
-        ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
+        ctx.db.unsafeRaw(),
       );
       if (!res.ok) return writeFailure(res.error);
       const { gracePeriodEnd, userEmail, userLocale } = res;

package/packages/bundled-features/src/user-data-rights/handlers/request-export.write.ts

@@ -77,7 +77,7 @@ export const requestExportWrite = defineWriteHandler({
     const userId = event.user.id;
     const T = getTemporal();
     const now = T.Now.instant();
-    const exportJobRunner = ctx.db.unsafeRaw(REQUEST_EXPORT_REASON);
+    const exportJobRunner = ctx.db.unsafeRaw();
 
     // Pre-Check: exportJobRunner bypasses the TenantDb-Filter — the
     // TenantDb-Wrapper would hide cross-tenant jobs.

package/packages/bundled-features/src/user-data-rights/handlers/restrict-account.write.ts

@@ -70,9 +70,7 @@ export const restrictAccountWrite = defineWriteHandler({
         );
       }
       const outside = await denyIfTargetOutsideAdminTenant(
-        ctx.db.unsafeRaw(
-          "checks the target user's membership in the admin's tenant via the DbRunner helper",
-        ),
+        ctx.db.unsafeRaw(),
         event.user,
         targetUserId,
       );
@@ -107,11 +105,7 @@ export const restrictAccountWrite = defineWriteHandler({
       );
     }
 
-    await updateUserLifecycle(
-      ctx.db.unsafeRaw("appends the user lifecycle event on the SYSTEM_TENANT_ID user stream"),
-      targetUserId,
-      { status: USER_STATUS.Restricted },
-    );
+    await updateUserLifecycle(ctx.db.unsafeRaw(), targetUserId, { status: USER_STATUS.Restricted });
 
     // Cross-Feature: alle live sessions revoken — sonst koennte der User
     // mit existierendem JWT bis zur Token-Expiry weiter schreiben.

package/packages/bundled-features/src/user-data-rights/handlers/run-forget-cleanup.write.ts

@@ -48,7 +48,7 @@ export function createRunForgetCleanupHandler(opts: RunForgetCleanupOptions = {}
       }
 
       const T = getTemporal();
-      const runner = ctx.db.unsafeRaw(RUN_FORGET_CLEANUP_REASON);
+      const runner = ctx.db.unsafeRaw();
       // Operator-triggered forget must also erase binaries, not just rows —
       // it flips users to Deleted, after which the cron never re-processes
       // them, so a row-only delete here would permanently leak the binaries.

package/packages/bundled-features/src/user-data-rights/lib/update-user-lifecycle.ts

@@ -29,7 +29,7 @@ export type UpdateUserLifecycleOptions = {
   readonly expect?: Readonly<Record<string, string | number | boolean | null>>;
 };
 
-// `conn` is ctx.db.unsafeRaw(reason) (regular handlers) or the open tx
+// `conn` is ctx.db.unsafeRaw() (regular handlers) or the open tx
 // (forget-cleanup sub-tx) — keeps the event append atomic with the write.
 //
 // Returns `{ applied: false }` instead of throwing only when `options.expect`

package/packages/bundled-features/src/user-data-rights/run-forget-cleanup.ts

@@ -155,7 +155,7 @@ export interface RunForgetCleanupArgs {
 
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
-  // escapeHatch when its delete hook calls ctx.db.unsafeRaw(reason).
+  // escapeHatch when its delete hook calls ctx.db.unsafeRaw().
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }

package/packages/bundled-features/src/user-data-rights/run-user-export.ts

@@ -60,7 +60,7 @@ export interface RunUserExportArgs {
   readonly now: Instant;
   // fw#2914 — sourced from the owning job's ctx (_escapeHatchAuditSink,
   // systemUser.id); attributes+audits any EXT_USER_DATA usage's declared
-  // escapeHatch when its export hook calls ctx.db.unsafeRaw(reason).
+  // escapeHatch when its export hook calls ctx.db.unsafeRaw().
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly actor?: string;
 }

package/packages/bundled-features/src/workflow-runner/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.339.0",
+    "type": "breaking",
+    "title": "workflow-run stream stores a reference to the trigger event instead of its payload",
+    "detail": "`workflow.run-started` now holds `triggerEventRef: { eventId, aggregateId, version }` and no `triggerPayload`; the wait, waitForEvent and retry step events no longer embed it either. `workflow_run_pending` gets a `trigger_event_ref` column and the event-subscriber stops writing `trigger_payload`. `resume-run` loads the trigger and the awaited event through `ctx.loadAggregate` and fails the run with `trigger_event_unavailable` or `awaited_event_unavailable` when one is gone.",
+    "migration": "Own code that reads `triggerPayload` from `workflow.run-started` must read `triggerEventRef` and load the event with `ctx.loadAggregate(ref.aggregateId)`. Apps generate the migration for the new `workflow_run_pending.trigger_event_ref` column with `kumiko schema generate`. The step events `workflow.step.waiting`, `workflow.step.waiting-for-event` and `workflow.retry.scheduled` no longer carry `triggerPayload`; a custom resume loop that read it must load the trigger event through the `triggerEventRef` on its own run-started event (see `samples/recipes/workflow-engine/src/postgres-resume-loop.ts`). Stored run-started events and pending rows keep their old copy; this release rewrites no events, and runs started before it resume from that copy."
+  },
   {
     "version": "0.337.0",
     "type": "fix",

package/packages/bundled-features/src/workflow-runner/event-subscriber.ts

@@ -20,7 +20,7 @@
 // This subscriber never resumes a run itself (D3, workflow-resume-loop.md):
 // the MultiStreamApplyContext it runs in has no callFeature/runStepList
 // access, only unsafeAppendEvent/loadAggregate. It writes triggerEventType
-// + triggerPayload + wakeAt=now() onto the matching pending row(s); the
+// + triggerEventRef + wakeAt=now() onto the matching pending row(s); the
 // existing resume-due-runs job (Phase 2) picks the row up on its next
 // cron tick — the one resume path stays exactly the one Phase 2 built.
 
@@ -34,6 +34,7 @@ import type {
 import { evaluateEventMatch } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import type { TriggerEventRef } from "./runner.js";
 import { workflowRunPendingTable } from "./tables.js";
 
 type CandidateRow = {
@@ -87,7 +88,11 @@ const wakeupApply: MultiStreamApplyFn = async (event, tx) => {
       workflowRunPendingTable,
       {
         triggerEventType: event.type,
-        triggerPayload: event.payload,
+        triggerEventRef: {
+          eventId: event.id,
+          aggregateId: event.aggregateId,
+          version: event.version,
+        } satisfies TriggerEventRef,
         wakeAt: getTemporal().Now.instant().toString(),
       },
       { tenantId: row.tenantId, runId: row.runId, stepIndex: row.stepIndex },

package/packages/bundled-features/src/workflow-runner/event-trigger.ts

@@ -85,6 +85,11 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
             runId,
             workflow,
             triggerEvent,
+            triggerEventRef: {
+              eventId: event.id,
+              aggregateId: event.aggregateId,
+              version: event.version,
+            },
             ...(idempotencyKey && { idempotencyKey }),
             // @cast-boundary msp-to-handler-ctx — MultiStreamApplyContext only
             // exposes unsafeAppendEvent/loadAggregate, a subset of