@remit/backend 0.0.143 → 0.0.145

package/dist/src/service/create-remit-client.d.ts

@@ -0,0 +1,109 @@
+import type { IAccountConfigRepository, IAccountExportRequestRepository, IAccountRepository, IAccountSettingRepository, IAddressRepository, ICalendarCollectionRepository, ICalendarEventIndexRepository, ICalendarFeedTokenRepository, ICalendarObjectRepository, ICalendarStore, ICalendarSuggestionRepository, IConfigImportRepository, IEnvelopeRepository, IFilterRepository, ILabelRepository, IMailboxLockRepository, IMailboxRepository, IMailboxSpecialUseRepository, IMessageFlagPushRepository, IMessageFlagRepository, IMessageLabelRepository, IMessagePlacementMoveRepository, IMessageRepository, IOrganizeJobRequestRepository, IOutboxAttachmentRepository, IOutboxMessageRepository, IQuarantineRepository, ISenderSignerStandingRepository, ISyncWarningRepository, IThreadMessageRepository } from "@remit/data-ports";
+import { BodySyncQueueService, BodySyncService, type FilterConfig, FlagQueueService, type IImapConnection, MailboxQueueService, MessageMoveService, OutboxAttachmentService, OutboxQueueService, SpamReportService } from "@remit/mailbox-service";
+import { type SecretsService } from "@remit/secrets-service";
+import type { StorageService } from "@remit/storage-service";
+import type { QueueName, RemitClientQueues } from "./queues.js";
+export interface ConnectionScope {
+    getConnection: () => Promise<IImapConnection>;
+    disconnect: () => Promise<void>;
+}
+export interface RemitClientCore {
+    accountConfig: IAccountConfigRepository;
+    account: IAccountRepository;
+    accountSetting: IAccountSettingRepository;
+    address: IAddressRepository;
+    mailbox: IMailboxRepository;
+    mailboxSpecialUse: IMailboxSpecialUseRepository;
+    mailboxLock: IMailboxLockRepository;
+    message: IMessageRepository;
+    messageFlag: IMessageFlagRepository;
+    outboxMessage: IOutboxMessageRepository;
+    threadMessage: IThreadMessageRepository;
+    envelope: IEnvelopeRepository;
+    accountExportRequest: IAccountExportRequestRepository;
+    configImport: IConfigImportRepository;
+    quarantine: IQuarantineRepository;
+    syncWarning: ISyncWarningRepository;
+    organizeJobRequest: IOrganizeJobRequestRepository;
+    filter: IFilterRepository;
+    label: ILabelRepository;
+    messageLabel: IMessageLabelRepository;
+    senderSignerStanding: ISenderSignerStandingRepository;
+    calendarCollection: ICalendarCollectionRepository;
+    calendarObject: ICalendarObjectRepository;
+    calendarEventIndex: ICalendarEventIndexRepository;
+    calendarFeedToken: ICalendarFeedTokenRepository;
+    calendarSuggestion: ICalendarSuggestionRepository;
+    calendarStore: ICalendarStore;
+    storage: StorageService;
+    secrets: SecretsService;
+    placementMove: IMessagePlacementMoveRepository;
+    flagPush: IMessageFlagPushRepository;
+    outboxAttachment: OutboxAttachmentService;
+    createConnectionScope: (accountId: string) => Promise<ConnectionScope>;
+}
+export interface SyncQueueServices {
+    flagQueue: FlagQueueService;
+    mailboxQueue: MailboxQueueService;
+    messageMove: MessageMoveService;
+    spamReport: SpamReportService;
+}
+export interface SmtpQueueServices {
+    outboxQueue: OutboxQueueService;
+}
+export interface BodyQueueServices {
+    bodySyncQueue: BodySyncQueueService;
+}
+export interface ReadPathServices {
+    bodySync: BodySyncService;
+}
+export type RemitClient<K extends QueueName = QueueName> = RemitClientCore & {
+    queues: Pick<RemitClientQueues, K>;
+} & ("sync" extends K ? SyncQueueServices : unknown) & ("smtp" extends K ? SmtpQueueServices : unknown) & ("body" extends K ? BodyQueueServices : unknown) & ("sync" | "messageManagement" extends K ? ReadPathServices : unknown);
+export interface RemitClientRepositories {
+    accountConfig: IAccountConfigRepository;
+    account: IAccountRepository;
+    accountSetting: IAccountSettingRepository;
+    address: IAddressRepository;
+    mailbox: IMailboxRepository;
+    mailboxSpecialUse: IMailboxSpecialUseRepository;
+    mailboxLock: IMailboxLockRepository;
+    message: IMessageRepository;
+    messageFlag: IMessageFlagRepository;
+    outboxMessage: IOutboxMessageRepository;
+    outboxAttachment: IOutboxAttachmentRepository;
+    threadMessage: IThreadMessageRepository;
+    envelope: IEnvelopeRepository;
+    accountExportRequest: IAccountExportRequestRepository;
+    configImport: IConfigImportRepository;
+    quarantine: IQuarantineRepository;
+    syncWarning: ISyncWarningRepository;
+    organizeJobRequest: IOrganizeJobRequestRepository;
+    placementMove: IMessagePlacementMoveRepository;
+    flagPush: IMessageFlagPushRepository;
+    filter: IFilterRepository;
+    label: ILabelRepository;
+    messageLabel: IMessageLabelRepository;
+    senderSignerStanding: ISenderSignerStandingRepository;
+    calendarCollection: ICalendarCollectionRepository;
+    calendarObject: ICalendarObjectRepository;
+    calendarEventIndex: ICalendarEventIndexRepository;
+    calendarFeedToken: ICalendarFeedTokenRepository;
+    calendarSuggestion: ICalendarSuggestionRepository;
+    calendarStore: ICalendarStore;
+}
+export interface RemitClientSharedDeps {
+    storage: StorageService;
+    secrets: SecretsService;
+    queues: RemitClientQueues;
+}
+export interface RemitClientDeps extends RemitClientSharedDeps {
+    repositories: RemitClientRepositories;
+}
+export declare const buildReadPathFilterConfig: (repositories: Pick<RemitClientRepositories, "filter" | "messageLabel" | "mailbox" | "message" | "threadMessage" | "placementMove" | "address" | "mailboxSpecialUse">, queues: Pick<RemitClientQueues, "messageManagement">) => FilterConfig;
+export declare const createRemitCore: (deps: Omit<RemitClientDeps, "queues">) => RemitClientCore;
+export declare const composeSyncServices: (core: RemitClientCore, queues: Pick<RemitClientQueues, "sync">) => SyncQueueServices;
+export declare const composeSmtpServices: (core: RemitClientCore, queues: Pick<RemitClientQueues, "smtp">) => SmtpQueueServices;
+export declare const composeBodyServices: (queues: Pick<RemitClientQueues, "body">) => BodyQueueServices;
+export declare const composeReadPathServices: (core: RemitClientCore, queues: Pick<RemitClientQueues, "messageManagement">, sync: Pick<SyncQueueServices, "flagQueue">) => ReadPathServices;
+export declare const createRemitClient: (deps: RemitClientDeps) => RemitClient;

