@dxos/pipeline-email 0.0.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@dxos/pipeline-email",
+  "version": "0.0.0",
+  "description": "Worked email pipeline over the Enron dataset (parquet source → summarize/extract/stats stages).",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "info@dxos.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./dist/lib/neutral/index.mjs",
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts"
+    },
+    "./testing": {
+      "default": "./dist/lib/neutral/testing/index.mjs",
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@effect/ai": "0.36.0",
+    "hyparquet": "^1.26.2",
+    "@dxos/ai": "0.10.0",
+    "@dxos/extractor-lib": "0.10.0",
+    "@dxos/echo": "0.10.0",
+    "@dxos/node-std": "0.10.0",
+    "@dxos/pipeline-rdf": "0.0.0",
+    "@dxos/util": "0.10.0",
+    "@dxos/pipeline": "0.9.0",
+    "@dxos/types": "0.10.0"
+  },
+  "devDependencies": {
+    "effect": "3.21.4",
+    "hyparquet-writer": "^0.16.1",
+    "vitest": "4.1.8",
+    "@dxos/echo-client": "0.10.0",
+    "@dxos/effect": "0.10.0",
+    "@dxos/log": "0.10.0"
+  },
+  "peerDependencies": {
+    "effect": "3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/corpus/digest.test.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Message } from '@dxos/types';
+
+import { buildThreads } from '../internal/threads';
+import { buildDigest, narrateDigest, renderDigest } from './digest';
+import { type Commitment } from './ledger';
+import { buildRollups } from './rollups';
+import { clusterThreads } from './topics';
+
+const OWNER = 'me@enron.com';
+const NOW = '2001-06-01T00:00:00.000Z';
+
+const COMMITMENTS: Commitment[] = [
+  { who: 'alice@enron.com', what: 'Q2 report', dueBy: '2001-05-18', factId: 'f1', source: '<m1>' },
+  { who: 'bob@enron.com', what: 'budget', factId: 'f2', source: '<m2>' },
+];
+
+describe('digest', () => {
+  test('builds a deterministic skeleton', ({ expect }) => {
+    const digest = buildDigest(input(), { now: NOW });
+    expect(digest.generatedAt).toBe(NOW);
+    expect(digest.threadCount).toBe(2);
+    expect(digest.topicCount).toBeGreaterThan(0);
+    expect(digest.stalledThreads).toContain('old deal terms');
+    expect(digest.awaitingMine).toContain('q2 report');
+    // Only the commitment with a deadline is due.
+    expect(digest.dueCommitments).toHaveLength(1);
+    expect(digest.dueCommitments[0].what).toBe('Q2 report');
+    expect(digest.topTopics.length).toBeGreaterThan(0);
+    expect(digest.narrative).toBe('');
+  });
+
+  test('renderDigest emits the skeleton as text', ({ expect }) => {
+    const text = renderDigest(buildDigest(input(), { now: NOW }));
+    expect(text).toContain('Threads: 2');
+    expect(text).toContain('old deal terms');
+    expect(text).toContain('Q2 report');
+  });
+
+  test('narrateDigest fills the narrative via the summarizer and degrades on failure', async ({ expect }) => {
+    const digest = buildDigest(input(), { now: NOW });
+    const narrated = await narrateDigest(digest, async () => 'All quiet except the Q2 report.');
+    expect(narrated.narrative).toBe('All quiet except the Q2 report.');
+
+    const degraded = await narrateDigest(digest, async () => {
+      throw new Error('model down');
+    });
+    expect(degraded.narrative).toBe('');
+  });
+});
+
+const msg = (subject: string, from: string, created: string) =>
+  Message.make({
+    created,
+    sender: { email: from },
+    blocks: [{ _tag: 'text', text: 'body' }],
+    properties: { subject, messageId: `<${from}:${created}>` },
+  });
+
+const input = () => {
+  const messages = [
+    // Recent thread awaiting my reply; older thread long stalled.
+    msg('Q2 report', 'alice@enron.com', '2001-05-31T10:00:00.000Z'),
+    msg('Old deal terms', 'bob@enron.com', '2001-04-01T10:00:00.000Z'),
+  ];
+  const threads = buildThreads(messages, { ownerEmail: OWNER, now: NOW });
+  return {
+    threads,
+    topics: clusterThreads(threads),
+    commitments: COMMITMENTS,
+    rollups: buildRollups(messages),
+  };
+};

package/src/corpus/digest.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Thread } from '../types';
+import { type Commitment } from './ledger';
+import { DEFAULT_EMAIL_PROMPTS, type EmailPrompts, type Summarizer, mergePrompts } from './prompts';
+import { type RelationshipRollup } from './rollups';
+import { type TopicDraft } from './topics';
+
+/**
+ * Everything the corpus pass has computed; the digest is a Query-mode view over it (spec §3③
+ * briefings) — assembled on demand, never materialized as ECHO.
+ */
+export type DigestInput = {
+  readonly threads: readonly Thread[];
+  readonly topics: readonly TopicDraft[];
+  readonly commitments: readonly Commitment[];
+  readonly rollups: readonly RelationshipRollup[];
+};
+
+export type DigestOptions = {
+  /** Timestamp the digest reports as its generation time (passed in for determinism). */
+  readonly now: string;
+  /** Topics listed in the skeleton (largest first). */
+  readonly maxTopTopics?: number;
+};
+
+/** Deterministic digest skeleton; `narrative` stays empty until {@link narrateDigest} fills it. */
+export type Digest = {
+  readonly generatedAt: string;
+  readonly threadCount: number;
+  readonly topicCount: number;
+  /** Threads needing attention. */
+  readonly stalledThreads: readonly string[];
+  readonly awaitingMine: readonly string[];
+  /** Commitments carrying a deadline, soonest first. */
+  readonly dueCommitments: readonly Commitment[];
+  readonly topTopics: readonly { readonly label: string; readonly threadCount: number }[];
+  /** LLM briefing text; empty when narration is off or degraded. */
+  readonly narrative: string;
+};
+
+/** Assemble the deterministic digest skeleton from the corpus outputs (Compute mode; no LLM). */
+export const buildDigest = (input: DigestInput, options: DigestOptions): Digest => ({
+  generatedAt: options.now,
+  threadCount: input.threads.length,
+  topicCount: input.topics.length,
+  stalledThreads: input.threads.filter((thread) => thread.state === 'stalled').map((thread) => thread.threadId),
+  awaitingMine: input.threads.filter((thread) => thread.state === 'awaiting-mine').map((thread) => thread.threadId),
+  dueCommitments: input.commitments
+    .filter((commitment) => commitment.dueBy !== undefined)
+    .sort((a, b) => (a.dueBy ?? '').localeCompare(b.dueBy ?? '')),
+  topTopics: [...input.topics]
+    .sort((a, b) => b.threadIds.length - a.threadIds.length || a.label.localeCompare(b.label))
+    .slice(0, options.maxTopTopics ?? 5)
+    .map((topic) => ({ label: topic.label, threadCount: topic.threadIds.length })),
+  narrative: '',
+});
+
+/** Render the skeleton as plain text — the prompt payload for narration, and a fallback briefing. */
+export const renderDigest = (digest: Digest): string =>
+  [
+    `Inbox digest (${digest.generatedAt})`,
+    `Threads: ${digest.threadCount}  Topics: ${digest.topicCount}`,
+    `Awaiting my reply: ${digest.awaitingMine.join(', ') || 'none'}`,
+    `Stalled: ${digest.stalledThreads.join(', ') || 'none'}`,
+    `Due commitments: ${
+      digest.dueCommitments
+        .map((commitment) => `${commitment.who} → ${commitment.what} (${commitment.dueBy})`)
+        .join('; ') || 'none'
+    }`,
+    `Top topics: ${digest.topTopics.map((topic) => `${topic.label} (${topic.threadCount})`).join('; ') || 'none'}`,
+  ].join('\n');
+
+/**
+ * Optionally add an LLM briefing over the skeleton, using the editable `digest` prompt. Degrades to
+ * the un-narrated digest on failure — the skeleton is always available.
+ */
+export const narrateDigest = async (
+  digest: Digest,
+  summarize: Summarizer,
+  options?: { readonly prompts?: Partial<EmailPrompts> },
+): Promise<Digest> => {
+  const prompts = options?.prompts ? mergePrompts(options.prompts) : DEFAULT_EMAIL_PROMPTS;
+  try {
+    const narrative = await summarize([prompts.digest, renderDigest(digest)].join('\n\n'));
+    return { ...digest, narrative: narrative.trim() };
+  } catch {
+    return digest;
+  }
+};

