feat(echidnabot): submitProofObligation + session persistence + port 9001

Closes B1/B3a/H2a session work:

src/api/graphql.rs:
- submit_proof_obligation mutation: ProofObligationInput { repo, claim,
  context, prover: Option<ProverKind> } → ProofObligationResult
- Persists ProofObligationRecord FIRST (source of truth for claim/context),
  then creates ProofJob with opaque obligation reference, back-fills job_id

src/fleet/mod.rs: fixed B1 session-persistence TODO — saves ctx via
ContextStorage::default().save_context() with warn-level logging on failure

src/store/{mod,models,sqlite}.rs: proof_obligations table DDL + ObligationRow
helpers + create_obligation/get_obligation/link_obligation_to_job trait methods

src/config.rs + src/main.rs: default port 8080 → 9001 (resolves collision
with verisimdb + gitbot-fleet)

tests/webhook_e2e_test.rs (new, 8 tests): real axum-test TestServer, real
HMAC, in-memory SQLite, wiremock stubs for echidna + GitHub

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

bots/echidnabot/Cargo.lock

@@ -82,6 +82,7 @@ axum-test = "18"
 mockall = "0.14"
 tempfile = "3"
 wiremock = "0.6"
+bytes = "1"
 
 [profile.release]
 lto = true

bots/echidnabot/Cargo.toml

@@ -14,7 +14,7 @@ use crate::dispatcher::{
 };
 use crate::dispatcher::echidna_client::ProverStatus as CoreProverStatus;
 use crate::scheduler::{JobPriority, JobScheduler};
-use crate::store::models::{ProofJobRecord, Repository as StoreRepository};
+use crate::store::models::{ProofJobRecord, ProofObligationRecord, Repository as StoreRepository};
 use crate::store::Store;
 
 /// GraphQL schema type
@@ -277,6 +277,30 @@ pub struct RegisterRepoInput {
     pub enabled_provers: Option<Vec<ProverKind>>,
 }
 
