@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

@@ -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 type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
@@ -111,7 +111,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).
@@ -135,7 +135,7 @@ export function createInboundMailFoundationFeature() {
         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,
@@ -177,7 +177,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",
       });
@@ -203,8 +203,8 @@ export function createInboundMailFoundationFeature() {
       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 },
@@ -218,7 +218,7 @@ export function createInboundMailFoundationFeature() {
         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
@@ -245,10 +245,10 @@ export function createInboundMailFoundationFeature() {
           const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
           const retentionDb = ctx.db.unsafeRaw() as DbConnection; // @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: Promise<FileStorageProvider> | null = null;
           const deleteBodyObject = async (bodyRef: string): Promise<void> => {
             if (!providerPromise) {

package/packages/bundled-features/src/inbound-mail-foundation/handlers/account-state.ts

@@ -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).
 
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { MailAccountEventPayload } from "../events.ts";

package/packages/bundled-features/src/inbound-mail-foundation/handlers/connect-account.write.ts

@@ -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,
@@ -30,7 +29,7 @@ import {
 } from "../events.ts";
 
 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([
@@ -39,16 +38,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(),
 });
 type ConnectAccountPayload = z.infer<typeof connectAccountSchema>;
@@ -75,8 +74,8 @@ export const connectAccountHandler: WriteHandlerDef = {
           ? 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
@@ -96,8 +95,8 @@ export const connectAccountHandler: WriteHandlerDef = {
       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/packages/bundled-features/src/inbound-mail-foundation/handlers/disconnect-account.write.ts

@@ -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 type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";

package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -1,24 +1,24 @@
-// ingest-message — programmatic entry-point für Provider-Plugins
-// (watch-callback + fetchSince-Sync). Nimmt eine normalisierte
-// RawInboundMessage und macht atomic in EINER TX:
+// ingest-message — programmatic entry point for provider plugins
+// (watch callback + fetchSince sync). Accepts a normalized
+// RawInboundMessage and performs atomically in ONE TX:
 //
-//   1. Idempotency-Check (cheap: store_mail_seen_messages; Defense-in-
-//      depth: Stream-Existenz auf der deterministic aggregateId).
-//   2. threadKey-Normalisierung (Provider-Thread-ID bevorzugt, sonst
-//      References-Chain-Root, sonst Message-ID = Single-Message-Thread).
-//   3. PII-Encrypt (from/to/cc/subject/snippet) VOR dem append —
-//      Event-Log UND Projection tragen Ciphertext (#800-Muster).
-//   4. inbound-message-received-append (Inline-Projection schreibt
-//      read_inbound_messages in derselben TX). Savepoint-scoped
+//   1. Idempotency check (cheap: store_mail_seen_messages; defense in
+//      depth: stream existence check on the deterministic aggregateId).
+//   2. threadKey normalization (provider thread ID preferred, otherwise
+//      References chain root, otherwise Message-ID = single-message thread).
+//   3. PII encryption (from/to/cc/subject/snippet) BEFORE the append —
+//      both the event log AND projection contain ciphertext.
+//   4. inbound-message-received append (inline projection writes
+//      read_inbound_messages in the same TX). Savepoint-scoped
 //      (ctx.tryAppendEvent) — a losing concurrent ingest for the same
 //      messageAggId returns { duplicate: true } instead of failing the TX.
-//   5. Thread-Rollup: mail-thread-updated-append mit neu berechnetem
-//      Snapshot (count+1, max(lastMessageAt)) — die apply ist ein
-//      dummer UPSERT.
-//   6. seen-message-Dedup-Anchor einfügen.
+//   5. Thread rollup: mail-thread-updated append with a recalculated
+//      snapshot (count+1, max(lastMessageAt)) — the apply is a
+//      dumb UPSERT.
+//   6. Insert the seen-message deduplication anchor.
 //
-// SystemAdmin-only: Aufrufer ist der Watch/Sync-Supervisor bzw. der
-// Poll-Cron mit programmatic SystemUser — nie ein Tenant-Request.
+// SystemAdmin-only: the caller is the watch/sync supervisor or
+// the poll cron with a programmatic SystemUser — never a tenant request.
 
 import {
   configuredPiiSubjectKms,
@@ -49,25 +49,25 @@ import {
 import { inboundMessagesProjectionTable } from "../projection.ts";
 
 // =============================================================================
-// Input-Schema — der normalisierte Provider-Output (RawInboundMessage,
-// types.ts) + Envelope (accountId/providerName/providerCursor). rawMime
-// ist hier bewusst NICHT dabei: der Aufrufer persisted den Body VOR dem
-// ingest-Call nach file-foundation und übergibt nur bodyRef — der
-// Handler-Payload bleibt blob-frei (Event-Store-Disziplin).
+// Input schema — the normalized provider output (RawInboundMessage,
+// types.ts) plus the envelope (accountId/providerName/providerCursor). rawMime
+// is intentionally excluded: the caller persists the body to
+// file-foundation BEFORE the ingest call and passes only bodyRef — the
+// handler payload remains blob-free (event-store discipline).
 // =============================================================================
 
 export const ingestMessageSchema = z.object({
   accountId: z.uuid(),
-  /** Scope-Vererbung vom Account — der Supervisor kennt den
-   *  MailAccountRecord und reicht ownerUserId durch. */
+  /** Scope inherited from the account — the supervisor knows the
+   *  MailAccountRecord and passes ownerUserId through. */
   ownerUserId: z.string().max(36).nullable(),
   providerName: z.string().min(1).max(50),
-  /** Provider-native Message-ID — Idempotency-Anchor mit accountId. */
+  /** Provider-native Message-ID — idempotency anchor with accountId. */
   providerMessageId: z.string().min(1).max(500),
-  /** RFC-5322 Message-ID ohne <>; null → deterministischer Ersatz. */
+  /** RFC-5322 Message-ID without <>; null → deterministic fallback. */
   messageIdHeader: z.string().min(1).max(500).nullable(),
   providerThreadId: z.string().min(1).max(500).nullable(),
-  /** References/In-Reply-To-Chain, älteste zuerst. */
+  /** References/In-Reply-To chain, oldest first. */
   references: z.array(z.string().min(1).max(500)).max(200),
   from: z.string().min(1).max(2000),
   to: z.array(z.string().max(2000)).max(200),
@@ -78,20 +78,20 @@ export const ingestMessageSchema = z.object({
   /** file-foundation-Ref; leer im snippet-only-Mode. */
   bodyRef: z.string().max(500),
   scope: z.string().min(1).max(200),
-  /** Cursor-Snapshot zum Ingest-Zeitpunkt — Debug/Replay, landet in
-   *  metadata.headers, nie im payload. */
+  /** Cursor snapshot at ingest time — used for debugging/replay and stored in
+   *  metadata.headers, never in the payload. */
   providerCursor: z.string().max(2000),
 });
 type IngestMessagePayload = z.infer<typeof ingestMessageSchema>;
 
 /**
- * threadKey-Normalisierung (Plan §3.2):
- *   1. Provider-Thread-ID falls vorhanden — provider-präfixed, damit
- *      IMAP-References-Keys und Graph-conversationIds nie kollidieren.
- *   2. Sonst Root der References-Chain (älteste Message-ID = der
- *      Thread-Anker, den alle Replies teilen).
- *   3. Sonst die eigene Message-ID → Single-Message-Thread; ein späteres
- *      Reply trägt sie als References-Root und landet im selben Thread.
+ * Normalizes threadKey:
+ *   1. Use the provider thread ID when present — prefix it with the provider
+ *      so IMAP References keys and Graph conversationIds never collide.
+ *   2. Otherwise use the root of the References chain (the oldest Message-ID,
+ *      which is the thread anchor shared by all replies).
+ *   3. Otherwise use the own Message-ID → single-message thread; a later
+ *      reply carries it as the References root and joins the same thread.
  */
 function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: string): string {
   if (p.providerThreadId) return `${p.providerName}:${p.providerThreadId}`.slice(0, 500);
@@ -123,12 +123,12 @@ export const ingestMessageHandler: WriteHandlerDef = {
     const messageAggId = inboundMessageAggregateId(payload.accountId, payload.providerMessageId);
 
     // ---------------------------------------------------------------
-    // 1. Idempotency. Cheap path zuerst: Dedup-Anchor-Row. Der
-    //    Stream-Check dahinter ist Defense-in-depth für den Fall dass
-    //    ein früherer ingest NACH dem append aber VOR dem seen-insert
-    //    gestorben ist (kann in einer TX nicht passieren — aber der
-    //    Check ist billig und macht den Handler rebuild-robust falls
-    //    store_mail_seen_messages je getruncated wird).
+    // 1. Idempotency. Use the deduplication anchor row first because it is
+    //    cheap. The stream check afterward provides defense in depth if
+    //    an earlier ingest died AFTER the append but BEFORE the seen insert
+    //    (this cannot happen within one TX, but the check is cheap and makes
+    //    the handler robust to rebuilding if store_mail_seen_messages is
+    //    ever truncated).
     // ---------------------------------------------------------------
     const seenRows = await ctx.db.selectMany(seenMessageTable, {
       accountId: payload.accountId,
@@ -163,11 +163,10 @@ export const ingestMessageHandler: WriteHandlerDef = {
     const threadAggId = mailThreadAggregateId(tenantId, threadKey);
 
     // ---------------------------------------------------------------
-    // 3. PII-Encrypt. to/cc werden VOR encryption JSON-stringified —
-    //    im Payload steht der Ciphertext-String, nicht das Array
-    //    (primitives only, upcaster-safe). Kein KMS konfiguriert =
-    //    plaintext-passthrough (Engine-off-Verhalten, Muster
-    //    billing-foundation process-event #724/#800).
+    // 3. PII encryption. Serialize to/cc as JSON BEFORE encryption so the
+    //    payload contains a ciphertext string rather than an array
+    //    (primitives only, upcaster-safe). If no KMS is configured, pass
+    //    through plaintext (engine-off behavior).
     // ---------------------------------------------------------------
     const piiKms = configuredPiiSubjectKms();
     const messagePlainPii = {
@@ -243,14 +242,14 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    concurrent ingests on the same thread (Watch-Push vs.
     //    Poll-Reconciliation overlap, or two different messages of the
     //    same thread arriving at once) converge on the true count.
-    //    acquireNamespacedAdvisoryLock below (issue #2155) serializes this whole
+    //    acquireNamespacedAdvisoryLock below serializes this whole
     //    countWhere+append section per threadAggId — transaction-scoped,
     //    so it survives tryAppendEvent's inner SAVEPOINT and releases at
     //    the enclosing TX's commit/rollback. Without it, a concurrent
     //    commit landing between countWhere and tryAppendEvent's own fresh
     //    version-read makes the append succeed with a stale count instead
     //    of a VersionConflictError, so the retry loop below never sees it
-    //    as a conflict to retry (#1229's original gap). Unlike step 4, a
+    //    as a conflict to retry (the original gap). Unlike step 4, a
     //    lost version-conflict race here must NOT be treated as a no-op
     //    duplicate — skipping would leave this message's contribution to
     //    messageCount/lastMessageAt out of the thread forever. Exhausting
@@ -315,8 +314,8 @@ export const ingestMessageHandler: WriteHandlerDef = {
     }
 
     // ---------------------------------------------------------------
-    // 6. Dedup-Anchor. Läuft in derselben TX wie die appends — stirbt
-    //    der Handler, rollt alles zusammen zurück.
+    // 6. Deduplication anchor. It runs in the same TX as the appends, so
+    //    if the handler fails, everything is rolled back together.
     // ---------------------------------------------------------------
     await ctx.db.insertOne(seenMessageTable, {
       tenantId,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -1,12 +1,12 @@
-// list-accounts — tenant-scoped Liste der verbundenen Postfächer fürs
-// Connect-/Settings-UI. PII (address) wird beim Read decrypted (Muster
-// billing-foundation list-subscriptions).
+// list-accounts — tenant-scoped list of connected mailboxes for the
+// Connect/Settings UI. PII (address) is decrypted on read, following the
+// billing-foundation list-subscriptions pattern.
 //
-// **Scope-Sichtbarkeit (Plan Entscheidung 2):** shared-Postfächer
-// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
-// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Filter läuft
-// in-memory nach dem tenant-scoped select — Volumen ist die Anzahl
-// verbundener Postfächer eines Tenants (einstellig bis zweistellig).
+// **Scope visibility:** authorized users can see shared mailboxes
+// (ownerUserId=null); personal mailboxes are visible only to their owner,
+// TenantAdmin, or SystemAdmin for compliance access. Filtering runs in memory
+// after the tenant-scoped select because a tenant has only a single- to
+// double-digit number of connected mailboxes.
 import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -1,12 +1,12 @@
-// list-messages — tenant-scoped Message-Liste (Inbox-Cockpit).
-// Optionale Filter: accountId (ein Postfach), threadKey (eine
-// Konversation), scope (Folder-Hint). PII (from/to/cc/subject/snippet)
-// wird beim Read decrypted; to/cc bleiben JSON-stringified strings —
-// der Client parsed sie (dokumentiert im Event-Payload).
+// list-messages — tenant-scoped message list for the inbox cockpit.
+// Optional filters: accountId (one mailbox), threadKey (one conversation),
+// scope (folder hint). PII (from/to/cc/subject/snippet) is decrypted on read;
+// to/cc remain JSON-stringified strings, which the client parses as documented
+// in the event payload.
 //
-// Bewusst KEINE Pagination in V1: die Projection ist tenant-scoped und
-// das Inbox-Cockpit lädt begrenzte Zeiträume; ein `limit`-Feld ist
-// vorwärtskompatibel ergänzbar ohne den QN zu brechen.
+// Deliberately no pagination in V1: the projection is tenant-scoped and the
+// inbox cockpit loads bounded time ranges; a `limit` field can be added
+// compatibly without breaking the QN.
 
 import {
   configuredPiiSubjectKms,
@@ -42,8 +42,8 @@ export const listMessagesQuery: QueryHandlerDef = {
     if (payload.scope) filter["scope"] = payload.scope;
 
     const allRows = await ctx.db.selectMany(inboundMessagesProjectionTable, filter);
-    // Scope-Sichtbarkeit (Plan Entscheidung 2): Messages persönlicher
-    // Postfächer nur für Owner + TenantAdmin/SystemAdmin.
+    // Scope visibility: messages in personal mailboxes are visible only to the
+    // owner or TenantAdmin/SystemAdmin.
     const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
     const piiKms = configuredPiiSubjectKms();
     if (!piiKms) return { rows };

package/packages/bundled-features/src/inbound-mail-foundation/handlers/scope-visibility.ts

@@ -1,7 +1,6 @@
-// Scope-Sichtbarkeit (Plan Entscheidung 2): shared-Rows
-// (ownerUserId=null) sieht jeder Berechtigte; persönliche nur der Owner
-// selbst + TenantAdmin/SystemAdmin (Compliance-Sicht). Gilt identisch
-// für read_mail_accounts und read_inbound_messages (Scope-Vererbung).
+// Scope visibility: shared rows (`ownerUserId=null`) are visible to any authorized caller;
+// personal rows are visible only to the owner, `TenantAdmin`, or `SystemAdmin` for compliance.
+// The same rule applies to `read_mail_accounts` and `read_inbound_messages`.
 
 export function isVisibleToCaller(
   row: Readonly<Record<string, unknown>>,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -1,7 +1,7 @@
-// update-account — Account-Status-Übergänge: Watch-Supervisor meldet
-// error/backoff, OAuth-Refresh scheitert (auth_error), Tenant-Admin
-// re-enabled nach Credential-Fix. Full-snapshot-Event: lädt den letzten
-// Stand, merged die Delta-Felder, appendet den neuen Snapshot.
+// update-account — Account status transitions: the watch supervisor reports
+// error/backoff, OAuth refresh fails (auth_error), or a tenant admin re-enables
+// the account after fixing its credentials. Full-snapshot event: loads the
+// latest state, merges the delta fields, and appends the new snapshot.
 
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
@@ -27,7 +27,7 @@ export const updateAccountSchema = z.object({
   /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
   watchState: z.string().max(100).optional(),
   displayName: z.string().max(200).optional(),
-  /** Audit-Grund für metadata.headers ("watch_supervisor",
+  /** Audit reason for metadata.headers ("watch_supervisor",
    *  "oauth_refresh", "tenant_admin"). */
   reason: z.string().min(1).max(100),
 });
@@ -48,15 +48,15 @@ export const updateAccountHandler: WriteHandlerDef = {
       return failNotFound("mail-account", payload.accountId);
     }
     if (current.status === InboundMailAccountStatuses.disconnected) {
-      // Getrennte Accounts sind final — Re-Enable läuft über einen
-      // frischen connect (neuer Stream, neuer Secret-Slot). Verhindert
-      // dass ein nachzügelnder Supervisor-Tick einen disconnected
-      // Account wieder auf active hebt (Race Disconnect vs. Poll).
+      // Disconnected accounts are final; re-enabling requires a fresh connect
+      // (new stream, new secret slot). This prevents a delayed supervisor tick
+      // from restoring a disconnected account to active (disconnect vs. poll
+      // race).
       return failUnprocessable("account_disconnected", { accountId: payload.accountId });
     }
 
-    // Merge: address/provider/authMethod kommen 1:1 aus dem letzten
-    // Snapshot (address bleibt Ciphertext — nie re-encrypten).
+    // address/provider/authMethod come unchanged from the latest snapshot
+    // (address remains ciphertext—never re-encrypt it).
     const eventPayload: MailAccountEventPayload = {
       ...current,
       ...(payload.status !== undefined ? { status: payload.status } : {}),