styling: style_column's col arg is an internal rewritten id, not the real column name — undocumented and easy to misuse

[paddymul]

Problem

StylingAnalysis.style_column(cls, col, column_metadata) (buckaroo/dataflow/styling_core.py:378-383) names its first positional argument col, and the base implementation's own docstring only says "This is the method that should be overridden by subclasses" — no mention of what col actually contains.

In practice col is buckaroo's internal rewritten short column id ("a", "bf", ...), produced by old_col_new_col rewriting. The real column name lives at column_metadata['orig_col_name'] and is only reunited with col afterward, in the caller (fix_column_config(col, orig_col_name, style_column(col, col_meta)), styling_core.py:449). DefaultMainStyling.style_column itself reinforces the ambiguity: it uses col directly for col_name (styling.py:82) but separately re-derives header_name = column_metadata.get('orig_col_name', col) for width estimation (styling.py:126) — so the one example implementation in the codebase treats col as both an id and (via fallback) a display name in different lines, with nothing calling out why.

Impact

A subclass that name-matches columns by comparing col against real column names (e.g. if col == "apy": ...) never raises and never matches — it just silently never fires, which is much harder to notice than a crash. There's no type-level or docstring signal that col isn't a plain string column name; the type hint is just col: str.

Suggested fix

• Rename the parameter (even just in the base class signature and docstring) to something like rewritten_col or add a one-line docstring clarifying it: "col: buckaroo's internal rewritten column id, not the original column name — use column_metadata['orig_col_name'] for that."
• Consider exposing column_metadata['orig_col_name'] as a helper on column_metadata or passing it as an explicit third positional arg to style_column so the common case (matching on real column name) doesn't require knowing about orig_col_name as a dict key at all.

Context

Found while writing a project-specific DefaultMainStyling override in tallyman (nfl-demo2 project) on buckaroo 0.15.6 — cost a full debug cycle (server-log tracing) to discover the override was exec'ing without error but never matching any column.