agentflow-proof 1.0.0__py3-none-any.whl

agentflow/artifacts.py

@@ -0,0 +1,331 @@
+"""Artifact defaults and filesystem helpers for Agentflow."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from .contracts import (
+    ARTIFACT_COMPATIBILITY_POLICIES,
+    ARTIFACT_PATHS,
+    ARTIFACT_SCHEMA_VERSIONS,
+    ASSUMPTIONS_SCHEMA_VERSION,
+    CONTEXT_RECEIPTS_SCHEMA_VERSION,
+    DRIFT_REPORT_SCHEMA_VERSION,
+    EVIDENCE_SCHEMA_VERSION,
+    FAILURES_SCHEMA_VERSION,
+    PLAN_SCHEMA_VERSION,
+    PROOF_PACK_SCHEMA_VERSION,
+    EXECUTION_ARTIFACT_SCHEMA_VERSIONS,
+)
+from .versioning import validate_schema_version_policy
+
+
+SCHEMA_VERSION = PLAN_SCHEMA_VERSION
+_VALIDATE_ARTIFACT_VERSIONS = ContextVar(
+    "agentflow_validate_artifact_versions", default=True
+)
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def dumps_json(data: Dict[str, Any]) -> str:
+    return json.dumps(data, indent=2, sort_keys=True) + "\n"
+
+
+# lock-plan restamps locked/locked_at on every re-lock, so a raw file hash
+# would invalidate plan-bound evidence even when nothing semantic changed.
+_PLAN_LOCK_METADATA_FIELDS = ("locked", "locked_at")
+
+
+def plan_binding_sha256(plan: Dict[str, Any]) -> str:
+    """Canonical content hash used to bind evidence to a plan.
+
+    Excludes lock bookkeeping so a no-op re-lock keeps existing bindings;
+    any semantic plan change still invalidates them.
+    """
+    content = {
+        key: value
+        for key, value in plan.items()
+        if key not in _PLAN_LOCK_METADATA_FIELDS
+    }
+    payload = json.dumps(content, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def default_plan() -> Dict[str, Any]:
+    return {
+        "schema_version": PLAN_SCHEMA_VERSION,
+        "objective": "",
+        "scope": [],
+        "non_goals": [],
+        "invariants": [],
+        "allowed_files": [],
+        "blocked_files": [],
+        "validation_gates": [],
+        "rollback_plan": "",
+        "risk_level": "low",
+        "drift_budget": {
+            "unrelated_edits": 0,
+            "new_dependencies": 0,
+            "formatting_drift": "minimal",
+            "architecture_drift": "requires_approval",
+            "test_weakening": 0,
+        },
+        "steps": [],
+        "evidence_ids": [],
+        "locked": False,
+        "locked_at": None,
+    }
+
+
+def default_assumptions() -> Dict[str, Any]:
+    return {
+        "schema_version": ASSUMPTIONS_SCHEMA_VERSION,
+        "assumptions": [],
+    }
+
+
+def default_drift_report() -> Dict[str, Any]:
+    return {
+        "schema_version": DRIFT_REPORT_SCHEMA_VERSION,
+        "status": "warning",
+        "changed_files": [],
+        "unmapped_hunks": [],
+        "out_of_scope_files": [],
+        "blocked_files_changed": [],
+        "dependency_changes": [],
+        "test_weakening": [],
+        "notes": ["No drift audit has been run yet."],
+        "generated_at": utc_now(),
+    }
+
+
+def default_proof_pack() -> str:
+    return """# Proof Pack
+
+## Objective
+
+TBD.
+
+## Scope
+
+TBD.
+
+## Plan Steps Completed
+
+TBD.
+
+## Files Changed
+
+TBD.
+
+## Evidence
+
+TBD.
+
+## Validation
+
+TBD.
+
+## Drift Audit
+
+TBD.
+
+## Remaining Risk
+
+TBD.
+
+## Follow-Ups
+
+TBD.
+"""
+
+
+def model_profile(provider: str, name: str, cost_tier: str) -> Dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "name": name,
+        "provider": provider,
+        "context_window": 0,
+        "supports_tool_calls": False,
+        "supports_json_schema": False,
+        "supports_vision": False,
+        "cost_tier": cost_tier,
+        "strengths": [],
+    }
+
+
+def initial_files() -> List[Tuple[str, str]]:
+    return [
+        (".agent/plan.lock.json", dumps_json(default_plan())),
+        (".agent/evidence.jsonl", ""),
+        (".agent/assumptions.json", dumps_json(default_assumptions())),
+        (".agent/context-receipts.jsonl", ""),
+        (".agent/failures.jsonl", ""),
+        (".agent/amendments.jsonl", ""),
+        (".agent/review-runs.jsonl", ""),
+        (".agent/capability-receipts.jsonl", ""),
+        (".agent/runtime-snapshots.jsonl", ""),
+        (".agent/drift-report.json", dumps_json(default_drift_report())),
+        (".agent/proof-pack.md", default_proof_pack()),
+        (
+            ".agent/model-profiles/openai.example.json",
+            dumps_json(model_profile("openai", "model-id", "medium")),
+        ),
+        (
+            ".agent/model-profiles/anthropic.example.json",
+            dumps_json(model_profile("anthropic", "model-id", "medium")),
+        ),
+        (
+            ".agent/model-profiles/local.example.json",
+            dumps_json(model_profile("local", "model-id", "low")),
+        ),
+    ]
+
+
+def _artifact_name(path: Path) -> Optional[str]:
+    candidate = path.as_posix()
+    paths = {**ARTIFACT_PATHS, "proof-pack": ".agent/proof-pack.json"}
+    return next(
+        (
+            name
+            for name, relative in paths.items()
+            if candidate == relative or candidate.endswith("/" + relative)
+        ),
+        None,
+    )
+
+
+def _validate_artifact_version(
+    path: Path, data: Any, line_number: Optional[int] = None
+) -> None:
+    if not _VALIDATE_ARTIFACT_VERSIONS.get():
+        return
+    artifact = _artifact_name(path)
+    reader_gated = set(ARTIFACT_COMPATIBILITY_POLICIES) - {
+        "aggregation",
+        "proof-pack",
+    }
+    if (
+        artifact not in reader_gated
+        or not isinstance(data, dict)
+    ):
+        return
+    supported = EXECUTION_ARTIFACT_SCHEMA_VERSIONS.get(
+        artifact, ARTIFACT_SCHEMA_VERSIONS.get(artifact)
+    )
+    if supported is None:
+        return
+    errors = validate_schema_version_policy(
+        data.get("schema_version"),
+        supported,
+        artifact,
+        ARTIFACT_COMPATIBILITY_POLICIES[artifact],
+    )
+    if errors:
+        location = f"{path}:{line_number}" if line_number is not None else str(path)
+        raise ValueError(f"{location}: {errors[0]}")
+
+
+@contextmanager
+def historical_proof_reads() -> Iterable[None]:
+    """Let verify-proof read its hash-bound historical source artifacts."""
+    token = _VALIDATE_ARTIFACT_VERSIONS.set(False)
+    try:
+        yield
+    finally:
+        _VALIDATE_ARTIFACT_VERSIONS.reset(token)
+
+
+def read_json(path: Path) -> Dict[str, Any]:
+    with path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    _validate_artifact_version(path, data)
+    return data
+
+
+def try_read_json(path: Path) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """Read a JSON object without raising for malformed or non-object JSON."""
+    try:
+        data = read_json(path)
+    except json.JSONDecodeError as exc:
+        return None, f"malformed JSON in {path.name}: {exc}"
+    except ValueError as exc:
+        # Version-gate rejection: the file is well-formed JSON, so calling it
+        # malformed would send users chasing a parse error that does not exist.
+        return None, str(exc)
+    if not isinstance(data, dict):
+        return None, f"{path.name} top-level value must be a JSON object"
+    return data, None
+
+
+def write_json(path: Path, data: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dumps_json(data), encoding="utf-8")
+
+
+def append_jsonl(path: Path, item: Dict[str, Any]) -> None:
+    artifact = _artifact_name(path)
+    supported = (
+        EXECUTION_ARTIFACT_SCHEMA_VERSIONS.get(
+            artifact, ARTIFACT_SCHEMA_VERSIONS.get(artifact)
+        )
+        if artifact is not None
+        else None
+    )
+    if supported is not None and "schema_version" not in item:
+        item = {"schema_version": supported, **item}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(item, sort_keys=True) + "\n")
+
+
+def read_jsonl(path: Path) -> List[Dict[str, Any]]:
+    if not path.exists():
+        return []
+
+    items: List[Dict[str, Any]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line_number, line in enumerate(handle, start=1):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                item = json.loads(stripped)
+                _validate_artifact_version(path, item, line_number)
+                items.append(item)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"{path}:{line_number}: invalid JSONL: {exc}") from exc
+    return items
+
+
+def create_initial_artifacts(root: Path, force: bool = False) -> Tuple[List[str], List[str]]:
+    created: List[str] = []
+    skipped: List[str] = []
+
+    for relative_path, content in initial_files():
+        path = root / relative_path
+        if path.exists() and not force:
+            skipped.append(relative_path)
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        created.append(relative_path)
+
+    return created, skipped
+
+
+def require_files(paths: Iterable[Path]) -> List[str]:
+    missing = []
+    for path in paths:
+        if not path.exists():
+            missing.append(str(path))
+    return missing

agentflow/capabilities.py

@@ -0,0 +1,124 @@
+"""Capability receipts: record and summarize specialized-practice usage.
+
+Agentflow declares required capabilities (via the workflow contract) and records
+evidence that they were used or knowingly waived. It never invokes a provider;
+``provider`` is a free string.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .artifacts import append_jsonl, read_jsonl, utc_now
+from .contracts import CAPABILITY_RECEIPTS_SCHEMA_VERSION, CAPABILITY_STATUSES
+
+CAPABILITY_RECEIPTS_PATH = ".agent/capability-receipts.jsonl"
+
+KNOWN_FIELDS = {
+    "schema_version",
+    "id",
+    "capability",
+    "status",
+    "provider",
+    "reason",
+    "evidence",
+    "recorded_at",
+}
+
+
+def _non_empty_string(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def validate_capability_receipt(row: Any) -> List[str]:
+    errors: List[str] = []
+    if not isinstance(row, dict):
+        return ["capability receipt must be a JSON object"]
+    for field in sorted(set(row) - KNOWN_FIELDS):
+        errors.append(f"unknown capability receipt field: {field}")
+    if row.get("schema_version") != CAPABILITY_RECEIPTS_SCHEMA_VERSION:
+        errors.append(f"schema_version must be {CAPABILITY_RECEIPTS_SCHEMA_VERSION}")
+    for field in ("id", "capability", "reason", "recorded_at"):
+        if not _non_empty_string(row.get(field)):
+            errors.append(f"{field} must be a non-empty string")
+    status = row.get("status")
+    if status not in CAPABILITY_STATUSES:
+        errors.append("status must be one of: " + ", ".join(CAPABILITY_STATUSES))
+    provider = row.get("provider")
+    if status == "used":
+        if not _non_empty_string(provider):
+            errors.append("provider must be a non-empty string when status is used")
+    elif provider is not None and not _non_empty_string(provider):
+        errors.append("provider must be a non-empty string when present")
+    evidence = row.get("evidence", [])
+    if not isinstance(evidence, list) or not all(_non_empty_string(item) for item in evidence):
+        errors.append("evidence must be a list of non-empty strings")
+    return errors
+
+
+def build_capability_receipt(
+    receipt_id: str,
+    capability: str,
+    status: str,
+    reason: str,
+    provider: Optional[str] = None,
+    evidence: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    row: Dict[str, Any] = {
+        "schema_version": CAPABILITY_RECEIPTS_SCHEMA_VERSION,
+        "id": receipt_id,
+        "capability": capability,
+        "status": status,
+        "reason": reason,
+        "evidence": list(evidence or []),
+        "recorded_at": utc_now(),
+    }
+    if provider is not None:
+        row["provider"] = provider
+    errors = validate_capability_receipt(row)
+    if errors:
+        raise ValueError("; ".join(errors))
+    return row
+
+
+def read_capability_receipts(root: Path) -> List[Dict[str, Any]]:
+    rows = read_jsonl(root / CAPABILITY_RECEIPTS_PATH)
+    for index, row in enumerate(rows, start=1):
+        errors = validate_capability_receipt(row)
+        if errors:
+            raise ValueError(
+                f"capability-receipts.jsonl row {index}: " + "; ".join(errors)
+            )
+    return rows
+
+
+def append_capability_receipt(root: Path, row: Dict[str, Any]) -> None:
+    append_jsonl(root / CAPABILITY_RECEIPTS_PATH, row)
+
+
+def capability_summary(root: Path, required_ids: List[str]) -> Dict[str, Any]:
+    rows = read_capability_receipts(root)
+    used = {row["capability"] for row in rows if row.get("status") == "used"}
+    waived = {row["capability"] for row in rows if row.get("status") == "waived"}
+    satisfied = used | waived
+    return {
+        "required": list(required_ids),
+        "recorded": sorted(used),
+        "waived": sorted(waived),
+        "missing": sorted({cap for cap in required_ids if cap not in satisfied}),
+    }
+
+
+def capability_checks(summary: Dict[str, Any]) -> List[Dict[str, Any]]:
+    missing = summary.get("missing", [])
+    if missing:
+        return [
+            {
+                "id": "required_capabilities_satisfied",
+                "status": "warning",
+                "count": len(missing),
+                "message": "missing required capabilities: " + ", ".join(missing),
+            }
+        ]
+    return [{"id": "required_capabilities_satisfied", "status": "passed", "count": 0}]