@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

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

@@ -1,7 +1,9 @@
 import type { ConfigAccessor, Registry } from "@cosmicdrift/kumiko-framework/engine";
 import type { MetricsHandle } from "@cosmicdrift/kumiko-framework/observability";
 import { INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus } from "./constants.ts";
-import type { OutboundMailMessage, OutboundMailSent } from "./outbound-mail.ts";
+import type { InboundOAuthFlow } from "./inbound-oauth-flow.ts";
+import type { OutboundAttachment, OutboundMailMessage, ProviderSentMail } from "./outbound-mail.ts";
+import type { SenderAuthentication } from "./sender-auth.ts";
 /**
  * Slim context for provider plugins.
  *
@@ -45,8 +47,22 @@ export type MailAccountRecord = {
     /** Postfach-Adresse, Plaintext (decrypted). */
     readonly address: string;
     readonly displayName: string;
+    /** The real status; the supervisor syncs active and degraded mailboxes. */
     readonly status: InboundMailAccountStatus;
     readonly watchState: string;
+    /** authserv-id of the mailbox's own server for sender verification; absent or null = none set. */
+    readonly trustedAuthservId?: string | null;
+};
+export type RawInboundAttachment = {
+    readonly fileName: string;
+    readonly mimeType: string;
+    readonly data: Uint8Array;
+};
+/** An attachment that was not stored. Carries no file name: the reason is shown to operators, not the content. */
+export type SkippedInboundAttachment = {
+    readonly mimeType: string;
+    readonly size: number;
+    readonly reason: "too_large" | "mail_too_large" | "rejected" | "no_file_storage" | "nesting_too_deep";
 };
 /**
  * Normalized incoming mail — provider output and ingest input.
@@ -74,9 +90,17 @@ export type RawInboundMessage = {
     readonly snippet: string;
     /** ISO instant — INTERNALDATE or receivedDateTime, not ingest time. */
     readonly receivedAtIso: string;
-    /** Raw MIME; null in snippet-only mode. The Foundation persists it through
+    /** Raw MIME; null when the provider has no original to keep. The Foundation persists it through
      *  file-foundation and writes bodyRef, so the event store remains blob-free. */
     readonly rawMime: Uint8Array | null;
+    /** Full plaintext (derived from the HTML for HTML-only mails). Optional so providers
+     *  predating the field keep compiling; the supervisor treats absent as empty. */
+    readonly text?: string;
+    readonly html?: string | null;
+    readonly attachments?: readonly RawInboundAttachment[];
+    readonly skippedAttachments?: readonly SkippedInboundAttachment[];
+    /** What the mailbox's own server verified about the sender. Absent counts as unknown, never as pass. */
+    readonly senderAuthentication?: SenderAuthentication | null;
     /** Generic scope hint ("inbox", folder name), with no application semantics. */
     readonly scope: string;
 };
