@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/inbound-mail-foundation/handlers/ingest-message.write.js

@@ -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, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { acquireNamespacedAdvisoryLock, countWhere } from "@cosmicdrift/kumiko-framework/db";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
@@ -29,24 +29,24 @@ import { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity, MAIL_THREAD_PII_FIELD
 import { INBOUND_MESSAGE_AGGREGATE_TYPE, INBOUND_MESSAGE_RECEIVED_EVENT_QN, MAIL_THREAD_AGGREGATE_TYPE, MAIL_THREAD_UPDATED_EVENT_QN, } from "../events.js";
 import { inboundMessagesProjectionTable } from "../projection.js";
 // =============================================================================
-// 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),
@@ -57,18 +57,18 @@ 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),
 });
 /**
- * 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, effectiveMessageIdHeader) {
     if (p.providerThreadId)
@@ -99,12 +99,12 @@ export const ingestMessageHandler = {
         const tenantId = event.user.tenantId;
         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,
@@ -137,11 +137,10 @@ export const ingestMessageHandler = {
         const threadKey = buildThreadKey(payload, effectiveMessageIdHeader);
         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 = {
@@ -208,14 +207,14 @@ export const ingestMessageHandler = {
         //    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
@@ -264,8 +263,8 @@ export const ingestMessageHandler = {
             });
         }
         // ---------------------------------------------------------------
-        // 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/dist/inbound-mail-foundation/handlers/list-accounts.query.js

@@ -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, } from "@cosmicdrift/kumiko-framework/crypto";
 import { MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";

package/dist/inbound-mail-foundation/handlers/list-messages.query.js

@@ -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, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
 import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.js";
@@ -35,8 +35,8 @@ export const listMessagesQuery = {
         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)

package/dist/inbound-mail-foundation/handlers/scope-visibility.js

@@ -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, user) {
     const owner = row["ownerUserId"];
     if (owner == null || owner === "")

package/dist/inbound-mail-foundation/handlers/update-account.write.d.ts

@@ -1,4 +1,4 @@
-import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 export declare const updateAccountSchema: z.ZodObject<{
     accountId: z.ZodUUID;
@@ -9,6 +9,6 @@ export declare const updateAccountSchema: z.ZodObject<{
     }>>;
     watchState: z.ZodOptional<z.ZodString>;
     displayName: z.ZodOptional<z.ZodString>;
-    reason: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const updateAccountHandler: WriteHandlerDef;

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

@@ -1,7 +1,9 @@
-// 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 { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { InboundMailAccountStatuses } from "../constants.js";
@@ -19,10 +21,16 @@ 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",
-     *  "oauth_refresh", "tenant_admin"). */
-    reason: z.string().min(1).max(100),
+    /** Audit reason for metadata.headers, honored for the system identity only
+     *  ("watch_supervisor", "oauth_refresh"); user callers get a role-derived reason. */
+    reason: z.string().min(1).max(100).optional(),
 });
