@opensoftware/contracts 1.6.0 → 1.7.0

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
@@ -116,6 +116,355 @@
           }
         }
       }
+    },
+    "/v1/runs": {
+      "post": {
+        "operationId": "ForemanApi_startRun",
+        "description": "Start a run of the factory's workflow for a work item. The same work item again answers the run it started.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WorkItem"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{runId}": {
+      "get": {
+        "operationId": "ForemanApi_getRun",
+        "description": "A run: its state and the state of each stage.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{runId}/signals": {
+      "post": {
+        "operationId": "ForemanApi_signalRun",
+        "description": "Steer the running stage's agent, or cancel the run.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "description": "The request has been accepted for processing, but processing has not yet completed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The request conflicts with the current state of the server.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RunSignal"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items": {
+      "post": {
+        "operationId": "IntakeApi_submitWork",
+        "description": "Put work into the inbox. A submission with the dedupe key of a work item answers that work item.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WorkSubmission"
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "IntakeApi_findWorkItem",
+        "description": "The work item with this dedupe key, such as an issue's link (ADR 0065).",
+        "parameters": [
+          {
+            "name": "dedupeKey",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "explode": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items/{workItemId}": {
+      "get": {
+        "operationId": "IntakeApi_getWorkItem",
+        "description": "A work item, its status and every request that asked for it.",
+        "parameters": [
+          {
+            "name": "workItemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "security": [
@@ -952,6 +1301,108 @@
         "maxLength": 128,
         "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
       },
+      "IssueLabeled": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "issue.labeled@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/IssueLabeledData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "forge adapters: a label was added to an issue."
+      },
+      "IssueLabeledData": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The issue."
+          },
+          "repository": {
+            "type": "string",
+            "format": "uri"
+          },
+          "number": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "body": {
+            "type": "string"
+          },
+          "author": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who opened the issue."
+          },
+          "labels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Every label of the issue after the change."
+          },
+          "label": {
+            "type": "string",
+            "description": "The label that was added, when the forge names it."
+          }
+        },
+        "required": [
+          "url",
+          "repository",
+          "number",
+          "title",
+          "author",
+          "labels"
+        ]
+      },
       "Link": {
         "type": "object",
         "properties": {
@@ -1570,7 +2021,32 @@
           "osf.source",
           "osf.harness.name"
         ],
-        "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+        "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+      },
+      "RunSignal": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/RunSignalType"
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The steering message. Required with \"steer\"."
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "description": "foreman: a signal to a run: \"steer\" with a message for the running stage's agent, or \"cancel\"."
+      },
+      "RunSignalType": {
+        "type": "string",
+        "enum": [
+          "steer",
+          "cancel"
+        ],
+        "description": "foreman: what a person tells a run."
       },
       "RunSpan": {
         "type": "object",
@@ -1662,6 +2138,165 @@
         ],
         "description": "Attributes of the root span of the run. GenAI names where a convention exists."
       },
+      "RunStarted": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "run.started@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/RunStartedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "foreman: a run started (ADR 0067)."
+      },
+      "RunStartedData": {
+        "type": "object",
+        "properties": {
+          "runId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "workItemId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "factory": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name of the factory."
+          },
+          "factoryVersion": {
+            "$ref": "#/components/schemas/CommitHash"
+          },
+          "stages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The stages of the run's workflow, in order."
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Name"
+          }
+        },
+        "required": [
+          "runId",
+          "workItemId",
+          "factory",
+          "factoryVersion",
+          "stages",
+          "startedAt",
+          "requester",
+          "source"
+        ]
+      },
+      "RunState": {
+        "type": "string",
+        "enum": [
+          "running",
+          "blocked",
+          "complete",
+          "failed",
+          "cancelled"
+        ],
+        "description": "foreman: where a run stands (vision scenario ORCH-008)."
+      },
+      "RunView": {
+        "type": "object",
+        "properties": {
+          "runId": {
+            "type": "string",
+            "pattern": "^run_[0-9a-f]{20}$",
+            "description": "\"run_\" and 20 hex digits of the SHA-256 of the work item's ID."
+          },
+          "workItem": {
+            "$ref": "#/components/schemas/WorkItem"
+          },
+          "factory": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name of the factory."
+          },
+          "factoryVersion": {
+            "$ref": "#/components/schemas/CommitHash",
+            "description": "The commit of the factory definition the run started with."
+          },
+          "state": {
+            "$ref": "#/components/schemas/RunState"
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "endedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "stages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StageView"
+            },
+            "description": "The stages of the workflow, in order."
+          }
+        },
+        "required": [
+          "runId",
+          "workItem",
+          "factory",
+          "factoryVersion",
+          "state",
+          "startedAt",
+          "stages"
+        ],
+        "description": "foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067)."
+      },
       "Sandbox": {
         "type": "object",
         "properties": {
@@ -2031,6 +2666,57 @@
         ],
         "additionalProperties": false
       },
