refactor: 大规模模块拆分与代码精简，新增 ai-pipeline/data-contracts 独立 crate

- 新增 aether-ai-pipeline 和 aether-data-contracts crate，将 pipeline 逻辑与数据契约从 gateway 中解耦 - 重构 admin handlers：拆分单体模块为 auth/billing/endpoint/features/model/observability/provider/system 等独立子模块 - 合并 chat/cli 重复代码路径：精简 conversion、finalize、planner 中的 sync/chat/cli 分支 - 重构 scheduler/executor/data 层，引入 facade 模式降低模块间耦合 - 移除冗余的 intent 模块，将 plan_fallback/policy/stream_path/sync_path 迁移至 executor - 前端适配：调整 admin API 调用和 provider 模型测试对话框
2026-09-02 17:30:23 +08:00 · 2026-04-07 02:50:19 +08:00
parent 763ff03a7b
commit 5d96d6673b
732 changed files with 28593 additions and 20666 deletions
--- a/apps/aether-gateway/src/tests/control/admin/adaptive.rs
+++ b/apps/aether-gateway/src/tests/control/admin/adaptive.rs
@@ -1,7 +1,8 @@
 use std::sync::{Arc, Mutex};

-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository, StoredProviderCatalogKey,
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::{
+    ProviderCatalogReadRepository, StoredProviderCatalogKey,
 };
 use axum::body::Body;
 use axum::routing::any;
@@ -222,9 +223,7 @@ async fn gateway_handles_admin_adaptive_mode_returns_service_unavailable_without
    let repository = adaptive_repository_with_keys(vec![adaptive_key]);

    assert_adaptive_route_returns_local_503(
-        crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(
-            repository,
-        ),
+        crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(repository),
        http::Method::PATCH,
        "/api/admin/adaptive/keys/key-adaptive/mode",
        Some(json!({ "enabled": false, "fixed_limit": 20 })),
--- a/apps/aether-gateway/src/tests/control/admin/api_keys.rs
+++ b/apps/aether-gateway/src/tests/control/admin/api_keys.rs
@@ -4,8 +4,9 @@ use aether_crypto::{encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY}
 use aether_data::repository::auth::{
    InMemoryAuthApiKeySnapshotRepository, StoredAuthApiKeyExportRecord, StoredAuthApiKeySnapshot,
 };
-use aether_data::repository::usage::{InMemoryUsageReadRepository, StoredRequestUsageAudit};
+use aether_data::repository::usage::InMemoryUsageReadRepository;
 use aether_data::repository::wallet::{InMemoryWalletRepository, StoredWalletSnapshot};
+use aether_data_contracts::repository::usage::StoredRequestUsageAudit;
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
@@ -203,15 +204,15 @@ async fn gateway_handles_admin_api_keys_list_locally_with_trusted_admin_principa
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_wallet_and_usage_for_tests(
-                auth_repository,
-                Arc::new(InMemoryWalletRepository::seed(
-                    Vec::<StoredWalletSnapshot>::new(),
-                )),
-                usage_repository,
-            )
-            .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
-        ),
+                crate::data::GatewayDataState::with_auth_wallet_and_usage_for_tests(
+                    auth_repository,
+                    Arc::new(InMemoryWalletRepository::seed(vec![
+                        sample_standalone_wallet("key-1"),
+                    ])),
+                    usage_repository,
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -234,7 +235,15 @@ async fn gateway_handles_admin_api_keys_list_locally_with_trusted_admin_principa
        json!("sk-key-1-p...text")
    );
    assert_eq!(payload["api_keys"][0]["total_requests"], json!(7));
-    assert_eq!(payload["api_keys"][0]["total_tokens"], json!(90));
+    assert_eq!(
+        payload["api_keys"][0]["total_tokens"],
+        serde_json::Value::Null
+    );
+    assert_eq!(
+        payload["api_keys"][0]["wallet"]["id"],
+        json!("wallet-key-1")
+    );
+    assert_eq!(payload["api_keys"][0]["wallet"]["balance"], json!(20.0));
    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);

    gateway_handle.abort();
@@ -267,13 +276,13 @@ async fn gateway_handles_admin_api_keys_detail_locally_with_trusted_admin_princi
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_wallet_and_usage_for_tests(
-                auth_repository,
-                wallet_repository,
-                usage_repository,
-            )
-            .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
-        ),
+                crate::data::GatewayDataState::with_auth_wallet_and_usage_for_tests(
+                    auth_repository,
+                    wallet_repository,
+                    usage_repository,
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -299,6 +308,56 @@ async fn gateway_handles_admin_api_keys_detail_locally_with_trusted_admin_princi
    upstream_handle.abort();
 }

+#[tokio::test]
+async fn gateway_includes_usage_summary_when_admin_api_keys_list_requests_it() {
+    let (_upstream_url, _upstream_hits, upstream_handle) =
+        start_api_keys_upstream("/api/admin/api-keys").await;
+    let auth_repository = Arc::new(
+        InMemoryAuthApiKeySnapshotRepository::seed(vec![(
+            None,
+            sample_standalone_api_key_snapshot("key-1", "user-1", true),
+        )])
+        .with_export_records([sample_standalone_export_record(
+            "key-1",
+            "user-1",
+            "sk-key-1-plaintext",
+            true,
+        )]),
+    );
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![sample_usage_row(
+        "usage-1", "req-1", "key-1", 90,
+    )]));
+    let gateway = build_router_with_state(
+        AppState::new()
+            .expect("gateway should build")
+            .with_data_state_for_tests(
+                crate::data::GatewayDataState::with_auth_wallet_and_usage_for_tests(
+                    auth_repository,
+                    Arc::new(InMemoryWalletRepository::seed(
+                        Vec::<StoredWalletSnapshot>::new(),
+                    )),
+                    usage_repository,
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = admin_request(reqwest::Client::new().get(format!(
+        "{gateway_url}/api/admin/api-keys?include_usage_summary=true"
+    )))
+    .send()
+    .await
+    .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["api_keys"][0]["total_tokens"], json!(90));
+
+    gateway_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_api_keys_full_key_locally_with_trusted_admin_principal() {
    let (upstream_url, upstream_hits, upstream_handle) =
@@ -359,11 +418,11 @@ async fn gateway_handles_admin_api_keys_create_locally_with_trusted_admin_princi
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(
-                Arc::clone(&repository),
-            )
-            .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
-        ),
+                crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(Arc::clone(
+                    &repository,
+                ))
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -431,11 +490,11 @@ async fn gateway_handles_admin_api_keys_update_locally_with_trusted_admin_princi
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(
-                Arc::clone(&repository),
-            )
-            .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
-        ),
+                crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(Arc::clone(
+                    &repository,
+                ))
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -487,11 +546,11 @@ async fn gateway_handles_admin_api_keys_toggle_locally_with_trusted_admin_princi
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(
-                Arc::clone(&repository),
-            )
-            .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
-        ),
+                crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(Arc::clone(
+                    &repository,
+                ))
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -533,11 +592,11 @@ async fn gateway_handles_admin_api_keys_delete_locally_with_trusted_admin_princi
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(
-                Arc::clone(&repository),
-            )
-            .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
-        ),
+                crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(Arc::clone(
+                    &repository,
+                ))
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

