# Create and run the first BLOGE graph

## When to use

Use this task when a Java project already chose BLOGE and needs its first `.bloge` graph or an equivalent fluent graph. Stop and revisit selection if the work is one local call with no meaningful dependency, branching, resilience, waiting, or recovery requirement.

## Inspect first

- Read the effective BLOGE version from Maven rather than assuming the newest release.
- Find the project's Operator registry or Spring `@BlogeOperator` components.
- Identify one business input, one Operator, and one observable output.
- Read [Chapter 2](/en/v/0.9.8-RC1/02-your-first-graph) and the [minimal graph asset](/assets/v/0.9.8-RC1/chapters/02-your-first-graph/assets/head-first-bloge-examples/src/main/resources/bloge/ch02/hello-world.bloge).

## Required inputs

Obtain the graph name, input field and type, Operator contract, timeout expectation, and the output the caller must observe. Do not invent a business default or fallback.

## Implementation path

1. Add one graph with one named node and an explicit Operator type.
2. Bind the node input from `ctx` rather than reading hidden global state.
3. Give the node a bounded timeout appropriate to the Operator contract.
4. Register the Operator through the project's existing mechanism.
5. Execute with a `GraphContext` and assert the result through `GraphResult`.
6. Add a second node only when a real dependency or transformation needs to be visible.

Minimal DSL shape:

```bloge
graph helloWorld {
  node echo : EchoOperator {
    input { message = ctx.message }
    timeout = 1s
  }
}
```

## MUST / SHOULD / MAY

- **MUST** keep graph inputs and node dependencies explicit.
- **MUST** use a registered Operator type; a node name alone is not executable.
- **MUST** add an observable success assertion and one failure assertion.
- **SHOULD** keep business logic in Operators and orchestration shape in the graph.
- **SHOULD** prefer the existing DSL or fluent style in the target module.
- **MAY** use a one-node graph as a learning or integration seam; do not claim it proves production topology.

## Failure patterns

- Missing Operator binding: compilation or loading fails. Register the Operator or fix the declared type; do not switch validation off to hide the error.
- Missing context field: input binding cannot produce the Operator input. Fix the caller contract or mapping.
- Graph compiles but has no assertion: add a test that inspects the node output and terminal graph state.

## Validation

Run the smallest test that loads and executes this graph, then the target module tests. Run the full reactor only when the repository contract or shared-module change requires it. Report each scope separately; `Tests run: 0` and skipped tests are not green evidence.

## Evidence

- [Chapter 2](/en/v/0.9.8-RC1/02-your-first-graph)
- [Chapter 3](/en/v/0.9.8-RC1/03-thinking-in-dependencies)
- [Pinned BLOGE core source](https://github.com/xbdotl/bloge/tree/cc38fbe5bb79ccc603888e4307cfe566d4674ffc/bloge-core)
- [Chapter-owned graph](/assets/v/0.9.8-RC1/chapters/02-your-first-graph/assets/head-first-bloge-examples/src/main/resources/bloge/ch02/hello-world.bloge)