@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/points.schema.json

@@ -238,7 +238,7 @@
           }
         },
         "criteria": {
-          "description": "What each candidate means, as the points file declares it: noul and choice give an object of strings keyed by candidate, score an array of ordered level descriptions.",
+          "description": "What each candidate means, as the points file declares it: noul and choice give an object of strings keyed by candidate, score an array of ordered level descriptions. Empty for an ad-hoc point (#3403).",
           "oneOf": [
             {
               "type": "object",
@@ -254,6 +254,10 @@
             }
           ]
         },
+        "adhoc": {
+          "type": "boolean",
+          "description": "An ad-hoc point (#3403): the question's text and candidates come with each ask, and each question lists them as asked. Its candidates are empty and its criteria an empty object, or an empty array for a score. Absent from a chant before it."
+        },
         "inputs": {
           "type": "array",
           "items": {
@@ -269,7 +273,7 @@
               },
               "output": {
                 "type": "string",
-                "description": "The read-contract output the input names: record, decision, work-item, finding, region, commit, member, gate, release, environment or component."
+                "description": "The read-contract output the input names: record, decision, work-item, finding, region, commit, node, member, gate, release, environment, component or ask."
               },
               "description": {
                 "type": "string"
@@ -464,6 +468,13 @@
             }
           ]
         },
+        "reason": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The model's own explanation of the recorded answer, a proposal or a confirmed proposal, when the backend gave one (#3345). null otherwise, and from a chant before it."
+        },
         "model": {
           "description": "Any model answer: the proposal (observed), or the last answer below a model decider's threshold (not observed). null when no model answered.",
           "oneOf": [
@@ -532,6 +543,13 @@
                 },
                 "observed": {
                   "type": "boolean"
+                },
+                "reason": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The model's explanation of this answer, when the backend gave one (#3345)."
                 }
               }
             }
@@ -591,6 +609,10 @@
                 "type": "number",
                 "minimum": 0,
                 "maximum": 1
+              },
+              "model_reason": {
+                "type": "string",
+                "description": "A model decider's own explanation of the answer it gave, when the backend gave one (#3345). reason is why the decider did not answer."
               }
             }
           }
@@ -646,6 +668,139 @@
             "null"
           ]
         },
+        "note": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What the people who answered wrote with their answer (points answer --note, #3351). null when they wrote nothing, and from a chant before it."
+        },
+        "relayedBy": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Who relayed the answer to chant for the people who gave it (points answer --relayed-by, #3402), such as a follower relaying a person's answer through hud. null when nobody did, and from a chant before it."
+        },
+        "retractions": {
+          "type": "array",
+          "description": "Answers people took back, oldest first (points retract, #3351): each answer as it was and who retracted it, when and why. A retracted question is escalated to people again. Empty when none was, and absent from a chant before it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "answer",
+              "decider",
+              "answeredBy",
+              "answeredOn",
+              "answerNote",
+              "answerRelayedBy",
+              "by",
+              "on",
+              "note"
+            ],
+            "properties": {
+              "answer": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "decider": {
+                "type": "object",
+                "description": "Who gave the answer: the record's decider as it was."
+              },
+              "answeredBy": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "answeredOn": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "answerNote": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The note the answer carried."
+              },
+              "answerRelayedBy": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Who relayed the answer (#3402)."
+              },
+              "by": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Who retracted it."
+              },
+              "on": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "note": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Why it was retracted (points retract --note)."
+              }
+            }
+          }
+        },
+        "asked": {
+          "description": "An ad-hoc point's question as its ask gave it (points ask --candidates, #3403): the question's text, and its criteria, what each candidate means, in the point's question type's shape. People's answer is one of the candidates. null for a declared point's question, and absent from a chant before it.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "question",
+                "criteria"
+              ],
+              "properties": {
+                "question": {
+                  "type": "string"
+                },
+                "criteria": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    },
+                    {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        },
         "valid": {
           "type": "boolean"
         },

package/src/workspace/points.test.ts

