okstra 0.130.1 → 0.130.3

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -8,7 +8,7 @@ from typing import Any, Mapping
 
 
 WORKING_SCHEMA_VERSION = "1.0"
-FINAL_SCHEMA_VERSION = "1.2"
+FINAL_SCHEMA_VERSION = "1.3"
 _AUDIENCES = {"analysis", "report-writer"}
 _VERIFICATION_MODES = {"lightweight", "full-reanalysis"}
 _CLASSIFICATION_COUNT_KEYS = {
@@ -18,8 +18,23 @@ _CLASSIFICATION_COUNT_KEYS = {
     "worker-unique": "workerUnique",
 }
 _VERDICTS = {"agree", "disagree", "supplement", "verification-error"}
+_INPUT_VERDICTS = _VERDICTS | {"unverifiable"}
 _DISAGREE_BASES = {"counter-evidence", "burden-not-met"}
 _DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
+_CRITIC_CLASSIFICATIONS = set(_CLASSIFICATION_COUNT_KEYS) | {"unverified"}
+_FINAL_V13_KEYS = {
+    "schemaVersion",
+    "taskKey",
+    "config",
+    "findings",
+    "roundHistory",
+    "round2SkippedReason",
+    "finalState",
+    "totalRounds",
+    "finalClassificationCounts",
+    "criticVerification",
+    "unverifiedGaps",
+}
 
 
 class ConvergenceContractError(ValueError):
@@ -282,8 +297,68 @@ def apply_round_results(
     return updated
 
 
+def apply_critic_gap_results(
+    state: Mapping[str, Any],
+    results: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Reduce one coverage-critic verification batch into working state."""
+    current = _object(state, "working state")
+    errors = validate_working_state(current)
+    if errors:
+        raise ConvergenceContractError("invalid working state: " + "; ".join(errors))
+    current_critic = current.get("config", {}).get("critic")
+    if (
+        isinstance(current_critic, Mapping)
+        and current_critic.get("mode") == "acceptance-devils-advocate"
+    ):
+        raise ConvergenceContractError(
+            "acceptance critic candidates must use confirm-or-downgrade"
+        )
+    if current.get("criticVerification") is not None:
+        raise ConvergenceContractError("critic gap batch was already applied")
+    if plan_next_round(current).get("action") != "finalize":
+        raise ConvergenceContractError("main finding queue must be terminal")
+
+    payload = _object(results, "critic gap results")
+    provider, model, dispatches, gaps = _parse_critic_gap_results(current, payload)
+    updated = deepcopy(dict(current))
+    ledger_gaps, unverified = _reduce_critic_gaps(updated, provider, gaps)
+    updated["criticVerification"] = {
+        "schemaVersion": WORKING_SCHEMA_VERSION,
+        "provider": provider,
+        "modelExecutionValue": model,
+        "analyserRoster": [
+            worker["workerId"]
+            for worker in updated["workers"]
+            if worker["audience"] == "analysis"
+        ],
+        "dispatches": dispatches,
+        "gaps": ledger_gaps,
+    }
+    merged = sum(gap["mergedFindingId"] is not None for gap in ledger_gaps)
+    rejected = sum(
+        gap["classification"] in {"contested", "worker-unique"}
+        for gap in ledger_gaps
+    )
+    updated["config"]["critic"] = {
+        "provider": provider,
+        "modelExecutionValue": model,
+        "gapsProposed": len(ledger_gaps),
+        "gapsMerged": merged,
+        "gapsRejected": rejected,
+        "gapsUnverified": len(unverified),
+    }
+    updated["unverifiedGaps"] = unverified
+    updated_errors = validate_working_state(updated)
+    if updated_errors:
+        raise ConvergenceContractError(
+            "invalid updated working state: " + "; ".join(updated_errors)
+        )
+    return updated
+
+
 def finalize_working_state(state: Mapping[str, Any]) -> dict[str, Any]:
-    """Return the public schema-v1.2 convergence artifact."""
+    """Return the public schema-v1.3 convergence artifact."""
     errors = validate_working_state(state)
     if errors:
         raise ConvergenceContractError("invalid working state: " + "; ".join(errors))
@@ -337,6 +412,9 @@ def finalize_working_state(state: Mapping[str, Any]) -> dict[str, Any]:
         "totalRounds": len(history),
         "finalClassificationCounts": classification_counts_from_findings(findings),
     }
+    if "criticVerification" in current:
+        final["criticVerification"] = deepcopy(current["criticVerification"])
+        final["unverifiedGaps"] = deepcopy(current.get("unverifiedGaps", []))
     final_errors = validate_final_state(final)
     if final_errors:
         raise ConvergenceContractError(
@@ -364,6 +442,22 @@ def validate_working_state(state: Mapping[str, Any]) -> list[str]:
     if not isinstance(workers, list):
         errors.append("workers must be an array")
         workers = []
+    else:
+        seen_workers: set[str] = set()
+        for index, worker in enumerate(workers):
+            if not isinstance(worker, Mapping):
+                errors.append(f"workers[{index}] must be an object")
+                continue
+            worker_id = worker.get("workerId")
+            audience = worker.get("audience")
+            if not _nonempty_string(worker_id):
+                errors.append(f"workers[{index}].workerId must be a non-empty string")
+            elif worker_id in seen_workers:
+                errors.append(f"duplicate workerId: {worker_id}")
+            else:
+                seen_workers.add(worker_id)
+            if not _nonempty_string(audience) or audience not in _AUDIENCES:
+                errors.append(f"workers[{index}].audience is unsupported")
     findings = state.get("findings")
     if not isinstance(findings, list):
         errors.append("findings must be an array")
@@ -404,15 +498,17 @@ def validate_working_state(state: Mapping[str, Any]) -> list[str]:
         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")
+    errors.extend(_validate_critic_contract(state, findings))
     return errors
 
 
 def validate_final_state(state: Mapping[str, Any]) -> list[str]:
-    """Validate historical v1.0/v1.1 and current v1.2 final artifacts."""
+    """Validate historical v1.0-v1.2 and strict current v1.3 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"}:
+    version = state.get("schemaVersion")
+    if version not in {"1.0", "1.1", "1.2", FINAL_SCHEMA_VERSION}:
         errors.append("unsupported final schemaVersion")
     config = state.get("config")
     if not isinstance(config, Mapping):
@@ -437,10 +533,12 @@ def validate_final_state(state: Mapping[str, Any]) -> list[str]:
             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))
+        if not _nonempty_string(finding_id):
+            errors.append("findingId must be a non-empty string")
+        elif finding_id in seen_ids:
+            errors.append(f"duplicate findingId: {finding_id}")
+        else:
+            seen_ids.add(finding_id)
         classification = finding.get("classification")
         if classification not in _CLASSIFICATION_COUNT_KEYS:
             errors.append(f"finding {finding_id} has invalid classification")
@@ -480,9 +578,727 @@ def validate_final_state(state: Mapping[str, Any]) -> list[str]:
             config,
         )
     )
