@dxos/pipeline-email 0.0.0

package/src/corpus/topics.ts

@@ -0,0 +1,211 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Obj } from '@dxos/echo';
+
+import { type Thread, Topic } from '../types';
+import { DEFAULT_EMAIL_PROMPTS, type EmailPrompts, type Summarizer, mergePrompts } from './prompts';
+
+// Subject tokens that carry no topical signal; excluded from signatures and keywords.
+const DEFAULT_STOPWORDS: readonly string[] = [
+  'the',
+  'and',
+  'for',
+  'with',
+  'from',
+  'about',
+  'this',
+  'that',
+  'your',
+  'our',
+  'are',
+  'was',
+  'will',
+  'has',
+  'have',
+  'not',
+  'you',
+  'all',
+  'any',
+  'can',
+  'per',
+  'new',
+];
+
+/**
+ * Tunable knobs for the deterministic shared-signal clustering (spec §10.3: agglomeration over
+ * participant/keyword overlap; embedding/LLM grouping deferred). All values have defaults so
+ * callers can adjust the algorithm without forking it.
+ */
+export type TopicOptions = {
+  /** Minimum Jaccard similarity between subject-token signatures that joins a topic. */
+  readonly similarityThreshold?: number;
+  /** Shared-participant count that joins a topic regardless of token overlap. */
+  readonly minSharedParticipants?: number;
+  /** Subject tokens shorter than this are ignored. */
+  readonly minTokenLength?: number;
+  /** Tokens excluded from signatures and keywords. */
+  readonly stopwords?: readonly string[];
+  /** Keywords retained per topic (most frequent first). */
+  readonly maxKeywords?: number;
+};
+
+export const DEFAULT_TOPIC_OPTIONS: Required<TopicOptions> = {
+  similarityThreshold: 0.25,
+  minSharedParticipants: 2,
+  minTokenLength: 3,
+  stopwords: DEFAULT_STOPWORDS,
+  maxKeywords: 5,
+};
+
+/** A topic before ECHO materialization: plain values so LLM enrichment can rewrite them freely. */
+export type TopicDraft = {
+  readonly label: string;
+  readonly summary: string;
+  readonly threadIds: readonly string[];
+  readonly participants: readonly string[];
+  readonly keywords: readonly string[];
+};
+
+type Signature = {
+  readonly thread: Thread;
+  readonly tokens: Set<string>;
+  readonly participants: Set<string>;
+};
+
+const tokenize = (subject: string, options: Required<TopicOptions>): Set<string> =>
+  new Set(
+    subject
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((token) => token.length >= options.minTokenLength && !options.stopwords.includes(token)),
+  );
+
+const jaccard = (left: Set<string>, right: Set<string>): number => {
+  if (left.size === 0 || right.size === 0) {
+    return 0;
+  }
+  let shared = 0;
+  for (const token of left) {
+    if (right.has(token)) {
+      shared += 1;
+    }
+  }
+  return shared / (left.size + right.size - shared);
+};
+
+const sharedCount = (left: Set<string>, right: Set<string>): number => {
+  let shared = 0;
+  for (const value of left) {
+    if (right.has(value)) {
+      shared += 1;
+    }
+  }
+  return shared;
+};
+
+/**
+ * Greedy agglomerative clustering of threads into topic drafts. Deterministic (Compute mode): a
+ * thread joins the first cluster whose aggregate signature overlaps enough — by subject-token
+ * Jaccard similarity or by shared participants — else starts its own. Bounded by O(threads ×
+ * clusters); no LLM involved, so results are stable and unit-testable.
+ */
+export const clusterThreads = (threads: readonly Thread[], options?: TopicOptions): TopicDraft[] => {
+  const opts = { ...DEFAULT_TOPIC_OPTIONS, ...options };
+  const clusters: { members: Signature[]; tokens: Set<string>; participants: Set<string> }[] = [];
+
+  for (const thread of threads) {
+    const signature: Signature = {
+      thread,
+      tokens: tokenize(thread.subject, opts),
+      participants: new Set(thread.participants),
+    };
+    const home = clusters.find(
+      (cluster) =>
+        jaccard(cluster.tokens, signature.tokens) >= opts.similarityThreshold ||
+        sharedCount(cluster.participants, signature.participants) >= opts.minSharedParticipants,
+    );
+    if (home) {
+      home.members.push(signature);
+      for (const token of signature.tokens) {
+        home.tokens.add(token);
+      }
+      for (const participant of signature.participants) {
+        home.participants.add(participant);
+      }
+    } else {
+      clusters.push({
+        members: [signature],
+        tokens: new Set(signature.tokens),
+        participants: new Set(signature.participants),
+      });
+    }
+  }
+
+  return clusters.map((cluster) => {
+    // Rank keywords by how many member threads mention them, then alphabetically for determinism.
+    const counts = new Map<string, number>();
+    for (const member of cluster.members) {
+      for (const token of member.tokens) {
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+      }
+    }
+    const keywords = [...counts.entries()]
+      .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+      .slice(0, opts.maxKeywords)
+      .map(([token]) => token);
+
+    const summaries = cluster.members.flatMap((member) =>
+      member.thread.summary.length > 0 ? [member.thread.summary] : [],
+    );
+
+    // Label from top keywords; a keyword-less cluster (e.g. blank subjects) falls back through the
+    // first thread's subject to its threadId so the label is never empty.
+    const first = cluster.members[0].thread;
+    return {
+      label: keywords.length > 0 ? keywords.slice(0, 3).join(' ') : first.subject || first.threadId,
+      summary: summaries.join('\n'),
+      threadIds: cluster.members.map((member) => member.thread.threadId),
+      participants: [...cluster.participants].sort(),
+      keywords,
+    };
+  });
+};
+
+/**
+ * Optionally replace each draft's deterministic summary with an LLM one, using the editable
+ * `topicSummary` prompt. Degrades per-topic: a failed call keeps that draft's deterministic summary
+ * (advisory enrichment must not fail the corpus pass).
+ */
+export const summarizeTopics = async (
+  drafts: readonly TopicDraft[],
+  summarize: Summarizer,
+  options?: { readonly prompts?: Partial<EmailPrompts> },
+): Promise<TopicDraft[]> => {
+  const prompts = options?.prompts ? mergePrompts(options.prompts) : DEFAULT_EMAIL_PROMPTS;
+  return Promise.all(
+    drafts.map(async (draft) => {
+      try {
+        const summary = await summarize(
+          [prompts.topicSummary, `Topic: ${draft.label}`, `Threads:\n${draft.summary}`].join('\n\n'),
+        );
+        return summary.trim().length > 0 ? { ...draft, summary: summary.trim() } : draft;
+      } catch {
+        return draft;
+      }
+    }),
+  );
+};
+
+/** Materialize drafts as canonical Topic ECHO objects (done last; drafts stay freely mutable). */
+export const materializeTopics = (drafts: readonly TopicDraft[]): Topic[] =>
+  drafts.map((draft) =>
+    Obj.make(Topic, {
+      label: draft.label,
+      summary: draft.summary,
+      threadIds: [...draft.threadIds],
+      participants: [...draft.participants],
+      keywords: [...draft.keywords],
+    }),
+  );

