feat(faces): let the photographer choose which photo represents a person (#1119)

Phase 1 of #1096.

Clustering picks the cover, and its idea of a good one and a human's do not
always agree. A cluster whose avatar is turned away or softer than the rest
stays that way in the guest-facing people strip too, and nothing in the UI
could change it.

A picker reachable from each person row, reusing the face list the split
dialog already loads — same query, same grid, different action on a click.

Making the choice actually stick took four changes
---------------------------------------------------------------------------
event_people.cover_face_id has existed since migration 177 and the PATCH
already accepted it, so the first version of this was frontend-only. It was
also a no-op:

- facePeopleService.listPeople SELECTED cover_face_id and then discarded it,
  recomputing the cover as the best-scoring VISIBLE face on every read. The
  picker saved, said so, and the avatar reverted immediately. It now prefers
  the stored pick whenever this audience can see it, and falls back to the
  score-ordered choice otherwise — so visibility scoping still wins, and a
  guest is never handed a crop of a photo they cannot open.
- recomputeCentroid overwrote cover_face_id unconditionally. It runs on
  rescan and on photo replacement, so any reprocessing silently undid a
  deliberate choice. It now keeps the chosen face while it is still a member
  of the cluster.
- The face list is cached per person, and split/merge move faces between
  people. Until now the only reader closed itself after acting, so nobody saw
  the stale copy; the picker is a second reader of the same key.
- cover_face_id meant two things. assignFaces seeded it with whichever face
  opened the cluster and recomputeCentroid overwrote it with the highest
  scoring one, so an automatic guess was indistinguishable from a deliberate
  choice — and honouring it would have pinned every UNCURATED person to that
  guess, which is worse than the fallback it replaced (the fallback is
  computed per audience and skips photos a guest cannot open). Both writers
  are gone, migration 179 clears the stored guesses, and the column now means
  one thing. That also removes the need to defend the choice against rescans:
  nothing overwrites it, and a dangling id self-heals to the derived cover.

Clearing existing values is safe rather than destructive: no install has ever
been able to SET a cover, so every stored value is an automatic guess by
construction.

Also fixes a PostgreSQL-only 500
---------------------------------------------------------------------------
GET /admin/events/:id/people/:personId/faces joined `photos` but did not
table-qualify its WHERE, and photo_faces and photos BOTH have an event_id:

  column reference "event_id" is ambiguous

Postgres refuses it, so the endpoint 500s and the Split dialog — its only
consumer until now — has been broken on every PostgreSQL install since the
join was added. SQLite resolves the ambiguity silently, which is why the suite
stayed green. Reproduced against a real Postgres before and after.

The query is now a named builder the route calls and the test imports, rather
than a copy: an earlier version of that test re-declared the query, so the
route could regress to the bare form while the assertions kept passing.

Merge and recluster preserve the choice as well. Both already carried labels
and privacy flags across; the chosen cover is human state of the same kind, so
it now rides along — through a merge when the target has none, and through a
recluster by following its FACE into whichever cluster ends up holding it,
rather than the majority-descendant rule the label uses.

The picker and the endpoint disagree past 500 faces, so the picker now says
when it is showing a capped list rather than presenting it as exhaustive.

Frontend suite 178 passing, backend 23 across the touched suites, build clean,
no new type errors. Mutation-checked twice: dropping the cover preference fails
the new listPeople test while the visibility-scoping test still passes, and
restoring the auto-seed in assignFaces fails it too.

backend/__tests__/integration/facePrivacy.test.js

@@ -139,6 +139,82 @@ describe('face privacy and visibility (#1074)', () => {
       expect(guestPerson.cover.photo_id).not.toBe(hidden.photoId);
     });
 
+    it('prefers the cover the photographer chose (#1096)', async () => {
+      const eventId = await seedEvent('chosen-cover');
+      // The auto-pick would take the 0.99 face. The photographer picked the
+      // other one — without this the PATCH saved, the toast said so, and the
+      // avatar reverted on the very next read.
+      const best = await addPhotoWithFace(eventId, makeEmbedding(9, 0), { score: 0.99 });
+      const chosen = await addPhotoWithFace(eventId, makeEmbedding(9, 1), { score: 0.70 });
+      await clustering.assignFaces(eventId, [best.face, chosen.face]);
+
+      const [before] = await peopleService.listPeople(eventId, { isClient: true, minClusterSize: 1 });
+      expect(before.cover.photo_id).toBe(best.photoId);
+      // Clustering must not have written one: an automatic seed here would be
+      // indistinguishable from a real choice the moment listPeople honours it.
+      const seeded = await db('event_people').where({ id: before.id }).first();
+      expect(seeded.cover_face_id).toBeFalsy();
+
+      await db('event_people').where({ id: before.id }).update({ cover_face_id: chosen.face.id });
+
+      const [after] = await peopleService.listPeople(eventId, { isClient: true, minClusterSize: 1 });
+      expect(after.cover.photo_id).toBe(chosen.photoId);
+    });
+
+    it('carries a chosen cover through a merge', async () => {
+      const eventId = await seedEvent('cover-merge');
+      const a = await addPhotoWithFace(eventId, makeEmbedding(20, 0), { score: 0.90 });
+      const b = await addPhotoWithFace(eventId, makeEmbedding(60, 0), { score: 0.95 });
+      await clustering.assignFaces(eventId, [a.face]);
+      await clustering.assignFaces(eventId, [b.face]);
+      const people = await db('event_people').where({ event_id: eventId }).orderBy('id');
+      expect(people.length).toBeGreaterThan(1);
+
+      // The SOURCE carries the choice; the target has none.
+      await db('event_people').where({ id: people[1].id }).update({ cover_face_id: b.face.id });
+      await clustering.mergePeople(eventId, [people[1].id], people[0].id);
+
+      const target = await db('event_people').where({ id: people[0].id }).first();
+      expect(target.cover_face_id).toBe(b.face.id);
+    });
+
+    it('carries a chosen cover through a recluster', async () => {
+      const eventId = await seedEvent('cover-recluster');
+      const faces = [];
+      for (let v = 0; v < 3; v++) {
+        faces.push((await addPhotoWithFace(eventId, makeEmbedding(21, v), { score: 0.9 - v * 0.1 })).face);
+      }
+      await clustering.assignFaces(eventId, faces);
+      const [person] = await db('event_people').where({ event_id: eventId });
+      // Pick the WORST-scoring face, so an automatic re-pick would differ.
+      const chosen = faces[2].id;
+      await db('event_people').where({ id: person.id }).update({ cover_face_id: chosen });
+
+      await clustering.recluster(eventId);
+
+      const after = await db('event_people').where({ event_id: eventId }).whereNotNull('cover_face_id');
+      expect(after).toHaveLength(1);
+      expect(after[0].cover_face_id).toBe(chosen);
+    });
+
+    it('falls back to a visible face when the chosen cover is hidden from this audience', async () => {
+      const eventId = await seedEvent('chosen-cover-hidden');
+      // Choosing a cover must never override the visibility scoping — that
+      // would hand a guest a crop of a photo they cannot open.
+      const hidden = await addPhotoWithFace(eventId, makeEmbedding(10, 0), {
+        visibility: 'hidden', score: 0.99,
+      });
+      const visible = await addPhotoWithFace(eventId, makeEmbedding(10, 1), { score: 0.70 });
+      await clustering.assignFaces(eventId, [hidden.face, visible.face]);
+
+      const [person] = await peopleService.listPeople(eventId, { isClient: true, minClusterSize: 1 });
+      await db('event_people').where({ id: person.id }).update({ cover_face_id: hidden.face.id });
+
+      const [guestView] = await peopleService.listPeople(eventId, { isClient: false, minClusterSize: 1 });
+      expect(guestView.cover.photo_id).toBe(visible.photoId);
+      expect(guestView.cover.photo_id).not.toBe(hidden.photoId);
+    });
+
     it('drops a person entirely when all their photos are hidden', async () => {
       const eventId = await seedEvent('all-hidden');
       const faces = [];

backend/__tests__/personFacesQuery.test.js

@@ -0,0 +1,63 @@
+/**
+ * The person-faces query must table-qualify its WHERE (#1096).
+ *
+ * `photo_faces` and `photos` BOTH have an event_id, so the moment the join was
+ * added a bare `where({ event_id })` became ambiguous. Postgres refuses it —
+ *
+ *   column reference "event_id" is ambiguous
+ *
+ * — and the endpoint 500s, which took the Split dialog down with it on every
+ * PostgreSQL install. SQLite resolves the ambiguity silently, which is why the
+ * suite stayed green and this reached production.
+ *
+ * Two deliberate choices about HOW this is tested:
+ *
+ * 1. It imports the builder the route actually calls. An earlier version of
+ *    this file re-declared the query locally, which meant the route could
+ *    regress to the bare form while these assertions kept passing — a test
+ *    that documents a bug without guarding it.
+ * 2. It asserts on the emitted SQL rather than executing it. A round-trip test
+ *    would run against the SQLite the suite uses and prove nothing about the
+ *    engine the bug affects.
+ */
+
+process.env.NODE_ENV = 'test';
+
+const knex = require('knex')({ client: 'pg' });
+const { buildPersonFacesQuery, PERSON_FACES_LIMIT } = require('../src/routes/adminEvents/faces');
+
+const sql = () => buildPersonFacesQuery(knex, 857, 143).toString();
+
+describe('person faces query', () => {
+  it('is the query the route runs, not a copy of it', () => {
+    expect(typeof buildPersonFacesQuery).toBe('function');
+    expect(sql()).toContain('from "photo_faces"');
+  });
+
+  it('qualifies event_id with its table', () => {
+    // The bare form is what Postgres rejects.
+    expect(sql()).toContain('"photo_faces"."event_id"');
+    expect(sql()).not.toMatch(/where\s+"event_id"/i);
+  });
+
+  it('qualifies person_id too, so the join cannot shadow it either', () => {
+    expect(sql()).toContain('"photo_faces"."person_id"');
+    expect(sql()).not.toMatch(/and\s+"person_id"\s*=/i);
+  });
+
+  it('still joins photos for the original dimensions', () => {
+    // The dimensions are what faceCropStyle scales the bbox against; without
+    // the join the crop maths has nothing to work from.
+    const s = sql();
+    expect(s).toContain('inner join "photos"');
+    expect(s).toContain('"photos"."width"');
+    expect(s).toContain('"photos"."height"');
+  });
+
+  it('caps the list at the limit the UI is told about', () => {
+    // The viewer reports truncation using this same number; if they drift, it
+    // silently claims a person has fewer appearances than they do.
+    expect(PERSON_FACES_LIMIT).toBe(500);
+    expect(sql()).toContain(`limit ${PERSON_FACES_LIMIT}`);
+  });
+});