PILOTAGE
GitHub Get started →

8. Demonstrate the alarm safely

Harborview declares execute.test_run. A test run evaluates a deploying flow without changing the real world.

↑Request
{
  "tool": "run_flow",
  "arguments": {
    "flow": {
      "name": "dock door alert",
      "trigger": {
        "event": "sensor.door_dock.opened"
      },
      "steps": [
        {
          "id": "check",
          "do": "branch",
          "when": {
            "gt": [
              "$.world.time",
              "21:00"
            ]
          },
          "then": [
            {
              "id": "alert",
              "do": "call",
              "device": "notify.facilities",
              "action": "send",
              "with": {
                "message": "Dock door opened after hours"
              }
            }
          ]
        }
      ]
    },
    "mode": "deploy",
    "test_run": true,
    "expected_catalog_version": "cv_590fefad56a7a504",
    "trace_level": "full"
  }
}
↓Response
{
  "run_id": "run_0005",
  "outcome": {
    "ok": true,
    "status": "success",
    "error": null
  },
  "trace": {
    "run_id": "run_0005",
    "level": "full",
    "steps": [
      {
        "id": "check",
        "outcome": {
          "ok": true,
          "status": "success",
          "error": null
        },
        "decisions": [
          {
            "at": "check",
            "took": "else",
            "because": "{\"gt\":[\"$.world.time\",\"21:00\"]} → false"
          }
        ]
      }
    ]
  }
}

At the current simulated time (14:03) the alarm's guard is false, so the test run takes the empty else path and sends nothing. The real building is unchanged; this is the guard working before 21:00.

Now advance the deterministic world to after hours and fire the real event. world_advance is a Harborview demo tool, not part of Pilotage:

↑Request
{"tool":"world_advance","arguments":{"to_time":"21:30","fire_event":"sensor.door_dock.opened"}}
↓Response
{
  "time": "21:30",
  "fired": [
    {
      "ref": "auto_001",
      "run_id": "run_0006",
      "outcome": {
        "ok": true,
        "status": "success",
        "error": null
      }
    }
  ]
}

The non-empty fired array proves the trigger was installed. But this run was started by the world, not by any request of ours, so no execute response of ours carried its trace. This is the moment the trace layer's second door matters: trace_run fetches the record of a retained Run by its run_id. Chapter 9 walks through that door fully; here, open it just enough to inspect the fired run's branch decision and notification step:

↑Request
{"tool":"trace_run","arguments":{"run_id":"run_0006"}}
↓Response
{
  "run_id": "run_0006",
  "outcome": {
    "ok": true,
    "status": "success",
    "error": null
  },
  "trace": {
    "run_id": "run_0006",
    "level": "full",
    "steps": [
      {
        "id": "check",
        "outcome": {
          "ok": true,
          "status": "success",
          "error": null
        },
        "decisions": [
          {
            "at": "check",
            "took": "then",
            "because": "{\"gt\":[\"$.world.time\",\"21:00\"]} → true"
          }
        ]
      },
      {
        "id": "alert",
        "calls": "notify.facilities",
        "input": {
          "action": "send",
          "message": "Dock door opened after hours"
        },
        "output": {
          "delivered": true,
          "message": "Dock door opened after hours"
        },
        "outcome": {
          "ok": true,
          "status": "success",
          "error": null
        }
      }
    ]
  }
}
What this taught

A test run checks the body without effects. A deterministic simulator can then demonstrate the installed trigger. The important evidence is the actual fired Run and its trace, not a claim that deployment succeeded.

See Execution, traces, and decisions and Part II §5.8.4.