feat: audit cross-provider place conflicts

Author: atomantic

.changelog/NEXT.md

@@ -49,6 +49,7 @@
 
 ## Fixed
 
+- The tree auditor now detects genuine birth/death/etc. place disagreements across providers. It reuses the place comparison normalization, so aliases such as `TX`/`Texas`, country synonyms, and a provider's less-detailed place do not create review noise. Date mismatch checks now likewise require a disagreement between sources rather than conflicting values from one source alone.
 - Search results now keep their alphabetical ordering. The batch person-loader (`getPersonsBatch`) re-orders rows back to the requested order, fixing a regression where SQLite's `WHERE person_id IN (...)` returned rows in table order and silently discarded the search query's `ORDER BY display_name` (so the default, unsorted search view appeared randomly ordered).
 - Platform comparison now treats equivalent place spellings as matches: "Dallas, Texas, USA" vs "Dallas, Texas, United States" (and U.S.A. / United States of America / state abbreviations like TX vs Texas, UK vs United Kingdom, etc.) — no longer flagged as `different`. Place containment is now suffix-based, so "Texas" no longer falsely matches "Texarkana"
 - Platform comparison now treats equivalent date formats as matches (e.g., "1979-07-31" vs "31 JUL 1979")

PLAN.md

@@ -10,7 +10,7 @@ For phase-by-phase implementation history, see [docs/roadmap.md](./docs/roadmap.
 
 1. **Reverse god-file regression** — `PersonDetail.tsx` (1360), `ProviderDataTable.tsx` (1243), `database.service.ts` (1618), `auditor-agent.service.ts` (1233 — new), `multi-platform-comparison.service.ts` (1099), `api.ts` (1249), `VerticalFamilyView.tsx` (977), `favorites.service.ts` (872), `person.routes.ts` (1119). Extract `usePersonData` / `usePersonOverrides` hooks, `PhotoThumbnail` / `ComparisonCell` / `ProviderRow` sub-components, and split `database.service.ts` along entity lines. Split `auditor-agent.service.ts` into walker + per-check modules.
 2. **Critical-path unit tests** — `credentials.service.ts` (encryption), `validation.ts` (input sanitization), `errorHandler.ts`, `requestTimeout.ts`, `augmentation.service.ts`, `auditor-agent.service.ts` all currently have **zero** tests. (`database.service.ts` and `search.service.ts` now have integration coverage but no unit tests of internal helpers.)
-3. **Phase 18 remaining checks** — implement `place_mismatch`, `name_mismatch`, `missing_parents`, `duplicate_suspect`, `stale_record` checks in `auditor-agent.service.ts` (types are declared in `shared/src/index.ts:918` but not yet wired). Reuse `multi-platform-comparison.service.ts` for the `*_mismatch` family.
+3. **Phase 18 remaining checks** — implement `name_mismatch`, `missing_parents`, `duplicate_suspect`, `stale_record` checks in `auditor-agent.service.ts` (types are declared in `shared/src/index.ts:918` but not yet wired). `place_mismatch` now detects only genuine cross-source vital-place conflicts, reusing the comparison service's alias and detail normalization to avoid noisy results.
 4. ~~**Search N+1**~~ — done. `searchWithSqlite` now uses `getPersonsBatch()` (6 queries vs 7×N), the batch loader preserves caller order (was silently dropping `ORDER BY display_name` because SQLite `IN (...)` returns table order), and the two dead N+1 service methods (`quickSearch`, `searchGlobal`) were removed. _Deferred:_ `getPersonsBatch()` does not populate `externalId` the way `getPerson()` does — fine for current consumers (SearchPage doesn't render it), but restore parity (one batched `external_identity` query) if a batch consumer ever needs it.
 5. **Phase 19 Guided Verification** — review-session schema (`verification_session`, `person_review`, `edge_review`, `provider_match_review`, `review_decision`) and root-to-ancestor BFS review queue (19.1 + 19.2).
 

server/src/services/auditor-agent.service.ts

@@ -24,6 +24,8 @@ import { sqliteService } from '../db/sqlite.service.js';
 import { resolveDbId } from './database.service.js';
 import { logger } from '../lib/logger.js';
 import { createOperationTracker } from '../utils/operationTracker.js';
+import { findCrossSourceMismatches } from '../utils/auditMismatches.js';
+import { placeContains, placesMatch } from '../utils/normalizePlace.js';
 import config from '../lib/config.js';
 
 const tracker = createOperationTracker('auditor');
@@ -522,36 +524,53 @@ function checkDateMismatches(runId: string, personId: string, displayName: strin
   const events = sqliteService.queryAll<{
     event_type: string;
     date_year: number | null;
-    source: string;
+    source: string | null;
   }>(
     `SELECT event_type, date_year, source FROM vital_event
      WHERE person_id = @personId AND date_year IS NOT NULL
      ORDER BY event_type, source`,
     { personId }
   );
 
-  const issues: AuditIssue[] = [];
-  const byType = new Map<string, { year: number; source: string }[]>();
+  return findCrossSourceMismatches(
+    events.map(event => ({
+      eventType: event.event_type,
+      value: event.date_year as number,
+      source: event.source,
+    })),
+    (left, right) => left === right,
+  ).map(({ eventType, details }) => makeIssue(runId, personId, 'date_mismatch', 'warning',
+    `${displayName}: ${eventType} date differs across sources (${details})`,
+    details, null));
+}
 
-  for (const e of events) {
-    if (!e.date_year) continue;
-    const list = byType.get(e.event_type) ?? [];
-    list.push({ year: e.date_year, source: e.source ?? 'unknown' });
-    byType.set(e.event_type, list);
-  }
+function checkPlaceMismatches(runId: string, personId: string, displayName: string): AuditIssue[] {
+  const events = sqliteService.queryAll<{
+    event_type: string;
+    place: string;
+    source: string | null;
+  }>(
+    `SELECT event_type, place, source FROM vital_event
+     WHERE person_id = @personId AND TRIM(place) != ''
+     ORDER BY event_type, source, id`,
+    { personId },
+  );
 
-  for (const [eventType, entries] of byType) {
-    if (entries.length < 2) continue;
-    const years = new Set(entries.map(e => e.year));
-    if (years.size > 1) {
-      const details = entries.map(e => `${e.source}: ${e.year}`).join(', ');
-      issues.push(makeIssue(runId, personId, 'date_mismatch', 'warning',
-        `${displayName}: ${eventType} date differs across sources (${details})`,
-        details, null));
-    }
-  }
+  const samePlace = (left: string | number, right: string | number) => {
+    const a = String(left);
+    const b = String(right);
+    return placesMatch(a, b) || placeContains(a, b) || placeContains(b, a);
+  };
 
-  return issues;
+  return findCrossSourceMismatches(events.map(event => ({
+    eventType: event.event_type,
+    value: event.place,
+    source: event.source,
+  })), samePlace).map(({ eventType, details }) => makeIssue(
+    runId, personId, 'place_mismatch', 'warning',
+    `${displayName}: ${eventType} place differs across sources (${details})`,
+    details, null,
+  ));
 }
 
 // ============================================================================
@@ -787,6 +806,7 @@ const DEFAULT_CONFIG: AuditRunConfig = {
     'missing_gender',
     'orphaned_edge',
     'date_mismatch',
+    'place_mismatch',
   ],
   autoAccept: false,
   autoAcceptTypes: [],
@@ -842,6 +862,9 @@ function auditPerson(
   if (checksEnabled.includes('date_mismatch')) {
     issues.push(...checkDateMismatches(runId, vitals.personId, vitals.displayName));
   }
+  if (checksEnabled.includes('place_mismatch')) {
+    issues.push(...checkPlaceMismatches(runId, vitals.personId, vitals.displayName));
+  }
 
   return { issues, displayName: vitals.displayName, linkedSources };
 }

server/src/utils/auditMismatches.ts

@@ -0,0 +1,84 @@
+/**
+ * Helpers for detecting disagreements between provider-sourced vital events.
+ *
+ * A disagreement must be between sources. Multiple values from one source are
+ * not enough evidence to ask the user to resolve a cross-provider conflict.
+ */
+
+export interface EventSourceValue {
+  eventType: string;
+  value: string | number;
+  source: string | null;
+}
+
+export interface EventMismatch {
+  eventType: string;
+  details: string;
+}
+
+type ValuesMatch = (a: string | number, b: string | number) => boolean;
+
+function sourceName(source: string | null): string {
+  return source?.trim() || 'local';
+}
+
+function formatSourceValues(entries: EventSourceValue[]): string {
+  const bySource = new Map<string, Set<string>>();
+
+  for (const entry of entries) {
+    const source = sourceName(entry.source);
+    const values = bySource.get(source) ?? new Set<string>();
+    values.add(String(entry.value));
+    bySource.set(source, values);
+  }
+
+  return [...bySource.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([source, values]) => `${source}: ${[...values].sort().join(' / ')}`)
+    .join(', ');
+}
+
+/**
+ * Find event types where at least two sources have no matching value.
+ *
+ * A source can contain more than one value (notably legacy records with a
+ * null source). We suppress a mismatch when the two sources share any value,
+ * because there is no unambiguous cross-provider disagreement to resolve.
+ */
+export function findCrossSourceMismatches(
+  entries: EventSourceValue[],
+  valuesMatch: ValuesMatch,
+): EventMismatch[] {
+  const byEventType = new Map<string, EventSourceValue[]>();
+
+  for (const entry of entries) {
+    const values = byEventType.get(entry.eventType) ?? [];
+    values.push(entry);
+    byEventType.set(entry.eventType, values);
+  }
+
+  const mismatches: EventMismatch[] = [];
+
+  for (const [eventType, eventEntries] of byEventType) {
+    const bySource = new Map<string, EventSourceValue[]>();
+    for (const entry of eventEntries) {
+      const source = sourceName(entry.source);
+      const values = bySource.get(source) ?? [];
+      values.push(entry);
+      bySource.set(source, values);
+    }
+
+    const sourceValues = [...bySource.values()];
+    const hasDisagreement = sourceValues.some((values, index) =>
+      sourceValues.slice(index + 1).some(otherValues =>
+        values.every(value => otherValues.every(other => !valuesMatch(value.value, other.value)))
+      )
+    );
+
+    if (hasDisagreement) {
+      mismatches.push({ eventType, details: formatSourceValues(eventEntries) });
+    }
+  }
+
+  return mismatches;
+}

tests/unit/utils/auditMismatches.spec.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { findCrossSourceMismatches } from '../../../server/src/utils/auditMismatches.js';
+import { placeContains, placesMatch } from '../../../server/src/utils/normalizePlace.js';
+
+describe('findCrossSourceMismatches', () => {
+  it('reports a disagreement between two provider values', () => {
+    const mismatches = findCrossSourceMismatches([
+      { eventType: 'birth', value: 1874, source: 'familysearch' },
+      { eventType: 'birth', value: 1875, source: 'ancestry' },
+    ], (a, b) => a === b);
+
+    expect(mismatches).toEqual([{
+      eventType: 'birth',
+      details: 'ancestry: 1875, familysearch: 1874',
+    }]);
+  });
+
+  it('does not report values that only disagree within one source', () => {
+    const mismatches = findCrossSourceMismatches([
+      { eventType: 'birth', value: 1874, source: null },
+      { eventType: 'birth', value: 1875, source: null },
+    ], (a, b) => a === b);
+
+    expect(mismatches).toEqual([]);
+  });
+
+  it('suppresses normalized aliases and detail-only place differences', () => {
+    const samePlace = (a: string | number, b: string | number) => {
+      const left = String(a);
+      const right = String(b);
+      return placesMatch(left, right) || placeContains(left, right) || placeContains(right, left);
+    };
+
+    const mismatches = findCrossSourceMismatches([
+      { eventType: 'birth', value: 'Dallas, TX, USA', source: 'familysearch' },
+      { eventType: 'birth', value: 'Dallas, Texas, United States', source: 'ancestry' },
+      { eventType: 'death', value: 'Texas, USA', source: 'familysearch' },
+      { eventType: 'death', value: 'Austin, Texas, United States', source: 'ancestry' },
+    ], samePlace);
+
+    expect(mismatches).toEqual([]);
+  });
+
+  it('reports genuinely different places from different sources', () => {
+    const mismatches = findCrossSourceMismatches([
+      { eventType: 'birth', value: 'Dallas, Texas, USA', source: 'familysearch' },
+      { eventType: 'birth', value: 'Houston, Texas, USA', source: 'ancestry' },
+    ], (a, b) => placesMatch(String(a), String(b)));
+
+    expect(mismatches).toEqual([{
+      eventType: 'birth',
+      details: 'ancestry: Houston, Texas, USA, familysearch: Dallas, Texas, USA',
+    }]);
+  });
+});