@intentius/chant 0.124.51 → 0.124.54

package/src/workspace/graph.schema.json

@@ -394,6 +394,13 @@
           ],
           "description": "What the per-member cache keys this read on (#2876): sha256 over the member's files and install state, or over the commit id with --at. Present on composed members; null for a live read or when no stamp could be taken. Two reads of a member with equal stamps read the same source."
         },
+        "rootReads": {
+          "type": "object",
+          "description": "Added in contract 1 by #4452. With --live: which read answered each of the member's roots, the member IR's rootReads as its chant wrote it, keyed by the lexicon's root key (terraform uses terraform.roots.<root>), unprefixed. The read that answered is fellBackTo when set, else depth. Absent when the member's IR had none, including a member read by a chant before #4452.",
+          "additionalProperties": {
+            "$ref": "#/$defs/rootRead"
+          }
+        },
         "meta": {
           "type": "object",
           "description": "The member IR's whole-read facts."
@@ -548,6 +555,45 @@
         "runtimeOwner": {
           "type": "string"
         },
+        "instanceOf": {
+          "type": "string",
+          "description": "Added in contract 1 by #4454. On an instance node of a count or for_each block: the block node's id, prefixed like the ids. The instance node's id is that id followed by instanceKey (<member>/<block>[0]); the block node stays and is the rollup."
+        },
+        "instanceKey": {
+          "type": "string",
+          "description": "Added in contract 1 by #4454. With instanceOf: the block's own instance key as the engine prints it, [0] or [\"a\"]. Absent on an instance only an expanded module call makes (#4486)."
+        },
+        "instanceScope": {
+          "type": "string",
+          "description": "Added in contract 1 by #4486. With instanceOf, under an expanded module call: the module path as the engine prints it, module.app[0]. The id then carries the key on the call's segment, <member>/<root>/module.app[0]/aws_eip.pool[1]."
+        },
+        "instanceRollup": {
+          "type": "object",
+          "description": "Added in contract 1 by #4489, written by chant 0.124.54 and newer. On a block node whose count or for_each the declared graph cannot count: why it stays one node, with no instance nodes under it. Absent on a block that is not expanded and on one whose instances are listed. The read contract lists every form that is rolled up and its code.",
+          "required": ["code", "argument", "expression"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "enum": ["instances-each-value", "instances-merge", "instances-value-unknown", "instances-form-unread", "instances-over-limit", "instances-module-uncounted"]
+            },
+            "argument": {
+              "type": "string",
+              "enum": ["count", "for_each"]
+            },
+            "expression": {
+              "type": "string",
+              "description": "The count or for_each expression as written, without the ${ } around it. With call, the module call's."
+            },
+            "call": {
+              "type": "string",
+              "description": "With instances-module-uncounted: the module call that could not be counted, module.app or module.app.module.db."
+            }
+          }
+        },
+        "facts": {
+          "type": "object",
+          "description": "Added in contract 1 by #4529, written by chant 0.124.54 and newer. What an ownership engine observed about the node: ownership, markers, ownedBy, cloudIds, recordVersions and observedAt, each optional, in the shape of EngineFacts (packages/core/src/graph-schema/graph.schema.json). Set on a Pulumi member on plunge from its checked-in engine-graph.json. Never read for a decision."
+        },
         "nested": {
           "type": "string",
           "description": "For a node read through a nested workspace (#2551): the nested workspace's member it belongs to. `member` is then the outer member, and the id is `<member>/<nested>/<id>`."
@@ -605,6 +651,10 @@
           "type": "boolean",
           "description": "Added in contract 1 by #3922. True when the edge leaves the pipeline `from` belongs to (#3910): a reusable-workflow call, a `workflow_run` trigger, a GitLab child or multi-project trigger, an include. Absent on every in-pipeline edge."
         },
+        "grain": {
+          "enum": ["block", "instance", "property"],
+          "description": "Added in contract 1 by #4529, written by chant 0.124.54 and newer. What the edge joins: two blocks, two instances, or a property of one instance to another. A Pulumi member's dependencies and parent edges are instance; a plunge member's property edges are property. Absent when the source does not say."
+        },
         "member": {
           "type": "string"
         }