package/src/fact-pipeline.test.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { EffectEx } from '@dxos/effect';
+import { Message, Organization, Person } from '@dxos/types';
+
+import { EmailFactPipeline } from './fact-pipeline';
+import { type FactIndexer } from './stages';
+import { Thread } from './types';
+
+describe('email fact pipeline (facts-only assembly)', () => {
+  let builder: EchoTestBuilder;
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  test('EmailFactPipeline.run: stats → extract-facts', async ({ expect }) => {
+    const { db } = await builder.createDatabase({
+      types: [Person.Person, Organization.Organization, Thread],
+    });
+
+    const messages = [
+      makeMessage('<m-1@enron.com>', 'alice@enron.com', 'Q2 report', 'I will send the Q2 report by Friday.'),
+      makeMessage('<m-2@enron.com>', 'bob@enron.com', 'Q2 report', 'Thanks, looking forward to it.'),
+    ];
+
+    const indexed: Message.Message[] = [];
+    const indexFacts: FactIndexer = async (message) => {
+      indexed.push(message);
+      return [];
+    };
+
+    const result = await EffectEx.runPromise(EmailFactPipeline.run(messages, { db, indexFacts }));
+
+    // All messages flowed through the stream and were collected in order.
+    expect(result.messages).toHaveLength(2);
+    // stats tallied each message that flowed through.
+    expect(result.stats.total).toBe(2);
+    expect(result.stats.from.get('alice@enron.com')).toBe(1);
+    expect(result.stats.from.get('bob@enron.com')).toBe(1);
+    // extract-facts invoked the indexer once per message.
+    expect(indexed).toHaveLength(2);
+    expect(indexed.map((message) => message.properties?.messageId)).toEqual(['<m-1@enron.com>', '<m-2@enron.com>']);
+    // Facts-only assembly omits summarize/extract-contacts/threads: `result` has no such keys
+    // (enforced at compile time by `EmailFactPipelineResult`, which declares only `messages`/`stats`).
+    expect(Object.keys(result).sort()).toEqual(['messages', 'stats']);
+  });
+});
+
+const makeMessage = (messageId: string, email: string, subject: string, text: string): Message.Message =>
+  Message.make({
+    created: '2001-05-14T10:00:00.000Z',
+    sender: { email },
+    blocks: [{ _tag: 'text', text }],
+    properties: { messageId, subject },
+  });