package/dist/src/service/create-remit-client.js

@@ -0,0 +1,188 @@
+import { logger } from "@remit/logger";
+import { BodySyncQueueService, BodySyncService, createConnection, FlagPushService, FlagQueueService, MailboxQueueService, MessageMoveService, OutboxAttachmentService, OutboxQueueService, PlacementMoveService, SpamReportService, SyncWarningService, } from "@remit/mailbox-service";
+import { buildFilterConfig } from "@remit/mailbox-service/filter-config";
+import { deserializeEncryptedPayload, } from "@remit/secrets-service";
+const buildConnectionScope = (accountService, secretsService) => async (accountId) => {
+    const account = await accountService.get(accountId);
+    if (!account.passwordHash) {
+        throw new Error(`Account ${accountId} has no passwordHash — OAuth accounts cannot use this connection path`);
+    }
+    const password = await secretsService.decrypt(deserializeEncryptedPayload(JSON.parse(account.passwordHash)));
+    let connection = null;
+    let connectPromise = null;
+    const getConnection = async () => {
+        if (connectPromise) {
+            return connectPromise;
+        }
+        const conn = createConnection({
+            user: account.username,
+            credentials: { kind: "password", password },
+            host: account.imapHost,
+            port: account.imapPort,
+            tls: account.imapTls,
+        });
+        connection = conn;
+        connectPromise = conn.connect().then(() => conn);
+        return connectPromise;
+    };
+    const disconnect = async () => {
+        if (connection) {
+            await connection.disconnect();
+            connection = null;
+            connectPromise = null;
+        }
+    };
+    return { getConnection, disconnect };
+};
+// The read-path body backfill (describeMessage / getRawMessage →
+// fetchAndGetBody) materializes a body that was never sync-synced, and must run
+// the account's standing filters the same way the imap-worker's sync path does.
+// Without this, a message a user opens before background body-sync is classified
+// but never filter-evaluated — and once its body is stored the filter-capable
+// sync path skips it, so an explicit standing filter silently never fires (issue
+// #223). Only the explicit user-rule half is wired here; heuristic classifier
+// placement stays on the sync path. It shares `buildFilterConfig` with
+// `sync-message-body.ts`, so a filter fires on either (issue #298). Over the
+// message-management queue's local-first PlacementMoveService.
+export const buildReadPathFilterConfig = (repositories, queues) => {
+    const { messageManagement } = queues;
+    return buildFilterConfig({
+        filterService: repositories.filter,
+        messageLabelService: repositories.messageLabel,
+        mailboxService: repositories.mailbox,
+        placementMoveService: new PlacementMoveService({
+            messageService: repositories.message,
+            threadMessageService: repositories.threadMessage,
+            markerService: repositories.placementMove,
+            addressService: repositories.address,
+            mailboxSpecialUseService: repositories.mailboxSpecialUse,
+            mailboxService: repositories.mailbox,
+            queue: messageManagement,
+        }),
+    });
+};
+export const createRemitCore = (deps) => {
+    const { repositories, storage, secrets } = deps;
+    return {
+        accountConfig: repositories.accountConfig,
+        account: repositories.account,
+        accountSetting: repositories.accountSetting,
+        address: repositories.address,
+        mailbox: repositories.mailbox,
+        mailboxSpecialUse: repositories.mailboxSpecialUse,
+        mailboxLock: repositories.mailboxLock,
+        message: repositories.message,
+        messageFlag: repositories.messageFlag,
+        outboxMessage: repositories.outboxMessage,
+        threadMessage: repositories.threadMessage,
+        envelope: repositories.envelope,
+        accountExportRequest: repositories.accountExportRequest,
+        configImport: repositories.configImport,
+        quarantine: repositories.quarantine,
+        syncWarning: repositories.syncWarning,
+        organizeJobRequest: repositories.organizeJobRequest,
+        filter: repositories.filter,
+        label: repositories.label,
+        messageLabel: repositories.messageLabel,
+        senderSignerStanding: repositories.senderSignerStanding,
+        calendarCollection: repositories.calendarCollection,
+        calendarObject: repositories.calendarObject,
+        calendarEventIndex: repositories.calendarEventIndex,
+        calendarFeedToken: repositories.calendarFeedToken,
+        calendarSuggestion: repositories.calendarSuggestion,
+        calendarStore: repositories.calendarStore,
+        storage,
+        secrets,
+        placementMove: repositories.placementMove,
+        flagPush: repositories.flagPush,
+        // One instance, shared with the outbox queue service: the per-draft chain
+        // that makes the attachment cap safe under concurrency lives on it, and a
+        // discard racing an upload has to take the same lock the upload does.
+        outboxAttachment: new OutboxAttachmentService({
+            outboxMessageService: repositories.outboxMessage,
+            outboxAttachmentService: repositories.outboxAttachment,
+            storage,
+        }),
+        createConnectionScope: buildConnectionScope(repositories.account, secrets),
+    };
+};
+export const composeSyncServices = (core, queues) => {
+    const flagPushService = new FlagPushService({
+        markerService: core.flagPush,
+        queue: queues.sync,
+        logger,
+    });
+    const messageMove = new MessageMoveService({
+        messageService: core.message,
+        mailboxService: core.mailbox,
+        mailboxSpecialUseService: core.mailboxSpecialUse,
+        threadMessageService: core.threadMessage,
+        addressService: core.address,
+        queue: queues.sync,
+        logger,
+    });
+    return {
+        flagQueue: new FlagQueueService({
+            messageFlagService: core.messageFlag,
+            messageService: core.message,
+            threadMessageService: core.threadMessage,
+            flagPushService,
+            logger,
+        }),
+        mailboxQueue: new MailboxQueueService({
+            mailboxService: core.mailbox,
+            queue: queues.sync,
+            logger,
+        }),
+        messageMove,
+        spamReport: new SpamReportService({
+            messageService: core.message,
+            addressService: core.address,
+            accountService: core.account,
+            mailboxSpecialUseService: core.mailboxSpecialUse,
+            messageMoveService: messageMove,
+            flagPushService,
+            logger,
+        }),
+    };
+};
+export const composeSmtpServices = (core, queues) => ({
+    outboxQueue: new OutboxQueueService({
+        outboxMessageService: core.outboxMessage,
+        outboxAttachmentService: core.outboxAttachment,
+        accountService: core.account,
+        queue: queues.smtp,
+        logger,
+    }),
+});
+export const composeBodyServices = (queues) => ({
+    bodySyncQueue: new BodySyncQueueService({ queue: queues.body, logger }),
+});
+export const composeReadPathServices = (core, queues, sync) => ({
+    // The flag service is the one `flagQueue` is (issue #302): body sync
+    // auto-marks-read a message from an unsubscribed sender through the exact
+    // same `FlagQueueService.markAsRead` a manual mark-as-read goes through.
+    bodySync: new BodySyncService(core.message, core.storage, core.threadMessage, core.address, core.envelope, new SyncWarningService(core.syncWarning), logger, undefined, buildReadPathFilterConfig(core, queues), undefined, { flagQueueService: sync.flagQueue }, 
+    // The read-path backfill materializes a body the sync path never got to,
+    // so it is a message's first sight as much as the sync pass is — and an
+    // invitation the user opens before background sync must still get its
+    // card (issue #1033, the same argument as the filter wiring above).
+    {
+        calendarSuggestionService: core.calendarSuggestion,
+        calendarStore: core.calendarStore,
+        filterService: core.filter,
+    }),
+});
+export const createRemitClient = (deps) => {
+    const { queues } = deps;
+    const core = createRemitCore(deps);
+    const sync = composeSyncServices(core, queues);
+    return {
+        ...core,
+        queues,
+        ...sync,
+        ...composeSmtpServices(core, queues),
+        ...composeBodyServices(queues),
+        ...composeReadPathServices(core, queues, sync),
+    };
+};

