@cosmicdrift/kumiko-samples 0.338.0 → 0.339.0

package/samples/apps/use-all-bundled/e2e-billing-gallery/server.ts

@@ -0,0 +1,82 @@
+// @runtime test
+//
+// Gallery boot: the stock dev app with consumer protection switched on. Only
+// this server mounts the billing catalog, the mock provider, the in-memory
+// mail transport, the webhook/termination routes and a host-based tenant
+// resolver; the shared dev app and its specs stay untouched.
+
+import {
+  createContractTerminationRoutes,
+  createSubscriptionWebhookRoute,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createDeliveryTestContext } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { seedTextBlock } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+import { runDevApp, type SeedFn } from "@cosmicdrift/kumiko-dev-server";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createE2eSeedRoutes } from "@cosmicdrift/kumiko-testing/e2e/seed-route";
+import { devAppOptions } from "../src/app/dev-app-options";
+import { GALLERY_TENANT_HOST, GALLERY_TERMS_SLUG } from "./gallery-constants";
+import {
+  createGalleryBillingFeature,
+  createGalleryEmailFeature,
+  galleryMailTransport,
+  galleryProviderFeature,
+  galleryScreensFeature,
+} from "./gallery-features";
+
+const port = Number.parseInt(process.env["PORT"] ?? "4196", 10);
+
+const BILLING_FEATURE = "billing-foundation";
+const EMAIL_FEATURE = "channel-email";
+
+const features = [
+  ...devAppOptions.features.map((feature) => {
+    if (feature.name === BILLING_FEATURE)
+      return createGalleryBillingFeature(`http://localhost:${port}`);
+    if (feature.name === EMAIL_FEATURE) return createGalleryEmailFeature();
+    return feature;
+  }),
+  galleryProviderFeature,
+  galleryScreensFeature,
+];
+
+const TERMS_TEXT: Readonly<Record<string, string>> = {
+  de: "## Allgemeine Geschäftsbedingungen\n\nDiese Bedingungen gelten für alle Verträge über die Plattform.",
+  en: "## Terms and conditions\n\nThese terms apply to every contract concluded through the platform.",
+};
+
+const seedTerms: SeedFn = async (stack) => {
+  for (const [locale, content] of Object.entries(TERMS_TEXT)) {
+    await seedTextBlock(stack.db, {
+      tenantId: SYSTEM_TENANT_ID,
+      slug: GALLERY_TERMS_SLUG,
+      locale,
+      title: "Terms",
+      content,
+    });
+  }
+};
+
+await runDevApp({
+  ...devAppOptions,
+  features,
+  seeds: [...(devAppOptions.seeds ?? []), seedTerms],
+  // The stock dev app pins every host to the SYSTEM tenant, which would hide
+  // platform mode: here only the named host resolves a tenant.
+  anonymousAccess: {
+    tenantResolver: (c) =>
+      c.req.header("host")?.startsWith(`${GALLERY_TENANT_HOST}:`) ? SYSTEM_TENANT_ID : null,
+    resolverTrust: "authoritative",
+    tenantExists: async (id) => id === SYSTEM_TENANT_ID,
+  },
+  extraContext: (deps) => ({
+    ...createDeliveryTestContext(deps),
+    templateResolver: createTemplateResolverApi(deps.db),
+  }),
+  extraRoutes: [
+    ...createE2eSeedRoutes({ mailOutbox: galleryMailTransport }),
+    createSubscriptionWebhookRoute(),
+    ...createContractTerminationRoutes(),
+  ],
+});

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 76,
+  "featureCount": 80,
   "features": [
     {
       "name": "admin-shell",
@@ -352,6 +352,33 @@
       "secrets": [],
       "writeHandlers": []
     },
+    {
+      "name": "channel-discord",
+      "description": "Posts delivery notifications to a Discord webhook, registered as the `discord` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { discord: \"<connection name>\" } })`. The webhook URL is a tenant secret under `channel-discord:webhooks.<connection name>`; only the connection name is logged. Mentions are disabled and content is cut to 2000 characters. Requires `delivery` and `secrets`. Host allowlist (discord.com, discordapp.com, path /api/webhooks/), https-only and the request timeout are app options of `createChannelDiscordFeature(opts)`, never tenant config.",
+      "toggleableDefault": null,
+      "requires": [
+        "delivery",
+        "secrets"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "deliveryChannel",
+          "entityName": "discord"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Discord Channel",
+        "category": "notifications",
+        "recommended": false
+      }
+    },
     {
       "name": "channel-email",
       "description": "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.",
@@ -433,6 +460,94 @@
         "recommended": false
       }
     },
