1 ADR 0012 collaborative family group person spaces
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0012: Collaborative Family Group Person Spaces

Status: superseded Date: 2026-05-14 Superseded by: 0013

Context

Superseded note (2026-05-15): This ADR was the first step toward collaborative family People. ADR 0013 refines the target model: collaborative people should be ownable, shareable, forkable Person identities that can be shared with users or groups. GroupPerson remains a useful transitional implementation concept, but it is no longer the long-term product boundary.

ADR 0011 defines owner-wide face recognition: Core stores face embeddings and groups people within one media owner's private person space. That protects privacy, but it does not by itself deliver the expected family workflow.

For a trusted family group, Christian expects people curation to be collaborative:

  • Rikke should not need to independently train/name William if Christian's family group already has a well-curated William.
  • Christian and Rikke should be able to contribute images with faces to the same family person.
  • Group person names must not be lost when recognition/clustering is rerun.
  • If a member leaves or revokes group contributions, their owner-local person curation should remain available in their private library.

This pushes two priorities against each other:

  • Privacy / ownership: a member's private, uncontributed media and tentative people must not leak into a group biometric/person graph.
  • Family collaboration: trusted family groups should not force duplicate per-owner person curation for the same children, partner, grandparents, and close relatives.

The existing GroupPerson and GroupPersonLink concepts are the right direction, but the approval and recognition boundaries need to be explicit before group recognition is implemented.

Options Considered

Option Summary Benefits Costs / Risks
A Owner-only person spaces; groups only see accepted owner person metadata Strong privacy and simple authority model Poor family UX; duplicate person training/naming for each member; group People surface feels fragmented
B One shared group person graph automatically owns all member faces Best collaborative UX; simplest group People view Major privacy boundary breach; private/tentative faces can leak; leaving/revocation becomes destructive or confusing
C Dual person spaces: owner-local people plus collaborative group person space over contributed/eligible faces, with explicit owner and group approvals Good family UX while preserving owner authority; stable names; reversible links; leaving group does not erase owner curation More entities/workflows; needs clear policy and approval UX; group recognition scheduling is more complex

Decision

Choose Option C.

Memories will support two related but distinct person spaces:

  1. Owner Person Space

    • Contains owner-local PersonRecords and assignments for the owner's media.
    • Applies to private and contributed media.
    • Remains the durable personal fallback if the owner leaves or revokes a group contribution.
  2. Group Person Space

    • Contains stable GroupPerson records for one sharing group.
    • Uses only media/faces/embeddings that are contributed to that group and eligible under the contributing owner's group policies.
    • May be curated collaboratively according to group and owner approval rules.
    • Does not own original media or erase owner-local person records.

Recognition and Clustering Semantics

  • Group recognition is a Core-owned workflow over contributed, group-eligible face embeddings: group_face_recognition or a semantically equivalent service.
  • New contributed faces should be matched incrementally against existing stable GroupPersons or their approved exemplars/linked owner people. A new contribution MUST NOT require reclustering the whole group graph.
  • Full group reclustering/reindexing may exist as maintenance, but it must produce suggestions or assignment/link updates against stable GroupPerson records. It must not delete/recreate named group people or lose names.
  • Group person names live on stable GroupPerson records. Recognition/clustering is evidence and assignment machinery, not the owner of the name.
  • Private, uncontributed media and owner-private tentative assignments are excluded from the group recognition index.

Approval and Authority Rules

Group person collaboration has two separate authority checks:

  1. Media-owner authority: the owner of the contributed face/media can approve, reject, or revoke whether their face/person metadata participates in the group person.
  2. Group authority: the group decides whether a proposed owner person/face should link to an existing GroupPerson or create/rename/merge a group person.

Default family-group behavior should be conservative but family-friendly:

  • Group recognition may suggest that a contributed face or owner person matches an existing GroupPerson.
  • The contributing media owner can always reject or undo the link for their own media/faces.
  • If the owner's policy is require_approval, the suggestion waits for owner approval before becoming accepted for that owner's contribution.
  • If the owner's policy is allow, high-confidence group-person matches may be accepted according to group policy, but the owner still retains later revoke/unlink authority.
  • Group-level link/merge decisions require group authority. For v1, default group authority should be group_admin or an explicitly accepted group workflow rather than any member silently rewriting the shared group person graph.

Canonical Workflows

Rikke joins a group where Christian already has Family William

  1. Christian has contributed media and the family group has GroupPerson: William.
  2. Rikke contributes images containing William.
  3. Core detects faces and stores Rikke-owned face embeddings.
  4. The contributed/eligible faces enter the family group's recognition candidate set.
  5. Core suggests linking Rikke's contributed faces or Rikke's owner-local person to GroupPerson: William.
  6. Rikke's owner policy determines whether her approval is required.
  7. Group policy determines whether group-admin/existing-group authority must approve the shared GroupPerson link.
  8. Accepted links make Rikke's contributed media appear under Family William while preserving Rikke's owner-local provenance.
  1. Rikke has OwnerPerson: William in her private person space.
  2. The family group has GroupPerson: William.
  3. Rikke proposes linking her owner person to the group person.
  4. Rikke's proposal counts as approval for her owner side.
  5. Group authority confirms or rejects the group side according to group policy.
  6. If accepted, future eligible contributed faces from Rikke can match Family William without Rikke retraining from scratch.

Member leaves or contributions are revoked

  • If contributions are kept visible, accepted group person links may remain as group-visible provenance according to the removal decision.
  • If contributions are revoked, that member's contributed faces and embeddings are removed from the group recognition index and group People views.
  • The leaving member keeps owner-local PersonRecords, names, and accepted assignments for their own media.
  • GroupPerson records with no remaining visible faces should be archived/dormant rather than silently hard-deleted.

Consequences

  • The current owner-wide recognition implementation remains valid foundation, but it is not sufficient for the family UX by itself.
  • We need a distinct group recognition/link workflow rather than extending owner recognition to silently cross owner boundaries.
  • GroupPerson is not merely a display projection; it is a stable collaborative identity for one sharing group, backed by approved links/assignments.
  • Contribution and member-removal workflows must account for group person visibility, group recognition index membership, and owner-local preservation.
  • The UI needs explicit language for suggestions: “Rikke's contributed face may be William in Family” is different from “Rikke has accepted this as her private William.”

Revisit Triggers

Revisit this decision if:

  • Family users find owner/group approval flows too heavy for trusted groups.
  • Group recognition creates privacy surprises or accidental exposure of private/tentative people.
  • GroupPerson links become too complex compared with a single shared household person graph.
  • Revocation/member-removal semantics prove too hard to make understandable.