@@ -84,50 +108,36 @@ export type RawInboundMessage = {
  *  · Gmail {historyId}. Foundation persisted ihn JSON-stringified in
  *  store_mail_sync_cursors, interpretiert ihn nie. */
 export type SyncCursorPayload = Readonly<Record<string, unknown>>;
+/** A message the provider could not turn into a RawInboundMessage; the cursor moves past it. */
+export type RejectedInboundMessage = {
+    readonly providerMessageId: string;
+    readonly reason: "unparseable";
+    /** The original, when the provider has it; kept so the quarantined mail stays visible and retryable. */
+    readonly rawMime?: Uint8Array;
+    /** Envelope headers the provider could read without parsing the body. */
+    readonly headers?: {
+        readonly from: string;
+        readonly to: readonly string[];
+        readonly cc: readonly string[];
+        readonly subject: string;
+        readonly messageIdHeader: string | null;
+        readonly receivedAtIso: string;
+    };
+};
+export type InboundContentFetchResult = {
+    readonly messages: readonly RawInboundMessage[];
+    /** Not on the server (anymore) or from a previous UIDVALIDITY. */
+    readonly missing: readonly string[];
+    readonly rejected: readonly RejectedInboundMessage[];
+};
 export type InboundFetchResult = {
     readonly messages: readonly RawInboundMessage[];
+    readonly rejected?: readonly RejectedInboundMessage[];
     readonly nextCursor: SyncCursorPayload;
     /** true ⇒ the Foundation calls fetch again in the same poll tick
      *  (pagination) until false or the maxMessages budget is exhausted. */
     readonly hasMore: boolean;
 };
-export type OAuthTokenSet = {
-    readonly accessToken: string;
-    /** ISO-Instant. TTL typisch ~1h ⇒ Foundation refresht before-poll. */
-    readonly expiresAt: string;
-    readonly refreshToken?: string;
-    readonly scopesGranted: readonly string[];
-};
-/**
- * OAuth portion of the contract — OAuth providers only; imap in password
- * mode omits `oauth`. The Foundation provides the routes
- * (`/inbound-mail/connect`, `/inbound-mail/oauth/callback`) generically;
- * providers MUST NOT register their own routes.
- */
-export type InboundOAuthFlow = {
-    /** Scopes: request receive AND send in a SINGLE consent; re-consent is costly. */
-    readonly scopes: {
-        readonly receive: readonly string[];
-        readonly send?: readonly string[];
-    };
-    readonly buildAuthorizeUrl: (ctx: InboundMailContext, p: {
-        readonly state: string;
-        readonly redirectUri: string;
-    }) => Promise<string>;
-    readonly exchangeCode: (ctx: InboundMailContext, p: {
-        readonly code: string;
-        readonly redirectUri: string;
-    }) => Promise<OAuthTokenSet>;
-    readonly refreshAccessToken: (ctx: InboundMailContext, account: MailAccountRecord, refreshToken: string, 
-    /** The foundation aborts `signal` after a hard timeout while holding a
-     *  per-account lock (a pool connection is pinned meanwhile). Providers
-     *  MUST pass it to their token-endpoint fetch; the foundation awaits the
-     *  provider's result and never drops a late one, because that could lose
-     *  a rotated refresh token. */
-    opts?: {
-        readonly signal?: AbortSignal;
-    }) => Promise<OAuthTokenSet>;
-};
 /**
  * Inbound-mail provider plugin contract. Each provider feature
  * (inbound-provider-imap, -m365-graph, -gmail-rest) registers an
@@ -155,19 +165,29 @@ export type InboundMailProviderPlugin = {
          *  the listing/delta page and download MIME only for the returned ids.
          *  Ingest dedup stays the correctness anchor; this only saves downloads. */
         readonly filterUnknownMessageIds?: (providerMessageIds: readonly string[]) => Promise<ReadonlySet<string>>;
+        /** Aborted when the supervisor gives up on this account's sync (per-account deadline). A
+         *  provider that can cancel closes its connection then; one that cannot is abandoned and
+         *  its late result is dropped. */
+        readonly signal?: AbortSignal;
     }) => Promise<InboundFetchResult>;
+    /** Re-downloads already imported messages that were stored as snippet only. */
+    readonly fetchContent?: (ctx: InboundMailContext, account: MailAccountRecord, providerMessageIds: readonly string[], opts?: {
+        readonly accessToken?: string;
+        readonly signal?: AbortSignal;
+    }) => Promise<InboundContentFetchResult>;
     /** Nur OAuth-Provider. */
     readonly oauth?: InboundOAuthFlow;
     /** Sends from the mailbox address through the customer's own server. Throws
      *  MailSendNotConfiguredError, InboundAuthError, InboundTransientError or MailSendRejectedError. */
