Struct Database 

pub struct Database { /* private fields */ }

Database handle wrapping a SQLite connection.

Implementations

impl Database

pub fn register_worker( &self, worker_id: Option<String>, tags: Vec<String>, force: bool, ) -> Result<Worker>

Register a new worker.

If worker_id is provided, it must be at most 36 characters. If not provided, a human-readable petname will be generated (e.g., “happy-turtle”). If force is true and the worker already exists, it will be re-registered (useful for stuck worker recovery).

pub fn get_worker(&self, worker_id: &str) -> Result<Option<Worker>>

Get a worker by ID.

pub fn require_worker(&self, worker_id: &str) -> Result<Worker>

Check if a worker exists. Returns error if not found.

pub fn update_worker( &self, worker_id: &str, tags: Option<Vec<String>>, max_claims: Option<i32>, ) -> Result<Worker>

Update a worker.

pub fn heartbeat(&self, worker_id: &str) -> Result<i32>

Update worker heartbeat.

pub fn unregister_worker( &self, worker_id: &str, final_status: &str, ) -> Result<DisconnectSummary>

Unregister a worker (releases all claims). Returns a summary of released tasks and files.

pub fn list_workers(&self) -> Result<Vec<Worker>>

List all workers.

pub fn list_workers_info(&self) -> Result<Vec<WorkerInfo>>

List all workers with extended info (claim count, current thought).

pub fn list_workers_filtered( &self, tags: Option<&Vec<String>>, file: Option<&str>, task_id: Option<&str>, depth: i32, ) -> Result<Vec<WorkerInfo>>

List workers with optional filters by tags, file claimed, or related task.

• tags: Workers must have ALL of these tags
• file: Workers that have claimed this file
• task_id: Workers working on tasks related to this task
• depth: Task relationship depth (-3 to 3). Negative: ancestors, positive: descendants

pub fn get_stale_workers(&self, timeout_seconds: i64) -> Result<Vec<Worker>>

Get workers with stale heartbeats.

pub fn cleanup_stale_workers( &self, timeout_seconds: i64, final_status: &str, ) -> Result<CleanupSummary>

Cleanup stale workers by evicting them and releasing their claims. Returns a summary of the cleanup operation.

pub fn get_claim_count(&self, worker_id: &str) -> Result<i32>

Get claim count for a worker.

impl Database

pub fn add_attachment( &self, task_id: &str, name: String, content: String, mime_type: Option<String>, file_path: Option<String>, ) -> Result<i32>

Add an attachment to a task with auto-increment order_index. Returns the order_index of the new attachment. If file_path is provided, content should be empty (stored externally).

pub fn get_attachments_full( &self, task_id: &str, include_content: bool, ) -> Result<Vec<Attachment>>

Get attachments for a task, optionally including content. Note: For file-based attachments, content is NOT loaded here - use get_attachment for that.

pub fn get_attachments(&self, task_id: &str) -> Result<Vec<AttachmentMeta>>

Get attachments for a task (metadata only).

pub fn get_attachments_filtered( &self, task_id: &str, name_pattern: Option<&str>, mime_pattern: Option<&str>, ) -> Result<Vec<AttachmentMeta>>

Get attachments for a task with optional filtering (metadata only).

• name_pattern: Optional glob pattern (with * wildcard) to filter by attachment name
• mime_pattern: Optional prefix to filter by MIME type (e.g., “image/” matches “image/png”)

pub fn get_attachment( &self, task_id: &str, order_index: i32, ) -> Result<Option<Attachment>>

Get a full attachment by (task_id, order_index). Note: For file-based attachments, content field contains the DB content (empty). The caller should read from file_path if set.

pub fn get_attachment_file_path( &self, task_id: &str, order_index: i32, ) -> Result<Option<String>>

Get just the file_path for an attachment (useful before deletion).

pub fn delete_attachment(&self, task_id: &str, order_index: i32) -> Result<bool>

Delete an attachment by (task_id, order_index).

pub fn delete_attachment_by_name( &self, task_id: &str, name: &str, ) -> Result<Option<String>>

