@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/intent.schema.json

@@ -66,7 +66,7 @@
         },
         "region": {
           "type": "string",
-          "description": "The id of the region node."
+          "description": "The id of the region node: region:<path>, with :<start>-<end> for a line range or #<symbol> for a symbol."
         },
         "history": {
           "type": "object",
@@ -90,7 +90,7 @@
                 "file",
                 "directory"
               ],
-              "description": "line-range: git log -L over the region's lines. file: git log --follow over the file. directory: git log over the directory."
+              "description": "line-range: git log -L over the region's lines, a symbol's current lines included. file: git log --follow over the file. directory: git log over the directory."
             },
             "shallow": {
               "type": "boolean",
@@ -182,6 +182,9 @@
               "minimum": 0
             }
           }
+        },
+        "why": {
+          "$ref": "#/$defs/why"
         }
       }
     },
@@ -216,6 +219,9 @@
         },
         {
           "$ref": "#/$defs/finding"
+        },
+        {
+          "$ref": "#/$defs/run"
         }
       ]
     },
@@ -237,7 +243,7 @@
       }
     },
     "region": {
-      "description": "The region the walk starts from. Its id is region:<path> with :<start>-<end> for a line range.",
+      "description": "The region the walk starts from. Its id is region:<path>, with :<start>-<end> for a line range, or #<symbol> for a symbol (#3034).",
       "type": "object",
       "required": [
         "id",
@@ -271,7 +277,7 @@
               "$ref": "#/$defs/lineRange"
             }
           ],
-          "description": "The line range asked for, in the file as read, or null for the whole path."
+          "description": "The line range asked for, in the file as read, or the current lines of the symbol asked for; null for the whole path."
         },
         "member": {
           "type": [
@@ -306,6 +312,36 @@
             "null"
           ],
           "description": "The graph node id the region was given as, whose sourceLoc it is, or null."
+        },
+        "symbol": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name",
+                "qualified",
+                "kind"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The symbol as given after #."
+                },
+                "qualified": {
+                  "type": "string",
+                  "description": "The declaration it resolved to, as a dotted path from the file's top level, such as Server.listen."
+                },
+                "kind": {
+                  "type": "string",
+                  "description": "What declares it: function, class, method, property, interface, type, enum, namespace, variable or member."
+                }
+              }
+            }
+          ],
+          "description": "For a region given as path#symbol (#3034): the symbol and the declaration it resolved to in the tree read; its current lines are in lines and are followed through history as a line range. Null otherwise. Added within version 1, so an older document may lack it."
         }
       }
     },
@@ -483,6 +519,12 @@
             null
           ],
           "description": "How the decisions constraining the region by path relate to the commit (#2656). decided: it falls inside a decision's window and that decision's own unit made it. decided-by-window: it falls inside a window, and it is not the decision's own work, so the person judges it. undecided: outside every window, with the finding intent-commit-undecided. null: no record kind was read. Added within version 1, so an older document may lack it."
+        },
+        "joins": {
+          "$ref": "#/$defs/trailerJoins"
+        },
+        "squash": {
+          "$ref": "#/$defs/squash"
         }
       }
     },
@@ -952,6 +994,9 @@
                   "work-done-gap-open",
                   "work-acceptance-unmet",
                   "work-acceptance-self-verified",
+                  "work-contract-unknown",
+                  "work-contract-undecided",
+                  "work-tier-unknown",
                   "answer-points-unreadable",
                   "answer-point-unknown",
                   "answer-point-changed"
@@ -962,6 +1007,51 @@
               }
             }
           }
+        },
+        "reviews": {
+          "description": "The review sessions whose comments led to this item (#3154, E21 in arugula-salad/hud#823): each record of a session kind read whose comments[].follow_ups, or its own follow_ups, name the item as <kind>:<id>. A commit that carries the item by its Chant-Record trailer joins back to the review through it. Absent when none does. Added within contract 1.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "recordKind",
+              "record",
+              "path",
+              "state",
+              "comments"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^record:"
+              },
+              "recordKind": {
+                "type": "string"
+              },
+              "record": {
+                "type": "string"
+              },
+              "path": {
+                "type": "string",
+                "description": "The session record file, from the repository root."
+              },
+              "state": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "comments": {
+                "type": "array",
+                "items": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "description": "The comments whose follow_ups name the item, numbered from 1; empty when only the session's own follow_ups do."
+              }
+            }
+          }
         }
       }
     },
