Common names tracking issue

[thompsonmj]

Issue text drafted with the help of Opus 5.5.

Common-name handling has gone through several iterations across releases, PRs, and branches. This issue collects that history in one place and gathers the open work that should inform the next iteration.

History

Stage	Where	Released?	Behavior
Original retrieval	#6 (merged 2025-05-01)	v0.1.0	Merges GBIF Backbone vernacular names into resolved output. Input common names could pass through.
Deterministic rewrite	#14 (open, branch feat/deterministic-common-names)	never merged	Backbone-only names, Polars rewrite, higher-rank coverage, tests. The review discussion there (usefulness of higher-rank names such as "Orchid" for many species; recording the source rank) directly shaped later work.
Hierarchical fallback	#26	v0.2.0	Always climbs species → kingdom. Prefers the first English name, then any language. Input common names always replaced.
Optional fallback + rank column	#36 → #37	unreleased (on main only)	--no-higher-rank-fallback disables climbing. New common_name_rank column records the rank the name came from. Default output matches v0.2.0 plus the new column.

Note: #37's behavior has not shipped in any tagged release. If the next iteration lands before the next tag, release notes should describe the net change from v0.2.0.

Open items

• Resolved common names should not allow variable input data through #10: input common names must not pass through. The literal request is addressed since v0.2.0 (the input common_name column is always dropped before lookup). Its broader goal, a uniform one-to-one mapping between taxonomy and vernacular, is affected by the homonym item below.
• Homonym-blind taxon lookup (new). Each rank's name is mapped to a backbone taxonID by canonicalName alone, ignoring kingdom and taxonomicStatus. Duplicates are dropped with Polars unique(subset=[rank]), which keeps an arbitrary row (stable in practice, not guaranteed). In the GBIF Backbone: 44,403 duplicated genus names (11,520 spanning more than one kingdom), 248,587 duplicated species names, 194 duplicated family names. Example: genus Laelia maps to taxonID 7562880 (Plantae, doubtful) for every row, so animal Laelia can receive a plant's common name.
• Common names cache dir dead code to remove #35: dead cache_dir handling in the standalone common-names parser.
• IO inaccuracies in documentation #34 (last bullet): --full-rerun does not apply to common-names, although the command writes its own manifest. Decide whether it should, or document that it is resolve-only.

Related branches (kept for reference)

• feat/deterministic-common-names: Deterministic common names; performance improvement; higher rank coverage #14's branch.

Next iteration

Should include fixes required by the above notes.
Before common names updates are added to a tagged release, the strategy should shift to use Catalogue of Life vernacular data retrieved from here.

Furthermore, a vernacular assignment strategy for TaxonoPy-resolved entries should be agreed upon. Default behavior can be unfiltered retrieval of all vernacular data, enabling a user to apply custom strategy of their design. Additionally, we can provide reasonable prioritization/filtering strategies that serve our own use-cases.