@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/inbound-mail-foundation/entities.js

@@ -2,27 +2,26 @@ import { collectPiiSubjectFields } from "@cosmicdrift/kumiko-framework/crypto";
 import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { access, createEntity, createNumberField, createTextField, createTimestampField, } 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).
-/** Ein verbundenes Postfach. Eine Row pro Account, PK = aggregateId
- *  (= accountId, random uuid beim connect). */
+// **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.
+/** A connected mailbox. One row per account, with PK = aggregateId
+ *  (= accountId, random uuid on connect). */
 export const mailAccountEntity = createEntity({
     table: "read_mail_accounts",
     fields: {
@@ -38,10 +37,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({
@@ -49,7 +48,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,
@@ -61,8 +60,8 @@ export const mailAccountEntity = createEntity({
         connectedAt: createTimestampField({ required: true }),
     },
 });
-/** 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",
@@ -73,9 +72,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,
@@ -116,27 +115,27 @@ export const mailThreadEntity = createEntity({
         messageCount: createNumberField({ required: true, integer: true }),
     },
 });
-// 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).
-/** 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. */
+// 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 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,
@@ -168,10 +167,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,
@@ -196,9 +195,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/dist/inbound-mail-foundation/events.d.ts

@@ -52,13 +52,14 @@ 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;
 };

package/dist/inbound-mail-foundation/events.js

@@ -1,31 +1,32 @@
-// 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.js";
-// Aggregate-types für den event-store.
+// Aggregate types for the event store.
 export const MAIL_ACCOUNT_AGGREGATE_TYPE = "mail-account";
 export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message";
 export const MAIL_THREAD_AGGREGATE_TYPE = "mail-thread";
-// 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";
 export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated";
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected";
@@ -43,46 +44,48 @@ const accountStatusEnum = z.enum([
     InboundMailAccountStatuses.disconnected,
 ]);
 // ============================================================================
-// 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),
 });
 // ============================================================================
-// 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. */
@@ -91,14 +94,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),
 });
 // ============================================================================

package/dist/inbound-mail-foundation/feature.js

@@ -1,44 +1,44 @@
 // kumiko-feature-version: 1
 //
-// inbound-mail-foundation — Plugin-Host für eingehende E-Mail
-// (Inbox-Föderation). Gegenstück zu mail-foundation (outbound): getrennte
-// Extension-Points, getrennter State — Architektur-Vorbild ist
-// file-foundation (Foundation besitzt State), nicht mail-transport.
+// inbound-mail-foundation — Plugin host for inbound e-mail
+// (inbox federation). Counterpart to mail-foundation (outbound): separate
+// extension points, separate state — architectural model is
+// file-foundation (the foundation owns state), not mail-transport.
 //
-// **Multi-Provider von Tag 1** (wie billing-foundation): KEIN globaler
-// `provider`-config-key. Ein Tenant verbindet parallel IMAP- und (später)
-// M365-/Gmail-Postfächer; der Provider steht pro MailAccount.
+// **Multi-provider from day one** (as with billing-foundation): NO global
+// `provider` config key. A tenant can connect IMAP and (later) M365/Gmail
+// mailboxes in parallel; the provider is specified per MailAccount.
 //
-// **Was diese Foundation liefert:**
-//   1. **Plugin-API** für Inbound-Provider via r.extendsRegistrar
+// **What this foundation provides:**
+//   1. **Plugin API** for inbound providers via r.extendsRegistrar
 //      ("inboundMailProvider"): verify/fetch/oauth?/watch? (types.ts).
-//   2. **3 event-sourced Streams** — mail-account (Lifecycle),
-//      inbound-message (genau EIN received-Event pro Mail, deterministic
-//      aggregateId ⇒ exactly-once trotz at-least-once-Ingest),
-//      mail-thread (Rollup). Volle Historie replay-fähig für spätere
-//      Consumer (Business-Prozesse: Ticket, Beleg, Auto-Antwort).
-//   3. **Inline-Projections** auf read_mail_accounts /
+//   2. **3 event-sourced streams** — mail-account (lifecycle),
+//      inbound-message (exactly ONE received event per message, deterministic
+//      aggregateId ⇒ exactly-once despite at-least-once ingest),
+//      mail-thread (rollup). Full replayable history for later
+//      consumers (business processes: ticket, receipt, auto-reply).
+//   3. **Inline projections** into read_mail_accounts /
 //      read_inbound_messages / read_mail_threads (read-your-own-write).