-    readonly send?: (ctx: InboundMailContext, account: MailAccountRecord, message: OutboundMailMessage) => Promise<OutboundMailSent>;
+    readonly send?: (ctx: InboundMailContext, account: MailAccountRecord, message: OutboundMailMessage, attachments: readonly OutboundAttachment[]) => Promise<ProviderSentMail>;
     /** Optional live push (IMAP IDLE, later Graph/Gmail webhooks).
      *  Returns stop(). Polling remains reconciliation: watch optimizes
      *  latency but is never the correctness anchor. `onError` reports a dead
      *  live connection (drop, auth revocation) to the supervisor, which
      *  restarts it with backoff; the provider does NOT reconnect itself. */
     readonly watch?: (ctx: InboundMailContext, account: MailAccountRecord, handlers: {
-        readonly onMessages: (msgs: readonly RawInboundMessage[]) => Promise<void>;
+        /** `rejected`: mails the provider could not parse, quarantined right away instead of at the next poll. */
+        readonly onMessages: (msgs: readonly RawInboundMessage[], rejected?: readonly RejectedInboundMessage[]) => Promise<void>;
         readonly onError: (err: unknown) => void;
     }, 
     /** Same `accessToken` semantics as `fetch` opts; re-minted on every
@@ -182,24 +202,3 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
         [INBOUND_MAIL_PROVIDER_EXTENSION]: InboundMailProviderPlugin;
     }
 }
-export declare class InboundAuthError extends Error {
-    readonly kind: "inbound-auth-error";
-    constructor(message: string);
-}
-export declare class InboundRateLimitError extends Error {
-    readonly kind: "inbound-rate-limit-error";
-    readonly retryAfterMs: number;
-    constructor(message: string, retryAfterMs: number);
-}
-export declare class InboundCursorInvalidError extends Error {
-    readonly kind: "inbound-cursor-invalid-error";
-    constructor(message: string);
-}
-export declare class InboundTransientError extends Error {
-    readonly kind: "inbound-transient-error";
-    constructor(message: string);
-}
-export declare function isInboundAuthError(e: unknown): e is InboundAuthError;
-export declare function isInboundRateLimitError(e: unknown): e is InboundRateLimitError;
-export declare function isInboundCursorInvalidError(e: unknown): e is InboundCursorInvalidError;
-export declare function isInboundTransientError(e: unknown): e is InboundTransientError;

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

@@ -21,57 +21,3 @@ export function isInboundMailProviderPlugin(o) {
         "fetch" in o &&
         typeof o.fetch === "function");
 }
-// =============================================================================
-// Typed errors handled uniformly by the Foundation during polling:
-//   InboundAuthError          → status=auth_error, no retry
-//   InboundRateLimitError     → abort poll, wait for the next cron tick
-//   InboundCursorInvalidError → reset cursor + full resync in the backfill
-//                               window; deduplication handles duplicates
-//   InboundTransientError     → job retry (retries: 3, exponential)
-// =============================================================================
-//
-// Use a `kind` discriminant instead of instanceof: plugins and the Foundation
-// may run in separate bundles (dual-package-hazard), and instanceof is
-// unreliable across realm or package-copy boundaries.
-export class InboundAuthError extends Error {
-    kind = "inbound-auth-error";
-    constructor(message) {
-        super(message);
-        this.name = "InboundAuthError";
-    }
-}
-export class InboundRateLimitError extends Error {
-    kind = "inbound-rate-limit-error";
-    retryAfterMs;
-    constructor(message, retryAfterMs) {
-        super(message);
-        this.name = "InboundRateLimitError";
-        this.retryAfterMs = retryAfterMs;
-    }
-}
-export class InboundCursorInvalidError extends Error {
-    kind = "inbound-cursor-invalid-error";
-    constructor(message) {
-        super(message);
-        this.name = "InboundCursorInvalidError";
-    }
-}
-export class InboundTransientError extends Error {
-    kind = "inbound-transient-error";
-    constructor(message) {
-        super(message);
-        this.name = "InboundTransientError";
-    }
-}
-export function isInboundAuthError(e) {
-    return e instanceof Error && "kind" in e && e.kind === "inbound-auth-error";
-}
-export function isInboundRateLimitError(e) {
-    return e instanceof Error && "kind" in e && e.kind === "inbound-rate-limit-error";
-}
-export function isInboundCursorInvalidError(e) {
-    return e instanceof Error && "kind" in e && e.kind === "inbound-cursor-invalid-error";
-}
-export function isInboundTransientError(e) {
-    return e instanceof Error && "kind" in e && e.kind === "inbound-transient-error";
-}

package/dist/inbound-mail-foundation/wake-consumer.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+export declare function registerMailAccountWakeConsumer(r: FeatureRegistrar<"inbound-mail-foundation">): void;

package/dist/inbound-mail-foundation/wake-consumer.js

@@ -0,0 +1,30 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { wakeMailAccount } from "./account-wake.js";
+import { InboundMailAccountStatuses } from "./constants.js";
+import { MAIL_ACCOUNT_CONNECTED_EVENT_QN, MAIL_ACCOUNT_UPDATED_EVENT_QN } from "./events.js";
+const SUPERVISOR_AUDIT_REASON = "watch_supervisor";
+// Per-instance consumer: every process sees every account event, so the supervisor running in that
+// process syncs a freshly connected, reconnected or re-activated mailbox immediately. Supervisor-made
+// updates (watch state, health) are skipped, otherwise its own bookkeeping would trigger syncs.
+// It only reaches an in-process registry and never writes to the database.
+export function registerMailAccountWakeConsumer(r) {
+    const wakeIfActive = (event) => {
+        // skip: only an account that is active again needs an immediate sync.
+        if (propertyOf(event.payload, "status") !== InboundMailAccountStatuses.active)
+            return;
+        // skip: the supervisor's own bookkeeping must not trigger another sync.
+        if (event.metadata.headers?.["reason"] === SUPERVISOR_AUDIT_REASON)
+            return;
+        wakeMailAccount(event.tenantId, event.aggregateId);
+    };
+    r.multiStreamProjection({
+        name: "mail-account-wake",
+        delivery: "per-instance",
+        startFrom: "now",
+        runIn: "both",
+        apply: {
+            [MAIL_ACCOUNT_CONNECTED_EVENT_QN]: async (event) => wakeIfActive(event),
+            [MAIL_ACCOUNT_UPDATED_EVENT_QN]: async (event) => wakeIfActive(event),
+        },
+    });
+}

package/dist/inbound-mail-foundation/watch-catch-up.d.ts

@@ -0,0 +1,19 @@
+import { type InFlightSyncs, type PollAccountOptions, type PollAccountResult } from "./sync-account-now.ts";
+import type { SyncableAccount } from "./syncable-accounts.ts";
+import type { InboundMailProviderPlugin } from "./types.ts";
+export type WatchCatchUp = {
+    /** Fire-and-forget; failures are logged and never stop the watch. */
+    readonly schedule: (account: SyncableAccount, plugin: InboundMailProviderPlugin) => void;
+    readonly settled: () => Promise<unknown>;
+};
+/**
+ * A watch only sees mail that arrives after its mailbox is open, so mail delivered between a
+ * poll's fetch and the watch start would wait for the next tick. One poll that starts after the
+ * watch is open closes that gap for every provider.
+ */
+export declare function createWatchCatchUp(deps: {
+    readonly inFlight: InFlightSyncs;
+    readonly pollAccount: (account: SyncableAccount, plugin: InboundMailProviderPlugin, options: PollAccountOptions) => Promise<PollAccountResult>;
+    readonly isRunning: () => boolean;
+    readonly log: (line: string) => void;
+}): WatchCatchUp;

