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:

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.

{
  "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:

Expected domain faults returned by an operation are not platform defects and do not automatically trigger retries. See the 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:

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.

Environment inputs#

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

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 and CI and release automation.

Acting on a diagnostic#

Diagnostics identify the source span, owner, lifecycle stage, violated contract, minimal conflict, and responsible next action. Troubleshooting walks the operator through preserving evidence and resolving each class. The product 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.

• Developer Interface
• Contracts
• 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.