-//   4. **Write-/Query-Handler**: connect/update/disconnect-account,
+//   4. **Write/query handlers**: connect/update/disconnect-account,
 //      ingest-message (programmatic, SystemAdmin), account:list +
-//      message:list (PII-decrypted, scope-gefiltert).
-//   5. **createInboundMailConnectRoutes**: OAuth-Connect + anonymer
-//      Callback (außerhalb /api/*), state HMAC-signiert.
-//   6. **createInboundMailSupervisor**: app-verdrahteter Watch-(IDLE)-
-//      Supervisor mit Backoff + Reconciliation-Poll.
+//      message:list (PII-decrypted, scope-filtered).
+//   5. **createInboundMailConnectRoutes**: OAuth connect + anonymous
+//      callback (outside /api/*), with HMAC-signed state.
+//   6. **createInboundMailSupervisor**: app-wired watch (IDLE)
+//      supervisor with backoff + reconciliation poll.
 //
-// **Was diese Foundation NICHT macht:**
-//   - Keine Business-Semantik (Intent, Ticket, Zuweisung, gelesen/
-//     erledigt) — das gehört dem App-Consumer (z.B. via Event-Job auf
-//     inbound-message-received + eigener Projection).
-//   - Kein Body-Blob im Event-Store: rawMime → file-foundation via
-//     Supervisor-storeBody-Hook, Event trägt nur bodyRef.
-//   - Kein IMAP-Flag-Write-back (V1) — Inbox-Status lebt beim Consumer.
+// **What this foundation does NOT do:**
+//   - No business semantics (intent, ticket, assignment, read/
+//     completed) — those belong to the app consumer (for example, via an
+//     event job on inbound-message-received + its own projection).
+//   - No body blob in the event store: rawMime → file-foundation via
+//     the Supervisor-storeBody-Hook; the event carries only bodyRef.
+//   - No IMAP flag write-back (V1) — inbox status belongs to the consumer.
 //
 // **PII/GDPR:** address/from/to/cc/subject/snippet are `personal: "tenant"`
 // — encrypted BEFORE every event append (the only write path), event log AND
 // projections carry ciphertext; tenant-destroy shreds the subject key
-// (crypto-shredding, same pattern as billing-foundation #800). The destroy
+// (crypto-shredding, the same pattern as billing-foundation). The destroy
 // hook additionally archives all streams + deletes the rows.
 import { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { createFileProviderForTenant, } from "@cosmicdrift/kumiko-framework/files";
@@ -64,7 +64,7 @@ export function createInboundMailFoundationFeature() {
             category: "notifications",
             recommended: false,
         });
-        // EXT_TENANT_DATA-Hook braucht den tenant-lifecycle-Host.
+        // The EXT_TENANT_DATA hook requires the tenant-lifecycle host.
         r.requires({ features: ["tenant-lifecycle"] });
         // 5 fine-grained domain-events (Payload-Schemas: events.ts).
         // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
@@ -86,7 +86,7 @@ export function createInboundMailFoundationFeature() {
         r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema, {
             piiFields: "none",
         });
