Validation and parsing

This section defines the validation responsibilities and command parsing requirements for interpreters invoked by the Courier Runner. Validation is intentionally split across two layers: Runner-level envelope validation and Interpreter-level command validation.

Validation model overview

Validation of an interpreter invocation occurs in two distinct phases:

Runner validation: The Courier Runner validates the interpreter invocation envelope, including interpreter selection, version compatibility, job context inputs, and execution constraints.
Interpreter validation: The interpreter validates the interpreter-specific command payload and any interpreter-defined semantics prior to execution.

Failure at either stage MUST result in interpreter failure signaling as defined in the Interpreter output contract and Variable substitution and inputs sections.

Runner-level validation

Before invoking an interpreter, the Courier Runner MUST validate the following envelope-level fields:

Interpreter identity (name)
Skill and interpreter version compatibility (skill, minVersion, and maxVersion)
Availability of required job context variables declared through expectedInputs
Execution constraints (limits, and accessMode)
Structural validity of the invocation contract as JSON

If Runner-level validation fails, the interpreter MUST NOT be invoked. The Runner MUST record the failure according to job failure semantics.

The Runner MUST NOT attempt to interpret or validate the internal structure of the command field beyond ensuring it’s valid JSON.

Interpreter-level validation

Upon receiving an invocation, the interpreter MUST validate the command field according to its published interpreter contract (refer to the Interpreter discovery section for further details).

Interpreter-level validation MUST include, at a minimum:

Structural validation of the command payload
Presence of required command fields
Type validation of command values
Validation of referenced inputs after variable substitution

If validation fails, the interpreter:

MUST return a non-zero status in the Interpreter Output Contract
SHOULD populate the error field with a human-readable description of the validation failure
MAY include structured validation diagnostics in the output object

Variable substitution and inputs

The Courier Runner MAY perform variable substitution using the inputs map prior to interpreter invocation. Interpreters MUST NOT assume that unresolved template placeholders will be substituted automatically.

If an interpreter encounters unresolved or invalid variable references during parsing or execution, it MUST treat this as a validation failure.

Interpreters SHOULD clearly distinguish between:

Validation failures (invalid or missing inputs)
Execution failures (runtime errors after validation)

Failure signaling

Any validation failure, whether at the Runner or interpreter level, MUST result in interpreter failure signaling as defined in the Interpreter output contract section:

The Interpreter Output Contract MUST include a non-zero status
The interpreter process exit code SHOULD match the status value
Partial or diagnostic output MAY be included in the output object

Validation failures MUST NOT be reported as successful executions.

Idempotency and validation

Validation MUST be side-effect free. Interpreters MUST NOT perform irreversible actions during command parsing or validation.

Any state mutation, external calls, or resource modification MUST occur only after validation has completed successfully.