feat: preload managed JDBC driver packs

Author: openai0229

.github/workflows/ci.yml

@@ -176,6 +176,31 @@ jobs:
         run: cargo test -p chat2db-storage --locked
       - name: Test local attachment
         run: cargo test -p chat2db-local --locked
+      - name: Test Windows Java bridge path contracts
+        if: runner.os == 'Windows'
+        run: cargo test -p chat2db-java-bridge --lib --locked
+      - uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.7.1
+        if: runner.os == 'Windows'
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: maven
+          cache-dependency-path: |
+            java/pom.xml
+            java/compat-runtime/pom.xml
+      - name: Package Java engine for Windows managed-driver test
+        if: runner.os == 'Windows'
+        working-directory: java
+        shell: pwsh
+        run: .\mvnw.cmd -B -DskipTests package
+      - name: Verify Windows managed H2 driver lifecycle
+        if: runner.os == 'Windows'
+        env:
+          CHAT2DB_JAVA_ENGINE_JAR: "${{ github.workspace }}/java/compat-runtime/target/chat2db-compat-runtime-0.1.0-SNAPSHOT.jar"
+          CHAT2DB_H2_DRIVER_JAR: "${{ github.workspace }}/java/compat-runtime/target/test-drivers/h2-2.3.232.jar"
+        run: >-
+          cargo test -p chat2db-core --features java-integration
+          --test java_h2_product --locked
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: "22.22.2"

Cargo.lock

@@ -56,9 +56,10 @@ Stage 6 is complete. Web and desktop own the product runtime and publish its
 owner-only local endpoint; CLI and MCP attach to that host and never contact
 Java directly. The current MCP surface is deliberately read-only and does not
 accept JDBC bind parameters. A complete end-user Agent workspace and
-CLI-started headless host remain follow-on product work. Signed driver packs and
-the existing Chat2DB plugin/ANTLR estate remain Stage 7; driver loading is
-currently proven through the internal H2 product fixture.
+CLI-started headless host remain follow-on product work. The first Stage 7
+slice adds strict local driver-pack manifests, bounded hash verification,
+startup preload, and Core/Axum/Tauri inventory. Signing, downloading, updating,
+rollback, and the existing Chat2DB plugin/ANTLR estate remain Stage 7 work.
 
 ## Architecture
 
