@cosmicdrift/kumiko-bundled-features 0.344.0 → 0.346.0

package/dist/billing-foundation/subscription-tier-sync.js

@@ -2,7 +2,7 @@
 // near-identical webhook-route.ts app copies in show-pony and publicstatus
 // (infra#446) — the only per-app variables were the TierName union/default,
 // so it is now a factory parameter.
-import { TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { TierAssignmentSources, TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
 import { subscriptionAggregateId } from "./aggregate-id.js";
 import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.js";
 import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
@@ -25,6 +25,13 @@ function asRows(result) {
     }
     throw new Error("expected a { rows: [...] } list-query result");
 }
+function findTierAssignment(rows, tenantId) {
+    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(deps) {
     async function syncTierFromSubscription(tenantId, routeDeps) {
         try {
@@ -43,13 +50,15 @@ export function createSubscriptionTierSync(deps) {
                 payload: {},
                 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) {
@@ -60,14 +69,16 @@ export function createSubscriptionTierSync(deps) {
                 }
                 return null;
             }
-            if (assignment["tier"] === effective)
+            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/dist/step-dispatcher/dispatch-payload.d.ts

@@ -0,0 +1,49 @@
+import * as z from "zod";
+import { type MailSpec } from "./mail-runner.js";
+import { type WebhookSpec } from "./webhook-runner.js";
+export declare const dispatchRequestedPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    stepKind: z.ZodLiteral<"webhook.send">;
+    url: z.ZodString;
+    method: z.ZodEnum<{
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>;
+    headersJson: z.ZodString;
+    bodyJson: z.ZodOptional<z.ZodString>;
+    auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"bearer">;
+        secret: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"header">;
+        name: z.ZodString;
+        secret: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodObject<{
+    stepKind: z.ZodLiteral<"mail.send">;
+    to: z.ZodString;
+    subject: z.ZodString;
+    body: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "stepKind">;
+type DispatchRequestedPayload = z.infer<typeof dispatchRequestedPayloadSchema>;
+export declare function rawStepKindOf(payload: unknown): string;
+type PayloadFieldName = "to" | "subject" | "body" | "from" | "url" | "headersJson" | "bodyJson";
+type ReadPayloadResult = {
+    readonly kind: "ready";
+    readonly fields: Readonly<Partial<Record<PayloadFieldName, string>>>;
+} | {
+    readonly kind: "erased";
+} | {
+    readonly kind: "unreadable";
+};
+export declare function readPayloadFields(payload: DispatchRequestedPayload): Promise<ReadPayloadResult>;
+type DispatchSpec = {
+    readonly stepKind: "mail.send";
+    readonly spec: MailSpec;
+} | {
+    readonly stepKind: "webhook.send";
+    readonly spec: WebhookSpec;
+};
+export declare function buildDispatchSpec(payload: DispatchRequestedPayload, fields: Readonly<Partial<Record<PayloadFieldName, string>>>): DispatchSpec | null;
+export {};

package/dist/step-dispatcher/dispatch-payload.js

@@ -0,0 +1,115 @@
+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 { mailSpecSchema } from "./mail-runner.js";
+import { 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(),
+    }),
+]);
+const rawStepKindSchema = z.object({ stepKind: z.string() });
+export function rawStepKindOf(payload) {
+    const parsed = rawStepKindSchema.safeParse(payload);
+    return parsed.success ? parsed.data.stepKind : "unknown";
+}
+const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
+    try {
+        const parsed = 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);
+function piiFieldsOf(payload) {
+    return payload.stepKind === "mail.send"
+        ? ["to", "subject", "body", "from"]
+        : ["url", "headersJson", "bodyJson"];
+}
+function payloadFieldValue(payload, field) {
+    const values = 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];
+}
+export async function readPayloadFields(payload) {
+    const kms = configuredPiiSubjectKms();
+    const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+    const fields = {};
+    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 };
+}
+// Parse failures return null — the caller records a generic error, never the
+// (decrypted) values.
+export function buildDispatchSpec(payload, fields) {
+    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;
+    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/dist/step-dispatcher/feature.js

@@ -7,14 +7,15 @@
 // or `kumiko:system:step.dispatch-failed` back onto the same stream so
 // 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, STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, } from "@cosmicdrift/kumiko-framework/engine";
 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 { mailSpecSchema, performMailDispatch } from "./mail-runner.js";
-import { performWebhookDispatch, WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR, WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS, webhookSpecSchema, } from "./webhook-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, } from "./webhook-runner.js";
 const log = createFallbackLogger("step-dispatcher");
 export const stepDispatcherEnvSchema = z.object({
     [WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
@@ -23,30 +24,6 @@ export const stepDispatcherEnvSchema = z.object({
         .describe("Comma-separated operator allowlist of private/internal hosts (e.g. a local webhook-receiver for dev/test) that bypass the public-address check for webhook.send targets. Never a tenant-config value."),
 });
 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(),
-    }),
-]);
 // 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";
@@ -55,96 +32,12 @@ const PAYLOAD_UNREADABLE_ERROR = "dispatch payload is not readable";
 // dispatch-failed text outlives the payload erase, so only this is persisted.
 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) {
-    const parsed = rawStepKindSchema.safeParse(payload);
-    return parsed.success ? parsed.data.stepKind : "unknown";
-}
-const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
-    try {
-        const parsed = 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);
-function piiFieldsOf(payload) {
-    return payload.stepKind === "mail.send"
-        ? ["to", "subject", "body", "from"]
-        : ["url", "headersJson", "bodyJson"];
-}
-function payloadFieldValue(payload, field) {
-    const values = 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];
-}
-async function readPayloadFields(payload) {
-    const kms = configuredPiiSubjectKms();
-    const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
-    const fields = {};
-    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 };
-}
-// Parse failures return null — the caller records a generic error, never the
-// (decrypted) values.
-function buildDispatchSpec(payload, fields) {
-    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;
-    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) {
+    return e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE;
 }
 export function createStepDispatcherFeature() {
     return defineFeature("step-dispatcher", (r) => {
-        r.describe("Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.");
+        r.describe("Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.");
         r.secretNamespace("webhook-auth", WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS);
         r.uiHints({
             displayLabel: "Step Dispatcher · Deferred Side-Effects",
@@ -159,9 +52,16 @@ export function createStepDispatcherFeature() {
                 [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
                     const kms = configuredPiiSubjectKms();
                     const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+                    const eraseDispatchKey = async () => {
+                        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, payload) => {
                         await ctx.unsafeAppendEvent({
                             aggregateId: event.aggregateId,
@@ -169,9 +69,15 @@ export function createStepDispatcherFeature() {
                             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, error) => 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);
@@ -186,11 +92,6 @@ export function createStepDispatcherFeature() {
                         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;
@@ -206,6 +107,7 @@ export function createStepDispatcherFeature() {
                             tenantId: event.tenantId,
                             userId: event.metadata.userId || SYSTEM_USER_ID,
                             secrets: ctx.secrets,
+                            idempotencyKey: event.aggregateId,
                         })
                         : await performMailDispatch(dispatchSpec.spec);
                     if (result.ok) {

package/dist/step-dispatcher/webhook-runner.d.ts

@@ -45,5 +45,9 @@ export type WebhookDispatchDeps = {
     readonly tenantId: TenantId;
     readonly userId: string;
     readonly secrets: SecretsContext | undefined;
+    readonly idempotencyKey: string;
+    readonly requestTimeoutMs?: number;
 };
+export declare const WEBHOOK_REQUEST_TIMEOUT_MS = 10000;
+export declare const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 export declare function performWebhookDispatch(spec: WebhookSpec, deps: WebhookDispatchDeps): Promise<WebhookDispatchResult>;

package/dist/step-dispatcher/webhook-runner.js

@@ -79,12 +79,34 @@ let fetchImpl = globalThis.fetch.bind(globalThis);
 export function setWebhookFetch(fn) {
     fetchImpl = fn;
 }
+// One hanging tenant-controlled receiver must not stall the shared
+// step-dispatcher consumer for every tenant.
+export const WEBHOOK_REQUEST_TIMEOUT_MS = 10_000;
 // Never includes the secret name or value — spec.auth.secret is a
 // tenant-chosen name, but the error still reaches the tenant via the
 // dispatch-failed event, so it stays generic.
 const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
+export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+function hasHeader(headers, lowerCaseName) {
+    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, name, value) {
+    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, deps) {
-    const headers = { "content-type": "application/json", ...spec.headers };
+    const headers = { ...spec.headers };
+    if (!hasHeader(headers, "content-type"))
+        headers["content-type"] = "application/json";
+    if (!hasHeader(headers, WEBHOOK_IDEMPOTENCY_KEY_HEADER)) {
+        headers[WEBHOOK_IDEMPOTENCY_KEY_HEADER] = deps.idempotencyKey;
+    }
     if (!spec.auth)
         return { ok: true, headers };
     if (!deps.secrets)
@@ -107,10 +129,10 @@ async function buildWebhookHeaders(spec, deps) {
         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 };
 }
@@ -159,6 +181,7 @@ export async function performWebhookDispatch(spec, deps) {
             ...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/dist/tier-engine/constants.d.ts

@@ -4,6 +4,11 @@ export declare const TierEngineHandlers: {
     readonly update: "tier-engine:write:tier-assignment:update";
     readonly setTenantTier: "tier-engine:write:set-tenant-tier";
 };
+export declare const TierAssignmentSources: {
+    readonly manual: "manual";
+    readonly billing: "billing";
+    readonly default: "default";
+};
 export declare const TierEngineQueries: {
     readonly list: "tier-engine:query:tier-assignment:list";
     readonly getActiveTier: "tier-engine:query:get-active-tier";

package/dist/tier-engine/constants.js

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

package/dist/tier-engine/entity.js

@@ -31,10 +31,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/dist/tier-engine/feature.js

@@ -50,7 +50,7 @@ import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { tenantTable } from "../tenant/index.js";
 import { tierAssignmentAggregateId } from "./aggregate-id.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";
@@ -347,7 +347,7 @@ export function createTierEngineFeature(opts = {}) {
                     roles: ["SystemAdmin"],
                 };
                 const tdb = createTenantDb(rawDb, newTenantId, "system");
-                await tierAssignmentExecutor.create({ id: aggregateId, tier: defaultTier, source: "default" }, systemUser, tdb);
+                await tierAssignmentExecutor.create({ id: aggregateId, tier: defaultTier, source: TierAssignmentSources.default }, systemUser, tdb);
             }, { phase: HookPhases.inTransaction, escapeHatch: { reason: autoDefaultTierHookReason } });
         }
         // Extension-point declaration + self-registration. Pattern analog

package/dist/tier-engine/handlers/set-tenant-tier.write.js

@@ -3,6 +3,7 @@ import { buildEntityTable, createEventStoreExecutor, createTenantDb, } from "@co
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { tierAssignmentAggregateId } from "../aggregate-id.js";
+import { TierAssignmentSources } from "../constants.js";
 import { tierAssignmentEntity } from "../entity.js";
 // SystemAdmin setzt das Tier eines BELIEBIGEN Tenants — manueller Grant ohne
 // Billing. Cross-tenant, daher SystemAdmin-only (kein TenantAdmin: sonst
@@ -16,8 +17,8 @@ import { 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
@@ -67,14 +68,19 @@ export function createSetTenantTierWrite(opts = {}) {
                 const result = await executor.update({
                     id: existing.id,
                     version: existing.version,
-                    changes: { tier, source: "manual" },
+                    changes: { tier, source: TierAssignmentSources.manual },
                 }, systemUser, tdb);
                 if (!result.isSuccess)
                     return result;
                 afterCommit(tenantId, tier);
                 return { isSuccess: true, data: { tenantId, tier, isNew: false } };
             }
-            const result = await executor.create({ id: tierAssignmentAggregateId(tenantId), tier, source: "manual", tenantId }, systemUser, tdb);
+            const result = await executor.create({
+                id: tierAssignmentAggregateId(tenantId),
+                tier,
+                source: TierAssignmentSources.manual,
+                tenantId,
+            }, systemUser, tdb);
             if (!result.isSuccess)
                 return result;
             afterCommit(tenantId, tier);

package/dist/tier-engine/index.d.ts

@@ -1,6 +1,6 @@
 export { tierAssignmentAggregateId } from "./aggregate-id.js";
 export { type AddOnDefinition, type AddOnMap, type ComposeAppInput, type ComposedApp, composeApp, 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, createTierEngineFeature, tierEngineFeature, } from "./feature.js";
 export { createTierResolver, type TierResolver, type TierResolverDeps, } from "./tier-resolver.js";

package/dist/tier-engine/index.js

@@ -8,7 +8,7 @@
 //   - `TierEngineHandlers` / `TierEngineQueries` — qualified handler names
 export { tierAssignmentAggregateId } from "./aggregate-id.js";
 export { composeApp, } 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 { createTierEngineFeature, tierEngineFeature, } from "./feature.js";
 export { createTierResolver, } from "./tier-resolver.js";