🥮 mooncakes.io

moonflowgraph

A MoonBit task graph and provenance trace library for reproducible research and agent workflows.

workflow
dag
provenance
agent
research
moon add AlexenderSokolov/moonflowgraph@0.3.0
Download zip
Version
0.3.0
License
Apache-2.0
Repository
Last updated
last month
Downloads
41
README

#MoonFlowGraph Executable Examples

///|
test {
  let graph = FlowGraph::new()
  guard graph.add_task(TaskNode::new("collect_papers", "Collect papers"))
    is Ok(_) else {
    fail("expected first task")
  }
  guard graph.add_task(TaskNode::new("write_report", "Write report")) is Ok(_) else {
    fail("expected second task")
  }
  guard graph.add_dependency(
      TaskId::new("collect_papers"),
      TaskId::new("write_report"),
    )
    is Ok(_) else {
    fail("expected dependency")
  }
  guard graph.plan() is Ok(plan) else { fail("expected valid graph") }
  debug_inspect(plan.order().length(), content="2")
  debug_inspect(plan.batches().length(), content="2")
  guard graph.roots() is Ok(roots) else { fail("expected roots") }
  guard graph.leaves() is Ok(leaves) else { fail("expected leaves") }
  debug_inspect(roots[0].value(), content="\"collect_papers\"")
  debug_inspect(leaves[0].value(), content="\"write_report\"")
  guard graph.to_mermaid() is Ok(mermaid) else { fail("expected Mermaid") }
  debug_inspect(mermaid.contains("task_0 --> task_1"), content="true")
  let trace = Trace::new()
  guard graph.to_json_checked(plan, trace) is Ok(snapshot) else {
    fail("expected checked JSON")
  }
  debug_inspect(snapshot.contains("\"schema_version\": 1"), content="true")
  guard RunSnapshot::from_json(snapshot) is Ok(imported_snapshot) else {
    fail("expected run snapshot import")
  }
  debug_inspect(imported_snapshot.audit() is Ok(_), content="true")
  let workflow_json = graph.to_workflow_spec().to_json()
  guard FlowGraph::from_workflow_json(workflow_json) is Ok(round_trip) else {
    fail("expected workflow import")
  }
  debug_inspect(round_trip.task_count(), content="2")
}

#
Dependency

source
pub struct Dependency {
  // private fields
} derive(Eq, 
Debug)

Directed dependency edge: before must finish before after.

#
Dependency::after

source
fn Dependency::after(self : Dependency) -> TaskId

Return the successor endpoint of this dependency.

#
Dependency::before

source
fn Dependency::before(self : Dependency) -> TaskId

Return the predecessor endpoint of this dependency.

#
Dependency::new

source
fn Dependency::new(before : TaskId, after : TaskId) -> Dependency

Build a dependency edge.

#
ExecutionPlan

source
pub struct ExecutionPlan {
  // private fields
} derive(Eq, 
Debug)

A validated execution plan with serial order and parallel-ready batches.

#
ExecutionPlan::batches

source
fn ExecutionPlan::batches(self : ExecutionPlan) -> Array[Array[TaskId]]

Return a detached copy of the parallel execution batches.

#
ExecutionPlan::order

source
fn ExecutionPlan::order(self : ExecutionPlan) -> Array[TaskId]

Return a detached copy of the serial execution order.

#
ExecutionPlan::snapshot

source
fn ExecutionPlan::snapshot(self : ExecutionPlan) -> ExecutionPlan

Return a detached copy of an execution plan, including nested batches.

#
FlowGraph

source
pub struct FlowGraph {
  // private fields
} derive(
Debug)

Mutable workflow graph.

#
FlowGraph::add_dependency

source
fn FlowGraph::add_dependency(self : FlowGraph, before : TaskId, after : TaskId) -> Result[Unit, GraphError]

Add a dependency edge. Duplicate edges are rejected; endpoint existence is checked by validate.

#
FlowGraph::add_task

source
fn FlowGraph::add_task(self : FlowGraph, node : TaskNode) -> Result[Unit, GraphError]

Add a task node. Duplicate ids return DuplicateTask.

