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

agent_lifecycle/specification/completion_signal.py

@@ -0,0 +1,75 @@
+"""Completion signal validation for terminal lifecycle decisions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+
+
+def validate_completion_signal(signal: dict[str, Any], *, state: dict[str, Any]) -> dict[str, Any]:
+    """Validate the final completion signal or explicit waiver."""
+
+    if not isinstance(signal, dict):
+        raise LifecycleError("completion-signal-required", "final audit requires completionSignal")
+    if signal.get("schemaVersion") != "agent-completion-signal.v1":
+        raise LifecycleError("invalid-completion-signal", "completionSignal schemaVersion is unsupported")
+    status = signal.get("status")
+    if status not in {"PASS", "WAIVED", "FAIL"}:
+        raise LifecycleError("invalid-completion-signal", "completionSignal status is unsupported")
+    _require_lineage(signal, state)
+    evidence_ids = _string_list(signal.get("evidenceIds"), label="completionSignal.evidenceIds")
+    if not evidence_ids:
+        raise LifecycleError("invalid-completion-signal", "completionSignal evidenceIds are required")
+    verifier = signal.get("verifier")
+    if not isinstance(verifier, dict) or not isinstance(verifier.get("id"), str) or not verifier["id"]:
+        raise LifecycleError("invalid-completion-signal", "completionSignal verifier.id is required")
+    if status == "FAIL":
+        raise LifecycleError("completion-signal-not-ready", "completionSignal status FAIL cannot finalize the run")
+    waiver = signal.get("waiver")
+    if status == "WAIVED":
+        _validate_waiver(waiver)
+    elif waiver is not None:
+        raise LifecycleError("invalid-completion-signal", "completionSignal waiver is only allowed for WAIVED status")
+    return {
+        "schemaVersion": "agent-completion-signal-validation.v1",
+        "status": "PASS",
+        "signalStatus": status,
+        "runId": signal.get("runId"),
+        "packageId": signal.get("packageId"),
+        "planRevision": signal.get("planRevision"),
+        "planDigest": signal.get("planDigest"),
+        "sourceRevision": signal.get("sourceRevision"),
+        "evidenceIds": evidence_ids,
+        "waived": status == "WAIVED",
+        "signalDigest": canonical_digest(signal),
+    }
+
+
+def _require_lineage(signal: dict[str, Any], state: dict[str, Any]) -> None:
+    expected = {
+        "runId": state.get("runId"),
+        "packageId": state.get("packageId"),
+        "planRevision": state.get("planRevision"),
+        "planDigest": state.get("planDigest"),
+        "sourceRevision": state.get("sourceRevision"),
+    }
+    for key, value in expected.items():
+        if signal.get(key) != value:
+            raise LifecycleError("completion-signal-lineage-mismatch", f"completionSignal {key} mismatch")
+
+
+def _validate_waiver(waiver: Any) -> None:
+    if not isinstance(waiver, dict):
+        raise LifecycleError("invalid-completion-signal-waiver", "WAIVED completionSignal requires waiver")
+    for key in ("reason", "approvedBy"):
+        if not isinstance(waiver.get(key), str) or not waiver[key]:
+            raise LifecycleError("invalid-completion-signal-waiver", f"waiver.{key} is required")
+    if not _string_list(waiver.get("evidenceIds"), label="waiver.evidenceIds"):
+        raise LifecycleError("invalid-completion-signal-waiver", "waiver.evidenceIds are required")
+
+
+def _string_list(value: Any, *, label: str) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        raise LifecycleError("invalid-completion-signal", f"{label} must be a list of non-empty strings")
+    return value

agent_lifecycle/specification/validation.py

@@ -0,0 +1,48 @@
+"""Validate portable SDD specification envelopes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+from agent_lifecycle.specification.completion_check import validate_completion_check
+
+SDD_TIERS = {"S0", "S1", "S2"}
+SPEC_STATUSES = {"DRAFT", "READY", "FROZEN", "REOPENED"}
+
+
+def validate_specification(specification: dict[str, Any]) -> dict[str, Any]:
+    tier = specification.get("tier")
+    if tier not in SDD_TIERS:
+        raise LifecycleError("invalid-specification", "specification tier must be S0, S1, or S2")
+    status = specification.get("status")
+    if status not in SPEC_STATUSES:
+        raise LifecycleError("invalid-specification", "specification status is invalid")
+    requirements = specification.get("requirements")
+    if not isinstance(requirements, list) or not requirements:
+        raise LifecycleError("invalid-specification", "specification requirements are required")
+    ids = [_requirement_id(item) for item in requirements]
+    if len(ids) != len(set(ids)):
+        raise LifecycleError("invalid-specification", "requirement ids must be unique")
+    result = {
+        "schemaVersion": "agent-specification-validation.v1",
+        "tier": tier,
+        "status": status,
+        "requirementCount": len(ids),
+        "requirementSetDigest": canonical_digest({"requirements": ids}),
+    }
+    check = specification.get("completionCheck")
+    if check is not None:
+        check_validation = validate_completion_check(check)
+        result["completionCheckId"] = check_validation["checkId"]
+        result["completionCheckKind"] = check_validation["kind"]
+        result["completionCheckDigest"] = check_validation["checkDigest"]
+    return result
+
+
+def _requirement_id(item: Any) -> str:
+    if not isinstance(item, dict) or not isinstance(item.get("id"), str) or not item["id"]:
+        raise LifecycleError("invalid-specification", "each requirement requires an id")
+    if item.get("required") is False:
+        raise LifecycleError("invalid-specification", "optional requirements are not accepted in frozen core")
+    return item["id"]

