ADR 0037: Collaborative Class Instances
Status: accepted Date: 2026-05-28
Context
ADR 0013 defines shareable, forkable Person identities so a household can collaborate on one visible William without collapsing media ownership or privacy boundaries. The generalized discovery architecture in ADR 0020 extends People into a generic class-instance lane for future durable household identities such as pets or owned vehicles.
That creates a boundary question: should collaboration remain a People-only subsystem, or should shared/collaborative identity become a generic class-instance concept?
If collaboration remains People-only, future domains such as pets or owned vehicles will either copy People-specific tables and services or lose the ownership/revocation/fork semantics that make People safe. If collaboration is generic too early, the data model becomes larger before non-People instance domains prove value.
Decision
Memories will treat collaborative shared class instances as the long-term target model.
A collaborative class instance is a durable shared identity graph for a real-world instance of a manifest-declared class, for example:
people/person: sharedWilliampets/pet: sharedFidoowned_vehicles/vehicle: sharedour Opel Astra
The current collaborative_persons, person_shares, person_roles, and person_contributions model remains a People-specific transitional implementation of this broader concept. Generic collaborative class-instance primitives now exist as additive persistence and export/backup-mapping infrastructure. People-specific tables remain the active product read/write path until a later migration slice switches services and UI onto the generic tables.
Target Concepts
- Owner-local ClassInstance: the media/instance owner's local identity and accepted occurrences.
- CollaborativeClassInstance: a shared identity graph with domain key, class key, display name, aliases, representative occurrence/media, lifecycle, provenance, and optional links/forks.
- CollaborativeClassInstanceShare: grants visibility/contribution/curation rights to a user or sharing group.
- CollaborativeClassInstanceRole: instance-scoped role such as owner, admin, contributor, or viewer.
- CollaborativeClassInstanceContribution: provenance-preserving link from an owner-local class instance occurrence to the collaborative instance.
- Fork / revocation semantics: when sharing ends, each side keeps a usable local/collaborative identity over the contributions it is allowed to retain.
Rules
- Collaborative class instances do not own original media bytes.
- Sharing a class instance is not the same as sharing every matching media item.
- Representative crops/thumbnails may be shared as identity metadata only for authorized instance viewers, without granting access to the surrounding media.
- Media visibility, domain-result visibility, and instance collaboration permissions remain separate Core API authorization checks.
- Workers may suggest candidate matches or contributions, but Core/user policy decides accepted collaborative membership.
- People is the first specialization; pets/vehicles must reuse the generic collaborative pattern rather than receiving separate bespoke sharing systems.
- Fork/revocation behavior must preserve provenance and avoid destructive loss of owner-local curation.
Consequences
Positive
- Avoids making People collaboration a permanent one-off subsystem.
- Gives future pets/vehicles the same ownership, sharing, contribution, and fork semantics when they become product-worthy.
- Keeps privacy boundaries explicit: identity collaboration does not imply media visibility.
- Aligns ADR 0013's family-friendly shared Person UX with ADR 0020's generic class-instance lane.
Negative / Costs
- Generic collaborative identity is larger than the current transitional People tables.
- Migration must account for existing
collaborative_personsand person contribution semantics. - UI copy and authorization must stay domain-aware enough that generic infrastructure does not feel abstract to households.
Migration Posture
Do not implement a broad generic collaborative UX or service rewrite inside the current People read-path migration slice. The near-term migration may continue to bridge People-specific collaboration tables while owner-local People converges on generic class_instances and class_instance_occurrences.
The first generic implementation is intentionally additive:
collaborative_class_instancesstores domain/class identity, labels/aliases, lifecycle, representative identity metadata, source owner-local class instance, source collaborative person, and provenance.collaborative_class_instance_sharesstores user/group audiences, approval policy, retention policy, source People share mapping, revocation, and provenance.collaborative_class_instance_rolesstores instance-scoped user roles with source People role mapping.collaborative_class_instance_contributionsstores owner-local class-instance/occurrence/media contributions, contribution state, retention snapshot, source People contribution mapping, and provenance.collaborative_class_instance_forksstores fork/revocation lineage with source People fork mapping and retained/removed contribution snapshots.
This satisfies the persistence, provenance, and export/backup mapping boundary needed before non-People collaborative instance domains are promoted. It does not yet make generic collaboration the primary People service path.
Before adding a non-People collaborative instance domain, services and UI must use the generic tables and authorization checks for:
- collaborative instances;
- shares/audiences;
- roles;
- contributions;
- forks/revocations;
- export/backup representation;
- authorization checks.
Revisit Triggers
- A non-People class-instance domain is promoted beyond owner-local use.
- People collaboration work would deepen
collaborative_personsin a way that cannot migrate generically. - Export/restore needs cannot represent shared instance contributions generically.
- Household UX testing shows generic collaborative terminology leaks into user-facing surfaces.
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