base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Simplify ADRs and relax premature constraints

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 02:45:09 +00:00
parent 984d159676
commit 7e453a2df2
9 changed files with 165 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/adr/0005-invocation-outcomes.md
View File

@@ -15,58 +15,47 @@ 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](0001-command-dispatch-and-inputs.md) establishes process and domain
ownership. [ADR 0003](0003-public-facade.md) 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.
Exact Go declarations remain part of facade API design under
[ADR 0003](0003-public-facade.md).
Use these mappings for CommandKit-owned commands:
| Status | Meaning |
| --- | --- |
| `0` | The requested operation completed successfully, including help and completed comparison. |
| `0` | The requested operation completed successfully. |
| `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. |
| `2` | The invocation failed command, flag, scope, format, operand, 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.
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.
conventionally stderr. Callers choose the streams. CommandKit assigns responsibility
for presenting its diagnostics, avoids duplicate presentation through its own
paths, and reports write failures. Caller callbacks retain control of their own
output. CommandKit adapts backend syntax failures into its public classification
and 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.
failure is an operational failure.
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](0007-native-yaml-reports.md).
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.
A writer failure can leave a partial report and returns operational failure. The
outcome identifies incomplete delivery. Custom handler output remains
application-owned. [ADR 0007](0007-native-yaml-reports.md) covers `config show` report
preparation; [ADR 0008](0008-semantic-configuration-diff.md) defines successful
comparison, including differences and coverage gaps.
## Alternatives considered
@@ -76,7 +65,6 @@ application or consuming script can interpret differences according to its task.
| 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
@@ -84,11 +72,7 @@ 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.
The public result/error design must preserve cause and delivery failures across
handlers, writers, and the backend adapter. Diagnostic delivery bookkeeping
remains API design work. Acceptance establishes the compatibility meaning of the
status values and delivery rules across standard commands.