Skip to main content

TaskStore

Struct TaskStore 

Source
pub struct TaskStore { /* private fields */ }
Expand description

A handle bound to a Repository and a path prefix. All operations on plans and tasks go through a TaskStore.

Implementations§

Source§

impl TaskStore

Source

pub fn renumber_before_merge( &self, ref_name: &str, theirs: &str, ) -> Result<Renumbering, TaskStoreError>

Before merging theirs into ref_name, renumber the tasks this side added that collide with ones theirs added, as the module docs describe. theirs is typically a remote-tracking ref after a fetch. Does nothing when nothing collides.

Source§

impl TaskStore

Source

pub fn new( repo: Arc<Repository>, prefix: impl Into<String>, agent_id: impl Into<String>, ) -> Self

Create a new task store bound to a path prefix in the given repository. The prefix must NOT end with a slash.

agent_id is used as the commit author for every task operation. Same as TaskStore::with_context with CallContext::new(agent_id).

Source

pub fn with_context( repo: Arc<Repository>, prefix: impl Into<String>, context: CallContext, ) -> Self

Create a task store whose commits carry context’s provenance: its agent, authorizing principal, delegation chain and device. A host that knows who is calling builds a store per caller this way, so plan commits are attributed the same as its other writes. The created_by, started_by, completed_by and closed_by fields record the context’s agent id.

Source

pub fn prefix(&self) -> &str

Source

pub fn agent_id(&self) -> &str

Source

pub fn context(&self) -> &CallContext

The provenance this store’s commits carry.

Source

pub fn create_plan( &self, ref_name: &str, name: &str, description: Option<String>, ) -> Result<Plan, TaskStoreError>

Create a new plan. Fails if a plan with the same name already exists.

Uses a CAS retry loop so concurrent writers across processes are safe: if the ref moves between the existence check and the commit, the loop retries up to MAX_CAS_RETRIES times before returning TaskStoreError::WriteConflict.

Source

pub fn list_plans(&self, ref_name: &str) -> Result<Vec<Plan>, TaskStoreError>

List every plan under the store’s prefix. Returns plans in the order they are stored (alphabetical by name, since state trees use BTreeMap underneath).

Source

pub fn list_plans_with_tasks( &self, ref_name: &str, ) -> Result<Vec<(Plan, Vec<Task>)>, TaskStoreError>

Every plan with its tasks (sorted by id), from one read of the plans tree: what a listing that shows task counts needs, without a read per plan.

Source

pub fn get_plan( &self, ref_name: &str, name: &str, ) -> Result<Plan, TaskStoreError>

Fetch a single plan by name.

Source

pub fn archive_plan( &self, ref_name: &str, name: &str, ) -> Result<Plan, TaskStoreError>

Archive a plan — a soft, reversible transition that marks the plan as no longer active but leaves all task data intact. Valid for any status (active, completed, empty) — archival never touches tasks, proofs, or abandonment reasons.

Uses a CAS retry loop so concurrent plan mutations on the same branch can’t silently overwrite one another. Each retry re-reads the plan from the snapshotted head, so a competing write that advanced the ref is picked up on the next pass rather than lost.

Source

pub fn close_plan( &self, ref_name: &str, name: &str, summary: &str, ) -> Result<Plan, TaskStoreError>

Close a plan, recording a required summary.

This is the explicit, gated replacement for the old auto-promotion: terminal task transitions no longer complete the plan on their own. Closing requires (1) a non-empty summary — the plan-level analog of a task’s proof — and (2) that every task is already terminal (Done/Abandoned), so a plan cannot be closed with work still open.

Idempotent on an already-closed (Completed) plan: returns it unchanged. Refuses an Archived plan. Sets status = Completed, summary, closed_at, and closed_by.

Source

pub fn delete_plan( &self, ref_name: &str, name: &str, ) -> Result<(), TaskStoreError>

Delete a plan and every task it contains. Destructive — use archive_plan if the history should remain discoverable.

Source

pub fn add_task( &self, ref_name: &str, plan: &str, title: &str, priority: Priority, parent_id: Option<TaskId>, blocked_by: Vec<TaskId>, assigned_to: Option<String>, ) -> Result<Task, TaskStoreError>

Add a new task to a plan. Task ids are assigned monotonically — the next available t-NNN is picked by scanning existing entries. assigned_to is optional — pass an agent id to record ownership.

Source

pub fn add_task_with_extensions( &self, ref_name: &str, plan: &str, title: &str, priority: Priority, parent_id: Option<TaskId>, blocked_by: Vec<TaskId>, assigned_to: Option<String>, opts: AddTaskOptions, ) -> Result<Task, TaskStoreError>

Like add_task but also accepts the policy-fallback extension fields (POLICY_V1.md §22.4) and notes. See AddTaskOptions for field docs.

Uses a CAS retry loop so concurrent writers across processes are safe. On each retry, next_task_number re-scans the current tree, naturally picking the next available id even if a concurrent writer added a task in the meantime.

Source

