refactor(provider): certify typed write ownership

Freeze prerequisite A as a component-level certification unit. Add the immutable v5 certification suite, split create/update row DTOs, preserve immutable creation time, map strict-create races to AppError::Conflict, make aggregate compensation insert-or-restore, and enforce reconcile preconditions through a single-lock transaction primitive.

Old save_provider callsite classification remains exhaustively recorded in 4f78451405575158ff6562c7021c7f31f2860780; this checkpoint does not add or reclassify an omitted legacy callsite. It tightens the remaining reconciliation classifications there: default live import is [create]; OpenCode/OpenClaw/Hermes existing branches are [update] and absent branches are [create]; universal Claude/Codex/Gemini branches are [create/update] selected from an observed fingerprint. The sealed compensation helper remains the only [restore] path. The old reconcile_provider_record symbol is deleted.

Remaining update_provider_settings_config callsites are classified as [update]: codex_history_migration updates an already-read Codex row; proxy token synchronization updates already-read Claude, Codex, Gemini, and GrokBuild rows. Each now uses ProviderKey plus ProviderRowUpdate, explicitly removes hydrated endpoint projections, preserves endpoint authority, and fails on a missing row instead of silently succeeding.

src-tauri/src/database/dao/mod.rs

@@ -8,6 +8,8 @@ pub mod pi_projections;
 pub mod profiles;
 pub mod prompts;
 pub mod provider_write;
+#[cfg(test)]
+mod provider_write_certification;
 pub mod providers;
 pub mod providers_seed;
 pub mod proxy;

src-tauri/src/database/dao/provider_write.rs

@@ -6,6 +6,8 @@ use rusqlite::{params, OptionalExtension, Transaction};
 use serde_json::Value;
 use std::collections::HashSet;
 
