okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -6,10 +6,18 @@ import hashlib
 import json
 from typing import Any, Mapping
 
+from .execution_identity import ExecutionManifest
+
 
 WORKING_SCHEMA_VERSION = "1.0"
+V2_WORKING_SCHEMA_VERSION = "2.0"
+EXECUTION_IDENTITY_VERSION = 2
 FINAL_SCHEMA_VERSION = "1.3"
 _AUDIENCES = {"analysis", "report-writer"}
+_AUDIENCE_SOURCE_ROLES = {
+    "analysis": frozenset({"analyser", "designer", "planner", "verifier"}),
+    "report-writer": frozenset({"report-writer"}),
+}
 _VERIFICATION_MODES = {"lightweight", "full-reanalysis"}
 _CLASSIFICATION_COUNT_KEYS = {
     "full-consensus": "fullConsensus",
@@ -52,19 +60,27 @@ def grouped_input_digest(grouped_input: Mapping[str, Any]) -> str:
     return hashlib.sha256(encoded).hexdigest()
 
 
-def seed_working_state(grouped_input: Mapping[str, Any]) -> dict[str, Any]:
+def seed_working_state(
+    grouped_input: Mapping[str, Any],
+    *,
+    execution_manifest: ExecutionManifest | None = None,
+) -> dict[str, Any]:
     """Validate grouped findings, classify Round 0, and create the queue."""
     source = _object(grouped_input, "grouped input")
-    if source.get("schemaVersion") != WORKING_SCHEMA_VERSION:
-        raise ConvergenceContractError("grouped input schemaVersion must be 1.0")
+    identity_version = _grouped_execution_identity_version(source)
     task_key = _required_string(source, "taskKey", "grouped input")
     config = _parse_config(source.get("config"))
-    workers = _parse_workers(source.get("workers"))
+    workers = _parse_workers(source.get("workers"), identity_version)
+    _validate_worker_execution_identity(
+        workers,
+        execution_manifest,
+        identity_version,
+    )
     analysis_workers = [
         worker["workerId"] for worker in workers if worker["audience"] == "analysis"
     ]
     state = {
-        "schemaVersion": WORKING_SCHEMA_VERSION,
+        "schemaVersion": source["schemaVersion"],
         "taskKey": task_key,
         "groupsDigest": grouped_input_digest(source),
         "config": config,
@@ -74,6 +90,15 @@ def seed_working_state(grouped_input: Mapping[str, Any]) -> dict[str, Any]:
         "roundHistory": [],
         "stopReason": None,
     }
+    if identity_version == EXECUTION_IDENTITY_VERSION:
+        state.update({
+            "executionIdentityVersion": EXECUTION_IDENTITY_VERSION,
+            "runManifestPath": _required_string(
+                source,
+                "runManifestPath",
+                "grouped input",
+            ),
+        })
     if not config["enabled"] or len(analysis_workers) < 2:
         state["stopReason"] = "auto-disabled"
         return state
@@ -141,16 +166,30 @@ def plan_next_round(state: Mapping[str, Any]) -> dict[str, Any]:
         if not isinstance(worker, Mapping) or worker.get("audience") != "analysis":
             continue
         worker_id = _required_string(worker, "workerId", "working state worker")
+        worker_participant_ref = _worker_participant_ref(worker)
         eligible = [
             finding_id
             for finding_id in queue
-            if findings[finding_id].get("originWorker") != worker_id
+            if _worker_is_independent_from_finding(
+                worker_id,
+                worker_participant_ref,
+                findings[finding_id],
+                workers,
+            )
         ]
         if eligible:
-            dispatches.append({"worker": worker_id, "findingIds": eligible})
+            dispatches.append({
+                **_worker_execution_refs(worker),
+                "worker": worker_id,
+                "findingIds": eligible,
+            })
         else:
             skipped.append(
-                {"worker": worker_id, "reason": "no items to verify"}
+                {
+                    **_worker_execution_refs(worker),
+                    "worker": worker_id,
+                    "reason": "no items to verify",
+                }
             )
     return {
         "schemaVersion": WORKING_SCHEMA_VERSION,
@@ -162,6 +201,45 @@ def plan_next_round(state: Mapping[str, Any]) -> dict[str, Any]:
     }
 
 
+def _worker_participant_ref(worker: Mapping[str, Any]) -> str | None:
+    value = worker.get("participantRef")
+    return value if isinstance(value, str) and value else None
+
+
+def _worker_is_independent_from_finding(
+    worker_id: str,
+    participant_ref: str | None,
+    finding: Mapping[str, Any],
+    workers: list[Any],
+) -> bool:
+    origin_worker = finding.get("originWorker")
+    if participant_ref is None:
+        return origin_worker != worker_id
+    origin = next(
+        (
+            row
+            for row in workers
+            if isinstance(row, Mapping) and row.get("workerId") == origin_worker
+        ),
+        None,
+    )
+    origin_participant_ref = (
+        _worker_participant_ref(origin) if origin is not None else None
+    )
+    return origin_participant_ref != participant_ref
+
+
+def _worker_execution_refs(worker: Mapping[str, Any]) -> dict[str, str]:
+    participant_ref = _worker_participant_ref(worker)
+    source_ref = worker.get("sourceRoleExecutionRef")
+    if participant_ref is None or not isinstance(source_ref, str) or not source_ref:
+        return {}
+    return {
+        "participantRef": participant_ref,
+        "sourceRoleExecutionRef": source_ref,
+    }
+
+
 def classify_collaborative_round(
     votes: Mapping[str, Mapping[str, Any]],
 ) -> str | None:
@@ -304,7 +382,10 @@ def apply_round_results(
         }
         for row in expected_plan["dispatches"]
     ]
