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

agent_lifecycle/workflow/implementation_audit_gate.py

@@ -0,0 +1,126 @@
+"""Shared workflow gates for implementation audit reports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, read_json_object
+from agent_lifecycle.contracts.paths import normalize_repo_path
+from agent_lifecycle.workflow.artifacts import artifact_identity, package_root
+
+
+def task_implementation_audit_required(
+    state_path: Path,
+    state: dict[str, Any],
+    task: dict[str, Any],
+) -> bool:
+    if state.get("implementationAuditRequired") is True or _required(state.get("implementationAudit")):
+        return True
+    if task.get("implementationAuditRequired") is True or _required(task.get("implementationAudit")):
+        return True
+    manifest = load_state_manifest(state_path, state)
+    if manifest is None:
+        return False
+    if _required(manifest.get("implementationAudit")):
+        return True
+    for workstream in manifest.get("workstreams", []):
+        if isinstance(workstream, dict) and workstream.get("id") == task.get("id"):
+            return workstream.get("implementationAuditRequired") is True or _required(workstream.get("implementationAudit"))
+    return False
+
+
+def final_implementation_audit_required(state_path: Path, state: dict[str, Any]) -> bool:
+    if state.get("finalImplementationAuditRequired") is True:
+        return True
+    implementation_audit = state.get("implementationAudit")
+    if isinstance(implementation_audit, dict) and implementation_audit.get("finalRequired") is True:
+        return True
+    manifest = load_state_manifest(state_path, state)
+    if manifest is None:
+        return False
+    manifest_audit = manifest.get("implementationAudit")
+    return isinstance(manifest_audit, dict) and manifest_audit.get("finalRequired") is True
+
+
+def validate_task_implementation_audit_artifact(
+    state_path: Path,
+    state: dict[str, Any],
+    task: dict[str, Any],
+    report_path: str,
+) -> dict[str, Any]:
+    root = package_root(state_path, state)
+    rel = normalize_repo_path(report_path, label="implementation audit report")
+    report = read_json_object(root / rel, label="implementation audit report")
+    from agent_lifecycle.audit.implementation import (
+        require_implementation_audit_accepted,
+        validate_implementation_audit_report,
+    )
+
+    validation = validate_implementation_audit_report(report, state=state, task=task)
+    require_implementation_audit_accepted(validation, report)
+    identity = artifact_identity(root, rel, report)
+    return {
+        **identity,
+        "taskId": report.get("taskId"),
+        "attempt": report.get("attempt"),
+        "verdict": report.get("verdict"),
+        "reportDigest": report.get("reportDigest"),
+        "validation": {
+            "status": validation["status"],
+            "validationDigest": validation["validationDigest"],
+        },
+    }
+
+
+def task_has_accepted_implementation_audit(task: dict[str, Any]) -> bool:
+    audit = task.get("implementationAuditReport")
+    return isinstance(audit, dict) and audit.get("verdict") == "ACCEPTED"
+
+
+def missing_required_implementation_audits(state_path: Path, state: dict[str, Any]) -> list[str]:
+    missing = []
+    for task in state.get("tasks", []):
+        if not isinstance(task, dict) or task.get("status") != "ACCEPTED":
+            continue
+        if task_implementation_audit_required(state_path, state, task) and not task_has_accepted_implementation_audit(task):
+            missing.append(str(task.get("id")))
+    return missing
+
+
+def load_state_manifest(state_path: Path, state: dict[str, Any]) -> dict[str, Any] | None:
+    manifest_path = state.get("manifestPath")
+    if not isinstance(manifest_path, str) or not manifest_path:
+        return None
+    root = package_root(state_path, state)
+    rel = normalize_repo_path(manifest_path, label="manifest path")
+    path = root / rel
+    if not path.is_file():
+        return None
+    return read_json_object(path, label="plan manifest")
+
+
+def implementation_audit_blockers(state_path: Path, state: dict[str, Any]) -> list[dict[str, Any]]:
+    blockers = []
+    for task in state.get("tasks", []):
+        if not isinstance(task, dict):
+            continue
+        if task.get("status") not in {"VERIFYING", "ACCEPTED"}:
+            continue
+        if task_implementation_audit_required(state_path, state, task) and not task_has_accepted_implementation_audit(task):
+            blockers.append({"code": "implementation-audit-required", "taskId": task.get("id")})
+    return blockers
+
+
+def require_final_implementation_audit_pass(audit: dict[str, Any]) -> dict[str, Any]:
+    if audit.get("status") != "PASS":
+        raise LifecycleError(
+            "final-implementation-audit-not-pass",
+            "final implementation audit did not pass",
+            {"blockers": audit.get("blockers", [])},
+        )
+    return audit
+
+
+def _required(value: Any) -> bool:
+    return isinstance(value, dict) and value.get("required") is True

agent_lifecycle/workflow/leases.py

@@ -0,0 +1,220 @@
+"""Worker lease and heartbeat receipts."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+
+WORKER_LEASE_RECEIPT_SCHEMA = "agent-worker-lease-receipt.v1"
+WORKER_LEASE_RECEIPT_VALIDATION_SCHEMA = "agent-worker-lease-receipt-validation.v1"
+
+LEASE_STATUSES = {"active", "expired", "completed"}
+RECEIPT_STATUSES = {"PASS", "FAIL"}
+LINEAGE_KEYS = ("runId", "packageId", "planRevision", "planDigest", "sourceRevision")
+
+
+def build_worker_lease_receipt(
+    *,
+    lineage: dict[str, Any],
+    worker_id: str,
+    lease_id: str,
+    task_id: str,
+    acquired_at: str,
+    expires_at: str,
+    observed_at: str | None = None,
+    heartbeat_at: str | None = None,
+    completed_at: str | None = None,
+    evidence_ids: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+    blockers: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Build a lease receipt with active/expired/completed classification."""
+
+    observed = observed_at or _now_iso()
+    lease_status = classify_lease_status(expires_at=expires_at, observed_at=observed, completed_at=completed_at)
+    body = {
+        "schemaVersion": WORKER_LEASE_RECEIPT_SCHEMA,
+        "status": "FAIL" if blockers else "PASS",
+        "lineage": _lineage(lineage, code="invalid-worker-lease-receipt"),
+        "workerId": _required_string(worker_id, label="workerId", code="invalid-worker-lease-receipt"),
+        "leaseId": _required_string(lease_id, label="leaseId", code="invalid-worker-lease-receipt"),
+        "taskId": _required_string(task_id, label="taskId", code="invalid-worker-lease-receipt"),
+        "leaseStatus": lease_status,
+        "acquiredAt": _iso(acquired_at, label="acquiredAt", code="invalid-worker-lease-receipt"),
+        "expiresAt": _iso(expires_at, label="expiresAt", code="invalid-worker-lease-receipt"),
+        "observedAt": _iso(observed, label="observedAt", code="invalid-worker-lease-receipt"),
+        "heartbeatAt": _optional_iso(heartbeat_at, label="heartbeatAt", code="invalid-worker-lease-receipt"),
+        "completedAt": _optional_iso(completed_at, label="completedAt", code="invalid-worker-lease-receipt"),
+        "evidenceIds": _string_list(evidence_ids or [], label="evidenceIds", code="invalid-worker-lease-receipt", allow_empty=True),
+        "metadata": dict(metadata or {}),
+        "blockers": list(blockers or []),
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def classify_lease_status(*, expires_at: str, observed_at: str, completed_at: str | None = None) -> str:
+    """Classify a lease from deterministic timestamps."""
+
+    if completed_at:
+        return "completed"
+    expires = _parse_iso(expires_at, label="expiresAt", code="invalid-worker-lease-receipt")
+    observed = _parse_iso(observed_at, label="observedAt", code="invalid-worker-lease-receipt")
+    return "expired" if observed > expires else "active"
+
+
+def validate_worker_lease_receipt(receipt: dict[str, Any], *, expected_lineage: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Validate a worker lease receipt and recompute lease state."""
+
+    blockers: list[dict[str, Any]] = []
+    if not isinstance(receipt, dict):
+        raise LifecycleError("invalid-worker-lease-receipt", "worker lease receipt must be an object")
+    if receipt.get("schemaVersion") != WORKER_LEASE_RECEIPT_SCHEMA:
+        blockers.append({"code": "worker-lease-schema-invalid"})
+    status = receipt.get("status")
+    if status not in RECEIPT_STATUSES:
+        blockers.append({"code": "worker-lease-status-invalid", "status": status})
+    lineage = _checked_lineage(receipt.get("lineage"), blockers)
+    if expected_lineage is not None and lineage is not None:
+        _compare_lineage(lineage, expected_lineage, blockers)
+    for key in ("workerId", "leaseId", "taskId"):
+        if not isinstance(receipt.get(key), str) or not receipt[key]:
+            blockers.append({"code": "worker-lease-field-missing", "field": key})
+    lease_status = receipt.get("leaseStatus")
+    if lease_status not in LEASE_STATUSES:
+        blockers.append({"code": "worker-lease-status-class-invalid", "leaseStatus": lease_status})
+    acquired = _checked_iso(receipt.get("acquiredAt"), "worker-lease-acquired-invalid", blockers)
+    expires = _checked_iso(receipt.get("expiresAt"), "worker-lease-expires-invalid", blockers)
+    observed = _checked_iso(receipt.get("observedAt"), "worker-lease-observed-invalid", blockers)
+    heartbeat = _checked_optional_iso(receipt.get("heartbeatAt"), "worker-lease-heartbeat-invalid", blockers)
+    completed = _checked_optional_iso(receipt.get("completedAt"), "worker-lease-completed-invalid", blockers)
+    if acquired and expires and acquired > expires:
+        blockers.append({"code": "worker-lease-window-invalid"})
+    if heartbeat and acquired and heartbeat < acquired:
+        blockers.append({"code": "worker-lease-heartbeat-before-acquire"})
+    if completed and acquired and completed < acquired:
+        blockers.append({"code": "worker-lease-completed-before-acquire"})
+    if expires and observed:
+        expected_status = "completed" if completed else "expired" if observed > expires else "active"
+        if lease_status != expected_status:
+            blockers.append({"code": "worker-lease-status-mismatch", "expected": expected_status, "actual": lease_status})
+    _check_string_list(receipt.get("evidenceIds", []), "worker-lease-evidence-ids", blockers, allow_empty=True)
+    if not isinstance(receipt.get("metadata", {}), dict):
+        blockers.append({"code": "worker-lease-metadata-invalid"})
+    _check_object_list(receipt.get("blockers", []), "worker-lease-blockers-invalid", blockers)
+    if receipt.get("productionPromotionClaimed") is not False:
+        blockers.append({"code": "worker-lease-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": "worker-lease-receipt-digest-mismatch"})
+    body = {
+        "schemaVersion": WORKER_LEASE_RECEIPT_VALIDATION_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "receiptStatus": status if isinstance(status, str) else None,
+        "workerId": receipt.get("workerId") if isinstance(receipt.get("workerId"), str) else None,
+        "leaseId": receipt.get("leaseId") if isinstance(receipt.get("leaseId"), str) else None,
+        "taskId": receipt.get("taskId") if isinstance(receipt.get("taskId"), str) else None,
+        "leaseStatus": lease_status if isinstance(lease_status, str) else None,
+        "blockers": blockers,
+        "receiptDigest": receipt.get("receiptDigest"),
+    }
+    return {**body, "validationDigest": canonical_digest(body)}
+
+
+def require_worker_lease_receipt_pass(validation: dict[str, Any]) -> dict[str, Any]:
+    if validation.get("status") != "PASS" or validation.get("receiptStatus") != "PASS":
+        raise LifecycleError("worker-lease-validation-failed", "worker lease receipt did not pass", {"validation": validation})
+    return validation
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _parse_iso(value: str, *, label: str, code: str) -> datetime:
+    if not isinstance(value, str) or not value:
+        raise LifecycleError(code, f"{label} must be an ISO timestamp")
+    normalized = value.replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError as exc:
+        raise LifecycleError(code, f"{label} must be an ISO timestamp") from exc
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def _iso(value: str, *, label: str, code: str) -> str:
+    _parse_iso(value, label=label, code=code)
+    return value
+
+
+def _optional_iso(value: str | None, *, label: str, code: str) -> str | None:
+    if value is None:
+        return None
+    return _iso(value, label=label, code=code)
+
+
+def _checked_iso(value: Any, code: str, blockers: list[dict[str, Any]]) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        blockers.append({"code": code})
+        return None
+    try:
+        return _parse_iso(value, label=code, code=code)
+    except LifecycleError:
+        blockers.append({"code": code})
+        return None
+
+
+def _checked_optional_iso(value: Any, code: str, blockers: list[dict[str, Any]]) -> datetime | None:
+    if value is None:
+        return None
+    return _checked_iso(value, code, blockers)
+
+
+def _lineage(value: dict[str, Any], *, code: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError(code, "lineage must be an object")
+    return {key: value[key] for key in LINEAGE_KEYS if key in value}
+
+
+def _checked_lineage(value: Any, blockers: list[dict[str, Any]]) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        blockers.append({"code": "worker-lease-lineage-missing"})
+        return None
+    for key in ("runId", "packageId", "planDigest", "sourceRevision"):
+        if not isinstance(value.get(key), str) or not value[key]:
+            blockers.append({"code": "worker-lease-lineage-field-missing", "field": key})
+    if not isinstance(value.get("planRevision"), int) or isinstance(value.get("planRevision"), bool) or value.get("planRevision") < 1:
+        blockers.append({"code": "worker-lease-lineage-plan-revision-invalid"})
+    return value
+
+
+def _compare_lineage(actual: dict[str, Any], expected: dict[str, Any], blockers: list[dict[str, Any]]) -> None:
+    for key in LINEAGE_KEYS:
+        if key in expected and actual.get(key) != expected.get(key):
+            blockers.append({"code": "worker-lease-lineage-mismatch", "field": key})
+
+
+def _required_string(value: Any, *, label: str, code: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise LifecycleError(code, f"{label} is required")
+    return value
+
+
+def _string_list(value: Any, *, label: str, code: str, allow_empty: bool = False) -> list[str]:
+    if not isinstance(value, list) or (not allow_empty and not value) or not all(isinstance(item, str) and item for item in value):
+        raise LifecycleError(code, f"{label} must be a list of strings")
+    return list(value)
+
+
+def _check_string_list(value: Any, code: str, blockers: list[dict[str, Any]], *, allow_empty: bool = False) -> None:
+    if not isinstance(value, list) or (not allow_empty and not value) or not all(isinstance(item, str) and item for item in value):
+        blockers.append({"code": code})
+
+
+def _check_object_list(value: Any, code: str, blockers: list[dict[str, Any]]) -> None:
+    if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
+        blockers.append({"code": code})

agent_lifecycle/workflow/lineage.py

@@ -0,0 +1,108 @@
+"""Shared workflow and release lineage checks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import canonical_digest
+
+
+def check_lineage(
+    manifest: dict[str, Any],
+    *,
+    state: dict[str, Any] | None = None,
+    task_packet_index: dict[str, Any] | None = None,
+    final_audit: dict[str, Any] | None = None,
+    final_proof: dict[str, Any] | None = None,
+    release_inventory: dict[str, Any] | None = None,
+    lock: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Compare frozen-plan identity across workflow and release artifacts."""
+
+    package = manifest.get("package", {})
+    expected = {
+        "packageId": package.get("id"),
+        "planRevision": manifest.get("planRevision"),
+        "planDigest": canonical_digest(manifest),
+    }
+    checks: list[dict[str, Any]] = []
+    _compare(checks, "manifest.packageId", expected["packageId"], package.get("id"))
+    _compare(checks, "manifest.planRevision", expected["planRevision"], manifest.get("planRevision"))
+    _compare(checks, "manifest.planDigest", expected["planDigest"], expected["planDigest"])
+    if lock is not None:
+        _compare(checks, "lock.packageId", expected["packageId"], lock.get("packageId"), optional_actual=True)
+        _compare(checks, "lock.planRevision", expected["planRevision"], lock.get("planRevision"))
+        _compare(checks, "lock.manifestHash", expected["planDigest"], lock.get("manifestHash"))
+    if state is not None:
+        _compare_artifact(checks, "state", expected, state)
+        _compare_required_tasks(checks, manifest, state)
+    if task_packet_index is not None:
+        _compare(checks, "taskPacketIndex.packageId", expected["packageId"], task_packet_index.get("packageId"), optional_actual=True)
+        _compare(checks, "taskPacketIndex.manifestDigest", expected["planDigest"], task_packet_index.get("manifestDigest"))
+    if final_audit is not None:
+        _compare_artifact(checks, "finalAudit", expected, final_audit, package_optional=True)
+    if final_proof is not None:
+        _compare_artifact(checks, "finalProof", expected, final_proof, package_optional=True)
+    if release_inventory is not None:
+        _compare_artifact(checks, "releaseInventory", expected, release_inventory, package_optional=True)
+    status = "PASS" if all(item["status"] == "PASS" for item in checks) else "FAIL"
+    return {
+        "schemaVersion": "agent-workflow-lineage-check.v1",
+        "status": status,
+        "packageId": expected["packageId"],
+        "planRevision": expected["planRevision"],
+        "planDigest": expected["planDigest"],
+        "lineageChecks": checks,
+    }
+
+
+def _compare_artifact(
+    checks: list[dict[str, Any]],
+    prefix: str,
+    expected: dict[str, Any],
+    artifact: dict[str, Any],
+    *,
+    package_optional: bool = False,
+) -> None:
+    _compare(
+        checks,
+        f"{prefix}.packageId",
+        expected["packageId"],
+        artifact.get("packageId"),
+        optional_actual=package_optional,
+    )
+    _compare(checks, f"{prefix}.planRevision", expected["planRevision"], artifact.get("planRevision"))
+    _compare(checks, f"{prefix}.planDigest", expected["planDigest"], artifact.get("planDigest"))
+
+
+def _compare_required_tasks(
+    checks: list[dict[str, Any]],
+    manifest: dict[str, Any],
+    state: dict[str, Any],
+) -> None:
+    expected = sorted(
+        str(item.get("id"))
+        for item in manifest.get("workstreams", [])
+        if isinstance(item, dict) and item.get("required", True)
+    )
+    actual = sorted(
+        str(item.get("id"))
+        for item in state.get("tasks", [])
+        if isinstance(item, dict) and item.get("required", True)
+    )
+    _compare(checks, "requiredTaskSet", expected, actual)
+
+
+def _compare(
+    checks: list[dict[str, Any]],
+    check_id: str,
+    expected: Any,
+    actual: Any,
+    *,
+    optional_actual: bool = False,
+) -> None:
+    if optional_actual and actual is None:
+        checks.append({"id": check_id, "status": "PASS", "expected": expected, "actual": actual, "skipped": True})
+        return
+    status = "PASS" if actual == expected else "FAIL"
+    checks.append({"id": check_id, "status": status, "expected": expected, "actual": actual})

agent_lifecycle/workflow/managed_runner.py

@@ -0,0 +1,167 @@
+"""Managed workflow step-function.
+
+This module is intentionally read-only. It checks the frozen plan and durable
+workflow state, then returns the next host action as a typed receipt. Host
+adapters remain responsible for launching model/tool work.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object
+from agent_lifecycle.freeze import verify_plan_lock
+from agent_lifecycle.workflow.next_action import MODEL_CALLS_STARTED, build_managed_next_action
+from agent_lifecycle.workflow.implementation_audit_gate import implementation_audit_blockers
+from agent_lifecycle.workflow.state import load_state, state_identity
+
+
+def run_managed_lifecycle_step(
+    *,
+    state_path: Path,
+    manifest_path: Path,
+    operation_id: str,
+    expected_revision: int,
+    source_revision: str,
+    lock_path: Path | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    blockers: list[dict[str, Any]] = []
+    manifest: dict[str, Any] | None = None
+    lock: dict[str, Any] | None = None
+    state: dict[str, Any] | None = None
+    next_action: dict[str, Any] | None = None
+
+    try:
+        manifest = read_json_object(manifest_path, label="frozen plan manifest")
+        _require_frozen_manifest(manifest)
+        lock = _load_lock(manifest_path, lock_path)
+        verify_plan_lock(manifest, lock)
+    except LifecycleError as exc:
+        blockers.append(_blocker(exc.code, exc.message, exc.details))
+
+    try:
+        state = load_state(state_path)
+        _require_state_lineage(
+            state,
+            manifest=manifest,
+            expected_revision=expected_revision,
+            source_revision=source_revision,
+        )
+        if not blockers:
+            next_action = build_managed_next_action(state)
+            audit_blockers = implementation_audit_blockers(state_path, state)
+            if audit_blockers:
+                blockers.extend(audit_blockers)
+                next_action = None
+    except LifecycleError as exc:
+        blockers.append(_blocker(exc.code, exc.message, exc.details))
+
+    status = "FAIL" if blockers else "PASS"
+    body = {
+        "schemaVersion": "agent-managed-lifecycle-runner-receipt.v1",
+        "status": status,
+        "operationId": operation_id,
+        "reason": reason,
+        "expectedRevision": expected_revision,
+        "sourceRevision": source_revision,
+        "state": _state_summary(state_path, state),
+        "plan": _plan_summary(manifest, manifest_path),
+        "nextAction": next_action or _blocked_next_action(blockers),
+        "blockers": blockers,
+        "modelCallsStarted": MODEL_CALLS_STARTED,
+        "stateWritten": False,
+        "hostLaunchStarted": False,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def _load_lock(manifest_path: Path, lock_path: Path | None) -> dict[str, Any]:
+    path = lock_path or manifest_path.with_name("plan.lock.json")
+    return read_json_object(path, label="plan lock")
+
+
+def _require_frozen_manifest(manifest: dict[str, Any]) -> None:
+    if manifest.get("status") != "FROZEN":
+        raise LifecycleError("plan-not-frozen", "managed lifecycle run requires a FROZEN plan")
+    revision = manifest.get("planRevision")
+    if not isinstance(revision, int) or isinstance(revision, bool) or revision < 1:
+        raise LifecycleError("invalid-plan-manifest", "planRevision must be a positive integer")
+
+
+def _require_state_lineage(
+    state: dict[str, Any],
+    *,
+    manifest: dict[str, Any] | None,
+    expected_revision: int,
+    source_revision: str,
+) -> None:
+    if state["stateRevision"] != expected_revision:
+        raise LifecycleError(
+            "state-revision-mismatch",
+            "workflow state revision mismatch",
+            {"expected": expected_revision, "actual": state["stateRevision"]},
+        )
+    if state.get("sourceRevision") != source_revision:
+        raise LifecycleError("source-revision-mismatch", "source revision mismatch")
+    if manifest is None:
+        return
+    package = manifest.get("package", {}) if isinstance(manifest.get("package"), dict) else {}
+    package_id = package.get("id")
+    if isinstance(package_id, str) and state.get("packageId") != package_id:
+        raise LifecycleError("package-id-mismatch", "workflow state packageId does not match manifest")
+    if state.get("planRevision") != manifest.get("planRevision"):
+        raise LifecycleError("plan-revision-mismatch", "workflow state planRevision does not match manifest")
+    digest = canonical_digest(manifest)
+    if state.get("planDigest") != digest:
+        raise LifecycleError("plan-digest-mismatch", "workflow state planDigest does not match manifest")
+
+
+def _state_summary(state_path: Path, state: dict[str, Any] | None) -> dict[str, Any] | None:
+    if state is None:
+        return None
+    return {
+        **state_identity(state_path, state),
+        "runId": state.get("runId"),
+        "packageId": state.get("packageId"),
+        "planRevision": state.get("planRevision"),
+        "planDigest": state.get("planDigest"),
+        "phase": state.get("phase"),
+    }
+
+
+def _plan_summary(manifest: dict[str, Any] | None, manifest_path: Path) -> dict[str, Any] | None:
+    if manifest is None:
+        return None
+    package = manifest.get("package", {}) if isinstance(manifest.get("package"), dict) else {}
+    return {
+        "path": manifest_path.as_posix(),
+        "packageId": package.get("id"),
+        "planRevision": manifest.get("planRevision"),
+        "planDigest": canonical_digest(manifest),
+        "status": manifest.get("status"),
+    }
+
+
+def _blocked_next_action(blockers: list[dict[str, Any]]) -> dict[str, Any]:
+    action = {
+        "schemaVersion": "agent-managed-lifecycle-next-action.v1",
+        "type": "blocked",
+        "status": "BLOCKED",
+        "hostActionRequired": False,
+        "modelCallsStarted": MODEL_CALLS_STARTED,
+        "stateMutationRequired": False,
+        "projectedAction": None,
+        "taskIds": [],
+        "blockers": blockers,
+    }
+    return {**action, "actionDigest": canonical_digest(action)}
+
+
+def _blocker(code: str, message: str, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    blocker: dict[str, Any] = {"code": code, "message": message}
+    if context:
+        blocker["context"] = context
+    return blocker