fix(#1470): two-hop ref display resolution (display_field that is itself a ref)

build_display_join_plan resolved one hop only — when a target's display_field
is itself a to-one ref, the FK display column projected the nested ref's raw
UUID. Now chains a second LEFT JOIN to the nested target's display_field so
{rel}__display carries the two-hop human name. One-hop unchanged; degrades to
the prior column when the nested target lacks a display_field. Closes the
two-hop "harder related case" from #1471. Plan-string unit tests assert the
exact chained SQL; full -m "not e2e" suite green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: claude

.claude/CLAUDE.md

@@ -374,4 +374,4 @@ Example: `examples/ops_dashboard` has working `bar_chart` (FK `group_by: system`
 - **KG re-seeding**: `ensure_seeded()` checks a version key; bump it in `seed.py` when TOML data changes.
 
 ---
-**Version**: 0.86.21 | **Python**: 3.12+ | **Status**: Production Ready
+**Version**: 0.86.22 | **Python**: 3.12+ | **Status**: Production Ready

CHANGELOG.md

@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.86.22] - 2026-06-25
+
+### Fixed
+- **#1470/#1471 two-hop: ref columns whose target `display_field` is itself a ref now resolve to a human string, not the nested FK's UUID.** `build_display_join_plan` resolved one hop only — when an entity's `display_field` points at another ref (e.g. `Manuscript.display_field: student → User`), the FK display column projected the nested ref's raw UUID. It now detects that case and chains a second `LEFT JOIN` to the nested target's `display_field`, so the `{rel}__display` column carries the two-hop name. One-hop (scalar `display_field`) behaviour is unchanged; degrades to the prior column when the nested target has no `display_field`. This closes the "harder related case" noted on #1471. (Follow-on: a PG fixture exercising the chained join at runtime — currently the join SQL is asserted at the generation level + composes via the proven one-hop path.)
+
 ## [0.86.21] - 2026-06-25
 
 ### Fixed

ROADMAP.md

@@ -1,7 +1,7 @@
 # DAZZLE Development Roadmap
 
 **Last Updated**: 2026-06-16
-**Current Version**: v0.86.21
+**Current Version**: v0.86.22
 
 For past releases, see [CHANGELOG.md](CHANGELOG.md).
 

homebrew/dazzle.rb

@@ -10,10 +10,10 @@ class Dazzle < Formula
 
   desc "DSL-first application framework with LLM-assisted development"
   homepage "https://github.com/manwithacat/dazzle"
-  version "0.86.21"
+  version "0.86.22"
   license "MIT"
 
-  url "https://github.com/manwithacat/dazzle/archive/refs/tags/v0.86.21.tar.gz"
+  url "https://github.com/manwithacat/dazzle/archive/refs/tags/v0.86.22.tar.gz"
   sha256 "PLACEHOLDER_SOURCE_SHA256"
 
   # pydantic-core requires Rust to build from source, so use pre-built wheels

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dazzle-dsl"
-version = "0.86.21"
+version = "0.86.22"
 description = "DAZZLE — declarative SaaS framework with built-in compliance (SOC 2, ISO 27001), provable RBAC, and graph features"
 readme = "README.md"
 requires-python = ">=3.12"

src/dazzle/http/runtime/relation_loader.py

@@ -476,9 +476,35 @@ def build_display_join_plan(
             alias = f"_fkd_{relation_name}"
             fk_col = quote_identifier(relation.foreign_key_field)
             target = quote_identifier(relation.to_entity)
-            display_col = quote_identifier(display_field)
             joins.append(f'LEFT JOIN {target} AS "{alias}" ON "{alias}".id = {base}.{fk_col}')
-            extra_cols.append(f'"{alias}".{display_col} AS "{relation_name}__display"')
+
+            # #1471 two-hop: if the target's own display_field is itself a to-one
+            # ref (e.g. Manuscript.display_field: student → User), chain a second
+            # LEFT JOIN so the column resolves to the nested target's display name
+            # instead of the nested FK's raw UUID. Falls back to the one-hop column
+            # when the display_field isn't a ref or the nested target has no
+            # display_field (degrades to the prior behaviour, no regression).
+            nested = self.registry.get_relation(relation.to_entity, display_field)
+            nested_display = (
+                self.registry.display_fields.get(nested.to_entity)
+                if nested and nested.is_to_one
+                else None
+            )
+            if nested and nested.is_to_one and nested_display:
+                alias2 = f"_fkd2_{relation_name}"
+                nested_fk = quote_identifier(nested.foreign_key_field)
+                nested_target = quote_identifier(nested.to_entity)
+                joins.append(
+                    f'LEFT JOIN {nested_target} AS "{alias2}" '
+                    f'ON "{alias2}".id = "{alias}".{nested_fk}'
+                )
+                extra_cols.append(
+                    f'"{alias2}".{quote_identifier(nested_display)} AS "{relation_name}__display"'
+                )
+            else:
+                extra_cols.append(
+                    f'"{alias}".{quote_identifier(display_field)} AS "{relation_name}__display"'
+                )
         return joins, extra_cols, fallback
 
     def apply_display_joins_to_rows(

src/dazzle/mcp/semantics_kb/core.toml

@@ -3,7 +3,7 @@
 
 [meta]
 category = "Core Constructs"
-version = "0.86.21"
+version = "0.86.22"
 
 [concepts.entity]
 category = "Core Construct"

tests/unit/test_fk_display_join.py

@@ -44,6 +44,64 @@ def _registry_with(
     return registry
 
 
+def _two_hop_registry() -> RelationRegistry:
+    """Order → customer (Customer); Customer.display_field = rep → SalesRep;
+    SalesRep.display_field = name. So Order.customer should two-hop resolve to
+    SalesRep.name, not the nested rep UUID (#1471 two-hop)."""
+    registry = RelationRegistry()
+    registry.register(
+        "Order",
+        RelationInfo(
+            name="customer",
+            from_entity="Order",
+            to_entity="Customer",
+            kind="many_to_one",
+            foreign_key_field="customer_id",
+        ),
+    )
+    registry.register(
+        "Customer",
+        RelationInfo(
+            name="rep",
+            from_entity="Customer",
+            to_entity="SalesRep",
+            kind="many_to_one",
+            foreign_key_field="rep_id",
+        ),
+    )
+    registry.display_fields["Customer"] = "rep"  # display_field is itself a ref
+    registry.display_fields["SalesRep"] = "name"
+    return registry
+
+
+class TestTwoHopDisplayJoin:
+    def test_chains_second_join_when_display_field_is_ref(self) -> None:
+        loader = RelationLoader(registry=_two_hop_registry(), entities=[])
+        joins, extras, fallback = loader.build_display_join_plan("Order", ["customer"])
+
+        assert fallback == []
+        assert len(joins) == 2  # base join + nested join
+        # base: Customer joined on Order.customer_id
+        assert any(
+            '"Customer"' in j and '"customer_id"' in j and '"_fkd_customer"' in j for j in joins
+        )
+        # nested: SalesRep joined on _fkd_customer.rep_id
+        assert any(
+            '"SalesRep"' in j and '"_fkd2_customer"' in j and '"_fkd_customer"."rep_id"' in j
+            for j in joins
+        )
+        # the display column resolves to SalesRep.name (two hops), not the UUID
+        assert extras[0] == '"_fkd2_customer"."name" AS "customer__display"'
+
+    def test_one_hop_unaffected_by_two_hop_logic(self) -> None:
+        # display_field is a plain scalar → still a single join + direct column.
+        registry = _registry_with("Order", "customer", "Customer", "customer_id", "name")
+        loader = RelationLoader(registry=registry, entities=[])
+        joins, extras, _ = loader.build_display_join_plan("Order", ["customer"])
+        assert len(joins) == 1
+        assert extras[0] == '"_fkd_customer"."name" AS "customer__display"'
+
+
 class TestBuildDisplayJoinPlan:
     def test_emits_join_and_alias_column_for_registered_display(self) -> None:
         registry = _registry_with("Order", "customer", "Customer", "customer_id", "name")