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 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.