@intentius/terragucci 0.4.2 → 0.4.4

package/README.md

@@ -23,6 +23,7 @@ A root is a directory whose Terraform files declare a backend or configure a pro
 |---|---|
 | `terragucci init` | sets one repo up; `--forge` and `--binary` override detection, `--dry-run` writes nothing |
 | `terragucci reconcile --config <file>` | from a control repo, previews every project's pipeline; `--mode apply` opens a pull request in each project that changes |
+| `terragucci generate` | writes each root's backend, provider and version files from the `generate` key; `--check` fails on one that differs |
 | `terragucci plan` | plans this repo's roots in apply order; `--root <glob>` narrows it |
 
 | Exit code | Means |

package/dist/audit.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/audit/v1/audit.schema.json",
+  "title": "terragucci.audit/v1",
+  "description": "One line of audit.jsonl at the top of a reports prefix: an approval, apply, policy override, refused wave or state migration. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "id", "kind", "project", "at", "who", "what", "digest", "result", "evidence"],
+  "properties": {
+    "schema": { "const": "terragucci.audit/v1" },
+    "id": { "type": "string", "description": "sha256: over where the entry came from; the same records give the same id." },
+    "kind": { "enum": ["approval-requested", "approval", "approval-revoked", "override-requested", "override", "override-revoked", "apply", "refused", "migration", "unlock"] },
+    "project": { "type": "string", "description": "<host>/<path> of the repo." },
+    "at": { "type": "string", "description": "When it happened, ISO 8601." },
+    "who": { "type": ["string", "null"], "description": "The approver, the overrider, whoever removed the line, or for an apply the approver it applied under. Null when nobody did." },
+    "what": { "type": "string", "description": "The gate (wave-<k>, or a migration's name) or, for an override, the root." },
+    "digest": { "type": ["string", "null"], "description": "The wave's set digest, or the digest an override binds. Null when a root failed to plan." },
+    "result": { "type": "string" },
+    "evidence": {
+      "type": "object",
+      "required": ["source"],
+      "properties": {
+        "source": { "enum": ["ledger", "report"] },
+        "branch": { "type": "string" },
+        "path": { "type": "string" },
+        "commit": { "type": "string" },
+        "bucket": { "type": "string" },
+        "key": { "type": "string" },
+        "url": { "type": "string" },
+        "job_url": { "type": "string" }
+      }
+    },
+    "detail": { "type": "object", "description": "What else the source says, by kind." }
+  }
+}

