# build_program

> Compiles a Program node's Rust source and stamps the built module on the node as a new version.

Source: https://orbitalaip.com/docs/claude-and-chatgpt/tools/build_program

Build a Program · strategies · write

> [!IMPORTANT] Disclaimer
> Backtest results are hypothetical and do not predict future performance. Nothing here is investment advice: Orbital computes the rules you supplied and recommends nothing. Orbital is not a registered investment adviser or broker-dealer. Costs are as modelled by the chosen cost profile and may differ from live trading.

## What it does

Compiles the Rust source of a Program node and writes the built module's reference onto the node, as a new version of the strategy. The builder's stage and diagnostics come back verbatim: a compile error is an answer with the failing line, not a dead end. Claude calls it after [get_authoring_guide](https://orbitalaip.com/docs/claude-and-chatgpt/tools/get_authoring_guide) with topic `program` and after [create_strategy](https://orbitalaip.com/docs/claude-and-chatgpt/tools/create_strategy). It is not for rule-card strategies.

The Program node must be saved first, with `decision_timeframe`, `warmup_bars` and `parameters` set, in a graph saved with `allow_incomplete_config` true. The build reads `warmup_bars` off the saved node and refuses without it. Claude never sends that number itself, so the module and the run agree on how much history the program reads.

A build also runs the program over three synthetic tapes and returns that as `check`. `warnings` says where the check and the node disagree: a fuel budget set too low, a program that fired on neither flat tape, or node parameters the module never reads. The source Claude builds is stored on the node, so Orbital's editor shows what runs.

It needs the write permission, shown on the consent page as **Create and edit strategies**, and a project role that may write: project owner, editor or member, or workspace owner or admin. A viewer's call is refused: a read-only role cannot use write or run tools. A strategy deployed to alerts, a paper account or a live account may not be rebuilt while that deployment runs.

One caveat: a run refuses the program when its source changes without a rebuild. After any edit to the source, Claude builds again before it estimates or runs.

## Parameters

| Parameter | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| workflow_id | string | yes | The strategy's workflow id, a UUID: createdWorkflowId from the create receipt, or strategy.workflowId from get_strategy. | 0193c2a1-5b7e-7f10-9c3d-2a6b8e4f1d07 |
| node_id | string | yes | The Program node's id in the graph. | prog |
| source | string | yes | The Rust source to build. It must not be empty. | #![no_std] use orbital_strategy::{close, enter_long, exit, is_flat}; … |
| language | string | no | The source language. Defaults to rust, the only language Orbital compiles. | rust |

## What comes back

- `ok`: true when a module was built, false when the build stopped.

- `stage`: `built`, or where it stopped: `engine`, `tooling`, `refused`, `compile`, `admission` or `check`.

- `note`: what happened, in words. On success it names the module the node now carries and says a changed source needs a rebuild. On a failure it is the builder's refusal, the check's failure, or "The build did not produce a module. Read the diagnostics and fix the source."

- `moduleRef`: the module reference now stamped on the node, `sha256:` followed by 64 hex digits.

- `byteLen` and `abiVersion`: the module's size and the host interface version it was built against.

- `sourceHash` and `builtAt`: the digest of the source that was sent, built or not, and when it was built.

- `diagnostics`: the compiler's messages, each with `level`, `message`, `line`, `column` and the `rendered` text, when there are any.

- `refusal`: the builder's `class` and `sentence` when it refused the source.

- `check`: the run-once check: a `verdict` and the `scenarios`, each with `position`, `decided`, `firing_bars`, `fuel_max` and `failure`.

- `imports`: the host functions the module links.

- `warnings`: where the check and the node disagree, each as a sentence.

## Try saying

- "Write a Rust program that buys the top three 20-day momentum names each day and test it on these ten tickers."
- "Build the program again with the lookback read from a parameter."
- "The build failed on line 14. Fix it and rebuild."

## If it fails

- **build_program needs the 'write' scope, which this connection was not granted. Ask the user to reconnect Orbital with it.** — The connection was made without the Create and edit strategies permission. Connect Orbital again and leave that permission on.
- **Your role in this project (viewer) cannot change strategies or spend credits.** — Your role in the connected project is read-only. The message names the role it found. Ask a project owner for a role that may write, or use the read tools.
- **Backtesting is not active in this project — turn it on under Settings → Apps in Orbital, then try again** — The Backtesting app is off in the project you connected. In Orbital open Settings, then Apps, and turn Backtesting on for the project you connected.
- **The source is empty — there is nothing to build.** — Claude sent an empty source string. Claude sends the whole program.
- **No workflow <workflow_id> in this project. List them with list_strategies.** — The workflow id is wrong, names a strategy id instead, or the workflow is archived or in Orbital's trash. Claude takes the workflow id from the create receipt or from get_strategy.
- **No node <node_id> in workflow <workflow_id>. Read it back with get_strategy.** — No node in the graph has that id. Claude reads the strategy and uses the Program node's id as saved.
- **Node <node_id> is a <type>, not a Program — only a Program node has source to build.** — The id names a node of another type. Claude names the Program node.
- **Node <node_id> has no "History the program reads" (warmup_bars) set. It is the deepest bar offset your source will ask for, and the host allocates exactly that much — set it on the node first, then build.** — The saved Program node has no numeric warmup_bars. Claude saves the node with warmup_bars set to the deepest bar offset the program reads, then builds.
- **Workflow <workflow_id> is deployed to a paper account (<status>), so it may not change while that deployment runs. Branch it in Orbital and change the branch instead.** — The strategy is deployed to alerts, a paper account or a live account, and a build would change what runs. The message names the target and the deployment's status. Stop the deployment first (alerts in Backtesting, a paper or live account in Trade), then build, or create a new strategy and build that.
- **language must be one of rust — the only language the engine compiles today.** — language was set to something other than rust. Claude sends rust or omits the field.
- **The source compiled, but the module failed its run-once check: <failure>** — The program built but trapped or broke a rule on one of the check tapes, such as a stop set while flat or a read deeper than warmup_bars. The result's stage is check. Claude reads the check's failure, fixes the source and builds again.
- **The build did not produce a module. Read the diagnostics and fix the source.** — The source did not compile. The result's stage says where it stopped, and diagnostics carry each compiler message with its line. Claude fixes the lines the diagnostics name and builds again.
- **The build did not finish within this side’s 60-second budget. The engine is still compiling and will store the module when it is done — build the same source again in a minute and it will answer at once.** — The build took longer than a minute. The result's stage is engine. Claude builds the same source again a minute later.
- **The backtesting engine is not configured on this deployment, so nothing can be built.** — The deployment has no backtesting engine. The result's stage is engine. Nothing on your side. Contact Orbital support.
- **The program could not be built.** — The build failed for a reason that carried no message of its own. Ask Claude to try again. If it keeps failing, build the program in Orbital's editor.

## Related

- [Read the authoring guide](https://orbitalaip.com/docs/claude-and-chatgpt/tools/get_authoring_guide)
- [Create a strategy](https://orbitalaip.com/docs/claude-and-chatgpt/tools/create_strategy)
- [Estimate a backtest](https://orbitalaip.com/docs/claude-and-chatgpt/tools/estimate_backtest)
- [Rule cards and Programs](https://orbitalaip.com/docs/claude-and-chatgpt/rule-cards-and-programs)