Skip to content

Source status: no status is stated in the source document, so none is assigned here. Do not treat this page as a finalized specification. The normative rules are in the Technical Specification.

Debugging and Diagnostic System

The language will provide built-in debugging tools designed for both human developers and AI agents.

1. Structured Diagnostics

Every diagnostic must include: - Unique error identifier. - Error category and severity. - Exact source location. - Description of the failure. - Relevant violated rule or contract. - Expected behavior versus actual behavior. - Suggested investigation steps.

2. Execution Tracing

  • Functions should support execution tracing.
  • State changes should be inspectable.
  • Function inputs and outputs should be traceable.
  • Failed operations should preserve their failure context.
  • Traces must identify the source version that produced them.

3. Reproducibility

  • Runtime failures should provide reproducible execution information where possible.
  • Tests should preserve failing inputs.
  • Randomized operations should support recorded seeds.
  • Concurrency failures should capture relevant execution events.

4. AI-Assisted Debugging

  • Diagnostics must be machine-readable.
  • AI agents should be able to inspect relevant execution traces.
  • Suggested fixes must identify which requirements they affect.
  • Fixes must trigger the appropriate verification checks.
  • Diagnostic suggestions must never be treated as proof that a correction is valid.

5. Debugging Safety

  • Debugging must not silently modify source code.
  • Sensitive information must be protected in logs and traces.
  • Diagnostic collection must not introduce undeclared side effects.

Design Goal

An AI agent should be able to identify, understand, reproduce, and correct a software defect while preserving existing requirements and verified behavior.

Source and authority

This page migrates DEBUGGING.md in full. It is an explanatory / implementation document, not the normative specification. Where it simplifies a rule, the Technical Specification governs. The original file is preserved in source-original/LANG/.