+      "StageState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "blocked",
+          "running",
+          "succeeded",
+          "failed",
+          "rejected",
+          "cancelled"
+        ],
+        "description": "foreman: where a stage of a run stands."
+      },
+      "StageView": {
+        "type": "object",
+        "properties": {
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "agent": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The agent that runs the stage."
+          },
+          "state": {
+            "$ref": "#/components/schemas/StageState"
+          },
+          "sessionId": {
+            "type": "string",
+            "description": "The harness session of the stage's agent, once it started."
+          },
+          "gateId": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$",
+            "description": "The gate that decides whether the stage starts, once it was requested."
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "endedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "stage",
+          "agent",
+          "state"
+        ],
+        "description": "foreman: one stage of a run (ADR 0067)."
+      },
       "TraceId": {
         "type": "string",
         "pattern": "^[0-9a-f]{32}$",
@@ -2104,6 +2790,13 @@
         ],
         "description": "One unit of requested work: the `data` of a `work.received@v1` CloudEvent."
       },
+      "WorkItemStatus": {
+        "type": "string",
+        "enum": [
+          "received"
+        ],
+        "description": "Where a work item stands."
+      },
       "WorkItemType": {
         "type": "string",
         "enum": [
@@ -2113,6 +2806,36 @@
           "automation"
         ]
       },
+      "WorkItemView": {
+        "type": "object",
+        "properties": {
+          "workItem": {
+            "$ref": "#/components/schemas/WorkItem",
+            "description": "Its ID is \"wi_\" and 20 hex digits of the SHA-256 of its dedupe key."
+          },
+          "status": {
+            "$ref": "#/components/schemas/WorkItemStatus"
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "requests": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/WorkRequest"
+            },
+            "description": "Every submission that asked for the work item, oldest first; one per origin."
+          }
+        },
+        "required": [
+          "workItem",
+          "status",
+          "receivedAt",
+          "requests"
+        ],
+        "description": "intake: a work item as the HTTP API shows it (ADR 0063)."
+      },
       "WorkReceived": {
         "type": "object",
         "properties": {
@@ -2166,6 +2889,70 @@
           "data"
         ],
         "description": "intake: a work item was accepted."
+      },
+      "WorkRequest": {
+        "type": "object",
+        "properties": {
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/Origin"
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "requester",
+          "origin",
+          "receivedAt"
+        ],
+        "description": "intake: one submission that asked for a work item."
+      },
+      "WorkSubmission": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/WorkItemType",
+            "description": "Default: task."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          },
+          "description": {
+            "type": "string"
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/Origin"
+          },
+          "dedupeKey": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Requests with the same key become one work item. Default: the origin's url, else \"<source>:<externalId>\"."
+          },
+          "surface": {
+            "type": "string"
+          },
+          "links": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Link"
+            }
+          }
+        },
+        "required": [
+          "title",
+          "requester",
+          "origin"
+        ],
+        "description": "intake: work to put into the inbox, a work item without its ID (ADR 0063)."
       }
     },
     "securitySchemes": {