Outcomes and diagnostics
Stable machine codes, bounded human messages, paths, retryability, and recovery behavior.
User-facing recovery follows receipt status first, then diagnostic code. Do not branch application logic on a human message.
Diagnostic shape#
Type
interface Diagnostic {
code: string;
message: string;
path?: readonly (string | number)[];
retryable: boolean;
remedies?: readonly string[];
}
Recovery map#
| Status | UI behavior | Automatic retry? |
|---|---|---|
needs-input | Show the bounded choices or missing form field. | No; wait for user input. |
denied | Remove no-longer-authorized data and explain the access boundary. | No. |
cancelled | Usually remain quiet when superseded; preserve current work. | No. |
unsupported | Keep the previous valid UI and show a supported alternative. | No. |
failed | Show an actionable recovery near the affected Region. | Only when retryable and host policy allow it. |
| Ambiguous action | Show uncertainty and a reconciliation control. | Never retry blindly. |
Privacy#
Diagnostics and audit events use fixed codes and bounded metadata. Keep credentials, row payloads, prompts, URLs with secrets, free-form identity, and private reasoning out of logs and inspectors.