Delete an attachment by name (for replace behavior). Returns the file_path if one was set (for cleanup).

pub fn delete_attachment_by_name_ex( &self, task_id: &str, name: &str, ) -> Result<(bool, Option<String>)>

Delete an attachment by name and return whether it was deleted plus the file_path. Returns (was_deleted, file_path).

impl Database

pub fn add_dependency( &self, from_task_id: &str, to_task_id: &str, dep_type: &str, deps_config: &DependenciesConfig, ) -> Result<()>

Add a typed dependency (from blocks/contains to).

pub fn would_create_cycle( &self, from_task_id: &str, to_task_id: &str, dep_type: &str, deps_config: &DependenciesConfig, ) -> Result<bool>

Check if adding a dependency would create a cycle. For horizontal deps: check cycle in the start-blocking graph. For vertical deps: check containment cycle.

pub fn remove_dependency( &self, from_task_id: &str, to_task_id: &str, dep_type: &str, ) -> Result<bool>

Remove a typed dependency. Returns true if a row was deleted.

pub fn remove_all_outgoing_dependencies( &self, from_task_id: &str, dep_type: &str, ) -> Result<Vec<Dependency>>

Remove all dependencies of a given type from a task (outgoing edges). Returns the list of removed dependencies.

pub fn remove_all_incoming_dependencies( &self, to_task_id: &str, dep_type: &str, ) -> Result<Vec<Dependency>>

Remove all dependencies of a given type to a task (incoming edges). Returns the list of removed dependencies.

pub fn get_all_dependencies(&self) -> Result<Vec<Dependency>>

Get all dependencies.

pub fn get_dependencies_by_type( &self, task_id: &str, dep_type: &str, direction: &str, ) -> Result<Vec<Dependency>>

Get dependencies of a specific type for a task.

pub fn get_start_blockers( &self, task_id: &str, deps_config: &DependenciesConfig, ) -> Result<Vec<String>>

Get tasks that block a given task from starting (dep_type with blocks: start).

pub fn get_completion_blockers( &self, task_id: &str, deps_config: &DependenciesConfig, ) -> Result<Vec<String>>

Get tasks that block a given task from completing (dep_type with blocks: completion). For a parent task, this returns children that must complete first.

pub fn get_parent(&self, task_id: &str) -> Result<Option<String>>

Get the parent of a task (via ‘contains’ dependency).

pub fn get_children_ids(&self, task_id: &str) -> Result<Vec<String>>

Get children of a task (via ‘contains’ dependency).

pub fn get_blockers(&self, task_id: &str) -> Result<Vec<String>>

Get all tasks that block a given task (backwards compatible). Returns tasks from both ‘blocks’ and ‘follows’ dependencies.

pub fn get_blocking(&self, task_id: &str) -> Result<Vec<String>>

Get tasks that a given task blocks.

pub fn get_blocked_tasks( &self, states_config: &StatesConfig, deps_config: &DependenciesConfig, sort_by: Option<&str>, sort_order: Option<&str>, ) -> Result<Vec<Task>>

Get tasks that are blocked by incomplete start dependencies. A task is blocked if any of its start-blocking dependencies are in a blocking state. Excludes soft-deleted tasks.

pub fn get_ready_tasks( &self, agent_id: Option<&str>, states_config: &StatesConfig, deps_config: &DependenciesConfig, sort_by: Option<&str>, sort_order: Option<&str>, ) -> Result<Vec<Task>>

Get tasks that are ready to be claimed (all start dependencies satisfied). A task is ready if it’s in the initial state, unclaimed, and all start-blocking deps are not blocking. When agent_id is provided, also filters by agent’s tag qualifications using junction tables. Excludes soft-deleted tasks.

pub fn has_unmet_start_dependencies( &self, task_id: &str, states_config: &StatesConfig, deps_config: &DependenciesConfig, ) -> Result<bool>

Check if a task has unmet start dependencies.

pub fn has_incomplete_children( &self, task_id: &str, states_config: &StatesConfig, ) -> Result<bool>

Check if a task has incomplete children (blocking completion).

