Table of contents
- ADR 0039: Legacy People Authority Retirement Boundary
- Context
- Decision
- Remaining Runtime Dependencies
- Schema and Foreign-Key Dependencies
- Retirement Prerequisites
- Owner-Local People Prerequisites
- Collaborative People Prerequisites
- Export, Backup, and Restore Prerequisites
- Code and Operations Prerequisites
- Operator Diagnostics
- Rollback Posture
- Consequences
- Revisit Triggers
ADR 0039: Legacy People Authority Retirement Boundary
Status: superseded Date: 2026-05-30 Superseded by: 0040
Context
Supersession note: This ADR captured the conservative boundary for removing legacy People tables under a future live/upgrade-compatibility posture. Memories is still pre-live and used only by the developer instance, so ADR 0040 supersedes this decision with a stricter pre-live cleanup policy: legacy non-generic People authority tables must be removed from current runtime/schema/test/export paths before Spec 2 is considered complete.
ADR 0020 defines the generic discovery platform. ADR 0037 defines collaborative class instances as the long-term sharing target. ADR 0038 defines owner-local class-instance governance and narrows auto-accept semantics.
People is the first active class-instance domain, but it predates the generic model. The implementation now has generic owner-local class_instances, generic class_instance_occurrences, generic candidate/review storage, and generic collaborative class-instance mirror tables. However, several People-specific tables still remain in runtime paths:
person_recordsperson_assignmentscollaborative_personsperson_sharesperson_rolesperson_contributionsperson_forks
Removing those tables too early would be a destructive migration that risks losing identity curation, sharing authorization, representative identity metadata, contribution/fork history, and operator rollback confidence. This ADR records the explicit boundary that must be crossed before schema removal is allowed.
Decision
Memories will treat legacy People tables as transitional compatibility storage until the generic owner-local and collaborative class-instance paths have been proven as the sole product authority.
Destructive removal of legacy People tables is not allowed until all retirement prerequisites in this ADR are met. Until then:
- Generic owner-local People state is the intended authority for active identity labels, lifecycle, accepted occurrences, representative overrides, review history, and owner-governed merge/split behavior.
- Generic collaborative class-instance state is the intended authority for shared identity metadata, roles, audiences, contributions, forks, revocations, provenance, and export/backup mapping.
- Legacy People rows may continue to exist as compatibility mirrors, foreign-key anchors, API compatibility paths, historical audit sources, or product paths that have not yet moved.
- New non-People class-instance domains must not depend on People-specific tables or services.
Remaining Runtime Dependencies
The following dependencies must be retired or explicitly replaced before destructive schema removal.
| Area | Remaining legacy dependency | Current reason it exists | Generic target before removal |
|---|---|---|---|
| Owner-local identity records | person_records reads/writes in PeopleService and OwnerFaceRecognitionService |
Compatibility identity row for existing People APIs, legacy person IDs, legacy detail/list fallbacks, representative fallback, lifecycle/fork/dissolve compatibility, auto-merge history, and FK repair for assignment paths | class_instances is the only owner-local People identity record used by product services; no runtime path requires a person_records row for active/archived/merged People instances |
| Owner-local face membership | person_assignments reads/writes in PeopleService, OwnerFaceRecognitionService, WorkerResultService, ContributionService, GroupFaceRecognitionService, and MediaMaintenanceService |
Legacy accepted/tentative assignment state, historical worker-result compatibility, contribution-policy filters, group face recognition inputs, maintenance deletion/archive behavior, and UI/API compatibility | class_instance_occurrences, class_instance_occurrence_candidates, and class_instance_review_decisions fully represent accepted, pending, rejected, removed, moved, and superseded People occurrence state |
| Historical worker result compatibility | WorkerResultService.acceptPersonAssignmentCandidate still accepts person_assignment_candidate only for historical face_recognition / face_clustering jobs |
Prevents old queued jobs from failing while the pipeline converges | Historical result type is drained/retired or transformed into generic class_instance_candidate; no fresh bundled worker emits person_assignment_candidate |
| Owner-local automation | person_auto_approval_policies, person_auto_merge_policies, person_auto_merge_events, person_auto_approval_retrospective_runs, and related result tables reference legacy People IDs and often read person_records / person_assignments |
Existing People retarget/auto-approval UX and audit history | Generic class-instance policy/run/event tables or a documented compatibility-history boundary exists; automation runs use generic candidates/occurrences/instances as their inputs and outputs |
| Group/shared face recognition | group_persons, group_person_links, person_merge_requests, person_merge_request_items, plus person_records references |
Existing group merge governance and group face recognition still use legacy person links | Collaborative class-instance contribution/merge governance replaces these tables or they are explicitly retired with no remaining product path |
| Collaborative People product path | collaborative_persons, person_shares, person_roles, person_contributions, and person_forks in CollaborativePersonService, shared People methods in PeopleService, and OwnerFaceRecognitionService |
Existing shared Person UX, authorization, roles, shares, contributions, revocations, forks, and resolved-person APIs still read/write the People-specific model | Services, authorization checks, and UI read/write collaborative_class_instances, shares, roles, contributions, and forks directly |
| Derived face thumbnail authorization | DerivedAssetController checks person_contributions, collaborative_persons, person_roles, and person_shares |
Representative crops/thumbnails may be visible through shared Person authorization independent of surrounding media | Authorization is evaluated through generic collaborative class-instance shares/roles/contributions and media visibility checks |
| Media reset/maintenance | MediaMaintenanceService deletes person_assignments, archives person_records, and now also updates generic occurrence state |
Face reset/delete must not leave stale People assignments or orphaned identities | Maintenance works only against generic occurrence/candidate/instance state, with no legacy cleanup needed |
| Export/inspection | ExportService still exports personRecords and personAssignments; generic collaborative tables are exported too |
Inspectable export must include data still used by runtime and historical state | Export continues to include legacy tables while they exist; after removal, generic export must contain equivalent identity, occurrence, contribution, fork, and provenance information |
| Operator diagnostics | OperatorStatusService.peopleGenericConsistency compares legacy owner-local rows with generic owner-local People rows |
Operators need read-only drift visibility during convergence | Owner-local diagnostics stay green over a soak period; additional collaborative generic/legacy parity diagnostics exist before collaboration table removal |
| Tests and fixtures | Multiple API tests seed/query legacy tables | Tests cover current product behavior and migration compatibility | Tests seed generic tables for authoritative behavior; remaining legacy tests are marked compatibility/export-only until dropped |
Schema and Foreign-Key Dependencies
Removal is also blocked while other tables still depend on legacy People IDs:
person_assignments.person_record_id -> person_records.idperson_records.merged_into_person_record_id -> person_records.idgroup_person_links.person_record_id -> person_records.idperson_merge_request_items.person_record_id -> person_records.idperson_merge_suggestion_decisions.first_person_record_id / second_person_record_id -> person_records.idperson_auto_merge_events.source_person_record_id / target_person_record_id -> person_records.idcollaborative_persons.source_person_record_id -> person_records.idperson_shares.person_id -> collaborative_persons.idperson_roles.person_id -> collaborative_persons.idperson_contributions.person_id -> collaborative_persons.idperson_contributions.person_assignment_id -> person_assignments.idperson_contributions.source_share_id -> person_shares.idperson_forks.source_person_id / new_person_id -> collaborative_persons.idcollaborative_class_instances.source_collaborative_person_id -> collaborative_persons.idcollaborative_class_instance_shares.source_person_share_id -> person_shares.idcollaborative_class_instance_roles.source_person_role_id -> person_roles.idcollaborative_class_instance_contributions.source_person_contribution_id -> person_contributions.idcollaborative_class_instance_forks.source_person_fork_id -> person_forks.id
These references are useful for migration provenance today. They must either be absent from runtime schema, nullable-and-unused with a documented final provenance copy, or deliberately retained as non-authoritative historical import references before the legacy source tables can be dropped.
Retirement Prerequisites
Destructive removal requires all of the following.
Owner-Local People Prerequisites
- Product APIs for People list/detail, rename, representative face selection, confirm/remove/move/dissolve, merge/split, review queues, and candidate history read and write generic
class_instances,class_instance_occurrences, candidates, and review decisions only. - No runtime path creates, repairs, validates, or requires
person_recordsfor an active owner-local People identity. - No runtime path creates, repairs, validates, or requires
person_assignmentsfor accepted/tentative/removed People occurrence membership. - Historical
person_assignment_candidatejobs are drained, transformed, or explicitly rejected with a migration note; fresh workers submit only the genericclass_instance_candidatemodel. - People automation policies/runs/events use generic instance and occurrence identifiers, or the remaining legacy automation history is explicitly read-only audit data that does not block table removal.
- Owner-local operator diagnostics report zero unmapped active legacy records, zero missing generic accepted occurrences for accepted legacy assignments, zero stale accepted generic occurrences, and zero unclassified drift for a documented soak period.
Collaborative People Prerequisites
- Shared/collaborative People services read and write
collaborative_class_instances,collaborative_class_instance_shares,collaborative_class_instance_roles,collaborative_class_instance_contributions, andcollaborative_class_instance_forksdirectly. - Legacy
collaborative_persons,person_shares,person_roles,person_contributions, andperson_forksreceive no new product writes. - Derived face/crop authorization uses generic collaborative shares, roles, contributions, and media visibility rather than People-specific collaboration tables.
- Every active, archived, forked, merged, or dormant collaborative Person has exactly one generic collaborative class-instance mapping with equivalent lifecycle, display metadata, representative identity metadata, roles, shares, contribution states, fork lineage, revocation state, retention snapshots, and provenance.
- Collaborative generic/legacy parity diagnostics exist and stay green for a documented soak period.
Export, Backup, and Restore Prerequisites
- Inspectable export contains all owner-local and collaborative People identity state through generic tables, including historical decisions and provenance needed to understand migrated identities.
- Fidelity restore documentation explicitly names the migration version that removed legacy People tables and confirms PostgreSQL dump restore remains the rollback path.
- A pre-removal migration checklist requires maintenance mode or writes stopped, a PostgreSQL dump,
stored-objects/, restore configuration/secrets/version metadata, and an inspectable export snapshot. - JSON/JSONL export is treated as an inspection/exit artifact, not a rollback source for destructive schema removal.
Code and Operations Prerequisites
git grepover runtime source has no SQL/read/write references to the legacy People tables outside final migration/export compatibility code explicitly approved for the removal release.- Compatibility migrations are idempotent and non-destructive until the final removal migration.
- The app runs for at least one release with generic-only product paths while legacy tables are read-only shadow/history, so rollback before destructive removal remains a normal deploy rollback.
- The removal PR includes focused tests for owner-local People, collaborative People, export, media maintenance, derived-asset authorization, worker-result compatibility, and operator diagnostics.
Operator Diagnostics
Current operator status exposes peopleGenericConsistency at GET /api/admin/operator-status for Super Admins. It is read-only and reports owner-local bridge drift using:
activePersonRecordCountactiveClassInstanceCountmissingClassInstanceCountextraActiveClassInstanceCounteligibleAssignmentCountacceptedOccurrenceCountmissingAcceptedOccurrenceCountstaleAcceptedOccurrenceCountremovedOccurrenceCountarchivedClassInstanceCount
Operator status also exposes legacyPeopleCollaborationParity. It is read-only and reports whether legacy People collaboration rows have generic collaborative class-instance mirrors using:
legacyActiveCollaborativePersonCountgenericActiveCollaborativeClassInstanceCountmissingGenericCollaborativeClassInstanceCountextraGenericCollaborativeClassInstanceCountlegacyActiveShareCountgenericActiveShareCountmissingGenericShareCountlegacyActiveRoleCountgenericActiveRoleCountmissingGenericRoleCountlegacyActiveContributionCountgenericActiveContributionCountmissingGenericContributionCountlegacyForkCountgenericForkCountmissingGenericForkCount
These diagnostics are necessary but not sufficient for removal. Before collaboration table removal, operator status or an equivalent Super Admin diagnostic must continue to prove collaborative parity for generic collaborative class instances, shares, roles, contributions, forks, revocations, representative metadata, and orphaned source mappings over a documented soak period.
Diagnostics must remain read-only. They may recommend a maintenance/backfill action, but they must not silently repair identity, sharing, or contribution state without an explicit operator action and recorded provenance.
Rollback Posture
Before destructive removal, rollback is simple: keep legacy tables and bridges, deploy a previous version, and inspect drift diagnostics.
After destructive removal, rollback is not a normal app rollback because prior application versions expect removed tables. Recovery requires restoring the PostgreSQL dump captured before the migration, along with stored-objects/, restore configuration/secrets, and matching version metadata.
Therefore destructive removal should be scheduled as an explicit maintenance operation, not hidden inside an unrelated feature PR.
Consequences
- This avoids premature data loss and keeps People convergence incremental.
- The migration takes longer because runtime paths must move before schema cleanup.
- Operators get an explicit safety checklist instead of a vague "drop legacy tables later" note.
- Generic tables become the required target for future pets, vehicles, or other class-instance domains without copying People-specific storage.
Revisit Triggers
Revisit this decision if:
- a non-People class-instance domain needs collaborative sharing before People collaboration has migrated;
- operator diagnostics show persistent drift that cannot be represented cleanly in the generic model;
- export/restore requirements require retaining legacy source IDs longer than expected;
- a future major version intentionally drops compatibility with old People APIs or historical worker result types.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference