@cosmicdrift/kumiko-samples 0.344.0 → 0.346.0

package/packages/bundled-features/src/auth-email-password/web/signup-complete-screen.tsx

@@ -57,6 +57,7 @@ export function SignupCompleteScreen({
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [continueHref, setContinueHref] = useState<string | null>(null);
+  const [mfaPending, setMfaPending] = useState(false);
 
   const doSubmit = async (): Promise<void> => {
     setError(null);
@@ -73,6 +74,11 @@ export function SignupCompleteScreen({
     const res = await confirmSignup(token, password);
     setSubmitting(false);
     if (res.ok) {
+      if (res.data.kind === "mfa-pending") {
+        setMfaPending(true);
+        setContinueHref(loginHref);
+        return;
+      }
       // Cookies are already set (auto-login). Show a confirmation with an
       // explicit continue button instead of navigating away silently —
       // the user otherwise gets no signal that activation worked.
@@ -124,7 +130,11 @@ export function SignupCompleteScreen({
     return (
       <AuthCard title={effectiveTitle}>
         <p className="text-sm text-muted-foreground" role="status">
-          {t("auth.signupComplete.activated")}
+          {t(
+            mfaPending
+              ? "auth.signupComplete.activatedMfaPending"
+              : "auth.signupComplete.activated",
+          )}
         </p>
         <Link href={continueHref} variant="button">
           {t("auth.signupComplete.continue")}

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "Subscription webhooks no longer overwrite manual tier grants",
+    "detail": "Subscription tier sync keeps manual tier grants\nThe billing webhook sync now skips tier assignments with `source: \"manual\"`, so a `set-tenant-tier` grant is no longer overwritten by Stripe created/canceled events. Rows the sync writes are marked `source: \"billing\"`. `TierAssignmentSources` is exported from tier-engine."
+  },
   {
     "version": "0.344.0",
     "type": "breaking",

package/packages/bundled-features/src/billing-foundation/subscription-tier-sync.ts

@@ -4,6 +4,7 @@
 // so it is now a factory parameter.
 
 import {
+  TierAssignmentSources,
   TierEngineHandlers,
   TierEngineQueries,
   tierAssignmentAggregateId,
@@ -61,6 +62,24 @@ function asRows(result: unknown): ReadonlyArray<Record<string, unknown>> {
   throw new Error("expected a { rows: [...] } list-query result");
 }
 
+type ExistingTierAssignment = {
+  readonly id: string;
+  readonly version: number;
+  readonly tier: unknown;
+  readonly source: unknown;
+};
+
+function findTierAssignment(
+  rows: ReadonlyArray<Record<string, unknown>>,
+  tenantId: TenantId,
+): ExistingTierAssignment | undefined {
+  const row = rows.find((candidate) => candidate["tenantId"] === tenantId);
+  if (!row || typeof row["id"] !== "string" || typeof row["version"] !== "number") {
+    return undefined;
+  }
+  return { id: row["id"], version: row["version"], tier: row["tier"], source: row["source"] };
+}
+
 export function createSubscriptionTierSync<TTier extends string>(
   deps: SubscriptionTierSyncDeps<TTier>,
 ) {
@@ -94,15 +113,15 @@ export function createSubscriptionTierSync<TTier extends string>(
           tenantId,
         }),
       );
-      const assignment = tierAssignmentRows.find((row) => row["tenantId"] === tenantId);
-      if (
-        !assignment ||
-        typeof assignment["id"] !== "string" ||
-        typeof assignment["version"] !== "number"
-      ) {
+      const assignment = findTierAssignment(tierAssignmentRows, tenantId);
+      if (!assignment) {
         const created = await routeDeps.dispatchSystemWrite({
           handlerQn: TierEngineHandlers.create,
-          payload: { id: tierAssignmentAggregateId(tenantId), tier: effective },
+          payload: {
+            id: tierAssignmentAggregateId(tenantId),
+            tier: effective,
+            source: TierAssignmentSources.billing,
+          },
           tenantId,
         });
         if (!created.isSuccess) {
@@ -113,14 +132,15 @@ export function createSubscriptionTierSync<TTier extends string>(
         }
         return null;
       }
-      if (assignment["tier"] === effective) return null;
+      if (assignment.source === TierAssignmentSources.manual) return null;
+      if (assignment.tier === effective) return null;
 
       const result = await routeDeps.dispatchSystemWrite({
         handlerQn: TierEngineHandlers.update,
         payload: {
-          id: assignment["id"],
-          version: assignment["version"],
-          changes: { tier: effective },
+          id: assignment.id,
+          version: assignment.version,
+          changes: { tier: effective, source: TierAssignmentSources.billing },
         },
         tenantId,
       });

package/packages/bundled-features/src/step-dispatcher/changes.json

@@ -1,4 +1,35 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "A failed key erase no longer causes a second delivery of the same dispatch request",
+    "detail": "step-dispatcher no longer re-sends after a failed key erase\nWhen erasing the per-dispatch key failed after the outcome was recorded, the redelivered request was sent again and produced a second `step.dispatched`. A redelivery now only repeats the erase."
+  },
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "Webhook caller headers no longer merge with the default Content-Type or the auth header",
+    "detail": "Webhook headers merge case-insensitively\nA caller `Content-Type` replaces the default `application/json` instead of being joined with it. When a caller header collides with the auth header (any casing), the resolved secret value wins."
+  },
+  {
+    "version": "0.346.0",
+    "type": "fix",
+    "title": "Webhook requests time out after 10 seconds instead of blocking the dispatcher",
+    "detail": "Webhook requests time out after 10 seconds\nA hanging receiver now ends as `step.dispatch-failed` and no longer stalls the step-dispatcher for every tenant."
+  },
+  {
+    "version": "0.346.0",
+    "type": "breaking",
+    "title": "r.step.webhook.send drops the unused retry option",
+    "detail": "`r.step.webhook.send` no longer accepts `retry`\nThe option was never applied: every dispatch request is delivered once. Passing it is now a type error, and the dispatch-requested payload no longer carries it. Stored events that still contain `retry` are parsed and delivered as before.",
+    "migration": "Remove `retry` from `r.step.webhook.send` calls; it was never applied. Each dispatch request is delivered once; a delivery error ends as step.dispatch-failed."
+  },
+  {
+    "version": "0.345.0",
+    "type": "improvement",
+    "title": "Webhook sends carry an Idempotency-Key header that is stable across redeliveries",
+    "detail": "Webhook sends carry an Idempotency-Key header\nEvery `r.step.webhook.send` request now has `Idempotency-Key: <dispatch stream id>`. The value stays the same when the same dispatch request is delivered again, so receivers can deduplicate. An explicit `Idempotency-Key` in `headers` (any casing) takes precedence."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/step-dispatcher/dispatch-payload.ts

@@ -0,0 +1,144 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiValueForSubject,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import * as z from "zod";
+import { type MailSpec, mailSpecSchema } from "./mail-runner.js";
+import { type WebhookSpec, webhookSpecSchema } from "./webhook-runner.js";
+
+// PII fields of the flat payload are ciphertext under the per-dispatch
+// record key (system-event-pii.ts). `to`/`headersJson`/`bodyJson` are JSON
+// strings because event PII encryption only handles top-level strings.
+// Runtime-validated instead of cast — `event.payload` is `unknown` at the
+// MSP-apply boundary, so a payload in another shape must end as
+// dispatch-failed, never reach the runners.
+export const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
+  z.object({
+    stepKind: z.literal("webhook.send"),
+    url: z.string(),
+    method: webhookSpecSchema.shape.method,
+    headersJson: z.string(),
+    bodyJson: z.string().optional(),
+    auth: webhookSpecSchema.shape.auth,
+  }),
+  z.object({
+    stepKind: z.literal("mail.send"),
+    to: z.string(),
+    subject: z.string(),
+    body: z.string(),
+    from: z.string().optional(),
+  }),
+]);
+
+type DispatchRequestedPayload = z.infer<typeof dispatchRequestedPayloadSchema>;
+
+const rawStepKindSchema = z.object({ stepKind: z.string() });
+
+export function rawStepKindOf(payload: unknown): string {
+  const parsed = rawStepKindSchema.safeParse(payload);
+  return parsed.success ? parsed.data.stepKind : "unknown";
+}
+
+const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed;
+  } catch {
+    refinementCtx.addIssue({ code: "custom", message: "invalid json" });
+    return z.NEVER;
+  }
+});
+
+const headersJsonSchema = jsonStringSchema.pipe(z.record(z.string(), z.string()));
+const mailToJsonSchema = jsonStringSchema.pipe(mailSpecSchema.shape.to);
+
+type PayloadFieldName = "to" | "subject" | "body" | "from" | "url" | "headersJson" | "bodyJson";
+
+function piiFieldsOf(payload: DispatchRequestedPayload): readonly PayloadFieldName[] {
+  return payload.stepKind === "mail.send"
+    ? ["to", "subject", "body", "from"]
+    : ["url", "headersJson", "bodyJson"];
+}
+
+function payloadFieldValue(
+  payload: DispatchRequestedPayload,
+  field: PayloadFieldName,
+): string | undefined {
+  const values: Readonly<Partial<Record<PayloadFieldName, string>>> =
+    payload.stepKind === "mail.send"
+      ? { to: payload.to, subject: payload.subject, body: payload.body, from: payload.from }
+      : { url: payload.url, headersJson: payload.headersJson, bodyJson: payload.bodyJson };
+  return values[field];
+}
+
+type ReadPayloadResult =
+  | { readonly kind: "ready"; readonly fields: Readonly<Partial<Record<PayloadFieldName, string>>> }
+  | { readonly kind: "erased" }
+  | { readonly kind: "unreadable" };
+
+export async function readPayloadFields(
+  payload: DispatchRequestedPayload,
+): Promise<ReadPayloadResult> {
+  const kms = configuredPiiSubjectKms();
+  const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+  const fields: Partial<Record<PayloadFieldName, string>> = {};
+  for (const field of piiFieldsOf(payload)) {
+    const value = payloadFieldValue(payload, field);
+    if (value === undefined) continue;
+    if (!isPiiCiphertext(value)) {
+      fields[field] = value;
+      continue;
+    }
+    if (!kms) return { kind: "unreadable" };
+    const plain = await decryptPiiValueForSubject(kms, value, { requestId }, field);
+    if (plain === PII_ERASED_SENTINEL) return { kind: "erased" };
+    fields[field] = plain;
+  }
+  return { kind: "ready", fields };
+}
+
+type DispatchSpec =
+  | { readonly stepKind: "mail.send"; readonly spec: MailSpec }
+  | { readonly stepKind: "webhook.send"; readonly spec: WebhookSpec };
+
+// Parse failures return null — the caller records a generic error, never the
+// (decrypted) values.
+export function buildDispatchSpec(
+  payload: DispatchRequestedPayload,
+  fields: Readonly<Partial<Record<PayloadFieldName, string>>>,
+): DispatchSpec | null {
+  if (payload.stepKind === "mail.send") {
+    const to = mailToJsonSchema.safeParse(fields.to);
+    if (!to.success || fields.subject === undefined || fields.body === undefined) return null;
+    return {
+      stepKind: "mail.send",
+      spec: {
+        to: to.data,
+        subject: fields.subject,
+        body: fields.body,
+        ...(fields.from !== undefined && { from: fields.from }),
+      },
+    };
+  }
+  const headers = headersJsonSchema.safeParse(fields.headersJson);
+  if (!headers.success || fields.url === undefined) return null;
+  let body: unknown;
+  if (fields.bodyJson !== undefined) {
+    const parsedBody = jsonStringSchema.safeParse(fields.bodyJson);
+    if (!parsedBody.success) return null;
+    body = parsedBody.data;
+  }
+  return {
+    stepKind: "webhook.send",
+    spec: {
+      url: fields.url,
+      method: payload.method,
+      headers: headers.data,
+      ...(body !== undefined && { body }),
+      ...(payload.auth && { auth: payload.auth }),
+    },
+  };
+}

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -8,12 +8,7 @@
 // the audit trail lives in the event log only — no separate status table.
 
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
-import {
-  configuredPiiSubjectKms,
-  decryptPiiValueForSubject,
-  isPiiCiphertext,
-  PII_ERASED_SENTINEL,
-} from "@cosmicdrift/kumiko-framework/crypto";
+import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
 import {
   defineFeature,
   type FeatureDefinition,
@@ -26,13 +21,17 @@ import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import * as z from "zod";
 import { redactEmailAddresses } from "../shared/index.js";
-import { type MailSpec, mailSpecSchema, performMailDispatch } from "./mail-runner.js";
+import {
+  buildDispatchSpec,
+  dispatchRequestedPayloadSchema,
+  rawStepKindOf,
+  readPayloadFields,
+} from "./dispatch-payload.js";
+import { performMailDispatch } from "./mail-runner.js";
 import {
   performWebhookDispatch,
   WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
   WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS,
-  type WebhookSpec,
-  webhookSpecSchema,
 } from "./webhook-runner.js";
 
 const log = createFallbackLogger("step-dispatcher");
@@ -48,33 +47,6 @@ export const stepDispatcherEnvSchema = z.object({
 
 export { STEP_DISPATCH_AGGREGATE_TYPE };
 
-// PII fields of the flat payload are ciphertext under the per-dispatch
-// record key (system-event-pii.ts). `to`/`headersJson`/`bodyJson` are JSON
-// strings because event PII encryption only handles top-level strings.
-// Runtime-validated instead of cast — `event.payload` is `unknown` at the
-// MSP-apply boundary, so a payload in another shape must end as
-// dispatch-failed, never reach the runners.
-const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
-  z.object({
-    stepKind: z.literal("webhook.send"),
-    url: z.string(),
-    method: webhookSpecSchema.shape.method,
-    headersJson: z.string(),
-    bodyJson: z.string().optional(),
-    auth: webhookSpecSchema.shape.auth,
-    retry: z.object({ times: z.number(), backoff: z.enum(["exponential", "linear"]) }).optional(),
-  }),
-  z.object({
-    stepKind: z.literal("mail.send"),
-    to: z.string(),
-    subject: z.string(),
-    body: z.string(),
-    from: z.string().optional(),
-  }),
-]);
-
-type DispatchRequestedPayload = z.infer<typeof dispatchRequestedPayloadSchema>;
-
 // zod issue messages can echo the invalid value (e.g. a rejected url) back
 // into the tenant-visible dispatch-failed event — keep this generic.
 const INVALID_DISPATCH_PAYLOAD_ERROR = "invalid dispatch payload";
@@ -84,116 +56,14 @@ const PAYLOAD_UNREADABLE_ERROR = "dispatch payload is not readable";
 const MAIL_DELIVERY_FAILED_ERROR = "mail delivery failed";
 const PAYLOAD_ERASED_ERROR = "dispatch payload erased before an outcome was recorded";
 
-const rawStepKindSchema = z.object({ stepKind: z.string() });
-
-function rawStepKindOf(payload: unknown): string {
-  const parsed = rawStepKindSchema.safeParse(payload);
-  return parsed.success ? parsed.data.stepKind : "unknown";
-}
-
-const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    return parsed;
-  } catch {
-    refinementCtx.addIssue({ code: "custom", message: "invalid json" });
-    return z.NEVER;
-  }
-});
-
-const headersJsonSchema = jsonStringSchema.pipe(z.record(z.string(), z.string()));
-const mailToJsonSchema = jsonStringSchema.pipe(mailSpecSchema.shape.to);
-
-type PayloadFieldName = "to" | "subject" | "body" | "from" | "url" | "headersJson" | "bodyJson";
-
-function piiFieldsOf(payload: DispatchRequestedPayload): readonly PayloadFieldName[] {
-  return payload.stepKind === "mail.send"
-    ? ["to", "subject", "body", "from"]
-    : ["url", "headersJson", "bodyJson"];
-}
-
-function payloadFieldValue(
-  payload: DispatchRequestedPayload,
-  field: PayloadFieldName,
-): string | undefined {
-  const values: Readonly<Partial<Record<PayloadFieldName, string>>> =
-    payload.stepKind === "mail.send"
-      ? { to: payload.to, subject: payload.subject, body: payload.body, from: payload.from }
-      : { url: payload.url, headersJson: payload.headersJson, bodyJson: payload.bodyJson };
-  return values[field];
-}
-
-type ReadPayloadResult =
-  | { readonly kind: "ready"; readonly fields: Readonly<Partial<Record<PayloadFieldName, string>>> }
-  | { readonly kind: "erased" }
-  | { readonly kind: "unreadable" };
-
-async function readPayloadFields(payload: DispatchRequestedPayload): Promise<ReadPayloadResult> {
-  const kms = configuredPiiSubjectKms();
-  const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
-  const fields: Partial<Record<PayloadFieldName, string>> = {};
-  for (const field of piiFieldsOf(payload)) {
-    const value = payloadFieldValue(payload, field);
-    if (value === undefined) continue;
-    if (!isPiiCiphertext(value)) {
-      fields[field] = value;
-      continue;
-    }
-    if (!kms) return { kind: "unreadable" };
-    const plain = await decryptPiiValueForSubject(kms, value, { requestId }, field);
-    if (plain === PII_ERASED_SENTINEL) return { kind: "erased" };
-    fields[field] = plain;
-  }
-  return { kind: "ready", fields };
-}
-
-type DispatchSpec =
-  | { readonly stepKind: "mail.send"; readonly spec: MailSpec }
-  | { readonly stepKind: "webhook.send"; readonly spec: WebhookSpec };
-
-// Parse failures return null — the caller records a generic error, never the
-// (decrypted) values.
-function buildDispatchSpec(
-  payload: DispatchRequestedPayload,
-  fields: Readonly<Partial<Record<PayloadFieldName, string>>>,
-): DispatchSpec | null {
-  if (payload.stepKind === "mail.send") {
-    const to = mailToJsonSchema.safeParse(fields.to);
-    if (!to.success || fields.subject === undefined || fields.body === undefined) return null;
-    return {
-      stepKind: "mail.send",
-      spec: {
-        to: to.data,
-        subject: fields.subject,
-        body: fields.body,
-        ...(fields.from !== undefined && { from: fields.from }),
-      },
-    };
-  }
-  const headers = headersJsonSchema.safeParse(fields.headersJson);
-  if (!headers.success || fields.url === undefined) return null;
-  let body: unknown;
-  if (fields.bodyJson !== undefined) {
-    const parsedBody = jsonStringSchema.safeParse(fields.bodyJson);
-    if (!parsedBody.success) return null;
-    body = parsedBody.data;
-  }
-  return {
-    stepKind: "webhook.send",
-    spec: {
-      url: fields.url,
-      method: payload.method,
-      headers: headers.data,
-      ...(body !== undefined && { body }),
-      ...(payload.auth && { auth: payload.auth }),
-    },
-  };
+function isDispatchOutcome(e: { readonly type: string }): boolean {
+  return e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE;
 }
 
 export function createStepDispatcherFeature(): FeatureDefinition {
   return defineFeature("step-dispatcher", (r) => {
     r.describe(
-      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
+      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
     );
     r.secretNamespace("webhook-auth", WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS);
     r.uiHints({
@@ -211,9 +81,20 @@ export function createStepDispatcherFeature(): FeatureDefinition {
           const kms = configuredPiiSubjectKms();
           const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
 
+          const eraseDispatchKey = async (): Promise<void> => {
+            await kms?.eraseKey(
+              { kind: "record", entity: STEP_DISPATCH_AGGREGATE_TYPE, id: event.aggregateId },
+              { requestId, eraseReason: "step-dispatch-outcome-recorded" },
+            );
+          };
+
           // Outcome events are plaintext and generic; the request payload's
           // per-dispatch key is erased right after, so the PII dies with the
-          // dispatch instead of living in the event log.
+          // dispatch instead of living in the event log. The outcome is
+          // appended before the erase on purpose: if the erase throws, the
+          // outcome survives and a redelivery only repeats the erase. A crash
+          // between the send and the outcome append still re-sends under the
+          // same Idempotency-Key — the one remaining double-send case.
           const recordOutcome = async (
             type: typeof STEP_DISPATCHED_TYPE | typeof STEP_DISPATCH_FAILED_TYPE,
             payload: Record<string, unknown>,
@@ -224,14 +105,18 @@ export function createStepDispatcherFeature(): FeatureDefinition {
               type,
               payload,
             });
-            await kms?.eraseKey(
-              { kind: "record", entity: STEP_DISPATCH_AGGREGATE_TYPE, id: event.aggregateId },
-              { requestId, eraseReason: "step-dispatch-outcome-recorded" },
-            );
+            await eraseDispatchKey();
           };
           const recordFailure = (stepKind: string, error: string) =>
             recordOutcome(STEP_DISPATCH_FAILED_TYPE, { stepKind, error, attempt: 1 });
 
+          const stream = await ctx.loadAggregate(event.aggregateId);
+          if (stream.some(isDispatchOutcome)) {
+            await eraseDispatchKey();
+            // skip: redelivery after an outcome was recorded — only the erase is repeated
+            return;
+          }
+
           const parsed = dispatchRequestedPayloadSchema.safeParse(event.payload);
           if (!parsed.success) {
             await recordFailure(rawStepKindOf(event.payload), INVALID_DISPATCH_PAYLOAD_ERROR);
@@ -247,12 +132,6 @@ export function createStepDispatcherFeature(): FeatureDefinition {
             return;
           }
           if (read.kind === "erased") {
-            const stream = await ctx.loadAggregate(event.aggregateId);
-            const hasOutcome = stream.some(
-              (e) => e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE,
-            );
-            // skip: redelivery after the key was erased — the outcome is already recorded
-            if (hasOutcome) return;
             await recordFailure(payload.stepKind, PAYLOAD_ERASED_ERROR);
             // skip: erased payload recorded via step.dispatch-failed above
             return;
@@ -270,6 +149,7 @@ export function createStepDispatcherFeature(): FeatureDefinition {
                   tenantId: event.tenantId,
                   userId: event.metadata.userId || SYSTEM_USER_ID,
                   secrets: ctx.secrets,
+                  idempotencyKey: event.aggregateId,
                 })
               : await performMailDispatch(dispatchSpec.spec);
           if (result.ok) {

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -114,18 +114,44 @@ export type WebhookDispatchDeps = {
   readonly tenantId: TenantId;
   readonly userId: string;
   readonly secrets: SecretsContext | undefined;
+  readonly idempotencyKey: string;
+  readonly requestTimeoutMs?: number;
 };
 
+// One hanging tenant-controlled receiver must not stall the shared
+// step-dispatcher consumer for every tenant.
+export const WEBHOOK_REQUEST_TIMEOUT_MS = 10_000;
+
 // Never includes the secret name or value — spec.auth.secret is a
 // tenant-chosen name, but the error still reaches the tenant via the
 // dispatch-failed event, so it stays generic.
 const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
 
+export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+
+function hasHeader(headers: Readonly<Record<string, string>>, lowerCaseName: string): boolean {
+  return Object.keys(headers).some((name) => name.toLowerCase() === lowerCaseName);
+}
+
+// Header names are case-insensitive: two keys differing only in case would be
+// comma-joined by `Headers`, so a replacement must drop every spelling first.
+function setHeader(headers: Record<string, string>, name: string, value: string): void {
+  const lowerCaseName = name.toLowerCase();
+  for (const existing of Object.keys(headers)) {
+    if (existing.toLowerCase() === lowerCaseName) delete headers[existing];
+  }
+  headers[name] = value;
+}
+
 async function buildWebhookHeaders(
   spec: WebhookSpec,
   deps: WebhookDispatchDeps,
 ): Promise<{ ok: true; headers: Record<string, string> } | { ok: false; error: string }> {
-  const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  const headers: Record<string, string> = { ...spec.headers };
+  if (!hasHeader(headers, "content-type")) headers["content-type"] = "application/json";
+  if (!hasHeader(headers, WEBHOOK_IDEMPOTENCY_KEY_HEADER)) {
+    headers[WEBHOOK_IDEMPOTENCY_KEY_HEADER] = deps.idempotencyKey;
+  }
   if (!spec.auth) return { ok: true, headers };
   if (!deps.secrets) return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
   // A throwing get (corrupt envelope, rotated key, KMS error) must become a
@@ -144,9 +170,9 @@ async function buildWebhookHeaders(
     return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
   }
   if (spec.auth.kind === "bearer") {
-    headers["authorization"] = `Bearer ${secret}`;
+    setHeader(headers, "authorization", `Bearer ${secret}`);
   } else {
-    headers[spec.auth.name] = secret;
+    setHeader(headers, spec.auth.name, secret);
   }
   return { ok: true, headers };
 }
@@ -205,6 +231,7 @@ export async function performWebhookDispatch(
       ...target.requestInit,
       method: spec.method,
       redirect: "manual",
+      signal: AbortSignal.timeout(deps.requestTimeoutMs ?? WEBHOOK_REQUEST_TIMEOUT_MS),
       body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
     });
     if (!res.ok) {

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

@@ -15,6 +15,13 @@ export const TierEngineHandlers = {
   setTenantTier: "tier-engine:write:set-tenant-tier",
 } as const;
 
+// Origin of a tier-assignment row; the billing sync must not touch "manual" rows.
+export const TierAssignmentSources = {
+  manual: "manual",
+  billing: "billing",
+  default: "default",
+} as const;
+
 // Qualified query handler names.
 export const TierEngineQueries = {
   list: "tier-engine:query:tier-assignment:list",

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

@@ -33,10 +33,8 @@ export const tierAssignmentEntity = createEntity({
       personal: false,
       reason: "catalog_label",
     }),
-    // Woher das Assignment stammt: "manual" (Admin-Grant via tier-admin-Screen),
-    // "stripe" (future Billing-Sync), "default" (auto-default-on-signup-Hook).
-    // Optional für Back-Compat zu bestehenden Rows ohne source. Schützt manuelle
-    // Grants davor, von einem späteren Stripe→Tier-Sync geplättet zu werden.
+    // Origin of the assignment, see TierAssignmentSources. Optional for back-compat with
+    // rows without source. Protects manual grants from being overwritten by the billing sync.
     source: createTextField({
       required: false,
       maxLength: 20,

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

@@ -75,7 +75,12 @@ import * as z from "zod";
 import { tenantTable } from "../tenant/index.js";
 import { tierAssignmentAggregateId } from "./aggregate-id.js";
 import type { TierMap } from "./compose-app.js";
-import { TIER_ADMIN_SCREEN_ID, TIER_ENGINE_FEATURE, TierEngineHandlers } from "./constants.js";
+import {
+  TIER_ADMIN_SCREEN_ID,
+  TIER_ENGINE_FEATURE,
+  TierAssignmentSources,
+  TierEngineHandlers,
+} from "./constants.js";
 import { tierAssignmentEntity } from "./entity.js";
 import { getActiveTierQuery } from "./handlers/active-tier.query.js";
 import { getTenantTierQuery } from "./handlers/get-tenant-tier.query.js";
@@ -450,7 +455,7 @@ export function createTierEngineFeature<
           const tdb = createTenantDb(rawDb, newTenantId, "system");
 
           await tierAssignmentExecutor.create(
-            { id: aggregateId, tier: defaultTier, source: "default" },
+            { id: aggregateId, tier: defaultTier, source: TierAssignmentSources.default },
             systemUser,
             tdb,
           );