Routing contract (canonical)

This page mirrors the repository source of truth docs/keys-routing-contract.md. It describes how Restormel Keys exposes multi-step routes, resolve, and simulate for complex hosts (for example SOPHIA ingestion), without executing LLM calls in Keys.

Agents: use MCP docs.canonical_resolve with topic keys_routing_contract, or suite tool routing.capabilities, for paths and tool names.

Contract version

Successful resolve and simulate responses include contractVersion (currently 2026-04-14). Additive features (2026-04-15): GET …/routes/{routeId}/export bundle, simulate routingAttempts, and stepChain advanceOn / retryOn hints — see repo canonical doc for detail.

Resolve highlights

Discovery: optional workload + stage pick a dedicated ingestion route, then a shared route with the same workload and null stage.
Explicit route: pass routeId (UUID or name) to skip discovery for other routes.
Chains: stepChain lists every enabled step in order with per-step metadata (timeout, policies, fallback hint, optional advanceOn/retryOn when set in JSON). Exactly one row has selected: true on success.
Server-advanced fallback: attemptNumber + previousFailure skip exhausted tiers.

Ingestion stages

stage	Note
`ingestion_extraction`	Extract
`ingestion_relations`	Relate
`ingestion_grouping`	Group
`ingestion_validation`	Validate
`ingestion_remediation`	Remediate
`ingestion_embedding`	Embed
`ingestion_json_repair`	JSON repair

Simulate

POST …/routes/{routeId}/simulate dry-runs selection for one route. Set includeStepDiagnostics: false to skip per-step policy evaluation when you only need cost hints. Set includeRoutingAttempts: true for hypothetical tier outcomes (routingAttempts).

Export (GitOps)

GET …/routes/{routeId}/export returns a versioned JSON bundle of the route and ordered steps (no secrets). MCP: routing.export.

Import (GitOps)

POST …/routes/import applies the same bundle shape: creates a route, or pass replaceRouteId in the JSON body to overwrite an existing route’s fields and ordered steps. MCP: routing.import.

Explain chain (agents)

GET …/routes/{routeId}/explain-chain returns a compact summary: route metadata, ordered steps (including advanceOn / retryOn hints when present), and policies bound at workspace, project, environment, and route scope (read-only). Optional query includePolicyRuleJson=true. MCP: routing.explain_chain.

AAIF

@restormel/aaif adds optional routingContext on requests (mirrors resolve hints). The AAIF helper does not call HTTP resolve; use @restormel/keys dashboard client resolve() when you need a full stepChain.

Full detail, capability matrix, and security notes: see the markdown file linked above or the public GitHub copy in the restormel-keys repo.