fix(person-db-resolver): editable person name, observation predicate optional — People-CSV flow basic-functioning

The first live click-through of person-db-resolver against real FreedomFest
2026 records surfaced two dead ends. The person-name input looked editable
but silently reset itself on every keystroke. The "add observation" button
stayed disabled unless a predicate field — never explained in the UI — was
also filled in.

The name-field bug was a Svelte 5 reactivity feedback loop: the row-change
effect that resets the name field also kicked off a candidate search that
transitively read the very `$derived` value built from that field. Svelte's
dependency tracking attributed that transitive read to the effect, so every
keystroke re-triggered the row-change effect, which reset what was just
typed. Fixed by splitting the shared load function into a row-change variant
(reads only the plain `record`) and an input-onchange variant (safe to read
the derived `personRecord`). Same split applied to the org-name input, which
carried the identical latent bug.

Observations now only require a value — `predicate` is optional and
defaults to `note`, so the form isn't dead when an operator just wants to
leave a quick note.

Files changed:
- apps/person-db-resolver/src/App.svelte

Also included:
- changelog/2026-07-07_04_People-CSV-Flow-Goes-From-Wired-Up-To-Actually-Usable.md

Author: mpstaton

apps/person-db-resolver/src/App.svelte

@@ -24,6 +24,7 @@
   } from './lib/resolver-client';
   import type {
     FieldMapping,
+    PersonNormRecord,
     PersonCandidate,
     PersonApplyResult,
     OrgCandidate,
@@ -54,6 +55,7 @@
   let personError = $state<string | null>(null);
   let personResult = $state<PersonApplyResult | null>(null);
   let personBusy = $state(false);
+  let personNameInput = $state('');
   let personSearchQuery = $state('');
   let personSearchResults = $state<PersonCandidate[]>([]);
   let personSearching = $state(false);
@@ -84,6 +86,13 @@
     current && mapping ? normalizePersonRecord(current.fields as Record<string, unknown>, mapping) : null,
   );
   const source = $derived(selectedSet ? `record-set:${selectedSet.name}` : 'person-db-resolver');
+  // The person actions (candidates/create/match) use the OPERATOR-EDITED
+  // name, not the raw mapped column — record.name stays visible in
+  // RecordCard as "here's what the CSV said," personNameInput is what
+  // actually gets written. Falls back to the mapped name if cleared.
+  const personRecord = $derived(
+    record ? { ...record, name: personNameInput.trim() || record.name } : null,
+  );
 
   function onActiveRecordSetChange(e: Event) {
     const detail = (e as CustomEvent).detail as { record_set_id?: string } | undefined;
@@ -199,23 +208,33 @@
     obsSaved = false;
   }
 
-  // Load person candidates whenever the current record changes.
+  // Load person candidates whenever the current record changes. Also resets
+  // the editable name input to the mapped column's value for the new row.
+  //
+  // IMPORTANT: this effect must only read `record`/`current` — NOT
+  // `personRecord`/`personNameInput`, even transitively. An earlier version
+  // called loadPersonCandidates() here, which synchronously read the
+  // personRecord derived (itself reading personNameInput) before its first
+  // await — that read got tracked as a dependency of THIS effect, so every
+  // keystroke in the name field re-triggered the row-change effect, which
+  // immediately reset the field back to the mapped value. Un-editable input.
   $effect(() => {
     const rid = current?.row_id;
     const rec = record;
     if (!rid || !rec || !rec.name) {
       personCandidates = [];
       return;
     }
-    void loadPersonCandidates();
+    personNameInput = rec.name;
+    void loadPersonCandidatesFor(rec);
   });
 
