# Accounts, Models and Providers Domain

**Status:** Approved target-state baseline — amended by pre-run reuse/VISION audit  
**First realization:** I0 seam / I1 live selection.

## Target State

AWP treats Provider, Account, Model and selection policy as independent primitives so multiple accounts/models/providers can be configured without embedding vendor rules into Factory/Agent domains.

```text
Provider
  ├─ Account* -> Connection/CredentialReference
  └─ Model*

AccountSelectionPolicy
  + Project/Plan/Task/Run overrides
  + provider/model capability/health/cost/rate state
  -> resolved Attempt inputs
```

## Provider

Describes an external execution/model/service provider and its adapter/capabilities. Provider identity is AWP-owned; vendor model/account IDs are mappings.

## Account

Represents one selectable account/subscription/tenant identity for a Provider. Credential material lives through Connection/CredentialReference. Account has status/capabilities/quota observations and allowed project bindings.

## Single Token / Credential Authority

The owner requirement for **one token owner** is binding.

For any one logical provider Account credential/session, exactly one configured credential authority owns mutable token/session state such as refresh, rotation and revocation reconciliation.

Conceptually:

```text
Account
  -> Connection
      -> CredentialReference
          -> one configured credential authority / SecretStore-provider path
              -> token refresh / rotation / revocation state

AgentRun / CI / Deployment workload
  -> receives narrow short-lived projection/reference as needed
  -> never becomes a competing refresh-token owner
```

The authority may be an accepted Platform/Subrouter/provider implementation behind the seam; the domain does not require AWP to custom-build token management.

Forbidden failure mode:

```text
control plane refresh loop
+ agent/workstation refresh loop
+ provider helper refresh loop
= duplicate token owners / races / drift
```

AWP must be able to explain which component currently owns refresh/session authority for an Account/Connection. Switching authorities is an explicit configuration/migration operation with old owner deactivated/reconciled before the new owner becomes authoritative.

## Model

Provider-scoped model/catalog identity with capability metadata (coding/tool use/context/effort modes/etc.) and availability observations. Model labels can change without changing historical Attempt records.

## AccountSelectionPolicy

Resolves eligible Provider/Account/Model based on configured order, capability, project binding, current availability/rate/cost rules and test-purpose aliases. It produces an explainable selection result.

## Platform / Subrouter Reuse Gate

Before AWP implements custom mechanics for any of the following, the consuming increment must verify the **current** `platform-modules/mod` and Subrouter capability rather than relying on historical planning notes:

```text
token ownership / refresh
provider account discovery
account health / quota / rate observations
routing / selection
sticky assignment
fallback / rotation
shared-account concurrency
usage accounting helpers
```

Decision rule:

```text
current Platform/Subrouter capability satisfies AWP contract
  -> wrap/adapt it behind AccountProvider / selection seam

partially satisfies
  -> reuse the fitting mechanics; build only the missing AWP-specific layer

does not satisfy
  -> record exact tested gap before custom generic routing/token machinery is authorized
```

`Subrouter` is therefore a strong reuse candidate/direction, **not** an unconditional target-domain dependency. Its provider-native IDs/configuration never become canonical `Account`, `Model`, `Provider` or `Attempt` identity.

The result of this check is recorded in the Overdeck/Platform/FOSS reuse inventory with exact package/revision/capability and integration evidence.

## Invariants From Day 1

- no assumption of one account per provider;
- exactly one mutable token/session authority exists per logical Account credential at a time;
- AgentRuns/CI/Deployment workloads do not independently refresh reusable provider credentials;
- credential-authority migration is explicit and observable rather than duplicate-running;
- account credential is not stored on Account domain record;
- selection is explicit/recorded, not hidden adapter behavior;
- selected Provider/Account/Model immutable per Attempt;
- exhaustion/fallback creates new Attempt;
- lower scopes can choose among allowed accounts/models but cannot broaden project/security eligibility;
- historical Attempt retains exact resolved provider/account/model even if catalog changes;
- free/volatile model aliases are runtime-resolved rather than permanent architecture;
- AWP does not rebuild token/routing mechanics before the Platform/Subrouter reuse gate is completed.

## Health / Capacity

Distinguish:

```text
auth invalid
permission/subscription missing
rate limited
quota exhausted
temporary provider outage
model unavailable
credential authority degraded/conflicted
healthy/available
unknown/stale observation
```

Availability observation can influence routing but cannot retroactively mutate an active Attempt. A duplicate/ambiguous credential-authority condition is an actionable configuration/Incident state, never something AWP tries to “heal” by letting both owners refresh.

## Dogfood Aliases

`factory-throwaway`, `factory-free-useful`, `factory-free-fallback` are stable test-purpose aliases with current mappings defined by dogfood testing policy. The alias is policy/configuration; the resolved provider/account/model is persisted.

The live dogfood policy currently resolves these toward Spark low-effort first, then free OpenCode/provider fallbacks. Model availability is volatile; the architecture relies on aliases/capabilities and immutable Attempt provenance rather than permanent model-name assumptions.

## Increment Realization

| Increment | Account/model realization |
|---|---|
| I0 | verify Platform/Subrouter current fit; provider/account/model catalogs, Connection seam, single token-authority contract, selection interfaces. |
| I1 | live Attempt selection, Spark rotation and free fallback. |
| I2 | project/plan defaults and Planning recommendations. |
| I4 | token/cost/provider observability. |
| I9 | customer catalogs, quotas/billing/enterprise governance if productized. |

## Current Implementation State

Target spec; current test model IDs are volatile policy, not architectural guarantees. Platform/Subrouter exact exports/revisions must be verified before I0 account-routing/token-authority implementation.

## Deferred Realization

Sophisticated cost optimizer and cross-provider quality scoring are not required for initial dogfood.

## Temporary Dogfood Behavior

Owner-controlled accounts may be configured manually before rich Settings UI, but all runs still use Account/Connection/Attempt provenance rather than direct environment-only hidden selection.

A temporary direct provider adapter is acceptable only if it obeys the canonical seam and does not become a duplicate token authority beside an accepted Platform/Subrouter/provider credential authority.

## Failure / Recovery

Selection failure returns no eligible account/model and structured reasons. It never loops indefinitely through unavailable models without exposing state. Credential refresh/revocation failures remain provider/connection state and do not silently mutate account identity. Credential-authority failover must fence the old owner before a new owner assumes mutable refresh authority.

## UI Implications

Settings shows provider/accounts/models/health/capabilities and the current credential/token authority without exposing secret material. Project/Plan/Task shows permitted/default selections; AgentRun shows exact resolved account/model without exposing secret token.

## FOSS / Harvest Links

See:

- `../architecture/platform-reuse.md` for the no-rebuild gate;
- `../../plans/AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md` for existing account/model helper disposition;
- `../../plans/AWP-DOGFOOD-LIVE-FACTORY-TESTING-POLICY.md` for volatile live-test aliases.

## Decisions / ADRs

Selection defaults are configurable policy. Adding/replacing a provider or credential authority is normally adapter/catalog/configuration work, not domain redesign. Selecting Subrouter or any alternate routing/token implementation as a concrete default requires current capability evidence, not inheritance from historical Overdeck design.