syncade 0.6.2__py3-none-any.whl

syncade/orchestrator/verdict.py

@@ -0,0 +1,279 @@
+"""Mechanical per-round verdict and phase-failure classification."""
+
+from __future__ import annotations
+
+from syncade.adapters.base import ReviewerInvocationError
+from syncade.adapters.registry import UnknownProviderError
+from syncade.dispatcher import DispatchResult
+from syncade.exit_codes import (
+    CLARIFICATION_NEEDED,
+    CONFIG_ERROR,
+    FINDINGS_PRESENT,
+    REVIEWER_FAILURE,
+    REVIEWER_OUTPUT_UNPARSEABLE,
+    SUCCESS,
+    WORKTREE_ERROR,
+)
+from syncade.findings import ReviewerOutputError
+from syncade.process import (
+    SubprocessError,
+    SubprocessNotFoundError,
+    SubprocessTimeoutError,
+)
+from syncade.retry import is_usage_limit_error
+from syncade.synthesis import SynthesizerOutput, SynthesizerOutputError, has_active_blocker
+from syncade.synthesizer import SynthesizerResult
+from syncade.test_runner import TestRunResult, is_blocking_check_subprocess_error
+
+from .results import RoundResult, TerminationReason
+
+
+def error_is_provider_usage_limit(error: BaseException | None) -> bool:
+    """One actor's error, one question — so every actor asks it the same way."""
+    return error is not None and is_usage_limit_error(error)
+
+
+def round_hit_provider_usage_limit(round_result: RoundResult) -> bool:
+    """Did this round fail because the PROVIDER refused on exhausted quota? (PR-h-field-02)
+
+    Distinct from ``budget_exceeded``, which is the operator's own configured ceiling. Both
+    exit 25 — stop cleanly, resume later — but conflating them would tell someone to raise a
+    budget they never hit.
+
+    Not retried and not permanent: the classifier keeps quota out of ``_TRANSIENT_MARKERS`` on
+    purpose, so no attempts are burned against a window that has not moved, and the run stays
+    resumable instead of dying at exit 40.
+
+    Covers the REVIEWERS and the JUDGE. The first version checked only reviewers and the blind
+    panel caught it unanimously — the same refusal reaching the judge still died at exit 40. The
+    PRODUCER is checked at its own branch in the loop, because it is decided after this one, and
+    it is the likeliest of the three to exhaust a limit: 6.6M tokens in a single field round.
+    """
+    if any(error_is_provider_usage_limit(r.error) for r in round_result.dispatch_result.results):
+        return True
+    synth = round_result.synth_result
+    return synth is not None and error_is_provider_usage_limit(synth.error)
+
+
+def _classify_phase_failure(round_result: RoundResult) -> TerminationReason:
+    """Map a phase-failure round_exit_code to a termination_reason.
+
+    Called from the loop terminator when ``round_exit_code`` is
+    one of {40, 50, 60, 70}. Inspects the round's per-phase
+    outcomes to distinguish which phase actually failed (e.g.
+    exit 40 could be reviewer / synth / test-subprocess; exit 70
+    could be reviewer-parse / synth-parse).
+    """
+    exit_code = round_result.round_exit_code
+    if exit_code == CONFIG_ERROR:
+        return "config_error"
+    if exit_code == WORKTREE_ERROR:
+        if round_result.fail_closed_headers is not None:
+            return "diff_malformed"
+        if round_result.oversize_diff_bytes is not None:
+            return "diff_too_large"
+        if round_result.oversize_prompt_chars is not None:
+            return "prompt_too_large"
+        return "worktree_error"
+    if exit_code == REVIEWER_OUTPUT_UNPARSEABLE:
+        return "parse_failure"
+    if exit_code == REVIEWER_FAILURE:
+        # Three flavors of 40: reviewer subprocess, synth subprocess,
+        # test subprocess. Distinguish by which phase has an error.
+        if not round_result.dispatch_result.all_succeeded:
+            return "reviewer_failure"
+        if round_result.synth_result is not None and round_result.synth_result.error is not None:
+            return "synth_failure"
+        if (
+            round_result.test_result is not None
+            and round_result.test_result.outcome == "subprocess_error"
+        ):
+            return "test_subprocess_error"
+        # A blocking mechanical check whose subprocess could not run is its
+        # own phase, distinct from a reviewer subprocess failure.
+        if any(
+            is_blocking_check_subprocess_error(c.severity, c.outcome)
+            for c in round_result.check_results
+        ):
+            return "check_subprocess_error"
+        # Fall-through default: treat as reviewer failure.
+        return "reviewer_failure"
+    # Shouldn't happen — caller filters to {40,50,60,70} before
+    # calling. Defensive fallback.
+    return "reviewer_failure"
+
+
+def _compute_exit_code(
+    dispatch_result: DispatchResult,
+    synth_result: SynthesizerResult | None,
+    test_result: TestRunResult | None = None,
+    blocking_check_results: list[TestRunResult] | None = None,
+) -> int:
+    """Compute the per-round mechanical exit code."""
+    failures = dispatch_result.failures
+
+    for r in failures:
+        if isinstance(r.error, UnknownProviderError):
+            return CONFIG_ERROR
+
+    for r in failures:
+        if isinstance(r.error, ReviewerOutputError):
+            return REVIEWER_OUTPUT_UNPARSEABLE
+
+    for r in failures:
+        if isinstance(
+            r.error,
+            (
+                ReviewerInvocationError,
+                SubprocessNotFoundError,
+                SubprocessTimeoutError,
+                SubprocessError,
+            ),
+        ):
+            return REVIEWER_FAILURE
+
+    if failures:
+        return REVIEWER_FAILURE
+
+    successes = dispatch_result.successes
+    if not successes:
+        return CONFIG_ERROR
+
+    if synth_result is None:
+        raise RuntimeError(
+            "_compute_exit_code: synth_result is None but every reviewer "
+            "succeeded. The orchestrator runs the synthesizer phase "
+            "whenever dispatch_result.all_succeeded is True; receiving "
+            "synth_result=None on this path means a caller bypassed "
+            "run_review's lifecycle."
+        )
+
+    if isinstance(synth_result.error, SynthesizerOutputError):
+        return REVIEWER_OUTPUT_UNPARSEABLE
+    if isinstance(
+        synth_result.error,
+        (
+            ReviewerInvocationError,
+            SubprocessNotFoundError,
+            SubprocessTimeoutError,
+            SubprocessError,
+        ),
+    ):
+        return REVIEWER_FAILURE
+    if synth_result.error is not None:
+        return REVIEWER_FAILURE
+
+    if synth_result.output is None:
+        raise RuntimeError(
+            "_compute_exit_code: synth_result has neither output nor "
+            "error — SynthesizerResult contract violated"
+        )
+    # Fold blocking mechanical-check results in alongside the test leg. Advisory
+    # results are never passed in by the caller and cannot gate the verdict.
+    mechanical = ([test_result] if test_result is not None else []) + list(
+        blocking_check_results or []
+    )
+    # A subprocess_error means the harness could not run, so it outranks every
+    # determinate verdict, including an active synth blocker.
+    if any(m.outcome == "subprocess_error" for m in mechanical):
+        return REVIEWER_FAILURE
+
+    if has_active_blocker(synth_result.output):
+        return FINDINGS_PRESENT
+
+    # A gate that ran and FAILED (a real defect → exit 30) is the same
+    # determinate NO-SHIP signal as a synth blocker; checked after it.
+    if any(m.outcome == "failed" for m in mechanical):
+        return FINDINGS_PRESENT
+
+    if _multi_reviewer_blockers_all_deactivated(dispatch_result):
+        return CLARIFICATION_NEEDED
+
+    return SUCCESS
+
+
+def _multi_reviewer_blockers_all_deactivated(dispatch_result: DispatchResult) -> bool:
+    """True when two or more DISTINCT reviewers each raised at least one
+    blocker-severity finding and none survived as an active blocker.
+
+    PR-h-01 increment D — the paraphrase guard, and the reason it is shaped
+    this way. The unanimous-blocker rule and the exact-duplicate split guard
+    both need to know that two reviewers named the SAME concern. Two reviewers
+    describing one bug in different words is the normal case — consolidating
+    that is the synthesizer's whole job — so the synthesizer can emit them as
+    two single-reviewer findings, dismiss each on its own merits, and neither
+    guard fires. ``has_active_blocker`` then sees nothing and the round is a
+    clean SHIP.
+
+    Semantic identity has no cheap correct implementation, and a similarity
+    heuristic manufactures FALSE locks — the worst possible failure for a tool
+    whose value is that its refusals mean something. So this does not attempt
+    to decide whether two findings are the same concern. It asks a question
+    with a mechanical answer: did multiple independent reviewers each say
+    "blocker", and did every one of those get deactivated?
+
+    That shape is not necessarily wrong — but it is not a verdict a machine
+    should render silently, so it escalates to exit 10 (decision needed) rather
+    than either shipping or blocking. It cannot false-lock: the worst case is a
+    human being asked to look. Callers reach this only when
+    ``has_active_blocker`` is already False, so "none survived" needs no
+    separate check.
+
+    Deliberately silent when: only one reviewer raised a blocker (the
+    synthesizer's dismissal authority over a single-source blocker is
+    intentional), no reviewer raised one, or any blocker is still active (that
+    round is already exit 30).
+    """
+    reviewers_with_blockers = {
+        r.reviewer_name
+        for r in dispatch_result.successes
+        if r.output is not None and any(f.severity == "blocker" for f in r.output.findings)
+    }
+    return len(reviewers_with_blockers) >= 2
+
+
+def deactivated_blocker_details(
+    dispatch_result: DispatchResult,
+    synth_output: SynthesizerOutput,
+) -> list[tuple[str, str, str]]:
+    """``(reviewer_name, verbatim_finding_text, disposition)`` for every source
+    blocker, for the exit-10 operator document.
+
+    The text is the REVIEWER's own, read from the parsed reviewer output rather
+    than from synthesizer-supplied provenance — the operator is being asked to
+    judge the synthesizer, so quoting the synthesizer back at them would beg the
+    question. (Increment C makes the two provably equal anyway; reading the
+    source directly means this stays true if that check is ever relaxed.)
+
+    ``disposition`` reports what the synthesizer did with it, resolved by
+    matching provenance on ``(reviewer_name, original_index)``. A source blocker
+    with no consolidated finding at all is reported as dropped, which is its own
+    kind of answer.
+    """
+    details: list[tuple[str, str, str]] = []
+    for r in dispatch_result.successes:
+        if r.output is None:
+            continue
+        for idx, source in enumerate(r.output.findings):
+            if source.severity != "blocker":
+                continue
+            details.append((r.reviewer_name, source.finding, _disposition(synth_output, r, idx)))
+    return details
+
+
+def _disposition(synth_output: SynthesizerOutput, reviewer, idx: int) -> str:
+    for consolidated in synth_output.consolidated_findings:
+        if not any(
+            p.reviewer_name == reviewer.reviewer_name and p.original_index == idx
+            for p in consolidated.provenance
+        ):
+            continue
+        if consolidated.dismissed:
+            rationale = (consolidated.dismissal_rationale or "").strip()
+            return f"dismissed — {rationale}" if rationale else "dismissed"
+        if consolidated.severity != "blocker":
+            rationale = (consolidated.severity_change_rationale or "").strip()
+            downgrade = f"downgraded to {consolidated.severity}"
+            return f"{downgrade} — {rationale}" if rationale else downgrade
+        return f"kept at {consolidated.severity}"
+    return "dropped — no consolidated finding carries provenance for it"

