Port SQL plan generation from pulseflow, add to screencast

New modules:
- schemas/sql_generator.py: SQLPlanGenerator generates full SQL execution
  plans from UMF metadata (base views, sequential joins, aggregations,
  window functions, UNPIVOT, derivation/survivorship column mapping)
- schemas/relationship_resolver.py: RelationshipResolver infers join
  sequences, strategies, and base tables from UMF relationships

All pulseflow-specific code removed (CatalogResolver, PipelineDiscovery,
hardcoded healthcare patterns). Generic table_resolver callback replaces
cross-pipeline resolution.

Public API: SQLPlanGenerator, generate_sql_plan()
Tests: 34 new tests covering basic generation, joins, derivations,
relationship resolution, and convenience function
Screencast: new SQL plan generation scene with voice narration

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

Author: easel

examples/narrate.sh

@@ -41,6 +41,7 @@ gen_clip "domains"  "42 domain types ship built in. Feed it a column name like p
 gen_clip "gx"       "Generate a full Great Expectations suite deterministically from metadata alone. 13 expectations covering column existence, types, nullability, and length constraints."
 gen_clip "prompts"  "Generate structured prompts for LLMs. Documentation prompts. Validation rule prompts. All the column metadata and domain context is included automatically."
 gen_clip "diff"     "Schema evolution tracking. Modify a table and see exactly what changed. Added columns. Modified descriptions."
+gen_clip "sql_plan" "Generate full SQL execution plans from UMF metadata. Joins, column derivations, survivorship logic, aggregations. All computed automatically from the schema relationships."
 gen_clip "spark"    "Now the PySpark features. Starting a Spark session. Creating DataFrames. Profiling schemas. Validating data against UMF specs. And generating sample data. All from the same UMF metadata."
 gen_clip "close"    "That's tablespec. Define once. Use everywhere."
 
@@ -59,6 +60,7 @@ CLIP_domains=${CLIP_DUR[domains]}
 CLIP_gx=${CLIP_DUR[gx]}
 CLIP_prompts=${CLIP_DUR[prompts]}
 CLIP_diff=${CLIP_DUR[diff]}
+CLIP_sql_plan=${CLIP_DUR[sql_plan]}
 CLIP_spark=${CLIP_DUR[spark]}
 CLIP_close=${CLIP_DUR[close]}
 EOF

examples/scene.py

@@ -294,6 +294,128 @@ def scene_spark():
     spark.stop()
 
 
+def scene_sql_plan():
+    from tablespec import (
+        UMF,
+        UMFColumn,
+        UMFColumnDerivation,
+        DerivationCandidate,
+        Nullable,
+        Relationships,
+        OutgoingRelationship,
+        generate_sql_plan,
+    )
+
+    # Build a derived table that joins claims + providers
+    target = UMF(
+        version="1.0",
+        table_name="Claims_Summary",
+        description="Enriched claims with provider info",
+        table_type="generated",
+        columns=[
+            UMFColumn(
+                name="claim_id",
+                data_type="VARCHAR",
+                length=50,
+                description="Unique claim identifier",
+                nullable=Nullable(MD=False, MP=False, ME=False),
+                derivation=UMFColumnDerivation(
+                    strategy="primary_key",
+                    candidates=[
+                        DerivationCandidate(
+                            table="Medical_Claims",
+                            column="claim_id",
+                            priority=1,
+                        )
+                    ],
+                ),
+            ),
+            UMFColumn(
+                name="claim_amount",
+                data_type="DECIMAL",
+                precision=10,
+                scale=2,
+                description="Claim amount",
+                derivation=UMFColumnDerivation(
+                    candidates=[
+                        DerivationCandidate(
+                            table="Medical_Claims",
+                            column="claim_amount",
+                            priority=1,
+                        )
+                    ],
+                ),
+            ),
+            UMFColumn(
+                name="provider_name",
+                data_type="VARCHAR",
+                length=200,
+                description="Provider full name",
+                derivation=UMFColumnDerivation(
+                    candidates=[
+                        DerivationCandidate(
+                            table="Providers",
+                            column="provider_name",
+                            priority=1,
+                        )
+                    ],
+                ),
+            ),
+            UMFColumn(
+                name="state_code",
+                data_type="VARCHAR",
+                length=2,
+                description="Provider state",
+                derivation=UMFColumnDerivation(
+                    candidates=[
+                        DerivationCandidate(
+                            table="Providers",
+                            column="state_code",
+                            priority=1,
+                        )
+                    ],
+                ),
+            ),
+        ],
+        relationships=Relationships(
+            outgoing=[
+                OutgoingRelationship(
+                    target_table="Medical_Claims",
+                    source_column="claim_id",
+                    target_column="claim_id",
+                    type="foreign_to_primary",
+                    confidence=1.0,
+                ),
+                OutgoingRelationship(
+                    target_table="Providers",
+                    source_column="provider_id",
+                    target_column="provider_id",
+                    type="foreign_to_primary",
+                    confidence=1.0,
+                ),
+            ]
+        ),
+    )
+
+    from tablespec import load_umf_from_yaml
+
+    claims = load_umf_from_yaml(str(CLAIMS_YAML))
+    providers = load_umf_from_yaml(str(PROVIDERS_YAML))
+
+    related = {
+        "Medical_Claims": claims,
+        "Providers": providers,
+    }
+
+    sql = generate_sql_plan(target, related)
+    # Show first 40 lines
+    lines = sql.splitlines()
+    for line in lines[:40]:
+        print(line)
+    if len(lines) > 40:
+        print(f"... ({len(lines)} total lines)")
+
+
 # ─── Dispatch ─────────────────────────────────────────────────────
 
 SCENES = {
@@ -305,6 +427,7 @@ def scene_spark():
     "gx": scene_gx,
     "prompts": scene_prompts,
     "diff": scene_diff,
+    "sql_plan": scene_sql_plan,
     "spark": scene_spark,
 }
 

examples/screencast.sh

@@ -149,7 +149,16 @@ echo
 run uv run python examples/scene.py diff
 wait_for_clip "${CLIP_diff:-5}" 3
 
-# ─── Scene 9: Spark ──────────────────────────────────────────────
+# ─── Scene 9: SQL Plan Generation ────────────────────────────────
+
+divider
+mark "sql_plan"
+narrate "Generate full SQL execution plans from UMF — joins, derivations, survivorship, all automatic."
+echo
+run uv run python examples/scene.py sql_plan
+wait_for_clip "${CLIP_sql_plan:-8}" 4
+
+# ─── Scene 10: Spark ─────────────────────────────────────────────
 
 divider
 mark "spark"