as4-411/docs/architecture/route-directive.md

RouteDirective Contract

Schema: ../api/route-directive.schema.json. OpenAPI: ../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):

• 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.