@remit/mailbox-service 0.0.112 → 0.0.114

package/dist/filters/filter-config.d.ts

@@ -0,0 +1,14 @@
+import type { IFilterRepository, IMessageLabelRepository } from "@remit/data-ports";
+import type { PlacementMoveService } from "../placement-move.js";
+import type { FilterConfig } from "./pipeline.js";
+export interface FilterConfigDeps {
+    filterService: IFilterRepository;
+    messageLabelService: IMessageLabelRepository;
+    mailboxService: FilterConfig["mailboxService"];
+    placementMoveService: PlacementMoveService;
+}
+/**
+ * Assemble the filter config a body-materializing pass runs (RFC 034), shared by
+ * the imap-worker's sync path and the backend's read-path backfill.
+ */
+export declare const buildFilterConfig: (deps: FilterConfigDeps) => FilterConfig;

package/dist/filters/filter-config.js

@@ -0,0 +1,10 @@
+/**
+ * Assemble the filter config a body-materializing pass runs (RFC 034), shared by
+ * the imap-worker's sync path and the backend's read-path backfill.
+ */
+export const buildFilterConfig = (deps) => ({
+    filterService: deps.filterService,
+    messageLabelService: deps.messageLabelService,
+    mailboxService: deps.mailboxService,
+    placementMoveService: deps.placementMoveService,
+});

package/{src/filters/list-id.ts → dist/filters/list-id.d.ts}

@@ -1,5 +1,4 @@
 import type { ParsedMail } from "mailparser";
-
 /**
  * Canonical form of a `List-Id` value for exact comparison: the bracketed
  * identifier when the header carries the RFC 2919 `Name <list.id>` shape,
@@ -7,23 +6,10 @@ import type { ParsedMail } from "mailparser";
  * a `ListId` clause pass through this, so `<weekly.news.example.com>` and
  * `weekly.news.example.com` are one list. An empty input normalizes to `""`.
  */
-export const normalizeListId = (value: string): string => {
-	const trimmed = value.trim();
-	const bracketed = trimmed.match(/<([^>]+)>/);
-	return (bracketed ? bracketed[1] : trimmed).trim().toLowerCase();
-};
-
+export declare const normalizeListId: (value: string) => string;
 /**
  * The normalized `List-Id` header value of a parsed message, or `""` when the
  * message carries no `List-Id`. Read from the raw header line so the exact
  * value survives regardless of how the parser structures the header.
  */
-export const extractListId = (parsed: ParsedMail): string => {
-	const line = parsed.headerLines.find(
-		(header) => header.key.toLowerCase() === "list-id",
-	);
-	if (!line) return "";
-	const colon = line.line.indexOf(":");
-	if (colon < 0) return "";
-	return normalizeListId(line.line.slice(colon + 1));
-};
+export declare const extractListId: (parsed: ParsedMail) => string;

package/dist/filters/list-id.js

@@ -0,0 +1,26 @@
+/**
+ * Canonical form of a `List-Id` value for exact comparison: the bracketed
+ * identifier when the header carries the RFC 2919 `Name <list.id>` shape,
+ * otherwise the whole value, trimmed and case-folded. Both the stored copy and
+ * a `ListId` clause pass through this, so `<weekly.news.example.com>` and
+ * `weekly.news.example.com` are one list. An empty input normalizes to `""`.
+ */
+export const normalizeListId = (value) => {
+    const trimmed = value.trim();
+    const bracketed = trimmed.match(/<([^>]+)>/);
+    return (bracketed ? bracketed[1] : trimmed).trim().toLowerCase();
+};
+/**
+ * The normalized `List-Id` header value of a parsed message, or `""` when the
+ * message carries no `List-Id`. Read from the raw header line so the exact
+ * value survives regardless of how the parser structures the header.
+ */
+export const extractListId = (parsed) => {
+    const line = parsed.headerLines.find((header) => header.key.toLowerCase() === "list-id");
+    if (!line)
+        return "";
+    const colon = line.line.indexOf(":");
+    if (colon < 0)
+        return "";
+    return normalizeListId(line.line.slice(colon + 1));
+};

