@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

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

@@ -13,7 +13,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.
@@ -59,8 +61,29 @@ 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";
 };
 
 /**
@@ -89,9 +112,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;
 };
@@ -101,55 +132,39 @@ export type RawInboundMessage = {
  *  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
@@ -183,8 +198,19 @@ export type InboundMailProviderPlugin = {
       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
@@ -193,7 +219,8 @@ export type InboundMailProviderPlugin = {
     ctx: InboundMailContext,
     account: MailAccountRecord,
     message: OutboundMailMessage,
-  ) => Promise<OutboundMailSent>;
+    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
@@ -203,7 +230,11 @@ export type InboundMailProviderPlugin = {
     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
@@ -232,63 +263,3 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
     [INBOUND_MAIL_PROVIDER_EXTENSION]: InboundMailProviderPlugin;
   }
 }
-
-// =============================================================================
-// 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 {
-  readonly kind = "inbound-auth-error" as const;
-  constructor(message: string) {
-    super(message);
-    this.name = "InboundAuthError";
-  }
-}
-
-export class InboundRateLimitError extends Error {
-  readonly kind = "inbound-rate-limit-error" as const;
-  readonly retryAfterMs: number;
-  constructor(message: string, retryAfterMs: number) {
-    super(message);
-    this.name = "InboundRateLimitError";
-    this.retryAfterMs = retryAfterMs;
-  }
-}
-
-export class InboundCursorInvalidError extends Error {
-  readonly kind = "inbound-cursor-invalid-error" as const;
-  constructor(message: string) {
-    super(message);
-    this.name = "InboundCursorInvalidError";
-  }
-}
-
-export class InboundTransientError extends Error {
-  readonly kind = "inbound-transient-error" as const;
-  constructor(message: string) {
-    super(message);
-    this.name = "InboundTransientError";
-  }
-}
-
-export function isInboundAuthError(e: unknown): e is InboundAuthError {
-  return e instanceof Error && "kind" in e && e.kind === "inbound-auth-error";
-}
-export function isInboundRateLimitError(e: unknown): e is InboundRateLimitError {
-  return e instanceof Error && "kind" in e && e.kind === "inbound-rate-limit-error";
-}
-export function isInboundCursorInvalidError(e: unknown): e is InboundCursorInvalidError {
-  return e instanceof Error && "kind" in e && e.kind === "inbound-cursor-invalid-error";
-}
-export function isInboundTransientError(e: unknown): e is InboundTransientError {
-  return e instanceof Error && "kind" in e && e.kind === "inbound-transient-error";
-}

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

@@ -0,0 +1,33 @@
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { wakeMailAccount } from "./account-wake.ts";
+import { InboundMailAccountStatuses } from "./constants.ts";
+import { MAIL_ACCOUNT_CONNECTED_EVENT_QN, MAIL_ACCOUNT_UPDATED_EVENT_QN } from "./events.ts";
+
+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: FeatureRegistrar<"inbound-mail-foundation">) {
+  const wakeIfActive = (
+    event: Parameters<Parameters<typeof r.multiStreamProjection>[0]["apply"][string]>[0],
+  ): void => {
+    // 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/packages/bundled-features/src/inbound-mail-foundation/watch-catch-up.ts

@@ -0,0 +1,68 @@
+import { describeError } from "./describe-error.ts";
+import {
+  type InFlightSyncs,
+  type PollAccountOptions,
+  type PollAccountResult,
+  runExclusivePerAccount,
+} 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 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 {
+  const pending = new Set<Promise<void>>();
+
+  async function catchUp(
+    account: SyncableAccount,
+    plugin: InboundMailProviderPlugin,
+  ): Promise<void> {
+    // 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: Promise<void> = 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/packages/bundled-features/src/inbound-mail-foundation/watch-lease.ts

@@ -0,0 +1,124 @@
+import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
+import { describeError } from "./describe-error.ts";
+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>;
+};
+
+// 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: {
+  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 {
+  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: MailAccountRecord,
+    state: WatcherState,
+    generation: number,
+  ): void {
+    state.renewTimer = setTimeout(() => {
+      void renewLeaseOnce(account, state, generation);
+    }, renewIntervalMs);
+  }
+
+  async function tearDownAfterRenewFailures(
+    account: MailAccountRecord,
+    state: WatcherState,
+    reason: string,
+  ): Promise<void> {
+    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: MailAccountRecord,
+    state: WatcherState,
+    generation: number,
+  ): Promise<void> {
+    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: boolean;
+    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: MailAccountRecord,
+    state: WatcherState,
+    generation: number,
+  ): void {
+    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: MailAccountRecord,
+    state: WatcherState,
+  ): Promise<WatchLeaseResult> {
+    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/packages/bundled-features/src/inbound-mail-foundation/watch-supervisor-types.ts

@@ -0,0 +1,87 @@
+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>;
+};