package/dist/changes.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/changes/v1/changes.schema.json",
+  "title": "terragucci.changes/v1",
+  "description": "changes.json in a project's directory of a reports prefix: one row per resource each applied tf-apply wave changed, newest first. Actions and attribute names, never a value. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "changes"],
+  "properties": {
+    "schema": { "const": "terragucci.changes/v1" },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["address", "type", "actions", "attributes", "root", "commit", "finished", "path", "plan_digest", "set_digest"],
+        "properties": {
+          "address": { "type": "string" },
+          "type": { "type": "string" },
+          "actions": { "type": "array", "items": { "enum": ["create", "update", "replace", "delete", "import", "move", "forget"] } },
+          "attributes": { "type": "array", "items": { "type": "string" }, "description": "The top-level attributes an update or a replacement changed, by name." },
+          "previous_address": { "type": "string", "description": "Where a moved resource was." },
+          "root": { "type": "string" },
+          "commit": { "type": "string" },
+          "wave": { "type": "integer" },
+          "finished": { "type": "string", "description": "When the wave finished." },
+          "path": { "type": "string", "description": "The wave's run directory, relative to the project's index.json." },
+          "plan_digest": { "type": ["string", "null"], "description": "The root's plan digest: the plan that applied." },
+          "set_digest": { "type": ["string", "null"], "description": "The wave's set digest, which its approval binds." },
+          "pull_request": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/dist/dora.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/dora/v1/dora.schema.json",
+  "title": "terragucci.dora/v1",
+  "description": "dora.json at the top of a reports prefix, beside estate.json: the four DORA metrics per project and for the estate, which terragucci estate builds from audit.jsonl and each project's index.json. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "generated", "weeks", "window", "drift_window_seconds", "audit", "estate", "projects"],
+  "properties": {
+    "schema": { "const": "terragucci.dora/v1" },
+    "generated": { "type": "string", "description": "When the metrics were built, ISO 8601." },
+    "weeks": { "type": "integer", "description": "How many weeks the metrics cover, the current one included." },
+    "window": {
+      "type": "object",
+      "required": ["from", "to"],
+      "properties": {
+        "from": { "type": "string", "description": "The Monday, 00:00 UTC, the window starts on." },
+        "to": { "type": "string", "description": "When it ends: generated." }
+      }
+    },
+    "drift_window_seconds": { "type": "integer", "description": "An applied wave whose roots drift within this long counts as a failed change." },
+    "audit": { "type": "boolean", "description": "Whether audit.jsonl was read. Without it no apply counts." },
+    "estate": { "$ref": "#/$defs/metrics" },
+    "projects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["project", "deployments", "per_week", "lead_time", "change_failure", "restore", "trend"],
+        "properties": {
+          "project": { "type": "string" },
+          "deployments": { "type": "integer" },
+          "per_week": { "type": "number" },
+          "lead_time": { "$ref": "#/$defs/lead_time" },
+          "change_failure": { "$ref": "#/$defs/change_failure" },
+          "restore": { "$ref": "#/$defs/restore" },
+          "trend": { "$ref": "#/$defs/trend" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "seconds": { "type": ["integer", "null"], "description": "A median in seconds; null when nothing counts." },
+    "metrics": {
+      "type": "object",
+      "required": ["deployments", "per_week", "lead_time", "change_failure", "restore", "trend"],
+      "properties": {
+        "deployments": { "type": "integer", "description": "Applied waves in the window." },
+        "per_week": { "type": "number", "description": "Deployment frequency: applied waves per week over the window." },
+        "lead_time": { "$ref": "#/$defs/lead_time" },
+        "change_failure": { "$ref": "#/$defs/change_failure" },
+        "restore": { "$ref": "#/$defs/restore" },
+        "trend": { "$ref": "#/$defs/trend" }
+      }
+    },
+    "lead_time": {
+      "type": "object",
+      "description": "From a change's first plan to its wave applied.",
+      "required": ["changes", "median_seconds", "before_gate_seconds", "at_gate_seconds", "after_gate_seconds"],
+      "properties": {
+        "changes": { "type": "integer", "description": "Applied waves whose first plan was found." },
+        "median_seconds": { "$ref": "#/$defs/seconds" },
+        "before_gate_seconds": { "$ref": "#/$defs/seconds" },
+        "at_gate_seconds": { "$ref": "#/$defs/seconds" },
+        "after_gate_seconds": { "$ref": "#/$defs/seconds" }
+      }
+    },
+    "change_failure": {
+      "type": "object",
+      "required": ["applies", "failed", "drifted", "rate"],
+      "properties": {
+        "applies": { "type": "integer", "description": "Waves that applied or failed. A refused or waiting wave is not an apply." },
+        "failed": { "type": "integer" },
+        "drifted": { "type": "integer", "description": "Applied waves whose roots drifted within drift_window_seconds." },
+        "rate": { "type": ["number", "null"], "description": "(failed + drifted) / applies; null with no applies." }
+      }
+    },
+    "restore": {
+      "type": "object",
+      "required": ["restored", "open", "median_seconds", "apply_restored", "drift_restored"],
+      "properties": {
+        "restored": { "type": "integer", "description": "Failed applies and drift restored in the window." },
+        "open": { "type": "integer", "description": "Failed roots no apply has restored yet, and drift no check has cleared." },
+        "median_seconds": { "$ref": "#/$defs/seconds" },
+        "apply_restored": { "type": "integer" },
+        "drift_restored": { "type": "integer" }
+      }
+    },
+    "trend": {
+      "type": "array",
+      "description": "One row per week, oldest first.",
+      "items": {
+        "type": "object",
+        "required": ["week", "deployments", "applies", "failures", "lead_time_seconds", "restore_seconds"],
+        "properties": {
+          "week": { "type": "string", "description": "The Monday the week starts on, YYYY-MM-DD." },
+          "deployments": { "type": "integer" },
+          "applies": { "type": "integer" },
+          "failures": { "type": "integer", "description": "Failed applies and applied waves followed by drift." },
+          "lead_time_seconds": { "$ref": "#/$defs/seconds" },
+          "restore_seconds": { "$ref": "#/$defs/seconds" }
+        }
+      }
+    }
+  }
+}

package/dist/estate.schema.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/estate/v1/estate.schema.json",
+  "title": "terragucci.estate/v1",
+  "description": "estate.json at the top of a reports prefix, which terragucci estate builds from every project's index.json, inventory.json and changes.json. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "generated", "totals", "projects", "recent"],
+  "properties": {
+    "schema": { "const": "terragucci.estate/v1" },
+    "generated": { "type": "string", "description": "When the page was built, ISO 8601. Every age on it is as of this time." },
+    "totals": {
+      "type": "object",
+      "required": ["projects", "waiting", "drifted_projects", "drifted_roots", "failed_roots", "unreadable"],
+      "properties": {
+        "projects": { "type": "integer" },
+        "waiting": { "type": "integer", "description": "Waves waiting for an approval." },
+        "drifted_projects": { "type": "integer" },
+        "drifted_roots": { "type": "integer" },
+        "failed_roots": { "type": "integer" },
+        "unreadable": { "type": "integer", "description": "Projects whose index could not be read." },
+        "overridden_roots": { "type": "integer", "description": "Roots the newest apply waves applied under a policy override. Absent when none." },
+        "resources": { "type": "integer", "description": "Resources across every project's inventory. Absent when no project has one." }
+      }
+    },
+    "projects": { "type": "array", "items": { "$ref": "#/$defs/project" } },
+    "recent": { "type": "array", "description": "The 20 newest runs across every project, newest first.", "items": { "$ref": "#/$defs/run" } },
+    "audit": {
+      "type": "object",
+      "description": "The audit trail beside the page, when terragucci audit wrote one.",
+      "required": ["page", "entries", "generated"],
+      "properties": {
+        "page": { "type": "string" },
+        "entries": { "type": "integer" },
+        "generated": { "type": "string" }
+      }
+    },
+    "history": {
+      "type": "object",
+      "description": "The resource history beside the page (history.json and history.html), when an apply changed a resource.",
+      "required": ["page", "resources", "generated"],
+      "properties": {
+        "page": { "type": "string" },
+        "resources": { "type": "integer", "description": "Addresses with at least one apply." },
+        "generated": { "type": "string" }
+      }
+    },
+    "dora": {
+      "type": "object",
+      "description": "The DORA metrics beside the page (dora.json, terragucci.dora/v1).",
+      "required": ["file", "generated", "deployments"],
+      "properties": {
+        "file": { "type": "string" },
+        "generated": { "type": "string" },
+        "deployments": { "type": "integer", "description": "The estate's applied waves in the metrics' window." }
+      }
+    },
+    "graph": {
+      "type": "object",
+      "description": "The dependency graph, from the run view of each project's newest applied commit: every root by wave, and an edge from each root to each root that reads its state through terraform_remote_state. An edge between two projects matched a read of a state outside the reader's project to the root of the other that holds it. Absent when no project has a run view.",
+      "required": ["nodes", "edges"],
+      "properties": {
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["project", "root", "wave"],
+            "properties": {
+              "project": { "type": "string" },
+              "root": { "type": "string" },
+              "wave": { "type": "integer" }
+            }
+          }
+        },
+        "edges": {
+          "type": "array",
+          "description": "Each edge: to reads the state of from.",
+          "items": {
+            "type": "object",
+            "required": ["from", "to"],
+            "properties": {
+              "from": { "$ref": "#/$defs/graphRoot" },
+              "to": { "$ref": "#/$defs/graphRoot" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "graphRoot": {
+      "type": "object",
+      "required": ["project", "root"],
+      "properties": {
+        "project": { "type": "string" },
+        "root": { "type": "string" }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "required": ["create", "update", "replace", "delete"],
+      "properties": {
+        "create": { "type": "integer" },
+        "update": { "type": "integer" },
+        "replace": { "type": "integer" },
+        "delete": { "type": "integer" }
+      }
+    },
+    "run": {
+      "type": "object",
+      "description": "A run, from its index row.",
+      "required": ["project", "commit", "stage", "finished", "roots", "refused", "totals", "destroys"],
+      "properties": {
+        "project": { "type": "string" },
+        "commit": { "type": "string" },
+        "stage": { "enum": ["tf-plan", "tf-apply", "tf-drift"] },
+        "wave": { "type": "integer" },
+        "share": { "type": "integer", "description": "The share of a tf-apply wave split across jobs." },
+        "finished": { "type": "string" },
+        "roots": { "type": "integer" },
+        "changed": { "type": "integer" },
+        "failed": { "type": "integer" },
+        "refused": { "type": "integer" },
+        "totals": { "$ref": "#/$defs/totals" },
+        "destroys": { "type": "integer", "description": "How many destroys and replacements the run has." },
+        "approval": { "enum": ["waiting", "approved", "not-required"] },
+        "waiting_since": { "type": "string" },
+        "applied": { "type": "string" },
+        "overridden": { "type": "integer" },
+        "report": { "type": "string", "description": "The run's report.html, relative to the page or absolute on another bucket's address. Absent when the page cannot link it." },
+        "pull_request": { "type": "string" },
+        "pull_request_url": { "type": "string" },
+        "job_url": { "type": "string" }
+      }
+    },
+    "waiting": {
+      "type": "object",
+      "required": ["project", "wave", "commit", "since", "age_seconds"],
+      "properties": {
+        "project": { "type": "string" },
+        "wave": { "type": "integer" },
+        "commit": { "type": "string" },
+        "since": { "type": "string", "description": "When the wave began waiting for an approval of its digest." },
+        "age_seconds": { "type": "integer", "description": "Seconds it had waited at generated." },
+        "report": { "type": "string" }
+      }
+    },
+    "project": {
+      "type": "object",
+      "required": ["project", "status", "waiting", "drifted", "failed"],
+      "properties": {
+        "project": { "type": "string" },
+        "status": { "enum": ["ok", "no-index", "error"] },
+        "error": { "type": "string", "description": "Why the index could not be read." },
+        "index": { "type": "string", "description": "The project's index.html, when the page can link it." },
+        "plan": { "$ref": "#/$defs/run", "description": "The latest tf-plan." },
+        "drift": { "$ref": "#/$defs/run", "description": "The latest tf-drift." },
+        "apply": {
+          "type": "object",
+          "description": "The waves of the newest commit that ran tf-apply, by wave number.",
+          "required": ["commit", "waves"],
+          "properties": {
+            "commit": { "type": "string" },
+            "waves": { "type": "array", "items": { "$ref": "#/$defs/run" } }
+          }
+        },
+        "waiting": { "type": "array", "items": { "$ref": "#/$defs/waiting" } },
+        "drifted": { "type": "integer", "description": "Roots that drifted in the latest drift check." },
+        "failed": { "type": "integer", "description": "Roots that failed in the latest plan, drift check and apply waves." },
+        "overridden": { "type": "integer", "description": "Roots the newest commit's apply waves applied under a policy override. Absent when none." },
+        "inventory": { "$ref": "#/$defs/inventory", "description": "The resources its roots hold, from its inventory.json. Absent until an apply records them." },
+        "states": { "type": "array", "description": "Each root's state versions, from its states.json. Absent until an apply records them.", "items": { "$ref": "#/$defs/stateRoot" } },
+        "run_view": {
+          "type": "object",
+          "description": "The run view of the project's newest applied commit, which the dependency graph read: its commit, when a wave last wrote it, and its run.html when the page can link it. Absent until a wave writes one.",
+          "required": ["commit", "updated"],
+          "properties": {
+            "commit": { "type": "string" },
+            "updated": { "type": "string" },
+            "page": { "type": "string" }
+          }
+        }
+      }
+    },
+    "stateRoot": {
+      "type": "object",
+      "description": "One root's state: where it is, whether its backend keeps versions, and the version ids its applies left, newest first. Never the state's contents.",
+      "required": ["root", "backend", "versioning", "checked", "versions"],
+      "properties": {
+        "root": { "type": "string" },
+        "backend": { "type": "string" },
+        "location": { "type": "string" },
+        "versioning": { "enum": ["on", "off", "unknown"] },
+        "note": { "type": "string" },
+        "checked": { "type": "string", "description": "When the newest apply that recorded the root finished." },
+        "versions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["version_id", "commit", "finished"],
+            "properties": {
+              "version_id": { "type": "string" },
+              "commit": { "type": "string" },
+              "finished": { "type": "string" },
+              "wave": { "type": "integer" },
+              "report": { "type": "string", "description": "The wave's report.html, when the page can link it." }
+            }
+          }
+        }
+      }
+    },
+    "inventory": {
+      "type": "object",
+      "required": ["resources", "types", "roots"],
+      "properties": {
+        "resources": { "type": "integer" },
+        "types": {
+          "type": "array",
+          "description": "How many resources of each type, most first.",
+          "items": { "type": "object", "required": ["type", "count"], "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } }
+        },
+        "roots": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "description": "One root's resources, as its newest applied wave left them.",
+            "required": ["root", "commit", "finished", "resources"],
+            "properties": {
+              "root": { "type": "string" },
+              "commit": { "type": "string" },
+              "finished": { "type": "string" },
+              "wave": { "type": "integer" },
+              "report": { "type": "string", "description": "The wave's report.html, when the page can link it." },
+              "resources": { "type": "array", "items": { "$ref": "#/$defs/resource" } }
+            }
+          }
+        }
+      }
+    },
+    "resource": {
+      "type": "object",
+      "required": ["address", "type", "provider"],
+      "properties": {
+        "address": { "type": "string" },
+        "type": { "type": "string" },
+        "provider": { "type": "string" },
+        "history": { "type": "string", "description": "Its section of history.html, when an apply changed it." }
+      }
+    }
+  }
+}

package/dist/history.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/history/v1/history.schema.json",
+  "title": "terragucci.history/v1",
+  "description": "history.json at the top of a reports prefix, which terragucci estate builds from every project's changes.json and the audit trail: each resource address with every apply that changed it, oldest first. Actions and attribute names, never a value. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "generated", "audit", "resources"],
+  "properties": {
+    "schema": { "const": "terragucci.history/v1" },
+    "generated": { "type": "string" },
+    "audit": { "type": "boolean", "description": "Whether the audit trail was read for the approvers." },
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "project", "root", "address", "type", "applies"],
+        "properties": {
+          "id": { "type": "string", "description": "Its anchor on history.html." },
+          "project": { "type": "string" },
+          "root": { "type": "string" },
+          "address": { "type": "string" },
+          "type": { "type": "string" },
+          "applies": {
+            "type": "array",
+            "description": "Oldest first.",
+            "items": {
+              "type": "object",
+              "required": ["actions", "attributes", "commit", "finished", "plan_digest", "set_digest"],
+              "properties": {
+                "actions": { "type": "array", "items": { "enum": ["create", "update", "replace", "delete", "import", "move", "forget"] } },
+                "attributes": { "type": "array", "items": { "type": "string" } },
+                "previous_address": { "type": "string" },
+                "commit": { "type": "string" },
+                "wave": { "type": "integer" },
+                "finished": { "type": "string" },
+                "plan_digest": { "type": ["string", "null"] },
+                "set_digest": { "type": ["string", "null"] },
+                "approver": { "type": ["string", "null"], "description": "Who approved the wave, from its apply entry in the audit trail; null when no gate held it. Absent when the audit trail has no entry for the wave." },
+                "approval": { "type": "string", "description": "The id of the approval entry in the audit trail." },
+                "report": { "type": "string" },
+                "pull_request": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/inventory.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/inventory/v1/inventory.schema.json",
+  "title": "terragucci.inventory/v1",
+  "description": "inventory.json in a project's directory of a reports prefix: the resources each root holds, as its newest applied tf-apply wave left them. Addresses, types and providers, never a value. Within v1 fields are only added, and an existing field never changes meaning.",
+  "type": "object",
+  "required": ["schema", "roots"],
+  "properties": {
+    "schema": { "const": "terragucci.inventory/v1" },
+    "roots": {
+      "type": "array",
+      "description": "By root path.",
+      "items": {
+        "type": "object",
+        "required": ["root", "commit", "finished", "path", "resources"],
+        "properties": {
+          "root": { "type": "string" },
+          "commit": { "type": "string" },
+          "finished": { "type": "string", "description": "When the wave that recorded the list finished." },
+          "wave": { "type": "integer" },
+          "path": { "type": "string", "description": "The wave's run directory, relative to the project's index.json." },
+          "resources": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["address", "type", "provider"],
+              "properties": {
+                "address": { "type": "string" },
+                "type": { "type": "string" },
+                "provider": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/notify.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/terragucci/schemas/notify/v1/notify.schema.json",
+  "title": "terragucci.notify/v1",
+  "description": "The event terragucci notify posts to the generic webhook when a tf-apply wave waits, is refused or fails. The schema changes only when a field is removed or changes meaning; new fields can appear without a bump.",
+  "type": "object",
+  "required": ["schema", "id", "event", "sent_at", "project", "wave", "roots"],
+  "properties": {
+    "schema": { "const": "terragucci.notify/v1" },
+    "id": { "type": "string", "description": "sha256 hex over the project, the wave, the event and the set digest (the commit when there is none): the same for every post of one wave's event about one digest." },
+    "event": { "enum": ["waiting", "refused", "failed"] },
+    "sent_at": { "type": "string", "description": "When the job posted it, ISO 8601." },
+    "project": { "type": "string", "description": "<host>/<path> of the repo." },
+    "forge": { "enum": ["github", "gitlab", "forgejo"] },
+    "repo": { "type": "string", "description": "owner/name on GitHub and Forgejo, the project path on GitLab." },
+    "sha": { "type": "string", "description": "The commit the wave applied." },
+    "pr": { "type": "integer", "description": "The pull or merge request the job applied, when a comment started it." },
+    "wave": { "type": "integer" },
+    "roots": { "type": "array", "items": { "type": "string" }, "description": "The wave's roots; for a refused or denied wave, the roots that moved or were denied; for a failed one, the roots that failed." },
+    "run_url": { "type": "string" },
+    "report_url": { "type": "string" },
+    "outcome": { "$ref": "#/$defs/outcome" }
+  },
+  "$defs": {
+    "outcome": {
+      "type": "object",
+      "description": "terragucci.outcome/v1, as stage tf-apply wrote it to TG_OUTCOME_JSON.",
+      "required": ["schema", "status", "exit", "wave", "roots"],
+      "properties": {
+        "schema": { "const": "terragucci.outcome/v1" },
+        "status": { "enum": ["applied", "waiting", "refused", "failed"] },
+        "exit": { "type": "integer" },
+        "wave": { "type": "integer" },
+        "roots": { "type": "array", "items": { "type": "string" } },
+        "line": { "type": "string" },
+        "set_digest": { "type": "string" },
+        "gate": {
+          "type": "object",
+          "required": ["name", "branch", "path"],
+          "properties": { "name": { "type": "string" }, "branch": { "type": "string" }, "path": { "type": "string" } }
+        },
+        "approval": { "enum": ["not-requested", "waiting", "approved", "not-required"] },
+        "approval_mode": { "enum": ["ledger", "pr-review", "sealed"] },
+        "approve_command": { "type": "string" },
+        "waiting_since": { "type": "string" },
+        "review": {
+          "type": "object",
+          "required": ["pull_request", "url"],
+          "properties": { "pull_request": { "type": "integer" }, "url": { "type": "string" } }
+        },
+        "refused": {
+          "type": "object",
+          "required": ["reason", "roots"],
+          "properties": {
+            "reason": { "enum": ["approval", "review", "override", "policy"] },
+            "approved": { "type": "string" },
+            "by": { "type": "string" },
+            "roots": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "policy_denied": { "type": "array", "items": { "type": "string" } },
+        "failed_roots": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}