1 ADR 0036 observation producer authority
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0036: Observation Producer Authority and Instance Candidate Arbitration

Status: accepted Date: 2026-05-26

Context

ADR 0020 defines typed observation domains for generalized discovery. The next boundary question is authority: if several local workers, scripts, or future providers submit observations for the same media, domain, or class-instance candidate, Memories must have deterministic ownership and conflict semantics.

The durable rule from v1 still applies: Core API owns authoritative metadata, sharing, backup/export, and user-visible state. Producers execute analysis and submit evidence. A worker lease proves the right to complete one scheduled job; it does not make that worker authoritative for the domain.

This matters especially for class-instance identities. A producer may claim that a face is William or that a vehicle region is our Opel Astra, but the identity assignment has ownership, privacy, merge/split, contribution, and sharing consequences. That cannot be delegated to arbitrary producer code.

Decision

Core API is authoritative for accepted observations and class-instance assignments.

Observation producers are evidence sources only. They may be:

  • Core-scheduled workers holding an active job lease;
  • authorized local scripts or tools using an inbound observation API;
  • future explicit provider integrations with privacy disclosure.

Class Occurrence Observations

For class occurrences such as robin, Bellis perennis, car, passport, or OCR text:

  1. Core validates producer authorization, media/input version, domain key, schema version, scope, confidence semantics, payload shape, and idempotency.
  2. Core stores accepted observations with producer provenance.
  3. Core-scheduled jobs are exclusive per leased job. Only the worker credential that owns the active lease may complete that job.
  4. Inbound producer submissions are independent submissions. They do not take over or complete Core-scheduled jobs.
  5. A domain may configure one default producer/profile for automatic Core-scheduled observations.
  6. Results from additional producers may coexist as provenance-bearing observations unless a domain-specific policy supersedes or rejects them.
  7. User-facing summaries/search must use Core-selected active observations, not producer authority.

The first inbound API slice accepts class-occurrence observations only. It does not create class-instance identities or accepted instance assignments.

To make this boundary enforceable, generic observation ingestion reserves People/face/person-like domain keys and rejects identity-bearing fields such as person record IDs, face annotation IDs, embeddings, embedding hashes, assignment IDs, candidate identity keys, or equivalent aliases. These are not ordinary class labels; they are evidence for a class-instance domain.

Class-Instance Occurrence Candidates

For class-instance domains such as People, pets, or owned vehicles:

  1. Producers may submit candidate evidence such as regions, embeddings, proposed instance IDs, labels, or confidence values only through a domain-specific adapter. This keeps the identity algorithm pluggable while preserving Core authority over acceptance.
  2. Core domain logic owns accepted assignments, merge/split, lifecycle, aliases, sharing, contribution policy, and rejection history.
  3. People remains the first class-instance identity domain. External producers must not directly create accepted PersonAssignment rows.
  4. People worker result types such as current class_instance_candidate with domainKey=people and historical compatibility person_assignment_candidate are People evidence adapters, not generic discovery domains. They may carry face regions, embeddings, clusters, proposed owner-local personRecordId references, confidence, and provenance, but those references are candidate evidence only. Core validates ownership/lifecycle and decides whether the candidate remains tentative, is rejected/superseded, or is accepted by owner action or owner-enabled auto-approval. Fresh bundled workers must not produce new person_assignment_candidate results; People grouping is worker-computed from Core-leased owner snapshots and Core-governed on acceptance.
  5. Conflicting producer evidence remains candidate/evidence until Core policy or owner action accepts, rejects, merges, or supersedes it.

Consequences

  • Multiple producers can be supported without turning Memories into a plugin host.
  • Worker leases remain useful for exclusive execution of Core-scheduled work but do not imply domain truth.
  • The inbound observation API can be model-runtime independent: Core stores what was observed, where, taxonomy/class namespace, confidence, and provenance.
  • The UI and search layers must treat producer output as Core-governed metadata, not direct truth.
  • Instance identity domains remain intentionally more complex than class occurrences.

Revisit Triggers

Revisit this decision if:

  • a production domain needs ensemble voting or weighted producer arbitration before storing active observations;
  • a third-party producer ecosystem requires stronger producer isolation/sandboxing;
  • non-People class-instance domains need shared infrastructure beyond what the People model can generalize;
  • inbound producer submissions need to operate on shared media owned by another user rather than only the credential user's own owner profile.