Executor

Executor

The executor runs Circuitry entries whose host fields include surface.

It does not own provider behavior, shell policy, prompt meaning, or response meaning.

Per executable entry

Zinc:

1. reads surface
2. resolves the installed package surface
3. builds a YAML request
4. invokes the package process
5. selects requested response fields
6. writes those fields into active run values
7. records the ready wave as a step

Ready waves

An entry is ready when all referenced inputs exist. Zinc runs ready entries in waves. runtime.parallel limits how many entries may run in one wave.

left:
  surface: unix-bash.bash
  in:
    command: $a
  out:
    output: $left

final:
  surface: unix-bash.bash
  in:
    left: $left
  out:
    output: $done

final waits for $left.

Run sources

zn run file.circuitry.yaml
zn run file.circuitry.md
zn run zinc://packages/zinc-chat/files/shapes/chat.circuitry.yaml
cat graph.circuitry.yaml | zn run -
cat graph.circuitry.yaml | zn run --report -

--report adds run and step refs around normal output.

Package-owned orchestration

Packages may call Zinc with generated shapes:

cat generated.circuitry.yaml | zn run --report -

Zinc remains the runner. The package owns the loop.

Run navigation

zn run - in zinc://runs/<id>
zn run - from zinc://steps/<id>
zn set zinc://runs/<id>/current zinc://steps/<id>

in appends to a run. from forks from a step. set moves the run's current pointer.

History

Zinc records:

run  = execution thread
step = one ready wave
packet = YAML bytes