validate() rejects documented aggregate example before global mappings and aliases are resolved

[kevintruong]

Summary

At v0.4.1, validate() rejects the documented aggregate range example even though the same query executes and renders successfully.

This creates a validation/execution parity problem for integrations that call validate() before execute(): a renderable chart is suppressed with:

Layer 1: aggregate target 'x' is not mapped on this layer

The example is currently documented in doc/syntax/layer/type/range.qmd.

Tested against tag v0.4.1, commit 6fcb07fd7ba40039c61b839c9979e0cad3bceea5.

Minimal reproduction

This uses the Python bindings pinned to core ggsql = "=0.4.1", but the failing behavior comes from the core ggsql::validate path.

import ggsql
import pyarrow as pa

query = """SELECT * FROM airquality
VISUALISE Date AS x, Temp AS ymin, Temp AS ymax, Temp AS color
DRAW range
 REMAPPING aggregate AS linewidth
 SETTING aggregate => (
 'x:first',
 'ymin:first', 'ymin:min',
 'ymax:last', 'ymax:max',
 'color:diff'
 ), hinge => null
 PARTITION BY Week
SCALE linewidth TO (5, 1)
SCALE BINNED color TO ('steelblue', 'firebrick')
 SETTING breaks => (-20, 0, 20)"""

reader = ggsql.DuckDBReader("duckdb://memory")
reader.register(
 "airquality",
 pa.table(
 {
 "Date": [
 "1973-05-01",
 "1973-05-02",
 "1973-05-08",
 "1973-05-09",
 ],
 "Temp": [67, 72, 68, 75],
 "Week": [18, 18, 19, 19],
 }
 ),
)

validated = ggsql.validate(query)
print(validated.valid())
print(validated.errors())

spec = reader.execute(query)
rendered = ggsql.VegaLiteWriter().render(spec)
print(len(rendered))

Actual output:

False
[{'message': "Layer 1: aggregate target 'x' is not mapped on this layer", 'location': None}]
6758

Expected:

• validated.valid() is True
• validated.errors() is empty
• execution continues to produce the Vega-Lite spec

Root cause

The static validation path and execution path prepare layer mappings differently.

In src/validate.rs:

1. The explicit mappings from VISUALISE ... live in plot.global_mappings.
2. Validation clones the layer and merges those global mappings into merged.
3. merged is used only for validate_mapping().
4. validate_aggregate_setting() is then called on the original layer, whose mappings do not contain x, ymin, ymax, or color.

Consequently, resolve_aggregate_targets() cannot resolve the first target, x, and emits the error.

There is a second parity requirement in this particular documented example: color:diff targets an aesthetic alias. The execution path first merges globals and then runs resolve_aesthetic_aliases(), turning color into the concrete aesthetic supported by range (here stroke). The standalone validation path does not mirror this alias-resolution step.

This explains both observations:

• static validation fails before execution;
• execution succeeds because it has already merged global mappings and resolved aliases before the aggregate stat runs.

Proposed fix

Make standalone validation use the same effective layer mappings that execution uses before validating aggregate targets:

1. Clone the layer.
2. Merge applicable plot.global_mappings, preserving layer precedence and annotation behavior.
3. Resolve aesthetic aliases on that effective layer according to the geom's supported aesthetics.
4. Use the effective layer for both:
   • validate_mapping()
   • validate_aggregate_setting()

Ideally, factor the merge/alias preparation into a shared helper so validation and execution cannot drift again.

Simply replacing:

layer.validate_aggregate_setting(...)

with:

merged.validate_aggregate_setting(...)

would fix the first x failure, but is not sufficient for the full documented query unless the color alias is also resolved to stroke/ fill as appropriate for the geom.

For wildcard mappings, where standalone validation lacks schema information, aggregate syntax/vocabulary/recycling can still be checked, while target-resolution checks may need to be deferred until effective mappings are knowable.

Suggested regression coverage

• The complete documented range query above returns valid() == true.
• Global x/ymin/ymax aggregate targets validate.
• Global color plus color:diff validates for a geom supporting the corresponding concrete alias target.
• A genuinely unmapped aggregate target remains invalid.
• Validation and execution agree for this query.