package/dist/src/service/data-client.d.ts

@@ -0,0 +1,12 @@
+import type { RemitClient } from "./create-remit-client.js";
+export type { ConnectionScope, RemitClient, } from "./create-remit-client.js";
+/**
+ * Register the client from the composition root. An adapter that lives outside
+ * this shared, open-core module — DynamoDB, or a Postgres adapter in the
+ * repository that deploys it — is never imported here; its composition root
+ * calls this before handling a request.
+ */
+export declare const setClient: (client: RemitClient) => void;
+export declare const getClient: () => Promise<RemitClient>;
+/** Reset the singleton and any injected client — test use only. */
+export declare const _resetForTest: () => void;

package/dist/src/service/data-client.js

@@ -0,0 +1,42 @@
+let clientPromise = null;
+let injected = null;
+/**
+ * Register the client from the composition root. An adapter that lives outside
+ * this shared, open-core module — DynamoDB, or a Postgres adapter in the
+ * repository that deploys it — is never imported here; its composition root
+ * calls this before handling a request.
+ */
+export const setClient = (client) => {
+    injected = client;
+    clientPromise = null;
+};
+/**
+ * The SQLite composition this build contains, reached only by a process that
+ * registered no client of its own. The `import()` is dynamic so a bundler
+ * following the entry graph of a process that injects its client never reaches
+ * `@remit/drizzle-service` or drizzle-orm (both `external` for the Lambda
+ * esbuild build).
+ *
+ * `SQLITE_APP_DB_PATH` is the precondition the composition needs, checked ahead of
+ * the import so its absence names `setClient` instead of failing on module
+ * resolution inside a bundle, or — worse — opening an empty database and
+ * serving an empty mailbox. It is a precondition, not a backend selection.
+ */
+const buildRelationalClient = async () => {
+    if (!process.env.SQLITE_APP_DB_PATH) {
+        throw new Error("no client registered — register one with setClient() from your composition root");
+    }
+    const composition = await import("./compose-sqlite.js");
+    return composition.buildSqliteClient();
+};
+export const getClient = () => {
+    clientPromise ??= injected
+        ? Promise.resolve(injected)
+        : buildRelationalClient();
+    return clientPromise;
+};
+/** Reset the singleton and any injected client — test use only. */
+export const _resetForTest = () => {
+    clientPromise = null;
+    injected = null;
+};

