okstra 0.127.0 → 0.129.0

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -0,0 +1,1152 @@
+"""Pure deterministic state transitions for Phase 5.5 convergence."""
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+from typing import Any, Mapping
+
+
+WORKING_SCHEMA_VERSION = "1.0"
+FINAL_SCHEMA_VERSION = "1.2"
+_AUDIENCES = {"analysis", "report-writer"}
+_VERIFICATION_MODES = {"lightweight", "full-reanalysis"}
+_CLASSIFICATION_COUNT_KEYS = {
+    "full-consensus": "fullConsensus",
+    "partial-consensus": "partialConsensus",
+    "contested": "contested",
+    "worker-unique": "workerUnique",
+}
+_VERDICTS = {"agree", "disagree", "supplement", "verification-error"}
+_DISAGREE_BASES = {"counter-evidence", "burden-not-met"}
+_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
+
+
+class ConvergenceContractError(ValueError):
+    """Raised when convergence input violates the persisted-state contract."""
+
+
+def grouped_input_digest(grouped_input: Mapping[str, Any]) -> str:
+    """Return SHA-256 over canonical compact JSON."""
+    encoded = json.dumps(
+        grouped_input,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def seed_working_state(grouped_input: Mapping[str, Any]) -> 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")
+    task_key = _required_string(source, "taskKey", "grouped input")
+    config = _parse_config(source.get("config"))
+    workers = _parse_workers(source.get("workers"))
+    analysis_workers = [
+        worker["workerId"] for worker in workers if worker["audience"] == "analysis"
+    ]
+    state = {
+        "schemaVersion": WORKING_SCHEMA_VERSION,
+        "taskKey": task_key,
+        "groupsDigest": grouped_input_digest(source),
+        "config": config,
+        "workers": workers,
+        "findings": [],
+        "queueFindingIds": [],
+        "roundHistory": [],
+        "stopReason": None,
+    }
+    if not config["enabled"] or len(analysis_workers) < 2:
+        state["stopReason"] = "auto-disabled"
+        return state
+
+    findings, queue = _parse_groups(source.get("groups"), analysis_workers)
+    state["findings"] = findings
+    state["queueFindingIds"] = queue
+    return state
+
+
+def classification_counts_from_findings(
+    findings: list[Mapping[str, Any]],
+) -> dict[str, int]:
+    """Return the four v1.2 finalClassificationCounts keys."""
+    counts = {value: 0 for value in _CLASSIFICATION_COUNT_KEYS.values()}
+    for finding in findings:
+        key = _CLASSIFICATION_COUNT_KEYS.get(finding.get("classification"))
+        if key:
+            counts[key] += 1
+    return counts
+
+
+def plan_next_round(state: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the next immutable roster-aware dispatch plan or final gate."""
+    current = _object(state, "working state")
+    queue, findings, history = _validate_plannable_state(current)
+    config = _object(current.get("config"), "working state.config")
+    effective_max = config.get("effectiveMaxRounds")
+    if not isinstance(effective_max, int):
+        raise ConvergenceContractError(
+            "working state.config.effectiveMaxRounds must be an integer"
+        )
+    stop_reason = current.get("stopReason")
+    reason = None
+    if stop_reason == "auto-disabled" or not config.get("enabled"):
+        reason = "auto-disabled"
+    elif stop_reason == "all-reverify-non-result":
+        reason = "all-reverify-non-result"
+    elif effective_max == 1 and history:
+        reason = "max-rounds-1"
+    elif not queue:
+        reason = "queue-empty"
+    elif len(history) >= effective_max:
+        reason = "max-rounds-reached"
+    round_number = len(history) + 1
+    if reason is not None:
+        return {
+            "schemaVersion": WORKING_SCHEMA_VERSION,
+            "action": "finalize",
+            "round": round_number,
+            "inputQueueSize": len(queue),
+            "reason": reason,
+            "dispatches": [],
+            "skippedWorkers": [],
+        }
+
+    workers = current.get("workers")
+    if not isinstance(workers, list):
+        raise ConvergenceContractError("working state.workers must be an array")
+    dispatches: list[dict[str, Any]] = []
+    skipped: list[dict[str, str]] = []
+    for worker in workers:
+        if not isinstance(worker, Mapping) or worker.get("audience") != "analysis":
+            continue
+        worker_id = _required_string(worker, "workerId", "working state worker")
+        eligible = [
+            finding_id
+            for finding_id in queue
+            if findings[finding_id].get("originWorker") != worker_id
+        ]
+        if eligible:
+            dispatches.append({"worker": worker_id, "findingIds": eligible})
+        else:
+            skipped.append(
+                {"worker": worker_id, "reason": "no items to verify"}
+            )
+    return {
+        "schemaVersion": WORKING_SCHEMA_VERSION,
+        "action": "dispatch",
+        "round": round_number,
+        "inputQueueSize": len(queue),
+        "dispatches": dispatches,
+        "skippedWorkers": skipped,
+    }
+
+
+def classify_collaborative_round(
+    votes: Mapping[str, Mapping[str, Any]],
+) -> str | None:
+    """Classify one collaborative round using non-error votes only."""
+    parsed = _parsed_votes(votes, adversarial=False)
+    usable = [vote for vote in parsed.values() if vote["verdict"] != "verification-error"]
+    if not usable:
+        return None
+    agreeing = sum(vote["verdict"] in {"agree", "supplement"} for vote in usable)
+    disagreeing = sum(vote["verdict"] == "disagree" for vote in usable)
+    if agreeing == len(usable):
+        return "full-consensus"
+    if disagreeing == len(usable):
+        return "worker-unique"
+    if agreeing > len(usable) / 2:
+        return "partial-consensus"
+    return None
+
+
+def classify_adversarial_round(
+    votes: Mapping[str, Mapping[str, Any]],
+) -> str | None:
+    """Classify one adversarial round using documented refutation bases."""
+    parsed = _parsed_votes(votes, adversarial=True)
+    usable = [vote for vote in parsed.values() if vote["verdict"] != "verification-error"]
+    if not usable:
+        return None
+    disagrees = [vote for vote in usable if vote["verdict"] == "disagree"]
+    if not disagrees:
+        return (
+            "partial-consensus"
+            if any(vote["verdict"] == "supplement" for vote in usable)
+            else "full-consensus"
+        )
+    if len(disagrees) == len(usable):
+        return "worker-unique"
+    if any(vote["disagreeBasis"] == "counter-evidence" for vote in disagrees):
+        return None
+    burden_count = sum(
+        vote["disagreeBasis"] == "burden-not-met" for vote in disagrees
+    )
+    if burden_count > len(usable) / 2:
+        return None
+    return "partial-consensus"
+
+
+def apply_round_results(
+    state: Mapping[str, Any],
+    plan: Mapping[str, Any],
+    results: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Validate and reduce one complete re-verification round."""
+    current = _object(state, "working state")
+    expected_plan = plan_next_round(current)
+    supplied_plan = _object(plan, "round plan")
+    if expected_plan.get("action") != "dispatch":
+        raise ConvergenceContractError("working state has no dispatch round to apply")
+    if supplied_plan != expected_plan:
+        raise ConvergenceContractError("round plan does not match current working state")
+    payload = _object(results, "round results")
+    if payload.get("schemaVersion") != WORKING_SCHEMA_VERSION:
+        raise ConvergenceContractError("round results schemaVersion must be 1.0")
+    if payload.get("round") != expected_plan["round"]:
+        raise ConvergenceContractError("round results round does not match plan round")
+
+    statuses = _parse_dispatch_results(payload.get("dispatches"), expected_plan)
+    raw_votes = _object(payload.get("votesByFinding"), "votesByFinding")
+    planned_by_finding = _planned_workers_by_finding(expected_plan)
+    votes_by_finding = _validate_round_votes(
+        raw_votes,
+        planned_by_finding,
+        statuses,
+    )
+    updated = deepcopy(dict(current))
+    queue = list(updated["queueFindingIds"])
+    findings = {row["findingId"]: row for row in updated["findings"]}
+    adversarial = bool(updated["config"].get("adversarial"))
+    resolved: list[str] = []
+    for finding_id in queue:
+        finding = findings[finding_id]
+        round_votes = _votes_for_finding(
+            finding_id,
+            planned_by_finding,
+            statuses,
+            votes_by_finding,
+            adversarial,
+        )
+        finding["rounds"].append(
+            {"round": expected_plan["round"], "votes": round_votes}
+        )
+        classification = (
+            classify_adversarial_round(round_votes)
+            if adversarial
+            else classify_collaborative_round(round_votes)
+        )
+        if classification is not None:
+            finding["classification"] = classification
+            resolved.append(finding_id)
+        _recompute_worker_positions(finding, updated["workers"])
+    updated["queueFindingIds"] = [
+        finding_id for finding_id in queue if finding_id not in set(resolved)
+    ]
+    dispatch_history = [
+        {
+            "worker": row["worker"],
+            "status": statuses[row["worker"]]["status"],
+            "durationMs": statuses[row["worker"]]["durationMs"],
+        }
+        for row in expected_plan["dispatches"]
+    ]
+    skipped = deepcopy(expected_plan["skippedWorkers"])
+    for row in dispatch_history:
+        if row["status"] != "completed":
+            skipped.append(
+                {
+                    "worker": row["worker"],
+                    "reason": "dispatch-non-result",
+                    "terminalStatus": row["status"],
+                }
+            )
+    updated["roundHistory"].append(
+        {
+            "round": expected_plan["round"],
+            "inputQueueSize": len(queue),
+            "resolvedCount": len(resolved),
+            "carriedForwardCount": len(updated["queueFindingIds"]),
+            "dispatches": dispatch_history,
+            "skippedWorkers": skipped,
+        }
+    )
+    if dispatch_history and all(
+        row["status"] != "completed" for row in dispatch_history
+    ):
+        updated["stopReason"] = "all-reverify-non-result"
+    return updated
+
+
+def finalize_working_state(state: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the public schema-v1.2 convergence artifact."""
+    errors = validate_working_state(state)
+    if errors:
+        raise ConvergenceContractError("invalid working state: " + "; ".join(errors))
+    current = deepcopy(dict(state))
+    config = deepcopy(current["config"])
+    findings = deepcopy(current["findings"])
+    queue = set(current["queueFindingIds"])
+    adversarial = bool(config.get("adversarial"))
+    for finding in findings:
+        if finding["findingId"] not in queue:
+            continue
+        finding["classification"] = (
+            "contested"
+            if adversarial
+            else _final_collaborative_classification(finding)
+        )
+    stop_reason = current.get("stopReason")
+    history = deepcopy(current["roundHistory"])
+    if stop_reason == "auto-disabled":
+        config["autoDisabled"] = "fewer-than-two-analysers"
+        skip_reason = "auto-disabled"
+        final_state = "converged"
+    elif config["effectiveMaxRounds"] == 1 and history:
+        skip_reason = "max-rounds-1"
+        if stop_reason == "all-reverify-non-result":
+            final_state = "aborted-non-result"
+        elif not queue:
+            final_state = "converged"
+        else:
+            final_state = "max-rounds-reached"
+    elif stop_reason == "all-reverify-non-result":
+        skip_reason = "all-reverify-non-result"
+        final_state = "aborted-non-result"
+    elif len(history) >= 2:
+        skip_reason = "not-skipped"
+        final_state = "converged" if not queue else "max-rounds-reached"
+    elif not queue:
+        skip_reason = "queue-empty"
+        final_state = "converged"
+    else:
+        skip_reason = "not-skipped"
+        final_state = "max-rounds-reached"
+    final = {
+        "schemaVersion": FINAL_SCHEMA_VERSION,
+        "taskKey": current["taskKey"],
+        "config": config,
+        "findings": findings,
+        "roundHistory": history,
+        "round2SkippedReason": skip_reason,
+        "finalState": final_state,
+        "totalRounds": len(history),
+        "finalClassificationCounts": classification_counts_from_findings(findings),
+    }
+    final_errors = validate_final_state(final)
+    if final_errors:
+        raise ConvergenceContractError(
+            "finalized convergence state is invalid: " + "; ".join(final_errors)
+        )
+    return final
+
+
+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")
+    if not _nonempty_string(state.get("taskKey")):
+        errors.append("taskKey must be a non-empty string")
+    digest = state.get("groupsDigest")
+    if not isinstance(digest, str) or len(digest) != 64:
+        errors.append("groupsDigest must be a SHA-256 hex digest")
+    config = state.get("config")
+    if not isinstance(config, Mapping):
+        errors.append("config must be an object")
+    workers = state.get("workers")
+    if not isinstance(workers, list):
+        errors.append("workers must be an array")
+        workers = []
+    findings = state.get("findings")
+    if not isinstance(findings, list):
+        errors.append("findings must be an array")
+        findings = []
+    queue = state.get("queueFindingIds")
+    if not isinstance(queue, list):
+        errors.append("queueFindingIds must be an array")
+        queue = []
+    elif len(queue) != len(set(queue)):
+        errors.append("duplicate queue finding ID")
+    history = state.get("roundHistory")
+    if not isinstance(history, list):
+        errors.append("roundHistory must be an array")
+        history = []
+    errors.extend(_validate_round_history(history))
+    by_id: dict[str, Mapping[str, Any]] = {}
+    for finding in findings:
+        if not isinstance(finding, Mapping):
+            errors.append("finding must be an object")
+            continue
+        finding_id = finding.get("findingId")
+        if not _nonempty_string(finding_id):
+            errors.append("findingId must be a non-empty string")
+            continue
+        if finding_id in by_id:
+            errors.append(f"duplicate findingId: {finding_id}")
+        by_id[str(finding_id)] = finding
+        errors.extend(_validate_finding_ledger(finding, len(history), bool(config and config.get("adversarial"))))
+    for finding_id in queue:
+        if finding_id not in by_id:
+            errors.append(f"queue references missing finding: {finding_id}")
+        elif by_id[finding_id].get("classification") is not None:
+            errors.append(f"queued finding is already classified: {finding_id}")
+    for finding_id, finding in by_id.items():
+        if finding.get("classification") is None and finding_id not in queue:
+            errors.append(f"unclassified finding is absent from queue: {finding_id}")
+    if history and history[-1].get("carriedForwardCount") != len(queue):
+        errors.append("last round carriedForwardCount disagrees with queue length")
+    if state.get("stopReason") not in {None, "auto-disabled", "all-reverify-non-result"}:
+        errors.append("stopReason is unsupported")
+    return errors
+
+
+def validate_final_state(state: Mapping[str, Any]) -> list[str]:
+    """Validate historical v1.0/v1.1 and current v1.2 final artifacts."""
+    errors: list[str] = []
+    if not isinstance(state, Mapping):
+        return ["final state must be an object"]
+    if state.get("schemaVersion") not in {"1.0", "1.1", "1.2"}:
+        errors.append("unsupported final schemaVersion")
+    config = state.get("config")
+    if not isinstance(config, Mapping):
+        errors.append("config must be an object")
+        config = {}
+    effective = config.get("effectiveMaxRounds")
+    if not isinstance(effective, int) or isinstance(effective, bool) or not 1 <= effective <= 3:
+        errors.append("config.effectiveMaxRounds must be an integer from 1 to 3")
+    findings = state.get("findings")
+    if not isinstance(findings, list):
+        errors.append("findings must be an array")
+        findings = []
+    history = state.get("roundHistory")
+    if not isinstance(history, list):
+        errors.append("roundHistory must be an array")
+        history = []
+    errors.extend(_validate_round_history(history))
+    adversarial = bool(config.get("adversarial"))
+    seen_ids: set[str] = set()
+    for finding in findings:
+        if not isinstance(finding, Mapping):
+            errors.append("finding must be an object")
+            continue
+        finding_id = finding.get("findingId")
+        if _nonempty_string(finding_id):
+            if finding_id in seen_ids:
+                errors.append(f"duplicate findingId: {finding_id}")
+            seen_ids.add(str(finding_id))
+        classification = finding.get("classification")
+        if classification not in _CLASSIFICATION_COUNT_KEYS:
+            errors.append(f"finding {finding_id} has invalid classification")
+        errors.extend(_validate_finding_ledger(finding, len(history), adversarial))
+        rounds = finding.get("rounds") if isinstance(finding.get("rounds"), list) else []
+        if classification == "contested" and rounds:
+            if rounds[-1].get("round") != len(history):
+                errors.append(f"finding {finding_id} contested before the final round")
+        if classification != "contested":
+            errors.extend(_validate_no_reappearance_after_resolution(finding, adversarial))
+        expected = _expected_final_classification(finding, adversarial)
+        if expected is not None and classification != expected:
+            errors.append(
+                f"finding {finding_id} classification {classification} "
+                f"does not match replayed classification {expected}"
+            )
+    errors.extend(_validate_round_ledger_counts(findings, history, adversarial))
+    total_rounds = state.get("totalRounds")
+    if total_rounds != len(history):
+        errors.append("totalRounds does not match roundHistory length")
+    declared = state.get("finalClassificationCounts")
+    if not isinstance(declared, Mapping):
+        errors.append("finalClassificationCounts must be an object")
+    else:
+        actual = classification_counts_from_findings(findings)
+        if dict(declared) != actual:
+            errors.append(
+                f"finalClassificationCounts {dict(declared)} does not match findings {actual}"
+            )
+    reason = state.get("round2SkippedReason")
+    errors.extend(
+        _validate_final_reason(
+            reason,
+            state.get("finalState"),
+            history,
+            effective,
+            config,
+        )
+    )
+    return errors
+
+
+def _final_collaborative_classification(finding: Mapping[str, Any]) -> str:
+    usable: list[Mapping[str, Any]] = []
+    for round_row in finding.get("rounds", []):
+        for vote in round_row.get("votes", {}).values():
+            if vote.get("verdict") != "verification-error":
+                usable.append(vote)
+    agreeing = sum(vote.get("verdict") in {"agree", "supplement"} for vote in usable)
+    return "partial-consensus" if usable and agreeing > len(usable) / 2 else "contested"
+
+
+def _expected_final_classification(
+    finding: Mapping[str, Any],
+    adversarial: bool,
+) -> str | None:
+    rounds = finding.get("rounds")
+    if not isinstance(rounds, list) or not rounds:
+        return None
+    for row in rounds:
+        if not isinstance(row, Mapping) or not isinstance(row.get("votes"), Mapping):
+            continue
+        try:
+            resolved = (
+                classify_adversarial_round(row["votes"])
+                if adversarial
+                else classify_collaborative_round(row["votes"])
+            )
+        except ConvergenceContractError:
+            continue
+        if resolved is not None:
+            return resolved
+    return "contested" if adversarial else _final_collaborative_classification(finding)
+
+
+def _validate_round_ledger_counts(
+    findings: list[Any],
+    history: list[Any],
+    adversarial: bool,
+) -> list[str]:
+    errors: list[str] = []
+    for round_number, history_row in enumerate(history, start=1):
+        if not isinstance(history_row, Mapping):
+            continue
+        ledgers = _round_ledgers(findings, round_number)
+        resolved = _resolved_ledger_count(ledgers, adversarial)
+        expected = (len(ledgers), resolved, len(ledgers) - resolved)
+        actual = (
+            history_row.get("inputQueueSize"),
+            history_row.get("resolvedCount"),
+            history_row.get("carriedForwardCount"),
+        )
+        if actual != expected:
+            errors.append(
+                f"round {round_number} counters {actual} do not match finding ledgers {expected}"
+            )
+    return errors
+
+
+def _round_ledgers(
+    findings: list[Any],
+    round_number: int,
+) -> list[Mapping[str, Any]]:
+    ledgers: list[Mapping[str, Any]] = []
+    for finding in findings:
+        if not isinstance(finding, Mapping):
+            continue
+        rounds = finding.get("rounds")
+        if not isinstance(rounds, list):
+            continue
+        ledgers.extend(
+            row
+            for row in rounds
+            if isinstance(row, Mapping) and row.get("round") == round_number
+        )
+    return ledgers
+
+
+def _resolved_ledger_count(
+    ledgers: list[Mapping[str, Any]],
+    adversarial: bool,
+) -> int:
+    resolved = 0
+    for row in ledgers:
+        votes = row.get("votes")
+        if not isinstance(votes, Mapping):
+            continue
+        try:
+            classification = (
+                classify_adversarial_round(votes)
+                if adversarial
+                else classify_collaborative_round(votes)
+            )
+        except ConvergenceContractError:
+            continue
+        resolved += classification is not None
+    return resolved
+
+
+def _validate_round_history(history: list[Any]) -> list[str]:
+    errors: list[str] = []
+    previous_carry = None
+    for index, row in enumerate(history, start=1):
+        if not isinstance(row, Mapping):
+            errors.append(f"roundHistory[{index - 1}] must be an object")
+            continue
+        if row.get("round") != index:
+            errors.append("roundHistory has duplicate or gapped round numbers")
+        input_size = row.get("inputQueueSize")
+        resolved = row.get("resolvedCount")
+        carried = row.get("carriedForwardCount")
+        if not all(isinstance(value, int) for value in (input_size, resolved, carried)):
+            errors.append(f"round {index} counters must be integers")
+        elif input_size != resolved + carried:
+            errors.append(f"round arithmetic mismatch at round {index}")
+        if previous_carry is not None and input_size != previous_carry:
+            errors.append(f"next-round input mismatch at round {index}")
+        previous_carry = carried
+        dispatches = row.get("dispatches")
+        if not isinstance(dispatches, list):
+            errors.append(f"round {index} dispatches must be an array")
+        else:
+            for dispatch in dispatches:
+                if not isinstance(dispatch, Mapping) or dispatch.get("status") not in _DISPATCH_STATUSES:
+                    errors.append(f"round {index} has invalid dispatch status")
+    return errors
+
+
+def _validate_finding_ledger(
+    finding: Mapping[str, Any],
+    total_rounds: int,
+    adversarial: bool,
+) -> list[str]:
+    errors: list[str] = []
+    finding_id = finding.get("findingId")
+    origin = finding.get("originWorker")
+    rounds = finding.get("rounds")
+    if not isinstance(rounds, list):
+        return [f"finding {finding_id} rounds must be an array"]
+    expected_round = 1
+    for row in rounds:
+        if not isinstance(row, Mapping):
+            errors.append(f"finding {finding_id} round ledger must be an object")
+            continue
+        round_number = row.get("round")
+        if round_number != expected_round:
+            errors.append(f"finding {finding_id} has duplicate or gapped round ledger")
+        expected_round += 1
+        if not isinstance(round_number, int) or round_number > total_rounds:
+            errors.append(f"finding {finding_id} references a non-executed round")
+        votes = row.get("votes")
+        if not isinstance(votes, Mapping):
+            errors.append(f"finding {finding_id} votes must be an object")
+            continue
+        if origin in votes:
+            errors.append(f"finding {finding_id} contains an origin worker vote")
+        for worker, vote in votes.items():
+            try:
+                _parse_vote(vote, adversarial=adversarial)
+            except ConvergenceContractError as exc:
+                errors.append(f"finding {finding_id} vote {worker}: {exc}")
+    return errors
+
+
+def _validate_no_reappearance_after_resolution(
+    finding: Mapping[str, Any],
+    adversarial: bool,
+) -> list[str]:
+    rounds = finding.get("rounds")
+    if not isinstance(rounds, list):
+        return []
+    for index, row in enumerate(rounds[:-1]):
+        votes = row.get("votes") if isinstance(row, Mapping) else None
+        if not isinstance(votes, Mapping):
+            continue
+        try:
+            classification = (
+                classify_adversarial_round(votes)
+                if adversarial
+                else classify_collaborative_round(votes)
+            )
+        except ConvergenceContractError:
+            continue
+        if classification is not None:
+            return [
+                f"finding {finding.get('findingId')} reappears after resolution in round {index + 1}"
+            ]
+    return []
+
+
+def _validate_final_reason(
+    reason: Any,
+    final_state: Any,
+    history: list[Any],
+    effective_max: Any,
+    config: Mapping[str, Any],
+) -> list[str]:
+    errors: list[str] = []
+    allowed = {
+        "auto-disabled",
+        "queue-empty",
+        "max-rounds-1",
+        "all-reverify-non-result",
+        "not-skipped",
+    }
+    if reason not in allowed:
+        return ["round2SkippedReason is unsupported"]
+    last_dispatches = history[-1].get("dispatches", []) if history else []
+    all_non_result = bool(last_dispatches) and all(
+        isinstance(row, Mapping) and row.get("status") != "completed"
+        for row in last_dispatches
+    )
+    auto_disabled = (
+        config.get("enabled") is False
+        or config.get("autoDisabled") == "fewer-than-two-analysers"
+    )
+    expected_reason = None
+    if auto_disabled:
+        expected_reason = "auto-disabled"
+    elif effective_max == 1 and history:
+        expected_reason = "max-rounds-1"
+    elif all_non_result:
+        expected_reason = "all-reverify-non-result"
+    elif len(history) >= 2:
+        expected_reason = "not-skipped"
+    elif not history or history[-1].get("carriedForwardCount") == 0:
+        expected_reason = "queue-empty"
+    if expected_reason is not None and reason != expected_reason:
+        errors.append(
+            f"round2SkippedReason {reason} does not match replayed reason {expected_reason}"
+        )
+    queue_drained = bool(history) and history[-1].get("carriedForwardCount") == 0
+    if all_non_result:
+        expected_state = "aborted-non-result"
+    elif reason in {"auto-disabled", "queue-empty"} or queue_drained:
+        expected_state = "converged"
+    else:
+        expected_state = "max-rounds-reached"
+    if reason == "all-reverify-non-result" and not all_non_result:
+        errors.append("all-reverify-non-result requires only non-result dispatches")
+    if reason == "max-rounds-1" and effective_max != 1:
+        errors.append("max-rounds-1 requires effectiveMaxRounds=1")
+    if reason == "queue-empty" and history and history[-1].get("carriedForwardCount") != 0:
+        errors.append("queue-empty requires zero carriedForwardCount")
+    if reason == "not-skipped" and len(history) < 2:
+        errors.append("not-skipped requires at least two rounds")
+    if final_state != expected_state:
+        errors.append(
+            f"finalState {final_state} is inconsistent with round2SkippedReason {reason}"
+        )
+    return errors
+
+
+def _nonempty_string(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _parse_dispatch_results(
+    value: Any,
+    plan: Mapping[str, Any],
+) -> dict[str, dict[str, Any]]:
+    if not isinstance(value, list):
+        raise ConvergenceContractError("round results dispatches must be an array")
+    planned_workers = [row["worker"] for row in plan["dispatches"]]
+    statuses: dict[str, dict[str, Any]] = {}
+    for index, raw in enumerate(value):
+        row = _object(raw, f"round results dispatches[{index}]")
+        worker = _required_string(row, "worker", f"round results dispatches[{index}]")
+        if worker in statuses:
+            raise ConvergenceContractError(f"duplicate dispatch result: {worker}")
+        if worker not in planned_workers:
+            raise ConvergenceContractError(f"unplanned worker in dispatch results: {worker}")
+        status = _required_string(row, "status", f"dispatch {worker}")
+        if status not in _DISPATCH_STATUSES:
+            raise ConvergenceContractError(f"dispatch {worker} has invalid status")
+        duration = row.get("durationMs")
+        if not isinstance(duration, int) or isinstance(duration, bool) or duration < 0:
+            raise ConvergenceContractError(
+                f"dispatch {worker}.durationMs must be a non-negative integer"
+            )
+        statuses[worker] = {"status": status, "durationMs": duration}
+    missing = [worker for worker in planned_workers if worker not in statuses]
+    if missing:
+        raise ConvergenceContractError(
+            "missing status for planned dispatch: " + ", ".join(missing)
+        )
+    return statuses
+
+
+def _planned_workers_by_finding(
+    plan: Mapping[str, Any],
+) -> dict[str, list[str]]:
+    planned: dict[str, list[str]] = {}
+    for row in plan["dispatches"]:
+        for finding_id in row["findingIds"]:
+            planned.setdefault(finding_id, []).append(row["worker"])
+    return planned
+
+
+def _validate_round_votes(
+    raw_votes: Mapping[str, Any],
+    planned_by_finding: Mapping[str, list[str]],
+    statuses: Mapping[str, Mapping[str, Any]],
+) -> dict[str, dict[str, Mapping[str, Any]]]:
+    parsed: dict[str, dict[str, Mapping[str, Any]]] = {}
+    for finding_id, worker_votes_value in raw_votes.items():
+        if finding_id not in planned_by_finding:
+            raise ConvergenceContractError(f"unplanned finding in votes: {finding_id}")
+        worker_votes = _object(worker_votes_value, f"votesByFinding.{finding_id}")
+        parsed[finding_id] = {}
+        for worker, vote_value in worker_votes.items():
+            if worker not in planned_by_finding[finding_id]:
+                raise ConvergenceContractError(
+                    f"origin worker or unplanned worker voted on {finding_id}: {worker}"
+                )
+            if statuses[worker]["status"] != "completed":
+                raise ConvergenceContractError(
+                    f"non-result dispatch supplied a vote: {worker} {finding_id}"
+                )
+            parsed[finding_id][worker] = _object(
+                vote_value, f"votesByFinding.{finding_id}.{worker}"
+            )
+    for finding_id, workers in planned_by_finding.items():
+        for worker in workers:
+            if statuses[worker]["status"] == "completed" and worker not in parsed.get(
+                finding_id, {}
+            ):
+                raise ConvergenceContractError(
+                    f"missing vote for completed worker {worker} on {finding_id}"
+                )
+    return parsed
+
+
+def _votes_for_finding(
+    finding_id: str,
+    planned_by_finding: Mapping[str, list[str]],
+    statuses: Mapping[str, Mapping[str, Any]],
+    votes_by_finding: Mapping[str, Mapping[str, Mapping[str, Any]]],
+    adversarial: bool,
+) -> dict[str, dict[str, Any]]:
+    votes: dict[str, dict[str, Any]] = {}
+    for worker in planned_by_finding.get(finding_id, []):
+        status = statuses[worker]["status"]
+        if status == "completed":
+            votes[worker] = _parse_vote(
+                votes_by_finding[finding_id][worker], adversarial=adversarial
+            )
+        else:
+            votes[worker] = {
+                "verdict": "verification-error",
+                "disagreeBasis": None,
+                "explanation": f"dispatch ended with terminal status {status}",
+            }
+    return votes
+
+
+def _recompute_worker_positions(
+    finding: dict[str, Any],
+    workers: list[Mapping[str, Any]],
+) -> None:
+    source_workers = set(finding.get("discoveredBy", {}).keys())
+    consensus = set(source_workers)
+    dissent = set()
+    for round_row in finding.get("rounds", []):
+        for worker, vote in round_row.get("votes", {}).items():
+            if vote.get("verdict") in {"agree", "supplement"}:
+                consensus.add(worker)
+                dissent.discard(worker)
+            elif vote.get("verdict") == "disagree":
+                dissent.add(worker)
+                consensus.discard(worker)
+    roster = [
+        worker.get("workerId")
+        for worker in workers
+        if worker.get("audience") == "analysis"
+    ]
+    finding["consensusWorkers"] = [worker for worker in roster if worker in consensus]
+    finding["dissentingWorkers"] = [worker for worker in roster if worker in dissent]
+
+
+def _parsed_votes(
+    votes: Mapping[str, Mapping[str, Any]],
+    *,
+    adversarial: bool,
+) -> dict[str, dict[str, Any]]:
+    if not isinstance(votes, Mapping):
+        raise ConvergenceContractError("votes must be an object")
+    return {
+        worker: _parse_vote(vote, adversarial=adversarial)
+        for worker, vote in votes.items()
+    }
+
+
+def _parse_vote(value: Any, *, adversarial: bool) -> dict[str, Any]:
+    vote = _object(value, "vote")
+    verdict = _required_string(vote, "verdict", "vote")
+    if verdict not in _VERDICTS:
+        raise ConvergenceContractError(f"unsupported vote verdict: {verdict}")
+    explanation = _required_string(vote, "explanation", "vote")
+    basis = vote.get("disagreeBasis")
+    if verdict == "disagree" and adversarial:
+        if basis not in _DISAGREE_BASES:
+            raise ConvergenceContractError(
+                "adversarial disagree vote requires disagreeBasis"
+            )
+    elif basis is not None:
+        raise ConvergenceContractError(
+            "disagreeBasis is allowed only for adversarial disagree votes"
+        )
+    return {
+        "verdict": verdict,
+        "disagreeBasis": basis,
+        "explanation": explanation,
+    }
+
+
+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")
+    queue_value = state.get("queueFindingIds")
+    if not isinstance(queue_value, list) or not all(
+        isinstance(item, str) and item for item in queue_value
+    ):
+        raise ConvergenceContractError(
+            "working state.queueFindingIds must be a string array"
+        )
+    queue = list(queue_value)
+    if len(queue) != len(set(queue)):
+        raise ConvergenceContractError("duplicate queue finding ID")
+    finding_rows = state.get("findings")
+    if not isinstance(finding_rows, list):
+        raise ConvergenceContractError("working state.findings must be an array")
+    findings: dict[str, Mapping[str, Any]] = {}
+    for row in finding_rows:
+        finding = _object(row, "working state finding")
+        finding_id = _required_string(finding, "findingId", "working state finding")
+        if finding_id in findings:
+            raise ConvergenceContractError(f"duplicate findingId: {finding_id}")
+        findings[finding_id] = finding
+    for finding_id in queue:
+        finding = findings.get(finding_id)
+        if finding is None:
+            raise ConvergenceContractError(
+                f"queue references missing finding: {finding_id}"
+            )
+        if finding.get("classification") is not None:
+            raise ConvergenceContractError(
+                f"queued finding is already classified: {finding_id}"
+            )
+    history_value = state.get("roundHistory")
+    if not isinstance(history_value, list):
+        raise ConvergenceContractError("working state.roundHistory must be an array")
+    history = [_object(row, "round history row") for row in history_value]
+    if history:
+        carried = history[-1].get("carriedForwardCount")
+        if carried != len(queue):
+            raise ConvergenceContractError(
+                "last round carriedForwardCount disagrees with current queue length"
+            )
+    return queue, findings, history
+
+
+def _parse_config(value: Any) -> dict[str, Any]:
+    config = _object(value, "config")
+    enabled = config.get("enabled")
+    adversarial = config.get("adversarial")
+    if not isinstance(enabled, bool):
+        raise ConvergenceContractError("config.enabled must be boolean")
+    if not isinstance(adversarial, bool):
+        raise ConvergenceContractError("config.adversarial must be boolean")
+    max_rounds = _round_limit(config.get("maxRounds"), "maxRounds")
+    effective = _round_limit(
+        config.get("effectiveMaxRounds"), "effectiveMaxRounds"
+    )
+    if effective > max_rounds:
+        raise ConvergenceContractError(
+            "config.effectiveMaxRounds cannot exceed maxRounds"
+        )
+    mode = _required_string(config, "verificationMode", "config")
+    if mode not in _VERIFICATION_MODES:
+        raise ConvergenceContractError("config.verificationMode is unsupported")
+    if adversarial and mode != "full-reanalysis":
+        raise ConvergenceContractError(
+            "adversarial convergence requires full-reanalysis verificationMode"
+        )
+    return {
+        "enabled": enabled,
+        "adversarial": adversarial,
+        "maxRounds": max_rounds,
+        "effectiveMaxRounds": effective,
+        "verificationMode": mode,
+    }
+
+
+def _parse_workers(value: Any) -> list[dict[str, str]]:
+    if not isinstance(value, list):
+        raise ConvergenceContractError("workers must be an array")
+    workers: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for index, raw in enumerate(value):
+        worker = _object(raw, f"workers[{index}]")
+        worker_id = _required_string(worker, "workerId", f"workers[{index}]")
+        audience = _required_string(worker, "audience", f"workers[{index}]")
+        if audience not in _AUDIENCES:
+            raise ConvergenceContractError(
+                f"workers[{index}] has unsupported audience: {audience}"
+            )
+        if worker_id in seen:
+            raise ConvergenceContractError(f"duplicate workerId: {worker_id}")
+        seen.add(worker_id)
+        workers.append({"workerId": worker_id, "audience": audience})
+    return workers
+
+
+def _parse_groups(
+    value: Any,
+    analysis_workers: list[str],
+) -> tuple[list[dict[str, Any]], list[str]]:
+    if not isinstance(value, list):
+        raise ConvergenceContractError("groups must be an array")
+    findings: list[dict[str, Any]] = []
+    queue: list[str] = []
+    seen_ids: set[str] = set()
+    for index, raw in enumerate(value):
+        group = _object(raw, f"groups[{index}]")
+        finding_id = _required_string(group, "findingId", f"groups[{index}]")
+        if finding_id in seen_ids:
+            raise ConvergenceContractError(f"duplicate findingId: {finding_id}")
+        seen_ids.add(finding_id)
+        finding, source_workers = _parse_group(group, index, analysis_workers)
+        if len(source_workers) >= 2:
+            finding["classification"] = "full-consensus"
+        else:
+            queue.append(finding_id)
+        findings.append(finding)
+    return findings, queue
+
+
+def _parse_group(
+    group: Mapping[str, Any],
+    index: int,
+    analysis_workers: list[str],
+) -> tuple[dict[str, Any], list[str]]:
+    label = f"groups[{index}]"
+    origin = _required_string(group, "originWorker", label)
+    if origin not in analysis_workers:
+        raise ConvergenceContractError(
+            f"{label}.originWorker is outside the analysis roster: {origin}"
+        )
+    origin_evidence = _required_string(group, "originEvidence", label)
+    discovered_by = _parse_discovered_by(
+        group.get("discoveredBy"), label, analysis_workers
+    )
+    if origin not in discovered_by:
+        raise ConvergenceContractError(
+            f"{label}.originWorker must appear in discoveredBy"
+        )
+    source_items = _parse_source_items(
+        group.get("sourceItems"), label, analysis_workers
+    )
+    source_workers = [
+        worker_id
+        for worker_id in analysis_workers
+        if worker_id in discovered_by
+        or any(item["worker"] == worker_id for item in source_items)
+    ]
+    return {
+        "findingId": _required_string(group, "findingId", label),
+        "summary": _required_string(group, "summary", label),
+        "category": _required_string(group, "category", label),
+        "ticketIds": _string_array(group.get("ticketIds"), f"{label}.ticketIds"),
+        "originWorker": origin,
+        "originEvidence": origin_evidence,
+        "discoveredBy": discovered_by,
+        "sourceItems": source_items,
+        "classification": None,
+        "rounds": [],
+        "consensusWorkers": source_workers,
+        "dissentingWorkers": [],
+    }, source_workers
+
+
+def _parse_discovered_by(
+    value: Any,
+    label: str,
+    analysis_workers: list[str],
+) -> dict[str, dict[str, str]]:
+    raw = _object(value, f"{label}.discoveredBy")
+    parsed: dict[str, dict[str, str]] = {}
+    for worker_id, details_value in raw.items():
+        if worker_id not in analysis_workers:
+            raise ConvergenceContractError(
+                f"{label}.discoveredBy contains non-analysis worker: {worker_id}"
+            )
+        details = _object(details_value, f"{label}.discoveredBy.{worker_id}")
+        parsed[worker_id] = {
+            "itemId": _required_string(
+                details, "itemId", f"{label}.discoveredBy.{worker_id}"
+            ),
+            "evidence": _required_string(
+                details, "evidence", f"{label}.discoveredBy.{worker_id}"
+            ),
+        }
+    if not parsed:
+        raise ConvergenceContractError(f"{label}.discoveredBy must not be empty")
+    return parsed
+
+
+def _parse_source_items(
+    value: Any,
+    label: str,
+    analysis_workers: list[str],
+) -> list[dict[str, str]]:
+    if not isinstance(value, list) or not value:
+        raise ConvergenceContractError(f"{label}.sourceItems must be a non-empty array")
+    items: list[dict[str, str]] = []
+    for index, raw in enumerate(value):
+        item = _object(raw, f"{label}.sourceItems[{index}]")
+        worker = _required_string(item, "worker", f"{label}.sourceItems[{index}]")
+        if worker not in analysis_workers:
+            raise ConvergenceContractError(
+                f"{label}.sourceItems contains non-analysis worker {worker}; "
+                "report-writer never votes"
+            )
+        items.append(
+            {
+                "worker": worker,
+                "itemId": _required_string(
+                    item, "itemId", f"{label}.sourceItems[{index}]"
+                ),
+            }
+        )
+    return items
+
+
+def _round_limit(value: Any, name: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= 3:
+        raise ConvergenceContractError(f"config.{name} must be an integer from 1 to 3")
+    return value
+
+
+def _string_array(value: Any, label: str) -> list[str]:
+    if not isinstance(value, list) or not value:
+        raise ConvergenceContractError(f"{label} must be a non-empty string array")
+    result = []
+    for item in value:
+        if not isinstance(item, str) or not item.strip():
+            raise ConvergenceContractError(f"{label} must contain non-empty strings")
+        result.append(item.strip())
+    return result
+
+
+def _object(value: Any, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ConvergenceContractError(f"{label} must be an object")
+    return value
+
+
+def _required_string(
+    payload: Mapping[str, Any],
+    key: str,
+    label: str,
+) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ConvergenceContractError(f"{label}.{key} must be a non-empty string")
+    return value.strip()