# Diagnostics

Diagnostics carry severity, a stable code, message, byte-accurate primary `SourceSpan`, secondary labels, notes, help, and runtime-frame storage. The lexer and parser recover at statement and declaration boundaries and can report multiple independent mistakes. Invalid trees are not analyzed or executed.

Text output prints the source line and an underline. `--diagnostic-format json` emits schema version 1 with the same code, severity, file, and range data; this is the contract used by the VS Code extension. Errors produce exit status `1`, warnings do not prevent checking or execution, and CLI usage or module/file resolution failures produce status `2`.

The semantic best-practice pass currently reports:

- `K2601`: a fallible network, filesystem, JSON, or database operation is outside a protecting `try` block.
- `K2602`: an empty `catch` block silently hides a failure.
- `K2603`: a literal network URL uses unencrypted `http://`.
- `K2604`: a host shell command requires trusted input.
- `K2605`: the result of a value-producing operation is ignored.
- `K2606`: `fetch` relies on the default timeout instead of selecting a backend-specific timeout.
- `K2610`: SQL text is dynamic instead of using constant SQL and bound parameters.

Runtime families include `KNET2001` for phase-specific network failures, `KDB2001` for PostgreSQL failures with SQLSTATE/native causes, `KRT2001`–`KRT2004` for member access, `KRT2101`–`KRT2105` for array/object indexing, and `KRT2200`–`KRT2204` for numeric operations. These codes are stable across the tree-walk compatibility engine and bytecode VM: `KRT2201` covers division/remainder by zero, `KRT2202` covers non-integer remainder operands, and `KRT2204` covers checked integer overflow. VM-only defects and invalid bytecode retain `KVM`/`KBC` codes. Runtime diagnostics include source mappings and VM call frames.

Semantic declaration and call validation uses `KSEM1101`–`KSEM1104` for duplicate declarations, bindings, declaration conflicts, and parameters. `KSEM1201` reports an argument-count mismatch and `KSEM1202` points at the exact argument whose type is incompatible. Semantic null and index misuse uses `KSEM2401`–`KSEM2403` before execution when the type is known.

`KSEM1203` rejects calls on statically non-callable values. The VM uses `KVM2010` when a dynamically typed value is not callable and `KVM2011` when an indirect function call supplies the wrong number of arguments.

Loop-control validation uses `KSEM1301` for `break`/`continue` outside a loop, `KSEM1302` for an unknown target label, `KSEM1303` for an ambiguous duplicate active label, and `KSEM1304` for a non-boolean loop condition.

Match validation uses `KSEM1401` for a non-exhaustive expression, `KSEM1402` for arms made unreachable by a wildcard, `KSEM1403` for duplicate literal patterns, and `KSEM1404` for a pattern incompatible with the subject type.

These diagnostics are emitted by the compiler rather than reconstructed by editor tooling, so CLI text, CLI JSON, and VS Code agree on the rule and source span.