Function parse_toolset 

pub fn parse_toolset(dir: &Path) -> Result<Toolset, ToolsetFormatError>

Parse and validate a toolset directory.

dir must be the path to a toolset DIRECTORY (not the TOOLSET.md file itself). The directory name is used for the name == directory-name check.

Parse pipeline

1. Read TOOLSET.md from dir (256 KiB size cap, UTF-8 only).
2. Split the leading --- YAML frontmatter.
3. Parse the frontmatter with an ITERATIVE event pull loop (Parser::next_token — no C-stack recursion; the parser’s state machine uses an explicit heap stack internally). Anchors, both BLOCK and FLOW nesting depth, and duplicate keys are all checked at the event level.
4. Validate name, description, compatibility.
5. Parse the capability manifest from stellar-agent-capabilities.
6. Return Toolset or the first ToolsetFormatError.

Security properties

• The parser operates on fully-adversarial bytes: no reliance on signature or hash verification running first.
• YAML anchors/aliases are rejected at the event level before any tree is materialised (billion-laughs defence).
• Nesting depth is bounded at 8 for BOTH BLOCK and FLOW styles via the iterative pull loop: the loop stops pulling events the instant depth exceeds MAX_DEPTH. Because the underlying Parser::next_token state machine is iterative (explicit heap stack, no C-stack recursion), this bound prevents stack overflow for both compact block-sequence - - - … chains and deeply nested flow documents {a:{a:…}} / [[[[….
• Duplicate mapping keys are refused (viewer-vs-parser confusion defence).
• The sign-transaction capability token is always refused.

Errors

Returns the first ToolsetFormatError encountered. See the error variant documentation for the triggering conditions.

Examples

use stellar_agent_toolsets::parse_toolset;
use std::path::Path;

// The path must point to a directory whose name matches the toolset's `name`
// field and which contains a valid `TOOLSET.md`.
let dir = Path::new("tests/fixtures/valid-minimal/read-balance");
match parse_toolset(dir) {
    Ok(toolset) => println!("parsed toolset: {}", toolset.name),
    Err(e) => eprintln!("parse error: {e}"),
}