pub fn list_tasks_with_tag_filters( &self, status: Option<Vec<String>>, owner: Option<&str>, parent_id: Option<Option<&str>>, tags_any: Option<Vec<String>>, tags_all: Option<Vec<String>>, qualified_for_agent_tags: Option<Vec<String>>, limit: Option<i32>, sort_by: Option<&str>, sort_order: Option<&str>, ) -> Result<Vec<Task>>

Get tasks with tag-based filtering using junction tables for indexed lookups.

• tags_any: Task must have at least one of these tags (OR)
• tags_all: Task must have all of these tags (AND)
• qualified_for_agent_tags: If provided, only return tasks where these tags satisfy the task’s agent_tags_all/agent_tags_any

Excludes soft-deleted tasks.

pub fn get_agent_tags(&self, agent_id: &str) -> Result<Vec<String>>

Get agent tags by agent ID.

pub fn relink( &self, prev_from_ids: &[String], prev_to_ids: &[String], from_ids: &[String], to_ids: &[String], dep_type: &str, deps_config: &DependenciesConfig, ) -> Result<RelinkResult>

Atomically relink dependencies: unlink all prev_from→prev_to, then link all from→to. This is a transaction-safe operation for moving children between parents. Returns a result with unlinked and linked pairs.

pub fn get_predecessors(&self, task_id: &str, depth: i32) -> Result<Vec<Task>>

Get predecessors (tasks that block this task) via blocks/follows dependencies. depth: 0 = none, N = N levels, -1 = all

pub fn get_successors(&self, task_id: &str, depth: i32) -> Result<Vec<Task>>

Get successors (tasks that this task blocks) via blocks/follows dependencies. depth: 0 = none, N = N levels, -1 = all

pub fn get_ancestors(&self, task_id: &str, depth: i32) -> Result<Vec<Task>>

Get ancestors (parent chain) via contains dependency. depth: 0 = none, N = N levels up, -1 = all

pub fn get_descendants(&self, task_id: &str, depth: i32) -> Result<Vec<Task>>

Get descendants (children tree) via contains dependency. depth: 0 = none, N = N levels down, -1 = all

impl Database

pub fn lock_file( &self, file_path: String, worker_id: &str, reason: Option<String>, task_id: Option<String>, ) -> Result<Option<String>>

Lock a file (advisory). Returns Ok with optional warning if already locked by another worker.

pub fn unlock_file( &self, file_path: &str, worker_id: &str, reason: Option<String>, ) -> Result<bool>

Unlock a file with optional reason for next claimant.

pub fn unlock_files_verbose( &self, file_paths: Vec<String>, worker_id: &str, reason: Option<String>, ) -> Result<Vec<(String, String)>>

Unlock multiple files with verbose return. Returns a list of (file_path, worker_id) pairs for files that were actually released.

pub fn release_worker_locks_verbose( &self, worker_id: &str, reason: Option<String>, ) -> Result<Vec<(String, String)>>

Release all files held by a worker with verbose return. Returns a list of (file_path, worker_id) pairs for files that were released.

pub fn release_task_locks_verbose( &self, task_id: &str, reason: Option<String>, ) -> Result<Vec<(String, String)>>

Release all files associated with a task with verbose return. Returns a list of (file_path, worker_id) pairs for files that were released.

pub fn claim_updates(&self, worker_id: &str) -> Result<ClaimUpdates>

Get claim updates since worker’s last poll. Returns all claim/release events since the agent’s last poll position.

pub fn get_file_locks( &self, file_paths: Option<Vec<String>>, agent_id: Option<&str>, task_id: Option<&str>, ) -> Result<HashMap<String, FileLock>>

Get file locks with full details.

pub fn get_all_file_locks(&self) -> Result<Vec<FileLock>>

Get all file locks as FileLock objects.

pub fn release_worker_locks(&self, worker_id: &str) -> Result<i32>

Release all locks held by a worker.

pub fn release_task_locks(&self, task_id: &str) -> Result<i32>

Release all locks associated with a task. Called automatically when a task completes.

impl Database

