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

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

docs/adr/001-adapter-interface-and-versioning.md

@@ -0,0 +1,44 @@
+# ADR-001: Adapter Interface and Semantic Versioning
+
+## Status
+
+Accepted.
+
+## Context
+
+Multi-rail support requires a strict plugin boundary so that each rail has a single adapter, version negotiation is clear, and compatibility is guaranteed. The protocol registry must define the minimum interface surface and versioning rules.
+
+## Decision
+
+### ProtocolAdapter Interface
+
+Every rail adapter implements the following (see `packages/core` adapter-interface.ts):
+
+- **validateIdentifier(type, value): boolean** — Validate format for the rail.
+- **normalizeIdentifier(type, value): string | null** — Return normalized value for lookup/storage, or null if invalid.
+- **resolveCandidates(ctx, request, options): Promise<AdapterCandidate[]]** — Use the supplied context (directory view) to return candidate participant+endpoint pairs.
+- **evaluateCapabilities(candidate, serviceContext): boolean** — Whether the candidate matches the requested service/action/process.
+- **renderRouteDirective(candidate, options): RouteDirective** — Build the canonical directive from a candidate.
+- **ingestSource?(config): Promise<IngestResult>** — Optional; for connectors that pull from external directories (SMP, file, etc.).
+
+The resolver (or a registry) supplies an **AdapterContext** to adapters; the context exposes findParticipantsByIdentifiers, getEndpointsByParticipantId, getCapabilitiesByParticipantId. The storage layer implements this context.
+
+### Plugin Boundaries
+
+- One adapter per rail (or per protocol family). Adapters are discovered by config or package layout (e.g. registered by protocol name or identifier type prefix).
+- No adapter depends on another adapter; shared logic lives in core or a shared utility package.
+
+### Semantic Versioning
+
+- The **adapter interface** (ProtocolAdapter) follows semantic versioning. Backward-compatible changes only: new optional methods, new optional fields on types. Breaking changes require a new major version of the interface.
+- Each **adapter implementation** has its own version (e.g. `version: "1.0.0"`). Registry can enforce minimum interface version when loading adapters.
+
+### Compatibility Guarantees
+
+- New optional methods or optional parameters do not break existing adapters.
+- New required methods or required fields are breaking; they belong to a new major version of the interface contract.
+
+## Consequences
+
+- Rails can be added by implementing ProtocolAdapter and registering; the resolver delegates to the appropriate adapter by identifier type or protocol.
+- Version mismatches can be detected at load time; operators can pin adapter or interface versions.