1 ADR 0037 collaborative class instances
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

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: shared William
  • pets/pet: shared Fido
  • owned_vehicles/vehicle: shared our 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

  1. Collaborative class instances do not own original media bytes.
  2. Sharing a class instance is not the same as sharing every matching media item.
  3. Representative crops/thumbnails may be shared as identity metadata only for authorized instance viewers, without granting access to the surrounding media.
  4. Media visibility, domain-result visibility, and instance collaboration permissions remain separate Core API authorization checks.
  5. Workers may suggest candidate matches or contributions, but Core/user policy decides accepted collaborative membership.
  6. People is the first specialization; pets/vehicles must reuse the generic collaborative pattern rather than receiving separate bespoke sharing systems.
  7. 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_persons and 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_instances stores domain/class identity, labels/aliases, lifecycle, representative identity metadata, source owner-local class instance, source collaborative person, and provenance.
  • collaborative_class_instance_shares stores user/group audiences, approval policy, retention policy, source People share mapping, revocation, and provenance.
  • collaborative_class_instance_roles stores instance-scoped user roles with source People role mapping.
  • collaborative_class_instance_contributions stores owner-local class-instance/occurrence/media contributions, contribution state, retention snapshot, source People contribution mapping, and provenance.
  • collaborative_class_instance_forks stores 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_persons in 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.