Publication Field Provenance

Publication Field Provenance

This document defines the first-release field catalogue and the source-attribution semantics for the dashboard field provenance viewer (ticket Quick-Release/legaciti#126, plan DASH-DATA-003).

Provenance answers one question per supported field: where did the current value come from? It is read-only, workspace-scoped, and never exposed publicly.

Contract

• Producer: worker-publication-query POST /v1/provenance ({ doi, entity_id }).
• Consumer: dashboard server function getPublicationProvenance, which resolves the active workspace from AuthContext (never from client input) and gates the read on workspace membership plus workspace_data:read.
• Derivation only: provenance is computed from existing representations — original_data (raw provider payloads), edited_data, edit_patch, and the fetch/edit timestamps. There is no new persistence and therefore no migration or rollback surface (ADR-0019).
• Decision recorded: v1 surfaces the raw source value next to the current value (compare view); prior edit values stay in the existing edit_patch / edited_data representations (ADR-0019).

Supported field catalogue (v1)

Field	OpenAlex raw source	Crossref raw source	ORCID raw source
title	display_name	message.title[0]	titles.title[].value
abstract	abstract_inverted_index (reconstructed)	message.abstract	abstract
authors	authorships[].author.display_name	message.author[].given+family	contributors[].name
publication_year	publication_year	message.issued."date-parts"[0][0]	—
publication_type	publication_type	message.type	—
cited_by_count	cited_by_count	message."is-referenced-by-count"	—

Expansion beyond this catalogue requires the packet’s field-expansion gate (TKT-004): new fields need deterministic raw-source accessors and validated spot checks before the viewer shows them.

Attribution semantics

Current values are taken from the merged representation (edited_data when present, otherwise original_data). Raw provider values are extracted from original_data.sources with the per-field accessors above and compared by deep equality (author order is significant).

States, evaluated in order:

State	Meaning
unavailable	No value exists for the field at all.
edited	The current value differs from the original_data value — a deliberate local edit. Source is manual_edit; the prior value is shown; observed_at is last_edited_at.
upstream	The current value equals the raw value of at least one provider. Source is the first matching provider (priority: OpenAlex → Crossref → ORCID).
conflict	Raw providers hold conflicting values and the current value matches none of them.
unknown_legacy	A value exists but no provider evidence matches or survives (legacy records without raw payloads).

Additional context carried per field:

• sources — every provider whose raw value equals the current value.
• source_conflict — true when raw providers disagree with each other, even when the current value still matches one of them.
• provider_values — the raw value of each provider, for the compare view.
• edit_context.patched — true when the JSON Patch in edit_patch touches the field.
• observed_at — last_edited_at for edited fields, otherwise last_fetched_at.

Missing or ambiguous evidence is explicit: unknown_legacy and unavailable are first-class states, and the viewer renders explanatory copy for them. Nothing is flattened into a false zero or a synthetic “healthy” value.

Limits (v1)

• Publication fields only; researcher/person provenance is not part of this release.
• Localized (multi-language) current titles will not deep-equal a single raw provider string; they surface as edited/unknown_legacy rather than a false match.
• No cross-entity provenance, no AI inference, no public provenance surface — per the dashboard spec’s out-of-scope list.

Rollout and rollback

• Rollout: the inspector mounts on demand from the edit dialog; it issues no writes and adds no cost to list/detail loads. Service failures degrade to an explicit “provenance unavailable” message.
• Rollback: hide the inspector entry point; the worker endpoint and contract can remain dark, and derivation involves no schema changes to revert.