Interpreter life-cycle

Invocation

Each job step results in exactly one interpreter invocation. Interpreters MUST accept input exclusively through standard input (stdin) and MUST NOT require command‑line arguments or environment variables to convey step‑specific data. If an interpreter supports multiple command types, the actual command is selected through the JSON payload rather than through different executables.

Execution duration

Interpreters MAY run for any duration up to the job step’s timeout. Long‑running processes are allowed; the only authoritative timeout is the timeout field in the Interpreter command or the step’s timeoutSeconds in the job definition. Courier Runner MUST terminate interpreters that exceed these limits.

Statelessness

Interpreters SHOULD be stateless across invocations. An interpreter MUST NOT depend on state produced by a previous invocation to function correctly.

An interpreter MAY maintain internal or cached state solely for performance or optimization purposes. Any such state MUST NOT affect the correctness or determinism of execution.

If an interpreter persists state beyond the lifetime of a single invocation, that behavior SHOULD be explicitly documented. Persisted state SHOULD be stored in a well-known location or in a user-configurable destination, and MUST NOT be implicitly shared across job steps without explicit operator intent.

Termination

After completing its work, an interpreter MUST terminate its process. The process exit code is the primary signal of success or failure (refer to the Validation and parsing section for further details).

An interpreter MUST close standard output (stdout) and standard error (stderr) to explicitly signal the end of all output to the Courier Runner.

An interpreter MUST document the set of exit codes it may emit, including the semantic meaning of each code, in its public documentation.

The Courier Runner MUST interpret an exit code of 0 as successful execution. Any non-zero exit code MUST be treated as a failure, subject to the failure handling and retry semantics defined in the Validation and parsing section.