# RouteDirective Contract

Schema: [../api/route-directive.schema.json](../api/route-directive.schema.json). OpenAPI: [../api/openapi.yaml](../api/openapi.yaml).

## Response Shape

- **primary:** One directive (best match). **alternates:** ordered fallback list with optional **reason** per entry.
- **directives:** Backward compat: `[primary, ...alternates]`.
- **failure_policy:** Optional retry, backoff, circuitBreak.
- **evidence[]:** source, freshness, confidence, optional signature (array for multiple sources).
- **negative_cache_ttl:** TTL for negative (no-match) cache.
- **resolution_trace:** Which source(s) contributed (tenant override, internal directory, SMP cache, etc.).
- **Idempotency:** Same request + same store ⇒ same ordering. Optional correlationId.

## Multi-Hop

Multi-hop (intermediary) routing is out of scope for MVP.

## Failover

Gateway uses primary first; on failure may try alternates in order. failure_policy is advisory.

## Optional extensions (settlement)

For CBDC/tokenized settlement overlays, a directive may include optional metadata for a settlement adapter (see [cbdc-settlement-adapter.md](cbdc-settlement-adapter.md)):

- **settlement_rail:** One of `RTGS` | `CBDC` | `tokenized_deposit` (when stored per participant/endpoint).
- **wallet_endpoint** (or **settlement_endpoint**): Optional URL or reference for wallet/DLT when settlement_rail is CBDC or tokenized. Not required for MVP; schema and OpenAPI may be extended when in scope.

## Invariants

1. Match: at least one of primary or directives present. No match: empty and negative_cache_ttl set.
2. When primary present, directives[0] equals primary.
3. evidence and resolution_trace must not contain sensitive data.