@cosmicdrift/kumiko-samples 0.393.0 → 0.394.0

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

@@ -0,0 +1,146 @@
+// Account health: maps what the supervisor observes (repeated poll failures, quarantined mails, file
+// storage, KMS or ingest outage) onto the account status "degraded" plus a lastError code, and back to "active" once
+// nothing is wrong any more. Auth errors and disconnects are never touched here. An update is
+// dispatched only when status or lastError really changes, so a healthy mailbox causes no events.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type InboundMailAccountStatus,
+  InboundMailAccountStatuses,
+  InboundMailFoundationHandlers,
+  type InboundMailLastError,
+  InboundMailLastErrors,
+} from "./constants.ts";
+import { hasOpenQuarantine } from "./quarantine.ts";
+import type {
+  DispatchWrite,
+  IngestBatchOutcome,
+  IngestBlockedReason,
+} from "./supervisor-ingest.ts";
+import type { AccountHealthRef, SyncableAccount } from "./syncable-accounts.ts";
+
+const FAILURES_BEFORE_DEGRADED = 3;
+const OUTAGE_LAST_ERRORS: ReadonlySet<string> = new Set([
+  InboundMailLastErrors.encryptionUnavailable,
+  InboundMailLastErrors.ingestUnavailable,
+  InboundMailLastErrors.fileStorageUnavailable,
+]);
+const SUPERVISOR_AUDIT_REASON = "watch_supervisor";
+
+export type PollFailureKind = "transient" | "rate_limited";
+
+type AppliedHealth = {
+  readonly status: InboundMailAccountStatus;
+  readonly lastError: string | null;
+};
+
+export type AccountHealth = {
+  readonly onPollSuccess: (
+    account: SyncableAccount,
+    outcome: Pick<IngestBatchOutcome, "storageUnavailable" | "storageHealthy">,
+  ) => Promise<void>;
+  readonly onPollFailure: (account: SyncableAccount, kind: PollFailureKind) => Promise<void>;
+  /** The cursor stayed before a failing mail: either the mail waits for its count or the ingest is down. */
+  readonly onIngestBlocked: (
+    account: SyncableAccount,
+    blocked: IngestBlockedReason,
+    outcome: Pick<IngestBatchOutcome, "storageHealthy">,
+  ) => Promise<void>;
+  /** The address did not decrypt because the key store is down, so the account could not be polled. */
+  readonly onKeyStoreUnavailable: (account: AccountHealthRef) => Promise<void>;
+};
+
+export function createAccountHealth(deps: {
+  readonly db: DbConnection;
+  readonly dispatchWrite: DispatchWrite;
+  readonly log: (line: string) => void;
+}): AccountHealth {
+  const consecutiveFailures = new Map<string, number>();
+  const storageUnavailable = new Set<string>();
+  // The account snapshot of a tick is stale after our own update; this keeps the "real change" check honest.
+  // Per process: a drift between workers costs at most one redundant update-account.
+  const applied = new Map<string, AppliedHealth>();
+
+  async function apply(account: AccountHealthRef, lastError: InboundMailLastError | null) {
+    const known = applied.get(account.id) ?? {
+      status: account.status,
+      lastError: account.lastError,
+    };
+    const status =
+      lastError === null ? InboundMailAccountStatuses.active : InboundMailAccountStatuses.degraded;
+    // skip: the stored health already matches, nothing to write.
+    if (known.status === status && known.lastError === lastError) return;
+    const result = await deps.dispatchWrite({
+      handlerQn: InboundMailFoundationHandlers.updateAccount,
+      tenantId: account.tenantId,
+      payload: { accountId: account.id, status, lastError, reason: SUPERVISOR_AUDIT_REASON },
+    });
+    if (!result.isSuccess) {
+      deps.log(
+        `inbound-mail: account ${account.id} health update was rejected (${rejectionCode(result.error)})`,
+      );
+      // skip: not recorded as applied, so the next tick retries the update.
+      return;
+    }
+    applied.set(account.id, { status, lastError });
+  }
+
+  async function lastErrorWithoutOutage(account: AccountHealthRef) {
+    if (await hasOpenQuarantine(deps.db, account.id)) {
+      return InboundMailLastErrors.messageQuarantined;
+    }
+    if (storageUnavailable.has(account.id)) return InboundMailLastErrors.fileStorageUnavailable;
+    return null;
+  }
+
+  return {
+    async onPollSuccess(account, outcome) {
+      consecutiveFailures.delete(account.id);
+      if (outcome.storageUnavailable) storageUnavailable.add(account.id);
+      else if (outcome.storageHealthy) storageUnavailable.delete(account.id);
+      return apply(account, await lastErrorWithoutOutage(account));
+    },
+    async onIngestBlocked(account, blocked, outcome) {
+      consecutiveFailures.delete(account.id);
+      if (blocked === "message_failing") {
+        deps.log(`inbound-mail: account ${account.id} waits for a failing message to be counted`);
+        if (outcome.storageHealthy) storageUnavailable.delete(account.id);
+        // A counted failure proves the ingest works again, so a shown outage is over; anything else stays.
+        const shown = (applied.get(account.id) ?? account).lastError;
+        // skip: no outage is shown, the status stays as it is
+        if (shown === null || !OUTAGE_LAST_ERRORS.has(shown)) return;
+        return apply(account, await lastErrorWithoutOutage(account));
+      }
+      // KMS and ingest outages need no memory like storage: the next unblocked poll proves they are over.
+      if (blocked === "encryption_unavailable") {
+        return apply(account, InboundMailLastErrors.encryptionUnavailable);
+      }
+      if (blocked === "ingest_unavailable") {
+        return apply(account, InboundMailLastErrors.ingestUnavailable);
+      }
+      storageUnavailable.add(account.id);
+      return apply(account, InboundMailLastErrors.fileStorageUnavailable);
+    },
+    async onKeyStoreUnavailable(account) {
+      consecutiveFailures.delete(account.id);
+      return apply(account, InboundMailLastErrors.encryptionUnavailable);
+    },
+    async onPollFailure(account, kind) {
+      const count = (consecutiveFailures.get(account.id) ?? 0) + 1;
+      consecutiveFailures.set(account.id, count);
+      // skip: below the failure threshold the mailbox stays as it is.
+      if (count < FAILURES_BEFORE_DEGRADED) return;
+      return apply(
+        account,
+        kind === "rate_limited"
+          ? InboundMailLastErrors.rateLimited
+          : InboundMailLastErrors.connectionFailed,
+      );
+    },
+  };
+}
+
+function rejectionCode(error: unknown): string {
+  if (typeof error === "object" && error !== null && "code" in error) return String(error.code);
+  return "unknown";
+}