agent_lifecycle/workflow/__init__.py

@@ -0,0 +1,79 @@
+"""Durable workflow controller primitives."""
+
+from agent_lifecycle.workflow.controller import (
+    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,
+)
+from agent_lifecycle.workflow.managed_runner import run_managed_lifecycle_step
+from agent_lifecycle.workflow.bug_forensics_gates import (
+    build_bug_forensics_gate_receipt,
+    bug_forensics_activated,
+    require_bug_forensics_gate_pass,
+    validate_bug_forensics_gate_receipt,
+)
+from agent_lifecycle.workflow.final_proof_integrity import (
+    proof_integrity_required,
+    validate_final_proof_integrity,
+)
+from agent_lifecycle.workflow.leases import (
+    build_worker_lease_receipt,
+    classify_lease_status,
+    require_worker_lease_receipt_pass,
+    validate_worker_lease_receipt,
+)
+from agent_lifecycle.workflow.sandbox_policy import (
+    build_sandbox_requirement_policy,
+    require_task_sandbox_evidence_pass,
+    sandbox_evidence_required,
+    validate_task_sandbox_evidence,
+)
+
+__all__ = [
+    "accept_task",
+    "adopt_plan",
+    "apply_budget_decision",
+    "block_run",
+    "build_bug_forensics_gate_receipt",
+    "build_worker_lease_receipt",
+    "build_sandbox_requirement_policy",
+    "bug_forensics_activated",
+    "check_lineage",
+    "classify_lease_status",
+    "commit_task_result",
+    "finalize_run",
+    "next_action",
+    "pause_for_budget_decision",
+    "pause_for_external_action",
+    "proof_integrity_required",
+    "require_bug_forensics_gate_pass",
+    "require_task_sandbox_evidence_pass",
+    "require_worker_lease_receipt_pass",
+    "resolve_blocker",
+    "resume_external_action",
+    "run_managed_lifecycle_step",
+    "sandbox_evidence_required",
+    "select_auto_budget_action",
+    "start_execution",
+    "start_task",
+    "status",
+    "validate_budget_exceeded_policy",
+    "validate_bug_forensics_gate_receipt",
+    "validate_final_proof_integrity",
+    "validate_task_sandbox_evidence",
+    "validate_worker_lease_receipt",
+]

agent_lifecycle/workflow/artifacts.py

