worktree-controller 1.30.4__py3-none-any.whl

worktree_controller/retirement_adapters.py

@@ -0,0 +1,130 @@
+"""Compatibility adapters between consumer wire formats and the neutral schema.
+
+Core governance speaks `retirement_execution` only.  These adapters translate the
+released 1.5.0/1.6.0 consumer vocabulary so existing integrations keep working
+while nothing in the governance path depends on one consumer product.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from . import retirement_execution as execution
+from .models import ControllerError
+
+GIT_FINALIZER_CONTRACT = "git-finalizer-summary/v1"
+
+_SUMMARY_OUTCOMES = {
+    "LOCAL_BRANCH_RETIRED_VERIFIED": (
+        execution.KIND_CAS_DELETE,
+        execution.REF_REMOVED_AT_EXPECTED_OID,
+    ),
+    "REMOTE_BRANCH_RETIRED_VERIFIED": (
+        execution.KIND_CAS_DELETE,
+        execution.REF_REMOVED_AT_EXPECTED_OID,
+    ),
+    "ALREADY_ABSENT_VERIFIED": (execution.KIND_ATTEST_ABSENT, execution.REF_ALREADY_ABSENT),
+}
+
+
+def _ref(operation: str, result: Mapping[str, Any]) -> str | None:
+    branch = result.get("branch")
+    if not isinstance(branch, str) or not branch:
+        return None
+    if operation == "local":
+        return f"refs/heads/{branch}"
+    remote = result.get("remote")
+    return f"refs/remotes/{remote}/{branch}" if isinstance(remote, str) and remote else None
+
+
+def load_summary(path: Path) -> tuple[bytes, dict[str, Any]]:
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise ControllerError("INVALID_FINALIZER_SUMMARY", f"cannot read summary: {exc}") from exc
+    import json
+
+    try:
+        summary = json.loads(raw)
+    except (UnicodeError, json.JSONDecodeError) as exc:
+        raise ControllerError("INVALID_FINALIZER_SUMMARY", f"cannot read summary: {exc}") from exc
+    if not isinstance(summary, dict):
+        raise ControllerError("INVALID_FINALIZER_SUMMARY", "summary must be a JSON object")
+    return raw, summary
+
+
+def from_summary(summary: Mapping[str, Any]) -> dict[str, Any]:
+    """Translate one released consumer summary into a neutral execution result.
+
+    Unrecognised shapes fail with the released error code so 1.5.0/1.6.0 callers
+    keep their existing failure contract.
+    """
+
+    status = summary.get("status")
+    mode = summary.get("mode")
+    result = summary.get("mode_result")
+    if status != "success" or not isinstance(mode, str) or not isinstance(result, Mapping):
+        raise ControllerError(
+            "FINALIZER_RESULT_MISMATCH", "Finalizer summary does not prove this plan"
+        )
+    operation = {"retire_local_branch": "local", "retire_remote_branch": "remote"}.get(mode)
+    if operation is None:
+        raise ControllerError(
+            "FINALIZER_RESULT_MISMATCH", "Finalizer summary does not prove this plan"
+        )
+    reported = result.get("result")
+    if reported not in _SUMMARY_OUTCOMES:
+        raise ControllerError(
+            "FINALIZER_RESULT_MISMATCH", "Finalizer summary does not prove this plan"
+        )
+    kind, outcome = _SUMMARY_OUTCOMES[reported]
+    executor_version = summary.get("finalizer_version")
+    return {
+        "schema_version": execution.RESULT_SCHEMA_VERSION,
+        "contract": execution.RESULT_CONTRACT,
+        "plan_id": result.get("retirement_plan_id"),
+        "operation": operation,
+        "kind": kind,
+        "outcome": outcome,
+        "ref": _ref(operation, result),
+        "expected_oid": result.get("expected_oid"),
+        "integrated_ref": result.get("integrated_ref"),
+        "expected_integrated_oid": result.get("integrated_into_oid"),
+        "performed_at": summary.get("finished_at") or summary.get("started_at"),
+        "executor": {
+            "name": GIT_FINALIZER_CONTRACT,
+            "version": executor_version if isinstance(executor_version, str) else "unknown",
+        },
+        "evidence": {"remote": result.get("remote")},
+    }
+
+
+def arguments(plan: Mapping[str, Any], operation: str, *, repository_root: Path) -> list[str]:
+    """The released consumer invocation for one authorized retirement operation."""
+
+    expected_flag = "--expected-local-oid" if operation == "local" else "--expected-remote-oid"
+    return [
+        "git-finalize",
+        f"--retire-{operation}-branch",
+        str(plan["branch"]),
+        "--remote",
+        str(plan["remote"]),
+        "--integrated-into",
+        str(plan["integrated_into"]),
+        expected_flag,
+        str(plan["expected_oid"]),
+        "--expected-integrated-oid",
+        str(plan["expected_integrated_oid"]),
+        "--retirement-plan-id",
+        str(plan["plan_id"]),
+        "--repo",
+        str(repository_root),
+        "--summary",
+    ]
+
+
+def summary_sha256(raw: bytes) -> str:
+    return hashlib.sha256(raw).hexdigest()

worktree_controller/retirement_execution.py

@@ -0,0 +1,234 @@
+"""Provider-neutral vocabulary for authorized retirement execution.
+
+The Controller owns the decision; a consumer owns the ref mutation.  These are the
+two documents that cross that boundary: an *authorization* the Controller issues
+and a *result* the consumer reports back.  Neither one names a consumer product,
+and neither one is trusted for what it claims about Git state — the Controller
+re-observes that itself.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .models import ControllerError
+
+AUTHORIZATION_SCHEMA_VERSION = 1
+AUTHORIZATION_CONTRACT = "branch-retirement-execution/v1"
+
+RESULT_SCHEMA_VERSION = 1
+RESULT_CONTRACT = "retirement-execution-result/v1"
+
+#: The plan publishes this recipe so a consumer knows what it may be granted to
+#: compare-and-delete without importing any Controller helper.
+RECIPE_SCHEMA_VERSION = 1
+RECIPE_CONTRACT = "retirement-execution-recipe/v1"
+
+KIND_CAS_DELETE = "CAS_DELETE"
+KIND_ATTEST_ABSENT = "ATTEST_ABSENT"
+EXECUTION_KINDS = frozenset({KIND_CAS_DELETE, KIND_ATTEST_ABSENT})
+
+REF_REMOVED_AT_EXPECTED_OID = "REF_REMOVED_AT_EXPECTED_OID"
+REF_ALREADY_ABSENT = "REF_ALREADY_ABSENT"
+REF_STILL_PRESENT = "REF_STILL_PRESENT"
+EXECUTION_FAILED = "EXECUTION_FAILED"
+OUTCOMES = frozenset(
+    {REF_REMOVED_AT_EXPECTED_OID, REF_ALREADY_ABSENT, REF_STILL_PRESENT, EXECUTION_FAILED}
+)
+SUCCESS_OUTCOMES = frozenset({REF_REMOVED_AT_EXPECTED_OID, REF_ALREADY_ABSENT})
+
+#: The authorization identity is content-addressed over exactly these fields, in
+#: this order.  ``token`` is deliberately excluded so the secret capability cannot
+#: change the authorization's own address.
+AUTHORIZATION_IDENTITY_FIELDS = (
+    "schema_version",
+    "contract",
+    "request_id",
+    "plan_id",
+    "operation",
+    "kind",
+    "repository_id",
+    "allocation_id",
+    "branch",
+    "ref",
+    "expected_oid",
+    "integrated_ref",
+    "expected_integrated_oid",
+    "tracking_ref",
+    "observed",
+    "controller_state_digest",
+    "holder_sha256",
+    "issued_at",
+    "expires_at",
+)
+
+#: Every result document carries these; they are the values the Controller can
+#: check against its own plan and against Git afterwards.
+RESULT_FIELDS = frozenset(
+    {
+        "schema_version",
+        "contract",
+        "plan_id",
+        "operation",
+        "kind",
+        "outcome",
+        "ref",
+        "expected_oid",
+        "expected_integrated_oid",
+        "executor",
+    }
+)
+#: Optional because a released consumer summary predates them; when present they are
+#: validated, and the Controller never infers a missing one.
+RESULT_OPTIONAL_FIELDS = frozenset({"integrated_ref", "performed_at", "evidence"})
+
+RECIPE_FIELDS = frozenset(
+    {"contract", "schema_version", "grant", "settle", "result_contract", "operations"}
+)
+RECIPE_OPERATION_FIELDS = frozenset(
+    {
+        "ref",
+        "mutation",
+        "expected_oid",
+        "integrated_ref",
+        "expected_integrated_oid",
+        "tracking_ref",
+        "kind",
+    }
+)
+
+OBSERVATION_FIELDS = frozenset(
+    {"refs", "checked_out_paths", "upstream_ref", "upstream_target", "classification", "blockers"}
+)
+
+_HEX = frozenset("0123456789abcdef")
+
+
+def identity(document: Mapping[str, Any]) -> dict[str, Any]:
+    """The authorization fields that must match at settle time."""
+
+    return {field: document.get(field) for field in AUTHORIZATION_IDENTITY_FIELDS}
+
+
+def _text(value: object, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ControllerError("INVALID_EXECUTION_RESULT", f"{field} must be a non-empty string")
+    return value
+
+
+def _object_id(value: object, field: str) -> str:
+    """Accept either Git object ID length; the repository decides which one it uses."""
+
+    text = _text(value, field)
+    if len(text) not in {40, 64} or not _HEX.issuperset(text):
+        raise ControllerError("INVALID_EXECUTION_RESULT", f"{field} must be a Git object id")
+    return text
+
+
+def _digest(value: object, field: str) -> str:
+    text = _text(value, field)
+    if len(text) != 64 or not _HEX.issuperset(text):
+        raise ControllerError("INVALID_EXECUTION_RESULT", f"{field} must be a sha256 hex digest")
+    return text
+
+
+def normalize_result(document: Mapping[str, Any]) -> dict[str, Any]:
+    """Validate one execution result document and return it with checked types.
+
+    A well-formed document proves nothing about the world: the caller must still
+    observe the ref.  This only guarantees every field the observation is compared
+    against is present and shaped.
+    """
+
+    unknown = sorted(set(document) - RESULT_FIELDS - RESULT_OPTIONAL_FIELDS)
+    if unknown:
+        raise ControllerError("INVALID_EXECUTION_RESULT", f"unknown result fields: {unknown}")
+    if not RESULT_FIELDS.issubset(document):
+        raise ControllerError(
+            "INVALID_EXECUTION_RESULT",
+            f"execution result is missing {sorted(RESULT_FIELDS - set(document))}",
+        )
+    if document.get("schema_version") != RESULT_SCHEMA_VERSION:
+        raise ControllerError(
+            "INVALID_EXECUTION_RESULT",
+            f"unsupported result schema {document.get('schema_version')!r}",
+        )
+    if document.get("contract") != RESULT_CONTRACT:
+        raise ControllerError(
+            "INVALID_EXECUTION_RESULT", f"unknown result contract {document.get('contract')!r}"
+        )
+    operation = _text(document.get("operation"), "operation")
+    if operation not in {"local", "remote"}:
+        raise ControllerError("INVALID_EXECUTION_RESULT", "operation must be local or remote")
+    kind = _text(document.get("kind"), "kind")
+    if kind not in EXECUTION_KINDS:
+        raise ControllerError("INVALID_EXECUTION_RESULT", f"unknown execution kind {kind!r}")
+    outcome = _text(document.get("outcome"), "outcome")
+    if outcome not in OUTCOMES:
+        raise ControllerError("INVALID_EXECUTION_RESULT", f"unknown outcome {outcome!r}")
+    executor = document.get("executor")
+    if not isinstance(executor, Mapping):
+        raise ControllerError("INVALID_EXECUTION_RESULT", "executor must be an object")
+    evidence = document.get("evidence")
+    if evidence is not None and not isinstance(evidence, Mapping):
+        raise ControllerError("INVALID_EXECUTION_RESULT", "evidence must be an object or null")
+    return {
+        "schema_version": RESULT_SCHEMA_VERSION,
+        "contract": RESULT_CONTRACT,
+        "plan_id": _digest(document.get("plan_id"), "plan_id"),
+        "operation": operation,
+        "kind": kind,
+        "outcome": outcome,
+        "ref": _text(document.get("ref"), "ref"),
+        "expected_oid": _object_id(document.get("expected_oid"), "expected_oid"),
+        "integrated_ref": (
+            _text(document["integrated_ref"], "integrated_ref")
+            if document.get("integrated_ref") is not None
+            else None
+        ),
+        "expected_integrated_oid": _object_id(
+            document.get("expected_integrated_oid"), "expected_integrated_oid"
+        ),
+        "performed_at": (
+            _text(document["performed_at"], "performed_at")
+            if document.get("performed_at") is not None
+            else None
+        ),
+        "executor": {
+            "name": _text(executor.get("name"), "executor.name"),
+            "version": _text(executor.get("version"), "executor.version"),
+        },
+        "evidence": dict(evidence or {}),
+    }
+
+
+def normalize_observation(value: object) -> dict[str, Any]:
+    """Return an observation vector with a stable shape, or fail closed."""
+
+    if not isinstance(value, Mapping) or not OBSERVATION_FIELDS.issubset(value):
+        raise ControllerError("INVALID_METADATA", "retirement observation vector is incomplete")
+    refs = value.get("refs")
+    if not isinstance(refs, Mapping):
+        raise ControllerError("INVALID_METADATA", "retirement observation refs must be an object")
+    paths = value.get("checked_out_paths")
+    if not isinstance(paths, list) or not all(isinstance(item, str) for item in paths):
+        raise ControllerError("INVALID_METADATA", "retirement observation paths must be a list")
+    blockers = value.get("blockers")
+    if not isinstance(blockers, list) or not all(isinstance(item, str) for item in blockers):
+        raise ControllerError("INVALID_METADATA", "retirement observation blockers must be a list")
+    return {
+        "refs": {
+            key: (oid if oid is None or isinstance(oid, str) else None)
+            for key, oid in sorted(refs.items())
+        },
+        "checked_out_paths": sorted(paths),
+        "upstream_ref": value.get("upstream_ref"),
+        "upstream_target": value.get("upstream_target"),
+        "classification": value.get("classification"),
+        "blockers": sorted(blockers),
+    }
+
+
+def succeeded(result: Mapping[str, Any]) -> bool:
+    return result.get("outcome") in SUCCESS_OUTCOMES