feat: move routing into a project __routing__.py with a RoutingTable

CLAUDE.md

@@ -69,6 +69,18 @@ The worktree shares git history with the main repo but has its own `.venv/`. Alw
 - Use `database_name` instead of `database`, `schema_name` instead of `schema`, `table_name` instead of `table`
 - Address git merge conflicts by pulling main, resolving conflicts, and pushing. Favour simplicity over clean commit history — PRs are squash-merged anyway.
 
+## Backwards compatibility
+
+The major version is 0. While the major version stays 0, clair does not keep backwards
+compatibility. clair has no users at this time, so the best design wins against a stable
+interface.
+
+- Change a public name, a file format, or a function signature when the change makes the
+  system better.
+- Do not add a deprecation shim, an alias for an old name, or a migration path.
+- Delete the old code path. Do not keep it beside the new one.
+- Name each behaviour change in the pull request description.
+
 ## Keep site_docs/ up to date
 
 `site_docs/docs/` is the source of truth for behaviour. Before you complete a change, compare

README.md

@@ -138,7 +138,10 @@ uv add rivage-clair
 
 ### 1. Set up an environment
 
-Run `clair init` — it will prompt for your Snowflake connection details and write `~/.clair/environments.yml`.
+Run `clair init`. It asks for your Snowflake connection details and writes two files:
+
+- `~/.clair/environments.yml` — your connection settings. Do not commit this file.
+- `<project>/__routing__.py` — the [routing](https://clair.rivage.sh/guides/routing/) entry of each environment. Commit this file.
 
 ### 2. Create a project
 

site_docs/docs/cli/compile.md

@@ -50,7 +50,7 @@ _clairtifacts/
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--project` | `.` | Path to the clair project root |
-| `--env` | optional | Environment name. Necessary if clair must apply routing to the generated SQL. |
+| `--env` | optional | Environment name. It selects the entry in `__routing__.py` that clair applies to the generated SQL. |
 | `--select` | all | Glob pattern that filters the Trouves. Repeat the flag to add more patterns. |
 | `--run-mode` | `full_refresh` | `full_refresh` or `incremental`. Selects which SQL variant clair generates. |
 

site_docs/docs/cli/overview.md

@@ -3,7 +3,7 @@
 All commands share two common flags:
 
 - `--project` — path to the clair project root (default: `.`)
-- `--env` — environment name from `~/.clair/environments.yml` (default: `CLAIR_ENV` or `dev`)
+- `--env` — environment name. It names a key in `~/.clair/environments.yml` and an entry in `__routing__.py` (default: `CLAIR_ENV` or `dev`)
 
 ## Commands
 
@@ -13,6 +13,7 @@ All commands share two common flags:
 | [`clair compile`](compile.md) | Resolve DAG and write SQL to `_clairtifacts/` | Optional (for routing) |
 | [`clair run`](run.md) | Run Trouves against Snowflake in dependency order | **Yes** |
 | [`clair test`](test.md) | Run data quality tests against Snowflake | **Yes** |
+| [`clair validate`](validate.md) | Apply the routing entries to every Trouve | No |
 | [`clair dag`](dag.md) | Print the dependency graph as an indented tree | No |
 | [`clair docs`](docs.md) | Start a local web UI for the DAG and the documentation | No |
 | [`clair clean`](clean.md) | Remove compiled artifacts from `_clairtifacts/` | No |
@@ -22,6 +23,7 @@ All commands share two common flags:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CLAIR_ENV` | `dev` | Active environment name. This is the same as `--env` on every command. `--env` wins if you set both. |
+| `CLAIR_USER` | — | The `clair init` routing template reads this name. Give each variable that a routing entry reads the `CLAIR_` prefix. |
 | `CLAIR_LOG_FORMAT` | _(text)_ | Set to `json` to write structured JSON logs. Use this in CI/CD pipelines and in container environments that read JSON logs. |
 
 ## Help

site_docs/docs/cli/validate.md

@@ -0,0 +1,73 @@
+# `clair validate`
+
+Apply the routing entries in `__routing__.py` to every Trouve in the project, and report every problem at once.
+
+This command needs no Snowflake credentials, so CI runs it on every change.
+
+```bash
+clair validate
+clair validate --env prod
+clair validate --project path/to/project
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--project` | `.` | Path to the clair project root. |
+| `--env` | `CLAIR_ENV` or `dev` | The environment to route for. It matches an entry in `__routing__.py`. |
+
+## What it examines
+
+- The routing file runs, and it gives a `RoutingTable`.
+- The table has one entry for each environment name.
+- Every directory name and file name makes a valid address.
+- The entry for this environment runs on every TABLE and VIEW Trouve.
+- Every address that the entry gives is a valid Snowflake identifier.
+- No two Trouves go to one physical target.
+
+## Output
+
+A project with no problems:
+
+```
+  environment: dev
+  routing file: /home/alice/project/__routing__.py
+  entry: DeveloperRouting(environment_name='dev', user_variable='CLAIR_USER')
+  Trouves to route: 12
+
+  ✓ Every routed name is valid. No collisions.
+```
+
+A project with a problem gives exit code 1:
+
+```
+  environment: dev
+  routing file: /home/alice/project/__routing__.py
+  entry: DeveloperRouting(environment_name='dev', user_variable='CLAIR_USER')
+  Trouves to route: 12
+
+  ✗ analytics.finance.revenue
+    The routing entry `DeveloperRouting(environment_name='dev', user_variable='CLAIR_USER')` failed on 'analytics.finance.revenue': KeyError: 'CLAIR_USER'
+
+  1 problem found.
+```
+
+`clair compile` and `clair run` stop at the first routing problem, because they must not write to a wrong target. `clair validate` instead reports every problem, so that you correct them together.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Every routed name is valid, and no two Trouves collide. |
+| 1 | clair found one problem or more. |
+
+## In CI
+
+```yaml
+- name: Validate clair routing
+  run: |
+    uv run clair validate --env prod
+```
+
+See the [routing guide](../guides/routing.md) for the entry types and how to write a `route` method.

site_docs/docs/concepts/environments.md

@@ -78,7 +78,6 @@ prod:
 | `role` | — | Default role. If you omit it, Snowflake uses the default role of the user. |
 | `region` | — | AWS/Azure region. clair needs it for the query URLs in the logs. |
 | `account_locator` | — | Classic account locator. clair needs it for the query URLs. |
-| `routing` | — | Routing policy. See [Routing Policies](../guides/routing.md). |
 
 ## Select an environment
 
@@ -106,6 +105,8 @@ In CI, set `CLAIR_ENV` and use key-pair authentication. This method does not nee
   run: clair run --project .
 ```
 
-## Routing policies
+## Routing
 
-Each environment can include a routing policy. The policy remaps logical Snowflake names to physical targets. See [Routing Policies](../guides/routing.md).
+An environment holds connection settings only. The routing rules are in `__routing__.py`, at the root of your project. clair joins the two files by the environment name.
+
+An unknown key in an environment block is an error. A `routing:` block from an older version of clair therefore stops the run, and the message tells you to move the rule. See [Routing](../guides/routing.md).

site_docs/docs/concepts/index.md

@@ -5,4 +5,4 @@ Read these four concepts before you use clair.
 - **[Trouve](trouve.md)** — the basic unit. One Python file, one Snowflake object.
 - **[DAG](dag.md)** — the dependency graph. clair builds it from the Python imports.
 - **[Project Layout](project-layout.md)** — how the directory structure maps to Snowflake names.
-- **[Environments](environments.md)** — Snowflake connection profiles and routing policies.
+- **[Environments](environments.md)** — Snowflake connection profiles.

site_docs/docs/concepts/project-layout.md

@@ -19,6 +19,8 @@ A clair project in production usually has 3 or 4 layers:
 
 ```
 my_project/
+├── __routing__.py                   # The routing entry of each environment
+│
 ├── source/                          # Tables that already exist — TrouveType.SOURCE
 │   ├── orders/
 │   │   ├── raw.py                   # source.orders.raw
@@ -46,6 +48,7 @@ my_project/
 
 | File | Location | Purpose |
 |------|----------|---------|
+| `__routing__.py` | project root | The [routing](../guides/routing.md) entry of each environment |
 | `__database_config__.py` | database directory | Warehouse/role defaults for all Trouves in that database |
 | `__schema_config__.py` | schema directory | Warehouse/role defaults for all Trouves in that schema |
 
@@ -81,4 +84,4 @@ Python imports work in the usual way. A Trouve in `refined/` can import from `so
 from source.orders.raw import trouve as raw_orders
 ```
 
-clair resolves `source.orders.raw` to the Snowflake object at `source.orders.raw`. An active [routing policy](../guides/routing.md) can change this target.
+clair resolves `source.orders.raw` to the Snowflake object at `source.orders.raw`. An active [routing entry](../guides/routing.md) can change this target.

site_docs/docs/guides/index.md

@@ -6,5 +6,5 @@ These guides show you how to do the usual clair tasks.
 - **[Incrementality](incrementality.md)** — APPEND and UPSERT strategies for large tables
 - **[Data Quality Tests](data-quality-tests.md)** — attach tests to Trouves
 - **[Selectors](selectors.md)** — run only a subset of your project
-- **[Routing Policies](routing.md)** — remap Snowflake targets per environment
+- **[Routing](routing.md)** — remap the Snowflake target of each environment
 - **[Per-Database & Schema Config](per-database-schema-config.md)** — warehouse and role overrides per directory