Package Surfaces

A package surface is a package-owned program that receives YAML on stdin and returns YAML on stdout.

Zinc owns the call contract. The package owns the behavior.

Surface manifest

surfaces:
  bash:
    about: Run one Bash command through package policy.
    python: surfaces/run.py

Today a surface must provide either:

python: surfaces/run.py

or:

command: ./run

Optional surface fields include args, cwd, and env.

When a Circuitry entry names surface, Zinc builds a YAML request:

surface: unix-bash.bash
in:
  command: pwd
out:
  output: $output
  exit: $exit

Any other host fields on the entry are passed through as package-owned request fields:

answer:
  surface: openai-responses.responses
  model: local-llama
  in:
    question: What is Zinc?
  out:
    answer: $answer

The package receives:

surface: openai-responses.responses
model: local-llama
in:
  question: What is Zinc?
out:
  answer: $answer

Package stdout must be direct YAML fields. Zinc does not expect a wrapper such as output: or exit: around the response.

answer: |
  Zinc coordinates Circuitry execution through package surfaces.

Zinc maps only the fields requested by the Circuitry entry. Missing requested fields fail the entry.

package.surface

The package part resolves an installed package. The surface part selects an entry under surfaces in that package manifest.