syncade 0.6.2__py3-none-any.whl

syncade/producer_escalation.py

@@ -0,0 +1,146 @@
+"""Producer escalation channel.
+
+The producer's commit/stall/subprocess-error outcomes need a separate way to
+say *"I did what I could; finding X is an operator decision, not a code defect I
+can fix."*
+
+This module adds that channel as data only: a small structured record
+(:class:`ProducerEscalation`) and a parser
+(:func:`parse_producer_escalation`) that extracts it from the producer's
+free-form narrative. The producer signals an escalation by emitting a
+sentinel-delimited JSON block:
+
+.. code-block:: text
+
+    <<<SYNCADE-ESCALATE>>>
+    {"finding_indices": [0, 2], "finding": "...", "decision": "...",
+     "options": ["A", "B"], "rationale": "..."}
+    <<<END-SYNCADE-ESCALATE>>>
+
+The evidence bar is enforced *structurally*: every field is required and non-empty, and
+``options`` must be a non-empty list of non-empty strings. A malformed or
+incomplete block is NOT an escalation — :func:`parse_producer_escalation`
+returns ``None`` and the producer run is treated as an ordinary stall.
+
+``finding_indices`` is the set of active-blocker indices into the
+round's ``SynthesizerOutput.consolidated_findings`` that this single
+operator decision resolves. The parser enforces it structurally — a non-empty list of
+unique non-negative ints — but does NOT check the indices against the
+round's findings (it has no access to them). The loop terminator does the
+in-range / is-active-blocker cross-check and honors the escalation only
+when ``finding_indices`` covers *every* active blocker in the round; see
+:func:`syncade.orchestrator.escalation_coverage.escalation_covers_active_blockers`.
+
+This module is pure data + parsing; it does not drive the loop. The loop handles
+the ``escalated`` producer outcome, ``decision_needed`` termination reason,
+``decision-needed.md``, and resume-with-decision.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+ESCALATE_OPEN = "<<<SYNCADE-ESCALATE>>>"
+"""Opening sentinel for the producer's escalation block. Hardcoded
+verbatim in ``templates/producer.md`` — the prompt and this parser MUST
+agree, pinned by ``test_prompts.py``'s sentinel-sync assertion."""
+
+ESCALATE_CLOSE = "<<<END-SYNCADE-ESCALATE>>>"
+"""Closing sentinel for the producer's escalation block."""
+
+
+@dataclass(frozen=True)
+class ProducerEscalation:
+    """One producer escalation: a finding the producer determined is an
+    operator decision rather than a code defect it can fix.
+
+    Attributes:
+        finding_indices: The indices into the round's
+            ``SynthesizerOutput.consolidated_findings`` that this single
+            operator decision resolves. Non-empty, unique, each
+            ``>= 0``. Structural-only here; the loop terminator checks them
+            against the round's actual findings and honors the escalation
+            only when they cover every active blocker.
+        finding: A one-line reference to the finding being escalated.
+        decision: The specific decision the operator must make.
+        options: The concrete options the operator chooses among
+            (non-empty; each a non-empty string).
+        rationale: The reproduction-backed justification for why this is
+            an operator decision, not a code fix (the evidence bar).
+    """
+
+    finding_indices: list[int]
+    finding: str
+    decision: str
+    options: list[str]
+    rationale: str
+
+
+def parse_producer_escalation(narrative_text: str) -> ProducerEscalation | None:
+    """Extract a :class:`ProducerEscalation` from the producer's narrative,
+    or ``None`` when there is no well-formed escalation block.
+
+    Finds the first ``ESCALATE_OPEN`` … ``ESCALATE_CLOSE`` pair and parses
+    the JSON between them. Returns ``None`` (→ treated as a plain stall)
+    on any of: no sentinels, an unterminated block, non-JSON content, a
+    non-object payload, a missing/empty required field, an ``options``
+    that isn't a non-empty list of non-empty strings, or a
+    ``finding_indices`` that isn't a non-empty list of unique
+    non-negative ints. The strictness IS the evidence bar — an escalation
+    that doesn't carry finding_indices + finding + decision + options +
+    rationale is not an escalation.
+    """
+    start = narrative_text.find(ESCALATE_OPEN)
+    if start == -1:
+        return None
+    body_start = start + len(ESCALATE_OPEN)
+    end = narrative_text.find(ESCALATE_CLOSE, body_start)
+    if end == -1:
+        return None
+    blob = narrative_text[body_start:end].strip()
+    try:
+        data = json.loads(blob)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    finding_indices = data.get("finding_indices")
+    finding = data.get("finding")
+    decision = data.get("decision")
+    options = data.get("options")
+    rationale = data.get("rationale")
+
+    if not (isinstance(finding, str) and finding.strip()):
+        return None
+    if not (isinstance(decision, str) and decision.strip()):
+        return None
+    if not (isinstance(rationale, str) and rationale.strip()):
+        return None
+    if not (
+        isinstance(options, list)
+        and options
+        and all(isinstance(o, str) and o.strip() for o in options)
+    ):
+        return None
+    # finding_indices: a non-empty list of unique non-negative ints.
+    # ``isinstance(True, int)`` is True, so bools are excluded explicitly
+    # (a JSON ``true`` must not masquerade as index 1). In-range and
+    # is-active-blocker checks are NOT done here — the parser has no access
+    # to the round's findings; the loop terminator does that cross-check.
+    if not (
+        isinstance(finding_indices, list)
+        and finding_indices
+        and all(isinstance(i, int) and not isinstance(i, bool) and i >= 0 for i in finding_indices)
+        and len(set(finding_indices)) == len(finding_indices)
+    ):
+        return None
+
+    return ProducerEscalation(
+        finding_indices=list(finding_indices),
+        finding=finding.strip(),
+        decision=decision.strip(),
+        options=[o.strip() for o in options],
+        rationale=rationale.strip(),
+    )

