feat: shared subplans (ReferenceRel) / DataFrame.cache() (CTEs)

Add CTE / shared-subplan support at both the builders.plan and native
DataFrame layers, carrying the shared subtrees in-band inside the resolved
Plan (the leading `rel` entries of Plan.relations, the way a Plan already
carries its extension declarations) rather than out-of-band via a contextvar.

type_inference: thread an optional `subtrees` list through infer_rel_schema /
infer_expression_type and add a `reference` case that resolves a ReferenceRel's
schema against subtrees[subtree_ordinal]. infer_plan_schema extracts the leading
subtrees and wraps them in a _SubtreeScope that memoizes each subtree's schema
(so a subtree referenced from many places is inferred once, not exponentially)
and detects reference cycles (a clear error instead of RecursionError).

builders: a `reference(plan)` builder promotes a plan to a shared subtree and
returns a ReferenceRel-rooted plan; every relational builder propagates its
inputs' shared subtrees upward and rebases subtree_ordinals when merging inputs,
structurally deduping identical subtrees so a cached frame reused across
branches is emitted once and referenced many times. A shared _plan_from helper
owns subtree propagation + Plan assembly, so each builder is a single call.

dataframe: DataFrame.cache() marks a frame as a reusable common subplan; the
hint() guard for RelCommon-less relations (e.g. a ReferenceRel) is restored.

A cached frame consumed inside a subquery is inlined into that subquery (a
plan-global ReferenceRel cannot cross the subquery boundary), keeping the
emitted plan valid.

Rel-walking primitives (plan_subtrees, rebase_reference_ordinals,
inline_reference_rels) live in substrait.utils and discover child-Rel fields
from the protobuf descriptor rather than a hand-maintained table.

Closes #211

Author: nielspardon

src/substrait/builders/extended_expression.py

@@ -13,8 +13,10 @@
 from substrait.extension_registry import ExtensionRegistry
 from substrait.type_inference import infer_extended_expression_schema, outer_schemas
 from substrait.utils import (
+    inline_reference_rels,
     merge_extension_declarations,
     merge_extension_urns,
+    plan_subtrees,
     type_num_names,
 )
 
@@ -1041,7 +1043,17 @@ def _inner_rel(query, registry: ExtensionRegistry, base_schema):
         plan = query(registry) if callable(query) else query
     finally:
         outer_schemas.reset(token)
-    return plan, plan.relations[-1].root.input
+    rel = plan.relations[-1].root.input
+    # An Expression.Subquery embeds only a bare Rel, but a ReferenceRel is
+    # plan-global -- it cannot resolve once lifted out of its plan. So if the
+    # subquery's plan carries shared subtrees (e.g. it uses a cached frame),
+    # inline them into the subquery Rel, making it self-contained. A cached frame
+    # used inside a subquery is thus inlined there rather than shared across the
+    # subquery boundary.
+    subtrees = plan_subtrees(plan)
+    if subtrees:
+        rel = inline_reference_rels(rel, subtrees)
+    return plan, rel
 
 
 def scalar_subquery(query, alias: Union[str, None] = None):