Introduction

Document purpose

Chef Courier enables operational workflows to be expressed as structured jobs composed of discrete steps. Each step delegates its work to an interpreter. Interpreters are therefore the primary interface through which users interact with execution capabilities inside Courier.

While the Courier Interpreter RFC precisely defines how interpreters are invoked and what the input and output contracts look like at a transport and lifecycle level, it intentionally doesn’t prescribe how interpreters should be designed or what constitutes a good interpreter experience.

This documentation exists to fill that gap.

Its purpose is to establish a shared, external understanding of:

• What a Courier interpreter is and isn’t
• How interpreters constrain and express user intent
• How interpreter contracts should be shaped, validated, and evolved
• How interpreters should behave to provide consistent, predictable outcomes
• How to reason about interpreters using familiar mental models

This guide treats interpreters not merely as executables, but as long-lived contracts that users, automation, and workflows depend on.

Intended audience

This documentation is intended for two primary audiences:

• Advanced Courier users and job authors who compose jobs using interpreters and need to understand what interpreters promise, how they behave, and what guarantees they provide over time. For these readers, the guide describes the expectations they can rely on when selecting and using interpreters as part of operational workflows.

• Interpreter designers and implementers who are extending Chef Courier by building new interpreters or evolving existing ones. For these readers, the guide defines the design principles, contract-shaping guidance, and behavioral constraints that must be honored to meet user expectations and maintain a consistent Courier ecosystem.

The documentation assumes familiarity with Chef Courier concepts and focuses on interpreter design and usage at the contract level rather than introductory material.

Scope and non-goals

This documentation focuses on the design, behavior, and user-facing contract of Courier interpreters.

In scope:

• Conceptual definitions and terminology related to Courier interpreters
• The responsibilities and boundaries of interpreters from both user and implementer perspectives
• Principles for designing interpreter command contracts that are stable, expressive, and constrained
• Mental models for understanding Courier jobs and interpreters in both technical and non-technical contexts
• Behavioral expectations, stability rules, and common anti-patterns

Out-of-scope:

• The Courier job definition language and schema
• The internal implementation of the Courier Runner
• Wire-level transport details, process invocation semantics, or lifecycle enforcement
• Exhaustive command schemas or catalogs for specific interpreters
• Language-specific or engine-specific implementation details, except where noted as non-normative guidance

This documentation isn’t a replacement for the Courier Interpreter RFC. For normative definitions of interpreter invocation, lifecycle, and input/output contracts, readers must refer to the Courier Interpreter RFC, which remains the authoritative specification for protocol and enforcement behavior.