+/// Input for submitting a proof obligation from an external scanner (e.g. hypatia)
+#[derive(async_graphql::InputObject)]
+pub struct ProofObligationInput {
+    /// Repository in "owner/name" format
+    pub repo: String,
+    /// Human-readable claim that must be proved
+    pub claim: String,
+    /// Original context/description from pattern detection
+    pub context: String,
+    /// Optional prover hint. When supplied (e.g. by hypatia's proof-strategy
+    /// rule picking the historically-best prover for this obligation class),
+    /// it overrides the default. Omitted → default Lean.
+    pub prover: Option<ProverKind>,
+}
+
+/// Result of submitting a proof obligation
+#[derive(SimpleObject, Clone)]
+pub struct ProofObligationResult {
+    /// Whether the obligation was successfully recorded
+    pub success: bool,
+    /// Scheduler job ID assigned to this obligation (UUID string), or empty on failure
+    pub proof_id: String,
+}
+
 /// Input for repository settings
 #[derive(async_graphql::InputObject)]
 pub struct RepoSettingsInput {
@@ -371,6 +395,114 @@ impl MutationRoot {
         Ok(ProofJobRecord::from(job).into())
     }
 
+    /// Record a proof obligation submitted by an external tool (e.g. hypatia fleet_dispatcher).
+    ///
+    /// This mutation RECORDS the obligation as a pending scheduler job — it does NOT immediately
+    /// invoke a prover. The scheduler will pick it up on its normal cycle. The repo must already
+    /// be registered with echidnabot; if it is not, this returns `success: false`.
+    ///
+    /// The `repo` argument must be in "owner/name" format. The mutation searches all platforms
+    /// for a matching registered repository and uses the first match found.
+    async fn submit_proof_obligation(
+        &self,
+        ctx: &Context<'_>,
+        input: ProofObligationInput,
+    ) -> async_graphql::Result<ProofObligationResult> {
+        let state = ctx.data::<GraphQLState>()?;
+
+        // Parse "owner/name" format
+        let (owner, name) = {
+            let parts: Vec<&str> = input.repo.splitn(2, '/').collect();
+            if parts.len() != 2 || parts[0].is_empty() || parts[1].is_empty() {
+                return Ok(ProofObligationResult {
+                    success: false,
+                    proof_id: String::new(),
+                });
+            }
+            (parts[0].to_string(), parts[1].to_string())
+        };
+
+        // Find a matching registered repository across all platforms
+        let repos = state
+            .store
+            .list_repositories(None)
+            .await
+            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+
+        let repo = repos
+            .into_iter()
+            .find(|r| r.owner == owner && r.name == name);
+
+        let repo = match repo {
+            Some(r) => r,
+            None => {
+                return Ok(ProofObligationResult {
+                    success: false,
+                    proof_id: String::new(),
+                });
+            }
+        };
+
+        let chosen_prover = input
+            .prover
+            .map(map_prover_kind_to_core)
+            .unwrap_or(CoreProverKind::Lean);
+
+        // Derive a human-readable hint string from the chosen prover so that
+        // the obligation row is self-contained (e.g. a future query can show
+        // "which prover was requested" without joining proof_jobs).
+        let prover_hint = Some(format!("{:?}", chosen_prover).to_lowercase());
+
+        // 1. Persist the obligation FIRST — it is the source of truth for claim/context.
+        let obligation = ProofObligationRecord::new(
+            repo.id,
+            input.claim,
+            input.context,
+            prover_hint,
+        );
+        state
+            .store
+            .create_obligation(&obligation)
+            .await
+            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+
+        // 2. Create a scheduler job whose file_paths carry an opaque reference to the
+        //    obligation row.  Nothing in file_paths encodes claim/context strings.
+        let job = crate::scheduler::ProofJob::new(
+            repo.id,
+            "manual-obligation".to_string(),
+            chosen_prover,
+            vec![format!("obligation:{}", obligation.id)],
+        )
+        .with_priority(JobPriority::Normal);
+
+        // 3. Persist job record, then enqueue.
+        let record = ProofJobRecord::from(job.clone());
+        state
+            .store
+            .create_job(&record)
+            .await
+            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+
+        let _ = state
+            .scheduler
+            .enqueue(job.clone())
+            .await
+            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+
+        // 4. Back-fill the job ID onto the obligation row so it can be followed.
+        state
+            .store
+            .link_obligation_to_job(&obligation.id.to_string(), &job.id.0.to_string())
+            .await
+            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+
+        Ok(ProofObligationResult {
+            success: true,
+            proof_id: job.id.0.to_string(),
+        })
+    }
+
     /// Request ML-powered tactic suggestions
     async fn request_suggestions(
         &self,

bots/echidnabot/src/api/graphql.rs

@@ -71,7 +71,10 @@ fn default_host() -> String {
 }
 
 fn default_port() -> u16 {
-    8080
+    // 9001 is echidnabot's canonical port in the hyperpolymath port map.
+    // (9000 = echidna core, 9001 = echidnabot, 9090 = hypatia.)
+    // Was 8080 which collided with verisimdb and gitbot-fleet.
+    9001
 }
 
 #[derive(Debug, Deserialize, Clone)]

bots/echidnabot/src/config.rs

@@ -11,9 +11,9 @@
 
 use crate::error::{Error, Result};
 use crate::scheduler::{JobResult, ProofJob};
-use gitbot_shared_context::{BotId, Context, Finding, Severity};
+use gitbot_shared_context::{BotId, Context, ContextStorage, Finding, Severity};
 use std::path::PathBuf;
-use tracing::{debug, info};
+use tracing::{debug, info, warn};
 
 /// Fleet coordinator for echidnabot
 pub struct FleetCoordinator {
@@ -53,7 +53,19 @@ impl FleetCoordinator {
             ctx.complete_bot(BotId::Echidnabot, findings_count, errors_count, files_analyzed)
                 .map_err(|e| Error::Internal(format!("Failed to complete bot: {}", e)))?;
 
-            // TODO: Persist context to ~/.gitbot-fleet/sessions/
+            // Persist context to ~/.gitbot-fleet/sessions/<session_id>.json so the
+            // fleet-coordinator and other bots can pick up echidnabot findings after
+            // this bot's process has exited. Persistence failure is logged but does
+            // NOT fail disconnect — losing a session log is less bad than crashing
+            // a running bot. Callers that need strict durability should call the
+            // persistence API directly.
+            match ContextStorage::default() {
+                Ok(storage) => match storage.save_context(ctx) {
+                    Ok(path) => info!(path = %path.display(), "Persisted session context"),
+                    Err(e) => warn!("Failed to persist session context: {}", e),
+                },
+                Err(e) => warn!("Failed to open session storage: {}", e),
+            }
         }
 
         self.context = None;

bots/echidnabot/src/fleet/mod.rs

@@ -47,8 +47,8 @@ enum Commands {
         #[arg(short = 'H', long, default_value = "0.0.0.0")]
         host: String,
 
-        /// Port to bind to
-        #[arg(short, long, default_value = "8080")]
+        /// Port to bind to (canonical: 9001)
+        #[arg(short, long, default_value = "9001")]
         port: u16,
     },
 

bots/echidnabot/src/main.rs

@@ -13,7 +13,7 @@ use uuid::Uuid;
 use crate::adapters::Platform;
 use crate::error::Result;
 use crate::scheduler::JobId;
-use models::{Repository, ProofJobRecord, ProofResultRecord};
+use models::{Repository, ProofJobRecord, ProofObligationRecord, ProofResultRecord};
 
 /// Abstract store trait for different database backends
 #[async_trait]
@@ -42,6 +42,11 @@ pub trait Store: Send + Sync {
     async fn save_result(&self, result: &ProofResultRecord) -> Result<()>;
     async fn get_result_for_job(&self, job_id: JobId) -> Result<Option<ProofResultRecord>>;
 
+    // Proof obligation operations
+    async fn create_obligation(&self, obligation: &ProofObligationRecord) -> Result<()>;
+    async fn get_obligation(&self, obligation_id: &str) -> Result<Option<ProofObligationRecord>>;
+    async fn link_obligation_to_job(&self, obligation_id: &str, job_id: &str) -> Result<()>;
+
     // Utility
     async fn health_check(&self) -> Result<bool>;
 }

bots/echidnabot/src/store/mod.rs

@@ -117,6 +117,55 @@ impl ProofResultRecord {
     }
 }
 
+/// Proof obligation record — the canonical source of truth for claim/context/prover_hint.
+///
+/// Created before the scheduler job so the obligation is persisted even if job creation
+/// fails.  Once a job is created, `proof_job_id` is back-filled via
+/// [`Store::link_obligation_to_job`].
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProofObligationRecord {
+    /// UUID v4 assigned at creation time
+    pub id: Uuid,
+    /// FK to `repositories.id`
+    pub repo_id: Uuid,
+    /// Human-readable claim that must be proved (from hypatia / external scanner)
+    pub claim: String,
+    /// Original context/description from pattern detection
+    pub context: String,
+    /// Optional prover hint supplied by the caller (e.g. "lean", "coq")
+    pub prover_hint: Option<String>,
+    /// Lifecycle status: `pending` → `processing` → `completed` | `failed`
+    pub status: String,
+    /// Scheduler job UUID, populated by [`Store::link_obligation_to_job`]
+    pub proof_job_id: Option<String>,
+    /// Timestamp when this obligation was first recorded
+    pub created_at: DateTime<Utc>,
+    /// Timestamp when a final terminal status was reached (completed / failed)
+    pub completed_at: Option<DateTime<Utc>>,
+}
+
+impl ProofObligationRecord {
+    /// Construct a new pending obligation.
+    pub fn new(
+        repo_id: Uuid,
+        claim: String,
+        context: String,
+        prover_hint: Option<String>,
+    ) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            repo_id,
+            claim,
+            context,
+            prover_hint,
+            status: "pending".to_string(),
+            proof_job_id: None,
+            created_at: Utc::now(),
+            completed_at: None,
+        }
+    }
+}
+
 /// Check run record (for tracking GitHub/GitLab status updates)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CheckRunRecord {