Package Surfaces

A package surface is package-owned software with a YAML boundary.

Zinc owns the call shape. The package owns behavior.

Manifest entry

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

A surface currently provides either:

python: surfaces/run.py

or:

command: ./run

Optional fields include args, cwd, and env.

When a shape entry names surface, Zinc builds YAML for stdin:

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

Other host fields pass through as package-owned request fields.

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

Package stdout is direct YAML fields:

answer: |
  Zinc runs package surfaces from Circuitry value flow.

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

package.surface

The package part resolves an installed package. The surface part selects a manifest surface.