+    {
+      "name": "channel-slack",
+      "description": "Posts delivery notifications to a Slack incoming webhook, registered as the `slack` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { slack: \"<connection name>\" } })`. The webhook URL is a tenant secret under `channel-slack:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (hooks.slack.com), https-only and the request timeout are app options of `createChannelSlackFeature(opts)`, never tenant config.",
+      "toggleableDefault": null,
+      "requires": [
+        "delivery",
+        "secrets"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "deliveryChannel",
+          "entityName": "slack"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Slack Channel",
+        "category": "notifications",
+        "recommended": false
+      }
+    },
+    {
+      "name": "channel-teams",
+      "description": "Posts delivery notifications to a Microsoft Teams webhook (Workflows or connector) as an Adaptive Card, registered as the `teams` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { teams: \"<connection name>\" } })`. The webhook URL is a tenant secret under `channel-teams:webhooks.<connection name>`; only the connection name is logged. Requires `delivery` and `secrets`. Host allowlist (.webhook.office.com, .logic.azure.com, .powerplatform.com), https-only and the request timeout are app options of `createChannelTeamsFeature(opts)`, never tenant config.",
+      "toggleableDefault": null,
+      "requires": [
+        "delivery",
+        "secrets"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "deliveryChannel",
+          "entityName": "teams"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Microsoft Teams Channel",
+        "category": "notifications",
+        "recommended": false
+      }
+    },
+    {
+      "name": "channel-telegram",
+      "description": "Sends delivery notifications through the Telegram Bot API (`sendMessage`, plain text), registered as the `telegram` channel in the delivery system. Tenant-owned chat target: reach it only via `ctx.notify(type, { route: { telegram: \"<chat id or @channel>\" } })`. The bot token is the tenant secret `channel-telegram:secret:bot-token`; the token never reaches logs or delivery attempts. Requires `delivery` and `secrets`. The API base URL and request timeout are app options of `createChannelTelegramFeature(opts)`, never tenant config.",
+      "toggleableDefault": null,
+      "requires": [
+        "delivery",
+        "secrets"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "deliveryChannel",
+          "entityName": "telegram"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [
+        {
+          "qualifiedName": "channel-telegram:secret:bot-token",
+          "scope": "tenant",
+          "label": "Telegram bot token",
+          "hint": "Token from @BotFather. Used for every Telegram chat the tenant addresses via route: { telegram: \"<chat id>\" }."
+        }
+      ],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Telegram Channel",
+        "category": "notifications",
+        "recommended": false
+      }
+    },
     {
       "name": "collection-labels",
       "description": "Nav labels for the content collections mounted by this sample app.",
@@ -2959,5 +3074,35 @@
         "recommended": false
       }
     }
+  ],
+  "systemEvents": [
+    {
+      "name": "kumiko:system:workflow.retry.scheduled",
+      "version": 1
+    },
+    {
+      "name": "kumiko:system:workflow.run-completed",
+      "version": 1
+    },
+    {
+      "name": "kumiko:system:workflow.run-failed",
+      "version": 1
+    },
+    {
+      "name": "kumiko:system:workflow.run-started",
+      "version": 1
+    },
+    {
+      "name": "kumiko:system:workflow.step.resumed",
+      "version": 1
+    },
+    {
+      "name": "kumiko:system:workflow.step.waiting",
+      "version": 1
+    },
+    {
+      "name": "kumiko:system:workflow.step.waiting-for-event",
+      "version": 1
+    }
   ]
 }

package/samples/apps/use-all-bundled/package.json

@@ -9,6 +9,7 @@
     "boot:bundled": "KUMIKO_DRY_RUN_ENV=boot bun dist-server/server.js",
     "dev": "PORT=4186 bun --env-file=../../../.env run src/app/server.ts",
     "screenshots": "bun x playwright test e2e/screenshots.spec.ts --config=playwright.config.ts",
+    "billing-gallery": "bun x playwright test --config=playwright.billing-gallery.config.ts",
     "e2e": "bun x playwright test e2e/mfa-login.spec.ts --config=playwright.config.ts",
     "gen:manifest": "bun run scripts/gen-feature-manifest.ts",
     "gen:sample-index": "bun run scripts/gen-sample-index.ts"

