How execution works¶
Zeroshot keeps control flow separate from model behavior through a caller-authored graph. After admission, the engine runs an executable node and checks its typed output; state reduction records that output before choosing the next edge.
The run boundary¶
A submission contains four pieces of caller-owned data:
| Input | Purpose |
|---|---|
| Title | Human-readable identity for lists and status output |
| Graph | Nodes, state, transitions, bounds, and terminal results |
| Initial input | The unchanged value checked against the graph's declared input type |
| Runtime plan | Harness, provider, model, session scope, and named connection requirements |
For inline graphs and built-in templates, Zeroshot completes admission before it starts a local
controller or contacts a target. The CLI first fetches a target-stored profile, then sends its graph
and runtime through the same checks. Those checks cover schema shape, graph semantics, bounds,
runtime bindings, and the initial input; --validate-only runs them without creating a run.
Graph nodes¶
Executable nodes are step and verifier. Groups compose them:
| Group | Behavior |
|---|---|
seq |
Evaluates children in order |
choice |
Selects an authored branch from typed control signals |
par |
Runs branches concurrently and joins them by an authored rule |
loop |
Provides a bounded do-while structure |
map |
Applies a bounded body to array items |
succeed and fail |
End the graph |
Selectors, guards, and bindings are structured data. They are not snippets of JavaScript, JSONPath, shell code, or prompt text. Full field rules live in the graph contract.
Concurrent workspace changes¶
par branches and map items can run multiple writing agents at once. Writers share the run's
workspace, so the graph and agent instructions must coordinate edits to the same files. Hosted
verifiers work in disposable copies; copying while a writer is active does not provide an atomic
snapshot. Place verification after the writers when it needs their completed changes.
Sequence Git delivery after the writing branches or map have joined. Graph validation rejects parallel delivery and writing, including delivery in a map that can have multiple items. Delivery can run alongside read-only verifiers. A delivery receipt can certify run success only when every other writer settled before that delivery execution started.
State reduction chooses the next step¶
An agent returns a value through a declared output channel. Zeroshot checks that value, applies authored bindings, and records the new state before it evaluates another node. Model output cannot add an edge or raise a bound.
Inside a repair loop, a reviewer emits a finite signal with a typed diagnostic. The graph routes that
signal to success or another iteration, and maxIterations still applies if an agent asks to
continue.
Durable run state¶
Each run has a public ID backed by a SQLite ledger. Status and safe-log events carry opaque cursors
for strict resume, so detaching a client, losing a terminal, or cancelling a Python await does not
stop the controller.
When a run closes, Zeroshot atomically closes its execution activity; a late process cannot appear after the terminal result. Observe and control runs covers the read and stop commands.
Built-in templates are ordinary graphs¶
The executable contains single-worker and software-change, and both produce the public
GraphSpec that custom submissions use:
software-change adds pull-request or merge delivery through --pr or --ship. That delivery is a
graph node with its own runtime binding rather than an unrecorded agent side effect.