From aba969bc1f0355063913db8813e9cef2ba620e91 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Sun, 30 Aug 2026 23:17:29 +0000
Subject: [PATCH] feat: rebuild PostgreSQL query store from JSON (#149)

---
 .changelog/NEXT.md                          |   1 +
 docs/cli.md                                 |   6 +
 docs/development.md                         |  26 +-
 scripts/index.ts                            |  29 +-
 scripts/rebuild.ts                          |  64 ++-
 server/src/lib/json-tree-loader.ts          |  70 +++
 server/src/lib/postgres-person-sync.ts      | 460 ++++++++++++++++++++
 server/src/lib/postgres-writer.ts           | 290 ++++++++++++
 server/src/lib/postgres-writer.types.ts     |  76 ++++
 tests/integration/db/postgresWriter.spec.ts | 232 ++++++++++
 10 files changed, 1239 insertions(+), 15 deletions(-)
 create mode 100644 server/src/lib/json-tree-loader.ts
 create mode 100644 server/src/lib/postgres-person-sync.ts
 create mode 100644 server/src/lib/postgres-writer.ts
 create mode 100644 server/src/lib/postgres-writer.types.ts
 create mode 100644 tests/integration/db/postgresWriter.spec.ts

diff --git a/.changelog/NEXT.md b/.changelog/NEXT.md
index 2ffcff4f..aa27a10b 100644
--- a/.changelog/NEXT.md
+++ b/.changelog/NEXT.md
@@ -14,6 +14,7 @@
 
 ## Internal
 
+- **[issue-149] PostgreSQL JSON rebuild writer** — Family-tree JSON can now populate the staged PostgreSQL query store transactionally and idempotently while preserving canonical identities and leaving SQLite available during migration.
 - **[issue-148] PostgreSQL query-store foundation** — Added a packaged PostgreSQL schema and lazy async connection layer with transactional initialization, health checks, and named parameters, while leaving the current SQLite/JSON runtime unchanged until the staged migration completes.
 - Provider comparison cards no longer emit an invalid nested-`<button>` HTML warning under React 19 (the card header is now a `role="button"` element, keeping click and keyboard toggling).
 - SQLite driver is now loaded lazily so the server can start and serve JSON-backed data even when the native binding is unavailable.
diff --git a/docs/cli.md b/docs/cli.md
index a3c560e5..eef0f8af 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -92,10 +92,16 @@ Remove person files that are not part of SQLite database. Useful for cleaning up
 ```bash
 npx tsx scripts/rebuild.ts DB_ID     # Rebuild specific database
 npx tsx scripts/rebuild.ts --all     # Rebuild all databases
+npx tsx scripts/rebuild.ts DB_ID --max=10
 ```
 
 Re-extract person data from cached JSON files using the latest schema. Useful after code updates that add new fields.
 
+With `DATABASE_URL` set, the command also rebuilds PostgreSQL transactionally by
+walking `data/person/*.json` from `DB_ID`. A specific root can populate a clean
+PostgreSQL store even when no legacy `db-DB_ID.json` exists. Without `DATABASE_URL`,
+the existing JSON/SQLite workflow is unchanged.
+
 ## Data Migration
 
 ### Run Migrations
diff --git a/docs/development.md b/docs/development.md
index ac63e9ee..f9894de7 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -66,17 +66,33 @@ export DATABASE_URL='postgresql://sparsetree:password@localhost:5432/sparsetree'
 pm2 restart ecosystem.config.cjs --update-env
 ```
 
-Credentials are not stored in `ecosystem.config.cjs`. When `DATABASE_URL` is absent
-or unreachable, the PostgreSQL service reports itself unavailable without changing
-the current SQLite/JSON startup behavior. This foundation is not selected by the
-application yet; later migration slices will move writers and readers onto it.
+Credentials are not stored in `ecosystem.config.cjs`. When `DATABASE_URL` is absent,
+indexing and rebuild commands keep their current SQLite/JSON behavior. When it is
+present, the completed JSON graph is also synchronized into PostgreSQL in one
+transaction; application reads still use SQLite/JSON until the later cutover slices.
+An unreachable configured database fails that explicit PostgreSQL write instead of
+silently leaving a partially refreshed query store.
+
+To rebuild a clean PostgreSQL query store directly from the read-only person cache:
+
+```bash
+DATABASE_URL='postgresql://sparsetree:password@localhost:5432/sparsetree' \
+  npx tsx scripts/rebuild.ts FAMILYSEARCH_ROOT_ID
+
+# Limit traversal to the same ancestor depth as an index run
+DATABASE_URL="$DATABASE_URL" npx tsx scripts/rebuild.ts FAMILYSEARCH_ROOT_ID --max=10
+```
+
+The root and its parents are loaded from `data/person/*.json`; no rows are copied
+from `data/sparsetree.db`. Re-running the command updates provider-derived rows in
+place while preserving canonical ULIDs and local rows that reference them.
 
 The PostgreSQL integration test creates and removes a unique schema inside the
 database named by `SPARSETREE_TEST_DATABASE_URL`:
 
 ```bash
 SPARSETREE_TEST_DATABASE_URL="$DATABASE_URL" \
-  npm test -- --run tests/integration/db/postgresSchema.spec.ts
+  npm test -- --run tests/integration/db/postgresWriter.spec.ts
 ```
 
 ## Build
diff --git a/scripts/index.ts b/scripts/index.ts
index 18242c9d..67f0310f 100644
--- a/scripts/index.ts
+++ b/scripts/index.ts
@@ -24,6 +24,7 @@ import { config } from '../server/src/lib/config.js';
 import { sleep } from '../server/src/utils/sleep.js';
 import { randInt } from '../server/src/utils/randInt.js';
 import { sqliteWriter } from '../server/src/lib/sqlite-writer.js';
+import { postgresWriter } from '../server/src/lib/postgres-writer.js';
 import { logPerson } from './utils/logPerson.js';
 import type { Person, Database } from '@fsf/shared';
 
@@ -262,6 +263,22 @@ const saveDB = async (): Promise<void> => {
   const dbId = sqliteWriter.getOrCreatePersonId(selfID, db[selfID]?.name || 'Unknown');
   sqliteWriter.finalizeDatabase(dbId, selfID, db, maxGenerations);
 
+  // PostgreSQL is an explicit staged opt-in. Mirror the complete graph in one
+  // transaction and reuse SQLite's canonical IDs while both stores coexist.
+  if (postgresWriter.isConfigured()) {
+    const canonicalIds = new Map<string, string>();
+    for (const externalId of Object.keys(db)) {
+      const canonicalId = sqliteWriter.getPersonId(externalId);
+      if (canonicalId) canonicalIds.set(externalId, canonicalId);
+    }
+    await postgresWriter.rebuildDatabase({
+      rootExternalId: selfID,
+      database: db,
+      databaseId: dbId,
+      canonicalIds,
+    });
+  }
+
   console.log(
     `finished building ${fileName} with ${
       Object.keys(db).length
@@ -274,13 +291,17 @@ const saveDB = async (): Promise<void> => {
 };
 
 process.on('SIGINT', async () => {
-  await saveDB();
-  sqliteWriter.close();
+  await saveDB().finally(async () => {
+    sqliteWriter.close();
+    await postgresWriter.close();
+  });
   process.exit();
 });
 
-(async () => {
+void (async () => {
   await getPerson(selfID, 0);
   await saveDB();
+})().finally(async () => {
   sqliteWriter.close();
-})();
+  await postgresWriter.close();
+});
diff --git a/scripts/rebuild.ts b/scripts/rebuild.ts
index 4ea22470..1d73ea44 100644
--- a/scripts/rebuild.ts
+++ b/scripts/rebuild.ts
@@ -14,15 +14,19 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import { json2person } from '../server/src/lib/familysearch/transformer.js';
+import { loadFamilySearchTreeFromJson } from '../server/src/lib/json-tree-loader.js';
+import { postgresWriter } from '../server/src/lib/postgres-writer.js';
 import type { Person, Database } from '@fsf/shared';
 
 const argv = yargs(hideBin(process.argv)).argv as {
   _: (string | number)[];
   all?: boolean;
+  max?: number;
 };
 
 const [dbId] = argv._ as string[];
 const rebuildAll = argv.all;
+const requestedMaxGenerations = argv.max === undefined ? undefined : Number(argv.max);
 
 const DATA_DIR = './data';
 const PERSON_DIR = `${DATA_DIR}/person`;
@@ -135,12 +139,48 @@ const rebuildDatabase = (dbPath: string): Database => {
   return db;
 };
 
+const maxGenerationsFromFilename = (filename: string): number => {
+  const match = filename.match(/-(\d+)\.json$/);
+  return match ? Number(match[1]) : Infinity;
+};
+
+/**
+ * Populate PostgreSQL directly from the read-only raw person cache. This path
+ * deliberately does not consult the legacy SQLite database.
+ */
+const rebuildPostgresDatabase = async (
+  rootExternalId: string,
+  maxGenerations: number
+): Promise<void> => {
+  const { database, missingPersonIds } = await loadFamilySearchTreeFromJson({
+    rootExternalId,
+    personDir: PERSON_DIR,
+    maxGenerations,
+  });
+  if (!database[rootExternalId]) {
+    throw new Error(`Root source file not found: ${path.join(PERSON_DIR, `${rootExternalId}.json`)}`);
+  }
+  if (missingPersonIds.length > 0) {
+    console.warn(`  Warning: ${missingPersonIds.length} referenced person file(s) were missing`);
+  }
+
+  const result = await postgresWriter.rebuildDatabase({
+    rootExternalId,
+    database,
+  });
+  console.log(
+    `  PostgreSQL query store rebuilt as ${result.databaseId}: ` +
+    `${result.personCount} persons, ${result.parentEdgeCount} parent edges, ` +
+    `${result.spouseEdgeCount} spouse edges`
+  );
+};
+
 /**
  * Main entry point
  */
-const main = (): void => {
+const main = async (): Promise<void> => {
   if (!rebuildAll && !dbId) {
-    console.error('Usage: npx tsx scripts/rebuild.ts DB_ID  or  npx tsx scripts/rebuild.ts --all');
+    console.error('Usage: npx tsx scripts/rebuild.ts DB_ID [--max=N]  or  npx tsx scripts/rebuild.ts --all');
     process.exit(1);
   }
 
@@ -148,8 +188,14 @@ const main = (): void => {
 
   if (rebuildAll) {
     console.log(`Found ${databases.length} databases to rebuild`);
-    for (const { filename } of databases) {
+    for (const { filename, rootId } of databases) {
       rebuildDatabase(path.join(DATA_DIR, filename));
+      if (postgresWriter.isConfigured()) {
+        await rebuildPostgresDatabase(
+          rootId,
+          requestedMaxGenerations ?? maxGenerationsFromFilename(filename)
+        );
+      }
     }
   } else {
     // Find matching database
@@ -157,17 +203,23 @@ const main = (): void => {
       (d) => d.rootId === dbId || d.filename === `db-${dbId}.json`
     );
 
-    if (!match) {
+    if (!match && !postgresWriter.isConfigured()) {
       console.error(`Database not found for ID: ${dbId}`);
       console.log('Available databases:');
       databases.forEach((d) => console.log(`  - ${d.rootId} (${d.filename})`));
       process.exit(1);
     }
 
-    rebuildDatabase(path.join(DATA_DIR, match.filename));
+    if (match) rebuildDatabase(path.join(DATA_DIR, match.filename));
+    if (postgresWriter.isConfigured()) {
+      await rebuildPostgresDatabase(
+        match?.rootId ?? dbId,
+        requestedMaxGenerations ?? (match ? maxGenerationsFromFilename(match.filename) : Infinity)
+      );
+    }
   }
 
   console.log('\nRebuild complete!');
 };
 
-main();
+void main().finally(() => postgresWriter.close());
diff --git a/server/src/lib/json-tree-loader.ts b/server/src/lib/json-tree-loader.ts
new file mode 100644
index 00000000..98bf9fe3
--- /dev/null
+++ b/server/src/lib/json-tree-loader.ts
@@ -0,0 +1,70 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { Database, Person } from '@fsf/shared';
+// @ts-ignore - the legacy transformer is JavaScript and has no declarations
+import { json2person } from './familysearch/transformer.js';
+
+export interface JsonTreeLoadOptions {
+  rootExternalId: string;
+  personDir?: string;
+  maxGenerations?: number;
+}
+
+export interface JsonTreeLoadResult {
+  database: Database;
+  missingPersonIds: string[];
+}
+
+/**
+ * Rebuild an ancestor graph directly from the raw FamilySearch JSON cache.
+ * Source files are read-only: children are derived on the returned in-memory
+ * graph and are never written back into data/person.
+ */
+export async function loadFamilySearchTreeFromJson({
+  rootExternalId,
+  personDir = path.resolve('data/person'),
+  maxGenerations = Infinity,
+}: JsonTreeLoadOptions): Promise<JsonTreeLoadResult> {
+  const database: Database = {};
+  const missingPersonIds: string[] = [];
+  const visited = new Set<string>();
+  const queue: Array<{ externalId: string; generation: number }> = [
+    { externalId: rootExternalId, generation: 0 },
+  ];
+
+  for (let cursor = 0; cursor < queue.length; cursor++) {
+    const { externalId, generation } = queue[cursor];
+    if (visited.has(externalId) || generation > maxGenerations) continue;
+    visited.add(externalId);
+
+    const sourcePath = path.join(personDir, `${externalId}.json`);
+    const source = await readFile(sourcePath, 'utf8').catch((error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') return undefined;
+      throw error;
+    });
+    if (source === undefined) {
+      missingPersonIds.push(externalId);
+      continue;
+    }
+
+    const person = json2person(JSON.parse(source)) as Person | undefined;
+    if (!person) continue;
+    database[externalId] = person;
+
+    if (generation === maxGenerations) continue;
+    for (const parentId of person.parents) {
+      if (parentId && !visited.has(parentId)) {
+        queue.push({ externalId: parentId, generation: generation + 1 });
+      }
+    }
+  }
+
+  for (const [childId, person] of Object.entries(database)) {
+    for (const parentId of person.parents) {
+      const parent = parentId ? database[parentId] : undefined;
+      if (parent && !parent.children.includes(childId)) parent.children.push(childId);
+    }
+  }
+
+  return { database, missingPersonIds };
+}
diff --git a/server/src/lib/postgres-person-sync.ts b/server/src/lib/postgres-person-sync.ts
new file mode 100644
index 00000000..598ce253
--- /dev/null
+++ b/server/src/lib/postgres-person-sync.ts
@@ -0,0 +1,460 @@
+/** Provider-owned person rows synchronized during a PostgreSQL JSON rebuild. */
+
+import { createHash } from 'node:crypto';
+import type { QueryResultRow } from 'pg';
+import { ulid } from 'ulid';
+import { parseYear } from '../utils/parseYear.js';
+import type {
+  CanonicalIds,
+  PostgresTransaction,
+  ProviderLifeEvent,
+  ProviderNote,
+  WritableDatabase,
+  WritablePerson,
+} from './postgres-writer.types.js';
+
+const SOURCE = 'familysearch';
+const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+
+export interface ExistingIdentityRow extends QueryResultRow {
+  external_id: string;
+  person_id: string;
+}
+
+interface ExistingClaimRow extends QueryResultRow {
+  claim_id: string;
+  predicate: string;
+  value_text: string | null;
+  value_date: string | null;
+}
+
+interface ExistingSourceRow extends QueryResultRow {
+  row_id: string;
+  source_id: string | null;
+}
+
+function preferredCanonicalId(
+  canonicalIds: CanonicalIds | undefined,
+  externalId: string
+): string | undefined {
+  if (!canonicalIds) return undefined;
+  const map = canonicalIds as ReadonlyMap<string, string>;
+  return typeof map.get === 'function'
+    ? map.get(externalId)
+    : (canonicalIds as Readonly<Record<string, string>>)[externalId];
+}
+
+export function resolvePersonIds(
+  externalIds: string[],
+  existingRows: ExistingIdentityRow[],
+  canonicalIds?: CanonicalIds
+): Map<string, string> {
+  const existing = new Map(existingRows.map((row) => [row.external_id, row.person_id]));
+  const result = new Map<string, string>();
+
+  for (const externalId of externalIds) {
+    const current = existing.get(externalId);
+    const preferred = preferredCanonicalId(canonicalIds, externalId);
+    if (preferred && !ULID_PATTERN.test(preferred)) {
+      throw new Error(`Canonical ID for ${externalId} is not a ULID: ${preferred}`);
+    }
+    result.set(externalId, current ?? preferred ?? ulid());
+  }
+
+  return result;
+}
+
+function uniqueStrings(values: Array<string | undefined>): string[] {
+  return [...new Set(values.map((value) => value?.trim()).filter((value): value is string => Boolean(value)))];
+}
+
+function claimKey(predicate: string, valueText: string | null, valueDate: string | null): string {
+  return JSON.stringify([predicate, valueText, valueDate]);
+}
+
+function derivedSourceId(kind: 'fact' | 'note', values: unknown[]): string {
+  const digest = createHash('sha256').update(JSON.stringify(values)).digest('hex');
+  return `derived-${kind}-${digest}`;
+}
+
+function indexIdsBySource(rows: ExistingSourceRow[]): Map<string, string[]> {
+  const idsBySource = new Map<string, string[]>();
+  for (const row of rows) {
+    if (!row.source_id) continue;
+    idsBySource.set(row.source_id, [...(idsBySource.get(row.source_id) ?? []), row.row_id]);
+  }
+  return idsBySource;
+}
+
+function collectClaims(person: WritablePerson): Array<{
+  predicate: string;
+  valueText: string;
+  valueDate: null;
+}> {
+  const claims = new Map<string, { predicate: string; valueText: string; valueDate: null }>();
+  const add = (predicate: string, value: string | undefined): void => {
+    const valueText = value?.trim();
+    if (!valueText) return;
+    claims.set(claimKey(predicate, valueText, null), { predicate, valueText, valueDate: null });
+  };
+
+  for (const occupation of uniqueStrings([...(person.occupations ?? []), person.occupation])) {
+    add('occupation', occupation);
+  }
+  for (const alias of uniqueStrings([
+    ...(person.aliases ?? []),
+    ...(person.alternateNames ?? []),
+    ...(person.marriedNames ?? []),
+  ])) {
+    add('alias', alias);
+  }
+  add('religion', person.religion);
+  add('titleOfNobility', person.titleOfNobility);
+  add('militaryService', person.militaryService);
+  add('causeOfDeath', person.causeOfDeath);
+
+  return [...claims.values()];
+}
+
+async function upsertPerson(
+  tx: PostgresTransaction,
+  externalId: string,
+  personId: string,
+  person: WritablePerson
+): Promise<void> {
+  await tx.run(
+    `INSERT INTO person (person_id, display_name, birth_name, gender, living, bio)
+     VALUES (@personId, @displayName, @birthName, @gender, @living, @bio)
+     ON CONFLICT (person_id) DO UPDATE SET
+       display_name = EXCLUDED.display_name,
+       birth_name = EXCLUDED.birth_name,
+       gender = EXCLUDED.gender,
+       living = EXCLUDED.living,
+       bio = EXCLUDED.bio`,
+    {
+      personId,
+      displayName: person.name,
+      birthName: person.birthName ?? null,
+      gender: person.gender ?? 'unknown',
+      living: person.living,
+      bio: person.bio ?? null,
+    }
+  );
+
+  await tx.run(
+    `INSERT INTO external_identity
+       (person_id, source, external_id, url, confidence, last_seen_at)
+     VALUES (@personId, @source, @externalId, @url, 1.0, CURRENT_TIMESTAMP)
+     ON CONFLICT (source, external_id) DO UPDATE SET
+       person_id = EXCLUDED.person_id,
+       url = EXCLUDED.url,
+       confidence = EXCLUDED.confidence,
+       last_seen_at = EXCLUDED.last_seen_at`,
+    {
+      personId,
+      source: SOURCE,
+      externalId,
+      url: `https://www.familysearch.org/tree/person/details/${externalId}`,
+    }
+  );
+
+  const aliases = uniqueStrings([
+    ...(person.aliases ?? []),
+    ...(person.alternateNames ?? []),
+    ...(person.marriedNames ?? []),
+  ]);
+  const occupations = uniqueStrings([...(person.occupations ?? []), person.occupation]);
+  await tx.run(
+    `INSERT INTO person_search
+       (person_id, display_name, birth_name, aliases, bio, occupations)
+     VALUES (@personId, @displayName, @birthName, @aliases, @bio, @occupations)
+     ON CONFLICT (person_id) DO UPDATE SET
+       display_name = EXCLUDED.display_name,
+       birth_name = EXCLUDED.birth_name,
+       aliases = EXCLUDED.aliases,
+       bio = EXCLUDED.bio,
+       occupations = EXCLUDED.occupations`,
+    {
+      personId,
+      displayName: person.name,
+      birthName: person.birthName ?? '',
+      aliases: aliases.join(' '),
+      bio: person.bio ?? '',
+      occupations: occupations.join(' '),
+    }
+  );
+}
+
+async function syncVitalEvents(
+  tx: PostgresTransaction,
+  personId: string,
+  person: WritablePerson
+): Promise<void> {
+  const events = [
+    ['birth', person.birth],
+    ['death', person.death],
+    ['burial', person.burial],
+  ] as const;
+  const presentTypes: string[] = [];
+
+  for (const [eventType, event] of events) {
+    if (!event) continue;
+    presentTypes.push(eventType);
+    await tx.run(
+      `INSERT INTO vital_event
+         (person_id, event_type, date_original, date_formal, date_year, place, place_id, source, confidence)
+       VALUES
+         (@personId, @eventType, @dateOriginal, @dateFormal, @dateYear, @place, @placeId, @source, 1.0)
+       ON CONFLICT (person_id, event_type, source) DO UPDATE SET
+         date_original = EXCLUDED.date_original,
+         date_formal = EXCLUDED.date_formal,
+         date_year = EXCLUDED.date_year,
+         place = EXCLUDED.place,
+         place_id = EXCLUDED.place_id,
+         confidence = EXCLUDED.confidence`,
+      {
+        personId,
+        eventType,
+        dateOriginal: event.date?.trim() || null,
+        dateFormal: event.dateFormal ?? null,
+        dateYear: parseYear(event.dateFormal ?? event.date),
+        place: event.place ?? null,
+        placeId: event.placeId ?? null,
+        source: SOURCE,
+      }
+    );
+  }
+
+  await tx.run(
+    `DELETE FROM vital_event
+     WHERE person_id = @personId AND source = @source
+       AND NOT (event_type = ANY(@presentTypes::text[]))`,
+    { personId, source: SOURCE, presentTypes }
+  );
+}
+
+async function syncClaims(
+  tx: PostgresTransaction,
+  personId: string,
+  person: WritablePerson
+): Promise<void> {
+  const existing = await tx.queryAll<ExistingClaimRow>(
+    `SELECT claim_id, predicate, value_text, value_date
+     FROM claim WHERE person_id = @personId AND source = @source
+     ORDER BY created_at, claim_id`,
+    { personId, source: SOURCE }
+  );
+  const idsByKey = new Map<string, string[]>();
+  for (const row of existing) {
+    const key = claimKey(row.predicate, row.value_text, row.value_date);
+    idsByKey.set(key, [...(idsByKey.get(key) ?? []), row.claim_id]);
+  }
+
+  const retainedIds: string[] = [];
+  for (const claim of collectClaims(person)) {
+    const key = claimKey(claim.predicate, claim.valueText, claim.valueDate);
+    const claimId = idsByKey.get(key)?.shift() ?? ulid();
+    retainedIds.push(claimId);
+    await tx.run(
+      `INSERT INTO claim
+         (claim_id, person_id, predicate, value_text, value_date, source, confidence)
+       VALUES (@claimId, @personId, @predicate, @valueText, @valueDate, @source, 1.0)
+       ON CONFLICT (claim_id) DO UPDATE SET
+         predicate = EXCLUDED.predicate,
+         value_text = EXCLUDED.value_text,
+         value_date = EXCLUDED.value_date,
+         source = EXCLUDED.source,
+         confidence = EXCLUDED.confidence`,
+      { claimId, personId, ...claim, source: SOURCE }
+    );
+  }
+
+  await tx.run(
+    `DELETE FROM claim
+     WHERE person_id = @personId AND source = @source
+       AND NOT (claim_id = ANY(@retainedIds::text[]))`,
+    { personId, source: SOURCE, retainedIds }
+  );
+}
+
+async function syncLifeEvents(
+  tx: PostgresTransaction,
+  personId: string,
+  events: ProviderLifeEvent[]
+): Promise<void> {
+  const existing = await tx.queryAll<ExistingSourceRow>(
+    `SELECT event_id AS row_id, source_id
+     FROM life_event
+     WHERE person_id = @personId AND source = @source
+     ORDER BY created_at, event_id`,
+    { personId, source: SOURCE }
+  );
+  const idsBySource = indexIdsBySource(existing);
+
+  const retainedIds: string[] = [];
+  for (const event of events) {
+    if (!event.eventType) continue;
+    const sourceId = event.sourceId?.trim() || derivedSourceId('fact', [
+      event.eventType,
+      event.eventRole,
+      event.dateOriginal,
+      event.dateFormal,
+      event.dateYear,
+      event.dateMonth,
+      event.dateDay,
+      event.dateEndYear,
+      event.placeOriginal,
+      event.placeNormalized,
+      event.placeId,
+      event.value,
+      event.description,
+      event.cause,
+    ]);
+    const eventId = idsBySource.get(sourceId)?.shift() ?? ulid();
+    retainedIds.push(eventId);
+    await tx.run(
+      `INSERT INTO life_event (
+         event_id, person_id, event_type, event_role,
+         date_original, date_formal, date_year, date_month, date_day, date_end_year,
+         place_original, place_normalized, place_id,
+         value, description, cause, source, source_id, confidence
+       ) VALUES (
+         @eventId, @personId, @eventType, @eventRole,
+         @dateOriginal, @dateFormal, @dateYear, @dateMonth, @dateDay, @dateEndYear,
+         @placeOriginal, @placeNormalized, @placeId,
+         @value, @description, @cause, @source, @sourceId, 1.0
+       )
+       ON CONFLICT (event_id) DO UPDATE SET
+         event_type = EXCLUDED.event_type,
+         event_role = EXCLUDED.event_role,
+         date_original = EXCLUDED.date_original,
+         date_formal = EXCLUDED.date_formal,
+         date_year = EXCLUDED.date_year,
+         date_month = EXCLUDED.date_month,
+         date_day = EXCLUDED.date_day,
+         date_end_year = EXCLUDED.date_end_year,
+         place_original = EXCLUDED.place_original,
+         place_normalized = EXCLUDED.place_normalized,
+         place_id = EXCLUDED.place_id,
+         value = EXCLUDED.value,
+         description = EXCLUDED.description,
+         cause = EXCLUDED.cause,
+         source = EXCLUDED.source,
+         source_id = EXCLUDED.source_id,
+         confidence = EXCLUDED.confidence`,
+      {
+        eventId,
+        personId,
+        eventType: event.eventType,
+        eventRole: event.eventRole ?? 'principal',
+        dateOriginal: event.dateOriginal ?? null,
+        dateFormal: event.dateFormal ?? null,
+        dateYear: event.dateYear ?? null,
+        dateMonth: event.dateMonth ?? null,
+        dateDay: event.dateDay ?? null,
+        dateEndYear: event.dateEndYear ?? null,
+        placeOriginal: event.placeOriginal ?? null,
+        placeNormalized: event.placeNormalized ?? null,
+        placeId: event.placeId ?? null,
+        value: event.value ?? null,
+        description: event.description ?? null,
+        cause: event.cause ?? null,
+        source: SOURCE,
+        sourceId,
+      }
+    );
+  }
+
+  await tx.run(
+    `DELETE FROM life_event
+     WHERE person_id = @personId AND source = @source
+       AND NOT (event_id = ANY(@retainedIds::text[]))`,
+    { personId, source: SOURCE, retainedIds }
+  );
+}
+
+async function syncNotes(
+  tx: PostgresTransaction,
+  personId: string,
+  notes: ProviderNote[]
+): Promise<void> {
+  const existing = await tx.queryAll<ExistingSourceRow>(
+    `SELECT note_id AS row_id, source_id
+     FROM note
+     WHERE person_id = @personId AND source = @source
+     ORDER BY created_at, note_id`,
+    { personId, source: SOURCE }
+  );
+  const idsBySource = indexIdsBySource(existing);
+
+  const retainedIds: string[] = [];
+  for (const note of notes) {
+    if (!note.content) continue;
+    const sourceId = note.sourceId?.trim() || derivedSourceId('note', [
+      note.noteType,
+      note.title,
+      note.content,
+      note.contentType,
+      note.language,
+      note.author,
+    ]);
+    const noteId = idsBySource.get(sourceId)?.shift() ?? ulid();
+    retainedIds.push(noteId);
+    await tx.run(
+      `INSERT INTO note (
+         note_id, person_id, note_type, title, content, content_type,
+         language, source, source_id, author
+       ) VALUES (
+         @noteId, @personId, @noteType, @title, @content, @contentType,
+         @language, @source, @sourceId, @author
+       )
+       ON CONFLICT (note_id) DO UPDATE SET
+         note_type = EXCLUDED.note_type,
+         title = EXCLUDED.title,
+         content = EXCLUDED.content,
+         content_type = EXCLUDED.content_type,
+         language = EXCLUDED.language,
+         source = EXCLUDED.source,
+         source_id = EXCLUDED.source_id,
+         author = EXCLUDED.author`,
+      {
+        noteId,
+        personId,
+        noteType: note.noteType ?? 'custom',
+        title: note.title ?? null,
+        content: note.content,
+        contentType: note.contentType ?? 'text',
+        language: note.language ?? 'en',
+        source: SOURCE,
+        sourceId,
+        author: note.author ?? null,
+      }
+    );
+  }
+
+  await tx.run(
+    `DELETE FROM note
+     WHERE person_id = @personId AND source = @source
+       AND NOT (note_id = ANY(@retainedIds::text[]))`,
+    { personId, source: SOURCE, retainedIds }
+  );
+}
+
+export async function syncPeople(
+  tx: PostgresTransaction,
+  externalIds: string[],
+  database: WritableDatabase,
+  personIds: Map<string, string>
+): Promise<void> {
+  for (const externalId of externalIds) {
+    await upsertPerson(tx, externalId, personIds.get(externalId)!, database[externalId]);
+  }
+  for (const externalId of externalIds) {
+    const personId = personIds.get(externalId)!;
+    const person = database[externalId];
+    await syncVitalEvents(tx, personId, person);
+    await syncClaims(tx, personId, person);
+    await syncLifeEvents(tx, personId, person.allLifeEvents ?? []);
+    await syncNotes(tx, personId, person.notes ?? []);
+  }
+}
diff --git a/server/src/lib/postgres-writer.ts b/server/src/lib/postgres-writer.ts
new file mode 100644
index 00000000..a8a6b294
--- /dev/null
+++ b/server/src/lib/postgres-writer.ts
@@ -0,0 +1,290 @@
+/**
+ * PostgreSQL writer for the rebuildable Layer 2 query store.
+ *
+ * A complete person graph is synchronized in one transaction. JSON remains
+ * authoritative; provider-owned rows are upserted/pruned while local rows such
+ * as overrides and media keep their foreign keys because canonical person IDs
+ * are reused from external_identity on every rebuild.
+ */
+
+import type { QueryResultRow } from 'pg';
+import { postgresService } from '../db/postgres.service.js';
+import {
+  resolvePersonIds,
+  syncPeople,
+  type ExistingIdentityRow,
+} from './postgres-person-sync.js';
+import type {
+  PostgresRebuildOptions,
+  PostgresRebuildResult,
+  PostgresTransaction,
+  PostgresWriterService,
+  WritableDatabase,
+  WritablePerson,
+} from './postgres-writer.types.js';
+
+export type {
+  PostgresRebuildOptions,
+  PostgresRebuildResult,
+} from './postgres-writer.types.js';
+
+const SOURCE = 'familysearch';
+
+interface ExistingParentEdgeRow extends QueryResultRow {
+  id: string;
+  child_id: string;
+  parent_id: string;
+}
+
+interface ExistingSpouseEdgeRow extends QueryResultRow {
+  id: string;
+  person1_id: string;
+  person2_id: string;
+}
+
+function calculateGenerations(rootExternalId: string, database: WritableDatabase): Map<string, number> {
+  const generations = new Map<string, number>();
+  const queue: Array<{ externalId: string; generation: number }> = [
+    { externalId: rootExternalId, generation: 0 },
+  ];
+
+  for (let cursor = 0; cursor < queue.length; cursor++) {
+    const { externalId, generation } = queue[cursor];
+    if (generations.has(externalId) || !database[externalId]) continue;
+    generations.set(externalId, generation);
+    for (const parentId of database[externalId].parents) {
+      if (parentId && database[parentId] && !generations.has(parentId)) {
+        queue.push({ externalId: parentId, generation: generation + 1 });
+      }
+    }
+  }
+
+  return generations;
+}
+
+async function syncRelationships(
+  tx: PostgresTransaction,
+  database: WritableDatabase,
+  personIds: Map<string, string>
+): Promise<{ parentEdgeCount: number; spouseEdgeCount: number }> {
+  const canonicalIds = [...personIds.values()];
+  const parentEdges = new Map<string, { childId: string; parentId: string; parentRole: string }>();
+  const spouseEdges = new Map<string, { person1Id: string; person2Id: string }>();
+
+  for (const [externalId, person] of Object.entries(database)) {
+    const childId = personIds.get(externalId)!;
+    for (const [index, parentExternalId] of person.parents.entries()) {
+      const parentId = parentExternalId ? personIds.get(parentExternalId) : undefined;
+      if (!parentId) continue;
+      const parentRole = index === 0 ? 'father' : index === 1 ? 'mother' : 'parent';
+      parentEdges.set(`${childId}:${parentId}`, { childId, parentId, parentRole });
+    }
+
+    for (const spouseExternalId of person.spouses ?? []) {
+      const spouseId = personIds.get(spouseExternalId);
+      if (!spouseId || spouseId === childId) continue;
+      const [person1Id, person2Id] = childId < spouseId
+        ? [childId, spouseId]
+        : [spouseId, childId];
+      spouseEdges.set(`${person1Id}:${person2Id}`, { person1Id, person2Id });
+    }
+  }
+
+  // Reconcile only relationships fully represented by this graph. An edge to
+  // a person outside a shallow rebuild may belong to another database view.
+  const existingParents = await tx.queryAll<ExistingParentEdgeRow>(
+    `SELECT id::text, child_id, parent_id
+     FROM parent_edge
+     WHERE source = @source
+       AND child_id = ANY(@personIds::text[])
+       AND parent_id = ANY(@personIds::text[])`,
+    { source: SOURCE, personIds: canonicalIds }
+  );
+  for (const edge of parentEdges.values()) {
+    await tx.run(
+      `INSERT INTO parent_edge (child_id, parent_id, parent_role, confidence, source)
+       VALUES (@childId, @parentId, @parentRole, 1.0, @source)
+       ON CONFLICT (child_id, parent_id) DO UPDATE SET
+         parent_role = EXCLUDED.parent_role,
+         confidence = EXCLUDED.confidence,
+         source = EXCLUDED.source
+       WHERE parent_edge.source IS NULL OR parent_edge.source = EXCLUDED.source`,
+      { ...edge, source: SOURCE }
+    );
+  }
+  const staleParentIds = existingParents
+    .filter((row) => !parentEdges.has(`${row.child_id}:${row.parent_id}`))
+    .map((row) => row.id);
+  if (staleParentIds.length > 0) {
+    await tx.run('DELETE FROM parent_edge WHERE id = ANY(@ids::bigint[])', { ids: staleParentIds });
+  }
+
+  const existingSpouses = await tx.queryAll<ExistingSpouseEdgeRow>(
+    `SELECT id::text, person1_id, person2_id
+     FROM spouse_edge
+     WHERE source = @source
+       AND person1_id = ANY(@personIds::text[])
+       AND person2_id = ANY(@personIds::text[])`,
+    { source: SOURCE, personIds: canonicalIds }
+  );
+  for (const edge of spouseEdges.values()) {
+    await tx.run(
+      `INSERT INTO spouse_edge (person1_id, person2_id, confidence, source)
+       VALUES (@person1Id, @person2Id, 1.0, @source)
+       ON CONFLICT (person1_id, person2_id) DO UPDATE SET
+         confidence = EXCLUDED.confidence,
+         source = EXCLUDED.source
+       WHERE spouse_edge.source IS NULL OR spouse_edge.source = EXCLUDED.source`,
+      { ...edge, source: SOURCE }
+    );
+  }
+  const staleSpouseIds = existingSpouses
+    .filter((row) => !spouseEdges.has(`${row.person1_id}:${row.person2_id}`))
+    .map((row) => row.id);
+  if (staleSpouseIds.length > 0) {
+    await tx.run('DELETE FROM spouse_edge WHERE id = ANY(@ids::bigint[])', { ids: staleSpouseIds });
+  }
+
+  return {
+    parentEdgeCount: parentEdges.size,
+    spouseEdgeCount: spouseEdges.size,
+  };
+}
+
+async function syncDatabaseMembership(
+  tx: PostgresTransaction,
+  databaseId: string,
+  rootExternalId: string,
+  rootPersonId: string,
+  rootPerson: WritablePerson,
+  personIds: Map<string, string>,
+  generations: Map<string, number>,
+  isSample: boolean
+): Promise<void> {
+  let actualMaxGeneration = 0;
+  for (const generation of generations.values()) {
+    actualMaxGeneration = Math.max(actualMaxGeneration, generation);
+  }
+  await tx.run(
+    `INSERT INTO database_info (
+       db_id, root_id, root_name, source_provider, max_generations,
+       person_count, is_sample, updated_at
+     ) VALUES (
+       @databaseId, @rootPersonId, @rootName, @source,
+       @maxGenerations, @personCount, @isSample, CURRENT_TIMESTAMP
+     )
+     ON CONFLICT (db_id) DO UPDATE SET
+       root_id = EXCLUDED.root_id,
+       root_name = EXCLUDED.root_name,
+       source_provider = EXCLUDED.source_provider,
+       max_generations = EXCLUDED.max_generations,
+       person_count = EXCLUDED.person_count,
+       is_sample = EXCLUDED.is_sample,
+       updated_at = CURRENT_TIMESTAMP`,
+    {
+      databaseId,
+      rootPersonId,
+      rootName: rootPerson.name,
+      source: SOURCE,
+      maxGenerations: actualMaxGeneration,
+      personCount: personIds.size,
+      isSample,
+    }
+  );
+
+  for (const [externalId, personId] of personIds) {
+    await tx.run(
+      `INSERT INTO database_membership (db_id, person_id, is_root, generation)
+       VALUES (@databaseId, @personId, @isRoot, @generation)
+       ON CONFLICT (db_id, person_id) DO UPDATE SET
+         is_root = EXCLUDED.is_root,
+         generation = EXCLUDED.generation`,
+      {
+        databaseId,
+        personId,
+        isRoot: externalId === rootExternalId,
+        generation: generations.get(externalId) ?? 0,
+      }
+    );
+  }
+
+  await tx.run(
+    `DELETE FROM database_membership
+     WHERE db_id = @databaseId
+       AND NOT (person_id = ANY(@personIds::text[]))`,
+    { databaseId, personIds: [...personIds.values()] }
+  );
+}
+
+export function createPostgresWriter(service: PostgresWriterService = postgresService) {
+  const isConfigured = (): boolean => service.isConfigured();
+
+  const rebuildDatabase = async ({
+    rootExternalId,
+    database: inputDatabase,
+    databaseId: requestedDatabaseId,
+    canonicalIds,
+    isSample = false,
+  }: PostgresRebuildOptions): Promise<PostgresRebuildResult> => {
+    const database = inputDatabase as WritableDatabase;
+    const externalIds = Object.keys(database);
+    const rootPerson = database[rootExternalId];
+    if (!rootPerson) {
+      throw new Error(`Cannot rebuild PostgreSQL: root ${rootExternalId} is missing from the JSON graph`);
+    }
+    if (!isConfigured()) {
+      throw new Error('PostgreSQL is not configured; set DATABASE_URL before rebuilding the query store');
+    }
+
+    await service.initDb();
+    return service.transaction(async (tx) => {
+      // Natural-key rows such as provider claims/events predate dedicated
+      // uniqueness constraints. Serialize rebuilds so two processes cannot
+      // both observe an empty key and mint different ULIDs for the same fact.
+      await tx.run(
+        'SELECT pg_advisory_xact_lock(hashtext(@lockName))',
+        { lockName: 'sparsetree:json-rebuild' }
+      );
+      const existingIdentities = await tx.queryAll<ExistingIdentityRow>(
+        `SELECT external_id, person_id
+         FROM external_identity
+         WHERE source = @source AND external_id = ANY(@externalIds::text[])`,
+        { source: SOURCE, externalIds }
+      );
+      const personIds = resolvePersonIds(externalIds, existingIdentities, canonicalIds);
+      const rootPersonId = personIds.get(rootExternalId)!;
+      const databaseId = requestedDatabaseId ?? rootPersonId;
+      const generations = calculateGenerations(rootExternalId, database);
+
+      await syncPeople(tx, externalIds, database, personIds);
+      const relationshipCounts = await syncRelationships(tx, database, personIds);
+      await syncDatabaseMembership(
+        tx,
+        databaseId,
+        rootExternalId,
+        rootPersonId,
+        rootPerson,
+        personIds,
+        generations,
+        isSample
+      );
+
+      return {
+        databaseId,
+        rootPersonId,
+        personIds,
+        personCount: externalIds.length,
+        ...relationshipCounts,
+      };
+    });
+  };
+
+  return {
+    isConfigured,
+    init: service.initDb,
+    close: service.closeDb,
+    rebuildDatabase,
+  };
+}
+
+export const postgresWriter = createPostgresWriter();
diff --git a/server/src/lib/postgres-writer.types.ts b/server/src/lib/postgres-writer.types.ts
new file mode 100644
index 00000000..f090701f
--- /dev/null
+++ b/server/src/lib/postgres-writer.types.ts
@@ -0,0 +1,76 @@
+import type { Database, Person } from '@fsf/shared';
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { QueryParams } from '../db/postgres.service.js';
+
+export type CanonicalIds = ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+
+export interface ProviderLifeEvent {
+  eventType: string;
+  eventRole?: string;
+  sourceId?: string;
+  dateOriginal?: string;
+  dateFormal?: string;
+  dateYear?: number;
+  dateMonth?: number;
+  dateDay?: number;
+  dateEndYear?: number;
+  placeOriginal?: string;
+  placeNormalized?: string;
+  placeId?: string;
+  value?: string;
+  description?: string;
+  cause?: string;
+}
+
+export interface ProviderNote {
+  noteType?: string;
+  title?: string;
+  content: string;
+  contentType?: string;
+  language?: string;
+  sourceId?: string;
+  author?: string;
+}
+
+export interface WritablePerson extends Person {
+  titleOfNobility?: string;
+  militaryService?: string;
+  causeOfDeath?: string;
+  allLifeEvents?: ProviderLifeEvent[];
+  notes?: ProviderNote[];
+}
+
+export type WritableDatabase = Record<string, WritablePerson>;
+
+export interface PostgresTransaction {
+  queryAll<Row extends QueryResultRow>(sql: string, params?: QueryParams): Promise<Row[]>;
+  queryOne<Row extends QueryResultRow>(sql: string, params?: QueryParams): Promise<Row | undefined>;
+  run<Row extends QueryResultRow = QueryResultRow>(
+    sql: string,
+    params?: QueryParams
+  ): Promise<QueryResult<Row>>;
+}
+
+export interface PostgresWriterService {
+  isConfigured(): boolean;
+  initDb(): Promise<void>;
+  closeDb(): Promise<void>;
+  transaction<T>(work: (tx: PostgresTransaction) => Promise<T>): Promise<T>;
+}
+
+export interface PostgresRebuildOptions {
+  rootExternalId: string;
+  database: Database | WritableDatabase;
+  databaseId?: string;
+  canonicalIds?: CanonicalIds;
+  isSample?: boolean;
+}
+
+export interface PostgresRebuildResult {
+  databaseId: string;
+  rootPersonId: string;
+  personIds: Map<string, string>;
+  personCount: number;
+  parentEdgeCount: number;
+  spouseEdgeCount: number;
+}
diff --git a/tests/integration/db/postgresWriter.spec.ts b/tests/integration/db/postgresWriter.spec.ts
new file mode 100644
index 00000000..81f1658a
--- /dev/null
+++ b/tests/integration/db/postgresWriter.spec.ts
@@ -0,0 +1,232 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Pool } from 'pg';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createPostgresService } from '../../../server/src/db/postgres.service.js';
+import { loadFamilySearchTreeFromJson } from '../../../server/src/lib/json-tree-loader.js';
+import { createPostgresWriter } from '../../../server/src/lib/postgres-writer.js';
+import { createFamilySearchResponse } from '../../utils/fixtures.js';
+
+const connectionString = process.env.SPARSETREE_TEST_DATABASE_URL;
+const describePostgres = connectionString ? describe : describe.skip;
+
+const count = async (
+  service: ReturnType<typeof createPostgresService>,
+  table: string
+): Promise<number> => {
+  const row = await service.queryOne<{ count: string }>(`SELECT COUNT(*)::text AS count FROM ${table}`);
+  return Number(row?.count ?? 0);
+};
+
+describePostgres('PostgreSQL JSON rebuild writer', () => {
+  const schemaName = `sparsetree_writer_${process.pid}_${Date.now()}`;
+  const quotedSchema = `"${schemaName}"`;
+  let adminPool: Pool;
+  let service: ReturnType<typeof createPostgresService>;
+  let writer: ReturnType<typeof createPostgresWriter>;
+  let personDir: string;
+
+  beforeAll(async () => {
+    adminPool = new Pool({ connectionString, application_name: 'sparsetree-writer-admin-test' });
+    await adminPool.query(`CREATE SCHEMA ${quotedSchema}`);
+    const pool = new Pool({
+      connectionString,
+      application_name: 'sparsetree-writer-test',
+      options: `-c search_path=${schemaName}`,
+    });
+    service = createPostgresService({ pool });
+    writer = createPostgresWriter(service);
+    personDir = await mkdtemp(path.join(os.tmpdir(), 'sparsetree-person-json-'));
+
+    const fixtures = {
+      'ROOT-001': createFamilySearchResponse({
+        id: 'ROOT-001',
+        name: 'Root Person',
+        parents: ['PARENT-001', 'PARENT-002'],
+        occupation: 'Cartographer',
+        bio: 'Mapped the family tree.',
+      }),
+      'PARENT-001': createFamilySearchResponse({
+        id: 'PARENT-001',
+        name: 'First Parent',
+        gender: 'Male',
+      }),
+      'PARENT-002': createFamilySearchResponse({
+        id: 'PARENT-002',
+        name: 'Second Parent',
+        gender: 'Female',
+      }),
+    };
+    await Promise.all(Object.entries(fixtures).map(([id, fixture]) =>
+      writeFile(path.join(personDir, `${id}.json`), JSON.stringify(fixture, null, 2))
+    ));
+  });
+
+  afterAll(async () => {
+    if (writer) await writer.close();
+    if (adminPool) {
+      await adminPool.query(`DROP SCHEMA IF EXISTS ${quotedSchema} CASCADE`);
+      await adminPool.end();
+    }
+    if (personDir) await rm(personDir, { recursive: true, force: true });
+  });
+
+  it('rebuilds a raw JSON tree idempotently without changing the source files', async () => {
+    const sourcePaths = ['ROOT-001', 'PARENT-001', 'PARENT-002']
+      .map((id) => path.join(personDir, `${id}.json`));
+    const sourceBefore = await Promise.all(sourcePaths.map((sourcePath) => readFile(sourcePath, 'utf8')));
+    const loaded = await loadFamilySearchTreeFromJson({
+      rootExternalId: 'ROOT-001',
+      personDir,
+    });
+
+    expect(loaded.missingPersonIds).toEqual([]);
+    expect(Object.keys(loaded.database)).toHaveLength(3);
+    expect(loaded.database['PARENT-001'].children).toEqual(['ROOT-001']);
+
+    const canonicalIds = new Map([
+      ['ROOT-001', '01ARZ3NDEKTSV4RRFFQ69G5FAV'],
+      ['PARENT-001', '01ARZ3NDEKTSV4RRFFQ69G5FAW'],
+      ['PARENT-002', '01ARZ3NDEKTSV4RRFFQ69G5FAX'],
+    ]);
+    const first = await writer.rebuildDatabase({
+      rootExternalId: 'ROOT-001',
+      database: loaded.database,
+      canonicalIds,
+    });
+    const identityIds = await service.queryAll<{ external_id: string; person_id: string }>(
+      'SELECT external_id, person_id FROM external_identity ORDER BY external_id'
+    );
+    const claimIds = await service.queryAll<{ claim_id: string }>(
+      'SELECT claim_id FROM claim ORDER BY claim_id'
+    );
+    const eventIds = await service.queryAll<{ event_id: string }>(
+      'SELECT event_id FROM life_event ORDER BY event_id'
+    );
+    const noteIds = await service.queryAll<{ note_id: string }>(
+      'SELECT note_id FROM note ORDER BY note_id'
+    );
+    const rootPersonId = canonicalIds.get('ROOT-001')!;
+    const firstParentId = canonicalIds.get('PARENT-001')!;
+    await service.run(
+      `INSERT INTO media (media_id, person_id, source, caption)
+       VALUES (@mediaId, @personId, 'local', 'Preserved portrait')`,
+      { mediaId: '01ARZ3NDEKTSV4RRFFQ69G5FAY', personId: rootPersonId }
+    );
+    await service.run(
+      `UPDATE parent_edge
+       SET source = 'local', parent_role = 'parent'
+       WHERE child_id = @childId AND parent_id = @parentId`,
+      { childId: rootPersonId, parentId: firstParentId }
+    );
+
+    const second = await writer.rebuildDatabase({
+      rootExternalId: 'ROOT-001',
+      database: loaded.database,
+    });
+
+    expect(second.databaseId).toBe(first.databaseId);
+    expect(identityIds).toEqual([
+      { external_id: 'PARENT-001', person_id: canonicalIds.get('PARENT-001') },
+      { external_id: 'PARENT-002', person_id: canonicalIds.get('PARENT-002') },
+      { external_id: 'ROOT-001', person_id: canonicalIds.get('ROOT-001') },
+    ]);
+    expect(await count(service, 'person')).toBe(3);
+    expect(await count(service, 'external_identity')).toBe(3);
+    expect(await count(service, 'parent_edge')).toBe(2);
+    expect(await count(service, 'database_membership')).toBe(3);
+    expect(await count(service, 'database_info')).toBe(1);
+    expect(await count(service, 'person_search')).toBe(3);
+    expect(await count(service, 'claim')).toBeGreaterThan(0);
+    expect(await service.queryAll('SELECT external_id, person_id FROM external_identity ORDER BY external_id'))
+      .toEqual(identityIds);
+    expect(await service.queryAll('SELECT claim_id FROM claim ORDER BY claim_id')).toEqual(claimIds);
+    expect(await service.queryAll('SELECT event_id FROM life_event ORDER BY event_id')).toEqual(eventIds);
+    expect(await service.queryAll('SELECT note_id FROM note ORDER BY note_id')).toEqual(noteIds);
+    expect(await service.queryOne(
+      `SELECT media_id, person_id, source, caption FROM media
+       WHERE media_id = '01ARZ3NDEKTSV4RRFFQ69G5FAY'`
+    )).toEqual({
+      media_id: '01ARZ3NDEKTSV4RRFFQ69G5FAY',
+      person_id: rootPersonId,
+      source: 'local',
+      caption: 'Preserved portrait',
+    });
+    expect(await service.queryOne(
+      `SELECT parent_role, source FROM parent_edge
+       WHERE child_id = @childId AND parent_id = @parentId`,
+      { childId: rootPersonId, parentId: firstParentId }
+    )).toEqual({ parent_role: 'parent', source: 'local' });
+
+    const memberships = await service.queryAll<{ external_id: string; generation: number; is_root: boolean }>(
+      `SELECT external_identity.external_id, database_membership.generation, database_membership.is_root
+       FROM database_membership
+       JOIN external_identity USING (person_id)
+       ORDER BY external_identity.external_id`
+    );
+    expect(memberships).toEqual([
+      { external_id: 'PARENT-001', generation: 1, is_root: false },
+      { external_id: 'PARENT-002', generation: 1, is_root: false },
+      { external_id: 'ROOT-001', generation: 0, is_root: true },
+    ]);
+    expect(await Promise.all(sourcePaths.map((sourcePath) => readFile(sourcePath, 'utf8'))))
+      .toEqual(sourceBefore);
+  });
+
+  it('rolls back the entire person graph when one row in the batch fails', async () => {
+    await service.run(`
+      CREATE FUNCTION sparsetree_reject_failure_fixture()
+      RETURNS TRIGGER LANGUAGE plpgsql AS $$
+      BEGIN
+        IF NEW.display_name = 'Rollback Failure' THEN
+          RAISE EXCEPTION 'forced rebuild failure';
+        END IF;
+        RETURN NEW;
+      END;
+      $$;
+      CREATE TRIGGER trg_reject_failure_fixture
+      BEFORE INSERT OR UPDATE ON person
+      FOR EACH ROW EXECUTE FUNCTION sparsetree_reject_failure_fixture();
+    `);
+
+    const failureDir = await mkdtemp(path.join(os.tmpdir(), 'sparsetree-failing-json-'));
+    await Promise.all([
+      writeFile(
+        path.join(failureDir, 'FAIL-ROOT.json'),
+        JSON.stringify(createFamilySearchResponse({
+          id: 'FAIL-ROOT',
+          name: 'Rollback Root',
+          parents: ['FAIL-PARENT'],
+        }))
+      ),
+      writeFile(
+        path.join(failureDir, 'FAIL-PARENT.json'),
+        JSON.stringify(createFamilySearchResponse({
+          id: 'FAIL-PARENT',
+          name: 'Rollback Failure',
+        }))
+      ),
+    ]);
+    const loaded = await loadFamilySearchTreeFromJson({
+      rootExternalId: 'FAIL-ROOT',
+      personDir: failureDir,
+    });
+
+    await expect(writer.rebuildDatabase({
+      rootExternalId: 'FAIL-ROOT',
+      database: loaded.database,
+    })).rejects.toThrow('forced rebuild failure');
+
+    expect(await count(service, 'person')).toBe(3);
+    expect(await service.queryAll(
+      `SELECT external_id FROM external_identity
+       WHERE external_id = ANY(@externalIds::text[])`,
+      { externalIds: ['FAIL-ROOT', 'FAIL-PARENT'] }
+    )).toEqual([]);
+
+    await rm(failureDir, { recursive: true, force: true });
+    await service.run('DROP TRIGGER trg_reject_failure_fixture ON person');
+    await service.run('DROP FUNCTION sparsetree_reject_failure_fixture()');
+  });
+});