application-ai — IMP FORGE

Forge module wrapping infrastructure-ai.

Tier	application
Role	unclassified (baselined)
Path	`crates/application/ai`
Edition	2024
Targets	application_ai, pg_ai_credentials
Public items	25 across 4 modules
Tests	17

What it is for

application-ai — wraps infrastructure-ai.

Sprint 3.55: before this sprint migrations() returned Vec::new() and migrate_pending returned Ok(0) while ignoring the pool, so ai_credentials (and its encryption functions + assert-encryption-key trigger, crates/infrastructure/ai/migrations/001_ai_credentials.sql) were never created by anything that actually called this module's own migration path — the same bug class application-research names and fixes for itself. This sprint also relocates application-classify's generic ai_credentials/ai_settings_admin admin surface here (Gate 1.5 OQ1, unanimous MOVE — nothing about it was classify-specific) and adds the RBAC gate neither crate had before (permission_codes below, crate::api::ai_settings_admin).

Deliberately narrow in scope: this crate owns migration application, credential admin, and provider construction/permissions for AI-provider access — it does not own report generation (domain-ai-report, explicitly deferred, see the sprint doc's OQ4) or prompt-template storage (application-prompts).

Capabilities

`AiModule`

application-ai — wraps infrastructure-ai.

Item
`pub struct AiModule`
`AiModule :: fn new() -> Self`
`AiModule :: fn name(& self) -> & 'static str`
`AiModule :: fn version(& self) -> & 'static str`
`AiModule :: fn migrations(& self) -> Vec <MigrationSet>`
`AiModule :: async fn migrate_pending(& self, pool : & PgPool) -> std::result::Result <u32, MigrationError>`
`AiModule :: fn permission_codes(& self) -> Vec <String>`

`api (other)`

HTTP API for application-ai.

Item
`fn admin_router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`

`api::ai_settings_admin (other)`

AI settings admin REST endpoints (Sprint 45 — Gate 1.5 Q4).

Item
`fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`

`services::ai_credentials (other)`

AI credentials service (Sprint 45).

Item
`async fn resolve_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <Option <ResolvedKey>, AiCredentialsError>`
`async fn test_connection(pool : & PgPool, tenant_id : Uuid, provider : & str, provider_client : & dyn infrastructure_ai::AiProvider,) -> Result <TestConnectionResult, AiCredentialsError>`

`AiCredentialsError`

AI credentials service (Sprint 45).

Item
`pub enum AiCredentialsError`
`AiCredentialsError :: fn from(e : AiError) -> Self`
`async fn set_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str, api_key : & str,) -> Result <(), AiCredentialsError>`
`async fn get_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <Option <String>, AiCredentialsError>`
`async fn delete_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <(), AiCredentialsError>`
`async fn has_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <bool, AiCredentialsError>`
`async fn list_tenant_providers(pool : & PgPool, tenant_id : Uuid,) -> Result <Vec <ProviderInfo>, AiCredentialsError>`
`async fn set_system_key(pool : & PgPool, provider : & str, api_key : & str,) -> Result <(), AiCredentialsError>`
`async fn get_system_key(pool : & PgPool, provider : & str,) -> Result <Option <String>, AiCredentialsError>`
`async fn delete_system_key(pool : & PgPool, provider : & str) -> Result <(), AiCredentialsError>`
`async fn has_system_key_for(pool : & PgPool, provider : & str) -> Result <bool, AiCredentialsError>`
`async fn list_system_providers(pool : & PgPool) -> Result <Vec <ProviderInfo>, AiCredentialsError>`

`ResolvedKey`

AI credentials service (Sprint 45).

Item
`pub struct ResolvedKey`

`TestConnectionResult`

AI credentials service (Sprint 45).

Item
`pub struct TestConnectionResult`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

application_ai

api
api::ai_settings_admin
services
services::ai_credentials

flowchart TD
  n_application_ai["application_ai"]
  n_application_ai --> n_api["api"]
  n_api --> n_api__ai_settings_admin["ai_settings_admin"]
  n_application_ai --> n_services["services"]
  n_services --> n_services__ai_credentials["ai_credentials"]

Public surface

`crate root`

Item	What it is
`pub struct AiModule`	—
`AiModule :: fn new() -> Self`	—
`AiModule :: fn name(& self) -> & 'static str`	—
`AiModule :: fn version(& self) -> & 'static str`	—
`AiModule :: fn migrations(& self) -> Vec <MigrationSet>`	—
`AiModule :: async fn migrate_pending(& self, pool : & PgPool) -> std::result::Result <u32, MigrationError>`	—
`AiModule :: fn permission_codes(& self) -> Vec <String>`	—

`api`

Item	What it is
`fn admin_router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`	The AI-settings admin router, generic over the consumer's state type `S`.

`api::ai_settings_admin`

Item	What it is
`fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static, PgPool : FromRef <S>,`	—

`services::ai_credentials`

Item	What it is
`pub enum AiCredentialsError`	—
`AiCredentialsError :: fn from(e : AiError) -> Self`	—
`async fn set_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str, api_key : & str,) -> Result <(), AiCredentialsError>`	—
`async fn get_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <Option <String>, AiCredentialsError>`	—
`async fn delete_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <(), AiCredentialsError>`	—
`async fn has_tenant_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <bool, AiCredentialsError>`	—
`async fn list_tenant_providers(pool : & PgPool, tenant_id : Uuid,) -> Result <Vec <ProviderInfo>, AiCredentialsError>`	—
`async fn set_system_key(pool : & PgPool, provider : & str, api_key : & str,) -> Result <(), AiCredentialsError>`	—
`async fn get_system_key(pool : & PgPool, provider : & str,) -> Result <Option <String>, AiCredentialsError>`	—
`async fn delete_system_key(pool : & PgPool, provider : & str) -> Result <(), AiCredentialsError>`	—
`async fn has_system_key_for(pool : & PgPool, provider : & str) -> Result <bool, AiCredentialsError>`	—
`async fn list_system_providers(pool : & PgPool) -> Result <Vec <ProviderInfo>, AiCredentialsError>`	—
`async fn resolve_key(pool : & PgPool, tenant_id : Uuid, provider : & str,) -> Result <Option <ResolvedKey>, AiCredentialsError>`	Resolve the effective API key for a (tenant, provider) pair — tenant-specific key takes precedence over system key
`pub struct ResolvedKey`	—
`pub struct TestConnectionResult`	—
`async fn test_connection(pool : & PgPool, tenant_id : Uuid, provider : & str, provider_client : & dyn infrastructure_ai::AiProvider,) -> Result <TestConnectionResult, AiCredentialsError>`	Resolve the key, then call the provider with a tiny prompt (Sprint 47 — closes TD-CMS-AI-TEST-CONNECTION)

No pub use re-exports: every item above is declared in this crate.

Boundary

Reaches into infrastructure, platform.

Shares tier application with 120 other crates: application-agreements, application-analytics, application-approvals, application-assessments, application-audit-log, application-auth, application-billing, application-browser-automation, … (120 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`application`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/application/ai`
Vocabulary in force (lexicon)	`current`

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_application["application"] --> n_infrastructure["infrastructure"]
  n_application["application"] --> n_platform["platform"]

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`application-core`	application	no	always
`application-rbac`	application	no	always
`infrastructure-ai`	infrastructure	no	always
`platform-dto`	platform	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`async-trait`	`^0.1`	—	no	always
`axum`	`^0.7`	`multipart`	no	always
`serde`	`^1`	`derive`	no	always
`serde_json`	`^1`	—	no	always
`sqlx`	`^0.8`	`runtime-tokio`, `postgres`, `chrono`, `uuid`, `json`	no	always
`thiserror`	`^2`	—	no	always
`uuid`	`^1`	`v4`, `v7`, `serde`, `js`	no	always

Development, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`tokio`	`^1`	`full`	no	always
`tower`	`^0.5`	—	no	always

Build. None.

Depended on by. 1 workspace crate.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_application_classify["application-classify"] -->|uses| SELF
  SELF["application-ai"]
  SELF -->|runtime| n_application_core["application-core"]
  SELF -->|runtime| n_application_rbac["application-rbac"]
  SELF -->|runtime| n_infrastructure_ai["infrastructure-ai"]
  SELF -->|runtime| n_platform_dto["platform-dto"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
lib	`application_ai`	`src/lib.rs`
test	`pg_ai_credentials`	`tests/pg_ai_credentials.rs`

Error model

Error type	Named by
`AiCredentialsError`	`delete_system_key`, `delete_tenant_key`, `get_system_key`, `get_tenant_key`, `has_system_key_for`, `has_tenant_key`, … (12 total)

Operational characteristics

Property	Evidence
async public surface	yes
async runtime	none detected
database access	yes
network I/O	yes
unsafe code	none detected
environment variables	yes

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Variable	Read in
`CARGO_PKG_VERSION`	`src/lib.rs`

1 workspace crate depends on this one: application-classify.

Verification

Kind	Count
Unit tests	13
Integration tests	4
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Consumers
`crate root`	1	0
`api`	1	1
`api::ai_settings_admin`	1	1
`services::ai_credentials`	15	1

What the tests establish, by name:

resolve_key_prefers_tenant_over_system — tests/pg_ai_credentials.rs
set_tenant_key_upsert_currently_fails_pre_existing_bug — tests/pg_ai_credentials.rs
test_connection_dispatches_through_ai_provider_trait — tests/pg_ai_credentials.rs
writes_without_encryption_key_are_rejected_by_the_trigger — tests/pg_ai_credentials.rs
system_delete_with_only_tenant_scope_is_403 — src/api/ai_settings_admin.rs
system_list_with_only_tenant_scope_is_403 — src/api/ai_settings_admin.rs
system_list_with_system_scope_passes_the_gate — src/api/ai_settings_admin.rs
system_put_with_only_tenant_scope_is_403 — src/api/ai_settings_admin.rs
system_put_with_system_scope_passes_the_gate — src/api/ai_settings_admin.rs
tenant_delete_without_write_code_is_403 — src/api/ai_settings_admin.rs
tenant_list_with_read_code_passes_the_gate — src/api/ai_settings_admin.rs
tenant_list_without_read_code_is_403 — src/api/ai_settings_admin.rs
tenant_put_without_write_code_is_403 — src/api/ai_settings_admin.rs
tenant_test_connection_without_test_code_is_403 — src/api/ai_settings_admin.rs
test_module_migrations_non_empty — src/lib.rs
test_permission_codes_cover_both_scopes — src/lib.rs
test_system_scope_codes_are_distinct_from_tenant_scope — src/lib.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	3	25
Public modules with a `//!` block	3	4

pie showData
    title Public items with rustdoc
    "Documented" : 3
    "No rustdoc detected" : 22

Metrics

Metric	Value
Rust source files	5
Source lines	778
Code lines	574
Public API items	25
Public modules	4
Tests	17
Examples	0
Cargo features	0
Direct runtime dependencies	11
Workspace reverse dependencies	1

pie showData
    title Public API by kind
    "enum" : 1
    "function" : 14
    "method" : 7
    "struct" : 3

pie showData
    title Rust source composition
    "Code" : 574
    "Blank or comment" : 204

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

What it is for

Capabilities

AiModule

api (other)

api::ai_settings_admin (other)

services::ai_credentials (other)

AiCredentialsError

ResolvedKey

TestConnectionResult

How to use it

Module structure

Public surface

Boundary

Where it sits

Dependencies

Feature flags

Targets

Error model

Operational characteristics

Configuration

Related capabilities

Verification

Documentation coverage

Metrics

Generation

`AiModule`

`api (other)`

`api::ai_settings_admin (other)`

`services::ai_credentials (other)`

`AiCredentialsError`

`ResolvedKey`

`TestConnectionResult`