@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

@@ -1,26 +1,26 @@
 import { v5 as uuidv5 } from "uuid";
 
-// Fixed UUID-namespaces für deterministic aggregate-id-Ableitung.
-// Generiert einmalig (2026-07-12), in Stein gemeißelt: ein Wechsel würde
-// jeden existing aggregate-Stream re-keyen → kaputte Message-Historie,
-// kaputte Idempotency. Drift-Pins in __tests__/feature.test.ts.
+// Fixed UUID namespaces for deterministic aggregate-ID derivation.
+// Generated once (2026-07-12) and immutable: changing one would re-key
+// every existing aggregate stream, breaking message history and idempotency.
+// Drift is pinned in __tests__/feature.test.ts.
 
-/** Namespace für inbound-message-Streams. */
+/** Namespace for inbound-message streams. */
 const INBOUND_MESSAGE_NAMESPACE = "7f2a9c41-3d6b-4e0f-9c58-2b1e7a4d8f63";
 
-/** Namespace für mail-thread-Streams. */
+/** Namespace for mail-thread streams. */
 const MAIL_THREAD_NAMESPACE = "b48d1e72-5c9a-4f36-8e0d-6a3f9b2c7e15";
 
 /**
- * Deterministic aggregate-id für eine inbound-message. Key ist
- * (accountId, providerMessageId): derselbe Provider-Fetch der zweimal
- * dieselbe Message liefert (IDLE-Doppel-Notify, Cursor-Overlap,
- * Watch-Restart-Replay) landet auf demselben Stream — der Idempotency-
- * Check im ingest-handler sieht den bereits appendeten Event.
+ * Deterministic aggregate ID for an inbound message. The key is
+ * (accountId, providerMessageId): if the provider delivers the same message
+ * twice (IDLE duplicate notification, cursor overlap, watch-restart replay),
+ * both deliveries use the same stream, so the idempotency check in the
+ * ingest handler sees the event that was already appended.
  *
- * accountId (nicht tenantId) im Key: zwei Accounts desselben Tenants
- * können dieselbe Mail empfangen (CC an beide Postfächer) — das sind
- * fachlich ZWEI inbound-messages.
+ * accountId, rather than tenantId, is part of the key because two accounts in
+ * the same tenant can receive the same email (CC'd to both inboxes); these
+ * are two distinct inbound messages.
  */
 // @wrapper-known uuid-domain
 export function inboundMessageAggregateId(accountId: string, providerMessageId: string): string {
@@ -28,11 +28,11 @@ export function inboundMessageAggregateId(accountId: string, providerMessageId:
 }
 
 /**
- * Deterministic aggregate-id für einen mail-thread. Key ist
- * (tenantId, threadKey) — Threads sind tenant-weit, nicht account-weit:
- * eine Konversation die über zwei verbundene Postfächer läuft ist EIN
- * Thread. threadKey kommt normalisiert vom Provider (References/
- * In-Reply-To-Chain bzw. Provider-Thread-ID).
+ * Deterministic aggregate ID for a mail thread. The key is
+ * (tenantId, threadKey): threads are tenant-wide, not account-specific, so a
+ * conversation spanning two connected inboxes is one thread. threadKey is
+ * normalized by the provider (References/In-Reply-To chain or provider
+ * thread ID).
  */
 // @wrapper-known uuid-domain
 export function mailThreadAggregateId(tenantId: string, threadKey: string): string {

package/packages/bundled-features/src/inbound-mail-foundation/connect-routes.ts

@@ -1,5 +1,5 @@
-// createInboundMailConnectRoutes — declarative extraRoutes (kumiko-
-// framework#3050) the app owner mounts via `extraRoutes` in buildServer.
+// createInboundMailConnectRoutes — declarative extraRoutes the app owner mounts
+// via `extraRoutes` in buildServer.
 //
 //   GET /api/inbound-mail/connect      (entry:"user" — signed-in caller)
 //   GET /inbound-mail/oauth/callback   (entry:"signature" — anonymous,
@@ -17,6 +17,7 @@ import type {
   UserExtraRouteDeps,
 } from "@cosmicdrift/kumiko-framework/api";
 import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { Context } from "hono";
 import {
   INBOUND_MAIL_FOUNDATION_FEATURE,
@@ -241,7 +242,7 @@ export function createInboundMailConnectRoutes(
       if (!dispatched.isSuccess) {
         return errorJson(c, 502, "account_create_failed", JSON.stringify(dispatched.error ?? {}));
       }
-      const accountId = (dispatched.data as { accountId?: unknown } | undefined)?.accountId;
+      const accountId = propertyOf(dispatched.data, "accountId");
       if (typeof accountId !== "string") {
         return errorJson(c, 502, "account_create_failed", "connect-account returned no accountId");
       }

package/packages/bundled-features/src/inbound-mail-foundation/constants.ts

@@ -1,71 +1,69 @@
 // Feature name
 export const INBOUND_MAIL_FOUNDATION_FEATURE = "inbound-mail-foundation" as const;
 
-// Extension-point name für Provider-Plugins (inbound-provider-imap,
+// Extension-point name for provider plugins (inbound-provider-imap,
 // inbound-provider-m365-graph, inbound-provider-gmail-rest, ...).
 export const INBOUND_MAIL_PROVIDER_EXTENSION = "inboundMailProvider" as const;
 
 // Qualified write handler names (QN format: scope:type:name).
 export const InboundMailFoundationHandlers = {
-  /** Programmatic entry-point für Provider-Plugins (watch-callback +
-   *  fetchSince-Sync): normalisierte Message rein, Idempotency +
-   *  PII-encrypt + event-append + Thread-Update atomic. */
+  /** Programmatic entry point for provider plugins (watch callback +
+   *  fetchSince sync): accepts a normalized message and atomically performs
+   *  idempotency handling, PII encryption, event append, and thread update. */
   ingestMessage: "inbound-mail-foundation:write:ingest-message",
-  /** Tenant-Admin verbindet ein Postfach (IMAP-Credentials via secrets
-   *  oder OAuth-Redirect via oauth-routes). Legt den mail-account-Stream
-   *  an. */
+  /** Tenant admin connects a mailbox (IMAP credentials via secrets or an
+   *  OAuth redirect via oauth-routes). Creates the mail-account stream. */
   connectAccount: "inbound-mail-foundation:write:connect-account",
-  /** Account-Status-Übergänge (watch error/backoff, oauth-refresh
-   *  failed, re-enabled). */
+  /** Account status transitions (watch error/backoff, OAuth refresh
+   *  failure, re-enabled). */
   updateAccount: "inbound-mail-foundation:write:update-account",
-  /** Tenant-Admin trennt ein Postfach. Stream bleibt (Audit), Status
-   *  wird disconnected, Watch stoppt. */
+  /** Tenant admin disconnects a mailbox. The stream remains for auditing;
+   *  the status becomes disconnected and the watch stops. */
   disconnectAccount: "inbound-mail-foundation:write:disconnect-account",
 } as const;
 
 // Qualified query handler names.
 export const InboundMailFoundationQueries = {
-  /** Tenant-scoped Liste der verbundenen Postfächer. */
+  /** Tenant-scoped list of connected mailboxes. */
   listAccounts: "inbound-mail-foundation:query:account:list",
-  /** Tenant-scoped Message-Liste (Inbox-Cockpit). PII wird beim Read
-   *  decrypted. */
+  /** Tenant-scoped message list (inbox cockpit). PII is decrypted on read.
+   */
   listMessages: "inbound-mail-foundation:query:message:list",
 } as const;
 
 // Normalized account status values — provider-agnostic.
 export const InboundMailAccountStatuses = {
-  /** Verbunden, Watch/Sync läuft (oder ist startbereit). */
+  /** Connected; watch/sync is running or ready to start. */
   active: "active",
-  /** Credentials/Token ungültig — Tenant-Admin muss re-connecten. */
+  /** Credentials or token are invalid; the tenant admin must reconnect. */
   authError: "auth_error",
   /** Transienter Fehler, Supervisor backoff-retried. */
   degraded: "degraded",
-  /** Vom Tenant-Admin getrennt. Keine Syncs mehr. */
+  /** Disconnected by the tenant admin; no further syncs run. */
   disconnected: "disconnected",
 } as const;
 export type InboundMailAccountStatus =
   (typeof InboundMailAccountStatuses)[keyof typeof InboundMailAccountStatuses];
 
 /**
- * Tenant-Secret-Slot eines Accounts: IMAP-App-Passwort ODER OAuth-
- * Refresh-Token — der Provider interpretiert den Inhalt gemäß
- * `authMethod` (Plan §4). Dynamisches Keying pro Account ist vom
- * secrets-Feature gedeckt: SecretsContext.get/set nehmen beliebige
- * String-Keys (resolveKey in secrets-context.ts) — Plan-Risiko 4
- * verifiziert, kein Framework-Gap.
+ * Tenant secret slot for an account: IMAP app password OR OAuth refresh
+ * token. The provider interprets the contents according to `authMethod`.
+ * Dynamic per-account keying is supported by the secrets feature:
+ * SecretsContext.get/set accept arbitrary string keys (resolveKey in
+ * secrets-context.ts), so no framework change is required.
  */
 export function inboundCredentialSecretKey(accountId: string): string {
   return `${INBOUND_MAIL_FOUNDATION_FEATURE}:inbound.credential.${accountId}`;
 }
 
-// Auth-Methode eines Accounts — vom connect-Flow gesetzt, von Providern
-// gelesen (imap unterscheidet hierüber Passwort-Formular vs. XOAUTH2-
-// Fallback, Plan §2).
+// Authentication method for an account, set by the connect flow and read
+// by providers (IMAP uses it to distinguish the password form from the
+// XOAUTH2 fallback).
 export const InboundMailAuthMethods = {
   /** Formular-Connect: Config (host/port/secure) + Tenant-Secret. */
   password: "password",
-  /** SASL XOAUTH2 über IMAP — Fallback für M365/Gmail-Konten ohne
-   *  gemounteten Enterprise-Provider (gleicher Secret-Slot). */
+  /** SASL XOAUTH2 over IMAP — fallback for M365/Gmail accounts without a
+   *  mounted enterprise provider (same secret slot). */
   xoauth2: "xoauth2",
   /** Nativer OAuth-Provider (m365-graph, gmail-rest). */
   oauth: "oauth",
@@ -73,8 +71,7 @@ export const InboundMailAuthMethods = {
 export type InboundMailAuthMethod =
   (typeof InboundMailAuthMethods)[keyof typeof InboundMailAuthMethods];
 
-// **Multi-Provider von Tag 1:** KEIN globaler `provider`-config-key
-// (anders als mail-foundation, gleich wie billing-foundation). Ein Tenant
-// kann parallel ein IMAP-Postfach UND ein M365-Postfach verbinden — der
-// Provider steht pro MailAccount-Row (`provider`-Feld), gesetzt beim
-// connect-Flow.
+// **Multi-provider:** no global `provider` config key
+// (unlike mail-foundation, as with billing-foundation). A tenant can connect
+// an IMAP mailbox and an M365 mailbox in parallel; the provider is stored per
+// MailAccount row (`provider` field) and set by the connect flow.

package/packages/bundled-features/src/inbound-mail-foundation/entities.ts

@@ -9,28 +9,27 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 
 // ============================================================================
-// Read-Models der drei event-sourced Aggregates
+// Read models for the three event-sourced aggregates
 // ============================================================================
 //
-// Inline-Projection-Targets. Geschrieben AUSSCHLIESSLICH von den
-// projection-applies (siehe feature.ts), nie direkt vom handler.
-// Source-of-truth sind die event-store-Streams `mail-account` /
-// `inbound-message` / `mail-thread` — die Tabellen sind rebuild-fähig.
+// Inline projection targets. Written EXCLUSIVELY by projection applies
+// (see feature.ts), never directly by the handler.
+// The event-store streams `mail-account` / `inbound-message` / `mail-thread`
+// are the source of truth, so these tables can be rebuilt.
 //
 // **PII convention:** `personal: "tenant"` (not `encrypted`): fields must
-// crypto-shred when eraseSubjectKeys deletes the tenant subject key on
-// tenant-destroy (#800 pattern from billing-foundation).
-// maxLength jeweils Ciphertext-budgetiert (`kumiko-pii:v1:<subject>:
-// <blob>` — Plaintext×~2.3 + Envelope-Overhead).
+// be crypto-shredded when eraseSubjectKeys deletes the tenant subject key on
+// tenant destruction (pattern from billing-foundation).
+// maxLength is budgeted for ciphertext (`kumiko-pii:v1:<subject>:
+// <blob>` — Plaintext×~2.3 + envelope overhead).
 //
-// **Offene Design-Frage aus dem Plan (§3.4):** PII-Subject einer
-// Inbound-Mail ist vorerst der TENANT (Postfach-Inhaber), nicht der
-// externe Absender — ein Absender-Forget-Flow bräuchte per-Sender-Keys
-// und ist bewusst NICHT Teil von Phase 1 (dokumentierte Entscheidung,
-// Erasure-Pfad ist tenant-destroy).
+// **Design decision:** The PII subject of an inbound mail is currently the
+// TENANT (mailbox owner), not the external sender. A sender-forget flow would
+// require per-sender keys and is deliberately not included; the erasure path
+// is tenant destruction.
 
-/** Ein verbundenes Postfach. Eine Row pro Account, PK = aggregateId
- *  (= accountId, random uuid beim connect). */
+/** A connected mailbox. One row per account, with PK = aggregateId
+ *  (= accountId, random uuid on connect). */
 export const mailAccountEntity = createEntity({
   table: "read_mail_accounts",
   fields: {
@@ -46,10 +45,10 @@ export const mailAccountEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
-    // null = tenant-geteiltes Postfach (info@), gesetzt = persönliches
-    // Postfach dieses Users. Sichtbarkeits-Filter in den list-queries:
-    // Owner + TenantAdmin (Compliance); KEIN Crypto-Subject-Wechsel in
-    // V1 (Subject bleibt Tenant, siehe Header).
+    // null = tenant-shared mailbox (info@), set = this user's personal
+    // mailbox. Visibility filters in the list queries:
+    // Owner + TenantAdmin (compliance); NO crypto-subject change in
+    // V1 (subject remains Tenant, see header).
     ownerUserId: createTextField({ maxLength: 36, personal: false, reason: "pseudonymous_fk" }),
     // Tenant-authored mailbox label, not a person's name.
     displayName: createTextField({
@@ -57,7 +56,7 @@ export const mailAccountEntity = createEntity({
       personal: false,
       reason: "tenant_config_not_personal",
     }),
-    // Postfach-Adresse — PII des Tenants.
+    // Mailbox address — tenant PII.
     address: createTextField({ required: true, maxLength: 1000, personal: "tenant", find: "none" }),
     status: createTextField({
       required: true,
@@ -70,8 +69,8 @@ export const mailAccountEntity = createEntity({
   },
 });
 
-/** Eine eingegangene Mail (Envelope + Snippet, KEIN Body — bodyRef
- *  zeigt auf file-foundation). PK = aggregateId =
+/** An incoming mail (envelope + snippet, NO body — bodyRef
+ *  points to file-foundation). PK = aggregateId =
  *  inboundMessageAggregateId(accountId, providerMessageId). */
 export const inboundMessageEntity = createEntity({
   table: "read_inbound_messages",
@@ -82,9 +81,9 @@ export const inboundMessageEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
-    // Scope-Vererbung vom Account zum Ingest-Zeitpunkt — Messages eines
-    // persönlichen Postfachs sind nur für den Owner (+ TenantAdmin)
-    // sichtbar, ohne Join auf read_mail_accounts.
+    // Scope is inherited from the account at ingest time: messages from a
+    // personal mailbox are visible only to the owner (+ TenantAdmin),
+    // without joining read_mail_accounts.
     ownerUserId: createTextField({ maxLength: 36, personal: false, reason: "pseudonymous_fk" }),
     messageIdHeader: createTextField({
       required: true,
@@ -127,29 +126,29 @@ export const mailThreadEntity = createEntity({
   },
 });
 
-// Single source of truth für die PII-Feld-Listen — encrypt (ingest/
-// connect-handler) und decrypt (list-queries) teilen dieselbe Liste,
-// damit ein künftiges weiteres tenantOwned-Feld nicht an einer der
-// Stellen vergessen wird (Muster billing-foundation entities.ts).
+// Single source of truth for the PII field lists — encrypt (ingest/
+// connect-handler) and decrypt (list-queries) share the same list,
+// so a future tenantOwned field cannot be omitted in either location
+// (pattern from billing-foundation entities.ts).
 export const MAIL_ACCOUNT_PII_FIELDS = collectPiiSubjectFields(mailAccountEntity);
 export const INBOUND_MESSAGE_PII_FIELDS = collectPiiSubjectFields(inboundMessageEntity);
 export const MAIL_THREAD_PII_FIELDS = collectPiiSubjectFields(mailThreadEntity);
 
 // ============================================================================
-// Unmanaged Direct-Write-Stores — Sync-Maschinerie, NICHT event-sourced
+// Unmanaged direct-write stores — sync machinery, NOT event-sourced
 // ============================================================================
 //
-// SyncCursor + SeenMessage sind technischer Tick-State des Watch/Sync-
-// Loops: hochfrequente Writes ohne Business-Fakt-Charakter. Als r.entity
-// würden sie (a) das Event-Log fluten und (b) beim Projection-Rebuild
-// gewischt (Direct-Write ohne Event → Rebuild findet nichts, #494/#498-
-// Klasse). Deshalb r.unmanagedTable — Migration-DDL ja, Rebuild-Target
-// nein (Muster sessions/feature.ts).
+// SyncCursor + SeenMessage are technical tick state for the watch/sync
+// loops: high-frequency writes without business-fact semantics. As
+// r.entity, they would (a) flood the event log and (b) be wiped during a
+// projection rebuild (direct write without an event means the rebuild finds
+// nothing). Therefore r.unmanagedTable — migration DDL, but not a rebuild
+// target (pattern from sessions/feature.ts).
 
-/** Provider-Cursor pro Account ("wo war ich?"): IMAP UIDVALIDITY:UIDNEXT,
- *  Graph deltaLink, Gmail historyId. Eine Row pro (accountId, scope).
- *  Write-locked auf privileged — nur Foundation-Handler/Supervisor
- *  schreiben, kein Tenant-Request. */
+/** Provider cursor per account ("where was I?"): IMAP UIDVALIDITY:UIDNEXT,
+ *  Graph deltaLink, Gmail historyId. One row per (accountId, scope).
+ *  Write-locked to privileged — only Foundation handlers/supervisors
+ *  write it; tenant requests cannot. */
 export const syncCursorEntity = createEntity({
   table: "store_mail_sync_cursors",
   softDelete: false,
@@ -182,10 +181,10 @@ export const syncCursorEntity = createEntity({
   },
 });
 
-/** Dedup-Anchor für O(1)-Idempotency ohne Stream-Scan bei sehr langen
- *  Message-Historien: (accountId, providerMessageId) UNIQUE. Der
- *  ingest-handler prüft zuerst hier (cheap), der Stream-Scan bleibt
- *  Defense-in-depth. */
+/** Deduplication anchor for O(1) idempotency without scanning the stream
+ *  for very long message histories: (accountId, providerMessageId) UNIQUE.
+ *  The ingest handler checks here first (cheap); the stream scan remains
+ *  defense-in-depth. */
 export const seenMessageEntity = createEntity({
   table: "store_mail_seen_messages",
   softDelete: false,
@@ -211,9 +210,9 @@ export const seenMessageEntity = createEntity({
   },
 });
 
-// Plain EntityTableMeta (kein branded EntityTable) — unmanaged Direct-
-// Write-Stores, Handler schreiben via ctx.db (siehe user-session.ts-
-// Rationale).
+// Plain EntityTableMeta (not a branded EntityTable) — unmanaged direct-
+// write stores; handlers write via ctx.db (see user-session.ts-
+// rationale).
 export const syncCursorTable = deriveEntityTableMeta("mail-sync-cursor", syncCursorEntity, {
   source: "unmanaged",
 });

package/packages/bundled-features/src/inbound-mail-foundation/events.ts

@@ -1,34 +1,35 @@
-// Domain-events für inbound-mail-foundation.
+// Domain events for inbound-mail-foundation.
 //
-// **Pattern:** event-sourced — jede eingehende Mail und jeder Account-
-// Lifecycle-Übergang wird zu einem domain-event. Read-models =
-// inline projections (read_mail_accounts / read_inbound_messages /
-// read_mail_threads). Future-consumer (Business-Prozesse: Ticket-
-// Anlage, Beleg-Erkennung, Auto-Antwort) listenen direkt auf
-// `inbound-message-received` und können via extendEntityProjection
-// die KOMPLETTE Historie rückwirkend replayen.
+// **Pattern:** event-sourced — each incoming mail and account-lifecycle
+// transition becomes a domain event. Read models = inline projections
+// (read_mail_accounts / read_inbound_messages / read_mail_threads).
+// Future consumers (business processes: ticket creation, receipt
+// recognition, auto-replies) listen directly to `inbound-message-received`
+// and can replay the COMPLETE history retroactively via
+// extendEntityProjection.
 //
-// **Payload-Disziplin (Events sind forever):**
-//   - domain-clean + generisch: keine App-Begriffe (kein solon), keine
-//     provider-raw-Strukturen im payload — raw lebt in metadata.headers.
-//   - KEINE Bodies: bodyRef zeigt auf file-foundation-Storage. Der
-//     Event-Store ist kein Blob-Store.
-//   - PII (address/from/to/cc/subject/snippet) steht als Ciphertext im
-//     payload (`kumiko-pii:v1:...`), encrypted VOR dem append im
-//     write-handler — Subject-Key ist der Tenant, tenant-destroy's
-//     eraseSubjectKeys macht Event-Log UND Projection unlesbar
-//     (crypto-shredding, Muster billing-foundation #800).
+// **Payload discipline (events are forever):**
+//   - Domain-clean and generic: no app-specific terms (no solon), and no
+//     provider-raw structures in the payload — raw data lives in
+//     metadata.headers.
+//   - NO bodies: bodyRef points to file-foundation storage. The event store
+//     is not a blob store.
+//   - PII (address/from/to/cc/subject/snippet) is stored as ciphertext in
+//     the payload (`kumiko-pii:v1:...`), encrypted BEFORE append in the
+//     write handler — the subject key is the tenant, and tenant destruction's
+//     eraseSubjectKeys makes both the event log and projection unreadable
+//     (crypto-shredding, the billing-foundation pattern).
 
 import * as z from "zod";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.ts";
 
-// Aggregate-types für den event-store.
+// Aggregate types for the event store.
 export const MAIL_ACCOUNT_AGGREGATE_TYPE = "mail-account" as const;
 export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message" as const;
 export const MAIL_THREAD_AGGREGATE_TYPE = "mail-thread" as const;
 
-// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
-// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
+// Event-name constants — short forms (for r.defineEvent) and qualified
+// FQNs (for ctx.unsafeAppendEvent and projection-apply keys).
 export const MAIL_ACCOUNT_CONNECTED_EVENT_SHORT = "mail-account-connected" as const;
 export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated" as const;
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected" as const;
@@ -54,48 +55,50 @@ const accountStatusEnum = z.enum([
 ]);
 
 // ============================================================================
-// mail-account-Stream — connected / updated / disconnected
+// mail-account stream — connected / updated / disconnected
 // ============================================================================
 //
-// Ein Stream pro Postfach (aggregateId = accountId, random uuid beim
-// connect). address ist PII → maxLength 1000 wegen Ciphertext-Blowup
-// (ein 200-char-Plaintext wird ~460+ chars JSON-envelope, siehe
-// billing-foundation events.ts).
+// One stream per mailbox (aggregateId = accountId, random UUID on connect).
+// address is PII, so maxLength is 1000 to allow for ciphertext expansion
+// (a 200-character plaintext becomes ~460+ characters in a JSON envelope;
+// see billing-foundation events.ts).
 export const mailAccountEventPayloadSchema = z.object({
   provider: z.string().min(1).max(50),
-  /** "password" | "xoauth2" | "oauth" (InboundMailAuthMethods) — bewusst
-   *  string statt enum: neue Auth-Methoden ohne Event-Upcaster. */
+  /** "password" | "xoauth2" | "oauth" (InboundMailAuthMethods) — deliberately
+   *  a string rather than an enum, so new auth methods require no event
+   *  upcaster. */
   authMethod: z.string().min(1).max(30),
-  /** null = tenant-geteilt, sonst persönliches Postfach dieses Users. */
+  /** null = shared by the tenant; otherwise, this user's personal mailbox. */
   ownerUserId: z.string().max(36).nullable(),
   displayName: z.string().max(200),
   address: z.string().min(1).max(1000),
   status: accountStatusEnum,
-  /** Provider-agnostischer Watch-Zustand ("idle", "watching",
-   *  "backoff:3", ...) — reines Ops-Signal, kein PII. */
+  /** Provider-agnostic watch state ("idle", "watching", "backoff:3", ...)
+   *  — an operational signal only, not PII. */
   watchState: z.string().max(100),
 });
 export type MailAccountEventPayload = z.infer<typeof mailAccountEventPayloadSchema>;
 
 // ============================================================================
-// inbound-message-Stream — genau EIN received-Event pro Message
+// inbound-message stream — exactly ONE received event per message
 // ============================================================================
 //
 // aggregateId = inboundMessageAggregateId(accountId, providerMessageId)
-// → deterministic, Provider-Replays kollidieren auf demselben Stream.
+// → deterministic, so provider replays collide on the same stream.
 //
-// PII-Felder (from/to/cc/subject/snippet): Ciphertext, maxLength großzügig.
-// to/cc als JSON-stringified string[] VOR encryption — im Payload steht
-// der Ciphertext-String, nicht das Array (primitives only, upcaster-safe).
+// PII fields (from/to/cc/subject/snippet): ciphertext with generous
+// maximum lengths. to/cc are JSON-stringified string[] BEFORE encryption;
+// the payload contains the ciphertext string, not the array (primitives only,
+// upcaster-safe).
 export const inboundMessageEventPayloadSchema = z.object({
   accountId: z.uuid(),
-  /** Scope-Vererbung vom Account (Ingest-Zeitpunkt). */
+  /** Scope inherited from the account at ingest time. */
   ownerUserId: z.string().max(36).nullable(),
-  /** RFC-5322 Message-ID-Header (normalisiert, ohne <>) — NICHT PII-
-   *  encrypted: Idempotency/Threading-Anchor, opaque technical id. */
+  /** RFC-5322 Message-ID header (normalized, without <>) — NOT PII-encrypted:
+   *  idempotency/threading anchor and opaque technical ID. */
   messageIdHeader: z.string().min(1).max(500),
-  /** Normalisierter Thread-Schlüssel (References-Chain-Root bzw.
-   *  Provider-Thread-ID, provider-präfixed). */
+  /** Normalized thread key (References-chain root or provider thread ID,
+   *  prefixed by the provider). */
   threadKey: z.string().min(1).max(500),
   from: z.string().min(1).max(2000),
   /** JSON-stringified string[], dann PII-encrypted. */
@@ -104,14 +107,14 @@ export const inboundMessageEventPayloadSchema = z.object({
   cc: z.string().max(8000),
   subject: z.string().max(4000),
   snippet: z.string().max(4000),
-  /** ISO-Instant — Empfangszeit laut Provider (INTERNALDATE bzw.
-   *  receivedDateTime), nicht Ingest-Zeit. */
+  /** ISO instant — receipt time reported by the provider (INTERNALDATE or
+   *  receivedDateTime), not ingest time. */
   receivedAtIso: z.string().min(1),
-  /** file-foundation-Referenz auf den raw-Body (MIME). Leer wenn die
-   *  App ohne Body-Persistenz mounted (snippet-only-Mode). */
+  /** file-foundation reference to the raw body (MIME). Empty when the app
+   *  is mounted without body persistence (snippet-only mode). */
   bodyRef: z.string().max(500),
-  /** Fachlicher Scope-Hint für nachgelagerte Business-Prozesse —
-   *  generisch ("inbox", Folder-Name), KEINE App-Semantik. */
+  /** Domain scope hint for downstream business processes — generic
+   *  ("inbox", folder name), with NO app-specific semantics. */
   scope: z.string().max(200),
 });
 export type InboundMessageEventPayload = z.infer<typeof inboundMessageEventPayloadSchema>;
@@ -134,14 +137,15 @@ export type MailThreadEventPayload = z.infer<typeof mailThreadEventPayloadSchema
 export type InboundMessageEventHeaders = {
   readonly providerMessageId: string;
   readonly providerName: string;
-  /** Provider-Cursor-Snapshot zum Ingest-Zeitpunkt (UIDVALIDITY:UID,
-   *  deltaLink, historyId ...) — Debug/Replay-Hilfe, kein Payload. */
+  /** Provider cursor snapshot at ingest time (UIDVALIDITY:UID, deltaLink,
+   *  historyId ...) — useful for debugging and replay, not part of the
+   *  payload. */
   readonly providerCursor: string;
 };
 
 export type MailAccountEventHeaders = {
   readonly providerName: string;
-  /** Was den Übergang ausgelöst hat ("connect_flow", "watch_supervisor",
+  /** What triggered the transition ("connect_flow", "watch_supervisor",
    *  "oauth_refresh", "tenant_admin"). */
   readonly reason: string;
 };