@cosmicdrift/kumiko-bundled-features 0.386.0 → 0.388.0

package/dist/form-draft/db/queries/cleanup.js

@@ -1,4 +1,4 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { readStoredDraft } from "../../decrypt-draft.js";
 // COALESCE(modified_at, inserted_at) — a draft's "last touched" timestamp is
@@ -6,7 +6,7 @@ import { readStoredDraft } from "../../decrypt-draft.js";
 // once; a draft saved exactly once (create, never updated) has no
 // modified_at yet, so falls back to inserted_at.
 //
-// Reads the blob + tenantId BEFORE anything is deleted (issue #1915) — the
+// Reads the blob + tenantId BEFORE anything is deleted — the
 // caller (cleanup.job.ts) walks each row's blob for FileRefs and releases
 // them per-tenant via ctx._fileProviderResolver, then deletes the batch
 // per-row via formDraftExecutor.delete (event-sourced, not raw SQL — a
@@ -17,7 +17,7 @@ export async function selectStaleDraftsBatch(db, olderThanDays, batchSize, exclu
      WHERE COALESCE("modified_at", "inserted_at") < now() - ($1::int * interval '1 day')
      AND NOT ("id"::text = ANY($3::text[]))
      ORDER BY COALESCE("modified_at", "inserted_at") ASC
-     LIMIT $2`, [olderThanDays, batchSize, [...excludeIds]]);
+     LIMIT $2`, [olderThanDays, batchSize, toPostgresArrayLiteral([...excludeIds])]);
     return Promise.all(rows.map(async (row) => {
         const base = {
             id: row.id,

package/dist/form-draft/db/queries/owned-file-refs.js

@@ -1,6 +1,6 @@
 import { instantToTimestamptzParam, toPostgresArrayLiteral, unsafeReadRetrying, } from "@cosmicdrift/kumiko-framework/db";
 // Narrows a draft blob's raw FileRef-shaped storageKeys (collectDraftFileRefKeys
-// output — extracted from free-form, client-supplied JSON, issue #1889) down to
+// output — extracted from free-form, client-supplied JSON) down to
 // the ones with a real, non-deleted file_refs row owned by this exact
 // (tenantId, ownerId). Without this, a crafted draft value like
 // { storageKey: "<someone-else's-real-key>" } would reach the storage

package/dist/form-draft/decrypt-draft.js

@@ -1,5 +1,6 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, } from "@cosmicdrift/kumiko-framework/crypto";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { formDraftBlobSchema } from "./schemas.js";
 // Raw reads (fetchOne/selectMany/SQL) return the stored column, which is
 // ciphertext once the owner's key exists. The field name is part of the AAD,
@@ -8,7 +9,10 @@ import { formDraftBlobSchema } from "./schemas.js";
 export async function readStoredDraft(stored) {
     let plain = stored;
     const kms = configuredPiiSubjectKms();
-    if (isPiiCiphertext(stored) && kms) {
+    if (isPiiCiphertext(stored)) {
+        // A silent null would make the stale-draft cleanup treat the draft as empty and leak its file refs.
+        if (!kms)
+            throw new InternalError({ message: "form-draft: pii kms not configured" });
         const out = await decryptPiiFieldValues({ draft: stored }, ["draft"], kms, {
             requestId: requestContext.get()?.requestId ?? "form-draft:read",
         });

package/dist/form-draft/entity.js

@@ -6,8 +6,8 @@ import { FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_UNIQUE_KEY_CONSTRAINT } from "./w
 // (tenant, ownerId): the same key from two different users, or the same
 // user in two different tenants, is a different draft.
 //
-// Boundary (issue #1889): form-draft never holds anything that already
-// lives in a domain stream — it's a Zwischenstand BEFORE the domain entity
+// Boundary: form-draft never holds anything that already
+// lives in a domain stream — it's an intermediate state BEFORE the domain entity
 // is created. Consumers delete the draft (discard handler) once the real
 // submit succeeds; partially-created domain data past that point is the
 // consuming app's concern, not this feature's.
@@ -29,7 +29,7 @@ export const formDraftEntity = createEntity({
             personal: false,
             reason: "technical_reference",
         }),
-        // The blob shape is fixed by issue #1889, not left to the caller:
+        // The blob shape is fixed, not left to the caller:
         // { values: Record<string, unknown>, stepIndex: number, savedAt: string }.
         // Free-form because `values` mirrors whatever fields the in-progress
         // form has, so it can carry arbitrary user-entered PII. Encrypted under

package/dist/form-draft/feature.js

@@ -1,9 +1,8 @@
 // form-draft — a per-user, per-tenant working copy of an in-progress form,
-// saved BEFORE the real domain entity exists. Backing for wizard-mode resume
-// (kumiko-framework#1884/#1883): a caller-assigned draftKey (typically
-// screenId + optional hostEntityId) round-trips { values, stepIndex,
-// savedAt } through save/discard/get. See entity.ts for the ownership +
-// uniqueness model.
+// saved BEFORE the real domain entity exists. Backing for wizard-mode resume.
+// A caller-assigned draftKey (typically screenId + optional hostEntityId)
+// round-trips { values, stepIndex, savedAt } through save/discard/get. See
+// entity.ts for the ownership + uniqueness model.
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { formDraftEntity } from "./entity.js";
 import { cleanupDraftsJob, formDraftRetentionDaysConfig } from "./handlers/cleanup.job.js";

package/dist/form-draft/handlers/discard.write.js

@@ -63,7 +63,7 @@ export const discardDraftWrite = defineWriteHandler({
             // Fail-closed erase of file_refs rows FIRST (outside the best-effort
             // storage-hygiene loop). releaseDraftFileRefs swallows per-key errors
             // by design — routing forget through it would report discarded:true
-            // while leaving the row behind (#1922 / review #2009).
+            // while leaving the row behind.
             for (const ref of ownedRefs) {
                 const forgetResult = await fileRefExecutor.forget({ id: ref.id }, event.user, ctx.db);
                 if (!forgetResult.isSuccess)

package/dist/form-draft/release-file-refs.js

@@ -1,5 +1,5 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-// The draft blob's `values` is free-form by design (issue #1889: form-draft
+// The draft blob's `values` is free-form by design: form-draft
 // never knows the consuming form's field schema, only { values, stepIndex,
 // savedAt }). A FileRef pointer is therefore recognised purely by shape —
 // any object anywhere in `values` carrying a non-empty string `storageKey`
@@ -45,11 +45,11 @@ export function collectDraftFileRefKeys(draft) {
 //
 // Takes an already-decided key list, not the draft blob — callers must run
 // collectDraftFileRefKeys() output through db/queries' owned-storage-key
-// filter first. `values` is free-form, client-supplied JSON (issue #1889);
-// releasing a key straight out of it without verifying a real, owned
-// file_refs row exists would let a crafted `{ storageKey: "<victim's key>" }`
-// delete someone else's file — the same ownership check file-routes.ts runs
-// before every read/delete (loadFileForTenant + FileAccessGuard).
+// filter first. `values` is free-form, client-supplied JSON; releasing a key
+// straight out of it without verifying a real, owned file_refs row exists
+// would let a crafted `{ storageKey: "<victim's key>" }` delete someone
+// else's file — the same ownership check file-routes.ts runs before every
+// read/delete (loadFileForTenant + FileAccessGuard).
 export async function releaseDraftFileRefs(keys, deleteBinary, log) {
     for (const key of keys) {
         try {

package/dist/form-draft/schemas.js

@@ -10,9 +10,9 @@ function jsonByteLength(value) {
 const draftValuesSchema = z
     .record(z.string(), z.unknown())
     .refine((values) => jsonByteLength(values) <= FORM_DRAFT_VALUES_MAX_BYTES, `values exceeds the ${FORM_DRAFT_VALUES_MAX_BYTES}-byte limit`);
-// The draft blob shape — fixed by issue #1889 here, not left for consumers
+// The draft blob shape — fixed here, not left for consumers
 // to invent per-app. `stepIndex` is in from the start so wizard-mode resume
-// (kumiko-framework#1884) doesn't need a later migration.
+// doesn't need a later migration.
 export const formDraftBlobSchema = z.object({
     values: z.record(z.string(), z.unknown()),
     stepIndex: z.number().int().min(0),
@@ -30,7 +30,7 @@ export const saveDraftPayloadSchema = z.object({
 // row right after the domain entity write already carries the same
 // storageKeys forward — releasing them here would destroy files the entity
 // now depends on. Only an actual abandon/abort flow should pass
-// releaseFiles: true (issue #1915's "explicit abort" case).
+// releaseFiles: true (the "explicit abort" case).
 export const discardDraftPayloadSchema = z.object({
     draftKey: draftKeySchema,
     releaseFiles: z.boolean().optional(),

package/dist/form-draft/web/constants.js

@@ -1,6 +1,4 @@
 // form-draft bundle constants — feature-name + qualified handler/query names.
-//
-// Part of CosmicDriftGameStudio/kumiko-framework#1883 (wizard mode), issue #1889.
 export const FORM_DRAFT_FEATURE_NAME = "form-draft";
 // Qualified handler/query names (QN format: scope:type:name). Clients
 // reference the object instead of magic strings.

package/dist/host-routing/dispatch.js

@@ -6,38 +6,29 @@ import { classifyHost, splitFirstSegment, tenantKeyFromPath } from "./host.js";
 import { matchRedirect, sameOriginPath } from "./redirects.js";
 import { validateHostRoutingOptions } from "./validate-options.js";
 const tenantKeyExistsResultSchema = z.object({ exists: z.boolean() });
-async function isTenantKeyKnown(systemQuery, key) {
+async function existsViaSystemQuery(systemQuery, queryType, payload) {
     let result;
     try {
-        result = await systemQuery(HostRoutingQueries.tenantKeyExists, { key }, SYSTEM_TENANT_ID);
+        result = await systemQuery(queryType, payload, SYSTEM_TENANT_ID);
     }
     catch (error) {
         if (error instanceof ValidationError)
             return false;
-        // Over the rate limit every key looks the same: serve the tenant shell,
-        // which leaks nothing; the API behind it still resolves the tenant itself.
+        // Over the rate limit every key looks the same: serve the shell, which
+        // leaks nothing. The API resolver is authoritative and answers
+        // tenant_required for unknown hosts, while a 404 would hit visitors
+        // behind a shared NAT under load.
         if (error instanceof RateLimitError)
             return true;
         throw error;
     }
     return tenantKeyExistsResultSchema.parse(result).exists;
 }
-async function isHostKnown(systemQuery, host) {
-    let result;
-    try {
-        result = await systemQuery(HostRoutingQueries.hostTenantExists, { host }, SYSTEM_TENANT_ID);
-    }
-    catch (error) {
-        if (error instanceof ValidationError)
-            return false;
-        // The shell is harmless: the API resolver is authoritative and answers
-        // tenant_required for unknown hosts, while a 404 would hit visitors behind
-        // a shared NAT under load.
-        if (error instanceof RateLimitError)
-            return true;
-        throw error;
-    }
-    return tenantKeyExistsResultSchema.parse(result).exists;
+function isTenantKeyKnown(systemQuery, key) {
+    return existsViaSystemQuery(systemQuery, HostRoutingQueries.tenantKeyExists, { key });
+}
+function isHostKnown(systemQuery, host) {
+    return existsViaSystemQuery(systemQuery, HostRoutingQueries.hostTenantExists, { host });
 }
 function serve(surface, file = surface.file) {
     return surface.csp === undefined

package/dist/inbound-mail-foundation/aggregate-id.d.ts

@@ -1,20 +1,20 @@
 /**
- * Deterministic aggregate-id für eine inbound-message. Key ist
- * (accountId, providerMessageId): derselbe Provider-Fetch der zweimal
- * dieselbe Message liefert (IDLE-Doppel-Notify, Cursor-Overlap,
- * Watch-Restart-Replay) landet auf demselben Stream — der Idempotency-
- * Check im ingest-handler sieht den bereits appendeten Event.
+ * Deterministic aggregate ID for an inbound message. The key is
+ * (accountId, providerMessageId): if the provider delivers the same message
+ * twice (IDLE duplicate notification, cursor overlap, watch-restart replay),
+ * both deliveries use the same stream, so the idempotency check in the
+ * ingest handler sees the event that was already appended.
  *
- * accountId (nicht tenantId) im Key: zwei Accounts desselben Tenants
- * können dieselbe Mail empfangen (CC an beide Postfächer) — das sind
- * fachlich ZWEI inbound-messages.
+ * accountId, rather than tenantId, is part of the key because two accounts in
+ * the same tenant can receive the same email (CC'd to both inboxes); these
+ * are two distinct inbound messages.
  */
 export declare function inboundMessageAggregateId(accountId: string, providerMessageId: string): string;
 /**
- * Deterministic aggregate-id für einen mail-thread. Key ist
- * (tenantId, threadKey) — Threads sind tenant-weit, nicht account-weit:
- * eine Konversation die über zwei verbundene Postfächer läuft ist EIN
- * Thread. threadKey kommt normalisiert vom Provider (References/
- * In-Reply-To-Chain bzw. Provider-Thread-ID).
+ * Deterministic aggregate ID for a mail thread. The key is
+ * (tenantId, threadKey): threads are tenant-wide, not account-specific, so a
+ * conversation spanning two connected inboxes is one thread. threadKey is
+ * normalized by the provider (References/In-Reply-To chain or provider
+ * thread ID).
  */
 export declare function mailThreadAggregateId(tenantId: string, threadKey: string): string;

package/dist/inbound-mail-foundation/aggregate-id.js

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

package/dist/inbound-mail-foundation/connect-routes.js

@@ -1,5 +1,5 @@
-// createInboundMailConnectRoutes — declarative extraRoutes (kumiko-
-// framework#3050) the app owner mounts via `extraRoutes` in buildServer.
+// createInboundMailConnectRoutes — declarative extraRoutes the app owner mounts
+// via `extraRoutes` in buildServer.
 //
 //   GET /api/inbound-mail/connect      (entry:"user" — signed-in caller)
 //   GET /inbound-mail/oauth/callback   (entry:"signature" — anonymous,
@@ -10,6 +10,7 @@
 // resolved via resolveInboundProviderForKey. The callback trusts ONLY the
 // HMAC-verified state (CSRF-/foreign-claiming lock, see oauth-state.ts).
 import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAuthMethods, InboundMailFoundationHandlers, inboundCredentialSecretKey, } from "./constants.js";
 import { inboundRefreshTokenSecretOptions, } from "./oauth-access-token.js";
 import { signOAuthState, verifyOAuthState } from "./oauth-state.js";
@@ -130,7 +131,7 @@ export function createInboundMailConnectRoutes(options) {
             if (!dispatched.isSuccess) {
                 return errorJson(c, 502, "account_create_failed", JSON.stringify(dispatched.error ?? {}));
             }
-            const accountId = dispatched.data?.accountId;
+            const accountId = propertyOf(dispatched.data, "accountId");
             if (typeof accountId !== "string") {
                 return errorJson(c, 502, "account_create_failed", "connect-account returned no accountId");
             }

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

@@ -1,53 +1,51 @@
 export declare const INBOUND_MAIL_FOUNDATION_FEATURE: "inbound-mail-foundation";
 export declare const INBOUND_MAIL_PROVIDER_EXTENSION: "inboundMailProvider";
 export declare const InboundMailFoundationHandlers: {
-    /** Programmatic entry-point für Provider-Plugins (watch-callback +
-     *  fetchSince-Sync): normalisierte Message rein, Idempotency +
-     *  PII-encrypt + event-append + Thread-Update atomic. */
+    /** Programmatic entry point for provider plugins (watch callback +
+     *  fetchSince sync): accepts a normalized message and atomically performs
+     *  idempotency handling, PII encryption, event append, and thread update. */
     readonly ingestMessage: "inbound-mail-foundation:write:ingest-message";
-    /** Tenant-Admin verbindet ein Postfach (IMAP-Credentials via secrets
-     *  oder OAuth-Redirect via oauth-routes). Legt den mail-account-Stream
-     *  an. */
+    /** Tenant admin connects a mailbox (IMAP credentials via secrets or an
+     *  OAuth redirect via oauth-routes). Creates the mail-account stream. */
     readonly connectAccount: "inbound-mail-foundation:write:connect-account";
-    /** Account-Status-Übergänge (watch error/backoff, oauth-refresh
-     *  failed, re-enabled). */
+    /** Account status transitions (watch error/backoff, OAuth refresh
+     *  failure, re-enabled). */
     readonly updateAccount: "inbound-mail-foundation:write:update-account";
-    /** Tenant-Admin trennt ein Postfach. Stream bleibt (Audit), Status
-     *  wird disconnected, Watch stoppt. */
+    /** Tenant admin disconnects a mailbox. The stream remains for auditing;
+     *  the status becomes disconnected and the watch stops. */
     readonly disconnectAccount: "inbound-mail-foundation:write:disconnect-account";
 };
 export declare const InboundMailFoundationQueries: {
-    /** Tenant-scoped Liste der verbundenen Postfächer. */
+    /** Tenant-scoped list of connected mailboxes. */
     readonly listAccounts: "inbound-mail-foundation:query:account:list";
-    /** Tenant-scoped Message-Liste (Inbox-Cockpit). PII wird beim Read
-     *  decrypted. */
+    /** Tenant-scoped message list (inbox cockpit). PII is decrypted on read.
+     */
     readonly listMessages: "inbound-mail-foundation:query:message:list";
 };
 export declare const InboundMailAccountStatuses: {
-    /** Verbunden, Watch/Sync läuft (oder ist startbereit). */
+    /** Connected; watch/sync is running or ready to start. */
     readonly active: "active";
-    /** Credentials/Token ungültig — Tenant-Admin muss re-connecten. */
+    /** Credentials or token are invalid; the tenant admin must reconnect. */
     readonly authError: "auth_error";
     /** Transienter Fehler, Supervisor backoff-retried. */
     readonly degraded: "degraded";
-    /** Vom Tenant-Admin getrennt. Keine Syncs mehr. */
+    /** Disconnected by the tenant admin; no further syncs run. */
     readonly disconnected: "disconnected";
 };
 export type InboundMailAccountStatus = (typeof InboundMailAccountStatuses)[keyof typeof InboundMailAccountStatuses];
 /**
- * Tenant-Secret-Slot eines Accounts: IMAP-App-Passwort ODER OAuth-
- * Refresh-Token — der Provider interpretiert den Inhalt gemäß
- * `authMethod` (Plan §4). Dynamisches Keying pro Account ist vom
- * secrets-Feature gedeckt: SecretsContext.get/set nehmen beliebige
- * String-Keys (resolveKey in secrets-context.ts) — Plan-Risiko 4
- * verifiziert, kein Framework-Gap.
+ * Tenant secret slot for an account: IMAP app password OR OAuth refresh
+ * token. The provider interprets the contents according to `authMethod`.
+ * Dynamic per-account keying is supported by the secrets feature:
+ * SecretsContext.get/set accept arbitrary string keys (resolveKey in
+ * secrets-context.ts), so no framework change is required.
  */
 export declare function inboundCredentialSecretKey(accountId: string): string;
 export declare const InboundMailAuthMethods: {
     /** Formular-Connect: Config (host/port/secure) + Tenant-Secret. */
     readonly password: "password";
-    /** SASL XOAUTH2 über IMAP — Fallback für M365/Gmail-Konten ohne
-     *  gemounteten Enterprise-Provider (gleicher Secret-Slot). */
+    /** SASL XOAUTH2 over IMAP — fallback for M365/Gmail accounts without a
+     *  mounted enterprise provider (same secret slot). */
     readonly xoauth2: "xoauth2";
     /** Nativer OAuth-Provider (m365-graph, gmail-rest). */
     readonly oauth: "oauth";

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

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

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

@@ -1,5 +1,5 @@
-/** Ein verbundenes Postfach. Eine Row pro Account, PK = aggregateId
- *  (= accountId, random uuid beim connect). */
+/** A connected mailbox. One row per account, with PK = aggregateId
+ *  (= accountId, random uuid on connect). */
 export declare const mailAccountEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     readonly provider: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
@@ -38,8 +38,8 @@ export declare const mailAccountEntity: import("@cosmicdrift/kumiko-types/fields
         required: true;
     };
 }, "tenant">;
-/** Eine eingegangene Mail (Envelope + Snippet, KEIN Body — bodyRef
- *  zeigt auf file-foundation). PK = aggregateId =
+/** An incoming mail (envelope + snippet, NO body — bodyRef
+ *  points to file-foundation). PK = aggregateId =
  *  inboundMessageAggregateId(accountId, providerMessageId). */
 export declare const inboundMessageEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     readonly accountId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
@@ -138,10 +138,10 @@ export declare const mailThreadEntity: import("@cosmicdrift/kumiko-types/fields"
 export declare const MAIL_ACCOUNT_PII_FIELDS: readonly string[];
 export declare const INBOUND_MESSAGE_PII_FIELDS: readonly string[];
 export declare const MAIL_THREAD_PII_FIELDS: readonly string[];
-/** Provider-Cursor pro Account ("wo war ich?"): IMAP UIDVALIDITY:UIDNEXT,
- *  Graph deltaLink, Gmail historyId. Eine Row pro (accountId, scope).
- *  Write-locked auf privileged — nur Foundation-Handler/Supervisor
- *  schreiben, kein Tenant-Request. */
+/** Provider cursor per account ("where was I?"): IMAP UIDVALIDITY:UIDNEXT,
+ *  Graph deltaLink, Gmail historyId. One row per (accountId, scope).
+ *  Write-locked to privileged — only Foundation handlers/supervisors
+ *  write it; tenant requests cannot. */
 export declare const syncCursorEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     readonly accountId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
@@ -168,10 +168,10 @@ export declare const syncCursorEntity: import("@cosmicdrift/kumiko-types/fields"
         required: true;
     };
 }, "tenant">;
-/** Dedup-Anchor für O(1)-Idempotency ohne Stream-Scan bei sehr langen
- *  Message-Historien: (accountId, providerMessageId) UNIQUE. Der
- *  ingest-handler prüft zuerst hier (cheap), der Stream-Scan bleibt
- *  Defense-in-depth. */
+/** Deduplication anchor for O(1) idempotency without scanning the stream
+ *  for very long message histories: (accountId, providerMessageId) UNIQUE.
+ *  The ingest handler checks here first (cheap); the stream scan remains
+ *  defense-in-depth. */
 export declare const seenMessageEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     readonly accountId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;