package/src/corpus/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './topics';
+export * from './ledger';
+export * from './rollups';
+export * from './digest';
+export * from './prompts';

package/src/corpus/ledger.test.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import { afterAll, describe, test } from 'vitest';
+
+import { FactStore, type RDF, normalizeEntityId } from '@dxos/pipeline-rdf';
+
+import { commitmentLedger } from './ledger';
+
+const runtime = ManagedRuntime.make(FactStore.layerMemory);
+
+describe('commitmentLedger', () => {
+  afterAll(async () => {
+    await runtime.dispose();
+  });
+
+  test('collects commitment facts by predicate, ignoring plain statements', async ({ expect }) => {
+    await runtime.runPromise(
+      Effect.gen(function* () {
+        const store = yield* FactStore;
+        yield* store.putFacts(FACTS);
+      }),
+    );
+
+    const commitments = await runtime.runPromise(
+      Effect.gen(function* () {
+        const store = yield* FactStore;
+        return yield* commitmentLedger(store);
+      }),
+    );
+
+    expect(commitments).toHaveLength(2);
+    const send = commitments.find((commitment) => commitment.what === 'Q2 report');
+    expect(send?.who).toBe('alice@enron.com');
+    expect(send?.dueBy).toBe('2001-05-18');
+    expect(send?.source).toBe('<m1@enron.com>');
+    expect(commitments.some((commitment) => commitment.what === 'Enron')).toBe(false);
+  });
+
+  test('custom predicates narrow the ledger', async ({ expect }) => {
+    const commitments = await runtime.runPromise(
+      Effect.gen(function* () {
+        const store = yield* FactStore;
+        return yield* commitmentLedger(store, { predicates: ['owes'] });
+      }),
+    );
+    expect(commitments).toHaveLength(1);
+    expect(commitments[0].who).toBe('bob@enron.com');
+  });
+});
+
+// Hand-built facts: two commitments (one with a deadline) and one plain statement.
+const fact = (
+  id: string,
+  subject: string,
+  predicate: string,
+  object: string,
+  extra?: { validTo?: string; confidence?: number },
+): RDF.Fact => ({
+  id,
+  assertion: {
+    subject: { entity: normalizeEntityId(subject), label: subject },
+    predicate,
+    object: { entity: normalizeEntityId(object), label: object },
+    ...(extra?.validTo ? { validTo: extra.validTo } : {}),
+  },
+  factuality: {
+    value: 'CT+',
+    polarity: '+',
+    ...(extra?.confidence !== undefined ? { confidence: extra.confidence } : {}),
+  },
+  attribution: { source: `<${id}@enron.com>`, generatedAtTime: '2001-05-01T10:00:00.000Z' },
+  recordedAt: '2001-05-01T10:00:00.000Z',
+  extractor: { id: 'test', model: 'test', version: '1' },
+  sourceHash: `h-${id}`,
+});
+
+const FACTS: RDF.Fact[] = [
+  fact('m1', 'alice@enron.com', 'will send', 'Q2 report', { validTo: '2001-05-18' }),
+  fact('m2', 'bob@enron.com', 'owes', 'budget confirmation'),
+  fact('m3', 'alice@enron.com', 'works at', 'Enron'),
+];