#
FlowGraph::dependencies

source
fn FlowGraph::dependencies(self : FlowGraph) -> Array[Dependency]

Return a detached copy of dependency edges.

#
FlowGraph::dependencies_snapshot

source
fn FlowGraph::dependencies_snapshot(self : FlowGraph) -> Array[Dependency]

Return a detached copy of dependency edges.

#
FlowGraph::dependency_count

source
fn FlowGraph::dependency_count(self : FlowGraph) -> Int

Return the number of dependency edges.

#
FlowGraph::execution_batches

source
fn FlowGraph::execution_batches(self : FlowGraph) -> Result[Array[Array[TaskId]], GraphError]

Return parallel-ready batches. Tasks in the same batch have no dependencies between them.

#
FlowGraph::find_task

source
fn FlowGraph::find_task(self : FlowGraph, id : TaskId) -> TaskNode?

Find a task by id.

#
FlowGraph::from_workflow_json

source
fn FlowGraph::from_workflow_json(input : String) -> Result[FlowGraph, WorkflowSpecError]

Parse workflow-spec-v1 JSON and return a validated graph.

#
FlowGraph::leaves

source
fn FlowGraph::leaves(self : FlowGraph) -> Result[Array[TaskId], GraphError]

Return tasks with no outgoing dependency edges.

#
FlowGraph::new

source
fn FlowGraph::new() -> FlowGraph

Create an empty flow graph.

#
FlowGraph::plan

source
fn FlowGraph::plan(self : FlowGraph) -> Result[ExecutionPlan, GraphError]

Create a full execution plan.

#
FlowGraph::predecessors

source
fn FlowGraph::predecessors(self : FlowGraph, id : TaskId) -> Result[Array[TaskId], GraphError]

Return immediate predecessor ids for a task.

#
FlowGraph::ready_tasks

source
fn FlowGraph::ready_tasks(self : FlowGraph, done : Array[TaskId]) -> Result[Array[TaskId], GraphError]

Return tasks whose predecessors are all in done.

#
FlowGraph::roots

source
fn FlowGraph::roots(self : FlowGraph) -> Result[Array[TaskId], GraphError]

Return tasks with no incoming dependency edges.

#
FlowGraph::runnable_tasks

source
fn FlowGraph::runnable_tasks(self : FlowGraph) -> Result[Array[TaskId], GraphError]

Return pending or ready tasks whose predecessors have succeeded.

Failed or skipped predecessors block their successors. Callers that manage completion separately should continue using ready_tasks(done).

#
FlowGraph::snapshot

source
fn FlowGraph::snapshot(self : FlowGraph) -> FlowGraph

Return a detached copy of this graph and all task metadata arrays.

#
FlowGraph::snapshot_json

source
fn FlowGraph::snapshot_json(self : FlowGraph, trace : Trace) -> Result[String, SnapshotError]

Build a fresh plan, validate trace references, and render JSON.

#
FlowGraph::snapshot_markdown

source
fn FlowGraph::snapshot_markdown(self : FlowGraph, trace : Trace) -> Result[String, SnapshotError]

Build a fresh plan, validate trace references, and render Markdown.

#
FlowGraph::successors

source
fn FlowGraph::successors(self : FlowGraph, id : TaskId) -> Result[Array[TaskId], GraphError]

Return immediate successor ids for a task.

#
FlowGraph::task_count

source
fn FlowGraph::task_count(self : FlowGraph) -> Int

Return the number of task nodes.

#
FlowGraph::tasks

source
fn FlowGraph::tasks(self : FlowGraph) -> Array[TaskNode]

Return a detached copy of task nodes and their metadata arrays.

#
FlowGraph::tasks_snapshot

source
fn FlowGraph::tasks_snapshot(self : FlowGraph) -> Array[TaskNode]

Return a detached copy of task nodes and their metadata arrays.

#
FlowGraph::to_json

source
fn FlowGraph::to_json(self : FlowGraph, plan : ExecutionPlan, trace : Trace) -> String

Render a compact JSON string for tooling or snapshot artifacts.

