Taurus Development Guide

This guide is for contributors working on Taurus itself. It documents how Taurus is structured, how execution flows through the runtime, and how to run and test changes locally.

What Taurus Does

Taurus is the execution runtime in the CodeZero execution block.

• Consumes flow execution requests from NATS (execution.*)
• Executes flow graphs via taurus-core::runtime::engine::ExecutionEngine
• Emits lifecycle events to NATS (runtime.emitter.<execution_id>)
• Delegates remote nodes to external services over NATS (action.<service>.<execution_id>)
• Reports runtime status and execution results to Aquila in dynamic mode

Workspace Layout

Runtime Flow

Execution details

1. Taurus subscribes to queue subject execution.* with queue group taurus.
2. Incoming payload is decoded as tucana::shared::ExecutionFlow.
3. ExecutionEngine::execute_flow_with_execution_id(...) compiles and executes nodes.
4. Local nodes run handlers from the built-in function registry.
5. Non-local definition_source values are executed remotely via RemoteRuntime.
6. Lifecycle events are emitted as starting, ongoing, finished, or failed.
7. The completed ExecutionResult is transmitted through the Aquila execution gRPC API in dynamic mode.

Runtime Modes

Taurus mode is controlled by MODE.

dynamic

dynamic enables control-plane integrations:

• Sends definitions to Aquila (retry loop until success)
• Starts runtime status reporting (including heartbeat)
• Sends execution result updates after each flow run

static

static disables those control-plane interactions.

• Taurus still executes flows from NATS
• No definition push
• No runtime status updates
• No execution result updates

Environment Variables

Defaults are defined in crates/taurus/src/config/mod.rs.

Local Development

1. Start dependencies

At minimum, start a reachable NATS instance at NATS_URL.

2. Configure environment

Create .env in the repository root (you can copy from .env-example and extend it).

3. Run Taurus

cargo run -p taurus

4. Run the execution suite

cargo run -p tests

This executes all JSON files in ./flows and compares runtime outputs.

5. Run one flow manually

cargo run -p manual -- --path ./flows/01_return_object.json --index 0 --nats-url nats://127.0.0.1:4222

This is useful when debugging one case or remote-execution behavior.

Testing

• Core unit/integration tests:

cargo test -p taurus-core

• Full workspace checks (recommended before merge):

cargo test

Extending Taurus

Add or modify built-in functions

• Implement handler logic in crates/taurus-core/src/runtime/functions/*
• Register function IDs via the FUNCTIONS arrays
• Registration is aggregated through ALL_FUNCTION_SETS in runtime/functions/mod.rs

Remote execution routing rule

In the compiler, a node is treated as local when definition_source is:

• empty
• taurus
• prefixed with draco

Any other source is routed as remote execution to that service name.