Skip to content
Almathal Handbook

ADR-0008: Adapter Slots with Capability Contracts

Accepted

Date: 2026-06-10

Context

Archetype Slots can match Adapters in two ways:

  • Category only: “I need an auth adapter.” Simple but weak — doesn’t distinguish between auth adapters with different capabilities (SSO, MFA, audit logging).
  • Capability and Contract: “I need an auth adapter that supports SSO, MFA, audit logging, and implements contract:auth/identity-provider/v1.” Richer matching, enables true substitutability.

For MVP, a simple category match plus a hardcoded default suffices since each category has only one or two Adapters. Long-term, capability matching is required.

Decision

Slots declare:

  • Category (required, broad matching)
  • Required Contract (the interface that must be implemented)
  • Required Capabilities (specific features the Adapter must provide, optional)

The schema includes all fields from day one. The Composer’s resolver initially uses category-and-default matching; capability-and-contract matching is enabled as Adapter Manifests start declaring richer Capability fields.

This is a phased rollout: schema supports it from v1; resolver behavior expands over time as data fills in.

Rationale

  • Avoids a schema-breaking change later when capability matching becomes essential.
  • Allows MVP velocity without locking in weak matching forever.
  • Adapter authors can incrementally adopt richer Capability declarations.
  • Capability and Contract concepts are clearly distinguished from day one in the schema.

Consequences

  • Manifest schema’s capability and contract fields are designed before the resolver fully uses them.
  • The Capability namespace (ADR-0019) must be established before Adapters can declare richer capabilities.
  • Tooling and documentation must clarify which matching mode is active per platform version.

References