This compatibility API trusts the supplied plan. New code should prefer to_json_checked or snapshot_json.

#
FlowGraph::to_json_checked

source
fn FlowGraph::to_json_checked(self : FlowGraph, plan : ExecutionPlan, trace : Trace) -> Result[String, SnapshotError]

Validate a supplied plan and trace before rendering JSON.

#
FlowGraph::to_markdown

source
fn FlowGraph::to_markdown(self : FlowGraph, plan : ExecutionPlan, trace : Trace) -> String

Render a graph, plan, and trace as a Markdown execution report.

This compatibility API trusts the supplied plan. New code should prefer to_markdown_checked or snapshot_markdown.

#
FlowGraph::to_markdown_checked

source
fn FlowGraph::to_markdown_checked(self : FlowGraph, plan : ExecutionPlan, trace : Trace) -> Result[String, SnapshotError]

Validate a supplied plan and trace before rendering Markdown.

#
FlowGraph::to_mermaid

source
fn FlowGraph::to_mermaid(self : FlowGraph) -> Result[String, GraphError]

Render a validated task graph as a Mermaid flowchart.

#
FlowGraph::to_workflow_spec

source
fn FlowGraph::to_workflow_spec(self : FlowGraph) -> WorkflowSpec

Convert a graph into workflow-spec-v1 input JSON semantics.

Runtime task status is intentionally not preserved in workflow specs.

#
FlowGraph::topological_sort

source
fn FlowGraph::topological_sort(self : FlowGraph) -> Result[Array[TaskId], GraphError]

Return a topological execution order.

#
FlowGraph::transition_status

source
fn FlowGraph::transition_status(self : FlowGraph, id : TaskId, status : TaskStatus) -> Result[Unit, StatusTransitionError]

Update a task through the documented execution-state machine.

update_status remains available for replay and compatibility. Normal execution should prefer this checked method.

#
FlowGraph::update_status

source
fn FlowGraph::update_status(self : FlowGraph, id : TaskId, status : TaskStatus) -> Result[Unit, GraphError]

Update the status of an existing task.

#
FlowGraph::validate

source
fn FlowGraph::validate(self : FlowGraph) -> Result[Unit, GraphError]

Validate all edge endpoints and cycle freedom.

#
FlowGraph::validate_plan

source
fn FlowGraph::validate_plan(self : FlowGraph, plan : ExecutionPlan) -> Result[Unit, SnapshotError]

Check that a plan still exactly matches the graph's deterministic plan.

#
FlowGraph::validate_snapshot

source
fn FlowGraph::validate_snapshot(self : FlowGraph, plan : ExecutionPlan, trace : Trace) -> Result[Unit, SnapshotError]

Check graph validity, plan freshness, and trace task references together.

#
FlowGraph::validate_trace

source
fn FlowGraph::validate_trace(self : FlowGraph, trace : Trace) -> Result[Unit, SnapshotError]

Check that every trace event refers to a task in this graph.

#
GraphError

source
pub(all) enum GraphError {
  DuplicateTask(TaskId)
  DuplicateDependency(Dependency)
  MissingTask(TaskId)
  MissingDependencyEndpoint(Dependency)
  CycleDetected(Array[TaskId])
} derive(Eq, 
Debug)

Graph errors retain the ids and edges needed for useful diagnostics.

#
GraphError::message

source
fn GraphError::message(self : GraphError) -> String

Return a readable diagnostic message for a graph error.

#
RunSnapshot

source
pub struct RunSnapshot {
  // private fields
} derive(
Debug)

A validated run-snapshot-v1 artifact containing graph, plan, and trace data.

#
RunSnapshot::audit

source
fn RunSnapshot::audit(self : RunSnapshot) -> Result[Unit, RunSnapshotError]

Validate graph structure, serialized plan, trace references, and lifecycle.

#
RunSnapshot::from_json

source
fn RunSnapshot::from_json(input : String) -> Result[RunSnapshot, RunSnapshotError]

Parse and audit a run-snapshot-v1 JSON string.

#
RunSnapshot::graph

source
fn RunSnapshot::graph(self : RunSnapshot) -> FlowGraph

