Section 12: Diagnostics, Debugging, and Execution Traces¶

TECHSPEC-12 — Section 12 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Diagnostic Philosophy¶

Errors must produce structured, actionable diagnostics.

The language must explain failures in terms of their actual cause rather than providing vague messages that require an agent to guess.

Diagnostics must distinguish confirmed causes from possible explanations.

2. Diagnostic Structure¶

Every compiler or runtime diagnostic must contain, where applicable:

ID: Unique diagnostic identifier.
CATEGORY: Type of failure.
SEVERITY: Error, warning, or informational.
LOCATION: File, line, column, and relevant source range.
MESSAGE: Concise explanation.
EXPECTED: Expected behavior or condition.
ACTUAL: Observed behavior or condition.
CONTRACT: Related function contract or invariant.
EVIDENCE: Information supporting the diagnostic.
SUGGESTION: Possible correction, if one can be identified.

Suggestions must never be presented as verified fixes.

3. Diagnostic Categories¶

The initial language defines:

Syntax errors.
Type errors.
Contract violations.
Ownership and lifetime violations.
Effect and permission violations.
Invalid state.
Concurrency violations.
Unhandled failures.
Test failures.
Runtime faults.
Verification failures.

Each diagnostic must identify the relevant category.

4. Execution Traces¶

The runtime must support structured execution traces.

Traces should record relevant events such as:

Function calls and returns.
Input and output values, where safe.
State transitions.
Error propagation.
Permission checks.
Resource acquisition and release.
Task creation, completion, and cancellation.
Contract checks.

Rules: - Traces must preserve event ordering. - Traces must identify the relevant execution. - Sensitive values must be redacted or excluded. - Tracing must not silently change program behavior. - Trace completeness must be reported when events are omitted or unavailable.

5. Reproducibility¶

The debugging system should preserve enough information to reproduce a failure where practical.

Records may include: - Program version and source hash. - Compiler and runtime versions. - Relevant input values. - Random seeds. - Environment information. - Dependency versions. - Relevant execution events.

External conditions that cannot be reproduced must be identified.

6. AI Agent Diagnostic Interface¶

Diagnostics must be available in both human-readable and machine-readable formats.

AI agents must be able to: - Retrieve diagnostics by identifier. - Identify the exact source location. - Inspect the violated rule or contract. - Access relevant evidence. - Compare expected and actual behavior. - Determine which verification steps must be repeated after a change.

Diagnostics should be specific enough to support targeted corrections rather than requiring unnecessary rewrites.

7. Compiler and Runtime Responsibilities¶

The compiler and runtime must: - Generate structured diagnostics. - Preserve relevant failure information. - Identify the source of detected violations. - Distinguish confirmed causes from hypotheses. - Support execution tracing. - Protect sensitive information. - Record limitations in diagnostic coverage.

8. Design Goal¶

AI agents must be able to investigate failures using reliable evidence rather than guessing.

The language must never present a speculative explanation as a confirmed cause or a suggested correction as a verified solution.

Source file: TECHSPEC-12.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.