Add Graphene .gsql semantic model importer (#181)

* Add Graphene .gsql semantic model importer

* Load Graphene projects in one pass

* Normalize Graphene percentile metrics

* Preserve explicit Graphene primary keys

* Preserve one-to-many join keys

* Preserve unresolved Graphene joins

* Preserve composite Graphene keys

* Project relationship join keys

* Preserve Graphene parameterized types

* Preserve unsupported Graphene join predicates

* Use Graphene view output aliases

* Inline Graphene computed dimensions

* Choose Graphene view primary keys from projections

Author: nicosuave

README.md

@@ -224,7 +224,7 @@ See `examples/` for more.
 
 - SQL query interface with automatic rewriting
 - Automatic joins across models
-- Multi-format adapters (Cube, MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML)
+- Multi-format adapters (Cube, MetricFlow, LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML, Graphene GSQL)
 - SQLGlot-based SQL generation and transpilation
 - Pydantic validation and type safety
 - Pre-aggregations with automatic routing
@@ -236,7 +236,7 @@ See `examples/` for more.
 
 ## Multi-Format Support
 
-Auto-detects: Sidemantic (SQL/YAML), Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML
+Auto-detects: Sidemantic (SQL/YAML), Cube, MetricFlow (dbt), LookML, Hex, Rill, Superset, Omni, BSL, GoodData LDM, OSI, AtScale SML, ThoughtSpot TML, Graphene GSQL
 
 ```bash
 sidemantic query "SELECT revenue FROM orders" --models ./my_models

docs/compatibility/graphene.md

@@ -0,0 +1,24 @@
+# Graphene GSQL Compatibility
+
+Sidemantic can import Graphene `.gsql` semantic model files through `load_from_directory()` and CLI commands that use the normal model loader.
+
+The importer is a Sidemantic-owned compatibility parser for Graphene's documented model declarations. It does not bundle Graphene, call the Graphene runtime, or vendor Graphene's parser/grammar/analyzer.
+
+## Supported
+
+- `table name (...)` physical table definitions
+- `table name as (...)` derived table definitions, with the view query preserved as model SQL
+- `extend name (...)` blocks
+- Base columns as Sidemantic dimensions
+- Computed scalar expressions as dimensions
+- Aggregate expressions and measure-composed expressions as metrics
+- `join one` as `many_to_one`
+- `join many` as `one_to_many`
+- Graphene metadata annotations such as `#ratio`, `#pct`, `#currency=USD`, `#unit=minutes`, `#timeGrain=day`, `#timeOrdinal=month_of_year`, `#description=...`, and `#pii`
+
+## Not Supported
+
+- Graphene Markdown pages are not imported as semantic models.
+- Full GSQL query compilation is not reimplemented; `select` statements are not imported as standalone semantic models, and `table name as (...)` query text is preserved.
+- Graphene-specific query-time behavior such as implicit modeled joins, multi-hop dot traversal, `group by all`, query DAGs, and page input interpolation is outside the importer.
+- Relationship aliases are represented by generated alias models that point at the same physical table as the target model.

docs/native-format.md

@@ -7,7 +7,7 @@ The native format has two source forms:
 - YAML semantic project files.
 - SQL semantic definition files.
 
-The native format is the runtime contract. External formats such as LookML, MetricFlow, Hex, Rill, Malloy, Omni, Superset, GoodData, Snowflake Cortex, ThoughtSpot, Holistics, Tableau, AtScale SML, BSL, and Yardstick should be converted into this format by Python importers before they are expected to run through the Rust native runtime.
+The native format is the runtime contract. External formats such as LookML, MetricFlow, Hex, Rill, Malloy, Omni, Superset, GoodData, Snowflake Cortex, ThoughtSpot, Holistics, Tableau, AtScale SML, BSL, Yardstick, and Graphene GSQL should be converted into this format by Python importers before they are expected to run through the Rust native runtime.
 
 ## Versioning
 

sidemantic-schema.json

@@ -1172,7 +1172,7 @@
             }
           ],
           "default": null,
-          "description": "Primary key column(s) in related model (defaults to id)",
+          "description": "Primary/unique key column(s): related model key for many_to_one, local model key for one_to_many",
           "title": "Primary Key"
         },
         "related_foreign_key": {
@@ -2964,7 +2964,7 @@
                   }
                 ],
                 "default": null,
-                "description": "Primary key column(s) in related model (defaults to id)",
+                "description": "Primary/unique key column(s): related model key for many_to_one, local model key for one_to_many",
                 "title": "Primary Key"
               },
               "related_foreign_key": {