@cosmicdrift/kumiko-samples 0.345.0 → 0.346.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.345.0",
+  "version": "0.346.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.346.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/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,29 @@
 [
+  {
+    "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,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,
           );

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/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:*",