DEV-1703: typed-pipeline branch → dev-1450 (latest: merge origin/main)

.claude/skills/slayer-models.md

@@ -43,7 +43,7 @@ measures:
     formula: "amount:sum / *:count"
 ```
 
-Aggregation is specified at query time with **colon syntax**: `"amount:sum"`, `"amount:avg"`, `"*:count"`. A bare-name reference like `{"formula": "aov"}` resolves to the saved `ModelMeasure` formula on the model. Built-in aggregations: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `first`, `last`, `weighted_avg`, `median`, `percentile`, `stddev_samp`, `stddev_pop`, `var_samp`, `var_pop`, `corr`, `covar_samp`, `covar_pop`. The two-column ones (`corr`, `covar_samp`, `covar_pop`) take the second column as a named param: `price:corr(other=quantity)`.
+Aggregation is specified at query time with **colon syntax**: `"amount:sum"`, `"amount:avg"`, `"*:count"`. A bare-name reference like `{"formula": "aov"}` resolves to the saved `ModelMeasure` formula on the model. Built-in aggregations: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `count_distinct_approx`, `first`, `last`, `weighted_avg`, `median`, `percentile`, `stddev_samp`, `stddev_pop`, `var_samp`, `var_pop`, `corr`, `covar_samp`, `covar_pop`. `count_distinct_approx` is dialect-aware (native approximate-distinct where available, exact `COUNT(DISTINCT)` fallback otherwise). The two-column ones (`corr`, `covar_samp`, `covar_pop`) take the second column as a named param: `price:corr(other=quantity)`.
 
 ## Data Types
 

.claude/skills/slayer-overview.md

@@ -23,16 +23,18 @@ SLayer is a lightweight, agent-first semantic layer. Instead of writing raw SQL,
 
 Query-backed models support two access patterns: **run by name** (`engine.execute("monthly_revenue", variables={...})` runs the stored backing query) and **as a source_model** (`{"source_model": "monthly_revenue", ...}` in another query). Variable precedence: runtime kwarg > stage > outer query > model defaults.
 
+- **SessionPolicy** (Row-Level Security, DEV-1578 / DEV-1718) — immutable, agent-invisible forced filter passed at engine/local-client init. Carries one required `ruleset`: a `ColumnFilterRuleset` (filter every table that has the tenant column) or a `JoinFilterRuleset` (one anchor table holds the identifier; others reach it via explicit joins, with a whitelist for shared tables). `SlayerQueryEngine(storage, policy=SessionPolicy(ruleset=ColumnFilterRuleset(column="organization_uuid", value=...)))`. Silently scopes every query (base, joins, CTEs, sql-mode, query-backed, profiling) to one tenant at the final-SQL layer. No-filtering = `policy=None`; local-engine only (HTTP `policy=` raises). See [row-level-security.md](../../docs/concepts/row-level-security.md).
+
 ## MCP Tools
 
-Discovery: `list_datasources`, `models_summary`, `inspect_model` (with sample data)
-Querying: `query`
+Discovery: `list_datasources`, `models_summary`, `inspect` (point lookup by `reference` + required `entity_type`; the model path carries sample data; `reference` accepts a single id, a same-kind **list** for a batched lookup, or **`None`/omitted** for the whole **collection** at that kind — `entity_type="model"` lists all models grouped by datasource, `entity_type="datasource"` lists all datasources, subsuming `models_summary` / `list_datasources`). `inspect_model` is DEPRECATED — use `inspect`.
+Querying: `query`, `recommend_root_model` (given `model.column` / `model.metric` items, introspects the join graph to recommend the query `source_model` + each item's join path from it; optional `root_hint` forces an intended root when it reaches every item; returns partial-root `coverage` when no single model reaches all items)
 Model editing: `create_model`, `edit_model`, `delete_model`
 Datasources: `create_datasource`, `list_datasources`, `describe_datasource` (includes table listing by default), `edit_datasource`, `delete_datasource`, `set_datasource_priority`
 Ingestion: `ingest_datasource_models`
 Schema drift: `validate_models` (read-only diff against live schema; surfaces `SchemaDriftError` cleanups)
 Memory write side: `save_memory`, `forget_memory` (per-entity learnings indexed by canonical entity strings — see [memories.md](../../docs/concepts/memories.md))
-Search: `search` (three-channel: entity-overlap BM25 over memories + tantivy full-text + optional dense embedding similarity, RRF-fused per kind so each output bucket — `memories` / `example_queries` / `entities` — has membership/order invariant under the other buckets' caps; embeddings require the `embedding_search` extra and degrade gracefully when unavailable; partitions query-bearing memories into `example_queries` — see [search.md](../../docs/concepts/search.md))
+Search: `search` (three-channel: entity-overlap BM25 over memory tags + tantivy full-text + optional dense embedding similarity, RRF-fused into a single flat `SearchResponse.results: List[SearchHit]` (DEV-1532) with a `kind` discriminator — `"memory"` / `"datasource"` / `"model"` / `"column"` / `"measure"` / `"aggregation"`; query-bearing memories are still memory hits, distinguished by `hit.query is not None`. Optional `cypher_filter` pre-narrows all three channels: full openCypher when `advanced_search` is installed, naive `MATCH (n:Label) RETURN n.id AS id` kind-filter otherwise. Embeddings also require the `advanced_search` extra and degrade gracefully when unavailable — see [search.md](../../docs/concepts/search.md))
 
 ## Package Structure
 

.claude/skills/slayer-query.md

@@ -22,7 +22,9 @@ A `SlayerQuery` is a JSON/dict object. The same shape works across the REST API,
 
 `order[].column` is the short alias (`count`, `revenue_sum`) — not the colon form.
 
-**Dim-only queries deduplicate.** A query with no measures and at least one dimension or time-dimension auto-emits `GROUP BY <dim/td aliases>` and returns the distinct combinations. The `GROUP BY` is applied before `LIMIT`, so a row cap can't silently drop unique tuples. There is no opt-out — if you want the raw row stream, query the underlying table outside the semantic layer.
+**Ordering by something you don't project.** `order` may name an undeclared column/aggregate/expression ("top-N by X, show only Y, Z"). Computed hidden, sorted on, and stripped from the result: an **aggregate** (`amount:sum`, `customers.revenue:sum`), an inline **transform** (`rank(amount:sum)`, `change(...)`, `cumsum`/`lag`/`lead`/`ntile`), an inline **composite** (`revenue:sum / cnt:sum`, `abs(amount:sum)`), and a **windowed** aggregate (`amount:sum(window='90d')`, alone or inside a composite). A **raw row column** is orderable only in a raw-rows query (`distinct_dimension_values: false`); in a grouped/dedup query it's rejected (HTTP 400 — add it to `dimensions` or order by an aggregate of it). A **joined** row column is rejected — project it. Order expressions must use formula syntax for their operands, not the `name`s of measures declared in the same query: `{"column": "revenue:sum / cnt:sum"}` works, `{"column": "rev / cnt"}` is rejected.
+
+**Dim-only queries deduplicate.** A query with no measures and at least one dimension or time-dimension auto-emits `GROUP BY <dim/td aliases>` and returns the distinct combinations. The `GROUP BY` is applied before `LIMIT`, so a row cap can't silently drop unique tuples. To opt out, set `"distinct_dimension_values": false` on the query — emits raw rows (no top-level `GROUP BY`), with WHERE / ORDER BY / LIMIT applied as usual. Any measure reference in `measures` / `filters` / `order` raises `DistinctDimensionValuesError` in this mode.
 
 ## Measures — colon aggregation
 
@@ -40,11 +42,15 @@ Each entry in `measures` is either a bare formula string or a `{"formula": ...,
   "last(revenue:sum)",
   "time_shift(revenue:sum, -1, 'year')",
   "lag(revenue:sum, 1)",
-  "rank(revenue:sum)"
+  "rank(revenue:sum)",
+  "round(revenue:sum, 2)",
+  "abs(revenue:sum - cost:sum)"
 ]
 ```
 
-Built-in aggregations: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `first`, `last`, `weighted_avg`, `median`, `percentile`, `stddev_samp`, `stddev_pop`, `var_samp`, `var_pop`, `corr`, `covar_samp`, `covar_pop`. Two-column `corr`/`covar_samp`/`covar_pop` take the second column as a named param: `price:corr(other=quantity)`. `sum` and `avg` accept an optional trailing-window: `revenue:sum(window='30d')`.
+Built-in aggregations: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `count_distinct_approx`, `first`, `last`, `weighted_avg`, `median`, `percentile`, `stddev_samp`, `stddev_pop`, `var_samp`, `var_pop`, `corr`, `covar_samp`, `covar_pop`. `count_distinct_approx` is dialect-aware (native approximate-distinct where available, exact `COUNT(DISTINCT)` fallback otherwise). Two-column `corr`/`covar_samp`/`covar_pop` take the second column as a named param: `price:corr(other=quantity)`. `sum` and `avg` accept an optional trailing-window: `revenue:sum(window='30d')`. A time bound narrows which buckets come back, not which rows the window may reach — so `date_range` and an equivalent explicit filter (`created_at >= '2025-01-01'`) give identical windowed numbers. Only `<`/`<=`/`>`/`>=` against a time dimension's own column and a literal counts; other operators, non-time-dimension columns, bounds under `or`/`not`, and model-level `filters` all restrict the window's input as usual. Same rule for `time_shift`.
+
+For month-over-month / period-over-period growth use `change_pct(x)` (absolute delta: `change(x)`) — both are calendar-aware and partition-safe (the underlying self-join matches on all non-time dimensions, so per-group series reset cleanly). Reach for `time_shift` only when you need the shifted value itself as a term in custom arithmetic or at a different grain (`time_shift(revenue:sum, -1, 'year')` for year-over-year).
 
 `*:count` is always available — no column definition needed. `col:count` counts non-nulls.
 
@@ -116,6 +122,20 @@ Reference measures from joined models with dotted syntax + colon aggregation:
 
 A dotted reference may target a *derived* column on the joined model (a column whose own `sql` is itself an expression). The engine recursively inlines the chain at query time — `"B.foo_normalized:sum"` where `B.foo_normalized.sql = "foo_raw / 100.0"` emits `SUM(B.foo_raw / 100.0)`. The same chaining works inside `Column.sql`, `filters`, and `dimensions`. When a filter names a *bare* local derived column whose SQL crosses a join (e.g. `Column(name="is_eu", sql="CASE WHEN customers.region = 'EU' THEN 1 ELSE 0 END")` referenced as `"filters": ["is_eu = 1"]`), the planner walks the column's chain and adds the joins the chain implies — no need to also list the column in `dimensions`.
 
+## Picking the root model
+
+Not sure which model to use as `source_model` for a set of columns/metrics? Call `recommend_root_model` with the `model.column` / `model.metric` items you want; it introspects the join graph and returns the recommended root plus each item's join-qualified path from it (aggregation suffixes preserved), ready to drop into a query.
+
+```python
+rec = client.recommend_root_model_sync(["customers.name", "products.category"])
+rec.root_model  # "orders"
+[ip.path for ip in rec.item_paths]  # ["customers.name", "products.category"]
+```
+
+Pass `root_hint` (a bare model name or `<data_source>.<model>`) to force an intended root — useful when the host is a bridge model that owns none of the items but matches your grain. It's honored when it reaches every item; otherwise the auto-pick is used and `warnings` says why.
+
+MCP: `recommend_root_model(items, data_source=None, root_hint=None, format="markdown")`. If no single model reaches every item, `root_model` is `None` and `coverage` lists the best partial roots — a hint to split into a multi-stage `source_queries` query.
+
 ## ModelExtension
 
 Extend a model inline with extra columns, named-formula measures, joins, or filters. The stored model is not modified:

.dockerignore

@@ -17,7 +17,6 @@ examples
 *.md
 !README.md
 !LICENSE
-mkdocs.yml
-.readthedocs.yaml
+zensical.toml
 .dockerignore
 .gitignore