+    if version == FINAL_SCHEMA_VERSION:
+        unexpected = set(state) - _FINAL_V13_KEYS
+        if unexpected:
+            errors.append(
+                "final v1.3 has unsupported top-level fields: "
+                + ", ".join(sorted(unexpected))
+            )
+        errors.extend(_validate_critic_contract(state, findings))
     return errors
 
 
+def _parse_critic_gap_results(
+    state: Mapping[str, Any],
+    payload: Mapping[str, Any],
+) -> tuple[str, str, list[dict[str, Any]], list[dict[str, Any]]]:
+    if payload.get("schemaVersion") != WORKING_SCHEMA_VERSION:
+        raise ConvergenceContractError("critic gap results schemaVersion must be 1.0")
+    if payload.get("taskKey") != state.get("taskKey"):
+        raise ConvergenceContractError("critic gap results taskKey does not match")
+    if payload.get("mode") != "coverage":
+        raise ConvergenceContractError(
+            "apply-critic-gaps accepts coverage mode only; acceptance candidates "
+            "use confirm-or-downgrade"
+        )
+    provider = _required_string(payload, "provider", "critic gap results")
+    model = _required_string(payload, "modelExecutionValue", "critic gap results")
+    roster = {
+        worker["workerId"]
+        for worker in state.get("workers", [])
+        if isinstance(worker, Mapping) and worker.get("audience") == "analysis"
+    }
+    dispatches, completed = _parse_critic_dispatches(
+        payload.get("dispatches"), roster, provider
+    )
+    gaps = _parse_critic_gaps(payload.get("gaps"), roster, provider, completed)
+    return provider, model, dispatches, gaps
+
+
+def _parse_critic_dispatches(
+    value: Any,
+    roster: set[str],
+    provider: str,
+) -> tuple[list[dict[str, Any]], set[str]]:
+    if not isinstance(value, list):
+        raise ConvergenceContractError("critic gap results dispatches must be an array")
+    dispatches: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for index, raw in enumerate(value):
+        row = _object(raw, f"critic dispatches[{index}]")
+        worker = _required_string(row, "worker", f"critic dispatches[{index}]")
+        if worker in seen:
+            raise ConvergenceContractError(f"duplicate critic voter dispatch: {worker}")
+        if worker not in roster or _is_critic_worker(worker, provider):
+            raise ConvergenceContractError(
+                f"critic voter must be a non-critic analyser: {worker}"
+            )
+        status = _required_string(row, "status", f"critic dispatch {worker}")
+        duration = row.get("durationMs")
+        if status not in _DISPATCH_STATUSES:
+            raise ConvergenceContractError(f"critic dispatch {worker} has invalid status")
+        if not isinstance(duration, int) or isinstance(duration, bool) or duration < 0:
+            raise ConvergenceContractError(
+                f"critic dispatch {worker}.durationMs must be a non-negative integer"
+            )
+        seen.add(worker)
+        dispatches.append({"worker": worker, "status": status, "durationMs": duration})
+    expected = {
+        worker for worker in roster if not _is_critic_worker(worker, provider)
+    }
+    if seen != expected:
+        missing = sorted(expected - seen)
+        raise ConvergenceContractError(
+            "critic dispatches must account for every non-critic analyser exactly "
+            f"once; missing: {', '.join(missing) or 'none'}"
+        )
+    completed = {row["worker"] for row in dispatches if row["status"] == "completed"}
+    return dispatches, completed
+
+
+def _parse_critic_gaps(
+    value: Any,
+    roster: set[str],
+    provider: str,
+    completed: set[str],
+) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        raise ConvergenceContractError("critic gap results gaps must be an array")
+    gaps: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for index, raw in enumerate(value):
+        gap = _object(raw, f"critic gaps[{index}]")
+        gap_id = _required_string(gap, "gapId", f"critic gaps[{index}]")
+        if gap_id in seen:
+            raise ConvergenceContractError(f"duplicate critic gapId: {gap_id}")
+        seen.add(gap_id)
+        parsed = _parse_critic_gap(gap, index, roster, provider, completed)
+        parsed["gapId"] = gap_id
+        gaps.append(parsed)
+    return gaps
+
+
+def _parse_critic_gap(
+    gap: Mapping[str, Any],
+    index: int,
+    roster: set[str],
+    provider: str,
+    completed: set[str],
+) -> dict[str, Any]:
+    label = f"critic gaps[{index}]"
+    votes_value = _object(gap.get("votes"), f"{label}.votes")
+    votes: dict[str, dict[str, Any]] = {}
+    for worker, raw_vote in votes_value.items():
+        if worker not in roster or _is_critic_worker(worker, provider):
+            raise ConvergenceContractError(
+                f"critic voter must be a non-critic analyser: {worker}"
+            )
+        if worker not in completed:
+            raise ConvergenceContractError(
+                f"critic voter has no completed dispatch: {worker}"
+            )
+        votes[worker] = _parse_vote(
+            raw_vote,
+            adversarial=True,
+            allow_unverifiable=True,
+        )
+    parsed = {
+        "summary": _required_string(gap, "summary", label),
+        "category": _required_string(gap, "category", label),
+        "ticketIds": _string_array_allow_empty(
+            gap.get("ticketIds"), f"{label}.ticketIds"
+        ),
+        "originEvidence": _required_string(gap, "originEvidence", label),
+        "votes": votes,
+    }
+    if "evidenceArtifacts" in gap:
+        parsed["evidenceArtifacts"] = _parse_evidence_artifacts(
+            gap.get("evidenceArtifacts"), label
+        )
+    return parsed
+
+
+def _reduce_critic_gaps(
+    state: dict[str, Any],
+    provider: str,
+    gaps: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, str]]]:
+    ledger: list[dict[str, Any]] = []
+    unverified: list[dict[str, str]] = []
+    next_number = _next_finding_number(state["findings"])
+    for gap in gaps:
+        classification = _critic_gap_classification(gap["votes"])
+        merged_id = None
+        if classification in {"full-consensus", "partial-consensus"}:
+            merged_id = f"F-{next_number:03d}"
+            next_number += 1
+            state["findings"].append(
+                _critic_finding(gap, provider, merged_id, classification, state["workers"])
+            )
+        elif classification == "unverified":
+            unverified.append(
+                {
+                    "gapId": gap["gapId"],
+                    "summary": gap["summary"],
+                    "reason": "no usable analyser vote",
+                }
+            )
+        ledger.append(
+            {
+                "gapId": gap["gapId"],
+                "summary": gap["summary"],
+                "category": gap["category"],
+                "ticketIds": deepcopy(gap["ticketIds"]),
+                "originEvidence": gap["originEvidence"],
+                "classification": classification,
+                "mergedFindingId": merged_id,
+                "votes": deepcopy(gap["votes"]),
+                **(
+                    {"evidenceArtifacts": deepcopy(gap["evidenceArtifacts"])}
+                    if "evidenceArtifacts" in gap
+                    else {}
+                ),
+            }
+        )
+    return ledger, unverified
+
+
+def _critic_gap_classification(votes: Mapping[str, Mapping[str, Any]]) -> str:
+    usable = [vote for vote in votes.values() if vote["verdict"] != "verification-error"]
+    if not usable:
+        return "unverified"
+    return classify_adversarial_round(votes) or "contested"
+
+
+def _next_finding_number(findings: list[Mapping[str, Any]]) -> int:
+    numbers = []
+    for finding in findings:
+        finding_id = finding.get("findingId")
+        if isinstance(finding_id, str) and finding_id.startswith("F-"):
+            suffix = finding_id[2:]
+            if suffix.isdigit():
+                numbers.append(int(suffix))
+    return max(numbers, default=0) + 1
+
+
+def _critic_finding(
+    gap: Mapping[str, Any],
+    provider: str,
+    finding_id: str,
+    classification: str,
+    workers: list[Mapping[str, Any]],
+) -> dict[str, Any]:
+    agreeing = {
+        worker
+        for worker, vote in gap["votes"].items()
+        if vote["verdict"] in {"agree", "supplement"}
+    }
+    dissenting = {
+        worker for worker, vote in gap["votes"].items() if vote["verdict"] == "disagree"
+    }
+    roster = [row["workerId"] for row in workers if row.get("audience") == "analysis"]
+    finding = {
+        "findingId": finding_id,
+        "summary": gap["summary"],
+        "category": gap["category"],
+        "ticketIds": deepcopy(gap["ticketIds"]),
+        "originWorker": f"{provider}-critic",
+        "originEvidence": gap["originEvidence"],
+        "discoveredBy": {},
+        "sourceItems": [],
+        "source": "critic",
+        "classification": classification,
+        "rounds": [],
+        "consensusWorkers": [worker for worker in roster if worker in agreeing],
+        "dissentingWorkers": [worker for worker in roster if worker in dissenting],
+    }
+    if "evidenceArtifacts" in gap:
+        finding["evidenceArtifacts"] = deepcopy(gap["evidenceArtifacts"])
+    return finding
+
+
+def _validate_critic_contract(
+    state: Mapping[str, Any],
+    findings: list[Any],
+) -> list[str]:
+    config = state.get("config")
+    critic_config = config.get("critic") if isinstance(config, Mapping) else None
+    ledger = state.get("criticVerification")
+    unverified = state.get("unverifiedGaps")
+    critic_findings: dict[str, Mapping[str, Any]] = {}
+    errors: list[str] = []
+    for finding in findings:
+        if not isinstance(finding, Mapping) or finding.get("source") != "critic":
+            continue
+        finding_id = finding.get("findingId")
+        if not _nonempty_string(finding_id):
+            errors.append("findingId must be a non-empty string")
+            continue
+        critic_findings[finding_id] = finding
+    if (
+        isinstance(critic_config, Mapping)
+        and critic_config.get("mode") == "acceptance-devils-advocate"
+    ):
+        errors.extend(
+            _validate_acceptance_critic_summary(
+                critic_config, ledger, unverified, critic_findings
+            )
+        )
+        return errors
+    if ledger is None and critic_config is None and unverified is None:
+        if critic_findings:
+            errors.append("critic-origin finding requires criticVerification ledger")
+        return errors
+    if not isinstance(ledger, Mapping):
+        errors.append("criticVerification must be an object")
+        return errors
+    if not isinstance(critic_config, Mapping):
+        errors.append("config.critic must be an object")
+        critic_config = {}
+    if not isinstance(unverified, list):
+        errors.append("unverifiedGaps must be an array")
+        unverified = []
+    errors.extend(_validate_critic_ledger_shape(ledger))
+    errors.extend(_validate_critic_roster(state, ledger))
+    gaps = ledger.get("gaps") if isinstance(ledger.get("gaps"), list) else []
+    errors.extend(
+        _validate_critic_gap_links(
+            gaps,
+            critic_findings,
+            unverified,
+            critic_config,
+            ledger,
+        )
+    )
+    if critic_config.get("provider") != ledger.get("provider"):
+        errors.append("config.critic.provider does not match criticVerification")
+    if critic_config.get("modelExecutionValue") != ledger.get("modelExecutionValue"):
+        errors.append(
+            "config.critic.modelExecutionValue does not match criticVerification"
+        )
+    return errors
+
+
+def _validate_acceptance_critic_summary(
+    config: Mapping[str, Any],
+    ledger: Any,
+    unverified: Any,
+    critic_findings: Mapping[Any, Mapping[str, Any]],
+) -> list[str]:
+    allowed = {
+        "mode", "provider", "modelExecutionValue", "candidatesProposed",
+        "confirmedBlockers", "downgradedToResidual",
+    }
+    errors = [] if set(config) == allowed else [
+        "acceptance critic config has unsupported fields"
+    ]
+    counts = (
+        config.get("candidatesProposed"),
+        config.get("confirmedBlockers"),
+        config.get("downgradedToResidual"),
+    )
+    valid_counts = all(
+        isinstance(value, int) and not isinstance(value, bool) and value >= 0
+        for value in counts
+    )
+    if not valid_counts:
+        errors.append("acceptance critic counts must be non-negative integers")
+    elif counts[0] != counts[1] + counts[2]:
+        errors.append(
+            "acceptance critic candidatesProposed must equal confirmedBlockers + "
+            "downgradedToResidual"
+        )
+    if ledger is not None or unverified is not None or critic_findings:
+        errors.append("acceptance critic must not use coverage critic merge semantics")
+    return errors
+
+
+def _validate_critic_ledger_shape(ledger: Mapping[str, Any]) -> list[str]:
+    errors: list[str] = []
+    allowed = {
+        "schemaVersion",
+        "provider",
+        "modelExecutionValue",
+        "analyserRoster",
+        "dispatches",
+        "gaps",
+    }
+    if set(ledger) != allowed:
+        errors.append("criticVerification has unsupported fields")
+    if ledger.get("schemaVersion") != WORKING_SCHEMA_VERSION:
+        errors.append("criticVerification.schemaVersion must be 1.0")
+    for key in ("provider", "modelExecutionValue"):
+        if not _nonempty_string(ledger.get(key)):
+            errors.append(f"criticVerification.{key} must be a non-empty string")
+    roster = ledger.get("analyserRoster")
+    if not isinstance(roster, list):
+        errors.append("criticVerification.analyserRoster must be a unique string array")
+    elif not all(_nonempty_string(worker) for worker in roster):
+        errors.append("criticVerification.analyserRoster must be a unique string array")
+    elif len(roster) != len(set(roster)):
+        errors.append("criticVerification.analyserRoster must be a unique string array")
+    dispatches = ledger.get("dispatches")
+    if not isinstance(dispatches, list):
+        errors.append("criticVerification.dispatches must be an array")
+    else:
+        errors.extend(_validate_critic_ledger_dispatches(dispatches))
+    gaps = ledger.get("gaps")
+    if not isinstance(gaps, list):
+        errors.append("criticVerification.gaps must be an array")
+    return errors
+
+
+def _validate_critic_ledger_dispatches(dispatches: list[Any]) -> list[str]:
+    errors: list[str] = []
+    seen: set[Any] = set()
+    for index, row in enumerate(dispatches):
+        if not isinstance(row, Mapping) or set(row) != {"worker", "status", "durationMs"}:
+            errors.append(f"criticVerification.dispatches[{index}] is invalid")
+            continue
+        worker = row.get("worker")
+        if not _nonempty_string(worker):
+            errors.append("criticVerification has invalid or duplicate dispatch worker")
+        elif worker in seen:
+            errors.append("criticVerification has invalid or duplicate dispatch worker")
+        else:
+            seen.add(worker)
+        status = row.get("status")
+        if not _nonempty_string(status) or status not in _DISPATCH_STATUSES:
+            errors.append("criticVerification has invalid dispatch status")
+        duration = row.get("durationMs")
+        if not isinstance(duration, int) or isinstance(duration, bool) or duration < 0:
+            errors.append("criticVerification has invalid dispatch durationMs")
+    return errors
+
+
+def _validate_critic_gap_links(
+    gaps: list[Any],
+    critic_findings: Mapping[Any, Mapping[str, Any]],
+    unverified: list[Any],
+    config: Mapping[str, Any],
+    ledger: Mapping[str, Any],
+) -> list[str]:
+    errors: list[str] = []
+    seen_gaps: set[str] = set()
+    merged_ids: set[str] = set()
+    unverified_ids: set[str] = set()
+    classifications: list[Any] = []
+    for finding_id, finding in critic_findings.items():
+        if finding.get("rounds") != []:
+            errors.append(
+                f"critic-origin finding rounds must be empty: {finding_id}"
+            )
+    for index, gap in enumerate(gaps):
+        gap_errors, gap_id, merged_id, classification = _validate_critic_gap_row(
+            gap, index
+        )
+        errors.extend(gap_errors)
+        if _nonempty_string(gap_id):
+            if gap_id in seen_gaps:
+                errors.append(f"duplicate critic gapId: {gap_id}")
+            seen_gaps.add(gap_id)
+        classifications.append(classification)
+        if isinstance(merged_id, str):
+            if merged_id in merged_ids:
+                errors.append(f"duplicate mergedFindingId: {merged_id}")
+            merged_ids.add(merged_id)
+            finding = critic_findings.get(merged_id)
+            if finding is None:
+                errors.append(f"critic mergedFindingId {merged_id} is not a critic-origin finding")
+            elif finding.get("classification") != classification:
+                errors.append(f"critic mergedFindingId {merged_id} classification mismatch")
+            elif not gap_errors and finding != _replay_critic_finding(
+                gap,
+                merged_id,
+                ledger,
+            ):
+                errors.append(
+                    f"critic mergedFindingId {merged_id} content does not match "
+                    "criticVerification ledger"
+                )
+        if classification == "unverified" and isinstance(gap_id, str):
+            unverified_ids.add(gap_id)
+    if set(critic_findings) != merged_ids:
+        errors.append(
+            "critic-origin findings do not match criticVerification "
+            "mergedFindingId links"
+        )
+    errors.extend(_validate_unverified_gap_rows(unverified, unverified_ids))
+    errors.extend(_validate_critic_counts(config, classifications))
+    return errors
+
+
+def _validate_critic_gap_row(
+    gap: Any,
+    index: int,
+) -> tuple[list[str], Any, Any, Any]:
+    if not isinstance(gap, Mapping):
+        return ([f"criticVerification.gaps[{index}] must be an object"], None, None, None)
+    errors: list[str] = []
+    required = {
+        "gapId",
+        "summary",
+        "category",
+        "ticketIds",
+        "originEvidence",
+        "classification",
+        "mergedFindingId",
+        "votes",
+    }
+    allowed = required | {"evidenceArtifacts"}
+    if set(gap) - allowed:
+        errors.append(f"criticVerification.gaps[{index}] has unsupported fields")
+    if required - set(gap):
+        errors.append(f"criticVerification.gaps[{index}] has missing required fields")
+    gap_id = gap.get("gapId")
+    classification = gap.get("classification")
+    merged_id = gap.get("mergedFindingId")
+    if not _nonempty_string(gap_id):
+        errors.append(f"criticVerification.gaps[{index}].gapId is invalid")
+    classification_valid = (
+        _nonempty_string(classification)
+        and classification in _CRITIC_CLASSIFICATIONS
+    )
+    if not classification_valid:
+        errors.append(f"criticVerification gap {gap_id} has invalid classification")
+    if classification_valid and classification in {"full-consensus", "partial-consensus"}:
+        if not _nonempty_string(merged_id):
+            errors.append(f"criticVerification gap {gap_id} requires mergedFindingId")
+    elif classification_valid and merged_id is not None:
+        errors.append(f"criticVerification gap {gap_id} must not be merged")
+    errors.extend(_validate_critic_gap_content(gap, gap_id))
+    errors.extend(_validate_critic_gap_votes(gap_id, gap.get("votes"), classification))
+    return errors, gap_id, merged_id, classification
+
+
+def _validate_critic_gap_content(
+    gap: Mapping[str, Any],
+    gap_id: Any,
+) -> list[str]:
+    errors: list[str] = []
+    for key in ("summary", "category", "originEvidence"):
+        if not _nonempty_string(gap.get(key)):
+            errors.append(f"criticVerification gap {gap_id} {key} is invalid")
+    ticket_ids = gap.get("ticketIds")
+    if not isinstance(ticket_ids, list) or not all(
+        _nonempty_string(ticket_id) for ticket_id in ticket_ids
+    ):
+        errors.append(f"criticVerification gap {gap_id} ticketIds is invalid")
+    artifacts = gap.get("evidenceArtifacts")
+    if "evidenceArtifacts" not in gap:
+        return errors
+    if isinstance(artifacts, list):
+        expected = {"path", "sha256", "command", "environment"}
+        for index, artifact in enumerate(artifacts):
+            if isinstance(artifact, Mapping) and set(artifact) != expected:
+                errors.append(
+                    f"criticVerification gap {gap_id}.evidenceArtifacts[{index}] "
+                    "has unsupported fields"
+                )
+    try:
+        _parse_evidence_artifacts(
+            artifacts,
+            f"criticVerification gap {gap_id}",
+        )
+    except ConvergenceContractError as exc:
+        errors.append(str(exc))
+    return errors
+
+
+def _replay_critic_finding(
+    gap: Mapping[str, Any],
+    finding_id: str,
+    ledger: Mapping[str, Any],
+) -> dict[str, Any]:
+    roster = ledger.get("analyserRoster")
+    workers = [
+        {"workerId": worker, "audience": "analysis"}
+        for worker in roster
+        if _nonempty_string(worker)
+    ] if isinstance(roster, list) else []
+    return _critic_finding(
+        gap,
+        str(ledger.get("provider")),
+        finding_id,
+        gap["classification"],
+        workers,
+    )
+
+
+def _validate_critic_gap_votes(
+    gap_id: Any,
+    votes: Any,
+    classification: Any,
+) -> list[str]:
+    if not isinstance(votes, Mapping):
+        return [f"criticVerification gap {gap_id} votes must be an object"]
+    errors: list[str] = []
+    parsed: dict[str, dict[str, Any]] = {}
+    for worker, vote in votes.items():
+        basis = vote.get("disagreeBasis") if isinstance(vote, Mapping) else None
+        if basis is not None and not _nonempty_string(basis):
+            errors.append(
+                f"criticVerification gap {gap_id} vote {worker}: "
+                "disagreeBasis must be a non-empty string"
+            )
+            continue
+        try:
+            parsed[worker] = _parse_vote(vote, adversarial=True)
+        except ConvergenceContractError as exc:
+            errors.append(f"criticVerification gap {gap_id} vote {worker}: {exc}")
+    if (
+        not errors
+        and _nonempty_string(classification)
+        and classification in _CRITIC_CLASSIFICATIONS
+    ):
+        expected = _critic_gap_classification(parsed)
+        if classification != expected:
+            errors.append(
+                f"criticVerification gap {gap_id} classification {classification} "
+                f"does not match replayed classification {expected}"
+            )
+    return errors
+
+
+def _validate_unverified_gap_rows(
+    rows: list[Any],
+    expected_ids: set[str],
+) -> list[str]:
+    errors: list[str] = []
+    actual_ids: list[str] = []
+    for index, row in enumerate(rows):
+        if not isinstance(row, Mapping) or set(row) != {"gapId", "summary", "reason"}:
+            errors.append(f"unverifiedGaps[{index}] is invalid")
+            continue
+        for key in ("gapId", "summary", "reason"):
+            if not _nonempty_string(row.get(key)):
+                errors.append(f"unverifiedGaps[{index}].{key} is invalid")
+        if isinstance(row.get("gapId"), str):
+            actual_ids.append(row["gapId"])
+    if len(actual_ids) != len(set(actual_ids)) or set(actual_ids) != expected_ids:
+        errors.append("unverifiedGaps do not match unverified criticVerification gaps")
+    return errors
+
+
+def _validate_critic_counts(
+    config: Mapping[str, Any],
+    classifications: list[Any],
+) -> list[str]:
+    allowed = {
+        "provider",
+        "modelExecutionValue",
+        "gapsProposed",
+        "gapsMerged",
+        "gapsRejected",
+        "gapsUnverified",
+    }
+    errors: list[str] = []
+    if set(config) != allowed:
+        errors.append("config.critic has unsupported fields")
+    expected = {
+        "gapsProposed": len(classifications),
+        "gapsMerged": sum(
+            _nonempty_string(value)
+            and value in {"full-consensus", "partial-consensus"}
+            for value in classifications
+        ),
+        "gapsRejected": sum(
+            _nonempty_string(value)
+            and value in {"contested", "worker-unique"}
+            for value in classifications
+        ),
+        "gapsUnverified": sum(value == "unverified" for value in classifications),
+    }
+    for key, value in expected.items():
+        declared = config.get(key)
+        if not isinstance(declared, int) or isinstance(declared, bool) or declared < 0:
+            errors.append(f"config.critic.{key} must be a non-negative integer")
+        elif declared != value:
+            errors.append(f"config.critic.{key} {declared} does not match ledger {value}")
+    proposed = config.get("gapsProposed")
+    merged = config.get("gapsMerged")
+    rejected = config.get("gapsRejected")
+    unverified = config.get("gapsUnverified")
+    counts = (proposed, merged, rejected, unverified)
+    if all(
+        isinstance(value, int) and not isinstance(value, bool)
+        for value in counts
+    ):
+        if proposed != merged + rejected + unverified:
+            errors.append(
+                "config.critic.gapsProposed must equal gapsMerged + gapsRejected + gapsUnverified"
+            )
+    return errors
+
+
+def _validate_critic_roster(
+    state: Mapping[str, Any],
+    ledger: Mapping[str, Any],
+) -> list[str]:
+    declared = ledger.get("analyserRoster")
+    roster = {
+        worker
+        for worker in declared
+        if _nonempty_string(worker)
+    } if isinstance(declared, list) else set()
+    workers = state.get("workers")
+    provider = ledger.get("provider")
+    dispatches = ledger.get("dispatches")
+    errors: list[str] = []
+    if isinstance(workers, list):
+        actual = [
+            worker.get("workerId")
+            for worker in workers
+            if isinstance(worker, Mapping) and worker.get("audience") == "analysis"
+        ]
+        if declared != actual:
+            errors.append("criticVerification.analyserRoster does not match workers")
+    for row in dispatches if isinstance(dispatches, list) else []:
+        worker = row.get("worker") if isinstance(row, Mapping) else None
+        if (
+            not _nonempty_string(worker)
+            or worker not in roster
+            or _is_critic_worker(worker, provider)
+        ):
+            errors.append(f"critic voter must be a non-critic analyser: {worker}")
+    expected_dispatches = {
+        worker for worker in roster if not _is_critic_worker(worker, provider)
+    }
+    actual_dispatches = {
+        row.get("worker")
+        for row in dispatches
+        if isinstance(row, Mapping) and _nonempty_string(row.get("worker"))
+    } if isinstance(dispatches, list) else set()
+    if actual_dispatches != expected_dispatches:
+        errors.append(
+            "criticVerification.dispatches must account for every non-critic "
+            "analyser exactly once"
+        )
+    completed = {
+        row.get("worker")
+        for row in dispatches
+        if (
+            isinstance(row, Mapping)
+            and _nonempty_string(row.get("worker"))
+            and row.get("status") == "completed"
+        )
+    } if isinstance(dispatches, list) else set()
+    gaps = ledger.get("gaps")
+    for gap in gaps if isinstance(gaps, list) else []:
+        votes = gap.get("votes") if isinstance(gap, Mapping) else None
+        for voter in votes if isinstance(votes, Mapping) else {}:
+            if voter not in roster or _is_critic_worker(voter, provider):
+                errors.append(f"critic voter must be a non-critic analyser: {voter}")
+            elif voter not in completed:
+                errors.append(f"critic voter has no completed dispatch: {voter}")
+    return errors
+
+
+def _is_critic_worker(worker: Any, provider: Any) -> bool:
+    return isinstance(provider, str) and worker in {provider, f"{provider}-worker"}
+
+
 def _final_collaborative_classification(finding: Mapping[str, Any]) -> str:
     usable: list[Mapping[str, Any]] = []
     for round_row in finding.get("rounds", []):
