agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/workflow/budget_policy.py

@@ -0,0 +1,140 @@
+"""Budget exceeded policy validation and deterministic action selection."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+
+ALLOWED_BUDGET_ACTIONS = {
+    "continue-same-route",
+    "reroute-cheaper",
+    "reroute-stronger",
+    "split-task",
+    "abort",
+}
+BUDGET_MODES = {"metered", "subscription", "local"}
+CRITICAL_DOWNGRADE_ACTIONS = {"reroute-cheaper"}
+
+
+def validate_budget_exceeded_policy(policy: dict[str, Any]) -> dict[str, Any]:
+    if policy.get("schemaVersion") != "agent-lifecycle-budget-exceeded-policy.v1":
+        raise LifecycleError("invalid-budget-policy", "unsupported budget exceeded policy schema")
+    mode = _required_str(policy, "mode")
+    if mode not in {"manual", "auto"}:
+        raise LifecycleError("invalid-budget-policy", "mode must be manual or auto", {"mode": mode})
+    allowed_actions = _required_string_list(policy, "allowedActions")
+    unknown = sorted(set(allowed_actions) - ALLOWED_BUDGET_ACTIONS)
+    if unknown:
+        raise LifecycleError("invalid-budget-policy", "allowedActions contains unsupported actions", {"actions": unknown})
+    if not allowed_actions:
+        raise LifecycleError("invalid-budget-policy", "allowedActions must not be empty")
+    forbid_critical = policy.get("forbidDowngradeForCriticalReview")
+    if not isinstance(forbid_critical, bool):
+        raise LifecycleError("invalid-budget-policy", "forbidDowngradeForCriticalReview must be boolean")
+    max_auto = policy.get("maxAutoReroutesPerTask")
+    if not isinstance(max_auto, int) or isinstance(max_auto, bool) or max_auto < 0:
+        raise LifecycleError("invalid-budget-policy", "maxAutoReroutesPerTask must be a non-negative integer")
+    default_auto = policy.get("defaultAutoAction")
+    if mode == "auto" and default_auto not in allowed_actions:
+        raise LifecycleError("invalid-budget-policy", "defaultAutoAction must be one of allowedActions")
+    budget_modes = policy.get("budgetModes")
+    if not isinstance(budget_modes, dict):
+        raise LifecycleError("invalid-budget-policy", "budgetModes must be an object")
+    mode_checks = [_budget_mode_check(name, budget_modes.get(name)) for name in sorted(BUDGET_MODES)]
+    if any(item["status"] == "FAIL" for item in mode_checks):
+        raise LifecycleError("invalid-budget-policy", "budget mode caps are invalid", {"checks": mode_checks})
+    return {
+        "schemaVersion": "agent-lifecycle-budget-exceeded-policy-validation.v1",
+        "status": "PASS",
+        "mode": mode,
+        "allowedActions": allowed_actions,
+        "policyDigest": canonical_digest(policy),
+        "checks": mode_checks,
+    }
+
+
+def select_auto_budget_action(
+    policy: dict[str, Any],
+    *,
+    task: dict[str, Any],
+    route_decision: dict[str, Any],
+) -> str:
+    validation = validate_budget_exceeded_policy(policy)
+    if validation["mode"] != "auto":
+        raise LifecycleError("invalid-budget-policy", "auto action selection requires auto mode")
+    reroutes = int(task.get("budgetAutoReroutes", 0))
+    if reroutes >= int(policy["maxAutoReroutesPerTask"]):
+        raise LifecycleError("budget-auto-reroute-limit", "max auto reroutes per task exhausted")
+    action = str(policy["defaultAutoAction"])
+    if (
+        policy.get("forbidDowngradeForCriticalReview") is True
+        and route_decision.get("criticalReview") is True
+        and action in CRITICAL_DOWNGRADE_ACTIONS
+    ):
+        for candidate in ("reroute-stronger", "split-task", "continue-same-route", "abort"):
+            if candidate in policy["allowedActions"]:
+                return candidate
+        raise LifecycleError("budget-critical-downgrade", "critical review cannot auto-downgrade to a cheaper route")
+    return action
+
+
+def _budget_mode_check(mode: str, config: Any) -> dict[str, Any]:
+    if not isinstance(config, dict):
+        return {"id": f"{mode}-cap-config", "status": "FAIL", "reason": "missing"}
+    if mode == "metered":
+        cap = config.get("budgetCapUsd")
+        threshold = config.get("meteredAskThreshold")
+        has_cap = _positive_number(cap)
+        threshold_present = threshold is not None
+        threshold_valid = (
+            not threshold_present
+            or (_positive_number(threshold) and has_cap and float(threshold) < float(cap))
+        )
+        return {
+            "id": "metered-usd-cap",
+            "status": "PASS" if has_cap and threshold_valid else "FAIL",
+            "hasBudgetCapUsd": has_cap,
+            "advisoryThresholdEnabled": threshold_present and threshold_valid,
+            "advisoryOnly": threshold_present,
+        }
+    if "meteredAskThreshold" in config:
+        return {
+            "id": f"{mode}-resource-caps",
+            "status": "FAIL",
+            "reason": "meteredAskThreshold is only valid for metered budget mode",
+        }
+    max_invocations = config.get("maxInvocations")
+    has_invocations = isinstance(max_invocations, int) and not isinstance(max_invocations, bool) and max_invocations > 0
+    has_tokens = (
+        isinstance(config.get("maxBillableTokens"), int)
+        and not isinstance(config.get("maxBillableTokens"), bool)
+        and config["maxBillableTokens"] > 0
+    )
+    has_wall = _positive_number(config.get("maxWallSeconds"))
+    return {
+        "id": f"{mode}-resource-caps",
+        "status": "PASS" if has_invocations and (has_tokens or has_wall) else "FAIL",
+        "hasMaxInvocations": has_invocations,
+        "hasTokenOrWallCap": has_tokens or has_wall,
+    }
+
+
+def _required_str(payload: dict[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value:
+        raise LifecycleError("invalid-budget-policy", f"{key} is required")
+    return value
+
+
+def _required_string_list(payload: dict[str, Any], key: str) -> list[str]:
+    value = payload.get(key)
+    if not isinstance(value, list) or any(not isinstance(item, str) or not item for item in value):
+        raise LifecycleError("invalid-budget-policy", f"{key} must be a list of non-empty strings")
+    if len(value) != len(set(value)):
+        raise LifecycleError("invalid-budget-policy", f"{key} contains duplicates")
+    return list(value)
+
+
+def _positive_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0

agent_lifecycle/workflow/budget_receipts.py

@@ -0,0 +1,70 @@
+"""Budget decision receipt construction helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import canonical_digest
+
+
+def build_budget_decision_receipt(
+    *,
+    state: dict[str, Any],
+    task: dict[str, Any],
+    route_decision: dict[str, Any],
+    usage_receipt: dict[str, Any],
+    usage_identity: dict[str, Any],
+    policy: dict[str, Any],
+    selected_action: str,
+    validation: dict[str, Any],
+    expected_workflow_revision: int,
+    operator_identity_hash: str | None = None,
+    prior_route_digest: str | None = None,
+    usage_receipt_digest: str | None = None,
+    policy_digest: str | None = None,
+    overrun_reason: str | None = None,
+    next_route_decision: dict[str, Any] | None = None,
+    next_route_identity: dict[str, Any] | None = None,
+    split_packet_identity: dict[str, Any] | None = None,
+    cap_deltas: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    receipt = {
+        "schemaVersion": "agent-lifecycle-budget-decision-receipt.v1",
+        "runId": state["runId"],
+        "packageId": state["packageId"],
+        "taskId": task["id"],
+        "attemptId": f"{task['id']}:attempt-{task.get('attempt')}",
+        "attempt": task.get("attempt"),
+        "sourceRevision": state["sourceRevision"],
+        "priorRouteDecisionDigest": prior_route_digest or route_digest(route_decision),
+        "usageReceiptDigest": usage_receipt_digest or canonical_digest(usage_receipt),
+        "usageReceipt": usage_identity,
+        "overrunReason": overrun_reason or overrun_reason_from_validation(validation),
+        "decisionMode": policy["mode"],
+        "selectedAction": selected_action,
+        "allowedActions": list(policy["allowedActions"]),
+        "operatorIdentityHash": operator_identity_hash,
+        "policyDigest": policy_digest or canonical_digest(policy),
+        "nextRouteDecisionDigest": route_digest(next_route_decision) if next_route_decision is not None else None,
+        "splitPacketIdentity": split_packet_identity,
+        "capDeltas": dict(cap_deltas or {}),
+        "resumePhase": "RUNNING",
+        "expectedWorkflowRevision": expected_workflow_revision,
+        "productionPromotionClaimed": False,
+    }
+    if next_route_identity is not None:
+        receipt["nextRouteDecision"] = next_route_identity
+    return receipt
+
+
+def route_digest(route_decision: dict[str, Any]) -> str:
+    return str(route_decision.get("decisionDigest") or canonical_digest(route_decision))
+
+
+def overrun_reason_from_validation(validation: dict[str, Any]) -> str:
+    failed = [
+        str(check.get("id"))
+        for check in validation.get("checks", [])
+        if isinstance(check, dict) and check.get("status") == "FAIL"
+    ]
+    return ",".join(failed) or "budget-overrun"

agent_lifecycle/workflow/bug_forensics_gates.py

@@ -0,0 +1,284 @@
+"""Workflow gate helpers for the optional bug-forensics profile."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.audit.proof_integrity import validate_fix_impact_receipt
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+from agent_lifecycle.quality.bug_forensics import (
+    build_bug_forensics_profile,
+    validate_bug_forensics_profile,
+    validate_bug_reproduction_receipt,
+    validate_failure_fingerprint,
+    validate_hypothesis_ledger,
+    validate_regression_proof_receipt,
+)
+from agent_lifecycle.quality.cross_check import validate_cross_check_receipt
+from agent_lifecycle.quality.failure_classification import (
+    HIGH_RISK_FAILURE_CLASSES,
+    validate_failure_classification_receipt,
+)
+
+BUG_FORENSICS_GATE_RECEIPT_SCHEMA = "agent-bug-forensics-gate-receipt.v1"
+BUG_FORENSICS_GATE_VALIDATION_SCHEMA = "agent-bug-forensics-gate-validation.v1"
+
+
+def bug_forensics_activated(task: dict[str, Any]) -> bool:
+    """Return true only when the task explicitly enables the optional profile."""
+
+    if not isinstance(task, dict):
+        return False
+    if task.get("qualityProfile") == "bug-forensics":
+        return True
+    profiles = task.get("qualityProfiles")
+    if isinstance(profiles, list) and "bug-forensics" in profiles:
+        return True
+    config = task.get("bugForensics")
+    return isinstance(config, dict) and config.get("enabled") is True
+
+
+def build_bug_forensics_gate_receipt(
+    *,
+    task: dict[str, Any],
+    profile: dict[str, Any] | None = None,
+    reproduction_receipt: dict[str, Any] | None = None,
+    failure_fingerprint: dict[str, Any] | None = None,
+    failure_classification: dict[str, Any] | None = None,
+    flake_signal: dict[str, Any] | None = None,
+    hypothesis_ledger: dict[str, Any] | None = None,
+    regression_proof: dict[str, Any] | None = None,
+    fix_impact_receipt: dict[str, Any] | None = None,
+    cross_check_receipt: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a gate receipt for an optional bug-forensics run."""
+
+    selected_profile = profile or build_bug_forensics_profile()
+    activated = bug_forensics_activated(task)
+    blockers: list[dict[str, Any]] = []
+    validations: dict[str, Any] = {"profile": validate_bug_forensics_profile(selected_profile)}
+    if validations["profile"]["status"] != "PASS":
+        blockers.append({"code": "bug-forensics-profile-invalid", "validation": validations["profile"]})
+
+    if not activated:
+        status = "SKIPPED"
+    else:
+        _collect_active_gate_blockers(
+            blockers,
+            validations,
+            task=task,
+            reproduction_receipt=reproduction_receipt,
+            failure_fingerprint=failure_fingerprint,
+            failure_classification=failure_classification,
+            flake_signal=flake_signal,
+            hypothesis_ledger=hypothesis_ledger,
+            regression_proof=regression_proof,
+            fix_impact_receipt=fix_impact_receipt,
+            cross_check_receipt=cross_check_receipt,
+        )
+        status = "PASS" if not blockers else "FAIL"
+
+    evidence = {
+        "reproduction": _digest_ref(reproduction_receipt, "receiptDigest"),
+        "failureFingerprint": _digest_ref(failure_fingerprint, "fingerprintDigest"),
+        "failureClassification": _digest_ref(failure_classification, "classificationDigest"),
+        "flakeSignal": _flake_signal_summary(flake_signal),
+        "hypothesisLedger": _digest_ref(hypothesis_ledger, "ledgerDigest"),
+        "regressionProof": _digest_ref(regression_proof, "proofDigest"),
+        "fixImpact": _digest_ref(fix_impact_receipt, "impactDigest"),
+        "crossCheck": _digest_ref(cross_check_receipt, "receiptDigest"),
+        "validations": validations,
+    }
+    body = {
+        "schemaVersion": BUG_FORENSICS_GATE_RECEIPT_SCHEMA,
+        "status": status,
+        "taskId": task.get("taskId") or task.get("id"),
+        "profileId": selected_profile.get("profileId", "bug-forensics"),
+        "activated": activated,
+        "chainVerified": activated and status == "PASS",
+        "evidence": evidence,
+        "blockers": blockers,
+        "phase2Deferred": list(selected_profile.get("phase2Deferred", [])),
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def validate_bug_forensics_gate_receipt(receipt: dict[str, Any]) -> dict[str, Any]:
+    blockers: list[dict[str, Any]] = []
+    if not isinstance(receipt, dict):
+        raise LifecycleError("invalid-bug-forensics-gate-receipt", "bug-forensics gate receipt must be an object")
+    if receipt.get("schemaVersion") != BUG_FORENSICS_GATE_RECEIPT_SCHEMA:
+        blockers.append({"code": "bug-forensics-gate-schema-invalid"})
+    gate_status = receipt.get("status")
+    if gate_status not in {"PASS", "FAIL", "SKIPPED"}:
+        blockers.append({"code": "bug-forensics-gate-status-invalid", "status": gate_status})
+    if not isinstance(receipt.get("profileId"), str) or not receipt["profileId"]:
+        blockers.append({"code": "bug-forensics-gate-profile-id-invalid"})
+    if not isinstance(receipt.get("activated"), bool):
+        blockers.append({"code": "bug-forensics-gate-activation-invalid"})
+    if not isinstance(receipt.get("chainVerified"), bool):
+        blockers.append({"code": "bug-forensics-gate-chain-invalid"})
+    if receipt.get("activated") is True and gate_status == "PASS" and receipt.get("chainVerified") is not True:
+        blockers.append({"code": "bug-forensics-gate-chain-not-verified"})
+    if receipt.get("activated") is True and gate_status == "SKIPPED":
+        blockers.append({"code": "bug-forensics-gate-skipped-while-activated"})
+    if not isinstance(receipt.get("evidence"), dict):
+        blockers.append({"code": "bug-forensics-gate-evidence-invalid"})
+    if not isinstance(receipt.get("blockers"), list) or not all(isinstance(item, dict) for item in receipt.get("blockers", [])):
+        blockers.append({"code": "bug-forensics-gate-blockers-invalid"})
+    if receipt.get("productionPromotionClaimed") is not False:
+        blockers.append({"code": "bug-forensics-gate-production-claim"})
+    expected_digest = canonical_digest({key: value for key, value in receipt.items() if key != "receiptDigest"})
+    if receipt.get("receiptDigest") != expected_digest:
+        blockers.append({"code": "bug-forensics-gate-digest-mismatch"})
+    if gate_status == "FAIL" and not receipt.get("blockers"):
+        blockers.append({"code": "bug-forensics-gate-fail-without-blockers"})
+    body = {
+        "schemaVersion": BUG_FORENSICS_GATE_VALIDATION_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "gateStatus": gate_status if isinstance(gate_status, str) else None,
+        "blockers": blockers,
+        "receiptDigest": receipt.get("receiptDigest"),
+    }
+    return {**body, "validationDigest": canonical_digest(body)}
+
+
+def require_bug_forensics_gate_pass(validation: dict[str, Any]) -> dict[str, Any]:
+    if validation.get("status") != "PASS" or validation.get("gateStatus") not in {"PASS", "SKIPPED"}:
+        raise LifecycleError("bug-forensics-gate-validation-failed", "bug-forensics gate did not pass", {"validation": validation})
+    return validation
+
+
+def _collect_active_gate_blockers(
+    blockers: list[dict[str, Any]],
+    validations: dict[str, Any],
+    *,
+    task: dict[str, Any],
+    reproduction_receipt: dict[str, Any] | None,
+    failure_fingerprint: dict[str, Any] | None,
+    failure_classification: dict[str, Any] | None,
+    flake_signal: dict[str, Any] | None,
+    hypothesis_ledger: dict[str, Any] | None,
+    regression_proof: dict[str, Any] | None,
+    fix_impact_receipt: dict[str, Any] | None,
+    cross_check_receipt: dict[str, Any] | None,
+) -> None:
+    for key, value, validator, missing_code in [
+        ("reproduction", reproduction_receipt, validate_bug_reproduction_receipt, "bug-forensics-reproduction-missing"),
+        ("failureFingerprint", failure_fingerprint, validate_failure_fingerprint, "bug-forensics-fingerprint-missing"),
+        ("hypothesisLedger", hypothesis_ledger, validate_hypothesis_ledger, "bug-forensics-hypothesis-ledger-missing"),
+        ("regressionProof", regression_proof, validate_regression_proof_receipt, "bug-forensics-regression-proof-missing"),
+    ]:
+        if value is None:
+            blockers.append({"code": missing_code})
+            continue
+        validation = validator(value)
+        validations[key] = validation
+        if validation.get("status") != "PASS":
+            blockers.append({"code": f"{key}-invalid", "validation": validation})
+    if fix_impact_receipt is None:
+        blockers.append({"code": "bug-forensics-fix-impact-missing"})
+    else:
+        validation = validate_fix_impact_receipt(fix_impact_receipt)
+        validations["fixImpact"] = validation
+        if validation.get("status") != "PASS":
+            blockers.append({"code": "bug-forensics-fix-impact-invalid", "validation": validation})
+    if failure_fingerprint is not None and regression_proof is not None:
+        before = regression_proof.get("before") if isinstance(regression_proof, dict) else {}
+        if isinstance(before, dict) and before.get("fingerprintDigest") != failure_fingerprint.get("fingerprintDigest"):
+            blockers.append({"code": "bug-forensics-fingerprint-regression-mismatch"})
+    if _classification_required(task) and failure_classification is None:
+        blockers.append({"code": "bug-forensics-failure-classification-missing"})
+    if failure_classification is not None:
+        validation = validate_failure_classification_receipt(failure_classification)
+        validations["failureClassification"] = validation
+        if validation.get("status") != "PASS" or validation.get("receiptStatus") != "PASS":
+            blockers.append({"code": "bug-forensics-failure-classification-invalid", "validation": validation})
+    if flake_signal is not None:
+        validations["flakeSignal"] = _validate_flake_signal(flake_signal)
+        if validations["flakeSignal"]["status"] != "PASS":
+            blockers.append({"code": "bug-forensics-flake-signal-invalid", "validation": validations["flakeSignal"]})
+    if _cross_check_required(task, failure_classification):
+        if cross_check_receipt is None:
+            blockers.append({"code": "bug-forensics-cross-check-missing"})
+        else:
+            validation = validate_cross_check_receipt(cross_check_receipt)
+            validations["crossCheck"] = validation
+            if validation.get("status") != "PASS" or validation.get("receiptStatus") != "PASS":
+                blockers.append({"code": "bug-forensics-cross-check-invalid", "validation": validation})
+    elif cross_check_receipt is not None:
+        validation = validate_cross_check_receipt(cross_check_receipt)
+        validations["crossCheck"] = validation
+        if validation.get("status") != "PASS":
+            blockers.append({"code": "bug-forensics-cross-check-invalid", "validation": validation})
+
+
+def _cross_check_required(task: dict[str, Any], failure_classification: dict[str, Any] | None = None) -> bool:
+    if task.get("blockingCrossCheckRequired") is True or task.get("crossCheckRequired") is True:
+        return True
+    config = task.get("bugForensics")
+    if isinstance(config, dict) and config.get("crossCheckRequired") is True:
+        return True
+    if _high_risk_classification(task, failure_classification):
+        return True
+    return False
+
+
+def _classification_required(task: dict[str, Any]) -> bool:
+    config = task.get("bugForensics")
+    if isinstance(config, dict) and config.get("requireFailureClassification") is True:
+        return True
+    return task.get("requireFailureClassification") is True
+
+
+def _high_risk_classification(task: dict[str, Any], failure_classification: dict[str, Any] | None) -> bool:
+    if not isinstance(failure_classification, dict):
+        return False
+    if failure_classification.get("failureClass") not in HIGH_RISK_FAILURE_CLASSES:
+        return False
+    risks = task.get("riskFlags", {})
+    active_security = bool(risks.get("security")) if isinstance(risks, dict) else "security" in risks if isinstance(risks, list) else False
+    return task.get("sddTier") == "S2" or active_security
+
+
+def _digest_ref(value: dict[str, Any] | None, key: str) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    return {"schemaVersion": value.get("schemaVersion"), "digest": value.get(key)}
+
+
+def _flake_signal_summary(value: dict[str, Any] | None) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    return {
+        "status": value.get("status") or value.get("flakeStatus"),
+        "runs": value.get("runs"),
+        "failures": value.get("failures"),
+    }
+
+
+def _validate_flake_signal(value: dict[str, Any]) -> dict[str, Any]:
+    blockers: list[dict[str, Any]] = []
+    status = value.get("status") or value.get("flakeStatus")
+    if status not in {"stable-fail", "stable-pass", "flaky", "inconclusive"}:
+        blockers.append({"code": "flake-signal-status-invalid", "status": status})
+    for field in ("runs", "failures"):
+        if field in value and (not isinstance(value[field], int) or isinstance(value[field], bool) or value[field] < 0):
+            blockers.append({"code": "flake-signal-count-invalid", "field": field})
+    body = {
+        "schemaVersion": "agent-flake-signal-validation.v1",
+        "status": "PASS" if not blockers else "FAIL",
+        "flakeStatus": status if isinstance(status, str) else None,
+        "blockers": blockers,
+    }
+    return {**body, "validationDigest": canonical_digest(body)}
+
+
+__all__ = [
+    "BUG_FORENSICS_GATE_RECEIPT_SCHEMA",
+    "build_bug_forensics_gate_receipt",
+    "bug_forensics_activated",
+    "require_bug_forensics_gate_pass",
+    "validate_bug_forensics_gate_receipt",
+]

agent_lifecycle/workflow/controller.py

@@ -0,0 +1,45 @@
+"""Compatibility facade for the standalone workflow controller API."""
+
+from __future__ import annotations
+
+from agent_lifecycle.workflow.finalization import finalize_run
+from agent_lifecycle.workflow.lineage import check_lineage
+from agent_lifecycle.workflow.budget_decisions import (
+    apply_budget_decision,
+    pause_for_budget_decision,
+    select_auto_budget_action,
+    validate_budget_exceeded_policy,
+)
+from agent_lifecycle.workflow.query import next_action, status
+from agent_lifecycle.workflow.plan_adoption import adopt_plan, start_execution
+from agent_lifecycle.workflow.run_transitions import (
+    block_run,
+    pause_for_external_action,
+    resolve_blocker,
+    resume_external_action,
+)
+from agent_lifecycle.workflow.task_transitions import (
+    accept_task,
+    commit_task_result,
+    start_task,
+)
+
+__all__ = [
+    "accept_task",
+    "adopt_plan",
+    "apply_budget_decision",
+    "block_run",
+    "check_lineage",
+    "commit_task_result",
+    "finalize_run",
+    "next_action",
+    "pause_for_budget_decision",
+    "pause_for_external_action",
+    "resolve_blocker",
+    "resume_external_action",
+    "select_auto_budget_action",
+    "start_execution",
+    "start_task",
+    "status",
+    "validate_budget_exceeded_policy",
+]

agent_lifecycle/workflow/events.py

@@ -0,0 +1,50 @@
+"""Append-only workflow event log."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_bytes
+from agent_lifecycle.workflow.state import now_iso
+
+
+def event_log_path(state_path: Path, state: dict[str, Any]) -> Path:
+    raw = state.get("eventLog")
+    if not isinstance(raw, str) or not raw:
+        raise LifecycleError("invalid-workflow-state", "eventLog is required")
+    raw_path = Path(raw)
+    if raw_path.is_absolute():
+        raise LifecycleError("invalid-workflow-state", "eventLog must be relative")
+    package_root = state.get("packageRoot")
+    if isinstance(package_root, str) and package_root:
+        return (state_path.parent / package_root / raw_path).resolve()
+    return state_path.parent / raw_path
+
+
+def append_event(
+    *,
+    state_path: Path,
+    state: dict[str, Any],
+    operation_id: str,
+    event_type: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    event = {
+        "schemaVersion": "agent-workflow-event.v1",
+        "runId": state.get("runId"),
+        "packageId": state.get("packageId"),
+        "stateRevision": state["stateRevision"],
+        "operationId": operation_id,
+        "eventType": event_type,
+        "payload": payload,
+        "recordedAt": now_iso(),
+    }
+    path = event_log_path(state_path, state)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("ab") as handle:
+        handle.write(canonical_bytes(event) + b"\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    return event

agent_lifecycle/workflow/final_proof_integrity.py

@@ -0,0 +1,74 @@
+"""Final-proof integration for proof-integrity receipts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.audit.proof_integrity import (
+    require_proof_integrity_pass,
+    validate_proof_integrity_receipt,
+)
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+
+
+def proof_integrity_required(state: dict[str, Any], final_audit: dict[str, Any] | None = None) -> bool:
+    """Return whether the current run explicitly requires proof-integrity evidence."""
+
+    policy = state.get("proofIntegrityPolicy")
+    if state.get("proofIntegrityRequired") is True:
+        return True
+    if isinstance(policy, dict) and policy.get("mode") in {"required", "bug-forensics", "strict"}:
+        return True
+    if isinstance(final_audit, dict):
+        if final_audit.get("proofIntegrityRequired") is True:
+            return True
+        evidence = final_audit.get("proofIntegrityEvidence")
+        if isinstance(evidence, dict) and evidence.get("required") is True:
+            return True
+    return False
+
+
+def validate_final_proof_integrity(
+    *,
+    state: dict[str, Any],
+    final_audit: dict[str, Any],
+    receipt: dict[str, Any] | None,
+    final_proof: dict[str, Any] | None = None,
+    required: bool | None = None,
+    new_run: bool = True,
+) -> dict[str, Any] | None:
+    """Validate optional final-proof integrity evidence and fail closed when required."""
+
+    must_validate = proof_integrity_required(state, final_audit) if required is None else required
+    if receipt is None:
+        if must_validate:
+            raise LifecycleError(
+                "proof-integrity-receipt-missing",
+                "final proof requires proof-integrity receipt",
+            )
+        return None
+    validation = validate_proof_integrity_receipt(
+        receipt,
+        state=state,
+        final_audit=final_audit,
+        final_proof=final_proof,
+        new_run=new_run,
+    )
+    require_proof_integrity_pass(validation)
+    if isinstance(final_proof, dict) and isinstance(final_proof.get("proofIntegrity"), dict):
+        _validate_embedded_identity(final_proof["proofIntegrity"], receipt)
+    return validation
+
+
+def _validate_embedded_identity(proof_integrity: dict[str, Any], receipt: dict[str, Any]) -> None:
+    receipt_identity = proof_integrity.get("receipt")
+    if not isinstance(receipt_identity, dict):
+        raise LifecycleError("proof-integrity-final-proof-mismatch", "final proof proofIntegrity.receipt must be an object")
+    if receipt_identity.get("sha256") != canonical_digest(receipt):
+        raise LifecycleError("proof-integrity-final-proof-mismatch", "final proof proofIntegrity receipt digest mismatch")
+    validation = proof_integrity.get("validation")
+    if not isinstance(validation, dict) or validation.get("receiptDigest") != receipt.get("receiptDigest"):
+        raise LifecycleError("proof-integrity-final-proof-mismatch", "final proof proofIntegrity validation mismatch")
+
+
+__all__ = ["proof_integrity_required", "validate_final_proof_integrity"]