phase-loop-runtime 0.7.3__tar.gz → 0.7.5__tar.gz

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.3
+Version: 0.7.5
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.3"
+version = "0.7.5"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.5}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.3"
+__version__ = "0.7.5"

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.5}/src/phase_loop_runtime/cli.py

@@ -728,6 +728,11 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="FILE",
         help="Path to the cross-repo release-train roadmap (same file as run-train).",
     )
+    train_status_sub.add_argument(
+        "--event-log",
+        metavar="PATH",
+        help="Read a coordinator-owned convergence event log instead of a legacy train ledger.",
+    )
     train_status_sub.add_argument(
         "--ledger-dir",
         default=None,
@@ -3059,6 +3064,21 @@ def _run_train_status_command(*, parser: argparse.ArgumentParser, args: argparse
     """
     import json as _json
 
+    event_log = getattr(args, "event_log", None)
+    if event_log:
+        if getattr(args, "train_file", None) or getattr(args, "ledger_dir", None):
+            parser.error("train-status --event-log is mutually exclusive with --train and --ledger-dir")
+            return 2
+        from .convergence import build_train_status, read_convergence_events, recover_train_state, render_train_status
+        path = Path(event_log)
+        try:
+            snapshot = build_train_status(recover_train_state(read_convergence_events(path)), path)
+        except Exception as exc:
+            print(f"train-status: failed to read event log at {path}: {exc}", file=sys.stderr)
+            return 1
+        print(render_train_status(snapshot, as_json=bool(getattr(args, "json", False))))
+        return 0
+
     from .train_ledger import default_ledger_path, read_ledger
 
     train_file = getattr(args, "train_file", None)

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/__init__.py

@@ -0,0 +1,110 @@
+"""Frozen convergence contracts only; runtime and broker behavior are intentionally absent."""
+
+from phase_loop_runtime.convergence.contracts import (
+    AdmissionRequest,
+    AuthoritySource,
+    BrokerRequest,
+    BrokerTerminalEvidence,
+    BrokerVerb,
+    InvalidationTrigger,
+    PublishCommittedBranchResult,
+    ReconciliationBinding,
+    ResourceIsolationDecision,
+    evaluate_resource_isolation,
+)
+from phase_loop_runtime.convergence.provider_contracts import (
+    PROVIDER_COMPLETION_CLASSIFICATIONS,
+    ProviderAutomationDisposition,
+    ProviderCompletionClassification,
+    ProviderCompletionContract,
+    TerminalOutcomeState,
+    validate_terminal_transition,
+)
+from phase_loop_runtime.train_ledger import (
+    CoordinatorEvent,
+    CoordinatorEventKind,
+    ConvergenceResultEnvelope,
+    ConvergenceResultStatus,
+    normalize_legacy_ledger_record,
+)
+from phase_loop_runtime.convergence.event_log import (
+    RecoveredTrainState,
+    default_convergence_event_log_path,
+    read_convergence_events,
+    record_intent,
+    record_outcome,
+    recover_train_state,
+)
+from phase_loop_runtime.convergence.reconcile import ActionReconciliation, ExactStateProbes, ReconciliationVerdict, SupportedConvergenceVersions, invalidate_action_evidence, reconcile_before_action, reconcile_train_state
+from phase_loop_runtime.convergence.dispatch import DispatchDecision, RepositoryDispatchRequest, RepositoryLockKey, dispatch_ready_nodes
+from phase_loop_runtime.convergence.fencing import ApprovalBinding, AttemptLease, FencedAdmissionFactory, compute_approval_digest, validate_attempt_lease
+from phase_loop_runtime.convergence.refresh import DownstreamRefreshRequest, DownstreamRefreshResult, DownstreamRefreshStatus, refresh_downstream_after_merge
+from phase_loop_runtime.convergence.status import TrainStatusSnapshot, build_train_status, render_train_status
+from phase_loop_runtime.convergence.adapters import AdapterExecutionRequest, run_claude_adapter, run_codex_adapter, run_outside_agent_adapter
+from phase_loop_runtime.convergence.broker import (
+    AdmissionRecord, BrokerAdmissionPolicy, BrokerClient, BrokerEnvironmentBoundary,
+    BrokerEvidenceStore, BrokerExecutionResult, BrokerProviderAdapter, BrokerService,
+    EvidenceRecord, GitHubBrokerAdapter, LinearizableAdmissionStore,
+    publish_committed_branch_idempotency_key,
+)
+
+__all__ = [
+    "AdmissionRequest",
+    "AuthoritySource",
+    "BrokerRequest",
+    "BrokerTerminalEvidence",
+    "BrokerVerb",
+    "CoordinatorEvent",
+    "CoordinatorEventKind",
+    "ConvergenceResultEnvelope",
+    "ConvergenceResultStatus",
+    "InvalidationTrigger",
+    "PROVIDER_COMPLETION_CLASSIFICATIONS",
+    "ProviderAutomationDisposition",
+    "ProviderCompletionClassification",
+    "ProviderCompletionContract",
+    "PublishCommittedBranchResult",
+    "ReconciliationBinding",
+    "ResourceIsolationDecision",
+    "TerminalOutcomeState",
+    "evaluate_resource_isolation",
+    "normalize_legacy_ledger_record",
+    "validate_terminal_transition",
+    "AdapterExecutionRequest",
+    "ExactStateProbes",
+    "ActionReconciliation",
+    "ApprovalBinding",
+    "AttemptLease",
+    "DispatchDecision",
+    "DownstreamRefreshRequest",
+    "DownstreamRefreshResult",
+    "DownstreamRefreshStatus",
+    "FencedAdmissionFactory",
+    "RecoveredTrainState",
+    "ReconciliationVerdict",
+    "RepositoryDispatchRequest",
+    "RepositoryLockKey",
+    "SupportedConvergenceVersions",
+    "TrainStatusSnapshot",
+    "build_train_status",
+    "default_convergence_event_log_path",
+    "compute_approval_digest",
+    "dispatch_ready_nodes",
+    "invalidate_action_evidence",
+    "read_convergence_events",
+    "reconcile_train_state",
+    "reconcile_before_action",
+    "record_intent",
+    "record_outcome",
+    "recover_train_state",
+    "render_train_status",
+    "run_claude_adapter",
+    "run_codex_adapter",
+    "run_outside_agent_adapter",
+    "refresh_downstream_after_merge",
+    "validate_attempt_lease",
+    "AdmissionRecord", "BrokerAdmissionPolicy", "BrokerClient", "BrokerEnvironmentBoundary",
+    "BrokerEvidenceStore", "BrokerExecutionResult", "BrokerProviderAdapter", "BrokerService",
+    "EvidenceRecord", "GitHubBrokerAdapter", "LinearizableAdmissionStore",
+    "publish_committed_branch_idempotency_key",
+]

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/adapters/__init__.py

@@ -0,0 +1,6 @@
+from .base import AdapterExecutionRequest
+from .codex import run_codex_adapter
+from .claude import run_claude_adapter
+from .outside_agent import run_outside_agent_adapter
+
+__all__ = ["AdapterExecutionRequest", "run_codex_adapter", "run_claude_adapter", "run_outside_agent_adapter"]

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/adapters/base.py

@@ -0,0 +1,52 @@
+"""Bounded, credential-stripped adapter execution primitives."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from phase_loop_runtime.convergence.contracts import AdmissionRequest
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope, ConvergenceResultStatus
+
+_DENIED_ENV = ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "GEMINI_API_KEY")
+_ALLOWED_ACTIONS = frozenset({"execute", "repair", "review"})
+
+@dataclass(frozen=True)
+class AdapterExecutionRequest:
+    attempt_id: str
+    admission: AdmissionRequest
+    argv: tuple[str, ...]
+    cwd: Path
+    timeout_seconds: float
+    allowed_action: str
+    evidence_references: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.argv or self.timeout_seconds <= 0 or self.allowed_action not in _ALLOWED_ACTIONS:
+            raise ValueError("adapter request is outside bounded execution contract")
+        if self.admission.attempt_id != self.attempt_id:
+            raise ValueError("adapter request must preserve admission attempt id")
+
+
+def run_bounded(request: AdapterExecutionRequest, *, expected_prefix: str) -> ConvergenceResultEnvelope:
+    if not request.argv[0].startswith(expected_prefix):
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.BLOCKED, request.attempt_id, "adapter command outside provider bounds")
+    env = {key: value for key, value in os.environ.items() if key not in _DENIED_ENV}
+    try:
+        result = subprocess.run(request.argv, cwd=request.cwd, env=env, text=True, capture_output=True, timeout=request.timeout_seconds, start_new_session=True, check=False)
+    except subprocess.TimeoutExpired:
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.DEGRADED, request.attempt_id, "adapter timed out")
+    except OSError as exc:
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.FAILED, request.attempt_id, str(exc)[:256])
+    detail = (result.stdout or result.stderr or "")[:1024]
+    if result.returncode:
+        return ConvergenceResultEnvelope(ConvergenceResultStatus.FAILED, request.attempt_id, detail)
+    try:
+        payload = json.loads(result.stdout)
+        status = ConvergenceResultStatus(payload.get("status", "completed"))
+    except (ValueError, json.JSONDecodeError):
+        status = ConvergenceResultStatus.COMPLETED
+    return ConvergenceResultEnvelope(status, request.attempt_id, detail)

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/adapters/claude.py