package/dist/src/service/export-identity.d.ts

@@ -0,0 +1,4 @@
+import type { ConfigExportIdentity } from "@remit/config-transfer";
+import type { ApiConfig } from "../config/api-config.js";
+/** Who wrote a configuration file, and from where. Provenance only. */
+export declare const exportIdentity: (config: Pick<ApiConfig, "updateControlDir" | "publicOrigin">, now?: Date) => ConfigExportIdentity;

package/dist/src/service/export-identity.js

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The version a file says it was written by. The updater owns this fact: it
+ * reads the tag from `.env` and writes it into `state.json`, which is the only
+ * honest source across an update that rewrites that tag underneath a
+ * long-lived process. With no state file there is nothing authoritative to
+ * stamp, and an export says so rather than inventing a version an importing
+ * reader would then trust.
+ */
+const runningVersion = (dir) => {
+    let raw;
+    try {
+        raw = readFileSync(join(dir, "state.json"), "utf8");
+    }
+    catch {
+        return "unknown";
+    }
+    const state = JSON.parse(raw);
+    if (typeof state !== "object" || state === null)
+        return "unknown";
+    const version = state.currentVersion;
+    return typeof version === "string" && version.length > 0
+        ? version
+        : "unknown";
+};
+/** Who wrote a configuration file, and from where. Provenance only. */
+export const exportIdentity = (config, now = new Date()) => ({
+    app: "reader",
+    version: runningVersion(config.updateControlDir),
+    exportedAt: now.toISOString(),
+    instance: config.publicOrigin,
+});

