# Integrations and Connections Domain

**Status:** Approved target-state baseline  
**First realization:** I0 seam; I2 full UX.

## Target State

The domain exposes reusable external-service access without coupling Projects or Runs to raw secrets/provider account APIs.

```text
Connection
  ├─ provider/account identity
  ├─ CredentialReference -> SecretStore
  ├─ discovered resources/capabilities
  └─ health/status

ProjectConnectionBinding
  -> allowed subset of capabilities/resources

ConnectionRequirement
  -> missing/deferred capability/resource
  -> blocks only at declared gate
```

## Connection

Stable AWP identity for an authenticated relationship with a provider/account/tenant. Credential versions may change without changing Connection identity.

Required target fields include provider, account identity/labels, credential reference, authentication method, lifecycle status, discovered capabilities/resources, health observation, timestamps and provenance.

## ProjectConnectionBinding

A project-local permission grant over a reusable Connection. It records allowed resources/capabilities and optional constraints. A Project can bind multiple Connections for the same provider.

## ConnectionRequirement

A durable planning/execution requirement with:

```text
provider/capability/resource need
reason
status
requiredByGate
owner
defer reason / revisit trigger
consequence
return target/context
```

## Invariants From Day 1

- credentials are never copied into Project/Plan/Task/Run records;
- global Connection does not automatically grant all Projects access;
- lower scopes narrow and never broaden bindings;
- provider account identity and Project ownership remain separate;
- auth, permission, resource selection, reauth/revocation, outage and adapter error are distinct;
- redirect/auth flows restore the exact interrupted context;
- `Set up later` creates explicit deferral rather than losing the requirement;
- revocation blocks only operations requiring the affected capability and preserves unrelated project state.

## Lifecycle

```text
connecting
 -> needs-resource-selection
 -> connected
 -> needs-permission
 -> needs-reauth
 -> degraded/error
 -> revoked
```

A Connection can be healthy for one capability/resource and insufficient for another; requirement evaluation uses capability/resource checks, not a single green/red boolean.

## Commands

- StartConnection / CompleteAuthentication
- DiscoverResources / SelectResources
- VerifyConnection
- Reauthorize / Revoke
- BindConnectionToProject / UpdateBinding / Unbind
- Create/Defer/SatisfyConnectionRequirement

## Increment Realization

| Increment | Realization |
|---|---|
| I0 | primitive/secrets/provider seam, Git/model/K8s minimum. |
| I1 | Factory Git/model account use and attempt-scoped projections. |
| I2 | in-context onboarding/defer/return-to-Planning flow and Settings UX. |
| I5/I6 | CI/deployment provider resources and credentials. |
| I9 | enterprise provider/org integrations. |

## Current Implementation State

Target spec; current owner credentials can be imported/provisioned but do not remain a parallel secret authority.

## Deferred Realization

Marketplace/general external adapter ecosystem is productization work. Core ProviderAdapter/Connection contracts are fixed now.

## Temporary Dogfood Behavior

CLI/manual setup may create Connections before polished connection UX exists. Runs still consume scoped projections from canonical Connection/SecretStore.

## Failure / Recovery

Transient provider outage can retry; missing authorization requires user/owner action; cancellation returns to prior Planning/operation without state loss.

## UI Implications

Settings and contextual connection cards show provider, identity/account, resources, capabilities, status, scope and exactly why access is required. Raw tokens are never shown after entry.

## Decisions / ADRs

See architecture integrations-and-connections and security-and-trust.