ADR 0040: Pre-Live Legacy People Removal
Status: accepted Date: 2026-05-31
Context
ADR 0039 defined a cautious retirement boundary for legacy People tables. That caution assumed a live product posture where existing external installations, stable upgrade compatibility, and normal rollback across releases matter.
That assumption is not true yet. Memories is pre-live. The only expected installation is Christian's developer instance. Original media bytes remain sacred, but developer-only database state can be backed up, reset, or migrated explicitly when that avoids carrying long-term architectural debt.
People is the first class-instance domain. It predates the generic class-instance model and still has legacy non-generic tables in the current schema and runtime/test/export/diagnostic paths:
person_recordsperson_assignmentscollaborative_personsperson_sharesperson_rolesperson_contributionsperson_forks
Related People-specific group/merge/automation tables also reference these IDs and must be either migrated to generic identifiers, converted to explicit generic audit/history, or removed if they no longer represent a product path.
Keeping these compatibility layers until after 1.0 would make the first public/family-ready version harder to reason about: there would be two identity authority models, duplicate diagnostics, and more surprising backup/restore and migration behavior.
Decision
Spec 2 is reopened and is not complete until legacy non-generic People authority is removed from the current product implementation.
Before Spec 2 can be marked complete again:
- Runtime application code, service methods, controller paths, DAO/SQL helpers, authorization checks, worker-result handling, maintenance jobs, operator diagnostics, and export code MUST NOT read from or write to the legacy People authority tables listed above.
- Current tests and fixtures MUST NOT seed or assert against those legacy tables except for tests of historical Flyway migration behavior. Normal product tests must use generic owner-local and generic collaborative class-instance tables.
- Current schema migrations must remove or replace active legacy People tables and foreign keys. Old Flyway migration files may remain in Git history as historical migrations, but the current migrated schema must not expose legacy People authority tables as product storage.
- People product APIs may remain People-shaped for household UX, but their persistence and
authorization authority must be generic:
- owner-local identities:
class_instances,class_instance_occurrences,class_instance_occurrence_candidates, andclass_instance_review_decisions; - collaborative identities:
collaborative_class_instances,collaborative_class_instance_shares,collaborative_class_instance_roles,collaborative_class_instance_contributions, andcollaborative_class_instance_forks.
- owner-local identities:
- Any remaining People-specific automation, group recognition, merge request, or history feature must either use generic identifiers/tables directly or be explicitly removed/deferred before Spec 2 closes.
- The removal path must include a developer-instance safety note: take a PostgreSQL dump and preserve
stored-objects/before applying destructive migrations; rollback is restore-from-backup rather than ordinary app downgrade.
Consequences
- Spec 2 is no longer complete as of pre-live
0.41.0/ PR #135. Its new completion boundary is stricter. - The project avoids shipping a first public/family-ready release with known duplicate People authority layers.
- The implementation will likely require several vertical slices because People touches owner-local curation, recognition automation, collaboration, sharing authorization, media maintenance, export, operator diagnostics, and tests.
- Backward compatibility for developer-only DB state is intentionally lower priority than long-term inspectability and architectural clarity.
- Original media bytes are still protected. Destructive database cleanup must not delete or rewrite stored original media objects.
Non-Goals
- This ADR does not require changing household-facing People terminology or routes.
- This ADR does not require a generic UI label such as "class instance" in household workflows.
- This ADR does not make JSON/JSONL export a restore source. Fidelity rollback before/after destructive
cleanup remains PostgreSQL dump plus
stored-objects/and configuration/secrets/version metadata. - This ADR does not require preserving old developer-instance People curation if doing so would add a larger compatibility layer than resetting/reprocessing can justify pre-live.
Acceptance Gates
Spec 2 can be re-closed only when all of these checks pass:
git grepover current non-migration source contains no references to the legacy People authority table names, except in documentation describing their removal.- Current product tests pass without creating the legacy People authority tables in test schemas.
- Export, operator status, derived-asset authorization, worker-result handling, media maintenance, owner-local People curation, and collaborative People flows all use generic tables directly.
- A destructive migration or reset path removes legacy People tables/FKs from the active schema.
- The PR that re-closes Spec 2 documents the developer-instance backup/reset procedure.
Migration-Preservation Gate
Pre-live removal does not mean discarding Christian's current People curation. Existing curated People labels, accepted face memberships, representative choices, shared identities, shares, roles, contributions, forks, and relevant provenance must be preserved through the generic tables before the legacy tables are dropped.
The removal sequence therefore has an explicit gate:
- Take a PostgreSQL dump and preserve
stored-objects/plus configuration/secrets/version metadata. - Run or verify the existing generic backfill/mirror path for owner-local and collaborative People.
- Prove parity between relevant legacy People state and generic state before switching product paths to generic-only behavior.
- Only after parity is proven may runtime code stop writing compatibility mirrors and destructive migrations remove legacy tables.
- If parity fails, stop and repair/backfill generic state; do not silently reset People curation.
Because the product is not live, the fallback for a failed destructive migration is restoring the developer-instance dump, not carrying permanent compatibility paths forward.
Current Legacy Reference Inventory
The first GDP010t audit found remaining references across these areas. Counts are approximate and are intended to size work, not as a normative checklist:
| Legacy table family | Main runtime references | Test/schema references | Replacement target |
|---|---|---|---|
person_records |
PeopleService, OwnerFaceRecognitionService, WorkerResultService, OperatorStatusService, CollaborativePersonService, ExportService, MediaMaintenanceService |
People governance/curation/recognition/collaboration/operator/export fixtures | class_instances plus generic representative metadata/provenance |
person_assignments |
PeopleService, OwnerFaceRecognitionService, WorkerResultService, CollaborativePersonService, ContributionService, MediaMaintenanceService, OperatorStatusService |
People governance/curation/recognition/collaboration/sharing fixtures | class_instance_occurrences, occurrence candidates, review decisions |
| People collaboration tables | CollaborativePersonService, shared People methods in PeopleService, OwnerFaceRecognitionService, OperatorStatusService |
Collaborative People, derived asset, operator, recognition fixtures | collaborative_class_instances, shares, roles, contributions, forks |
| Group/merge tables | PeopleService, GroupFaceRecognitionService |
Group face recognition and governance fixtures | Generic collaborative/owner-local merge or explicit pre-live removal/deferment |
| People automation tables | PeopleService, OwnerFaceRecognitionService, PeopleAutomationRunService, PeopleAutomationProgressStore, WorkerResultService |
Auto-approval/recognition fixtures | Generic class-instance policy/run/history tables or explicit pre-live removal/deferment |
The implementation tasks in Spec 2 GDP010t-GDP010w own turning this inventory into generic-only code, tests, export, diagnostics, and active schema.
Revisit Triggers
Revisit this ADR if:
- Memories gains external users before legacy People removal is complete;
- a future 1.0 readiness review decides to preserve a specific historical People audit table as an explicitly generic import/provenance artifact;
- removal would require rewriting original media bytes, which remains forbidden;
- a non-People identity domain cannot be implemented without reintroducing domain-specific Core authority tables.
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