@cosmicdrift/kumiko-bundled-features 0.385.0 → 0.387.0

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.js

@@ -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 { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { InboundMailAccountStatuses } from "../constants.js";
@@ -19,7 +19,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),
 });
@@ -36,14 +36,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 } : {}),

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 {

package/dist/inbound-mail-foundation/retention-sweep.js

@@ -1,28 +1,30 @@
-// Inbound-mail data-retention (#957). DSGVO Art. 5 (Datenminimierung):
-// ohne Retention wachsen read_inbound_messages + die File-Storage-Bodies
-// unbegrenzt. Zwei Targets, zwei Mechanismen — der Unterschied ist
-// event-sourced vs. unmanaged:
+// Inbound-mail data retention. DSGVO Art. 5 (data minimization):
+// without retention, read_inbound_messages and the file-storage bodies grow
+// without bound. Two targets, two mechanisms—the difference is
+// event-sourced versus unmanaged:
 //
-//   read_inbound_messages (event-sourced, EXPLIZITE r.projection):
-//     pro Row aelter als messageRetentionDays → archiveStream + Row-Delete
-//     (+ bodyRef-Objekt loeschen). archiveStream statt executor.forget, weil
-//     die Projection nur das received-Domain-Event mappt, nicht den
-//     forgotten-Auto-Verb (den registriert nur ImplicitProjection). Ein
-//     forget-Event wuerde beim Rebuild ignoriert und die Row aus dem
-//     received-Event resurrecten (#648-Klasse). Der archivierte Stream macht
-//     loadAggregate leer → received wird gar nicht erst repliziert. Gleiches
-//     Muster wie tenant-destroy-hook, nur per-Row-cutoff statt ganzer Tenant.
+//   read_inbound_messages (event-sourced, EXPLICIT r.projection):
+//     each Row older than messageRetentionDays → archiveStream + Row delete
+//     (+ delete the bodyRef object). archiveStream instead of executor.forget
+//     because the projection maps only the received domain event, not the
+//     forgotten auto-verb (which only ImplicitProjection registers). A
+//     forget event would be ignored during a rebuild, causing the Row to be
+//     resurrected from the received event. The archived stream makes
+//     loadAggregate empty, so received is not replicated in the first place.
+//     Same pattern as tenant-destroy-hook, but with a per-Row cutoff instead
+//     of an entire Tenant.
 //
-//   store_mail_seen_messages (unmanaged, direct-write, nicht event-sourced):
-//     Dedup-Anker braucht nur das Backfill-/Replay-Fenster → seenAt-cutoff
-//     via plain deleteMany, kein Stream/Archiv. Gescoped direkt über die
-//     tenant_id-Spalte der Tabelle (table-builder-Konvention), kein Account-Join.
+//   store_mail_seen_messages (unmanaged, direct-write, not event-sourced):
+//     The deduplication anchor is needed only for the backfill/replay window →
+//     seenAt cutoff via plain deleteMany, with no stream/archive. Scoped
+//     directly through the table's tenant_id column (table-builder convention),
+//     without an Account join.
 //
-// GRENZE (#957 Teil 2, Plan §3.4): die PII in den Message-Events bleibt
-// unter dem TENANT-Subject-Key entschluesselbar — per-Row-Retention
-// shreddet keinen Key. Echte Art.-17-Erasure der Event-Payloads passiert
-// erst bei tenant-destroy (Key-Erase). Read-Row + Body-File sind nach dem
-// Sweep weg; das Event-Log ist append-only by design.
+// LIMITATION: the PII in the message events remains decryptable under the
+// TENANT subject key—per-Row retention does not shred a key. Actual Art.-17
+// erasure of event payloads happens only during tenant-destroy (key erasure).
+// The read Row and body file are gone after the sweep; the event log is
+// append-only by design.
 import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { archiveStream, deleteRowsWithoutReplayableStream, } from "@cosmicdrift/kumiko-framework/event-store";
 import { seenMessageTable } from "./entities.js";
@@ -46,18 +48,18 @@ async function purgeExpiredMessages(args, cutoff) {
     let messagesPurged = 0;
     let bodyObjectsDeleted = 0;
     let bodyObjectErrors = 0;
-    // Drain-Loop: jede Page loescht die Rows die sie liest, die naechste ist
-    // damit frisch. archiveStream VOR dem Delete (crash dazwischen → naechster
-    // Lauf re-archiviert idempotent + loescht). Delete strikt nach den
-    // archivierten ids, nie per cutoff-WHERE — sonst koennte eine zwischen
-    // select und delete eingegangene Alt-Mail unarchiviert geloescht werden
-    // und beim Rebuild resurrecten.
+    // Drain loop: each page deletes the Rows it reads, so the next page is fresh.
+    // Run archiveStream BEFORE deletion: if a crash occurs in between, the next
+    // run re-archives idempotently and deletes the Row. Delete strictly by the
+    // archived IDs, never with a cutoff WHERE; otherwise an old mail arriving
+    // between select and delete could be deleted without being archived and
+    // resurrected during a rebuild.
     //
-    // Ein Row deren deleteBodyObject fehlschlaegt wird NICHT geloescht — sonst
-    // ginge die einzige Referenz auf das (dann verwaiste) File-Objekt verloren
-    // (kein Retry, kein Dead-Letter). Die Row bleibt fuer den naechsten Sweep
-    // stehen (archiveStream ist idempotent). failedIds verhindert, dass so ein
-    // Row innerhalb DIESES Laufs endlos re-selektiert wird.
+    // A Row whose deleteBodyObject fails is NOT deleted; otherwise the only
+    // reference to the now-orphaned file object would be lost (no retry or
+    // dead-letter). The Row remains for the next sweep (archiveStream is
+    // idempotent). failedIds prevents such a Row from being selected endlessly
+    // during THIS run.
     const failedIds = new Set();
     for (;;) {
         const rows = (await selectMany(args.db, inboundMessagesProjectionTable, { receivedAt: { lt: cutoff }, tenantId: args.tenantId }, { limit: BATCH_LIMIT })).filter((row) => !failedIds.has(row.id));
@@ -99,9 +101,9 @@ async function purgeExpiredMessages(args, cutoff) {
     return { messagesPurged, bodyObjectsDeleted, bodyObjectErrors };
 }
 async function purgeExpiredSeenAnchors(db, tenantId, cutoff) {
-    // Seen-Anker erben tenantId (table-builder: jede Entity hat tenant_id) →
-    // direkt tenant-scoped, kein Account-Join. Trifft auch Anker, deren Account
-    // schon disconnected/geloescht ist.
+    // Seen anchors inherit tenantId (table-builder: every Entity has tenant_id) →
+    // scoped directly to the tenant, without an Account join. This also includes
+    // anchors whose Account has already been disconnected or deleted.
     const where = { tenantId, seenAt: { lt: cutoff } };
     const expired = await selectMany(db, seenMessageTable, where);
     if (expired.length === 0)

package/dist/inbound-mail-foundation/tenant-destroy-hook.js

@@ -1,21 +1,19 @@
-// Tenant-destroy hooks — räumen beim Tenant-Destroy alle Inbound-Mail-
-// Spuren des Tenants ab. Ein Hook PRO tenant-subject-Entity (der
-// gdpr-storage-Boot-Validator prüft die EXT_TENANT_DATA-Registrierung
-// entity-genau), jeweils:
+// Tenant-destroy hooks remove all inbound-mail traces belonging to the tenant.
+// One hook per tenant-subject entity (the gdpr-storage boot validator checks
+// the EXT_TENANT_DATA registration per entity), each of which:
 //
-//   1. Streams archivieren — ein künftiger Projection-Rebuild kann
-//      Gelöschtes nicht resurrecten (Muster billing-foundation #800).
-//      Message-Streams sind viele → Loop über die Projection-Rows
-//      (Row-PK = Stream-ID); tenant-destroy ist ein seltener
-//      Batch-Vorgang, O(n) ist ok.
-//   2. Projection-Rows löschen.
-//   3. Nur mail-account: unmanaged Sync-State (Cursors, Seen-Anchors)
-//      löschen — gekeyt per accountId, deshalb aus den Account-Rows
-//      VOR dem Delete eingesammelt.
+//   1. Archives streams so a future projection rebuild cannot resurrect
+//      deleted data. Message streams are numerous, so loop over the
+//      projection rows (row PK = stream ID); tenant-destroy is a rare batch
+//      operation, so O(n) is acceptable.
+//   2. Deletes the projection rows.
+//   3. For mail-account only, deletes unmanaged sync state (cursors,
+//      seen anchors), which is keyed by accountId and must therefore be
+//      collected from the account rows BEFORE deletion.
 //
-// Die eigentliche PII-Erasure macht crypto-shredding: eraseSubjectKeys
-// löscht den Tenant-Subject-Key, damit werden Event-Log-Payloads UND
-// etwaige Ciphertext-Kopien unlesbar. Diese Hooks entsorgen die Rows.
+// The actual PII erasure uses crypto-shredding: eraseSubjectKeys deletes the
+// tenant subject key, making event-log payloads AND any ciphertext copies
+// unreadable. These hooks dispose of the rows.
 import { declareEscapeHatch } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { seenMessageTable, syncCursorTable } from "./entities.js";