refactor(handlers): add handler_err_msg trait, dedupe 12 verbatim-message sites (#968)

Adds IntoHandlerErrorMsg sibling to IntoHandlerError. Unlike .handler_err()
("Failed to {verb}: {e}"), .handler_err_msg() uses the supplied message
verbatim — for sites whose existing prefix has different capitalization,
embeds a runtime ID, or otherwise doesn't fit the fixed shape.

Migrates the 12 verbatim-message HandlerError::Internal(format!(...)) sites
in src/handlers/fingerprints/ that PR #967 explicitly left out of scope:
- ingestion_errors.rs (1 site)
- import_identity_card.rs (1 site)
- reissue_identity_card.rs (1 site)
- suggestions.rs (1 site)
- personas.rs (8 sites)

Error-message text is preserved byte-for-byte — no API contract change.

Continues the handler-error refactor from #964 / #966 / #967.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: shiba4life

src/handlers/fingerprints/import_identity_card.rs

@@ -75,7 +75,9 @@ use crate::fold_node::FoldNode;
 use crate::handlers::fingerprints::personas::{
     apply_persona_patch, PersonaDetailResponse, PersonaPatch,
 };
-use crate::handlers::response::{ApiResponse, HandlerError, HandlerResult, IntoHandlerError};
+use crate::handlers::response::{
+    ApiResponse, HandlerError, HandlerResult, IntoHandlerError, IntoHandlerErrorMsg,
+};
 
 /// Incoming card body. Shape mirrors `MyIdentityCardResponse` so a
 /// node can paste the JSON from another node's `/my-identity-card`
@@ -150,12 +152,9 @@ pub async fn import_identity_card(
                 &now,
             ));
         }
