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

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