@@ -617,6 +1433,13 @@ def _validate_finding_ledger(
     errors: list[str] = []
     finding_id = finding.get("findingId")
     origin = finding.get("originWorker")
+    if "evidenceArtifacts" in finding:
+        try:
+            _parse_evidence_artifacts(
+                finding.get("evidenceArtifacts"), f"finding {finding_id}"
+            )
+        except ConvergenceContractError as exc:
+            errors.append(str(exc))
     rounds = finding.get("rounds")
     if not isinstance(rounds, list):
         return [f"finding {finding_id} rounds must be an array"]
@@ -826,7 +1649,9 @@ def _votes_for_finding(
         status = statuses[worker]["status"]
         if status == "completed":
             votes[worker] = _parse_vote(
-                votes_by_finding[finding_id][worker], adversarial=adversarial
+                votes_by_finding[finding_id][worker],
+                adversarial=adversarial,
+                allow_unverifiable=True,
             )
         else:
             votes[worker] = {
@@ -874,11 +1699,19 @@ def _parsed_votes(
     }
 
 
-def _parse_vote(value: Any, *, adversarial: bool) -> dict[str, Any]:
+def _parse_vote(
+    value: Any,
+    *,
+    adversarial: bool,
+    allow_unverifiable: bool = False,
+) -> dict[str, Any]:
     vote = _object(value, "vote")
     verdict = _required_string(vote, "verdict", "vote")
-    if verdict not in _VERDICTS:
+    allowed = _INPUT_VERDICTS if allow_unverifiable else _VERDICTS
+    if verdict not in allowed:
         raise ConvergenceContractError(f"unsupported vote verdict: {verdict}")
+    if verdict == "unverifiable":
+        verdict = "verification-error"
     explanation = _required_string(vote, "explanation", "vote")
     basis = vote.get("disagreeBasis")
     if verdict == "disagree" and adversarial:
@@ -1049,7 +1882,7 @@ def _parse_group(
         if worker_id in discovered_by
         or any(item["worker"] == worker_id for item in source_items)
     ]
-    return {
+    finding = {
         "findingId": _required_string(group, "findingId", label),
         "summary": _required_string(group, "summary", label),
         "category": _required_string(group, "category", label),
@@ -1062,7 +1895,53 @@ def _parse_group(
         "rounds": [],
         "consensusWorkers": source_workers,
         "dissentingWorkers": [],
-    }, source_workers
+    }
+    if "evidenceArtifacts" in group:
+        finding["evidenceArtifacts"] = _parse_evidence_artifacts(
+            group.get("evidenceArtifacts"), label
+        )
+    return finding, source_workers
+
+
+def _parse_evidence_artifacts(value: Any, label: str) -> list[dict[str, str]]:
+    if not isinstance(value, list) or not value:
+        raise ConvergenceContractError(
+            f"{label}.evidenceArtifacts must be a non-empty array"
+        )
+    artifacts: list[dict[str, str]] = []
+    for index, raw in enumerate(value):
+        item_label = f"{label}.evidenceArtifacts[{index}]"
+        artifact = _object(raw, item_label)
+        path = _required_string(artifact, "path", item_label)
+        if not _is_normalized_okstra_path(path):
+            raise ConvergenceContractError(
+                f"{item_label}.path must be a normalized project-relative .okstra path"
+            )
+        sha256 = _required_string(artifact, "sha256", item_label)
+        if len(sha256) != 64 or any(
+            char not in "0123456789abcdef" for char in sha256
+        ):
+            raise ConvergenceContractError(
+                f"{item_label}.sha256 must be a lowercase SHA-256 hex digest"
+            )
+        artifacts.append(
+            {
+                "path": path,
+                "sha256": sha256,
+                "command": _required_string(artifact, "command", item_label),
+                "environment": _required_string(
+                    artifact, "environment", item_label
+                ),
+            }
+        )
+    return artifacts
+
+
+def _is_normalized_okstra_path(path: str) -> bool:
+    if not path.startswith(".okstra/") or "\\" in path:
+        return False
+    segments = path.split("/")
+    return all(segment not in {"", ".", ".."} for segment in segments)
 
 
 def _parse_discovered_by(
@@ -1135,6 +2014,17 @@ def _string_array(value: Any, label: str) -> list[str]:
     return result
 
 
+def _string_array_allow_empty(value: Any, label: str) -> list[str]:
+    if not isinstance(value, list):
+        raise ConvergenceContractError(f"{label} must be a 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")