package/dist/filters/match.d.ts

@@ -0,0 +1,69 @@
+import { type FilterItem, type ThreadMessageFieldTerm } from "@remit/data-ports";
+type FilterClause = FilterItem["literalClauses"][number];
+/**
+ * The `"None"` sentinel a filter's action fields carry when that action is
+ * absent (RFC 034 Decision 3.1) — `actionLabelId`/`actionMailboxId` are never
+ * empty/optional strings, so a missing action is this exact value, never `""`.
+ */
+export declare const NO_ACTION = "None";
+/**
+ * The message fields a filter evaluates against — the literal-clause targets
+ * (from / subject / body / list). A plain value object so the matcher stays independent of the `ParsedMail` shape and is
+ * trivially constructed in a test.
+ */
+export interface FilterMessage {
+    from: string;
+    fromName: string;
+    subject: string;
+    text: string;
+    /** Normalized `List-Id` header value (see `normalizeListId`); `""` when absent. */
+    listId: string;
+}
+/**
+ * Whether one literal clause matches the message. From matches against the
+ * sender address and display name; Subject against the subject; HasWords
+ * requires every word somewhere in sender, subject or body; ListId against the exact normalized `List-Id`; FromDomain
+ * against the sender's registrable domain. An empty clause value never matches.
+ */
+export declare const clauseMatches: (clause: FilterClause, msg: FilterMessage) => boolean;
+/**
+ * Whether the literal clauses match under their combine operator. Empty clauses
+ * carry no literal constraint and pass vacuously; a caller that needs a
+ * predicate checks for clauses itself.
+ */
+export declare const literalClausesMatch: (clauses: readonly FilterClause[], operator: FilterItem["matchOperator"], msg: FilterMessage) => boolean;
+/**
+ * The terms to query with, and how to combine them. Empty terms narrow nothing
+ * — the caller reads the whole corpus and refines it.
+ */
+export interface LiteralClauseNarrowing {
+    terms: ThreadMessageFieldTerm[];
+    operator: "and" | "or";
+}
+/**
+ * The store-side half of {@link literalClausesMatch}: the column terms a query
+ * can evaluate on behalf of these clauses, or `null` when they can match
+ * nothing at all and there is no query worth running.
+ *
+ * A term is deliberately WIDER than the clause it stands for — a `FromDomain`
+ * clause narrows to the registrable domain appearing anywhere in the sender,
+ * so `github.com.evil.example` still comes back — and a `HasWords` clause
+ * cannot be narrowed at all, since no row column carries the body. The rows a
+ * term selects are candidates; `literalClausesMatch` still decides. Pushing the
+ * terms down is what makes the caller's bound a bound on RESULTS: filtering a
+ * date-ordered page instead answers "matches among the newest N messages"
+ * (#459).
+ */
+export declare const literalClauseTerms: (clauses: readonly FilterClause[], operator: FilterItem["matchOperator"]) => LiteralClauseNarrowing | null;
+/**
+ * The move a message ends in when several filters matched: the filter whose
+ * predicate or action was most recently *changed* wins (RFC 034 Decision 3.2),
+ * tie-broken on `filterId` for the unreachable identical-timestamp case.
+ * `actionChangedAt` — not `ruleChangedAt` — is the signal: `ruleChangedAt` also
+ * bumps on a scope/expiry-only edit (reader #266), which changes a filter's
+ * lifecycle, not what it matches or does, and must not reorder exclusive-move
+ * precedence (reader #384). Nor is it `updatedAt`, so a cosmetic rename never
+ * flips an exclusive move either.
+ */
+export declare const selectMoveWinner: (candidates: readonly FilterItem[]) => FilterItem | undefined;
+export {};

package/dist/filters/match.js