+const SYSTEM_FALLBACK_REASON = "system";
+function auditReasonFor(user, requestedReason) {
+    if (user.id === SYSTEM_USER_ID)
+        return requestedReason ?? SYSTEM_FALLBACK_REASON;
+    return user.roles.includes(ROLES.SystemAdmin) ? "system_admin" : "tenant_admin";
+}
 export const updateAccountHandler = {
     name: "update-account",
     schema: updateAccountSchema,
@@ -36,14 +44,14 @@ export const updateAccountHandler = {
             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 = {
             ...current,
             ...(payload.status !== undefined ? { status: payload.status } : {}),
@@ -52,7 +60,7 @@ export const updateAccountHandler = {
         };
         const headers = {
             providerName: current.provider,
-            reason: payload.reason,
+            reason: auditReasonFor(event.user, payload.reason),
         };
         await ctx.unsafeAppendEvent({
             aggregateId: payload.accountId,

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

@@ -31,5 +31,4 @@ export const INBOUND_MAIL_FOUNDATION_I18N = {
     },
     [formFieldKey("accountId")]: { en: "Mailbox" },
     [formFieldKey("displayName")]: { en: "Name" },
-    [formFieldKey("reason")]: { en: "Reason" },
 };

package/dist/inbound-mail-foundation/oauth-state.d.ts

@@ -1,14 +1,14 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 export type OAuthStatePayload = {
     readonly tenantId: string;
-    /** null = shared-Postfach, sonst persönliches Postfach dieses Users. */
+    /** null = shared mailbox; otherwise this user's personal mailbox. */
     readonly ownerUserId: string | null;
     readonly providerKey: string;
-    /** Postfach-Adresse aus dem Connect-Request — landet nach dem
-     *  Token-Exchange im MailAccount. */
+    /** Mailbox address from the connect request; after token exchange, it is
+     * stored in the MailAccount. */
     readonly mailbox: string;
-    /** Einmal-Nonce — macht jeden state einzigartig (kein Replay über
-     *  zwei parallele Connect-Flows hinweg). */
+    /** One-time nonce makes each state unique, preventing replay across
+     * two parallel connect flows. */
     readonly nonce: string;
 };
 export type VerifyOAuthStateResult = {

package/dist/inbound-mail-foundation/oauth-state.js

@@ -1,14 +1,15 @@
-// HMAC-signierter OAuth-`state`-Parameter für den Connect-Flow.
+// HMAC-signed OAuth-`state` parameter for the connect flow.
 //
-// Bindet {tenantId, ownerUserId?, providerKey, mailbox, nonce} an den
-// Redirect: der anonyme Callback (außerhalb /api/*) vertraut NUR dem
-// verifizierten state — verhindert CSRF und Fremd-Claiming (ein
-// Angreifer kann den Callback nicht auf einen fremden Tenant/User
-// umbiegen, ohne die Signatur zu brechen).
+// Binds {tenantId, ownerUserId?, providerKey, mailbox, nonce} to the
+// redirect: the anonymous callback (outside /api/*) trusts only the
+// verified state, preventing CSRF and cross-tenant or cross-user claiming
+// because an attacker cannot redirect the callback to another tenant or
+// user without breaking the signature.
 //
 // Format: <payload-base64url>.<expiresAtMs>.<hmac-base64url>
-// Muster: auth-email-password/signed-token.ts (HMAC-SHA256, purpose im
-// HMAC-Input, timing-safe compare, Expiry im Klartext-Segment).
+// Patterned after auth-email-password/signed-token.ts (HMAC-SHA256, purpose
+// in the HMAC input, timing-safe comparison, expiry in the clear-text
+// segment).
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
@@ -40,8 +41,8 @@ export function verifyOAuthState(state, secret, now = Temporal.Now.instant()) {
     const expected = sign(hmacInput(payloadB64, expiresAtMs), secret);
     const expectedBuf = Buffer.from(expected, "base64url");
     const providedBuf = Buffer.from(providedSig, "base64url");
-    // Length-check VOR timingSafeEqual — die würde bei Längen-Mismatch
-    // werfen, und der Throw selbst leakt via Timing.
+    // Check the length before timingSafeEqual: it throws on a length mismatch,
+    // and the throw itself leaks information through timing.
     if (expectedBuf.length !== providedBuf.length)
         return { ok: false, reason: "bad_signature" };
     if (!timingSafeEqual(expectedBuf, providedBuf))

package/dist/inbound-mail-foundation/projection.d.ts

@@ -130,12 +130,12 @@ export declare const mailThreadsProjectionTable: import("@cosmicdrift/kumiko-fra
 }, "tenant">>;
 /** mail-account-connected → UPSERT full. */
 export declare const applyMailAccountConnected: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
-/** mail-account-updated → UPSERT full (status/watchState-Übergänge). */
+/** mail-account-updated → full UPSERT for status/watchState transitions. */
 export declare const applyMailAccountUpdated: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
-/** mail-account-disconnected → UPSERT full (payload.status=disconnected).
- *  Row bleibt (Audit-Sicht in der Account-Liste), Stream bleibt. */
+/** mail-account-disconnected → full UPSERT (payload.status=disconnected).
+ *  The row and stream remain for audit visibility in the account list. */
 export declare const applyMailAccountDisconnected: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
 /** inbound-message-received → INSERT ... ON CONFLICT DO NOTHING. */
 export declare const applyInboundMessageReceived: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
-/** mail-thread-updated → UPSERT full mit dem Payload-Snapshot. */
+/** mail-thread-updated → full UPSERT with the payload snapshot. */
 export declare const applyMailThreadUpdated: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;

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

@@ -1,26 +1,27 @@
-// Inline-projections für die drei event-sourced Streams:
+// Inline projections for the three event-sourced streams:
 //   mail-account     → read_mail_accounts     (UPSERT, current state)
 //   inbound-message  → read_inbound_messages  (INSERT-ignore, append-only)
-//   mail-thread      → read_mail_threads      (UPSERT, Rollup)
+//   mail-thread      → read_mail_threads      (UPSERT, rollup)
 //
-// Apply läuft in derselben TX wie ctx.unsafeAppendEvent — read-your-
-// own-write ohne dispatcher-tick (Muster billing-foundation).
+// Apply runs in the same transaction as ctx.unsafeAppendEvent, providing
+// read-your-own-write without waiting for a dispatcher tick (as in
+// billing-foundation).
 //
-// **Production-deployment caveat** (gleich wie billing-foundation):
-// die Tables sind als raw drizzle-pgTable in r.projection registriert,
-// NICHT als r.entity — Apps müssen sie in ihre drizzle/generate.ts
-// aufnehmen (via *-ProjectionTable-Imports). setupTestStack pusht sie
-// automatisch via r.projection.table.
+// **Production-deployment caveat** (same as billing-foundation):
+// The tables are registered as raw drizzle-pgTable instances in r.projection,
+// NOT as r.entity. Apps must include them in their drizzle/generate.ts
+// (via *-ProjectionTable imports). setupTestStack pushes them automatically
+// via r.projection.table.
 //
-// **PII:** die Payload-Felder (address/from/to/cc/subject/snippet)
-// kommen bereits als Ciphertext an — encrypted VOR dem append im
-// write-handler. Die applies kopieren nur durch; decrypted wird erst
-// in den list-queries.
+// **PII:** The payload fields (address/from/to/cc/subject/snippet) already
+// arrive as ciphertext because they are encrypted BEFORE the append in the
+// write handler. The applies only copy them through; decryption happens only
+// in the list queries.
 import { buildEntityTable, insertOnConflictDoNothing, requireEntityTableMeta, upsertOnConflict, } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities.js";
-// Drizzle-table-instances aus den entity-shapes — geteilt zwischen
-// projection-applies und list-queries (ein column-namespace).
+// Drizzle table instances derived from the entity shapes, shared between
+// projection applies and list queries to provide one column namespace.
 export const mailAccountsProjectionTable = buildEntityTable("mail-account", mailAccountEntity);
 export const inboundMessagesProjectionTable = buildEntityTable("inbound-message", inboundMessageEntity);
 export const mailThreadsProjectionTable = buildEntityTable("mail-thread", mailThreadEntity);
@@ -30,9 +31,10 @@ const mailAccountsProjectionMeta = requireEntityTableMeta(mailAccountsProjection
 const inboundMessagesProjectionMeta = requireEntityTableMeta(inboundMessagesProjectionTable, "inbound-message");
 const mailThreadsProjectionMeta = requireEntityTableMeta(mailThreadsProjectionTable, "mail-thread");
 // =============================================================================
-// mail-account — connected/updated/disconnected teilen den payload-shape,
-// der event-type taggt was passiert ist. Alle drei UPSERT-full für
-// defensive consistency (rebuild-aus-dem-Nichts, out-of-order).
+// mail-account — connected/updated/disconnected share the payload shape;
+// the event type identifies what happened. All three perform a full UPSERT
+// for defensive consistency during from-scratch rebuilds and out-of-order
+// processing.
 // =============================================================================
 const applyMailAccountUpsert = defineApply(async (event, tx) => {
     const p = event.payload;
@@ -57,15 +59,15 @@ const applyMailAccountUpsert = defineApply(async (event, tx) => {
 });
 /** mail-account-connected → UPSERT full. */
 export const applyMailAccountConnected = applyMailAccountUpsert;
-/** mail-account-updated → UPSERT full (status/watchState-Übergänge). */
+/** mail-account-updated → full UPSERT for status/watchState transitions. */
 export const applyMailAccountUpdated = applyMailAccountUpsert;
-/** mail-account-disconnected → UPSERT full (payload.status=disconnected).
- *  Row bleibt (Audit-Sicht in der Account-Liste), Stream bleibt. */
+/** mail-account-disconnected → full UPSERT (payload.status=disconnected).
+ *  The row and stream remain for audit visibility in the account list. */
 export const applyMailAccountDisconnected = applyMailAccountUpsert;
 // =============================================================================
-// inbound-message — genau EIN received-event pro Stream (deterministic
-// aggregateId). INSERT-ignore: Replays no-op'en auf der PK statt zu
-// knallen; es gibt keinen update-Fall.
+// inbound-message — exactly one received event per stream (deterministic
+// aggregateId). INSERT-ignore makes replays no-ops on the primary key;
+// there is no update case.
 // =============================================================================
 /** inbound-message-received → INSERT ... ON CONFLICT DO NOTHING. */
 export const applyInboundMessageReceived = defineApply(async (event, tx) => {
@@ -88,12 +90,12 @@ export const applyInboundMessageReceived = defineApply(async (event, tx) => {
     });
 });
 // =============================================================================
-// mail-thread — Rollup pro (tenantId, threadKey). Der write-handler
-// berechnet messageCount/lastMessageAt und appendet den updated-event
-// mit dem NEUEN Stand — die apply ist ein dummer UPSERT-full (kein
-// increment in der apply: Replays wären sonst nicht idempotent).
+// mail-thread — rollup per (tenantId, threadKey). The write handler computes
+// messageCount/lastMessageAt and appends the updated event with the NEW state.
+// The apply performs a full UPSERT rather than incrementing, because
+// replays would otherwise not be idempotent.
 // =============================================================================
-/** mail-thread-updated → UPSERT full mit dem Payload-Snapshot. */
+/** mail-thread-updated → full UPSERT with the payload snapshot. */
 export const applyMailThreadUpdated = defineApply(async (event, tx) => {
     const p = event.payload;
     const mutable = {

package/dist/inbound-mail-foundation/provider-factory.d.ts

@@ -1,7 +1,7 @@
 import { type InboundMailContext, type InboundMailProviderPlugin, type MailAccountRecord } from "./types.ts";
-/** Lookup per Provider-Key ("imap", "m365-graph", ...) — genutzt von den
- *  OAuth-Connect-Routen, wo noch kein Account existiert. */
+/** Looks up a provider by key ("imap", "m365-graph", ...); used by OAuth
+ *  connect routes before an account exists. */
 export declare function resolveInboundProviderForKey(ctx: InboundMailContext, providerKey: string, handlerName?: string): InboundMailProviderPlugin;
-/** Lookup für einen konkreten Account — der Standard-Pfad in Poll-Job
- *  und Watch-Supervisor. */
+/** Looks up the provider for a specific account; the standard path for poll jobs
+ *  and the watch supervisor. */
 export declare function resolveInboundProviderForAccount(ctx: InboundMailContext, account: MailAccountRecord, handlerName?: string): InboundMailProviderPlugin;

package/dist/inbound-mail-foundation/provider-factory.js

@@ -1,12 +1,12 @@
-// Provider-Factory — Mirror von mail-foundation's createTransportForTenant
-// inkl. der drei Fehlerpfade (kein registry / nicht registriert / falsche
-// Plugin-Shape). Abweichung zum Outbound-Muster (Plan §1.3): KEIN
-// per-Tenant-Config-Selector — der Provider steht pro MailAccount
-// (`account.provider`), ein Tenant kann mehrere Provider parallel nutzen.
+// Provider factory — mirrors mail-foundation's createTransportForTenant, including
+// the three error paths (missing registry, unregistered provider, invalid plugin
+// shape). Unlike the outbound pattern, there is no per-tenant config selector:
+// the provider is specified per MailAccount (`account.provider`), so a tenant can
+// use multiple providers in parallel.
 import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.js";
 import { isInboundMailProviderPlugin, } from "./types.js";
-/** Lookup per Provider-Key ("imap", "m365-graph", ...) — genutzt von den
- *  OAuth-Connect-Routen, wo noch kein Account existiert. */
+/** Looks up a provider by key ("imap", "m365-graph", ...); used by OAuth
+ *  connect routes before an account exists. */
 export function resolveInboundProviderForKey(ctx, providerKey, handlerName = "inbound-mail-foundation:provider-factory") {
     if (!ctx.registry) {
         throw new Error(`${handlerName}: ctx.registry is missing — required to look up registered inbound-mail provider plugins`);
@@ -24,8 +24,8 @@ export function resolveInboundProviderForKey(ctx, providerKey, handlerName = "in
     }
     return usage.options;
 }
-/** Lookup für einen konkreten Account — der Standard-Pfad in Poll-Job
- *  und Watch-Supervisor. */
+/** Looks up the provider for a specific account; the standard path for poll jobs
+ *  and the watch supervisor. */
 export function resolveInboundProviderForAccount(ctx, account, handlerName = "inbound-mail-foundation:provider-factory") {
     return resolveInboundProviderForKey(ctx, account.provider, handlerName);
 }

package/dist/inbound-mail-foundation/retention-sweep.d.ts

@@ -7,12 +7,14 @@ export declare const SEEN_RETENTION_DAYS = 90;
 export interface InboundRetentionArgs {
     readonly db: DbRunner;
     readonly tenantId: TenantId;
-    /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
+    /**
+     * Injects the current time so tests can pin it without a date mock (pattern from keep-for.ts).
+     */
     readonly now: Instant;
     readonly messageRetentionDays?: number;
     readonly seenRetentionDays?: number;
-    /** Loescht ein file-storage-Body-Objekt per bodyRef-key. Vom Job lazy
-     *  verdrahtet (createFileProviderForTenant). Fehlt = kein Body-Delete. */
+    /** Deletes a file-storage body object by bodyRef key. Wired lazily by the job
+     * (createFileProviderForTenant); if absent, no body is deleted. */
     readonly deleteBodyObject?: (bodyRef: string) => Promise<void>;
 }
 export interface InboundRetentionReport {