+use super::providers::{StoredProviderRow, PROVIDER_SELECT};
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderKey {
     app_type: String,
@@ -39,7 +41,6 @@ pub struct ProviderRowUpdate {
     settings_config: Value,
     website_url: Option<String>,
     category: Option<String>,
-    created_at: Option<i64>,
     notes: Option<String>,
     meta: ProviderMeta,
     icon: Option<String>,
@@ -60,7 +61,6 @@ impl ProviderRowUpdate {
             settings_config: input.settings_config.clone(),
             website_url: input.website_url.clone(),
             category: input.category.clone(),
-            created_at: input.created_at,
             notes: input.notes.clone(),
             meta,
             icon: input.icon.clone(),
@@ -69,6 +69,12 @@ impl ProviderRowUpdate {
     }
 }
 
+#[derive(Debug, Clone)]
+pub struct ProviderRowCreate {
+    content: ProviderRowUpdate,
+    created_at: Option<i64>,
+}
+
 #[derive(Debug, Clone)]
 pub struct NewEndpoint {
     url: String,
@@ -111,7 +117,7 @@ impl TryFrom<CustomEndpoint> for NewEndpoint {
 #[derive(Debug, Clone)]
 pub struct NewProviderAggregate {
     key: ProviderKey,
-    row: ProviderRowUpdate,
+    row: ProviderRowCreate,
     sort_index: Option<usize>,
     in_failover_queue: bool,
     initial_endpoints: Vec<NewEndpoint>,
@@ -142,7 +148,10 @@ impl NewProviderAggregate {
             initial_endpoints.push(endpoint.try_into()?);
         }
         let key = ProviderKey::new(app_type, input.id.clone())?;
-        let row = ProviderRowUpdate::from_input(&input)?;
+        let row = ProviderRowCreate {
+            content: ProviderRowUpdate::from_input(&input)?,
+            created_at: input.created_at,
+        };
         Ok(Self {
             key,
             row,
@@ -203,6 +212,7 @@ fn insert_row(
     tx: &Transaction<'_>,
     key: &ProviderKey,
     row: &ProviderRowUpdate,
+    created_at: Option<i64>,
     sort_index: Option<usize>,
     is_current: bool,
     in_failover_queue: bool,
@@ -223,7 +233,7 @@ fn insert_row(
             settings_config,
             row.website_url,
             row.category,
-            row.created_at,
+            created_at,
             sort_index,
             row.notes,
             row.icon,
@@ -233,7 +243,21 @@ fn insert_row(
             in_failover_queue,
         ],
     )
-    .map_err(|error| AppError::Database(error.to_string()))?;
+    .map_err(|error| match &error {
+        rusqlite::Error::SqliteFailure(code, _)
+            if matches!(
+                code.extended_code,
+                rusqlite::ffi::SQLITE_CONSTRAINT_PRIMARYKEY
+                    | rusqlite::ffi::SQLITE_CONSTRAINT_UNIQUE
+            ) =>
+        {
+            AppError::Conflict(format!(
+                "provider '{}/{}' already exists",
+                key.app_type, key.id
+            ))
+        }
+        _ => AppError::Database(error.to_string()),
+    })?;
     Ok(())
 }
 
@@ -262,21 +286,38 @@ fn insert_endpoint(
 /// catalog compensation coordinator introduced with the ordered mutation
 /// pipeline is the only intended caller.
 #[allow(dead_code)]
+// The certification contract keeps immutable creation time separate from the
+// mutable row DTO and calls this sealed helper directly with the full snapshot.
+#[allow(clippy::too_many_arguments)]
 pub(super) fn restore_provider_aggregate_on_tx(
     tx: &Transaction<'_>,
     key: &ProviderKey,
     row: &ProviderRowUpdate,
+    created_at: Option<i64>,
     sort_index: Option<usize>,
     is_current: bool,
     in_failover_queue: bool,
     endpoints: &[NewEndpoint],
 ) -> Result<(), AppError> {
     let updated = update_row(tx, key, row)?;
-    if updated != 1 {
-        return Err(AppError::NotFound(format!(
-            "provider '{}/{}'",
-            key.app_type, key.id
-        )));
+    if updated == 0 {
+        insert_row(
+            tx,
+            key,
+            row,
+            created_at,
+            sort_index,
+            is_current,
+            in_failover_queue,
+        )?;
+    } else {
+        // Exact compensation is the only path allowed to restore immutable
+        // creation time after a prior aggregate mutation.
+        tx.execute(
+            "UPDATE providers SET created_at = ?1 WHERE id = ?2 AND app_type = ?3",
+            params![created_at, key.id, key.app_type],
+        )
+        .map_err(|error| AppError::Database(error.to_string()))?;
     }
     tx.execute(
         "DELETE FROM provider_endpoints WHERE provider_id = ?1 AND app_type = ?2",
@@ -317,18 +358,16 @@ fn update_row(
             settings_config = ?2,
             website_url = ?3,
             category = ?4,
-            created_at = ?5,
-            notes = ?6,
-            icon = ?7,
-            icon_color = ?8,
-            meta = ?9
-          WHERE id = ?10 AND app_type = ?11",
+            notes = ?5,
+            icon = ?6,
+            icon_color = ?7,
+            meta = ?8
+          WHERE id = ?9 AND app_type = ?10",
         params![
             row.name,
             settings_config,
             row.website_url,
             row.category,
-            row.created_at,
             row.notes,
             row.icon,
             row.icon_color,
@@ -349,7 +388,8 @@ impl Database {
         insert_row(
             &tx,
             &input.key,
-            &input.row,
+            &input.row.content,
+            input.row.created_at,
             input.sort_index,
             false,
             input.in_failover_queue,
@@ -380,6 +420,42 @@ impl Database {
             .map_err(|error| AppError::Database(error.to_string()))
     }
 
+    pub(crate) fn update_provider_if_content_fingerprint(
+        &self,
+        key: &ProviderKey,
+        expected_fingerprint: &str,
+        row: &ProviderRowUpdate,
+    ) -> Result<(), AppError> {
+        let mut conn = lock_conn!(self.conn);
+        let tx = conn
+            .transaction()
+            .map_err(|error| AppError::Database(error.to_string()))?;
+        let current = tx
+            .query_row(
+                &format!("{PROVIDER_SELECT} WHERE id = ?1 AND app_type = ?2"),
+                params![key.id, key.app_type],
+                StoredProviderRow::from_row,
+            )
+            .optional()
+            .map_err(|error| AppError::Database(error.to_string()))?
+            .ok_or_else(|| AppError::NotFound(format!("provider '{}/{}'", key.app_type, key.id)))?
+            .decode(key.app_type())?;
+        if current.row_content_fingerprint() != expected_fingerprint {
+            return Err(AppError::Conflict(format!(
+                "provider '{}/{}' changed since it was read",
+                key.app_type, key.id
+            )));
+        }
+        if update_row(&tx, key, row)? != 1 {
+            return Err(AppError::NotFound(format!(
+                "provider '{}/{}'",
+                key.app_type, key.id
+            )));
+        }
+        tx.commit()
+            .map_err(|error| AppError::Database(error.to_string()))
+    }
+
     pub fn rename_db_only_additive_provider(&self, input: RenameProvider) -> Result<(), AppError> {
         let mut conn = lock_conn!(self.conn);
         let tx = conn
@@ -387,7 +463,7 @@ impl Database {
             .map_err(|error| AppError::Database(error.to_string()))?;
         let source_state = tx
             .query_row(
-                "SELECT sort_index, is_current, in_failover_queue, category
+                "SELECT sort_index, is_current, in_failover_queue, category, created_at
                    FROM providers
                   WHERE id = ?1 AND app_type = ?2",
                 params![input.source.id, input.source.app_type],
@@ -397,6 +473,7 @@ impl Database {
                         row.get::<_, bool>(1)?,
                         row.get::<_, bool>(2)?,
                         row.get::<_, Option<String>>(3)?,
+                        row.get::<_, Option<i64>>(4)?,
                     ))
                 },
             )
@@ -418,6 +495,7 @@ impl Database {
             &tx,
             &target,
             &input.row,
+            source_state.4,
             source_state.0,
             source_state.1,
             source_state.2,

src-tauri/src/database/dao/providers.rs

@@ -6,7 +6,7 @@ use indexmap::IndexMap;
 use rusqlite::{params, OptionalExtension, Row};
 use std::collections::{HashMap, HashSet};
 
-struct StoredProviderRow {
+pub(super) struct StoredProviderRow {
     id: String,
     name: String,
     settings_config: String,
@@ -22,7 +22,7 @@ struct StoredProviderRow {
 }
 
 impl StoredProviderRow {
-    fn from_row(row: &Row<'_>) -> rusqlite::Result<Self> {
+    pub(super) fn from_row(row: &Row<'_>) -> rusqlite::Result<Self> {
         Ok(Self {
             id: row.get(0)?,
             name: row.get(1)?,
@@ -39,7 +39,7 @@ impl StoredProviderRow {
         })
     }
 
-    fn decode(self, app_type: &str) -> Result<Provider, AppError> {
+    pub(super) fn decode(self, app_type: &str) -> Result<Provider, AppError> {
         let (settings_config, mut meta) =
             decode_provider_json(app_type, &self.id, &self.settings_config, &self.meta)?;
         // Child rows are the sole endpoint authority. Do not expose a stale
@@ -96,7 +96,7 @@ pub(crate) fn validate_provider_storage_json(
     decode_provider_json(app_type, provider_id, settings_config, meta).map(|_| ())
 }
 
-const PROVIDER_SELECT: &str =
+pub(super) const PROVIDER_SELECT: &str =
     "SELECT id, name, settings_config, website_url, category, created_at, sort_index,
             notes, icon, icon_color, meta, in_failover_queue
      FROM providers";
@@ -306,27 +306,6 @@ impl Database {
         Ok(())
     }
 
-    pub fn update_provider_settings_config(
-        &self,
-        app_type: &str,
-        provider_id: &str,
-        settings_config: &serde_json::Value,
-    ) -> Result<(), AppError> {
-        let conn = lock_conn!(self.conn);
-        conn.execute(
-            "UPDATE providers SET settings_config = ?1 WHERE id = ?2 AND app_type = ?3",
-            params![
-                serde_json::to_string(settings_config).map_err(|e| AppError::Database(format!(
-                    "Failed to serialize settings_config: {e}"
-                )))?,
-                provider_id,
-                app_type
-            ],
-        )
-        .map_err(|e| AppError::Database(e.to_string()))?;
-        Ok(())
-    }
-
     pub fn set_omo_provider_current(
         &self,
         app_type: &str,
@@ -1034,6 +1013,7 @@ mod aggregate_tests {
                 &tx,
                 &key,
                 &row,
+                snapshot.provider.created_at,
                 snapshot.provider.sort_index,
                 false,
                 snapshot.provider.in_failover_queue,

src-tauri/src/database/tests.rs

@@ -1,3 +1,5 @@
+#![cfg(test)]
+
 //! 数据库模块测试
 //!
 //! 包含 Schema 迁移和基本功能的测试。