Module api 

mana-core Public API

Programmatic access to all mana unit operations. Use this module when embedding mana in another application — a GUI, MCP server, orchestration daemon, or custom tooling.

The API is organized into layers:

• Types — Core data structures re-exported from internal modules
• Discovery — Find .mana/ directories and unit files
• Query — Read-only operations (list, get, tree, status, graph)
• Mutations — Write operations (create, update, close, delete)
• Orchestration — Agent dispatch, context assembly, and verification
• Facts — Verified project knowledge with TTL

Quick Start

use mana_core::api::*;
use std::path::Path;

// Find the .mana/ directory
let mana_dir = find_mana_dir(Path::new(".")).unwrap();

// Load the index (cached, rebuilds if stale)
let index = load_index(&mana_dir).unwrap();

// Get a specific unit
let unit = get_unit(&mana_dir, "1").unwrap();
println!("{}: {}", unit.id, unit.title);

Design Principles

• No I/O side effects — Library functions never print to stdout/stderr. All output is returned as structured data.
• Structured params and results — Each mutation takes a Params struct and returns a typed result. No raw argument passing.
• &Path as entry point — Every function takes mana_dir: &Path. No global state, no singletons, no Arc required.
• Serializable — All types derive Serialize/Deserialize for easy IPC (Tauri, JSON-RPC, MCP).
• Thread-safe — No interior mutability, no shared global state.

Re-exports

pub use crate::unit::AttemptOutcome;

pub use crate::unit::AttemptRecord;

pub use crate::unit::OnCloseAction;

pub use crate::unit::OnFailAction;

pub use crate::unit::RunRecord;

pub use crate::unit::RunResult;

pub use crate::unit::Status;

pub use crate::unit::Unit;

pub use crate::index::Index;

pub use crate::index::IndexEntry;

pub use crate::config::Config;

pub use crate::error;

pub use crate::error::ManaError as Error;

pub use crate::discovery::find_mana_dir;

pub use crate::discovery::find_unit_file;

pub use crate::discovery::find_archived_unit;

pub use crate::ops::claim;

pub use crate::ops::close;

pub use crate::ops::context;

pub use crate::ops::create;

pub use crate::ops::delete;

pub use crate::ops::dep;

pub use crate::ops::fact;

pub use crate::ops::list;

pub use crate::ops::plan;

pub use crate::ops::show;

pub use crate::ops::update;

pub use crate::ops::verify;

pub use crate::ops::context::AgentContext;

pub use crate::ops::fact::FactParams;

pub use crate::ops::fact::FactResult;

pub use crate::ops::fact::VerifyFactsResult;

pub use crate::ops::run::BlockedUnit;

pub use crate::ops::run::ReadyQueue;

pub use crate::ops::run::ReadyUnit;

pub use crate::ops::run::RunPlan;

pub use crate::ops::run::RunWave;

pub use crate::ops::stats::StatsResult;

pub use crate::ops::status::StatusSummary;

pub use crate::ops::verify::VerifyResult;

pub use crate::graph::build_dependency_tree;

pub use crate::graph::build_full_graph;

pub use crate::graph::count_subtree_attempts;

pub use crate::graph::find_all_cycles;

pub use crate::unit::validate_priority;

Structs

DependencyGraph

A full dependency graph representation.

GraphNode

A node in the dependency graph.

TreeNode

A node in the unit hierarchy tree, used by get_tree.

Functions

add_dep

Add a dependency: from_id depends on dep_id.

assemble_context

Assemble the full agent context for a unit.

claim_unit

Claim a unit for work.

close_unit

Close a unit — run verify, archive, and cascade to parents.

compute_ready_queue

Compute which units are ready to dispatch.

create_fact

Create a verified fact — a unit that encodes checked project knowledge.

create_unit

Create a new unit.

delete_unit

Delete a unit and remove all references to it from other units’ dependencies.

dependency_graph

Build a dependency graph from the active index.

detect_cycle

Detect whether adding an edge from from_id to to_id would create a cycle.

fail_unit

Mark a unit as explicitly failed without closing it.

get_archived_unit

Load a unit from the archive by ID.

get_stats

Get aggregate project statistics.

get_status

Get a categorized project status summary.

get_tree

Build a unit hierarchy tree rooted at the given unit ID.

get_unit

Load a unit by ID.

list_units

List units with optional filters.

load_index

Load the index, rebuilding from unit files if stale.

ready_units

Return units with all dependencies satisfied (ready to dispatch).

record_attempt

Record a verify attempt result on a unit.

release_unit

Release a claim on a unit.

remove_dep

Remove a dependency: from_id no longer depends on dep_id.

reopen_unit

Reopen a closed unit.

run_verify

Run the verify command for a unit without closing it.

topological_sort

Topologically sort all units by dependency order.

update_unit

Update a unit’s fields.

verify_facts

Verify all facts and report staleness and failures.