package/samples/apps/use-all-bundled/playwright.billing-gallery.config.ts

@@ -0,0 +1,14 @@
+// @runtime test
+// Review gallery for the consent/termination flows. Not part of the CI e2e
+// list (.github/workflows/ci.yml) and gated by SCREENSHOT_DIR like every other
+// screenshot spec: run it by hand, see the `billing-gallery` script.
+import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
+import { E2E_PORTS } from "../../e2e/e2e-ports";
+
+export default defineAppE2eConfig({
+  port: E2E_PORTS["framework/use-all-bundled-billing-gallery"],
+  env: PLAYWRIGHT_DEMO_ENV,
+  locale: "de",
+  testDir: "./e2e-billing-gallery",
+  serverEntry: "e2e-billing-gallery/server.ts",
+});

package/samples/apps/use-all-bundled/schema/generate.ts

@@ -445,6 +445,26 @@ const FEATURE_IMPORT_REGISTRY: Record<string, FeatureImport> = {
     path: "@cosmicdrift/kumiko-bundled-features/channel-push",
     factory: "createChannelPushFeature",
   },
+  "channel-slack": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-bundled-features/channel-slack",
+    factory: "createChannelSlackFeature",
+  },
+  "channel-discord": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-bundled-features/channel-discord",
+    factory: "createChannelDiscordFeature",
+  },
+  "channel-teams": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-bundled-features/channel-teams",
+    factory: "createChannelTeamsFeature",
+  },
+  "channel-telegram": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-bundled-features/channel-telegram",
+    factory: "createChannelTelegramFeature",
+  },
   readiness: {
     kind: "named",
     path: "@cosmicdrift/kumiko-bundled-features/readiness",

package/samples/apps/use-all-bundled/scripts/gen-feature-manifest.ts

@@ -36,6 +36,7 @@ export type {
   ManifestExtension,
   ManifestFeature,
   ManifestSecret,
+  ManifestSystemEvent,
 } from "@cosmicdrift/kumiko-framework/engine";
 export { serializeManifest };
 

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -22,6 +22,7 @@ import { authMfaUserDataFeature } from "@cosmicdrift/kumiko-bundled-features/aut
 import { billingFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { capCounterFeature } from "@cosmicdrift/kumiko-bundled-features/cap-counter";
 import { createCapOverviewFeature } from "@cosmicdrift/kumiko-bundled-features/cap-overview";
+import { createChannelDiscordFeature } from "@cosmicdrift/kumiko-bundled-features/channel-discord";
 import {
   createChannelEmailFeature,
   type EmailTransport,
@@ -31,6 +32,9 @@ import {
   createChannelPushFeature,
   type PushTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-push";
+import { createChannelSlackFeature } from "@cosmicdrift/kumiko-bundled-features/channel-slack";
+import { createChannelTeamsFeature } from "@cosmicdrift/kumiko-bundled-features/channel-teams";
+import { createChannelTelegramFeature } from "@cosmicdrift/kumiko-bundled-features/channel-telegram";
 import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
 import { complianceProfilesOpsFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles-ops";
 import { customFieldsFeature } from "@cosmicdrift/kumiko-bundled-features/custom-fields";
@@ -171,6 +175,12 @@ export const APP_FEATURES = [
     transport: stubPushTransport,
     resolveToken: async () => "smoke-push-token",
   }),
+  // Chat channels are route-only and read their webhook URL / bot token from the
+  // tenant's secrets at send time, so the smoke app needs no credentials here.
+  createChannelSlackFeature(),
+  createChannelDiscordFeature(),
+  createChannelTeamsFeature(),
+  createChannelTelegramFeature(),
 
   // mail (foundation before transport)
   mailFoundationFeature,

package/samples/apps/use-all-bundled/tsconfig.json

@@ -26,6 +26,7 @@
     "scripts",
     "kumiko.config.ts",
     "e2e",
+    "e2e-billing-gallery",
     "../../e2e"
   ]
 }

package/samples/recipes/chat-channels/README.md

@@ -0,0 +1,19 @@
+# Sample: Chat Channels
+
+Shows how a feature posts to a tenant's Slack channel without ever handling the webhook URL.
+
+## What you learn here
+
+**Route-only targets:** Chat targets belong to the tenant, not to a user. A handler addresses one with `ctx.notify(type, { route: { slack: "ops" } })`; `"ops"` is a connection name. The chat channels declare no `resolve`, so a normal `to: userId` notification skips them without a log row.
+
+**Secrets for the URL:** The tenant stores the webhook URL as a secret under `channel-slack:webhooks.<connection name>` (namespace declared by the channel, written through `secrets:write:set`). The `delivery.send` job reads it with an audit entry (`channel-slack:send`), posts the message and records only the connection name and an outcome code (`http_500`, `timeout`, `redirect_blocked`, `host_not_allowed`, `missing_credentials`, `invalid_address`).
+
+**App-level hardening:** Each channel only talks to its provider's hosts, over https, without following redirects. `allowedHosts`, `requireHttps` and `timeoutMs` are options of `createChannelSlackFeature(opts)`. Tenants cannot change them; the test uses them to point at a local stub.
+
+The same shape works for `channel-discord`, `channel-teams` (connection name + webhook secret) and `channel-telegram` (one `botToken` secret, the address is the chat id).
+
+## Run
+
+```bash
+bun test --config=bunfig.integration.toml --timeout=15000 samples/recipes/chat-channels
+```

package/samples/recipes/chat-channels/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-chat-channels",
+  "description": "Chat channels. Delivery notifications to Slack, minus the browser tab.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/chat-channels/src/feature.ts

@@ -0,0 +1,40 @@
+// Chat Channels Sample
+//
+// A handler tells the tenant's ops chat about something. Chat targets belong to
+// the tenant, not to a user, so the feature addresses one by connection name via
+// `route` — it never sees the webhook URL. The tenant stores that URL as a secret
+// under `channel-slack:webhooks.<connection name>`.
+
+import {
+  defineFeature,
+  defineWriteHandler,
+  type NotifyFn,
+  qn,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+
+export const OPS_ANNOUNCEMENT_TYPE = qn("ops", "notify", "announcement");
+
+export const opsFeature = defineFeature("ops", (r) => {
+  r.requires("delivery");
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "announce",
+      schema: z.object({
+        connection: z.string(),
+        title: z.string().min(1),
+        body: z.string().optional(),
+      }),
+      access: { roles: ["Admin"] },
+      handler: async (event, ctx) => {
+        const notify = ctx.notify as NotifyFn;
+        await notify(OPS_ANNOUNCEMENT_TYPE, {
+          route: { slack: event.payload.connection },
+          data: { title: event.payload.title, body: event.payload.body },
+        });
+        return { isSuccess: true, data: { announced: true } };
+      },
+    }),
+  );
+});