package/src/fact-pipeline.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { type Database } from '@dxos/echo';
+import { Pipeline } from '@dxos/pipeline';
+import { Message } from '@dxos/types';
+
+import { EmailPipelineCtx, type FactIndexer, type Stats, emptyStats, extractFactsStage, statsStage } from './stages';
+
+export type EmailFactPipelineOptions = {
+  /** ECHO space database, required by `EmailPipelineCtx` even though this assembly never writes to it. */
+  readonly db: Database.Database;
+  /** Persists one message's facts to the fact substrate (a closure over a `FactStore`). */
+  readonly indexFacts: FactIndexer;
+};
+
+export type EmailFactPipelineResult = {
+  readonly messages: Message.Message[];
+  readonly stats: Stats;
+};
+
+export const EmailFactPipeline = {
+  /**
+   * Facts-only assembly of the email stages over a batch of messages: stats → extract-facts. Omits
+   * summarize, extract-contacts, and {@link buildThreads} from {@link EmailPipeline}, so it needs no
+   * `AiService` and never writes to `db`. The cursored `EnrichMailbox` operation (in plugin-inbox)
+   * covers the same fact-extraction concern incrementally, via a sibling facts-returning stage
+   * (`extractFactsUnitStage`) that commits pages atomically with a cursor advance instead of indexing
+   * in-stage; this batch variant is for one-shot runs over an already-collected set of messages.
+   */
+  run: (
+    messages: readonly Message.Message[],
+    options: EmailFactPipelineOptions,
+  ): Effect.Effect<EmailFactPipelineResult> =>
+    Effect.gen(function* () {
+      const stats = emptyStats();
+      const collected: Message.Message[] = [];
+      yield* Stream.fromIterable(messages).pipe(
+        statsStage,
+        extractFactsStage(options.indexFacts),
+        Pipeline.run({ sink: (message) => Effect.sync(() => collected.push(message)) }),
+        Effect.provideService(EmailPipelineCtx, { db: options.db, stats, summaries: [] }),
+      );
+
+      return { messages: collected, stats };
+    }),
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './corpus';
+export * from './fact-pipeline';
+export * from './pipeline';
+export * from './stages';
+export * from './types';

package/src/internal/fact-index.test.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Obj } from '@dxos/echo';
+import { RDF, normalizeEntityId } from '@dxos/pipeline-rdf';
+import { Organization, Person } from '@dxos/types';
+
+import { buildEntityIndex, reconcileFactEntities } from './fact-index';
+
+const fact = (subjectLabel: string, objectLabel: string): RDF.Fact => ({
+  id: 'f1',
+  assertion: {
+    subject: { entity: normalizeEntityId(subjectLabel), label: subjectLabel },
+    predicate: 'works at',
+    object: { entity: normalizeEntityId(objectLabel), label: objectLabel },
+  },
+  factuality: { value: 'CT+', polarity: '+' },
+  attribution: { source: 'dxn:queue:m1', generatedAtTime: '2001-05-14T10:00:00.000Z' },
+  recordedAt: '2001-05-14T10:00:00.000Z',
+  extractor: { id: 'default', model: 'test', version: '1' },
+  sourceHash: 'h1',
+});
+
+describe('entity reconciliation', () => {
+  test('buildEntityIndex maps normalized names/emails to object DXNs', ({ expect }) => {
+    const alice = Obj.make(Person.Person, { fullName: 'Alice Smith', emails: [{ value: 'alice@enron.com' }] });
+    const enron = Obj.make(Organization.Organization, { name: 'Enron' });
+
+    const index = buildEntityIndex([alice, enron]);
+    expect(index.get(normalizeEntityId('Alice Smith'))).toBe(Obj.getURI(alice));
+    expect(index.get(normalizeEntityId('alice@enron.com'))).toBe(Obj.getURI(alice));
+    expect(index.get(normalizeEntityId('Enron'))).toBe(Obj.getURI(enron));
+  });
+
+  test('reconcileFactEntities resolves subject/object to DXNs when known', ({ expect }) => {
+    const alice = Obj.make(Person.Person, { fullName: 'Alice Smith', emails: [{ value: 'alice@enron.com' }] });
+    const enron = Obj.make(Organization.Organization, { name: 'Enron' });
+    const index = buildEntityIndex([alice, enron]);
+
+    const resolved = reconcileFactEntities(fact('Alice Smith', 'Enron'), index);
+    expect(resolved.subject).toBe(Obj.getURI(alice));
+    expect(resolved.object).toBe(Obj.getURI(enron));
+  });
+
+  test('reconcileFactEntities leaves unknown entities unresolved', ({ expect }) => {
+    const index = buildEntityIndex([]);
+    const resolved = reconcileFactEntities(fact('Nobody', 'Nowhere'), index);
+    expect(resolved.subject).toBeUndefined();
+    expect(resolved.object).toBeUndefined();
+  });
+});

