# AWP Integration and Connection Architecture

**Date:** 2026-08-19  
**Status:** Canonical architecture supplement within the existing provider/credential boundary.  
**Purpose:** Freeze the account/connection model required by Planning, CI/CD, deployment, repository access, and future external adapters without making provider credentials ordinary project configuration.

## 1. Boundary

AWP already separates provider mechanics from product semantics and stores secret material behind `SecretStore`/`CredentialReference`. This document specializes that existing boundary for authenticated external services.

It does not change the three-plane architecture or provider-ownership law.

## 2. Core primitives

```text
ProviderAdapter
  implementation for an external service/capability family

Connection
  user-owned authenticated external identity/session
  reusable across Projects
  multiple Connections per provider are allowed

ProjectConnectionBinding
  project-local authorization to use one Connection
  includes allowed capability/role and provider resource scope

ConnectionRequirement
  structured requirement produced by planning/runtime readiness
  identifies what access is missing or unhealthy

CredentialReference
  reference to secret/token material behind SecretStore
```

Provider-native account IDs, installation IDs, zone IDs, repository IDs, OAuth grant IDs, etc. are mappings on these AWP records, not the sole domain identity.

## 3. Scope model

Connections are global **per user** in the initial product model. Projects bind only the Connections they are allowed to use.

```text
User
  Connection A: GitHub personal
  Connection B: GitHub work
  Connection C: Cloudflare personal
  Connection D: Cloudflare customer-a

Project X
  ProjectConnectionBinding -> GitHub work / source+CI
  ProjectConnectionBinding -> Cloudflare customer-a / production deploy
```

A Plan normally inherits permitted ProjectConnectionBindings. Plan/Task/Run selection may narrow or select among project-permitted bindings, but may not broaden access to an unrelated user-global Connection without an explicit project authorization change.

## 4. Multiple accounts and roles

Never model a provider as one global token such as `githubToken` or `cloudflareToken`.

A Project may use multiple Connections from the same provider for different roles, for example:

```text
GitHub source read      -> account A
GitHub publication      -> GitHub App/install B
Cloudflare staging      -> account C
Cloudflare production   -> account D
```

Selection is capability/role based and may use an explicit `ConnectionSelectionPolicy` where several bindings satisfy the same requirement.

## 5. Capability/resource scoping

A `ProjectConnectionBinding` is narrower than the underlying authenticated account.

It constrains:

```text
provider capabilities
provider resource selectors
allowed environments/roles
AWP policy constraints
```

Examples include a GitHub installation/repository or a Cloudflare account/zone/Workers project.

Least privilege is the default. Binding a Connection to a Project does not automatically grant every provider permission exposed by that Connection.

## 6. Secret handling

```text
Connection
  -> CredentialReference
  -> SecretStore
```

Raw secrets/tokens are never copied into Project, Plan, Task, Run, CIExecution, Deployment, or ordinary configuration records.

Execution workloads receive only the access required for the attempt. Prefer short-lived/delegated provider credentials where supported. Reusable publication/production credentials remain behind trusted control-plane/provider execution boundaries.

## 7. Connection lifecycle

Connections are stateful and observable:

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

Provider adapters normalize expiration/revocation/permission/resource errors into AWP state. Dependent Planning/CI/Deployment state references the affected ConnectionRequirement rather than exposing raw provider errors as the product model.

## 8. Readiness behavior

A missing Connection is not automatically a global blocker.

`ConnectionRequirement` declares the lifecycle gate at which access becomes required, for example:

```text
repository inspection
CI execution
release publication
deployment preflight
production launch
external research/data access
```

Planning can proceed past a deferred setup item when the requirement is not yet needed. The requirement remains visible and becomes blocking at its declared gate.

## 9. Architecture implications

The architecture foundation specs must define:

```text
Connection/ProjectConnectionBinding ownership and authorization
provider capability/resource normalization
OAuth/token lifecycle and re-authentication
SecretStore/CredentialReference contracts
project and plan selection rules
attempt-bound credential delegation
connection audit/events
provider health/error normalization
multi-user/project ownership rules
```

This belongs in the architecture/specification phase before provider-specific UI or adapter implementation.