--- a/apps/aether-gateway/src/tests/control/admin/billing.rs
+++ b/apps/aether-gateway/src/tests/control/admin/billing.rs
@@ -131,9 +131,9 @@ async fn gateway_handles_admin_billing_apply_preset_locally_with_trusted_admin_p
    let gateway = build_router_with_state(
        AppState::new()
            .expect("gateway should build")
-            .with_admin_billing_collectors_for_tests(Vec::<
-                crate::AdminBillingCollectorRecord,
-            >::new()),
+            .with_admin_billing_collectors_for_tests(
+                Vec::<crate::AdminBillingCollectorRecord>::new(),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -215,11 +215,9 @@ async fn gateway_returns_conflict_for_admin_billing_apply_preset_when_backend_un
    let (upstream_url, upstream_handle) = start_server(upstream).await;
    let mut state = AppState::new()
        .expect("gateway should build")
-        .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_user_reader_for_tests(Arc::new(
-                InMemoryUserReadRepository::seed_auth_users(Vec::new()),
-            )),
-        );
+        .with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+            Arc::new(InMemoryUserReadRepository::seed_auth_users(Vec::new())),
+        ));
    state.admin_billing_collector_store = None;
    let gateway = build_router_with_state(state);
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -443,11 +441,9 @@ async fn gateway_returns_conflict_for_admin_billing_rule_create_when_backend_una
    let (upstream_url, upstream_handle) = start_server(upstream).await;
    let mut state = AppState::new()
        .expect("gateway should build")
-        .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_user_reader_for_tests(Arc::new(
-                InMemoryUserReadRepository::seed_auth_users(Vec::new()),
-            )),
-        );
+        .with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+            Arc::new(InMemoryUserReadRepository::seed_auth_users(Vec::new())),
+        ));
    state.admin_billing_rule_store = None;
    let gateway = build_router_with_state(state);
    let (gateway_url, gateway_handle) = start_server(gateway).await;
--- a/apps/aether-gateway/src/tests/control/admin/endpoints/keys.rs
+++ b/apps/aether-gateway/src/tests/control/admin/endpoints/keys.rs
@@ -3,9 +3,8 @@ use std::sync::{Arc, Mutex};
 use aether_crypto::{
    decrypt_python_fernet_ciphertext, encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY,
 };
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
--- a/apps/aether-gateway/src/tests/control/admin/endpoints/quota.rs
+++ b/apps/aether-gateway/src/tests/control/admin/endpoints/quota.rs
@@ -2,9 +2,9 @@ use std::collections::BTreeMap;
 use std::sync::{Arc, Mutex};

 use aether_crypto::{encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY};
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository, StoredProviderCatalogKey,
-    StoredProviderCatalogProvider,
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::{
+    ProviderCatalogReadRepository, StoredProviderCatalogKey, StoredProviderCatalogProvider,
 };
 use axum::body::{to_bytes, Body};
 use axum::routing::any;
@@ -428,6 +428,105 @@ async fn gateway_refreshes_admin_provider_quota_locally_for_kiro_with_trusted_ad
    upstream_handle.abort();
 }