syncade/persistence/__init__.py

@@ -0,0 +1,189 @@
+"""On-disk persistence of dispatch + synthesizer results.
+
+Materializes a :class:`~syncade.dispatcher.DispatchResult` and
+:class:`~syncade.synthesizer.SynthesizerResult` into the
+``.syncade/runs/<run-id>/round-N/`` layout the PRD specifies. The
+orchestrator is the only production caller; tests construct
+synthesized inputs directly so they can exercise persistence without
+spawning real subprocesses.
+
+File layout per reviewer (one set per ``ReviewerRunResult``):
+
+- ``<round_dir>/<name>.stdout``       — raw subprocess stdout (always
+                                        written; empty when no
+                                        subprocess ran)
+- ``<round_dir>/<name>.stderr``       — raw subprocess stderr (same)
+- ``<round_dir>/<name>.parsed.json``  — :class:`~syncade.findings.ReviewerOutput` as JSON
+                                        (success path only)
+- ``<round_dir>/<name>.error.txt``    — exception class + message
+                                        + traceback (failure path
+                                        only)
+
+This adds synthesizer artifacts:
+
+- ``<round_dir>/synthesizer.stdout``       — raw codex stdout
+- ``<round_dir>/synthesizer.stderr``       — raw codex stderr
+- ``<round_dir>/synthesizer.parsed.json``  — :class:`~syncade.synthesis.SynthesizerOutput`
+                                             as JSON (success path)
+- ``<round_dir>/synthesizer.error.txt``    — exception + traceback
+                                             (failure path)
+- ``<round_dir>/findings.md``              — operator-facing
+                                             consolidated review
+                                             report (only when synth
+                                             succeeded)
+
+This adds test re-run artifacts (opt-in; written only when the
+operator configured ``[loop] test_command`` AND every prior phase
+succeeded AND the synthesizer was clean):
+
+- ``<round_dir>/test-run.stdout``          — captured test command
+                                             stdout
+- ``<round_dir>/test-run.stderr``          — captured test command
+                                             stderr
+- ``<round_dir>/test-run.exit-code.txt``   — one-line integer (or
+                                             ``-1\\n`` for the
+                                             subprocess-error path)
+                                             so manifest-readers
+                                             can grab it without
+                                             parsing JSON
+
+Plus one file per round:
+
+- ``<round_dir>/manifest.json``       — round-level summary written
+                                        by :func:`persist_round_manifest`
+- ``<round_dir>/summary.md``          — human-readable dashboard
+                                        written by
+                                        :func:`persist_run_summary`
+"""
+
+from __future__ import annotations
+
+from ._markdown import (
+    _md_command_lines as _md_command_lines,
+)
+from ._markdown import (
+    _md_inline_code as _md_inline_code,
+)
+from .checks import (
+    CheckArtifactPaths as CheckArtifactPaths,
+)
+from .checks import (
+    persist_check_result as persist_check_result,
+)
+from .decision_needed import (
+    DECISION_NEEDED_FILENAME as DECISION_NEEDED_FILENAME,
+)
+from .decision_needed import (
+    OPERATOR_DECISION_FILENAME as OPERATOR_DECISION_FILENAME,
+)
+from .decision_needed import (
+    persist_deactivated_blockers_decision_needed as persist_deactivated_blockers_decision_needed,
+)
+from .decision_needed import (
+    persist_decision_needed as persist_decision_needed,
+)
+from .decision_needed import (
+    read_operator_decision as read_operator_decision,
+)
+from .findings_md import (
+    persist_current_findings_md as persist_current_findings_md,
+)
+from .findings_md import (
+    persist_findings_md as persist_findings_md,
+)
+from .handoff import (
+    persist_handoff as persist_handoff,
+)
+from .last_reviewed import (
+    LAST_REVIEWED_FILENAME as LAST_REVIEWED_FILENAME,
+)
+from .last_reviewed import (
+    persist_last_reviewed as persist_last_reviewed,
+)
+from .last_reviewed import (
+    read_last_reviewed as read_last_reviewed,
+)
+from .loop_manifest import (
+    persist_loop_manifest as persist_loop_manifest,
+)
+from .loop_summary import (
+    persist_loop_summary as persist_loop_summary,
+)
+from .producer import (
+    ProducerArtifactPaths as ProducerArtifactPaths,
+)
+from .producer import (
+    persist_producer_result as persist_producer_result,
+)
+from .reviewer import (
+    persist_dispatch_record as persist_dispatch_record,
+)
+from .reviewer import (
+    persist_reviewer_result as persist_reviewer_result,
+)
+from .reviewer import (
+    record_child_pid as record_child_pid,
+)
+from .round_manifest import (
+    persist_round_manifest as persist_round_manifest,
+)
+from .run_init import (
+    RUN_INIT_FILENAME as RUN_INIT_FILENAME,
+)
+from .run_init import (
+    persist_run_init as persist_run_init,
+)
+from .run_summary import (
+    persist_run_summary as persist_run_summary,
+)
+from .synth import (
+    SynthesizerArtifactPaths as SynthesizerArtifactPaths,
+)
+from .synth import (
+    persist_synthesizer_result as persist_synthesizer_result,
+)
+from .test_run import (
+    TEST_RUN_NAME as TEST_RUN_NAME,
+)
+from .test_run import (
+    TestRunArtifactPaths as TestRunArtifactPaths,
+)
+from .test_run import (
+    persist_test_run_result as persist_test_run_result,
+)
+
+# Public re-export surface. The 2 underscore-prefixed helpers
+# (_md_inline_code, _md_command_lines) are intentionally NOT in
+# __all__ per Python convention, but they remain importable from
+# syncade.persistence for tests that reach into them directly.
+__all__ = [
+    "CheckArtifactPaths",
+    "DECISION_NEEDED_FILENAME",
+    "LAST_REVIEWED_FILENAME",
+    "OPERATOR_DECISION_FILENAME",
+    "persist_last_reviewed",
+    "read_last_reviewed",
+    "ProducerArtifactPaths",
+    "RUN_INIT_FILENAME",
+    "SynthesizerArtifactPaths",
+    "TEST_RUN_NAME",
+    "TestRunArtifactPaths",
+    "persist_check_result",
+    "persist_current_findings_md",
+    "persist_deactivated_blockers_decision_needed",
+    "persist_decision_needed",
+    "persist_findings_md",
+    "read_operator_decision",
+    "persist_handoff",
+    "persist_loop_manifest",
+    "persist_loop_summary",
+    "persist_producer_result",
+    "persist_dispatch_record",
+    "record_child_pid",
+    "persist_reviewer_result",
+    "persist_round_manifest",
+    "persist_run_init",
+    "persist_run_summary",
+    "persist_synthesizer_result",
+    "persist_test_run_result",
+]

