Validation and closed diagnostics

This page explains how a Client checks and repairs a program before execution.

Validation is a side-effect-free check that returns structured findings from a closed diagnostic vocabulary.

A validator checks more than JSON shape. It can resolve live names, verify actions and arguments, type-check expressions, enforce scope, and apply language constraints. It must not invoke catalog entries or change observable state.

Each finding has a severity, stable code, locator, message, and optional hint. The code set is finite for a Language version and published in the closed-sets guide. That matters because a Client can branch on unknown_device or type_error. Free text alone is harder to learn, test, and repair reliably.

Harborview returns this exact result for a misspelled device:

{
  "valid": false,
  "diagnostics": [
    {
      "severity": "error",
      "code": "unknown_device",
      "path": "/steps/0/device",
      "message": "unknown device 'light.loby'",
      "hint": "close match: light.lobby"
    }
  ],
  "catalog_version": "cv_590fefad56a7a504"
}

The result is not a transport error. valid: false means the validation operation worked and found a problem. The Model can replace light.loby with light.lobby and validate again.

Warnings do not make a program invalid. A program is valid exactly when no error-severity diagnostic remains. When planning is declared, a valid response also contains the plan: the loop's next layer, delivered in the same response rather than through a second round trip.

Formal rules: Part II §5.5, Diagnostic, Part II §6.4, validate, and Part III §7, Error mapping.

Next: The plan and risk · Outcomes