package/samples/recipes/public-share-token/src/feature.ts

@@ -169,7 +169,7 @@ export const shareByTokenQuery = defineQueryHandler({
   },
   handler: async (query, ctx) => {
     const hash = await hashToken(query.payload.token);
-    const row = await fetchOne<ShareLinkRow>(ctx.db.unsafeRaw(SHARE_BY_TOKEN_REASON), table, {
+    const row = await fetchOne<ShareLinkRow>(ctx.db.unsafeRaw(), table, {
       tokenHash: hash,
     });
 

package/samples/recipes/workflow-engine/src/event-trigger.ts

@@ -60,6 +60,11 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
             runId,
             workflow,
             triggerEvent,
+            triggerEventRef: {
+              eventId: event.id,
+              aggregateId: event.aggregateId,
+              version: event.version,
+            },
             ...(idempotencyKey && { idempotencyKey }),
             handlerCtx: ctx as never,
           });

package/samples/recipes/workflow-engine/src/postgres-resume-loop.ts

@@ -4,19 +4,23 @@
 //   1. createSuspendedRunFetcher(db, workflowRegistry) — Postgres-backed
 //   2. createInMemorySuspendedRunFetcher(runs) — for unit tests
 //
-// The fetcher extracts the trigger-event snapshot + Q7 fingerprint directly
-// from the suspension event payload (the wait/waitForEvent/retry steps
-// stamp them there), avoiding a per-run lookup against run.started.
+// The fetcher reads the Q7 fingerprint from the suspension event payload and
+// re-loads the trigger event from the event store through the
+// triggerEventRef on the run's own run.started event (no payload copy lives
+// on the run stream).
 
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
-import type { WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type { TenantId, WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
   WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
   WORKFLOW_WAITING_FOR_EVENT_TYPE,
   WORKFLOW_WAITING_TYPE,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
 import { selectExpiredSuspensionEvents } from "./db/queries/suspended-runs";
 import type { SuspendableRun } from "./resume-loop";
+import type { TriggerEventRef } from "./workflow-runner";
 
 export type WorkflowRegistry = ReadonlyMap<string, WorkflowDefinition>;
 
@@ -26,6 +30,42 @@ const SUSPEND_EVENT_TYPES = [
   WORKFLOW_RETRY_SCHEDULED_TYPE,
 ] as const;
 
+function isTriggerEventRef(value: unknown): value is TriggerEventRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "eventId" in value &&
+    typeof value.eventId === "string" &&
+    "aggregateId" in value &&
+    typeof value.aggregateId === "string" &&
+    "version" in value &&
+    typeof value.version === "number"
+  );
+}
+
+// undefined when the run has no usable reference or the trigger event can no
+// longer be loaded (archived stream): the run is skipped, never resumed on
+// made-up data.
+async function loadTriggerEvent(
+  db: DbRunner,
+  tenantId: TenantId,
+  runId: string,
+): Promise<{ aggregateId: string; type: string; payload: unknown } | undefined> {
+  const runEvents = await loadAggregate(db, runId, tenantId);
+  const started = runEvents.find((e) => e.type === WORKFLOW_RUN_STARTED_TYPE);
+  if (!started) return undefined;
+  const ref = started.payload["triggerEventRef"];
+  if (ref === undefined) {
+    // Cron run: the synthetic trigger event was never stored.
+    return { aggregateId: runId, type: String(started.payload["triggerEventType"]), payload: {} };
+  }
+  if (!isTriggerEventRef(ref)) return undefined;
+  const source = (await loadAggregate(db, ref.aggregateId, tenantId)).find(
+    (e) => e.id === ref.eventId,
+  );
+  return source && { aggregateId: source.aggregateId, type: source.type, payload: source.payload };
+}
+
 /**
  * Postgres-backed fetcher. Queries kumiko_events for suspension events with
  * expired wakeAt/timeoutAt timestamps. The resume-loop applies the Q7
@@ -64,11 +104,12 @@ export function createSuspendedRunFetcher(
       const wakeAt = (payload["wakeAt"] ?? payload["timeoutAt"]) as string | undefined;
       if (!wakeAt) continue;
 
-      const triggerEvent = {
-        aggregateId: (payload["triggerAggregateId"] as string | undefined) ?? aggregateId,
-        type: (payload["triggerEventType"] as string | undefined) ?? "kumiko:system:resume",
-        payload: payload["triggerPayload"] ?? {},
-      };
+      const triggerEvent = await loadTriggerEvent(
+        db,
+        (row["tenantId"] ?? row["tenant_id"]) as TenantId, // @cast-boundary raw-sql-row
+        aggregateId,
+      );
+      if (!triggerEvent) continue;
 
       results.push({
         runId: aggregateId,

package/samples/recipes/workflow-engine/src/workflow-runner.ts

@@ -26,10 +26,19 @@ import {
   WORKFLOW_RUN_STARTED_TYPE,
 } from "@cosmicdrift/kumiko-framework/engine";
 
+// Reference into the event store; the run stream never copies a foreign
+// payload, so erasing the source event also covers the workflow.
+export type TriggerEventRef = {
+  readonly eventId: string;
+  readonly aggregateId: string;
+  readonly version: number;
+};
+
 export type WorkflowRunStartedPayload = {
   readonly workflowName: string;
   readonly triggerEventType: string;
-  readonly triggerPayload: unknown;
+  // Absent for cron runs: their synthetic trigger event has no stored source.
+  readonly triggerEventRef?: TriggerEventRef;
   readonly definitionFingerprint: string;
   readonly idempotencyKey?: string;
 };
@@ -47,6 +56,7 @@ export async function startAndRunWorkflow(args: {
   readonly runId: string;
   readonly workflow: WorkflowDefinition;
   readonly triggerEvent: WriteEvent;
+  readonly triggerEventRef?: TriggerEventRef;
   readonly idempotencyKey?: string;
   readonly handlerCtx: HandlerContext;
 }): Promise<{ readonly outcome: "completed" | "suspended" }> {
@@ -55,7 +65,7 @@ export async function startAndRunWorkflow(args: {
   const startedPayload: WorkflowRunStartedPayload = {
     workflowName: args.workflow.name,
     triggerEventType: args.triggerEvent.type,
-    triggerPayload: args.triggerEvent.payload,
+    ...(args.triggerEventRef && { triggerEventRef: args.triggerEventRef }),
     definitionFingerprint: fingerprint,
     ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
   };