executions.report
What `majordomus run` posts while it runs a capability in its own process and a server already serves the checkout: the execution's description and its events after the last sequence this server took. The server holds it as an execution started by the command line, with the pid, in the same store, listing, Cockpit pages and live channel as its own; applies each event once and in order, answering where the next report starts; tells the reporter when somebody asked it to stop; and fails it with `unavailable` once the reporter has been silent for 30 s. Nothing runs here. Changes this process's memory only.
What `majordomus run` posts while it runs a capability in its own process and a server already serves the checkout: the execution's description and its events after the last sequence this server took. The server holds it as an execution started by the command line, with the pid, in the same store, listing, Cockpit pages and live channel as its own; applies each event once and in order, answering where the next report starts; tells the reporter when somebody asked it to stop; and fails it with `unavailable` once the reporter has been silent for 30 s. Nothing runs here. Changes this process's memory only.
- command
- behaviorally_verified
- module executions
- #executions
- #control-plane
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | — |
| HTTP | POST /api/v1/executions/report operationId executions.report |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · ReportInput
The input of
executions.report: what a process that runs an execution says about it to
the server serving the same checkout.| property | type | required | description |
|---|---|---|---|
| cancellable | boolean | no | Whether the capability stops when asked. When it does, a cancel asked of this server reaches the reporter in the answer to its next report. default false |
| capability | string | yes | The capability it runs, by its canonical id. |
| events | array | no | Its events after the last sequence this server answered through, in its own
sequence, oldest first; at most 500. Empty is a heartbeat. default [] |
| id | string | yes | The execution's id, as the reporting process minted it. |
| input | object | no | The input it was given, as the reporting process stored it: already redacted there, and redacted again here by this registry's schema when this registry knows it. default null |
| pid | integer | yes | The process that runs it. |
| title | string | yes | That capability's title. |
JSON Schema
{
"$defs": {
"ExecutionDiagnostic": {
"description": "A structured finding an execution reported on its way, distinct from its outcome.",
"properties": {
"code": {
"description": "A stable machine-readable code.",
"type": "string"
},
"detail": {
"description": "The rest, when there is more.",
"type": [
"string",
"null"
]
},
"severity": {
"$ref": "#/$defs/Severity",
"description": "How bad."
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
},
"summary": {
"description": "One line, for a person.",
"type": "string"
}
},
"required": [
"severity",
"code",
"summary"
],
"type": "object"
},
"ExecutionError": {
"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.",
"properties": {
"code": {
"description": "`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`.",
"type": "string"
},
"correlation_id": {
"description": "The execution this failure belongs to, so a log line and a UI agree.",
"type": "string"
},
"message": {
"description": "What went wrong, for a person.",
"type": "string"
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
}
},
"required": [
"code",
"message",
"correlation_id"
],
"type": "object"
},
"ExecutionEvent": {
"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.",
"oneOf": [
{
"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.",
"properties": {
"data": {
"properties": {
"capability": {
"description": "The capability's canonical id.",
"type": "string"
},
"input": {
"description": "The input, with sensitive values already replaced."
},
"title": {
"description": "Its title.",
"type": "string"
}
},
"required": [
"capability",
"title",
"input"
],
"type": "object"
},
"type": {
"const": "execution.created",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "It is waiting for a worker.",
"properties": {
"data": {
"properties": {
"ahead": {
"description": "How many executions are ahead of it.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"ahead"
],
"type": "object"
},
"type": {
"const": "execution.queued",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A worker picked it up and is about to enter the handler.",
"properties": {
"type": {
"const": "execution.started",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"description": "How far along it is.",
"properties": {
"data": {
"$ref": "#/$defs/ProgressView"
},
"type": {
"const": "execution.progress",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A named phase was entered.",
"properties": {
"data": {
"properties": {
"name": {
"description": "The step's stable name.",
"type": "string"
},
"title": {
"description": "One line for a reader.",
"type": "string"
}
},
"required": [
"name",
"title"
],
"type": "object"
},
"type": {
"const": "execution.step.started",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A named phase finished.",
"properties": {
"data": {
"properties": {
"detail": {
"description": "What it said, when it said anything.",
"type": [
"string",
"null"
]
},
"name": {
"description": "The step's stable name.",
"type": "string"
},
"ok": {
"description": "Whether what it was asked to do happened.",
"type": "boolean"
}
},
"required": [
"name",
"ok"
],
"type": "object"
},
"type": {
"const": "execution.step.completed",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A line of output.",
"properties": {
"data": {
"properties": {
"message": {
"description": "The text, with control characters and terminal escapes already removed.",
"type": "string"
},
"stream": {
"$ref": "#/$defs/LogStream",
"description": "Which stream it came from."
}
},
"required": [
"stream",
"message"
],
"type": "object"
},
"type": {
"const": "execution.log",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A structured finding, distinct from the outcome.",
"properties": {
"data": {
"$ref": "#/$defs/ExecutionDiagnostic"
},
"type": {
"const": "execution.diagnostic",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "Cancellation was asked for; the handler has not stopped yet.",
"properties": {
"data": {
"properties": {
"by": {
"description": "Who asked, in one word.",
"type": "string"
}
},
"required": [
"by"
],
"type": "object"
},
"type": {
"const": "execution.cancelling",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "It stopped because it was asked to.",
"properties": {
"type": {
"const": "execution.cancelled",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"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.",
"properties": {
"data": {
"properties": {
"output": {
"description": "What the handler returned."
}
},
"required": [
"output"
],
"type": "object"
},
"type": {
"const": "execution.completed",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "It finished, and it did not.",
"properties": {
"data": {
"properties": {
"error": {
"$ref": "#/$defs/ExecutionError",
"description": "Why."
}
},
"required": [
"error"
],
"type": "object"
},
"type": {
"const": "execution.failed",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
}
],
"properties": {
"event_id": {
"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.",
"type": "string"
},
"execution_id": {
"$ref": "#/$defs/ExecutionId",
"description": "The execution it is about."
},
"schema_version": {
"description": "The protocol version, `PROTOCOL_VERSION`.",
"type": "string"
},
"sequence": {
"description": "Its position in that execution's stream, from 1, without gaps.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"timestamp": {
"description": "When the event was produced, RFC 3339 in UTC.",
"type": "string"
}
},
"required": [
"schema_version",
"event_id",
"execution_id",
"sequence",
"timestamp"
],
"type": "object"
},
"ExecutionId": {
"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.",
"type": "string"
},
"LogStream": {
"description": "Which stream a log line came from.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"ProgressView": {
"description": "How far along an execution is.",
"properties": {
"current": {
"description": "Units done.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"message": {
"description": "What is being done, for a reader.",
"type": [
"string",
"null"
]
},
"total": {
"description": "Units in total, when the handler knows how many.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"current"
],
"type": "object"
},
"Severity": {
"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.",
"oneOf": [
{
"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.",
"type": "string"
}
]
}
},
"additionalProperties": false,
"description": "The input of `executions.report`: what a process that runs an execution says about it to\nthe server serving the same checkout.",
"properties": {
"cancellable": {
"default": false,
"description": "Whether the capability stops when asked. When it does, a cancel asked of this server\nreaches the reporter in the answer to its next report.",
"type": "boolean"
},
"capability": {
"description": "The capability it runs, by its canonical id.",
"type": "string"
},
"events": {
"default": [],
"description": "Its events after the last sequence this server answered `through`, in its own\nsequence, oldest first; at most 500. Empty is a heartbeat.",
"items": {
"$ref": "#/$defs/ExecutionEvent"
},
"type": "array"
},
"id": {
"description": "The execution's id, as the reporting process minted it.",
"type": "string"
},
"input": {
"default": null,
"description": "The input it was given, as the reporting process stored it: already redacted there,\nand redacted again here by this registry's schema when this registry knows it."
},
"pid": {
"description": "The process that runs it.",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"title": {
"description": "That capability's title.",
"type": "string"
}
},
"required": [
"id",
"capability",
"title",
"pid"
],
"title": "ReportInput",
"type": "object"
}output · ReportAnswer
The answer of
executions.report.| property | type | required | description |
|---|---|---|---|
| applied | integer | yes | How many of the reported events were applied. |
| cancel_requested | boolean | yes | Whether somebody asked this server to stop the execution. The reporter runs it, so the reporter cancels it. |
| execution | reference | yes | The execution as this server now holds it. |
| through | integer | yes | The reporter's sequence this server holds everything up to: the next report sends the events after it, so a lost or repeated report costs nothing. |
JSON Schema
{
"$defs": {
"Actor": {
"description": "Who asked, and which peer they are when this process knows.",
"properties": {
"kind": {
"$ref": "#/$defs/ActorKind",
"description": "Where the request came from."
},
"peer": {
"description": "The peer id, for a call that arrived through an MCP session.",
"type": [
"string",
"null"
]
},
"pid": {
"description": "The process that ran it, for an execution another process ran and reported to this\none: the work happened there, and this process holds what it was told about it.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"kind"
],
"type": "object"
},
"ActorKind": {
"description": "Who asked for the execution. Not an authorisation decision — this server authenticates\nnobody — but a fact worth carrying into the audit line and the UI.",
"oneOf": [
{
"const": "http",
"description": "An HTTP client, which includes the Cockpit.",
"type": "string"
},
{
"const": "mcp",
"description": "An MCP client attached to this process.",
"type": "string"
},
{
"const": "cli",
"description": "A command line: this process's own, or `majordomus run` in another process of the\nsame checkout that reported its execution to this server, with its pid.",
"type": "string"
},
{
"const": "internal",
"description": "This executable's own tests and benchmarks.",
"type": "string"
}
]
},
"ExecutionDiagnostic": {
"description": "A structured finding an execution reported on its way, distinct from its outcome.",
"properties": {
"code": {
"description": "A stable machine-readable code.",
"type": "string"
},
"detail": {
"description": "The rest, when there is more.",
"type": [
"string",
"null"
]
},
"severity": {
"$ref": "#/$defs/Severity",
"description": "How bad."
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
},
"summary": {
"description": "One line, for a person.",
"type": "string"
}
},
"required": [
"severity",
"code",
"summary"
],
"type": "object"
},
"ExecutionError": {
"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.",
"properties": {
"code": {
"description": "`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`.",
"type": "string"
},
"correlation_id": {
"description": "The execution this failure belongs to, so a log line and a UI agree.",
"type": "string"
},
"message": {
"description": "What went wrong, for a person.",
"type": "string"
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
}
},
"required": [
"code",
"message",
"correlation_id"
],
"type": "object"
},
"ExecutionId": {
"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.",
"type": "string"
},
"ExecutionLinks": {
"description": "Where to read more about one execution, in this server's own terms.\n\nEvery value is derived from the registry's declared routes and from the live channel's\nown constant, so a route that moves moves here too and no client holds a path this\nserver does not serve.",
"properties": {
"cancel": {
"description": "Where to ask it to stop: `POST /api/v1/executions/cancel`.",
"type": "string"
},
"cockpit": {
"description": "The page a person opens.",
"type": "string"
},
"events": {
"description": "The retained history: `GET /api/v1/executions/events?id=…`.",
"type": "string"
},
"self": {
"description": "The snapshot: `GET /api/v1/executions/get?id=…`.",
"type": "string"
},
"websocket": {
"description": "The live channel, from the beginning: `GET /events?execution=…`.",
"type": "string"
}
},
"required": [
"self",
"events",
"cancel",
"websocket",
"cockpit"
],
"type": "object"
},
"ExecutionState": {
"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.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"ExecutionView": {
"description": "One execution with the links to everything else about it.",
"properties": {
"actor": {
"$ref": "#/$defs/Actor",
"description": "Who asked for it."
},
"cancellable": {
"description": "Whether asking to cancel this execution will do anything: the capability's policy.",
"type": "boolean"
},
"capability": {
"description": "The capability that ran, by its canonical id.",
"type": "string"
},
"correlation_id": {
"description": "The id used in this process's logs and tracing spans for this execution; the\nexecution id itself, carried under the name a reader of a log expects.",
"type": "string"
},
"created_at": {
"description": "When it was accepted, RFC 3339 in UTC.",
"type": "string"
},
"diagnostics": {
"description": "The findings it reported.",
"items": {
"$ref": "#/$defs/ExecutionDiagnostic"
},
"type": "array"
},
"duration_ms": {
"description": "How long it ran, in milliseconds, once it has finished.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/$defs/ExecutionError"
},
{
"type": "null"
}
],
"description": "Why it failed, for a failed execution and never before."
},
"event_count": {
"description": "How many events it has produced, including the ones no longer retained.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"events_truncated": {
"description": "Whether the retained event history has lost its oldest entries to the bound.",
"type": "boolean"
},
"finished_at": {
"description": "When it reached a final state.",
"type": [
"string",
"null"
]
},
"id": {
"$ref": "#/$defs/ExecutionId",
"description": "The identity."
},
"input": {
"description": "The input it was given, with every value the input schema marks sensitive replaced."
},
"last_sequence": {
"description": "The sequence number of the last event: the cursor a client subscribes from.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"links": {
"$ref": "#/$defs/ExecutionLinks",
"description": "Where to read more."
},
"output": {
"description": "What the handler returned, for a succeeded execution and never before."
},
"progress": {
"anyOf": [
{
"$ref": "#/$defs/ProgressView"
},
{
"type": "null"
}
],
"description": "The last progress the handler reported."
},
"repository": {
"$ref": "#/$defs/RepositoryRef",
"description": "Which repository it ran against."
},
"started_at": {
"description": "When the handler was entered.",
"type": [
"string",
"null"
]
},
"state": {
"$ref": "#/$defs/ExecutionState",
"description": "Where it is."
},
"steps": {
"description": "The steps it entered, in order.",
"items": {
"$ref": "#/$defs/StepView"
},
"type": "array"
},
"title": {
"description": "That capability's title, so a list needs no second lookup.",
"type": "string"
}
},
"required": [
"id",
"capability",
"title",
"state",
"created_at",
"input",
"last_sequence",
"event_count",
"events_truncated",
"cancellable",
"actor",
"repository",
"correlation_id",
"links"
],
"type": "object"
},
"ProgressView": {
"description": "How far along an execution is.",
"properties": {
"current": {
"description": "Units done.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"message": {
"description": "What is being done, for a reader.",
"type": [
"string",
"null"
]
},
"total": {
"description": "Units in total, when the handler knows how many.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"current"
],
"type": "object"
},
"RepositoryRef": {
"description": "Which repository, and which checkout of it, an execution ran against.\n\nAn execution is never run against \"wherever this process happens to be\": the engine\nstamps the repository the index was read from, and a request that names a different one\nis refused. The path itself is not here — this value is served to whoever can reach the\nsocket, and where the checkout sits on the host is of no use to them.",
"properties": {
"branch": {
"description": "The branch checked out, when git can say.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The stable identity two processes over one checkout both compute.",
"type": "string"
},
"name": {
"description": "The repository's name: the last component of its root.",
"type": "string"
}
},
"required": [
"name",
"id"
],
"type": "object"
},
"Severity": {
"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.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"StepState": {
"description": "Where a step of an execution stands.",
"oneOf": [
{
"const": "running",
"description": "Entered and not finished.",
"type": "string"
},
{
"const": "completed",
"description": "Finished, and what it was asked to do happened.",
"type": "string"
},
{
"const": "failed",
"description": "Finished, and it did not.",
"type": "string"
}
]
},
"StepView": {
"description": "One named phase of an execution, as the handler reported it.",
"properties": {
"detail": {
"description": "What it said when it finished, when it said anything.",
"type": [
"string",
"null"
]
},
"finished_at": {
"description": "When it finished, when it has.",
"type": [
"string",
"null"
]
},
"name": {
"description": "A stable name, unique within the execution.",
"type": "string"
},
"started_at": {
"description": "When it was entered, RFC 3339 in UTC.",
"type": "string"
},
"state": {
"$ref": "#/$defs/StepState",
"description": "Where it stands."
},
"title": {
"description": "One line for a reader.",
"type": "string"
}
},
"required": [
"name",
"title",
"state",
"started_at"
],
"type": "object"
}
},
"description": "The answer of `executions.report`.",
"properties": {
"applied": {
"description": "How many of the reported events were applied.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"cancel_requested": {
"description": "Whether somebody asked this server to stop the execution. The reporter runs it, so\nthe reporter cancels it.",
"type": "boolean"
},
"execution": {
"$ref": "#/$defs/ExecutionView",
"description": "The execution as this server now holds it."
},
"through": {
"description": "The reporter's sequence this server holds everything up to: the next report sends\nthe events after it, so a lost or repeated report costs nothing.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"applied",
"through",
"cancel_requested",
"execution"
],
"title": "ReportAnswer",
"type": "object"
}Policies
- benchmark
- waived — waived: transient_state
- cache
- disabled — every call runs the handler
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.
| transport | state | cases | targets |
|---|---|---|---|
| direct | waived (transient_state) | 0 | |
| http | waived (transient_state) | 0 |