package/dist/src/service/fire-and-forget.d.ts

@@ -0,0 +1,54 @@
+type StructuredLog = (fields: Record<string, unknown>, message: string) => void;
+export interface FireAndForgetLogger {
+    error: StructuredLog;
+}
+export interface FireAndForgetContext {
+    /**
+     * Stable discriminator for the originating call site (e.g. `"config_load"`,
+     * `"account_create"`). Surfaces on the log line as `source` so a CloudWatch
+     * metric filter / alarm can attribute a leak to its origin.
+     */
+    source: string;
+    /**
+     * Message logged when the background work rejects. Should describe the work
+     * and reassure that the failure is contained (e.g. "...best-effort").
+     */
+    message: string;
+    /**
+     * Identifiers carried onto the structured error line (accountId,
+     * accountConfigId, …) so a failure is traceable without a stack dive.
+     */
+    ids?: Record<string, unknown>;
+    /**
+     * Alertable discriminator on the structured error line, the field CloudWatch
+     * metric filters key on. Defaults to `"sync_trigger_failed"` for the original
+     * sync-kick sites; a different fire-and-forget surface (e.g. a flag enqueue)
+     * must pass its own so it is not mis-attributed to the sync-trigger alarm.
+     */
+    alert?: string;
+    logger?: FireAndForgetLogger;
+}
+/**
+ * Run unawaited background work that MUST NOT be able to fail the request that
+ * spawned it.
+ *
+ * The dev/Lambda runtime shares one event loop across concurrent requests, so a
+ * rejection escaping an unawaited background promise (a `void trigger()`) lands
+ * on whatever request happens to be in flight when the deferred work finally
+ * fails — turning an unrelated READ into a spurious 500. That is exactly how an
+ * unreachable SQS queue 500'd `/mailboxes`, `/threads`, `/outbox` and `/config`.
+ *
+ * This helper is the single containment point: it awaits the work inside a
+ * try/catch, logs every rejection LOUDLY with the alertable structured fields
+ * (`alert` — defaulting to `"sync_trigger_failed"`, `source`, the SDK error
+ * name/code, the caller ids), and ALWAYS resolves to void. Callers `void
+ * fireAndForget(...)` with no
+ * chance of an unhandled rejection escaping. Routing all fire-and-forget sites
+ * through here keeps the containment from regressing one handler at a time.
+ *
+ * Use this ONLY for genuine side effects whose failure must not change the
+ * response. A failure the caller is responsible for (the real DynamoDB read, an
+ * enqueue that IS the request's purpose) must still propagate and 500.
+ */
+export declare const fireAndForget: (work: () => Promise<unknown>, context: FireAndForgetContext) => Promise<void>;
+export {};

