Arcs: The Work Tree

What Is an Arc?

#

An arc is a unit of work with a lifecycle. It is the only work abstraction in Carpenter — tasks, projects, cron jobs, and sub-steps are all arcs at different depths in a recursive tree.

This unification eliminates the friction of mapping between “tasks,” “workflows,” “jobs,” and “history.” An arc is all of them at once.

State Machine

#

Every arc follows this lifecycle:

pending → active → waiting / completed / failed / cancelled

completed, failed, and cancelled are frozen — the arc record becomes immutable. History entries can still be appended for audit purposes.

Cancellation cascades to all descendants. Children execute in step_order.

Tree Structure

#

Each arc has a parent_id (root arcs have none) and a step_order for sibling sequencing. This creates an arbitrarily deep tree:

• A root arc might represent “deploy new feature”
• Its children are the steps: plan, implement, test, review, merge
• Each child can have its own children — the implementation step might spawn coding-change sub-workflows

Agent Types

#

Each arc declares an agent type that determines its capabilities:

Escalation Policies

#

When a child arc fails, the parent is notified. The response is governed by the arc’s escalation policy:

Iterative Planning (Ralph Loop)

#

Complex work often needs iteration. Rather than special loop machinery, Carpenter uses a pattern called the Ralph Loop: a planner creates pairs of sibling arcs — an implementation arc and a monitor arc. Each monitor evaluates the result and, if it decides to continue, creates two more siblings. When a monitor decides “done,” all children complete and the parent regains agency.

Platform-managed performance counters give monitors trustworthy resource data. Each arc maintains descendant_tokens, descendant_executions, and descendant_arc_count, updated by the platform (not executor code) so they can’t be tampered with.

Workflow Templates

#

YAML templates constrain arc subtrees for common patterns:

Template-created arcs are completely immutable — they can’t be deleted, reordered, or have children added. This ensures the workflow structure remains exactly as designed.