fix(persons, resolver): reads coalesce name ?? full_name — import-born rows stop rendering as UUIDs

The Gates Foundation's Deputy Director rendered as a bare UUID: her row
came from the crawlbase/event-CSV import generation, which wrote
full_name (+ first_name/surname) and never name — the field every person
read selects. Measured live: 136 of 1232 persons affected; 39 more have
no name data at all.

Every read point coalesces now — PERSON_FIELDS (candidates + lookups),
person.search (projection, filter, ordering), affiliation.detail, and
organization.affiliations. Proven read-only against the live row: the
affiliations projection returns "Melanie Brown".

Also included: scripts/surreal-backfill-person-names.mjs — the additive
operator-run backfill (fills name from full_name where missing, dry-run
by default, APPLY=1 to write) that makes the fix durable on data.

Closes #28.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UvYzx7vDWeafnkAi2nEQeb

Author: mpstaton

changelog/2026-07-24_03_People-Rows-Show-Names-Not-UUIDs-Two-Generations-Of-Person-Rows-Reconciled.md

@@ -0,0 +1,48 @@
+---
+date_created: 2026-07-24
+date_modified: 2026-07-24
+title: "People rows show names, not UUIDs — two generations of person rows reconciled at the read layer"
+lede: "The Gates Foundation's Deputy Director rendered as a bare UUID: her row was born from the crawlbase/event-CSV import scripts, which wrote full_name and never name — the field every person read selects. All person reads now coalesce name ?? full_name, fixing 136 of 1232 persons at once; the operator-run backfill makes it durable on data."
+publish: true
+authors:
+  - Michael Staton
+augmented_with:
+  - Claude Code on Claude Fable 5
+files_changed:
+  - services/record-surrealdb-resolver/src/person-resolver.ts
+tags:
+  - Org-Workbench
+  - Persons
+  - Canonical-Layer
+  - Usability
+---
+
+# People rows show names, not UUIDs
+
+## The diagnosis ([#28](https://github.com/lossless-group/augment-it/issues/28))
+
+The people reveal fell back to `person_uuid` because the row genuinely had no
+`name` — a live SurrealDB inspection showed the affected person carries
+`full_name: "Melanie Brown"` (+ `first_name`/`surname`) and no `name` at all.
+The persons table has **two generations of rows**: `person.apply`-born rows
+write `name`; the crawlbase LinkedIn and event-CSV import scripts wrote
+`full_name`. Scope, measured live: 1232 persons — 1057 with `name`, **136
+missing it but holding `full_name`**, 39 with no name data of any kind.
+
+## The fix
+
+Every person read in the resolver now projects `name ?? full_name AS name`:
+`PERSON_FIELDS` (candidates scoring + person lookups), `person.search`'s
+autocomplete (projection, filter, and ordering), `affiliation.detail`, and
+`organization.affiliations`. One coalesce per read point; both generations
+display. Proven live read-only: the affiliations projection returns
+`"Melanie Brown"` for the Gates Foundation edge.
+
+## The durable half — operator-run backfill
+
+Filling `name` from `full_name` where missing is a bulk canonical write, so it
+stays operator-run rather than agent-run. The scoped, additive script (fills
+the missing field only, never overwrites) is staged for a scripts/ home; until
+it runs, the coalesce carries the display alone. The 39 rows with no name data
+at all keep showing their UUID — there is nothing to derive a name from; they
+are import stubs awaiting enrichment.

scripts/surreal-backfill-person-names.mjs