package/src/corpus/ledger.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type FactStoreApi, type RDF, type SemanticIndexError } from '@dxos/pipeline-rdf';
+
+/**
+ * Predicates treated as commitments (spec §3③ commitment ledger). Editable: extraction phrasing
+ * varies by corpus and extraction rules, so callers tune this list rather than the query logic.
+ */
+export const DEFAULT_COMMITMENT_PREDICATES: readonly string[] = ['owes', 'will send', 'will provide', 'must', 'due'];
+
+export type LedgerOptions = {
+  /** Predicates that mark a fact as a commitment. */
+  readonly predicates?: readonly string[];
+};
+
+/** One row of the commitment ledger, traceable to its supporting fact. */
+export type Commitment = {
+  /** Who owes it (fact subject label). */
+  readonly who: string;
+  /** What is owed (fact object label or literal). */
+  readonly what: string;
+  /** Deadline (assertion validTo), when stated. */
+  readonly dueBy?: string;
+  /** Model confidence carried from the fact's factuality. */
+  readonly confidence?: number;
+  readonly factId: string;
+  /** Source message (fact attribution). */
+  readonly source: string;
+};
+
+const termLabel = (term: RDF.Assertion['subject']): string =>
+  'entity' in term ? (term.label ?? term.entity) : term.literal;
+
+const toCommitment = (fact: RDF.Fact): Commitment => ({
+  who: termLabel(fact.assertion.subject),
+  what: termLabel(fact.assertion.object),
+  ...(fact.assertion.validTo ? { dueBy: fact.assertion.validTo } : {}),
+  ...(fact.factuality.confidence !== undefined ? { confidence: fact.factuality.confidence } : {}),
+  factId: fact.id,
+  source: fact.attribution.source,
+});
+
+/**
+ * Query the fact store for outstanding commitments — the spec's cross-thread "owe / owed" ledger.
+ * Uses the structured query path (one `query({ predicate })` per commitment predicate, compiled to
+ * SPARQL on the sqlite backend), which works on both store backends; rows are advisory evidence
+ * (§4 canonicality) and each carries its fact id + source message for grounding.
+ */
+export const commitmentLedger = (
+  store: FactStoreApi,
+  options?: LedgerOptions,
+): Effect.Effect<Commitment[], SemanticIndexError> =>
+  Effect.forEach(options?.predicates ?? DEFAULT_COMMITMENT_PREDICATES, (predicate) => store.query({ predicate })).pipe(
+    Effect.map((results) => {
+      // A fact can match several predicate probes; keep the first occurrence.
+      const seen = new Set<string>();
+      const commitments: Commitment[] = [];
+      for (const fact of results.flat()) {
+        if (!seen.has(fact.id)) {
+          seen.add(fact.id);
+          commitments.push(toCommitment(fact));
+        }
+      }
+      // Deadlines first (soonest first), then the rest in stable fact order.
+      return commitments.sort((a, b) =>
+        a.dueBy && b.dueBy ? a.dueBy.localeCompare(b.dueBy) : a.dueBy ? -1 : b.dueBy ? 1 : 0,
+      );
+    }),
+  );

