cloudfall 0.5.0__tar.gz → 0.5.1__tar.gz

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

@@ -6,6 +6,27 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudfall
-Version: 0.5.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.0 → cloudfall-0.5.1}/config/schemas/v1/operation-decision.schema.json

@@ -337,6 +337,12 @@
           ],
           "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": [

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

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

{cloudfall-0.5.0 → cloudfall-0.5.1}/sdk/src/cloudfall/decision.py

@@ -42,8 +42,15 @@ type CheckRunner = Callable[[Sequence[str], Mapping[str, str], Path], int]
 API_VERSION = "cloudfall/v1"
 DECISION_KIND = "OperationDecision"
 DECISION_SCHEMA = "operation-decision.schema.json"
-DECISION_DIRECTORY = "tmp/decisions"
-"""Where decision records and their diffs land inside the repository."""
+DECISION_DIRECTORY = "decisions"
+"""Where decision records and their artifacts land inside the repository.
+
+Beside the operations rather than under ``tmp/``: the record is what the
+team keeps, and the runtime directory is what they throw away. Commit the
+records; the diffs and logs beside them are raw Ansible output, so they
+belong in git only in a repository whose tasks set ``no_log`` where it
+matters.
+"""
 
 _TREE_DIRECTORY = "tree"
 _DIFF_SUFFIX = ".diff"
@@ -248,6 +255,7 @@ class Decision:
     approval: Approval | None = None
     execution: RunRecord | None = None
     verification: RunRecord | None = None
+    verdict: str | None = None
 
     def as_document(self) -> dict[str, object]:
         """Serialize the decision as a schema-valid record document."""
@@ -274,6 +282,8 @@ class Decision:
             spec["execution"] = self.execution.as_dict()
         if self.verification is not None:
             spec["verify"] = self.verification.as_dict()
+        if self.verdict is not None:
+            spec["verdict"] = self.verdict
         return {
             "apiVersion": API_VERSION,
             "kind": DECISION_KIND,
@@ -399,8 +409,8 @@ def propose(
         inputs=declared,
         requirement=requirement,
         reason=reason,
-        basis=read_basis(request.observations),
-        check=_preview(exit_code, tree, diff_path),
+        basis=read_basis(request.observations, request.repository),
+        check=_preview(exit_code, tree, diff_path, request.repository),
         status=DecisionStatus.PROPOSED,
     )
     store.save(decision)
@@ -468,6 +478,7 @@ def approve(
         if decision.verify_playbook is not None and execution.exit_code == 0
         else None
     )
+    status, verdict = _outcome(execution, verification, decision.verify_playbook)
     approved = replace(
         decision,
         approval=Approval(
@@ -475,7 +486,8 @@ def approve(
         ),
         execution=execution,
         verification=verification,
-        status=_outcome(execution, verification, decision.verify_playbook),
+        status=status,
+        verdict=verdict,
     )
     store.update(approved)
     return approved
@@ -485,15 +497,42 @@ def _outcome(
     execution: RunRecord,
     verification: RunRecord | None,
     verify_playbook: Path | None,
-) -> DecisionStatus:
-    """Return the status one run earned: unverified is not the same as done."""
+) -> tuple[DecisionStatus, str]:
+    """Return the status one run earned, and why, for the record.
+
+    Verification is a claim about the fleet's state, so a verify run that
+    changed something did not verify anything: it found the fleet not as
+    the operation left it and converged it further. Exiting zero is not
+    enough.
+    """
     if execution.exit_code != 0:
-        return DecisionStatus.FAILED
+        return (
+            DecisionStatus.FAILED,
+            f"the run exited {execution.exit_code}",
+        )
     if verify_playbook is None:
-        return DecisionStatus.EXECUTED
-    if verification is None or verification.exit_code != 0:
-        return DecisionStatus.FAILED
-    return DecisionStatus.VERIFIED
+        return (
+            DecisionStatus.EXECUTED,
+            "the run succeeded; the operation declares no verify step",
+        )
+    if verification is None:  # pragma: no cover - callers verify after a clean run
+        return (DecisionStatus.FAILED, "the verify step did not run")
+    if verification.exit_code != 0:
+        return (
+            DecisionStatus.FAILED,
+            f"the verify step exited {verification.exit_code}",
+        )
+    if verification.changed:
+        changed = ", ".join(verification.changed)
+        return (
+            DecisionStatus.FAILED,
+            "the verify step changed "
+            f"{changed}, so the fleet was not in the state the run claimed",
+        )
+    return (
+        DecisionStatus.VERIFIED,
+        "the run succeeded and the verify step changed nothing",
+    )
 
 
 def _run_stage(
@@ -513,7 +552,9 @@ def _run_stage(
     argv, environment = run_command(invocation)
     log_path.parent.mkdir(parents=True, exist_ok=True)
     exit_code = stage.runner(argv, environment, log_path)
-    preview = _preview(exit_code, invocation.tree, log_path)
+    preview = _preview(
+        exit_code, invocation.tree, log_path, stage.request.repository
+    )
     return RunRecord(
         ran_at=_timestamp(moment),
         exit_code=exit_code,
@@ -554,7 +595,19 @@ def run_command(
     return tuple(argv), environment
 
 
-def read_basis(observations: Path) -> Basis:
+def repository_relative(path: Path, repository: Path) -> Path:
+    """Return the path as the repository sees it, when it lies inside it.
+
+    Records are committed, so a path that names one machine's home
+    directory is worse than useless to everyone else reading the trail.
+    """
+    try:
+        return path.resolve().relative_to(repository.resolve())
+    except ValueError:
+        return path
+
+
+def read_basis(observations: Path, repository: Path | None = None) -> Basis:
     """Return the observation evidence a proposal cites.
 
     A proposal made against no evidence says so, rather than implying it
@@ -571,10 +624,19 @@ def read_basis(observations: Path) -> Basis:
             spec = document.get("spec")
             if isinstance(spec, dict) and isinstance(spec.get("observedAt"), str):
                 observed_at[path.stem] = str(spec["observedAt"])
-    return Basis(observations=observations, observed_at=observed_at)
+    return Basis(
+        observations=(
+            repository_relative(observations, repository)
+            if repository is not None
+            else observations
+        ),
+        observed_at=observed_at,
+    )
 
 
-def _preview(exit_code: int, tree: Path, diff_path: Path) -> CheckPreview:
+def _preview(
+    exit_code: int, tree: Path, diff_path: Path, repository: Path | None = None
+) -> CheckPreview:
     changed: list[str] = []
     unchanged: list[str] = []
     if tree.is_dir():
@@ -596,7 +658,11 @@ def _preview(exit_code: int, tree: Path, diff_path: Path) -> CheckPreview:
         changed=tuple(changed),
         unchanged=tuple(unchanged),
         diff=DiffArtifact(
-            path=diff_path,
+            path=(
+                repository_relative(diff_path, repository)
+                if repository is not None
+                else diff_path
+            ),
             sha256=hashlib.sha256(content).hexdigest(),
             size=len(content),
         ),
@@ -768,6 +834,7 @@ def _decision_from_document(document: Mapping[str, object]) -> Decision:
             ),
         ),
         status=DecisionStatus(str(spec["status"])),
+        verdict=str(spec["verdict"]) if "verdict" in spec else None,
         execution=_run_from_document(spec.get("execution")),
         verification=_run_from_document(spec.get("verify")),
         approval=(

{cloudfall-0.5.0 → cloudfall-0.5.1}/sdk/tests/test_decision.py

@@ -11,6 +11,7 @@ import pytest
 from cloudfall.catalog import RiskLevel, TargetScope, load_catalog
 from cloudfall.cli import main
 from cloudfall.decision import (
+    DECISION_DIRECTORY,
     ApprovalRequest,
     DecisionError,
     DecisionStatus,
@@ -49,7 +50,7 @@ verify:
 
 def _store(repository: Path) -> DecisionStore:
     return DecisionStore(
-        directory=repository / "tmp" / "decisions",
+        directory=repository / DECISION_DIRECTORY,
         catalog=SchemaCatalog(SCHEMAS),
     )
 
@@ -84,13 +85,21 @@ def _proposal(
 
 
 class _Runner:
-    """A check runner that writes what Ansible would write."""
+    """A runner that writes what Ansible would write, stage by stage.
+
+    An idempotent fleet changes on the run and changes nothing on the
+    verify that follows, so the two stages are modelled separately.
+    """
 
     def __init__(
-        self, exit_code: int = 0, changed: tuple[str, ...] = ("web-1",)
+        self,
+        exit_code: int = 0,
+        changed: tuple[str, ...] = ("web-1",),
+        verify_changed: tuple[str, ...] = (),
     ) -> None:
         self.exit_code = exit_code
         self.changed = changed
+        self.verify_changed = verify_changed
         self.recorded: list[tuple[str, ...]] = []
 
     def __call__(
@@ -99,15 +108,20 @@ class _Runner:
         environment: Mapping[str, str],
         diff_path: Path,
     ) -> int:
-        self.recorded.append(tuple(argv))
         tree = Path(environment["ANSIBLE_CALLBACK_TREE_DIR"])
+        changed = self.verify_changed if self._verifying(tree) else self.changed
+        self.recorded.append(tuple(argv))
         tree.mkdir(parents=True, exist_ok=True)
-        for host in self.changed:
+        for host in changed:
             (tree / host).write_text('{"changed": true}', encoding="utf-8")
         (tree / "web-2").write_text('{"changed": false}', encoding="utf-8")
         diff_path.write_text("--- before\n+++ after\n", encoding="utf-8")
         return self.exit_code
 
+    @staticmethod
+    def _verifying(tree: Path) -> bool:
+        return tree.name.endswith("-verify")
+
 
 def test_the_gate_follows_the_risk_level() -> None:
     """The table is the product's: a human cannot be skipped by policy."""
@@ -131,7 +145,11 @@ def test_a_proposal_records_what_check_mode_would_change(tmp_path: Path) -> None
     assert decision.check.changed == ("web-1",)
     assert decision.check.unchanged == ("web-2",)
     assert decision.check.diff.size == len(b"--- before\n+++ after\n")
-    assert decision.check.diff.path.read_text(encoding="utf-8").startswith("---")
+    # A committed record names paths as the repository sees them.
+    assert not decision.check.diff.path.is_absolute()
+    artifact = repository / decision.check.diff.path
+    assert artifact.read_text(encoding="utf-8").startswith("---")
+    assert not decision.basis.observations.is_absolute()
 
 
 def test_a_proposal_cites_the_evidence_it_was_made_against(
@@ -442,6 +460,10 @@ def test_an_approval_runs_the_recorded_proposal_and_verifies_it(
     assert approved.execution is not None
     assert approved.execution.changed == ("web-1",)
     assert approved.verification is not None
+    assert approved.verification.changed == ()
+    assert approved.verdict == (
+        "the run succeeded and the verify step changed nothing"
+    )
     assert [argv[1] for argv in run.recorded] == ["--diff", "--diff"]
     assert run.recorded[0][-1].endswith("playbooks/deploy.yml")
     assert run.recorded[1][-1].endswith("playbooks/health.yml")
@@ -630,3 +652,66 @@ def test_an_approved_decision_round_trips_through_the_store(
     assert loaded.execution.exit_code == 0
     assert loaded.verification is not None
     assert loaded.status is DecisionStatus.VERIFIED
+
+
+def test_a_verify_step_that_changes_the_fleet_did_not_verify_it(
+    tmp_path: Path,
+) -> None:
+    """Exiting zero is not enough: verification is a claim about state."""
+    repository = _repository(tmp_path)
+    store = _store(repository)
+    proposed = propose(_proposal(repository), store, lambda: MOMENT, _Runner())
+
+    approved = approve(
+        ApprovalRequest(
+            decision=proposed, approver="roman", repository=repository
+        ),
+        store,
+        lambda: MOMENT,
+        _Runner(verify_changed=("web-1",)),
+    )
+
+    assert approved.status is DecisionStatus.FAILED
+    assert approved.verification is not None
+    assert approved.verification.exit_code == 0
+    assert approved.verification.changed == ("web-1",)
+    assert approved.verdict is not None
+    assert "the verify step changed web-1" in approved.verdict
+
+
+def test_every_outcome_says_why_in_the_record(tmp_path: Path) -> None:
+    repository = _repository(tmp_path, deploy=DEPLOY, facts=FACTS)
+    store = _store(repository)
+
+    failed = approve(
+        ApprovalRequest(
+            decision=propose(
+                _proposal(repository), store, lambda: MOMENT, _Runner()
+            ),
+            approver="roman",
+            repository=repository,
+        ),
+        store,
+        lambda: MOMENT,
+        _Runner(exit_code=2),
+    )
+    executed = approve(
+        ApprovalRequest(
+            decision=propose(
+                _proposal(repository, "facts", target=None, inputs={}),
+                store,
+                lambda: MOMENT,
+                _Runner(),
+            ),
+            approver="roman",
+            repository=repository,
+        ),
+        store,
+        lambda: MOMENT,
+        _Runner(),
+    )
+
+    assert failed.verdict == "the run exited 2"
+    assert executed.verdict == (
+        "the run succeeded; the operation declares no verify step"
+    )

{cloudfall-0.5.0 → cloudfall-0.5.1}/uv.lock

@@ -254,7 +254,7 @@ wheels = [
 
 [[package]]
 name = "cloudfall"
-version = "0.5.0"
+version = "0.5.1"
 source = { editable = "." }
 dependencies = [
     { name = "ansible-core" },