package/src/internal/fact-index.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Obj } from '@dxos/echo';
+import { RDF, normalizeEntityId } from '@dxos/pipeline-rdf';
+import { Organization, Person } from '@dxos/types';
+
+// Surface forms (name + emails) under which a Person may be referenced in extracted facts.
+const personKeys = (person: Person.Person): string[] =>
+  [person.fullName, ...(person.emails ?? []).map((email) => email.value)].filter(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  );
+
+const orgKeys = (org: Organization.Organization): string[] =>
+  [org.name].filter((value): value is string => typeof value === 'string' && value.length > 0);
+
+// Reconciliation table: normalized entity id (as produced by the extractor) → canonical ECHO URI.
+// ECHO objects remain the source of truth (spec §4); this table lets advisory facts point at them.
+export const buildEntityIndex = (
+  objects: readonly (Person.Person | Organization.Organization)[],
+): Map<string, string> => {
+  const index = new Map<string, string>();
+  for (const object of objects) {
+    const uri = Obj.getURI(object);
+    const keys = Obj.instanceOf(Person.Person, object) ? personKeys(object) : orgKeys(object);
+    for (const key of keys) {
+      index.set(normalizeEntityId(key), uri);
+    }
+  }
+  return index;
+};
+
+// Resolve a fact's subject/object entity ids to canonical URIs where the index knows them; unknown
+// referents are simply omitted (an advisory fact about an unresolved entity is still a valid fact).
+export const reconcileFactEntities = (
+  fact: RDF.Fact,
+  index: Map<string, string>,
+): { subject?: string; object?: string } => {
+  const subject = 'entity' in fact.assertion.subject ? index.get(fact.assertion.subject.entity) : undefined;
+  const object = 'entity' in fact.assertion.object ? index.get(fact.assertion.object.entity) : undefined;
+  return { ...(subject ? { subject } : {}), ...(object ? { object } : {}) };
+};

