@dxos/pipeline-email 0.0.0 → 0.11.0

package/src/model-policy.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Declarative model routing for the email pipeline stages (productized from the stories-brain research
+// harness): one place that maps each LLM-bearing stage to the model it runs on, instead of hard-coding
+// a model DXN at every call site. Product tiers only (Anthropic); the research ladder's open-weight
+// (ollama) variants stay in the harness. Each layer overrides the previous: default ← per-run policy.
+
+/** Anthropic model DXNs available to product pipelines. */
+export const MODEL_HAIKU = 'com.anthropic.model.claude-haiku-4-5.default';
+export const MODEL_SONNET = 'com.anthropic.model.claude-sonnet-4-6.default';
+export const MODEL_OPUS = 'com.anthropic.model.claude-opus-4-8.default';
+
+/** The LLM-bearing email pipeline stages. Deterministic stages (threading, dedup, stats) never appear. */
+export type StageId =
+  | 'classify-sender'
+  | 'tag'
+  | 'summarize-message'
+  | 'summarize-thread'
+  | 'summarize-topic'
+  | 'extract-facts'
+  | 'draft';
+
+/** A partial policy: stage → a model DXN. */
+export type ModelPolicy = Partial<Record<StageId, string>>;
+
+/**
+ * Default stage → model routing, seeded from the model-ladder findings (REPORT §4/§5): labeling and
+ * summaries want a premier model, drafting tolerates a cheaper one. Product defaults to haiku across
+ * the board (the cheapest premier tier); callers override per run via a `ModelPolicy`.
+ */
+export const DEFAULT_MODEL_POLICY: Record<StageId, string> = {
+  'classify-sender': MODEL_HAIKU,
+  'tag': MODEL_HAIKU,
+  'summarize-message': MODEL_HAIKU,
+  'summarize-thread': MODEL_HAIKU,
+  'summarize-topic': MODEL_HAIKU,
+  'extract-facts': MODEL_HAIKU,
+  'draft': MODEL_HAIKU,
+};
+
+/** Resolves the model DXN for a stage: per-run `policy` wins over `DEFAULT_MODEL_POLICY`. */
+export const resolveModel = (stage: StageId, policy?: ModelPolicy): string =>
+  policy?.[stage] ?? DEFAULT_MODEL_POLICY[stage];

package/src/stages/EmailStage.ts

@@ -0,0 +1,398 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { Blob, Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { type IdentityIndex, overlayIdentityIndex } from '@dxos/extractor';
+import { buildContactFromActor, getIdentityIndex, identitySpecs } from '@dxos/extractor-lib';
+import { Cursor } from '@dxos/link';
+import { log } from '@dxos/log';
+import { normalizeText } from '@dxos/markdown';
+import { Stage } from '@dxos/pipeline';
+import { Tagging, TagIndex } from '@dxos/schema';
+import { DraftMessage, Message, Person } from '@dxos/types';
+
+// TODO(burdon): Factor out.
+
+/**
+ * Reusable, generic email-processing pipeline stages: {@link Change} → {@link Change}, composing in any
+ * order, each simply recording what it found (`message.attachments`, `contact`, …) rather than writing
+ * directly. {@link toCommitUnit} is the terminal stage that turns those into a generic
+ * `Cursor.CommitUnit`, and must run last. Provider-specific decode/map stages construct the initial
+ * `Change` (an `Insert`, tagged from the start) and stay in each sync op.
+ */
+
+/** An item carrying a body string that may contain HTML. */
+export type Bodied = { readonly body: string };
+
+/**
+ * Normalizes an item's `body` from (possibly) HTML into markdown via `normalizeText` (turndown when
+ * HTML, passthrough for plaintext). Requires nothing from the Requirements channel. Written as a
+ * generic pipeable so the item type infers from the upstream stream (no type argument needed).
+ */
+export const htmlToMarkdown = <In extends Bodied, E, R>(self: Stream.Stream<In, E, R>): Stream.Stream<In, E, R> =>
+  Stage.map('html-to-markdown', (item: In) => Effect.sync(() => ({ ...item, body: normalizeText(item.body) })))(self);
+
+/**
+ * A new message to append, tagged `insert` from the moment a provider decodes it. The upstream dedup
+ * stage (`Cursor.dedupStage`) guarantees a message reaching this variant was never previously committed,
+ * so it's a one-time insert, never a resync/overwrite. The generic email stages act only on this variant
+ * of {@link Change}.
+ */
+export type Insert = {
+  readonly _tag: 'insert';
+  readonly message: Message.Message;
+  readonly foreignId: string;
+  readonly key: number;
+  /** Provider label/folder tag URIs to apply on commit; omit for providers/stages that don't tag. */
+  readonly tagUris?: readonly string[];
+  /** Attachments fetched by a provider-specific stage upstream of {@link processAttachments}. */
+  readonly attachments?: readonly Attachment[];
+  /** Contact resolved by {@link extractContacts}, added to the database by {@link toCommitUnit}. */
+  readonly contact?: Person.Person;
+  /** Local drafts this synced message supersedes ({@link reconcileDrafts}), removed by {@link toCommitUnit}. */
+  readonly supersededDrafts?: readonly Message.Message[];
+};
+
+/**
+ * A label change on an already-committed message, resolved to its feed message's `entityId`.
+ * {@link toCommitUnit} turns it into an objectless commit unit that applies the tag adds/removes — no
+ * feed append, so the body stages ({@link processAttachments}, {@link extractContacts},
+ * {@link reconcileDrafts}) pass it through untouched.
+ */
+export type Retag = {
+  readonly _tag: 'retag';
+  readonly foreignId: string;
+  readonly entityId: Obj.ID;
+  readonly addTagIds: readonly string[];
+  readonly removeTagIds: readonly string[];
+};
+
+/**
+ * A remote deletion of an already-committed message. Wired but STUBBED — {@link toCommitUnit} emits an
+ * objectless unit with no effect (see the TODO there) pending safe in-sync feed object deletion.
+ */
+export type Delete = {
+  readonly _tag: 'delete';
+  readonly foreignId: string;
+  readonly entityId: Obj.ID;
+};
+
+/**
+ * The discriminated item flowing through the shared email tail. `insert` is a new message; `retag`/
+ * `delete` act on existing feed messages by `entityId`. All converge on the single {@link toCommitUnit}
+ * → `Cursor.commit`.
+ */
+export type Change = Insert | Retag | Delete;
+
+/** A decoded email attachment, ready for {@link processAttachments} to turn into a Blob. */
+export type Attachment = {
+  readonly name?: string;
+  readonly mimeType?: string;
+  readonly size: number;
+  readonly bytes: Uint8Array;
+  /** The attachment's `Content-ID`, if any — matches a `cid:` reference in the message's HTML body. */
+  readonly contentId?: string;
+};
+
+/**
+ * Builds a Person (+ Organization link by domain) from the message sender and records it on the
+ * item as {@link Insert.contact} — the stage writes nothing itself; {@link toCommitUnit} defers
+ * the actual `db.add` to commit.
+ *
+ * Dedup is the space's shared identity index (see `getIdentityIndex`), refreshed once at the start
+ * of the run: it covers contacts committed before the run, contacts built earlier in it, and — since
+ * the index is shared per database — contacts a concurrently-syncing mailbox is building right now.
+ *
+ * Not every sender earns a record: {@link senderSignals} feeds the allow-list in
+ * `shouldExtractContact`, so bulk and automated mail no longer fills the space with contacts nobody
+ * will look at. NOTE: no provider records an outbound signal yet, so in practice the allow-list is
+ * "the domain matches a known Organization" — stricter than the policy intends. Extracting the
+ * recipients of sent mail is what closes that gap.
+ */
+export const extractContacts = (): Stage.Stage<Change, Change, never, Database.Service> => {
+  // Run-scoped overlay over the space's shared index: reads see everything committed (including by a
+  // concurrent sync), writes stay local, so a run that dies mid-way leaves nothing claiming a contact
+  // it never committed.
+  let index: IdentityIndex | undefined;
+  return Stage.map('extract-contacts', (change: Change) =>
+    Effect.gen(function* () {
+      // Only new messages carry a body/sender; retag/delete pass through untouched.
+      if (change._tag !== 'insert') {
+        return change;
+      }
+      const { db } = yield* Database.Service;
+      if (!index) {
+        // Re-seed once per run so the shared index picks up whatever was committed since it was built.
+        index = overlayIdentityIndex(identitySpecs, yield* getIdentityIndex(db, { refresh: true }));
+      }
+      const sender = change.message.sender;
+      const contact = sender
+        ? yield* buildContactFromActor(sender, db, { signals: senderSignals(change.message), index })
+        : undefined;
+      return contact ? { ...change, contact } : change;
+    }),
+  );
+};
+
+/**
+ * The sender signals the shared extraction gate reads, taken from the fields provider mappers
+ * already record on `properties`. `Precedence`/`Auto-Submitted` are folded into `bulk` by the mapper
+ * where available.
+ */
+const senderSignals = (message: Message.Message) => {
+  const properties = message.properties ?? {};
+  return {
+    noReply: properties.noReply === true,
+    listUnsubscribe: typeof properties.listUnsubscribe === 'string' ? properties.listUnsubscribe : undefined,
+    bulk: properties.bulk === true,
+  };
+};
+
+/**
+ * Turns each of the item's `attachments` into a Blob object (via the database's configured storage
+ * backend — edge in Composer) and adds a {@link Message.Attachment} pointing at it to the message.
+ * {@link toCommitUnit} finds these blobs again via each attachment's ref (inlined, since the
+ * blob isn't attached to a database yet) to defer their feed append to commit. A no-op when the item
+ * has no attachments.
+ *
+ * One bad or oversized attachment must not fail the whole message: each `Blob.fromBytes` is caught
+ * and logged individually, so a rejected attachment is simply dropped from the message.
+ */
+export const processAttachments = (): Stage.Stage<Change, Change, never, Database.Service> =>
+  Stage.map('process-attachments', (change: Change) =>
+    Effect.gen(function* () {
+      // Only new messages carry attachments; retag/delete pass through untouched.
+      if (change._tag !== 'insert') {
+        return change;
+      }
+      const mapped = change;
+      if (!mapped.attachments?.length) {
+        return mapped;
+      }
+
+      const attachments: Message.Attachment[] = [];
+      for (const attachment of mapped.attachments) {
+        const blob: Blob.Blob | undefined = yield* Blob.fromBytes(attachment.bytes, {
+          type: attachment.mimeType,
+        }).pipe(
+          Effect.catchAll((error) => {
+            log.catch(error, { foreignId: mapped.foreignId, name: attachment.name, size: attachment.size });
+            return Effect.succeed(undefined);
+          }),
+        );
+        if (!blob) {
+          continue;
+        }
+        attachments.push({ name: attachment.name, ref: Ref.make(blob), contentId: attachment.contentId });
+      }
+      if (attachments.length === 0) {
+        return mapped;
+      }
+
+      // The message is not yet appended to the feed, so mutating it here is safe — mirrors how the
+      // mappers assemble `blocks` before the message is ever persisted.
+      Obj.update(mapped.message, (message) => {
+        message.attachments = [...(message.attachments ?? []), ...attachments];
+      });
+
+      return mapped;
+    }),
+  );
+
+/**
+ * Queries the parent container's already-sent drafts once per sync run and pools them by the provider
+ * message id captured at send time (`properties.sentMessageId`) — the key {@link reconcileDrafts}
+ * matches each incoming message's `foreignId` against. Doing this once (rather than per item) keeps
+ * reconciliation off the database as messages stream through. Unsent drafts (no `sentMessageId`) are
+ * never pooled and thus never eligible for removal.
+ *
+ * `parent` is the local root object drafts are scoped to (e.g. a Mailbox) — only its URI is read, so
+ * any object works.
+ */
+export const queryDraftPool = Effect.fn('queryDraftPool')(function* (parent: Obj.Unknown) {
+  const parentUri = Obj.getURI(parent);
+  const drafts = (yield* Database.query(Filter.type(Message.Message, { properties: { mailbox: parentUri } }))
+    .run).filter((candidate) => DraftMessage.belongsTo(candidate, parentUri) && candidate.properties?.sentMessageId);
+
+  const pool = new Map<string, Message.Message[]>();
+  for (const draft of drafts) {
+    const sentMessageId = draft.properties?.sentMessageId;
+    if (!sentMessageId) {
+      continue;
+    }
+    const existing = pool.get(sentMessageId);
+    if (existing) {
+      existing.push(draft);
+    } else {
+      pool.set(sentMessageId, [draft]);
+    }
+  }
+  return pool;
+});
+
+/**
+ * Records the local drafts each incoming message supersedes — matched by the provider message id the
+ * draft captured at send time (`properties.sentMessageId`), which equals the synced message's
+ * `foreignId` — from a pool built once per run and keyed by that id. Writes nothing itself;
+ * {@link toCommitUnit} defers the `db.remove` to commit, so the canonical message is appended
+ * to the feed before its now-redundant drafts are deleted. A stage factory: pass the run's draft
+ * pool once.
+ *
+ * The pool is queried a single time by the caller (per sync operation), so this stage never touches
+ * the database or feed per item.
+ */
+export const reconcileDrafts = (
+  draftPool: ReadonlyMap<string, readonly Message.Message[]>,
+): Stage.Stage<Change, Change, never, never> =>
+  Stage.map('reconcile-drafts', (change: Change) =>
+    Effect.sync(() => {
+      // Only new messages can supersede a draft; retag/delete pass through untouched.
+      if (change._tag !== 'insert') {
+        return change;
+      }
+      const drafts = draftPool.get(change.foreignId);
+      return drafts?.length ? { ...change, supersededDrafts: drafts } : change;
+    }),
+  );
+
+/**
+ * Terminal stage converting a run's {@link Change} into the generic `Cursor.CommitUnit` the commit sink
+ * consumes. For an `insert`: `message.attachments` (populated by {@link processAttachments}) becomes a
+ * feed-append commit effect for the referenced blobs, `mapped.contact` (from {@link extractContacts})
+ * becomes a `db.add` commit effect, and `mapped.supersededDrafts` (from {@link reconcileDrafts})
+ * becomes a `db.remove` commit effect. Every other email stage is Change → Change and composes in
+ * any order; this is the one stage that must run last.
+ *
+ * Tagging is email-specific (`Cursor.CommitUnit` carries no tag data), so it's applied here rather
+ * than by the generic commit sink: `tagIndex` is optional (omit for providers/tests that don't tag),
+ * and every tagged unit attaches the *same* `applyTags` closure (keyed by `mapped.tagUris` recorded in
+ * a run-scoped map, read back by object identity) so the commit's identity-based batching applies
+ * every tag pair for the page in one `Tagging.setBatch` call rather than one per message.
+ */
+export const toCommitUnit = (
+  options: { readonly tagIndex?: TagIndex.TagIndex } = {},
+): Stage.Stage<Change, Cursor.CommitUnit, never, Cursor.Service> => {
+  const { tagIndex } = options;
+  const tagUrisByObject = new WeakMap<Obj.Any, readonly string[]>();
+  const applyTags: Cursor.CommitEffect = Effect.fn('email.commit.tags')(function* (
+    units: readonly Cursor.CommitUnit[],
+  ) {
+    if (!tagIndex) {
+      return;
+    }
+    const tagEntries: { object: Obj.Any; tagId: string }[] = [];
+    for (const unit of units) {
+      if (!unit.object) {
+        continue;
+      }
+      for (const uri of tagUrisByObject.get(unit.object) ?? []) {
+        tagEntries.push({ object: unit.object, tagId: uri });
+      }
+    }
+    if (tagEntries.length > 0) {
+      Tagging.setBatch(tagEntries, { index: tagIndex });
+    }
+  });
+
+  // Retag adds/removes recorded per foreign id, applied in one shared effect (identity-batched by the
+  // commit) so a page of label changes resolves to a single pass over the tag index.
+  const retagByForeignId = new Map<string, Pick<Retag, 'entityId' | 'addTagIds' | 'removeTagIds'>>();
+  const applyRetags: Cursor.CommitEffect = Effect.fn('email.commit.retags')(function* (
+    units: readonly Cursor.CommitUnit[],
+  ) {
+    if (!tagIndex) {
+      return;
+    }
+    const accessor = TagIndex.bind(tagIndex);
+    for (const unit of units) {
+      const retag = retagByForeignId.get(unit.foreignId);
+      if (!retag) {
+        continue;
+      }
+      for (const tagId of retag.addTagIds) {
+        accessor.setTag(tagId, retag.entityId);
+      }
+      for (const tagId of retag.removeTagIds) {
+        accessor.unsetTag(tagId, retag.entityId);
+      }
+    }
+  });
+
+  return Stage.map('to-commit-unit', (change: Change) =>
+    Effect.gen(function* () {
+      // Label change on an existing message: an objectless unit (no feed append, key 0) whose effect
+      // retags by entityId.
+      if (change._tag === 'retag') {
+        retagByForeignId.set(change.foreignId, {
+          entityId: change.entityId,
+          addTagIds: change.addTagIds,
+          removeTagIds: change.removeTagIds,
+        });
+        return {
+          foreignId: change.foreignId,
+          key: 0,
+          commitEffects: tagIndex ? [applyRetags] : undefined,
+        } satisfies Cursor.CommitUnit;
+      }
+
+      // Remote deletion: wired but STUBBED — the branch resolves an objectless unit that does nothing.
+      // TODO(wittjosiah): Remove the message from the feed once in-sync feed object deletion is safe
+      //   (cursor/dedup-set interaction across the non-transactional queue↔space-db seam).
+      if (change._tag === 'delete') {
+        return { foreignId: change.foreignId, key: 0 } satisfies Cursor.CommitUnit;
+      }
+
+      const mapped = change;
+      const { feed } = yield* Cursor.Service;
+      const commitEffects: Cursor.CommitEffect[] = [];
+
+      // Each attachment's ref is inlined (its blob isn't attached to a database yet), so `.target`
+      // resolves it synchronously without an Insert.attachmentBlobs field to carry it separately.
+      const blobs = (mapped.message.attachments ?? [])
+        .map((attachment) => attachment.ref.target)
+        .filter((target): target is Blob.Blob => Obj.instanceOf(Blob.Blob, target));
+      if (feed && blobs.length > 0) {
+        commitEffects.push(() => Feed.append(feed, blobs));
+      }
+
+      if (mapped.contact) {
+        const contact = mapped.contact;
+        commitEffects.push(
+          Effect.fn('email.commit.addContact')(function* () {
+            yield* Database.add(contact);
+          }),
+        );
+      }
+
+      if (mapped.supersededDrafts?.length) {
+        const drafts = mapped.supersededDrafts;
+        commitEffects.push(
+          Effect.fn('email.commit.removeDrafts')(function* () {
+            const { db } = yield* Database.Service;
+            for (const draft of drafts) {
+              db.remove(draft);
+            }
+          }),
+        );
+      }
+
+      if (tagIndex && mapped.tagUris?.length) {
+        tagUrisByObject.set(mapped.message, mapped.tagUris);
+        commitEffects.push(applyTags);
+      }
+
+      return {
+        object: mapped.message,
+        foreignId: mapped.foreignId,
+        key: mapped.key,
+        commitEffects: commitEffects.length > 0 ? commitEffects : undefined,
+      };
+    }),
+  );
+};

package/src/stages/extract-facts-commit.ts

@@ -29,13 +29,22 @@ export type FactUnit = {
 // instead of persisting them in-stage, so the sink can write a page atomically with the cursor
 // advance. Extraction degrades to no facts on failure (advisory layer) but logs first, matching
 // `extractFactsStage`'s degradation, so the loss stays observable.
-export const extractFactsUnitStage = (extract: FactExtractor): Stage.Stage<Message.Message, FactUnit> =>
-  Stage.map('extract-facts-unit', (message) =>
-    Effect.tryPromise(() => extract(message)).pipe(
-      Effect.tapError((error) => Effect.logWarning('extract-facts-unit failed; degrading to no facts', error)),
-      Effect.orElse(() => Effect.succeed<RDF.Fact[]>([])),
-      Effect.map((facts): FactUnit => ({ facts, foreignId: messageSource(message), key: keyOf(message) })),
-    ),
+// `concurrency` bounds in-flight extractions; >1 runs the (independent, network-bound) per-message
+// LLM calls in parallel. Facts are order-independent — the sink commits by max cursor key — so the
+// reordering `mapEffect` may introduce is harmless here.
+export const extractFactsUnitStage = (
+  extract: FactExtractor,
+  concurrency = 1,
+): Stage.Stage<Message.Message, FactUnit> =>
+  Stage.map(
+    'extract-facts-unit',
+    (message) =>
+      Effect.tryPromise(() => extract(message)).pipe(
+        Effect.tapError((error) => Effect.logWarning('extract-facts-unit failed; degrading to no facts', error)),
+        Effect.orElse(() => Effect.succeed<RDF.Fact[]>([])),
+        Effect.map((facts): FactUnit => ({ facts, foreignId: messageSource(message), key: keyOf(message) })),
+      ),
+    { concurrency },
   );
 
 // NOTE(workaround): `message.created` is the incremental cursor key because ECHO's native feed

package/src/stages/index.ts

@@ -9,3 +9,6 @@ export * from './extract-facts-commit';
 export * from './facts';
 export * from './stats';
 export * from './summarize';
+export * from './tag';
+
+export * as EmailStage from './EmailStage';

package/src/stages/tag.test.ts

@@ -0,0 +1,98 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { applyBulkTag, classifyBulk, parseTagResult } from './tag';
+
+describe('parseTagResult', () => {
+  test('parses tags (lowercased) and spam flag', ({ expect }) => {
+    const result = parseTagResult('{"tags":["Invoice","Finance"],"spam":false}');
+    expect(result.tags).toEqual(['invoice', 'finance']);
+    expect(result.spam).toBe(false);
+    expect(result.bulk).toBe(false);
+  });
+
+  test('flags bulk when the model emits the tag', ({ expect }) => {
+    const result = parseTagResult('{"tags":["receipt","bulk"],"spam":false}');
+    expect(result.bulk).toBe(true);
+  });
+
+  test('extracts JSON wrapped in prose', ({ expect }) => {
+    const result = parseTagResult('Here you go:\n{"tags":["personal"],"spam":false}\nHope that helps.');
+    expect(result.tags).toEqual(['personal']);
+  });
+
+  test('infers spam from a spam tag and dedups it', ({ expect }) => {
+    const result = parseTagResult('{"tags":["spam","marketing"]}');
+    expect(result.spam).toBe(true);
+    expect(result.tags.filter((tag) => tag === 'spam')).toHaveLength(1);
+  });
+
+  test('adds the spam tag when the flag is set but the tag is missing', ({ expect }) => {
+    const result = parseTagResult('{"tags":["promo"],"spam":true}');
+    expect(result.spam).toBe(true);
+    expect(result.tags).toContain('spam');
+  });
+
+  test('degrades to empty on unparseable output', ({ expect }) => {
+    const result = parseTagResult('no json here');
+    expect(result.tags).toEqual([]);
+    expect(result.spam).toBe(false);
+    expect(result.bulk).toBe(false);
+  });
+});
+
+describe('classifyBulk', () => {
+  test('receipts and login/security notices are bulk', ({ expect }) => {
+    expect(classifyBulk({ subject: 'Receipt from Anthropic PBC' })).toBe('bulk');
+    expect(classifyBulk({ subject: 'Your receipt from HeyGen Inc' })).toBe('bulk');
+    expect(classifyBulk({ subject: 'Linear login' })).toBe('bulk');
+    expect(classifyBulk({ subject: 'New sign-in to your account' })).toBe('bulk');
+    expect(classifyBulk({ subject: 'Your order has shipped' })).toBe('bulk');
+  });
+
+  test('invoices and payment requests are action-required, never bulk', ({ expect }) => {
+    expect(classifyBulk({ subject: 'Invoice #4021 — payment due' })).toBe('action');
+    expect(classifyBulk({ subject: 'Payment reminder', senderEmail: 'billing@acme.com' })).toBe('action');
+    expect(classifyBulk({ subject: 'Your invoice receipt' })).toBe('action');
+  });
+
+  test('a person with no automated signal is unknown (left to the model / person gate)', ({ expect }) => {
+    expect(classifyBulk({ subject: 'Barbera Corporate — Dmytro', senderEmail: 'dmytro@barbera.com' })).toBe('unknown');
+  });
+
+  test('a no-reply / notifications local part is bulk when the subject is silent', ({ expect }) => {
+    expect(classifyBulk({ subject: 'Update', senderEmail: 'no-reply@service.io' })).toBe('bulk');
+    expect(classifyBulk({ subject: 'Update', senderEmail: 'notifications@service.io' })).toBe('bulk');
+  });
+
+  test('an unsubscribe affordance (header or body link) deterministically marks bulk', ({ expect }) => {
+    // List-Unsubscribe header (real synced mail).
+    expect(classifyBulk({ subject: 'Interview with Eric Ries', listUnsubscribe: '<https://x.io/unsub>' })).toBe('bulk');
+    // Unsubscribe link in the body (e.g. the fixture, no header).
+    expect(classifyBulk({ subject: 'Interview with Eric Ries', bodyText: 'Great read.\n\nUnsubscribe here.' })).toBe(
+      'bulk',
+    );
+    // Outranks an action-looking subject — transactional invoices don't carry an unsubscribe link.
+    expect(classifyBulk({ subject: 'Invoice #12 payment due', bodyText: 'Click to unsubscribe.' })).toBe('bulk');
+    // No unsubscribe → the normal person path.
+    expect(classifyBulk({ subject: 'Interview with Eric Ries', bodyText: 'Looking forward to it.' })).toBe('unknown');
+  });
+});
+
+describe('applyBulkTag', () => {
+  test('adds bulk for no-action mail (deduped)', ({ expect }) => {
+    expect(applyBulkTag(['receipt'], 'bulk')).toEqual(['receipt', 'bulk']);
+    expect(applyBulkTag(['receipt', 'bulk'], 'bulk')).toEqual(['receipt', 'bulk']);
+  });
+
+  test('strips bulk the model wrongly added to action-required mail', ({ expect }) => {
+    expect(applyBulkTag(['invoice', 'bulk'], 'action')).toEqual(['invoice']);
+  });
+
+  test('leaves tags untouched when unknown', ({ expect }) => {
+    expect(applyBulkTag(['personal'], 'unknown')).toEqual(['personal']);
+  });
+});