integration.explain

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "number": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "The pull request number."
    }
  },
  "required": [
    "number"
  ],
  "description": "One pull request to explain.",
  "title": "PullRequestExplainInput"
}

{
  "type": "object",
  "properties": {
    "found": {
      "type": "boolean",
      "description": "Whether the pull request is in the observed queue."
    },
    "reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why not, when not."
    },
    "rank": {
      "type": [
        "integer",
        "null"
      ],
      "format": "uint",
      "minimum": 0,
      "description": "Its position in the ranked queue, 1-based."
    },
    "of": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many open pull requests were ranked."
    },
    "observed_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the forge was observed."
    },
    "assessment": {
      "anyOf": [
        {
          "$ref": "#/$defs/PullRequestAssessment"
        },
        {
          "type": "null"
        }
      ],
      "description": "The assessment."
    }
  },
  "required": [
    "found",
    "of"
  ],
  "description": "One pull request's assessment and rank, or why it has none.",
  "title": "IntegrationExplanation",
  "$defs": {
    "PullRequestAssessment": {
      "type": "object",
      "properties": {
        "number": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The number."
        },
        "title": {
          "type": "string",
          "description": "The title."
        },
        "author": {
          "type": "string",
          "description": "The author."
        },
        "head_ref": {
          "type": "string",
          "description": "The head branch."
        },
        "base_ref": {
          "type": "string",
          "description": "The base branch."
        },
        "evaluated_against": {
          "$ref": "#/$defs/EvaluatedAgainst",
          "description": "The revisions this was decided against."
        },
        "disposition": {
          "$ref": "#/$defs/PullRequestDisposition",
          "description": "The classification."
        },
        "superseded_by": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "The successor that landed and replaces it, exactly when the disposition is\n`superseded`: the disposition stays one word on the wire, and this is its `by`.\nAbsent otherwise; a successor still open, or merged somewhere master does not contain,\nis in the `supersession` evidence and the reasons instead, and one closed unmerged is\nevidence only."
        },
        "issue": {
          "type": [
            "string",
            "null"
          ],
          "description": "The issue of `.ai/repo/project/issues/` its head branch names — a path component equal\nto the id, or the id followed by `-`, the form `majordomus worktree create --issue`\ngives — when it names one. Derived, never declared here: the issue record and the\nbranch name are the two sources, and nothing else."
        },
        "milestone": {
          "type": [
            "string",
            "null"
          ],
          "description": "The milestone that issue's record declares, when it declares one."
        },
        "lane": {
          "$ref": "#/$defs/IntegrationLane",
          "description": "The queue it is in."
        },
        "reasons": {
          "type": "array",
          "items": {
            "description": "A reason code, `code` or `code:payload`, one of: `stacked_on:#N`, `base_is:BRANCH`, `draft`, `label:NAME`, `auto_merge_armed`, `merge_commit_not_allowed`, `superseded_by:#N`, `successor_open:#N`, `successor_not_landed:#N`, `successor_unread:#N`, `head_reachable_from_master`, `merge_changes_nothing`, `patch_ids_upstream`, `only_derived_artifacts_differ`, `relation_unknown:WHY`, `conflicts_on:COUNT`, `depends_on:#N`, `review:STATE`, `review_policy_unread`, `required_check_failed`, `behind_master:COMMITS`, `fork_head`, `version_unallocated:VERSION`, `required_checks:STATE`, `no_required_checks`, `required_checks_unread`, `contains_master`, `carries_master`, `required_checks_passed`, `required_checks_skipped`, `executor_merge_refused:HEAD`, `executor_refresh_failed:MASTER`, `label_obsolete:NAME`, `dependency_cycle:#N`, `dependency_closed_unmerged:#N`, `dependency_unread:#N`, `declarations_unread`. A code outside this list (an older trail's) is carried verbatim.",
            "type": "string"
          },
          "description": "Machine-readable reasons, one for every failing gate's every finding, in policy order:\nthe first is the decisive one. A ready pull request carries why it is ready."
        },
        "gates": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GateResult"
          },
          "description": "Every gate of the policy, in order, and whether it passed.",
          "default": []
        },
        "next_action": {
          "type": [
            "string",
            "null"
          ],
          "description": "What a person or the executor does next, when anything."
        },
        "required_checks": {
          "$ref": "#/$defs/RequiredCheckState",
          "description": "The required checks on the head."
        },
        "review": {
          "$ref": "#/$defs/PullRequestReview",
          "description": "The review state."
        },
        "relation": {
          "$ref": "#/$defs/RelationToMaster",
          "description": "What the head is to master."
        },
        "dependencies": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PullRequestDependency"
          },
          "description": "Declared and inferred dependencies."
        },
        "authored_paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Paths the pull request changes (authored ones; derived output is excluded)."
        },
        "overlaps": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PathOverlap"
          },
          "description": "Other open pull requests changing a same authored path, with the shared paths."
        },
        "risk": {
          "$ref": "#/$defs/IntegrationRisk",
          "description": "The planning risk."
        },
        "risk_factors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Why the risk is what it is."
        },
        "evidence": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntegrationEvidence"
          },
          "description": "Every fact read."
        },
        "created_at": {
          "type": "string",
          "description": "When it was opened."
        },
        "wait": {
          "anyOf": [
            {
              "$ref": "#/$defs/ExecutorWait"
            },
            {
              "type": "null"
            }
          ],
          "description": "How long it has been the executor's to act on, and how often another was chosen\ninstead — derived from the audit trail (`super::wait`), present only while it is\nready or refreshable."
        },
        "rank_factors": {
          "anyOf": [
            {
              "$ref": "#/$defs/RankFactors"
            },
            {
              "type": "null"
            }
          ],
          "description": "Why it stands where it does in the rank: every component the order compares, in the\norder it compares them. Set by the planner; absent on an assessment never ranked."
        },
        "change_shape": {
          "anyOf": [
            {
              "$ref": "#/$defs/ChangeShape"
            },
            {
              "type": "null"
            }
          ],
          "description": "What its merge into master changes, by kind (`ChangeShape`): read beside the\nrelation, from the same pair of commits. Absent when it could not be read."
        }
      },
      "required": [
        "number",
        "title",
        "author",
        "head_ref",
        "base_ref",
        "evaluated_against",
        "disposition",
        "lane",
        "reasons",
        "required_checks",
        "review",
        "relation",
        "dependencies",
        "authored_paths",
        "overlaps",
        "risk",
        "risk_factors",
        "evidence",
        "created_at"
      ],
      "description": "The canonical state of one open pull request: what was observed, what it is to master,\nhow it is classified and why. The one value every surface renders."
    },
    "EvaluatedAgainst": {
      "type": "object",
      "properties": {
        "master_sha": {
          "type": "string",
          "description": "The master commit."
        },
        "head_sha": {
          "type": "string",
          "description": "The pull request's head commit."
        },
        "observed_at": {
          "type": "string",
          "description": "When the forge was observed, RFC 3339; empty in a value written before it was named.",
          "default": ""
        }
      },
      "required": [
        "master_sha",
        "head_sha"
      ],
      "description": "The revisions a decision was taken against, and when the forge was observed. A decision is\nvalid only while both revisions still hold: the executor compares them with what it\nre-reads before it acts."
    },
    "PullRequestDisposition": {
      "oneOf": [
        {
          "type": "string",
          "const": "ready",
          "description": "Contains the current master, every required check passed on its head, nothing\nblocks it: the executor may merge it."
        },
        {
          "type": "string",
          "const": "needs_refresh",
          "description": "Merges cleanly but does not contain master: the executor may bring master in (a\nmerge commit on the branch, never a rewrite), after which CI must run again."
        },
        {
          "type": "string",
          "const": "waiting_for_checks",
          "description": "Contains master; a required check has not finished on this head."
        },
        {
          "type": "string",
          "const": "waiting_for_review",
          "description": "A required review is missing or changes were requested."
        },
        {
          "type": "string",
          "const": "waiting_for_dependency",
          "description": "A declared dependency has not landed."
        },
        {
          "type": "string",
          "const": "draft",
          "description": "A draft."
        },
        {
          "type": "string",
          "const": "needs_repair",
          "description": "A required check failed on this head."
        },
        {
          "type": "string",
          "const": "conflicting",
          "description": "Conflicts on authored paths: a person resolves them."
        },
        {
          "type": "string",
          "const": "blocked",
          "description": "A label whose policy is to hold holds it, or the repository allows no merge commit,\nwhich is the only way the executor merges."
        },
        {
          "type": "string",
          "const": "unsafe",
          "description": "The forge has auto-merge armed on it: the forge would merge it on its own, outside the\nexecutor and against whatever master is then. Held until a person disarms it."
        },
        {
          "type": "string",
          "const": "redundant",
          "description": "Its head already landed, its merge changes nothing, or every one of its commits is on\nmaster as an equal patch: strong evidence from git, eligible for closure under policy.\n(Before 0.13 this was the word `superseded`.)"
        },
        {
          "type": "string",
          "const": "superseded",
          "description": "A successor was declared for it by someone the repository lets declare one — an owner,\nmember or collaborator, in a pull request of this repository — and that successor\nlanded: git finds its head or its merge commit in master. The successor is\n`PullRequestAssessment::superseded_by`. Eligible for closure under policy."
        },
        {
          "type": "string",
          "const": "possibly_redundant",
          "description": "Weak evidence: only derived artifacts would change, or its declared successor was merged\nsomewhere master does not contain. Surfaced for a person; never closed automatically."
        },
        {
          "type": "string",
          "const": "other_base",
          "description": "Targets a branch other than the integration base."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "Something needed to decide could not be observed."
        },
        {
          "type": "string",
          "const": "obsolete",
          "description": "A person marked it obsolete with a label the label policy declares (owner decision\nD3): the only evidence that reaches this word. Listed for a person by cleanup and\nnever closed automatically; age, shared paths or a similar title never make one."
        }
      ],
      "description": "The one classification of an open pull request. Every value carries a machine-readable\nreason in `PullRequestAssessment::reasons`; there is no `mergeable: bool`."
    },
    "IntegrationLane": {
      "oneOf": [
        {
          "type": "string",
          "const": "ready",
          "description": "The executor may merge it now."
        },
        {
          "type": "string",
          "const": "waiting",
          "description": "Something will happen without a person: a refresh, a check, a dependency."
        },
        {
          "type": "string",
          "const": "repair",
          "description": "A person must change the branch."
        },
        {
          "type": "string",
          "const": "cleanup",
          "description": "Its work is on master already, or a successor that landed replaced it."
        },
        {
          "type": "string",
          "const": "held",
          "description": "Not asking to be merged, held by a label or a setting, unsafe for the executor, or\nundecidable."
        }
      ],
      "description": "The queues the Cockpit and the status table group pull requests into."
    },
    "GateResult": {
      "type": "object",
      "properties": {
        "gate": {
          "$ref": "#/$defs/IntegrationGate",
          "description": "The gate."
        },
        "passed": {
          "type": "boolean",
          "description": "Whether it passed. A gate that fails only because an earlier one did (the head is not\nfresh when its merge conflicts) fails without a reason of its own."
        }
      },
      "required": [
        "gate",
        "passed"
      ],
      "description": "How one gate answered."
    },
    "IntegrationGate": {
      "oneOf": [
        {
          "type": "string",
          "const": "base",
          "description": "It targets the integration base."
        },
        {
          "type": "string",
          "const": "draft",
          "description": "It is not a draft."
        },
        {
          "type": "string",
          "const": "label",
          "description": "It carries no label whose policy is to hold."
        },
        {
          "type": "string",
          "const": "auto_merge",
          "description": "The forge has no auto-merge armed on it."
        },
        {
          "type": "string",
          "const": "supersession",
          "description": "No authorised successor is declared to replace it, and the pull requests that mention\nit were all read. Asked before the relation to master, because a pull request whose\nsuccessor landed usually conflicts with what the successor brought, and is superseded\nrather than conflicting. A declaration nobody entitled made does not fail it."
        },
        {
          "type": "string",
          "const": "relation_to_master",
          "description": "Its head is not on master already, and git could say that it merges cleanly."
        },
        {
          "type": "string",
          "const": "merge_method",
          "description": "The repository allows a merge commit, the only way the executor merges. Asked after\nthe relation, so work already on master is still `redundant` and may be closed."
        },
        {
          "type": "string",
          "const": "dependency",
          "description": "Every declared dependency has landed."
        },
        {
          "type": "string",
          "const": "review",
          "description": "The review policy is satisfied on the head."
        },
        {
          "type": "string",
          "const": "no_failing_check",
          "description": "No required check failed on the head."
        },
        {
          "type": "string",
          "const": "freshness",
          "description": "The head contains the current master."
        },
        {
          "type": "string",
          "const": "required_checks",
          "description": "Every required check passed on the head."
        }
      ],
      "description": "One question of the policy, in the order `IntegrationGate::ALL` asks them. The\ndisposition is the first that fails; every one is answered."
    },
    "RequiredCheckState": {
      "oneOf": [
        {
          "type": "string",
          "const": "passed",
          "description": "Every required check passed on this head."
        },
        {
          "type": "string",
          "const": "skipped",
          "description": "Every required check passed, at least one of them by a skip the policy permits for\nthat context. A skip the policy does not permit is not a pass: it is `missing`."
        },
        {
          "type": "string",
          "const": "pending",
          "description": "A required check is queued or running."
        },
        {
          "type": "string",
          "const": "failed",
          "description": "A required check failed."
        },
        {
          "type": "string",
          "const": "missing",
          "description": "A required check has not reported on this head at all."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "The repository's required checks could not be read."
        }
      ],
      "description": "The state of the repository's *required* checks on one head, which is the only check\nstate a merge decision reads. A visible green check that is not required proves nothing,\nand a required check that is absent is not a pass."
    },
    "PullRequestReview": {
      "oneOf": [
        {
          "type": "string",
          "const": "not_required",
          "description": "The branch protection requires no review."
        },
        {
          "type": "string",
          "const": "approved",
          "description": "Approved."
        },
        {
          "type": "string",
          "const": "changes_requested",
          "description": "A reviewer asked for changes."
        },
        {
          "type": "string",
          "const": "pending",
          "description": "A required review has not been given."
        },
        {
          "type": "string",
          "const": "stale",
          "description": "The approvals were given on another commit than the head: an approval is of one\ncommit, and these are not of this one."
        },
        {
          "type": "string",
          "const": "code_owners_pending",
          "description": "The approvals are there, but a code owner's is still required."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "The protection could not be read."
        }
      ],
      "description": "Where the forge's review policy stands."
    },
    "RelationToMaster": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "contained"
            }
          },
          "required": [
            "kind"
          ],
          "description": "The head is an ancestor of master: every commit already landed."
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "const": "superseded"
            }
          },
          "required": [
            "kind"
          ],
          "description": "Merging the head into master changes nothing: its patch is already fully there."
        },
        {
          "type": "object",
          "properties": {
            "commits": {
              "type": "integer",
              "format": "uint64",
              "minimum": 0,
              "description": "How many commits, every one of them already on master."
            },
            "kind": {
              "type": "string",
              "const": "patch_ids_upstream"
            }
          },
          "required": [
            "kind",
            "commits"
          ],
          "description": "The merge would conflict or change only derived output, but every commit the head has\nand master lacks is on master already as an equal patch (`git cherry` marks each `-`):\nthe change landed, and master moved on past it. Never a partial match, and never a\nhead that carries a merge commit of its own, whose resolution has no patch to compare."
        },
        {
          "type": "object",
          "properties": {
            "paths": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "The derived paths that would change."
            },
            "kind": {
              "type": "string",
              "const": "derived_only"
            }
          },
          "required": [
            "kind",
            "paths"
          ],
          "description": "Merging changes only derived artifacts: the authored change is already on master,\nand what differs is output the generators rewrite."
        },
        {
          "type": "object",
          "properties": {
            "authored": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Authored (non-derived) paths the merge changes."
            },
            "owes_version": {
              "type": [
                "string",
                "null"
              ],
              "description": "The version a landing of this head allocates, when master allocates at landing\n(ADR 0134) and the head does not carry it: the head owes a refresh even though it\ncontains master. Absent when the policy does not allocate, or the head carries it."
            },
            "kind": {
              "type": "string",
              "const": "up_to_date"
            }
          },
          "required": [
            "kind",
            "authored"
          ],
          "description": "The head already contains master and merges cleanly."
        },
        {
          "type": "object",
          "properties": {
            "behind": {
              "type": "integer",
              "format": "uint64",
              "minimum": 0,
              "description": "Commits on master the head does not have."
            },
            "authored": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Authored (non-derived) paths the merge changes."
            },
            "kind": {
              "type": "string",
              "const": "carries_master"
            }
          },
          "required": [
            "kind",
            "behind",
            "authored"
          ],
          "description": "The head does not contain master, yet master holds nothing the head lacks: merging it\nwrites the head's own tree, and every commit master has beyond it is a merge commit.\nThat is a head stacked on a pull request that has since landed. A verdict on the head\nis then a verdict on what master becomes, tree and listed history alike, exactly as\nwhen the head contains master; and no path is merged at all, so the forge needs no\ndriver for it."
        },
        {
          "type": "object",
          "properties": {
            "behind": {
              "type": "integer",
              "format": "uint64",
              "minimum": 0,
              "description": "Commits on master the head does not have."
            },
            "authored": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Authored paths the merge changes."
            },
            "kind": {
              "type": "string",
              "const": "behind"
            }
          },
          "required": [
            "kind",
            "behind",
            "authored"
          ],
          "description": "The head does not contain master, but the merge is clean with the derived driver."
        },
        {
          "type": "object",
          "properties": {
            "paths": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "The conflicting authored paths."
            },
            "kind": {
              "type": "string",
              "const": "conflicting"
            }
          },
          "required": [
            "kind",
            "paths"
          ],
          "description": "Merging conflicts on authored paths: a person must resolve it."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Why."
            },
            "kind": {
              "type": "string",
              "const": "unknown"
            }
          },
          "required": [
            "kind",
            "reason"
          ],
          "description": "Git could not answer (the head is not fetched, or git failed); the reason."
        }
      ],
      "description": "What the pull request's head is to the current master, decided locally by git with\nthis repository's own merge drivers — never by the forge's `mergeable`, which cannot\nrun the derived-file driver and calls nearly every pull request here conflicting."
    },
    "PullRequestDependency": {
      "type": "object",
      "properties": {
        "number": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The pull request this one waits for."
        },
        "certainty": {
          "$ref": "#/$defs/DependencyCertainty",
          "description": "How it is known."
        },
        "satisfied": {
          "type": "boolean",
          "description": "Whether it is satisfied: that pull request merged. Closed without a merge, or not\nread, it is not — a dependency that never landed is no less a dependency."
        },
        "state": {
          "$ref": "#/$defs/DependencyState",
          "description": "What the forge says became of it. `open` in a record written before it was read.",
          "default": "open"
        }
      },
      "required": [
        "number",
        "certainty",
        "satisfied"
      ],
      "description": "Explicit ordering between pull requests, as declared."
    },
    "DependencyCertainty": {
      "oneOf": [
        {
          "type": "string",
          "const": "confirmed",
          "description": "Declared: a `Depends on #N` / `Stacked on #N` line in the body, or a base branch\nthat is another open pull request's head."
        },
        {
          "type": "string",
          "const": "inferred",
          "description": "Inferred: the head contains the other's head commit. Evidence, never a block."
        }
      ],
      "description": "How a dependency is known. Only a declared one blocks."
    },
    "DependencyState": {
      "oneOf": [
        {
          "type": "string",
          "const": "open",
          "description": "Still open."
        },
        {
          "type": "string",
          "const": "merged",
          "description": "Merged: the only state that satisfies it."
        },
        {
          "type": "string",
          "const": "closed_unmerged",
          "description": "Closed without a merge: its work never landed, so a person decides."
        },
        {
          "type": "string",
          "const": "unread",
          "description": "Not open, and the forge could not say what became of it — refused, or not a pull\nrequest at all: unknown, never satisfied."
        }
      ],
      "description": "What became of a pull request another one depends on."
    },
    "PathOverlap": {
      "type": "object",
      "properties": {
        "number": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The other pull request."
        },
        "paths": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The paths both change."
        },
        "kind": {
          "$ref": "#/$defs/OverlapKind",
          "description": "What the two share. `authored` in a record written before it was said.",
          "default": "authored"
        }
      },
      "required": [
        "number",
        "paths"
      ],
      "description": "Shared authored paths with one other open pull request."
    },
    "OverlapKind": {
      "oneOf": [
        {
          "type": "string",
          "const": "authored",
          "description": "Authored paths both change."
        },
        {
          "type": "string",
          "const": "version_bump",
          "description": "Both raise the crate's version: whichever lands second must be re-derived on the first."
        },
        {
          "type": "string",
          "const": "release",
          "description": "Both change the release records under `.ai/repo/releases/`."
        }
      ],
      "description": "What two open pull requests have in common that makes landing one change the other."
    },
    "IntegrationRisk": {
      "oneOf": [
        {
          "type": "string",
          "const": "low",
          "description": "Documentation, tests, content."
        },
        {
          "type": "string",
          "const": "medium",
          "description": "Code of the executable or the tool."
        },
        {
          "type": "string",
          "const": "high",
          "description": "CI, release, governance, schemas, or a large change."
        }
      ],
      "description": "How much could go wrong if this lands and something was missed. Planning information:\nit orders work and it never relaxes a policy."
    },
    "IntegrationEvidence": {
      "type": "object",
      "properties": {
        "kind": {
          "$ref": "#/$defs/EvidenceKind",
          "description": "What kind of fact."
        },
        "status": {
          "type": "string",
          "description": "What it said, as a word."
        },
        "detail": {
          "type": "string",
          "description": "The detail a person reads."
        },
        "source": {
          "anyOf": [
            {
              "$ref": "#/$defs/EvidenceSource"
            },
            {
              "type": "null"
            }
          ],
          "description": "Where it was read. Every assessment names it; a trail line written before evidence\ncarried it has none."
        }
      },
      "required": [
        "kind",
        "status",
        "detail"
      ],
      "description": "One piece of evidence behind a disposition: what was read, where, and what it said."
    },
    "EvidenceKind": {
      "oneOf": [
        {
          "type": "string",
          "const": "required_check",
          "description": "One required check's state on the head: one entry per context the base requires."
        },
        {
          "type": "string",
          "const": "required_checks",
          "description": "The required checks together: their verdict, and each context's state."
        },
        {
          "type": "string",
          "const": "review",
          "description": "The review policy and the forge's decision, or one reviewer's latest review."
        },
        {
          "type": "string",
          "const": "relation_to_master",
          "description": "What the head is to master, as git decided it."
        },
        {
          "type": "string",
          "const": "dependency",
          "description": "One declared dependency."
        },
        {
          "type": "string",
          "const": "label",
          "description": "One label whose policy is to hold."
        },
        {
          "type": "string",
          "const": "draft",
          "description": "Whether it is a draft; always emitted."
        },
        {
          "type": "string",
          "const": "base",
          "description": "The branch it targets; always emitted."
        },
        {
          "type": "string",
          "const": "freshness",
          "description": "How old the observation is. Declared so the vocabulary is settled; nothing emits it yet."
        },
        {
          "type": "string",
          "const": "auto_merge",
          "description": "The forge has auto-merge armed; emitted whenever it is."
        },
        {
          "type": "string",
          "const": "supersession",
          "description": "One declared successor: which pull request replaces this one, whose body said so, and\nwhether it landed. One entry per authorised successor (status `open`, `landed`,\n`not_landed` or `unread`), one per declaration nobody entitled made\n(`possible_supersession`), and one when the pull requests that mention it were not all\nread (`references_truncated`, `references_unread`)."
        },
        {
          "type": "string",
          "const": "repository_settings",
          "description": "What the repository's settings allow the executor; emitted when they allow no merge\ncommit."
        }
      ],
      "description": "What kind of fact a piece of evidence is. The wire words are the ones the evidence carried\nwhile its kind was a string, so a trail written then still reads."
    },
    "EvidenceSource": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "observed_at": {
              "type": "string",
              "description": "When the forge was observed, RFC 3339."
            },
            "kind": {
              "type": "string",
              "const": "forge"
            }
          },
          "required": [
            "kind",
            "observed_at"
          ],
          "description": "The forge observation, at its moment."
        },
        {
          "type": "object",
          "properties": {
            "master_sha": {
              "type": "string",
              "description": "The master commit."
            },
            "head_sha": {
              "type": "string",
              "description": "The head commit."
            },
            "kind": {
              "type": "string",
              "const": "git"
            }
          },
          "required": [
            "kind",
            "master_sha",
            "head_sha"
          ],
          "description": "Git, on this pair of commits."
        }
      ],
      "description": "Where a piece of evidence was read."
    },
    "ExecutorWait": {
      "type": "object",
      "properties": {
        "actionable_since": {
          "type": "string",
          "description": "When it was first observed ready or refreshable in its current run of being so,\nRFC 3339."
        },
        "passed_over": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "How many times the executor selected another pull request while this one was ready\nor refreshable."
        },
        "last_passed_over": {
          "anyOf": [
            {
              "$ref": "#/$defs/PassedOver"
            },
            {
              "type": "null"
            }
          ],
          "description": "The last of those times."
        }
      },
      "required": [
        "actionable_since",
        "passed_over"
      ],
      "description": "How long a pull request has waited for the executor, from the audit trail. Starvation is\nmade visible here, never resolved by changing the rank: the rank's age tie-break already\nprefers the older of two otherwise equal candidates, and a wait this long is a fact a\nperson reads, not a reason to merge anything less safe."
    },
    "PassedOver": {
      "type": "object",
      "properties": {
        "at": {
          "type": "string",
          "description": "When, RFC 3339."
        },
        "for_pr": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The pull request chosen instead."
        },
        "action": {
          "$ref": "#/$defs/IntegrationAction",
          "description": "What it was chosen for (`selected` to merge, `refresh_selected` to bring master in)."
        }
      },
      "required": [
        "at",
        "for_pr",
        "action"
      ],
      "description": "One time the executor chose another pull request."
    },
    "IntegrationAction": {
      "oneOf": [
        {
          "type": "string",
          "const": "lease_acquired",
          "description": "The executor took the base branch's lease."
        },
        {
          "type": "string",
          "const": "lease_released",
          "description": "It gave the lease back."
        },
        {
          "type": "string",
          "const": "continuous_started",
          "description": "A continuous drain started."
        },
        {
          "type": "string",
          "const": "continuous_stopped",
          "description": "A continuous drain stopped; the detail says why."
        },
        {
          "type": "string",
          "const": "observed",
          "description": "The forge was observed and the observation recorded."
        },
        {
          "type": "string",
          "const": "became_actionable",
          "description": "A pull request became actionable (ready or refreshable)."
        },
        {
          "type": "string",
          "const": "left_actionable",
          "description": "A pull request stopped being actionable."
        },
        {
          "type": "string",
          "const": "selected",
          "description": "The first ready pull request was chosen to merge."
        },
        {
          "type": "string",
          "const": "refresh_selected",
          "description": "The first refreshable pull request was chosen to bring master into."
        },
        {
          "type": "string",
          "const": "stale_decision",
          "description": "The decision went stale between planning and acting; nothing was done."
        },
        {
          "type": "string",
          "const": "merge_attempted",
          "description": "A merge is about to be asked of the forge."
        },
        {
          "type": "string",
          "const": "merge_succeeded",
          "description": "The merge landed and was verified."
        },
        {
          "type": "string",
          "const": "merge_failed",
          "description": "The forge refused the merge."
        },
        {
          "type": "string",
          "const": "verification_failed",
          "description": "What landed could not be verified."
        },
        {
          "type": "string",
          "const": "failure_acknowledged",
          "description": "A person looked at a merge that could not be verified and lets drains merge again\n(`prs drain --resume-after-failure`)."
        },
        {
          "type": "string",
          "const": "refresh_attempted",
          "description": "Master is about to be merged into a branch and pushed."
        },
        {
          "type": "string",
          "const": "refreshed",
          "description": "Master was brought into the branch and pushed."
        },
        {
          "type": "string",
          "const": "refresh_failed",
          "description": "Bringing master in failed."
        },
        {
          "type": "string",
          "const": "close_attempted",
          "description": "A redundant or superseded pull request is about to be closed."
        },
        {
          "type": "string",
          "const": "closed_redundant",
          "description": "A redundant one was closed."
        },
        {
          "type": "string",
          "const": "closed_superseded",
          "description": "A superseded one was closed (before 0.13, a line with this word recorded what is now\n`closed_redundant`)."
        },
        {
          "type": "string",
          "const": "close_failed",
          "description": "Closing it failed."
        },
        {
          "type": "string",
          "const": "reopen_attempted",
          "description": "A record pull request the workflow's token opened is about to be closed and reopened,\nso that a run of its own starts (`RecordStanding::Reopenable`)."
        },
        {
          "type": "string",
          "const": "reopened",
          "description": "It was closed and reopened; its required check can report now."
        },
        {
          "type": "string",
          "const": "reopen_failed",
          "description": "Reopening it failed; the detail says whether the pull request was left closed."
        },
        {
          "type": "string",
          "const": "repair_selected",
          "description": "A person named a pull request to repair (`prs repair --apply`) and its classification\nmakes it eligible: master is what it lacks, and nothing authored conflicts."
        },
        {
          "type": "string",
          "const": "repair_attempted",
          "description": "Master is about to be merged into the named branch and pushed."
        },
        {
          "type": "string",
          "const": "repaired",
          "description": "Master was brought into the named branch and pushed."
        },
        {
          "type": "string",
          "const": "repair_refused",
          "description": "The repair was refused — by the classification (an authored conflict, a fork, armed\nauto-merge, another base, an undecidable relation) or by the act (a merge, derive,\ncommit or push that failed) — and nothing reached the branch; `class` says why."
        },
        {
          "type": "string",
          "const": "idle",
          "description": "Nothing was ready."
        },
        {
          "type": "string",
          "const": "observe_failed",
          "description": "A continuous drain's cycle could not observe the forge, and the outage was short\nenough to wait out (`CONTINUOUS_TRANSIENT_LIMIT`)."
        }
      ],
      "description": "What one line of the audit trail records. The wire word is the variant's `snake_case`\nname — the same word each was written as while the action was a string — so every line\nwritten before still parses, and a word nobody writes is not an action."
    },
    "RankFactors": {
      "type": "object",
      "properties": {
        "lane": {
          "$ref": "#/$defs/IntegrationLane",
          "description": "The lane: what kind of work the executor does with it."
        },
        "disposition": {
          "$ref": "#/$defs/PullRequestDisposition",
          "description": "The disposition, within the lane."
        },
        "risk": {
          "$ref": "#/$defs/IntegrationRisk",
          "description": "The planning risk: lower first."
        },
        "contention": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many other ready or refreshable pull requests it overlaps (`PathOverlap`): an\nauthored path, a version bump or a release in common. Fewer first, because landing it\ninvalidates less."
        },
        "dependents": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many open pull requests declare that they wait for this one and are not yet\nsatisfied: more first, because landing it unblocks them."
        },
        "authored_paths": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many authored paths it changes: fewer first, a smaller change is cheaper to land\nand to undo."
        },
        "created_at": {
          "type": "string",
          "description": "When it was opened: older first, so easy new work cannot starve old work."
        },
        "number": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The number: the last tie-break, total."
        }
      },
      "required": [
        "lane",
        "disposition",
        "risk",
        "contention",
        "dependents",
        "authored_paths",
        "created_at",
        "number"
      ],
      "description": "What the rank compares, in order: the first component that differs between two pull\nrequests decides which comes first. Each is a value of the assessment or of the queue\naround it, so the order can be explained and is the same whatever order the forge listed\nthe pull requests in."
    },
    "ChangeShape": {
      "type": "object",
      "properties": {
        "authored": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Authored (non-derived) paths the merge changes or conflicts on, in path order."
        },
        "derived": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Derived paths the merge changes or conflicts on, in path order."
        },
        "version_bump": {
          "type": [
            "string",
            "null"
          ],
          "description": "The version the head declares in the crate manifest, when it is not the one its merge\nbase declares: the head raises the version."
        }
      },
      "required": [
        "authored",
        "derived"
      ],
      "description": "What a head's merge into master changes, by kind: the authored paths a person wrote, the\nderived paths a generator writes (by the repository's `merge=derived` attributes on master),\nand the version the head declares when it raises the crate's. Decided from the same pair\nof commits as the relation to master, and cached under the same key beside it, so a change\nof either commit — a `.gitattributes` change on master is one — makes both stale together."
    }
  }
}