package/src/internal/threading.test.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Message } from '@dxos/types';
+
+import { deriveThreadId, normalizeSubject } from './threading';
+
+describe('threading', () => {
+  test('normalizeSubject strips reply/forward prefixes and normalizes', ({ expect }) => {
+    expect(normalizeSubject('Re: Q2 Report')).toBe('q2 report');
+    expect(normalizeSubject('FW: Fwd:  Re: Q2   Report ')).toBe('q2 report');
+    expect(normalizeSubject('Q2 Report')).toBe('q2 report');
+  });
+
+  test('deriveThreadId groups replies onto one thread', ({ expect }) => {
+    const original = Message.make({ sender: { email: 'a@x.com' }, properties: { subject: 'Deal terms' } });
+    const reply = Message.make({ sender: { email: 'b@x.com' }, properties: { subject: 'RE: Deal terms' } });
+    expect(deriveThreadId(original)).toBe(deriveThreadId(reply));
+  });
+
+  test('deriveThreadId falls back for missing subject', ({ expect }) => {
+    const message = Message.make({ sender: { email: 'a@x.com' } });
+    expect(deriveThreadId(message)).toBe('no-subject');
+  });
+});

package/src/internal/threading.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Message } from '@dxos/types';
+
+// Leading reply/forward markers, stripped repeatedly ("Fw: Re:" → "").
+const PREFIX = /^\s*(re|fwd?|fw)\s*:\s*/i;
+
+// Canonical subject for threading: drop reply/forward prefixes, collapse internal whitespace,
+// lowercase. Two messages with the same normalized subject belong to the same thread.
+export const normalizeSubject = (subject: string): string => {
+  let value = subject;
+  while (PREFIX.test(value)) {
+    value = value.replace(PREFIX, '');
+  }
+  return value.replace(/\s+/g, ' ').trim().toLowerCase();
+};
+
+// Derive a thread id from the subject. The Enron dataset carries no References/In-Reply-To headers,
+// so the normalized subject is the available grouping signal; blank subjects share a `no-subject`
+// bucket rather than each forming a singleton thread.
+export const deriveThreadId = (message: Message.Message): string => {
+  const subject = message.properties?.subject;
+  const normalized = typeof subject === 'string' ? normalizeSubject(subject) : '';
+  return normalized.length > 0 ? normalized : 'no-subject';
+};

package/src/internal/threads.test.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Message } from '@dxos/types';
+
+import { buildThreads } from './threads';
+
+const msg = (subject: string, from: string, created: string, summary?: string) =>
+  Message.make({
+    created,
+    sender: { email: from },
+    blocks: [{ _tag: 'text', text: 'body' }],
+    properties: { subject, messageId: `<${from}:${created}>`, ...(summary ? { summary } : {}) },
+  });
+
+const OWNER = 'me@enron.com';
+
+describe('buildThreads', () => {
+  test('groups messages by normalized subject', ({ expect }) => {
+    const threads = buildThreads(
+      [
+        msg('Deal terms', 'a@x.com', '2001-05-01T10:00:00.000Z'),
+        msg('RE: Deal terms', OWNER, '2001-05-01T11:00:00.000Z'),
+        msg('Lunch?', 'b@x.com', '2001-05-01T12:00:00.000Z'),
+      ],
+      { ownerEmail: OWNER, now: '2001-05-02T00:00:00.000Z' },
+    );
+
+    expect(threads).toHaveLength(2);
+    const deal = threads.find((thread) => thread.threadId === 'deal terms');
+    expect(deal?.messageIds).toHaveLength(2);
+    expect([...(deal?.participants ?? [])].sort()).toEqual(['a@x.com', 'me@enron.com']);
+  });
+
+  test('state is awaiting-theirs when owner sent last', ({ expect }) => {
+    const [thread] = buildThreads(
+      [
+        msg('Deal terms', 'a@x.com', '2001-05-01T10:00:00.000Z'),
+        msg('RE: Deal terms', OWNER, '2001-05-01T11:00:00.000Z'),
+      ],
+      { ownerEmail: OWNER, now: '2001-05-02T00:00:00.000Z' },
+    );
+    expect(thread.state).toBe('awaiting-theirs');
+  });
+
+  test('state is awaiting-mine when other party sent last', ({ expect }) => {
+    const [thread] = buildThreads([msg('Deal terms', 'a@x.com', '2001-05-01T10:00:00.000Z')], {
+      ownerEmail: OWNER,
+      now: '2001-05-02T00:00:00.000Z',
+    });
+    expect(thread.state).toBe('awaiting-mine');
+  });
+
+  test('state is stalled when awaiting past the stale period', ({ expect }) => {
+    const [thread] = buildThreads([msg('Deal terms', 'a@x.com', '2001-05-01T10:00:00.000Z')], {
+      ownerEmail: OWNER,
+      now: '2001-06-01T00:00:00.000Z',
+    });
+    expect(thread.state).toBe('stalled');
+  });
+
+  test('summary concatenates per-message summaries', ({ expect }) => {
+    const [thread] = buildThreads(
+      [
+        msg('Deal terms', 'a@x.com', '2001-05-01T10:00:00.000Z', 'Opening offer.'),
+        msg('RE: Deal terms', OWNER, '2001-05-01T11:00:00.000Z', 'Countered.'),
+      ],
+      { ownerEmail: OWNER, now: '2001-05-02T00:00:00.000Z' },
+    );
+    expect(thread.summary).toContain('Opening offer.');
+    expect(thread.summary).toContain('Countered.');
+  });
+});

