Align Python native contract and SQL correctness

Author: nicosuave

docs/native-fixtures.md

@@ -79,7 +79,8 @@ The suite currently covers:
 - Parameter interpolation in query filters.
 - Pre-aggregation routing shape and DuckDB execution against seeded rollup tables.
 - Semantic SQL rewrite cases for single-model and relationship queries.
-- Query-local table calculations on the Rust SQL compiler path, including Rust-only DuckDB result coverage.
+- Query-local table calculations for the shared Python/Rust subset. Python applies these after fetching rows;
+  Rust compiles them into SQL window expressions.
 - Native `.sql` definition files.
 - Native SQL frontmatter model definitions.
 - YAML `sql_metrics` and `sql_segments` blocks.
@@ -112,6 +113,15 @@ The default Rust runner loads every manifest fixture, asserts `expected/validati
 
 The `adbc-exec` Rust runner executes every query with `expected_result` or `rust_expected_result` through DuckDB ADBC, using the fixture seed SQL and result columns from the manifest. Any Rust-only expected output must include `rust_only_reason`. It is enabled in CI after installing the DuckDB ADBC driver.
 
+Table-calculation fixture contract:
+
+- Shared table calculations may use `percent_of_total`, `percent_of_previous`, `running_total`, `rank`, `row_number`, or `moving_average`.
+- Shared calculations should include deterministic query `order_by` when row order affects the result.
+- Python evaluates shared calculations with `TableCalculationProcessor` after query execution.
+- Rust evaluates shared calculations by compiling them into SQL expressions.
+- Rust-only table calculation types (`dense_rank`, `difference`, `lead`, `lag`) must use `rust_expected_result` and `rust_only_reason`.
+- Python-only post-query table calculation types (`percent_of_column_total`, `percentile`) stay out of shared native fixtures until Rust supports them.
+
 ## Adding Fixtures
 
 Add the narrowest fixture that proves one semantic behavior. Avoid kitchen-sink fixtures unless the behavior itself is cross-feature interaction.

docs/native-format.md

@@ -9,6 +9,20 @@ The native format has two source forms:
 
 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.
 
+## Rust Loader Scope
+
+The Rust runtime and Rust CLI directory loader intentionally have a smaller direct
+input surface than Python:
+
+- `.yml` / `.yaml`: native Sidemantic YAML or Cube YAML.
+- `.sql`: native Sidemantic SQL definition files.
+
+They do not auto-detect LookML, MetricFlow/dbt manifests, Hex, Rill, Malloy,
+Omni, Superset, GoodData, Snowflake Cortex, ThoughtSpot, Holistics, Tableau,
+AtScale SML, BSL, Yardstick, or other external source formats. Convert those
+formats through the Python CLI/API first, then load the exported native YAML/SQL
+with the Rust runtime.
+
 ## Versioning
 
 Current native format version: `1`.
@@ -61,6 +75,18 @@ Top-level sections:
 | `metrics` | No | Graph-level metrics. Rust assigns these to exactly one owning model when possible. |
 | `parameters` | No | Graph-level parameters for templates and query-time substitution. |
 
+Top-level metrics are graph-scoped in the Python runtime. The Rust runtime does not
+store a separate graph-metric namespace at execution time; it assigns each top-level
+metric to one owning model by resolving explicit model references, metric dependencies,
+entity dimensions, or a single-model project fallback. If Rust cannot infer exactly
+one owner, loading fails. Portable native files should therefore make top-level metric
+dependencies explicit, for example `orders.total_revenue` rather than `total_revenue`
+when multiple models define the same local metric name. Dotted top-level metric names
+are allowed and are resolved by exact metric name before `model.metric` parsing.
+
+Top-level parameters remain graph-scoped in both runtimes. Query APIs interpolate
+parameter values before SQL compilation.
+
 ## Models
 
 Models describe physical or logical query sources.
@@ -94,6 +120,12 @@ At least one of `table`, `sql`, or `source_uri` should be present unless the mod
 | `pre_aggregations` | No | List of pre-aggregation definitions. |
 | `default_time_dimension` | No | Time dimension to add by default when the query needs time grouping. |
 | `default_grain` | No | Default time grain for the default time dimension. |
+| `auto_dimensions` | No | Python auto-discovery flag. Rust accepts `false` for compatibility and rejects `true` because it does not perform schema discovery. |
+
+Canonical CLI-authored files should use `metrics` and `sql`. The native loaders
+also accept compatibility input aliases: model-level `measures` for `metrics`,
+dimension/metric `expr` for `sql`, and metric `measure` for `sql`. Exports use
+canonical field names.
 
 Single-column primary key:
 
@@ -332,8 +364,21 @@ relationships:
 | `primary_key_columns` | Conditional | Explicit target-column list. |
 | `through` | For many-to-many | Junction model. |
 | `through_foreign_key` | For many-to-many | Source-to-through key. |
+| `through_foreign_key_columns` | For many-to-many | Explicit source-to-through key columns. |
 | `related_foreign_key` | For many-to-many | Through-to-target key. |
-| `sql` | No | Custom join SQL using runtime placeholders where supported. |
+| `related_foreign_key_columns` | For many-to-many | Explicit through-to-target key columns. |
+| `sql` | No | Custom join SQL using `{from}` and `{to}` runtime placeholders. |
+
+For CLI-authored native files, prefer explicit `foreign_key` and `primary_key`
+fields. Omitted keys are still supported for compatibility: `many_to_one`
+defaults the source key to `{name}_id`, while `one_to_many` and `one_to_one`
+default the related-side key to `id`; omitted `primary_key` resolves to the
+target model's declared primary key when building graph joins.
+
+When `sql` is present, Python and Rust use it instead of the FK/PK-generated
+predicate. `{from}` is replaced with the source model's runtime alias and `{to}`
+with the target model's runtime alias. Reverse graph traversal swaps the
+placeholders automatically.
 
 Relationship types: