# Providers and adapters Providers turn contracts into physical behavior. Adapters connect an owned contract to an external system. Both remain replaceable because neither owns the application meaning it realizes. ## Selection is evidence-based A provider package declares exact capability profiles, configuration schemas, targets, topology, limits, effects, authority, cost, lifecycle, observation, recovery, and conformance evidence. Admission evaluates each exact claim under the root's selected assurance policy. An `Accountable` release retains an exact, attributable root-owner acceptance; it does not claim independent verification. A policy requiring governed assurance admits only the matching independent evidence. `UnverifiedDevelopment` is command-scoped and cannot support a durable release. Planning considers only profiles reachable from one root and selects the canonical valid plan. Package installation creates no semantic activation, artifact, instance, grant, or runtime binding. A selected profile is not yet a realized provider. Build retains a complete realization receipt tying the exact profile to its implementation, configuration contract, provenance, and conformance evidence. Deployment validates that receipt separately from the grants and binding required to dispatch an effect. ## Review and change provider choice The ordinary state is automatic: no authored override. Planning still records one exact immutable selection and explains why it won. The command examples below illustrate the end-product interface for source-based provider choice. Review one demand with: ```console one select provider --root OrdersApi --for one.data#Transactional@1 ``` Commit an exact choice, ordered preference, allow set, or exclusion through the same command contract: ```console one select provider --root OrdersApi --for one.data#Transactional@1 --use one select provider --root OrdersApi --for one.data#Transactional@1 --prefer ... one select provider --root OrdersApi --for one.data#Transactional@1 --allow ... one select provider --root OrdersApi --for one.data#Transactional@1 --exclude ... one select provider --root OrdersApi --for one.data#Transactional@1 --automatic ``` The command first prints the consequence and source patch. In an interactive session it commits only after review; automation supplies an explicit accepted transaction rather than inheriting an interactive default. The review output supplies stable owner-qualified selectors. Exact descriptor, claim, or configuration revisions are expert pins and are not required for an ordinary choice. A choice is scoped to one root and one provider-neutral contract, exact requirement edge, or deployment unit. Repeated demands require exact narrowing; One never guesses from source order. The intended choice semantics are: | Intent | Planning behavior | | --- | --- | | Use | Require one unambiguous eligible provider or fail `Unsatisfied` | | Prefer | Rank named tiers first, then other eligible providers | | Only | Limit eligibility to a nonempty allow set | | Never | Exclude named providers and fail if none remain | | Automatic | Remove the override and use deterministic objectives | Before committing a change, One shows the provider/profile difference, compatibility and accepted losses, topology, trust crossings, artifacts, services, secrets, authority, resources, comparable costs and evidence scope, rollout consequences, and exact source patch. Missing evidence remains unavailable; it never becomes a made-up score or recommendation. Selection edits one Planning-owned declaration in an explicitly selected `.one` source through an exact source transaction. Direct source editing, CLI, TUI, editor, Agent, and MCP all use that same declaration and transaction. Provider configuration remains provider-owned, and local paths, processes, credentials, and bindings stay in `.one/execution.toml`. Preference cannot override eligibility. There is no force switch for missing compatibility, policy, qualification, or admission evidence. Returning to automatic removes the override; it does not write a redundant automatic rule. ## Four binding modes | Mode | What the plan fixes | What runtime may choose | | --- | --- | --- | | Fixed provider | One exact profile and support closure | Lazy activation of that profile | | Instance binding | One profile plus a bounded resolver and binding policy | An exact compatible endpoint or resource instance | | Bounded provider binding | A binder and signed slot envelope | An admitted profile that needs no undeclared code, authority, resource, or cost | | Adaptive composite | A provider graph, roles, routing policy, and maximum closure | Safe routing among eligible members at declared boundaries | Changing to a profile outside the envelope requires a new plan. Health is evidence, not authority. Switching providers is separate from retrying an operation, and stateful failover requires explicit continuity, fencing, replication, compatibility, RPO, RTO, and repair proof. ## Thin adapters preserve ownership An adapter contains only the irreducible mapping, protocol behavior, and evidence needed to realize its contract. It does not copy an external platform, rename every API, or move domain meaning into a generic host. For example, a PostgreSQL adapter maps One's selected storage and transaction contract to PostgreSQL behavior. PostgreSQL continues to own its engine and protocol; Data continues to own the semantic requirement. The application depends on the smallest public Data contract, not the adapter's internals. ## Use established systems and native realizations together One can plan across databases, queues, object stores, identity providers, cloud APIs, containers, Kubernetes, GitOps, observability backends, Wasm hosts, and ordinary processes. A native provider is worthwhile when it creates a demonstrated usability, correctness, performance, portability, or operational advantage behind the same public contract. Native and external providers pass the same admission gate. A provider can be the curated default because its evidence and ordinary-use fit are stronger, never because it bypasses governance. ## Authors build a reusable integration once Provider and adapter authors define the boundary contract, implement the mapping, run owner conformance and negative suites, package exact evidence, and publish through governed admission. Scaffolding and generated wiring remove mechanical work while leaving protocol, security, state, lifecycle, and recovery behavior in ordinary owned code. One admitted profile can then serve every compatible root. Evidence is qualified by exact version, configuration, target, environment, security, and freshness rather than copied into each application. Follow [Build a provider adapter](/one/examples/provider-adapter) for a complete external-carrier example. Illustrative planning output keeps selection explicit: ```text accepted acme_carrier.provider#AcmeShipmentCreate@1 evidence conformance:sha256:… rejected other.provider#Create@1: outcome lookup unsatisfied ``` Canonical owner: [Provider Ecosystem](https://github.com/muijf/one/blob/main/systems/providers/AGENTS.md).