@@ -0,0 +1,5 @@
+from .base import AdapterExecutionRequest, run_bounded
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope
+
+def run_claude_adapter(request: AdapterExecutionRequest) -> ConvergenceResultEnvelope:
+    return run_bounded(request, expected_prefix="claude")

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/adapters/codex.py

@@ -0,0 +1,5 @@
+from .base import AdapterExecutionRequest, run_bounded
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope
+
+def run_codex_adapter(request: AdapterExecutionRequest) -> ConvergenceResultEnvelope:
+    return run_bounded(request, expected_prefix="codex")

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/adapters/outside_agent.py

@@ -0,0 +1,9 @@
+from .base import AdapterExecutionRequest, run_bounded
+from phase_loop_runtime.train_ledger import ConvergenceResultEnvelope, ConvergenceResultStatus
+
+def run_outside_agent_adapter(request: AdapterExecutionRequest, submission: dict | None = None) -> ConvergenceResultEnvelope:
+    if submission is not None:
+        from phase_loop_runtime.conformance import validate_outside_agent_submission
+        if validate_outside_agent_submission(submission).status.value != "pass":
+            return ConvergenceResultEnvelope(ConvergenceResultStatus.BLOCKED, request.attempt_id, "outside-agent submission failed conformance")
+    return run_bounded(request, expected_prefix="outside-agent")

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/broker/__init__.py

