[Router] Interfaces + fixtures stub (foundation)

[ramkrishna2910]

Closes #2407.

Foundation for the Lemonade Router milestone (#2389): the shared C++ contract surface, the policy/decision JSON schemas, the back-compat guardrails, and the per-tier example policies that every downstream engine/wiring issue codes against. Interfaces only — no engine behavior (route() is declared, not implemented; that's #2382).

Draft: gated on schema sign-off (#2375 / #2376). If a schema is revised, churn stays in the schema files + fixtures; the C++ surface barely moves.

Contract header — src/cpp/include/lemon/routing_policy.h

Std library + nlohmann/json only — no Router/backend include, per the engine invariant.

• Data: RouteContext, Score (label→score), OnError, Rule, MatchExpr AST, TraceEntry, Decision, RoutePolicy.
• Injection seam: ClassifierServices (embed / run_classifier / chat — chat powers the L0a llm router), ClassifierContext, Classifier.
• Evaluation seam: Condition, EvalContext (per-request state: classifier memo + trace), LeafFactory — the shared contract that lets the evaluator ([Router] Core types + match-expression evaluator (M6/M7) #2378) and registry ([Router] Classifier + Condition registry (M3) #2379) be built in parallel without colliding at the leaf boundary.
• Engine: RoutingPolicyEngine ctor signature; route() declared, intentionally undefined.

Schemas — src/cpp/resources/schemas/

• route_policy.schema.json ([Schema][Router] route_policy — routing block in collection.router JSON #2375), request.schema.json (request-side metadata + route_trace, [Schema][Router] Decision + trace object (pure selection) #2376), decision.schema.json ([Schema][Router] Decision + trace object (pure selection) #2376), README.md.
• The policy + decision schemas carry a required root version ("1"); the request schema rides on the stock OpenAI body so it has no version.
• Engine-owned v1 semantics are frozen in the field descriptions so a future change can't silently re-route an old policy: keywords = case-insensitive substring, regex = ECMAScript, score bands inclusive within [0,1] (default min_score: 0.5), min/max_chars = UTF-8 bytes, metadata match = case-sensitive comma-split token set, on_error default match_false, routing.router desugaring behavior-equivalent.
• Classifier declarations enforce type-specific required fields (semantic_similarity → reference_phrases, llm → prompt, …) via if/then.

Back-compat guardrails

The README documents the contract — never redefine a shipped field; never delete a major's schema; migrate-on-load — enforced mechanically, not by convention:

• schema-lock.json + test/test_schema_lock.py — canonical-hash snapshot guard (buf breaking-lite). A released major is immutable (any change fails CI → ship a new major); an unreleased major may change only with a refreshed lock in the same diff, so every schema edit is a visible, reviewed change. (v1 is released: false until sign-off.)
• test/test_routing_fixtures.py — schemas are self-valid and every fixture conforms.

(Behavioral back-compat — golden policy → Decision — is the conformance corpus #2425, non-gating, tracked separately.)

Fixtures — test/cpp/fixtures/routing/

Lean local-form examples, verbatim from the locked level issues:

Fixture	Level	Source
l0a_llm_router.json	L0(a) llm-as-router	#2405
l1_keywords.json	L1 deterministic (keywords / regex / chars)	#2380
l1_metadata.json	L1 deterministic (metadata match — equals/any/exists)	#2380
l2_semantic.json	L2 semantic_similarity	#2381
l3_classifier.json	L3 model-backed classifier	#2379
decision_example.json	Decision + trace	#2376

The metadata leaf condition (lets rules branch on caller-supplied OpenAI metadata like task_class / consent) was contributed by @SlawomirNowaczyk.

Tests

• test/cpp/test_routing_policy_contract.cpp → CTest RoutingPolicyContractTest: header compiles standalone, every type constructs, the Condition/EvalContext/LeafFactory seam is exercised, the fake ClassifierServices is callable, the engine is constructible, and fixtures satisfy the locked cross-field invariants (default_model ∈ candidates; every route_to ∈ candidates; classifier refs resolve).
• test/cpp/fake_classifier_services.h: configurable fixed embeddings / scores / replies.
• test/test_routing_fixtures.py: fixtures validate against the JSON Schemas + cross-field invariants (jsonschema, added to test/requirements.txt).
• test/test_schema_lock.py: the frozen-major snapshot guard.

Acceptance (#2407) — all met

• Headers compile standalone (no backend/Router include)
• Fixtures validate against the [Schema][Router] route_policy — routing block in collection.router JSON #2375/[Schema][Router] Decision + trace object (pure selection) #2376 JSON Schemas
• The fake ClassifierServices builds and is usable from a trivial test

Verification

• C++: compiles clean at /W4 (MSVC, VS2026); builds in-tree via CMake; ctest -R RoutingPolicyContract passes.
• Python: test_routing_fixtures.py and test_schema_lock.py pass; Black-clean.
• CI: these now run on every PR — RoutingPolicyContractTest is built + run in the C++ unit-test steps, and a fast server-less Routing Schema Tests lane runs the two Python guards (so the schema lock + fixture validation are enforced, not decorative).

🤖 Generated with Claude Code

[eddierichter-amd]

Just some small nits. Otherwise looks good.

[ramkrishna2910]

Thanks @eddierichter-amd — all three addressed in the latest commit:

1. Request-extension schema — added request.schema.json + a request_example.json fixture covering the request side of [Schema][Router] Decision + trace object (pure selection) #2376: metadata (object, string values only — list values are comma-encoded) and the optional route_trace (bool). It validates only the extension fields and leaves the rest of the OpenAI body alone (additionalProperties: true), and intentionally has no version since it rides on the stock request rather than being a versioned document. Added a test that a non-string metadata value is rejected.
2. [0,1] bounds — min_score/max_score now carry minimum: 0, maximum: 1 (the Score contract range).
3. Type-specific required fields — classifier declarations now enforce, via if/then: semantic_similarity → model + reference_phrases, classifier → model, llm → model + prompt. Type-specific validation now lives in the schema rather than deferring to the parser. (Reserved post-v1 preset types stay unconstrained for now.)

Lock refreshed, README + both test harnesses updated. Good catches — the request schema in particular was a real gap against #2376's deliverable.

[eddierichter-amd]

@ramkrishna2910 one more question now that I am scoping out #2379. Should the classifier contract expose declared labels and default_label?

The registry/leaf factory needs this to:

• reject condition label refs that are not in the classifier's declared labels
• apply default_label when a classifier condition omits label

Something like:

const std::vectorstd::string& labels() const;
const std::optionalstd::string& default_label() const;

and corresponding protected constructor fields would make #2379 implementable without keeping a sidecar metadata table outside the Classifier.