Return a detached graph copy.

#
RunSnapshot::plan

source

Return a detached execution-plan copy.

#
RunSnapshot::to_json

source
fn RunSnapshot::to_json(self : RunSnapshot) -> String

Render this audited snapshot in canonical run-snapshot-v1 form.

#
RunSnapshot::trace

source
fn RunSnapshot::trace(self : RunSnapshot) -> Trace

Return a detached trace copy.

#
RunSnapshotError

source
pub(all) enum RunSnapshotError {
  InvalidRunSnapshotJson(String)
  UnsupportedRunSnapshotSchema(String)
  MissingRunSnapshotField(String)
  InvalidRunSnapshotField(String)
  RunSnapshotGraphError(GraphError)
  RunSnapshotPlanMismatch
  RunSnapshotUnknownTraceTask(TaskId)
  InvalidTraceLifecycle(TaskId, TraceEventType)
  RunSnapshotStatusMismatch(TaskId, TaskStatus, String)
} derive(Eq, 
Debug)

Errors raised while parsing or auditing run-snapshot-v1 JSON.

#
RunSnapshotError::message

source
fn RunSnapshotError::message(self : RunSnapshotError) -> String

Return a readable diagnostic for snapshot import and audit errors.

#
SnapshotError

source
pub(all) enum SnapshotError {
  SnapshotGraphError(GraphError)
  StaleExecutionPlan
  UnknownTraceTask(TaskId)
} derive(Eq, 
Debug)

Errors raised when a plan or trace no longer matches its graph.

#
SnapshotError::message

source
fn SnapshotError::message(self : SnapshotError) -> String

Return a readable diagnostic for snapshot validation.

#
StatusTransitionError

source
pub(all) enum StatusTransitionError {
  TransitionMissingTask(TaskId)
  InvalidStatusTransition(TaskId, TaskStatus, TaskStatus)
} derive(Eq, 
Debug)

Errors raised by checked task-status transitions.

#
StatusTransitionError::message

source
fn StatusTransitionError::message(self : StatusTransitionError) -> String

Return a readable diagnostic for a checked status transition.

#
TaskId

source
pub struct TaskId {
  // private fields
} derive(Eq, 
Debug)

Task identifier used by the public graph API.

#
TaskId::new

source
fn TaskId::new(value : String) -> TaskId

Build a task id.

#
TaskId::value

source
fn TaskId::value(self : TaskId) -> String

Return the raw string value of this task id.

#
TaskNode

source
pub struct TaskNode {
  // private fields
} derive(Eq, 
Debug)

A node in a reproducible research or agent workflow.

#
TaskNode::description

source
fn TaskNode::description(self : TaskNode) -> String

Return this task's description.

#
TaskNode::id

source
fn TaskNode::id(self : TaskNode) -> TaskId

Return this task's id.

#
TaskNode::inputs

source
fn TaskNode::inputs(self : TaskNode) -> Array[String]

Return a detached copy of this task's input labels.

#
TaskNode::new

source
fn TaskNode::new(id : String, title : String) -> TaskNode

Build a basic pending task.

#
TaskNode::outputs

source
fn TaskNode::outputs(self : TaskNode) -> Array[String]

Return a detached copy of this task's output labels.

#
TaskNode::snapshot

source
fn TaskNode::snapshot(self : TaskNode) -> TaskNode

Return a detached copy of a task node and its metadata arrays.

#
TaskNode::status

source
fn TaskNode::status(self : TaskNode) -> TaskStatus

Return this task's execution status.

#
TaskNode::tags

source
fn TaskNode::tags(self : TaskNode) -> Array[String]

Return a detached copy of this task's tags.

#
TaskNode::title

source
fn TaskNode::title(self : TaskNode) -> String

Return this task's title.

#
TaskNode::with_description

source
fn TaskNode::with_description(self : TaskNode, description : String) -> TaskNode

Add a short description.

#
TaskNode::with_inputs

source
fn TaskNode::with_inputs(self : TaskNode, inputs : Array[String]) -> TaskNode

Add input labels or artifacts.