package/dist/src/service/fire-and-forget.js

@@ -0,0 +1,37 @@
+import { logger } from "@remit/logger";
+/**
+ * Run unawaited background work that MUST NOT be able to fail the request that
+ * spawned it.
+ *
+ * The dev/Lambda runtime shares one event loop across concurrent requests, so a
+ * rejection escaping an unawaited background promise (a `void trigger()`) lands
+ * on whatever request happens to be in flight when the deferred work finally
+ * fails — turning an unrelated READ into a spurious 500. That is exactly how an
+ * unreachable SQS queue 500'd `/mailboxes`, `/threads`, `/outbox` and `/config`.
+ *
+ * This helper is the single containment point: it awaits the work inside a
+ * try/catch, logs every rejection LOUDLY with the alertable structured fields
+ * (`alert` — defaulting to `"sync_trigger_failed"`, `source`, the SDK error
+ * name/code, the caller ids), and ALWAYS resolves to void. Callers `void
+ * fireAndForget(...)` with no
+ * chance of an unhandled rejection escaping. Routing all fire-and-forget sites
+ * through here keeps the containment from regressing one handler at a time.
+ *
+ * Use this ONLY for genuine side effects whose failure must not change the
+ * response. A failure the caller is responsible for (the real DynamoDB read, an
+ * enqueue that IS the request's purpose) must still propagate and 500.
+ */
+export const fireAndForget = async (work, context) => {
+    await work().catch((error) => {
+        const log = context.logger ?? logger;
+        log.error({
+            alert: context.alert ?? "sync_trigger_failed",
+            source: context.source,
+            ...context.ids,
+            errorName: error?.name,
+            errorCode: error?.Code ??
+                error?.code,
+            error,
+        }, context.message);
+    });
+};

package/dist/src/service/organize.d.ts