@@ -0,0 +1,165 @@
+import { FILTER_NO_ACTION, } from "@remit/data-ports";
+import { FilterClauseField, FilterMatchOperator } from "@remit/domain-enums";
+import { getDomain } from "tldts";
+import { normalizeListId } from "./list-id.js";
+/**
+ * The `"None"` sentinel a filter's action fields carry when that action is
+ * absent (RFC 034 Decision 3.1) — `actionLabelId`/`actionMailboxId` are never
+ * empty/optional strings, so a missing action is this exact value, never `""`.
+ */
+export const NO_ACTION = FILTER_NO_ACTION;
+const includesFold = (haystack, needle) => haystack.toLowerCase().includes(needle.toLowerCase());
+/**
+ * Whether every whitespace-separated word of `value` appears somewhere in the
+ * sender address, sender name, subject or body — the shape free-text search
+ * matches with (`buildSearchConditions`), so a filter made from a search keeps
+ * the mail that search showed.
+ */
+const hasEveryWord = (value, msg) => {
+    const fields = [msg.from, msg.fromName, msg.subject, msg.text];
+    return value
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((word) => fields.some((field) => includesFold(field, word)));
+};
+const hostOf = (address) => {
+    const at = address.lastIndexOf("@");
+    return at >= 0 ? address.slice(at + 1) : address;
+};
+/**
+ * The registrable, public-suffix-aware domain of an email address or host, or
+ * `null` when none resolves. `getDomain` folds case and applies the ICANN
+ * suffix list, so `github.com.evil.example` yields `evil.example`, never
+ * `github.com` — a `FromDomain` clause cannot be spoofed by a crafted subdomain.
+ */
+const registrableDomain = (addressOrHost) => getDomain(hostOf(addressOrHost.trim()));
+/**
+ * Whether one literal clause matches the message. From matches against the
+ * sender address and display name; Subject against the subject; HasWords
+ * requires every word somewhere in sender, subject or body; ListId against the exact normalized `List-Id`; FromDomain
+ * against the sender's registrable domain. An empty clause value never matches.
+ */
+export const clauseMatches = (clause, msg) => {
+    const value = clause.value.trim();
+    if (value === "")
+        return false;
+    switch (clause.field) {
+        case FilterClauseField.From:
+            return includesFold(msg.from, value) || includesFold(msg.fromName, value);
+        case FilterClauseField.Subject:
+            return includesFold(msg.subject, value);
+        case FilterClauseField.HasWords:
+            return hasEveryWord(value, msg);
+        case FilterClauseField.ListId: {
+            const target = normalizeListId(value);
+            return target !== "" && normalizeListId(msg.listId) === target;
+        }
+        case FilterClauseField.FromDomain: {
+            const target = registrableDomain(value);
+            if (target === null)
+                return false;
+            return registrableDomain(msg.from) === target;
+        }
+        default:
+            return false;
+    }
+};
+/**
+ * Whether the literal clauses match under their combine operator. Empty clauses
+ * carry no literal constraint and pass vacuously; a caller that needs a
+ * predicate checks for clauses itself.
+ */
+export const literalClausesMatch = (clauses, operator, msg) => {
+    if (clauses.length === 0)
+        return true;
+    return operator === FilterMatchOperator.Or
+        ? clauses.some((clause) => clauseMatches(clause, msg))
+        : clauses.every((clause) => clauseMatches(clause, msg));
+};
+const clauseNarrowing = (clause) => {
+    const value = clause.value.trim();
+    if (value === "")
+        return { kind: "NeverMatches" };
+    switch (clause.field) {
+        case FilterClauseField.From:
+            return { kind: "Term", term: { field: "sender", contains: value } };
+        case FilterClauseField.Subject:
+            return { kind: "Term", term: { field: "subject", contains: value } };
+        case FilterClauseField.ListId: {
+            const target = normalizeListId(value);
+            if (target === "")
+                return { kind: "NeverMatches" };
+            return { kind: "Term", term: { field: "listId", contains: target } };
+        }
+        case FilterClauseField.FromDomain: {
+            const target = registrableDomain(value);
+            if (target === null)
+                return { kind: "NeverMatches" };
+            return { kind: "Term", term: { field: "sender", contains: target } };
+        }
+        default:
+            return { kind: "Unnarrowable" };
+    }
+};
+/**
+ * The store-side half of {@link literalClausesMatch}: the column terms a query
+ * can evaluate on behalf of these clauses, or `null` when they can match
+ * nothing at all and there is no query worth running.
+ *
+ * A term is deliberately WIDER than the clause it stands for — a `FromDomain`
+ * clause narrows to the registrable domain appearing anywhere in the sender,
+ * so `github.com.evil.example` still comes back — and a `HasWords` clause
+ * cannot be narrowed at all, since no row column carries the body. The rows a
+ * term selects are candidates; `literalClausesMatch` still decides. Pushing the
+ * terms down is what makes the caller's bound a bound on RESULTS: filtering a
+ * date-ordered page instead answers "matches among the newest N messages"
+ * (#459).
+ */
+export const literalClauseTerms = (clauses, operator) => {
+    const combine = operator === FilterMatchOperator.Or ? "or" : "and";
+    if (clauses.length === 0)
+        return { terms: [], operator: combine };
+    const narrowings = clauses.map(clauseNarrowing);
+    const terms = narrowings.flatMap((narrowing) => narrowing.kind === "Term" ? [narrowing.term] : []);
+    if (combine === "and") {
+        if (narrowings.some((narrowing) => narrowing.kind === "NeverMatches")) {
+            return null;
+        }
+        return { terms, operator: "and" };
+    }
+    if (narrowings.every((narrowing) => narrowing.kind === "NeverMatches")) {
+        return null;
+    }
+    if (narrowings.some((narrowing) => narrowing.kind === "Unnarrowable")) {
+        return { terms: [], operator: "or" };
+    }
+    return { terms, operator: "or" };
+};
+/**
+ * The move a message ends in when several filters matched: the filter whose
+ * predicate or action was most recently *changed* wins (RFC 034 Decision 3.2),
+ * tie-broken on `filterId` for the unreachable identical-timestamp case.
+ * `actionChangedAt` — not `ruleChangedAt` — is the signal: `ruleChangedAt` also
+ * bumps on a scope/expiry-only edit (reader #266), which changes a filter's
+ * lifecycle, not what it matches or does, and must not reorder exclusive-move
+ * precedence (reader #384). Nor is it `updatedAt`, so a cosmetic rename never
+ * flips an exclusive move either.
+ */
+export const selectMoveWinner = (candidates) => {
+    let winner;
+    for (const candidate of candidates) {
+        if (!winner) {
+            winner = candidate;
+            continue;
+        }
+        if (candidate.actionChangedAt > winner.actionChangedAt) {
+            winner = candidate;
+            continue;
+        }
+        if (candidate.actionChangedAt === winner.actionChangedAt &&
+            candidate.filterId > winner.filterId) {
+            winner = candidate;
+        }
+    }
+    return winner;
+};