package/dist/inbound-mail-foundation/watch-catch-up.js

@@ -0,0 +1,33 @@
+import { describeError } from "./describe-error.js";
+import { runExclusivePerAccount, } from "./sync-account-now.js";
+/**
+ * A watch only sees mail that arrives after its mailbox is open, so mail delivered between a
+ * poll's fetch and the watch start would wait for the next tick. One poll that starts after the
+ * watch is open closes that gap for every provider.
+ */
+export function createWatchCatchUp(deps) {
+    const pending = new Set();
+    async function catchUp(account, plugin) {
+        // A sync running now may have fetched before the mailbox was open, so joining it would not close the gap.
+        for (let running = deps.inFlight.get(account.id); running; running = deps.inFlight.get(account.id)) {
+            await running.catch(() => { });
+        }
+        // skip: the supervisor stopped while the sync ran.
+        if (!deps.isRunning())
+            return;
+        await runExclusivePerAccount(deps.inFlight, account.id, async () => {
+            await deps.pollAccount(account, plugin, {});
+        });
+    }
+    return {
+        schedule(account, plugin) {
+            const task = catchUp(account, plugin)
+                .catch((err) => deps.log(`inbound-mail: watch catch-up for account ${account.id} failed: ${describeError(err)}`))
+                .finally(() => {
+                pending.delete(task);
+            });
+            pending.add(task);
+        },
+        settled: () => Promise.allSettled([...pending]),
+    };
+}