package/packages/bundled-features/src/inbound-mail-foundation/account-poll-schedule.ts

@@ -0,0 +1,74 @@
+// How the supervisor tick spreads its accounts: a bounded number of syncs side by side, and a
+// deadline after which a sync that never answers is abandoned instead of holding the tick.
+
+import type { PollAccountOptions, PollAccountResult } from "./sync-account-now.ts";
+import type { SyncableAccount } from "./syncable-accounts.ts";
+import type { InboundMailProviderPlugin } from "./types.ts";
+
+export const DEFAULT_POLL_CONCURRENCY = 4;
+export const DEFAULT_ACCOUNT_POLL_DEADLINE_MS = 10 * 60 * 1000;
+
+export function pollScheduleOf(options: {
+  readonly pollConcurrency?: number;
+  readonly accountPollDeadlineMs?: number;
+}): { readonly pollConcurrency: number; readonly accountPollDeadlineMs: number } {
+  return {
+    pollConcurrency: options.pollConcurrency ?? DEFAULT_POLL_CONCURRENCY,
+    accountPollDeadlineMs: options.accountPollDeadlineMs ?? DEFAULT_ACCOUNT_POLL_DEADLINE_MS,
+  };
+}
+
+type DeadlineOutcome<T> =
+  | { readonly timedOut: false; readonly value: T }
+  | { readonly timedOut: true };
+
+/** Aborts the signal when the deadline passes. The abandoned work may still settle later; its
+ *  outcome is dropped and a late rejection is swallowed. */
+async function runWithDeadline<T>(
+  deadlineMs: number,
+  run: (signal: AbortSignal) => Promise<T>,
+): Promise<DeadlineOutcome<T>> {
+  const controller = new AbortController();
+  const work = run(controller.signal);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<DeadlineOutcome<T>>((resolve) => {
+    timer = setTimeout(() => resolve({ timedOut: true }), deadlineMs);
+  });
+  try {
+    const outcome = await Promise.race([
+      work.then((value): DeadlineOutcome<T> => ({ timedOut: false, value })),
+      deadline,
+    ]);
+    if (outcome.timedOut) {
+      controller.abort();
+      work.catch(() => {});
+    }
+    return outcome;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+type PollAccount = (
+  account: SyncableAccount,
+  plugin: InboundMailProviderPlugin,
+  options: PollAccountOptions,
+) => Promise<PollAccountResult>;
+
+/** A sync past the deadline counts as one failed poll and its in-flight slot is freed. */
+export function withPollDeadline(
+  pollAccount: PollAccount,
+  deadline: {
+    readonly ms: number;
+    readonly onDeadline: (account: SyncableAccount) => Promise<void>;
+  },
+): PollAccount {
+  return async (account, plugin, options) => {
+    const outcome = await runWithDeadline(deadline.ms, (signal) =>
+      pollAccount(account, plugin, { ...options, signal }),
+    );
+    if (!outcome.timedOut) return outcome.value;
+    await deadline.onDeadline(account);
+    return "done";
+  };
+}

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

@@ -0,0 +1,238 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import type { AccountHealth, PollFailureKind } from "./account-health.ts";
+import { refetchSnippetOnlyMessages } from "./content-refetch.ts";
+import { describeError } from "./describe-error.ts";
+import { seenMessageTable } from "./entities.ts";
+import {
+  isInboundAuthError,
+  isInboundCredentialNotStoredError,
+  isInboundCursorInvalidError,
+  isInboundRateLimitError,
+} from "./provider-errors.ts";
+import { quarantinedMessageIds } from "./quarantine.ts";
+import { retryQuarantinedMessages } from "./quarantine-retry.ts";
+import type {
+  DispatchWrite,
+  IngestBatchOutcome,
+  IngestBlockedReason,
+  MessageIngester,
+} from "./supervisor-ingest.ts";
+import type { PollAccountOptions, PollAccountResult } from "./sync-account-now.ts";
+import type { SyncCursorStore } from "./sync-cursor-store.ts";
+import type { SyncableAccount } from "./syncable-accounts.ts";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "./types.ts";
+
+const SEEN_LOOKUP_CHUNK_SIZE = 1000;
+
+export type AccountPollerDeps = {
+  readonly systemDb: DbConnection;
+  readonly cursors: SyncCursorStore;
+  readonly ingester: MessageIngester;
+  readonly health: AccountHealth;
+  readonly providerCtx: InboundMailContext;
+  readonly dispatchWrite: DispatchWrite;
+  readonly backfillWindowDays: number;
+  readonly maxMessagesPerPoll: number;
+  readonly resolveAccessToken: (
+    account: MailAccountRecord,
+    plugin: InboundMailProviderPlugin,
+  ) => Promise<string | undefined>;
+  /** Returns true when the account may keep running. */
+  readonly handleSyncError: (account: MailAccountRecord, err: unknown) => Promise<boolean>;
+  readonly log: (line: string) => void;
+};
+
+export function createAccountPoller(deps: AccountPollerDeps): {
+  readonly pollAccount: (
+    account: SyncableAccount,
+    plugin: InboundMailProviderPlugin,
+    options?: PollAccountOptions,
+  ) => Promise<PollAccountResult>;
+} {
+  const {
+    systemDb,
+    cursors,
+    ingester,
+    health,
+    providerCtx,
+    backfillWindowDays,
+    maxMessagesPerPoll,
+    resolveAccessToken,
+    handleSyncError,
+    log,
+  } = deps;
+
+  function unknownMessageIdsFilterFor(account: MailAccountRecord) {
+    return async (providerMessageIds: readonly string[]): Promise<ReadonlySet<string>> => {
+      if (providerMessageIds.length === 0) return new Set();
+      // One bind parameter per id: a full-mailbox listing would exceed Postgres' 65535 limit.
+      const seenIds = new Set<string>();
+      for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
+        const seen = await selectMany<{ providerMessageId: string }>(
+          systemDb,
+          seenMessageTable,
+          {
+            tenantId: account.tenantId,
+            accountId: account.id,
+            providerMessageId: {
+              in: providerMessageIds.slice(start, start + SEEN_LOOKUP_CHUNK_SIZE),
+            },
+          },
+          { fields: ["providerMessageId"] },
+        );
+        for (const row of seen) seenIds.add(row.providerMessageId);
+      }
+      // A quarantined message counts as seen: re-fetching it would only fail the same way again.
+      for (const id of await quarantinedMessageIds(systemDb, account.id, providerMessageIds)) {
+        seenIds.add(id);
+      }
+      return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
+    };
+  }
+
+  function pollFailureKindOf(err: unknown): PollFailureKind | null {
+    if (isInboundAuthError(err) || isInboundCursorInvalidError(err)) return null;
+    return isInboundRateLimitError(err) ? "rate_limited" : "transient";
+  }
+
+  async function refetchContentSafely(
+    account: SyncableAccount,
+    plugin: InboundMailProviderPlugin,
+    signal: AbortSignal | undefined,
+  ): Promise<void> {
+    // skip: the provider cannot reload content.
+    if (!plugin.fetchContent) return;
+    try {
+      const accessToken = await resolveAccessToken(account, plugin);
+      await refetchSnippetOnlyMessages({
+        db: systemDb,
+        dispatchWrite: deps.dispatchWrite,
+        providerCtx,
+        account,
+        plugin,
+        windowDays: backfillWindowDays,
+        accessToken,
+        signal,
+      });
+    } catch (err) {
+      // Best effort: the sync itself succeeded, the next tick retries the reload.
+      log(`inbound-mail: content reload for account ${account.id} failed: ${describeError(err)}`);
+    }
+  }
+
+  async function retryQuarantineSafely(
+    account: SyncableAccount,
+    plugin: InboundMailProviderPlugin,
+    signal: AbortSignal | undefined,
+  ): Promise<void> {
+    try {
+      const accessToken = await resolveAccessToken(account, plugin);
+      await retryQuarantinedMessages({
+        db: systemDb,
+        dispatchWrite: deps.dispatchWrite,
+        providerCtx,
+        account,
+        plugin,
+        accessToken,
+        signal,
+        log,
+      });
+    } catch (err) {
+      // Best effort: the sync itself succeeded, the flag stays and the next tick retries.
+      log(`inbound-mail: quarantine retry for account ${account.id} failed: ${describeError(err)}`);
+    }
+  }
+
+  // Fetches and ingests batch after batch until the provider has no more or the message budget of
+  // this tick is used up. An abandoned sync (deadline) throws out of the loop.
+  async function ingestBatches(
+    account: SyncableAccount,
+    plugin: InboundMailProviderPlugin,
+    options: PollAccountOptions,
+  ): Promise<{
+    storageUnavailable: boolean;
+    storageHealthy: boolean;
+    ingested: boolean;
+    blocked?: IngestBlockedReason;
+  }> {
+    const { signal } = options;
+    let cursor = await cursors.load(account.id);
+    let budget = maxMessagesPerPoll;
+    const totals = { storageUnavailable: false, storageHealthy: false, ingested: false };
+    for (;;) {
+      const accessToken = await resolveAccessToken(account, plugin);
+      const result = await plugin.fetch(providerCtx, account, cursor, {
+        backfillWindowDays,
+        maxMessages: budget,
+        filterUnknownMessageIds: unknownMessageIdsFilterFor(account),
+        ...(accessToken !== undefined && { accessToken }),
+        ...(signal && { signal }),
+      });
+      // The sync was abandoned while the provider was busy; its late result is dropped.
+      signal?.throwIfAborted();
+      const outcome: IngestBatchOutcome = await ingester.ingestBatch(
+        account,
+        result.messages,
+        result.rejected ?? [],
+        JSON.stringify(result.nextCursor),
+        {
+          ...(options.countBucket !== undefined && { countBucket: options.countBucket }),
+          ...(signal && { signal }),
+          proof: { ingested: totals.ingested, storageHealthy: totals.storageHealthy },
+        },
+      );
+      totals.storageUnavailable ||= outcome.storageUnavailable;
+      totals.storageHealthy ||= outcome.storageHealthy;
+      totals.ingested ||= outcome.ingested;
+      // Blocked: the cursor stays before the stuck mail, the next tick fetches it again.
+      if (outcome.blocked) return { ...totals, blocked: outcome.blocked };
+      // A newer poll may already own the account; an abandoned one must not move its cursor back.
+      signal?.throwIfAborted();
+      await cursors.save(account, result.nextCursor);
+      cursor = result.nextCursor;
+      budget -= result.messages.length;
+      if (!result.hasMore || budget <= 0) return totals;
+    }
+  }
+
+  async function pollAccount(
+    account: SyncableAccount,
+    plugin: InboundMailProviderPlugin,
+    options: PollAccountOptions = {},
+  ): Promise<PollAccountResult> {
+    let totals: Awaited<ReturnType<typeof ingestBatches>>;
+    try {
+      totals = await ingestBatches(account, plugin, options);
+    } catch (err) {
+      // skip: an error caused by abandoning the sync is already counted as the deadline failure.
+      if (options.signal?.aborted) return "done";
+      if (options.fromWake && isInboundCredentialNotStoredError(err)) {
+        // The secret is written after the account is created; the next tick picks it up.
+        log(`inbound-mail: account ${account.id} credential not stored yet, wake sync skipped`);
+        return "credential_pending";
+      }
+      const stillRunning = await handleSyncError(account, err);
+      const failureKind = pollFailureKindOf(err);
+      if (stillRunning && failureKind) await health.onPollFailure(account, failureKind);
+      return "done";
+    }
+    // skip: abandoned during the last batch; the deadline already counted this poll as failed.
+    if (options.signal?.aborted) return "done";
+    if (totals.blocked) {
+      await health.onIngestBlocked(account, totals.blocked, totals);
+      // A retry asked for by an admin does not depend on the cursor, so a stuck mail must not hold it.
+      // During an outage it would fail the same way; the flag stays and runs after the recovery.
+      if (totals.blocked === "message_failing") {
+        await retryQuarantineSafely(account, plugin, options.signal);
+      }
+      return "done";
+    }
+    await health.onPollSuccess(account, totals);
+    await retryQuarantineSafely(account, plugin, options.signal);
+    await refetchContentSafely(account, plugin, options.signal);
+    return "done";
+  }
+
+  return { pollAccount };
+}

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

@@ -16,6 +16,7 @@ export type MailAccountRow = {
   readonly displayName?: string | null;
   readonly status?: string | null;
   readonly watchState?: string | null;
+  readonly trustedAuthservId?: string | null;
 };
 
 function isAccountStatus(value: unknown): value is InboundMailAccountStatus {
@@ -44,5 +45,6 @@ export async function toMailAccountRecord(
     displayName: row.displayName ?? "",
     status: isAccountStatus(row.status) ? row.status : InboundMailAccountStatuses.active,
     watchState: row.watchState ?? "idle",
+    trustedAuthservId: row.trustedAuthservId ?? null,
   };
 }

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

@@ -0,0 +1,21 @@
+// Process-local wake channel between the account-event consumer (feature.ts) and the sync supervisor.
+// A freshly connected, reconnected or re-activated mailbox is synced right away instead of waiting
+// for the next poll tick. The consumer runs "per-instance", so every process wakes its own supervisor.
+//
+// Without a running event dispatcher in the process (or without a supervisor) nothing wakes anyone;
+// the regular poll tick then picks the account up, so this is purely a latency optimisation.
+
+export type MailAccountWakeListener = (tenantId: string, accountId: string) => void;
+
+const listeners = new Set<MailAccountWakeListener>();
+
+export function registerMailAccountWakeListener(listener: MailAccountWakeListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function wakeMailAccount(tenantId: string, accountId: string): void {
+  for (const listener of listeners) listener(tenantId, accountId);
+}

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,147 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Imported mails store full text, original and attachments",
+    "detail": "ingest-message now takes bodyText (at most 32,000 characters, cut with bodyTextTruncated set; 32,000 keeps a long mail readable while one event, one projection row and the PII-encrypted column stay small, the original keeps everything), rawMime, bodyHtml, attachments (at most 50) and skippedAttachments (at most 200). The original is stored as .eml (or .html for HTML-only mails) and each attachment as a file reference through file storage; apps without a file provider still import the mail, mark contentState unavailable and show the mailbox as interrupted. The event inbound-message-received is now v2 with an upcast that defaults the new fields; bodyText is personal tenant data. The new query inbound-mail-foundation:query:message:content returns text, original reference and attachments of one mail; message:list never carries the body. Retention removes the mail row, its body object and its attachment files. RawInboundMessage gains text, html, attachments and skippedAttachments."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A mail that cannot be parsed is quarantined instead of blocking the mailbox",
+    "detail": "A mail the provider reports as rejected, or whose ingest fails, is normalized where possible and otherwise stored in the unmanaged table store_mail_quarantine; every message is isolated in the supervisor, so the rest of the batch imports and the sync cursor moves on. An ingest failure only counts against a mail once a later mail of the batch succeeded, and the third counted failure quarantines it as ingest_failed; an outage of the database, KMS or file storage never quarantines good mail and never moves the cursor past an unhandled mail. The account list shows quarantinedCount and lastError, the new handler acknowledge-quarantine confirms the entries, acknowledged entries are purged by retention after 90 days, and the tenant-destroy hook removes them."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A mailbox that stops syncing shows as interrupted with a reason",
+    "detail": "The account events mail-account-connected and mail-account-updated are v2 with lastError (connection_failed, rate_limited, message_quarantined, file_storage_unavailable). Three failed polls in a row set the status degraded, shown as Unterbrochen in German; the next successful poll sets it back to active. New key in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A disconnected mailbox is reactivated under the same account",
+    "detail": "The new handler reactivate-account puts a disconnected mailbox back to active with its stream and sync cursor, so no mail is imported twice. connect-account refuses an address that is already connected (address_already_connected) or disconnected (address_disconnected) and reopens a disconnected OAuth mailbox in place; connect-routes answers 409 with the reason. reconnect-mailbox now also accepts a disconnected account."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Snippet-only mails get their content reloaded",
+    "detail": "Mails imported before this change carry only a snippet. The supervisor asks the provider for their content through fetchContent and stores it with attach-message-content (event inbound-message-content-fetched v1); a mail the server no longer has becomes unavailable and is not asked for again."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Connected, reconnected and reactivated mailboxes sync immediately",
+    "detail": "A per-instance event consumer wakes the supervisor on a new or active-again mailbox, which syncs once right away instead of waiting for the next poll. A sync of one account never runs twice at the same time. A woken sync that finds the credential not stored yet (the OAuth secret is written after the account) sets no status and leaves it to the next tick; stop() waits for running syncs."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "The first sync after an OAuth connect no longer waits for the next poll",
+    "detail": "The OAuth callback now dispatches the internal handler mark-credential-stored once the refresh token is saved, so the sync that the account commit triggers earlier than the token is repeated as soon as the credential exists. Originals above 50 MB are not stored; they are listed in skippedAttachments as message/rfc822 with reason too_large while text and attachments are kept. attach-message-content no longer accepts a caller-supplied bodyRef."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Outgoing mail carries attachments",
+    "detail": "sendMailFromAccount takes attachmentFileIds (at most 10 file references of the caller's tenant, at most 18 MB together, duplicates dropped). The bytes are read through file storage and sent over SMTP and stored in the sent folder unchanged; an unknown or foreign file gives mail_send_attachment_invalid, too many bytes mail_send_attachments_too_large, and nothing is sent. The plugin method send now receives the resolved attachments as a fourth argument and returns ProviderSentMail. New keys in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A hanging mailbox no longer blocks the others",
+    "detail": "The supervisor syncs up to 4 accounts at the same time (pollConcurrency), skips an account whose previous sync is still running, and abandons a sync after 10 minutes (accountPollDeadlineMs) as one failed poll; plugin.fetch and plugin.fetchContent receive an AbortSignal, and an abandoned sync stores nothing and moves no cursor. The IMAP client sets connection (20 s) and greeting (16 s) timeouts explicitly."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Sender authentication (SPF, DKIM, DMARC) of imported mails",
+    "detail": "inbound-message-received v2 carries senderAuthentication ({ authservId, spf, dkim, dkimDomains, dmarc, fromDomain } or null; verdicts pass, fail, none, unknown; dkimDomains at most 10), stored as JSON text in read_inbound_messages.sender_authentication and returned by message:content and loadInboundMessageContent; isSenderAuthenticated is true only for a dmarc pass. The mail account has a new optional trustedAuthservId (events mail-account-* v2, read_mail_accounts.trusted_authserv_id, input of connect-account, update-account, reactivate-account and the IMAP connect and reconnect forms). Only the first Authentication-Results header from the top whose authserv-id equals it counts; without an id, without such a header or when its header.from domain differs from the From domain the result is null, and a dmarc result without header.from is unknown. Headers below the trusted one are ignored, so a sender cannot inject a pass. Mails imported before, and content refetched later, have null. New keys in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "Mail account handlers are stricter and the trusted authserv-id has its own handler",
+    "detail": "trustedAuthservId is no longer accepted by connect-account, update-account and reactivate-account (strict schemas reject unknown keys); set it with the new set-trusted-authserv-id (SystemAdmin, TenantAdmin, not model-callable). update-account accepts status, lastError, watchState and reason only from the system identity; connect-account is no longer exposed to agents. reactivate-account checks the account owner (unless the OAuth override is set), fails with credential_required when a password account has no stored credential, and reopens an account in place only with that override; disconnect-account deletes the stored secret. Outgoing attachments must pass the file read check of the sender, and SendMailFromAccountContext needs dispatch. New screen \"Absenderprüfung\" edits the id. The watch supervisor and the IMAP forms use mapWithConcurrency and implicit TLS on port 465 for SMTPS.",
+    "migration": "Drop trustedAuthservId from connect-account, update-account and reactivate-account payloads and dispatch set-trusted-authserv-id after connecting. Wrapping or agent setups that called connect-account as a model tool need their own exposed handler. Callers of sendMailFromAccount pass a context that includes dispatch. Personal mailboxes are reactivated by their owner only; after disconnect-account a new credential must be stored before reactivate-account."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "The mailbox row action Reconnect is folded into Reactivate",
+    "detail": "The row action reconnect of mailAccountListScreen and its i18n key inboundMail.accounts.reconnect are removed. A password IMAP mailbox with a sign-in error now shows Reactivate, which opens the same screen mail-account-reconnect-imap; OAuth mailboxes get the client action reactivate-oauth instead.",
+    "migration": "Apps that override inboundMail.accounts.reconnect move the text to inboundMail.accounts.reactivate. Apps that reference the row action id reconnect (tests, screen extensions) use reactivate for password IMAP and reactivate-oauth for OAuth mailboxes, and mount inboundMailFoundationClient() from @cosmicdrift/kumiko-bundled-features/inbound-mail-foundation/web so the OAuth action runs."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "The OAuth callback only connects a personal mailbox for the account that signed in",
+    "detail": "InboundOAuthFlow.exchangeCode returns OAuthCodeExchange, an OAuthTokenSet with the required accountAddress of the signed-in provider account. The callback compares it with the mailbox address, ignoring case, and answers 403 mailbox_address_mismatch with a plain-text message and no account when they differ, so nobody can claim another person's address. This applies to personal mailboxes; a shared mailbox (only admins start that flow) is often opened with the admin's own login through delegated access, as with M365 shared mailboxes, so its address is not compared, and a token without access to it shows auth_error on the first sync.",
+    "migration": "Inbound providers with an oauth block return accountAddress from exchangeCode, taken from the token's email claim or the provider's profile endpoint (for example the userinfo email). There is no default: a provider that cannot name the signed-in address cannot connect mailboxes."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Failing ingests are counted and a poison mail is quarantined after three intervals",
+    "detail": "The supervisor counts an ingest failure once per poll interval in the unmanaged table store_mail_ingest_failures, but only when another mail of the account went through in the same poll (for a storage failure another storage write); at three it quarantines the mail with reason ingest_failed and moves the cursor on, before that the batch stops and nothing behind it is skipped. A failure nothing proves to be the mail's (KMS, file storage, the app's storeBody hook, the ingest handler or projection failing for every mail) counts nothing (when every failure of a poll was counted before as a storage or ingest failure, they all keep counting), keeps the cursor and sets the account to degraded with lastError encryption_unavailable, file_storage_unavailable or ingest_unavailable; the next interval retries. An account the supervisor cannot poll because the key store fails while decrypting its address is set to encryption_unavailable too, instead of being skipped silently. A mail that waits for its count clears a shown encryption_unavailable or ingest_unavailable, and file_storage_unavailable once a storage write went through. A requested quarantine retry also runs while a failing mail holds the cursor; during an outage, and when a reload fails because of the provider, the KMS or file storage, the request stays and runs after the recovery. Every quarantined mail also gets a header-only entry (contentState unavailable, contentUnavailableReason quarantined); after a storage failure it goes without the original."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Quarantined mails can be retried",
+    "detail": "The write handler retry-quarantined-message (mailbox owner or admin) flags a quarantine entry; the next successful sync loads the mail again, attaches the content to the header entry or ingests it in full, and removes the entry."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "inbound-message-received is v3 and inbound-message-content-fetched is v2",
+    "detail": "Both events carry contentUnavailableReason (null for older events through upcasters). The read table read_inbound_messages gets content_unavailable_reason, store_mail_quarantine gets retry_requested_at, and store_mail_ingest_failures is new; generate and apply a migration with `kumiko-schema generate`. ingest-message and attach-message-content upload files before their transaction when called at top level, and attach-message-content skips the upload when the mail already shows its content; inside a wrapper handler's transaction they upload in it, as before. RejectedInboundMessage may carry rawMime and headers, and an inbound provider's fetch may take filterUnknownMessageIds to skip mails that are already known.",
+    "migration": "Run `kumiko-schema generate` and apply the migration; read_inbound_messages is rebuilt from events because attachment_file_ids becomes jsonb. Consumers that read the event payloads type them against the new versions (upcasters fill contentUnavailableReason with null). To get the pre-transaction upload, trigger on inbound-message-received or inbound-message-content-fetched instead of wrapping ingest-message in an own write handler."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A watch that starts during a sync catches up on mail that arrived before it opened",
+    "detail": "After a successful watch start the supervisor runs one catch-up poll (after a running sync finished), and a tick also starts the watch while the account is still syncing. Mail delivered between the last poll and the watch opening is imported without waiting for the poll interval. The watch start is idempotent per account."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Exports for consumers of content events and attachment names",
+    "detail": "INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN, its payload type and schema, and readableFileName({ id, fileName }) are exported from the feature index, so an app can react to fetched content and show decrypted attachment names."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Reactivate a disconnected mailbox from the mailbox list",
+    "detail": "list-accounts returns reactivateVia per mailbox (password_form, oauth_flow or null) for a disconnected mailbox or one with a sign-in error, set only for the owner of a personal mailbox and for admins of a shared one. The mailbox list shows Reactivate for password_form; the new dormant screen my-mail-accounts (MY_MAIL_ACCOUNT_LIST_SCREEN_ID, role User) and the admin list show Reactivate for oauth_flow as the client action inbound-mail-foundation:reconnect-oauth, which goes through GET /api/inbound-mail/connect and the callback again and reopens the mailbox under its old id; apps mount it with inboundMailFoundationClient() from inbound-mail-foundation/web. The callback also reopens an OAuth mailbox with a sign-in error. It switches a reopened mailbox back on only after the new refresh token is stored; when storing fails it answers 502 credential_store_failed with a plain-text message and the mailbox keeps its previous state. reactivate-account admits the system user for this step. reactivate-account admits role User, gated by the owner rule for personal mailboxes, and requires a credential for disconnected, auth_error and degraded alike. set-trusted-authserv-id is a tenant security policy: only SystemAdmin and TenantAdmin change it, on every mailbox of the tenant including personal ones. The connect route answers 403 shared_mailbox_requires_admin when a user without admin role starts the shared flow. The row action Reconnect is folded into Reactivate (see the breaking entry). The connect-mailbox form reopens a disconnected shared IMAP mailbox of the same address under its old account id with the new password. For anything else connect-account answers with a text pointing to Reactivate, and credential_required from reactivate-account is a plain-text message. A new i18n key set (de, en, fr, es, it) is part of the locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Quarantined mails are listed with sender and subject and handled one by one",
+    "detail": "The query quarantine:list and the dormant screen mail-quarantine show the open entries of the mailboxes the caller may manage, with sender and subject from the header-only import (empty without one), reason and date; row actions fetch a mail again or confirm it. acknowledge-quarantine takes an optional providerMessageId (without it all entries of the mailbox as before) and now also admits the owner of a personal mailbox (role User). The mailbox list gets a row action Quarantine for mailboxes with open entries."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Mail attachments are bound to the mail and follow its visibility",
+    "detail": "The attachment fileRefs of an imported mail are bound to the inbound-message record (field attachmentFileIds). GET /files/:id answers with the mail's visibility: owner and admins for a personal mailbox, whoever may see the mail for a shared one. The new query inbound-message:detail ({ id }) backs that check and is not exposed to agents. Outbound attachments use the same rule (canCallerReadFileRef). Retention now also removes the attachment files of a purged mail. read_inbound_messages.attachment_file_ids is jsonb; the migration 0056 carries a table rebuild marker, so the read table is rebuilt from the events. InboundMessageContent.attachmentFileIds stays string[]."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "Personal mail is private to its owner, roles are configurable",
+    "detail": "Admins no longer read messages, bodies, attachments or quarantine of a personal mailbox; list-accounts still shows them the account without counts. The screens and the IMAP handlers are factories (createMailAccountListScreen, createImapConnectScreen and others) taking the resolved roles instead of constants. The content-fetched event is version 3 with accountId and ownerUserId. createDefaultGuard has a fourth parameter recordOnlyEntityTypes; for those entity types the files privilegedRoles no longer read or delete attached files (shared mailboxes included), only the uploader and readers of the record do. The OAuth connect route answers 403 mail_role_required to callers without a mail role.",
+    "migration": "Apps that import mailAccountListScreen, mailAccountEditScreen, mailAccountSenderCheckScreen, myMailAccountListScreen, mailQuarantineScreen, imapConnectScreen or imapReconnectScreen call the matching create*Screen factory with resolveInboundMailRoles(). Apps with their own roles pass { userRoles, adminRoles } to createInboundMailFoundationFeature and the same options to createInboundProviderImapFeature. Callers of createDefaultGuard pass a Set of record-only entity types as fourth argument. Code that read personal mail as an admin must run as the owner; the nullable accountId and ownerUserId on content-fetched events need no action."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "Supervisor and OAuth callback writes work when the app roles leave out SystemAdmin",
+    "detail": "`update-account`, `connect-account` and `reactivate-account` are dispatched as the system user by the watch supervisor, the account health and the OAuth callback, but their access list held only the configured `adminRoles`/`memberRoles`. An app whose roles exclude SystemAdmin saw every health, watch-state and callback write refused (\"health update was rejected\"), so mailboxes never showed `degraded`. These three handlers now also accept SystemAdmin (the list is `SYSTEM_DISPATCHED_MAIL_HANDLERS`). `isMailAdmin`, screens and what real users may do stay on the configured roles."
+  },
   {
     "version": "0.393.0",
     "type": "improvement",