feat: chart decisions Phase 3 — inspector profile integration

Problem

Dataface's chart-decision engine (which recommends chart types for query results) currently operates without knowledge of the underlying column profiles. It relies only on runtime data values and cursor.description metadata, which means it cannot account for known distribution shape, cardinality ranges, null density, or semantic types that the profiler has already computed. This gap is most visible on skewed, sparse, or high-cardinality columns where naive heuristics pick poor chart types — recommending a bar chart for a 50K-cardinality dimension, or a line chart for a heavily-null time series. Bridging profiler metadata into chart decisions requires SQL lineage tracing (mapping query output columns back to source table columns), which is a hard problem deferred to M3 since Layers 1-2 handle common cases adequately.

Context

• Inspector profile metrics are available to chart-decision pipeline at runtime.
• Recommendation quality improves on skewed/sparse/high-cardinality data cases.
• Diagnostics expose which profile signals drove final chart choices.

Possible Solutions

• A - Keep chart decisions independent from inspect artifacts: simplest, but loses reusable semantic signal.
• B - Recommended: integrate selected inspector profile signals into chart-decision inputs: expose the highest-value profile data without tightly coupling the systems to every inspect detail.
• C - Rebuild chart decisions fully around inspect output first: potentially powerful, but too much coupling and scope for this phase.

Plan

• Define contract between profiler outputs and chart-decision inputs.
• Implement integration path with fallback for missing profile data.
• Add benchmark datasets to evaluate recommendation quality changes.
• Create tests for deterministic decisions under fixed profile inputs.
• Document new decision factors and debugging workflow for analysts.

Implementation Progress

Deferred from M1 → M3

Reason: Inspector profiles are per-table/model (e.g. orders.revenue), but chart queries produce derived output columns (e.g. total_rev, avg_score). Bridging the gap requires SQL lineage tracing (sqlglot or similar) to map query output columns back to source columns — a hard, error-prone problem that isn't justified for M1.

Chart decisions Layers 1 (data value heuristics) and 2 (cursor.description metadata) already handle the common cases well and are shipped. Layer 3 (inspector profiles) adds marginal value only when column names pass through unchanged, which is the easy case that name-matching can handle later without urgency.

• GitHub issue: https://github.com/fivetran/dataface/issues/376

Review Feedback

• [ ] Review cleared