@@ -0,0 +1,74 @@
+"""Workflow artifact path and identity helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+from agent_lifecycle.contracts.canonical import canonical_bytes
+from agent_lifecycle.contracts.paths import normalize_repo_path
+
+
+def package_root(state_path: Path, state: dict[str, Any]) -> Path:
+    raw = state.get("packageRoot")
+    if isinstance(raw, str) and raw:
+        return (state_path.parent / raw).resolve()
+    return state_path.parent
+
+
+def artifact_path(task: dict[str, Any], role: str, attempt: int) -> str:
+    artifacts = task.get("artifactPaths")
+    if not isinstance(artifacts, dict) or not isinstance(artifacts.get(role), str):
+        raise LifecycleError(
+            "missing-artifact-template",
+            f"task {task.get('id')} has no {role} artifact template",
+        )
+    return normalize_repo_path(artifacts[role].replace("{attempt}", str(attempt)))
+
+
+def artifact_identity(root: Path, path: str, value: dict[str, Any]) -> dict[str, Any]:
+    data = canonical_bytes(value) + b"\n"
+    actual = (root / path).read_bytes()
+    if actual != data:
+        raise LifecycleError(
+            "non-canonical-artifact",
+            f"artifact is not canonical JSON: {path}",
+        )
+    return {"path": path, "sha256": canonical_digest(value), "bytes": len(actual)}
+
+
+def next_available_attempt(
+    state_path: Path,
+    state: dict[str, Any],
+    task: dict[str, Any],
+) -> int:
+    max_attempts = int(state.get("budgets", {}).get("maxTaskAttempts", 1))
+    current = int(task.get("attempt", 0))
+    for attempt in range(current + 1, max_attempts + 1):
+        if not attempt_artifacts_exist(state_path, state, task, attempt):
+            return attempt
+    raise LifecycleError(
+        "task-attempt-output-conflict",
+        f"task {task.get('id')} has no unoccupied attempt artifact path",
+        {"maxTaskAttempts": max_attempts},
+    )
+
+
+def attempt_artifacts_exist(
+    state_path: Path,
+    state: dict[str, Any],
+    task: dict[str, Any],
+    attempt: int,
+) -> bool:
+    artifacts = task.get("artifactPaths", {})
+    if not isinstance(artifacts, dict):
+        return False
+    root = package_root(state_path, state)
+    for template in artifacts.values():
+        if not isinstance(template, str):
+            continue
+        rendered = normalize_repo_path(template.replace("{attempt}", str(attempt)))
+        if (root / rendered).exists():
+            return True
+    return False

agent_lifecycle/workflow/budget_decisions.py

@@ -0,0 +1,370 @@
+"""Budget-overrun pause, decision, and resume helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, read_json_object, write_json_create
+from agent_lifecycle.contracts.paths import normalize_repo_path
+from agent_lifecycle.workflow.artifacts import artifact_identity, package_root
+from agent_lifecycle.workflow.budget_policy import (
+    ALLOWED_BUDGET_ACTIONS,
+    select_auto_budget_action,
+    validate_budget_exceeded_policy,
+)
+from agent_lifecycle.workflow.budget_receipts import (
+    build_budget_decision_receipt,
+    route_digest,
+)
+from agent_lifecycle.workflow.model_usage import (
+    UNSAFE_CRITICAL_REVIEW_CLASSES,
+    validate_attempt_model_route,
+    validate_task_model_usage_receipt,
+)
+from agent_lifecycle.workflow.operation_kernel import commit_state, load_for_update
+from agent_lifecycle.workflow.query import status
+from agent_lifecycle.workflow.selectors import find_task
+
+def pause_for_budget_decision(
+    state_path: Path,
+    *,
+    task_id: str,
+    operation_id: str,
+    expected_revision: int,
+    source_revision: str,
+    usage_receipt_path: str,
+    budget_policy_path: str,
+    decision_receipt_path: str,
+    reason: str,
+) -> dict[str, Any]:
+    state = load_for_update(state_path, operation_id=operation_id, expected_revision=expected_revision)
+    if state["phase"] != "RUNNING":
+        raise LifecycleError("invalid-phase", "budget decision pause requires RUNNING phase")
+    if state.get("sourceRevision") != source_revision:
+        raise LifecycleError("source-revision-mismatch", "source revision mismatch")
+    task = find_task(state, task_id)
+    if task.get("status") != "RUNNING":
+        raise LifecycleError("invalid-task-status", f"task {task_id} is not RUNNING")
+    route = _attempt_route(task)
+    if route is None:
+        raise LifecycleError("budget-decision-not-required", "task has no model route")
+
+    root = package_root(state_path, state)
+    usage_rel = normalize_repo_path(usage_receipt_path, label="model usage receipt")
+    receipt = read_json_object(root / usage_rel, label="model usage receipt")
+    usage_identity = artifact_identity(root, usage_rel, receipt)
+    validation = validate_task_model_usage_receipt(state, task, receipt, fail_on_invalid=False)
+    if validation["status"] != "FAIL" or not _has_budget_failure(validation):
+        raise LifecycleError("budget-decision-not-required", "model usage receipt did not fail a budget guard")
+
+    policy_rel = normalize_repo_path(budget_policy_path, label="budget policy")
+    policy = read_json_object(root / policy_rel, label="budget policy")
+    policy_validation = validate_budget_exceeded_policy(policy)
+    action = "await-operator" if policy_validation["mode"] == "manual" else select_auto_budget_action(policy, task=task, route_decision=route)
+
+    decision_rel = normalize_repo_path(decision_receipt_path, label="budget decision receipt")
+    decision = build_budget_decision_receipt(
+        state=state,
+        task=task,
+        route_decision=route,
+        usage_receipt=receipt,
+        usage_identity=usage_identity,
+        policy=policy,
+        selected_action=action,
+        validation=validation,
+        expected_workflow_revision=state["stateRevision"] + 1,
+    )
+    write_json_create(root / decision_rel, decision)
+    decision_identity = artifact_identity(root, decision_rel, decision)
+    task["status"] = "WAITING_FOR_BUDGET_DECISION"
+    task["budgetDecision"] = {
+        **decision_identity,
+        "selectedAction": action,
+        "decisionMode": policy_validation["mode"],
+        "usageReceipt": usage_identity,
+        "usageValidation": validation,
+    }
+    if policy_validation["mode"] == "auto":
+        task["budgetAutoReroutes"] = int(task.get("budgetAutoReroutes", 0)) + 1
+    state["phase"] = "WAITING_FOR_BUDGET_DECISION"
+    state["blocker"] = {
+        "code": "BUDGET_DECISION_REQUIRED",
+        "reason": reason,
+        "resumePhase": "RUNNING",
+        "taskId": task_id,
+        "attempt": task.get("attempt"),
+        "allowedActions": policy["allowedActions"],
+        "decisionReceiptTarget": decision_rel,
+        "decisionReceipt": decision_identity,
+    }
+    commit_state(
+        state_path,
+        state,
+        operation_id=operation_id,
+        event_type="budget-decision-required",
+        payload={"taskId": task_id, "attempt": task.get("attempt"), "decisionReceipt": decision_identity},
+    )
+    return status(state_path)
+
+
+def apply_budget_decision(
+    state_path: Path,
+    *,
+    task_id: str,
+    operation_id: str,
+    expected_revision: int,
+    source_revision: str,
+    decision_receipt_path: str,
+    action: str,
+    applied_receipt_path: str,
+    route_decision_path: str | None = None,
+    split_packet_path: str | None = None,
+    cap_deltas_path: str | None = None,
+    operator_identity_hash: str | None = None,
+    reason: str,
+) -> dict[str, Any]:
+    if action not in ALLOWED_BUDGET_ACTIONS:
+        raise LifecycleError("invalid-budget-action", "unsupported budget decision action", {"action": action})
+    state = load_for_update(state_path, operation_id=operation_id, expected_revision=expected_revision)
+    if state["phase"] != "WAITING_FOR_BUDGET_DECISION":
+        raise LifecycleError("invalid-phase", "budget decision apply requires WAITING_FOR_BUDGET_DECISION phase")
+    if state.get("sourceRevision") != source_revision:
+        raise LifecycleError("source-revision-mismatch", "source revision mismatch")
+    task = find_task(state, task_id)
+    if task.get("status") != "WAITING_FOR_BUDGET_DECISION":
+        raise LifecycleError("invalid-task-status", f"task {task_id} is not waiting for a budget decision")
+    blocker = _budget_blocker(state, task)
+    root = package_root(state_path, state)
+    pending_rel = normalize_repo_path(decision_receipt_path, label="budget decision receipt")
+    pending = read_json_object(root / pending_rel, label="budget decision receipt")
+    pending_identity = artifact_identity(root, pending_rel, pending)
+    _validate_pending_decision(state, task, pending, action)
+
+    next_route, next_route_identity = _read_next_route(root, route_decision_path, action, task)
+    split_identity = _read_split_packet(root, split_packet_path, action)
+    cap_deltas = _read_cap_deltas(root, cap_deltas_path, action)
+    _require_operator_identity(pending, operator_identity_hash)
+
+    receipt_rel = normalize_repo_path(applied_receipt_path, label="applied budget decision receipt")
+    applied = build_budget_decision_receipt(
+        state=state,
+        task=task,
+        route_decision=_attempt_route(task) or {},
+        usage_receipt={"identity": pending.get("usageReceiptDigest")},
+        usage_identity=dict(pending["usageReceipt"]),
+        policy={"mode": pending["decisionMode"], "allowedActions": pending["allowedActions"]},
+        selected_action=action,
+        validation={"checks": [{"id": pending["overrunReason"], "status": "FAIL"}]},
+        expected_workflow_revision=state["stateRevision"] + 1,
+        operator_identity_hash=operator_identity_hash,
+        prior_route_digest=str(pending["priorRouteDecisionDigest"]),
+        usage_receipt_digest=str(pending["usageReceiptDigest"]),
+        policy_digest=str(pending["policyDigest"]),
+        overrun_reason=str(pending["overrunReason"]),
+        next_route_decision=next_route,
+        next_route_identity=next_route_identity,
+        split_packet_identity=split_identity,
+        cap_deltas=cap_deltas,
+    )
+    applied["pendingDecisionReceipt"] = pending_identity
+    write_json_create(root / receipt_rel, applied)
+    applied_identity = artifact_identity(root, receipt_rel, applied)
+    _apply_action(
+        state,
+        task,
+        action=action,
+        next_route=next_route,
+        split_identity=split_identity,
+        applied_identity=applied_identity,
+        pending_identity=pending_identity,
+        reason=reason,
+    )
+    commit_state(
+        state_path,
+        state,
+        operation_id=operation_id,
+        event_type="budget-decision-applied",
+        payload={
+            "taskId": task_id,
+            "attempt": task.get("attempt"),
+            "action": action,
+            "previousBlocker": blocker,
+            "decisionReceipt": applied_identity,
+        },
+    )
+    return status(state_path)
+
+
+def _apply_action(
+    state: dict[str, Any],
+    task: dict[str, Any],
+    *,
+    action: str,
+    next_route: dict[str, Any] | None,
+    split_identity: dict[str, Any] | None,
+    applied_identity: dict[str, Any],
+    pending_identity: dict[str, Any],
+    reason: str,
+) -> None:
+    task["budgetDecisionApplied"] = {
+        **applied_identity,
+        "selectedAction": action,
+        "pendingDecisionReceipt": pending_identity,
+        "reason": reason,
+    }
+    task["lastReason"] = reason
+    if action == "continue-same-route":
+        task["status"] = "RUNNING"
+        state["phase"] = "RUNNING"
+        state["blocker"] = None
+        return
+    if action in {"reroute-cheaper", "reroute-stronger"}:
+        assert next_route is not None
+        task["modelRoute"] = next_route
+        task.pop("attemptModelRoute", None)
+        task["status"] = "READY"
+        state["phase"] = "RUNNING"
+        state["blocker"] = None
+        return
+    task["status"] = "BLOCKED"
+    state["phase"] = "BLOCKED"
+    code = "BUDGET_SPLIT_REQUIRED" if action == "split-task" else "BUDGET_ABORTED"
+    state["blocker"] = {
+        "code": code,
+        "reason": reason,
+        "resumePhase": "RUNNING",
+        "taskId": task["id"],
+        "attempt": task.get("attempt"),
+        "selectedAction": action,
+        "decisionReceipt": applied_identity,
+        "splitPacketIdentity": split_identity,
+    }
+
+
+def _budget_blocker(state: dict[str, Any], task: dict[str, Any]) -> dict[str, Any]:
+    blocker = state.get("blocker")
+    if not isinstance(blocker, dict) or blocker.get("code") != "BUDGET_DECISION_REQUIRED":
+        raise LifecycleError("budget-decision-not-required", "run is not blocked on a budget decision")
+    if blocker.get("taskId") != task["id"] or blocker.get("attempt") != task.get("attempt"):
+        raise LifecycleError("budget-decision-lineage-mismatch", "budget blocker does not match task attempt")
+    return dict(blocker)
+
+
+def _validate_pending_decision(
+    state: dict[str, Any],
+    task: dict[str, Any],
+    receipt: dict[str, Any],
+    action: str,
+) -> None:
+    if receipt.get("schemaVersion") != "agent-lifecycle-budget-decision-receipt.v1":
+        raise LifecycleError("invalid-budget-decision-receipt", "unsupported budget decision receipt schema")
+    expected = {
+        "runId": state.get("runId"),
+        "packageId": state.get("packageId"),
+        "taskId": task.get("id"),
+        "attempt": task.get("attempt"),
+        "sourceRevision": state.get("sourceRevision"),
+        "expectedWorkflowRevision": state.get("stateRevision"),
+    }
+    for key, value in expected.items():
+        if receipt.get(key) != value:
+            raise LifecycleError("budget-decision-lineage-mismatch", f"budget decision receipt {key} mismatch")
+    if action not in receipt.get("allowedActions", []):
+        raise LifecycleError("budget-action-not-allowed", "budget decision action is not allowed", {"action": action})
+    selected = receipt.get("selectedAction")
+    if receipt.get("decisionMode") == "manual" and selected != "await-operator":
+        raise LifecycleError("invalid-budget-decision-receipt", "manual pending receipt must await operator action")
+    if receipt.get("decisionMode") == "auto" and selected != action:
+        raise LifecycleError("budget-action-mismatch", "auto budget decision must apply the selected action")
+    prior_route = _attempt_route(task)
+    if prior_route is not None and receipt.get("priorRouteDecisionDigest") != route_digest(prior_route):
+        raise LifecycleError("budget-decision-lineage-mismatch", "prior route decision digest mismatch")
+
+
+def _read_next_route(
+    root: Path,
+    route_decision_path: str | None,
+    action: str,
+    task: dict[str, Any],
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    if action not in {"reroute-cheaper", "reroute-stronger"}:
+        if route_decision_path is not None:
+            raise LifecycleError("unexpected-route-decision", "route decision is only valid for reroute actions")
+        return None, None
+    if route_decision_path is None:
+        raise LifecycleError("route-decision-required", "reroute actions require --route-decision")
+    route_rel = normalize_repo_path(route_decision_path, label="route decision")
+    route = read_json_object(root / route_rel, label="route decision")
+    if route.get("schemaVersion") != "agent-lifecycle-model-route-decision.v1":
+        raise LifecycleError("invalid-model-route", "route decision schema is unsupported")
+    if not isinstance(route.get("modelClass"), str) or not route["modelClass"]:
+        raise LifecycleError("invalid-model-route", "route decision modelClass is required")
+    _require_critical_safety(task, route, action)
+    candidate = {**task, "modelRoute": route}
+    validate_attempt_model_route(candidate)
+    return route, artifact_identity(root, route_rel, route)
+
+
+def _read_split_packet(root: Path, split_packet_path: str | None, action: str) -> dict[str, Any] | None:
+    if action != "split-task":
+        if split_packet_path is not None:
+            raise LifecycleError("unexpected-split-packet", "split packet is only valid for split-task")
+        return None
+    if split_packet_path is None:
+        raise LifecycleError("split-packet-required", "split-task requires --split-packet")
+    packet_rel = normalize_repo_path(split_packet_path, label="split packet")
+    packet = read_json_object(root / packet_rel, label="split packet")
+    return artifact_identity(root, packet_rel, packet)
+
+
+def _read_cap_deltas(root: Path, cap_deltas_path: str | None, action: str) -> dict[str, Any]:
+    if action == "continue-same-route" and cap_deltas_path is None:
+        raise LifecycleError("cap-deltas-required", "continue-same-route requires explicit cap deltas")
+    if cap_deltas_path is None:
+        return {}
+    deltas_rel = normalize_repo_path(cap_deltas_path, label="cap deltas")
+    deltas = read_json_object(root / deltas_rel, label="cap deltas")
+    if not isinstance(deltas, dict):
+        raise LifecycleError("invalid-cap-deltas", "cap deltas must be an object")
+    return deltas
+
+
+def _require_operator_identity(receipt: dict[str, Any], operator_identity_hash: str | None) -> None:
+    if receipt.get("decisionMode") != "manual":
+        return
+    if not isinstance(operator_identity_hash, str) or not operator_identity_hash:
+        raise LifecycleError("operator-identity-required", "manual budget decision requires operator identity hash")
+
+
+def _require_critical_safety(task: dict[str, Any], next_route: dict[str, Any], action: str) -> None:
+    prior = _attempt_route(task) or {}
+    if prior.get("criticalReview") is not True:
+        return
+    next_class = str(next_route.get("modelClass", ""))
+    if action == "reroute-cheaper" or next_class in UNSAFE_CRITICAL_REVIEW_CLASSES:
+        raise LifecycleError(
+            "budget-critical-downgrade",
+            "critical review route cannot be rerouted to a cheaper or compact class",
+            {"modelClass": next_class},
+        )
+
+
+def _attempt_route(task: dict[str, Any]) -> dict[str, Any] | None:
+    route = task.get("attemptModelRoute")
+    if isinstance(route, dict) and route:
+        return route
+    route = task.get("modelRoute")
+    if isinstance(route, dict) and route:
+        return route
+    return None
+
+
+def _has_budget_failure(validation: dict[str, Any]) -> bool:
+    for check in validation.get("checks", []):
+        if not isinstance(check, dict) or check.get("status") != "FAIL":
+            continue
+        check_id = str(check.get("id", ""))
+        if check_id == "route-max-billable-tokens" or check_id.startswith("hard-ceiling-"):
+            return True
+    return False