package/src/corpus/prompts.test.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { DEFAULT_EMAIL_PROMPTS, mergePrompts } from './prompts';
+
+describe('prompts', () => {
+  test('defaults cover every prompt slot', ({ expect }) => {
+    expect(DEFAULT_EMAIL_PROMPTS.topicSummary.length).toBeGreaterThan(0);
+    expect(DEFAULT_EMAIL_PROMPTS.digest.length).toBeGreaterThan(0);
+  });
+
+  test('mergePrompts overrides only the given slots', ({ expect }) => {
+    const merged = mergePrompts({ digest: 'Custom digest prompt.' });
+    expect(merged.digest).toBe('Custom digest prompt.');
+    expect(merged.topicSummary).toBe(DEFAULT_EMAIL_PROMPTS.topicSummary);
+  });
+
+  test('mergePrompts with no overrides returns the defaults', ({ expect }) => {
+    expect(mergePrompts()).toEqual(DEFAULT_EMAIL_PROMPTS);
+  });
+});

package/src/corpus/prompts.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { trim } from '@dxos/util';
+
+/**
+ * User-editable prompts for the LLM-assisted corpus algorithms. Every slot has a default; callers
+ * override any subset via {@link mergePrompts}, so the discovery algorithms stay configurable
+ * without forking the pipeline. (Extraction rules are configured separately, via pipeline-rdf
+ * `ExtractOptions.rules`.)
+ */
+export type EmailPrompts = {
+  /** Summarize one topic (cluster of threads); receives the topic label + per-thread summaries. */
+  readonly topicSummary: string;
+  /** Narrate a corpus digest; receives the deterministic digest skeleton. */
+  readonly digest: string;
+};
+
+export const DEFAULT_EMAIL_PROMPTS: EmailPrompts = {
+  topicSummary: trim`
+    Summarize the following email conversation topic in 1-2 sentences.
+    Focus on what the threads have in common and any outcome or open question.
+    Respond with ONLY the summary text.
+  `,
+  digest: trim`
+    Write a short briefing (3-5 sentences) from the following inbox digest data.
+    Lead with what needs attention (stalled threads, due commitments), then notable topics.
+    Respond with ONLY the briefing text.
+  `,
+};
+
+/** Overlay caller overrides onto the defaults; absent slots keep their default. */
+export const mergePrompts = (overrides?: Partial<EmailPrompts>): EmailPrompts => ({
+  ...DEFAULT_EMAIL_PROMPTS,
+  ...overrides,
+});
+
+/**
+ * LLM call boundary used by the corpus algorithms: the harness owns model/runtime plumbing and hands
+ * modules a plain async closure (same pattern as `FactIndexer`), so algorithm Effects stay R = never.
+ */
+export type Summarizer = (prompt: string) => Promise<string>;

