cloudfall 0.4.0__tar.gz → 0.5.1__tar.gz

{cloudfall-0.4.0 → cloudfall-0.5.1}/CHANGELOG.md

@@ -6,6 +6,29 @@ Notable changes to Cloudfall. The format follows
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-09-22
+
+### Changed
+
+- Decision records default to `decisions/` beside the operations rather
+  than to `tmp/decisions`: the record is what a team keeps, and `tmp/` is
+  what they throw away. The diffs and logs beside each record are raw
+  Ansible output, so a repository that commits them wants `no_log` on the
+  tasks that handle secrets
+
+### Fixed
+
+- A decision is `verified` only when its verify run changed nothing. A
+  verify step that exits zero while changing a host found the fleet not as
+  the run left it and converged it further, which verifies nothing, so it
+  is recorded `failed`. Every approved decision now carries a `verdict`
+  saying why it ended where it did
+- A record cites its artifacts and its observation basis as the repository
+  sees them rather than by absolute path, because a record is committed
+  and one machine's home directory means nothing in anyone else's checkout
+
+## [0.5.0] — 2026-09-21
+
 ## [0.4.0] — 2026-09-21
 
 ### Added
@@ -31,6 +54,22 @@ Notable changes to Cloudfall. The format follows
 - `StateValidator.validate_documents` validates resource documents
   assembled in memory, with the schemas, reference checks and error codes
   documents on disk get
+- The operations catalog: every playbook the team runs is declared in
+  `operations/` with a risk level, a target scope, typed inputs,
+  preconditions and a verify step, and `cloudfall operations list|show`
+  reads it. A playbook nobody declared is not an operation
+- The gate and the record: `cloudfall operations propose` runs an
+  operation in check mode and records the operation, targets, inputs, the
+  evidence it was based on and the diff by sha256;
+  `cloudfall operations approve --yes` records the approver, runs it, runs
+  the verify playbook and closes the record as executed, verified or
+  failed; `cloudfall operations decisions` reads the trail without the
+  catalog
+- The agent surface: `cloudfall-mcp --repository` serves a brownfield
+  repository, where the tool list is the catalog. Each declared operation
+  is one tool carrying its risk as MCP annotations, calling it runs check
+  mode and records a proposal, and no tool approves anything: that stays a
+  command a person runs
 
 ## [0.3.0] — 2026-09-20
 