@@ -76,9 +77,10 @@ React / TypeScript              CLI / MCP client
   -> database
 ```
 
-See [`docs/architecture.md`](docs/architecture.md) for ownership and protocol
-decisions and [`docs/protocol.md`](docs/protocol.md) for the implemented 1.0
-process contract.
+See [`docs/architecture.md`](docs/architecture.md) for ownership,
+[`docs/protocol.md`](docs/protocol.md) for the implemented 1.0 process contract,
+and [`docs/driver-packs.md`](docs/driver-packs.md) for the local manifest and
+startup contract.
 
 ## Build
 

README.md

@@ -17,11 +17,11 @@ use chat2db_contract::{
     AgentRunSnapshot, AgentSession, AgentSessionList, AgentStreamMessage,
     AgentSubscriptionAccepted, ApiError, CancelAgentRunResponse, CancelOperationResponse,
     CreateAgentSessionRequest, CreateDatasourceRequest, CreateProviderProfileRequest, Datasource,
-    DatasourceList, DecideAgentPermissionRequest, HealthResponse, OperationEventEnvelope,
-    OperationSnapshot, OperationStreamMessage, OperationSubscriptionAccepted, ProviderProfile,
-    ProviderProfileList, QueryAccepted, ResultPage, ResultPageRequest, StartAgentRunRequest,
-    StartQueryRequest, UpdateAgentSessionRequest, UpdateDatasourceRequest,
-    UpdateProviderProfileRequest,
+    DatasourceList, DecideAgentPermissionRequest, HealthResponse, JdbcDriverList,
+    OperationEventEnvelope, OperationSnapshot, OperationStreamMessage,
+    OperationSubscriptionAccepted, ProviderProfile, ProviderProfileList, QueryAccepted, ResultPage,
+    ResultPageRequest, StartAgentRunRequest, StartQueryRequest, UpdateAgentSessionRequest,
+    UpdateDatasourceRequest, UpdateProviderProfileRequest,
 };
 use chat2db_core::{AppError, Application, RuntimeConfig, RuntimeHost};
 use chat2db_java_bridge::{EngineCommand, EngineConfig};
@@ -30,6 +30,7 @@ use tauri::{State, ipc::Channel};
 use tokio::sync::{Mutex, oneshot};
 
 const DATA_DIR_ENV: &str = "CHAT2DB_DATA_DIR";
+const DRIVER_PACK_DIR_ENV: &str = "CHAT2DB_DRIVER_PACK_DIR";
 const JAVA_BIN_ENV: &str = "CHAT2DB_JAVA_BIN";
 const JAVA_ENGINE_JAR_ENV: &str = "CHAT2DB_JAVA_ENGINE_JAR";
 const VAULT_MASTER_KEY_ENV: &str = "CHAT2DB_VAULT_MASTER_KEY";
@@ -154,6 +155,7 @@ impl DesktopState {
 #[derive(Debug)]
 pub enum DesktopError {
     MissingJavaEngineJar,
+    EmptyEnvironmentVariable(&'static str),
     InvalidJavaEngineJar(PathBuf),
     JavaEngineJarMetadata {
         path: PathBuf,
@@ -186,6 +188,9 @@ impl std::fmt::Display for DesktopError {
                 formatter,
                 "{JAVA_ENGINE_JAR_ENV} is required and must point to the compatibility-engine JAR"
             ),
+            Self::EmptyEnvironmentVariable(name) => {
+                write!(formatter, "{name} must not be empty when configured")
+            }
             Self::InvalidJavaEngineJar(path) => write!(
                 formatter,
                 "{JAVA_ENGINE_JAR_ENV} does not point to a regular file: {}",
@@ -215,6 +220,7 @@ impl std::error::Error for DesktopError {
             Self::Runtime(error) => Some(error.as_ref()),
             Self::Tauri(error) => Some(error.as_ref()),
             Self::MissingJavaEngineJar
+            | Self::EmptyEnvironmentVariable(_)
             | Self::InvalidJavaEngineJar(_)
             | Self::InvalidVaultMasterKeyEncoding => None,
         }
@@ -236,6 +242,7 @@ pub fn run() -> Result<i32, DesktopError> {
         .manage(managed_state)
         .invoke_handler(tauri::generate_handler![
             health,
+            list_drivers,
             list_datasources,
             create_datasource,
             get_datasource,
@@ -281,13 +288,16 @@ pub fn run() -> Result<i32, DesktopError> {
 
 fn runtime_config_from_environment() -> Result<RuntimeConfig, DesktopError> {
     let engine_jar = required_java_engine_jar()?;
-    let java = env::var_os(JAVA_BIN_ENV).unwrap_or_else(|| OsString::from("java"));
+    let java = optional_nonempty_os_env(JAVA_BIN_ENV)?.unwrap_or_else(|| OsString::from("java"));
     let engine = EngineConfig::new(EngineCommand::java_jar(java, engine_jar));
     let mut config = RuntimeConfig::new(engine);
 
-    if let Some(data_dir) = env::var_os(DATA_DIR_ENV).filter(|value| !value.is_empty()) {
+    if let Some(data_dir) = optional_nonempty_os_env(DATA_DIR_ENV)? {
         config = config.with_data_dir(PathBuf::from(data_dir));
     }
+    if let Some(driver_pack_dir) = optional_nonempty_os_env(DRIVER_PACK_DIR_ENV)? {
+        config = config.with_driver_pack_dir(PathBuf::from(driver_pack_dir));
+    }
     match env::var(VAULT_MASTER_KEY_ENV) {
         Ok(master_key) => config = config.with_vault_master_key_base64(master_key),
         Err(env::VarError::NotPresent) => {}
@@ -299,14 +309,27 @@ fn runtime_config_from_environment() -> Result<RuntimeConfig, DesktopError> {
 }
 
 fn required_java_engine_jar() -> Result<PathBuf, DesktopError> {
-    let path = env::var_os(JAVA_ENGINE_JAR_ENV)
-        .filter(|value| !value.is_empty())
+    let path = optional_nonempty_os_env(JAVA_ENGINE_JAR_ENV)?
         .map(PathBuf::from)
         .ok_or(DesktopError::MissingJavaEngineJar)?;
     validate_java_engine_jar(&path)?;
     Ok(path)
 }
 
+fn optional_nonempty_os_env(name: &'static str) -> Result<Option<OsString>, DesktopError> {
+    validate_optional_os_env(name, env::var_os(name))
+}
+
+fn validate_optional_os_env(
+    name: &'static str,
+    value: Option<OsString>,
+) -> Result<Option<OsString>, DesktopError> {
+    match value {
+        Some(value) if value.is_empty() => Err(DesktopError::EmptyEnvironmentVariable(name)),
+        value => Ok(value),
+    }
+}
+
 fn validate_java_engine_jar(path: &Path) -> Result<(), DesktopError> {
     match fs::metadata(path) {
         Ok(metadata) if metadata.is_file() => Ok(()),
@@ -344,6 +367,12 @@ fn health(state: State<'_, Arc<DesktopState>>) -> HealthResponse {
     state.application.health()
 }
 
+#[tauri::command]
+#[allow(clippy::needless_pass_by_value)]
+fn list_drivers(state: State<'_, Arc<DesktopState>>) -> JdbcDriverList {
+    state.application.list_drivers()
+}
+
 #[tauri::command]
 async fn list_datasources(state: State<'_, Arc<DesktopState>>) -> Result<DatasourceList, ApiError> {
     state
@@ -823,7 +852,7 @@ async fn result_page(
 
 #[cfg(test)]
 mod tests {
-    use std::{fs::File, sync::Arc};
+    use std::{ffi::OsString, fs::File, sync::Arc};
 
     use chat2db_contract::{
         AgentEvent, AgentEventEnvelope, AgentStreamMessage, OperationEvent, OperationEventEnvelope,
@@ -834,7 +863,7 @@ mod tests {
 
     use super::{
         DesktopError, SubscriptionRegistry, agent_stream_message, operation_stream_message,
-        parse_after_sequence, validate_java_engine_jar,
+        parse_after_sequence, validate_java_engine_jar, validate_optional_os_env,
     };
 
     #[test]
@@ -867,6 +896,21 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn optional_path_environment_rejects_explicit_empty_values() {
+        assert!(matches!(
+            validate_optional_os_env("CHAT2DB_DRIVER_PACK_DIR", Some(OsString::new())),
+            Err(DesktopError::EmptyEnvironmentVariable(
+                "CHAT2DB_DRIVER_PACK_DIR"
+            ))
+        ));
+        assert_eq!(
+            validate_optional_os_env("CHAT2DB_DRIVER_PACK_DIR", None)
+                .expect("missing optional variable must be accepted"),
+            None
+        );
+    }
+
     #[test]
     fn stream_result_maps_events_errors_and_clean_end() {
         let event = OperationEventEnvelope {

apps/chat2db-desktop/src/lib.rs

@@ -16,12 +16,12 @@ use chat2db_contract::{
     ContextCompactionStrategy, CreateAgentSessionRequest, CreateDatasourceRequest,
     CreateProviderProfileRequest, Datasource, DatasourceConnection, DatasourceConnectionProperty,
     DatasourceList, DatasourceSecretChange, DecideAgentPermissionRequest, HealthResponse,
-    JdbcValue, JdbcValueType, OperationEvent, OperationEventEnvelope, OperationSnapshot,
-    OperationStatus, OperationStreamMessage, OperationSubscriptionAccepted, ProductInfo,
-    ProviderCredentials, ProviderKind, ProviderProfile, ProviderProfileList, ProviderSecretChange,
-    QueryAccepted, QueryLimits, QueryParameter, ResultColumn, ResultMetadata, ResultPage,
-    ResultPageRequest, ResultRow, RuntimeStatus, SqlPermissionMode, StartAgentRunRequest,
-    StartQueryRequest, UpdateAgentSessionRequest, UpdateDatasourceRequest,
+    JdbcDriver, JdbcDriverList, JdbcValue, JdbcValueType, OperationEvent, OperationEventEnvelope,
+    OperationSnapshot, OperationStatus, OperationStreamMessage, OperationSubscriptionAccepted,
+    ProductInfo, ProviderCredentials, ProviderKind, ProviderProfile, ProviderProfileList,
+    ProviderSecretChange, QueryAccepted, QueryLimits, QueryParameter, ResultColumn, ResultMetadata,
+    ResultPage, ResultPageRequest, ResultRow, RuntimeStatus, SqlPermissionMode,
+    StartAgentRunRequest, StartQueryRequest, UpdateAgentSessionRequest, UpdateDatasourceRequest,
     UpdateProviderProfileRequest,
 };
 use chat2db_core::{AppError, Application};
@@ -46,6 +46,7 @@ const SSE_KEEP_ALIVE_SECONDS: u64 = 15;
     ),
     tags(
         (name = "system", description = "Runtime identity and readiness"),
+        (name = "drivers", description = "Hash-verified JDBC driver inventory"),
         (name = "datasources", description = "Secret-safe datasource lifecycle"),
         (name = "queries", description = "Asynchronous query submission"),
         (name = "operations", description = "Query progress, replay, and cancellation"),
@@ -93,6 +94,8 @@ const SSE_KEEP_ALIVE_SECONDS: u64 = 15;
         DatasourceSecretChange,
         DecideAgentPermissionRequest,
         HealthResponse,
+        JdbcDriver,
+        JdbcDriverList,
         JdbcValue,
         JdbcValueType,
         OperationEvent,
@@ -143,6 +146,7 @@ fn documented_router() -> OpenApiRouter<Application> {
     OpenApiRouter::<Application>::with_openapi(ApiDocument::openapi())
         .routes(routes!(health))
         .routes(routes!(info))
+        .routes(routes!(list_drivers))
         .routes(routes!(list_datasources, create_datasource))
         .routes(routes!(
             get_datasource,
@@ -216,6 +220,16 @@ async fn info(State(application): State<Application>) -> Json<ProductInfo> {
     Json(application.health().product)
 }
 
+#[utoipa::path(
+    get,
+    path = "/api/v1/drivers",
+    tag = "drivers",
+    responses((status = 200, description = "Loaded JDBC driver inventory", body = JdbcDriverList))
+)]
+async fn list_drivers(State(application): State<Application>) -> Json<JdbcDriverList> {
+    Json(application.list_drivers())
+}
+
 #[utoipa::path(
     get,
     path = "/api/v1/datasources",

apps/chat2db-web/src/api.rs

@@ -192,8 +192,8 @@ mod tests {
     use chat2db_contract::{
         AgentMessageContent, AgentMessageList, AgentRunAccepted, AgentRunSnapshot, AgentRunStatus,
         AgentSession, AgentSessionList, ApiError, ApiErrorDetails, CancelAgentRunResponse,
-        CancelDisposition, Datasource, DatasourceList, HealthResponse, ProviderProfile,
-        ProviderProfileList, RuntimeStatus,
+        CancelDisposition, Datasource, DatasourceList, HealthResponse, JdbcDriverList,
+        ProviderProfile, ProviderProfileList, RuntimeStatus,
     };
     use chat2db_core::Application;
     use chat2db_storage::{
@@ -226,6 +226,18 @@ mod tests {
         assert_eq!(health.status, RuntimeStatus::Unavailable);
     }
 
+    #[tokio::test]
+    async fn driver_inventory_route_uses_the_shared_contract() {
+        let response = router(Application::new())
+            .oneshot(request(Method::GET, "/api/v1/drivers"))
+            .await
+            .expect("router must respond");
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let inventory: JdbcDriverList = response_json(response).await;
+        assert!(inventory.items.is_empty());
+    }
+
     #[tokio::test]
     async fn unknown_routes_use_the_error_contract() {
         let response = router(Application::new())
@@ -325,6 +337,7 @@ mod tests {
 
         for path in [
             "/api/v1/system/health",
+            "/api/v1/drivers",
             "/api/v1/datasources",
             "/api/v1/datasources/{datasource_id}",
             "/api/v1/agent/providers",

apps/chat2db-web/src/lib.rs

@@ -93,6 +93,9 @@ fn runtime_config_from_env() -> Result<RuntimeConfig, Box<dyn std::error::Error>
     if let Some(data_dir) = optional_nonempty_os_env("CHAT2DB_DATA_DIR")? {
         config = config.with_data_dir(PathBuf::from(data_dir));
     }
+    if let Some(driver_pack_dir) = optional_nonempty_os_env("CHAT2DB_DRIVER_PACK_DIR")? {
+        config = config.with_driver_pack_dir(PathBuf::from(driver_pack_dir));
+    }
     if let Some(master_key) = optional_unicode_env("CHAT2DB_VAULT_MASTER_KEY")? {
         config = config.with_vault_master_key_base64(master_key);
     }

apps/chat2db-web/src/main.rs

@@ -16,6 +16,8 @@ export type DatasourceConnectionProperty = Schema<'DatasourceConnectionProperty'
 export type DatasourceList = Schema<'DatasourceList'>;
 export type DatasourceSecretChange = Schema<'DatasourceSecretChange'>;
 export type HealthResponse = Schema<'HealthResponse'>;
+export type JdbcDriver = Schema<'JdbcDriver'>;
+export type JdbcDriverList = Schema<'JdbcDriverList'>;
 export type JdbcValue = Schema<'JdbcValue'>;
 export type OperationEventEnvelope = Schema<'OperationEventEnvelope'>;
 export type OperationSnapshot = Schema<'OperationSnapshot'>;
@@ -78,6 +80,7 @@ export interface AgentSubscription {
 export interface BackendClient {
   readonly transport: 'http' | 'tauri';
   health(signal?: AbortSignal): Promise<HealthResponse>;
+  listDrivers(signal?: AbortSignal): Promise<JdbcDriverList>;
   listDatasources(signal?: AbortSignal): Promise<DatasourceList>;
   createDatasource(
     request: CreateDatasourceRequest,

apps/frontend/src/backend/client.ts

@@ -150,6 +150,28 @@ function agentEventStream(events: AgentEventEnvelope[]): Response {
 }
 
 describe('HttpBackendClient', () => {
+  it('loads the managed driver inventory from the HTTP contract', async () => {
+    const inventory = {
+      items: [{
+        packId: 'h2',
+        name: 'H2',
+        version: '2.3.232',
+        driverId: 'sha256:driver',
+        driverClass: 'org.h2.Driver',
+        artifactCount: 1,
+        artifactBytes: '2614933',
+      }],
+    };
+    const fetch = vi.fn(async () => jsonResponse(inventory, 200));
+    const client = new HttpBackendClient({ baseUrl: 'http://127.0.0.1:10825/', fetch });
+
+    await expect(client.listDrivers()).resolves.toEqual(inventory);
+    expect(fetch).toHaveBeenCalledWith(
+      'http://127.0.0.1:10825/api/v1/drivers',
+      expect.objectContaining({ method: 'GET' }),
+    );
+  });
+
   it('maps every agent catalog method to its HTTP contract without narrowing integers', async () => {
     const updatedProvider = {
       ...providerProfile,