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

[OmerBaddour]

Routing moves out of ~/.clair/environments.yml and into a project __routing__.py. Credentials stay global and inert. Routing becomes Python, and the team commits it.

Supersedes #4.

The split

File	Holds	Commit it?
~/.clair/environments.yml	Connection settings and credentials	No
<project>/__routing__.py	The routing rules	Yes

Credentials and routing want opposite things. Credentials want to sit outside the repo and stay boring: no imports, no logic, no coupling to the clair version that a project pins. Routing wants to be expressive, reviewable, and version-matched to the project. The environment name joins the two files.

The three types

from clair import RoutingEntry, RoutingTable, TrouveAddress


class DeveloperRouting(RoutingEntry):
    environment_name: str = "dev"
    user_variable: str = "CLAIR_USER"

    def route(self, trouve_address: TrouveAddress) -> TrouveAddress:
        user_name = os.environ[self.user_variable].upper()
        return trouve_address.model_copy(
            update={"database_name": f"{trouve_address.database_name}_{user_name}"}
        )


routing = RoutingTable(entries=[DeveloperRouting()])

• TrouveAddress holds a database_name, a schema_name, and a table_name, and validates each one on construction. An address that exists is a valid Snowflake identifier. It is frozen and hashable.
• RoutingEntry is the abstract base class for one environment's rule. A subclass adds a field for each value that the rule needs, and Pydantic validates the fields.
• RoutingTable holds the entries and rejects two entries for one environment name, because only one can win.

That CLAIR_USER field is the argument for the whole design: one committed rule that resolves to a different target for each person. No per-developer config, nothing gitignored. YAML could not express it.

clair ships no concrete entry. The clair init template writes two, and the guide explains how to write one.

Validation moved to construction

An earlier draft of this work made a rule a plain callable, which removed the static validation that Pydantic gave the typed configs. The replacement was to inspect the output after each rule ran.

Putting the validation in TrouveAddress.__init__ is better. A rule that gives an address gives a correct address, or it raises. The check happens once, in one place, for every rule kind and for the logical names that the file system gives.

This also closes a pre-existing gap: the identifier and 255-character checks used to live only inside SchemaIsolationRouting.apply, so DatabaseOverrideRouting validated nothing.

clair validate

A credential-free command, for CI. compile and run stop at the first bad address, because they must not write to a wrong target. validate instead reports every problem at once, then the collisions, and exits 1 on any problem.

  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.

Two guards against silent production writes

The join-key design has one scary failure mode: a rule that does not apply means the writes land on the logical, that is production, names. Two guards:

1. An unknown key in an environments.yml block is an error, through extra="forbid". A leftover routing: block therefore stops the run. Pydantic would otherwise drop the key without a word.
2. A __routing__.py that does not name the active environment warns. An entry for that environment stays quiet, because an explicit passthrough is a decision, not a typo.

Behaviour changes

The major version is 0, so this PR keeps no backwards compatibility and adds no migration path.

• A callable or a dict in __routing__.py is an error. The file must give the name routing a RoutingTable.
• An unknown key in an environments.yml block is an error.
• A directory name or a file name that Snowflake cannot use as an identifier stops discovery. Before, clair found the fault at run time, in Snowflake.

Why a class beats a callable

The class name and the field values replace inspect.getsource() in the CLI messages. That deletes the source-text mangling that the callable design needed, and a rule keeps a stable description even when no source file is available.

Also

• Every environment variable that clair reads takes the CLAIR_ prefix.
• CLAUDE.md records the v0 no-backwards-compatibility stance.

Verification

• 579 tests pass, up from 513 on main.
• ruff check src/ tests/ clean.
• End-to-end CLI run on a scaffolded project: validate passes with CLAIR_USER set and exits 1 without it, compile writes to analytics_OBADDOUR/finance/revenue.sql, --env prod stays quiet, --env typo warns, a my-db directory fails, and a stale routing: block fails with the migration message.

Docs

Rewrote guides/routing.md, added cli/validate.md, and corrected every page that named a routing policy.

🤖 Generated with Claude Code

[OmerBaddour]

I don't think we should have this. I think instead we should look to site_docs as the source of truth, and make sure after each PR that it is completely consistent with the code changes made.

[OmerBaddour]

this feels like a mistake.. remove