package/dist/inbound-mail-foundation/watch-lease.d.ts

@@ -0,0 +1,15 @@
+import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { MailAccountRecord } from "./types.ts";
+import type { WatcherState, WatchLeaseResult } from "./watch-supervisor-types.ts";
+export type WatchLease = {
+    readonly acquire: (account: MailAccountRecord, state: WatcherState) => Promise<WatchLeaseResult>;
+};
+export declare function createWatchLease(deps: {
+    readonly lock: DistributedLock | undefined;
+    readonly ttlSeconds: number;
+    readonly renewIntervalMs: number;
+    readonly watchers: ReadonlyMap<string, WatcherState>;
+    readonly isRunning: () => boolean;
+    readonly stopWatcher: (accountId: string) => Promise<void>;
+    readonly log: (line: string) => void;
+}): WatchLease;

package/dist/inbound-mail-foundation/watch-lease.js

@@ -0,0 +1,81 @@
+import { describeError } from "./describe-error.js";
+// The cross-worker claim on one account's watch: acquired before plugin.watch(), renewed by a
+// heartbeat for as long as the watcher state exists, and given up locally once it is lost.
+export function createWatchLease(deps) {
+    const { lock, ttlSeconds, renewIntervalMs, watchers, isRunning, stopWatcher, log } = deps;
+    // Heartbeat for a held watch lease. Independent of the connection's own
+    // lifecycle — it keeps renewing across reconnect backoff, not just while
+    // `plugin.watch()` is actually connected, so a flaky IMAP link doesn't
+    // make this worker lose the account to a peer mid-backoff.
+    function scheduleRenew(account, state, generation) {
+        state.renewTimer = setTimeout(() => {
+            void renewLeaseOnce(account, state, generation);
+        }, renewIntervalMs);
+    }
+    async function tearDownAfterRenewFailures(account, state, reason) {
+        log(`inbound-mail: watch lease ${reason} for account ${account.id} — tearing down local watcher`);
+        state.lockToken = null;
+        await stopWatcher(account.id);
+    }
+    async function renewLeaseOnce(account, state, generation) {
+        state.renewTimer = null;
+        // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
+        if (!isRunning() || state.generation !== generation || !state.lockToken || !lock)
+            return;
+        let renewed;
+        try {
+            renewed = await lock.renew(account.id, state.lockToken, ttlSeconds);
+        }
+        catch (err) {
+            log(`inbound-mail: watch lease renew for account ${account.id} failed: ${describeError(err)}`);
+            state.renewFailures += 1;
+            // After failures spanning a full lease TTL, tear down — otherwise a
+            // peer can acquire the expired key while we still hold an IDLE conn.
+            if (state.renewFailures * renewIntervalMs >= ttlSeconds * 1000) {
+                await tearDownAfterRenewFailures(account, state, "renew failed across TTL");
+                // skip: connection torn down, no reschedule
+                return;
+            }
+            rescheduleIfStillHeld(account, state, generation);
+            // skip: renew failed but TTL not yet exhausted, retry already scheduled
+            return;
+        }
+        state.renewFailures = 0;
+        if (!renewed) {
+            await tearDownAfterRenewFailures(account, state, "lost");
+            // skip: lease lost and torn down, nothing to reschedule
+            return;
+        }
+        rescheduleIfStillHeld(account, state, generation);
+    }
+    function rescheduleIfStillHeld(account, state, generation) {
+        if (isRunning() && state.generation === generation && state.lockToken) {
+            scheduleRenew(account, state, generation);
+        }
+    }
+    // kumiko-lint-ignore complexity-budget yield-point stale-map check after acquire is intentional
+    async function acquire(account, state) {
+        if (!lock || state.lockToken)
+            return "acquired";
+        // A throwing lock (Redis outage) reads as "not claimed": the next tick retries instead of leaving the start flag set.
+        const token = await lock.acquire(account.id, { ttlSeconds: ttlSeconds }).catch((err) => {
+            log(`inbound-mail: watch lease acquire for account ${account.id} failed: ${describeError(err)}`);
+            return null;
+        });
+        if (!token)
+            return "no-token";
+        // The acquire() await is a yield point: a concurrent stopWatcher()
+        // (e.g. from a lost-lease renewal on a different generation) may have
+        // already retired this exact state and removed it from the map. If so,
+        // committing the fresh token onto it would leak the lease — nothing
+        // would ever release it, blocking failover for the full TTL.
+        if (watchers.get(account.id) !== state) {
+            await lock.release(account.id, token);
+            return "stale";
+        }
+        state.lockToken = token;
+        scheduleRenew(account, state, state.generation);
+        return "acquired";
+    }
+    return { acquire };
+}