{cloudfall-0.4.0 → cloudfall-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudfall
-Version: 0.4.0
+Version: 0.5.1
 Summary: AI-native control plane for dedicated Debian application fleets
 Project-URL: Homepage, https://cloudfall.dev
 Project-URL: Repository, https://github.com/romamo/cloudfall

cloudfall-0.5.1/config/schemas/v1/operation-decision.schema.json

@@ -0,0 +1,368 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cloudfall.internal/schemas/v1/operation-decision.schema.json",
+  "title": "Cloudfall operation decision",
+  "description": "What an agent proposed, what check mode showed, who let it, and what came of it.",
+  "type": "object",
+  "properties": {
+    "apiVersion": {
+      "$ref": "common.schema.json#/$defs/apiVersion"
+    },
+    "kind": {
+      "const": "OperationDecision"
+    },
+    "metadata": {
+      "$ref": "common.schema.json#/$defs/metadata"
+    },
+    "spec": {
+      "type": "object",
+      "properties": {
+        "proposedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "operation": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "$ref": "common.schema.json#/$defs/resourceId"
+            },
+            "playbook": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "risk": {
+              "enum": [
+                "read",
+                "mutating",
+                "destructive"
+              ]
+            },
+            "verifyPlaybook": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            }
+          },
+          "required": [
+            "id",
+            "playbook",
+            "risk"
+          ],
+          "additionalProperties": false
+        },
+        "targets": {
+          "type": "object",
+          "properties": {
+            "scope": {
+              "enum": [
+                "fleet",
+                "group",
+                "host"
+              ]
+            },
+            "pattern": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 200
+            }
+          },
+          "required": [
+            "scope"
+          ],
+          "additionalProperties": false
+        },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": {
+            "type": [
+              "string",
+              "integer",
+              "boolean"
+            ]
+          }
+        },
+        "gate": {
+          "type": "object",
+          "properties": {
+            "requirement": {
+              "enum": [
+                "runs-freely",
+                "check-then-approve",
+                "human-required"
+              ]
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 300
+            }
+          },
+          "required": [
+            "requirement",
+            "reason"
+          ],
+          "additionalProperties": false
+        },
+        "basis": {
+          "type": "object",
+          "description": "The fleet evidence the proposal was made against.",
+          "properties": {
+            "observations": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "observedAt": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string",
+                "format": "date-time"
+              }
+            }
+          },
+          "required": [
+            "observations",
+            "observedAt"
+          ],
+          "additionalProperties": false
+        },
+        "check": {
+          "type": "object",
+          "description": "What check mode reported before any change was made.",
+          "properties": {
+            "exitCode": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 255
+            },
+            "changed": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 253
+              }
+            },
+            "unchanged": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 253
+              }
+            },
+            "diff": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "sha256": {
+                  "$ref": "common.schema.json#/$defs/sha256"
+                },
+                "bytes": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "path",
+                "sha256",
+                "bytes"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "exitCode",
+            "changed",
+            "unchanged",
+            "diff"
+          ],
+          "additionalProperties": false
+        },
+        "status": {
+          "enum": [
+            "proposed",
+            "approved",
+            "rejected",
+            "executed",
+            "verified",
+            "failed"
+          ]
+        },
+        "approval": {
+          "type": "object",
+          "properties": {
+            "approver": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "approvedAt": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          "required": [
+            "approver",
+            "approvedAt"
+          ],
+          "additionalProperties": false
+        },
+        "execution": {
+          "type": "object",
+          "properties": {
+            "ranAt": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "exitCode": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 255
+            },
+            "changed": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 253
+              }
+            },
+            "unchanged": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 253
+              }
+            },
+            "log": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "sha256": {
+                  "$ref": "common.schema.json#/$defs/sha256"
+                },
+                "bytes": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "path",
+                "sha256",
+                "bytes"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "ranAt",
+            "exitCode",
+            "changed",
+            "unchanged",
+            "log"
+          ],
+          "additionalProperties": false,
+          "description": "What the approved run did."
+        },
+        "verify": {
+          "type": "object",
+          "properties": {
+            "ranAt": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "exitCode": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 255
+            },
+            "changed": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 253
+              }
+            },
+            "unchanged": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 253
+              }
+            },
+            "log": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "sha256": {
+                  "$ref": "common.schema.json#/$defs/sha256"
+                },
+                "bytes": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "path",
+                "sha256",
+                "bytes"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "ranAt",
+            "exitCode",
+            "changed",
+            "unchanged",
+            "log"
+          ],
+          "additionalProperties": false,
+          "description": "What the operation's verify playbook reported afterwards."
+        },
+        "verdict": {
+          "type": "string",
+          "description": "Why the decision ended in its status.",
+          "minLength": 1,
+          "maxLength": 300
+        }
+      },
+      "required": [
+        "proposedAt",
+        "operation",
+        "targets",
+        "inputs",
+        "gate",
+        "basis",
+        "check",
+        "status"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "spec"
+  ],
+  "additionalProperties": false
+}

cloudfall-0.5.1/config/schemas/v1/operation.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cloudfall.internal/schemas/v1/operation.schema.json",
+  "title": "Cloudfall operation",
+  "description": "One playbook the team already runs, declared as an operation an agent may call.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "$ref": "common.schema.json#/$defs/resourceId"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
+    },
+    "playbook": {
+      "$ref": "#/$defs/repositoryPath"
+    },
+    "risk": {
+      "enum": [
+        "read",
+        "mutating",
+        "destructive"
+      ]
+    },
+    "targets": {
+      "enum": [
+        "fleet",
+        "group",
+        "host"
+      ]
+    },
+    "inputs": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]{0,63}$"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/inputType"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "$ref": "#/$defs/inputType"
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "description": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200,
+                "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "preconditions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "health": {
+            "const": "ok"
+          }
+        },
+        "required": [
+          "health"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "verify": {
+      "type": "object",
+      "properties": {
+        "playbook": {
+          "$ref": "#/$defs/repositoryPath"
+        }
+      },
+      "required": [
+        "playbook"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "id",
+    "playbook",
+    "risk",
+    "targets"
+  ],
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "risk": {
+            "enum": [
+              "mutating",
+              "destructive"
+            ]
+          }
+        },
+        "required": [
+          "risk"
+        ]
+      },
+      "then": {
+        "required": [
+          "verify"
+        ]
+      }
+    }
+  ],
+  "$defs": {
+    "inputType": {
+      "enum": [
+        "string",
+        "integer",
+        "boolean"
+      ]
+    },
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "pattern": "^[A-Za-z0-9._][A-Za-z0-9._/-]*\\.ya?ml$",
+      "not": {
+        "pattern": "\\.\\."
+      }
+    }
+  }
+}

{cloudfall-0.4.0 → cloudfall-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cloudfall"
-version = "0.4.0"
+version = "0.5.1"
 description = "AI-native control plane for dedicated Debian application fleets"
 readme = "README.md"
 license = "AGPL-3.0-or-later"