syncade/producer_git.py

@@ -0,0 +1,199 @@
+"""Git-side helpers for the producer phase.
+
+Split out of ``producer.py`` when it crossed the blocking 500-LOC cap (PR-v2-24). These
+three are one cohesive concern -- reading the worktree's HEAD and staging the producer's
+inputs -- and are entirely separable from the run loop that drives the subprocess.
+
+``_read_worktree_head`` is the load-bearing one: HEAD before vs after the subprocess is
+how the orchestrator distinguishes "committed" from "stalled", which is the invariant
+that producer work is accepted ONLY through commits.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import filecmp
+import hashlib
+import shutil
+from pathlib import Path
+
+from syncade.adapters.producer import ProducerOutput
+from syncade.git_object_id import is_full_git_object_id
+from syncade.process import (
+    SubprocessError,
+    SubprocessNotFoundError,
+    SubprocessTimeoutError,
+    run_subprocess,
+)
+from syncade.producer_result import ProducerResult
+
+
+def _read_worktree_head(worktree_path: Path) -> str:
+    """Return ``git rev-parse HEAD`` in ``worktree_path``.
+
+    Internal helper used at both ends of the producer run to derive
+    the (starting_sha, ending_sha) tuple stall detection compares.
+    Failures bubble as :class:`SubprocessError` — the orchestrator
+    treats them as subprocess-error outcomes (exit 40) since a
+    worktree that can't be queried for HEAD isn't usable for the
+    next round either.
+
+    Uses :func:`syncade.process.run_subprocess` (not
+    :func:`subprocess.run` directly) so the shared subprocess
+    machinery (timeout handling, error classification, process-
+    group cleanup) is exercised consistently with the rest of
+    syncade.
+    """
+    try:
+        result = run_subprocess(
+            ["git", "rev-parse", "HEAD"],
+            cwd=worktree_path,
+            timeout=10.0,
+        )
+    except SubprocessNotFoundError as exc:
+        # ``git`` itself missing is an environment failure — bubble.
+        raise SubprocessError(
+            f"producer: git binary missing while reading worktree HEAD at {worktree_path}: {exc}"
+        ) from exc
+    except SubprocessTimeoutError as exc:
+        raise SubprocessError(
+            f"producer: git rev-parse HEAD timed out at {worktree_path} (timeout={exc.timeout}s)"
+        ) from exc
+    if result.returncode != 0:
+        raise SubprocessError(
+            f"producer: git rev-parse HEAD failed at {worktree_path}: "
+            f"rc={result.returncode}, stderr: {result.stderr.strip()[:200]!r}"
+        )
+    sha = result.stdout.strip()
+    if not is_full_git_object_id(sha):
+        raise SubprocessError(
+            f"producer: git rev-parse HEAD at {worktree_path} returned "
+            f"unexpected value {sha!r} (expected full SHA-1/SHA-256 object ID)"
+        )
+    return sha
+
+
+def _best_effort_head_after_failure(worktree_path: Path, fallback_sha: str) -> str:
+    try:
+        return _read_worktree_head(worktree_path)
+    except SubprocessError:
+        return fallback_sha
+
+
+def _authoritative_head(worktree_path: Path) -> str | None:
+    """The worktree's real HEAD, or ``None`` when it cannot be read.
+
+    Unlike the ``ending_sha`` an error-path :class:`ProducerResult` carries — which
+    :func:`_best_effort_head_after_failure` may have COLLAPSED to ``starting_sha`` when its own
+    read failed — this reports the truth: a moved HEAD as itself, an unreadable HEAD as ``None``
+    (never silently as ``starting_sha``). That distinction is load-bearing for the retry gate
+    (PR-v2-22 Q3): resetting on a HEAD we merely failed to observe would destroy a real commit.
+    """
+    try:
+        return _read_worktree_head(worktree_path)
+    except SubprocessError:
+        return None
+
+
+def _accept_committed_after_error(result: ProducerResult, *, ending_sha: str) -> ProducerResult:
+    """Re-classify a ``subprocess_error`` whose producer ACTUALLY committed (HEAD moved to
+    ``ending_sha``) into a ``committed`` outcome, so the orchestrator fast-forwards the branch
+    instead of dropping the work at exit 40 (PR-v2-22 C1 — *never discard a made commit*).
+
+    ``committed`` requires ``output is not None`` and ``error is None`` (:class:`ProducerResult`
+    invariant), so the trailing error is folded into a synthesized narrative rather than kept on
+    ``.error``. The branch-advance path independently re-gates descendant-ness (``git merge-base
+    --is-ancestor``), so a non-descendant move is still caught downstream.
+    """
+    err = result.error
+    detail = f"{type(err).__name__}: {err}" if err is not None else "an unspecified error"
+    narrative = (
+        f"[syncade] The producer committed (HEAD -> {ending_sha[:12]}) and its session then ended "
+        f"with {detail}. The commit is accepted; the trailing error did not discard it."
+    )
+    return dataclasses.replace(
+        result,
+        outcome="committed",
+        ending_sha=ending_sha,
+        output=ProducerOutput(narrative_text=narrative),
+        error=None,
+    )
+
+
+def _reset_worktree(worktree_path: Path, starting_sha: str) -> None:
+    """Discard whatever a crashed producer attempt left in the worktree, so a transient RETRY
+    starts from EXACTLY the state the first attempt saw (PR-v2-22 C2). ``git reset --hard
+    <starting_sha>`` drops tracked/staged edits + any partial commit; ``git clean -ffd`` drops
+    untracked files + dirs, including nested git repositories (the second ``-f`` is required;
+    a single ``-f`` silently leaves nested repos in place with exit code 0).
+
+    NOT ``git clean -ffdx``: a producer only edits TRACKED source, and ``-x`` would ALSO nuke the
+    gitignored worktree-env scaffolding (the ``sitecustomize`` shim + ``PYTHONPATH=<wt>/src``
+    layout) the retried subprocess needs to import ``syncade`` — a self-inflicted failure. Only
+    reached with ``HEAD == starting_sha`` (the caller's HEAD-gate never resets over a real
+    commit, C1).
+
+    Raises :class:`SubprocessError` (or its subclasses) on any failure — a non-zero exit code,
+    launch error, or timeout — so the caller aborts the retry rather than proceeding on a dirty
+    worktree. A silently-ignored reset failure would allow attempt 1's partial edits to survive
+    into attempt 2, violating C2.
+    """
+    for argv in (["git", "reset", "--hard", starting_sha], ["git", "clean", "-ffd"]):
+        result = run_subprocess(argv, cwd=worktree_path, timeout=10.0)
+        if result.returncode != 0:
+            raise SubprocessError(
+                f"producer: {argv[1]} failed in {worktree_path}: "
+                f"rc={result.returncode}, stderr={result.stderr.strip()[:200]!r}"
+            )
+
+
+def _stage_producer_input(src: Path, *, worktree_path: Path, repo_root: Path) -> str:
+    """Stage one producer input inside the worktree; return a
+    worktree-relative reference to it.
+
+    Confinement (H4): the producer runs ``yolo`` with cwd = its own
+    worktree. Handing it an ABSOLUTE main-repo or run-artifact path
+    lures it OUT of that isolated worktree to read or edit the live
+    operator repo — the same escape the reviewer path was closed
+    against structurally (see ``orchestrator/round.py``). So every input
+    is copied INTO the worktree and referenced by a path relative to the
+    worktree root, which the producer resolves against its own cwd.
+
+    Mirrors the reviewer PR-doc staging in ``round.py``: an input that is
+    a tracked in-repo file is already present at the same relative path
+    (the copy is a no-op); a run artifact (``findings.md``,
+    ``test-run.stdout``) is copied in; an out-of-repo PR doc is staged
+    under a reserved, collision-free ``.syncade-inputs/<digest>-<name>``
+    path so a same-named tracked file cannot shadow it (H2). Run
+    artifacts carry their repo-relative ``.syncade/runs/...`` path, so
+    they land under the worktree's gitignored ``.syncade/runs/`` and
+    cannot be swept into a producer commit. ``Path.relative_to`` yields a
+    forward-only subpath (never ``..``), so the staged ref can never
+    escape the worktree.
+    """
+    try:
+        ref = str(src.relative_to(repo_root))
+    except ValueError:
+        # Out-of-repo input (e.g. an external PR doc): a bare basename
+        # would be SHADOWED by a tracked worktree file of the same name —
+        # the no-op-if-exists copy below would be skipped and the producer
+        # would read the WRONG (tracked) file. Stage it under a reserved,
+        # collision-free ref and copy unconditionally, mirroring the
+        # reviewer PR-doc staging in round.py (H2).
+        digest = hashlib.sha256(str(src).encode("utf-8")).hexdigest()[:16]
+        ref = f".syncade-inputs/{digest}-{src.name}"
+        dest = worktree_path / ref
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dest)
+        return ref
+    dest = worktree_path / ref
+    # Refresh from the pristine source when the staged copy is MISSING or has been MUTATED (PR-v2-22
+    # F8): a run-artifact input corrupted by a crashed prior attempt SURVIVES the gitignored reset
+    # (`.syncade/runs/` is untouched by `git clean -ffd`), so a retry must re-copy it or read
+    # corrupted input (a C2 violation). The content compare keeps the happy path byte-identical (no
+    # copy when it already matches — including the same-root case where dest IS src, which also
+    # avoids SameFileError).
+    if not dest.exists() or not filecmp.cmp(src, dest, shallow=False):
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dest)
+    return ref

syncade/producer_result.py

@@ -0,0 +1,205 @@
+"""Producer subprocess result model.
+
+:data:`ProducerOutcome` (the four-way outcome literal) and :class:`ProducerResult`
+(the frozen dataclass with the exactly-one-of contract enforced in
+``__post_init__``). ``producer.py`` re-imports both so
+``syncade.producer.ProducerResult`` / ``syncade.producer.ProducerOutcome``
+import paths are unchanged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from syncade.adapters.producer import ProducerOutput
+from syncade.process import SubprocessResult
+from syncade.producer_escalation import ProducerEscalation
+from syncade.usage import Usage
+
+ProducerOutcome = Literal["committed", "stalled", "subprocess_error", "escalated"]
+"""Three-way outcome of one producer subprocess run.
+
+- ``"committed"`` — the subprocess completed cleanly AND the
+  worktree's HEAD moved forward (``ending_sha != starting_sha``).
+  The orchestrator advances the operator's branch to ``ending_sha``
+  and the next round snapshots the new HEAD.
+- ``"stalled"`` — the subprocess completed cleanly (no
+  :class:`ReviewerInvocationError`, no timeout) BUT the worktree's
+  HEAD did NOT move. The producer either made no changes or made
+  changes without committing. The orchestrator terminates the loop
+  with exit 30 + ``termination_reason="producer_stalled"`` — the
+  next round would dispatch reviewers against an identical diff,
+  burning compute for no signal delta.
+- ``"subprocess_error"`` — the producer subprocess itself failed
+  (:class:`ReviewerInvocationError` from the adapter,
+  :class:`SubprocessTimeoutError`,
+  :class:`SubprocessNotFoundError`, or any other
+  :class:`SubprocessError` subclass). The orchestrator terminates
+  with exit 40 + ``termination_reason="producer_subprocess_error"``.
+  ``raw_subprocess_result`` preserves any partial output captured
+  before the failure (same pattern as reviewer / synthesizer
+  subprocess errors). ``ending_sha`` may differ from ``starting_sha``
+  when the subprocess failed after moving HEAD; that is an
+  indeterminate producer commit, not a successful ``"committed"``
+  outcome.
+- ``"escalated"`` — the subprocess completed cleanly, HEAD did
+  NOT move (a stall mechanically), but the producer emitted a
+  well-formed escalation block flagging a finding as an operator
+  decision rather than a code defect it can fix. A stall-variant.
+  whether the orchestrator HONORS this outcome is decided at the
+  terminator, not here — it honors (exit 10 +
+  ``termination_reason="decision_needed"`` + ``decision-needed.md``)
+  ONLY when the escalation's ``finding_indices`` cover every active
+  blocker in the round (mechanical set-containment over
+  ``consolidated_findings``; see
+  :func:`syncade.orchestrator.escalation_coverage.escalation_covers_active_blockers`).
+  An escalation that leaves an active blocker uncovered — or references a
+  non-blocker / out-of-range index — is treated as an ordinary stall
+  (exit 30, ``producer_stalled``, no ``decision-needed.md``). Either way
+  escalation does NOT override the mechanical verdict (the round is still
+  NO-SHIP from ``consolidated_findings``); it is an advisory channel
+  telling the operator *what decision* unblocks the loop. See
+  :mod:`syncade.producer_escalation`.
+"""
+
+
+@dataclass(frozen=True)
+class ProducerResult:
+    """Outcome of one producer subprocess run.
+
+    Mirrors :class:`syncade.synthesizer.SynthesizerResult` and
+    :class:`syncade.test_runner.TestRunResult` shape so persistence
+    can treat all subprocess-result types with the same vocabulary
+    (output / error / raw_subprocess_result / duration_seconds).
+
+    Attributes:
+        outcome: ``"committed"`` | ``"stalled"`` | ``"subprocess_error"``
+            | ``"escalated"``. See :data:`ProducerOutcome` for the
+            contract (incl. the coverage condition that decides
+            whether an ``"escalated"`` outcome is honored at the terminator).
+        starting_sha: The worktree HEAD before the subprocess ran.
+            Always equal to the round-start snapshot's
+            ``commit_sha``. Persisted into ``manifest.json``'s
+            ``producer`` section.
+        ending_sha: The worktree HEAD after the subprocess returned.
+            Equal to ``starting_sha`` on ``"stalled"``; differs on
+            ``"committed"``. On ``"subprocess_error"`` it is the best
+            observed HEAD after the failure and may differ from
+            ``starting_sha`` when the producer moved HEAD before failing.
+            Persisted into ``producer.commit.txt`` for shell-script
+            consumers; also surfaces as the producer's commit SHA
+            in ``loop-summary.md``'s commit series.
+        duration_seconds: Wall-clock duration. ``0.0`` for failures
+            that fire before the subprocess starts (e.g.
+            :class:`ProducerSetupError` from a bad worktree HEAD
+            read); subprocess-error path records the time spent
+            attempting the subprocess.
+        output: The :class:`ProducerOutput` on the ``"committed"``
+            and ``"stalled"`` paths; ``None`` on ``"subprocess_error"``.
+        error: The exception that fired on ``"subprocess_error"``;
+            ``None`` otherwise.
+        raw_subprocess_result: The :class:`SubprocessResult` from
+            the producer subprocess. Preserved on ``"committed"``,
+            ``"stalled"``, and timeout paths (synthesized from
+            :class:`SubprocessTimeoutError`'s partial output, same
+            convention as :class:`ReviewerRunResult` and
+            :class:`SynthesizerResult`). ``None`` only on
+            :class:`SubprocessNotFoundError` (the process never
+            started, so there's no partial output to preserve).
+
+    The ``__post_init__`` enforces an exactly-one-of-three contract
+    across the (outcome, output, error, ending_sha-vs-starting_sha)
+    state: a ``"committed"`` result MUST have ``output is not None``
+    AND ``error is None`` AND ``ending_sha != starting_sha``; a
+    ``"stalled"`` result MUST have ``output is not None`` AND
+    ``error is None`` AND ``ending_sha == starting_sha``; a
+    ``"subprocess_error"`` result MUST have ``output is None`` AND
+    ``error is not None``. A ``"subprocess_error"`` may have a moved
+    ``ending_sha`` so persistence can report an indeterminate producer
+    commit truthfully.
+    Any other combination is a caller bug — surface it as
+    ValueError at construction time rather than letting it produce
+    a misleading manifest.
+    """
+
+    outcome: ProducerOutcome
+    starting_sha: str
+    ending_sha: str
+    duration_seconds: float
+    output: ProducerOutput | None
+    error: Exception | None
+    raw_subprocess_result: SubprocessResult | None = field(default=None)
+    escalation: ProducerEscalation | None = field(default=None)
+    """the structured escalation, set IFF ``outcome == "escalated"``.
+    ``None`` on every other outcome (enforced in ``__post_init__``)."""
+    usage: Usage | None = field(default=None)
+    provider: str | None = None
+    model: str | None = None
+    retries: int = 0
+    """Number of EXTRA producer subprocess attempts consumed riding out transient provider
+    errors (PR-v2-22). ``0`` when the first attempt settled it. Mirrors
+    :attr:`ReviewerRunResult.retries` / :attr:`SynthesizerResult.retries` so the round manifest
+    can sum ONE ``retried`` count across all three model legs."""
+
+    def __post_init__(self) -> None:
+        sha_moved = self.ending_sha != self.starting_sha
+        # escalation is set exactly when (and only when) the outcome
+        # is "escalated". Cross-cutting guard before the per-outcome table.
+        if (self.escalation is not None) != (self.outcome == "escalated"):
+            raise ValueError(
+                "ProducerResult: escalation must be set IFF "
+                "outcome=='escalated' (got outcome="
+                f"{self.outcome!r}, escalation="
+                f"{'set' if self.escalation is not None else 'None'})"
+            )
+        if self.outcome == "escalated":
+            if self.output is None:
+                raise ValueError("ProducerResult(outcome='escalated') requires output is not None")
+            if self.error is not None:
+                raise ValueError("ProducerResult(outcome='escalated') requires error is None")
+            if sha_moved:
+                raise ValueError(
+                    "ProducerResult(outcome='escalated') requires ending_sha "
+                    "== starting_sha (escalation does not commit; HEAD must "
+                    "not have moved)"
+                )
+            return
+        if self.outcome == "committed":
+            if self.output is None:
+                raise ValueError("ProducerResult(outcome='committed') requires output is not None")
+            if self.error is not None:
+                raise ValueError("ProducerResult(outcome='committed') requires error is None")
+            if not sha_moved:
+                raise ValueError(
+                    "ProducerResult(outcome='committed') requires ending_sha "
+                    "!= starting_sha (HEAD must have moved to claim "
+                    "'committed')"
+                )
+            return
+        if self.outcome == "stalled":
+            if self.output is None:
+                raise ValueError("ProducerResult(outcome='stalled') requires output is not None")
+            if self.error is not None:
+                raise ValueError("ProducerResult(outcome='stalled') requires error is None")
+            if sha_moved:
+                raise ValueError(
+                    "ProducerResult(outcome='stalled') requires ending_sha "
+                    "== starting_sha (HEAD must not have moved to claim "
+                    "'stalled')"
+                )
+            return
+        if self.outcome == "subprocess_error":
+            if self.output is not None:
+                raise ValueError(
+                    "ProducerResult(outcome='subprocess_error') requires output is None"
+                )
+            if self.error is None:
+                raise ValueError(
+                    "ProducerResult(outcome='subprocess_error') requires error is not None"
+                )
+            return
+        # Defensive — Literal narrows ``outcome`` at type-check time,
+        # but a caller bypassing the type hint (e.g. a dict-fed
+        # dataclass construction) could land here.
+        raise ValueError(f"ProducerResult: unknown outcome {self.outcome!r}")