Failure semantics

Exit codes

The process exit code is the authoritative indicator of success or failure. This specification recognizes two canonical states:

• Success - Exit code 0 indicates the interpreter completed the requested action successfully.
• Failure - Any non‑zero exit code indicates failure.

  Note

  At present the Runner only differentiates between 0 and 1 but interpreters MAY use other codes for internal diagnostics; those codes are collapsed to 1 by the Runner.
  Interpreters MUST set an appropriate exit code even when exceptions or crashes occur. The Runner MUST treat abnormal termination (for example, signal or crash) as failure.

Error reporting

When a failure occurs, the interpreter SHOULD provide diagnostic information:

• Write a human‑readable error message to stderr.
• Call AddErrorToRawMessage() with error logs or output from sub‑processes.

Partial success is permitted; interpreters MAY return artifacts even when the overall operation fails. The Runner can still capture these artifacts for analysis.

Idempotency and retries

Interpreters SHOULD design commands to be idempotent where practical. For example, if an interpreter creates a resource, repeated calls with the same parameters should leave the system in the same state. However, idempotency is OPTIONAL; some operations (for example, sending notifications) are inherently non‑idempotent.

Job definitions may specify retry policies (retryCount or failureBehavior) and success criteria (for example, numRuns), as shown in the job template example. The Runner controls retries. Interpreters MUST NOT implement their own retry loops.