pub fn get_schema(&self, include_sql: bool) -> Result<DatabaseSchema>

Get complete schema information for the database.

pub fn get_table_names(&self) -> Result<Vec<String>>

Get a list of table names only (lightweight).

impl Database

pub fn search_tasks( &self, query: &str, limit: Option<i32>, include_attachments: bool, status_filter: Option<&str>, ) -> Result<Vec<SearchResult>>

Search tasks using FTS5 full-text search.

The query supports FTS5 MATCH syntax:

• Simple words: error handling
• Phrases: "error handling"
• Prefix: error*
• Boolean: error AND NOT warning
• Column-specific: title:error or description:handling

Results are ranked by BM25 relevance score.

impl Database

pub fn get_task_state_history( &self, task_id: &str, ) -> Result<Vec<TaskStateEvent>>

Get the state transition history for a task.

pub fn get_current_state_duration( &self, task_id: &str, states_config: &StatesConfig, ) -> Result<Option<i64>>

Get the current duration in the current state (for active time tracking). Only returns a duration if the current state is a timed state.

pub fn get_project_state_history( &self, from_timestamp: Option<i64>, to_timestamp: Option<i64>, state_filter: Option<&[String]>, limit: Option<i64>, ) -> Result<Vec<TaskStateEvent>>

Get project-wide state transition history with optional time range filter. Returns all state transitions across all tasks within the specified time range.

pub fn get_project_state_stats( &self, from_timestamp: Option<i64>, to_timestamp: Option<i64>, ) -> Result<ProjectStateStats>

Get aggregate project statistics for state transitions within a time range. Returns counts of transitions per state and per agent.

impl Database

pub fn get_stats( &self, agent_id: Option<&str>, task_id: Option<&str>, states_config: &StatesConfig, ) -> Result<Stats>

Get aggregate statistics with dynamic state counting.

impl Database

pub fn create_task( &self, id: Option<String>, description: String, parent_id: Option<String>, priority: Option<Priority>, points: Option<i32>, time_estimate_ms: Option<i64>, agent_tags_all: Option<Vec<String>>, agent_tags_any: Option<Vec<String>>, tags: Option<Vec<String>>, states_config: &StatesConfig, ) -> Result<Task>

Create a new task. If id is provided, uses it as the task ID; otherwise generates UUID7. If parent_id is provided, creates a ‘contains’ dependency from parent to this task.

pub fn create_task_tree( &self, input: TaskTreeInput, parent_id: Option<String>, child_type: Option<String>, sibling_type: Option<String>, states_config: &StatesConfig, ) -> Result<(String, Vec<String>)>

Create a task tree from nested input. Uses child_type for parent-child dependencies (default: “contains”). Uses sibling_type for sibling dependencies (default: none/parallel).

pub fn get_task(&self, task_id: &str) -> Result<Option<Task>>

Get a task by ID.

pub fn get_task_tree(&self, task_id: &str) -> Result<Option<TaskTree>>

Get a task with all its children (tree).

pub fn get_children(&self, parent_id: &str) -> Result<Vec<Task>>

Get direct children of a task (via ‘contains’ dependency).

pub fn update_task( &self, task_id: &str, title: Option<String>, description: Option<Option<String>>, status: Option<String>, priority: Option<Priority>, points: Option<Option<i32>>, tags: Option<Vec<String>>, states_config: &StatesConfig, ) -> Result<Task>

Update a task.

pub fn update_task_unified( &self, task_id: &str, agent_id: &str, assignee: Option<&str>, title: Option<String>, description: Option<Option<String>>, status: Option<String>, priority: Option<Priority>, points: Option<Option<i32>>, tags: Option<Vec<String>>, needed_tags: Option<Vec<String>>, wanted_tags: Option<Vec<String>>, time_estimate_ms: Option<i64>, reason: Option<String>, force: bool, states_config: &StatesConfig, deps_config: &DependenciesConfig, auto_advance: &AutoAdvanceConfig, ) -> Result<(Task, Vec<String>, Vec<String>)>

Update a task with unified claim/release logic.