@@ -1620,6 +1670,28 @@
           }
         }
       }
+    },
+    "rootRead": {
+      "type": "object",
+      "description": "Which read answered one root (#4452), as packages/core/src/observation.ts RootRead. depth is the read asked for (plan for a plan-depth root, live+plan for a live root at the plan depth). fellBackTo is set only when that read failed: the read that answered instead (live is live-plan alone, for a live root), or declared when none did. reason is a short machine-stable cause such as no-credentials, needs-init, backend-unreachable or plan-failed, not prose to match on.",
+      "required": [
+        "depth"
+      ],
+      "properties": {
+        "depth": {
+          "type": "string"
+        },
+        "fellBackTo": {
+          "enum": [
+            "state",
+            "live",
+            "declared"
+          ]
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
     }
   }
 }

package/src/workspace/init.test.ts

@@ -4,7 +4,8 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { parseArgs } from "../cli/main";
-import { parseDeclaration } from "./declaration";
+import { parseDeclaration, resolveGroups } from "./declaration";
+import { workingTree } from "./tree";
 import { proposeWorkspace, runWorkspaceInit, sanitizeName } from "./init";
 
 const REPO = join(import.meta.dirname, "..", "..", "..", "..");
@@ -129,6 +130,42 @@ describe("proposeWorkspace (#2534)", () => {
     expect(() => parseDeclaration(JSON.stringify(declaration), "chant.workspace.json")).not.toThrow();
   });
 