syncade/persistence/_atomic.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=path.parent,
+        text=True,
+    )
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_path, path)
+    except BaseException:
+        try:
+            tmp_path.unlink()
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def atomic_write_json(path: Path, data: object, *, sort_keys: bool = False) -> None:
+    atomic_write_text(path, json.dumps(data, indent=2, sort_keys=sort_keys) + "\n")

syncade/persistence/_clusters.py

@@ -0,0 +1,70 @@
+"""Root-cause cluster rendering for findings.md.
+
+Renders the descriptive-only ``## Root-cause clusters`` section that
+``persist_findings_md`` places ABOVE the individual findings, so the producer
+reads "these N findings are one root cause — here is what each reviewer said
+about it" before reading them individually.
+
+Lives in its own module (called by ``findings_md.py``) per the LOC discipline —
+``findings_md.py`` was already at the ~500-LOC cap. The renderer is purely
+descriptive: it surfaces the synth's grouping + the verbatim reviewer quotes and
+authors nothing (the synth emits no cause or fix, and neither does this).
+
+Returns ``[]`` when there are no clusters.
+"""
+
+from __future__ import annotations
+
+from syncade.synthesis import SynthesizerOutput
+
+
+def render_cluster_section(output: SynthesizerOutput) -> list[str]:
+    """Return the ``## Root-cause clusters`` section as a list of lines, or
+    ``[]`` when ``output.root_cause_clusters`` is empty.
+
+    For each cluster: the ``anchor_file`` (+ the optional ``label``, itself a
+    verbatim quote excerpt), the member finding indices, and one bullet per
+    member with the finding's first description line and that member's verbatim
+    reviewer quote. Descriptive-only — no authored cause or fix.
+
+    Member indices are schema-validated in range by the time a
+    :class:`SynthesizerOutput` exists, but the render guards defensively so a
+    stray index can never raise mid-write.
+    """
+    clusters = output.root_cause_clusters
+    if not clusters:
+        return []
+
+    findings = output.consolidated_findings
+    lines: list[str] = [
+        "## Root-cause clusters",
+        "",
+        "_Advisory groupings of related findings (descriptive-only — they do "
+        "not change the verdict). Each member is quoted verbatim from a "
+        "reviewer's original finding; the cause is the reviewers' words, not "
+        "the synthesizer's._",
+        "",
+    ]
+    for n, cluster in enumerate(clusters, start=1):
+        heading = f"### Cluster {n}: `{cluster.anchor_file}`"
+        if cluster.label:
+            heading += f" — {cluster.label}"
+        lines.append(heading)
+        lines.append("")
+        member_list = ", ".join(f"#{idx}" for idx in cluster.member_finding_indices)
+        lines.append(f"**Member findings:** {member_list}  ")
+        lines.append("")
+        quote_by_index = {e.finding_index: e.quote for e in cluster.evidence}
+        for idx in cluster.member_finding_indices:
+            if 0 <= idx < len(findings):
+                member = findings[idx]
+                desc_first = member.description.strip().splitlines()[0]
+                severity = member.severity
+            else:  # pragma: no cover - defensive; schema validates in range
+                desc_first = "(member index out of range)"
+                severity = "?"
+            lines.append(f"- **#{idx}** [{severity}] {desc_first}")
+            quote = quote_by_index.get(idx, "").strip().replace("\n", " ")
+            lines.append(f"  - reviewer quote: {quote!r}")
+        lines.append("")
+    return lines