-    skipped = deepcopy(expected_plan["skippedWorkers"])
+    skipped = [
+        {"worker": row["worker"], "reason": row["reason"]}
+        for row in expected_plan["skippedWorkers"]
+    ]
     for row in dispatch_history:
         if row["status"] != "completed":
             skipped.append(
@@ -457,13 +538,40 @@ def finalize_working_state(state: Mapping[str, Any]) -> dict[str, Any]:
     return final
 
 
+def _working_execution_identity_version(
+    state: Mapping[str, Any],
+    errors: list[str],
+) -> int | None:
+    schema_version = state.get("schemaVersion")
+    identity_version = state.get("executionIdentityVersion")
+    run_manifest_path = state.get("runManifestPath")
+    if schema_version == WORKING_SCHEMA_VERSION:
+        if (
+            "executionIdentityVersion" in state
+            or "runManifestPath" in state
+        ):
+            errors.append(
+                "working schemaVersion 1.0 v1 state forbids v2 identity fields"
+            )
+        return 1
+    if schema_version == V2_WORKING_SCHEMA_VERSION:
+        if identity_version != EXECUTION_IDENTITY_VERSION:
+            errors.append(
+                "working execution identity version must be 2 for schemaVersion 2.0"
+            )
+        if not _nonempty_string(run_manifest_path):
+            errors.append("working runManifestPath must be a non-empty string")
+        return EXECUTION_IDENTITY_VERSION
+    errors.append(f"unsupported working schemaVersion: {schema_version!r}")
+    return None
+
+
 def validate_working_state(state: Mapping[str, Any]) -> list[str]:
     """Return structural and transition errors for a working-state object."""
     errors: list[str] = []
     if not isinstance(state, Mapping):
         return ["working state must be an object"]
-    if state.get("schemaVersion") != WORKING_SCHEMA_VERSION:
-        errors.append("working schemaVersion must be 1.0")
+    identity_version = _working_execution_identity_version(state, errors)
     if not _nonempty_string(state.get("taskKey")):
         errors.append("taskKey must be a non-empty string")
     digest = state.get("groupsDigest")
@@ -497,6 +605,24 @@ def validate_working_state(state: Mapping[str, Any]) -> list[str]:
                     "use 'analysis'; only the report author uses 'report-writer'. "
                     f"Allowed: {sorted(_AUDIENCES)}."
                 )
+            participant_ref = worker.get("participantRef")
+            source_ref = worker.get("sourceRoleExecutionRef")
+            has_execution_fields = (
+                "participantRef" in worker
+                or "sourceRoleExecutionRef" in worker
+            )
+            if identity_version == 1 and has_execution_fields:
+                errors.append(
+                    f"workers[{index}] v1 row forbids execution identity references"
+                )
+            elif identity_version == EXECUTION_IDENTITY_VERSION and (
+                not _nonempty_string(participant_ref)
+                or not _nonempty_string(source_ref)
+            ):
+                errors.append(
+                    f"workers[{index}] must carry participantRef and "
+                    "sourceRoleExecutionRef together"
+                )
     findings = state.get("findings")
     if not isinstance(findings, list):
         errors.append("findings must be an array")