@@ -1114,7 +1204,8 @@
                 "intent-region-unconstrained",
                 "intent-decision-unimplemented",
                 "intent-work-blocked",
-                "intent-work-open-decided-code"
+                "intent-work-open-decided-code",
+                "intent-commit-join-conflict"
               ]
             },
             {
@@ -1179,7 +1270,7 @@
       }
     },
     "edge": {
-      "description": "constrains: decision or work item to region, file or contract. pins: decision to artifact. touched-by: region to commit. produced-by: commit to unit. serves: unit to contract. supersedes: the newer decision to the one it replaces. cites-evidence: unit, contract or decision to evidence. links: consumer member to producer member. within: commit to a decision whose path window it falls in, or to a work item whose window it falls in. implements: work item to the decision it carries out. needs: work item to a work item it waits on. addressed-by: finding to a work item that addresses it.",
+      "description": "constrains: decision or work item to region, file or contract. pins: decision to artifact. touched-by: region to commit. produced-by: commit to unit. serves: unit to contract. supersedes: the newer decision to the one it replaces. cites-evidence: unit, contract or decision to evidence. links: consumer member to producer member. within: commit to a decision whose path window it falls in, or to a work item whose window it falls in. implements: work item to the decision it carries out. needs: work item to a work item it waits on. addressed-by: finding to a work item that addresses it. carries: commit to a decision or work item its Chant-Record trailer names, or to the work item its Chant-Lease was taken on (#3149). made-by: commit to the agent run that made it, joined by its Chant-Run trailer or the run's own list of commits (#3033). worked-on: agent run to the work item it worked on and to each record it names, when a kind read has them; the commits it made carry them as they carry a Chant-Lease's item and a Chant-Record (#3034).",
       "oneOf": [
         {
           "$ref": "#/$defs/constrainsEdge"
@@ -1195,6 +1286,9 @@
         },
         {
           "$ref": "#/$defs/plainEdge"
+        },
+        {
+          "$ref": "#/$defs/madeByEdge"
         }
       ]
     },
@@ -1208,7 +1302,8 @@
         "code": {
           "enum": [
             "intent-history-shallow",
-            "intent-plugin-failed"
+            "intent-plugin-failed",
+            "squash-unfollowed"
           ]
         },
         "message": {
@@ -1260,7 +1355,10 @@
                 "schema-invalid",
                 "location-missing",
                 "intent-region-invalid",
-                "intent-record-unknown"
+                "intent-record-unknown",
+                "intent-symbol-unsupported",
+                "intent-symbol-unknown",
+                "intent-symbol-ambiguous"
               ]
             },
             "message": {
@@ -1397,7 +1495,9 @@
             "links",
             "implements",
             "needs",
-            "addressed-by"
+            "addressed-by",
+            "carries",
+            "worked-on"
           ]
         }
       }
@@ -1474,6 +1574,847 @@
           "type": "string"
         }
       }