package/dist/filters/pipeline.d.ts

@@ -0,0 +1,64 @@
+import type { IFilterRepository, IMailboxRepository, IMessageLabelRepository } from "@remit/data-ports";
+import type { PlacementMoveService } from "../placement-move.js";
+import { type FilterMessage } from "./match.js";
+export interface FilterLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    debug?(obj: Record<string, unknown>, msg: string): void;
+    warn?(obj: Record<string, unknown>, msg: string): void;
+    error?(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Dependencies for the index-time filter pass (RFC 034). Optional on
+ * {@link BodySyncService} the same way {@link PlacementConfig} is — a deployment
+ * without it simply runs no filter matching.
+ */
+export interface FilterConfig {
+    filterService: IFilterRepository;
+    messageLabelService: IMessageLabelRepository;
+    /** Names the account a filter's folder belongs to. */
+    mailboxService: Pick<IMailboxRepository, "resolveAccountId">;
+    placementMoveService: PlacementMoveService;
+}
+/**
+ * What the matched filters resolve to for one message: every matching filter's
+ * label (additive — RFC 034 Decision 3.1), and at most one move (exclusive — the
+ * most-recently-changed matching filter, Decision 3.2).
+ */
+export interface FilterDecision {
+    labels: Array<{
+        labelId: string;
+        filterId: string;
+    }>;
+    move?: {
+        destinationMailboxId: string;
+        filterId: string;
+    };
+}
+/**
+ * Evaluates a synced message against the account's active filters and resolves
+ * the actions to apply (RFC 034). Reads only — listing filters and refreshing
+ * lazy expiry; the caller applies the
+ * resulting {@link FilterDecision}.
+ *
+ * `evaluate` isolates every failure in this read/decision phase from body sync,
+ * matching the placement-resolution precedent (#1246): a schema-drifted query
+ * must never fail the surrounding message store, since the body is
+ * already durable by the time this runs. The apply of the decision — label
+ * writes and the move enqueue — is the caller's responsibility and is *not*
+ * swallowed there, so a genuine DDB/SQS write failure still propagates and
+ * requeues the message.
+ */
+export declare class FilterPipeline {
+    private readonly config;
+    private readonly log;
+    constructor(config: FilterConfig, log: FilterLogger);
+    evaluate(accountConfigId: string, accountId: string, messageId: string, msg: FilterMessage): Promise<FilterDecision>;
+    /**
+     * A filter sits on the account config and sees every account's mail, but its
+     * folder is one account's: mail of another account is not this filter's to
+     * act on, exactly as if it had not matched. A folder no account holds any
+     * more turns the filter off, with the reason the filter list shows.
+     */
+    private appliesTo;
+    private match;
+}

package/dist/filters/pipeline.js

@@ -0,0 +1,100 @@
+import { inspect } from "node:util";
+import { FilterDisabledReason, FilterState } from "@remit/domain-enums";
+import { literalClausesMatch, NO_ACTION, selectMoveWinner, } from "./match.js";
+const EMPTY_DECISION = { labels: [] };
+/**
+ * Evaluates a synced message against the account's active filters and resolves
+ * the actions to apply (RFC 034). Reads only — listing filters and refreshing
+ * lazy expiry; the caller applies the
+ * resulting {@link FilterDecision}.
+ *
+ * `evaluate` isolates every failure in this read/decision phase from body sync,
+ * matching the placement-resolution precedent (#1246): a schema-drifted query
+ * must never fail the surrounding message store, since the body is
+ * already durable by the time this runs. The apply of the decision — label
+ * writes and the move enqueue — is the caller's responsibility and is *not*
+ * swallowed there, so a genuine DDB/SQS write failure still propagates and
+ * requeues the message.
+ */
+export class FilterPipeline {
+    config;
+    log;
+    constructor(config, log) {
+        this.config = config;
+        this.log = log;
+    }
+    async evaluate(accountConfigId, accountId, messageId, msg) {
+        return this.match(accountConfigId, accountId, msg).catch((error) => {
+            this.log.error?.({
+                alert: "body_sync_filter_match_failed",
+                messageId,
+                accountConfigId,
+                errorName: error?.name,
+                error: inspect(error),
+            }, "Filter matching failed; body already stored, continuing without filter actions (best-effort, non-fatal)");
+            return EMPTY_DECISION;
+        });
+    }
+    /**
+     * A filter sits on the account config and sees every account's mail, but its
+     * folder is one account's: mail of another account is not this filter's to
+     * act on, exactly as if it had not matched. A folder no account holds any
+     * more turns the filter off, with the reason the filter list shows.
+     */
+    async appliesTo(accountConfigId, accountId, filter) {
+        if (filter.actionMailboxId === NO_ACTION)
+            return true;
+        const owner = await this.config.mailboxService.resolveAccountId(filter.actionMailboxId);
+        if (owner !== null)
+            return owner === accountId;
+        await this.config.filterService.update(accountConfigId, filter.filterId, {
+            state: FilterState.Disabled,
+            disabledReason: FilterDisabledReason.FolderMissing,
+        });
+        this.log.warn?.({ filterId: filter.filterId, accountConfigId }, "Filter turned off: the folder it moves mail into no longer exists");
+        return false;
+    }
+    async match(accountConfigId, accountId, msg) {
+        const active = await this.config.filterService.listByAccountAndState(accountConfigId, FilterState.Active);
+        if (active.length === 0)
+            return EMPTY_DECISION;
+        const matched = [];
+        for (const filter of active) {
+            // Lazy expiry (RFC 034 Decision 1.2): reading a Temporary filter past
+            // its expiresAt patches it to Expired on this read and drops it from
+            // evaluation, independent of whether the TTL delete has run.
+            const usable = await this.config.filterService.refreshExpiry(filter);
+            if (usable.state !== FilterState.Active)
+                continue;
+            if (!(await this.appliesTo(accountConfigId, accountId, usable)))
+                continue;
+            if (filterMatches(usable, msg))
+                matched.push(usable);
+        }
+        if (matched.length === 0)
+            return EMPTY_DECISION;
+        const labels = [];
+        const seenLabels = new Set();
+        for (const filter of matched) {
+            if (filter.actionLabelId === NO_ACTION)
+                continue;
+            if (seenLabels.has(filter.actionLabelId))
+                continue;
+            seenLabels.add(filter.actionLabelId);
+            labels.push({ labelId: filter.actionLabelId, filterId: filter.filterId });
+        }
+        const winner = selectMoveWinner(matched.filter((filter) => filter.actionMailboxId !== NO_ACTION));
+        return {
+            labels,
+            ...(winner
+                ? {
+                    move: {
+                        destinationMailboxId: winner.actionMailboxId,
+                        filterId: winner.filterId,
+                    },
+                }
+                : {}),
+        };
+    }
+}
+const filterMatches = (filter, msg) => literalClausesMatch(filter.literalClauses, filter.matchOperator, msg);

package/{src/flag-push-terminal.ts → dist/flag-push-terminal.d.ts}

@@ -1,32 +1,28 @@
 import type { IMessageRepository, MessageItem } from "@remit/data-ports";
 import type { FlagPushLogger } from "./flag-push.js";
-import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
 import type { IImapConnection } from "./types.js";
-
 export interface ResolveExhaustedFlagPushDeps {
-	messageService: Pick<IMessageRepository, "deleteIfPlacement">;
-	markerService: { delete(messageId: string, flagName: string): Promise<void> };
-	log: FlagPushLogger;
+    messageService: Pick<IMessageRepository, "deleteIfPlacement">;
+    markerService: {
+        delete(messageId: string, flagName: string): Promise<void>;
+    };
+    log: FlagPushLogger;
 }
-
 export interface ResolveExhaustedFlagPushInput {
-	/** Where the row stood when the caller read it; the delete holds only while it still does. */
-	placement: Pick<MessageItem, "status" | "mailboxId" | "uid">;
-	accountId: string;
-	accountConfigId: string;
-	messageId: string;
-	flagName: string;
-	uid: number;
-	mailboxPath: string;
-	getConnection: () => Promise<IImapConnection>;
+    /** Where the row stood when the caller read it; the delete holds only while it still does. */
+    placement: Pick<MessageItem, "status" | "mailboxId" | "uid">;
+    accountId: string;
+    accountConfigId: string;
+    messageId: string;
+    flagName: string;
+    uid: number;
+    mailboxPath: string;
+    getConnection: () => Promise<IImapConnection>;
 }
-
 export type FlagPushTerminalOutcome = "reconciled" | "broken";
-
 export interface ResolveExhaustedFlagPushResult {
-	outcome: FlagPushTerminalOutcome;
+    outcome: FlagPushTerminalOutcome;
 }
-
 /**
  * Resolve a FLAG_PUSH failure that has exhausted the delivering queue's
  * redelivery budget into exactly one of two terminal outcomes, mirroring
@@ -59,56 +55,4 @@ export interface ResolveExhaustedFlagPushResult {
  * mail, so the cost is paid deliberately: a stale alert is recoverable, a
  * deleted message is not.
  */
-export const resolveExhaustedFlagPushFailure = async (
-	deps: ResolveExhaustedFlagPushDeps,
-	input: ResolveExhaustedFlagPushInput,
-): Promise<ResolveExhaustedFlagPushResult> => {
-	const {
-		accountId,
-		accountConfigId,
-		messageId,
-		flagName,
-		uid,
-		mailboxPath,
-		getConnection,
-	} = input;
-
-	const connection = await getConnection();
-	await connection.openBox(mailboxPath, true);
-
-	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
-		await deps.markerService.delete(messageId, flagName);
-		const reconciled = await deps.messageService.deleteIfPlacement(
-			messageId,
-			input.placement,
-		);
-		deps.log.info(
-			{
-				metric: "flag_push_stale_row_reconciled",
-				accountId,
-				accountConfigId,
-				messageId,
-				flagName,
-				uid,
-				mailboxPath,
-				reconciled,
-			},
-			"Message no longer at its flag-push mailbox after retry exhaustion (external delete); marker dropped, stale row reconciled",
-		);
-		return { outcome: "reconciled" };
-	}
-
-	deps.log.error(
-		{
-			alert: "flag_push_failed",
-			accountId,
-			accountConfigId,
-			messageId,
-			flagName,
-			uid,
-			mailboxPath,
-		},
-		"Flag push could not be pushed to IMAP after retry exhaustion; message still exists — marker left pending for operator investigation",
-	);
-	return { outcome: "broken" };
-};
+export declare const resolveExhaustedFlagPushFailure: (deps: ResolveExhaustedFlagPushDeps, input: ResolveExhaustedFlagPushInput) => Promise<ResolveExhaustedFlagPushResult>;

