A Result Contract You Can Trust📋

A short result can still be misleading. An empty list might mean that no matches exist, that parsing failed, or that the output budget removed the data. QuietCli makes these distinctions expressible through a common execution envelope and domain data chosen by the companion author. Consumers need to read both layers before making a decision.

The inspected module uses SchemaVersion: 1. Its result properties are Summary, Outcome, Data, Execution, Error and Truncation. This is QuietCli's interface. It should not be replaced with the superficially similar OutputPumps envelope, which has different conventions and additional fields.

One envelope, freely chosen data📋

.Data can be an object, an array, a dictionary, a scalar or null. A repository answer does not need an artificial Items collection. Named properties can make its meaning easier to use in subsequent local calculations. If a parser returns an array, PowerShell pipeline enumeration needs attention: return that array as one value, using a unary comma where necessary.

New-QuietResult creates an envelope for data already calculated locally. ConvertTo-QuietJson produces compact JSON and applies the requested budget. A minimal illustrative construction is:

New-QuietResult -Summary 'Count is unavailable.' `
    -Data @{ Count=$null; AnswerComplete=$false } `
    -Execution @{ AnalysisComplete=$false } `
    -Outcome Failed -ErrorInfo @{ Code='MissingEvidence' } `
    -MaxOutputBytes 2048 |
    ConvertTo-QuietJson -MaxOutputBytes 2048

The unknown count remains null. The Boolean explains why the value cannot answer the question. An application can choose richer domain qualifiers, but their semantics are the companion author's responsibility.

Three different completeness questions📋

Execution analysis asks whether the native output was processed successfully within the selected scope. In the inspected runtime, Execution.AnalysisComplete follows successful execution and parsing. It does not independently validate whether a callback implements the correct domain algorithm.

Domain completeness asks whether the available properties answer this particular request. A parser can finish successfully while omitting fields the user needs. Add qualifiers such as AnswerComplete, a count unit, or a scope where they make that distinction explicit. The runtime cannot infer the question from arbitrary data.

Transmission completeness asks what survived the final budget and sanitization. A count may remain exact even if an example preview was omitted. Conversely, a result can report successful execution while its .Data has been removed to meet the byte limit. These states require different next actions.

For that reason, Outcome: Success alone is insufficient. Check Execution.AnalysisComplete, the required domain fields and Truncation. If the requested answer disappeared, revise the projection or narrow the request deliberately. Do not treat the absence of data as evidence that the original program found nothing.

What the budget actually does📋

QuietCli defaults to 4,096 UTF-8 bytes. The examples in this series explicitly request 2,048 bytes for the final result. Bytes measure the serialized document; they are not an exact token count and say nothing by themselves about the total cost of a model session.

The inspected implementation first sanitizes and limits values. If the serialized envelope still exceeds the budget, it sets .Data to null and adds OutputBudget to the omission reasons. It can further reduce diagnostic details and execution metadata. It does not rank arbitrary domain properties intelligently and select the most important ones for the user.

That makes explicit projection design worthwhile. Return the few properties needed for the current question instead of hoping the final serializer will discover their priority. If two limits apply, explain both: a document capture limit controls internal analysis input, while a final JSON limit controls transmission to the agent.

Failure is useful information📋

The runtime distinguishes native failure, parser failure, timeout, capture overflow and oversized streaming records. The examples verify those paths. Some failure paths can retain partial domain data, so consumers must check status even when .Data is present. Other paths correctly return null because a trustworthy value was never established.

Sanitization provides an additional protection for known sensitive patterns and values. It does not certify that every secret has been removed. The companion should select appropriate diagnostics before transmission and keep raw captures local. A failed operation is still an occasion to return a bounded structured diagnostic.

The Git companion in the next chapter shows how a concrete domain contract fits inside this envelope and why carefully named counts matter.

Previous: The Agent Writes the Companion · Series overview · Next: A Practical Git Companion