feat(service): create flowctl-service crate scaffold with ServiceError and connection management

- New flowctl-service crate added as 7th workspace member
- ServiceError enum with 9 variants: TaskNotFound, EpicNotFound, InvalidTransition, DependencyUnsatisfied, CrossActorViolation, DbError, IoError, ValidationError, CoreError
- From<DbError> and From<CoreError> impls via thiserror derive
- ConnectionProvider trait for sync/async connection abstraction
- FileConnectionProvider wraps flowctl_db::open() for file-backed DBs
- open_sync() convenience function for CLI callers
- Tests for file-backed, in-memory, and sync connection paths

Task: fn-10-dag-delight.1

Author: z23cc

flowctl/Cargo.lock

@@ -4,6 +4,7 @@ members = [
     "crates/flowctl-core",
     "crates/flowctl-db",
     "crates/flowctl-scheduler",
+    "crates/flowctl-service",
     "crates/flowctl-cli",
     "crates/flowctl-daemon",
     "crates/flowctl-web",
@@ -75,6 +76,7 @@ trycmd = "0.15"
 flowctl-core = { path = "crates/flowctl-core" }
 flowctl-db = { path = "crates/flowctl-db" }
 flowctl-scheduler = { path = "crates/flowctl-scheduler" }
+flowctl-service = { path = "crates/flowctl-service" }
 
 # ── Release profile (size-optimized) ─────────────────────────────────
 [profile.release]

flowctl/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "flowctl-service"
+version = "0.1.0"
+description = "Business logic service layer for flowctl — unifies CLI, daemon, and MCP execution paths"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[dependencies]
+flowctl-core = { workspace = true }
+flowctl-db = { workspace = true }
+rusqlite = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+
+[dev-dependencies]
+tempfile = "3"

flowctl/crates/flowctl-service/Cargo.toml

@@ -0,0 +1,97 @@
+//! Connection management for the service layer.
+//!
+//! Wraps `flowctl_db::open()` behind a trait so that:
+//! - Sync callers (CLI) use it directly
+//! - Async callers (daemon) use `spawn_blocking` to avoid blocking the runtime
+//!
+//! The `ConnectionProvider` trait enables testing with in-memory databases.
+
+use std::path::{Path, PathBuf};
+
+use rusqlite::Connection;
+
+use crate::error::{ServiceError, ServiceResult};
+
+/// Trait for obtaining a database connection.
+///
+/// The default implementation opens a file-backed SQLite database via
+/// `flowctl_db::open()`. Tests can provide an in-memory alternative.
+pub trait ConnectionProvider: Send + Sync {
+    /// Open a new database connection.
+    ///
+    /// Each call returns a fresh `Connection`. rusqlite `Connection` is
+    /// `!Send`, so callers in async contexts must use `spawn_blocking`.
+    fn connect(&self) -> ServiceResult<Connection>;
+}
+
+/// File-backed connection provider using a working directory.
+///
+/// Resolves the database path via `flowctl_db::pool::resolve_db_path()`
+/// and opens with production PRAGMAs + migrations.
+#[derive(Debug, Clone)]
+pub struct FileConnectionProvider {
+    working_dir: PathBuf,
+}
+
+impl FileConnectionProvider {
+    /// Create a provider rooted at the given working directory.
+    pub fn new(working_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            working_dir: working_dir.into(),
+        }
+    }
+
+    /// Return the working directory this provider is rooted at.
+    pub fn working_dir(&self) -> &Path {
+        &self.working_dir
+    }
+}
+
+impl ConnectionProvider for FileConnectionProvider {
+    fn connect(&self) -> ServiceResult<Connection> {
+        flowctl_db::open(&self.working_dir).map_err(ServiceError::from)
+    }
+}
+
+/// Open a connection synchronously (convenience for CLI callers).
+pub fn open_sync(working_dir: &Path) -> ServiceResult<Connection> {
+    flowctl_db::open(working_dir).map_err(ServiceError::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// In-memory connection provider for tests.
+    pub struct MemoryConnectionProvider;
+
+    impl ConnectionProvider for MemoryConnectionProvider {
+        fn connect(&self) -> ServiceResult<Connection> {
+            let conn = Connection::open_in_memory()
+                .map_err(|e| ServiceError::DbError(flowctl_db::DbError::Sqlite(e)))?;
+            Ok(conn)
+        }
+    }
+
+    #[test]
+    fn file_provider_roundtrip() {
+        let tmp = tempfile::tempdir().unwrap();
+        let provider = FileConnectionProvider::new(tmp.path());
+        let conn = provider.connect();
+        assert!(conn.is_ok(), "should open file-backed connection");
+    }
+
+    #[test]
+    fn memory_provider_works() {
+        let provider = MemoryConnectionProvider;
+        let conn = provider.connect();
+        assert!(conn.is_ok(), "should open in-memory connection");
+    }
+
+    #[test]
+    fn open_sync_works() {
+        let tmp = tempfile::tempdir().unwrap();
+        let conn = open_sync(tmp.path());
+        assert!(conn.is_ok(), "open_sync should succeed");
+    }
+}

flowctl/crates/flowctl-service/src/connection.rs

@@ -0,0 +1,50 @@
+//! Service-layer error types.
+//!
+//! `ServiceError` is the canonical error type for all business logic
+//! operations. It wraps lower-level errors from `flowctl-core` and
+//! `flowctl-db` and adds service-specific variants.
+
+use thiserror::Error;
+
+/// Top-level error type for service operations.
+#[derive(Debug, Error)]
+pub enum ServiceError {
+    /// Task not found in the database.
+    #[error("task not found: {0}")]
+    TaskNotFound(String),
+
+    /// Epic not found in the database.
+    #[error("epic not found: {0}")]
+    EpicNotFound(String),
+
+    /// Invalid state transition (e.g., done → in_progress without restart).
+    #[error("invalid transition: {0}")]
+    InvalidTransition(String),
+
+    /// A dependency is not satisfied (blocking task not done/skipped).
+    #[error("dependency unsatisfied: task {task} blocked by {dependency}")]
+    DependencyUnsatisfied { task: String, dependency: String },
+
+    /// Cross-actor violation (e.g., modifying another agent's locked task).
+    #[error("cross-actor violation: {0}")]
+    CrossActorViolation(String),
+
+    /// Underlying database error.
+    #[error("database error: {0}")]
+    DbError(#[from] flowctl_db::DbError),
+
+    /// I/O error (file reads, state directory operations).
+    #[error("io error: {0}")]
+    IoError(#[from] std::io::Error),
+
+    /// Validation error (bad input, missing fields, constraint checks).
+    #[error("validation error: {0}")]
+    ValidationError(String),
+
+    /// Core-layer error (ID parsing, DAG operations).
+    #[error("core error: {0}")]
+    CoreError(#[from] flowctl_core::CoreError),
+}
+
+/// Convenience alias used throughout the service layer.
+pub type ServiceResult<T> = Result<T, ServiceError>;

flowctl/crates/flowctl-service/src/error.rs

@@ -0,0 +1,28 @@
+//! flowctl-service: Business logic service layer for flowctl.
+//!
+//! This crate provides the canonical business logic that is shared across
+//! all three execution paths (CLI, daemon, MCP). It sits between the
+//! transport layer (HTTP handlers, CLI commands, MCP protocol) and the
+//! storage layer (flowctl-db).
+//!
+//! # Architecture
+//!
+//! ```text
+//!   CLI commands ─┐
+//!   HTTP handlers ─┼─► flowctl-service ──► flowctl-db ──► SQLite
+//!   MCP server ───┘         │
+//!                    flowctl-core (types, DAG, state machine)
+//! ```
+//!
+//! # Connection management
+//!
+//! rusqlite `Connection` is `!Send`. The service layer provides a
+//! `ConnectionProvider` trait that async callers (daemon) wrap with
+//! `tokio::task::spawn_blocking`, while sync callers (CLI) use directly.
+
+pub mod connection;
+pub mod error;
+
+// Re-export key types at crate root.
+pub use connection::{open_sync, ConnectionProvider, FileConnectionProvider};
+pub use error::{ServiceError, ServiceResult};