package/src/corpus/rollups.test.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Message } from '@dxos/types';
+
+import { buildRollups } from './rollups';
+
+describe('buildRollups', () => {
+  test('aggregates per sender: counts, contact span, cadence, threads', ({ expect }) => {
+    const rollups = buildRollups([
+      msg('Q2 report', 'Alice@Enron.com', '2001-05-01T10:00:00.000Z'),
+      msg('RE: Q2 report', 'alice@enron.com', '2001-05-03T10:00:00.000Z'),
+      msg('Budget', 'alice@enron.com', '2001-05-05T10:00:00.000Z'),
+      msg('Lunch', 'bob@enron.com', '2001-05-02T10:00:00.000Z'),
+    ]);
+
+    expect(rollups).toHaveLength(2);
+    // Sorted by message count, so alice first; mixed casing folds into one sender.
+    const [alice, bob] = rollups;
+    expect(alice.email).toBe('alice@enron.com');
+    expect(alice.messageCount).toBe(3);
+    expect(alice.firstContact).toBe('2001-05-01T10:00:00.000Z');
+    expect(alice.lastContact).toBe('2001-05-05T10:00:00.000Z');
+    expect(alice.cadenceDays).toBe(2);
+    expect(alice.threadIds).toEqual(['q2 report', 'budget']);
+
+    expect(bob.messageCount).toBe(1);
+    expect(bob.cadenceDays).toBeUndefined();
+  });
+
+  test('skips messages without a sender email', ({ expect }) => {
+    const anonymous = Message.make({
+      created: '2001-05-01T10:00:00.000Z',
+      sender: { name: 'Mystery' },
+      blocks: [{ _tag: 'text', text: 'body' }],
+    });
+    expect(buildRollups([anonymous])).toHaveLength(0);
+  });
+});
+
+const msg = (subject: string, from: string, created: string) =>
+  Message.make({
+    created,
+    sender: { email: from },
+    blocks: [{ _tag: 'text', text: 'body' }],
+    properties: { subject, messageId: `<${from}:${created}>` },
+  });

package/src/corpus/rollups.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Message } from '@dxos/types';
+
+import { deriveThreadId } from '../internal/threading';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Per-sender relationship aggregate (spec §3③ relationship rollups). Computed values, not ECHO
+ * mutations: `Person` is a closed, canonical schema the pipeline must not write onto, so rollups are
+ * consumed by the digest / callers (join back to a Person via the lowercased email and the
+ * fact-index reconciliation table); materialization waits for a proper schema home.
+ */
+export type RelationshipRollup = {
+  /** Lowercased sender address (email addresses are case-insensitive). */
+  readonly email: string;
+  readonly messageCount: number;
+  readonly firstContact: string;
+  readonly lastContact: string;
+  /** Mean days between messages; absent below two messages. */
+  readonly cadenceDays?: number;
+  /** Threads this sender participated in (send-side), in first-seen order. */
+  readonly threadIds: readonly string[];
+};
+
+/** Aggregate messages into per-sender rollups, most active sender first. Deterministic (Compute mode). */
+export const buildRollups = (messages: readonly Message.Message[]): RelationshipRollup[] => {
+  const bySender = new Map<string, { created: string[]; threadIds: string[] }>();
+  for (const message of messages) {
+    const email = message.sender.email?.toLowerCase();
+    if (!email) {
+      continue;
+    }
+    let entry = bySender.get(email);
+    if (!entry) {
+      entry = { created: [], threadIds: [] };
+      bySender.set(email, entry);
+    }
+    entry.created.push(message.created);
+    const threadId = deriveThreadId(message);
+    if (!entry.threadIds.includes(threadId)) {
+      entry.threadIds.push(threadId);
+    }
+  }
+
+  const rollups: RelationshipRollup[] = [];
+  for (const [email, entry] of bySender) {
+    const ordered = [...entry.created].sort();
+    const first = ordered[0];
+    const last = ordered[ordered.length - 1];
+    const spanMs = new Date(last).getTime() - new Date(first).getTime();
+    rollups.push({
+      email,
+      messageCount: ordered.length,
+      firstContact: first,
+      lastContact: last,
+      ...(ordered.length >= 2 ? { cadenceDays: spanMs / (ordered.length - 1) / MS_PER_DAY } : {}),
+      threadIds: entry.threadIds,
+    });
+  }
+  return rollups.sort((a, b) => b.messageCount - a.messageCount || a.email.localeCompare(b.email));
+};

