dataface 0.3.2.dev150__py3-none-any.whl → 0.4.1.dev5__py3-none-any.whl

dataface/agent_api/docs/yaml-reference.md

@@ -902,9 +902,7 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `spark` | [SparkStyle](#sparkstyle) | ✓ | Inline sparkline defaults for table cells. |
 | `transpose` | bool | ✓ | When True, render a single wide data row as N (label, value) rows — one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures. |
 | `text_baseline_offset` | float | ✓ | Vertical offset to align SVG text baseline with cell grid in pixels. |
-| `title_baseline_offset` | float | ✓ | Vertical offset to align SVG title baseline in pixels. |
-| `title_subtitle_gap` | float | ✓ | Gap between table title and subtitle lines in pixels. |
-| `subtitle` | [SubtitleStyle](#subtitlestyle) | ✓ | Table subtitle font-sizing constants. |
+| `title_subtitle_gap` | float | ✓ | Pure whitespace between the title's descent and the subtitle's ascent, in pixels — not a baseline-to-baseline distance. Combined with the title and subtitle font sizes (via _TITLE_ASCENT_RATIO in render/chart/table.py) to reproduce Vega-Lite's title->subtitle spacing at any font size, not one calibrated pair. Font size and colour for the subtitle itself come from style.title.subtitle — the same source chart-family titles use — not a table-local constant. |
 
 <a id="basemapconfig"></a>
 ## BasemapConfig
@@ -1062,6 +1060,9 @@ Box border. Does NOT cascade (ADR-003: box properties reset per level).
 | `radius` | float | ✓ | Border corner radius in pixels. |
 | `color` | str | ✓ | Border color (CSS color string). |
 | `width` | float | ✓ | Border width in pixels. |
+| `dash_array` | list[float] | ✓ | SVG stroke-dasharray pattern in pixels (e.g. [4, 4]). None means a solid border. |
+| `line_cap` | enum: "butt", "round", "square" | ✓ | SVG stroke-linecap for a dashed border. None uses the renderer default (butt). |
+| `dash_offset` | float | ✓ | SVG stroke-dashoffset in pixels. None means 0. |
 
 <a id="titlestyle"></a>
 ## TitleStyle
@@ -1776,14 +1777,6 @@ Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).
 | `bar` | [SparkBarCellStyle](#sparkbarcellstyle) | ✓ | Style for bar/bar-normalize sparklines. |
 | `area` | [SparkAreaStyle](#sparkareastyle) | ✓ | Style for area sparklines. |
 
-<a id="subtitlestyle"></a>
-## SubtitleStyle
-Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `font` | [FontStyle](#fontstyle) | ✓ | Subtitle font style; theme populates font.size directly. |
-
 <a id="projectionstyle"></a>
 ## ProjectionStyle
 Authored overlay for ProjectionStyle. Vega-Lite map projection configuration for geo chart families.
@@ -1854,6 +1847,14 @@ Authored overlay for SparkBarCountStyle. Count-value sub-block for SparkBarChart
 | `visible` | bool | ✓ | Show count/value text next to bars. |
 | `width` | float | ✓ | Reserved width for bar count text in pixels. |
 
+<a id="subtitlestyle"></a>
+## SubtitleStyle
+Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Subtitle font style; theme populates font.size directly. |
+
 <a id="titlewidthoffsetsstyle"></a>
 ## TitleWidthOffsetsStyle
 Authored overlay for TitleWidthOffsetsStyle. Additive level offsets applied to a face/chart title's heading level, by card pixel width.

dataface/ai/llm.py

@@ -28,7 +28,7 @@ else:
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_OPENAI_MODEL = "gpt-5.6"
+DEFAULT_OPENAI_MODEL = "gpt-5.6-terra"
 
 
 #: Connect budget for a caller-supplied read timeout. Named so the callers that

dataface/ai/skills/kpi-row/SKILL.md

@@ -82,7 +82,7 @@ See `examples/kpi-row.yml` for the full 3-KPI worked example.
 | Currency | `style.value.format: currency_whole` | Revenue, spend, cost |
 | Percent | `style.value.format: percent` | Rate, conversion, margin |
 | Negative delta | `tone: negative`, `glyph: "▼"` | Unfavorable direction |
-| Fixed row height | `height: 120` on the row | Prevent KPIs growing taller than charts below |
+| Cap row height | `height: 120` on the row | Prevent KPIs growing taller than charts below. It is a ceiling, not a reservation — if the KPIs need less, the row shrinks to fit rather than leaving an empty band. |
 
 ## Common pitfalls
 

dataface/ai/skills/kpi-row/examples/kpi-row.yml

@@ -52,6 +52,7 @@ charts:
       tone: positive
 
 rows:
+  # Ceiling, not a reservation: the row shrinks to the KPIs if they need less.
   - height: 120
     cols:
       - revenue_kpi

dataface/core/compile/channel.py

@@ -24,6 +24,7 @@ from dataface.core.compile.models.primitives import (
     ColorStyle,
     ScaleTargetConfig,
     StaticGradientColorStyle,
+    bake_scale_target_stops,
 )
 
 _RawStyleChannel = str | dict[str, Any]
@@ -188,7 +189,10 @@ def _parse_channel_scale(raw: dict[str, Any], channel_name: str) -> ScaleTargetC
     scale_dict = dict(scale)
     if channel_name in ("opacity", "stroke_width") and "palette" not in scale_dict:
         scale_dict["palette"] = [0.2, 1.0]
-    return ScaleTargetConfig.model_validate(scale_dict)
+    # A named Dataface palette resolves to hex stops via bake_scale_target_stops;
+    # a Vega scheme name (e.g. "viridis") is left alone and forwarded to VL as
+    # `scheme:` directly (gradient_scale_to_vl).
+    return bake_scale_target_stops(ScaleTargetConfig.model_validate(scale_dict))
 
 
 def validate_channel_fields(

dataface/core/compile/chart_update.py

@@ -64,7 +64,7 @@ def update_chart_in_yaml(
         yaml_content: Original dashboard YAML content
         chart_id: ID of the chart to update
         edits: Dict of fields to update (sql, type, x, y, title, etc.)
-        source_path: Original source path (e.g., "charts.revenue", "rows[0]")
+        source_path: Original source path (e.g., "charts.revenue", "rows.0")
         query_is_inline: Whether the chart had an inline query
 
     Returns:
@@ -159,9 +159,7 @@ def update_chart_in_yaml(
     data["charts"][chart_id] = chart_def
 
     # If chart was inline, we need to update the layout reference
-    if source_path and (
-        source_path.startswith("rows[") or source_path.startswith("cols[")
-    ):
+    if source_path and source_path.split(".")[0] in ("rows", "cols"):
         _update_layout_reference(data, source_path, chart_id)
 
     # Serialize back to YAML
@@ -177,29 +175,21 @@ def _update_layout_reference(
 
     Args:
         data: Parsed YAML data (modified in place)
-        source_path: Path like "rows[0]" or "cols[1]"
+        source_path: Path like "rows.0" or "rows.0.cols.1"
         chart_id: ID of the chart to reference
     """
-    # Parse the source path to get the layout type and index
-    if source_path.startswith("rows["):
-        layout_key = "rows"
-        try:
-            index = int(source_path.split("[")[1].rstrip("]"))
-        except (ValueError, IndexError):
-            logger.warning(f"Failed to parse row index from source_path: {source_path}")
-            return
-    elif source_path.startswith("cols["):
-        layout_key = "cols"
-        try:
-            index = int(source_path.split("[")[1].rstrip("]"))
-        except (ValueError, IndexError):
-            logger.warning(
-                f"Failed to parse column index from source_path: {source_path}"
-            )
-            return
-    else:
+    # Only a top-level position is rewritable here: this replaces an entry in
+    # `data[layout_key]`, and a deeper path (`rows.0.cols.1`) names an entry in a
+    # nested face's own list, which this function never walks into.
+    segments = source_path.split(".")
+    if len(segments) != 2 or segments[0] not in ("rows", "cols"):
         logger.debug(f"Unrecognized source_path format: {source_path}")
         return
+    layout_key, raw_index = segments
+    if not raw_index.isdigit():
+        logger.warning(f"Failed to parse index from source_path: {source_path}")
+        return
+    index = int(raw_index)
 
     # Update the layout
     if (

dataface/core/compile/merge.py

@@ -423,7 +423,9 @@ class _ExtendCtx:
     theme_names: frozenset[str]  # built-in theme stems
 
 
-def _fragment_from_yaml(content: str, relpath: str) -> BaseModel:
+def _fragment_from_yaml(
+    content: str, relpath: str, *, is_builtin: bool = False
+) -> BaseModel:
     """Parse extends-fragment YAML text into a FacePatch.
 
     Fragments are partial content — they don't need the AuthoredFace
@@ -431,6 +433,13 @@ def _fragment_from_yaml(content: str, relpath: str) -> BaseModel:
     FacePatch (all-optional, no content requirement). *relpath* is the
     fragment's identity, used only in error messages.
 
+    *is_builtin* skips migration-currency detection entirely: built-in
+    theme YAML is package data we ship and keep current by construction,
+    so there is nothing to detect. A user-authored fragment (the default)
+    still gets checked, against FacePatch rather than AuthoredFace — the
+    latter's "must have layout/chart/etc" invariant would make every
+    current-schema patch look like a migration candidate.
+
     Note: fragments must use canonical (non-shorthand) form. Chart
     shorthand (``- chart_name`` without a type key) and certain source
     shapes require the AuthoredFace normalizer and will fail here with a
@@ -443,7 +452,6 @@ def _fragment_from_yaml(content: str, relpath: str) -> BaseModel:
     import yaml
     from pydantic import ValidationError as PydanticValidationError
 
-    from dataface.core.compile.migrations import prepare_face_mapping
     from dataface.core.compile.models.face.patch import FacePatch
     from dataface.core.utils import UniqueKeyLoader
 
@@ -455,8 +463,12 @@ def _fragment_from_yaml(content: str, relpath: str) -> BaseModel:
         raise CompilationError(
             f"extends: {relpath} must be a YAML mapping, got {type(data).__name__}"
         )
+    if not is_builtin:
+        from dataface.core.compile.migrations import prepare_face_mapping
+
+        data = prepare_face_mapping(data, model=FacePatch)
     try:
-        return FacePatch.model_validate(prepare_face_mapping(data))
+        return FacePatch.model_validate(data)
     except PydanticValidationError as e:
         raise CompilationError(f"extends: schema error in {relpath}: {e}") from e
 
@@ -562,7 +574,7 @@ def _resolve_entry(
             )
         theme_file = _built_in_unified_theme_dir.joinpath(theme_relpath)
         fragment = _fragment_from_yaml(
-            theme_file.read_text(encoding="utf-8"), theme_relpath
+            theme_file.read_text(encoding="utf-8"), theme_relpath, is_builtin=True
         )
         extends_patch = _merge_extends_inner(
             fragment, ctx, seen | {theme_relpath}, theme_sink
@@ -721,7 +733,9 @@ def merge_metas(
         try:
             from dataface.core.compile.migrations import prepare_face_mapping
 
-            fragment = FacePatch.model_validate(prepare_face_mapping(meta_data))
+            fragment = FacePatch.model_validate(
+                prepare_face_mapping(meta_data, model=FacePatch)
+            )
         except PydanticValidationError as e:
             raise CompilationError(
                 f"meta schema error in {meta_path.relpath}: {e}"

dataface/core/compile/migrations/__init__.py

@@ -0,0 +1,27 @@
+from .migrations import (
+    MigrationConflictError,
+    MigrationError,
+    MigrationRegistry,
+    Move,
+    SchemaMigrationWarning,
+    SchemaVersionTooOldError,
+    UnsupportedSchemaError,
+    migrate_face_yaml_text,
+    migrate_mapping,
+    migrate_yaml_text,
+    prepare_face_mapping,
+)
+
+__all__ = [
+    "MigrationConflictError",
+    "MigrationError",
+    "MigrationRegistry",
+    "Move",
+    "SchemaVersionTooOldError",
+    "SchemaMigrationWarning",
+    "UnsupportedSchemaError",
+    "migrate_face_yaml_text",
+    "migrate_mapping",
+    "migrate_yaml_text",
+    "prepare_face_mapping",
+]

dataface/core/compile/{migrations.py → migrations/migrations.py}

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import copy
 import dataclasses
+import importlib
 import json
+import types
 import warnings
 from collections.abc import Iterable, Mapping
 from datetime import date, timedelta
@@ -14,7 +16,6 @@ from typing import Annotated, TypeAlias, get_args, get_origin
 from importlib_resources import files
 from jsonschema import Draft7Validator
 from pydantic import BaseModel, ValidationError
-from pydantic.fields import FieldInfo
 
 from dataface.core.compile.schema_renderers.yaml_schema_catalog import (
     JsonObject,
@@ -45,20 +46,6 @@ class SchemaMigrationWarning(UserWarning):
     """A face was migrated in memory and should be rewritten with ``dft migrate``."""
 
 
-@dataclasses.dataclass(frozen=True)
-class MovedFrom:
-    """Declare a version-scoped structural move on a current Pydantic field.
-
-    ``old_path`` is explicit because it cannot safely be inferred. It is a YAML
-    mapping-key path, not a project file path. The registry
-    derives the destination from the annotated field's current model path.
-    """
-
-    source_schema: str
-    target_schema: str
-    old_path: YamlKeyPath
-
-
 @dataclasses.dataclass(frozen=True)
 class Move:
     """One resolved adjacent structural rename or move."""
@@ -70,7 +57,7 @@ class Move:
 
 
 class MigrationRegistry:
-    """Validated adjacent transitions assembled from model metadata."""
+    """Validated adjacent transitions assembled from tail-rename tables."""
 
     def __init__(self, moves: Iterable[Move], *, catalog: YamlSchemaCatalog) -> None:
         self.moves = tuple(moves)
@@ -81,77 +68,6 @@ class MigrationRegistry:
             self._moves_by_source[move.source_schema] = (*moves_for_schema, move)
         self._validate()
 
-    @classmethod
-    def from_model(
-        cls, root_model: type[BaseModel], *, catalog: YamlSchemaCatalog
-    ) -> MigrationRegistry:
-        """Build a move registry from ``MovedFrom`` field metadata."""
-        moves: list[Move] = []
-        for path, field in _walk_fields(root_model):
-            for marker in field.metadata:
-                if isinstance(marker, MovedFrom):
-                    moves.append(
-                        Move(
-                            marker.source_schema,
-                            marker.target_schema,
-                            marker.old_path,
-                            path,
-                        )
-                    )
-        return cls(moves, catalog=catalog)
-
-    @classmethod
-    def from_suffix_renames(
-        cls,
-        root_model: type[BaseModel],
-        source_schema: str,
-        target_schema: str,
-        renames: Iterable[tuple[YamlKeyPath, YamlKeyPath]],
-        *,
-        catalog: YamlSchemaCatalog,
-    ) -> MigrationRegistry:
-        """Build a move registry for tail-only path renames, one entry per
-        occurrence a shared style class is reused at.
-
-        ``MovedFrom`` (``from_model``) declares one fixed ``old_path`` per
-        field *declaration*, which is correct only for a field that occurs at
-        a single position in the tree. A cascade style class like
-        ``AxisLabelStyle`` is reused at hundreds of absolute positions (every
-        chart family's ``axis_x``/``axis_y``, every nested face, every theme
-        override) — one literal ``old_path`` cannot describe all of them.
-        ``renames`` instead pairs a *new-path tail* with the corresponding
-        *old-path tail*; this walks every occurrence of the new tail and
-        substitutes the old tail at that same position, keeping the shared
-        prefix. Candidates that don't structurally exist in both frozen
-        schemas (a coincidental tail match on an unrelated field, e.g. a mark
-        family also named ``line``) are silently dropped rather than passed
-        to ``Move`` — that keeps this safe to run over the whole field tree
-        without hand-enumerating every real position.
-        """
-        old_schema = catalog.schema_for(source_schema)
-        new_schema = catalog.schema_for(target_schema)
-        # Walk the field tree once and reuse it for every rename tuple —
-        # re-walking per rename is O(renames * tree_size) and the per-variant
-        # axis/scale models made tree_size large enough for that to matter.
-        paths = [path for path, _field in _walk_fields(root_model)]
-        seen: set[tuple[YamlKeyPath, YamlKeyPath]] = set()
-        moves: list[Move] = []
-        for new_tail, old_tail in renames:
-            width = len(new_tail)
-            for path in paths:
-                if len(path) < width or path[-width:] != new_tail:
-                    continue
-                old_path = path[:-width] + old_tail
-                key = (old_path, path)
-                if key in seen:
-                    continue
-                seen.add(key)
-                if _schema_path_exists(old_schema, old_path) and _schema_path_exists(
-                    new_schema, path
-                ):
-                    moves.append(Move(source_schema, target_schema, old_path, path))
-        return cls(moves, catalog=catalog)
-
     def transition_from(self, identifier: str) -> tuple[Move, ...]:
         if identifier not in self._moves_by_source:
             return ()
@@ -191,14 +107,72 @@ class MigrationRegistry:
                 )
 
 
+def suffix_rename_moves(
+    root_model: type[BaseModel],
+    source_schema: str,
+    target_schema: str,
+    renames: Iterable[tuple[YamlKeyPath, YamlKeyPath]],
+    *,
+    catalog: YamlSchemaCatalog,
+) -> tuple[Move, ...]:
+    """Resolve tail-only path renames to Move objects without constructing a registry.
+
+    ``renames`` pairs a *new-path tail* with the corresponding *old-path tail*;
+    this walks every occurrence of the new tail in the field tree and substitutes
+    the old tail at that same position, keeping the shared prefix. Candidates
+    that don't structurally exist in both frozen schemas are silently dropped —
+    that keeps this safe to run over the whole field tree without hand-enumerating
+    every real position.
+
+    Walk the field tree once and reuse it for every rename tuple — re-walking per
+    rename is O(renames * tree_size) and the per-variant axis/scale models made
+    tree_size large enough for that to matter.
+    """
+    old_schema = catalog.schema_for(source_schema)
+    new_schema = catalog.schema_for(target_schema)
+    paths = list(_walk_fields(root_model))
+    seen: set[tuple[YamlKeyPath, YamlKeyPath]] = set()
+    result: list[Move] = []
+    for new_tail, old_tail in renames:
+        width = len(new_tail)
+        for path in paths:
+            if len(path) < width or path[-width:] != new_tail:
+                continue
+            old_path = path[:-width] + old_tail
+            key = (old_path, path)
+            if key in seen:
+                continue
+            seen.add(key)
+            if _schema_path_exists(old_schema, old_path) and _schema_path_exists(
+                new_schema, path
+            ):
+                result.append(Move(source_schema, target_schema, old_path, path))
+    return tuple(result)
+
+
 def prepare_face_mapping(
-    mapping: Mapping[str, JsonValue], *, allow_expired: bool = False
+    mapping: Mapping[str, JsonValue],
+    *,
+    model: type[BaseModel] | None = None,
+    allow_expired: bool = False,
 ) -> JsonObject:
-    """Recognize and migrate a raw face-shaped mapping before model validation."""
+    """Recognize and migrate a raw face-shaped mapping before model validation.
+
+    ``model`` is the currency check: does this mapping already validate
+    against the current schema, so migration can be skipped? Defaults to
+    ``AuthoredFace`` for a real, standalone face. Callers handling a
+    patch-shaped fragment (a theme YAML's ``style:``-only content, a
+    meta.yaml override, an extends target) must pass ``FacePatch`` —
+    ``AuthoredFace`` carries a "must have layout/chart/text/title/description"
+    invariant that no patch can ever satisfy, which would make every current
+    patch look like a migration candidate.
+    """
     from dataface.core.compile.models.face.authored import AuthoredFace
 
+    currency_model = model if model is not None else AuthoredFace
+
     try:
-        AuthoredFace.model_validate(mapping)
+        currency_model.model_validate(mapping)
     except ValidationError:
         if not _face_has_historical_schemas():
             return dict(mapping)
@@ -225,58 +199,51 @@ def migrate_face_yaml_text(yaml_text: str) -> str:
     return migrate_yaml_text(yaml_text, catalog=catalog, registry=registry)
 
 
-# 0.3.1 -> 0.3.2: the axis/scale model split (per-variant AxisXStyle/AxisYStyle,
-# BaseScaleStyle.continuous nesting) renamed several theme-cascade fields.
-# Every rename here is a pure tail substitution — same shared prefix, only the
-# trailing segment(s) change — so from_suffix_renames derives every occurrence
-# a rename applies at. Leaf renames that land *inside* the "labels"/"scale"
-# containers run before the "labels"/"line" container renames themselves: a
-# leaf move creates its destination container on demand, and the later
-# container move must find that destination still empty (or absent) to avoid
-# a spurious MigrationConflictError against an unrelated field that also sets
-# the old container. See dataface/AGENTS.md's "Two validation boundaries" —
-# these are structural moves; categorical_orient (deleted), ticks.interval
-# (reinterpreted vocabulary, not renamed), and the band/point/quantize scale
-# groups (deleted) are semantic changes with no lossless move and are left to
-# raise UnsupportedSchemaError for manual migration.
-_AXIS_RESHAPE_RENAMES: tuple[tuple[YamlKeyPath, YamlKeyPath], ...] = (
-    (("labels", "format"), ("format",)),
-    (("scale", "values"), ("values",)),
-    (("scale", "continuous", "domain"), ("scale", "domain")),
-    (("scale", "continuous", "zero"), ("scale", "zero")),
-    (("scale", "continuous", "type"), ("scale", "type")),
-    (("scale", "continuous", "domain_strategy"), ("scale", "domain_strategy")),
-    (("scale", "continuous", "log", "base"), ("scale", "base")),
-    (("scale", "continuous", "pow", "exponent"), ("scale", "exponent")),
-    (("scale", "continuous", "symlog", "constant"), ("scale", "constant")),
-    (("scale", "padding"), ("scale", "band_padding_inner")),
-    (("ticks", "length"), ("ticks", "size")),
-    (("labels",), ("label",)),
-    (("line",), ("domain",)),
-)
-
-
 @cache
 def _face_migration_context() -> tuple[YamlSchemaCatalog, MigrationRegistry]:
-    """Load and validate the package's immutable migration metadata once."""
-    from dataface.core.compile.models.face.authored import AuthoredFace
+    """Load and validate the package's immutable migration metadata once.
+
+    Walks catalog.entries newest-to-oldest, skipping the oldest (predecessor
+    is None). For each remaining entry, imports the corresponding version module
+    from ``migrations.versions``. A missing module means no structural migration
+    was declared for that boundary — not an error. Each found module's
+    ``moves()`` function owns the migration strategy; the collector stays
+    agnostic to the mechanism.
+    """
     from dataface.core.compile.schema_renderers.yaml_schema_catalog import (
         load_yaml_schema_catalog,
     )
 
     catalog = load_yaml_schema_catalog()
-    marker_registry = MigrationRegistry.from_model(AuthoredFace, catalog=catalog)
-    axis_reshape_registry = MigrationRegistry.from_suffix_renames(
-        AuthoredFace,
-        "0.3.1",
-        "0.3.2",
-        _AXIS_RESHAPE_RENAMES,
-        catalog=catalog,
-    )
-    registry = MigrationRegistry(
-        marker_registry.moves + axis_reshape_registry.moves, catalog=catalog
-    )
-    return catalog, registry
+    all_moves: list[Move] = []
+    for entry in catalog.entries:
+        if entry.predecessor is None:
+            continue
+        module = _load_version_module(entry.version)
+        if module is None:
+            continue
+        all_moves.extend(
+            module.moves(entry.predecessor, entry.version, catalog=catalog)
+        )
+    return catalog, MigrationRegistry(all_moves, catalog=catalog)
+
+
+def _load_version_module(version: str) -> types.ModuleType | None:
+    """Import the version-migration module for *version*, or return None if absent."""
+    module_name = "v" + version.replace(".", "_")
+    dotted = f"dataface.core.compile.migrations.versions.{module_name}"
+    try:
+        module = importlib.import_module(dotted)
+    except ModuleNotFoundError as exc:
+        if exc.name != dotted:
+            raise
+        return None
+    if not hasattr(module, "moves"):
+        raise MigrationError(
+            f"{dotted} was found but does not define "
+            "moves(source_schema, target_schema, *, catalog) -> tuple[Move, ...]"
+        )
+    return module
 
 
 @cache
@@ -322,10 +289,10 @@ def migrate_mapping(
         identifier = moves[0].target_schema
 
     # A transition's declared moves may not cover every field a source schema
-    # allowed (a deleted field has no lossless Move — see MovedFrom's
-    # docstring). Recognizing an older schema and exhausting its transition
-    # chain is not proof the result is current-compatible; check explicitly
-    # rather than trust silently reaching the current identifier.
+    # allowed (a deleted field has no lossless Move). Recognizing an older
+    # schema and exhausting its transition chain is not proof the result is
+    # current-compatible; check explicitly rather than trust silently reaching
+    # the current identifier.
     current_errors = _current_schema_rejections(result, catalog)
     if current_errors:
         raise _unsupported_schema_error(current_errors[0])
@@ -346,15 +313,24 @@ def migrate_yaml_text(
     catalog: YamlSchemaCatalog,
     registry: MigrationRegistry,
 ) -> str:
-    """Rewrite declared scalar moves while preserving unrelated YAML text.
-
-    The general in-memory transformer supports any JSON-shaped value. The file
-    writer is deliberately narrower: its surgical YAML editor only moves scalar
-    block-mapping leaves. Unsupported shapes fail instead of reformatting a face
+    """Rewrite declared moves while preserving unrelated YAML text.
+
+    The general in-memory transformer supports any JSON-shaped value. The
+    file writer is narrower, for two shapes only: it moves scalar
+    block-mapping leaves, and it renames a key in place when the move is a
+    pure rename (old and new path share the same parent -- only the final
+    segment's spelling differs). A rename never relocates content, so it
+    carries no restriction on the value's shape -- an entire nested block
+    renames as cleanly as a scalar. Any other non-scalar move (a genuine
+    relocation to a different parent) fails instead of reformatting a face
     through a YAML dump/load round trip.
     """
     from dataface.core.compile.parser import load_yaml_mapping
-    from dataface.core.compile.yaml_patch import ScalarLeaf, set_face_values
+    from dataface.core.compile.yaml_patch import (
+        ScalarLeaf,
+        rename_key_at_path,
+        set_face_values,
+    )
 
     raw = load_yaml_mapping(yaml_text)
     identifier = _recognize(raw, catalog)
@@ -378,16 +354,25 @@ def migrate_yaml_text(
                     )
                 assert isinstance(key, str)
                 value = parent[key]
-                if value is None or not isinstance(value, (str, int, float, bool)):
-                    raise MigrationError(
-                        f"Cannot rewrite {_format_path(move.old_path)!r}: "
-                        "only scalar block-mapping "
-                        "moves are supported; migrate this field manually."
-                    )
                 source = _substitute_wildcards(move.old_path, bindings)
                 destination = _substitute_wildcards(move.new_path, bindings)
-                updates[".".join(destination)] = value
-                removals.add(".".join(source))
+                if value is None or not isinstance(value, (str, int, float, bool)):
+                    if source[:-1] != destination[:-1]:
+                        raise MigrationError(
+                            f"Cannot rewrite {_format_path(move.old_path)!r}: "
+                            "only scalar block-mapping moves or same-position "
+                            "key renames are supported; migrate this field "
+                            "manually."
+                        )
+                    # A rename never relocates content -- any value shape
+                    # (including this nested mapping/list) is safe to
+                    # rewrite in place; only the key token changes.
+                    yaml_text = rename_key_at_path(
+                        yaml_text, ".".join(source), destination[-1]
+                    )
+                else:
+                    updates[".".join(destination)] = value
+                    removals.add(".".join(source))
             _apply_move(staged, move)
         identifier = moves[0].target_schema
 
@@ -546,12 +531,12 @@ def _walk_fields(
     model: type[BaseModel],
     path: tuple[str, ...] = (),
     seen: frozenset[type[BaseModel]] = frozenset(),
-) -> Iterable[tuple[tuple[str, ...], FieldInfo]]:
+) -> Iterable[tuple[str, ...]]:
     if model in seen:
         return
     for name, field in model.model_fields.items():
         field_path = path + (name,)
-        yield field_path, field
+        yield field_path
         if field.annotation is not None:
             for nested, suffix in _nested_models(field.annotation):
                 yield from _walk_fields(nested, field_path + suffix, seen | {model})