35 lines
1.7 KiB
Markdown
35 lines
1.7 KiB
Markdown
# 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.
|