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
impl TaskStore
Sourcepub fn renumber_before_merge(
&self,
ref_name: &str,
theirs: &str,
) -> Result<Renumbering, TaskStoreError>
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
impl TaskStore
Sourcepub fn new(
repo: Arc<Repository>,
prefix: impl Into<String>,
agent_id: impl Into<String>,
) -> Self
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).
Sourcepub fn with_context(
repo: Arc<Repository>,
prefix: impl Into<String>,
context: CallContext,
) -> Self
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.
pub fn prefix(&self) -> &str
pub fn agent_id(&self) -> &str
Sourcepub fn context(&self) -> &CallContext
pub fn context(&self) -> &CallContext
The provenance this store’s commits carry.
Sourcepub fn create_plan(
&self,
ref_name: &str,
name: &str,
description: Option<String>,
) -> Result<Plan, TaskStoreError>
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.
Sourcepub fn list_plans(&self, ref_name: &str) -> Result<Vec<Plan>, TaskStoreError>
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).
Sourcepub fn list_plans_with_tasks(
&self,
ref_name: &str,
) -> Result<Vec<(Plan, Vec<Task>)>, TaskStoreError>
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.
Sourcepub fn get_plan(
&self,
ref_name: &str,
name: &str,
) -> Result<Plan, TaskStoreError>
pub fn get_plan( &self, ref_name: &str, name: &str, ) -> Result<Plan, TaskStoreError>
Fetch a single plan by name.
Sourcepub fn archive_plan(
&self,
ref_name: &str,
name: &str,
) -> Result<Plan, TaskStoreError>
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.
Sourcepub fn close_plan(
&self,
ref_name: &str,
name: &str,
summary: &str,
) -> Result<Plan, TaskStoreError>
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.
Sourcepub fn delete_plan(
&self,
ref_name: &str,
name: &str,
) -> Result<(), TaskStoreError>
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.
Sourcepub 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>
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.
Sourcepub 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>
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.
Sourcepub fn task_ids(
&self,
ref_name: &str,
plan: &str,
) -> Result<Vec<TaskId>, TaskStoreError>
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.
Sourcepub fn list_tasks(
&self,
ref_name: &str,
plan: &str,
) -> Result<Vec<Task>, TaskStoreError>
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.
pub fn get_task( &self, ref_name: &str, plan: &str, id: &TaskId, ) -> Result<Task, TaskStoreError>
Sourcepub fn start_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
) -> Result<Task, TaskStoreError>
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).
Sourcepub fn complete_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
proof: Proof,
) -> Result<Task, TaskStoreError>
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.
Sourcepub fn abandon_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
reason: &str,
) -> Result<Task, TaskStoreError>
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.
pub fn set_priority( &self, ref_name: &str, plan: &str, id: &TaskId, priority: Priority, ) -> Result<Task, TaskStoreError>
Sourcepub fn set_title(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
title: &str,
) -> Result<Task, TaskStoreError>
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.
Sourcepub fn set_notes(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
notes: Option<&str>,
) -> Result<Task, TaskStoreError>
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.
Sourcepub fn set_blockers(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
blockers: Vec<TaskId>,
) -> Result<Task, TaskStoreError>
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.
Sourcepub fn assign_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
agent: &str,
) -> Result<Task, TaskStoreError>
pub fn assign_task( &self, ref_name: &str, plan: &str, id: &TaskId, agent: &str, ) -> Result<Task, TaskStoreError>
Set assigned_to on a task.
Sourcepub fn unassign_task(
&self,
ref_name: &str,
plan: &str,
id: &TaskId,
) -> Result<Task, TaskStoreError>
pub fn unassign_task( &self, ref_name: &str, plan: &str, id: &TaskId, ) -> Result<Task, TaskStoreError>
Clear assigned_to on a task.
Sourcepub fn next_task(
&self,
ref_name: &str,
plan: &str,
) -> Result<Option<Task>, TaskStoreError>
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).
Sourcepub fn next_task_for(
&self,
ref_name: &str,
plan: &str,
assigned_to: Option<&str>,
include_unassigned: bool,
) -> Result<Option<Task>, TaskStoreError>
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 asnext_task).assigned_to = Some(agent),include_unassigned = true→ tasks assigned toagentOR unassigned.assigned_to = Some(agent),include_unassigned = false→ only tasks explicitly assigned toagent.
Sourcepub fn list_plans_by_status(
&self,
ref_name: &str,
status: Option<PlanStatus>,
) -> Result<Vec<Plan>, TaskStoreError>
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.
Sourcepub fn derived_status(
&self,
ref_name: &str,
plan: &str,
parent_id: &TaskId,
) -> Result<TaskStatus, TaskStoreError>
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:
Doneif every non-abandoned subtask isDone.InProgressif any subtask isInProgress.Pendingotherwise.
If the parent has no subtasks, returns the parent’s own status.
Sourcepub fn verify_plan(
&self,
ref_name: &str,
plan: &str,
verifier: &dyn Verifier,
) -> Result<VerifyReport, TaskStoreError>
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.