+#[tokio::test]
+async fn gateway_reports_codex_quota_runtime_failures_locally_without_falling_back_to_admin_passthrough(
+) {
+    let upstream_hits = Arc::new(Mutex::new(0usize));
+    let upstream_hits_clone = Arc::clone(&upstream_hits);
+    let upstream = Router::new().route(
+        "/api/admin/endpoints/providers/provider-codex/refresh-quota",
+        any(move |_request: Request| {
+            let upstream_hits_inner = Arc::clone(&upstream_hits_clone);
+            async move {
+                *upstream_hits_inner.lock().expect("mutex should lock") += 1;
+                (StatusCode::OK, Body::from("unexpected upstream hit"))
+            }
+        }),
+    );
+
+    let execution_runtime = Router::new().route(
+        "/v1/execute/sync",
+        any(move |_request: Request| async move {
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Body::from("runtime unavailable"),
+            )
+        }),
+    );
+
+    let provider_catalog_repository = Arc::new(InMemoryProviderCatalogReadRepository::seed(
+        vec![StoredProviderCatalogProvider::new(
+            "provider-codex".to_string(),
+            "codex".to_string(),
+            Some("https://example.com".to_string()),
+            "codex".to_string(),
+        )
+        .expect("provider should build")],
+        vec![sample_endpoint(
+            "endpoint-codex-cli",
+            "provider-codex",
+            "openai:cli",
+            "https://chatgpt.com/backend-api",
+        )],
+        vec![sample_key(
+            "key-codex-a",
+            "provider-codex",
+            "openai:cli",
+            "sk-codex-123",
+        )],
+    ));
+
+    let (_upstream_url, upstream_handle) = start_server(upstream).await;
+    let (execution_runtime_url, execution_runtime_handle) = start_server(execution_runtime).await;
+    let gateway = build_router_with_state(
+        build_state_with_execution_runtime_override(execution_runtime_url.clone())
+            .with_data_state_for_tests(
+                GatewayDataState::with_provider_catalog_repository_for_tests(
+                    provider_catalog_repository.clone(),
+                )
+                .with_encryption_key_for_tests(DEVELOPMENT_ENCRYPTION_KEY),
+            ),
+    );
+    let (gateway_url, gateway_handle) = start_server(gateway).await;
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{gateway_url}/api/admin/endpoints/providers/provider-codex/refresh-quota"
+        ))
+        .header(crate::constants::GATEWAY_HEADER, "rust-phase3b")
+        .header(TRUSTED_ADMIN_USER_ID_HEADER, "admin-user-123")
+        .header(TRUSTED_ADMIN_USER_ROLE_HEADER, "admin")
+        .header(TRUSTED_ADMIN_SESSION_ID_HEADER, "session-123")
+        .send()
+        .await
+        .expect("request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["success"], 0);
+    assert_eq!(payload["failed"], 1);
+    assert_eq!(payload["total"], 1);
+    assert_eq!(payload["results"][0]["status"], "error");
+    assert_eq!(payload["results"][0]["status_code"], 502);
+    assert!(payload["results"][0]["message"]
+        .as_str()
+        .expect("message should be string")
+        .contains("wham/usage 请求执行失败: execution runtime returned HTTP 500"));
+    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);
+
+    let reloaded = provider_catalog_repository
+        .list_keys_by_ids(&["key-codex-a".to_string()])
+        .await
+        .expect("keys should read");
+    assert_eq!(reloaded.len(), 1);
+    assert_eq!(reloaded[0].oauth_invalid_reason, None);
+    assert_eq!(reloaded[0].upstream_metadata, None);
+
+    gateway_handle.abort();
+    execution_runtime_handle.abort();
+    upstream_handle.abort();
+}
+
 #[tokio::test]
 async fn gateway_refreshes_admin_provider_quota_locally_for_antigravity_with_trusted_admin_principal(
 ) {
--- a/apps/aether-gateway/src/tests/control/admin/endpoints/routes.rs
+++ b/apps/aether-gateway/src/tests/control/admin/endpoints/routes.rs
@@ -1,8 +1,7 @@
 use std::sync::{Arc, Mutex};

-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
@@ -599,9 +598,7 @@ async fn gateway_handles_admin_default_body_rules_locally_with_trusted_admin_pri
    let rules = payload["body_rules"]
        .as_array()
        .expect("body_rules should be an array");
-    assert_eq!(rules.len(), 5);
-    assert_eq!(rules[0]["action"], "drop");
-    assert_eq!(rules[0]["path"], "max_output_tokens");
+    assert!(rules.is_empty());
    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);

    gateway_handle.abort();
--- a/apps/aether-gateway/src/tests/control/admin/gemini_files.rs
+++ b/apps/aether-gateway/src/tests/control/admin/gemini_files.rs
@@ -3,9 +3,9 @@ use aether_data::repository::candidates::InMemoryRequestCandidateRepository;
 use aether_data::repository::gemini_file_mappings::{
    GeminiFileMappingReadRepository, InMemoryGeminiFileMappingRepository,
 };
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, StoredProviderCatalogEndpoint, StoredProviderCatalogKey,
-    StoredProviderCatalogProvider,
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::{
+    StoredProviderCatalogEndpoint, StoredProviderCatalogKey, StoredProviderCatalogProvider,
 };
 use axum::body::{to_bytes, Body};
 use axum::routing::any;
--- a/apps/aether-gateway/src/tests/control/admin/health_access.rs
+++ b/apps/aether-gateway/src/tests/control/admin/health_access.rs
@@ -3,13 +3,11 @@ use std::time::{SystemTime, UNIX_EPOCH};

 use aether_crypto::DEVELOPMENT_ENCRYPTION_KEY;
 use aether_data::repository::auth_modules::InMemoryAuthModuleReadRepository;
-use aether_data::repository::candidates::{
-    InMemoryRequestCandidateRepository, RequestCandidateStatus,
-};
+use aether_data::repository::candidates::InMemoryRequestCandidateRepository;
 use aether_data::repository::management_tokens::InMemoryManagementTokenRepository;
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::candidates::RequestCandidateStatus;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::Body;
 use axum::routing::{any, get, patch, put};
 use axum::{extract::Request, Router};
--- a/apps/aether-gateway/src/tests/control/admin/models/external.rs
+++ b/apps/aether-gateway/src/tests/control/admin/models/external.rs
@@ -11,6 +11,27 @@ use crate::constants::{
    TRUSTED_ADMIN_USER_ROLE_HEADER,
 };

+struct TestEnvVarGuard {
+    key: &'static str,
+    previous: Option<String>,
+}
+
+impl Drop for TestEnvVarGuard {
+    fn drop(&mut self) {
+        if let Some(previous) = self.previous.as_deref() {
+            std::env::set_var(self.key, previous);
+        } else {
+            std::env::remove_var(self.key);
+        }
+    }
+}
+
+fn set_test_env_var(key: &'static str, value: &str) -> TestEnvVarGuard {
+    let previous = std::env::var(key).ok();
+    std::env::set_var(key, value);
+    TestEnvVarGuard { key, previous }
+}
+
 #[tokio::test]
 async fn gateway_handles_admin_external_models_locally_with_trusted_admin_principal() {
    let upstream_hits = Arc::new(Mutex::new(0usize));
@@ -27,6 +48,29 @@ async fn gateway_handles_admin_external_models_locally_with_trusted_admin_princi
    );

    let (upstream_url, upstream_handle) = start_server(upstream).await;