+    },
+    "trailerJoins": {
+      "type": "object",
+      "description": "What chant's own commit trailers join the commit to (#3149, ws-075). Added within version 1, so an older document may lack it.",
+      "required": [
+        "agent",
+        "lease",
+        "run",
+        "records",
+        "applied"
+      ],
+      "properties": {
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Agent: the agent session that wrote the commit (ws-067)."
+        },
+        "lease": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "token",
+                "item"
+              ],
+              "properties": {
+                "token": {
+                  "type": "string",
+                  "description": "Chant-Lease: the work lease's fencing token."
+                },
+                "item": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The work item a lease history on the local chant/lifecycle branch names for the token, or null when none does."
+                }
+              }
+            }
+          ]
+        },
+        "run": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Run: the agent run that made the commit (#3033)."
+        },
+        "records": {
+          "type": "array",
+          "description": "Each well-formed Chant-Record value, <kind>:<id>, in order.",
+          "items": {
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "node"
+            ],
+            "properties": {
+              "kind": {
+                "type": "string",
+                "description": "The record kind's name."
+              },
+              "id": {
+                "type": "string"
+              },
+              "node": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The id of the record's node, record:<kind>/<id>, when a kind read has the record; null otherwise."
+              }
+            }
+          }
+        },
+        "applied": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "by",
+                "at",
+                "commit"
+              ],
+              "properties": {
+                "by": {
+                  "type": "string",
+                  "description": "Chant-Applied-By: who applied the branch."
+                },
+                "at": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-At, ISO 8601, or null when it is missing."
+                },
+                "commit": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-Commit: the applied branch's tip, or null when it is missing or not a commit id."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "run": {
+      "type": "object",
+      "description": "An agent run that made a commit in the walk (#3033), from the run ledger on the local chant/lifecycle branch. Linked from each commit it made by a made-by edge. Added within version 1. A recorded run has a worked-on edge to the work item it worked on and to each record it names, when a kind read has them (#3034).",
+      "required": [
+        "id",
+        "kind",
+        "run",
+        "recorded",
+        "state",
+        "harness",
+        "model",
+        "provider",
+        "by",
+        "agent",
+        "unit",
+        "startedAt",
+        "endedAt",
+        "outcome",
+        "usage",
+        "cost",
+        "transcript"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^run:"
+        },
+        "kind": {
+          "const": "run"
+        },
+        "run": {
+          "type": "string"
+        },
+        "recorded": {
+          "type": "boolean",
+          "description": "Whether the ledger has the run. A Chant-Run trailer can name a run whose record is missing or not fetched; then every other field is null."
+        },
+        "state": {
+          "enum": [
+            "running",
+            "ended",
+            null
+          ]
+        },
+        "harness": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name",
+                "version"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "version": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "provider": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "by": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "unit": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "startedAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "endedAt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "outcome": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "usage": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/runUsage"
+            }
+          ]
+        },
+        "cost": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/runCost"
+            }
+          ]
+        },
+        "transcript": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/runPin"
+            }
+          ]
+        },
+        "instruction": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/runPin"
+            }
+          ],
+          "description": "The instruction the run was given, pinned by hash, with the writer's excerpt when it gave one (#3034). Added within version 1."
+        },
+        "lease": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The fencing token of the work lease the run worked under (#3034). Added within version 1."
+        }
+      }
+    },
+    "runUsage": {
+      "type": "object",
+      "required": [
+        "turns",
+        "inputTokens",
+        "outputTokens",
+        "cacheReadTokens",
+        "cacheWriteTokens"
+      ],
+      "properties": {
+        "turns": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "inputTokens": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "outputTokens": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "cacheReadTokens": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "cacheWriteTokens": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        }
+      }
+    },
+    "runCost": {
+      "type": "object",
+      "required": [
+        "amount",
+        "currency",
+        "source"
+      ],
+      "properties": {
+        "amount": {
+          "type": "number",
+          "minimum": 0
+        },
+        "currency": {
+          "type": "string",
+          "pattern": "^[A-Z]{3}$",
+          "description": "ISO 4217, such as USD."
+        },
+        "source": {
+          "type": "string",
+          "description": "What priced it, as the writer names it: a harness's own report (harness:claude-code), a proxy's price table (lobby:list-2026-09), a provider's bill."
+        }
+      }
+    },
+    "runPin": {
+      "type": "object",
+      "description": "A file pinned by hash and never copied.",
+      "required": [
+        "sha256",
+        "bytes",
+        "ref"
+      ],
+      "properties": {
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "bytes": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0,
+          "description": "Its size, when chant hashed the file itself; null when the writer gave the hash."
+        },
+        "ref": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where the writer keeps it, as the writer named it. chant never reads it back."
+        },
+        "excerpt": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "On the instruction only, and only when the writer gave one (#3034): a short excerpt to show beside the hash, such as its first line. The hash pins the whole instruction; the excerpt is the writer's and is never checked against it. Added within version 1."
+        }
+      }
+    },
+    "madeByEdge": {
+      "type": "object",
+      "required": [
+        "kind",
+        "from",
+        "to",
+        "joinedBy"
+      ],
+      "properties": {
+        "kind": {
+          "const": "made-by"
+        },
+        "from": {
+          "type": "string"
+        },
+        "to": {
+          "type": "string"
+        },
+        "joinedBy": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "trailer",
+              "record",
+              "patch-id",
+              "squash"
+            ]
+          },
+          "description": "trailer: the commit carries Chant-Run with the run's id. record: the run's end lists the commit. patch-id: neither holds, and the commit's git patch-id --stable equals a commit's the run's end recorded, as after a rebase or a cherry-pick that dropped the trailer (#3036); never alongside the others. Added within version 1. squash: the commit squashes a pull request whose original commits join the run one of those ways, and the read was asked to follow squashes (#3035); via names them. Added within version 1."
+        },
+        "recordedAs": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "For a patch-id join (#3036): the commit the run's end recorded with the same patch-id, which this one rewrites. Added within version 1."
+        },
+        "via": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40,64}$"
+          },
+          "description": "For a squash join (#3035): the pull request's original commits through which the commit joins the run, oldest first. Added within version 1."
+        }
+      }
+    },
+    "why": {
+      "type": "object",
+      "description": "The answer to why the region is like this (#3034, hud#700): who last wrote its current lines, from git blame, the agent run behind each, and the decisions governing the region, most relevant first. explained is false, with intent-why-no-decision in gaps, when no current decision accounts for it. Added within version 1, so an older document may lack it.",
+      "required": [
+        "lines",
+        "blame",
+        "decisions",
+        "runs",
+        "explained",
+        "gaps"
+      ],
+      "properties": {
+        "lines": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/lineRange"
+            }
+          ],
+          "description": "The lines accounted for: the region's range or symbol, the whole file, or null for a directory, which is not blamed."
+        },
+        "blame": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/whySpan"
+          },
+          "description": "The current lines, top to bottom, in spans that one commit and the same runs last wrote. Read with git blame at the revision read, or in the working tree. Empty for a directory."
+        },
+        "decisions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/whyDecision"
+          },
+          "description": "Every decision node in the graph, most relevant first: current before superseded; then carried, path, contract, issue, member, related; then more of the current lines carried out; closed before open; the narrower path constraint; the later deciding commit."
+        },
+        "runs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/whyRun"
+          },
+          "description": "For a file, the runs that wrote its current lines, most lines first, then the later start. For a directory, every run in the walk, the latest start first, with lines 0."
+        },
+        "explained": {
+          "type": "boolean",
+          "description": "Whether a current decision governs the region at any granularity, or is carried out by the commits or runs that made its current lines."
+        },
+        "gaps": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/whyGap"
+          },
+          "description": "What the answer can't account for, each with a closed code."
+        }
+      }
+    },
+    "whySpan": {
+      "type": "object",
+      "required": [
+        "start",
+        "end",
+        "commit",
+        "sha",
+        "runs",
+        "narrowedBy"
+      ],
+      "properties": {
+        "start": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "commit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The commit node that last wrote the lines, or null for lines not committed yet."
+        },
+        "sha": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "runs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The run nodes behind the lines: the run the commit's Chant-Run names first, then those whose record lists the commit. More than one is intent-why-run-ambiguous."
+        },
+        "narrowedBy": {
+          "enum": [
+            "hunks",
+            null
+          ],
+          "description": "hunks: runs' recorded hunks chose among the runs that made the commit, and a run whose hunks miss the lines is left out. null: every run that made the commit is listed."
+        },
+        "joinedBy": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "trailer",
+              "record",
+              "patch-id",
+              "squash"
+            ]
+          },
+          "description": "How the runs in runs join the commit, as their made-by edges say, without repeats; empty with no runs. patch-id marks a join by content, which a reader shows apart from a trailer or a record (#3036). Added within version 1, so an older document may lack it."
+        },
+        "via": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40,64}$"
+          },
+          "description": "Only on the lines of a followed squash (#3035): the original commit that last wrote them, one of the commit node's squash.commits, by git blame at the pull request's head, and runs keeps that commit's runs and the squash's own. Empty when the file at the head differs from the squash's, so blame there can't say. Added within version 1."
+        }
+      }
+    },
+    "whyDecision": {
+      "type": "object",
+      "required": [
+        "decision",
+        "relevance",
+        "current",
+        "closed",
+        "lines"
+      ],
+      "properties": {
+        "decision": {
+          "type": "string",
+          "description": "The decision node."
+        },
+        "relevance": {
+          "enum": [
+            "carried",
+            "path",
+            "contract",
+            "issue",
+            "member",
+            "related"
+          ],
+          "description": "carried: a commit or run that made current lines carries the decision out, through a unit, a Chant-Record or Chant-Lease trailer, or the run's work item and records (for a directory, any commit in the walk). path, contract, issue, member: it constrains the region that way. related: it is in the graph only through supersession, or through a commit that made no current line."
+        },
+        "current": {
+          "type": "boolean",
+          "description": "Not superseded."
+        },
+        "closed": {
+          "type": "boolean",
+          "description": "Its state is one its kind closes, such as ratified."
+        },
+        "lines": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many current lines were made as its own work."
+        }
+      }
+    },
+    "whyRun": {
+      "type": "object",
+      "required": [
+        "run",
+        "lines",
+        "commits",
+        "unit",
+        "decisions"
+      ],
+      "properties": {
+        "run": {
+          "type": "string",
+          "description": "The run node."
+        },
+        "lines": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The commit nodes through which it made the lines."
+        },
+        "unit": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "id",
+                "kind",
+                "node"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "kind": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "node": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The work node, when a work kind read has the item."
+                }
+              }
+            }
+          ],
+          "description": "The work item the run record names."
+        },
+        "decisions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The decision nodes it carried out: the ones its work item implements and the decision records it names."
+        },
+        "joinedBy": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "trailer",
+              "record",
+              "patch-id",
+              "squash"
+            ]
+          },
+          "description": "How the run joins the commits in commits, as their made-by edges say, without repeats (#3036). Added within version 1, so an older document may lack it."
+        }
+      }
+    },
+    "whyGap": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "enum": [
+            "intent-why-no-decision",
+            "intent-why-no-run",
+            "intent-why-uncommitted",
+            "intent-why-run-ambiguous"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "lines": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/lineRange"
+          },
+          "description": "The lines the gap is about, for intent-why-uncommitted and intent-why-run-ambiguous."
+        }
+      }
+    },
+    "squash": {
+      "type": "object",
+      "description": "Present only when the read follows squashes (--follow-squash, #3035) and the commit squashes a pull request: its subject ends with (#<n>), it has one parent, and the pull request's head is not in its history. The commit carries what the original commits' trailers carry and joins their runs. Added within version 1.",
+      "required": [
+        "pullRequest",
+        "forge",
+        "ref",
+        "head",
+        "fetched",
+        "followed",
+        "commits"
+      ],
+      "properties": {
+        "pullRequest": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "forge": {
+          "enum": [
+            "github",
+            "forgejo",
+            null
+          ],
+          "description": "The forge origin points at, from its URL, or null for one chant doesn't know or no origin. Both keep the pull request's head at refs/pull/<n>/head."
+        },
+        "ref": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The local ref the head was read from: refs/chant/pull/<n>/head where a read fetched it, refs/pull/<n>/head, or refs/remotes/origin/pr/<n>. Null when none could be read."
+        },
+        "head": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^[0-9a-f]{40,64}$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The pull request's head commit, or null."
+        },
+        "fetched": {
+          "type": "boolean",
+          "description": "Whether this read fetched the ref from origin."
+        },
+        "followed": {
+          "type": "boolean",
+          "description": "Whether the original commits were read. When false, squash-unfollowed in reasons says why, and commits is empty."
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "sha",
+              "subject",
+              "author",
+              "date",
+              "trailers",
+              "signature",
+              "joins"
+            ],
+            "properties": {
+              "sha": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{40,64}$"
+              },
+              "subject": {
+                "type": "string"
+              },
+              "author": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "email"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  }
+                }
+              },
+              "date": {
+                "type": "string"
+              },
+              "trailers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "joins": {
+                "$ref": "#/$defs/trailerJoins"
+              },
+              "signature": {
+                "type": "object",
+                "required": [
+                  "level",
+                  "reason"
+                ],
+                "properties": {
+                  "level": {
+                    "enum": [
+                      "attested",
+                      "attested-unverifiable-here",
+                      "adopted",
+                      "unattested"
+                    ],
+                    "description": "The commit's provenance level, judged by the signers at base as records judges a record (#2547)."
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "principal": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "description": "The original commits, oldest first: the head's commits the squash's parent doesn't have, merges left out."
+        }
+      }
     }
   }
 }