@@ -0,0 +1,181 @@
+import type { FilterItem, OrganizeJobRequestItem } from "@remit/data-ports";
+import { type FilterMessage, type LiteralClauseNarrowing, PlacementMoveService } from "@remit/mailbox-service";
+import type { RemitClient } from "./data-client.js";
+/**
+ * Hard cap on both the previewed and the applied set. A back-apply is a
+ * data-heavy corpus pass (remit-data-heavy: frugal), bounded by counting
+ * MATCHES as it pages a store-side narrowed listing, and the final match set
+ * never exceeds this. It bounds the answer, never the corpus the question is
+ * asked of (#459).
+ */
+export declare const ORGANIZE_MATCH_LIMIT = 500;
+/**
+ * The predicate + action for one back-apply pass — the OrganizeInput fields,
+ * flattened. The action fields carry absence as the `"None"` sentinel (RFC 034
+ * Decision 3.1).
+ */
+export interface OrganizePredicate {
+    matchOperator: FilterItem["matchOperator"];
+    literalClauses: FilterItem["literalClauses"];
+    actionLabelId: string;
+    actionMailboxId: string;
+}
+/**
+ * The predicate a back-apply job snapshotted onto its row, read back verbatim so
+ * the worker runs exactly what the request asked for.
+ */
+export declare const predicateFromJob: (job: OrganizeJobRequestItem) => OrganizePredicate;
+/**
+ * One corpus message projected onto the fields a literal clause matches
+ * against, paired with its id. Sourced from the core thread rows.
+ */
+export interface OrganizeCandidate {
+    messageId: string;
+    message: FilterMessage;
+}
+/**
+ * One page of the narrowed corpus, cursored exactly as the underlying listing
+ * is: an absent `continuationToken` means the store has no more rows matching
+ * the terms, never that a read window ran out.
+ */
+export interface OrganizeCandidatePage {
+    items: OrganizeCandidate[];
+    continuationToken?: string;
+}
+/** What to ask the store for, and where to resume. */
+export interface OrganizeCandidateQuery extends LiteralClauseNarrowing {
+    limit: number;
+    continuationToken?: string;
+    mailboxIds?: readonly string[];
+}
+/**
+ * Where a pass looks and which standing filter it runs for. A filter
+ * back-apply narrows the corpus to the inbox and matches a body-content clause
+ * on the stored preview; an "all like these" pass sets neither.
+ */
+export interface OrganizeMatchScope {
+    filterId?: string;
+    mailboxIds?: readonly string[];
+}
+export interface OrganizeMatchDeps {
+    /**
+     * One page of the account's messages as literal-match candidates, with the
+     * clause terms evaluated by the store. Paged rather than capped, so the
+     * caller's bound falls on matches instead of on how far back the read
+     * reached (#459).
+     */
+    listAccountFilterMessages: (accountConfigId: string, query: OrganizeCandidateQuery) => Promise<OrganizeCandidatePage>;
+}
+/**
+ * Why the matcher refused a predicate. A refusal is an expected outcome of
+ * asking for a rule this deployment cannot evaluate, not a fault: the HTTP
+ * boundary words it as a 400 and the back-apply worker fails the job row on it,
+ * neither of which may treat it as the infrastructure failure a throw would
+ * make it (reader #463).
+ */
+export interface OrganizeRejection {
+    reason: "BodyContentUnsupported" | "FilterNotActive" | "FilterMissing" | "FolderMissing";
+    message: string;
+}
+/** The matched ids. */
+export interface OrganizeMatched {
+    rejected: null;
+    messageIds: string[];
+}
+/** The predicate was refused: nothing matched, and nothing may be applied. */
+export interface OrganizeMatchRejected {
+    rejected: OrganizeRejection;
+}
+export type OrganizeMatchResult = OrganizeMatched | OrganizeMatchRejected;
+/**
+ * A `HasWords` clause matches the message body (RFC 031, `clauseMatches`). The
+ * live index-time filter evaluates it against the full parsed body
+ * (`body-sync.ts` `toFilterMessage`); the corpus slice carries only
+ * `From`/`Subject` at full fidelity and no faithful body, so it cannot serve a
+ * body-content clause without silently narrowing the match to whatever preview
+ * happened to be stored. A body-content clause on an "all like these" pass is
+ * refused instead of returning a wrong set.
+ */
+export declare const BODY_CONTENT_REJECTION_MESSAGE = "Organize cannot match a body-content (HasWords) clause over the mailbox: it reads only each message's preview, not its body";
+/**
+ * The refusal a predicate carries on its own, decidable without reading the
+ * corpus: a body-content clause is refused up front. `createOrganizeJob` runs
+ * this before enqueueing and {@link matchOrganize} runs it too, so preview, the
+ * worker and the request boundary all refuse the same rule (reader #463).
+ */
+export declare const organizePredicateRejection: (predicate: OrganizePredicate) => OrganizeRejection | null;
+/**
+ * The matcher shared by preview and apply — the previewed set equals the applied
+ * set for the same input. Read-only. Returns the matching message ids, bounded.
+ *
+ * - An ad-hoc predicate with no clause matches nothing: a run-now request
+ *   carries none, and an empty predicate must never sweep the whole mailbox.
+ * - A predicate the corpus read cannot evaluate (a body-content clause on an
+ *   "all like these" pass, see {@link bodyContentRejection}) comes back as a
+ *   rejection, so a caller can tell a refused rule from a broken deployment
+ *   (reader #463).
+ */
+export declare const matchOrganize: (deps: OrganizeMatchDeps, accountConfigId: string, predicate: OrganizePredicate, limit?: number, scope?: OrganizeMatchScope) => Promise<OrganizeMatchResult>;
+/** The matcher deps for the running backend/worker. */
+export declare const buildOrganizeMatchDeps: (client: RemitClient<never>) => OrganizeMatchDeps;
+/**
+ * The exclusive-move arm of a back-apply, wired exactly like the body-sync
+ * placement mover (`sync-message-body.ts`): the local-first
+ * {@link PlacementMoveService} over the shared message-management queue. A move
+ * commits locally (marker + ThreadMessage + Message row) and enqueues a
+ * `PLACEMENT_MOVE_PUSH` for the reconciler; its marker state engine makes a
+ * redelivered job idempotent (mirrors #1297).
+ */
+export declare const buildOrganizeMoveService: (client: RemitClient<"messageManagement">) => PlacementMoveService;
+export interface ApplyOrganizeDeps {
+    client: RemitClient<never>;
+    moveService: PlacementMoveService;
+}
+export interface ApplyOrganizeResult {
+    applied: number;
+    failed: number;
+    /** Why each failed message failed, as the job reports it. */
+    failures: string[];
+}
+/**
+ * Apply the back-apply action to every matched message, reusing the index-time
+ * apply plumbing: an idempotent MessageLabel upsert (additive) with
+ * `appliedByFilterId` deliberately ABSENT — this path attributes to no filter,
+ * exactly like a hand-applied label (RFC 034 Decision 3.3) — and an idempotent
+ * folder move (exclusive). One poisoned message never fails the batch; it is
+ * counted as failed and the pass continues.
+ *
+ * Every requested move happens. A standing filter acts at exactly two moments —
+ * when a message is first seen, and when the user presses "run rules now" — and
+ * holds no claim on that message afterwards, so it never arbitrates against a
+ * later user-initiated apply (reader #497). Cross-filter precedence stays where
+ * two filters collide over the same message at the same trigger
+ * (`FilterPipeline`/`selectMoveWinner`), and `applied` therefore counts moves
+ * that actually happened.
+ */
+export declare const applyOrganize: (deps: ApplyOrganizeDeps, accountConfigId: string, messageIds: readonly string[], predicate: OrganizePredicate) => Promise<ApplyOrganizeResult>;
+export interface FilterBackApplyResult {
+    rejected: null;
+    matched: number;
+    applied: number;
+    failed: number;
+    failures: string[];
+}
+export interface FilterBackApplyDeps {
+    client: RemitClient<never>;
+    matchDeps: OrganizeMatchDeps;
+    moveService: PlacementMoveService;
+}
+/**
+ * Run one standing filter over the inbox as if each matching message had just
+ * arrived. Every message the matcher returns is a match: its label always
+ * applies, being additive. The index-time {@link FilterPipeline} only orders
+ * the exclusive move, so the move is skipped where it names another active
+ * filter. The pipeline sees the stored preview rather than the full body, so
+ * its verdict on whether this filter matches is not asked; and an evaluate it
+ * could not finish names no other filter, so the move goes ahead rather than
+ * silently dropping out.
+ */
+export declare const backApplyFilter: (deps: FilterBackApplyDeps, accountConfigId: string, filterId: string) => Promise<FilterBackApplyResult | OrganizeMatchRejected>;
+/** Whether a job row runs a standing filter rather than its own snapshot. */
+export declare const isFilterJob: (job: Pick<OrganizeJobRequestItem, "filterId">) => boolean;