Initial commit: AS4/411 directory and discovery service for Sankofa Marketplace

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/architecture/route-directive.md

@@ -0,0 +1,34 @@
+# 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.