Executor

Executor

The executor advances Circuitry entries whose host fields include surface.

It does not own provider behavior, shell policy, prompt meaning, or response meaning. It only prepares the package call and routes the YAML result.

What Zinc does

For each executable entry, Zinc:

1. reads surface from the entry
2. resolves the installed package and surface
3. builds a YAML request from entry fields, recursively resolved $value references, in, and out
4. invokes the package surface
5. selects requested response fields from package stdout
6. writes those fields back into the active run values
7. records the event and packet history

Ready waves

Zinc keeps active run values in memory while a shape runs.

An entry is ready when every input it references is already present. Zinc advances ready entries in waves. runtime.parallel controls how many ready entries may run at once in a wave.

Dependent entries wait:

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

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

final cannot run until left exists.

Run sources

zn run accepts local YAML, Markdown front matter, package references, and stdin:

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 emits structured YAML for package-owned orchestration while normal zn run keeps direct shape output.

Events

Every surface invocation is recorded in ~/.zinc/zinc.db as an event. The event points at request, response, and selected-output packets.