package/dist/flag-push-terminal.js

@@ -0,0 +1,63 @@
+import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
+/**
+ * Resolve a FLAG_PUSH failure that has exhausted the delivering queue's
+ * redelivery budget into exactly one of two terminal outcomes, mirroring
+ * `resolveExhaustedPlacementMoveFailure` (#1289) and
+ * `resolveExhaustedBodySyncFailures` (#1270) for the same failure taxonomy
+ * (epic #1281 invariant 3) — no third, softer outcome.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at its mailbox on
+ *    IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather than by a
+ *    FETCH coming back empty. Per invariant 2, an external delete supersedes
+ *    the marker entirely: the marker is dropped and the stale
+ *    Message/ThreadMessage rows are deleted via `deleteIfPlacement`.
+ *    Metric only, no alarm — routine.
+ * 2. BROKEN — the message still exists, but the flag push keeps failing.
+ *    Broken code or a broken account, not a transient blip. The marker is
+ *    left in place (not cleared) — while pending, resync never reverts the
+ *    local flag (invariant 3 of this issue's own spec), so leaving it does
+ *    not risk correctness, and dropping it here would discard the only
+ *    record that IMAP still owes this push. Logged with an `alert`-shaped
+ *    entry for an operator alarm; never re-thrown (terminal — the caller acks
+ *    either way, since retrying a stale or permanently-broken push can never
+ *    succeed).
+ *
+ * An operator reading `flag_push_failed` should know one case where the
+ * message is not actually there: a message another client expunged
+ * mid-session can answer an empty FETCH while the server still lists its UID
+ * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
+ * lands in BROKEN, and BROKEN is terminal — the marker stays pending and the
+ * alert stands until someone clears it. The reverse mistake deletes live
+ * mail, so the cost is paid deliberately: a stale alert is recoverable, a
+ * deleted message is not.
+ */
+export const resolveExhaustedFlagPushFailure = async (deps, input) => {
+    const { accountId, accountConfigId, messageId, flagName, uid, mailboxPath, getConnection, } = input;
+    const connection = await getConnection();
+    await connection.openBox(mailboxPath, true);
+    if (await isMessageGoneFromOpenMailbox(connection, uid)) {
+        await deps.markerService.delete(messageId, flagName);
+        const reconciled = await deps.messageService.deleteIfPlacement(messageId, input.placement);
+        deps.log.info({
+            metric: "flag_push_stale_row_reconciled",
+            accountId,
+            accountConfigId,
+            messageId,
+            flagName,
+            uid,
+            mailboxPath,
+            reconciled,
+        }, "Message no longer at its flag-push mailbox after retry exhaustion (external delete); marker dropped, stale row reconciled");
+        return { outcome: "reconciled" };
+    }
+    deps.log.error({
+        alert: "flag_push_failed",
+        accountId,
+        accountConfigId,
+        messageId,
+        flagName,
+        uid,
+        mailboxPath,
+    }, "Flag push could not be pushed to IMAP after retry exhaustion; message still exists — marker left pending for operator investigation");
+    return { outcome: "broken" };
+};