{
  "format": 1,
  "part": "build-step",
  "description": "What the three build seats share: the verbs that read and steer a node's builds, and the layouts of the asks they accept and the steps they keep. A seat lists its states against these (a part carries no states).",
  "verbs": [
    {
      "name": "current",
      "description": "The asks this node runs now (each ask's id, kind, module and when it started), its build capacity, and whether it is paused, taking no new ask.",
      "input": {
        "type": "object",
        "properties": {}
      },
      "answer": {
        "type": "object",
        "description": "the steps running, the capacity and whether paused"
      }
    },
    {
      "name": "pause",
      "description": "Take no new ask on this node until resumed; an ask running here ends in its place. Kept across a restart of the build module. A capacity of 0 is the lasting way to keep a node from building.",
      "input": {
        "type": "object",
        "properties": {}
      },
      "answer": {
        "type": "object",
        "description": "whether the node is paused"
      }
    },
    {
      "name": "resume",
      "description": "Take asks again on this node.",
      "input": {
        "type": "object",
        "properties": {}
      },
      "answer": {
        "type": "object",
        "description": "whether the node is paused"
      }
    }
  ],
  "defs": {
    "StepAsk": {
      "type": "object",
      "properties": {
        "v": {
          "type": "integer",
          "description": "the layout version"
        },
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "description": "build, check or compose"
        },
        "language": {
          "type": "string",
          "description": "go, typescript or image"
        },
        "asker": {
          "type": "string"
        },
        "at": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        },
        "build": {
          "type": "object",
          "properties": {
            "module": {
              "type": "string"
            },
            "path": {
              "type": "string"
            },
            "fp": {
              "type": "string"
            },
            "fetch": {
              "$ref": "#/defs/Fetch"
            },
            "artifacts": {
              "type": "array",
              "items": {
                "$ref": "#/defs/AskArtifact"
              }
            },
            "publish": {
              "type": "boolean"
            },
            "toolchain": {
              "$ref": "#/defs/ToolchainUsed"
            }
          },
          "required": [
            "module",
            "artifacts"
          ]
        },
        "check": {
          "type": "object",
          "properties": {
            "fetch": {
              "$ref": "#/defs/Fetch"
            },
            "levels": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "unit or integration"
              }
            },
            "kept": {
              "type": "boolean"
            },
            "runner": {
              "type": "string"
            },
            "runner_when": {
              "type": "string"
            },
            "run": {
              "type": "string"
            },
            "packages": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "toolchain": {
              "$ref": "#/defs/ToolchainUsed",
              "description": "the toolchain the checker agreed for the language (ADR 0584 clause 2): a node on another declines the check"
            },
            "node-names": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "the node names the check's tests run against"
            }
          },
          "required": [
            "fetch",
            "levels"
          ]
        },
        "compose": {
          "type": "object",
          "properties": {
            "fetch": {
              "$ref": "#/defs/Fetch"
            },
            "dir": {
              "type": "string"
            },
            "package": {
              "type": "string"
            },
            "request": {
              "description": "the compose-candidate request"
            },
            "reader": {
              "type": "string"
            }
          },
          "required": [
            "fetch",
            "dir",
            "package",
            "request"
          ]
        },
        "needs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "packages": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "package to the tagged version a build pins"
        }
      },
      "required": [
        "id",
        "kind",
        "language",
        "asker"
      ],
      "description": "one ask of a build module"
    },
    "BuildAnswer": {
      "type": "object",
      "properties": {
        "artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/defs/BuiltArtifact"
          }
        },
        "toolchain": {
          "$ref": "#/defs/ToolchainUsed"
        },
        "imports": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "out-of-step": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "artifacts"
      ]
    },
    "CheckAnswer": {
      "type": "object",
      "properties": {
        "fetch": {
          "$ref": "#/defs/FetchAnswer"
        },
        "levels": {
          "type": "array",
          "items": {
            "$ref": "#/defs/LevelAnswer"
          }
        }
      },
      "required": [
        "fetch"
      ]
    },
    "ComposeAnswer": {
      "type": "object",
      "properties": {
        "built": {
          "type": "boolean"
        },
        "key": {
          "type": "string"
        },
        "verdict": {
          "description": "the compose-candidate verdict"
        }
      },
      "required": [
        "built"
      ]
    },
    "Step": {
      "type": "object",
      "properties": {
        "v": {
          "type": "integer",
          "description": "the layout version"
        },
        "id": {
          "type": "string"
        },
        "tool": {
          "type": "string"
        },
        "node": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "description": "running, passed, failed or refused"
        },
        "started": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        },
        "ended": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        },
        "reason": {
          "type": "string"
        },
        "result": {
          "$ref": "#/defs/StepResult"
        },
        "what": {
          "type": "string"
        },
        "phase": {
          "type": "string"
        },
        "phase-at": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        },
        "owner": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "tool",
        "node",
        "state",
        "started"
      ],
      "description": "one step a build module runs on a node"
    },
    "Toolchain": {
      "type": "object",
      "properties": {
        "v": {
          "type": "integer",
          "description": "the layout version"
        },
        "language": {
          "type": "string",
          "description": "go or typescript"
        },
        "version": {
          "type": "string"
        },
        "recipe": {
          "type": "string"
        },
        "at": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        }
      },
      "required": [
        "language",
        "version",
        "recipe"
      ],
      "description": "the toolchain a node reports"
    },
    "Pause": {
      "type": "object",
      "properties": {
        "v": {
          "type": "integer",
          "description": "the layout version"
        },
        "paused": {
          "type": "boolean"
        },
        "by": {
          "type": "string"
        },
        "at": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        }
      },
      "required": [
        "paused"
      ],
      "description": "whether the node takes no new ask"
    },
    "Capacity": {
      "type": "object",
      "properties": {
        "v": {
          "type": "integer",
          "description": "the layout version"
        },
        "effective": {
          "type": "integer"
        },
        "configured": {
          "type": "integer"
        },
        "configured-from": {
          "type": "string"
        },
        "quota-cores": {
          "type": "number"
        },
        "quota-from": {
          "type": "string"
        },
        "cores-per-step": {
          "type": "number"
        },
        "by-cpu": {
          "type": "integer"
        },
        "build-hours": {
          "type": "string"
        },
        "outside-hours": {
          "type": "boolean"
        },
        "build-hours-fault": {
          "type": "string"
        },
        "ineligible": {
          "type": "string"
        },
        "why": {
          "type": "string"
        },
        "at": {
          "type": "string",
          "description": "when (RFC 3339 time)",
          "format": "date-time"
        }
      },
      "required": [
        "effective",
        "configured",
        "why"
      ],
      "description": "how many steps the node runs at once"
    },
    "Fetch": {
      "type": "object",
      "description": "what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, and the sibling repositories placed beside",
      "properties": {
        "repository": {
          "type": "string",
          "description": "<owner>/<name>"
        },
        "commit": {
          "type": "string",
          "description": "the full commit"
        },
        "ref": {
          "type": "string",
          "description": "the pull request's ref, when only its head carries the commit"
        },
        "base": {
          "type": "string",
          "description": "the trunk commit a merge preview merges onto"
        },
        "dir": {
          "type": "string",
          "description": "the module's directory in the repository (\".\" for its root), with paths"
        },
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "the paths the module names, relative to dir"
        },
        "packages": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "the version (a full commit) of each mesh package to build against, by its module path"
        },
        "package": {
          "type": "object",
          "description": "the TypeScript module's group package: the group's tagged version of the SDK ({name, version}), placed from the registry in each member whatever its lock names, or the group's package member ({repository, commit, ref}), packed by the fetch and served to the members in place of the registry's",
          "properties": {
            "name": { "type": "string" },
            "version": { "type": "string" },
            "repository": { "type": "string" },
            "commit": { "type": "string" },
            "ref": { "type": "string" }
          }
        },
        "beside": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "repository": {
                "type": "string"
              },
              "commit": {
                "type": "string"
              }
            },
            "required": [
              "repository",
              "commit"
            ]
          },
          "description": "the sibling repositories placed beside the fetched tree"
        }
      },
      "required": [
        "repository",
        "commit"
      ]
    },
    "ToolchainUsed": {
      "type": "object",
      "properties": {
        "language": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "recipe": {
          "type": "string"
        }
      },
      "required": [
        "language",
        "version",
        "recipe"
      ],
      "description": "the toolchain a build was made with: the language, the installed version and the build module's recipe"
    },
    "AskArtifact": {
      "type": "object",
      "properties": {
        "artifact": {
          "type": "string"
        },
        "from": {
          "type": "string"
        },
        "seat": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "artifact"
      ],
      "description": "one artifact of a build ask: built from the fetched tree, or copied from an upstream pin"
    },
    "BuiltArtifact": {
      "type": "object",
      "properties": {
        "artifact": {
          "type": "string"
        },
        "digest": {
          "type": "string"
        },
        "reference": {
          "type": "string"
        }
      },
      "required": [
        "artifact",
        "digest"
      ],
      "description": "one artifact a build made: its digest and the reference it was published under"
    },
    "LevelAnswer": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string"
        },
        "judged": {
          "type": "string"
        },
        "digest": {
          "type": "object",
          "properties": {
            "level": {
              "type": "string"
            },
            "packages": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "package": {
                    "type": "string"
                  },
                  "digest": {
                    "type": "string"
                  }
                },
                "required": [
                  "package",
                  "digest"
                ]
              }
            },
            "beside": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "without_tests": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "judged_by": {
              "type": "string"
            },
            "needs": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "package": {
                    "type": "string"
                  },
                  "needs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "kept": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "package": {
                "type": "string"
              },
              "digest": {
                "type": "string"
              },
              "tests": {
                "type": "integer"
              }
            }
          }
        },
        "tests": {
          "type": "array",
          "items": {
            "description": "one test's result"
          }
        },
        "unmet": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "package": {
                "type": "string"
              },
              "needs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "required": [
        "level"
      ],
      "description": "one level of a check ask: the digest's answer, the kept verdicts taken, one test result per test step run, and the packages the node could not test"
    },
    "StepResult": {
      "type": "object",
      "description": "what a step answered, by the kind of ask: a build's artifacts, toolchain, imports and out-of-step modules; a check's fetch and levels; a compose's built, key and verdict; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the four",
      "properties": {
        "artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/defs/BuiltArtifact"
          }
        },
        "toolchain": {
          "$ref": "#/defs/ToolchainUsed"
        },
        "imports": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "out-of-step": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "fetch": {
          "$ref": "#/defs/FetchAnswer"
        },
        "levels": {
          "type": "array",
          "items": {
            "$ref": "#/defs/LevelAnswer"
          }
        },
        "built": {
          "type": "boolean"
        },
        "key": {
          "type": "string"
        },
        "verdict": {
          "description": "the compose-candidate verdict (the composer's own layout)"
        },
        "declined": {
          "type": "boolean",
          "description": "the holder declined the ask: its node lacks what the ask needs"
        },
        "needs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "what the declined ask needs"
        },
        "lacks": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "what the holder's node lacks of it"
        }
      }
    },
    "ModuleTree": {
      "type": "object",
      "description": "the tree of one module directory in a merge preview: its git tree, the digest of its manifest, the lock files' digests and the digests of the named paths",
      "properties": {
        "tree": {
          "type": "string"
        },
        "manifest": {
          "type": "string"
        },
        "locks": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "paths": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "packages": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "no longer filled (ADR 0593 section 2); kept so a preview written before still reads"
        }
      },
      "required": [
        "tree",
        "manifest"
      ]
    },
    "Program": {
      "type": "object",
      "description": "a changed file that is a compiled program (issue 1577): its path, its executable format, and the commit of the branch that added it when the merge's tree no longer holds it",
      "properties": {
        "path": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "description": "ELF, Mach-O or PE"
        },
        "commit": {
          "type": "string"
        }
      },
      "required": [
        "path",
        "kind"
      ]
    },
    "PlacedBeside": {
      "type": "object",
      "description": "a sibling repository placed as a plain directory under the workspace's beside directory",
      "properties": {
        "repository": {
          "type": "string"
        },
        "commit": {
          "type": "string"
        },
        "dir": {
          "type": "string"
        }
      },
      "required": [
        "repository",
        "commit",
        "dir"
      ]
    },
    "TakenVersion": {
      "type": "object",
      "description": "of a directory whose go.mod requires an asked mesh package, the version it is built against: the asked one, or go.mod's when it names a newer one, said",
      "properties": {
        "dir": {
          "type": "string"
        },
        "package": {
          "type": "string"
        },
        "asked": {
          "type": "string"
        },
        "named": {
          "type": "string"
        },
        "built": {
          "type": "string"
        },
        "sum": {
          "type": "string"
        },
        "said": {
          "type": "string"
        }
      },
      "required": [
        "dir",
        "package",
        "asked",
        "named",
        "built"
      ]
    },
    "FetchRefusal": {
      "type": "object",
      "description": "a TypeScript module whose packages the fetch did not install, with why",
      "properties": {
        "module": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "required": [
        "module",
        "reason"
      ]
    },
    "FetchAnswer": {
      "type": "object",
      "description": "what a build module's fetch tool answers, whole: the workspace it made, the commit in it, the module directories found; and, when the call gave a base, the merge preview (the trunk commit, the merge commit, the files that conflict, the paths the merge changes, the compiled programs among them, the tree of each module directory). A head that does not merge cleanly is an answer, not an error: merge is empty and conflicts names the files. The Go module adds the sibling repositories placed and the package versions taken; the TypeScript module the directories installed and refused and the group's package",
      "properties": {
        "workspace": {
          "type": "string"
        },
        "commit": {
          "type": "string"
        },
        "modules": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "base": {
          "type": "string"
        },
        "merge": {
          "type": "string"
        },
        "conflicts": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "changed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "programs": {
          "type": "array",
          "items": {
            "$ref": "#/defs/Program"
          }
        },
        "trees": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/defs/ModuleTree"
          }
        },
        "beside": {
          "type": "array",
          "items": {
            "$ref": "#/defs/PlacedBeside"
          }
        },
        "packages": {
          "type": "array",
          "items": {
            "$ref": "#/defs/TakenVersion"
          }
        },
        "installed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "refused": {
          "type": "array",
          "items": {
            "$ref": "#/defs/FetchRefusal"
          }
        },
        "group": {
          "type": "string"
        }
      },
      "required": [
        "workspace",
        "commit",
        "modules"
      ]
    }
  }
}