# Historical comparison

`pipewhy.compare.ArtifactObservations` validates flat captured observation columns.
`ComparisonContext.from_metadata` restores snapshot policy/source information and
requires explicit discovery completeness. `compare(before, after)` compares dataset
summaries by stable ID; its `resolution` argument selects retained record/value detail.
Results include immutable status/reason/flag arrays, both snapshot contexts and
observation links/timestamps. Incomplete reads/discovery remain visible as uncertainty.

`drill_down(before, after, artifact_id, resolution="record")` selects retained
historical descendants. Missing retained detail returns `Availability.UNAVAILABLE`
with a reason; it never substitutes a current source read. An available comparison
may still be unknown or incompatible. Labels do not determine identity; changed
profiles, algorithms or schemas are checked before comparing content.

See [blueprint/COMPARISON_CONTRACT.txt](../development/architecture.rst) for exact input/result columns, stable codes,
coverage precedence and consumer rules. `tests/fixtures/comparison_v1.json` supplies
manually specified truth cases; separate integration tests verify fixture reads,
fingerprints and saved snapshots together. These are reference Python operations;
native CPU fingerprints also have separate parity checks. Further lineage analysis
and CLI comparison commands remain in development.