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