feat: complete provider-uniformity boundary

.github/workflows/ci.yml

@@ -38,7 +38,9 @@ jobs:
           go-version: ${{ env.GO_VERSION }}
           cache: true
       - name: Boundary guard
-        run: bash ./scripts/check-ecosystem-boundaries.sh
+        run: |
+          bash ./scripts/check-ecosystem-boundaries.sh
+          bash ./scripts/check-client-layering.sh
       - name: gofumpt
         run: |
           go install mvdan.cc/gofumpt@v0.10.0
@@ -121,7 +123,9 @@ jobs:
       - name: Clone tok (workspace dep)
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
       - name: Boundary guard
-        run: bash ./scripts/check-ecosystem-boundaries.sh
+        run: |
+          bash ./scripts/check-ecosystem-boundaries.sh
+          bash ./scripts/check-client-layering.sh
       - name: Run golangci-lint
         run: |
           go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.0
@@ -143,7 +147,9 @@ jobs:
       - name: Clone tok (workspace dep)
         run: git clone --depth=1 https://github.com/GrayCodeAI/tok.git ../tok
       - name: Boundary guard
-        run: bash ./scripts/check-ecosystem-boundaries.sh
+        run: |
+          bash ./scripts/check-ecosystem-boundaries.sh
+          bash ./scripts/check-client-layering.sh
       - name: Test with race detector
         run: go test ./... -race -count=1 -shuffle=on -coverprofile=coverage.out -covermode=atomic -timeout=300s
       - name: Coverage summary

.gitignore

@@ -3,6 +3,7 @@
 /basic
 bin/
 *.exe
+*.test
 
 # Secrets / local config
 .env
@@ -11,6 +12,8 @@ bin/
 
 # Build / cache / seed artifacts
 .gocache/
+.gomodcache/
+.golangci-cache/
 *.seeds.json
 elrond*.db
 *.codegraph.db

AGENTS.md

@@ -5,7 +5,8 @@ Universal LLM provider runtime. One interface for every model. Authentication, r
 ## Design Principles
 
 - **Model-agnostic** — single interface for 75+ LLM providers
-- **Zero opinions** — consumers control routing, caching, and retry strategies
+- **Host-neutral engine** — Eyrie owns provider routing, transport, caching,
+  retry/fallback, and normalized telemetry; hosts own product UX and semantics
 - **Streaming-first** — all responses are streamed; blocking is opt-in
 
 ## Observability
@@ -25,13 +26,13 @@ make ci                          # Full CI suite
 
 ## Architecture
 
-- `provider.go` — Provider interface and registry
-- `routing.go` — Model routing and fallback chains
-- `streaming.go` — SSE streaming with backpressure
-- `auth.go` — API key management and rotation
-- `cache.go` — Response caching (optional)
-- `retry.go` — Retry with exponential backoff + Retry-After
-- `catalog.go` — Model catalog and capability discovery
+- `engine/` — stable host-facing provider engine facade and DTO contract
+- `client/core/` — provider-neutral wire types, transport, stream, and retry primitives
+- `client/adapters/` — provider protocol adapters and construction registry
+- `client/` — backwards-compatible public facade, middleware, and caches
+- `credentials/` — API key storage, lookup, and safe status projection
+- `catalog/` — model catalog, discovery, capabilities, and pricing
+- `router/` and `runtime/` — route policy and runtime resolution
 
 ## Conventions
 
@@ -44,7 +45,10 @@ make ci                          # Full CI suite
 
 ## Common Pitfalls
 
-- Provider interface is the boundary — keep it stable
+- `engine` is Hawk's product boundary; Hawk must not assemble lower-level
+  `client`, `catalog`, `config`, `credentials`, `router`, or `runtime` packages
+- `client.Provider` remains the lower-level compatibility boundary for other
+  consumers; preserve its method set and the facade's type identity
 - Streaming tests need careful goroutine management
 - `go.work` here should stay minimal; hawk's own `go.work` adds an `external/eyrie` replace so hawk can develop against a local eyrie checkout. Do not add extra local `replace` directives here without coordinating with hawk's workspace.
 
@@ -106,14 +110,16 @@ make ci                          # Full CI suite
 |---|---|
 | Provider interface | `client/client.go` (`Provider`, `EyrieConfig`, `EyrieMessage`, `ContentPart`) |
 | Chat implementation | `client/chat.go` (`Chat()`, `StreamChat()`, `StreamChatContinue()`) |
-| Anthropic provider | `client/anthropic.go` |
-| OpenAI provider | `client/openai.go` |
-| Gemini provider | `client/gemini.go` |
-| Bedrock provider | `client/bedrock.go` |
-| Vertex provider | `client/vertex.go` |
-| Azure provider | `client/azure.go` |
-| Provider registry | `client/provider_registry.go` |
-| Provider compatibility | `client/compat.go` (`OpenAICompat`, `GrokCompat`, etc.) |
+| Host-facing engine facade | `engine/` |
+| Provider-neutral core | `client/core/` |
+| Anthropic provider | `client/adapters/anthropic.go` |
+| OpenAI provider | `client/adapters/openai.go` |
+| Gemini provider | `client/adapters/gemini.go` |
+| Bedrock provider | `client/adapters/bedrock.go` |
+| Vertex provider | `client/adapters/vertex.go` |
+| Azure provider | `client/adapters/azure.go` |
+| Provider registry | `client/adapters/provider_registry.go` |
+| Provider compatibility | `client/adapters/compat.go` (`OpenAICompat`, `GrokCompat`, etc.) |
 | SSE streaming | `client/stream.go` (`parseSSEStream()`, `SSEEvent`) |
 | Retry logic | `client/retry.go` (`RetryConfig`, `backoffDelay()`, `shouldRetry()`) |
 | Rate limiting | `client/ratelimit.go`, `client/adaptive_ratelimit.go` |

