79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
# ADR 0006: Share invocation reporting while preserving application outcomes
|
|
|
|
## Status
|
|
|
|
Accepted. Consolidated during the [alpha ADR cleanup](README.md#alpha-consolidation).
|
|
The structured-report formatting extension is accepted but not yet implemented;
|
|
the [adoption roadmap](../roadmap/promptkit-v0.19.0.md#shared-core-report-output-prerequisite)
|
|
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](../cli.md#reporting) 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.
|