design: define complete ASP diagnostic context and failure envelope

Summary

Define and implement the remaining Agent Server Protocol diagnostic contract so agent-mode compiler and query failures preserve structured compiler context instead of degrading to prose-only error scalars.

Source documentation

• docs/progress.md — Phase H: Agent Tooling
• docs/design.md — Rule Set 21: The Agent Server Protocol, especially The Agent TOON Payload and ASP Beyond Build Errors
• docs/architecture.md — Diagnostics System, Query Engine, and ASP Server

Current state

jett build --agent emits structured status/count fields, ranged diagnostics and labels, and tabular suggested fixes. Successful namespace, symbol, type, definition, reference, completion, and signature queries also have deterministic structured schemas. Merged PR #25 extended this behavior to bundle validation failures.

The documented diagnostic model additionally promises optional AST-node, in-scope-variable, and violated-constraint context, but the current Diagnostic type and TOON renderer do not carry those fields. Query, format, run, and test failure paths can still flatten parse, resolution, type-check, or operational failures into an escaped prose error scalar, losing diagnostic codes and ranges. Trace and breakpoint rows are typed only by a row kind while their payload remains a human-formatted string.

Scope

This issue includes:

• deciding the stable optional schema and omission rules for AST-node, scope, and constraint context;
• preserving compiler diagnostics through agent-mode query and other command failure paths;
• defining a consistent structured failure envelope without changing successful query schemas;
• deciding whether trace/breakpoint payload structure belongs here or is explicitly deferred to Phase I;
• focused renderer and CLI tests for structured failures and optional diagnostic context.

It does not include MCP transport, salsa/incremental-query architecture, profiler work, HIR/MIR/native backends, or unrelated language-policy changes.

Acceptance criteria

• The optional ast_node, scope, and constraint_violated contract is documented with deterministic source-range and omission rules.
• Agent-mode parse, resolution, and type-check failures retain stable diagnostic codes, severity, primary ranges, labels, and suggested fixes wherever the compiler produced them.
• Build and query failures use a consistent structured envelope; format, run, and test compiler failures either use it too or have an explicitly documented command-specific reason not to.
• Trace and breakpoint rows gain a documented structured payload or are explicitly deferred to the Phase I tracing/debugging scope.
• Focused tests cover diagnostics with and without optional context, malformed/failing query inputs, command compiler-failure paths, and trace/breakpoint output.
• Existing successful ASP query schemas and human-readable output remain compatible.
• docs/design.md, docs/architecture.md, and the Phase H status in docs/progress.md reflect the accepted boundary.

Dependencies / open questions

The implementation may begin in the existing diagnostics, driver, and CLI crates; extracting the documented jett_query or jett_asp crates is not required. Bundle-specific ordering remains tracked by #13, and merged PR #25 is a useful precedent for retaining structured diagnostics through a command boundary.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.

Start with docs/design.md Rule Set 21, the Agent TOON Payload, and ASP Beyond Build Errors, then read docs/architecture.md and docs/progress.md Phase H. Trace the existing diagnostics, driver, and CLI paths, using merged PR #25 as precedent. Define the optional context and failure-envelope boundary, add focused renderer and CLI tests, and update the three named documents when the acceptance criteria are met.