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.

Modules

claim

close

context

create

delete

dep

error

fact

list

plan

show

update

verify

Structs

AgentContext

Fully assembled agent context for a unit.

AttemptRecord

A single attempt record (claim→close cycle).

BlockedUnit

A unit that was excluded from dispatch.

Config

Project-level mana configuration, loaded from .mana/config.yaml.

DependencyGraph

A full dependency graph representation.

FactParams

Parameters for creating a fact.

FactResult

Result of creating a fact.

GraphNode

A node in the dependency graph.

Index

The in-memory and on-disk unit index.

IndexEntry

A lightweight summary of a single unit, stored in the index cache.

ReadyQueue

The result of computing the ready queue.

ReadyUnit

A unit that is ready to be dispatched.

RunPlan

A full execution plan grouped into dependency-ordered waves.

RunRecord

A single verification run record.

RunWave

A wave of units that can run concurrently (no inter-wave dependencies).

StatsResult

Project statistics snapshot.

StatusSummary

Categorized view of project status.

TreeNode

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

Unit

A single unit of work managed by mana.

VerifyFactsResult

Aggregated result of verifying all facts.

VerifyResult

Result of running a verify command.

Enums

AttemptOutcome

Outcome of a claim→close cycle.

Error

Typed error for mana-core’s public API surface.

OnCloseAction

Declarative actions to run when a unit is closed. Processed after the unit is archived and post-close hook fires.

OnFailAction

Declarative action to run when a unit’s verify command fails.

RunResult

Outcome of a verification run.

Status

Functions

add_dep

Add a dependency: from_id depends on dep_id.

assemble_context

Assemble the full agent context for a unit.

build_dependency_tree

Build a dependency tree rooted at id. Returns a string representation with box-drawing characters.

build_full_graph

Build a project-wide dependency graph as a text tree. Shows all dependencies rooted at units with no parents.

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.

count_subtree_attempts

Count total verify attempts across all descendants of a unit.

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.

find_all_cycles

Find all cycles in the dependency graph. Returns a list of cycle paths.

find_archived_unit

Find an archived unit by ID within the .mana/archive/ directory tree.

find_mana_dir

Walk up from start looking for a .mana/ directory. Returns the path to the .mana/ directory if found. Errors if no .mana/ directory exists in any ancestor.

find_unit_file

Find a unit file by ID, supporting both new and legacy naming conventions.

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.

validate_priority

Validate that priority is in the valid range (0-4, P0-P4).

verify_facts

Verify all facts and report staleness and failures.