Makefile

@@ -1,5 +1,5 @@
 # Canonical hawk-eco Makefile for Go LIBRARY repos.
-# eyrie is a library consumed by hawk (no standalone binary, no release).
+# eyrie is a versioned Go library consumed by Hawk (no standalone binary).
 
 # ---------------------------------------------------------------------------
 # Project metadata
@@ -36,6 +36,7 @@ GOVULNCHECK  := $(GOBIN_DIR)/govulncheck
 
 boundaries: ## Enforce support-repo import boundaries.
 	bash ./scripts/check-ecosystem-boundaries.sh
+	bash ./scripts/check-client-layering.sh
 
 # ---------------------------------------------------------------------------
 # Default target.

README.md

@@ -36,6 +36,13 @@ When your app calls a model, eyrie figures out which provider to use, how to tal
 
 **Your app never talks to an LLM API directly. eyrie does.**
 
+Hawk is the product face: it owns UX, agent orchestration, tools, permissions,
+sessions, and product semantics. Eyrie is the provider engine: it owns
+credentials, catalog and route resolution, provider transports, normalized
+streams, retry/fallback, usage, and provider telemetry. Hawk integrates through
+the stable [`engine`](engine/) facade rather than assembling Eyrie's internal
+provider packages.
+
 ## Ecosystem Boundaries
 
 eyrie is a Hawk support engine. Keep the dependency edge one-way:
@@ -240,7 +247,11 @@ config.SaveProviderConfig(cfg, "")               // save changes
 
 ```
 eyrie/
-├── client/                 # Provider client & streaming interface
+├── engine/                 # Stable host-facing facade and provider-neutral DTOs
+├── client/                 # Backwards-compatible public client facade
+│   ├── core/               # Provider-neutral wire, stream, retry, and transport primitives
+│   ├── adapters/           # Provider protocol adapters and construction registry
+│   └── embeddings/         # Embedding clients, cache, and defaults
 ├── config/                 # Provider configuration & routing
 │   └── credential/         # Credential file management
 ├── catalog/                # Model catalog & tier system
@@ -253,7 +264,7 @@ eyrie/
 ├── credentials/            # Credential management
 ├── docs/                   # Documentation & guides
 ├── examples/               # Runnable code examples
-├── router/                 # Weighted provider router
+├── router/                 # Provider routing strategies
 ├── runtime/                # Runtime manifest & routing policies
 ├── storage/                # SQLite conversation DAG store
 ├── types/                  # Branded types & API errors

catalog/discover/discover.go

@@ -37,7 +37,8 @@ func liveDeploymentIDs(v1Catalog catalog.Catalog) []string {
 // Options configures catalog discovery: published catalog + live provider APIs via API keys.
 type Options struct {
 	catalog.LoadCatalogOptions
-	Credentials catalog.Credentials
+	Credentials               catalog.Credentials
+	DisableCredentialFallback bool
 }
 
 // Run loads the deployment-aware catalog, optionally refreshes the remote catalog,
@@ -100,13 +101,13 @@ func run(ctx context.Context, opts Options) (*catalog.RefreshResult, error) {
 	catalog.EnsureCredentialRegistryInCatalog(base)
 
 	env := opts.Credentials.Env()
-	if len(env) == 0 {
+	if len(env) == 0 && !opts.DisableCredentialFallback {
 		env = eyriecfg.DiscoveryCredentials(ctx).Env()
 	}
 	if len(env) > 0 {
 		v1Catalog, enrichment := catalog.FetchLiveProviderCatalog(env)
 		liveProviders = enrichment
-		if len(v1Catalog.Models) > 0 {
+		if liveEnrichmentSucceeded(enrichment) {
 			base = MergeCatalogWithPolicy(base, &v1Catalog, MergePolicy{
 				PreferLive:                 true,
 				ReplaceDeploymentOfferings: liveDeploymentIDs(v1Catalog),
@@ -137,9 +138,18 @@ func run(ctx context.Context, opts Options) (*catalog.RefreshResult, error) {
 		CachePath:       opts.CachePath,
 		Source:          source,
 		RemoteURL:       opts.RemoteURL,
-		Refreshed:       refreshed || len(liveProviders) > 0,
+		Refreshed:       refreshed || liveEnrichmentSucceeded(liveProviders),
 		RemoteRefreshed: remoteRefreshed,
 		LiveProviders:   liveProviders,
 		StaleAfter:      base.StaleAfter,
 	}, nil
 }
+
+func liveEnrichmentSucceeded(enrichment []catalog.LiveProviderEnrichment) bool {
+	for _, provider := range enrichment {
+		if provider.Error == "" && provider.ModelCount > 0 {
+			return true
+		}
+	}
+	return false
+}