• Transition to timed state = CLAIM (set owner, validate tags, check limit)
• Transition from timed to non-timed = RELEASE (clear owner)
• Transition to terminal = COMPLETE (check children, release file locks)
• With assignee = ASSIGN (set owner to assignee, transition to ‘assigned’ state)
• Only the owner can update a claimed task (unless force=true)

Returns (task, unblocked, auto_advanced):

• task: The updated task
• unblocked: Task IDs that are now ready (all dependencies satisfied)
• auto_advanced: Subset of unblocked that were actually transitioned

pub fn delete_task( &self, task_id: &str, worker_id: &str, cascade: bool, reason: Option<String>, obliterate: bool, force: bool, ) -> Result<()>

Delete a task (soft delete by default, hard delete with obliterate=true).

• worker_id: The worker attempting to delete (required for ownership check)
• cascade: Whether to delete children (default: false)
• reason: Optional reason for deletion
• obliterate: If true, permanently deletes the task; if false (default), soft deletes
• force: If true, allows deletion even if owned by another worker

pub fn list_tasks( &self, status: Option<&str>, owner: Option<&str>, parent_id: Option<Option<&str>>, limit: Option<i32>, sort_by: Option<&str>, sort_order: Option<&str>, ) -> Result<Vec<Task>>

List tasks with optional filters. Returns full Task objects. Excludes soft-deleted tasks.

pub fn set_thought( &self, agent_id: &str, thought: Option<String>, task_ids: Option<Vec<String>>, ) -> Result<i32>

Set the current thought for tasks owned by an agent.

pub fn log_time(&self, task_id: &str, duration_ms: i64) -> Result<i64>

Log time for a task.

pub fn log_metrics( &self, task_id: &str, cost_usd: Option<f64>, values: &[i64], ) -> Result<Task>

Log metrics and cost for a task. Values in the metrics array are aggregated (added) to existing values.

pub fn claim_task( &self, task_id: &str, agent_id: &str, states_config: &StatesConfig, ) -> Result<Task>

Claim a task for an agent. Uses the first timed state (typically “in_progress”) as the claiming state.

pub fn release_task( &self, task_id: &str, agent_id: &str, states_config: &StatesConfig, ) -> Result<()>

Release a task claim.

pub fn force_release( &self, task_id: &str, states_config: &StatesConfig, ) -> Result<()>

Force release a task regardless of owner.

pub fn force_claim_task( &self, task_id: &str, agent_id: &str, states_config: &StatesConfig, ) -> Result<Task>

Force claim a task even if owned by another agent.

pub fn release_task_with_state( &self, task_id: &str, agent_id: &str, state: &str, states_config: &StatesConfig, ) -> Result<()>

Release a task claim with a specified state.

pub fn force_release_stale( &self, timeout_seconds: i64, states_config: &StatesConfig, ) -> Result<i32>

Force release stale claims.

pub fn complete_task( &self, task_id: &str, agent_id: &str, states_config: &StatesConfig, ) -> Result<Task>

Complete a task and release file locks held by the agent. Uses “completed” state by default, which should be a terminal state. Checks that all children (via ‘contains’ dependencies) are complete.

pub fn get_all_tasks(&self) -> Result<Vec<Task>>

Get all tasks. Excludes soft-deleted tasks.

pub fn get_tasks_by_status(&self, status: &str) -> Result<Vec<Task>>

Get tasks by status.

pub fn get_claimed_tasks(&self, agent_id: Option<&str>) -> Result<Vec<Task>>

Get claimed tasks. Excludes soft-deleted tasks.

impl Database

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open or create the database at the given path.

pub fn open_in_memory() -> Result<Self>

Open an in-memory database (for testing).

pub fn with_conn<F, T>(&self, f: F) -> Result<T>

where F: FnOnce(&Connection) -> Result<T>,

Execute a function with exclusive access to the connection.

pub fn with_conn_mut<F, T>(&self, f: F) -> Result<T>

where F: FnOnce(&mut Connection) -> Result<T>,

Execute a function with mutable access to the connection (for transactions).

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.