@@ -0,0 +1,6 @@
+"""Credential-capable, fail-closed broker epoch."""
+from .admission import AdmissionRecord, BrokerAdmissionPolicy, LinearizableAdmissionStore
+from .credsep import BrokerEnvironmentBoundary, GitHubBrokerAdapter
+from .evidence import BrokerEvidenceStore, EvidenceRecord
+from .verbs import BrokerClient, BrokerExecutionResult, BrokerProviderAdapter, BrokerService, publish_committed_branch_idempotency_key
+__all__ = ["AdmissionRecord", "BrokerAdmissionPolicy", "LinearizableAdmissionStore", "BrokerEnvironmentBoundary", "GitHubBrokerAdapter", "BrokerEvidenceStore", "EvidenceRecord", "BrokerClient", "BrokerExecutionResult", "BrokerProviderAdapter", "BrokerService", "publish_committed_branch_idempotency_key"]

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/broker/admission.py

@@ -0,0 +1,56 @@
+"""Durable, metadata-only broker admission ordering."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Callable
+
+from phase_loop_runtime.convergence.contracts import AdmissionRequest
+
+
+@dataclass(frozen=True)
+class AdmissionRecord:
+    sequence: int
+    epoch: int
+    request: AdmissionRequest
+
+
+BrokerAdmissionPolicy = Callable[[AdmissionRequest], bool]
+
+
+class LinearizableAdmissionStore:
+    """Append-only admission log guarded by an OS advisory lock."""
+    def __init__(self, root: Path, policy: BrokerAdmissionPolicy | None = None, epoch_blocked: Callable[[], bool] | None = None) -> None:
+        self.root, self.policy, self.epoch_blocked = root, policy, epoch_blocked or (lambda: False)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.path, self.lock_path = root / "admissions.jsonl", root / "admissions.lock"
+
+    def _records(self) -> list[AdmissionRecord]:
+        if not self.path.exists(): return []
+        records = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            raw = json.loads(line); raw["request"] = AdmissionRequest(**raw["request"]); records.append(AdmissionRecord(**raw))
+        return records
+
+    def admit(self, request: AdmissionRequest) -> AdmissionRecord:
+        import fcntl
+        with self.lock_path.open("a+", encoding="utf-8") as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            try:
+                if self.epoch_blocked() or self.policy is None or not self.policy(request):
+                    raise PermissionError("broker admission denied")
+                records = self._records()
+                for record in records:
+                    if record.request.idempotency_key == request.idempotency_key:
+                        if record.request != request: raise ValueError("conflicting idempotency key")
+                        return record
+                if records and request.lease_epoch < max(r.epoch for r in records): raise PermissionError("stale epoch")
+                record = AdmissionRecord(len(records) + 1, request.lease_epoch, request)
+                with self.path.open("a", encoding="utf-8") as stream:
+                    stream.write(json.dumps(asdict(record), sort_keys=True) + "\n"); stream.flush(); os.fsync(stream.fileno())
+                return record
+            finally: fcntl.flock(lock, fcntl.LOCK_UN)
+
+    def replay(self) -> tuple[AdmissionRecord, ...]: return tuple(self._records())

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/broker/credsep.py

@@ -0,0 +1,54 @@
+"""Credential boundary and GitHub publish adapter."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Mapping
+
+from phase_loop_runtime.convergence.contracts import BrokerRequest, BrokerTerminalEvidence, PublishCommittedBranchResult
+
+MUTATION_CREDENTIAL_KEYS = frozenset({"GH_TOKEN", "GITHUB_TOKEN"})
+def strip_mutation_credentials(environment: Mapping[str, str]) -> dict[str, str]: return {k: v for k, v in environment.items() if k not in MUTATION_CREDENTIAL_KEYS}
+class BrokerEnvironmentBoundary:
+    def environment_for(self, role: str, environment: Mapping[str, str] | None = None) -> dict[str, str]:
+        env = dict(os.environ if environment is None else environment)
+        return env if role == "broker" else strip_mutation_credentials(env)
+def build_non_force_branch_ref(branch: str) -> str:
+    if not branch or branch.startswith("-") or branch in {"main", "master", "develop", "release"}: raise ValueError("unsafe branch")
+    return f"refs/heads/{branch}"
+class GitHubBrokerAdapter:
+    def __init__(self, repo_path: Path, run=subprocess.run) -> None: self.repo_path, self.run = repo_path, run
+    def _output(self, *args: str) -> str:
+        return self.run(["git", "-C", str(self.repo_path), *args], capture_output=True, text=True, check=True).stdout.strip()
+    def _ambiguous(self, request: BrokerRequest, reference: str):
+        # v5 rule: a failed/empty remote read is NEVER inferred as no_effect and
+        # NEVER fabricated as success — it is a permanent ambiguous block.
+        return None, BrokerTerminalEvidence(request.admission.idempotency_key, "outcome_ambiguous_blocked", reference)
+
+    def execute(self, request: BrokerRequest):
+        if self._output("branch", "--show-current") != request.branch or self._output("rev-parse", "HEAD") != request.head_sha: raise ValueError("branch/head mismatch")
+        ref = build_non_force_branch_ref(request.branch)
+        pushed = self.run(["git", "-C", str(self.repo_path), "push", "origin", ref], capture_output=True, text=True)
+        if pushed.returncode: return self._ambiguous(request, "push-unconfirmed")
+        args = ["gh", "pr", "create", "--draft"] if request.draft else ["gh", "pr", "create", "--fill"]
+        created = self.run(args, cwd=self.repo_path, capture_output=True, text=True)
+        if created.returncode: return self._ambiguous(request, "pr-unconfirmed")
+        # Exact-published-head verification: READ the remote and confirm the branch
+        # head on origin equals the pushed sha, then resolve the REAL PR url and
+        # confirm its headRefOid matches.  Only then is the effect terminally observed.
+        remote = self.run(["git", "-C", str(self.repo_path), "ls-remote", "origin", ref], capture_output=True, text=True)
+        if remote.returncode: return self._ambiguous(request, "remote-read-failed")
+        remote_sha = remote.stdout.split("\t", 1)[0].strip() if remote.stdout.strip() else ""
+        if not remote_sha: return self._ambiguous(request, "remote-branch-absent")
+        if remote_sha != request.head_sha: return self._ambiguous(request, "remote-head-mismatch")
+        listed = self.run(["gh", "pr", "list", "--head", request.branch, "--json", "url,headRefOid"], cwd=self.repo_path, capture_output=True, text=True)
+        if listed.returncode: return self._ambiguous(request, "pr-read-failed")
+        try:
+            prs = json.loads(listed.stdout or "[]")
+        except json.JSONDecodeError:
+            return self._ambiguous(request, "pr-read-unparsable")
+        match = next((p for p in prs if p.get("headRefOid") == request.head_sha and p.get("url")), None)
+        if match is None: return self._ambiguous(request, "pr-head-unconfirmed")
+        return PublishCommittedBranchResult(request.branch, request.head_sha, match["url"]), BrokerTerminalEvidence(request.admission.idempotency_key, "effect_terminal_observed", match["url"])

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/broker/evidence.py