#
TaskNode::with_outputs

source
fn TaskNode::with_outputs(self : TaskNode, outputs : Array[String]) -> TaskNode

Add output labels or artifacts.

#
TaskNode::with_status

source
fn TaskNode::with_status(self : TaskNode, status : TaskStatus) -> TaskNode

Override status.

#
TaskNode::with_tags

source
fn TaskNode::with_tags(self : TaskNode, tags : Array[String]) -> TaskNode

Add topic tags.

#
TaskStatus

source
pub(all) enum TaskStatus {
  Pending
  Ready
  Running
  Succeeded
  Failed(String)
  Skipped(String)
} derive(Eq, 
Debug)

Execution status tracked for each task node.

#
TaskStatus::can_transition_to

source
fn TaskStatus::can_transition_to(self : TaskStatus, next : TaskStatus) -> Bool

Return whether a status transition is valid for normal execution.

#
TaskStatus::kind

source
fn TaskStatus::kind(self : TaskStatus) -> String

Return a stable machine-readable status kind without an error reason.

#
TaskStatus::label

source
fn TaskStatus::label(self : TaskStatus) -> String

Return a stable human-readable task status label.

#
TaskStatus::reason

source
fn TaskStatus::reason(self : TaskStatus) -> String?

Return the reason attached to a failed or skipped status.

#
Trace

source
pub struct Trace {
  // private fields
} derive(
Debug)

Mutable trace log.

#
Trace::event_count

source
fn Trace::event_count(self : Trace) -> Int

Return the number of recorded events.

#
Trace::events

source
fn Trace::events(self : Trace) -> Array[TraceEvent]

Return a detached copy of events in append order.

#
Trace::events_for

source
fn Trace::events_for(self : Trace, task_id : TaskId) -> Array[TraceEvent]

Return events for a single task id in append order.

#
Trace::events_snapshot

source
fn Trace::events_snapshot(self : Trace) -> Array[TraceEvent]

Return a detached copy of events in append order.

#
Trace::latest_for

source
fn Trace::latest_for(self : Trace, task_id : TaskId) -> TraceEvent?

Return the most recently appended event for a task.

#
Trace::new

source
fn Trace::new() -> Trace

Build an empty trace log.

#
Trace::record

source
fn Trace::record(self : Trace, event : TraceEvent) -> Unit

Append an event.

#
Trace::snapshot

source
fn Trace::snapshot(self : Trace) -> Trace

Return a detached copy of this trace log.

#
Trace::summary_markdown

source
fn Trace::summary_markdown(self : Trace) -> String

Render a compact Markdown summary of trace events.

#
TraceEvent

source
pub struct TraceEvent {
  // private fields
} derive(Eq, 
Debug)

A single trace event. Timestamp is a string so users can choose wall-clock, logical, or deterministic timestamps.

#
TraceEvent::event_type

source
fn TraceEvent::event_type(self : TraceEvent) -> TraceEventType

Return this event's type.

#
TraceEvent::message

source
fn TraceEvent::message(self : TraceEvent) -> String

Return this event's human-readable message.

#
TraceEvent::new

source
fn TraceEvent::new(task_id : TaskId, event_type : TraceEventType, message : String, timestamp : String) -> TraceEvent

Build a trace event.

#
TraceEvent::task_id

source
fn TraceEvent::task_id(self : TraceEvent) -> TaskId

Return the task id associated with this event.

#
TraceEvent::timestamp

source
fn TraceEvent::timestamp(self : TraceEvent) -> String

Return this event's timestamp string.

#
TraceEventType

source
pub(all) enum TraceEventType {
  Planned
  Started
  Completed
  FailedEvent
  SkippedEvent
  Note
} derive(Eq, 
Debug)

Event type for provenance trace.

#
TraceEventType::label

source
fn TraceEventType::label(self : TraceEventType) -> String

Return a stable human-readable event type label.

#
WorkflowSpec

source
pub struct WorkflowSpec {
  // private fields
} derive(Eq, 
Debug)

Workflow input definition, separated from run-snapshot JSON output.

#
WorkflowSpec::dependencies