-  async function loadPersonCandidates() {
-    if (!record || !record.name) return;
+  async function loadPersonCandidatesFor(rec: PersonNormRecord) {
+    if (!rec.name) return;
     loadingPerson = true;
     personError = null;
     try {
-      personCandidates = await fetchPersonCandidates(record, client);
+      personCandidates = await fetchPersonCandidates(rec, client);
     } catch (err) {
       personError = err instanceof Error ? err.message : String(err);
       personCandidates = [];
@@ -224,29 +243,37 @@
     }
   }
 
+  // Called from the name input's onchange (a DOM event handler, not a
+  // reactive effect) — safe to read personRecord here.
+  async function loadPersonCandidates() {
+    if (!personRecord) return;
+    await loadPersonCandidatesFor(personRecord);
+  }
+
   // Independent of person state — per the "independent decisions" design
   // (person and org are mutually independent OR interdependent, operator's
   // choice), the org section is always live, not gated behind personResult.
+  // Same "don't transitively read the input you just wrote" rule as above.
   $effect(() => {
     const rec = record;
     if (!rec) {
       orgCandidates = [];
       return;
     }
     orgNameInput = rec.org_name ?? '';
-    void loadOrgCandidates();
+    void loadOrgCandidatesFor(rec.org_name ?? '');
   });
 
-  async function loadOrgCandidates() {
-    const name = orgNameInput.trim();
-    if (!name) {
+  async function loadOrgCandidatesFor(name: string) {
+    const trimmed = name.trim();
+    if (!trimmed) {
       orgCandidates = [];
       return;
     }
     loadingOrg = true;
     orgError = null;
     try {
-      orgCandidates = await fetchOrgCandidates(name, client);
+      orgCandidates = await fetchOrgCandidates(trimmed, client);
     } catch (err) {
       orgError = err instanceof Error ? err.message : String(err);
       orgCandidates = [];
@@ -255,12 +282,17 @@
     }
   }
 
+  // Called from the org-name input's onchange — safe to read orgNameInput here.
+  async function loadOrgCandidates() {
+    await loadOrgCandidatesFor(orgNameInput);
+  }
+
   async function doMatchPerson(c: PersonCandidate) {
-    if (!record) return;
+    if (!personRecord) return;
     personBusy = true;
     personError = null;
     try {
-      personResult = await applyPerson({ action: 'match', person_uuid: c.person_uuid, record, client, source });
+      personResult = await applyPerson({ action: 'match', person_uuid: c.person_uuid, record: personRecord, client, source });
     } catch (err) {
       personError = err instanceof Error ? err.message : String(err);
     } finally {
@@ -269,11 +301,11 @@
   }
 
   async function doCreatePerson() {
-    if (!record) return;
+    if (!personRecord || !personRecord.name) return;
     personBusy = true;
     personError = null;
     try {
-      personResult = await applyPerson({ action: 'create', record, client, source });
+      personResult = await applyPerson({ action: 'create', record: personRecord, client, source });
     } catch (err) {
       personError = err instanceof Error ? err.message : String(err);
     } finally {
@@ -378,9 +410,11 @@
 
   async function doAddObservation() {
     if (!personResult) return;
-    const predicate = obsPredicate.trim();
+    // Only the value is required — predicate defaults to a generic 'note'
+    // so the button isn't dead just because the operator only typed a value.
+    const predicate = obsPredicate.trim() || 'note';
     const value = obsValue.trim();
-    if (!predicate || !value) return;
+    if (!value) return;
     obsBusy = true;
     obsError = null;
     obsSaved = false;
@@ -458,9 +492,13 @@
           {#if personError}<div class="pdr-error">candidates: {personError}</div>{/if}
 
           {#if !personResult && !personSkipped}
+            <label class="pdr-org-name-row">
+              <span>person name</span>
+              <input type="text" bind:value={personNameInput} onchange={() => void loadPersonCandidates()} placeholder="Person name" />
+            </label>
             <PersonCandidateList candidates={personCandidates} busy={personBusy} onMatch={doMatchPerson} />
             <div class="pdr-create">
-              <button type="button" class="pdr-btn pdr-btn-create" disabled={personBusy || !record.name} onclick={doCreatePerson}>
+              <button type="button" class="pdr-btn pdr-btn-create" disabled={personBusy || !personRecord?.name} onclick={doCreatePerson}>
                 + create new person from this record
               </button>
               <button type="button" class="pdr-btn" disabled={personBusy} onclick={doSkipPerson}>
@@ -500,9 +538,9 @@
                 {personResult.created ? '✓ created' : '✓ matched'} <strong>{personResult.name}</strong>
               </div>
               <div class="pdr-add-obs">
-                <label><span>predicate</span><input type="text" bind:value={obsPredicate} placeholder="e.g. confirmed_via_email" /></label>
+                <label><span>predicate (optional)</span><input type="text" bind:value={obsPredicate} placeholder="defaults to 'note'" /></label>
                 <label><span>value</span><input type="text" bind:value={obsValue} placeholder="e.g. confirmed 2026-07-07" /></label>
-                <button type="button" class="pdr-btn" disabled={obsBusy || !obsPredicate.trim() || !obsValue.trim()} onclick={doAddObservation}>
+                <button type="button" class="pdr-btn" disabled={obsBusy || !obsValue.trim()} onclick={doAddObservation}>
                   + add observation
                 </button>
                 {#if obsSaved}<span class="pdr-stamp-ok">✓ saved</span>{/if}

changelog/2026-07-07_04_People-CSV-Flow-Goes-From-Wired-Up-To-Actually-Usable.md

@@ -0,0 +1,96 @@
+---
+date_created: 2026-07-07
+date_modified: 2026-07-07
+title: "The People-CSV Flow Goes From Wired-Up to Actually Usable"
+lede: "person-db-resolver shipped a few hours ago wired end to end — but the name field couldn't be typed into, and the observation form refused to save unless you filled in a predicate nobody was prompted for. Both are fixed. Improve a CSV of People is now basic-functioning: pick a record, edit the name, match or create the person, match or create the org, drop a note."
+publish: true
+authors:
+  - Michael Staton
+augmented_with:
+  - Claude Code on Claude Sonnet 5
+files_changed:
+  - apps/person-db-resolver/src/App.svelte
+tags:
+  - Progress-Update
+  - Person-DB-Resolver
+  - Svelte-5
+  - Reactivity
+  - Canonical-Layer
+  - Reach-Edu
+  - FreedomFest
+---
+
+## Why Care?
+
+`person-db-resolver` [[2026-07-07_03_Person-DB-Resolver-A-Sibling-Remote-For-People-Not-Orgs|shipped earlier tonight]]
+with the right shape — person and org as independent match-or-create
+decisions — but the first live click-through against real FreedomFest 2026
+records surfaced two dead ends: the person-name input looked editable but
+reset itself after every keystroke, and the "add observation" button stayed
+disabled unless you typed something into a `predicate` field the UI never
+explained. Both are fixed now. The **Improve a CSV of People** flow is at
+basic-functioning: an operator can run a real record through match/create/
+skip for both person and org, and leave a note, without fighting the form.
+
+## What's New?
+
+- **The person-name field is actually editable.** A CSV's mapped name column
+  isn't always what should get written — a "Lyn" needs to become "Lynette
+  Ulbricht," a title needs trimming out of a name column. That's now a real
+  input, not a read-only echo of the mapped value.
+- **Observations no longer require a predicate.** The form asked for
+  `predicate` + `value` with no explanation of what a predicate even was;
+  half the time the operator just wants to jot a note. The value field alone
+  now unlocks the button — `predicate` is optional and defaults to `note`.
+
+## The Story
+
+The name-field bug was the interesting one. It didn't fail loudly — the
+input rendered, accepted keystrokes, and then silently reverted to the
+CSV's original value on every single one, making it look broken rather than
+explaining why.
+
+The cause was a feedback loop hiding inside Svelte 5's fine-grained
+reactivity. The effect that resets the name field when the operator moves to
+a new record also kicked off the person-candidate search — and that search
+function read a `$derived` value (`personRecord`) that itself read the very
+input the effect was about to reset. Svelte's dependency tracking doesn't
+care where in a function body a read happens, only that it happened during
+the effect's synchronous execution — so that one transitive read got
+attributed to the row-change effect, not to the keystroke that actually
+should have triggered it. Every keystroke re-ran the row-change effect,
+which reset the field it was just typed into.
+
+```mermaid
+flowchart LR
+    A[operator types a letter] --> B[personNameInput updates]
+    B --> C[personRecord derived recomputes]
+    C --> D["row-change $effect (wrongly) re-fires"]
+    D --> E[personNameInput reset to CSV value]
+    E -.->|next keystroke, same loop| A
+```
+
+The fix: split the one function that read `personRecord` into two. The
+row-change effect now calls `loadPersonCandidatesFor(rec)`, which only ever
+touches the plain `record` the effect is already watching — no transitive
+read of the input. A separate `loadPersonCandidates()` (no arguments) is
+wired to the input's own `onchange`, where reading `personRecord` is exactly
+what should happen. Same split applied to the org-name input, which had the
+identical latent bug waiting to bite the next person who typed into it.
+
+## What's Next
+
+Basic-functioning isn't done-functioning — the flow still doesn't
+retroactively `RELATE` an affiliation if the org gets resolved before the
+person on the same row (documented as an open question in the prior entry).
+The next real step, per
+[[../context-v/plans/SurrealDB-MCP-Plus-Skill-for-Canonical-Layer-Verification|the SurrealDB MCP + verification-skill plan]],
+is standing up direct query access to the canonical layer so tonight's
+FreedomFest batch (and every batch after it) can be checked for coherence
+without another disposable Node script.
+
+## Related
+
+- [[2026-07-07_03_Person-DB-Resolver-A-Sibling-Remote-For-People-Not-Orgs]] — the remote this flow lives in
+- `context-v/plans/Person-Aware-Canonical-Resolver-Extension.md` — the design this implements
+- `context-v/plans/SurrealDB-MCP-Plus-Skill-for-Canonical-Layer-Verification.md` — the next step