5.1 KiB
ADR 0005: Return explicit outcomes and deliver reports through defined channels
Status
Proposed
Date
2026-10-06
Context
An invocation crosses routing, parsing, provider acquisition, a standard or application handler, report writing, and the application entry point. Operators and subprocess consumers need consistent classifications for those stages. Applications also have meaningful domain outcomes of their own.
ADR 0001 establishes process and domain ownership. ADR 0003 establishes public error and backend boundaries. The remaining decisions concern the public outcome model, report and diagnostic channels, and standard process-status mappings.
Decision
CommandKit returns an invocation outcome with an explicit classification and
recommended process status. The public model distinguishes successful operation,
usage error, operational failure, and application domain outcome. Failures retain
their consumer-facing cause and supported errors.Is/errors.As identity.
Exact Go declarations remain part of facade API design.
Use these mappings for CommandKit-owned commands:
| Status | Meaning |
|---|---|
0 |
The requested operation completed successfully, including help and completed comparison. |
1 |
A syntactically valid operation failed during loading, validation, lookup, inspection, cancellation, diagnostics delivery, or report writing. |
2 |
The invocation failed command, flag, scope, format, operand, repetition, or input-combination validation. |
CommandKit's handler result contract accepts domain classifications and suggested process statuses supplied by the caller. CommandKit preserves that classification when returning the handler's result. A custom domain status and a shared usage status may have the same numeric value; their explicit classifications retain their distinct meanings. The application entry point controls final process termination and status mapping.
CommandKit writes standard reports to the supplied report stream, conventionally stdout, and its warnings and errors to the supplied diagnostic stream, conventionally stderr. Callers choose the streams. Each CommandKit diagnostic has one delivery owner and one emission through the selected channel. The provider contract carries acquisition diagnostics and their delivery state so CommandKit can present pending diagnostics once. CommandKit adapts backend syntax failures into its public classification and safe diagnostic presentation. Usage guidance accompanies usage errors; operational failures receive diagnostics appropriate to the failed operation.
Warning severity alone permits a successful operation. A diagnostic writer failure is an operational failure. Source coordinates and source-ID legends are preserved where supplied by the owning library.
Report writers use the application's supplied streams. Shell redirection provides file output for the initial standard. A writer failure can leave a partial report and returns operational failure. The outcome identifies incomplete delivery; checking it before interpreting reports is recommended caller practice. Custom handler output remains application-owned. Multi-scope loading and ordering follow the YAML report policy.
A completed semantic comparison returns success with its differences and coverage gaps recorded in the report. Its outcome describes successful inspection; the application or consuming script can interpret differences according to its task.
Alternatives considered
| Alternative | Analysis |
|---|---|
| A single failure classification | Simplifies outcome handling. Callers derive syntax, operational, and domain distinctions through additional interpretation. |
| Backend errors and output as the public outcome model | Reuses framework machinery directly. Backend conventions become dependencies for applications and subprocess consumers. |
| One common mapping for application domain failures | Produces uniform numeric statuses. Applications adapt existing artifact and execution outcomes to shared categories. |
| Handler-owned diagnostics for every failure | Gives each handler full presentation control. Shared diagnostic consistency requires repeated ownership and formatting coordination. |
| Dedicated file-output options | Adds direct file targeting. The standard acquires creation, replacement, and retention responsibilities alongside report writing. |
Consequences
The outcome model supports both Go callers and executable entry points. Explicit classification keeps domain identity intact through adapter and facade conversion. Single diagnostic ownership supports predictable presentation.
CommandKit handlers and writers coordinate cause propagation and delivery responsibility. Output failures may produce partial bytes; callers receive an outcome describing delivery failure. The public result/error design preserves these semantics through fresh invocation state and private adapter callbacks.
Acceptance establishes the compatibility meaning of these status values and delivery rules across standard commands.