45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# 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.
|