package/dist/inbound-mail-foundation/watch-supervisor-types.d.ts

@@ -0,0 +1,83 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { OAuthAccessTokenManager } from "./oauth-access-token.ts";
+import type { InboundMailContext, MailAccountRecord, RawInboundMessage } from "./types.ts";
+export type InboundMailSupervisorDeps = {
+    /** Slim context for provider calls (`registry` is required; `secrets` is
+     *  used for provider credential reads). */
+    readonly providerCtx: InboundMailContext;
+    /** App database — direct reads from read_mail_accounts (account snapshot)
+     *  and direct writes to store_mail_sync_cursors (unmanaged store). */
+    readonly db: DbConnection;
+    /** Standard dispatcher with SystemUser — carries ingest-message and
+     *  update-account. */
+    readonly dispatchWrite: (args: {
+        readonly handlerQn: string;
+        readonly payload: unknown;
+        readonly tenantId: string;
+    }) => Promise<{
+        readonly isSuccess: boolean;
+        readonly data?: unknown;
+        readonly error?: unknown;
+    }>;
+    /** Optional override for where the raw MIME original is stored. Without it the ingest handler
+     *  stores original and attachments itself through the tenant's file provider
+     *  (bodyRef = "" here lets it pick the deterministic key). */
+    readonly storeBody?: (account: MailAccountRecord, msg: RawInboundMessage) => Promise<string>;
+    readonly pollIntervalMs?: number;
+    /** Clock for the failure-count bucket of a tick; tests inject a fake one. */
+    readonly now?: () => Temporal.Instant;
+    readonly backfillWindowDays?: number;
+    readonly maxMessagesPerPoll?: number;
+    /** Accounts synced side by side within one tick. Default 4. */
+    readonly pollConcurrency?: number;
+    /** Longest a single account's sync may run before the supervisor abandons it as a failed poll.
+     *  Default 10 minutes. */
+    readonly accountPollDeadlineMs?: number;
+    readonly watchBackoffInitialMs?: number;
+    readonly watchBackoffMaxMs?: number;
+    /** Coordinates the IMAP watch (not the poll) across worker processes:
+     *  before `plugin.watch()`, ensureWatcher claims a TTL lease for the
+     *  account via `lock.acquire` and renews it via `lock.renew` while the
+     *  watcher lives. Omit for single-process deployments — every active
+     *  account is watched locally, same as before. */
+    readonly lock?: DistributedLock;
+    /** Access-token lifecycle for OAuth accounts. Defaults to a manager built
+     *  from `db` + `providerCtx.secrets`; pass the instance shared with
+     *  `createInboundMailConnectRoutes` so a fresh connect primes this cache. */
+    readonly oauthTokens?: OAuthAccessTokenManager;
+    /** TTL (seconds) for the per-account watch lease. Default 90s, renewed
+     *  every ttl/3. Only used when `lock` is set. */
+    readonly watchLeaseTtlSeconds?: number;
+    readonly log?: (line: string) => void;
+};
+export type WatcherState = {
+    stop: (() => Promise<void>) | null;
+    backoffMs: number;
+    restartTimer: ReturnType<typeof setTimeout> | null;
+    /** Incremented by stop() to prevent a delayed restart from reviving
+     *  an already stopped watcher. */
+    generation: number;
+    /** Token from `deps.lock.acquire` while this worker owns the account's
+     *  watch lease; null when unclaimed (no `deps.lock`, or claim lost). */
+    lockToken: string | null;
+    renewTimer: ReturnType<typeof setTimeout> | null;
+    /** Consecutive renew() throws — tear down once failures span a full TTL. */
+    renewFailures: number;
+    /** True while plugin.watch() is in flight (re-entrancy guard). */
+    starting: boolean;
+    /** The provider reads the account it was handed at watch start; a changed trust setting
+     *  only reaches it through a fresh watch. */
+    trustedAuthservId: string | null;
+};
+export type WatchLeaseResult = "acquired" | "no-token" | "stale";
+export type InboundMailSupervisor = {
+    readonly start: () => Promise<void>;
+    /** Reconciliation run across all active accounts; also usable standalone
+     *  for tests and manual operational triggers. */
+    readonly pollOnce: () => Promise<void>;
+    /** Syncs one account immediately (connect/reconnect wake-up); joins a sync already running for it. */
+    readonly syncAccountNow: (accountId: string) => Promise<void>;
+    readonly stop: () => Promise<void>;
+};