-        // Inline projections — apply in derselben TX wie der Append.
+        // Inline projections — apply in the same transaction as the append.
         r.projection({
             name: "mail-account",
             source: MAIL_ACCOUNT_AGGREGATE_TYPE,
@@ -126,7 +126,7 @@ export function createInboundMailFoundationFeature() {
         });
         // Sync machinery: high-frequency tick state, deliberately NOT
         // event-sourced — r.storeTable keeps the migration DDL but excludes the
-        // tables from the projection rebuild (#494/#498 class).
+        // tables from the projection rebuild.
         r.storeTable(syncCursorTable, {
             reason: "read_side.mail_sync_cursors_direct_write",
         });
@@ -148,8 +148,8 @@ export function createInboundMailFoundationFeature() {
         r.screen(mailAccountListScreen);
         r.screen(mailAccountEditScreen);
         r.translations({ keys: INBOUND_MAIL_FOUNDATION_I18N });
-        // Entity-genaue GDPR-Destroy-Hooks — der gdpr-storage-Boot-Validator
-        // prueft die EXT_TENANT_DATA-Registrierung pro tenant-subject-Entity.
+        // Entity-specific GDPR destroy hooks — the gdpr-storage boot validator
+        // checks the EXT_TENANT_DATA registration for each tenant-subject entity.
         r.useExtension(EXT_TENANT_DATA, "mail-account", {
             destroy: mailAccountTenantDestroyHook,
             escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
@@ -162,7 +162,7 @@ export function createInboundMailFoundationFeature() {
             destroy: mailThreadTenantDestroyHook,
             escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
         });
-        // Data-Retention (#957) — perTenant fan-out (one run per tenant, like
+        // Data-Retention — perTenant fan-out (one run per tenant, like
         // data-retention:retention-cleanup): runInboundMailRetention's raw query
         // helpers need the unfiltered runner, so the handler declares escapeHatch
         // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
@@ -185,10 +185,10 @@ export function createInboundMailFoundationFeature() {
                 }
                 const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
                 const retentionDb = ctx.db.unsafeRaw(); // @cast-boundary db-operator — jobs never run inside a DbTx
-                // Body-Objekte liegen in file-foundation. Provider lazy + memoized —
-                // heute schreibt der Ingest kein bodyRef (storeBody-Hook ungebunden),
-                // der Provider wird also nie gebaut. Sobald storeBody wired ist, raeumt
-                // die Retention die Bodies mit ab.
+                // Body objects are stored in file-foundation. The provider is lazy and memoized —
+                // ingest currently writes no bodyRef (the storeBody hook is not wired),
+                // so the provider is never built. Once storeBody is wired, retention
+                // also cleans up the bodies.
                 let providerPromise = null;
                 const deleteBodyObject = async (bodyRef) => {
                     if (!providerPromise) {

package/dist/inbound-mail-foundation/handlers/account-state.js

@@ -1,13 +1,13 @@
-// Geteilter State-Loader für update-account / disconnect-account.
+// Shared state loader for update-account / disconnect-account.
 //
-// Die mail-account-Events sind full-snapshots (Muster billing-foundation:
-// "Alle nutzen denselben payload-shape, der event-type taggt was
-// passiert ist") — ein Übergangs-Handler lädt den letzten Snapshot,
-// merged seine Delta-Felder rein und appendet den neuen Snapshot.
+// mail-account events are full snapshots (following the billing-foundation
+// pattern: "All events use the same payload shape; the event-type identifies
+// what happened") — a transitional handler loads the latest snapshot, merges
+// its delta fields into it, and appends the new snapshot.
 //
-// **PII-Disziplin:** `address` steht im geladenen Payload bereits als
-// Ciphertext und wird 1:1 durchkopiert — NIE re-encrypten (würde bei
-// fehlendem KMS decrypt erzwingen bzw. Double-Encryption produzieren).
+// **PII discipline:** `address` is already ciphertext in the loaded payload
+// and is copied byte-for-byte — NEVER re-encrypt it (that would require KMS
+// decryption when unavailable or produce double encryption).
 export async function loadCurrentMailAccountPayload(ctx, accountId) {
     const events = await ctx.loadAggregate(accountId);
     const last = events[events.length - 1];

package/dist/inbound-mail-foundation/handlers/connect-account.write.js

@@ -1,17 +1,16 @@
-// connect-account — Tenant-Admin verbindet ein Postfach. Legt den
-// mail-account-Stream an (aggregateId = random uuid = accountId =
-// Secret-Slot-Key für IMAP-Passwort/OAuth-Refresh-Token).
+// connect-account — A tenant admin connects a mailbox. Creates the
+// mail-account stream (aggregateId = random uuid = accountId =
+// secret-slot key for the IMAP password/OAuth refresh token).
 //
-// **Was hier NICHT passiert:**
-//   - Kein Secret-Write: IMAP-Credentials laufen über den secrets-Pfad,
-//     OAuth-Tokens über die generischen /inbound-mail/oauth-Routen —
-//     beides VOR bzw. NACH diesem Call, nie durch den Handler-Payload
-//     (Plain-Passwörter gehören nicht in einen Write-Payload, der im
-//     Dispatcher-Log landen kann).
-//   - Kein Verbindungs-Test: der Watch-Supervisor probiert den ersten
-//     fetch und schaltet bei Fehler via update-account auf auth_error —
-//     der Connect bleibt schnell und offline-fähig (Test-Ergebnis kommt
-//     asynchron als Status-Übergang).
+// **What does NOT happen here:**
+//   - No secret write: IMAP credentials use the secrets path, and OAuth
+//     tokens use the generic /inbound-mail/oauth routes—both before or
+//     after this call, never in the handler payload (plain passwords must
+//     not enter a write payload that can appear in the dispatcher log).
+//   - No connection test: the watch supervisor attempts the first fetch
+//     and switches to auth_error via update-account on failure—the connect
+//     stays fast and offline-capable (the test result arrives asynchronously
+//     as a status transition).
 import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
@@ -19,7 +18,7 @@ import { InboundMailAccountStatuses, InboundMailAuthMethods } from "../constants
 import { MAIL_ACCOUNT_PII_FIELDS, mailAccountEntity } from "../entities.js";
 import { MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_CONNECTED_EVENT_QN, } from "../events.js";
 export const connectAccountSchema = z.object({
-    /** Provider-Key wie an der Extension registriert ("imap",
+    /** Provider key registered with the extension ("imap",
      *  "m365-graph", "gmail-rest"). */
     provider: z.string().min(1).max(50),
     authMethod: z.enum([
@@ -28,16 +27,16 @@ export const connectAccountSchema = z.object({
         InboundMailAuthMethods.oauth,
     ]),
     displayName: z.string().max(200),
-    /** Postfach-Adresse, Plaintext — wird hier encrypted. */
+    /** Mailbox address in plaintext; it is encrypted here. */
     address: z.string().min(1).max(320),
-    /** "shared" = tenant-geteilt (info@) · "user" = persönliches Postfach
-     *  des Callers (ownerUserId wird aus der Session gezogen, nie aus dem
-     *  Payload — kein Fremd-Claiming). */
+    /** "shared" = shared across the tenant (info@) · "user" = the caller's
+     *  personal mailbox (ownerUserId is taken from the session, never from
+     *  the payload—preventing claims on another user's mailbox). */
     scope: z.enum(["shared", "user"]),
-    /** NUR für den programmatic OAuth-Callback-Pfad (SystemAdmin): dort
-     *  ist der Dispatcher-User ein SystemUser, der echte Owner steht im
-     *  HMAC-verifizierten state. Tenant-Caller dürfen das Feld nicht
-     *  setzen (Fremd-Claiming-Sperre im Handler). */
+    /** Only for the programmatic OAuth callback path (SystemAdmin): there,
+     *  the dispatcher user is a SystemUser and the actual owner is in the
+     *  HMAC-verified state. Tenant callers must not set this field (the
+     *  handler prevents claims on another user's mailbox). */
     ownerUserIdOverride: z.string().max(36).nullable().optional(),
 });
 export const connectAccountHandler = {
@@ -58,8 +57,8 @@ export const connectAccountHandler = {
             : payload.scope === "user"
                 ? event.user.id
                 : null;
-        // PII-Encrypt der Adresse vor dem append — einziger Write-Pfad auf
-        // den Stream, deckt Event-Log UND Projection ab (#800-Muster).
+        // PII-encrypt the address before the append. This is the only write path to
+        // the stream, so it covers both the event log and the projection.
         const piiKms = configuredPiiSubjectKms();
         const plainPii = { tenantId, address: payload.address };
         const encryptedFields = piiKms
@@ -71,8 +70,8 @@ export const connectAccountHandler = {
             ownerUserId,
             displayName: payload.displayName,
             address: encryptedFields.address,
-            // active ab Connect — der Supervisor greift den Account beim
-            // nächsten Tick auf und degradiert ihn bei Credential-Fehlern.
+            // The account is active upon connection; the supervisor picks it up on
+            // the next tick and downgrades it when credentials fail.
             status: InboundMailAccountStatuses.active,
             watchState: "idle",
         };

package/dist/inbound-mail-foundation/handlers/disconnect-account.write.js

@@ -1,11 +1,11 @@
-// disconnect-account — Tenant-Admin trennt ein Postfach. Stream bleibt
-// (Audit-Historie), Status wird disconnected, der Watch-Supervisor
-// überspringt den Account ab dem nächsten Tick. Secret-Cleanup (IMAP-
-// Passwort/Refresh-Token im Slot accountId) macht der Aufrufer-Flow —
-// der Handler fasst den secrets-Pfad nicht an.
+// disconnect-account — A TenantAdmin disconnects a mailbox. The stream is retained
+// for audit history, the status becomes disconnected, and the watch supervisor
+// skips the account starting with the next tick. Secret cleanup (IMAP password/
+// refresh token in the accountId slot) is handled by the caller flow; this handler
+// does not touch the secrets path.
 //
-// Idempotent: disconnect auf bereits disconnected Account ist ein
-// success-no-op (kein zweites Event) — Doppelklick-/Retry-freundlich.
+// Idempotent: disconnecting an already disconnected account is a success no-op
+// with no second event, making double-clicks and retries safe.
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { InboundMailAccountStatuses } from "../constants.js";