# Diagnostics and output

One reports failures as typed, owned records rather than free-form error
strings. The same diagnostic meaning reaches a person, a JSON consumer, an
editor, and an agent without any of them scraping rendered human output.

## The diagnostic envelope

A `Diagnostic` contains:

- a stable code;
- severity;
- primary and secondary source spans;
- affected graph IDs;
- the violated law or invariant;
- an explanation proof;
- consequences;
- candidate fixes; and
- machine actions.

Each diagnostic distinguishes the kind of value involved — authored,
domain-defaulted, domain-derived, cross-owner-mapped, or planning-derived — and
names every exact semantic package, declaration namespace authority, and rule
revision that produced it. Ambiguity is itself a diagnostic; the tooling never
infers intent from a name, shape, or similarity.

A suggested fix is a typed patch against a System IDL semantic item, a selected
peer declaration frontend, an implementation item/body or external
implementation dependency, or policy. It is never an opaque target mutation. A
structural syntax match can locate the bytes for a patch, but the preview is
produced by bounded item acceptance and the applicable semantic owner or
implementation-language frontend over the complete affected dependency closure.

## A worked diagnostic

Human output leads with the code, the cause, the exact source locations, and a
bounded "choose one" fix set:

```text
ONE-RMT-0042  remote boundary lacks idempotency semantics
  one/production.realization.one:52  inventory placed in another process
  one/contracts.one:87               create_order calls reserve_stock (effectful)

  The local direct call was lowered to at-least-once QUIC RPC. A lost response
  cannot prove whether stock was reserved.

  Choose one:
    - declare idempotency key ReservationId (recommended),
    - change delivery to at-most-once and handle unknown outcome,
    - co-locate the components,
    - wrap the operation in workflow reconciliation.
```

> **Illustrative end-product envelope.** The owner contract fixes the fields
> below; the JSON shape is shown for orientation and is not cited against a
> checked-in fixture.

```json
{
  "code": "ONE-RMT-0042",
  "schema": "one.developer.interface.diagnostic@1",
  "severity": "error",
  "stage": "planning",
  "subject": "acme.orders#Orders.place@1",
  "details": { "reason": "remote boundary lacks idempotency semantics" },
  "fixes": ["declare idempotency identity", "co-locate the components", "wrap in reconciliation"]
}
```

## Failure and exit classes

The lifecycle distinguishes failure classes so that recovery advice is exact.
A class never collapses into a generic error, and the safe next action never
widens authority or blindly repeats an effect:

| Class | Meaning | Safe next action |
| --- | --- | --- |
| Success | The declared success value was produced | Continue |
| Invalid source or type | The source or type does not satisfy its schema, bounds, or static rules | Correct the source and re-check |
| Unresolved identity or dependency | A referenced identity, package, or lock entry cannot be resolved | Supply the exact dependency or lock entry; do not guess |
| Incompatible change | Selected schemas, protocols, targets, or versions cannot interoperate | Rebuild, remap, migrate, or replan |
| Unsupported capability | No declared contract or implementation path provides the requested semantics | Add or select a real implementation at the owning boundary |
| Unsatisfied evidence or observation | The contract is supported but no eligible realization meets the root constraints | Change constraints, evidence, or provider availability |
| Policy denial or pending approval | Policy rejected the exact request, or required approval is absent | Change scope, obtain approval, or reauthorize |
| Stale source/lock/plan | Reviewed input no longer matches current revisions or freshness | Refresh the source, lock, or plan and re-review |
| Unknown effect outcome | Dispatch may have happened, but the outcome is not established | Reconcile through the owner before any re-dispatch |
| Internal defect | An implementation, provider, tool, or One invariant was violated | Retain evidence, stop, and inspect the responsible boundary |

Expected domain faults returned by an operation are not platform defects and do
not automatically trigger retries. See the
[failure model](/one/reference/failure-model) for the full outcome vocabulary.

## Retry advice

Retry advice is owner-typed and finite. A generic string is never the only
failure contract:

| Retry advice | Meaning |
| --- | --- |
| `Never` | Do not retry; the request or meaning is wrong |
| `After` | Retry after the stated delay or condition, within the admitted envelope |
| `AfterReauth` | Obtain fresh authority, then retry the exact request |
| `AfterReplan` | Produce a new plan; never reuse the stale one |
| `AfterHumanReview` | A person with authority must review before retry |
| `RequiresIdempotency` | Retry only when the effect is idempotent or has a matching prior intent |

No retry advice authorizes widening authority, reselecting a provider,
rebuilding an artifact, or repeating an unknown-outcome effect.

## Machine output

`--format human|json` applies uniformly across the CLI. Machine responses are
stable versioned schemas of owner envelopes and typed diagnostics; consumers
never scrape human output. Current in-tree report and record identities include:

- `one.project-plan-command-report/v1` — the authority-free project planning result;
- `one.agent-event/v1` — the streamed governed-agent event projection;
- `one.agent-report/v1` — the terminal governed-agent report;
- `one.source-acquisition/v1` — the project source-acquisition receipt;
- `LocalReleaseInspectionRecord` — the Deployment-owned local-release inspection record.

> These `/v1` spellings are transitional under the identity migration. New
> One-owned protocols, schemas, and formats use a nominal identity with a lane
> (`namespace#Name@lane`), never a new `/vN` tag.

The CLI also surfaces delegated tool diagnostics. Cargo/rustc, linkers,
container tools, Kubernetes, and cloud adapters are invoked only when the
applicable Build or Deployment contract selects them, and their diagnostics
stay source-mapped without forcing users to learn the foreign command syntax.
See [CLI reference](/one/reference/cli).

## Environment inputs

One has no ambient untyped environment or configuration channel. Configuration
is typed and owner-separated — see [project and workspace](/one/reference/project).
The current variables are implementation, acceptance, and test inputs, not a
product configuration API:

| Variable | Role |
| --- | --- |
| `ONE_POSTGRES_TEST_URL` | Explicit external database for the ignored PostgreSQL acceptance test |
| `ONE_TEST_INPUT_RELEASE_DISTRIBUTION` | Base-free distribution input for a governed release acceptance fixture |
| `ONE_TEST_INPUT_AUTHORITY_EPOCH` | Exact Authority epoch paired with the acceptance distribution input |
| `ONE_*_ACCEPTANCE_DISTRIBUTION` | Per-owner acceptance distribution inputs |
| `ONE_SERVER_HTML_ADDRESS` | Fixed loopback binding supplied by the Rust server-HTML development session |
| `NO_COLOR`, `TERM=dumb` | Presentation-only: the same classified text without color |

These values select test or development inputs only. They never become
portable project meaning, a provider selection, or a grant, and no product
feature may depend on an untyped environment lookup. See
[check, test, and invoke](/one/lifecycle/check-test-invoke) and
[CI and release automation](/one/guides/ci-automation).

## Acting on a diagnostic

Diagnostics identify the source span, owner, lifecycle stage, violated
contract, minimal conflict, and responsible next action.
[Troubleshooting](/one/lifecycle/troubleshooting) walks the operator through
preserving evidence and resolving each class. The
[product guarantees](/one/reference/guarantees) define what remains invariant
even when a diagnostic reports an unsupported, unsatisfied, missing-evidence,
or unknown-outcome state.

## Normative owner & evidence

Developer Interface owns the CLI output contract, the `Diagnostic` envelope,
and uniform `--format human|json` behavior. Each owning system owns the
diagnostics and exit classes it emits; the failure vocabulary is shared with
the [failure model](/one/reference/failure-model).

- [Developer Interface](https://github.com/muijf/one/blob/main/systems/developer-interface/AGENTS.md)
- [Contracts](https://github.com/muijf/one/blob/main/systems/contracts/AGENTS.md)
- [`SPEC_V2.md`](https://github.com/muijf/one/blob/main/SPEC_V2.md)

Executable evidence for the current CLI output, report identities, and
environment inputs is the Developer Interface CLI test suite and the owning
crate tests named by those packages. The JSON envelope shown above is an
illustrative end-product shape, not a cited test fixture.