fix(adapter-github): stable tiebreaker for commit-email canonical ranking (#19)

extractEmailsFromCommits sorted by (personal-vs-work, frequency desc) but
ties fell back to Map insertion order, which mirrors the GitHub commits API
response order. Since the first email becomes the canonical email used in
identity resolution, a tie could flip canonicalId across runs — the same
class of bug as #10 (selectTopRepos), one layer downstream.

Add a final localeCompare tiebreaker so equal-class, equal-frequency emails
sort deterministically by string.

The test mirrors the H-10 pattern: two equal-frequency personal emails,
shuffled via a deterministic LCG across 100 seeds, asserting the top-1
canonical email is identical every time. Verified RED (returned
insertion-order 'zoe@gmail.com') before the fix, GREEN after.

Verification: adapter-github 37/37, full suite 793 passing / 1 skipped,
lint 14/14, typecheck 27/27, build 14/14.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: matthewod11-stack

packages/adapters/adapter-github/src/__tests__/github-adapter.test.ts

@@ -403,6 +403,52 @@ describe('selectTopRepos (H-10 stable sort)', () => {
   });
 });
 
+describe('extractEmailsFromCommits (H-10 follow-up: stable tiebreaker)', () => {
+  // LCG-based shuffle so test outcome is reproducible (mirrors the H-10 test).
+  function deterministicShuffle<T>(arr: readonly T[], seed: number): T[] {
+    const a = [...arr];
+    let s = seed >>> 0;
+    for (let i = a.length - 1; i > 0; i--) {
+      s = (s * 1103515245 + 12345) >>> 0;
+      const j = s % (i + 1);
+      [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+  }
+
+  function makeCommit(email: string): GitHubCommit {
+    return {
+      sha: `sha-${email}`,
+      commit: {
+        author: { name: 'Dev', email, date: '2026-01-01T00:00:00Z' },
+        message: 'commit',
+      },
+      html_url: 'https://github.com/u/r/commit/sha',
+    };
+  }
+
+  it('produces identical top-1 canonical email across 100 shuffles when frequency ties', () => {
+    // Both emails are personal (gmail) and tie at frequency 2. Without a string
+    // tiebreaker, the commit API response order decides which becomes the
+    // canonical email used in identity resolution — flipping canonicalId across runs.
+    const commits: GitHubCommit[] = [
+      makeCommit('zoe@gmail.com'),
+      makeCommit('zoe@gmail.com'),
+      makeCommit('amy@gmail.com'),
+      makeCommit('amy@gmail.com'),
+    ];
+
+    const expected = extractEmailsFromCommits(commits);
+    // localeCompare ascending → 'amy' sorts before 'zoe' deterministically.
+    expect(expected[0]).toBe('amy@gmail.com');
+
+    for (let seed = 1; seed <= 100; seed++) {
+      const shuffled = deterministicShuffle(commits, seed);
+      expect(extractEmailsFromCommits(shuffled)[0]).toBe(expected[0]);
+    }
+  });
+});
+
 describe('GitHubClient API contract validation (H-11)', () => {
   it('throws ApiContractError with the missing field path', async () => {
     mockFetch.mockImplementation(async () => ({

packages/adapters/adapter-github/src/parsers.ts

@@ -46,7 +46,10 @@ export function extractEmailsFromCommits(commits: GitHubCommit[]): string[] {
       const aPersonal = isPersonalEmail(a[0]) ? 0 : 1;
       const bPersonal = isPersonalEmail(b[0]) ? 0 : 1;
       if (aPersonal !== bPersonal) return aPersonal - bPersonal;
-      return b[1] - a[1]; // higher frequency first
+      if (b[1] !== a[1]) return b[1] - a[1]; // higher frequency first
+      // Deterministic tiebreaker: equal-class, equal-frequency emails sort by
+      // string so the canonical email can't flip with commit API order (#19).
+      return a[0].localeCompare(b[0]);
     })
     .map(([email]) => email);
 }