-        write_records(node.clone(), &records).await.map_err(|e| {
-            HandlerError::Internal(format!(
-                "import_identity_card: failed to persist Identity/IdentityReceipt: {}",
-                e
-            ))
-        })?;
+        write_records(node.clone(), &records)
+            .await
+            .handler_err_msg("import_identity_card: failed to persist Identity/IdentityReceipt")?;
         tracing::info!(
             "fingerprints.handler: imported Identity Card for pub_key='{}' (display_name='{}', face={})",
             req.card.pub_key,

src/handlers/fingerprints/ingestion_errors.rs

@@ -22,7 +22,9 @@
 
 use crate::fingerprints::schemas::INGESTION_ERROR;
 use crate::fold_node::FoldNode;
-use crate::handlers::response::{ApiResponse, HandlerError, HandlerResult, IntoHandlerError};
+use crate::handlers::response::{
+    ApiResponse, HandlerError, HandlerResult, IntoHandlerError, IntoHandlerErrorMsg,
+};
 use fold_db::schema::types::key_value::KeyValue;
 use fold_db::schema::types::operations::{MutationType, Query};
 use serde::{Deserialize, Serialize};
@@ -172,12 +174,7 @@ pub async fn resolve_ingestion_error(
     processor
         .execute_mutation(canonical, payload, key_value, MutationType::Update)
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!(
-                "failed to update ingestion error '{}': {}",
-                error_id, e
-            ))
-        })?;
+        .handler_err_msg(&format!("failed to update ingestion error '{}'", error_id))?;
 
     tracing::info!(
         "fingerprints.handler: ingestion error '{}' resolved={}",

src/handlers/fingerprints/personas.rs

@@ -28,6 +28,7 @@ use crate::fingerprints::schemas::{EDGE, FINGERPRINT, MENTION, MENTION_BY_FINGER
 use crate::fold_node::FoldNode;
 use crate::handlers::response::{
     require_non_empty, ApiResponse, HandlerError, HandlerResult, IntoHandlerError,
+    IntoHandlerErrorMsg,
 };
 use fold_db::schema::types::key_value::KeyValue;
 use fold_db::schema::types::operations::{MutationType, Query};
@@ -306,9 +307,7 @@ pub async fn delete_persona(
             MutationType::Delete,
         )
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!("failed to delete persona '{}': {}", persona_id, e))
-        })?;
+        .handler_err_msg(&format!("failed to delete persona '{}'", persona_id))?;
 
     tracing::info!(
         "fingerprints.handler: deleted persona '{}' (underlying fingerprints/edges/mentions untouched)",
@@ -460,9 +459,10 @@ async fn fetch_fingerprint_views(
             sort_order: None,
             value_filters: None,
         };
-        let records = processor.execute_query_json(query).await.map_err(|e| {
-            HandlerError::Internal(format!("fingerprint '{}' query failed: {}", id, e))
-        })?;
+        let records = processor
+            .execute_query_json(query)
+            .await
+            .handler_err_msg(&format!("fingerprint '{}' query failed", id))?;
         let Some(record) = records.first() else {
             tracing::warn!(
                 "fingerprints.handler: fingerprint '{}' not found during enrichment",
@@ -532,12 +532,10 @@ async fn fetch_sample_mention_for_fingerprint(
     let junction_records = processor
         .execute_query_json(junction_query)
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!(
-                "sample-mention junction query failed for '{}': {}",
-                fingerprint_id, e
-            ))
-        })?;
+        .handler_err_msg(&format!(
+            "sample-mention junction query failed for '{}'",
+            fingerprint_id
+        ))?;
 
     let Some(first) = junction_records.first() else {
         return Ok(None);
@@ -597,7 +595,7 @@ async fn fetch_edge_views(
         let records = processor
             .execute_query_json(query)
             .await
-            .map_err(|e| HandlerError::Internal(format!("edge '{}' query failed: {}", id, e)))?;
+            .handler_err_msg(&format!("edge '{}' query failed", id))?;
         let Some(record) = records.first() else {
             tracing::warn!(
                 "fingerprints.handler: edge '{}' not found during enrichment",
@@ -654,7 +652,7 @@ async fn fetch_mention_views(
         let records = processor
             .execute_query_json(query)
             .await
-            .map_err(|e| HandlerError::Internal(format!("mention '{}' query failed: {}", id, e)))?;
+            .handler_err_msg(&format!("mention '{}' query failed", id))?;
         let Some(record) = records.first() else {
             tracing::warn!(
                 "fingerprints.handler: mention '{}' not found during enrichment",
@@ -1006,9 +1004,7 @@ pub async fn apply_persona_patch(
     processor
         .execute_mutation(persona_canonical, payload, key_value, MutationType::Update)
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!("failed to update persona '{}': {}", persona_id, e))
-        })?;
+        .handler_err_msg(&format!("failed to update persona '{}'", persona_id))?;
 
     tracing::info!(
         "fingerprints.handler: applied patch to persona '{}' \
@@ -1326,12 +1322,10 @@ pub async fn merge_personas(
             MutationType::Update,
         )
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!(
-                "failed to write merged survivor persona '{}': {}",
-                survivor_id, e
-            ))
-        })?;
+        .handler_err_msg(&format!(
+            "failed to write merged survivor persona '{}'",
+            survivor_id
+        ))?;
 
     let absorbed_key = KeyValue::new(Some(absorbed_id.clone()), None);
     processor
@@ -1342,12 +1336,10 @@ pub async fn merge_personas(
             MutationType::Delete,
         )
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!(
-                "survivor merged but failed to delete absorbed persona '{}': {}",
-                absorbed_id, e
-            ))
-        })?;
+        .handler_err_msg(&format!(
+            "survivor merged but failed to delete absorbed persona '{}'",
+            absorbed_id
+        ))?;
 
     tracing::info!(
         "fingerprints.handler: merged persona '{}' into '{}'",

src/handlers/fingerprints/reissue_identity_card.rs

@@ -56,6 +56,7 @@ use crate::fold_node::FoldNode;
 use crate::handlers::fingerprints::my_identity_card::MyIdentityCardResponse;
 use crate::handlers::response::{
     require_non_empty, ApiResponse, HandlerError, HandlerResult, IntoHandlerError,
+    IntoHandlerErrorMsg,
 };
 
 /// Request body for the reissue endpoint. Both fields are optional
@@ -243,12 +244,7 @@ pub async fn reissue_identity_card(
     if request.display_name.is_some() {
         update_me_persona_name(&processor, &persona_canonical, &new_display_name)
             .await
-            .map_err(|e| {
-                HandlerError::Internal(format!(
-                    "Identity card updated but failed to sync Me persona name: {}",
-                    e
-                ))
-            })?;
+            .handler_err_msg("Identity card updated but failed to sync Me persona name")?;
     }
 
     tracing::info!(

src/handlers/fingerprints/suggestions.rs

@@ -23,7 +23,9 @@ use crate::fold_node::{FoldNode, OperationProcessor};
 use crate::handlers::fingerprints::personas::{
     get_persona, FingerprintView, PersonaDetailResponse,
 };
-use crate::handlers::response::{ApiResponse, HandlerError, HandlerResult, IntoHandlerError};
+use crate::handlers::response::{
+    ApiResponse, HandlerError, HandlerResult, IntoHandlerError, IntoHandlerErrorMsg,
+};
 use fold_db::schema::types::field::HashRangeFilter;
 use fold_db::schema::types::key_value::KeyValue;
 use fold_db::schema::types::operations::{MutationType, Query};
@@ -228,12 +230,10 @@ pub async fn accept_suggested_persona(
             MutationType::Create,
         )
         .await
-        .map_err(|e| {
-            HandlerError::Internal(format!(
-                "failed to create accepted persona '{}': {}",
-                persona_id, e
-            ))
-        })?;
+        .handler_err_msg(&format!(
+            "failed to create accepted persona '{}'",
+            persona_id
+        ))?;
 
     tracing::info!(
         "fingerprints.handler: accepted suggested persona '{}' with {} seeds",

src/handlers/mod.rs

@@ -52,5 +52,6 @@ pub mod trust;
 pub use caller::current_caller_pubkey;
 pub(crate) use response::handler_response;
 pub use response::{
-    get_db_guard, ApiResponse, HandlerError, HandlerResult, IntoHandlerError, IntoTypedHandlerError,
+    get_db_guard, ApiResponse, HandlerError, HandlerResult, IntoHandlerError, IntoHandlerErrorMsg,
+    IntoTypedHandlerError,
 };

src/handlers/response.rs

@@ -229,6 +229,25 @@ impl<T, E: fmt::Display> IntoHandlerError<T> for Result<T, E> {
     }
 }
 
+/// Like `.handler_err()` but uses the supplied message verbatim — does NOT
+/// prepend "Failed to ". Use when the existing message has different
+/// capitalization, embeds a runtime ID inside the prefix, or otherwise
+/// doesn't fit the `"Failed to {verb}: {e}"` shape produced by `handler_err`.
+///
+/// ```ignore
+/// .handler_err_msg(&format!("fingerprint '{}' query failed", id))?
+/// // → HandlerError::Internal("fingerprint '<id>' query failed: <e>")
+/// ```
+pub trait IntoHandlerErrorMsg<T> {
+    fn handler_err_msg(self, msg: &str) -> Result<T, HandlerError>;
+}
+
+impl<T, E: fmt::Display> IntoHandlerErrorMsg<T> for Result<T, E> {
+    fn handler_err_msg(self, msg: &str) -> Result<T, HandlerError> {
+        self.map_err(|e| HandlerError::Internal(format!("{}: {}", msg, e)))
+    }
+}
+
 /// Extension trait for converting FoldDbError results using the typed From conversion.
 ///
 /// Unlike `.handler_err()` which wraps every error as Internal(500), this preserves