+    let external_source = Router::new().route(
+        "/api.json",
+        any(|_request: Request| async move {
+            (
+                StatusCode::OK,
+                axum::Json(serde_json::json!({
+                    "openai": {
+                        "name": "OpenAI",
+                        "models": {
+                            "gpt-5": {
+                                "name": "GPT-5"
+                            }
+                        }
+                    }
+                })),
+            )
+        }),
+    );
+    let (external_source_url, external_source_handle) = start_server(external_source).await;
+    let _guard = set_test_env_var(
+        "AETHER_GATEWAY_EXTERNAL_MODELS_URL",
+        &format!("{external_source_url}/api.json"),
+    );
    let gateway = build_router_with_state(AppState::new().expect("gateway should build"));
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -40,15 +84,17 @@ async fn gateway_handles_admin_external_models_locally_with_trusted_admin_princi
        .await
        .expect("request should succeed");

-    assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
+    assert_eq!(response.status(), StatusCode::OK);
    let payload: serde_json::Value = response.json().await.expect("json body should parse");
+    assert_eq!(payload["openai"]["official"], serde_json::json!(true));
    assert_eq!(
-        payload["detail"],
-        "External models catalog requires Rust admin backend"
+        payload["openai"]["models"]["gpt-5"]["name"],
+        serde_json::json!("GPT-5")
    );
    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);

    gateway_handle.abort();
+    external_source_handle.abort();
    upstream_handle.abort();
 }

--- a/apps/aether-gateway/src/tests/control/admin/models/global.rs
+++ b/apps/aether-gateway/src/tests/control/admin/models/global.rs
@@ -1,9 +1,10 @@
 use std::sync::{Arc, Mutex};

-use aether_data::repository::global_models::{
-    AdminProviderModelListQuery, GlobalModelReadRepository, InMemoryGlobalModelReadRepository,
-};
+use aether_data::repository::global_models::InMemoryGlobalModelReadRepository;
 use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::global_models::{
+    AdminProviderModelListQuery, GlobalModelReadRepository,
+};
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
--- a/apps/aether-gateway/src/tests/control/admin/models/provider.rs
+++ b/apps/aether-gateway/src/tests/control/admin/models/provider.rs
@@ -1,10 +1,12 @@
 use std::sync::{Arc, Mutex};

-use aether_data::repository::global_models::{
-    AdminProviderModelListQuery, GlobalModelReadRepository, InMemoryGlobalModelReadRepository,
-};
+use aether_data::repository::global_models::InMemoryGlobalModelReadRepository;
 use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
 use aether_data::repository::quota::InMemoryProviderQuotaRepository;
+use aether_data_contracts::repository::{
+    global_models::{AdminProviderModelListQuery, GlobalModelReadRepository},
+    quota::StoredProviderQuotaSnapshot,
+};
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
--- a/apps/aether-gateway/src/tests/control/admin/monitoring.rs
+++ b/apps/aether-gateway/src/tests/control/admin/monitoring.rs
@@ -4,17 +4,19 @@ use aether_crypto::{encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY}
 use aether_data::repository::auth::{
    InMemoryAuthApiKeySnapshotRepository, StoredAuthApiKeyExportRecord,
 };
-use aether_data::repository::candidates::{
-    InMemoryRequestCandidateRepository, RequestCandidateStatus, StoredRequestCandidate,
-};
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, StoredProviderCatalogEndpoint, StoredProviderCatalogKey,
-    StoredProviderCatalogProvider,
-};
-use aether_data::repository::usage::{InMemoryUsageReadRepository, StoredRequestUsageAudit};
+use aether_data::repository::candidates::InMemoryRequestCandidateRepository;
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data::repository::usage::InMemoryUsageReadRepository;
 use aether_data::repository::users::{
    InMemoryUserReadRepository, StoredUserAuthRecord, StoredUserExportRow,
 };
+use aether_data_contracts::repository::candidates::{
+    RequestCandidateStatus, StoredRequestCandidate,
+};
+use aether_data_contracts::repository::provider_catalog::{
+    StoredProviderCatalogEndpoint, StoredProviderCatalogKey, StoredProviderCatalogProvider,
+};
+use aether_data_contracts::repository::usage::StoredRequestUsageAudit;
 use axum::body::Body;
 use axum::routing::{any, delete, get};
 use axum::{extract::Request, Router};
