@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -150,8 +150,8 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       // re-enrollment until an operator manually disables MFA. NOT fixed by
       // this ordering: burnToken() above still runs before this check, so a
       // mid-flight restricted/deleted user still burns their setup token
-      // (framework#1523/5) — moving the burn later would need care around
-      // the existing userId-unique-constraint backstop between the
+      // — moving the burn later would need care around the
+      // existing userId-unique-constraint backstop between the
       // `existing` check above and executor.create() below.
       const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
       const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
@@ -207,10 +207,10 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
         id: userId,
         tenantId,
         roles: mergedRoles,
-        // This endpoint logs the user in directly (fw#1760), so a stored
+        // This endpoint logs the user in directly, so a stored
         // timezone must survive the preauth-MFA-enrollment login just like
         // a plain password login does — same helper as verify.write.ts /
-        // invite-accept-with-login.write.ts (#1759).
+        // invite-accept-with-login.write.ts.
         ...sessionTimezoneField(userRow?.timezone),
         ...sessionLocaleField(userRow?.locale),
       };

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm.write.ts

@@ -56,8 +56,8 @@ export function createEnableConfirmHandler(opts: EnableConfirmOptions) {
       // already rules that out).
       if (verify.payload.userId !== event.user.id) return invalidSetupToken();
 
-      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
-      // (#1467): session-authed (lower risk — the caller already has a
+      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts:
+      // session-authed (lower risk — the caller already has a
       // valid JWT), but silently skipping the single-use burn here would
       // still let a double-confirm race complete twice instead of the
       // second seeing invalidSetupToken(). Checked before the TOTP verify

package/packages/bundled-features/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -55,7 +55,7 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       );
       // Same generic "sign in again" error as an expired/invalid MFA
       // challenge token — both mean the login-flow token expired, no
-      // distinct i18n needed (see #1465's scoping comment).
+      // distinct i18n needed.
       if (!verified.ok) return invalidChallengeToken();
       const { userId, tenantId } = verified.payload;
 

package/packages/bundled-features/src/auth-mfa/handlers/reencrypt.job.ts

