dataface 0.1.6.dev622__py3-none-any.whl → 0.1.6.dev644__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -516,22 +516,20 @@ charts:
     y: total                  # column name OR [col, col, ...] for multi-series
     color: segment            # column | {value: "#ccc"} | {field, scale} | {field, when}
 
-    # Sizing — live at chart root, NOT under style:
+    # Sizing — height lives at chart root; aspect_ratio is a style field
     height: 400               # exact px; bypasses aspect_ratio and min/max clamps
-    aspect_ratio: 2.0         # shape without a fixed size; height = width / aspect_ratio
-    # height and aspect_ratio are ignored on kpi, table, callout, spark_bar
+    # height/aspect_ratio are ignored on kpi, table, callout, spark_bar
 
     # Style + behavior
     sort: { by: total, order: desc }
     x_label: "Month"
     y_label: "Revenue (USD)"
     link: "/orders?month={{ month }}"      # Click-through URL template (drill-down)
-    filters: { ... }                        # Result filters
 
     style:                    # Chart-local style patch (typed; not raw CSS) — paint only
-      orientation: vertical   # style: does NOT accept height or aspect_ratio
+      aspect_ratio: 2.0       # shape without a fixed size; height = width / aspect_ratio
       number_format: ",.0f"   # D3 format string or named alias for axis/tooltip format