@@ -0,0 +1,41 @@
+// Scope + (with APPLY=1) backfill: persons rows missing `name` but holding
+// full_name (or first_name/surname). Additive — fills a missing field only,
+// never overwrites an existing name.
+import { Surreal } from 'surrealdb';
+
+const { SURREAL_URL, SURREAL_NS, SURREAL_DB, SURREAL_USER, SURREAL_PASS, APPLY } = process.env;
+const db = new Surreal();
+await db.connect(SURREAL_URL);
+await db.signin({ username: SURREAL_USER, password: SURREAL_PASS });
+await db.use({ namespace: SURREAL_NS, database: SURREAL_DB });
+
+const counts = await db.query(`
+  RETURN {
+    total: (SELECT VALUE count() FROM persons GROUP ALL)[0],
+    with_name: (SELECT VALUE count() FROM persons WHERE name IS NOT NONE AND name != '' GROUP ALL)[0],
+    missing_name_has_full: (SELECT VALUE count() FROM persons WHERE (name IS NONE OR name = '') AND full_name IS NOT NONE AND full_name != '' GROUP ALL)[0],
+    missing_name_parts_only: (SELECT VALUE count() FROM persons WHERE (name IS NONE OR name = '') AND (full_name IS NONE OR full_name = '') AND first_name IS NOT NONE GROUP ALL)[0],
+    missing_everything: (SELECT VALUE count() FROM persons WHERE (name IS NONE OR name = '') AND (full_name IS NONE OR full_name = '') AND first_name IS NONE GROUP ALL)[0]
+  };
+`);
+console.log('scope:', JSON.stringify(counts?.[0]));
+
+if (APPLY === '1') {
+  const r1 = await db.query(`
+    UPDATE persons SET name = full_name
+      WHERE (name IS NONE OR name = '') AND full_name IS NOT NONE AND full_name != ''
+      RETURN person_uuid, name;
+  `);
+  console.log('backfilled from full_name:', (r1?.[0] ?? []).length);
+  const r2 = await db.query(`
+    UPDATE persons SET name = string::trim(string::concat(first_name ?? '', ' ', surname ?? ''))
+      WHERE (name IS NONE OR name = '') AND (full_name IS NONE OR full_name = '') AND first_name IS NOT NONE
+      RETURN person_uuid, name;
+  `);
+  console.log('backfilled from first+surname:', (r2?.[0] ?? []).length);
+  const check = await db.query(
+    `SELECT VALUE name FROM persons WHERE person_uuid = '019f3b9c-52ac-7a91-b47e-cfab416eb33d';`,
+  );
+  console.log('melanie now:', JSON.stringify(check?.[0]));
+}
+await db.close();

services/record-surrealdb-resolver/src/person-resolver.ts

@@ -43,7 +43,13 @@ type PersonRow = {
   email?: string | null;
 };
 
-const PERSON_FIELDS = 'id, person_uuid, name, headline, linkedin_profile_url, email';
+// `name ?? full_name` — the persons table has two generations of rows:
+// person.apply-born rows write `name`; the crawlbase/event-CSV import
+// scripts wrote `full_name` (+ first_name/surname) and no `name` at all.
+// Every read coalesces so both generations display; the durable fix on
+// data is the name backfill (fills `name` from `full_name` where missing).
+const PERSON_FIELDS =
+  'id, person_uuid, name ?? full_name AS name, headline, linkedin_profile_url, email';
 
 export type PersonCandidate = {
   // Wire-safe handle — NEVER the raw RecordId (SurrealDB RecordIds don't
@@ -176,8 +182,9 @@ export async function searchPersons(
   if (!trimmed || trimmed.length < 2) return { candidates: [] };
   await ensurePersonSchema(db);
   const r = await db.query(
-    `SELECT person_uuid, name, headline FROM persons
-       WHERE client_access CONTAINS $client AND string::lowercase(name) CONTAINS $q
+    `SELECT person_uuid, name ?? full_name AS name, headline FROM persons
+       WHERE client_access CONTAINS $client
+         AND string::lowercase(name ?? full_name ?? '') CONTAINS $q
        ORDER BY name ASC LIMIT 8`,
     { client, q: trimmed },
   );
@@ -734,7 +741,7 @@ export async function getAffiliationDetail(
   input: AffiliationDetailInput,
 ): Promise<AffiliationDetailResult> {
   const personRes = await db.query(
-    `SELECT id, person_uuid, name, personal_links, personal_corpus FROM persons WHERE person_uuid = $u LIMIT 1;`,
+    `SELECT id, person_uuid, name ?? full_name AS name, personal_links, personal_corpus FROM persons WHERE person_uuid = $u LIMIT 1;`,
     { u: input.person_uuid },
   );
   const person = ((personRes?.[0] as PersonDetailRow[]) ?? [])[0];
@@ -861,7 +868,7 @@ export async function listOrgAffiliations(
 
   const affRes = await db.query(
     `SELECT kind, relevance,
-            in.person_uuid AS person_uuid, in.name AS name, in.headline AS headline,
+            in.person_uuid AS person_uuid, in.name ?? in.full_name AS name, in.headline AS headline,
             in.personal_links AS personal_links,
             in.personal_corpus ?? [] AS personal_corpus,
             array::len(in.personal_corpus ?? []) AS personal_corpus_count