@cosmicdrift/kumiko-samples 0.338.0 → 0.339.0

package/packages/bundled-features/src/workflow-runner/handlers/resume-run.write.ts

@@ -16,16 +16,19 @@
 //      otherwise (wait already wrote its effect; resume past it).
 //
 // The run's ORIGINAL trigger event (the one that started the whole run) is
-// always recovered from the run's own WORKFLOW_RUN_STARTED_TYPE event,
-// never from the pending row — that event always carries it (see
-// WorkflowRunStartedPayload in ./runner). The pending row's own
-// triggerEventType/triggerPayload columns are a DIFFERENT thing: for a
-// waitForEvent suspension they hold the AWAITED event the Phase 3b
+// always re-read from the event store via the triggerEventRef on the run's
+// own WORKFLOW_RUN_STARTED_TYPE event, never from the pending row (see
+// WorkflowRunStartedPayload in ./runner). Neither the run stream nor the
+// pending row holds a copy of a foreign payload, so an erased source event
+// shows up here in its shredded form, and an unloadable one (archived
+// stream) fails the run. The pending row's own
+// triggerEventType/triggerEventRef columns are a DIFFERENT thing: for a
+// waitForEvent suspension they point at the AWAITED event the Phase 3b
 // event-subscriber matched (NULL until then, and NULL forever on a
-// timeout-without-a-match). That payload becomes the resumed pipeline's
-// result for the skipped waitForEvent step itself (see resultKey on
-// steps/wait-for-event.ts) — pre-seeded into stepsAcc below so a
-// subsequent step's resolver can read `ctx.steps[awaits.someKey]`.
+// timeout-without-a-match). That event's payload becomes the resumed
+// pipeline's result for the skipped waitForEvent step itself (see
+// resultKey on steps/wait-for-event.ts) — pre-seeded into stepsAcc below so
+// a subsequent step's resolver can read `ctx.steps[awaits.someKey]`.
 
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -53,9 +56,9 @@ import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import * as z from "zod";
 import {
   isResumableSuspension,
+  type TriggerEventRef,
   type WorkflowRunCompletedPayload,
   type WorkflowRunFailedPayload,
-  type WorkflowRunStartedPayload,
   WorkflowSuspensionUnsupportedError,
 } from "../runner.js";
 import { workflowRunPendingTable } from "../tables.js";
@@ -182,50 +185,218 @@ function isRunAlreadySettled(
   });
 }
 