-      stack: zero               # none | zero | normalize | center
+      # bar/area families also accept style.orientation and style.stack
 ```
 
 ### Chart types (29 total)
@@ -585,7 +583,6 @@ All chart types accept the channels and style fields below — but each type rej
 | `background` | string \| object | Background channel — color, `{value}`, `{field, scale/when}`, or map layer |
 | `sort` | object | `{by, order}` — categorical sort. Horizontal bar charts default to value-descending order when omitted. |
 | `link` | string | Click-through URL template for drill-down links |
-| `filters` | object | Post-execution row filters: `{col: var_name}` (implicit `eq`) or `{col: {op: var}}` where op is one of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `not_in`, `between`. Implicit-eq values may also be Jinja templates (e.g. `"{{ region }}"`) resolved at execute time. A filter is skipped when the variable is `None`, `""`, or renders to `"none"`. |
 | `layers` | list | Layer definitions for `type: layered` (see [Composition](#composition)) |
 | `conditional_formatting` | object | Discrete style rules by column (see [Conditional formatting](#conditional-formatting)) |
 | `data_table` | list | Attached mini-table beneath bar/line/area/layered (see [Composition](#composition)) |
@@ -598,7 +595,7 @@ All chart types accept the channels and style fields below — but each type rej
 
 KPI-only fields: `value`, `label`, `support`. KPI uses `label:` for the header text — `title:` is rejected on KPI charts. `glyph` and `tone` moved into the style namespace: use `style.glyph.character` and `style.tone`. To override glyph/value color, use `style.kpi.glyph.font.color` / `style.kpi.value.font.color`.
 
-Top-level chart fields shared by all types: `id`, `query`, `type`, `title`, `subtitle`, `description`, `height`, `aspect_ratio`, `style`, `link`, `filters`, `conditional_formatting`.
+Top-level chart fields shared by all types: `id`, `query`, `type`, `title`, `subtitle`, `description`, `height`, `aspect_ratio`, `style`, `link`, `conditional_formatting`.
 
 ### Chart-type cheatsheet
 

dataface/agent_api/cache.py

@@ -3,13 +3,14 @@
 from collections.abc import Generator
 from contextlib import contextmanager
 
-from dataface.core.execute.duckdb_cache import DuckDBCache, open_cache_from_env
+from dataface.core.execute.duckdb_cache import open_cache_from_env
+from dataface.core.execute.trivial_local_cache import TrivialDuckDBCache
 
 __all__ = ["cache_from_env", "open_cache_from_env"]
 
 
 @contextmanager
-def cache_from_env() -> Generator[DuckDBCache | None]:
+def cache_from_env() -> Generator[TrivialDuckDBCache | None]:
     """Open DFT_CACHE_PATH-backed cache (or None) and close it on exit.
 
     Use for CLI verbs and composition roots that need a cache scoped to

dataface/agent_api/data_paths.py

@@ -201,19 +201,25 @@ def build_alias_index_for_project(project: Project) -> AliasIndex:
 def data_alias_errors_for_file(
     face_file: Path,
     source_names: frozenset[str],
+    project: Project,
 ) -> list[str]:
     """Read aliases from a face file and lint any /data/ prefixed ones.
 
-    Source-name check only — no DB connection, no resolver. Called from the
-    validate path which must stay connection-free.
+    Reads through *project* (the FilePlugin seam), so it works against a
+    git-blob store as well as the filesystem. Source-name check only — no DB
+    connection, no resolver. Called from the validate path which must stay
+    connection-free.
 
     Returns a list of error message strings; empty means no data alias issues.
     Silently returns [] when the file cannot be parsed (compile catches that).
     """
     from dataface.core.serve.alias_index import read_aliases_from_file
 
+    # file_for_path raises ValueError when face_file is outside project.root —
+    # that is a caller bug, not a parse error, and must NOT be swallowed.
+    project_file = project.file_for_path(face_file)
     try:
-        aliases = read_aliases_from_file(face_file)
+        aliases = read_aliases_from_file(project_file)
     except ValueError:
-        return []  # compile path reports alias parse errors with better context
+        return []  # compile path reports alias-shape parse errors with context
     return validate_data_aliases(aliases, source_names=source_names)

dataface/agent_api/docs/yaml-reference.md

@@ -100,9 +100,8 @@ AuthoredQuery definition from YAML.
 | `rows` | list[dict[str, Any]] | ✓ | Inline data rows for values-type queries (list of row dicts). |
 | `values` | list[list[Any]] | ✓ | Inline column-oriented data for values-type queries (list of lists). |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
-| `filters` | dict[str, Any] | ✓ | Jinja2 filter expressions applied to query results. |
+| `filters` | dict[str, Any] | ✓ | Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources). |
 | `limit` | int | ✓ | Maximum number of rows returned. |
-| `pivot` | [Pivot](#pivot) | ✓ | Cross-tab pivot hint: transforms long-form SQL output into a wide table at render time (table consumers only). Does not affect SQL execution. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']). |
 
 <a id="barchart"></a>
@@ -116,7 +115,6 @@ Authored patch for bar and histogram charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -144,7 +142,6 @@ Authored patch for line charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -172,7 +169,6 @@ Authored patch for area charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -200,7 +196,6 @@ Authored patch for scatter charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -230,7 +225,6 @@ Authored patch for heatmap charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -259,7 +253,6 @@ Authored patch for pie and donut charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -281,7 +274,6 @@ Authored patch for KPI (key performance indicator) charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `label` | str | ✓ | KPI label rendered above the headline value. |
@@ -300,12 +292,14 @@ Authored patch for table charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
 | `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
 | `style` | [TableChartStyle](#tablechartstyle) | ✓ | Chart-local style overrides. |
+| `rows` | list[str] | ✓ | Fields whose distinct values form the row dimension of a pivot cross-tab. Each string is a column name from the query result. Omit for flat (non-pivot) tables. |
+| `columns` | list[str] | ✓ | Fields whose distinct values become column headers in a pivot cross-tab. Multiple fields create a nested multi-dimension pivot (outer → inner). Omit for flat tables. |
+| `values` | list[str] | ✓ | Measure fields that fill pivot cells. Each string is a column name from the query result. When omitted, all query columns not claimed by rows or columns are used. |
 
 <a id="pointmapchart"></a>
 ## PointMapChart
@@ -318,7 +312,6 @@ Authored patch for point_map and bubble_map charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -346,7 +339,6 @@ Authored patch for map and geoshape charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -373,7 +365,6 @@ Authored patch for layered multi-mark charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -408,7 +399,6 @@ Authored patch for spark_bar charts (compact horizontal bars).
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -510,25 +500,6 @@ Options configuration for variable inputs.
 | `column` | str | ✓ | Column in the query result to use as option values. |
 | `label_column` | str | ✓ | Column in the query result to use as display labels (separate from values). |
 
-<a id="pivot"></a>
-## Pivot
-Query-level pivot rendering hint for cross-tab table layout.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `column` | str | Dimension whose distinct values become column headers in the cross-tab layout. |
-| `value` | str | Measure that fills each cell in the cross-tab layout. |
-
-<a id="filterdef"></a>
-## FilterDef
-One column→variable binding in chart.filters.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `op` | enum: "eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "not_in", "between" | ✓ | Comparison operator. Defaults to 'eq'. |
-| `var` | str | ✓ | Plain variable name (no Jinja). Set when the filter value is a dashboard variable reference. |
-| `template` | str | ✓ | Jinja template resolved at execute time. Only valid with op='eq'. Set when conditional-disable or complex expressions are needed. |
-
 <a id="fieldconditionalformatting"></a>
 ## FieldConditionalFormatting
 Conditional formatting rules scoped to a single column.

dataface/agent_api/project_session.py

@@ -124,7 +124,7 @@ class ProjectSession:
         """Construct a ProjectSession rooted at *project_dir*.
 
         Cache lifecycle belongs to the caller: pass ``cache=open_cache_from_env()``
-        (or another DuckDBCache) when persistent caching is desired, otherwise omit
+        (or another cache backend) when persistent caching is desired, otherwise omit
         and the project will run uncached. ``close()`` does not touch the cache —
         whoever opened it closes it.
 

dataface/agent_api/render_face.py

@@ -45,7 +45,7 @@ def render_face(
         use_cache: Whether to use the in-memory Executor result cache.
         cache: Optional DuckDB query-result cache. When provided, the caller
             owns the cache lifecycle and must close it. The DuckDB cache is
-            *not* read from DFT_CACHE_PATH — pass an open DuckDBCache to
+            *not* read from DFT_CACHE_PATH — pass an open cache backend to
             enable caching (see ``open_cache_from_env`` in
             ``dataface.core.execute.duckdb_cache``).
         **options: Additional render options (e.g. ``scale`` for PNG).

dataface/agent_api/validate.py

@@ -258,7 +258,9 @@ def annotate_with_data_lint(
         if not result.path.exists() or not result.path.is_file():
             annotated.append(result)
             continue
-        alias_msgs = data_alias_errors_for_file(result.path, source_names=source_names)
+        alias_msgs = data_alias_errors_for_file(
+            result.path, source_names=source_names, project=project_session.project
+        )
         if not alias_msgs:
             annotated.append(result)
             continue

dataface/core/compile/detect.py

@@ -60,7 +60,14 @@ def is_dataface_file(path: Path | str) -> bool:
     if "faces" in path.parts:
         return True
 
-    # Content detection: check for Dataface-specific keys
+    # Content detection: check for Dataface-specific keys.
+    # TODO(fileplugin): this content branch (and is_markdown_face) reads the path
+    # off disk, bypassing the Project/FilePlugin seam. Enumeration already routes
+    # through project.iter_faces, but routing content detection through the seam
+    # means threading a ProjectFile here and into the path-based is_markdown_face
+    # / resolve_meta_chain helpers in compiler.py, plus keeping the VS Code
+    # extension's duplicated detection in sync. Deferred as a follow-up; faces
+    # discovered under faces/ or named *.dataface.yml never reach this branch.
     if path.exists():
         try:
             content = path.read_text(encoding="utf-8")

dataface/core/compile/models/chart/authored.py

@@ -861,133 +861,6 @@ class Layer(BaseModel):
         return data
 
 
-# ============================================================================
-# FILTER BINDING
-# ============================================================================
-
-# Canonical set of recognized filter operator keys.
-# filter_injection._OP_MAP holds the sqlglot-class mapping for SQL injection;
-# this set is the authoritative list for compile-time validation.
-FILTER_OPS: frozenset[str] = frozenset(
-    {"eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "not_in", "between"}
-)
-
-
-class FilterDef(BaseModel):
-    """One column→variable binding in chart.filters.
-
-    Authored in YAML as a plain variable name (implicit eq), a Jinja template
-    (implicit eq, resolved at execute time), or a single-key operator dict:
-
-        filters:
-          region: selected_region          → FilterDef(op="eq", var="selected_region")
-          region: "{{ selected_region }}"  → FilterDef(op="eq", template="{{ selected_region }}")
-          revenue:
-            gte: min_revenue               → FilterDef(op="gte", var="min_revenue")
-
-    Exactly one of ``var`` or ``template`` must be set. Operator dicts require
-    plain variable names; Jinja templates are not accepted in operator-dict values.
-    """
-
-    model_config = ConfigDict(extra="forbid")
-
-    op: Literal[
-        "eq",
-        "neq",
-        "gt",
-        "gte",
-        "lt",
-        "lte",
-        "like",
-        "ilike",
-        "in",
-        "not_in",
-        "between",
-    ] = Field(default="eq", description="Comparison operator. Defaults to 'eq'.")
-    var: str | None = Field(
-        default=None,
-        description="Plain variable name (no Jinja). Set when the filter value is a dashboard variable reference.",
-    )
-    template: str | None = Field(
-        default=None,
-        description="Jinja template resolved at execute time. Only valid with op='eq'. Set when conditional-disable or complex expressions are needed.",
-    )
-
-    @model_validator(mode="before")
-    @classmethod
-    def _from_yaml(cls, v: Any) -> dict[str, Any]:
-        """Coerce authored YAML shapes into normalized dict form.
-
-        Accepts four input forms:
-          - plain variable name:  "region_var"             → {op: "eq", var: "region_var"}
-          - Jinja template:       "{{ region_var }}"       → {op: "eq", template: "{{ region_var }}"}
-          - single-key op dict:   {"gte": "min_rev"}       → {op: "gte", var: "min_rev"}
-          - already-normalized:   {"op": X, "var": Y}      — passed through as-is
-                                  {"op": X, "template": Y} — passed through as-is
-        """
-        if isinstance(v, str):
-            if not v:
-                raise ValueError("filter value must be a non-empty string")
-            if "{{" in v or "}}" in v:
-                return {"op": "eq", "template": v}
-            return {"op": "eq", "var": v}
-        if isinstance(v, dict):
-            # Already-normalized form from programmatic construction — pass through.
-            if set(v.keys()) <= {"op", "var", "template"}:
-                return v
-            # YAML authored shape: single-key {operator: var_name} — plain var only.
-            if len(v) != 1:
-                raise ValueError(
-                    f"operator dict must have exactly one key, got {sorted(v.keys())!r}"
-                )
-            op, var = next(iter(v.items()))
-            if op not in FILTER_OPS:
-                raise ValueError(
-                    f"unknown operator {op!r}; must be one of {sorted(FILTER_OPS)}"
-                )
-            if not isinstance(var, str) or not var:
-                raise ValueError(
-                    f"filters.{op}: variable name must be a non-empty string"
-                )
-            if "{{" in var or "}}" in var:
-                raise ValueError(
-                    f"filters.{op}: Jinja templates are not allowed in operator-dict "
-                    f"filter values; use a plain variable name instead of {var!r}"
-                )
-            return {"op": op, "var": var}
-        raise ValueError(
-            f"filter binding must be a variable name string or single-key operator dict, "
-            f"got {type(v).__name__}"
-        )
-
-    @model_validator(mode="after")
-    def _exactly_one(self) -> FilterDef:
-        """Exactly one of var or template must be set; template requires op='eq'."""
-        if (self.var is None) == (self.template is None):
-            raise ValueError(
-                "FilterDef must set exactly one of var or template, "
-                f"got var={self.var!r}, template={self.template!r}"
-            )
-        if self.template is not None and self.op != "eq":
-            raise ValueError(
-                f"FilterDef.template is only valid with op='eq', got op={self.op!r}"
-            )
-        return self
-
-    def to_yaml_form(self) -> str | dict[str, str]:
-        """Return the canonical YAML-authored representation.
-
-        Template bindings and implicit-eq bindings round-trip as a plain string;
-        all other operators round-trip as a single-key operator dict.
-        """
-        if self.template is not None:
-            return self.template
-        assert self.var is not None  # enforced by _exactly_one
-        if self.op == "eq":
-            return self.var
-        return {self.op: self.var}
-
-
 # ============================================================================
 # CHART FIELD BASES
 # ============================================================================
@@ -1076,13 +949,6 @@ class _BaseChartFields(BaseModel):
             )
         return data
 
-    filters: Annotated[
-        dict[str, FilterDef] | None,
-        Field(
-            default=None,
-            description="Declarative column filters applied to chart data after query execution.",
-        ),
-    ]
     conditional_formatting: Annotated[
         dict[str, FieldConditionalFormatting] | None,
         Field(
@@ -1619,6 +1485,57 @@ class TableChart(_SharedChartFields):
         TableChartStylePatch | None,
         Field(default=None, description="Chart-local style overrides."),
     ]
+    rows: Annotated[
+        list[str] | None,
+        Field(
+            default=None,
+            description=(
+                "Fields whose distinct values form the row dimension of a pivot cross-tab. "
+                "Each string is a column name from the query result. "
+                "Omit for flat (non-pivot) tables."
+            ),
+        ),
+    ]
+    columns: Annotated[
+        list[str] | None,
+        Field(
+            default=None,
+            description=(
+                "Fields whose distinct values become column headers in a pivot cross-tab. "
+                "Multiple fields create a nested multi-dimension pivot (outer → inner). "
+                "Omit for flat tables."
+            ),
+        ),
+    ]
+    values: Annotated[
+        list[str] | None,
+        Field(
+            default=None,
+            description=(
+                "Measure fields that fill pivot cells. "
+                "Each string is a column name from the query result. "
+                "When omitted, all query columns not claimed by rows or columns are used."
+            ),
+        ),
+    ]
+
+    @model_validator(mode="after")
+    def _validate_pivot_channels(self) -> TableChart:
+        # A field may appear on at most one channel.
+        seen: dict[str, str] = {}
+        for channel, fields in (
+            ("rows", self.rows or []),
+            ("columns", self.columns or []),
+            ("values", self.values or []),
+        ):
+            for f in fields:
+                if f in seen:
+                    raise ValueError(
+                        f"Field {f!r} appears on both '{seen[f]}' and '{channel}' channels. "
+                        "A field may appear on at most one of rows/columns/values."
+                    )
+                seen[f] = channel
+        return self
 
 
 # --- Geo family ---

dataface/core/compile/models/chart/normalized.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Literal, TypeGuard
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from dataface.core.compile.models.chart.authored import (
     BUILTIN_CHART_TYPE_VALUES,
@@ -19,7 +19,6 @@ from dataface.core.compile.models.chart.authored import (
     ChartSort,
     ChartTotal,
     FieldConditionalFormatting,
-    FilterDef,
     KpiSupportConfig,
     Layer,
 )
@@ -125,7 +124,7 @@ class Chart(BaseModel):
     # Variable dependencies - computed during normalization
     variable_dependencies: set[str] = Field(
         default_factory=set,
-        description="Variable names this chart depends on (from title, filters, query SQL).",
+        description="Variable names this chart depends on (from title, subtitle, query SQL).",
     )
 
     # Source location in YAML for edit-back support
@@ -233,10 +232,6 @@ class Chart(BaseModel):
     link: str | None = Field(
         default=None, description="Click-through URL template for drill-down links."
     )
-    filters: dict[str, FilterDef] | None = Field(
-        default=None,
-        description="Declarative column filters applied to chart data after query execution.",
-    )
     layers: list[Layer] | None = Field(
         default=None, description="Layers for multi-mark charts (layered type)."
     )
@@ -284,6 +279,57 @@ class Chart(BaseModel):
             "Has no effect when chart.height is set. Promoted from per-chart style at compile time."
         ),
     )
+    # --- Pivot encoding channels (table charts only) ---
+    rows: list[str] | None = Field(
+        default=None,
+        description=(
+            "Fields whose distinct values form the row dimension of a pivot cross-tab. "
+            "None = flat table (no pivot)."
+        ),
+    )
+    # Justification for T | None: None means 'no pivot dimension' (flat table),
+    # which is a genuinely distinguishable authored state from an empty list.
+    columns: list[str] | None = Field(
+        default=None,
+        description=(
+            "Fields whose distinct values become column headers in a pivot cross-tab. "
+            "Multiple fields create a nested multi-dimension pivot (outer → inner). "
+            "None = flat table."
+        ),
+    )
+    # Justification for T | None: None means 'infer values:* at render time',
+    # which is semantically distinct from an explicit empty list.
+    values: list[str] | None = Field(
+        default=None,
+        description=(
+            "Measure fields that fill pivot cells. "
+            "None = infer as all query columns not claimed by rows or columns."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _validate_pivot_channels(self) -> Chart:
+        """Validate pivot channel invariants at the trust boundary.
+
+        Mirrors the authored-stage TableChart validator so the invariant also
+        holds for Chart objects built directly (tests, internal callers), not
+        only those that flow through AuthoredChart. Render trusts this.
+        """
+        seen: dict[str, str] = {}
+        for channel, fields in (
+            ("rows", self.rows or []),
+            ("columns", self.columns or []),
+            ("values", self.values or []),
+        ):
+            for f in fields:
+                if f in seen:
+                    raise ValueError(
+                        f"Field {f!r} appears on both {seen[f]!r} and {channel!r} "
+                        "channels. A field may appear on at most one of rows/columns/values."
+                    )
+                seen[f] = channel
+        return self
+
     warnings_ignore: list[str] = Field(
         default_factory=list,
         description="Codes of render warnings to suppress for this chart.",
@@ -380,11 +426,6 @@ class Chart(BaseModel):
         if self.link:
             result["link"] = self.link
 
-        if self.filters:
-            result["filters"] = {
-                col: fd.to_yaml_form() for col, fd in self.filters.items()
-            }
-
         return result
 
     def get_dependencies(self) -> ChartDependencies: