3.9 KiB
ADR 0006: Share invocation reporting while preserving application outcomes
Status
Accepted. Consolidated during the alpha ADR cleanup. The structured-report formatting extension is accepted but not yet implemented; the adoption roadmap tracks that work.
Date
2026-11-07; consolidates decisions made on 2026-10-06 and 2026-10-25 and the accepted shared-format ownership extension.
Context
An invocation crosses routing, parsing, acquisition, command execution, and output delivery. Applications need consistent presentation and useful returned outcomes without giving a CLI library control of domain recovery or process termination. Separate reporting facilities would repeat visibility and failure-handling rules.
Decision
Core provides one reporting facility per invocation for command results, immediate messages, deferred messages, and final presentation. Callers choose result and diagnostic destinations. Applications and integrations choose content, messages, and domain outcomes; core coordinates visibility, delivery, and its own parsing and presentation failures.
Applications decide whether a domain error warrants recovery, a warning, or a failed invocation. They supply explicit outcomes and explanations, optionally with an error cause. A cause alone does not select an outcome or create an operator-facing message. Preserve supplied causes and their supported public identity. Integrations adapt upstream evidence without taking ownership of its domain meaning or disclosure rules.
Return explicit outcome classifications that distinguish shared usage and operational failures from application-defined domain outcomes. Preserve domain classification and keep presentation failures separately observable from the operation's explanation and cause. Delivery failure must be visible without silently discarding the application's result. The application entry point owns final process status mapping and termination.
Present terminal failure explanations after ordinary reporting finishes. Core coordinates its own diagnostic paths to avoid duplicate presentation. Reporting state serves delivery and the returned outcome; logging and message history remain application responsibilities.
The accepted structured-report extension centralizes format selection, serialization, and rendering in core. Applications and integrations hand off selected content, including their chosen detail level and optional text template; core determines how to output it. New core formats should work through that shared handoff without each command maintaining encoders. This extends the same invocation lifecycle, with a writer API sharing rendering outside invocations. Implementation status and initial format choices remain in the roadmap above.
Alternatives considered
- Handler-owned presentation would maximize local control but repeat output, visibility, and delivery-error infrastructure.
- Letting core interpret domain errors would give it recovery decisions that depend on application behavior.
- One failure category or numeric status alone would lose meaningful distinctions between usage, operational, and domain results.
- Separate facilities for results and messages, or encoders in each integration, would spread shared behavior across independent implementations.
Consequences
Commands share presentation while retaining ownership of their content and outcomes. Core must keep operation and presentation evidence distinguishable, including when output is partial. Caller writers retain their own lifecycle.
GoDoc and the CLI reference own implemented APIs, numeric statuses, visibility controls, and exact delivery behavior. Report layouts, format defaults, YAML framing, and scope ordering are presentation contracts, not separate architectural decisions. The shared-format extension remains planned until its implementation and canonical contracts land.