entity role: cross-model join matching via entity.role

[QMalcolm]

Summary

Stacked on #2126 (mfsql-where-translator) — this PR targets that branch, not main.

Widens cross-model join matching from requiring the exact same entity name on both sides
to matching on join key (entity.role if set, else entity.name). This lets a model
declare multiple, differently-named entities (e.g. buyer, seller) that each join to
the same target entity elsewhere (e.g. user) under their own local name.

Entity.role already existed in the schema/protocol/impl but was dead code - never read
anywhere in join-building. This PR makes it do something, and removes a hack the project
had already hit and documented: scd_bookings.yaml carried a duplicate user entity
aliasing guest_id, commented "Hack around lack of support for entity/role functionality" with its own TODO: Remove this when full support ... is available.
guest now declares role: user directly instead.

What this touches, and why it's bigger than "widen a few dict keys"

Investigation before writing code found two separate, independently-implemented
join-matching systems, both keyed on literal entity-name equality, both required for a
role-based join to actually work end-to-end rather than validate-then-crash:

1. Query resolution (join_lookup.py, manifest_object_lookup.py,
   entity_lookup.py) - decides whether a query is valid. Now matches by join key;
   JoinModelOnRightDescriptor always carries the right model's own entity name (never
   the left's), since that's the identity entity_join_subgraph.py needs for graph
   connectivity.
2. Dataflow plan building (node_evaluator.py,
   semantic_model_join_evaluator.py) - a wholly separate, legacy implementation that
   dataflow_plan_builder.py routes through instead of the semantic_graph module.
   Confirmed by direct testing: with only (1) fixed, a role-based query resolved
   successfully and then failed at plan-building with "Unable to join all items in
   request" - exactly the validate-then-crash risk flagged before starting.
   is_valid_semantic_model_join now takes separate left_entity_reference/
   right_entity_reference. A fourth call site inside evaluate_node (an early
   "is this even joinable" classification, easy to miss) had the same literal-name
   assumption and needed the same fix.
3. SQL predicate construction (sql_join_builder.py) - the deepest layer.
   join_on_entity (a single shared reference) is used to find the join column on
   both sides via column_associations_for_entity; with genuinely different left/right
   names, the left-side lookup finds nothing. Added join_on_left_entity to
   JoinDescription/JoinLinkableInstancesRecipe - None means "same as
   join_on_entity" (every existing non-role join, unchanged). Verified the actual
   generated SQL end-to-end (subq.guest = users_latest.user_id, using guest_id
   correctly).

Also found and fixed a real correctness risk before shipping: if more than one local
entity shares a role (e.g. both guest and host declared role: user), the naive
implementation silently picked whichever was iterated first - a query that looks correct
but joins on an arbitrary entity, no error, no way to ask for the other one. Added an
explicit check that raises a clear error naming the competing entities instead. There's
no "default" disambiguation mechanism yet (unlike the POC design that motivated this
work) - deliberately deferred, which is why scd_bookings.yaml only adds role: user to
guest, not host.

Explicitly out of scope (separate, larger pieces)

• Full query-surface role names - guest__x/host__x resolving independently as
  distinct dunder paths. Dunder-path resolution today still uses the target entity's
  own name (user__x), confirmed empirically, not the role-aliased local name.
• Multi-hop role-based joins (dataflow_join_validator.py's JoinDataflowOutputValidator
  is unchanged, still single-shared-reference).
• A default-style disambiguation mechanism for the multi-role-per-model ambiguity case.

Test plan

• New tests in test_node_evaluator.py: a passing single-role join (asserting
  join_on_left_entity is set correctly) and the ambiguous-multi-role rejection.
• Full tests_metricflow_semantics suite (287 passed) and tests_metricflow suite
  (1159 passed, 4 pre-existing/unrelated release_validation failures confirmed
  present on the base commit too via git stash comparison) - zero regressions.
• Existing golden-SQL snapshot diffs for SCD tests reviewed and confirmed as the
  expected, purely mechanical removal of the redundant user/booking__user
  columns bookings_source no longer emits.
• Cross-checked against the real-data DuckDB integration suite (itest_scd.yaml,
  which already covers the exact listing__user__home_state_latest path) that
  nothing about correctness changed, only SQL text/aliasing.
• ruff/black/mypy clean.
• No changelog entry yet - stacked on an unmerged PR, not yet ready for release.

🤖 Generated with Claude Code

[github-actions]

Thank you for your pull request! We could not find a changelog entry for this change. For details on how to document a change, see the contributing guide.