+  test("a workspace under an examples directory is a workspace member with a note; plain projects there stay examples (#4499)", () => {
+    const root = repo({
+      "examples/a/chant.config.ts": "",
+      "examples/b/chant.config.ts": "",
+      "examples/kit/chant.workspace.json": JSON.stringify({ name: "kit", schema: 1, members: [] }),
+      "examples/kit/chant.config.ts": "",
+      "examples/kit/app/chant.config.ts": "",
+    });
+    const { declaration } = proposeWorkspace(root, { name: "acme" });
+    expect(declaration.members).toEqual([
+      {
+        name: "kit",
+        dir: "examples/kit",
+        kind: "workspace",
+        because: "a workspace of its own under examples, an examples directory; a workspace is a member, never an example",
+      },
+      // The group's glob leaves the member's directory out by name.
+      { name: "examples", kind: "examples", glob: "examples/!(kit)" },
+    ]);
+    const parsed = parseDeclaration(JSON.stringify(declaration), "chant.workspace.json");
+    expect(resolveGroups(parsed, workingTree(root))[0].matches).toEqual(["examples/a", "examples/b"]);
+  });
+
+  test("a workspace under an examples directory inside another package stays an example, since members don't nest (#4499)", () => {
+    const root = repo({
+      "package.json": JSON.stringify({ name: "acme", workspaces: ["lexicons/*"] }),
+      "lexicons/x/package.json": pkg("@acme/lexicon-x"),
+      "lexicons/x/examples/ws/chant.workspace.json": JSON.stringify({ name: "ws", schema: 1, members: [] }),
+      "lexicons/x/examples/ws/chant.config.ts": "",
+      "lexicons/x/examples/plain/chant.config.ts": "",
+    });
+    const { declaration } = proposeWorkspace(root, { name: "acme" });
+    expect(declaration.members.some((m) => m.kind === "workspace")).toBe(false);
+    expect(declaration.members.find((m) => m.kind === "examples")?.glob).toBe("lexicons/x/examples/*");
+  });
+
   test("names the workspace by --name, then the remote, then the root package, then the directory", () => {
     expect(proposeWorkspace(repo(ACME, "https://example.com/org/Platform.git"), { name: "given" }).declaration.name).toBe("given");
     expect(proposeWorkspace(repo(ACME)).declaration.name).toBe("acme-monorepo");

package/src/workspace/init.ts

@@ -8,7 +8,11 @@
  *
  * - each outermost chant project (a chant.config.ts or .json) becomes a
  *   `chant` member, and the root's own config makes a root member `"."`;
- * - each nested declaration becomes a `workspace` member;
+ * - each nested declaration becomes a `workspace` member; one under an
+ *   examples-style directory does too, with a `because` saying where it sits
+ *   (#4499), and the example group's glob leaves its directory out, unless
+ *   it sits inside another package or project, where it stays an example
+ *   since only the root member contains other members;
  * - each other npm package, from the npm workspaces or any other
  *   package.json, becomes an `other` member with a `because`;
  * - projects under an `examples`, `test` or `fixtures`-style directory become
@@ -342,8 +346,24 @@ function exampleGlobs(tree: WorkspaceTree, matches: string[], memberDirs: string
     if (ms.length * 2 >= subdirs) wide.push(parent);
     else explicit.push(...ms);
   }
-  const safe = (glob: string): boolean =>
-    expandGlob(tree, glob).every((d) => !memberDirs.some((m) => m !== "" && isInside(m, d)) && (matches.includes(d) || !holdsChantProject(tree, d)));
+  const blocked = (d: string): boolean => memberDirs.some((m) => m !== "" && isInside(m, d)) || (!matches.includes(d) && holdsChantProject(tree, d));
+  const safe = (glob: string): boolean => expandGlob(tree, glob).every((d) => !blocked(d));
+  /**
+   * `<prefix>/*` when it is safe, else `<prefix>/!(a|b)` leaving out the
+   * directories that block it (a workspace member under an examples
+   * directory, #4499), when that is safe and still covers every match the
+   * prefix's parents hold. Undefined when neither works.
+   */
+  const lastSegment = (prefix: string, parents: readonly string[]): string | undefined => {
+    const all = `${prefix}/*`;
+    if (safe(all)) return all;
+    const names = [...new Set(expandGlob(tree, all).filter(blocked).map((d) => d.slice(d.lastIndexOf("/") + 1)))].sort();
+    if (names.length === 0 || names.some((n) => /[*?[\]{}()!+@|]/.test(n))) return undefined;
+    const glob = `${prefix}/!(${names.join("|")})`;
+    if (!safe(glob)) return undefined;
+    const reached = new Set(expandGlob(tree, glob));
+    return matches.every((m) => !parents.includes(dirOf(m)) || reached.has(m)) ? glob : undefined;
+  };
 
   const globs: string[] = [];
   const left = new Set(wide);
@@ -358,11 +378,17 @@ function exampleGlobs(tree: WorkspaceTree, matches: string[], memberDirs: string
   }
   for (const [pattern, parents] of [...candidates].sort((a, b) => b[1].length - a[1].length)) {
     const open = parents.filter((p) => left.has(p));
-    if (open.length < 2 || !safe(`${pattern}/*`)) continue;
-    globs.push(`${pattern}/*`);
+    if (open.length < 2) continue;
+    const glob = lastSegment(pattern, open);
+    if (glob === undefined) continue;
+    globs.push(glob);
     for (const p of open) left.delete(p);
   }
-  for (const p of left) globs.push(`${p}/*`);
+  for (const p of left) {
+    const glob = lastSegment(p, [p]);
+    if (glob !== undefined) globs.push(glob);
+    else explicit.push(...(byParent.get(p) ?? []));
+  }
   // Explicit matches a glob already covers need no entry of their own.
   const covered = new Set(globs.flatMap((g) => expandGlob(tree, g)));
   for (const m of explicit) if (!covered.has(m)) globs.push(m);
@@ -422,7 +448,14 @@ export function proposeWorkspace(root: string, options: { name?: string } = {}):
   const declDirs = dirsWith((n) => (DECLARATION_FILES as readonly string[]).includes(n));
   const pkgDirs = dirsWith((n) => n === "package.json");
 
-  const nested = outermost([...declDirs].filter((d) => d !== ""));
+  // A declaration under an examples-style directory is a `workspace` member
+  // too (#4499, ruled), with a note saying where it sits. Plain projects
+  // there stay examples. Only the root member contains other members, so one
+  // that sits inside another package or project (a lexicon shipping a whole
+  // workspace as an example, chant#4468) stays an example of its group.
+  const insideAnother = (d: string): boolean =>
+    [...pkgDirs, ...configDirs, ...declDirs].some((o) => o !== "" && o !== d && isInside(d, o));
+  const nested = outermost([...declDirs].filter((d) => d !== "" && !(exampleMatch(d) && insideAnother(d))));
   const notNested = (d: string) => !nested.some((n) => isInside(d, n));
 
   const projects = outermost([...configDirs].filter((d) => d !== "" && notNested(d)));
@@ -476,7 +509,16 @@ export function proposeWorkspace(root: string, options: { name?: string } = {}):
   const taken = new Set<string>([name]);
   const entries: (ProposedEntry & { sort: string })[] = [];
   if (configDirs.has("")) entries.push({ sort: "", name: uniqueName(memberName(tree, "", name), taken), dir: ".", kind: "chant" });
-  for (const d of nested) entries.push({ sort: d, name: uniqueName(memberName(tree, d, name), taken), dir: d, kind: "workspace" });
+  for (const d of nested) {
+    const ex = exampleMatch(d);
+    entries.push({
+      sort: d,
+      name: uniqueName(memberName(tree, d, name), taken),
+      dir: d,
+      kind: "workspace",
+      ...(ex ? { because: `a workspace of its own under ${ex.parent}, an examples directory; a workspace is a member, never an example` } : {}),
+    });
+  }
   for (const d of chantMembers) entries.push({ sort: d, name: uniqueName(memberName(tree, d, name), taken), dir: d, kind: "chant" });
   for (const d of packages) {
     entries.push({

package/src/workspace/intent-gaps.test.ts

@@ -14,6 +14,10 @@
  *   intent-decision-contested on the server, which still fires), W-004
  *   (done, from intent-pin-drifted on the spec, which does not fire) and
  *   W-005 (open, implements dec-002 and dec-003, no gap source).
+ *
+ * Kept fast (#4502): a walk reads the repository through git, so the tests
+ * that only read a region share one walk of it. The one test that edits the
+ * working tree walks afresh.
  */
 
 import { readFileSync } from "node:fs";
@@ -106,13 +110,25 @@ const intent = contract(intentSchema);
 const records = contract(recordsSchema);
 type Result = Exclude<IntentDocument, { error: unknown }>;
 
-async function walk(region: string): Promise<Result> {
+async function freshWalk(region: string): Promise<Result> {
   const { doc } = await intentGraph({ cwd: root, region, kinds: ["decisions/decision.kind.mjs", "work/work.kind.mjs"].map((k) => join(root, k)) });
   intent.expectValid(doc);
   if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
   return doc;
 }
 
+const walks = new Map<string, Promise<Result>>();
+
+/** The walk of `region` over the committed fixture, made once and shared by the tests that only read it. */
+function walk(region: string): Promise<Result> {
+  let w = walks.get(region);
+  if (!w) {
+    w = freshWalk(region);
+    walks.set(region, w);
+  }
+  return w;
+}
+
 const findingsOf = (doc: Result, code: string) => doc.nodes.filter((n): n is FindingNode => n.kind === "finding" && n.code === code);
 
 describe("intent-pin-stale (#2686)", () => {
@@ -166,7 +182,7 @@ describe("intent-decision-contested (#2686)", () => {
   test("a decision whose dissents are all addressed or withdrawn is not contested", async () => {
     writeFiles(root, { "decisions/dec-003-server.md": DEC_003.replace(`"note": "The port is wrong.",`, `"note": "The port is wrong.", "addressed_by": "acme/studio#8",`) });
     try {
-      const doc = await walk("app/server.mjs");
+      const doc = await freshWalk("app/server.mjs");
       expect(findingsOf(doc, "intent-decision-contested")).toEqual([]);
     } finally {
       writeFiles(root, { "decisions/dec-003-server.md": DEC_003 });

package/src/workspace/ledger.schema.json

@@ -102,7 +102,7 @@
     },
     "row": {
       "type": "object",
-      "description": "One row, keyed by column. Every row starts with member: the workspace member whose ledger it came from, or null outside a workspace. A value is a string, a number, a boolean, an object or array (a JSON column), or null.",
+      "description": "One row, keyed by column. Every row starts with member: the workspace member whose ledger it came from, or null outside a workspace. A value is a string, a number, a boolean, an object or array (a JSON column), or null. A runs row's root_member, added within version 1 by #4500, written by chant 0.124.54 and newer, is the member whose directory holds the terraform root a TerraformApplyOp run applied, or null when that is unknown (another kind of run, or a run whose Init step failed before it resolved the root, #4508; a failed terraform init still names it, #4512); a row from an older chant lacks it. A resources row's marker_stack, marker_env, engine_ownership and engine_owned_by, added within version 1 by #4534, written by chant 0.124.54 and newer, are the stack and env the resource's chant marker names and an ownership engine's verdict and what bound the node (never read for a decision), or null when unknown; a row from an older chant lacks them.",
       "required": [
         "member"
       ],

package/src/workspace/nested-graph.ts

@@ -143,6 +143,7 @@ export function foldNested(graph: WorkspaceGraph, member: ComposedMember, inner:
     };
     if (node.compositeInstance) n.compositeInstance = prefixed(outer, node.compositeInstance);
     if (node.runtimeOwner) n.runtimeOwner = prefixed(outer, node.runtimeOwner);
+    if (node.instanceOf) n.instanceOf = prefixed(outer, node.instanceOf);
     if (node.compositeParent) n.compositeParent = node.compositeParent;
     // sourceLoc is relative to the member's directory: the outer member's is the nested root.
     const dir = dirs.get(node.member);

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

@@ -153,6 +153,16 @@
           },
           "status": { "enum": ["applied", "failed", "waiting", "plan-failed"] },
           "message": { "type": "string", "description": "With waiting: why an approval that stands does not count under --require-review." },
+          "covered": {
+            "type": "object",
+            "required": ["digest", "filledInputs"],
+            "description": "Added within contract version 1 by #4419. The first approval covered this round's plan, so no gate of its own was decided and approval is the first one. The plan touched only components and logical ids the first plan previewed, with the same actions, and only inputs the first plan marked unknown differed.",
+            "properties": {
+              "digest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The digest of the first approval, which the coverage is bound to: the report's digest." },
+              "filledInputs": { "type": "array", "items": { "type": "string" }, "description": "The inputs the first plan marked unknown that this plan had a value for, as <component>.<output>, sorted." }
+            }
+          },
+          "notCovered": { "type": "string", "description": "Added within contract version 1 by #4419. Why an approval that stands for the first plan did not cover this round, so the round asked for its own." },
           "changeSet": { "type": "object", "description": "The change-set document the round planned. Its digest equals digest." }
         }
       }
@@ -188,7 +198,7 @@
           "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", "waiting"], "description": "waiting (#3999): held back because its plan read an upstream output that applied as another value, or was known only after apply; it waits on an approval of its plan in rounds." },
+          "status": { "enum": ["planned", "plan-failed", "applied", "failed", "blocked", "waiting", "not-started"], "description": "waiting (#3999): held back because its plan read an upstream output that applied as another value, or was known only after apply; it waits on an approval of its plan in rounds. not-started (ws-107, #4440, written by chant 0.124.54 and newer): a member of a group whose apply stopped before its part began." },
           "counts": {
             "type": "object",
             "required": ["create", "update", "replace", "delete"],
@@ -208,15 +218,78 @@
           "unknownInputs": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "#3999: the upstream outputs its plan read that the change's plans could not say, as <component>.<output>, sorted. Known only after that upstream applies; the approval does not cover what this member does with them."
+            "description": "#3999: the upstream outputs its plan read that the change's plans could not say, as <component>.<output>, sorted. Known only after that upstream applies. The first approval covers the round that plans the member again when that plan does only what the preview showed, with only these inputs filled in; anything else waits for an approval of its own."
           },
           "buildInputs": {
             "type": "array",
             "items": { "type": "string" },
             "description": "#3999: the published artifact identities its plan read from a build in the same change, as <component>.publish.<field>, sorted. Known only after the build runs and never approved again: the build's provenance binds them, so the member applies without a later round."
           },
+          "reads": {
+            "type": "array",
+            "description": "Added within contract version 1, written by chant 0.124.52 and newer. Every other component's output its steps read, one entry per upstream: the output names, sorted, and under unknown the ones its plan had no value for. A read whose value the plan knew is listed too. Absent when it reads none.",
+            "items": {
+              "type": "object",
+              "required": ["upstream", "outputs"],
+              "additionalProperties": false,
+              "properties": {
+                "upstream": { "type": "string", "description": "The component (or stack) whose outputs it reads." },
+                "outputs": { "type": "array", "items": { "type": "string" }, "description": "The output names it reads, sorted. publish.<field> for a published artifact." },
+                "unknown": { "type": "array", "items": { "type": "string" }, "description": "The ones its plan had no value for, sorted: known only after the upstream applies. Absent when every one was known." }
+              }
+            }
+          },
           "round": { "type": "integer", "minimum": 2, "description": "Apply stage (#3999): the round whose plan it applied or waits on, when not the first. planDigest and counts are that round's." },
-          "held": { "type": "string", "description": "Apply stage (#3999): why the first round's plan did not apply." }
+          "held": { "type": "string", "description": "Apply stage (#3999): why the first round's plan did not apply." },
+          "group": { "type": "integer", "minimum": 0, "description": "Added within contract version 1 by #4446, written by chant 0.124.54 and newer. The index in groups of the group the member planned and applied with. Absent when it is in no group." },
+          "groupOutcome": {
+            "enum": ["applied", "partial", "failed", "not-started", "no-changes"],
+            "description": "Added within contract version 1 by #4446, written by chant 0.124.54 and newer. Apply stage: how the member's part of its group's apply ended, as the capability said. applied and no-changes give status applied, and what applied stays applied; partial and failed give status failed; not-started gives status not-started. pr-apply --resume plans partial, failed and not-started members again. Absent when the group did not run."
+          }
+        }
+      }
+    },
+    "groups": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4446, written by chant 0.124.54 and newer. The groups of components one capability planned and applied as one (ws-107), in plan order of their first member. On a resumed apply, what is left of each approved group, grouped again. Absent when none formed.",
+      "items": {
+        "type": "object",
+        "required": ["capability", "components", "wave", "digest"],
+        "additionalProperties": false,
+        "properties": {
+          "capability": { "type": "string", "description": "The kind of the capability every member's one step names, such as terraform-apply." },
+          "components": { "type": "array", "minItems": 2, "items": { "type": "string" }, "description": "The members, by component, in apply order: upstreams first." },
+          "wave": { "type": "integer", "minimum": 1, "description": "The 1-based wave of selection.waves the group ran in." },
+          "digest": { "type": ["string", "null"], "description": "The group digest folded into each member's planDigest. null when the group failed to plan." },
+          "error": { "type": "string", "description": "Why the group failed to plan. Every member is then plan-failed." },
+          "reads": {
+            "type": "array",
+            "description": "Each read of another member that its plan did not know, which the group's apply computes, sorted by component then ref. Absent when none.",
+            "items": {
+              "type": "object",
+              "required": ["component", "ref"],
+              "additionalProperties": false,
+              "properties": {
+                "component": { "type": "string", "description": "The member that reads." },
+                "ref": { "type": "string", "description": "What it reads, as <component>.<output>." }
+              }
+            }
+          }
+        }
+      }
+    },
+    "fallbacks": {
+      "type": "array",
+      "description": "Added within contract version 1 by #4446, written by chant 0.124.54 and newer. Each component in the change whose capability declares planGroup and runGroup, that a read joins to another such component of its kind, and that ended in no group, sorted by component. Absent when none.",
+      "items": {
+        "type": "object",
+        "required": ["component", "capability", "kind", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "component": { "type": "string" },
+          "capability": { "type": "string", "description": "The kind of the capability its step names." },
+          "kind": { "type": "string", "description": "Why, as a kind: core's steps (its deploy has more than one step), split (a component outside the group lies on a dependency path between it and the rest), alone (the capability dropped the other members of its group and a group of one is no group), cycle (placing the group would order two groups each before the other) or error (the capability's groupFallback threw), or the capability's own, for the whole group or for each member it drops. off: the capability's setting turns grouping off; the note does not print it." },
+          "reason": { "type": "string", "description": "The reason as printed." }
         }
       }
     },