@@ -0,0 +1,53 @@
+"""Append-only terminal evidence for broker operations."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from phase_loop_runtime.convergence.provider_contracts import TerminalOutcomeState, validate_terminal_transition
+
+
+@dataclass(frozen=True)
+class EvidenceRecord:
+    idempotency_key: str
+    state: TerminalOutcomeState
+    evidence_reference: str = ""
+
+
+class BrokerEvidenceStore:
+    def __init__(self, root: Path) -> None:
+        self.root = root; root.mkdir(parents=True, exist_ok=True); self.path = root / "evidence.jsonl"
+    def replay(self) -> dict[str, EvidenceRecord]:
+        result: dict[str, EvidenceRecord] = {}
+        if self.path.exists():
+            for line in self.path.read_text(encoding="utf-8").splitlines():
+                raw = json.loads(line); raw["state"] = TerminalOutcomeState(raw["state"]); result[raw["idempotency_key"]] = EvidenceRecord(**raw)
+        return result
+    @property
+    def epoch_blocked(self) -> bool:
+        return any(r.state is TerminalOutcomeState.OUTCOME_AMBIGUOUS_BLOCKED for r in self.replay().values())
+    def record_intent(self, key: str) -> EvidenceRecord:
+        current = self.replay().get(key)
+        if current: return current
+        return self._append(EvidenceRecord(key, TerminalOutcomeState.PROVIDER_CALL_IN_FLIGHT))
+    def record_terminal(self, record: EvidenceRecord, *, pre_linearization_proven: bool = False) -> EvidenceRecord:
+        current = self.replay().get(record.idempotency_key)
+        if current is None: raise ValueError("intent must precede evidence")
+        if current == record: return current
+        if not validate_terminal_transition(current.state, record.state, pre_linearization_proven=pre_linearization_proven): raise ValueError("invalid terminal transition")
+        return self._append(record)
+    def rejected_before_start(self, key: str, evidence_reference: str) -> EvidenceRecord:
+        return self._append(EvidenceRecord(key, TerminalOutcomeState.REJECTED_BEFORE_START, evidence_reference))
+    def _append(self, record: EvidenceRecord) -> EvidenceRecord:
+        # Storage-layer permanence: no write may transition OUT of a terminal
+        # outcome_ambiguous_blocked record.  This is self-enforcing regardless of
+        # caller path (record_terminal, rejected_before_start, record_intent), so a
+        # buggy caller cannot escape the block by writing a fresh terminal record.
+        current = self.replay().get(record.idempotency_key)
+        if current is not None and current.state is TerminalOutcomeState.OUTCOME_AMBIGUOUS_BLOCKED and record != current:
+            raise ValueError("outcome_ambiguous_blocked is permanent; no transition out")
+        with self.path.open("a", encoding="utf-8") as stream:
+            stream.write(json.dumps(asdict(record), sort_keys=True) + "\n"); stream.flush(); os.fsync(stream.fileno())
+        return record

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/broker/verbs.py

@@ -0,0 +1,72 @@
+"""The sole provider-agnostic mutation boundary."""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Protocol
+
+from phase_loop_runtime.convergence.contracts import BrokerRequest, BrokerTerminalEvidence, BrokerVerb, PublishCommittedBranchResult
+from phase_loop_runtime.convergence.provider_contracts import PROVIDER_COMPLETION_CLASSIFICATIONS, ProviderCompletionClassification, TerminalOutcomeState
+from .evidence import BrokerEvidenceStore, EvidenceRecord
+
+
+class BrokerProviderAdapter(Protocol):
+    def execute(self, request: BrokerRequest) -> tuple[PublishCommittedBranchResult | None, BrokerTerminalEvidence]: ...
+class BrokerClient(Protocol):
+    def execute(self, request: BrokerRequest) -> "BrokerExecutionResult": ...
+
+@dataclass(frozen=True)
+class BrokerExecutionResult:
+    accepted: bool
+    evidence: BrokerTerminalEvidence
+    publish_result: PublishCommittedBranchResult | None = None
+    reason: str = ""
+
+def publish_committed_branch_idempotency_key(repo: str, branch: str, head_sha: str) -> str:
+    return hashlib.sha256(f"{repo}\0{branch}\0{head_sha}".encode()).hexdigest()
+
+class BrokerService:
+    def __init__(self, admission_store, evidence_store: BrokerEvidenceStore, adapter: BrokerProviderAdapter, contracts=PROVIDER_COMPLETION_CLASSIFICATIONS) -> None:
+        self.admission_store, self.evidence_store, self.adapter, self.contracts = admission_store, evidence_store, adapter, contracts
+    def _dedup_key(self, request: BrokerRequest) -> str:
+        # publish_committed_branch de-dups on the canonical (repo, branch, head_sha)
+        # triple so a repeat under a fresh admission key is a no-op that returns the
+        # SAME prior result.  Other verbs remain keyed by the admission key.
+        if request.verb is BrokerVerb.PUBLISH_COMMITTED_BRANCH:
+            return publish_committed_branch_idempotency_key(request.repo, request.branch, request.head_sha)
+        return request.admission.idempotency_key
+
+    def _replay(self, request: BrokerRequest, key: str, current: EvidenceRecord) -> BrokerExecutionResult:
+        observed = current.state is TerminalOutcomeState.EFFECT_TERMINAL_OBSERVED
+        # Idempotent recovery: a replay of a COMPLETED publish_committed_branch must
+        # return the prior PublishCommittedBranchResult (pr_url persisted in the
+        # evidence reference), NOT None — otherwise the caller reports it blocked.
+        result = (
+            PublishCommittedBranchResult(request.branch, request.head_sha, current.evidence_reference)
+            if observed and request.verb is BrokerVerb.PUBLISH_COMMITTED_BRANCH
+            else None
+        )
+        return BrokerExecutionResult(observed, BrokerTerminalEvidence(key, current.state.value, current.evidence_reference), result)
+
+    def execute(self, request: BrokerRequest) -> BrokerExecutionResult:
+        key = self._dedup_key(request)
+        current = self.evidence_store.replay().get(key)
+        if current and current.state is not TerminalOutcomeState.PROVIDER_CALL_IN_FLIGHT:
+            return self._replay(request, key, current)
+        contract = next((c for c in self.contracts if c.verb == request.verb.value and c.provider == "github"), None)
+        if contract is None or contract.classification is not ProviderCompletionClassification.SUPPORTED:
+            evidence = self.evidence_store.rejected_before_start(key, "provider-classification")
+            return BrokerExecutionResult(False, BrokerTerminalEvidence(key, evidence.state.value, evidence.evidence_reference), reason="provider_not_supported")
+        if self.evidence_store.epoch_blocked: raise PermissionError("epoch permanently blocked")
+        self.admission_store.admit(request.admission); self.evidence_store.record_intent(key)
+        try:
+            result, evidence = self.adapter.execute(request)
+            state = TerminalOutcomeState(evidence.terminal_state)
+            # Persist the real pr_url as the evidence reference so a later replay can
+            # reconstruct the identical PublishCommittedBranchResult.
+            reference = result.pr_url if result is not None else evidence.evidence_reference
+            recorded = self.evidence_store.record_terminal(EvidenceRecord(key, state, reference))
+            return BrokerExecutionResult(state is TerminalOutcomeState.EFFECT_TERMINAL_OBSERVED, BrokerTerminalEvidence(key, recorded.state.value, recorded.evidence_reference), result)
+        except Exception:
+            recorded = self.evidence_store.record_terminal(EvidenceRecord(key, TerminalOutcomeState.OUTCOME_AMBIGUOUS_BLOCKED, "adapter-exception"))
+            return BrokerExecutionResult(False, BrokerTerminalEvidence(key, recorded.state.value, recorded.evidence_reference), reason="outcome_ambiguous")

phase_loop_runtime-0.7.5/src/phase_loop_runtime/convergence/contracts.py

@@ -0,0 +1,129 @@
+"""Behavior-neutral coordination contracts shared by future runtime and broker phases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Tuple
+
+
+class BrokerVerb(str, Enum):
+    PUBLISH = "publish"
+    MERGE = "merge"
+    RELEASE = "release"
+    PACKAGE = "package"
+    PUBLISH_COMMITTED_BRANCH = "publish_committed_branch"
+
+
+@dataclass(frozen=True)
+class AdmissionRequest:
+    """The sole fencing shape shared by RUNTIME and BROKER."""
+
+    attempt_id: str
+    lease_epoch: int
+    fence_token: str
+    approval_digest: str
+    expected_version_predicate: str
+    authority_domain_scope: str
+    idempotency_key: str
+
+    def __post_init__(self) -> None:
+        if not all((self.attempt_id, self.fence_token, self.approval_digest, self.expected_version_predicate, self.authority_domain_scope, self.idempotency_key)):
+            raise ValueError("admission requests require every fencing field")
+
+
+@dataclass(frozen=True)
+class BrokerRequest:
+    """A future broker request bound to one shared admission request."""
+
+    verb: BrokerVerb
+    admission: AdmissionRequest
+    repo: str
+    branch: str
+    head_sha: str
+    owned_paths: Tuple[str, ...]
+    draft: bool = True
+    pr_body: str = ""
+
+
+@dataclass(frozen=True)
+class BrokerTerminalEvidence:
+    """Effect or no-effect evidence keyed by the admission idempotency key."""
+
+    idempotency_key: str
+    terminal_state: str
+    evidence_reference: str
+
+
+@dataclass(frozen=True)
+class PublishCommittedBranchResult:
+    """Frozen result shape for publish_committed_branch."""
+
+    branch: str
+    head_sha: str
+    pr_url: str
+
+
+class AuthoritySource(str, Enum):
+    ROADMAP = "roadmap_intent"
+    EVENT_LOG = "event_log_active_operation"
+    GIT_HEAD = "git_commit_or_pr_head_implementation"
+    MERGED_SHA = "merged_sha_merged_state"
+    REGISTRY_MANIFEST = "registry_or_manifest_released_state"
+    RECOVERY_EVIDENCE = "transcripts_or_phase_loop_recovery_evidence"
+
+
+class InvalidationTrigger(str, Enum):
+    EFFECTIVE_CODE_CHANGED = "effective_code_changed"
+    ROADMAP_CHANGED = "roadmap_changed"
+    BASE_SHA_CHANGED = "base_sha_changed"
+    DEPENDENCY_SHA_CHANGED = "dependency_sha_changed"
+    VERIFICATION_PLAN_DIGEST_CHANGED = "verification_plan_digest_changed"
+
+
+@dataclass(frozen=True)
+class ReconciliationBinding:
+    """Versioned authority decision and the invalidations that require recomputation."""
+
+    authority: AuthoritySource
+    authority_version: str
+    invalidation_model_version: str
+    invalidation_triggers: Tuple[InvalidationTrigger, ...] = ()
+
+
+@dataclass(frozen=True)
+class ResourceIsolationDecision:
+    """Fail-closed decision explaining whether two future units may run concurrently."""
+
+    parallel_safe: bool
+    reason: str
+
+
+def evaluate_resource_isolation(
+    *,
+    left_repo: str,
+    right_repo: str,
+    left_owned_paths: Tuple[str, ...],
+    right_owned_paths: Tuple[str, ...],
+    frozen_shared_interfaces: bool,
+    same_repo_mutation: bool = False,
+    topological_merge: bool = False,
+    release_publication: bool = False,
+    evidence_known: bool = True,
+) -> ResourceIsolationDecision:
+    """Apply the FREEZE fail-closed concurrency predicate without scheduling work."""
+    if not evidence_known:
+        return ResourceIsolationDecision(False, "unknown evidence")
+    if same_repo_mutation or left_repo == right_repo:
+        return ResourceIsolationDecision(False, "same-repo mutation serializes")
+    if topological_merge:
+        return ResourceIsolationDecision(False, "topological merges serialize")
+    if release_publication:
+        return ResourceIsolationDecision(False, "release publication serializes")
+    if not frozen_shared_interfaces:
+        return ResourceIsolationDecision(False, "shared interfaces are not frozen")
+    if not left_owned_paths or not right_owned_paths:
+        return ResourceIsolationDecision(False, "owned-path evidence is incomplete")
+    if set(left_owned_paths) & set(right_owned_paths):
+        return ResourceIsolationDecision(False, "owned paths overlap")
+    return ResourceIsolationDecision(True, "disjoint paths with frozen interfaces")