pub fn task_ids( &self, ref_name: &str, plan: &str, ) -> Result<Vec<TaskId>, TaskStoreError>

List every task id in a plan, cheaply — this walks tree paths without deserializing task bodies. Use this when you only need to know which tasks exist (e.g. picking the next task number, checking blocker existence). Prefer list_tasks when you need task data.

Source

pub fn list_tasks( &self, ref_name: &str, plan: &str, ) -> Result<Vec<Task>, TaskStoreError>

List every task in a plan. Ordered by task id. This fully deserializes every task — O(n) in total field count. For id-only operations prefer task_ids.

Source

pub fn get_task( &self, ref_name: &str, plan: &str, id: &TaskId, ) -> Result<Task, TaskStoreError>

Source

pub fn start_task( &self, ref_name: &str, plan: &str, id: &TaskId, ) -> Result<Task, TaskStoreError>

Transition pending → in_progress. Fails with Blocked if any blocker is not done, or BlockerNotFound if any blocker id no longer exists in the plan (e.g. because the plan was rebuilt after a delete).

Source

pub fn complete_task( &self, ref_name: &str, plan: &str, id: &TaskId, proof: Proof, ) -> Result<Task, TaskStoreError>

Transition in_progress → done. Requires a Proof — it’s stored but NOT verified here (use verify_plan for that).

A terminal task transition does NOT auto-promote the plan to Completed. Closing a plan is an explicit, summary-gated action (close_plan) so implementations own their close workflow and can require a summary — the plan-level analog of a task’s proof.

Source

pub fn abandon_task( &self, ref_name: &str, plan: &str, id: &TaskId, reason: &str, ) -> Result<Task, TaskStoreError>

Transition to abandoned. Legal from both pending and in_progress. Reason is required. Like complete_task, it does not touch the plan’s status.

Source

pub fn set_priority( &self, ref_name: &str, plan: &str, id: &TaskId, priority: Priority, ) -> Result<Task, TaskStoreError>

Source

pub fn set_title( &self, ref_name: &str, plan: &str, id: &TaskId, title: &str, ) -> Result<Task, TaskStoreError>

Replace a task’s title. The title must not be blank. Status, proof, blockers and timestamps are left as they are; the commit records who changed it.

Source

pub fn set_notes( &self, ref_name: &str, plan: &str, id: &TaskId, notes: Option<&str>, ) -> Result<Task, TaskStoreError>

Replace a task’s notes, or clear them with None or blank text.

Notes may span lines and are kept exactly as given, up to MAX_NOTES_BYTES of UTF-8; longer notes are refused with TaskStoreError::NotesTooLong and the task is left as it was. Like set_title, this works at any status, done and abandoned included, and leaves everything else as it is. Each edit is a commit that records who made it.

Source

pub fn set_blockers( &self, ref_name: &str, plan: &str, id: &TaskId, blockers: Vec<TaskId>, ) -> Result<Task, TaskStoreError>

Replace a task’s blocker list. Every blocker must be a task in the same plan, and the new list must not make the task wait on itself, directly or through other tasks: a cycle would leave every task in it blocked for good.

Source

pub fn assign_task( &self, ref_name: &str, plan: &str, id: &TaskId, agent: &str, ) -> Result<Task, TaskStoreError>

Set assigned_to on a task.

Source

pub fn unassign_task( &self, ref_name: &str, plan: &str, id: &TaskId, ) -> Result<Task, TaskStoreError>

Clear assigned_to on a task.

Source

pub fn next_task( &self, ref_name: &str, plan: &str, ) -> Result<Option<Task>, TaskStoreError>

Highest-priority pending task whose blockers are all done. Ties broken by ascending task id (insertion order).

Source

pub fn next_task_for( &self, ref_name: &str, plan: &str, assigned_to: Option<&str>, include_unassigned: bool, ) -> Result<Option<Task>, TaskStoreError>

Like next_task, but filter by assignment.

  • assigned_to = None → any pending unblocked task (same as next_task).
  • assigned_to = Some(agent), include_unassigned = true → tasks assigned to agent OR unassigned.
  • assigned_to = Some(agent), include_unassigned = false → only tasks explicitly assigned to agent.
Source

pub fn list_plans_by_status( &self, ref_name: &str, status: Option<PlanStatus>, ) -> Result<Vec<Plan>, TaskStoreError>

List plans filtered by status. None returns all plans.

Source

pub fn derived_status( &self, ref_name: &str, plan: &str, parent_id: &TaskId, ) -> Result<TaskStatus, TaskStoreError>

Compute the rollup status of a parent task from its direct subtasks. Read-only — does not mutate storage.

Rules:

  • Done if every non-abandoned subtask is Done.
  • InProgress if any subtask is InProgress.
  • Pending otherwise.

If the parent has no subtasks, returns the parent’s own status.

Source

pub fn verify_plan( &self, ref_name: &str, plan: &str, verifier: &dyn Verifier, ) -> Result<VerifyReport, TaskStoreError>

Walk every done task and run the given verifier against each proof. Non-done tasks are skipped.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more