@@ -154,7 +154,7 @@ export async function mfaReencryptJob(
 
     // After PII peel (when configured), values must be current-cipher
     // envelopes — non-JSON/non-envelope is not a supported legacy decrypt
-    // path (#1541, mirrors config #1513).
+    // path, matching config behavior.
     const totpClass = classifyStoredEnvelope(envelopeValues.totpSecret, targetVersion);
     const recoveryClass = classifyStoredEnvelope(envelopeValues.recoveryCodes, targetVersion);
     if (totpClass === "unrecognized" || recoveryClass === "unrecognized") {

package/packages/bundled-features/src/auth-mfa/handlers/regenerate-recovery.write.ts

@@ -47,11 +47,11 @@ export function createRegenerateRecoveryHandler(opts: RegenerateRecoveryOptions)
       // count, since either way the presented code is consumed/irrelevant
       // afterward.
       //
-      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
-      // (#1467): without ctx.redis, verifyMfaFactor's TOTP-replay burn is
-      // skipped, letting an observed code be replayed within the ±1-step
-      // window to regenerate (and thus invalidate) recovery codes — a
-      // session-authed route, so pre-unwiring JWTs stay a valid attack path.
+      // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts:
+      // without ctx.redis, verifyMfaFactor's TOTP-replay burn is skipped,
+      // letting an observed code be replayed within the ±1-step window to
+      // regenerate (and thus invalidate) recovery codes — a session-authed
+      // route, so pre-unwiring JWTs stay a valid attack path.
       if (!ctx.redis) {
         return writeFailure(
           new InternalError({

package/packages/bundled-features/src/auth-mfa/handlers/verify.write.ts

@@ -67,7 +67,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       if (!verified.ok) return invalidChallengeToken();
       const { userId, tenantId } = verified.payload;
 
-      // Fail closed, matching enable-confirm-preauth.write.ts (#1467):
+      // Fail closed, matching enable-confirm-preauth.write.ts:
       // this route sits behind a challenge token from a successful login,
       // but its own secret is still just a short TOTP/recovery code —
       // silently skipping the brute-force cap and single-use burn when

package/packages/bundled-features/src/auth-mfa/token-secrets.ts

@@ -18,7 +18,7 @@ const CHALLENGE_TOKEN_PURPOSE = "mfa-challenge-token-v1";
 
 // A blank or whitespace-only override is treated as absent — an empty env
 // var (MFA_SETUP_TOKEN_SECRET="") must fall back to derivation, not sign
-// tokens with an empty/near-empty HMAC key (fw#1623).
+// tokens with an empty/near-empty HMAC key.
 function resolveSecret(override: string | undefined, fallback: () => string): string {
   return override !== undefined && override.trim() !== "" ? override : fallback();
 }

package/packages/bundled-features/src/auth-mfa/web/client-plugin.ts

@@ -1,4 +1,4 @@
-// Client-Feature-Factory für auth-mfa — mirrors emailPasswordClient()'s
+// Client feature factory for auth-mfa — mirrors emailPasswordClient()'s
 // shape so apps register both the same way:
 // createKumikoApp({ clientFeatures: [emailPasswordClient(), authMfaClient()] }).
 // No gates: MfaVerifyScreen isn't a route gate, it's a state swap wired
@@ -12,7 +12,7 @@ import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "./i18n.ts";
 
 export type AuthMfaClientOptions = {
-  /** Key-Overrides pro Locale, gemerged mit den Default-Bundles (de/en). */
+  /** Key overrides per locale, merged with the default bundles (de/en). */
   readonly translations?: TranslationsByLocale;
 };
 

package/packages/bundled-features/src/auth-mfa/web/i18n.ts

@@ -1,6 +1,6 @@
-// Default-Bundles für die auth-mfa Feature-UI. Merged in mit
-// authMfaClient() analog zu emailPasswordClient() aus auth-email-password.
-// Keys folgen `auth.mfa.<area>.<slug>`.
+// Default bundles for the auth-mfa feature UI, merged by
+// authMfaClient() analogously to emailPasswordClient() from auth-email-password.
+// Keys follow `auth.mfa.<area>.<slug>`.
 
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 

package/packages/bundled-features/src/auth-mfa/web/index.ts

@@ -1,7 +1,7 @@
-// Public exports für die Browser-Seite des auth-mfa Features. Sub-Path-
-// Export `@cosmicdrift/kumiko-bundled-features/auth-mfa/web` — Server-Seite
-// (defineFeature) bleibt frei von React-/DOM-Deps, siehe auth-email-
-// password/web/index.ts für die selbe Trennung.
+// Public exports for the browser side of the auth-mfa feature. The subpath
+// export `@cosmicdrift/kumiko-bundled-features/auth-mfa/web` keeps the server
+// side (`defineFeature`) free of React/DOM dependencies, matching the same
+// separation in auth-email-password/web/index.ts.
 
 export type { AuthMfaClientFeature, AuthMfaClientOptions } from "./client-plugin.ts";
 export { authMfaClient } from "./client-plugin.ts";

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

@@ -1,10 +1,10 @@
-// Browser-Seite von POST /api/auth/mfa/verify — completes the two-step
-// login LoginScreen started when the server responded mfaRequired. Same
-// fetch/CSRF pattern as auth-email-password's login() (pre-session, no
-// csrfHeader() — there's no session yet to protect). Response shape is
+// Browser side of POST /api/auth/mfa/verify — completes the two-step
+// login that LoginScreen started when the server responded with mfaRequired.
+// Uses the same fetch/CSRF pattern as auth-email-password's login(), but runs
+// before a session exists, so it does not call csrfHeader(). The response is
 // byte-identical to /auth/login's ({isSuccess, token, user} | {isSuccess:
-// false, error}) since auth-routes.ts mints via the same
-// mintSessionAndRespond() for both routes.
+// false, error}) because auth-routes.ts uses mintSessionAndRespond() for both
+// routes.
 
 // kumiko-lint-ignore cross-feature-import client-only types, the feature's server barrel has no web/ re-export
 import {
@@ -76,11 +76,12 @@ export type MfaSetupPreauthStartResult =
   | { readonly kind: "success"; readonly data: MfaSetupPreauthStart }
   | { readonly kind: "failure"; readonly error: LoginFailure };
 
-// Browser-Seite von POST /api/auth/mfa/preauth-enable-start — lets a user
+// Browser side of POST /api/auth/mfa/preauth-enable-start — lets a user
 // blocked at login by MFA enforcement generate a TOTP secret/QR without a
-// session, using the preauthSetupToken login()'s mfa-setup-required result
-// carries. No JWT/cookie here (see auth-routes.ts's route comment) — the
-// response's setupToken is consumed by confirmMfaSetupPreauth below.
+// session, using the preauthSetupToken carried by login()'s
+// mfa-setup-required result. No JWT/cookie is issued here (see the route
+// comment in auth-routes.ts); the response's
+// setupToken is consumed by confirmMfaSetupPreauth below.
 export async function startMfaSetupPreauth(
   preauthSetupToken: string,
   accountLabel: string,
@@ -139,12 +140,12 @@ export async function startMfaSetupPreauth(
   };
 }
 
-// Browser-Seite von POST /api/auth/mfa/preauth-confirm — completes both
-// the enrollment startMfaSetupPreauth began and the login mfa-setup-
-// required block. Response shape mirrors /auth/mfa/verify's (mints via
-// the same mintSessionAndRespond()), same as verifyMfaChallenge above —
-// kept as its own function rather than a shared helper so this file's
-// two already-tested request shapes stay independently editable.
+// Browser side of POST /api/auth/mfa/preauth-confirm — completes both the
+// enrollment started by startMfaSetupPreauth and the login
+// mfa-setup-required block. Its response mirrors /auth/mfa/verify's and is
+// minted via the same mintSessionAndRespond(). It remains a separate function
+// so this file's two already-tested request shapes stay independently
+// editable.
 export async function confirmMfaSetupPreauth(
   setupToken: string,
   code: string,

package/packages/bundled-features/src/auth-mfa/web/mfa-verify-screen.tsx

@@ -1,9 +1,9 @@
-// Login-Challenge-Step, gerendert wenn LoginScreen's onMfaChallenge feuert
-// (/auth/login antwortete mfaRequired). Stilistisch wie login-screen.tsx:
-// useState + direkter fetch-Call, kein Dispatcher — es existiert noch kein
-// JWT. Nach Erfolg ruft es session.refresh() statt eines Hard-Reloads, weil
-// der Aufrufer (typisch ein Wizard-State im App-Root) sofort neu rendern
-// will, sobald status:"authenticated" ankommt.
+// Login challenge step, rendered when LoginScreen's onMfaChallenge fires
+// (/auth/login returned mfaRequired). It follows login-screen.tsx:
+// useState plus a direct fetch call, without a dispatcher because no JWT
+// exists yet. After success, it calls session.refresh() instead of a hard
+// reload so the caller (typically wizard state in the app root) can render
+// immediately when status:"authenticated" arrives.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";

package/packages/bundled-features/src/billing-foundation/aggregate-id.ts

@@ -1,12 +1,11 @@
 import { v5 as uuidv5 } from "uuid";
 
-// Fixed UUID-namespace für die deterministic aggregate-id-Ableitung.
-// Generiert einmalig (2026-05-03), in Stein gemeißelt: ein Wechsel
-// würde jeden existing aggregate-Stream re-keyen → kaputter
-// Subscription-State, kaputte Audit-History. Drift-Pin in
-// __tests__/feature.test.ts pinnt die UUID.
+// Fixed UUID namespace for deterministic aggregate-id derivation.
+// Generated once and immutable: changing it would re-key every existing
+// aggregate stream, breaking subscription state and audit history. The drift
+// pin in __tests__/feature.test.ts locks the UUID.
 
-/** Pro Plattform-Tenant existiert genau EIN subscription-Aggregate. */
+/** Exactly one subscription aggregate exists per platform tenant. */
 const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
 
 /** Exactly ONE payment-aggregate-stream exists per platform tenant (it
@@ -26,11 +25,11 @@ const PAYMENT_ROW_NAMESPACE = "3a1c9f4e-6b2d-4c8a-9e5f-7d4b1a2c8e6f";
 const TERMINATION_UNMATCHED_NAMESPACE = "7e2f4b9a-3c1d-4a68-8d05-b6c9e1f27a34";
 
 /**
- * Deterministic aggregate-id für die subscription eines Plattform-
- * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
- * derselben subscription, nicht eigene). Provider-Wechsel (z.B.
- * Stripe→Mollie-Migration) appended einen neuen event auf denselben
- * Stream — selber Tenant, selber Aggregate-Stream.
+ * Deterministic aggregate ID for a platform tenant's subscription. Exactly
+ * one subscription exists per tenant; add-ons are line items in that
+ * subscription, not separate aggregates. A provider change, such as a
+ * Stripe→Mollie migration, appends a new event to the same stream because
+ * the tenant and aggregate stream remain the same.
  */
 // @wrapper-known uuid-domain
 export function subscriptionAggregateId(tenantId: string): string {

package/packages/bundled-features/src/billing-foundation/entities.ts

@@ -4,39 +4,39 @@ import {
   createTextField,
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
-// `subscription` — current state pro Plattform-Tenant (= Read-Model)
+// `subscription` — current state per platform tenant (= read model)
 // =============================================================================
 //
-// Inline-Projection-Target. Geschrieben vom `subscription`-projection-
-// apply (siehe feature.ts), NIE direkt vom handler. Source-of-truth ist
-// der event-store stream `subscription` mit aggregate-id =
+// Inline projection target. Written by the `subscription` projection-
+// apply (see feature.ts), NEVER directly by the handler. Source of truth is
+// the event-store stream `subscription` with aggregate-id =
 // uuidv5(SUBSCRIPTION_NAMESPACE, tenantId).
 //
-// EINE Row pro Plattform-Tenant. Aggregate-ID ist deterministic, damit
-// Webhook-Replays (Stripe sendet bei Hängern bis zu 5x in 4h) auf
-// denselben Stream schreiben statt zwei Rows zu erzeugen.
+// ONE row per platform tenant. The aggregate ID is deterministic so that
+// webhook replays (Stripe sends up to 5 times in 4 hours when delivery is
+// stalled) write to the same stream instead of creating two rows.
 //
-// **Felder:**
-//   - providerName: "stripe" / "mollie" — welcher Provider die
-//     Subscription hält. Provider-Wechsel = neuer event auf demselben
-//     Stream, projection überschreibt.
-//   - providerCustomerId / providerSubscriptionId: provider-eigene
-//     IDs.
+// **Fields:**
+//   - providerName: "stripe" / "mollie" — the provider holding the
+//     subscription. A provider change is a new event on the same stream;
+//     the projection overwrites the value.
+//   - providerCustomerId / providerSubscriptionId: provider-specific IDs.
 //   - status: active / past_due / canceled / trialing / incomplete —
-//     normalisiert über provider-grenzen hinweg.
-//   - tier: "free" / "pro" / ... — vom tier-engine konsumiert. Aus
-//     price-to-tier-Map resolved im Plugin.
-//   - currentPeriodEnd: wann läuft die aktuelle Billing-Period aus.
+//     normalized across providers.
+//   - tier: "free" / "pro" / ... — consumed by the tier engine. Resolved
+//     from the price-to-tier map in the plugin.
+//   - currentPeriodEnd: when the current billing period ends.
 //   - cancelAt: when a scheduled cancellation ends the subscription;
 //     nullable because a renewing subscription has none.
 //
-// **Was hier NICHT ist:**
-//   - invoice-history, payment-method, line-items, tax-info → all das
-//     fetcht der Tenant via customer-portal-session direkt vom Provider.
+// **Not included here:**
+//   - invoice-history, payment-method, line-items, tax-info — the tenant
+//     fetches all of these directly from the provider via a
+//     customer-portal-session.
 //
-// **Audit/event-history:** lebt im event-store unter dem `subscription`-
-// stream — KEIN eigene `subscription-event`-Tabelle mehr (= ES ist die
-// audit-truth, replay-fähig durch upcasters).
+// **Audit/event history:** lives in the event store under the `subscription`
+// stream — there is NO separate `subscription-event` table (= ES is the
+// audit source of truth and can be replayed through upcasters).
 export const subscriptionEntity = createEntity({
   table: "read_subscriptions",
   fields: {
@@ -47,10 +47,10 @@ export const subscriptionEntity = createEntity({
       reason: "technical_reference",
     }),
     // `personal: "tenant"` (not `encrypted`): the field must crypto-shred when
-    // eraseSubjectKeys erases the tenant's subject key on tenant-destroy
-    // (#800). `encrypted: true` uses the app-wide master key instead — that
+    // eraseSubjectKeys erases the tenant's subject key on tenant-destroy.
+    // `encrypted: true` uses the app-wide master key instead — that
     // key is never erased per-tenant, so it would only add encryption-at-
-    // rest, not the erasure guarantee #800 actually asks for.
+    // rest, not the erasure guarantee.
     // maxLength 1000, not 200: the stored value is PII-ciphertext
     // (`kumiko-pii:v1:<subject>:<blob>`), not the raw provider id — a
     // 200-char plaintext id becomes ~300+ chars of ciphertext. Matches
@@ -112,7 +112,7 @@ export const paymentEntity = createEntity({
       reason: "technical_reference",
     }),
     // Same `personal: "tenant"` rationale as subscriptionEntity above —
-    // crypto-shreds on tenant-destroy (#800) via eraseSubjectKeys.
+    // crypto-shreds on tenant-destroy via eraseSubjectKeys.
     providerCustomerId: createTextField({
       required: true,
       maxLength: 1000,

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -1,25 +1,25 @@
-// Domain-events für subscription-foundation.
+// Domain events for subscription-foundation.
 //
-// **Pattern:** event-sourced — jeder Provider-Webhook (nach Plugin-
-// verify) wird zu einem domain-event auf dem subscription-stream
-// (= ein stream pro Tenant via subscriptionAggregateId(tenantId)).
-// Read-model = inline projection in `subscriptions`-Tabelle.
+// **Pattern:** event-sourced — each provider webhook (after plugin
+// verification) becomes a domain event on the subscription stream
+// (= one stream per tenant via subscriptionAggregateId(tenantId)).
+// The read model is an inline projection in the `subscriptions` table.
 //
-// 5 fine-grained event-typen statt einem generic "webhook-received"-
-// bucket — events sind business-facts: future-consumer (billing-history,
-// accounting-export, churn-analytics) listenen direkt auf den event-
-// type ohne payload-discriminator.
+// Five fine-grained event types instead of a generic "webhook-received"
+// bucket — events are business facts: future consumers (billing-history,
+// accounting-export, churn-analytics) listen directly for the event type
+// without a payload discriminator.
 
 import * as z from "zod";
 import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./web/constants.ts";
 import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.ts";
 
-// Aggregate-type für den event-store. Eine subscription pro Tenant ist
-// ein stream; der subscriptionAggregateId-helper liefert die stream-id.
+// Aggregate type for the event store. One subscription per tenant is
+// one stream; the subscriptionAggregateId helper provides the stream ID.
 export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
 
-// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
-// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
+// Event-name constants — short form (for r.defineEvent) and qualified
+// FQN (for ctx.unsafeAppendEvent and projection-apply keys).
 export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created" as const;
 export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated" as const;
 export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled" as const;
@@ -37,7 +37,7 @@ export const INVOICE_PAID_EVENT_QN =
 export const INVOICE_PAYMENT_FAILED_EVENT_QN =
   `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAYMENT_FAILED_EVENT_SHORT}` as const;
 
-// Status-enum für event-payloads (= subscription-state-snapshot vom Provider).
+// Status enum for event payloads (= the provider's subscription-state snapshot).
 const statusEnum = z.enum([
   SubscriptionStatuses.active,
   SubscriptionStatuses.trialing,
@@ -46,10 +46,11 @@ const statusEnum = z.enum([
   SubscriptionStatuses.incomplete,
 ]);
 
-// Common payload — alle 5 events tragen denselben subscription-state-
-// snapshot. Event-type tagged was passiert ist, payload den state-after.
+// Common payload — all five events carry the same subscription-state
+// snapshot. The event type identifies what happened; the payload contains
+// the resulting state.
 // The raw provider event is deliberately not stored: it carries plaintext
-// PII and event headers are not crypto-shreddable.
+// PII, and event headers cannot be crypto-shredded.
 export const subscriptionEventPayloadSchema = z.object({
   providerName: z.string().min(1).max(50),
   // 1000, not 200: these two are `tenantOwned: true` on the entity (see
@@ -72,10 +73,10 @@ export const subscriptionEventPayloadSchema = z.object({
 });
 export type SubscriptionEventPayload = z.infer<typeof subscriptionEventPayloadSchema>;
 
-// Headers-shape — wird im event-store als event.metadata.headers
-// persistiert (open-shape jsonb-column, primitives only).
-// Idempotency-anchor: providerEventId pro provider, foundation checked
-// vor append ob bereits gesehen.
+// Header shape — persisted in the event store as event.metadata.headers
+// (an open-shape JSONB column containing primitives only).
+// Idempotency anchor: providerEventId is checked per provider before append
+// to determine whether it has already been seen.
 export type SubscriptionEventHeaders = {
   readonly providerEventId: string;
   readonly providerName: string;

package/packages/bundled-features/src/billing-foundation/feature.ts

@@ -1,54 +1,53 @@
 // kumiko-feature-version: 1
 //
-// subscription-foundation als Kumiko bundled feature (Plugin-Host).
+// subscription-foundation as a Kumiko bundled feature (plugin host).
 //
-// **Multi-Provider von Tag 1** — der App-Builder kann mehrere Plugins
-// parallel mounten (subscription-stripe + subscription-paypal +
-// subscription-apple-iap + ...) und der Endkunde wählt beim Subscribe-
-// Klick zwischen Karte/PayPal/Apple-Pay/Klarna/SEPA (Disney+-Pattern).
-// KEIN globaler `provider`-config-key — alle gemounteten Plugins sind
-// aktiv.
+// **Multi-provider from day one** — the app builder can mount multiple plugins
+// in parallel (subscription-stripe + subscription-paypal +
+// subscription-apple-iap + ...), and the end user chooses between
+// card/PayPal/Apple Pay/Klarna/SEPA at checkout (Disney+ pattern).
+// There is no global `provider` config key — all mounted plugins are active.
 //
-// **Was diese Foundation liefert:**
-//   1. **Plugin-API** für Subscription-Provider via `r.extendsRegistrar(
+// **What this foundation provides:**
+//   1. **Plugin API** for subscription providers via `r.extendsRegistrar(
 //      "subscriptionProvider", ...)`.
-//   2. **5 Domain-Events** auf dem `subscription`-stream (eine
-//      stream-id pro Tenant): created/updated/canceled/invoice-paid/
-//      invoice-payment-failed. Audit-history kommt frei vom event-store.
-//   3. **Inline-Projection** auf `read_subscriptions` (= current state
-//      pro Tenant). Apply läuft in derselben TX wie der event-append
+//   2. **5 domain events** on the `subscription` stream (one stream ID per
+//      tenant): created/updated/canceled/invoice-paid/invoice-payment-failed.
+//      Audit history is provided automatically by the event store.
+//   3. **Inline projection** onto `read_subscriptions` (current state per
+//      tenant). Apply runs in the same TX as the event append
 //      → read-your-own-write semantics.
-//   4. **process-event-handler**: programmatic write-handler den der
-//      webhook-handler aufruft, dispatcht zu type-passendem appendEvent.
+//   4. **process-event handler**: a programmatic write handler called by the
+//      webhook handler that dispatches to the type-matched appendEvent.
 //   5. **createSubscriptionWebhookRoute**: factory for the `entry:"signature"`
 //      extraRoute `/api/subscription/webhook/:providerName`.
-//   6. **payment-received event + read_payments projection**: one-off-
-//      payments (checkout mode "payment") get their own event, own
-//      per-tenant aggregate, and own `process-payment-event` write-handler
-//      — not a sixth SubscriptionEventTypes value (fw#2791).
+//   6. **payment-received event + read_payments projection**: one-off payments
+//      (checkout mode "payment") get their own event, per-tenant aggregate,
+//      and `process-payment-event` write handler — not a sixth
+//      SubscriptionEventTypes value.
 //   7. **Optional billing-plans catalog** (`createBillingFoundationFeature({
 //      baseUrl, catalog })`): a `billing-foundation:query:billing-plans`
-//      query plus `start-plan-checkout`/`switch-plan` write-handlers and a
+//      query plus `start-plan-checkout`/`switch-plan` write handlers and a
 //      dormant `billing-plans` dashboard screen/panel, all derived from the
-//      one `catalog` option — no separate per-app price wiring.
+//      single `catalog` option — no separate per-app price wiring.
 //
-// **Was diese Foundation NICHT macht:**
-//   - Kein r.entity für `subscription`. Die Tabelle ist eine reine
-//     Read-Projection — kein CRUD-Pfad. Schreibt wird ausschließlich
-//     via projection-apply, getriggert von einem der 5 events.
-//   - Kein Tier-Sync zum tier-engine. App-Owner liest die subscription-
-//     row via `getSubscriptionForTenant(ctx, tenantId)` wenn er möchte.
-//   - Keine provider-spezifischen Configs.
-//   - Kein Marketplace-Use-Case (App-Tenant billed Endkunden via
-//     Stripe Connect). Kommt als separate `marketplace-foundation`.
+// **What this foundation does NOT do:**
+//   - No r.entity for `subscription`. The table is a read-only projection —
+//     there is no CRUD path. It is written exclusively via projection-apply,
+//     triggered by one of the 5 events.
+//   - No tier sync with tier-engine. App owners can read the subscription row
+//     via `getSubscriptionForTenant(ctx, tenantId)` if needed.
+//   - No provider-specific configs.
+//   - No marketplace use case (the app tenant bills end customers via Stripe
+//     Connect). That comes later as a separate `marketplace-foundation`.
 //
-// **Provider-Wechsel:** Disney+-Pattern (= Tenant cancelt Stripe-sub,
-// startet neue mit PayPal) wird heute als zweiter `subscription-created`-
-// event modelliert. UPSERT in der projection-apply überschreibt den
-// existing row mit dem neuen providerName. Reicht für MVP. Wenn das
-// business-fact "Provider-Wechsel" ein eigenes domain-event braucht
-// (z.B. für analytics: "wie viele Wechsel im Monat?"), kommt ein
-// `subscription-provider-changed`-event-type später.
+// **Provider changes:** The Disney+ pattern (the tenant cancels a Stripe
+// subscription and starts a new one with PayPal) is currently modeled as a
+// second `subscription-created` event. UPSERT in projection-apply overwrites
+// the existing row with the new providerName. This is sufficient for the MVP.
+// If the business fact "provider change" needs its own domain event (for
+// example, for analytics such as "how many changes per month?"), a
+// `subscription-provider-changed` event type can be added later.
 
 import {
   defineFeature,
@@ -199,19 +198,19 @@ export function createBillingFoundationFeature<TTier extends string = string>(
         },
       });
 
-      // Plugin extension-point. Provider-Plugins registrieren sich hier.
+      // Plugin extension point. Provider plugins register here.
       r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
         onRegister: () => {
           // No side-effects at register-time.
         },
       });
 
-      // Custom write-handlers:
-      //   - process-event: programmatic entry-point vom webhook-handler;
-      //     dispatcht zu type-passendem appendEvent
+      // Custom write handlers:
+      //   - process-event: programmatic entry point called by the webhook
+      //     handler; dispatches to the type-matched appendEvent
       //   - create-checkout-session: bare priceId-driven checkout (hardened,
       //     see checkout-core)
-      //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
+      //   - create-portal-session: Tenant Admin "Manage Subscription" flow
       r.writeHandler(createProcessEventHandler(widened.now));
       r.writeHandler(createCheckoutSessionHandler(widened));
       r.writeHandler(createPortalSessionHandler(widened));

package/packages/bundled-features/src/billing-foundation/get-subscription-for-tenant.ts

@@ -1,6 +1,4 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-// Resolver-helper: liest die current subscription-row für einen Tenant
-// aus der read_subscriptions-projection.
 
 import {
   configuredPiiSubjectKms,
@@ -27,9 +25,9 @@ export type SubscriptionView = {
   readonly lastChangedAt: Temporal.Instant;
 };
 
-/** Liefert die einzige subscription-row für den Tenant (deterministic
- *  aggregate-id), oder null wenn der Tenant nie subscribed hat. Status
- *  kann active/canceled/past_due/etc sein — Caller entscheidet was tun. */
+/** Returns the tenant's only subscription row (deterministic
+ *  aggregate ID), or null if the tenant has never subscribed. The status
+ *  may be active/canceled/past_due/etc.; the caller decides what to do. */
 export async function getSubscriptionForTenant(
   ctx: HandlerContext,
   tenantId: string,