source
fn WorkflowSpec::dependencies(self : WorkflowSpec) -> Array[Dependency]

Return a detached copy of workflow dependency edges.

#
WorkflowSpec::from_json

source
fn WorkflowSpec::from_json(input : String) -> Result[WorkflowSpec, WorkflowSpecError]

Parse, type-check, and validate a workflow-spec-v1 JSON string.

#
WorkflowSpec::new

source
fn WorkflowSpec::new(tasks : Array[WorkflowTaskSpec], dependencies : Array[Dependency]) -> WorkflowSpec

Build a workflow spec from tasks and dependency edges.

#
WorkflowSpec::tasks

source

Return a detached copy of workflow task specs.

#
WorkflowSpec::to_graph

source
fn WorkflowSpec::to_graph(self : WorkflowSpec) -> Result[FlowGraph, GraphError]

Convert this workflow definition into a validated flow graph.

#
WorkflowSpec::to_json

source
fn WorkflowSpec::to_json(self : WorkflowSpec) -> String

Render this workflow spec as workflow-spec-v1 JSON.

#
WorkflowSpecError

source
pub(all) enum WorkflowSpecError {
  InvalidWorkflowJson(String)
  UnsupportedWorkflowSchema(String)
  MissingWorkflowField(String)
  InvalidWorkflowField(String)
  WorkflowGraphError(GraphError)
} derive(Eq, 
Debug)

Errors raised while parsing and validating workflow-spec-v1 JSON.

#
WorkflowSpecError::message

source
fn WorkflowSpecError::message(self : WorkflowSpecError) -> String

Return a readable diagnostic for workflow spec errors.

#
WorkflowTaskSpec

source
pub struct WorkflowTaskSpec {
  // private fields
} derive(Eq, 
Debug)

A task definition in workflow-spec-v1 input JSON.

Unlike TaskNode, this type models user-supplied workflow structure and does not carry runtime execution status.

#
WorkflowTaskSpec::description

source
fn WorkflowTaskSpec::description(self : WorkflowTaskSpec) -> String

Return this workflow task description.

#
WorkflowTaskSpec::id

source

Return this workflow task id.

#
WorkflowTaskSpec::inputs

source
fn WorkflowTaskSpec::inputs(self : WorkflowTaskSpec) -> Array[String]

Return a detached copy of this workflow task's input labels.

#
WorkflowTaskSpec::new

source
fn WorkflowTaskSpec::new(id : String, title : String) -> WorkflowTaskSpec

Build a workflow task spec.

#
WorkflowTaskSpec::outputs

source
fn WorkflowTaskSpec::outputs(self : WorkflowTaskSpec) -> Array[String]

Return a detached copy of this workflow task's output labels.

#
WorkflowTaskSpec::snapshot

source

Return a detached copy of a workflow task spec.

#
WorkflowTaskSpec::tags

source
fn WorkflowTaskSpec::tags(self : WorkflowTaskSpec) -> Array[String]

Return a detached copy of this workflow task's tags.

#
WorkflowTaskSpec::title

source
fn WorkflowTaskSpec::title(self : WorkflowTaskSpec) -> String

Return this workflow task title.

#
WorkflowTaskSpec::with_description

source
fn WorkflowTaskSpec::with_description(self : WorkflowTaskSpec, description : String) -> WorkflowTaskSpec

Add a short description to a workflow task spec.

#
WorkflowTaskSpec::with_inputs

source
fn WorkflowTaskSpec::with_inputs(self : WorkflowTaskSpec, inputs : Array[String]) -> WorkflowTaskSpec

Add input labels or artifacts to a workflow task spec.

#
WorkflowTaskSpec::with_outputs

source
fn WorkflowTaskSpec::with_outputs(self : WorkflowTaskSpec, outputs : Array[String]) -> WorkflowTaskSpec

Add output labels or artifacts to a workflow task spec.

#
WorkflowTaskSpec::with_tags

source
fn WorkflowTaskSpec::with_tags(self : WorkflowTaskSpec, tags : Array[String]) -> WorkflowTaskSpec

Add topic tags to a workflow task spec.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io