@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.339.0

package/dist/workflow-runner/handlers/resume-run.write.js

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

package/dist/workflow-runner/pending-projection.js

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

package/dist/workflow-runner/runner.d.ts

@@ -1,9 +1,14 @@
 import type { HandlerContext, StepInstance, WorkflowDefinition, WriteEvent } from "@cosmicdrift/kumiko-framework/engine";
 export declare function isResumableSuspension(steps: readonly StepInstance[], stepIndex: number): boolean;
+export type TriggerEventRef = {
+    readonly eventId: string;
+    readonly aggregateId: string;
+    readonly version: number;
+};
 export type WorkflowRunStartedPayload = {
     readonly workflowName: string;
     readonly triggerEventType: string;
-    readonly triggerPayload: unknown;
+    readonly triggerEventRef: TriggerEventRef;
     readonly definitionFingerprint: string;
     readonly idempotencyKey?: string;
 };
@@ -35,6 +40,7 @@ export declare function startAndRunWorkflow(args: {
     readonly runId: string;
     readonly workflow: WorkflowDefinition;
     readonly triggerEvent: WriteEvent;
+    readonly triggerEventRef: TriggerEventRef;
     readonly idempotencyKey?: string;
     readonly handlerCtx: HandlerContext;
 }): Promise<{

package/dist/workflow-runner/runner.js

@@ -42,7 +42,7 @@ export async function startAndRunWorkflow(args) {
     const startedPayload = {
         workflowName: args.workflow.name,
         triggerEventType: args.triggerEvent.type,
-        triggerPayload: args.triggerEvent.payload,
+        triggerEventRef: args.triggerEventRef,
         definitionFingerprint: fingerprint,
         ...(args.idempotencyKey && { idempotencyKey: args.idempotencyKey }),
     };

package/dist/workflow-runner/tables.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.337.1",
+  "version": "0.339.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>",
@@ -365,6 +365,22 @@
       "types": "./dist/channel-push/index.d.ts",
       "default": "./dist/channel-push/index.js"
     },
+    "./channel-slack": {
+      "types": "./dist/channel-slack/index.d.ts",
+      "default": "./dist/channel-slack/index.js"
+    },
+    "./channel-discord": {
+      "types": "./dist/channel-discord/index.d.ts",
+      "default": "./dist/channel-discord/index.js"
+    },
+    "./channel-teams": {
+      "types": "./dist/channel-teams/index.d.ts",
+      "default": "./dist/channel-teams/index.js"
+    },
+    "./channel-telegram": {
+      "types": "./dist/channel-telegram/index.d.ts",
+      "default": "./dist/channel-telegram/index.js"
+    },
     "./renderer-simple": {
       "types": "./dist/renderer-simple/index.d.ts",
       "default": "./dist/renderer-simple/index.js"
@@ -483,12 +499,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.337.1",
-    "@cosmicdrift/kumiko-framework": "0.337.1",
-    "@cosmicdrift/kumiko-headless": "0.337.1",
-    "@cosmicdrift/kumiko-renderer": "0.337.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.337.1",
-    "@cosmicdrift/kumiko-types": "0.337.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.339.0",
+    "@cosmicdrift/kumiko-framework": "0.339.0",
+    "@cosmicdrift/kumiko-headless": "0.339.0",
+    "@cosmicdrift/kumiko-renderer": "0.339.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.339.0",
+    "@cosmicdrift/kumiko-types": "0.339.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -859,6 +875,22 @@
         "types": "./dist/channel-push/index.d.ts",
         "default": "./dist/channel-push/index.js"
       },
+      "./channel-slack": {
+        "types": "./dist/channel-slack/index.d.ts",
+        "default": "./dist/channel-slack/index.js"
+      },
+      "./channel-discord": {
+        "types": "./dist/channel-discord/index.d.ts",
+        "default": "./dist/channel-discord/index.js"
+      },
+      "./channel-teams": {
+        "types": "./dist/channel-teams/index.d.ts",
+        "default": "./dist/channel-teams/index.js"
+      },
+      "./channel-telegram": {
+        "types": "./dist/channel-telegram/index.d.ts",
+        "default": "./dist/channel-telegram/index.js"
+      },
       "./renderer-simple": {
         "types": "./dist/renderer-simple/index.d.ts",
         "default": "./dist/renderer-simple/index.js"
@@ -985,8 +1017,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.337.1",
-    "@cosmicdrift/kumiko-locale-es": "0.337.1",
+    "@cosmicdrift/kumiko-locale-de": "0.339.0",
+    "@cosmicdrift/kumiko-locale-es": "0.339.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/agent-tools/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "entity get/list tools honour agent.risk, PII-bearing system lists are high risk",
+    "detail": "agent-tools: `get_<entity>` and `list_<entity>` take their risk from the entity handler's `agent.risk` instead of a hard-coded `low`. The SystemAdmin `user:list`, `user:detail` and `download-attempt:list` handlers declare `risk: \"high\"`.",
+    "migration": "No action needed: handlers without an agent.risk hint stay low risk."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "agent entity tools no longer filter on read-restricted fields",
+    "detail": "agent-tools: `list_<entity>` filters and `find_<entity>_by_<field>` tools only offer filterable fields that every caller role may read without a row condition. A role- or ownership-restricted filterable field can no longer be probed through `totalCount` or hit/miss results.",
+    "migration": "No action needed: fields whose access.read is not unconditionally open to the agent's roles drop out of list filters and find-by tools."
+  },
   {
     "version": "0.337.0",
     "type": "fix",

package/src/auth-email-password/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "emailPasswordClient({ loginUrl, postLogoutUrl }) sends unauthenticated visitors to an external login page with a same-origin next path and navigates there on logout",
+    "detail": "emailPasswordClient accepts loginUrl and postLogoutUrl for external login pages",
+    "migration": "No code change needed."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/src/billing-foundation/changes.json

@@ -1,4 +1,87 @@
 [
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Missing or unchecked checkout consent returns 422 consent_required",
+    "detail": "The consent payload is optional in the `start-plan-checkout` and `create-checkout-session` input schemas and its two flags are plain booleans. `prepareConsent` throws `UnprocessableError(\"consent_required\")` with `billing-foundation.errors.consentRequired` when consumer protection is on and the consent is missing or either flag is not true.",
+    "migration": "Clients that treated the previous `400` validation error for a missing consent as the signal must check for `422` with `reason: \"consent_required\"`."
+  },
+  {
+    "version": "0.339.0",
+    "type": "fix",
+    "title": "Contract confirmation, termination receipt and cancellation pages use \"du\"",
+    "detail": "The German contract confirmation mail, the termination and withdrawal receipt mail, the public cancellation pages and the subscription and payment submit messages address the customer with \"du\". The recorded consent statements are first-person and unchanged, so `consentTextVersion` stays the same."
+  },
+  {
+    "version": "0.339.0",
+    "type": "fix",
+    "title": "The § 312k confirm POST forwards the visitor's host to /api/write",
+    "detail": "The `/legal/kuendigen` and `/legal/cancel` pages re-enter `/api/write` through the app. The re-entry now carries `Host`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Tenant` and the `kumiko_tenant` cookie as the visitor sent them, so a host-based `tenantResolver` resolves the same tenant as for a direct call; before, it saw no host and every confirm failed with `400 tenant_required`. The session cookie, `Authorization` and `X-Forwarded-For` are not forwarded.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "consumerProtection.terminationScope \"platform\" for hosts without a tenant",
+    "detail": "`consumerProtection.terminationScope` is `\"tenant-host\"` (default, unchanged) or `\"platform\"`. With `\"platform\"`, `request-contract-termination` is flagged `tenantlessAnonymous` and also runs on a host whose resolver returns no tenant: it finds the contract by the declarant's email as before, records on the matched tenant's subscription stream, and answers every outcome identically. An unknown option value fails at `createBillingFoundationFeature`.",
+    "migration": "Apps that serve the pages on a platform apex (publicstatus) set `consumerProtection.terminationScope: \"platform\"`. Other apps change nothing."
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Public termination declarations cancel at the provider in a job",
+    "detail": "For the public channel, `request-contract-termination` no longer calls the provider in the request. A matched request appends the PII-free `contract-termination-declared` event (`requestId`, `declarationType`, `terminationKind`, `receivedAtIso`, `locale`) via the system-only `declare-contract-termination`; the job `cancel-on-public-termination-declared` then runs `record-contract-termination`, which asks the provider for `cancel_at_period_end` and appends `contract-termination-requested` with the outcome. Matched and unmatched requests do the same work in the request, so the response time does not reveal whether the email is a customer. The job is idempotent per `requestId`. A provider without `cancelSubscription`, a provider error or a missing subscription now sends a separate operator notice with request id and tenant id but no name or email. A public withdrawal still makes no provider call. The account path (`terminate-contract`) stays synchronous.",
+    "migration": "Code that expected `contract-termination-requested` right after the public request must wait for the job (in tests: `drainJobs`)."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Contract confirmation mail after a recorded checkout consent",
+    "detail": "With `consumerProtection`, four event-triggered jobs (`confirm-on-subscription-created`, `confirm-on-subscription-updated`, `confirm-on-invoice-paid`, `confirm-on-payment-received`) call the system-only `billing-foundation:write:issue-contract-confirmation` (`consentId`, `sourceAggregateId`, optional `currentPeriodEndIso`) for events carrying a `consentId`; subscription events only count with status `active` or `trialing`. The handler only reads the caller tenant's own subscription or payment stream, finds the `checkout-consent-recorded` event, appends `contract-confirmation-issued` (`consentId`, `issuedAtIso`, `locale`, `termsTemplateVersion`) at the fetched stream version and then notifies `billing-foundation:contract-confirmation` (critical priority) to the consenting user's email. A second run returns `{ issued: false, reason: \"already_issued\" }` or fails with a version conflict; an unknown consent returns `consent_not_found` and sends nothing. The mail is rendered in German or English (fallback German) as structured header/sections content for the email channel's renderer.",
+    "migration": "Enabling `consumerProtection` additionally requires the `user` feature, and an email channel plus renderer must be mounted for the mail to go out."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Optional consumer-protection consent gate on checkout",
+    "detail": "`BillingFoundationOptions.consumerProtection` (`termsTextBlock`, `vatNote` with `de` and `en`, `operatorEmail`, `legalLinks`) requires `baseUrl` and additionally requires the `template-resolver` and `delivery` features. When set, `start-plan-checkout` and `create-checkout-session` take a strict `consent` object (`earlyPerformanceRequested: true`, `withdrawalLossAcknowledged: true`, `consentTextVersion`, `locale`); a missing or unchecked consent fails validation (400). The consent texts and their version (first 16 hex characters of the SHA-256 of the early-performance and withdrawal-loss texts) are owned by the framework in German and English. After the provider returned the checkout URL, `checkout-consent-recorded` is appended (no email, no IP). `billing-plans` returns `consumerProtection: { consentTexts, legalLinks }` so a client can render and echo the version.",
+    "migration": "No code change needed unless you enable consumerProtection; then callers of start-plan-checkout/create-checkout-session must send `consent`."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Consent dialog and cancel-contract button in the billing panel",
+    "detail": "The checkout CTA opens `CheckoutConsentDialog` when `billing-plans` returns `consumerProtection`; `start-plan-checkout` then receives `consent: { earlyPerformanceRequested, withdrawalLossAcknowledged, consentTextVersion, locale }`. The locale rule (`resolveConsentLocale`) moved to the crypto-free `consumer-protection/consent-locale.ts` and is still re-exported from `consent-text.ts`. `CancelContractDialog` calls `billing-foundation:write:terminate-contract`. New English i18n keys under `billing-foundation.consent.*` and `billing-foundation.cancel.*`.",
+    "migration": "No action. Apps that translate the panel add the new `billing-foundation.consent.*` and `billing-foundation.cancel.*` keys to their locale bundles."
+  },
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "SubscriptionProviderPlugin.cancelSubscription takes { providerSubscriptionId, when }",
+    "detail": "`cancelSubscription(ctx, { providerSubscriptionId, when })` replaces the positional `providerSubscriptionId` argument. `when` is `SubscriptionCancelTimings.periodEnd` (`\"period-end\"`, the subscription runs to the end of the paid period) or `SubscriptionCancelTimings.immediately` (`\"immediately\"`). `createCheckoutSession` options gain optional `consentId`, `locale` and `submitMessage`; `SubscriptionEvent` and `PaymentEvent` gain an optional `consentId`, validated by `parseProviderConsentId` (max 100 characters of `A-Z a-z 0-9 _ -`), and `subscription` / `payment` event payloads store it.",
+    "migration": "Custom provider plugins that implement `cancelSubscription` change the signature to `(ctx, { providerSubscriptionId, when })` and honor `when`. A provider that can only cancel immediately may treat both values the same or leave the method out. Callers pass `{ providerSubscriptionId, when: SubscriptionCancelTimings.immediately }` to keep the old behavior."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "§ 312k cancellation pages and handlers with consumerProtection",
+    "detail": "`contract-termination-requested` (on the tenant's subscription stream: `requestId`, `declarationType` termination|withdrawal, `terminationKind` ordinary|extraordinary, `channel` public|account, `receivedAtIso`, `effectiveAtIso`, `providerCancel` period-end|immediately|none) and `contract-termination-unmatched` (system-tenant stream, `matchResult` none|ambiguous) are appended by the system-only `record-contract-termination` and `record-unmatched-contract-termination` handlers. `billing-foundation:write:request-contract-termination` is anonymous and answers `{ requestId, receivedAtIso }` for every outcome; `billing-foundation:write:terminate-contract` (purchase roles) answers `{ requestId, receivedAtIso, effectiveAtIso, providerCancel }`. Provider errors or a provider without `cancelSubscription` still record the declaration (`providerCancel: none`) and notify the operator. `consumerProtection` now also requires the `tenant` and `user` features.",
+    "migration": "Add `createContractTerminationRoutes()` from billing-foundation to the app's `extraRoutes`, make sure `anonymousAccess` is configured, and link `/legal/kuendigen` (or `/legal/cancel`) in the page footer."
+  },
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "Remove rawPayload from provider events and event headers",
+    "detail": "`rawPayload` is removed from `SubscriptionEvent`, `PaymentEvent`, `ProviderSubscriptionSnapshot`, the `process-event` and `process-payment-event` schemas and `SubscriptionEventHeaders` / `PaymentEventHeaders`. New events carry `providerEventId` and `providerName` in their headers; payment events also carry the optional `providerCheckoutId` (Stripe checkout session id).",
+    "migration": "Custom subscription provider plugins must stop returning `rawPayload`; TypeScript flags the removed field. Code that read the checkout session id out of `headers.rawPayload` reads `headers.providerCheckoutId` instead. Events already stored keep their old `rawPayload` header; this release does not rewrite stored events."
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "late events of a superseded provider subscription no longer overwrite the live row",
+    "detail": "billing-foundation: `process-event` drops a non-`created` provider event that belongs to a different subscription than the one the tenant's row currently tracks, while that row still blocks checkout. A late webhook retry of a superseded subscription can no longer flip the live subscription to `canceled`. The webhook answers 200 with `stale: true`.",
+    "migration": "No action needed: events of the tracked subscription and `created` events behave as before."
+  },
   {
     "version": "0.335.0",
     "type": "breaking",

package/src/cap-counter/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "corrected the documented reason rolling cap booking needs SystemAdmin",
+    "detail": "cap-counter: corrected the documented reason why rolling cap booking still needs a `SystemAdmin` identity. The event-ownership check only guards `appendDomainEventCore`, not the entity-executor path, so the earlier \"ownership rule rejects in-process appends\" wording was inaccurate. Behavior is unchanged.",
+    "migration": "No action needed: behavior is unchanged."
+  },
   {
     "version": "0.336.0",
     "type": "fix",

package/src/cap-overview/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "breaking",
+    "title": "caps:usage and my-caps default to admin roles; widen with usageVisibleTo",
+    "detail": "`createCapOverviewFeature` gets `usageVisibleTo?: readonly string[]`. Without it, the `caps:usage` query and the `my-caps` screen accept `access.admin` (TenantAdmin, Admin, SystemAdmin) instead of every tenant member. The screen and the query share the resolved roles. Only built-in roles are accepted (User, Member, Editor, Admin, TenantAdmin, SystemAdmin); an unknown or empty list throws at feature definition. The SystemAdmin `tenantId` override and the platform-wide screens are unchanged. The `MY_CAPS_ACCESS_ROLES` export is replaced by `DEFAULT_CAP_USAGE_ROLES` (the admin default), and `myCapsScreen` by `createMyCapsScreen(roles)`.",
+    "migration": "Apps whose regular members should keep seeing their usage pass `createCapOverviewFeature({ ..., usageVisibleTo: [\"User\", \"Editor\", \"Admin\", \"TenantAdmin\", \"SystemAdmin\"] })`. Code that imported `MY_CAPS_ACCESS_ROLES` (handlers or nav entries mirroring the screen rule) imports `DEFAULT_CAP_USAGE_ROLES` for the admin default, or reuses the same `usageVisibleTo` array it passed to the feature."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "Cross-tenant cap limits read the target tenant's config",
+    "detail": "`caps:usage` with a SystemAdmin `tenantId` override and `tenant-caps:list` passed the caller's config accessor to `CapSpec.limit`, so a limit that reads a tenant-scoped config key showed the caller's value for every tenant. Both now resolve one accessor per target tenant through `ctx.configFor`, and `tenant-caps:list` resolves each tenant's limit separately instead of once per tier.",
+    "migration": "No code change needed."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/src/config/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "config keys can declare an async write validator that rejects with a KumikoError",
+    "detail": "Config key definitions accept a new async `validate(value, ctx)` function. `config:write:set` runs it after the type, bounds and pattern checks and before the value is stored, for every scope and backing. A validator rejects the write by throwing a `KumikoError`, for example an `UnprocessableError`. The feature manifest reports `validated` per key.",
+    "migration": "No action needed: keys without `validate` behave as before."
+  },
   {
     "version": "0.335.0",
     "type": "breaking",

package/src/crypto-shredding/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "forget-denied audit digest is keyed and omitted without a blind-index key",
+    "detail": "crypto-shredding: the forget-denied audit event now stores `subjectKeyDigest` as a keyed blind-index HMAC instead of a bare SHA-256 of the subject key, so a candidate id cannot be matched against it. Without a configured blind-index key the digest is omitted (`subjectKeyDigest` is now optional in the payload).",
+    "migration": "No action needed. Existing denial events keep their old digest; configure the blind-index key to get a digest on new ones."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "forget-subject tenant check falls back to event-store provenance",
+    "detail": "forget-subject now accepts a record subject for a DPO when the owning tenant is proven by the event stream, not only by a projection row. A record whose row was already deleted, or a custom aggregate without a registered entity, can be shredded by the DPO of the tenant that owns it. A DPO of another tenant is still denied, and so is any DPO when events for the same aggregate id exist in more than one tenant."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/src/custom-fields/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "field-definition list keeps TenantAdmin when fieldDefinitionWriteRoles is set",
+    "detail": "custom-fields: the field-definition list roles always include the default `TenantAdmin`, also when `fieldDefinitionWriteRoles` is set. `TenantAdmin` keeps saving values by default, so the form section must keep loading for it; `fieldDefinitionWriteRoles: []` no longer locks out the list.",
+    "migration": "No action needed. Set fieldDefinitionListRoles explicitly to narrow the list roles."
+  },
   {
     "version": "0.146.0",
     "type": "improvement",

package/src/delivery/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Slack, Discord, Microsoft Teams and Telegram delivery channels",
+    "detail": "`channel-slack`, `channel-discord`, `channel-teams` and `channel-telegram` register route-only delivery channels. Webhook URLs and the Telegram bot token live in the tenant's secrets; the send job reads them with an audit entry `<feature>:send`. `DeliveryChannel.resolve` is optional and `ChannelContext.secrets` is available on the send job path.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "tenant broadcast recipient query no longer reads across tenants through ctx.db",
+    "detail": "delivery: the `tenantUserIdsQuery` handler of a tenant broadcast now always gets a tenant-filtered `ctx.db` and `ctx.dbOutsideTransaction`, also when it is declared `r.systemScope()`. A systemScope handler could previously read the memberships of every tenant through `ctx.db` and notify users of foreign tenants. Cross-tenant reads stay available through `ctx.systemDb`.",
+    "migration": "No action needed for handlers that resolve recipients through `ctx.systemDb`, like `tenant:query:resolveUserIds`. A systemScope handler that read `ctx.db` unfiltered now sees only the broadcast tenant's rows."
+  },
   {
     "version": "0.336.0",
     "type": "fix",