@opensoftware/contracts 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
     "@typespec/openapi": "1.17.0",
     "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.33.0"
+    "@opensoftware/testkit": "0.34.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/typespec/events.tsp

@@ -39,12 +39,24 @@ model CloudEvent<Type extends string, Data> {
 /** intake: a work item was accepted. */
 model WorkReceived is CloudEvent<"work.received@v1", WorkItem>;
 
+/** intake: a person asked to run a work item's run again (ADR 0105). The ID is `<run ID>.retry`. */
+model WorkRetryRequested is CloudEvent<"work.retry-requested@v1", WorkRetryRequestedData>;
+
 /** foreman: a run started (ADR 0067). */
 model RunStarted is CloudEvent<"run.started@v1", RunStartedData>;
 
 /** foreman: a run ended. */
 model RunCompleted is CloudEvent<"run.completed@v1", RunCompletedData>;
 
+/** foreman: a stage of a run waits for the checks of its pull request (ADR 0127). The ID is `<run ID>.blocked.<stage>`. */
+model RunBlocked is CloudEvent<"run.blocked@v1", RunBlockedData>;
+
+/**
+ * console: `console doctor --deep` checks that an event reaches the foreman (ADR 0120). The ID is fresh and random;
+ * the foreman shows it on `GET /v1/doctor/pings/{id}` and acts on nothing else.
+ */
+model DoctorPing is CloudEvent<"doctor.ping@v1", DoctorPingData>;
+
 /** gatekeeper: a decision is needed before a stage starts. */
 model GateRequested is CloudEvent<"gate.requested@v1", GateRequestedData>;
 
@@ -81,6 +93,9 @@ model RunStartedData {
   startedAt: utcDateTime;
   requester: Actor;
   source: Name;
+
+  /** The run before, when this run runs a work item again (ADR 0105). */
+  retryOf?: Identifier;
 }
 
 model RunCompletedData {
@@ -100,6 +115,49 @@ model RunCompletedData {
   traceId?: TraceId;
   pullRequests?: url[];
   evidenceBundle?: url;
+
+  /** The run before, when this run runs a work item again (ADR 0105). */
+  retryOf?: Identifier;
+
+  /** Why the stage the run ended at failed, when the foreman knows it (ADR 0127). */
+  reason?: string;
+}
+
+/** What a blocked stage waits for: the checks of the run's pull request. A gate has its own `gate.requested@v1`. */
+enum BlockedOn {
+  checks,
+}
+
+model RunBlockedData {
+  runId: Identifier;
+  workItemId: Identifier;
+
+  /** The stage that waits. */
+  stage: Name;
+
+  waitsFor: BlockedOn;
+
+  /** The pull request whose checks the stage waits for. */
+  pullRequest?: url;
+
+  /** The names of the checks the stage waits for. */
+  checks?: string[];
+
+  requester: Actor;
+  source: Name;
+}
+
+/** A ping carries nothing but its ID. */
+model DoctorPingData {}
+
+model WorkRetryRequestedData {
+  workItemId: Identifier;
+
+  /** The run to run again: the run the work item follows. */
+  runId: Identifier;
+
+  /** The person who asked. */
+  requester: Actor;
 }
 
 model GateRequestedData {

package/typespec/factory-definition.tsp

@@ -36,7 +36,7 @@ model FactoryDefinition {
   @minProperties(1)
   agents: Record<Agent>;
 
-  /** Stages in order. Each stage runs one agent; the agent defaults to the stage name. */
+  /** Stages in order. Each stage runs one agent, which defaults to the stage name, or only waits (ADR 0107). */
   workflow?: Stage[];
 
   /** What starts work without a person asking. */
@@ -155,6 +155,12 @@ model Stage {
 
   /** Whether the stage must produce an evidence bundle. */
   evidence?: EvidenceRequirement;
+
+  /**
+   * The stage runs no agent: it only waits for its checks, its evidence and its gate, then succeeds (ADR 0107). It
+   * names no agent and at least one of checks, evidence "required" or gate.
+   */
+  wait?: boolean;
 }
 
 /** The name of a check on the forge: a commit status context. */

package/typespec/factory-lock.tsp

@@ -0,0 +1,56 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/**
+ * factory.lock next to factory.yaml (ADR 0020, ADR 0125): the exact versions that `factory plan` pinned. factory-spec
+ * writes it; the foreman reads the pins of its adapters.
+ */
+model FactoryLock {
+  /** The version of the lock's format. */
+  version: 1;
+
+  /** The registry MCP servers, by their reference in factory.yaml, for example `registry:io.github.acme/tracker@1.4`. */
+  mcp: Record<FactoryLockMcpPin>;
+
+  /**
+   * The adapters under `providers` that `factory plan --adapters` pinned, per port and adapter name (ADR 0125). A pin
+   * counts only while its `range` is the range factory.yaml declares.
+   */
+  adapters?: Record<Record<FactoryLockAdapterPin>>;
+}
+
+/** One registry MCP server at its exact version, with the npm package or the remote it starts. */
+model FactoryLockMcpPin {
+  @minLength(1)
+  name: string;
+
+  @minLength(1)
+  version: string;
+
+  package?: {
+    registryType: "npm";
+    @minLength(1) identifier: string;
+    @minLength(1) version: string;
+  };
+
+  remote?: {
+    @minLength(1) type: string;
+    @minLength(1) url: string;
+  };
+}
+
+/** One adapter's npm package `@opensoftware/<port>-<name>` at the newest version inside its range. */
+@extension("additionalProperties", Json<false>)
+model FactoryLockAdapterPin {
+  /** The range under `providers` that the pin was resolved from, for example "^2". */
+  @minLength(1)
+  range: string;
+
+  /** The exact version, for example "2.3.1". */
+  @minLength(1)
+  version: string;
+}

package/typespec/foreman-api.tsp

@@ -10,7 +10,7 @@ using TypeSpec.Http;
 namespace Osf.Contracts;
 
 namespace ForemanApi {
-  /** Start a run of the factory's workflow for a work item. The same work item again answers the run it started. */
+  /** Start a run of the factory's workflow for a work item. The same work item again answers its newest run. */
   @route("/v1/runs")
   @post
   op startRun(@body workItem: WorkItem):
@@ -25,10 +25,18 @@ namespace ForemanApi {
     | GatekeeperApi.Failure<400>
     | GatekeeperApi.Failure<401>;
 
-  /** The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071). */
+  /**
+   * A page of the runs of the server, running runs first, then the runs that ended, the one that ended last first; with
+   * `state`, only the runs in that state (ADR 0071). `limit` runs at most, 50 by default; `cursor` is the `next` of the
+   * page before (ADR 0115). With `state`, a page may hold fewer runs than `limit` and still have a `next`.
+   */
   @route("/v1/runs")
   @get
-  op listRuns(@query state?: RunState): RunList | GatekeeperApi.Failure<400> | GatekeeperApi.Failure<401>;
+  op listRuns(
+    @query state?: RunState,
+    @query @minValue(1) @maxValue(500) limit?: int32,
+    @query @minLength(1) cursor?: string,
+  ): RunList | GatekeeperApi.Failure<400> | GatekeeperApi.Failure<401>;
 
   /** A run: its state and the state of each stage. */
   @route("/v1/runs/{runId}")
@@ -47,4 +55,25 @@ namespace ForemanApi {
     | GatekeeperApi.Failure<401>
     | GatekeeperApi.Failure<404>
     | GatekeeperApi.Failure<409>;
+
+  /** Run a run that failed or was cancelled again, as a new run that names it (ADR 0105). */
+  @route("/v1/runs/{runId}/retry")
+  @post
+  op retryRun(@path runId: string, @body retry: RunRetry):
+    | {
+        @statusCode statusCode: 201;
+        @body run: RunView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>
+    | GatekeeperApi.Failure<404>
+    | GatekeeperApi.Failure<409>;
+
+  /**
+   * The `doctor.ping@v1` event with this ID, when the foreman's consumer received it since the server started (ADR
+   * 0120). `console doctor --deep` asks for it after it published the event.
+   */
+  @route("/v1/doctor/pings/{id}")
+  @get
+  op getDoctorPing(@path id: string): DoctorPingSeen | GatekeeperApi.Failure<401> | GatekeeperApi.Failure<404>;
 }

package/typespec/foreman.tsp

@@ -45,14 +45,24 @@ model CheckView {
 model StageView {
   stage: Name;
 
-  /** The agent that runs the stage. */
+  /** The agent that runs the stage; the stage's name for a stage that only waits (ADR 0107). */
   agent: Name;
 
+  /** True for a stage that only waits: it runs no agent and starts no session (ADR 0107). */
+  wait?: boolean;
+
   state: StageState;
 
   /** The harness session of the stage's agent, once it started. */
   sessionId?: string;
 
+  /**
+   * The span of the stage in the run's trace, once it started: the first 16 hex digits of the SHA-256 of
+   * `<runId>:<stage index>` (ADR 0087, ADR 0121).
+   */
+  @pattern("^[0-9a-f]{16}$")
+  spanId?: string;
+
   /** The gate that decides whether the stage starts, once it was requested. */
   @pattern("^g[0-9a-f]{16}$")
   gateId?: string;
@@ -60,6 +70,9 @@ model StageView {
   /** The checks the stage waits for, once the foreman read them (ADR 0069). */
   checks?: CheckView[];
 
+  /** Since when the stage waits for its checks, its gate or a person, while it is blocked (ADR 0106). */
+  waitingSince?: utcDateTime;
+
   /** When a person took the stage over from its agent (ADR 0070). */
   takenOverAt?: utcDateTime;
 
@@ -67,16 +80,51 @@ model StageView {
   @minLength(1)
   reason?: string;
 
+  /** Why the stage gave the run no pull request: a refused link, a branch the forge has none of, or the forge adapter's error (ADR 0109). */
+  @minLength(1)
+  note?: string;
+
   startedAt?: utcDateTime;
   endedAt?: utcDateTime;
 }
 
 /** foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067). */
+/** An adapter of the factory's `providers` and the version a run of it asks for (ADR 0110). */
+model AdapterVersion {
+  /** The port under `providers`: harness, sandbox, forge or inference. */
+  port: "harness" | "sandbox" | "forge" | "inference";
+
+  @minLength(1)
+  name: string;
+
+  /** The exact version that factory.lock pins for the range under `providers.<port>.<name>`, else that range (ADR 0125). */
+  @minLength(1)
+  version?: string;
+
+  /** The command line the foreman builds when no map names the adapter: npx at the version. */
+  command?: string[];
+
+  /** The variable whose map gives the adapter's command line instead, for example "FOREMAN_HARNESSES". */
+  @minLength(1)
+  configured?: string;
+}
+
 model RunView {
-  /** "run_" and 20 hex digits of the SHA-256 of the work item's ID. */
+  /** "run_" and 20 hex digits of the SHA-256 of the work item's ID; for the n-th run of the work item, n ≥ 2, of "<work item ID>#<n>" (ADR 0105). */
   @pattern("^run_[0-9a-f]{20}$")
   runId: string;
 
+  /** Which run of the work item this is: 1 when absent (ADR 0105). */
+  @minValue(1)
+  attempt?: safeint;
+
+  /** The run before this one, which a person ran again (ADR 0105). */
+  @pattern("^run_[0-9a-f]{20}$")
+  retryOf?: string;
+
+  /** The person who ran the run before again (ADR 0105). */
+  retriedBy?: Actor;
+
   workItem: WorkItem;
 
   /** The name of the factory. */
@@ -85,9 +133,12 @@ model RunView {
   /** The commit of the factory definition the run started with. */
   factoryVersion: CommitHash;
 
+  /** The adapters of the factory's `providers` and the versions the run asks for (ADR 0110). */
+  adapters?: AdapterVersion[];
+
   state: RunState;
 
-  /** The last pull request link that an agent of the run wrote (ADR 0069). */
+  /** The run's pull request: the forge's of the run's branch, the one an agent stated, or else the last link an agent wrote (ADR 0069, ADR 0109). */
   pullRequest?: url;
 
   /** The run's folder on the foreman's machine, where a person who took over a stage goes on (ADR 0070). */
@@ -102,11 +153,18 @@ model RunView {
 
   /** The stages of the workflow, in order. */
   stages: StageView[];
+
+  /** The signals that named their person, oldest first (ADR 0118). */
+  actions?: RunAction[];
 }
 
 /** foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071). */
 model RunList {
   runs: RunView[];
+
+  /** The cursor of the next page, while more runs follow (ADR 0115). */
+  @minLength(1)
+  next?: string;
 }
 
 /** foreman: what a person tells a run. */
@@ -127,4 +185,42 @@ model RunSignal {
   /** The steering message. Required with "steer". */
   @minLength(1)
   message?: string;
+
+  /** The person who sends the signal; the run then records it in `actions` (ADR 0118). */
+  by?: Actor;
+}
+
+/** foreman: a signal a person sent a run, as the run records it (ADR 0118). */
+model RunAction {
+  type: RunSignalType;
+
+  /** The person who sent it. */
+  by: Actor;
+
+  /** When the foreman took it. */
+  at: utcDateTime;
+
+  /** The steering message of "steer". */
+  @minLength(1)
+  message?: string;
+}
+
+/**
+ * foreman: run a run that failed or was cancelled again, as a new run (ADR 0105). The new run starts at the first stage
+ * that did not succeed, or at `from`, a stage at or before it.
+ */
+model RunRetry {
+  /** The person who asks. */
+  by: Actor;
+
+  from?: Name;
+}
+
+/** foreman: a `doctor.ping@v1` event that its consumer received (ADR 0120). */
+model DoctorPingSeen {
+  /** The event's ID. */
+  id: Identifier;
+
+  /** When the foreman received it. */
+  receivedAt: utcDateTime;
 }

package/typespec/gatekeeper-api.tsp

@@ -36,4 +36,18 @@ namespace GatekeeperApi {
   @route("/v1/gates/{gateId}")
   @get
   op getGate(@path gateId: string): GateView | Failure<401> | Failure<404>;
+
+  /**
+   * A person decides a pending gate (ADR 0118): 403 when they are in no group the gate waits for, 409 when the gate
+   * is no longer pending.
+   */
+  @route("/v1/gates/{gateId}/decisions")
+  @post
+  op decideGate(@path gateId: string, @body decision: GateDecisionRequest):
+    | GateView
+    | Failure<400>
+    | Failure<401>
+    | Failure<403>
+    | Failure<404>
+    | Failure<409>;
 }

package/typespec/gatekeeper.tsp

@@ -132,3 +132,18 @@ model ApiProblem {
   /** What went wrong this time, for example the field that is missing. */
   detail?: string;
 }
+
+/**
+ * gatekeeper: a person's decision of a pending gate through the API, as a member of a group the gate waits for
+ * (ADR 0118). It decides like a reply "approve" or "reject <reason>" in the gate's channel.
+ */
+model GateDecisionRequest {
+  decision: "approved" | "rejected";
+
+  /** The person who decides; their `id` must be a member of a group in `waitingFor`. */
+  by: Actor;
+
+  /** The reason of a rejection. */
+  @minLength(1)
+  reason?: string;
+}

package/typespec/intake-api.tsp

@@ -33,10 +33,17 @@ namespace IntakeApi {
     | GatekeeperApi.Failure<401>
     | GatekeeperApi.Failure<404>;
 
-  /** The 50 latest work items, the one received last first; with `status`, only the work items in that status. */
+  /**
+   * A page of the latest work items, the one received last first; with `status`, only the work items in that status.
+   * `limit` work items at most, 50 by default; `cursor` is the `next` of the page before (ADR 0115).
+   */
   @route("/v1/inbox")
   @get
-  op listWorkItems(@query status?: WorkItemStatus):
+  op listWorkItems(
+    @query status?: WorkItemStatus,
+    @query @minValue(1) @maxValue(500) limit?: int32,
+    @query @minLength(1) cursor?: string,
+  ):
     | WorkItemList
     | GatekeeperApi.Failure<400>
     | GatekeeperApi.Failure<401>;

package/typespec/intake.tsp

@@ -46,6 +46,10 @@ model WorkRequest {
 /** intake: the latest work items, as `GET /v1/inbox` answers them, the one received last first. */
 model WorkItemList {
   workItems: WorkItemView[];
+
+  /** The cursor of the next page, while more work items follow (ADR 0115). */
+  @minLength(1)
+  next?: string;
 }
 
 /** intake: a work item as the HTTP API shows it (ADR 0063). */

package/typespec/main.tsp

@@ -15,4 +15,5 @@ import "./intake-api.tsp";
 import "./foreman.tsp";
 import "./foreman-api.tsp";
 import "./sandbox.tsp";
+import "./factory-lock.tsp";
 import "./health.tsp";