okstra 0.174.0 → 0.175.1

package/runtime/python/okstra_ctl/render.py

@@ -84,6 +84,16 @@ def _write_json(path: Path, payload: dict) -> None:
     _write_text(path, json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
 
 
+def _execution_identity(ctx: Mapping[str, object]) -> dict:
+    raw = ctx.get("EXECUTION_IDENTITY_JSON")
+    if not isinstance(raw, str) or not raw.strip():
+        return {}
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise TokenRenderError("EXECUTION_IDENTITY_JSON must contain an object")
+    return payload
+
+
 def _lead_runtime(ctx: dict) -> str:
     return ctx.get("LEAD_RUNTIME", "") or "claude-code"
 
@@ -377,10 +387,14 @@ def _agent_contract(ctx: dict) -> dict:
     return parsed
 
 
-def _executor_contract(ctx: dict) -> dict:
+def _executor_contract(ctx: dict) -> dict | None:
     runner = ctx.get("EXECUTOR_RUNNER", "")
     dispatch_mode = ctx.get("EXECUTOR_DISPATCH_MODE", "")
     host_model_value = ctx.get("EXECUTOR_HOST_MODEL_VALUE") or None
+    if not runner and not ctx.get("EXECUTOR_PROVIDER"):
+        if ctx.get("TASK_TYPE") == "implementation":
+            raise ValueError("implementation executor assignment is required")
+        return None
     expected_mode = {
         "native-session": "host-native",
         "cli-wrapper": "worker-dispatch",
@@ -1326,8 +1340,14 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
     latest_team_state_relative = pointers["latestTeamStatePath"]
     latest_resume_command_relative = pointers["latestResumeCommandPath"]
     convergence_block = _build_convergence_block(ctx)
+    execution_identity = _execution_identity(ctx)
+    existing_v2 = (
+        existing.get("schemaVersion") == "2.0"
+        and existing.get("executionIdentityVersion") == 2
+    )
+    writes_v2 = execution_identity.get("executionIdentityVersion") == 2
     payload = {
-        "schemaVersion": "1.0",
+        "schemaVersion": "2.0" if existing_v2 or writes_v2 else "1.0",
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
         "taskId": ctx.get("TASK_ID", ""),
@@ -1487,6 +1507,12 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
             "sessionId": ctx.get("CLAUDE_SESSION_ID", ""),
             "resumeCommandPath": ctx.get("CLAUDE_RESUME_COMMAND_RELATIVE_PATH", ""),
         }
+    if existing_v2 or writes_v2:
+        existing_index = existing.get("roleExecutionIndex")
+        payload["executionIdentityVersion"] = 2
+        payload["roleExecutionIndex"] = (
+            list(existing_index) if isinstance(existing_index, list) else []
+        )
     _write_json(path, payload)
 
 
@@ -1608,8 +1634,9 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         for s in str(ctx.get("CONCURRENT_RUN_STAGES", "") or "").split(",")
         if s.strip().isdigit()
     ]
+    execution_identity = _execution_identity(ctx)
     payload = {
-        "schemaVersion": "1.0",
+        "schemaVersion": execution_identity.get("schemaVersion", "1.0"),
         "okstraVersion": ctx.get("OKSTRA_VERSION", ""),
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
@@ -1783,6 +1810,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     )
     if _lead_runtime(ctx) == "claude-code":
         payload["claudeSessionId"] = ctx.get("CLAUDE_SESSION_ID", "")
+    payload.update(execution_identity)
     _guard_invocation_manifest_rewrite(existing_run_manifest, payload)
     _write_json(Path(run_manifest_path), payload)
 
@@ -1795,6 +1823,11 @@ _MODEL_ASSIGNMENT_KEYS = {
     "hostRuntime",
     "hostModelValue",
 }
+_V2_INVOCATION_IDENTITY_KEYS = {
+    "participantRef",
+    "roleExecutionRef",
+    "dutyId",
+}
 _AGENT_CONTRACT_KEYS = {
     "schemaVersion",
     "dutyRootPath",
@@ -1860,11 +1893,8 @@ def _validate_invocation_manifest(payload: Mapping[str, object]) -> None:
         or not assignments
     ):
         raise ValueError("incomplete invocation manifest")
-    if any(
-        not isinstance(item, Mapping) or set(item) != _MODEL_ASSIGNMENT_KEYS
-        for item in assignments.values()
-    ):
-        raise ValueError("incomplete invocation manifest assignments")
+    _invocation_manifest_identity_version(payload)
+    _validate_invocation_assignment_shapes(assignments)
     _validate_compatibility_projections(payload, assignments)
     for key in (
         item
@@ -1901,13 +1931,17 @@ def _validate_compatibility_projections(
     workers = payload.get("workerAssignments")
     if not isinstance(lead, Mapping) or not isinstance(workers, list):
         raise ValueError("incomplete invocation manifest compatibility projection")
-    if _model_projection(lead) != assignments.get("lead"):
+    if _model_projection(lead) != _model_projection_from_assignment(
+        assignments.get("lead")
+    ):
         raise ValueError("immutable invocation manifest lead projection drift")
     for worker in workers:
         if not isinstance(worker, Mapping):
             raise ValueError("incomplete invocation manifest worker projection")
         reference = f"initial/{worker.get('workerId', '')}"
-        if _model_projection(worker) != assignments.get(reference):
+        if _model_projection(worker) != _model_projection_from_assignment(
+            assignments.get(reference)
+        ):
             raise ValueError("immutable invocation manifest worker projection drift")
 
 
@@ -1915,6 +1949,40 @@ def _model_projection(value: Mapping[str, object]) -> dict[str, object]:
     return {key: value.get(key) for key in _MODEL_ASSIGNMENT_KEYS}
 
 
+def _model_projection_from_assignment(value: object) -> dict[str, object] | None:
+    if not isinstance(value, Mapping) or not _MODEL_ASSIGNMENT_KEYS.issubset(value):
+        return None
+    return _model_projection(value)
+
+
+def _invocation_manifest_identity_version(payload: Mapping[str, object]) -> int:
+    schema = payload.get("schemaVersion")
+    identity = payload.get("executionIdentityVersion")
+    if schema == "2.0" and identity == 2:
+        return 2
+    if schema == "2.0" or identity is not None:
+        raise ValueError("invocation manifest mixes v1 and v2 execution identity")
+    if schema not in (None, 1, "1", "1.0"):
+        raise ValueError("unsupported invocation manifest execution identity version")
+    return 1
+
+
+def _validate_invocation_assignment_shapes(
+    assignments: Mapping[str, object],
+) -> None:
+    allowed = {frozenset(_MODEL_ASSIGNMENT_KEYS)}
+    for item in assignments.values():
+        if not isinstance(item, Mapping):
+            raise ValueError("incomplete invocation manifest assignments")
+        keys = set(item)
+        if keys & _V2_INVOCATION_IDENTITY_KEYS:
+            raise ValueError(
+                "invocation assignment duplicates v2 execution identity"
+            )
+        if frozenset(keys) not in allowed:
+            raise ValueError("incomplete invocation manifest assignments")
+
+
 def render_timeline(timeline_path: str, ctx: dict) -> None:
     task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
     task_manifest = {}

package/runtime/python/okstra_ctl/render_final_report.py

@@ -566,6 +566,8 @@ def _ai_markdown_context(data: dict, schema: dict | None) -> dict:
     context["md_rest"] = sections.rest
     context["md_has"] = sections.has
     context["md_claim"] = sections.mark_rendered
+    context["executionRolesTable"] = render_execution_roles_markdown(data)
+    context["executionIdentityVersion"] = data.get("executionIdentityVersion")
     return context
 
 
@@ -623,6 +625,23 @@ _OPTIONAL_ANALYSIS_DEFAULTS = (
 )
 
 
+def render_execution_roles_markdown(data: dict) -> str:
+    roles = data.get("executionRoles") or []
+    if data.get("executionIdentityVersion") != 2:
+        return "legacy execution roles"
+    lines = ["| Role | Label | Status |", "|---|---|---|"]
+    for row in roles:
+        lines.append(
+            f"| {row.get('role', '')} | {row.get('executionLabel', '')} | "
+            f"{row.get('status', '')} |"
+        )
+    return "\n".join(lines)
+
+
+def render_execution_roles_html(data: dict) -> str:
+    return render_execution_roles_markdown(data)
+
+
 def _with_optional_defaults(data: dict) -> dict:
     """Render context with schema-optional fields filled in.
 

package/runtime/python/okstra_ctl/report_contract.py

@@ -170,6 +170,45 @@ def html_template_for(task_type: str) -> str:
         raise ValueError(f"no task-specific html template for: {task_type}") from exc
 
 
+def execution_roles_from_manifest(manifest: dict) -> list[dict]:
+    """Copy the exact RoleExecution set. Do not invent rows."""
+    if int(manifest.get("executionIdentityVersion") or 0) != 2:
+        return []
+    roles = []
+    for row in manifest.get("roleExecutions") or []:
+        if not isinstance(row, dict):
+            continue
+        roles.append({
+            "roleExecutionRef": row.get("roleExecutionRef"),
+            "role": row.get("role"),
+            "provider": row.get("provider"),
+            "modelRef": row.get("modelRef"),
+            "ordinal": row.get("ordinal"),
+            "executionLabel": row.get("executionLabel"),
+            "status": row.get("status"),
+        })
+    return roles
+
+
+def apply_execution_roles(data: dict, manifest: dict) -> dict:
+    """Copy the manifest RoleExecution set onto a final-report payload."""
+    updated = dict(data)
+    if int(manifest.get("executionIdentityVersion") or 0) != 2:
+        return updated
+    updated["executionIdentityVersion"] = 2
+    updated["executionRoles"] = execution_roles_from_manifest(manifest)
+    return updated
+
+
+def assert_execution_roles_match_manifest(report: dict, manifest: dict) -> None:
+    report_refs = {row.get("roleExecutionRef") for row in report.get("executionRoles") or []}
+    manifest_refs = {
+        row.get("roleExecutionRef") for row in manifest.get("roleExecutions") or []
+    }
+    if report_refs != manifest_refs:
+        raise ValueError("report executionRoles must equal manifest roleExecutions")
+
+
 def markdown_template_for(task_type: str) -> str:
     try:
         return TASK_TYPE_MARKDOWN_TEMPLATE[task_type]

package/runtime/python/okstra_ctl/report_finalize.py

@@ -38,6 +38,7 @@ from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
 from .agent_activity import ActivityProjectionError, project_agent_activity
+from .report_contract import apply_execution_roles
 from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
@@ -388,6 +389,7 @@ def run_finalize(
     steps: list[dict[str, Any]] = []
     deferred = ""
     try:
+        write_execution_roles(ctx)
         commands = build_commands(ctx)
     except FinalizeError as exc:
         return {"ok": False, "reason": str(exc), "steps": steps}
@@ -465,6 +467,20 @@ def run_finalize(
     return {"ok": True, "reason": "", "steps": steps}
 
 
+def write_execution_roles(ctx: FinalizeContext) -> None:
+    """Write the exact manifest role set onto the final-report data.json."""
+    if not ctx.data_path.is_file() or not ctx.manifest_path.is_file():
+        return
+    manifest = _load_manifest(ctx.manifest_path)
+    data = _load_manifest(ctx.data_path)
+    updated = apply_execution_roles(dict(data), dict(manifest))
+    if updated == data:
+        return
+    tmp = ctx.data_path.with_suffix(ctx.data_path.suffix + ".tmp")
+    tmp.write_text(json.dumps(updated, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(ctx.data_path)
+
+
 def _link_lead_result_for_validation(ctx: FinalizeContext) -> None:
     """Link the lead-authored synthesis artifact before Phase 7 validation."""
     manifest = _load_manifest(ctx.manifest_path)

package/runtime/python/okstra_ctl/report_html/render.py

@@ -155,6 +155,7 @@ def render_v2_html_view(
         # Every task type ends with the same run-cost section, so it is bound
         # here rather than in ten view models that would each rebuild it.
         "runUsage": run_usage(data),
+        "executionRoles": data.get("executionRoles") or [],
         "css": (root / "html/assets/base.css").read_text(encoding="utf-8"),
         "js": response_js + "\n" + base_js,
     }

package/runtime/python/okstra_ctl/role_requirements.py

@@ -0,0 +1,217 @@
+"""Parse canonical role requirements declared in phase profiles."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .domain.role import RoleCatalogError, normalize_role, role_for_duty
+
+
+class RoleProfileError(ValueError):
+    """Raised when a profile's structured role declaration is invalid."""
+
+
+@dataclass(frozen=True)
+class RoleRequirement:
+    role: str
+    count: int
+    duty: str
+    optional_count: int = 0
+    min_distinct_providers: int | None = None
+    dynamic: bool = False
+
+    def signature(self) -> tuple[str, int, int, str, int | None, bool]:
+        return (
+            self.role,
+            self.count,
+            self.optional_count,
+            self.duty,
+            self.min_distinct_providers,
+            self.dynamic,
+        )
+
+
+@dataclass(frozen=True)
+class RoleProfile:
+    roles: tuple[RoleRequirement, ...]
+
+    def role_signature(self) -> tuple[tuple[str, int, int, str, int | None, bool], ...]:
+        return tuple(requirement.signature() for requirement in self.roles)
+
+
+_REQUIRED_FIELDS = frozenset({"role", "count", "duty"})
+_ALLOWED_FIELDS = _REQUIRED_FIELDS | {
+    "optionalCount",
+    "minDistinctProviders",
+    "dynamic",
+}
+
+
+def load_role_profile(path: Path) -> RoleProfile:
+    """Load and validate the one fenced YAML ``roles:`` declaration in a profile."""
+    profile_path = Path(path)
+    try:
+        text = profile_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise RoleProfileError(f"cannot read role profile: {profile_path}") from exc
+    raw_roles, errors = _parse_roles_block(text)
+    requirements = tuple(
+        _validate_requirement(raw, index, errors)
+        for index, raw in enumerate(raw_roles, 1)
+    )
+    _validate_static_role_duplicates(requirements, errors)
+    if errors:
+        raise RoleProfileError("invalid role profile:\n- " + "\n- ".join(errors))
+    return RoleProfile(requirements)
+
+
+def _parse_roles_block(text: str) -> tuple[list[dict[str, str]], list[str]]:
+    blocks = _yaml_blocks_with_roles(text)
+    if len(blocks) != 1:
+        return [], ["profile must declare exactly one fenced YAML roles block"]
+    lines = blocks[0]
+    if lines == ["roles: []"]:
+        return [], []
+    if not lines or lines[0] != "roles:":
+        return [], ["roles block must start with roles:"]
+    roles: list[dict[str, str]] = []
+    errors: list[str] = []
+    current: dict[str, str] | None = None
+    for line_number, line in enumerate(lines[1:], 2):
+        if not line.strip():
+            continue
+        if line.startswith("  - "):
+            if current is not None:
+                roles.append(current)
+            current = {}
+            _add_yaml_field(current, line[4:], line_number, errors)
+            continue
+        if line.startswith("    ") and current is not None:
+            _add_yaml_field(current, line[4:], line_number, errors)
+            continue
+        errors.append(f"roles block line {line_number} is not a role field")
+    if current is not None:
+        roles.append(current)
+    elif not errors:
+        errors.append("roles block must contain a role or use roles: []")
+    return roles, errors
+
+
+def _yaml_blocks_with_roles(text: str) -> list[list[str]]:
+    blocks: list[list[str]] = []
+    current: list[str] | None = None
+    for line in text.splitlines():
+        if line.strip() == "```yaml":
+            current = []
+            continue
+        if line.strip() == "```" and current is not None:
+            if any(item.strip().startswith("roles:") for item in current):
+                blocks.append(current)
+            current = None
+            continue
+        if current is not None:
+            current.append(line)
+    return blocks
+
+
+def _add_yaml_field(
+    fields: dict[str, str], line: str, line_number: int, errors: list[str],
+) -> None:
+    if ":" not in line:
+        errors.append(f"roles block line {line_number} must contain key: value")
+        return
+    key, value = (part.strip() for part in line.split(":", 1))
+    if not key or not value:
+        errors.append(f"roles block line {line_number} must contain key: value")
+        return
+    if key in fields:
+        errors.append(f"roles block line {line_number} repeats {key}")
+        return
+    fields[key] = value
+
+
+def _validate_requirement(
+    raw: dict[str, str], index: int, errors: list[str],
+) -> RoleRequirement:
+    prefix = f"role requirement {index}"
+    for field in sorted(_REQUIRED_FIELDS - raw.keys()):
+        errors.append(f"{prefix} is missing {field}")
+    for field in sorted(raw.keys() - _ALLOWED_FIELDS):
+        errors.append(f"{prefix} has unknown field {field}")
+
+    role = _validate_role(raw.get("role", ""), prefix, errors)
+    count = _validate_non_negative_integer(raw.get("count", ""), "count", prefix, errors)
+    duty = _validate_duty(raw.get("duty", ""), role, prefix, errors)
+    optional_count = _validate_non_negative_integer(
+        raw.get("optionalCount", "0"), "optionalCount", prefix, errors,
+    )
+    diversity = _validate_diversity(raw.get("minDistinctProviders"), prefix, errors)
+    dynamic = _validate_dynamic(raw.get("dynamic", "false"), prefix, errors)
+    if diversity is not None and diversity > count + optional_count:
+        errors.append(f"{prefix} minDistinctProviders must not exceed count + optionalCount")
+    if dynamic and (count != 0 or optional_count != 0):
+        errors.append(f"{prefix} dynamic roles must have count and optionalCount of zero")
+    if dynamic and diversity is not None:
+        errors.append(f"{prefix} dynamic roles must not declare minDistinctProviders")
+    return RoleRequirement(role, count, duty, optional_count, diversity, dynamic)
+
+
+def _validate_role(raw: str, prefix: str, errors: list[str]) -> str:
+    try:
+        return normalize_role(raw)
+    except RoleCatalogError as exc:
+        errors.append(f"{prefix} {exc}")
+        return raw
+
+
+def _validate_duty(raw: str, role: str, prefix: str, errors: list[str]) -> str:
+    try:
+        duty_role = role_for_duty(raw)
+    except RoleCatalogError as exc:
+        errors.append(f"{prefix} {exc}")
+        return raw
+    if duty_role != role:
+        errors.append(f"{prefix} duty {raw} belongs to role {duty_role}, not {role}")
+    return raw
+
+
+def _validate_non_negative_integer(raw: str, field: str, prefix: str, errors: list[str]) -> int:
+    try:
+        value = int(raw)
+    except ValueError:
+        errors.append(f"{prefix} {field} must be a non-negative integer")
+        return 0
+    if value < 0 or str(value) != raw:
+        errors.append(f"{prefix} {field} must be a non-negative integer")
+        return 0
+    return value
+
+
+def _validate_diversity(raw: str | None, prefix: str, errors: list[str]) -> int | None:
+    if raw is None:
+        return None
+    value = _validate_non_negative_integer(raw, "minDistinctProviders", prefix, errors)
+    if value == 0:
+        errors.append(f"{prefix} minDistinctProviders must be at least one")
+    return value
+
+
+def _validate_dynamic(raw: str, prefix: str, errors: list[str]) -> bool:
+    if raw == "true":
+        return True
+    if raw == "false":
+        return False
+    errors.append(f"{prefix} dynamic must be true or false")
+    return False
+
+
+def _validate_static_role_duplicates(
+    requirements: tuple[RoleRequirement, ...], errors: list[str],
+) -> None:
+    static_roles: set[str] = set()
+    for requirement in requirements:
+        if requirement.dynamic:
+            continue
+        if requirement.role in static_roles:
+            errors.append(f"duplicate static role: {requirement.role}")
+        static_roles.add(requirement.role)