feat(herdr): add Herdr v0.8.0 Iris bridge

Cargo.toml

@@ -9,6 +9,7 @@ members = [
     "crates/iris-cli",
     "crates/iris-mcp",
     "crates/iris-codegen",
+    "crates/iris-herdr-bridge",
 ]
 
 [workspace.package]

README.md

@@ -17,6 +17,11 @@ Point Iris at your messaging sources. Query all of them through one API — via
 - **Self-hostable**: MIT licensed, no cloud dependencies, runs anywhere Rust runs.
 - **Extensible**: Adding a provider = implementing one trait.
 
+Herdr workstation events can be bridged to Iris's existing authenticated
+`POST /ingest` contract by the separate `iris-herdr-bridge` daemon. See
+[`docs/providers/herdr-bridge.md`](docs/providers/herdr-bridge.md) for its
+protocol-19, bounded-spool, retry, and manual systemd installation contract.
+
 ## Quick Start
 
 ```bash

contrib/systemd/herdr-iris-bridge.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=Herdr to Iris durable event bridge
+After=default.target
+
+[Service]
+Type=simple
+EnvironmentFile=%h/.config/herdr-iris-bridge/env
+ExecStart=%h/.local/bin/iris-herdr-bridge
+Restart=on-failure
+RestartSec=2s
+UMask=0077
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=%h/.local/state/herdr-iris-bridge
+
+[Install]
+WantedBy=default.target

crates/iris-core/src/ingest.rs

@@ -24,8 +24,12 @@ pub enum IngestMutation {
     UpsertThread(Thread),
     /// Mark a source-backed thread archived without deleting its history.
     ArchiveThread { source: String, source_id: String },
-    /// Append a normalized message. Replays are controlled by the batch key.
-    AppendMessage(Message),
+    /// Append a normalized message. The nested field keeps the mutation tag
+    /// distinct from `Message::kind` in the JSON representation.
+    AppendMessage {
+        /// Normalized message to append to its source-backed thread.
+        message: Message,
+    },
 }
 
 /// A source cursor committed only when the complete batch commits.
@@ -128,6 +132,7 @@ fn canonicalize(value: serde_json::Value) -> serde_json::Value {
 mod tests {
     use chrono::TimeZone;
     use serde_json::json;
+    use uuid::Uuid;
 
     use super::*;
 
@@ -182,4 +187,40 @@ mod tests {
             second.canonical_hash().unwrap()
         );
     }
+
+    #[test]
+    fn append_message_mutation_round_trips_without_colliding_with_message_kind() {
+        let sender = Contact {
+            id: Uuid::from_u128(1),
+            source: "herdr".into(),
+            provider_instance: None,
+            source_id: "bridge".into(),
+            display_name: Some("Bridge".into()),
+            avatar_url: None,
+            metadata: json!({}),
+        };
+        let mutation = IngestMutation::AppendMessage {
+            message: Message {
+                id: Uuid::from_u128(2),
+                thread_id: Uuid::from_u128(3),
+                source: "herdr".into(),
+                source_id: "event-1".into(),
+                sender,
+                kind: crate::MessageKind::System,
+                body: "heartbeat".into(),
+                attachments: Vec::new(),
+                timestamp: Utc.timestamp_opt(1_700_000_000, 0).unwrap(),
+                is_outbound: false,
+                metadata: json!({}),
+            },
+        };
+
+        let value = serde_json::to_value(&mutation).unwrap();
+        assert_eq!(value["kind"], "append_message");
+        assert_eq!(value["message"]["kind"], "system");
+        assert_eq!(
+            serde_json::from_value::<IngestMutation>(value).unwrap(),
+            mutation
+        );
+    }
 }

crates/iris-herdr-bridge/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "iris-herdr-bridge"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Durable Herdr v0.8.0 event bridge into Iris ingest"
+
+[ lints ]
+workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+chrono = { workspace = true }
+iris-core = { path = "../iris-core" }
+iris-providers = { path = "../iris-providers" }
+reqwest = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+uuid = { workspace = true }
+
+[dev-dependencies]
+tempfile = "3"
+wiremock = { workspace = true }

crates/iris-herdr-bridge/src/config.rs

@@ -0,0 +1,53 @@
+use std::path::PathBuf;
+
+use anyhow::{Context as _, bail};
+
+const DEFAULT_INGEST_URL: &str = "http://100.66.233.79:9876/ingest";
+
+/// Runtime configuration loaded from the systemd environment file.
+///
+/// The token deliberately has no `Debug` implementation and is never written
+/// to the spool or logs.
+pub struct Config {
+    /// Herdr's local API Unix socket.
+    pub socket_path: PathBuf,
+    /// Existing source-agnostic Iris ingest endpoint.
+    pub ingest_url: reqwest::Url,
+    /// Bearer credential loaded from the systemd environment file.
+    pub ingest_token: String,
+    /// Private durable outbox directory.
+    pub state_dir: PathBuf,
+}
+
+impl Config {
+    /// Load and validate the runtime configuration from environment variables.
+    pub fn from_env() -> anyhow::Result<Self> {
+        let home = std::env::var_os("HOME")
+            .map(PathBuf::from)
+            .context("HOME is not set")?;
+        let socket_path = std::env::var_os("HERDR_SOCKET")
+            .map_or_else(|| home.join(".config/herdr/herdr.sock"), PathBuf::from);
+        let state_dir = std::env::var_os("HERDR_BRIDGE_STATE_DIR").map_or_else(
+            || home.join(".local/state/herdr-iris-bridge"),
+            PathBuf::from,
+        );
+        let ingest_url = reqwest::Url::parse(DEFAULT_INGEST_URL)
+            .context("the approved Iris ingest URL is invalid")?;
+        let ingest_token =
+            std::env::var("IRIS_INGEST_TOKEN").context("IRIS_INGEST_TOKEN is not set")?;
+        if ingest_token.trim().is_empty()
+            || ingest_token.trim() != ingest_token
+            || ingest_token.contains('\r')
+            || ingest_token.contains('\n')
+        {
+            bail!("IRIS_INGEST_TOKEN must be a non-empty single-line bearer token");
+        }
+
+        Ok(Self {
+            socket_path,
+            ingest_url,
+            ingest_token,
+            state_dir,
+        })
+    }
+}