okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -14,6 +14,8 @@ import re
 import tempfile
 from typing import Iterator, Literal, Mapping, get_args
 
+from .domain.role import RoleCatalogError, role_for_duty
+
 
 AgentAudience = Literal[
     "lead",
@@ -79,6 +81,15 @@ _TOP_LEVEL_KEYS = {
     "prompt",
     "digests",
 }
+_V2_TOP_LEVEL_KEYS = (_TOP_LEVEL_KEYS - {"workerId"}) | {
+    "executionIdentityVersion",
+    "invocationRef",
+    "participantRef",
+    "roleExecutionRef",
+    "executionLabel",
+    "dutyId",
+    "attempt",
+}
 _NESTED_KEYS = {
     "contractSource": {"mode", "runManifestPath", "dutyRootPath"},
     "modelAssignment": {
@@ -130,6 +141,24 @@ class AgentModelAssignment:
     host_model_value: str | None
 
 
+@dataclass(frozen=True)
+class InvocationExecutionIdentity:
+    participant_ref: str
+    role_execution_ref: str
+    execution_label: str
+    duty_id: str
+
+
+@dataclass(frozen=True)
+class InvocationMetadataIdentity:
+    invocation_ref: str
+    participant_ref: str
+    role_execution_ref: str
+    execution_label: str
+    duty_id: str
+    attempt: int
+
+
 @dataclass(frozen=True)
 class AgentInstructionSource:
     kind: Literal["project", "runtime"]
@@ -158,6 +187,11 @@ class AgentInvocationRequest:
     prompt_path: Path
     metadata_path: Path
     dispatch_kind: str
+    participant_ref: str | None
+    role_execution_ref: str | None
+    duty_id: str | None
+    invocation_ref: str | None
+    attempt: int
     # Republish a prompt this invocation id already wrote, but only while no
     # dispatch has used it. See `_publish_or_reuse`.
     replace_undispatched: bool = False
@@ -178,6 +212,10 @@ class PreparedAgentInvocation:
     duty_digest: str
     instruction_digest: str
     prompt_digest: str
+    participant_ref: str | None = None
+    role_execution_ref: str | None = None
+    invocation_ref: str | None = None
+    attempt: int = 1
 
 
 @dataclass(frozen=True)
@@ -189,6 +227,15 @@ class MaterializedStandaloneResult:
     result_envelope_digest: str
 
 
+@dataclass(frozen=True)
+class RetryAgentInvocation:
+    invocation_id: str
+    invocation_ref: str
+    prompt_path: Path
+    metadata_path: Path
+    attempt: int
+
+
 @dataclass(frozen=True)
 class VerifiedStandaloneResult:
     purpose: str
@@ -228,6 +275,201 @@ def agent_model_assignment_from_payload(payload: object) -> AgentModelAssignment
     return assignment
 
 
+def invocation_execution_identity_from_manifest(
+    manifest: Mapping[str, object],
+    *,
+    assignment: AgentModelAssignment,
+    assignment_ref: str,
+    duty_id: str,
+    role_execution_ref: str | None = None,
+) -> InvocationExecutionIdentity | None:
+    """Resolve v2 refs from Task 8 without duplicating them in model assignments."""
+    schema = manifest.get("schemaVersion")
+    identity_version = manifest.get("executionIdentityVersion")
+    if schema in (None, 1, "1", "1.0") and identity_version is None:
+        return None
+    if schema != "2.0" or identity_version != 2:
+        raise AgentInvocationError("run manifest mixes v1 and v2 execution identity")
+    try:
+        role = role_for_duty(duty_id)
+    except RoleCatalogError as exc:
+        raise AgentInvocationError(str(exc)) from exc
+    role_executions = manifest.get("roleExecutions")
+    candidates = [
+        row for row in role_executions
+        if isinstance(row, Mapping)
+        and row.get("role") == role
+        and row.get("provider") == assignment.provider
+        and _role_execution_matches_assignment(row, assignment)
+    ] if isinstance(role_executions, list) else []
+    if role_execution_ref is None:
+        selected = _select_role_execution_candidate(
+            manifest,
+            candidates,
+            assignment_ref=assignment_ref,
+            role=role,
+            assignment=assignment,
+        )
+    else:
+        selected = next(
+            (
+                row
+                for row in candidates
+                if row.get("roleExecutionRef") == role_execution_ref
+            ),
+            None,
+        )
+    if selected is None:
+        raise AgentInvocationError(
+            "v2 execution identity does not match a canonical role execution"
+        )
+    return InvocationExecutionIdentity(
+        participant_ref=_required_metadata_string(selected, "participantRef"),
+        role_execution_ref=_required_metadata_string(selected, "roleExecutionRef"),
+        execution_label=_required_metadata_string(selected, "executionLabel"),
+        duty_id=duty_id,
+    )
+
+
+def v2_role_assignment_authority_errors(
+    manifest: Mapping[str, object],
+    *,
+    role_execution_ref: str,
+    participant_ref: str,
+    assignment: AgentModelAssignment,
+) -> list[str]:
+    """Compare one v2 role and participant with the provider-neutral assignment."""
+    role_executions = manifest.get("roleExecutions")
+    execution = next((
+        row for row in role_executions
+        if isinstance(row, Mapping)
+        and row.get("roleExecutionRef") == role_execution_ref
+    ), None) if isinstance(role_executions, list) else None
+    participants = manifest.get("participantAssignments")
+    participant = next((
+        row for row in participants
+        if isinstance(row, Mapping)
+        and row.get("participantRef") == participant_ref
+    ), None) if isinstance(participants, list) else None
+    if not isinstance(execution, Mapping) or not isinstance(participant, Mapping):
+        return ["v2 assignment does not reference canonical execution identity"]
+    errors: list[str] = []
+    if participant.get("hostModelValue") != assignment.host_model_value:
+        errors.append(
+            "participant hostModelValue does not match invocation metadata"
+        )
+    if (
+        participant.get("hostRuntime") != assignment.host_runtime
+        or (
+            manifest.get("leadRuntime") is not None
+            and participant.get("hostRuntime") != manifest.get("leadRuntime")
+        )
+    ):
+        errors.append(
+            "participant hostRuntime does not match invocation metadata"
+        )
+    binding = execution.get("binding")
+    binding_matches = (
+        isinstance(binding, Mapping)
+        and binding.get("runner") == assignment.runner
+        and binding.get("resolvedExecutionValue")
+        == assignment.model_execution_value
+        and binding.get("hostModelValue") == assignment.host_model_value
+        and binding.get("hostModelValue") == participant.get("hostModelValue")
+        and binding.get("workerWriteCapability")
+        == participant.get("workerWriteCapability")
+        and participant.get("runner") == binding.get("runner")
+    ) or (
+        binding is None
+        and assignment.model_execution_value == "unknown"
+        and participant.get("runner") == assignment.runner
+    )
+    if (
+        execution.get("participantRef") != participant_ref
+        or execution.get("provider") != assignment.provider
+        or execution.get("provider") != participant.get("provider")
+        or execution.get("modelRef") != participant.get("modelRef")
+        or execution.get("modelId") != assignment.model
+        or execution.get("modelId") != participant.get("modelId")
+        or not binding_matches
+    ):
+        errors.append("v2 assignment does not match role execution authority")
+    return errors
+
+
+def _role_execution_matches_assignment(
+    row: Mapping[str, object], assignment: AgentModelAssignment,
+) -> bool:
+    binding = row.get("binding")
+    if isinstance(binding, Mapping):
+        return binding.get("resolvedExecutionValue") == assignment.model_execution_value
+    return assignment.model_execution_value == "unknown"
+
+
+def _select_role_execution_candidate(
+    manifest: Mapping[str, object],
+    candidates: list[Mapping[str, object]],
+    *,
+    assignment_ref: str,
+    role: str,
+    assignment: AgentModelAssignment,
+) -> Mapping[str, object] | None:
+    if len(candidates) == 1:
+        return candidates[0]
+    if not assignment_ref.startswith("initial/"):
+        return None
+    worker_id = assignment_ref.partition("/")[2]
+    workers = manifest.get("workerAssignments")
+    matching_workers = [
+        row for row in workers
+        if isinstance(row, Mapping)
+        and row.get("role") == role
+        and row.get("provider") == assignment.provider
+        and row.get("modelExecutionValue") == assignment.model_execution_value
+    ] if isinstance(workers, list) else []
+    worker_index = next((
+        index for index, row in enumerate(matching_workers)
+        if row.get("workerId") == worker_id
+    ), None)
+    ordered = sorted(candidates, key=lambda row: int(row.get("ordinal", 0)))
+    if worker_index is None or worker_index >= len(ordered):
+        return None
+    return ordered[worker_index]
+
+
+def _required_metadata_string(
+    payload: Mapping[str, object], key: str,
+) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value:
+        raise AgentInvocationError(f"v2 execution identity field is invalid: {key}")
+    return value
+
+
+def invocation_metadata_identity(
+    payload: Mapping[str, object],
+) -> InvocationMetadataIdentity | None:
+    """Read one exact metadata version without guessing from partial fields."""
+    schema = payload.get("schemaVersion")
+    identity_version = payload.get("executionIdentityVersion")
+    if schema == 1 and identity_version is None:
+        if not _metadata_schema_is_exact(payload):
+            raise AgentInvocationError("agent invocation metadata schema is invalid")
+        return None
+    if schema != "2.0" or identity_version != 2:
+        raise AgentInvocationError("agent invocation metadata mixes v1 and v2 identity")
+    if not _metadata_schema_is_exact(payload):
+        raise AgentInvocationError("v2 execution identity metadata is invalid")
+    return InvocationMetadataIdentity(
+        invocation_ref=payload["invocationRef"],
+        participant_ref=payload["participantRef"],
+        role_execution_ref=payload["roleExecutionRef"],
+        execution_label=payload["executionLabel"],
+        duty_id=payload["dutyId"],
+        attempt=payload["attempt"],
+    )
+
+
 @dataclass(frozen=True)
 class _MaterializedInvocation:
     prepared: PreparedAgentInvocation
@@ -307,18 +549,132 @@ def prepare_agent_invocation(
         expected_worker_id=request.worker_id,
         expected_assignment_ref=request.assignment_ref,
         expected_audience=request.audience,
+        expected_participant_ref=request.participant_ref,
+        expected_role_execution_ref=request.role_execution_ref,
+        expected_invocation_ref=request.invocation_ref,
     )
     if errors:
         raise AgentInvocationError("; ".join(errors))
     return materialized.prepared
 
 
+def materialize_retry_invocation(
+    metadata_path: Path,
+    *,
+    project_root: Path,
+    attempt: int,
+) -> RetryAgentInvocation:
+    """Publish an attempt-specific prompt/metadata pair for one v2 retry."""
+    metadata = _load_json_object(metadata_path, "agent invocation metadata")
+    identity = invocation_metadata_identity(metadata)
+    if identity is None:
+        raise AgentInvocationError("v1 invocation metadata cannot be retried as v2")
+    if attempt != identity.attempt + 1:
+        raise AgentInvocationError(
+            f"retry attempt must be {identity.attempt + 1}"
+        )
+    source = metadata.get("contractSource")
+    prompt_spec = metadata.get("prompt")
+    if not isinstance(source, dict) or not isinstance(prompt_spec, dict):
+        raise AgentInvocationError("retry invocation metadata is incomplete")
+    manifest_path = _project_path(
+        project_root, source.get("runManifestPath"), must_exist=True
+    )
+    prompt_path = _project_path(
+        project_root, prompt_spec.get("path"), must_exist=True
+    )
+    retry_prompt_path = prompt_path.with_name(
+        f"{prompt_path.stem}-attempt-{attempt}{prompt_path.suffix}"
+    )
+    retry_metadata_path = retry_prompt_path.with_name(
+        retry_prompt_path.name + ".meta.json"
+    )
+    retry_invocation_id = f"{metadata['invocationId']}-attempt-{attempt}"
+    retry_metadata = dict(metadata)
+    retry_metadata["invocationId"] = retry_invocation_id
+    retry_metadata["attempt"] = attempt
+    retry_metadata["prompt"] = {
+        "path": _project_relative(
+            retry_prompt_path, project_root, must_exist=False
+        )
+    }
+    manifest = _load_json_object(manifest_path, "run manifest")
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, dict):
+        raise AgentInvocationError("run manifest has no agent contract")
+    reservation_root = _project_path(
+        project_root,
+        contract.get("invocationReservationRootPath"),
+        must_exist=True,
+    )
+    reservation = {
+        "schemaVersion": "2.0",
+        "executionIdentityVersion": 2,
+        "invocationId": retry_invocation_id,
+        "assignmentRef": metadata["assignmentRef"],
+        "audience": metadata["audience"],
+        "dispatchKind": metadata["dispatchKind"],
+        "promptPath": retry_metadata["prompt"]["path"],
+        "metadataPath": _project_relative(
+            retry_metadata_path, project_root, must_exist=False
+        ),
+        "invocationRef": identity.invocation_ref,
+        "participantRef": identity.participant_ref,
+        "roleExecutionRef": identity.role_execution_ref,
+        "dutyId": identity.duty_id,
+        "attempt": attempt,
+    }
+    with _exclusive_lock(reservation_root / "publish.lock"):
+        _publish_or_reuse_exact(
+            reservation_root / f"{retry_invocation_id}.json",
+            _pretty_json(reservation),
+        )
+        with _exclusive_lock(_prompt_lock_path(retry_prompt_path)):
+            _publish_or_reuse_exact(retry_prompt_path, prompt_path.read_bytes())
+            _publish_or_reuse_exact(
+                retry_metadata_path, _pretty_json(retry_metadata)
+            )
+    errors = verify_agent_invocation(
+        retry_metadata_path,
+        project_root=project_root,
+        expected_run_manifest_path=manifest_path,
+        expected_assignment=agent_model_assignment_from_payload(
+            metadata["modelAssignment"]
+        ),
+        expected_invocation_id=retry_invocation_id,
+        expected_assignment_ref=str(metadata["assignmentRef"]),
+        expected_audience=str(metadata["audience"]),
+        expected_participant_ref=identity.participant_ref,
+        expected_role_execution_ref=identity.role_execution_ref,
+        expected_invocation_ref=identity.invocation_ref,
+    )
+    if errors:
+        raise AgentInvocationError("; ".join(errors))
+    return RetryAgentInvocation(
+        invocation_id=retry_invocation_id,
+        invocation_ref=identity.invocation_ref,
+        prompt_path=retry_prompt_path,
+        metadata_path=retry_metadata_path,
+        attempt=attempt,
+    )
+
+
 def compose_agent_prompt(request: AgentInvocationRequest) -> str:
     """Render and validate a prompt candidate without publishing artifacts."""
     _validate_request(request)
     return _materialize(request).prompt_bytes.decode("utf-8")
 
 
+def compose_unbound_run_prompt(request: AgentInvocationRequest) -> bytes:
+    """Compose v2 run prompt bytes before a dynamic role identity is reserved."""
+    _validate_common_request(request)
+    _validate_unbound_v2_run_request(request)
+    common = load_common_duty_contract(request.duty_root)
+    catalog = load_duty_catalog(request.duty_root)
+    duty = catalog[request.audience]
+    return _render_prompt(request, common, duty).encode("utf-8")
+
+
 def verify_agent_invocation(
     metadata_path: Path,
     *,
@@ -329,6 +685,9 @@ def verify_agent_invocation(
     expected_worker_id: str | None = None,
     expected_assignment_ref: str | None = None,
     expected_audience: AgentAudience | None = None,
+    expected_participant_ref: str | None = None,
+    expected_role_execution_ref: str | None = None,
+    expected_invocation_ref: str | None = None,
 ) -> list[str]:
     """Return every deterministic violation found in a published invocation."""
     metadata = _read_metadata(metadata_path)
@@ -340,6 +699,9 @@ def verify_agent_invocation(
         expected_worker_id=expected_worker_id,
         expected_assignment_ref=expected_assignment_ref,
         expected_audience=expected_audience,
+        expected_participant_ref=expected_participant_ref,
+        expected_role_execution_ref=expected_role_execution_ref,
+        expected_invocation_ref=expected_invocation_ref,
     )
     errors.extend(_verify_prompt_file(metadata, project_root))
     errors.extend(_verify_assignment(metadata, expected_assignment))
@@ -618,6 +980,8 @@ def _materialize(request: AgentInvocationRequest) -> _MaterializedInvocation:
     common = load_common_duty_contract(request.duty_root)
     catalog = load_duty_catalog(request.duty_root)
     duty = catalog[request.audience]
+    if _request_identity_version(request) == 2 and request.duty_id != duty.id:
+        raise AgentInvocationError("v2 execution identity duty does not match audience")
     prompt_bytes = _render_prompt(request, common, duty).encode("utf-8")
     digests = _invocation_digests(request, duty, prompt_bytes)
     metadata = _metadata_payload(request, duty, digests)
@@ -635,6 +999,10 @@ def _materialize(request: AgentInvocationRequest) -> _MaterializedInvocation:
         duty_digest=digests["dutyDigest"],
         instruction_digest=digests["instructionDigest"],
         prompt_digest=digests["promptDigest"],
+        participant_ref=request.participant_ref,
+        role_execution_ref=request.role_execution_ref,
+        invocation_ref=request.invocation_ref,
+        attempt=request.attempt,
     )
     reservation_root, reservation = _reservation_spec(request)
     return _MaterializedInvocation(
@@ -648,6 +1016,14 @@ def _materialize(request: AgentInvocationRequest) -> _MaterializedInvocation:
 
 
 def _validate_request(request: AgentInvocationRequest) -> None:
+    _validate_common_request(request)
+    if request.run_manifest_path is None:
+        _validate_standalone_identity(request)
+    else:
+        _validate_run_identity(request)
+
+
+def _validate_common_request(request: AgentInvocationRequest) -> None:
     if request.audience not in _SUPPORTED_AUDIENCES:
         raise AgentInvocationError(f"unknown duty audience: {request.audience}")
     adjacent = request.prompt_path.with_name(request.prompt_path.name + ".meta.json")
@@ -658,10 +1034,35 @@ def _validate_request(request: AgentInvocationRequest) -> None:
     _project_relative(request.duty_root, request.project_root, must_exist=True)
     _project_relative(request.prompt_path, request.project_root, must_exist=False)
     _project_relative(request.metadata_path, request.project_root, must_exist=False)
-    if request.run_manifest_path is None:
-        _validate_standalone_identity(request)
-    else:
-        _validate_run_identity(request)
+
+
+def _validate_unbound_v2_run_request(request: AgentInvocationRequest) -> None:
+    if request.run_manifest_path is None or request.purpose is not None:
+        raise AgentInvocationError("unbound prompt requires a run invocation")
+    if _request_identity_version(request) != 2:
+        raise AgentInvocationError("unbound prompt requires v2 execution identity")
+    if not request.assignment_ref:
+        raise AgentInvocationError("run assignment reference is required")
+    if any((
+        request.participant_ref,
+        request.role_execution_ref,
+        request.duty_id,
+        request.invocation_ref,
+    )):
+        raise AgentInvocationError("unbound prompt cannot carry execution identity")
+    if not request.worker_id or not _SLUG_RE.fullmatch(request.worker_id):
+        raise AgentInvocationError("run worker ID must be a non-empty slug")
+    suffix = request.assignment_ref.partition("/")[2]
+    if suffix and request.assignment_ref.split("/", 1)[0] in {"initial", "reverify"}:
+        if suffix != request.worker_id:
+            raise AgentInvocationError(
+                "run worker ID does not match assignment reference"
+            )
+    manifest = _load_json_object(request.run_manifest_path, "run manifest")
+    contract = manifest.get("agentContract")
+    if not isinstance(contract, Mapping):
+        raise AgentInvocationError("run manifest has no agent contract")
+    _validate_manifest_contract(request, manifest, contract)
 
 
 def _validate_assignment(assignment: AgentModelAssignment) -> None:
@@ -697,6 +1098,13 @@ def _validate_standalone_identity(request: AgentInvocationRequest) -> None:
         raise AgentInvocationError("standalone invocation ID must be a slug")
     if request.worker_id is not None or request.assignment_ref is not None:
         raise AgentInvocationError("standalone invocation cannot bind a run worker")
+    if any((
+        request.participant_ref,
+        request.role_execution_ref,
+        request.duty_id,
+        request.invocation_ref,
+    )):
+        raise AgentInvocationError("standalone invocation cannot bind v2 execution identity")
     root = (
         request.project_root
         / ".okstra"
@@ -712,8 +1120,6 @@ def _validate_standalone_identity(request: AgentInvocationRequest) -> None:
 def _validate_run_identity(request: AgentInvocationRequest) -> None:
     if request.purpose is not None:
         raise AgentInvocationError("run invocation cannot define standalone purpose")
-    if not request.worker_id or not _SLUG_RE.fullmatch(request.worker_id):
-        raise AgentInvocationError("run worker ID must be a non-empty slug")
     if not request.assignment_ref:
         raise AgentInvocationError("run assignment reference is required")
     _project_relative(
@@ -721,12 +1127,74 @@ def _validate_run_identity(request: AgentInvocationRequest) -> None:
         request.project_root,
         must_exist=True,
     )
+    if _request_identity_version(request) == 2:
+        _validate_v2_run_identity(request)
+        return
+    if any((
+        request.participant_ref,
+        request.role_execution_ref,
+        request.duty_id,
+        request.invocation_ref,
+    )):
+        raise AgentInvocationError("v1 run invocation cannot bind v2 execution identity")
+    if not request.worker_id or not _SLUG_RE.fullmatch(request.worker_id):
+        raise AgentInvocationError("run worker ID must be a non-empty slug")
     suffix = request.assignment_ref.partition("/")[2]
     if suffix and request.assignment_ref.split("/", 1)[0] in {"initial", "reverify"}:
         if suffix != request.worker_id:
             raise AgentInvocationError("run worker ID does not match assignment reference")
 
 
+def _request_identity_version(request: AgentInvocationRequest) -> int:
+    if request.run_manifest_path is None:
+        return 1
+    manifest = _load_json_object(request.run_manifest_path, "run manifest")
+    schema = manifest.get("schemaVersion")
+    identity = manifest.get("executionIdentityVersion")
+    if schema == "2.0" and identity == 2:
+        return 2
+    if schema == "2.0" or identity is not None:
+        raise AgentInvocationError("run manifest mixes v1 and v2 execution identity")
+    if schema not in (None, 1, "1", "1.0"):
+        raise AgentInvocationError("run manifest execution identity version is unsupported")
+    return 1
+
+
+def _validate_v2_run_identity(request: AgentInvocationRequest) -> None:
+    fields = (
+        request.participant_ref,
+        request.role_execution_ref,
+        request.duty_id,
+        request.invocation_ref,
+    )
+    if any(not isinstance(value, str) or not value.strip() for value in fields):
+        raise AgentInvocationError("v2 execution identity references are required")
+    if request.invocation_ref != request.invocation_id:
+        raise AgentInvocationError("v2 execution identity invocation reference is invalid")
+    if (
+        not isinstance(request.attempt, int)
+        or isinstance(request.attempt, bool)
+        or request.attempt < 1
+    ):
+        raise AgentInvocationError("v2 execution identity attempt must be positive")
+    manifest = _load_json_object(request.run_manifest_path, "run manifest")
+    identity = invocation_execution_identity_from_manifest(
+        manifest,
+        assignment=request.assignment,
+        assignment_ref=request.assignment_ref,
+        duty_id=request.duty_id,
+        role_execution_ref=request.role_execution_ref,
+    )
+    if (
+        identity is None
+        or identity.participant_ref != request.participant_ref
+        or identity.role_execution_ref != request.role_execution_ref
+    ):
+        raise AgentInvocationError(
+            "v2 execution identity does not match a canonical role execution"
+        )
+
+
 def _render_prompt(
     request: AgentInvocationRequest,
     common: DutyContract,
@@ -799,7 +1267,7 @@ def _metadata_payload(
         if request.run_manifest_path is not None
         else None
     )
-    return {
+    payload: dict[str, object] = {
         "schemaVersion": 1,
         "invocationId": request.invocation_id,
         "audience": request.audience,
@@ -832,6 +1300,31 @@ def _metadata_payload(
         },
         "digests": dict(digests),
     }
+    if _request_identity_version(request) == 2:
+        manifest = _load_json_object(request.run_manifest_path, "run manifest")
+        identity = invocation_execution_identity_from_manifest(
+            manifest,
+            assignment=request.assignment,
+            assignment_ref=request.assignment_ref,
+            duty_id=request.duty_id,
+            role_execution_ref=request.role_execution_ref,
+        )
+        if identity is None:
+            raise AgentInvocationError(
+                "v2 execution identity does not match a canonical role execution"
+            )
+        payload.update({
+            "schemaVersion": "2.0",
+            "executionIdentityVersion": 2,
+            "invocationRef": request.invocation_ref,
+            "participantRef": request.participant_ref,
+            "roleExecutionRef": request.role_execution_ref,
+            "executionLabel": identity.execution_label,
+            "dutyId": request.duty_id,
+            "attempt": request.attempt,
+        })
+        payload.pop("workerId")
+    return payload
 
 
 def _reservation_spec(
@@ -850,7 +1343,7 @@ def _reservation_spec(
         reservation_value,
         must_exist=False,
     )
-    reservation = {
+    reservation: dict[str, object] = {
         "schemaVersion": 1,
         "invocationId": request.invocation_id,
         "workerId": request.worker_id,
@@ -868,6 +1361,17 @@ def _reservation_spec(
             must_exist=False,
         ),
     }
+    if _request_identity_version(request) == 2:
+        reservation.update({
+            "schemaVersion": "2.0",
+            "executionIdentityVersion": 2,
+            "invocationRef": request.invocation_ref,
+            "participantRef": request.participant_ref,
+            "roleExecutionRef": request.role_execution_ref,
+            "dutyId": request.duty_id,
+            "attempt": request.attempt,
+        })
+        reservation.pop("workerId")
     return reservation_root, reservation
 
 
@@ -894,7 +1398,9 @@ def _validate_manifest_contract(
         if isinstance(assignments, dict)
         else None
     )
-    if manifest_assignment != _assignment_payload(request.assignment):
+    if _model_assignment_projection(manifest_assignment) != _assignment_payload(
+        request.assignment
+    ):
         raise AgentInvocationError("model assignment does not match run manifest")
     _validate_authorized_prompt_path(request, contract)
 
@@ -1114,6 +1620,14 @@ def _prompt_lock_path(prompt_path: Path) -> Path:
     return prompt_path.with_name(prompt_path.name + ".publish.lock")
 
 
+def _publish_or_reuse_exact(path: Path, body: bytes) -> None:
+    if path.exists():
+        if path.read_bytes() != body:
+            raise _existing_conflict(f"published path differs: {path}")
+        return
+    _publish_exclusive(path, body)
+
+
 def _publish_exclusive(path: Path, body: bytes, *, replace: bool = False) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     temp_path: Path | None = None
@@ -1150,13 +1664,20 @@ def _verify_expected_identity(
     expected_worker_id: str | None,
     expected_assignment_ref: str | None,
     expected_audience: AgentAudience | None,
+    expected_participant_ref: str | None,
+    expected_role_execution_ref: str | None,
+    expected_invocation_ref: str | None,
 ) -> list[str]:
     expected = {
         "invocationId": expected_invocation_id,
-        "workerId": expected_worker_id,
         "assignmentRef": expected_assignment_ref,
         "audience": expected_audience,
+        "participantRef": expected_participant_ref,
+        "roleExecutionRef": expected_role_execution_ref,
+        "invocationRef": expected_invocation_ref,
     }
+    if metadata.get("schemaVersion") == 1:
+        expected["workerId"] = expected_worker_id
     errors = []
     for key, value in expected.items():
         if value is not None and metadata.get(key) != value:
@@ -1371,6 +1892,8 @@ def _verify_run_manifest_contract(
     if not isinstance(allowed, list) or metadata["audience"] not in allowed:
         errors.append("audience is not allowed by run manifest")
     errors.extend(_verify_manifest_assignment(metadata, manifest))
+    if metadata.get("executionIdentityVersion") == 2:
+        errors.extend(_verify_manifest_execution_identity(metadata, manifest))
     return errors
 
 
@@ -1382,11 +1905,39 @@ def _verify_manifest_assignment(
     reference = metadata["assignmentRef"]
     if not isinstance(assignments, dict) or reference not in assignments:
         return ["assignment reference is missing from run manifest"]
-    if assignments[reference] != metadata["modelAssignment"]:
+    if _model_assignment_projection(assignments[reference]) != metadata["modelAssignment"]:
         return ["model assignment does not match run manifest"]
     return []
 
 
+def _verify_manifest_execution_identity(
+    metadata: Mapping[str, object],
+    manifest: Mapping[str, object],
+) -> list[str]:
+    if metadata["dutyContract"]["id"] != metadata["dutyId"]:
+        return ["v2 duty identity does not match duty contract"]
+    try:
+        identity = invocation_execution_identity_from_manifest(
+            manifest,
+            assignment=agent_model_assignment_from_payload(
+                metadata["modelAssignment"]
+            ),
+            assignment_ref=str(metadata["assignmentRef"]),
+            duty_id=str(metadata["dutyId"]),
+            role_execution_ref=str(metadata["roleExecutionRef"]),
+        )
+    except AgentInvocationError as exc:
+        return [str(exc)]
+    if (
+        identity is None
+        or identity.participant_ref != metadata["participantRef"]
+        or identity.role_execution_ref != metadata["roleExecutionRef"]
+        or identity.execution_label != metadata["executionLabel"]
+    ):
+        return ["v2 identity does not match a canonical role execution"]
+    return []
+
+
 def _verify_duty_snapshot(
     metadata: Mapping[str, object],
     project_root: Path,
@@ -1473,23 +2024,57 @@ def _verify_reservation(
         return ["invocation reservation is missing or invalid"]
     prompt = metadata["prompt"]
     assert isinstance(prompt, dict)
-    expected = {
+    expected: dict[str, object] = {
         "schemaVersion": 1,
         "invocationId": metadata["invocationId"],
-        "workerId": metadata["workerId"],
         "assignmentRef": metadata["assignmentRef"],
         "audience": metadata["audience"],
         "dispatchKind": metadata["dispatchKind"],
         "promptPath": prompt["path"],
         "metadataPath": f"{prompt['path']}.meta.json",
     }
+    if metadata.get("executionIdentityVersion") == 2:
+        expected.update({
+            "schemaVersion": "2.0",
+            "executionIdentityVersion": 2,
+            "invocationRef": metadata["invocationRef"],
+            "participantRef": metadata["participantRef"],
+            "roleExecutionRef": metadata["roleExecutionRef"],
+            "dutyId": metadata["dutyId"],
+            "attempt": metadata["attempt"],
+        })
+    else:
+        expected["workerId"] = metadata["workerId"]
     if actual != expected:
         return ["invocation reservation does not match invocation metadata"]
     return []
 
 
 def _metadata_schema_is_exact(metadata: Mapping[str, object]) -> bool:
-    if set(metadata) != _TOP_LEVEL_KEYS or metadata.get("schemaVersion") != 1:
+    schema = metadata.get("schemaVersion")
+    if schema == 1:
+        if set(metadata) != _TOP_LEVEL_KEYS:
+            return False
+    elif schema == "2.0":
+        if (
+            set(metadata) != _V2_TOP_LEVEL_KEYS
+            or metadata.get("executionIdentityVersion") != 2
+            or not all(
+                isinstance(metadata.get(key), str) and metadata[key]
+                for key in (
+                    "invocationRef",
+                    "participantRef",
+                    "roleExecutionRef",
+                    "executionLabel",
+                    "dutyId",
+                )
+            )
+            or not isinstance(metadata.get("attempt"), int)
+            or isinstance(metadata.get("attempt"), bool)
+            or metadata["attempt"] < 1
+        ):
+            return False
+    else:
         return False
     for key, expected_keys in _NESTED_KEYS.items():
         value = metadata.get(key)
@@ -1509,6 +2094,15 @@ def _metadata_schema_is_exact(metadata: Mapping[str, object]) -> bool:
     }
 
 
+def _model_assignment_projection(payload: object) -> dict[str, object] | None:
+    if not isinstance(payload, Mapping):
+        return None
+    keys = _NESTED_KEYS["modelAssignment"]
+    if not keys.issubset(payload):
+        return None
+    return {key: payload[key] for key in keys}
+
+
 def _digest_paths(value: object, prefix: str = "") -> set[str]:
     if not isinstance(value, dict):
         return set()