package/src/internal/threads.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Obj } from '@dxos/echo';
+import { Message } from '@dxos/types';
+
+import { messageSource } from '../stages/facts';
+import { Thread, type ThreadState } from '../types';
+import { deriveThreadId } from './threading';
+
+const DEFAULT_STALE_PERIOD_MS = 14 * 24 * 60 * 60 * 1000;
+
+export type BuildThreadsOptions = {
+  readonly ownerEmail: string;
+  readonly now: string;
+  readonly stalePeriodMs?: number;
+};
+
+// Coarse thread state from who spoke last and how long ago. `resolved` needs a signal we do not yet
+// extract, so it is not inferred in this slice.
+const computeState = (lastFromOwner: boolean, lastCreated: string, options: BuildThreadsOptions): ThreadState => {
+  const idleMs = new Date(options.now).getTime() - new Date(lastCreated).getTime();
+  const stale = idleMs > (options.stalePeriodMs ?? DEFAULT_STALE_PERIOD_MS);
+  if (stale) {
+    return 'stalled';
+  }
+  return lastFromOwner ? 'awaiting-theirs' : 'awaiting-mine';
+};
+
+// Group messages into canonical Thread objects. Messages are bucketed by derived threadId; within a
+// bucket they are ordered by `created` to find the last speaker.
+export const buildThreads = (messages: readonly Message.Message[], options: BuildThreadsOptions): Thread[] => {
+  const buckets = new Map<string, Message.Message[]>();
+  for (const message of messages) {
+    const threadId = deriveThreadId(message);
+    let bucket = buckets.get(threadId);
+    if (!bucket) {
+      bucket = [];
+      buckets.set(threadId, bucket);
+    }
+    bucket.push(message);
+  }
+
+  const threads: Thread[] = [];
+  for (const [threadId, bucket] of buckets) {
+    const ordered = [...bucket].sort((a, b) => a.created.localeCompare(b.created));
+    const last = ordered[ordered.length - 1];
+    // Email addresses are case-insensitive, so compare and dedup on a lowercased form; otherwise
+    // mixed-case senders split into distinct participants and can misclassify awaiting-mine/theirs.
+    const owner = options.ownerEmail.toLowerCase();
+    const lastFromOwner = last.sender.email?.toLowerCase() === owner;
+    const participants = [...new Set(ordered.flatMap((m) => (m.sender.email ? [m.sender.email.toLowerCase()] : [])))];
+    const summaries = ordered.flatMap((m) =>
+      typeof m.properties?.summary === 'string' && m.properties.summary.length > 0 ? [m.properties.summary] : [],
+    );
+    const subject = typeof ordered[0].properties?.subject === 'string' ? ordered[0].properties.subject : threadId;
+
+    threads.push(
+      Obj.make(Thread, {
+        threadId,
+        subject,
+        summary: summaries.length > 0 ? summaries.join('\n') : subject,
+        state: computeState(lastFromOwner, last.created, options),
+        participants,
+        messageIds: ordered.map(messageSource),
+        openQuestions: [],
+        actionItems: [],
+      }),
+    );
+  }
+  return threads;
+};