-function recoverTriggerEvent(
-  runEvents: Awaited<ReturnType<HandlerContext["loadAggregate"]>>,
+type LoadedEvents = Awaited<ReturnType<HandlerContext["loadAggregate"]>>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isTriggerEventRef(value: unknown): value is TriggerEventRef {
+  return (
+    isRecord(value) &&
+    typeof value["eventId"] === "string" &&
+    typeof value["aggregateId"] === "string" &&
+    typeof value["version"] === "number"
+  );
+}
+
+// run-started events written before the reference existed carry a copy of the
+// trigger payload instead; they stay readable for runs still in flight.
+type TriggerSource =
+  | { readonly kind: "ref"; readonly eventType: string; readonly ref: TriggerEventRef }
+  | { readonly kind: "legacy-copy"; readonly eventType: string; readonly payload: unknown };
+
+function readTriggerSource(startedPayload: unknown): TriggerSource | null {
+  if (!isRecord(startedPayload) || typeof startedPayload["triggerEventType"] !== "string") {
+    return null;
+  }
+  const eventType = startedPayload["triggerEventType"];
+  const ref = startedPayload["triggerEventRef"];
+  if (isTriggerEventRef(ref)) {
+    return { kind: "ref", eventType, ref };
+  }
+  if ("triggerPayload" in startedPayload) {
+    return { kind: "legacy-copy", eventType, payload: startedPayload["triggerPayload"] };
+  }
+  return null;
+}
+
+async function loadReferencedEvent(ctx: HandlerContext, ref: TriggerEventRef) {
+  const events = await ctx.loadAggregate(ref.aggregateId);
+  return events.find((e) => e.id === ref.eventId);
+}
+
+type RecoveredTrigger =
+  | { readonly event: WriteEvent; readonly unavailable: false }
+  | { readonly event: null; readonly unavailable: true };
+
+async function recoverTriggerEvent(
+  ctx: HandlerContext,
+  runEvents: LoadedEvents,
   runId: string,
   user: WriteEvent["user"],
-): WriteEvent {
+): Promise<RecoveredTrigger> {
   const started = runEvents.find((e) => e.type === WORKFLOW_RUN_STARTED_TYPE);
   if (!started) {
     throw new InternalError({
       message: `workflow-runner:write:resume-run: run ${runId} has no ${WORKFLOW_RUN_STARTED_TYPE} event — cannot recover its trigger event.`,
     });
   }
-  const startedPayload = started.payload as WorkflowRunStartedPayload; // @cast-boundary event-store-payload
-  const triggerEvent: WriteEvent = {
-    type: startedPayload.triggerEventType,
-    payload: startedPayload.triggerPayload,
-    user,
+  const source = readTriggerSource(started.payload);
+  if (!source) {
+    throw new InternalError({
+      message: `workflow-runner:write:resume-run: run ${runId} has a malformed ${WORKFLOW_RUN_STARTED_TYPE} event — neither triggerEventRef nor a legacy triggerPayload.`,
+    });
+  }
+  if (source.kind === "legacy-copy") {
+    return {
+      event: { type: source.eventType, payload: source.payload, user },
+      unavailable: false,
+    };
+  }
+  const triggerEvent = await loadReferencedEvent(ctx, source.ref);
+  if (!triggerEvent) {
+    return { event: null, unavailable: true };
+  }
+  return {
+    event: { type: source.eventType, payload: triggerEvent.payload, user },
+    unavailable: false,
   };
-  return triggerEvent;
+}
+
+type PendingTriggerColumns = {
+  readonly triggerEventRef: unknown | null;
+  readonly triggerPayload: unknown | null;
+};
+
+type AwaitedPayload =
+  | { readonly unavailable: false; readonly payload: unknown }
+  | { readonly unavailable: true };
+
+// NULL ref + NULL payload = timeout without a match: the step result stays
+// undefined, same as before. A matched row whose event can no longer be loaded
+// is NOT folded into that case: a later step could not tell "nothing arrived"
+// from "arrived but gone" and would run on missing data, so the run fails
+// instead. Rows matched before the reference existed still carry the copy.
+async function loadAwaitedPayload(
+  ctx: HandlerContext,
+  pending: PendingTriggerColumns,
+): Promise<AwaitedPayload> {
+  if (!isTriggerEventRef(pending.triggerEventRef)) {
+    return { unavailable: false, payload: pending.triggerPayload ?? undefined };
+  }
+  const awaited = await loadReferencedEvent(ctx, pending.triggerEventRef);
+  return awaited ? { unavailable: false, payload: awaited.payload } : { unavailable: true };
 }
 
 // The suspended waitForEvent step itself is skipped on resume
 // (resumeFrom = stepIndex + 1) — its run() never re-executes, so its
 // resultKey (args.event, see steps/wait-for-event.ts) never gets
-// populated by the normal runStepList loop. Seed it here from the
-// pending row's own triggerPayload so a subsequent step's resolver
-// sees the matched event via `ctx.steps[awaits.someKey]`, same as any
-// other step result. NULL on a timeout-without-a-match — a later
-// resolver reading it just sees `undefined`, no special-casing needed.
+// populated by the normal runStepList loop. Seed it here from the awaited
+// event's payload so a subsequent step's resolver sees the matched event via
+// `ctx.steps[awaits.someKey]`, same as any other step result.
 function seedResumedStepResults(
-  pending: { suspensionEventType: string; triggerPayload: unknown | null },
+  suspensionEventType: string,
+  awaitedPayload: unknown,
   steps: readonly StepInstance[],
   stepIndex: number,
 ): Record<string, unknown> {
   const stepsAcc: Record<string, unknown> = {};
-  if (pending.suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE) {
+  if (suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE) {
     const suspendedStep = steps[stepIndex];
     const key = suspendedStep && getStep(suspendedStep.kind)?.resultKey?.(suspendedStep.args);
     if (key !== undefined) {
-      stepsAcc[key] = pending.triggerPayload;
+      stepsAcc[key] = awaitedPayload;
     }
   }
   return stepsAcc;
 }
 
+type ResumedPipelineInput = {
+  readonly workflow: WorkflowDefinition;
+  readonly workflowName: string;
+  readonly runId: string;
+  readonly stepIndex: number;
+  readonly resumeFrom: number;
+  readonly triggerEvent: WriteEvent;
+  readonly awaitedPayload: unknown;
+  readonly pending: {
+    readonly suspensionEventType: string;
+    readonly retryAttempt: number | null;
+    readonly definitionFingerprint: string | null;
+  };
+};
+
+async function runResumedPipeline(ctx: HandlerContext, input: ResumedPipelineInput) {
+  const {
+    workflow,
+    workflowName,
+    runId,
+    stepIndex,
+    resumeFrom,
+    triggerEvent,
+    awaitedPayload,
+    pending,
+  } = input;
+  try {
+    const steps = buildPipelineSteps(workflow.pipelineDef, triggerEvent);
+    const workflowCtx = {
+      runId,
+      workflowName,
+      stepIndex,
+      definitionFingerprint: pending.definitionFingerprint ?? undefined,
+      ...(pending.retryAttempt !== null && { retryAttempt: pending.retryAttempt + 1 }),
+    };
+
+    const stepsAcc = seedResumedStepResults(
+      pending.suspensionEventType,
+      awaitedPayload,
+      steps,
+      stepIndex,
+    );
+
+    const outcome = await runStepList(
+      steps,
+      triggerEvent,
+      ctx,
+      stepsAcc,
+      {},
+      workflowCtx,
+      resumeFrom,
+    );
+
+    if (outcome.kind === "suspended") {
+      if (!isResumableSuspension(steps, outcome.stepIndex)) {
+        throw new WorkflowSuspensionUnsupportedError(workflowName, outcome.stepIndex);
+      }
+      // Another suspension further down the pipeline — pending-projection.ts
+      // already materialised the new row; nothing more to do this pass.
+      return { isSuccess: true as const, data: { outcome: "suspended" as const } };
+    }
+
+    const completedPayload: WorkflowRunCompletedPayload = {
+      workflowName,
+      stepIndex: steps.length,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: runId,
+      aggregateType: WORKFLOW_AGGREGATE_TYPE,
+      type: WORKFLOW_RUN_COMPLETED_TYPE,
+      payload: completedPayload,
+    });
+    return { isSuccess: true as const, data: { outcome: "completed" as const } };
+  } catch (error) {
+    log.warn("workflow run failed", { runId, workflowName, stepIndex, error: String(error) });
+    const failedPayload: WorkflowRunFailedPayload = {
+      workflowName,
+      stepIndex,
+      error: describeWorkflowStepError(error),
+    };
+    await appendRunFailed(ctx, runId, failedPayload);
+    return { isSuccess: true as const, data: { outcome: "failed" as const } };
+  }
+}
+
 export const resumeRunHandler: WriteHandlerDef = {
   name: "resume-run",
   agent: { expose: false },
@@ -248,6 +419,7 @@ export const resumeRunHandler: WriteHandlerDef = {
       suspensionEventType: string;
       retryAttempt: number | null;
       definitionFingerprint: string | null;
+      triggerEventRef: unknown | null;
       triggerPayload: unknown | null;
     }>(db, workflowRunPendingTable, { runId, stepIndex, tenantId });
 
@@ -297,62 +469,44 @@ export const resumeRunHandler: WriteHandlerDef = {
       return { isSuccess: true, data: { outcome: "already-resumed" as const } };
     }
 
-    const triggerEvent = recoverTriggerEvent(runEvents, runId, event.user);
-
-    const resumeFrom =
-      pending.suspensionEventType === WORKFLOW_RETRY_SCHEDULED_TYPE ? stepIndex : stepIndex + 1;
-
-    try {
-      const steps = buildPipelineSteps(workflow.pipelineDef, triggerEvent);
-      const workflowCtx = {
-        runId,
+    const recovered = await recoverTriggerEvent(ctx, runEvents, runId, event.user);
+    if (recovered.unavailable) {
+      await appendRunFailed(ctx, runId, {
         workflowName,
         stepIndex,
-        definitionFingerprint: pending.definitionFingerprint ?? undefined,
-        ...(pending.retryAttempt !== null && { retryAttempt: pending.retryAttempt + 1 }),
-      };
-
-      const stepsAcc = seedResumedStepResults(pending, steps, stepIndex);
-
-      const outcome = await runStepList(
-        steps,
-        triggerEvent,
-        ctx,
-        stepsAcc,
-        {},
-        workflowCtx,
-        resumeFrom,
-      );
-
-      if (outcome.kind === "suspended") {
-        if (!isResumableSuspension(steps, outcome.stepIndex)) {
-          throw new WorkflowSuspensionUnsupportedError(workflowName, outcome.stepIndex);
-        }
-        // Another suspension further down the pipeline — pending-projection.ts
-        // already materialised the new row; nothing more to do this pass.
-        return { isSuccess: true, data: { outcome: "suspended" as const } };
-      }
-
-      const completedPayload: WorkflowRunCompletedPayload = {
-        workflowName,
-        stepIndex: steps.length,
-      };
-      await ctx.unsafeAppendEvent({
-        aggregateId: runId,
-        aggregateType: WORKFLOW_AGGREGATE_TYPE,
-        type: WORKFLOW_RUN_COMPLETED_TYPE,
-        payload: completedPayload,
+        error: `Trigger event of run ${runId} is no longer available — cannot resume.`,
+        reason: "trigger_event_unavailable",
       });
-      return { isSuccess: true, data: { outcome: "completed" as const } };
-    } catch (error) {
-      log.warn("workflow run failed", { runId, workflowName, stepIndex, error: String(error) });
-      const failedPayload: WorkflowRunFailedPayload = {
+      return { isSuccess: true, data: { outcome: "failed" as const } };
+    }
+    const triggerEvent = recovered.event;
+
+    const awaited =
+      pending.suspensionEventType === WORKFLOW_WAITING_FOR_EVENT_TYPE
+        ? await loadAwaitedPayload(ctx, pending)
+        : ({ unavailable: false, payload: undefined } as const);
+    if (awaited.unavailable) {
+      await appendRunFailed(ctx, runId, {
         workflowName,
         stepIndex,
-        error: describeWorkflowStepError(error),
-      };
-      await appendRunFailed(ctx, runId, failedPayload);
+        error: `Awaited event of run ${runId} is no longer available — cannot resume.`,
+        reason: "awaited_event_unavailable",
+      });
       return { isSuccess: true, data: { outcome: "failed" as const } };
     }
+
+    const resumeFrom =
+      pending.suspensionEventType === WORKFLOW_RETRY_SCHEDULED_TYPE ? stepIndex : stepIndex + 1;
+
+    return runResumedPipeline(ctx, {
+      workflow,
+      workflowName,
+      runId,
+      stepIndex,
+      resumeFrom,
+      triggerEvent,
+      awaitedPayload: awaited.payload,
+      pending,
+    });
   },
 };

package/packages/bundled-features/src/workflow-runner/pending-projection.ts

@@ -84,6 +84,7 @@ async function upsertPending(tx: DbRunner, row: PendingRow): Promise<void> {
       // Phase 3's event-subscriber writes these when the awaited event
       // arrives — Phase 1 never touches them, insert or update.
       triggerEventType: null,
+      triggerEventRef: null,
       triggerPayload: null,
     },
     { conflictKeys: ["tenantId", "runId", "stepIndex"] },

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

@@ -35,10 +35,19 @@ export function isResumableSuspension(steps: readonly StepInstance[], stepIndex:
   return RESUMABLE_STEP_KINDS.has(steps[stepIndex]?.kind ?? "");
 }
 
+// Points at the trigger event in the event store. The run stream never holds a
+// copy of a foreign payload: erasing or archiving the source event must also
+// cover the workflow, so a resume re-reads the event through this reference.
+export type TriggerEventRef = {
+  readonly eventId: string;
+  readonly aggregateId: string;
+  readonly version: number;
+};
+
 export type WorkflowRunStartedPayload = {
   readonly workflowName: string;
   readonly triggerEventType: string;
-  readonly triggerPayload: unknown;
+  readonly triggerEventRef: TriggerEventRef;
   readonly definitionFingerprint: string;
   readonly idempotencyKey?: string;
 };
@@ -91,6 +100,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" }> {
@@ -99,7 +109,7 @@ export async function startAndRunWorkflow(args: {
   const startedPayload: WorkflowRunStartedPayload = {
     workflowName: args.workflow.name,
     triggerEventType: args.triggerEvent.type,
-    triggerPayload: args.triggerEvent.payload,
+    triggerEventRef: args.triggerEventRef,
     definitionFingerprint: fingerprint,
     ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
   };

package/packages/bundled-features/src/workflow-runner/tables.ts

@@ -52,8 +52,14 @@ export const workflowRunPendingTable = pgTable(
     waitEventType: text("wait_event_type"),
     matchExpr: jsonb("match_expr"),
     // Written by the Phase 3 event-subscriber when the awaited event
-    // arrives — always NULL in Phase 1/2.
+    // arrives — always NULL in Phase 1/2. The row points at the awaited event
+    // ({ eventId, aggregateId, version }); resume-run re-reads it from the
+    // event store, so erasing the event also covers the workflow.
     triggerEventType: text("trigger_event_type"),
+    triggerEventRef: jsonb("trigger_event_ref"),
+    // Legacy copy of the awaited payload. No longer written; only rows
+    // matched before the reference existed still carry it, and resume-run
+    // falls back to it for those.
     triggerPayload: jsonb("trigger_payload"),
   },
   (t) => [
@@ -82,6 +88,7 @@ export const workflowRunPendingTableMeta: EntityTableMeta = defineUnmanagedTable
     { name: "wait_event_type", pgType: "text", notNull: false },
     { name: "match_expr", pgType: "jsonb", notNull: false },
     { name: "trigger_event_type", pgType: "text", notNull: false },
+    { name: "trigger_event_ref", pgType: "jsonb", notNull: false },
     { name: "trigger_payload", pgType: "jsonb", notNull: false },
   ],
   indexes: [

package/samples/apps/styleguide/src/features/widgets/i18n.ts

@@ -55,6 +55,11 @@ export const WIDGETS_I18N = {
     de: "Antwortzeit-Verlauf",
     en: "Response time history",
   },
+  "widgets:catalog:response-time-p95": { de: "p95: 180 ms", en: "p95: 180 ms" },
+  "widgets:catalog:response-time-p95-aria": {
+    de: "p95-Schwelle der letzten 24 Stunden",
+    en: "p95 threshold over the last 24 hours",
+  },
   "widgets:catalog:24h-ago": { de: "vor 24h", en: "24h ago" },
   "widgets:catalog:12h-ago": { de: "vor 12h", en: "12h ago" },
   "widgets:catalog:now": { de: "jetzt", en: "now" },

package/samples/apps/styleguide/src/features/widgets/web/Widgets.tsx

@@ -120,6 +120,17 @@ export function Widgets(): ReactNode {
             end: t("widgets:catalog:now"),
           }}
         />
+        <div className="mt-4">
+          <TimeseriesChart
+            points={RESPONSE_TIMES}
+            windowStartMs={0}
+            windowEndMs={24 * 60 * 60 * 1000}
+            ariaLabel={t("widgets:catalog:response-time-p95-aria")}
+            referenceLines={[
+              { value: 180, label: t("widgets:catalog:response-time-p95"), tone: "warn" },
+            ]}
+          />
+        </div>
       </SectionCard>
 
       <SectionCard

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

@@ -0,0 +1,16 @@
+// @runtime test
+//
+// Framework-free constants shared by the gallery server and spec (the spec
+// runs in a Playwright worker and must not pull the server import chain).
+
+export const GALLERY_PROVIDER = "gallery-mock-provider";
+export const GALLERY_TERMS_SLUG = "gallery-terms";
+export const GALLERY_OPERATOR_EMAIL = "billing@gallery.example";
+export const GALLERY_PLAN_PATH = "/tenant-admin/billing-plans";
+
+// "localhost" resolves the SYSTEM tenant like the stock dev app; the numeric
+// loopback host resolves none and plays the platform apex.
+export const GALLERY_TENANT_HOST = "localhost";
+export const GALLERY_APEX_HOST = "127.0.0.1";
+
+export const GALLERY_PRICE_IDS = { starter: "price_gallery_starter", pro: "price_gallery_pro" };

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

@@ -0,0 +1,152 @@
+// @runtime test
+//
+// E2E-only wiring for the consent/termination review gallery: a mock billing
+// provider (the only fake — real handlers, real dispatcher), the catalog and
+// the nav entry that makes billing-foundation's dormant plans screen reachable.
+
+import {
+  createBillingFoundationFeature,
+  type ProviderPrice,
+  type SubscriptionProviderPlugin,
+  SubscriptionStatuses,
+  subscriptionAggregateId,
+  subscriptionsProjectionTable,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  createChannelEmailFeature,
+  createInMemoryTransport,
+} from "@cosmicdrift/kumiko-bundled-features/channel-email";
+import { simpleRenderer } from "@cosmicdrift/kumiko-bundled-features/renderer-simple";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  GALLERY_OPERATOR_EMAIL,
+  GALLERY_PLAN_PATH,
+  GALLERY_PRICE_IDS,
+  GALLERY_PROVIDER,
+  GALLERY_TERMS_SLUG,
+} from "./gallery-constants";
+
+export const galleryMailTransport = createInMemoryTransport();
+
+const PRICES: readonly ProviderPrice[] = [
+  {
+    priceId: GALLERY_PRICE_IDS.starter,
+    unitAmount: 900,
+    currency: "eur",
+    interval: "month",
+    intervalCount: 1,
+    active: true,
+    metadata: {},
+  },
+  {
+    priceId: GALLERY_PRICE_IDS.pro,
+    unitAmount: 1900,
+    currency: "eur",
+    interval: "month",
+    intervalCount: 1,
+    active: true,
+    metadata: {},
+  },
+];
+
+async function resolveCurrentTier(db: TenantDb, tenantId: string): Promise<string> {
+  const rows = await db.selectMany(
+    subscriptionsProjectionTable,
+    { id: subscriptionAggregateId(tenantId) },
+    { limit: 1 },
+  );
+  const row = rows[0];
+  if (!row) return "free";
+  const status = row["status"] as string;
+  return status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing
+    ? (row["tier"] as string)
+    : "free";
+}
+
+export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition {
+  return createBillingFoundationFeature({
+    baseUrl,
+    catalog: {
+      plans: ["starter", "pro"],
+      tierLabelKey: (tier) => `gallery.plan.${tier}.label`,
+      benefits: (tier) => [{ labelKey: `gallery.plan.${tier}.benefit` }],
+      resolveCurrentTier,
+      viewRoles: ["TenantAdmin", "SystemAdmin"],
+      successPath: GALLERY_PLAN_PATH,
+      cancelPath: GALLERY_PLAN_PATH,
+      providerName: GALLERY_PROVIDER,
+    },
+    consumerProtection: {
+      termsTextBlock: GALLERY_TERMS_SLUG,
+      vatNote: { de: "Preise inkl. USt.", en: "Prices include VAT." },
+      operatorEmail: GALLERY_OPERATOR_EMAIL,
+      terminationScope: "platform",
+      legalLinks: {
+        terms: "/legal/terms",
+        withdrawal: "/legal/withdrawal",
+        privacy: "/legal/privacy",
+      },
+    },
+  });
+}
+
+export function createGalleryEmailFeature(): FeatureDefinition {
+  return createChannelEmailFeature({
+    transport: galleryMailTransport,
+    renderer: simpleRenderer,
+    resolveEmail: async () => "unused@gallery.example",
+  });
+}
+
+// The page URL carries the consent id so the spec can echo it on the webhook,
+// exactly as a real provider echoes the checkout metadata.
+const galleryProviderPlugin: SubscriptionProviderPlugin = {
+  verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody),
+  priceToTier: {
+    [GALLERY_PRICE_IDS.starter]: "starter",
+    [GALLERY_PRICE_IDS.pro]: "pro",
+  },
+  retrievePrices: async (_ctx, priceIds) => PRICES.filter((p) => priceIds.includes(p.priceId)),
+  createCheckoutSession: async (_ctx, options) => {
+    const url = new URL(options.successUrl);
+    if (options.consentId !== undefined) url.searchParams.set("consentId", options.consentId);
+    return { url: url.toString() };
+  },
+  cancelSubscription: async () => {},
+};
+
+export const galleryProviderFeature: FeatureDefinition = defineFeature(
+  "gallery-mock-provider",
+  (r) => {
+    r.describe("E2E-only mock subscription provider for the consent/termination gallery.");
+    r.requires("billing-foundation");
+    r.useExtension("subscriptionProvider", GALLERY_PROVIDER, galleryProviderPlugin);
+  },
+);
+
+export const galleryScreensFeature: FeatureDefinition = defineFeature("gallery-screens", (r) => {
+  r.describe("E2E-only nav entry for the billing plans screen plus plan labels.");
+  r.requires("billing-foundation", "admin-shell");
+  r.nav({
+    id: "billing",
+    label: "gallery:nav.billing",
+    icon: "file",
+    screen: "billing-foundation:screen:billing-plans",
+    order: 20,
+    access: { roles: ["TenantAdmin", "SystemAdmin"] },
+    workspaces: ["admin-shell:workspace:tenant-admin"],
+  });
+  r.translations({
+    keys: {
+      "gallery:nav.billing": { de: "Abrechnung", en: "Billing" },
+      "gallery.plan.free.label": { de: "Free", en: "Free" },
+      "gallery.plan.starter.label": { de: "Starter", en: "Starter" },
+      "gallery.plan.pro.label": { de: "Pro", en: "Pro" },
+      "gallery.plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
+      "gallery.plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
+      "gallery.plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
+    },
+  });
+  return {};
+});