validate_acquisition_source is dormant: 0 call sites, docstring claims a _finalize_result call that doesn't exist

[ligon]

Summary

validate_acquisition_source (lsms_library/transformations.py) has zero call sites in the codebase, yet its docstring claims it is wired into the read path:

"Called from Country._finalize_result for tables that carry an s level (currently just food_acquired and its derivatives)."

That call does not exist. Verified:

$ grep -rn "validate_acquisition_source" lsms_library/ | grep -v "def validate_acquisition_source"
lsms_library/transformations.py:<comment>  # enforced in code by :func:`validate_acquisition_source`.

— only a comment reference; no actual invocation anywhere (country.py included).

Why it matters

The function is meant to enforce that the food_acquired s (acquisition source) index level only contains the canonical S_VALUES = ('purchased', 'produced', 'inkind', 'other'). Right now that guard is dormant — a non-canonical s value would pass through unchecked, defeating the design in slurm_logs/DESIGN_food_acquired_canonical_2026-05-05.org (GH #169).

Surfaced while prototyping the build/read transform split (#534): the function was initially (mis)counted among the build-path transforms; tracing call sites showed it is neither build- nor read-path — it is simply uninvoked. Its intended home, per the docstring, is read-path (_finalize_result).

Options

1. Wire it in — call validate_acquisition_source(df) from _finalize_result (or a narrower hook) for tables carrying an s level, as the docstring already claims. Decide raise-vs-warn (a hard ValueError could break a currently-passing country with a stray label).
2. Drop it — remove the function + S_VALUES if the canonical-s invariant is considered adequately enforced upstream (in food_acquired_to_canonical, which only ever emits purchased/produced).

Either is fine; the current state (a documented guard that does nothing) is the thing to fix.

References

• refactor: split build-path transforms into build_transforms.py (step 1, cf. #531) #534 (build/read transform split — where this was surfaced)
• slurm_logs/DESIGN_food_acquired_canonical_2026-05-05.org, GH Design: food_acquired canonical columns (+ cascade to food_prices, food_quantities) #169 (the canonical-s design)