chore(infra): add gRPC layer, update protobufs, remove immediate module

- Add gRPC service modules: auth, channel, channel settings, member,
  permission
- Update protobuf definitions and generated code
- Remove immediate/ real-time module (superseded by IM service)
- Update etcd discovery and registration
- Update cache, error, config, and build infrastructure
- Add ADR documentation
- Update OpenAPI spec

etcd/mod.rs

@@ -2,7 +2,7 @@ mod discovery;
 mod register;
 mod types;
 
-pub use types::ServiceInstance;
+pub use types::{GitksPeerInfo, ServiceInstance};
 
 use std::sync::Arc;
 use std::sync::atomic::AtomicI64;
@@ -19,6 +19,7 @@ use crate::pb::{EmailClient, RepoClient};
 #[derive(Clone)]
 pub struct EtcdRegistry {
     pub(crate) inner: Arc<EtcdRegistryInner>,
+    email_client: Option<EmailClient>,
 }
 
 pub(crate) struct EtcdRegistryInner {
@@ -38,7 +39,7 @@ impl EtcdRegistry {
         let opts = etcd_client::ConnectOptions::new()
             .with_connect_timeout(std::time::Duration::from_secs(timeout));
 
-        let client = Client::connect(&endpoints, Some(opts))
+        let client = Client::connect(endpoints, Some(opts))
             .await
             .map_err(|e| AppError::Config(format!("etcd connect failed: {e}")))?;
 
@@ -54,6 +55,25 @@ impl EtcdRegistry {
 
         let key_prefix = config.etcd_key_prefix()?;
 
+        let email_client = match config.email_rpc_addr()? {
+            Some(addr) if !addr.is_empty() => match EmailClient::lazy_connect(&addr) {
+                Ok(client) => {
+                    tracing::info!(addr = %addr, "email client connected via APP_EMAIL_RPC_ADDR");
+                    Some(client)
+                }
+                Err(e) => {
+                    tracing::error!(addr = %addr, error = %e, "email client connect via APP_EMAIL_RPC_ADDR failed");
+                    None
+                }
+            },
+            _ => {
+                tracing::info!(
+                    "APP_EMAIL_RPC_ADDR not set, will fall back to etcd discovery for email"
+                );
+                None
+            }
+        };
+
         Ok(Self {
             inner: Arc::new(EtcdRegistryInner {
                 client: Mutex::new(client),
@@ -63,6 +83,7 @@ impl EtcdRegistry {
                 mail_nodes: DashMap::new(),
                 lease_id: AtomicI64::new(0),
             }),
+            email_client,
         })
     }
 
@@ -75,6 +96,9 @@ impl EtcdRegistry {
     }
 
     pub fn get_email_client(&self) -> Option<EmailClient> {
+        if let Some(ref client) = self.email_client {
+            return Some(client.clone());
+        }
         self.inner
             .mail_nodes
             .iter()
@@ -85,4 +109,18 @@ impl EtcdRegistry {
     pub fn has_git_nodes(&self) -> bool {
         !self.inner.git_nodes.is_empty()
     }
+
+    /// Sort available gitks node UUIDs for deterministic selection.
+    pub fn git_node_ids_sorted(&self) -> Vec<Uuid> {
+        let mut ids: Vec<Uuid> = self.git_node_ids();
+        ids.sort();
+        ids
+    }
+}
+
+/// Derive a deterministic UUID from a gitks storage_name.
+/// Uses UUID v5 with DNS namespace so the same storage_name always
+/// maps to the same UUID across all appks instances.
+pub fn storage_name_to_uuid(storage_name: &str) -> Uuid {
+    Uuid::new_v5(&Uuid::NAMESPACE_DNS, storage_name.as_bytes())
 }