package/dist/inbound-mail-foundation/watch-supervisor-types.js

@@ -0,0 +1 @@
+export {};

package/dist/inbound-mail-foundation/watch-supervisor.d.ts

@@ -1,54 +1,2 @@
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
-import { type OAuthAccessTokenManager } from "./oauth-access-token.ts";
-import { type InboundMailContext, type MailAccountRecord, type RawInboundMessage } from "./types.ts";
-export type InboundMailSupervisorDeps = {
-    /** Slim context for provider calls (`registry` is required; `secrets` is
-     *  used for provider credential reads). */
-    readonly providerCtx: InboundMailContext;
-    /** App database — direct reads from read_mail_accounts (account snapshot)
-     *  and direct writes to store_mail_sync_cursors (unmanaged store). */
-    readonly db: DbConnection;
-    /** Standard dispatcher with SystemUser — carries ingest-message and
-     *  update-account. */
-    readonly dispatchWrite: (args: {
-        readonly handlerQn: string;
-        readonly payload: unknown;
-        readonly tenantId: string;
-    }) => Promise<{
-        readonly isSuccess: boolean;
-        readonly data?: unknown;
-        readonly error?: unknown;
-    }>;
-    /** Persists the raw MIME body (file-foundation) and returns its bodyRef
-     *  for the event. Without this hook, runs in snippet-only mode
-     *  (bodyRef = ""). */
-    readonly storeBody?: (account: MailAccountRecord, msg: RawInboundMessage) => Promise<string>;
-    readonly pollIntervalMs?: number;
-    readonly backfillWindowDays?: number;
-    readonly maxMessagesPerPoll?: number;
-    readonly watchBackoffInitialMs?: number;
-    readonly watchBackoffMaxMs?: number;
-    /** Coordinates the IMAP watch (not the poll) across worker processes:
-     *  before `plugin.watch()`, ensureWatcher claims a TTL lease for the
-     *  account via `lock.acquire` and renews it via `lock.renew` while the
-     *  watcher lives. Omit for single-process deployments — every active
-     *  account is watched locally, same as before. */
-    readonly lock?: DistributedLock;
-    /** Access-token lifecycle for OAuth accounts. Defaults to a manager built
-     *  from `db` + `providerCtx.secrets`; pass the instance shared with
-     *  `createInboundMailConnectRoutes` so a fresh connect primes this cache. */
-    readonly oauthTokens?: OAuthAccessTokenManager;
-    /** TTL (seconds) for the per-account watch lease. Default 90s, renewed
-     *  every ttl/3. Only used when `lock` is set. */
-    readonly watchLeaseTtlSeconds?: number;
-    readonly log?: (line: string) => void;
-};
-export type InboundMailSupervisor = {
-    readonly start: () => Promise<void>;
-    /** Reconciliation run across all active accounts; also usable standalone
-     *  for tests and manual operational triggers. */
-    readonly pollOnce: () => Promise<void>;
-    readonly stop: () => Promise<void>;
-};
+import type { InboundMailSupervisor, InboundMailSupervisorDeps } from "./watch-supervisor-types.ts";
 export declare function createInboundMailSupervisor(deps: InboundMailSupervisorDeps): InboundMailSupervisor;