[Deeds67]

Adds a way to dissolve a person from the admin Face Cleanup console, and to undo it. Revised for issue #1228: "junk persons" built from small, blurry or non-face detections that face recognition chains together, and that came back after any cleanup.

What a dissolve does

The admin picks which faces: all, imported from metadata, detected, or without an embedding. Each face then gets the one treatment that keeps it from coming back:

Face	Treatment
Detected (machine-learning)	Hidden: asset_face.deletedAt set, person and identity links cleared. Recorded for restore.
Imported from metadata (exif)	Deleted, and its photo queued for the non-forced "Detect faces (missing)" pass.
Hand-drawn or manual	Unassigned and left on the photo.

The person is removed once no face carries it. In Spaces, the dissolved faces are unlinked, Space people left empty are removed, survivors are recounted, and a survivor whose representative face was hidden gets a visible one.

Why hidden rather than unassigned or deleted: the non-forced recognition pass picks up every unassigned detected face and clusters it again with the same rules, and re-detecting the same photo finds the same boxes. A soft-deleted face is skipped by getAllFaces, searchFaces, suggestions and Space matching, and a re-scan matches the tombstone instead of adding the box again. deletedAt is upstream's own soft-delete column, so stock Immich hides these faces too.

Restore

Administration → Face cleanup → Dissolved lists every dissolve with how many hidden faces can still come back. Restore un-hides them as unnamed faces and queues a non-forced recognition pass. Deleted imported faces cannot be restored, and a forced "Detect faces (All)" removes hidden faces too.

Discovery

Unchanged from the first version: the Health tab ranks people by imported, manual and embedding-less faces. Junk clusters made of ordinary detected faces do not show there; the admin names the person on the People page and searches for it in the console.

Schema

Fork migration 1799100000000-AddFaceDissolveTables adds face_dissolve and face_dissolve_face. Three new FKs onto upstream keys are in gallery-upstream-fks.json; revert-to-immich.sql drops both tables. down() drops them: the record has no upstream home, and the hidden faces stay hidden in upstream's column.

Upstream files: registration lines only, +17 lines across base.service.ts, test/utils.ts, test/medium.factory.ts, schema/gallery.ts and web/src/lib/route.ts (grew). New server code lives under server/src/gallery/.

Testing

• Server unit suite and the dissolve medium specs (53) pass.
• face-dissolve.sticks.spec.ts runs real recognition and detection after a dissolve: the faces stay unassigned, no person re-forms, and a neighbouring real person gains nothing. With the hide step reverted to a plain unassign, four of its five tests fail. The Space-matching test passes either way and only guards the hidden case.
• Web unit tests cover the dialog and the Dissolved page. The e2e spec dissolves an imported-face person and a detected-face person, then restores the latter. It was not run locally; CI runs it.
• Mobile: synced faces carry deletedAt and the people strip filters it, so no mobile change.

Known limits

• New uploads can still chain into a new junk person. Preventing that (a minimum face size for clustering, a check against the whole person) is a separate change.
• On "All faces", an imported face on a photo whose detected face was just hidden is re-scanned without effect: the tombstone absorbs the detection.
• Space face matching is not part of the "detection or recognition is running" refusal, so a match job already in flight could re-link a face hidden at the same moment.

Design: specs/2026-09-06-dissolve-person-design.md (Revision 2 at the top).