executions.events

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The execution's id."
    },
    "after": {
      "type": [
        "integer",
        "null"
      ],
      "format": "uint64",
      "minimum": 0,
      "description": "Only events after this sequence number: the cursor a reconnecting client holds."
    },
    "limit": {
      "type": [
        "integer",
        "null"
      ],
      "format": "uint",
      "minimum": 0,
      "description": "How many, oldest first; the default and the bound are both `500`."
    }
  },
  "required": [
    "id"
  ],
  "description": "The input of `executions.events`.",
  "title": "EventsInput"
}

{
  "type": "object",
  "properties": {
    "execution_id": {
      "type": "string",
      "description": "The execution the events belong to."
    },
    "state": {
      "$ref": "#/$defs/ExecutionState",
      "description": "Where the execution stands now, so a client needs one request rather than two."
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ExecutionEvent"
      },
      "description": "The events, oldest first."
    },
    "last_sequence": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "The sequence of the last event here: the cursor for the next page, and the one to\nopen the live channel with."
    },
    "more": {
      "type": "boolean",
      "description": "Whether more events follow this page right now."
    },
    "truncated": {
      "type": "boolean",
      "description": "Whether events before this page had already been dropped by the store's bound."
    }
  },
  "required": [
    "execution_id",
    "state",
    "events",
    "last_sequence",
    "more",
    "truncated"
  ],
  "description": "The answer of `executions.events`: one page of an execution's retained history.",
  "title": "EventHistory",
  "$defs": {
    "ExecutionState": {
      "oneOf": [
        {
          "type": "string",
          "const": "queued",
          "description": "Accepted, and no worker has picked it up."
        },
        {
          "type": "string",
          "const": "running",
          "description": "The handler is running."
        },
        {
          "type": "string",
          "const": "cancelling",
          "description": "Cancellation was asked for and the handler has not stopped yet."
        },
        {
          "type": "string",
          "const": "succeeded",
          "description": "The handler returned an output."
        },
        {
          "type": "string",
          "const": "failed",
          "description": "The handler returned an error, or the worker could not run it."
        },
        {
          "type": "string",
          "const": "cancelled",
          "description": "It stopped because it was asked to."
        }
      ],
      "description": "Where an execution is in its life.\n\nThe transitions are the whole contract, and `ExecutionState::may_move_to` is the one\nplace they are written down: the engine asks before every change, the store refuses a\nmove it did not allow, and a client that reads a final state never sees it move again.\n\n```text\n  queued ──► running ──┬──► succeeded\n     │                 ├──► failed\n     │                 └──► cancelling ──┬──► cancelled\n     │                                   ├──► succeeded\n     └──► cancelled                      └──► failed\n```\n\nThere is no `starting`. An in-process engine claims an execution and enters its handler\nin the same instant, so a state between the two would be one no client could ever\nobserve and every client would have to handle."
    },
    "ExecutionEvent": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "description": "The protocol version, `PROTOCOL_VERSION`."
        },
        "event_id": {
          "type": "string",
          "description": "The identity of this event: the execution's id and the sequence, so a client that\ndeduplicates needs no composite key of its own."
        },
        "execution_id": {
          "$ref": "#/$defs/ExecutionId",
          "description": "The execution it is about."
        },
        "sequence": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Its position in that execution's stream, from 1, without gaps."
        },
        "timestamp": {
          "type": "string",
          "description": "When the event was produced, RFC 3339 in UTC."
        }
      },
      "required": [
        "schema_version",
        "event_id",
        "execution_id",
        "sequence",
        "timestamp"
      ],
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.created"
            },
            "data": {
              "type": "object",
              "properties": {
                "capability": {
                  "description": "The capability's canonical id.",
                  "type": "string"
                },
                "title": {
                  "description": "Its title.",
                  "type": "string"
                },
                "input": {
                  "description": "The input, with sensitive values already replaced."
                }
              },
              "required": [
                "capability",
                "title",
                "input"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "The execution was accepted and exists. Carries what it will run and with what,\nredacted, so a client that joins at the first event needs nothing else to render a\nheading."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.queued"
            },
            "data": {
              "type": "object",
              "properties": {
                "ahead": {
                  "description": "How many executions are ahead of it.",
                  "type": "integer",
                  "format": "uint",
                  "minimum": 0
                }
              },
              "required": [
                "ahead"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "It is waiting for a worker."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.started"
            }
          },
          "required": [
            "type"
          ],
          "description": "A worker picked it up and is about to enter the handler."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.progress"
            },
            "data": {
              "$ref": "#/$defs/ProgressView"
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "How far along it is."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.step.started"
            },
            "data": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The step's stable name.",
                  "type": "string"
                },
                "title": {
                  "description": "One line for a reader.",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "title"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A named phase was entered."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.step.completed"
            },
            "data": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The step's stable name.",
                  "type": "string"
                },
                "ok": {
                  "description": "Whether what it was asked to do happened.",
                  "type": "boolean"
                },
                "detail": {
                  "description": "What it said, when it said anything.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "ok"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A named phase finished."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.log"
            },
            "data": {
              "type": "object",
              "properties": {
                "stream": {
                  "description": "Which stream it came from.",
                  "$ref": "#/$defs/LogStream"
                },
                "message": {
                  "description": "The text, with control characters and terminal escapes already removed.",
                  "type": "string"
                }
              },
              "required": [
                "stream",
                "message"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A line of output."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.diagnostic"
            },
            "data": {
              "$ref": "#/$defs/ExecutionDiagnostic"
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A structured finding, distinct from the outcome."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.cancelling"
            },
            "data": {
              "type": "object",
              "properties": {
                "by": {
                  "description": "Who asked, in one word.",
                  "type": "string"
                }
              },
              "required": [
                "by"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "Cancellation was asked for; the handler has not stopped yet."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.cancelled"
            }
          },
          "required": [
            "type"
          ],
          "description": "It stopped because it was asked to."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.completed"
            },
            "data": {
              "type": "object",
              "properties": {
                "output": {
                  "description": "What the handler returned."
                }
              },
              "required": [
                "output"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "It finished, and the handler returned an output.\n\nThe output is on this event and not on one of its own, because a client must never\nbe able to read \"succeeded\" and find no result: the state and the value it produced\nare one fact and travel together."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.failed"
            },
            "data": {
              "type": "object",
              "properties": {
                "error": {
                  "description": "Why.",
                  "$ref": "#/$defs/ExecutionError"
                }
              },
              "required": [
                "error"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "It finished, and it did not."
        }
      ],
      "description": "One event about one execution.\n\n`sequence` is dense and starts at 1 within an execution: a client that has seen\nsequence `n` knows it has missed something when the next event it reads is not `n + 1`,\nand asks for the gap by cursor rather than reloading the world."
    },
    "ExecutionId": {
      "type": "string",
      "description": "The identity of one execution: `x-<UTC timestamp>-<8 hex>`.\n\nThe shape is the layer's own — a task is `t-20260905034523-a9f1` — so that an id read\nin a log, a URL or a browser tab is recognisable as this repository's without a\ndependency on a UUID crate. The timestamp orders ids by creation for a reader; the\nsuffix, not the timestamp, is what makes two ids created in the same second differ."
    },
    "ProgressView": {
      "type": "object",
      "properties": {
        "current": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Units done."
        },
        "total": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "Units in total, when the handler knows how many."
        },
        "message": {
          "type": [
            "string",
            "null"
          ],
          "description": "What is being done, for a reader."
        }
      },
      "required": [
        "current"
      ],
      "description": "How far along an execution is."
    },
    "LogStream": {
      "oneOf": [
        {
          "type": "string",
          "const": "stdout",
          "description": "The standard output of a child process the handler ran."
        },
        {
          "type": "string",
          "const": "stderr",
          "description": "Its standard error."
        },
        {
          "type": "string",
          "const": "handler",
          "description": "The handler itself, saying something it wants a reader to see."
        }
      ],
      "description": "Which stream a log line came from."
    },
    "ExecutionDiagnostic": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        },
        "code": {
          "type": "string",
          "description": "A stable machine-readable code."
        },
        "summary": {
          "type": "string",
          "description": "One line, for a person."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "The rest, when there is more."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "What to do about it, when there is something."
        }
      },
      "required": [
        "severity",
        "code",
        "summary"
      ],
      "description": "A structured finding an execution reported on its way, distinct from its outcome."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    },
    "ExecutionError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`."
        },
        "message": {
          "type": "string",
          "description": "What went wrong, for a person."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "What to do about it, when there is something."
        },
        "correlation_id": {
          "type": "string",
          "description": "The execution this failure belongs to, so a log line and a UI agree."
        }
      },
      "required": [
        "code",
        "message",
        "correlation_id"
      ],
      "description": "Why an execution ended badly, in the repository's diagnostic vocabulary rather than in\nRust's: a code a program branches on, a sentence a person reads, and where to look.\n\nA panic message and a backtrace are never in here. The engine catches a panicking\nhandler and reports `internal` with the execution's correlation id; the panic itself is\non the process's own error stream, where the operator running the server can read it."
    }
  }
}