PILOTAGE
GitHub Get started →

4. Draft the daytime flow, and make the classic mistake

Start with the smallest daytime slice: the lobby light. The first draft deliberately misspells light.lobby. The live server's captured diagnostic for this classic typo follows the request:

↑Request
{
  "tool": "validate_flow",
  "arguments": {
    "flow": {
      "name": "lobby on",
      "steps": [
        {
          "id": "on",
          "do": "call",
          "device": "light.loby",
          "action": "turn_on"
        }
      ]
    }
  }
}
↓Response
{
  "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 tool call succeeded. The program did not validate.

Repair the identifier, add the dock step, and validate the full daytime flow:

↑Request
{
  "tool": "validate_flow",
  "arguments": {
    "flow": {
      "name": "open Harborview for the day",
      "steps": [
        {
          "id": "lobby-on",
          "do": "call",
          "device": "light.lobby",
          "action": "turn_on"
        },
        {
          "id": "dock-unlock",
          "do": "call",
          "device": "lock.dock_door",
          "action": "unlock"
        }
      ]
    }
  }
}
↓Response
{
  "valid": true,
  "diagnostics": [],
  "catalog_version": "cv_590fefad56a7a504",
  "plan": {
    "steps": [
      {
        "id": "lobby-on",
        "risk": "write",
        "risk_hints": {
          "readOnly": false,
          "destructive": false,
          "openWorld": false
        },
        "calls": "light.lobby"
      },
      {
        "id": "dock-unlock",
        "risk": "destructive",
        "risk_hints": {
          "readOnly": false,
          "destructive": true,
          "openWorld": false
        },
        "calls": "lock.dock_door"
      }
    ],
    "max_risk": "destructive",
    "max_risk_hints": {
      "readOnly": false,
      "destructive": true,
      "openWorld": false
    }
  }
}
What this taught

A closed diagnostic code is machine-actionable. The JSON Pointer identifies the exact field. The hint offers a visible, authorization-safe repair. No side effect occurred during either validation.

See Validation and closed diagnostics and Part II ยง6.4.