@@ -1788,8 +1914,10 @@ def _parse_vote(
 def _validate_plannable_state(
     state: Mapping[str, Any],
 ) -> tuple[list[str], dict[str, Mapping[str, Any]], list[Mapping[str, Any]]]:
-    if state.get("schemaVersion") != WORKING_SCHEMA_VERSION:
-        raise ConvergenceContractError("working state schemaVersion must be 1.0")
+    version_errors: list[str] = []
+    _working_execution_identity_version(state, version_errors)
+    if version_errors:
+        raise ConvergenceContractError("; ".join(version_errors))
     queue_value = state.get("queueFindingIds")
     if not isinstance(queue_value, list) or not all(
         isinstance(item, str) and item for item in queue_value
@@ -1833,6 +1961,41 @@ def _validate_plannable_state(
     return queue, findings, history
 
 
+def _grouped_execution_identity_version(source: Mapping[str, Any]) -> int:
+    schema_version = source.get("schemaVersion")
+    identity_version = source.get("executionIdentityVersion")
+    workers = source.get("workers")
+    worker_rows = workers if isinstance(workers, list) else []
+    has_worker_identity = any(
+        isinstance(worker, Mapping)
+        and (
+            "participantRef" in worker
+            or "sourceRoleExecutionRef" in worker
+        )
+        for worker in worker_rows
+    )
+    if schema_version == WORKING_SCHEMA_VERSION:
+        if (
+            "executionIdentityVersion" in source
+            or "runManifestPath" in source
+            or has_worker_identity
+        ):
+            raise ConvergenceContractError(
+                "v1 convergence groups forbid v2 execution identity fields"
+            )
+        return 1
+    if schema_version == V2_WORKING_SCHEMA_VERSION:
+        if identity_version != EXECUTION_IDENTITY_VERSION:
+            raise ConvergenceContractError(
+                "v2 convergence groups require executionIdentityVersion 2"
+            )
+        _required_string(source, "runManifestPath", "grouped input")
+        return EXECUTION_IDENTITY_VERSION
+    raise ConvergenceContractError(
+        f"unsupported grouped input schemaVersion: {schema_version!r}"
+    )
+
+
 def _parse_config(value: Any) -> dict[str, Any]:
     config = _object(value, "config")
     enabled = config.get("enabled")
@@ -1865,7 +2028,7 @@ def _parse_config(value: Any) -> dict[str, Any]:
     }
 
 
-def _parse_workers(value: Any) -> list[dict[str, str]]:
+def _parse_workers(value: Any, identity_version: int) -> list[dict[str, str]]:
     if not isinstance(value, list):
         raise ConvergenceContractError("workers must be an array")
     workers: list[dict[str, str]] = []
@@ -1885,10 +2048,80 @@ def _parse_workers(value: Any) -> list[dict[str, str]]:
         if worker_id in seen:
             raise ConvergenceContractError(f"duplicate workerId: {worker_id}")
         seen.add(worker_id)
-        workers.append({"workerId": worker_id, "audience": audience})
+        parsed = {"workerId": worker_id, "audience": audience}
+        participant_ref = worker.get("participantRef")
+        source_ref = worker.get("sourceRoleExecutionRef")
+        has_execution_refs = (
+            "participantRef" in worker
+            or "sourceRoleExecutionRef" in worker
+        )
+        if identity_version == 1 and has_execution_refs:
+            raise ConvergenceContractError(
+                "v1 convergence workers forbid execution identity references"
+            )
+        if identity_version == EXECUTION_IDENTITY_VERSION and (
+            not _nonempty_string(participant_ref)
+            or not _nonempty_string(source_ref)
+        ):
+            raise ConvergenceContractError(
+                "v2 convergence workers require execution identity references: "
+                f"workers[{index}] must carry participantRef and "
+                "sourceRoleExecutionRef"
+            )
+        if identity_version == EXECUTION_IDENTITY_VERSION:
+            parsed.update({
+                "participantRef": str(participant_ref),
+                "sourceRoleExecutionRef": str(source_ref),
+            })
+        workers.append(parsed)
     return workers
 
 
+def _validate_worker_execution_identity(
+    workers: list[dict[str, str]],
+    execution_manifest: ExecutionManifest | None,
+    identity_version: int,
+) -> None:
+    if identity_version == 1:
+        if execution_manifest is not None:
+            raise ConvergenceContractError(
+                "v1 convergence forbids execution manifest authority; "
+                "omit --run-manifest"
+            )
+        return
+    if execution_manifest is None:
+        raise ConvergenceContractError(
+            "v2 convergence requires execution manifest authority; "
+            "pass --run-manifest"
+        )
+    if execution_manifest.legacy:
+        raise ConvergenceContractError(
+            "v2 convergence workers require v2 execution manifest"
+        )
+    roles = {
+        role.role_execution_ref: role
+        for role in execution_manifest.role_executions
+    }
+    for worker in workers:
+        source_ref = worker["sourceRoleExecutionRef"]
+        source = roles.get(source_ref)
+        if source is None:
+            raise ConvergenceContractError(
+                f"unknown sourceRoleExecutionRef: {source_ref}"
+            )
+        if source.participant_ref != worker["participantRef"]:
+            raise ConvergenceContractError(
+                f"worker {worker['workerId']} participantRef does not match "
+                f"sourceRoleExecutionRef: {source_ref}"
+            )
+        allowed_roles = _AUDIENCE_SOURCE_ROLES[worker["audience"]]
+        if source.role not in allowed_roles:
+            raise ConvergenceContractError(
+                f"{worker['audience']} audience source role is not allowed: "
+                f"{source.role}"
+            )
+
+
 def _parse_groups(
     value: Any,
     analysis_workers: list[str],

package/runtime/python/okstra_ctl/convergence_store.py

@@ -2,13 +2,28 @@
 from __future__ import annotations
 
 import json
-import hashlib
 import os
 from pathlib import Path
 import tempfile
 from typing import Any, Mapping
 
 from .convergence_engine import ConvergenceContractError
+from .domain.role import RoleCatalogError, role_for_duty
+from .execution_identity import ExecutionManifestError, Invocation, RoleExecution
+from .execution_manifest import (
+    read_execution_manifest,
+    reserve_derived_role_invocation,
+)
+from .worker_request import verifier_extra_dirs
+from .write_policy import build_invocation_write_contract
+
+
+DYNAMIC_VERIFIER_SOURCE_ROLES = frozenset({
+    "analyser",
+    "designer",
+    "planner",
+    "verifier",
+})
 
 
 def load_json_object(path: Path) -> dict[str, Any]:
@@ -62,6 +77,160 @@ def write_final_state_atomic(
     write_json_atomic(path, payload)
 
 
+def reserve_dynamic_verifier(
+    manifest_path: Path,
+    source_role_execution_ref: str,
+    duty_id: str,
+    round_number: int,
+    task_key: str,
+    *,
+    input_digest: str,
+    invocation_ref: str | None = None,
+    artifact_paths: tuple[Path, ...],
+) -> tuple[RoleExecution, Invocation]:
+    """Reserve one provider-neutral verifier identity for a logical round."""
+    if round_number < 1:
+        raise ExecutionManifestError("dynamic verifier round must be positive")
+    manifest_path = Path(manifest_path).resolve()
+    manifest = read_execution_manifest(manifest_path)
+    if manifest.legacy:
+        raise ExecutionManifestError("cannot reserve a dynamic verifier in v1 data")
+    _validate_dynamic_verifier_request(
+        manifest.role_executions,
+        source_role_execution_ref,
+        duty_id,
+    )
+    authority = load_json_object(manifest_path)
+    if authority.get("taskKey") not in (None, task_key):
+        raise ExecutionManifestError("dynamic verifier taskKey does not match manifest")
+    project_root = _manifest_project_root(authority, manifest_path)
+    task_manifest_path = _manifest_authority_path(
+        authority,
+        "taskManifestPath",
+        project_root,
+    )
+    run_ref = _manifest_run_ref(authority, manifest_path, project_root)
+
+    def invocation_factory(verifier: RoleExecution) -> Invocation:
+        selected_ref = invocation_ref or (
+            f"{verifier.role_execution_ref}-{duty_id}-r{round_number:03d}"
+        )
+        capability = (
+            verifier.binding.worker_write_capability
+            if verifier.binding is not None
+            else None
+        )
+        if capability is None:
+            raise ExecutionManifestError(
+                "dynamic verifier has no runner write capability"
+            )
+        try:
+            policy, enforcement = build_invocation_write_contract(
+                role="verifier",
+                project_root=project_root,
+                worktree=None,
+                artifact_paths=artifact_paths,
+                maximum_precision=capability.max_boundary_precision,
+                auxiliary_roots=verifier_extra_dirs("verifier"),
+                validated_auxiliary_roots=verifier_extra_dirs("verifier"),
+            )
+        except (OSError, ValueError) as exc:
+            raise ExecutionManifestError(
+                f"dynamic verifier write policy is invalid: {exc}"
+            ) from exc
+        return Invocation(
+            invocation_ref=selected_ref,
+            participant_ref=verifier.participant_ref,
+            role_execution_ref=verifier.role_execution_ref,
+            source_invocation_ref=None,
+            recovery_ref=None,
+            duty_id=duty_id,
+            dispatch_kind=f"reverify-r{round_number}",
+            round=round_number,
+            input_digest=input_digest,
+            write_policy=policy.to_payload(),
+            write_policy_digest=policy.digest,
+            write_enforcement=enforcement.to_payload(),
+        )
+
+    return reserve_derived_role_invocation(
+        manifest_path,
+        source_role_execution_ref=source_role_execution_ref,
+        role="verifier",
+        invocation_factory=invocation_factory,
+        task_key=task_key,
+        task_manifest_path=task_manifest_path,
+        run_ref=run_ref,
+    )
+
+
+def _validate_dynamic_verifier_request(
+    roles: tuple[RoleExecution, ...],
+    source_role_execution_ref: str,
+    duty_id: str,
+) -> None:
+    try:
+        duty_role = role_for_duty(duty_id)
+    except RoleCatalogError as exc:
+        raise ExecutionManifestError(f"unknown verifier duty: {duty_id}") from exc
+    if duty_role != "verifier":
+        raise ExecutionManifestError(f"dynamic verifier duty is not verifier: {duty_id}")
+    source = next(
+        (
+            role
+            for role in roles
+            if role.role_execution_ref == source_role_execution_ref
+        ),
+        None,
+    )
+    if source is not None and source.role not in DYNAMIC_VERIFIER_SOURCE_ROLES:
+        raise ExecutionManifestError(
+            f"dynamic verifier source role is not eligible: {source.role}"
+        )
+
+
+def _manifest_project_root(
+    manifest: Mapping[str, Any],
+    manifest_path: Path,
+) -> Path:
+    value = manifest.get("projectRoot")
+    if not isinstance(value, str) or not value.strip():
+        raise ExecutionManifestError("run manifest has no projectRoot")
+    project_root = Path(value).resolve()
+    if not manifest_path.is_relative_to(project_root):
+        raise ExecutionManifestError("run manifest resolves outside projectRoot")
+    return project_root
+
+
+def _manifest_authority_path(
+    manifest: Mapping[str, Any],
+    key: str,
+    project_root: Path,
+) -> Path:
+    value = manifest.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ExecutionManifestError(f"run manifest has no {key}")
+    path = (project_root / value).resolve()
+    if not path.is_relative_to(project_root):
+        raise ExecutionManifestError(f"run manifest {key} escapes projectRoot")
+    return path
+
+
+def _manifest_run_ref(
+    manifest: Mapping[str, Any],
+    manifest_path: Path,
+    project_root: Path,
+) -> str:
+    value = manifest.get("runManifestPath")
+    if not isinstance(value, str) or not value.strip():
+        raise ExecutionManifestError("run manifest has no runManifestPath")
+    if (project_root / value).resolve() != manifest_path:
+        raise ExecutionManifestError(
+            "runManifestPath does not identify the execution manifest"
+        )
+    return value
+
+
 def _validate_final_replacement(
     path: Path,
     migration: Mapping[str, Any] | None,