@@ -685,13 +687,11 @@ async fn gateway_handles_admin_monitoring_cache_stats_locally_with_trusted_admin
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_usage_reader_for_tests(
-                    usage_repository,
-                )
-                .with_system_config_values_for_tests([
-                    ("scheduling_mode".to_string(), json!("cache_affinity")),
-                    ("provider_priority_mode".to_string(), json!("provider")),
-                ]),
+                crate::data::GatewayDataState::with_usage_reader_for_tests(usage_repository)
+                    .with_system_config_values_for_tests([
+                        ("scheduling_mode".to_string(), json!("cache_affinity")),
+                        ("provider_priority_mode".to_string(), json!("provider")),
+                    ]),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -963,10 +963,8 @@ async fn gateway_handles_admin_monitoring_cache_affinity_locally_without_redis_o
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_user_reader_for_tests(
-                    user_repository,
-                )
-                .with_auth_api_key_reader(auth_repository),
+                crate::data::GatewayDataState::with_user_reader_for_tests(user_repository)
+                    .with_auth_api_key_reader(auth_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -1028,10 +1026,8 @@ async fn gateway_handles_admin_monitoring_cache_users_delete_locally_with_truste
    let state = AppState::new()
        .expect("gateway should build")
        .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_user_reader_for_tests(
-                user_repository,
-            )
-            .with_auth_api_key_reader(auth_repository),
+            crate::data::GatewayDataState::with_user_reader_for_tests(user_repository)
+                .with_auth_api_key_reader(auth_repository),
        )
        .with_admin_monitoring_cache_affinity_entry_for_tests(
            "cache_affinity:user-key-1:openai:model-alpha",
@@ -1105,10 +1101,8 @@ async fn gateway_handles_admin_monitoring_cache_affinity_delete_locally_with_tru
    let state = AppState::new()
        .expect("gateway should build")
        .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_user_reader_for_tests(
-                user_repository,
-            )
-            .with_auth_api_key_reader(auth_repository),
+            crate::data::GatewayDataState::with_user_reader_for_tests(user_repository)
+                .with_auth_api_key_reader(auth_repository),
        )
        .with_admin_monitoring_cache_affinity_entry_for_tests(
            "cache_affinity:user-key-1:openai:model-alpha",
@@ -1366,13 +1360,11 @@ async fn gateway_handles_admin_monitoring_cache_metrics_locally_with_trusted_adm
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_usage_reader_for_tests(
-                    usage_repository,
-                )
-                .with_system_config_values_for_tests([
-                    ("scheduling_mode".to_string(), json!("cache_affinity")),
-                    ("provider_priority_mode".to_string(), json!("provider")),
-                ]),
+                crate::data::GatewayDataState::with_usage_reader_for_tests(usage_repository)
+                    .with_system_config_values_for_tests([
+                        ("scheduling_mode".to_string(), json!("cache_affinity")),
+                        ("provider_priority_mode".to_string(), json!("provider")),
+                    ]),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -2056,10 +2048,10 @@ async fn gateway_handles_admin_monitoring_resilience_circuit_history_locally_wit
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(
-                provider_catalog,
+                crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(
+                    provider_catalog,
+                ),
            ),
-        ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

--- a/apps/aether-gateway/src/tests/control/admin/oauth.rs
+++ b/apps/aether-gateway/src/tests/control/admin/oauth.rs
@@ -9,9 +9,8 @@ use aether_data::repository::management_tokens::{
 use aether_data::repository::oauth_providers::{
    InMemoryOAuthProviderRepository, OAuthProviderReadRepository,
 };
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::{to_bytes, Body, Bytes};
 use axum::response::{IntoResponse, Response};
 use axum::routing::{any, delete, get, patch, post, put};
@@ -30,7 +29,7 @@ use crate::constants::{
 };
 use crate::control::resolve_public_request_context;
 use crate::data::GatewayDataState;
-use crate::handlers::admin::maybe_build_local_admin_provider_oauth_response;
+use crate::handlers::admin::provider::maybe_build_local_admin_provider_oauth_response;

 fn trusted_admin_headers() -> HeaderMap {
    let mut headers = HeaderMap::new();
@@ -1990,12 +1989,12 @@ async fn gateway_refreshes_admin_provider_oauth_key_locally_with_trusted_admin_p
    let (upstream_url, upstream_handle) = start_server(upstream).await;
    let (token_url, token_handle) = start_server(token_server).await;
    let oauth_refresh =
-        crate::provider_transport::LocalOAuthRefreshCoordinator::with_adapters_for_tests(
-            vec![Arc::new(
+        crate::provider_transport::LocalOAuthRefreshCoordinator::with_adapters_for_tests(vec![
+            Arc::new(
                crate::provider_transport::oauth_refresh::GenericOAuthRefreshAdapter::default()
                    .with_token_url_for_tests("codex", format!("{token_url}/oauth/token")),
-            )],
-        );
+            ),
+        ]);
    let gateway = build_router_with_state(
        AppState::new()
            .expect("gateway should build")
--- a/apps/aether-gateway/src/tests/control/admin/pool.rs
+++ b/apps/aether-gateway/src/tests/control/admin/pool.rs
@@ -1,9 +1,8 @@
 use std::sync::{Arc, Mutex};

 use aether_crypto::DEVELOPMENT_ENCRYPTION_KEY;
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::{Body, Bytes};
 use axum::routing::{any, get, post};
 use axum::{extract::Request, Router};
@@ -20,7 +19,7 @@ use crate::constants::{
 };
 use crate::control::resolve_public_request_context;
 use crate::data::GatewayDataState;
-use crate::handlers::admin::maybe_build_local_admin_pool_response;
+use crate::handlers::admin::system::maybe_build_local_admin_pool_response;

 fn trusted_admin_headers() -> HeaderMap {
    let mut headers = HeaderMap::new();
--- a/apps/aether-gateway/src/tests/control/admin/provider_ops.rs
+++ b/apps/aether-gateway/src/tests/control/admin/provider_ops.rs
@@ -3,9 +3,8 @@ use std::sync::{Arc, Mutex};
 use aether_crypto::{
    decrypt_python_fernet_ciphertext, encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY,
 };
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
 use axum::body::to_bytes;
 use axum::body::Body;
 use axum::routing::{any, get, post};
--- a/apps/aether-gateway/src/tests/control/admin/provider_query.rs
+++ b/apps/aether-gateway/src/tests/control/admin/provider_query.rs
@@ -1,9 +1,8 @@
 use std::sync::{Arc, Mutex};

 use aether_data::repository::global_models::InMemoryGlobalModelReadRepository;
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, StoredProviderCatalogEndpoint,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data_contracts::repository::provider_catalog::StoredProviderCatalogEndpoint;
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
@@ -248,6 +247,27 @@ async fn gateway_handles_admin_provider_query_test_model_failover_locally_with_t
    .await;
 }

+#[tokio::test]
+async fn gateway_handles_admin_provider_query_test_model_failover_with_single_model_name_alias() {
+    assert_admin_provider_query_route(
+        "/api/admin/provider-query/test-model-failover",
+        json!({
+            "provider_id": "provider-openai",
+            "model_name": "gpt-4.1"
+        }),
+        StatusCode::OK,
+        |payload| {
+            assert_eq!(payload["success"], json!(false));
+            assert_eq!(payload["tested"], json!(false));
+            assert_eq!(payload["model"], json!("gpt-4.1"));
+            assert_eq!(payload["failover_models"], json!(["gpt-4.1"]));
+            assert_eq!(payload["attempts"], json!([]));
+            assert_eq!(payload["total_attempts"], json!(0));
+        },
+    )
+    .await;
+}
+
 #[tokio::test]
 async fn gateway_rejects_admin_provider_query_invalid_json_body() {
    let upstream_hits = Arc::new(Mutex::new(0usize));
--- a/apps/aether-gateway/src/tests/control/admin/provider_strategy.rs
+++ b/apps/aether-gateway/src/tests/control/admin/provider_strategy.rs
@@ -1,9 +1,9 @@
 use std::sync::{Arc, Mutex};

-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
-use aether_data::repository::usage::{InMemoryUsageReadRepository, StoredProviderUsageWindow};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data::repository::usage::InMemoryUsageReadRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
+use aether_data_contracts::repository::usage::StoredProviderUsageWindow;
 use axum::body::Body;
 use axum::routing::any;
 use axum::{extract::Request, Router};
@@ -143,9 +143,7 @@ async fn gateway_handles_admin_provider_strategy_stats_locally_returns_service_u
    let catalog_reader: Arc<dyn ProviderCatalogReadRepository> =
        provider_catalog_repository.clone();
    assert_provider_strategy_route_returns_local_503(
-        crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(
-            catalog_reader,
-        ),
+        crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(catalog_reader),
        Method::GET,
        "/api/admin/provider-strategy/providers/provider-openai/stats?hours=1",
        None,
@@ -165,9 +163,7 @@ async fn gateway_handles_admin_provider_strategy_quota_locally_returns_service_u
    let catalog_reader: Arc<dyn ProviderCatalogReadRepository> =
        provider_catalog_repository.clone();
    assert_provider_strategy_route_returns_local_503(
-        crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(
-            catalog_reader,
-        ),
+        crate::data::GatewayDataState::with_provider_catalog_reader_for_tests(catalog_reader),
        Method::DELETE,
        "/api/admin/provider-strategy/providers/provider-openai/quota",
        None,
--- a/apps/aether-gateway/src/tests/control/admin/providers.rs
+++ b/apps/aether-gateway/src/tests/control/admin/providers.rs
@@ -2,16 +2,19 @@ use std::sync::{Arc, Mutex};
 use std::time::{SystemTime, UNIX_EPOCH};

 use aether_crypto::{encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY};
-use aether_data::repository::candidates::{
-    InMemoryRequestCandidateRepository, RequestCandidateStatus,
-};
-use aether_data::repository::global_models::{
-    GlobalModelReadRepository, InMemoryGlobalModelReadRepository,
-};
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
+use aether_data::repository::candidates::InMemoryRequestCandidateRepository;
+use aether_data::repository::global_models::InMemoryGlobalModelReadRepository;
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
 use aether_data::repository::quota::InMemoryProviderQuotaRepository;
+use aether_data_contracts::repository::candidates::RequestCandidateStatus;
+use aether_data_contracts::repository::global_models::{
+    GlobalModelReadRepository, StoredAdminGlobalModel, StoredAdminProviderModel,
+    StoredProviderActiveGlobalModel, StoredProviderModelStats, StoredPublicGlobalModel,
+};
+use aether_data_contracts::repository::provider_catalog::{
+    ProviderCatalogReadRepository, StoredProviderCatalogEndpoint, StoredProviderCatalogKey,
+    StoredProviderCatalogProvider,
+};
 use axum::body::{Body, Bytes};
 use axum::routing::any;
 use axum::{extract::Request, Router};
@@ -31,7 +34,7 @@ use crate::constants::{
 };
 use crate::control::resolve_public_request_context;
 use crate::data::GatewayDataState;
-use crate::handlers::admin::maybe_build_local_admin_providers_response;
+use crate::handlers::admin::provider::maybe_build_local_admin_providers_response;

 const ADMIN_PROVIDERS_DATA_UNAVAILABLE_DETAIL: &str = "Admin provider catalog data unavailable";

@@ -952,16 +955,8 @@ async fn gateway_creates_admin_provider_locally_with_trusted_admin_principal() {
            .and_then(serde_json::Value::as_str),
        Some("force_stream")
    );
-    assert!(cli_endpoint
-        .body_rules
-        .as_ref()
-        .and_then(serde_json::Value::as_array)
-        .is_some_and(|rules| !rules.is_empty()));
-    assert!(compact_endpoint
-        .body_rules
-        .as_ref()
-        .and_then(serde_json::Value::as_array)
-        .is_some_and(|rules| !rules.is_empty()));
+    assert!(cli_endpoint.body_rules.is_none());
+    assert!(compact_endpoint.body_rules.is_none());
    assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);

    gateway_handle.abort();
@@ -1319,7 +1314,7 @@ async fn gateway_submits_admin_provider_delete_task_locally_with_trusted_admin_p
    assert!(remaining_keys.is_empty());
    let remaining_models = global_model_repository
        .list_admin_provider_models(
-            &aether_data::repository::global_models::AdminProviderModelListQuery {
+            &aether_data_contracts::repository::global_models::AdminProviderModelListQuery {
                provider_id: "provider-openai".to_string(),
                offset: 0,
                limit: 100,
--- a/apps/aether-gateway/src/tests/control/admin/security.rs
+++ b/apps/aether-gateway/src/tests/control/admin/security.rs
@@ -13,7 +13,7 @@ use crate::constants::{
    TRUSTED_ADMIN_USER_ID_HEADER, TRUSTED_ADMIN_USER_ROLE_HEADER,
 };
 use crate::control::resolve_public_request_context;
-use crate::handlers::admin::maybe_build_local_admin_security_response;
+use crate::handlers::admin::auth::maybe_build_local_admin_security_response;

 async fn send_admin_security_request(
    gateway: Router,
--- a/apps/aether-gateway/src/tests/control/admin/stats.rs
+++ b/apps/aether-gateway/src/tests/control/admin/stats.rs
@@ -4,10 +4,11 @@ use aether_data::repository::auth::{
    InMemoryAuthApiKeySnapshotRepository, StoredAuthApiKeySnapshot,
 };
 use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
-use aether_data::repository::usage::{InMemoryUsageReadRepository, StoredRequestUsageAudit};
+use aether_data::repository::usage::InMemoryUsageReadRepository;
 use aether_data::repository::users::{
    InMemoryUserReadRepository, StoredUserAuthRecord, StoredUserSummary,
 };
+use aether_data_contracts::repository::usage::StoredRequestUsageAudit;
 use axum::body::Body;
 use axum::routing::{any, get};
 use axum::{extract::Request, Router};
--- a/apps/aether-gateway/src/tests/control/admin/system.rs
+++ b/apps/aether-gateway/src/tests/control/admin/system.rs
@@ -9,15 +9,13 @@ use aether_data::repository::auth_modules::{
    InMemoryAuthModuleReadRepository, StoredOAuthProviderModuleConfig,
 };
 use aether_data::repository::candidates::InMemoryRequestCandidateRepository;
-use aether_data::repository::global_models::{
-    InMemoryGlobalModelReadRepository, StoredPublicGlobalModel,
-};
+use aether_data::repository::global_models::InMemoryGlobalModelReadRepository;
 use aether_data::repository::oauth_providers::InMemoryOAuthProviderRepository;
 use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
 use aether_data::repository::proxy_nodes::InMemoryProxyNodeRepository;
 use aether_data::repository::users::{InMemoryUserReadRepository, StoredUserExportRow};
-use aether_data::repository::wallet::InMemoryWalletRepository;
-use aether_data::repository::wallet::StoredWalletSnapshot;
+use aether_data::repository::wallet::{InMemoryWalletRepository, StoredWalletSnapshot};
+use aether_data_contracts::repository::global_models::StoredPublicGlobalModel;
 use axum::body::Body;
 use axum::routing::{any, delete, get, post, put};
 use axum::{extract::Request, Router};
--- a/apps/aether-gateway/src/tests/control/admin/usage.rs
+++ b/apps/aether-gateway/src/tests/control/admin/usage.rs
@@ -1,8 +1,9 @@
 use std::sync::{Arc, Mutex};

 use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
-use aether_data::repository::usage::{InMemoryUsageReadRepository, StoredRequestUsageAudit};
+use aether_data::repository::usage::InMemoryUsageReadRepository;
 use aether_data::repository::users::{InMemoryUserReadRepository, StoredUserSummary};
+use aether_data_contracts::repository::usage::StoredRequestUsageAudit;
 use axum::body::{Body, Bytes};
 use axum::routing::{any, get, post};
 use axum::{extract::Request, Router};
@@ -20,7 +21,7 @@ use crate::constants::{
 };
 use crate::control::resolve_public_request_context;
 use crate::data::GatewayDataState;
-use crate::handlers::admin::maybe_build_local_admin_usage_response;
+use crate::handlers::admin::observability::maybe_build_local_admin_usage_response;

 const ADMIN_USAGE_DATA_UNAVAILABLE_DETAIL: &str = "Admin usage data unavailable";
 const DAY_1_UNIX_SECS: i64 = 1_711_000_000;
--- a/apps/aether-gateway/src/tests/control/admin/users.rs
+++ b/apps/aether-gateway/src/tests/control/admin/users.rs
@@ -514,11 +514,9 @@ async fn gateway_handles_admin_user_session_routes_locally_with_trusted_admin_pr
    let gateway = build_router_with_state(
        AppState::new()
            .expect("gateway should build")
-            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_user_reader_for_tests(
-                    user_repository,
-                ),
-            )
+            .with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+                user_repository,
+            ))
            .with_auth_sessions_for_tests([older.clone(), newer.clone(), revoked, expired]),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -601,11 +599,11 @@ async fn gateway_handles_admin_user_api_key_routes_locally_with_trusted_admin_pr
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(
-                auth_repository,
-            )
-            .with_user_reader(user_repository),
-        ),
+                crate::data::GatewayDataState::with_auth_api_key_repository_for_tests(
+                    auth_repository,
+                )
+                .with_user_reader(user_repository),
+            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;

@@ -759,10 +757,8 @@ async fn gateway_returns_conflict_for_admin_create_user_api_key_when_writer_unav
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(
-                    auth_repository,
-                )
-                .with_user_reader(user_repository),
+                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(auth_repository)
+                    .with_user_reader(user_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -805,11 +801,10 @@ async fn gateway_returns_conflict_for_admin_create_user_when_writer_unavailable(

    let (upstream_url, upstream_handle) = start_server(upstream).await;
    let mut state = AppState::new().expect("gateway should build");
-    state = state.with_data_state_for_tests(
-        crate::data::GatewayDataState::with_user_reader_for_tests(Arc::new(
-            InMemoryUserReadRepository::seed_auth_users(Vec::new()),
-        )),
-    );
+    state =
+        state.with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+            Arc::new(InMemoryUserReadRepository::seed_auth_users(Vec::new())),
+        ));
    state.auth_user_store = None;
    state.auth_wallet_store = None;
    let gateway = build_router_with_state(state);
@@ -887,9 +882,7 @@ async fn gateway_returns_conflict_for_admin_lock_user_api_key_when_writer_unavai
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(
-                    auth_repository,
-                ),
+                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(auth_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -939,11 +932,9 @@ async fn gateway_returns_conflict_for_admin_update_user_when_writer_unavailable(
    let (upstream_url, upstream_handle) = start_server(upstream).await;
    let mut state = AppState::new()
        .expect("gateway should build")
-        .with_data_state_for_tests(
-            crate::data::GatewayDataState::with_user_reader_for_tests(
-                user_repository,
-            ),
-        );
+        .with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+            user_repository,
+        ));
    state.auth_user_store = None;
    state.auth_wallet_store = None;
    let gateway = build_router_with_state(state);
@@ -1016,9 +1007,7 @@ async fn gateway_returns_conflict_for_admin_update_user_api_key_when_writer_unav
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(
-                    auth_repository,
-                ),
+                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(auth_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -1092,9 +1081,7 @@ async fn gateway_returns_conflict_for_admin_delete_user_api_key_when_writer_unav
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(
-                    auth_repository,
-                ),
+                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(auth_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -1173,10 +1160,8 @@ async fn gateway_lists_admin_user_api_keys_locally_with_trusted_admin_principal(
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_user_reader_for_tests(
-                    user_repository,
-                )
-                .with_auth_api_key_reader(auth_repository),
+                crate::data::GatewayDataState::with_user_reader_for_tests(user_repository)
+                    .with_auth_api_key_reader(auth_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -1232,11 +1217,9 @@ async fn gateway_revokes_admin_user_session_locally_with_trusted_admin_principal
    let gateway = build_router_with_state(
        AppState::new()
            .expect("gateway should build")
-            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_user_reader_for_tests(
-                    user_repository,
-                ),
-            )
+            .with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+                user_repository,
+            ))
            .with_auth_session_for_tests(sample_admin_session("user-1", "session-1")),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -1288,11 +1271,9 @@ async fn gateway_revokes_all_admin_user_sessions_locally_with_trusted_admin_prin
    let gateway = build_router_with_state(
        AppState::new()
            .expect("gateway should build")
-            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_user_reader_for_tests(
-                    user_repository,
-                ),
-            )
+            .with_data_state_for_tests(crate::data::GatewayDataState::with_user_reader_for_tests(
+                user_repository,
+            ))
            .with_auth_sessions_for_tests(sessions),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
@@ -1366,9 +1347,7 @@ async fn gateway_reveals_admin_user_full_key_locally_with_trusted_admin_principa
        AppState::new()
            .expect("gateway should build")
            .with_data_state_for_tests(
-                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(
-                    auth_repository,
-                ),
+                crate::data::GatewayDataState::with_auth_api_key_reader_for_tests(auth_repository),
            ),
    );
    let (gateway_url, gateway_handle) = start_server(gateway).await;
--- a/apps/aether-gateway/src/tests/control/admin/video_tasks.rs
+++ b/apps/aether-gateway/src/tests/control/admin/video_tasks.rs
@@ -1,11 +1,11 @@
 use std::sync::{Arc, Mutex};

 use aether_crypto::DEVELOPMENT_ENCRYPTION_KEY;
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-};
-use aether_data::repository::video_tasks::{
-    InMemoryVideoTaskRepository, UpsertVideoTask, VideoTaskStatus, VideoTaskWriteRepository,
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data::repository::video_tasks::InMemoryVideoTaskRepository;
+use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
+use aether_data_contracts::repository::video_tasks::{
+    UpsertVideoTask, VideoTaskStatus, VideoTaskWriteRepository,
 };
 use axum::body::{to_bytes, Body, Bytes};
 use axum::response::Response;
@@ -25,7 +25,7 @@ use crate::constants::{
 };
 use crate::control::resolve_public_request_context;
 use crate::data::GatewayDataState;
-use crate::handlers::admin::maybe_build_local_admin_video_tasks_response;
+use crate::handlers::admin::features::maybe_build_local_admin_video_tasks_response;

 fn trusted_admin_headers() -> HeaderMap {
    let mut headers = HeaderMap::new();
--- a/apps/aether-gateway/src/tests/control/helpers.rs
+++ b/apps/aether-gateway/src/tests/control/helpers.rs
@@ -135,9 +135,7 @@ pub(super) async fn issue_test_admin_access_token(
        user.id.clone(),
        client_device_id.to_string(),
        None,
-        crate::data::state::StoredUserSessionRecord::hash_refresh_token(
-            &refresh_token,
-        ),
+        crate::data::state::StoredUserSessionRecord::hash_refresh_token(&refresh_token),
        None,
        None,
        Some(now),
--- a/apps/aether-gateway/src/tests/control/mod.rs
+++ b/apps/aether-gateway/src/tests/control/mod.rs
@@ -11,14 +11,6 @@ use aether_data::repository::auth::{
 use aether_data::repository::auth_modules::{
    InMemoryAuthModuleReadRepository, StoredLdapModuleConfig, StoredOAuthProviderModuleConfig,
 };
-use aether_data::repository::candidates::{
-    InMemoryRequestCandidateRepository, RequestCandidateStatus, StoredRequestCandidate,
-};
-use aether_data::repository::global_models::{
-    GlobalModelReadRepository, InMemoryGlobalModelReadRepository, StoredAdminGlobalModel,
-    StoredAdminProviderModel, StoredProviderActiveGlobalModel, StoredProviderModelStats,
-    StoredPublicGlobalModel,
-};
 use aether_data::repository::management_tokens::{
    InMemoryManagementTokenRepository, ManagementTokenReadRepository, StoredManagementToken,
    StoredManagementTokenUserSummary, StoredManagementTokenWithUser,
@@ -26,17 +18,24 @@ use aether_data::repository::management_tokens::{
 use aether_data::repository::oauth_providers::{
    InMemoryOAuthProviderRepository, OAuthProviderReadRepository, StoredOAuthProviderConfig,
 };
-use aether_data::repository::provider_catalog::{
-    InMemoryProviderCatalogReadRepository, ProviderCatalogReadRepository,
-    StoredProviderCatalogEndpoint, StoredProviderCatalogKey, StoredProviderCatalogProvider,
-};
+use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
 use aether_data::repository::proxy_nodes::{
    InMemoryProxyNodeRepository, ProxyNodeReadRepository, StoredProxyNode, StoredProxyNodeEvent,
 };
-use aether_data::repository::quota::{
-    InMemoryProviderQuotaRepository, StoredProviderQuotaSnapshot,
-};
+use aether_data::repository::quota::InMemoryProviderQuotaRepository;
 use aether_data::repository::wallet::InMemoryWalletRepository;
+use aether_data_contracts::repository::{
+    candidates::{RequestCandidateStatus, StoredRequestCandidate},
+    global_models::{
+        GlobalModelReadRepository, StoredAdminGlobalModel, StoredAdminProviderModel,
+        StoredProviderActiveGlobalModel, StoredProviderModelStats, StoredPublicGlobalModel,
+    },
+    provider_catalog::{
+        ProviderCatalogReadRepository, StoredProviderCatalogEndpoint, StoredProviderCatalogKey,
+        StoredProviderCatalogProvider,
+    },
+    quota::StoredProviderQuotaSnapshot,
+};
 use axum::body::{to_bytes, Body, Bytes};
 use axum::response::Response;
 use axum::routing::{any, post};