package/src/corpus/topics.test.ts

@@ -0,0 +1,90 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Obj } from '@dxos/echo';
+import { Message } from '@dxos/types';
+
+import { buildThreads } from '../internal/threads';
+import { Topic } from '../types';
+import { clusterThreads, materializeTopics, summarizeTopics } from './topics';
+
+const OWNER = 'me@enron.com';
+const NOW = '2001-05-02T00:00:00.000Z';
+
+describe('topics', () => {
+  test('clusters related threads and separates unrelated ones', ({ expect }) => {
+    const drafts = clusterThreads(threads());
+    expect(drafts).toHaveLength(2);
+
+    const q2 = drafts.find((draft) => draft.threadIds.includes('q2 report draft'));
+    expect(q2?.threadIds).toContain('q2 report budget numbers');
+    expect(q2?.participants).toContain('alice@enron.com');
+    expect(q2?.keywords).toContain('report');
+
+    const lunch = drafts.find((draft) => draft.threadIds.includes('lunch on friday?'));
+    expect(lunch?.threadIds).toHaveLength(1);
+  });
+
+  test('every thread lands in exactly one topic', ({ expect }) => {
+    const input = threads();
+    const drafts = clusterThreads(input);
+    const assigned = drafts.flatMap((draft) => draft.threadIds);
+    expect(assigned.sort()).toEqual(input.map((thread) => thread.threadId).sort());
+  });
+
+  test('deterministic summary concatenates thread summaries; label from top keywords', ({ expect }) => {
+    const drafts = clusterThreads(threads());
+    const q2 = drafts.find((draft) => draft.threadIds.includes('q2 report draft'));
+    expect(q2?.summary).toContain('Draft circulated.');
+    expect(q2?.label.length).toBeGreaterThan(0);
+  });
+
+  test('blank-subject threads still get a non-empty topic label', ({ expect }) => {
+    const blank = buildThreads([msg('', 'a@x.com', '2001-05-01T10:00:00.000Z')], { ownerEmail: OWNER, now: NOW });
+    const [draft] = clusterThreads(blank);
+    expect(draft.label).toBe('no-subject');
+  });
+
+  test('summarizeTopics replaces summaries via the summarizer and degrades on failure', async ({ expect }) => {
+    const drafts = clusterThreads(threads());
+    const summarized = await summarizeTopics(drafts, async () => 'LLM topic summary.');
+    for (const draft of summarized) {
+      expect(draft.summary).toBe('LLM topic summary.');
+    }
+
+    // A failing summarizer keeps the deterministic summary.
+    const degraded = await summarizeTopics(drafts, async () => {
+      throw new Error('model down');
+    });
+    expect(degraded.map((draft) => draft.summary)).toEqual(drafts.map((draft) => draft.summary));
+  });
+
+  test('materializeTopics produces Topic ECHO objects', ({ expect }) => {
+    const [first] = materializeTopics(clusterThreads(threads()));
+    expect(Obj.instanceOf(Topic, first)).toBe(true);
+    expect(first.threadIds.length).toBeGreaterThan(0);
+  });
+});
+
+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 } : {}) },
+  });
+
+// Two related threads (shared participants + overlapping subject tokens) and one unrelated thread.
+const threads = () =>
+  buildThreads(
+    [
+      msg('Q2 report draft', 'alice@enron.com', '2001-05-01T10:00:00.000Z', 'Draft circulated.'),
+      msg('RE: Q2 report draft', OWNER, '2001-05-01T11:00:00.000Z', 'Comments sent.'),
+      msg('Q2 report budget numbers', 'alice@enron.com', '2001-05-01T12:00:00.000Z', 'Budget attached.'),
+      msg('Lunch on friday?', 'zed@other.org', '2001-05-01T13:00:00.000Z'),
+    ],
+    { ownerEmail: OWNER, now: NOW },
+  );