@cosmicdrift/kumiko-samples 0.345.0 → 0.347.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.345.0",
+  "version": "0.347.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.345.0",
+  "version": "0.347.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "improvement",
+    "title": "Audit queries can read app-instance system events with scope \"system\" (SystemAdmin only)",
+    "detail": "Audit queries accept `scope: \"system\"` for SystemAdmin\n`audit:query:list` and `audit:query:details` take an optional `scope` (`\"tenant\"` or `\"system\"`). With `\"system\"` a SystemAdmin reads the app-instance system events, e.g. `kumiko:system:app.started`; other roles are denied. Without `scope` nothing changes."
+  },
   {
     "version": "0.345.0",
     "type": "fix",

package/packages/bundled-features/src/audit/constants.ts

@@ -19,6 +19,11 @@ export const AuditQueries = {
   details: "audit:query:details",
 } as const;
 
+/** Read scope of the audit queries: the caller's own tenant (default) or the system tenant (SystemAdmin only). */
+export const AuditScopes = { tenant: "tenant", system: "system" } as const;
+export type AuditScope = (typeof AuditScopes)[keyof typeof AuditScopes];
+export const AUDIT_SCOPE_VALUES = [AuditScopes.tenant, AuditScopes.system] as const;
+
 /** Tenant-admin audit log screen. Nav: `audit:screen:audit-log`. */
 export const AUDIT_LOG_SCREEN_ID = "audit-log" as const;
 

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

@@ -36,7 +36,7 @@ export function createAuditFeature(): FeatureDefinition {
     "audit",
     (r) => {
       r.describe(
-        "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
+        "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       );
       r.uiHints({
         displayLabel: "Audit Log",

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -1,21 +1,26 @@
 // Single audit event by its event-store id — backs the audit-log-detail
 // screen. Tenant-isolated at the WHERE level like list.query, so a caller
-// can only read events in their own tenant.
+// can only read events in their own tenant; a SystemAdmin can pass scope
+// "system" to read app-instance system events (e.g. app.started).
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";
+import { AUDIT_SCOPE_VALUES } from "../constants.js";
+import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
 export const detailsQuery = defineQueryHandler({
   name: "details",
   description:
-    "Returns one audit-trail event of the caller's tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list.",
+    'Returns one audit-trail event of the caller\'s tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list. A SystemAdmin can set scope "system" to read an app-instance system event (e.g. app.started).',
   schema: z.object({
     id: z.string().regex(/^[1-9]\d*$/, "id must be a positive integer"),
+    scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
   }),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
+    const scopeFilter = resolveAuditScopeFilter(query.user, query.payload.scope);
     const rows = await selectMany<{
       id: bigint;
       aggregateId: string;
@@ -29,7 +34,13 @@ export const detailsQuery = defineQueryHandler({
     }>(
       ctx.db,
       eventsTable,
-      { tenantId: query.user.tenantId, id: BigInt(query.payload.id) },
+      {
+        tenantId: scopeFilter.tenantId,
+        ...(scopeFilter.aggregateType !== undefined && {
+          aggregateType: scopeFilter.aggregateType,
+        }),
+        id: BigInt(query.payload.id),
+      },
       { limit: 1 },
     );
     const row = rows[0];

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -6,6 +6,8 @@
 // No projection, no separate audit table. Queryable with the same filter
 // surface any audit UI needs; tenant-isolated at the WHERE level so cross-
 // tenant peeking is structurally impossible for non-SystemAdmin callers.
+// A SystemAdmin can pass scope "system" to read the app-instance system events
+// (e.g. app.started); no other cross-tenant read exists.
 //
 // Sensitive field-values are ciphertext inside the event payload (the log
 // carries them encrypted); stripSensitive only strips the event echo. This
@@ -17,6 +19,8 @@ import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "temporal-polyfill";
 import * as z from "zod";
+import { AUDIT_SCOPE_VALUES } from "../constants.js";
+import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
 const MAX_LIMIT = 100;
 
@@ -65,7 +69,7 @@ function buildAuditWhere(
 export const listQuery = defineQueryHandler({
   name: "list",
   description:
-    "Lists the tenant's audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when.",
+    'Lists the tenant\'s audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when. A SystemAdmin can set scope "system" to read the app-instance system events (e.g. app.started) instead of the own tenant.',
   schema: z
     .object({
       cursor: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
@@ -80,6 +84,7 @@ export const listQuery = defineQueryHandler({
       sortDirection: z.enum(["asc", "desc"]).optional(),
       from: z.iso.datetime().optional(),
       to: z.iso.datetime().optional(),
+      scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
     })
     .refine((v) => !v.from || !v.to || v.from <= v.to, {
       message: "`from` must be less than or equal to `to`",
@@ -88,7 +93,11 @@ export const listQuery = defineQueryHandler({
   access: { roles: access.admin },
   handler: async (query, ctx) => {
     const p = query.payload;
-    const where = buildAuditWhere(query.user.tenantId, p);
+    const scopeFilter = resolveAuditScopeFilter(query.user, p.scope);
+    const where = buildAuditWhere(scopeFilter.tenantId, {
+      ...p,
+      aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
+    });
 
     const rows = await selectMany<{
       id: bigint;

package/packages/bundled-features/src/audit/handlers/resolve-audit-tenant.ts

@@ -0,0 +1,22 @@
+import { crossTenantOverrideDenied, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { APP_INSTANCE_STREAM_TYPE } from "@cosmicdrift/kumiko-framework/event-store";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { type AuditScope, AuditScopes } from "../constants.js";
+
+export type AuditScopeFilter = { readonly tenantId: string; readonly aggregateType?: string };
+
+// The system tenant also holds personal streams of other features (session
+// revocations, exports, ...); only app-instance streams are released.
+export function resolveAuditScopeFilter(
+  user: SessionUser,
+  scope: AuditScope | undefined,
+): AuditScopeFilter {
+  if (scope !== AuditScopes.system) return { tenantId: user.tenantId };
+  const denied = crossTenantOverrideDenied(
+    user,
+    SYSTEM_TENANT_ID,
+    "audit.errors.systemScopeRequiresSystemAdmin",
+  );
+  if (denied) throw denied;
+  return { tenantId: SYSTEM_TENANT_ID, aggregateType: APP_INSTANCE_STREAM_TYPE };
+}

package/packages/bundled-features/src/audit/i18n.ts

@@ -9,6 +9,9 @@ export const AUDIT_I18N: Readonly<Record<string, LocalizedString>> = {
   "audit.log.detail.subtitle": {
     en: "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
   },
+  "audit.errors.systemScopeRequiresSystemAdmin": {
+    en: "Only SystemAdmin may read system events.",
+  },
   "audit:nav.auditLog": { en: "Audit" },
   "audit.log.col.when": { en: "When" },
   "audit.log.col.type": { en: "Event" },

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Signup-confirm under an MFA policy returns the signup landing path and the activation screen forwards it to login as next",
+    "detail": "Signup with an MFA requirement keeps its landing path\nWhen the MFA policy asks for a factor at self-registration, `/auth/signup-confirm` now also returns the `landingPath` that `auth.postAuthLanding` resolves for the signup flow (including a claimed handover). `SignupCompleteScreen` passes it to the login link as `?next=`, so the login that follows can land where a signup without MFA would have."
+  },
   {
     "version": "0.345.0",
     "type": "fix",

package/packages/bundled-features/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -76,7 +76,16 @@ export type SignupConfirmData =
       // actually succeeded (see the handler body below).
       readonly handover?: { readonly entityType: string; readonly id: string };
     }
-  | Exclude<LoginResult, { readonly kind: "auth-session" }>;
+  | (Exclude<LoginResult, { readonly kind: "auth-session" }> & {
+      // What the response needs to resolve the signup landing although no
+      // session is issued yet.
+      readonly signup: {
+        readonly roles: readonly string[];
+        readonly tenantId: TenantId;
+        readonly tenantKey: string;
+        readonly handover?: ClaimedHandover;
+      };
+    });
 
 export type SignupConfirmOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
 
@@ -240,7 +249,18 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
 
         if (mfaGate !== undefined) {
           committed = true;
-          return { isSuccess: true, data: mfaGate };
+          return {
+            isSuccess: true,
+            data: {
+              ...mfaGate,
+              signup: {
+                roles: session.roles,
+                tenantId: provisioned.tenantId,
+                tenantKey,
+                ...(handover !== undefined && { handover }),
+              },
+            },
+          };
         }
 
         committed = true;

package/packages/bundled-features/src/auth-email-password/web/auth-client.ts

@@ -362,9 +362,11 @@ export type SignupConfirmSuccess = {
 
 // mfa-pending: account exists but the server issued no session because the
 // new roles require a second factor — the user must sign in to enroll.
+// landingPath is where the signup would have landed; the login that follows
+// should end there.
 export type SignupConfirmResult =
   | ({ readonly kind: "signed-in" } & SignupConfirmSuccess)
-  | { readonly kind: "mfa-pending" };
+  | { readonly kind: "mfa-pending"; readonly landingPath?: string };
 
 export async function confirmSignup(
   token: string,
@@ -383,7 +385,13 @@ export async function confirmSignup(
       readonly mfaSetupRequired?: boolean;
     };
     if (body.mfaRequired === true || body.mfaSetupRequired === true) {
-      return { ok: true, data: { kind: "mfa-pending" } };
+      return {
+        ok: true,
+        data: {
+          kind: "mfa-pending",
+          ...(typeof body.landingPath === "string" && { landingPath: body.landingPath }),
+        },
+      };
     }
     return { ok: true, data: { kind: "signed-in", ...body } };
   }

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

@@ -22,6 +22,7 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { confirmSignup, type SignupConfirmSuccess } from "./auth-client.js";
 import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic.js";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.js";
+import { buildLoginRedirectUrl } from "./auth-redirect.js";
 
 export type SignupCompleteScreenProps = {
   readonly title?: string;
@@ -76,7 +77,11 @@ export function SignupCompleteScreen({
     if (res.ok) {
       if (res.data.kind === "mfa-pending") {
         setMfaPending(true);
-        setContinueHref(loginHref);
+        setContinueHref(
+          res.data.landingPath === undefined
+            ? loginHref
+            : buildLoginRedirectUrl(loginHref, res.data.landingPath, window.location.origin),
+        );
         return;
       }
       // Cookies are already set (auto-login). Show a confirmation with an

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/personal-access-tokens/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "improvement",
+    "title": "API-token screens hide behind the tier gate and can fall back to an upgrade screen via lockedFallbackScreen",
+    "detail": "Token screens follow the tier gate of personal-access-tokens\nThe list and mint screens carry a `visibleWhen` on the new `personal-access-tokens:query:availability` probe. For a tenant whose tier excludes the feature (`toggleable`), the dispatcher already rejected every token handler with `feature_disabled`; now the screens also show the unavailable notice instead of an empty list with a broken Create button. A new option `lockedFallbackScreen` names a screen (for example an upgrade notice) to show in its place. Without `toggleable` nothing changes: the feature stays always on."
+  },
   {
     "version": "0.336.0",
     "type": "fix",

package/packages/bundled-features/src/personal-access-tokens/constants.ts

@@ -32,6 +32,7 @@ export const PatHandlers = {
 export const PatQueries = {
   mine: "personal-access-tokens:query:mine",
   availableScopes: "personal-access-tokens:query:available-scopes",
+  availability: "personal-access-tokens:query:availability",
 } as const;
 
 // Only the first chars of a minted token are stored (alongside the hash) so the

package/packages/bundled-features/src/personal-access-tokens/feature.ts

@@ -11,6 +11,7 @@ import {
   PAT_FEATURE,
   type PatRateLimit,
 } from "./constants.js";
+import { availabilityQuery } from "./handlers/availability.query.js";
 import { buildAvailableScopesQuery } from "./handlers/available-scopes.query.js";
 import { type CreatePatOptions, createPatCreateHandler } from "./handlers/create.write.js";
 import { listPatQuery } from "./handlers/list.query.js";
@@ -65,6 +66,10 @@ export type PersonalAccessTokensOptions = {
    *  { default: false } for fail-closed gating (feature off until a tier grants
    *  it). Omit to keep PAT always-on (default). */
   readonly toggleable?: { readonly default: boolean };
+  /** Screen (same-feature id or `<feature>:screen:<id>`, must not be gated itself)
+   *  shown in place of the token screens when the tenant's tier excludes the
+   *  feature, e.g. an upgrade notice. Default: the standard "unavailable" notice. */
+  readonly lockedFallbackScreen?: string;
   // Opt-in MFA re-auth gate for minting a token — wired via
   // mfaVerifierFromFeature (auth-mfa/feature.ts) at app-composition time. No
   // hard dependency on the optional auth-mfa feature.
@@ -161,13 +166,16 @@ export function createPersonalAccessTokensFeature(
     };
     const queries = {
       mine: r.queryHandler(listPatQuery),
+      availability: r.queryHandler(availabilityQuery),
       availableScopes: r.queryHandler(buildAvailableScopesQuery(scopes)),
     };
 
     // Declarative screens — list-with-revoke + mint-with-reveal. The app
     // places `patListScreen` via r.nav in its logged-in settings area.
-    r.screen(patListScreen);
-    r.screen(createPatMintScreen(scopes));
+    const lockedFallback =
+      options.lockedFallbackScreen === undefined ? {} : { fallback: options.lockedFallbackScreen };
+    r.screen({ ...patListScreen, ...lockedFallback });
+    r.screen({ ...createPatMintScreen(scopes), ...lockedFallback });
     r.translations({ keys: { ...PAT_FEATURE_I18N, ...patScopeOptionTranslations(scopes) } });
 
     // rateLimit flows into feature.exports so run-prod-app builds the

package/packages/bundled-features/src/personal-access-tokens/handlers/availability.query.ts

@@ -0,0 +1,20 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+
+// Screen gate probe: the dispatcher's feature gate rejects every handler of a
+// toggleable feature the tenant's tier does not include, so this query only
+// answers for tenants that may use tokens — a rejection makes the screens'
+// visibleWhen fall back instead of rendering an unusable token list.
+export const availabilityQuery = defineQueryHandler({
+  name: "availability",
+  schema: z.object({}),
+  access: {
+    openToAll: {
+      reason:
+        "constant answer that only exists to be gated by the feature toggle; it carries no user or tenant data",
+    },
+  },
+  description:
+    "Reports that personal access tokens are available to the caller's tenant; fails with feature_disabled when the tenant's tier excludes them. The token screens use it to decide whether to render.",
+  handler: async () => ({ enabled: true }),
+});

package/packages/bundled-features/src/personal-access-tokens/screens.ts

@@ -9,9 +9,18 @@ import type { PatScopeConfig } from "./scopes.js";
 
 const PAT_STATUS_OPTION_KEY_PREFIX = "pat.list.status.";
 
+// Both screens render only for tenants whose tier includes the feature; the
+// availability query is rejected by the feature gate otherwise.
+const PAT_SCREEN_VISIBLE_WHEN = {
+  query: PatQueries.availability,
+  field: "enabled",
+  eq: true,
+} as const;
+
 export const patListScreen: ProjectionListScreenDefinition = {
   id: PAT_SCREEN_ID,
   type: "projectionList",
+  visibleWhen: PAT_SCREEN_VISIBLE_WHEN,
   query: PatQueries.mine,
   // The `mine` handler honours `limit` only (no offset/total), so a pager would
   // show page 1 forever: send one max-size request and render no pager.
@@ -86,6 +95,7 @@ export function createPatMintScreen(scopes: PatScopeConfig): SecretMintScreenDef
   return {
     id: PAT_MINT_SCREEN_ID,
     type: "secretMint",
+    visibleWhen: PAT_SCREEN_VISIBLE_WHEN,
     handler: PatHandlers.create,
     fields: {
       name: { type: "text", required: true, maxLength: 120 },

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

@@ -1,4 +1,35 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "fix",
+    "title": "Webhook dispatch cancels the unread response body so a stalling receiver cannot hold the connection",
+    "detail": "Webhook dispatch releases the connection right after the status\nThe step-dispatcher only needs the response status, so it now cancels the unread response body instead of leaving the socket open until the 10 s request timeout fires."
+  },
+  {
+    "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",

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,110 +56,8 @@ 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 {
@@ -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;

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

@@ -115,8 +115,13 @@ export type WebhookDispatchDeps = {
   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.
@@ -124,16 +129,27 @@ const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not availa
 
 export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 
-function hasIdempotencyKeyHeader(headers: Readonly<Record<string, string>>): boolean {
-  return Object.keys(headers).some((name) => name.toLowerCase() === WEBHOOK_IDEMPOTENCY_KEY_HEADER);
+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 };
-  if (!hasIdempotencyKeyHeader(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 };
@@ -154,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 };
 }
@@ -215,8 +231,11 @@ 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,
     });
+    // Only the status is used; an unread body would pin the socket until the timeout fires.
+    await res.body?.cancel().catch(() => {});
     if (!res.ok) {
       return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
     }

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";
@@ -292,6 +297,7 @@ export function createTierEngineFeature<
         ],
       },
       submitLabel: "tier-admin.submit",
+      successMessage: "tier-admin.success",
       cancelTarget: false,
       description: "tier-admin.screen.subtitle",
       access: { roles: ["SystemAdmin"] },
@@ -450,7 +456,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,
           );

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

@@ -7,6 +7,7 @@ import {
 import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { tierAssignmentAggregateId } from "../aggregate-id.js";
+import { TierAssignmentSources } from "../constants.js";
 import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.js";
 
 // SystemAdmin setzt das Tier eines BELIEBIGEN Tenants — manueller Grant ohne
@@ -21,8 +22,8 @@ import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.js";
 // funktioniert nur für SYSTEM_TENANT_ID (immer im IN-Filter). Dies ist das
 // auto-default-Hook-Muster (feature.ts), generalisiert auf einen Request-Handler.
 //
-// `source: "manual"` markiert den Grant, damit ein späterer Stripe→Tier-Sync ihn
-// nicht plättet. Upsert: ein Aggregat pro Tenant (deterministische aggregate-id).
+// `source: TierAssignmentSources.manual` marks the grant so the billing sync skips it.
+// Upsert: one aggregate per tenant (deterministic aggregate id).
 //
 // Effective-set invalidation: the executor write does not fire the
 // `tier-assignment:postSave` entity hook, and a per-handler postSave would not
@@ -90,7 +91,7 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
           {
             id: existing.id,
             version: existing.version,
-            changes: { tier, source: "manual" },
+            changes: { tier, source: TierAssignmentSources.manual },
           },
           systemUser,
           tdb,
@@ -101,7 +102,12 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
       }
 
       const result = await executor.create(
-        { id: tierAssignmentAggregateId(tenantId), tier, source: "manual", tenantId },
+        {
+          id: tierAssignmentAggregateId(tenantId),
+          tier,
+          source: TierAssignmentSources.manual,
+          tenantId,
+        },
         systemUser,
         tdb,
       );

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

@@ -25,6 +25,7 @@ export const TIER_ENGINE_I18N: Readonly<Record<string, LocalizedString>> = {
   "tier-engine:entity:__action-form__:field:tenantId": { en: "Tenant" },
   "tier-engine:entity:__action-form__:field:tier": { en: "New tier" },
   "tier-admin.submit": { en: "Assign tier" },
+  "tier-admin.success": { en: "Tier assigned: {tenantId} → {tier}" },
 };
 
 export const defaultTranslations: TranslationsByLocale =

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

@@ -17,7 +17,12 @@ export {
   type TierDefinition,
   type TierMap,
 } from "./compose-app.js";
-export { TIER_ENGINE_FEATURE, TierEngineHandlers, TierEngineQueries } from "./constants.js";
+export {
+  TIER_ENGINE_FEATURE,
+  TierAssignmentSources,
+  TierEngineHandlers,
+  TierEngineQueries,
+} from "./constants.js";
 export { tierAssignmentEntity } from "./entity.js";
 export {
   type CreateTierEngineOptions,

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

@@ -51,7 +51,7 @@
     },
     {
       "name": "audit",
-      "description": "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
+      "description": "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection — the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       "toggleableDefault": null,
       "requires": [
         "tenant",

package/samples/recipes/webhook-step/README.md

@@ -5,7 +5,7 @@ Workflow / pipeline step that calls an HTTP webhook.
 ## What it shows
 
 - Webhook step registration in a workflow
-- Retry / failure surface for outbound HTTP
+- Failure surface for outbound HTTP (one delivery attempt per request)
 - Authenticated webhooks via a tenant-owned secret (`incident:open-authenticated`)
 
 ## Auth secret

package/samples/recipes/webhook-step/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-sample-webhook-step",
-  "description": "Tier-2 r.step.webhook.send showcase: deferred webhook dispatch via step-dispatcher subscription, no outbox table, retry from event-stream.",
+  "description": "Tier-2 r.step.webhook.send showcase: deferred webhook dispatch via step-dispatcher subscription, no outbox table.",
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",

package/samples/recipes/workflow-engine/README.md

@@ -1,11 +1,12 @@
 # Workflow Engine
 
-Tier-3 `defineWorkflow` vocabulary: wait, branch, mail, webhook, retry.
+Tier-3 `defineWorkflow` vocabulary: wait, branch, mail, webhook.
 
 ## What it shows
 
 - Real runnable pipelines (no empty `build: () => []` stubs)
-- Workflow-run lifecycle across wait / waitForEvent / retry
+- Workflow-run lifecycle across wait / waitForEvent
+- `webhook.send` is delivered once by the step-dispatcher; a failed delivery ends as `step.dispatch-failed`. Wrapping it in `r.step.retry` would not repeat it, because the step only enqueues the request and never throws on a delivery error
 
 ## Source
 

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

@@ -1,7 +1,7 @@
 // workflow-engine Sample — M.4 Tier-3 step-vocabulary showcase.
 //
-// Demonstrates defineWorkflow with wait, branch, mail.send, webhook.send,
-// retry, and the workflow-run lifecycle. Each workflow below is a real,
+// Demonstrates defineWorkflow with wait, branch, mail.send, webhook.send
+// and the workflow-run lifecycle. Each workflow below is a real,
 // runnable pipeline — no empty `build: () => []` stubs. The
 // integration-tests in __tests__/ exercise the suspension/resume cycle
 // against the in-memory fetcher and (separately) the postgres event-store.
@@ -17,7 +17,7 @@
 //     full HandlerContext surface. `r.step.read.findOne` works (db is
 //     present), `r.step.callFeature` does NOT yet (no `write`/`writeAs`
 //     on apply-ctx). Pipelines should stick to compute / branch / wait /
-//     retry / mail.send / webhook.send for now.
+//     mail.send / webhook.send for now.
 //   - The fetcher reads every suspension row whose wakeAt has expired
 //     (no `workflow_run_pending` read-side projection yet). Concurrency
 //     is safe via the event-store version-conflict path; performance is
@@ -98,28 +98,24 @@ export const userOnboardingWorkflow: WorkflowDefinition<{ email: string; userId:
   });
 
 /**
- * Retry-with-backoff workflow: wraps a deferred webhook in retry(3,
- * exponential). The retry step suspends the run between attempts and
- * the resume-loop re-enters it after the backoff window.
+ * Webhook-delivery workflow: one deferred webhook per `data.processed` event.
+ * `webhook.send` only enqueues a dispatch request; the step-dispatcher
+ * delivers it once and a failed delivery ends as `step.dispatch-failed`. A
+ * `retry` around it would never fire, because the step itself cannot throw
+ * on a delivery error.
  */
-export const resilientWebhookWorkflow: WorkflowDefinition<
+export const webhookDeliveryWorkflow: WorkflowDefinition<
   { data: unknown; webhookUrl: string },
   void
 > = defineWorkflow({
-  name: "resilient-webhook",
+  name: "webhook-delivery",
   trigger: { kind: "event", eventType: "data.processed" },
 
   steps: stepsPipeline<{ data: unknown; webhookUrl: string }, void>(({ r }) => [
-    r.step.retry({
-      times: 3,
-      backoff: "exponential",
-      do: [
-        r.step.webhook.send({
-          url: (ctx: PipelineCtx) => (ctx.event.payload as { webhookUrl: string }).webhookUrl,
-          body: (ctx: PipelineCtx) => (ctx.event.payload as { data: unknown }).data,
-          mode: "deferred",
-        }),
-      ],
+    r.step.webhook.send({
+      url: (ctx: PipelineCtx) => (ctx.event.payload as { webhookUrl: string }).webhookUrl,
+      body: (ctx: PipelineCtx) => (ctx.event.payload as { data: unknown }).data,
+      mode: "deferred",
     }),
     r.step.return({ isSuccess: true, data: undefined }),
   ]),
@@ -155,7 +151,7 @@ export const workflowEngineFeature = defineFeature("workflowEngine", (r) => {
   // The runtime only touches trigger/name/idempotencyKey + executes
   // the closure with the real event payload — payload-agnostic.
   registerEventTrigger(r, userOnboardingWorkflow as unknown as WorkflowDefinition);
-  registerEventTrigger(r, resilientWebhookWorkflow as unknown as WorkflowDefinition);
+  registerEventTrigger(r, webhookDeliveryWorkflow as unknown as WorkflowDefinition);
   // dailyReportWorkflow is cron-triggered — skip MSP registration
 });