@@ -143,7 +143,7 @@ describe("the decision points schema (#2738)", () => {
 
   test("the reference workspace's points validate", () => {
     const points = parsePoints(readFileSync(join(REPO, "reference-workspace", "decisions", "points.json"), "utf-8"), "decisions/points.json");
-    expect(Object.keys(points)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision"]);
+    expect(Object.keys(points)).toEqual(["slice-tier", "understand", "ship-skip", "finding-triage", "needs-a-decision", "intent-origin", "intent-judgment", "intent-disposition", "agent-question"]);
   });
 
   test("a point whose chain does not end in a quorum is refused", () => {
@@ -232,6 +232,18 @@ describe("the decider chain (#2739)", () => {
     expect(r.escalations[1]).toMatchObject({ kind: "model", answer: "medium", confidence: 0.25, threshold: 0.8, reason: "not observed: confidence 0.25 is below the threshold 0.8" });
   });
 
+  test("the model's reason is kept with a proposal, and in the escalation of an answer below the threshold (#3345)", async () => {
+    const proposed = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", probabilities: { large: 0.9 }, confidence: 0.9, reason: "  Nine criteria across three services.\n" }));
+    expect(proposed).toMatchObject({ status: "proposed", reason: "Nine criteria across three services." });
+    const low = await runChain("n", NOUL, {}, stub({ type: "noul", noul: 0.6, reason: "Probably, but the diff is small." }));
+    expect(low.escalations[0]).toMatchObject({ kind: "model", answer: true, reason: "not observed: confidence 0.6 is below the threshold 0.8", model_reason: "Probably, but the diff is small." });
+    // A blank or non-string reason is no reason.
+    const blank = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", confidence: 0.9, reason: "  " }));
+    expect(blank).not.toHaveProperty("reason");
+    const odd = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", confidence: 0.9, reason: 3 } as unknown as WireAnswer));
+    expect(odd).not.toHaveProperty("reason");
+  });
+
   test("without a backend, or with an unpinned model answering, the model is not asked or not observed", async () => {
     expect((await runChain("slice-tier", SLICE, big)).escalations[1].reason).toBe("not asked: no model backend was given to this ask");
     const r = await runChain("slice-tier", SLICE, big, stub({ type: "choice", choice: "large", confidence: 0.99 }, "bosun-latest"));

package/src/workspace/points.ts

@@ -15,6 +15,12 @@
  *           proposal a person confirms; below it, the next decider is asked.
  *   quorum  people. Always last: the question escalates to them.
  *
+ * A point declared `adhoc` (#3403) has no candidates of its own: its
+ * question's text and candidates come with each ask, as an agent's question
+ * to the room does, and the answer record keeps them as `asked`, so people's
+ * answer is checked against the candidates the question was asked with. Only
+ * people decide it: its chain is one quorum.
+ *
  * chant never calls a model (ws-052). {@link runChain} takes the model call
  * as a function, {@link ModelAsk}, which the decide Op activity (#2740), a
  * runtime's decider or a test's stub supplies. Without one, a model decider is
@@ -51,6 +57,8 @@ export const POINT_INPUT_OUTPUTS = {
   finding: { schema: "intent", def: "finding", description: "a finding of graph --intent, or of check --changes (#2794)" },
   region: { schema: "intent", def: "region", description: "the region an intent graph covers" },
   commit: { schema: "intent", def: "commit", description: "a commit in an intent graph's window" },
+  node: { schema: "intent", def: "node", description: "any node of an intent graph, by its id and kind: a commit, decision, unit, artifact or the region itself, as an intent walk asks of it (#3351)" },
+  ask: { schema: "points", def: "question", description: "an ad-hoc question as its asker knows it (#3403): the asker's own id for the ask, such as hud's request id for an agent's question, and who asked" },
   member: { schema: "ls", def: "member", description: "a member, as ls lists it" },
   gate: { schema: "status", def: "gate", description: "a gate, as status lists it" },
   release: { schema: "status", def: "release", description: "a release, as status lists it; a release plan's fields until the lifecycle ledger lists plans (#2717)" },
@@ -73,7 +81,8 @@ export type QuestionType = "noul" | "choice" | "score";
 export interface Question {
   type: QuestionType;
   instructions: string;
-  criteria: Record<string, string> | string[];
+  /** The candidates and what each means. Absent only from an ad-hoc point's declaration, whose candidates come with each ask (#3403). */
+  criteria?: Record<string, string> | string[];
 }
 
 export type Scalar = string | number | boolean | null;
@@ -92,6 +101,8 @@ export type Decider =
 
 export interface Point {
   title: string;
+  /** The question's text and candidates come with each ask, not the declaration (#3403). */
+  adhoc?: boolean;
   question: Question;
   inputs: Record<string, string>;
   deciders: Decider[];
@@ -116,8 +127,8 @@ export class PointsError extends Error {
 /** A question's candidate answers: true and false, a choice's options, or a score's levels. */
 export function candidates(question: Question): (string | boolean)[] {
   if (question.type === "noul") return [true, false];
-  if (question.type === "choice") return Object.keys(question.criteria);
-  return [...(question.criteria as string[])];
+  if (question.type === "choice") return Object.keys(question.criteria ?? {});
+  return [...((question.criteria as string[] | undefined) ?? [])];
 }
 
 const ONLY: Record<Decider["kind"], string[]> = { table: ["rows"], model: ["backend", "model", "threshold", "unreachable"], quorum: ["count", "roles"] };
@@ -140,6 +151,12 @@ function pointProblems(points: Record<string, Point>): PointProblem[] {
         });
       }
     }
+    if (point.adhoc && (point.deciders.length !== 1 || point.deciders[0].kind !== "quorum")) {
+      problems.push({
+        field: at("deciders"),
+        message: "is an ad-hoc point's chain, and an ad-hoc point is decided by people alone: its chain is one quorum, since no table row or model can know candidates that come with the ask",
+      });
+    }
     const allowed = candidates(point.question);
     const last = point.deciders.length - 1;
     point.deciders.forEach((d, i) => {
@@ -210,7 +227,9 @@ export function schemaProblems(data: unknown): PointProblem[] {
           ? `is missing ${JSON.stringify(e.params.missingProperty)}`
           : e.keyword === "propertyNames"
             ? `has a name that is not allowed: ${JSON.stringify(e.params.propertyName)}`
-            : (e.message ?? "is invalid");
+            : e.keyword === "not"
+              ? "has criteria, and an ad-hoc point's candidates come with each ask (#3403): leave criteria out"
+              : (e.message ?? "is invalid");
     const key = `${field}\0${message}`;
     if (seen.has(key)) continue;
     seen.add(key);
@@ -262,8 +281,71 @@ const sha256 = (text: string): string => createHash("sha256").update(text, "utf8
 /** The version of a point: the sha256 of its declaration. Editing the question or any decider changes it. */
 export const pointVersion = (point: Point): string => sha256(canonical(point));
 
-/** What is answered once: the point, its version and the inputs. */
-export const inputsHash = (name: string, version: string, inputs: Record<string, unknown>): string => sha256(canonical({ point: name, version, inputs }));
+/**
+ * What is answered once: the point, its version and the inputs, and for an
+ * ad-hoc point the question and candidates it was asked with (#3403).
+ */
+export const inputsHash = (name: string, version: string, inputs: Record<string, unknown>, asked?: Asked): string => sha256(canonical({ point: name, version, inputs, asked }));
+
+// ── Ad-hoc questions (#3403) ─────────────────────────────────────────────────
+
+/** An ad-hoc point's question as one ask gave it: its text and its candidates, in the point's question type's shape. */
+export interface Asked {
+  question: string;
+  criteria: Record<string, string> | string[];
+}
+
+/** The question an answer asks: the point's own, or for an ad-hoc point the one the ask gave. */
+export function askedQuestion(point: Point, asked: Asked | undefined): Question {
+  return asked ? { type: point.question.type, instructions: asked.question, criteria: asked.criteria } : point.question;
+}
+
+const nonEmpty = (v: unknown): v is string => typeof v === "string" && v.trim() !== "";
+
+/**
+ * An ad-hoc ask's question and candidates (`points ask --candidates`), checked
+ * against the point's question type as a declaration's criteria are: noul
+ * describes true and false, choice gives 2 to 255 options, each with what it
+ * means, and score 2 to 10 distinct ordered levels. Returns the problems, or
+ * the question.
+ */
+export function parseAsked(point: Point, value: unknown): { asked: Asked } | { problems: string[] } {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return { problems: ["the candidates must be a JSON object with question and criteria"] };
+  const v = value as Record<string, unknown>;
+  const problems: string[] = [];
+  const extra = Object.keys(v).filter((k) => k !== "question" && k !== "criteria");
+  if (extra.length > 0) problems.push(`the candidates take question and criteria, not ${extra.join(", ")}`);
+  if (!nonEmpty(v.question)) problems.push("question must be the question's text");
+  const c = v.criteria;
+  const type = point.question.type;
+  if (type === "score") {
+    if (!Array.isArray(c) || c.length < 2 || c.length > 10 || !c.every(nonEmpty) || new Set(c).size !== c.length) problems.push("criteria must be 2 to 10 distinct levels, in order, for a score question");
+  } else if (c === null || typeof c !== "object" || Array.isArray(c)) {
+    problems.push(`criteria must be an object of ${type === "noul" ? "true and false" : "options"}, each with what it means`);
+  } else {
+    const entries = Object.entries(c as Record<string, unknown>);
+    if (!entries.every(([k, d]) => k !== "" && typeof d === "string")) problems.push("each criterion must be a non-empty name with what it means as a string");
+    if (type === "noul") {
+      const keys = entries.map(([k]) => k).sort();
+      if (keys.length !== 2 || keys[0] !== "false" || keys[1] !== "true") problems.push("criteria must describe true and false, and nothing else, for a noul question");
+    } else if (entries.length < 2 || entries.length > 255) {
+      problems.push("criteria must give 2 to 255 options for a choice question");
+    }
+  }
+  if (problems.length > 0) return { problems };
+  const criteria = Array.isArray(c) ? [...(c as string[])] : { ...(c as Record<string, string>) };
+  return { asked: { question: (v.question as string).trim(), criteria } };
+}
+
+/** An answer record's `asked`, when it has one. */
+export function askedOf(data: Record<string, unknown>): Asked | undefined {
+  const a = data.asked as Record<string, unknown> | undefined;
+  if (a === null || typeof a !== "object" || Array.isArray(a) || typeof a.question !== "string") return undefined;
+  const c = a.criteria;
+  if (Array.isArray(c)) return { question: a.question, criteria: c.filter((x): x is string => typeof x === "string") };
+  if (c !== null && typeof c === "object") return { question: a.question, criteria: Object.fromEntries(Object.entries(c as Record<string, unknown>).filter(([, d]) => typeof d === "string")) as Record<string, string> };
+  return undefined;
+}
 
 /** The id of the answer to `name` for inputs hashing to `hash`: the name and the hash's first 12 hex digits. */
 export const answerId = (name: string, hash: string): string => `${name}-${hash.slice(0, 12)}`;
@@ -311,15 +393,28 @@ export interface WireQuestion {
   criteria: Record<string, string> | string[];
 }
 
-/** One answer in the wire format's shape. */
+/**
+ * One answer in the wire format's shape. `reason` is the model's own
+ * explanation of its answer, when the backend gives one (#3345): kept in the
+ * answer record beside a proposal, or in the escalation entry of an answer
+ * below the threshold, so a person sees why the model chose.
+ */
 export type WireAnswer =
-  | { type: "noul"; noul: number }
-  | { type: "choice"; choice: string; probabilities?: Record<string, number>; confidence?: number }
-  | { type: "score"; score?: number; legend?: unknown; probabilities?: Record<string, number>; confidence?: number }
+  | { type: "noul"; noul: number; reason?: string }
+  | { type: "choice"; choice: string; probabilities?: Record<string, number>; confidence?: number; reason?: string }
+  | { type: "score"; score?: number; legend?: unknown; probabilities?: Record<string, number>; confidence?: number; reason?: string }
   | { type: "unsupported" };
 
+/** A wire answer's reason, trimmed, or undefined when it gives none (or not a string). */
+export function answerReason(answer: WireAnswer | undefined): string | undefined {
+  const raw = (answer as { reason?: unknown } | undefined)?.reason;
+  if (typeof raw !== "string") return undefined;
+  const reason = raw.trim();
+  return reason === "" ? undefined : reason;
+}
+
 export function wireQuestion(question: Question): WireQuestion {
-  return { type: question.type, instructions: question.instructions, criteria: question.criteria };
+  return { type: question.type, instructions: question.instructions, criteria: question.criteria ?? {} };
 }
 
 /** What a model decider is asked. */
@@ -388,7 +483,12 @@ export function observe(question: Question, answer: WireAnswer | undefined, thre
   return { observed: false, answer: choice, probabilities, confidence, reason: `confidence ${confidence} is below the threshold ${threshold}` };
 }
 
-/** A decider that was asked and did not answer, and why. */
+/**
+ * A decider that was asked and did not answer, and why: `reason` is chant's
+ * account of why it did not answer. `model_reason` is the model's own
+ * explanation of the answer it gave (#3345), when it gave one; it is not named
+ * `reason` because that field already says why the decider escalated.
+ */
 export interface Escalation {
   kind: "table" | "model";
   reason: string;
@@ -398,6 +498,7 @@ export interface Escalation {
   probabilities?: Record<string, number>;
   confidence?: number;
   threshold?: number;
+  model_reason?: string;
 }
 
 export type ChainResult =
@@ -409,6 +510,8 @@ export type ChainResult =
       probabilities: Record<string, number>;
       confidence: number;
       threshold: number;
+      /** The model's explanation of its answer, when the backend gave one (#3345). */
+      reason?: string;
       escalations: Escalation[];
     }
   | { status: "escalated"; decider: { kind: "quorum"; count: number; roles?: string[] }; escalations: Escalation[] };
@@ -455,6 +558,7 @@ export async function runChain(name: string, point: Point, inputs: Record<string
         continue;
       }
       const seen = observe(point.question, reply.answer, d.threshold);
+      const why = answerReason(reply.answer);
       if (seen.observed) {
         return {
           status: "proposed",
@@ -463,6 +567,7 @@ export async function runChain(name: string, point: Point, inputs: Record<string
           probabilities: seen.probabilities,
           confidence: seen.confidence,
           threshold: d.threshold,
+          ...(why !== undefined ? { reason: why } : {}),
           escalations,
         };
       }
@@ -475,6 +580,7 @@ export async function runChain(name: string, point: Point, inputs: Record<string
         ...(seen.confidence !== undefined ? { confidence: seen.confidence } : {}),
         threshold: d.threshold,
         reason: `not observed: ${seen.reason}`,
+        ...(why !== undefined ? { model_reason: why } : {}),
       });
     } else {
       return { status: "escalated", decider: { kind: "quorum", count: d.count, ...(d.roles ? { roles: d.roles } : {}) }, escalations };

package/src/workspace/pr-report.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json",
+  "title": "pull-request report",
+  "description": "What one stage of the pull-request loop (#3183) planned or applied: the members a change reaches, the digest the gate binds, where the approval stands and how the stage ended. Written by `chant components pr-plan` (pr-plan.json) and `chant components pr-apply` (pr-apply.json), and built by prReport in @intentius/chant/components/pr-run. The pull-request note is rendered from it by renderPrNote in @intentius/chant/pr-loop. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "type": "object",
+  "required": ["$schema", "contract", "stage", "pr", "env", "base", "head", "op", "gate", "digest", "status", "approval", "selection", "members", "changeSet"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json" },
+    "contract": { "const": 1 },
+    "stage": { "enum": ["plan", "apply"] },
+    "pr": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "The pull or merge request number. null when an apply found no pull request that merged its commit."
+    },
+    "env": { "type": "string" },
+    "base": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the change is measured from: the merge base of the given base and head." },
+    "head": { "type": "string", "pattern": "^[0-9a-f]{40,64}$" },
+    "op": {
+      "type": "string",
+      "description": "The gate's op, pr-<number>. Its ledger is _gates/<op>.jsonl on chant/lifecycle. pr-unknown when no pull request was found."
+    },
+    "gate": { "type": "string", "description": "The gate the apply waits on, pr-apply unless the pipeline names another." },
+    "digest": {
+      "type": "string",
+      "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$",
+      "description": "The change-set digest of what this stage planned: computePlanDigest(\"change-set\", ...) over every member's { member, planDigest }. What the gate binds."
+    },
+    "status": {
+      "enum": ["planned", "plan-failed", "nothing", "applied", "failed", "refused"],
+      "description": "planned: every member planned (plan stage). plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. refused: nothing applied, see refusal."
+    },
+    "refusal": {
+      "enum": ["not-approved", "plan-changed", "not-a-reviewer", "no-pull-request"],
+      "description": "Why an apply refused. plan-changed: an approval stands for another digest, so the plan changed after review."
+    },
+    "message": { "type": "string", "description": "The refusal or failure as printed." },
+    "approval": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["approved", "changed", "pending"], "description": "approved: an approval stands for digest. changed: one stands for another digest. pending: none stands." },
+        "approvedBy": { "type": "array", "items": { "type": "string" }, "description": "Who approved digest, as the approval names them (github:<login>, gitlab:<login>, <forge>@<host>:<login>, or a signer)." },
+        "approved": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "With changed: the digest that was approved." }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "required": ["changed", "dependents", "unclaimed", "indeterminate", "waves"],
+      "description": "Component names. The fan-out derivation the change gives (#2417).",
+      "properties": {
+        "changed": { "type": "array", "items": { "type": "string" }, "description": "Components deploying a unit the change touched, in dependency order." },
+        "dependents": { "type": "array", "items": { "type": "string" }, "description": "Components selected because they depend on a changed one, in dependency order." },
+        "unclaimed": { "type": "array", "items": { "type": "string" }, "description": "Units the change touched that no component deploys." },
+        "indeterminate": { "type": "array", "items": { "type": "string" }, "description": "Components a source diff cannot judge that the walk did not reach." },
+        "waves": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "The selected components in parallel-safe waves, in apply order." }
+      }
+    },
+    "members": {
+      "type": "array",
+      "description": "One entry per change-set member, sorted by member.",
+      "items": {
+        "type": "object",
+        "required": ["member", "component", "planDigest", "status", "counts"],
+        "properties": {
+          "member": { "type": "string", "description": "The member's name in the change set: the root, for a terraform-family step." },
+          "component": { "type": "string" },
+          "planDigest": { "type": ["string", "null"], "description": "What a gate on this member alone binds. null when it failed to plan." },
+          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked"] },
+          "counts": {
+            "type": "object",
+            "required": ["create", "update", "replace", "delete"],
+            "properties": {
+              "create": { "type": "integer", "minimum": 0 },
+              "update": { "type": "integer", "minimum": 0 },
+              "replace": { "type": "integer", "minimum": 0 },
+              "delete": { "type": "integer", "minimum": 0 }
+            }
+          },
+          "error": { "type": "string" },
+          "inputsMoved": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Apply stage: components this one depends on whose outputs changed when they applied. It applied the plan it was approved with; the next run plans it against the new values."
+          }
+        }
+      }
+    },
+    "changeSet": {
+      "type": "object",
+      "description": "The change-set document over every member (change-set.schema.json). Its digest equals digest."
+    }
+  }
+}