macp-sdk-python 0.6.0__tar.gz → 0.8.0__tar.gz

{macp_sdk_python-0.6.0/src/macp_sdk_python.egg-info → macp_sdk_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.6.0
+Version: 0.8.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: grpcio>=1.82.0rc2
 Requires-Dist: protobuf>=7.35.0
-Requires-Dist: macp-proto<0.1.9,>=0.1.6
+Requires-Dist: macp-proto<0.1.10,>=0.1.6
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -30,6 +30,7 @@ Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: grpc-stubs>=1.53; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
 Requires-Dist: jsonschema>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
@@ -127,7 +128,7 @@ if winner and not session.decision_projection.has_blocking_objection(winner):
 make setup              # pip install -e ".[dev,docs]"
 
 # Quality
-make lint               # ruff check
+make lint               # ruff check + ruff format --check
 make fmt                # ruff format
 make typecheck          # mypy strict
 make test               # unit tests + coverage gate (85% branch, from pyproject)
@@ -136,7 +137,7 @@ make test-all           # lint + typecheck + all tests
 make coverage           # HTML + terminal coverage report
 
 # Build
-make build              # sdist + wheel
+make build              # build sdist + wheel, then twine check
 
 # Proto definitions (provided by macp-proto package)
 make dev-link-protos    # link local proto package for development

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/README.md

@@ -89,7 +89,7 @@ if winner and not session.decision_projection.has_blocking_objection(winner):
 make setup              # pip install -e ".[dev,docs]"
 
 # Quality
-make lint               # ruff check
+make lint               # ruff check + ruff format --check
 make fmt                # ruff format
 make typecheck          # mypy strict
 make test               # unit tests + coverage gate (85% branch, from pyproject)
@@ -98,7 +98,7 @@ make test-all           # lint + typecheck + all tests
 make coverage           # HTML + terminal coverage report
 
 # Build
-make build              # sdist + wheel
+make build              # build sdist + wheel, then twine check
 
 # Proto definitions (provided by macp-proto package)
 make dev-link-protos    # link local proto package for development

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macp-sdk-python"
-version = "0.6.0"
+version = "0.8.0"
 description = "Python SDK for the MACP Rust runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -52,7 +52,7 @@ dependencies = [
   # grpcio comment above) — PEP 440 sorts 1.82.0rc2 below 1.82.0, so no
   # candidate exists. 0.1.6/0.1.7 declare "grpcio>=1.74.0" and resolve fine.
   # Re-widen to <0.2.0 once grpcio publishes a stable >= 1.82.1.
-  "macp-proto>=0.1.6,<0.1.9",
+  "macp-proto>=0.1.6,<0.1.10",
 ]
 
 [project.urls]
@@ -74,6 +74,7 @@ dev = [
   "ruff>=0.5",
   "grpc-stubs>=1.53",
   "build>=1.0",
+  "twine>=5.0",  # validates the built artifacts (`make build`), mirroring ci.yml's build job
   "jsonschema>=4.0",  # validate vendored conformance fixtures against schema.json
 ]
 docs = [

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk/__init__.py

@@ -1,8 +1,14 @@
 from ._logging import configure_logging
 from .auth import AuthConfig
-from .base_projection import BaseProjection
+from .base_projection import (
+    ANOMALY_DUPLICATE_BALLOT,
+    ANOMALY_DUPLICATE_VOTE,
+    BaseProjection,
+    ProjectionAnomaly,
+)
 from .base_session import BaseSession
 from .client import InlineErrorCallback, MacpClient, MacpStream
+from .commitment_hash import commitment_hash, is_canonical_commitment_hash
 from .constants import (
     DEFAULT_CONFIGURATION_VERSION,
     DEFAULT_MODE_VERSION,
@@ -85,6 +91,7 @@ from .quorum import QuorumProjection, QuorumSession
 from .retry import RetryPolicy, retry_send
 from .task import TaskProjection, TaskSession
 from .validation import (
+    validate_commitment_hash,
     validate_confidence,
     validate_participant_count,
     validate_participants,
@@ -108,6 +115,8 @@ from .watchers import (
 )
 
 __all__ = [
+    "ANOMALY_DUPLICATE_BALLOT",
+    "ANOMALY_DUPLICATE_VOTE",
     "DEFAULT_CONFIGURATION_VERSION",
     "DEFAULT_MODE_VERSION",
     "DEFAULT_POLICY_VERSION",
@@ -163,6 +172,7 @@ __all__ = [
     "ObjectionHandlingRules",
     "PolicyChange",
     "PolicyWatcher",
+    "ProjectionAnomaly",
     "ProposalAcceptanceRules",
     "ProposalProjection",
     "ProposalSession",
@@ -195,13 +205,16 @@ __all__ = [
     "build_session_start_payload",
     "build_signal_payload",
     "build_task_policy",
+    "commitment_hash",
     "configure_logging",
     "infer_outcome_positive",
+    "is_canonical_commitment_hash",
     "new_commitment_id",
     "new_message_id",
     "new_session_id",
     "retry_send",
     "serialize_message",
+    "validate_commitment_hash",
     "validate_confidence",
     "validate_participant_count",
     "validate_participants",

macp_sdk_python-0.8.0/src/macp_sdk/base_projection.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import ClassVar
+
+from macp.v1 import core_pb2, envelope_pb2
+
+from ._logging import logger
+
+# Cross-SDK contract with macp-sdk-typescript#55 — these two string values are
+# part of the wire-adjacent public API and must match the TypeScript SDK
+# byte-for-byte. Do not rename, and do not add a third without coordinating
+# there first.
+ANOMALY_DUPLICATE_VOTE = "duplicate_vote"  # RFC-MACP-0007 §5.3
+ANOMALY_DUPLICATE_BALLOT = "duplicate_ballot"  # RFC-MACP-0011 §5
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectionAnomaly:
+    """A discarded-message observation recorded by a projection.
+
+    Cross-SDK contract with macp-sdk-typescript#55: the field names, their
+    order, and both ``kind`` string values (``ANOMALY_DUPLICATE_VOTE``,
+    ``ANOMALY_DUPLICATE_BALLOT``) are a byte-for-byte contract shared with the
+    TypeScript SDK. Do not rename, reorder, or extend the field set without
+    coordinating there first.
+
+    Honesty clause: this records an **observation**, not a spec-violation
+    verdict. A projection cannot distinguish a genuinely non-conforming
+    source from a conforming source fed through an unfiltered loader --
+    acceptance is not a wire property (see ``apply_envelope``'s docstring).
+    Treat ``kind`` as "a second distinct message of this shape was observed
+    and discarded; the first stands," not as "this transcript violates the
+    spec."
+
+    Deliberately does not carry the full ``Envelope``: too heavy a public
+    commitment. The discarded envelope remains recoverable by correlating
+    ``message_id`` against a projection's ``transcript``.
+    """
+
+    kind: str
+    mode: str
+    message_type: str
+    message_id: str
+    sender: str
+    subject_id: str  # proposal_id / request_id
+    detail: str = ""
+
+
+class BaseProjection(ABC):
+    """Abstract base for in-process mode state tracking.
+
+    Maintains a local transcript and delegates mode-specific message handling
+    to subclasses.  Needed because the runtime's ``GetSession`` RPC returns
+    metadata only, not mode state or transcript.
+    """
+
+    MODE: ClassVar[str]
+
+    def __init__(self) -> None:
+        self.transcript: list[envelope_pb2.Envelope] = []
+        self.phase: str = ""
+        self.commitment: core_pb2.CommitmentPayload | None = None
+        # Implementation detail, not public API: tracks message_id values already
+        # applied to this projection so a redelivered envelope is a no-op. See
+        # apply_envelope's docstring for the contract.
+        self._seen_message_ids: set[str] = set()
+        # Public: discarded-message observations recorded via _record_anomaly
+        # (Decision Vote, Quorum ballot -- see those projections' first-wins
+        # branches). See ProjectionAnomaly's docstring for the cross-SDK
+        # contract it carries.
+        self.anomalies: list[ProjectionAnomaly] = []
+
+    @property
+    def is_committed(self) -> bool:
+        return self.commitment is not None
+
+    @property
+    def has_anomalies(self) -> bool:
+        return bool(self.anomalies)
+
+    @property
+    def is_positive_outcome(self) -> bool | None:
+        """Return the outcome polarity, or ``None`` if not yet committed."""
+        if self.commitment is None:
+            return None
+        return getattr(self.commitment, "outcome_positive", True)
+
+    def apply_envelope(self, envelope: envelope_pb2.Envelope) -> None:
+        """Apply one envelope from **accepted history** to local state.
+
+        Precondition — accepted history only, not enforced here: callers MUST
+        feed only envelopes that a conforming runtime accepted. A subscribe
+        stream satisfies this automatically (RFC-MACP-0006 §3.2 obligation 4:
+        a runtime never replays rejected envelopes). Any other feed — hand-built
+        fixtures, captured logs, transcripts carrying non-accepted entries — MUST
+        be filtered by the caller before it reaches this method, the way
+        ``tests/conformance/test_conformance_projections.py:153`` filters out
+        non-``accept`` fixture entries. This method has no way to verify that
+        precondition, and derived state is **undefined** without it.
+
+        Idempotency: applying an envelope whose ``message_id`` has already been
+        seen by this projection is a total no-op — it is not appended to
+        ``transcript`` and is not dispatched to mode handling. This makes
+        redelivery (e.g. a stream resubscribe replaying accepted history from
+        the start) safe to re-apply without corrupting derived state. An empty
+        ``message_id`` (the proto3 default for hand-built envelopes) is never
+        deduplicated — every such envelope is applied. See the code comment on
+        the dedup gate below for the precise normative basis.
+
+        Honest limitation: this dedups **redelivery of the same envelope**, not
+        every way a feed can carry a non-conforming message. A *genuine*
+        duplicate -- e.g. a second, distinct ``Vote`` from a sender who already
+        voted on the same proposal, carrying its own new ``message_id`` -- is
+        not caught here: it passes this method's dedup gate, is appended to
+        ``transcript``, and is dispatched to mode handling like any other
+        envelope. Discarding it and recording the observation is the mode
+        projection's job, not this base method's -- see
+        ``DecisionProjection``'s Vote branch and ``QuorumProjection._set_ballot``,
+        which apply first-wins and append a ``ProjectionAnomaly`` (``anomalies``,
+        ``has_anomalies``) rather than silently overwriting. A rejected vote
+        from a sender who never votes again still corrupts derived state with
+        nothing here to detect it -- this method has no visibility into
+        cardinality rules, which are mode-specific. No mechanism in this
+        method closes that narrower gap; do not imply one exists.
+
+        Determinism holds in both directions: replaying ``transcript`` through a
+        fresh projection reproduces the same state, whether or not duplicates or
+        redeliveries were present in the original feed.
+
+        Acceptance is not a wire property: nothing on the envelope itself marks
+        it as "accepted" — it is accepted only by virtue of appearing in
+        accepted history at all, per the precondition above. If a caller sees a
+        surprising result, correlate the offending envelope's ``message_id``
+        against their own acceptance metadata (what they actually received back
+        from the runtime) to determine whether the surprise came from a
+        non-conforming source or from an unfiltered feed, rather than assuming
+        this method mis-processed it.
+
+        Not thread-safe: the ``message_id`` dedup check-then-add below is not
+        atomic across threads, and this class holds no lock. A single
+        projection instance must not be fed concurrently from multiple threads.
+
+        On failure: if applying the envelope raises, this method removes the
+        envelope from ``transcript`` and releases its ``message_id`` from the
+        dedup set before the exception propagates, so the caller may retry
+        the identical envelope and it will be applied rather than silently
+        swallowed as a redelivery. This rollback covers only ``transcript``
+        and the dedup set — subclass-derived state (e.g. ``self.phase``, or
+        any subclass collection) is not rolled back.
+        """
+        if envelope.mode != self.MODE:
+            return
+
+        # Empty-id guard — the real reason, not a test accommodation: message_id
+        # is a proto3 scalar, so its unset value is "" — not a real identity.
+        # Deduplicating on "" would collapse every envelope lacking an id into a
+        # single logical message. Hand-built envelopes without an id are a real,
+        # exercised path in this repo: tests/unit/test_client_helpers.py:142 and
+        # tests/unit/test_client_stream.py:160 both construct one. So the guard
+        # only dedupes non-empty ids.
+        #
+        # At-least-once basis for dedup, cited precisely:
+        #   - Load-bearing: RFC-MACP-0001-core.md:306 — "MACP assumes
+        #     at-least-once delivery semantics at the transport layer."
+        #     Unqualified, about the transport, so it binds any consumer of that
+        #     transport including client projections. From this alone it
+        #     follows that a projection may be handed the same envelope twice.
+        #     This is an INFERENCE from a transport-layer premise, not a MUST
+        #     addressed to clients.
+        #   - Corroborating only, not compelling on its own: RFC-MACP-0001 §8.2
+        #     (:316) — "Runtimes MUST enforce idempotent handling of duplicates
+        #     using message_id." That MUST is addressed to runtimes at their
+        #     ingress boundary, not to clients; its contribution here is only
+        #     the *identity* to key dedup on (message_id, not envelope bytes).
+        #   - Now normative for clients directly: RFC-MACP-0006 §3.2 (spec PR
+        #     #80, RFC-0006 1.4.0-draft) requires a client to tolerate an
+        #     already-observed envelope and to key duplicate detection on
+        #     message_id.
+        # Mirrors the runtime's own boundary idempotency: src/macp_sdk/client.py
+        # :419-422 already treats ack.duplicate as idempotent success.
+        message_id = envelope.message_id
+        seen_id_added = False
+        if message_id:
+            if message_id in self._seen_message_ids:
+                return
+            self._seen_message_ids.add(message_id)
+            seen_id_added = True
+
+        self.transcript.append(envelope)
+
+        # Rollback scope — narrower than "atomic" might suggest: the
+        # dedup-set add and transcript append above both happen BEFORE the
+        # actual effect (Commitment ParseFromString, or the subclass's
+        # _apply_mode_message dispatch), either of which can raise. On such
+        # a raise, the except block below undoes exactly those two
+        # mutations — transcript and _seen_message_ids — and re-raises, so
+        # a retry of the SAME envelope is not swallowed as a redelivery.
+        # Concretely: a supervisor that catches an exception out of
+        # Participant.run() and resubscribes (agent/transports.py:60
+        # replays accepted history from after_sequence=0) re-feeds the same
+        # envelope to the same projection (agent/participant.py:410,
+        # apply_envelope unguarded) — without this rollback the dedup gate
+        # would silently swallow that retry, permanently losing the
+        # envelope's effect while transcript still claims it is present.
+        #
+        # What this does NOT cover: self.phase (assigned directly on
+        # BaseProjection by subclasses — see projections.py:84,
+        # task.py:103, handoff.py:71) and any subclass-owned collection
+        # (evaluations, objections, accepts, rejections, updates,
+        # completions, failures) are never rolled back, because this
+        # method has no way to know what a subclass mutated. That is safe
+        # only because every _apply_mode_message implementation in this
+        # SDK today performs its one fallible operation (ParseFromString)
+        # strictly before any mutation, and every record type it
+        # constructs is a plain slotted dataclass whose construction
+        # cannot raise — so there is presently no reachable path that
+        # mutates subclass state and then raises. This is a
+        # raise-before-mutate invariant that _apply_mode_message
+        # implementations must preserve. BaseProjection is exported for
+        # third-party subclassing (see __init__.py:143), and upcoming
+        # first-wins/anomaly-tracking logic must keep fallible work ahead
+        # of mutations to keep this guarantee honest.
+        #
+        # Catches Exception, not BaseException: KeyboardInterrupt/SystemExit
+        # signal that the process is being torn down, not a recoverable
+        # per-envelope failure, and should propagate immediately rather than
+        # be treated as "this envelope's apply failed, try rolling back."
+        try:
+            if envelope.message_type == "Commitment":
+                payload = core_pb2.CommitmentPayload()
+                payload.ParseFromString(envelope.payload)
+                self.commitment = payload
+                self.phase = "Committed"
+                return
+
+            self._apply_mode_message(envelope)
+        except Exception:
+            # Roll back exactly what this call added, nothing more. In
+            # every path exercised by this SDK today, the append two lines
+            # above is the only mutation of transcript between there and
+            # here, so transcript[-1] is the entry this call just
+            # appended. But BaseProjection is a public ABC (exported at
+            # __init__.py:143) that third parties may subclass, so guard
+            # with an identity check rather than popping unconditionally.
+            # The two ways the guard could see something else at [-1] are:
+            #   - a subclass's _apply_mode_message appending to
+            #     self.transcript itself before raising (no subclass in
+            #     this SDK does this — each mutates only its own
+            #     collections, never self.transcript directly);
+            #   - a re-entrant call to apply_envelope on the same instance
+            #     while this call is still on the stack (nothing in this
+            #     SDK calls apply_envelope from within apply_envelope or
+            #     from a mode handler).
+            # Neither happens here, but a wrong-entry pop under either
+            # would silently corrupt an unrelated transcript entry — data
+            # corruption strictly worse than the bug this rollback fixes.
+            # `is` identity, not `==`: protobuf messages compare by value,
+            # so two distinct envelopes can be equal without being the
+            # same object.
+            if self.transcript and self.transcript[-1] is envelope:
+                self.transcript.pop()
+            if seen_id_added:
+                self._seen_message_ids.discard(message_id)
+            raise
+
+    @abstractmethod
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        """Handle a mode-specific (non-Commitment) envelope."""
+
+    def _record_anomaly(
+        self,
+        *,
+        kind: str,
+        message_type: str,
+        message_id: str,
+        sender: str,
+        subject_id: str,
+        detail: str = "",
+    ) -> None:
+        """Append a `ProjectionAnomaly` and emit exactly one WARNING log line.
+
+        Protected and keyword-only: subclasses are the only callers, and
+        keyword-only arguments prevent a positional call from silently
+        transposing two same-typed fields (e.g. sender/subject_id). ``mode``
+        is filled in from ``self.MODE`` rather than accepted as an argument,
+        so call sites cannot drift from the projection's own mode.
+
+        Call sites: ``DecisionProjection``'s Vote branch and
+        ``QuorumProjection._set_ballot``, on first-wins discard of a genuine
+        duplicate Vote/ballot.
+        """
+        anomaly = ProjectionAnomaly(
+            kind=kind,
+            mode=self.MODE,
+            message_type=message_type,
+            message_id=message_id,
+            sender=sender,
+            subject_id=subject_id,
+            detail=detail,
+        )
+        self.anomalies.append(anomaly)
+        logger.warning(
+            "projection anomaly kind=%s mode=%s message_type=%s message_id=%s "
+            "sender=%s subject_id=%s detail=%s",
+            anomaly.kind,
+            anomaly.mode,
+            anomaly.message_type,
+            anomaly.message_id,
+            anomaly.sender,
+            anomaly.subject_id,
+            anomaly.detail,
+        )

macp_sdk_python-0.8.0/src/macp_sdk/commitment_hash.py

@@ -0,0 +1,317 @@
+"""Canonical commitment hash (RFC-MACP-0013).
+
+Computes ``CommitmentRef.commitment_hash`` as a domain-separated SHA-256
+digest over an RFC 8785 (JCS) canonicalized JSON projection of the frozen
+nine-field ``CommitmentPayload`` set (RFC-MACP-0013 §5).
+
+This module intentionally has **no third-party imports beyond
+``google.protobuf``/``macp.v1.core_pb2``** — the hashing algorithm is pure
+stdlib (plus the protobuf runtime already required to hold ``payload``
+itself) so that it can be reused (and re-verified) without pulling in the
+rest of the SDK.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from google.protobuf import unknown_fields  # type: ignore[import-untyped]
+from macp.v1 import core_pb2
+
+from .errors import MacpSessionError
+
+#: Identifies this projection/preimage construction (RFC-MACP-0013 §4, §7).
+#: A change here is a MACP protocol MINOR change (new label, e.g. "/2").
+LABEL = "macp-commitment-hash/1"
+
+#: The frozen nine-field set ``CommitmentPayload`` MUST be limited to for this
+#: hash label (RFC-MACP-0013 §5). A future ``macp-proto`` release that adds a
+#: tenth field to the message is not hashable under this label -- see
+#: `_check_frozen_field_set`.
+_FROZEN_FIELD_NAMES = frozenset(
+    {
+        "commitment_id",
+        "action",
+        "authority_scope",
+        "reason",
+        "mode_version",
+        "policy_version",
+        "configuration_version",
+        "outcome_positive",
+        "supersedes",
+    }
+)
+
+#: The installed ``macp-proto``'s actual ``CommitmentPayload`` field names,
+#: computed once at import time so `_check_frozen_field_set` never has to
+#: walk the descriptor on every `commitment_hash()` call.
+_ACTUAL_FIELD_NAMES: frozenset[str] = frozenset(
+    f.name for f in core_pb2.CommitmentPayload.DESCRIPTOR.fields
+)
+
+#: The frozen two-field set ``CommitmentRef`` (the type of `supersedes`) MUST
+#: be limited to for this hash label (RFC-MACP-0013 §5): "``supersedes``,
+#: when set, carries exactly two fields (``session_id``, ``commitment_hash``)".
+#: A future ``macp-proto`` release that adds a third field to ``CommitmentRef``
+#: itself is not hashable under this label -- see `_check_frozen_ref_field_set`.
+_FROZEN_REF_FIELD_NAMES = frozenset({"session_id", "commitment_hash"})
+
+#: The installed ``macp-proto``'s actual ``CommitmentRef`` field names,
+#: computed once at import time, mirroring `_ACTUAL_FIELD_NAMES` above.
+_ACTUAL_REF_FIELD_NAMES: frozenset[str] = frozenset(
+    f.name for f in core_pb2.CommitmentRef.DESCRIPTOR.fields
+)
+
+#: Matched with `re.fullmatch` (see `is_canonical_commitment_hash`), so the
+#: anchors here are redundant but kept for readability.
+_HASH_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+# RFC 8785 §3.2.2.2 short-form escapes.
+_SHORT_ESCAPES: dict[str, str] = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def _escape_json_string(value: str) -> str:
+    """Escape ``value`` per RFC 8785 §3.2.2.2 and wrap it in double quotes.
+
+    Short-form escapes are used for backslash, quote, and the C0 controls
+    that have them (\\b \\t \\n \\f \\r); other C0 controls (U+0000-U+001F)
+    use \\u00XX; everything else -- including all non-ASCII and astral-plane
+    code points -- is emitted literally as the Unicode scalar value it is
+    (Python `str` already holds scalar values, not UTF-16 code units, so no
+    surrogate-pair handling is needed here).
+    """
+    out: list[str] = ['"']
+    for ch in value:
+        short = _SHORT_ESCAPES.get(ch)
+        if short is not None:
+            out.append(short)
+        elif ch < "\x20":
+            out.append(f"\\u{ord(ch):04x}")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _json_bool(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _supersedes_member(ref: core_pb2.CommitmentRef) -> str:
+    # Inside `supersedes`, key order is commitment_hash, session_id
+    # (plain lexicographic sort of the two ASCII member names).
+    members = [
+        f"{_escape_json_string('commitment_hash')}:{_escape_json_string(ref.commitment_hash)}",
+        f"{_escape_json_string('session_id')}:{_escape_json_string(ref.session_id)}",
+    ]
+    return "{" + ",".join(members) + "}"
+
+
+def _check_frozen_field_set(field_names: frozenset[str] | None = None) -> None:
+    """Raise if ``field_names`` contains anything outside the RFC-MACP-0013 §5
+    frozen nine-field set for ``CommitmentPayload``.
+
+    RFC-MACP-0013 §5: "A ``CommitmentPayload`` carrying a field outside this
+    set is not hashable under this label. A verifier presented with such a
+    payload MUST return a cannot-verify result... never silently ignored."
+    §12 reinforces that skipping this check "produces a value that is not a
+    canonical commitment hash at all."
+
+    Defaults to the installed proto's actual field set (`_ACTUAL_FIELD_NAMES`,
+    computed once at import time and re-read from the module namespace here
+    -- not bound as a mutable default argument -- so that tests can
+    monkeypatch it); a caller may also pass an explicit set directly. Either
+    way this is how tests exercise the "extra field" branch without needing a
+    real 10-field proto descriptor.
+
+    This is *not* about an older proto missing a field (that's already
+    handled by the comment in `commitment_hash()`: accessing a genuinely
+    absent field raises ``AttributeError`` naturally) -- this is only about a
+    newer proto carrying a field this module does not know about.
+    """
+    if field_names is None:
+        field_names = _ACTUAL_FIELD_NAMES
+    extra = field_names - _FROZEN_FIELD_NAMES
+    if extra:
+        raise MacpSessionError(
+            "CommitmentPayload carries field(s) outside the RFC-MACP-0013 §5 "
+            f"frozen nine-field set and is not hashable under label {LABEL!r}: "
+            f"{sorted(extra)}"
+        )
+
+
+def _check_frozen_ref_field_set(field_names: frozenset[str] | None = None) -> None:
+    """Raise if ``field_names`` contains anything outside the RFC-MACP-0013 §5
+    frozen two-field set for ``CommitmentRef`` (the type of ``supersedes``).
+
+    Mirrors `_check_frozen_field_set` exactly, one level down: that guard
+    catches a future ``macp-proto`` growing a 10th field on
+    ``CommitmentPayload`` itself; this one catches a future ``macp-proto``
+    growing a 3rd field on the nested ``CommitmentRef`` message, which
+    `_supersedes_member` would otherwise silently under-project without
+    anything raising.
+
+    Defaults to the installed proto's actual field set
+    (`_ACTUAL_REF_FIELD_NAMES`, computed once at import time and re-read from
+    the module namespace here -- not bound as a mutable default argument --
+    so that tests can monkeypatch it); a caller may also pass an explicit set
+    directly, exactly as `_check_frozen_field_set` does.
+    """
+    if field_names is None:
+        field_names = _ACTUAL_REF_FIELD_NAMES
+    extra = field_names - _FROZEN_REF_FIELD_NAMES
+    if extra:
+        raise MacpSessionError(
+            "CommitmentRef carries field(s) outside the RFC-MACP-0013 §5 "
+            f"frozen two-field set and is not hashable under label {LABEL!r}: "
+            f"{sorted(extra)}"
+        )
+
+
+def _check_no_unknown_wire_fields(payload: core_pb2.CommitmentPayload) -> None:
+    """Raise if ``payload`` carries wire data for a field number the
+    installed schema does not recognize at all (an "unknown field").
+
+    `_check_frozen_field_set` only catches schema drift: a *newer* installed
+    ``macp-proto`` whose ``CommitmentPayload.DESCRIPTOR`` has grown a 10th
+    field. It cannot see this case: a peer sent bytes for a field number the
+    *local* schema has never heard of, so protobuf parses the message
+    successfully and stashes those bytes as an "unknown field" on the
+    instance, invisible to ``DESCRIPTOR.fields`` (RFC-MACP-0013 §5). Left
+    unchecked, `canonical_projection` would silently hash only the known
+    fields and drop the unknown field's contribution -- exactly the
+    "not hashable under this label ... never silently ignored" outcome the
+    RFC prohibits.
+
+    Classic ``payload.UnknownFields()`` raises ``NotImplementedError`` under
+    the ``upb`` backend (the default fast C-extension protobuf backend), so
+    this uses ``google.protobuf.unknown_fields.UnknownFieldSet``, the public
+    upb-safe replacement, instead.
+
+    This only inspects ``payload`` itself, not the nested ``supersedes``
+    submessage -- see `_check_no_unknown_ref_wire_fields` for the equivalent
+    check one level down.
+    """
+    unknown = unknown_fields.UnknownFieldSet(payload)
+    if len(unknown) > 0:
+        field_numbers = sorted({f.field_number for f in unknown})
+        raise MacpSessionError(
+            "CommitmentPayload carries wire data for unrecognized field "
+            "number(s) outside the RFC-MACP-0013 §5 frozen nine-field set "
+            f"and is not hashable under label {LABEL!r}: {field_numbers}"
+        )
+
+
+def _check_no_unknown_ref_wire_fields(ref: core_pb2.CommitmentRef) -> None:
+    """Raise if ``ref`` (a ``supersedes`` submessage) carries wire data for a
+    field number the installed schema does not recognize at all.
+
+    Mirrors `_check_no_unknown_wire_fields` one level down: a peer may send a
+    ``CommitmentRef`` with wire data for a field number outside the
+    RFC-MACP-0013 §5 frozen two-field set (``session_id``=1,
+    ``commitment_hash``=2). `_check_frozen_ref_field_set` only catches schema
+    drift (a newer installed ``macp-proto``'s ``CommitmentRef.DESCRIPTOR``
+    growing a 3rd field); it cannot see wire data for a field number the
+    *local* schema has never heard of at all, which protobuf parses
+    successfully and stashes as an "unknown field", invisible to
+    ``DESCRIPTOR.fields``. Left unchecked, `_supersedes_member` would
+    silently hash only ``session_id``/``commitment_hash`` and drop the
+    unknown field's contribution -- the same "not hashable under this label
+    ... never silently ignored" outcome the RFC prohibits, just nested one
+    level deeper.
+    """
+    unknown = unknown_fields.UnknownFieldSet(ref)
+    if len(unknown) > 0:
+        field_numbers = sorted({f.field_number for f in unknown})
+        raise MacpSessionError(
+            "CommitmentPayload.supersedes carries wire data for unrecognized "
+            "field number(s) outside the RFC-MACP-0013 §5 frozen two-field "
+            f"set and is not hashable under label {LABEL!r}: {field_numbers}"
+        )
+
+
+def canonical_projection(payload: core_pb2.CommitmentPayload) -> bytes:
+    """Return the JCS-canonicalized UTF-8 bytes of the Section 3 projection.
+
+    This is intermediate value ``C`` of RFC-MACP-0013 §4 step 2 -- the
+    canonicalized projection, not the full domain-separated preimage.
+
+    Raises `MacpSessionError` if the installed proto's `CommitmentPayload`
+    carries a field outside the RFC-MACP-0013 §5 frozen nine-field set (see
+    `_check_frozen_field_set`), or if this particular message instance
+    carries wire data for a field number the installed schema does not
+    recognize at all (see `_check_no_unknown_wire_fields`). When `supersedes`
+    is set, the same two checks are additionally applied one level down to
+    the nested `CommitmentRef` (see `_check_frozen_ref_field_set` and
+    `_check_no_unknown_ref_wire_fields`) -- an absent `supersedes` has no
+    `CommitmentRef` to check, so those two are skipped in that case.
+    """
+    _check_frozen_field_set()
+    _check_no_unknown_wire_fields(payload)
+    if payload.HasField("supersedes"):
+        _check_frozen_ref_field_set()
+        _check_no_unknown_ref_wire_fields(payload.supersedes)
+    members: list[tuple[str, str]] = [
+        ("action", _escape_json_string(payload.action)),
+        ("authority_scope", _escape_json_string(payload.authority_scope)),
+        ("commitment_id", _escape_json_string(payload.commitment_id)),
+        ("configuration_version", _escape_json_string(payload.configuration_version)),
+        ("mode_version", _escape_json_string(payload.mode_version)),
+        ("outcome_positive", _json_bool(payload.outcome_positive)),
+        ("policy_version", _escape_json_string(payload.policy_version)),
+        ("reason", _escape_json_string(payload.reason)),
+    ]
+    # Message field: omit entirely when unset (RFC-MACP-0013 §3 rule 3).
+    # HasField, not a truthiness check -- an empty CommitmentRef ({} with
+    # both sub-fields "") is falsy-looking but MUST still be projected when
+    # explicitly set, distinct from `supersedes` being absent altogether.
+    if payload.HasField("supersedes"):
+        members.append(("supersedes", _supersedes_member(payload.supersedes)))
+        # Top-level members are already in lexicographic key order except for
+        # "supersedes", which we appended last; re-sort to be explicit and
+        # robust regardless of append order above.
+        members.sort(key=lambda kv: kv[0])
+
+    body = ",".join(f"{_escape_json_string(k)}:{v}" for k, v in members)
+    text = "{" + body + "}"
+    return text.encode("utf-8")
+
+
+def commitment_hash(payload: core_pb2.CommitmentPayload) -> str:
+    """Compute the canonical commitment hash of ``payload`` (RFC-MACP-0013 §4).
+
+    Accepts any ``CommitmentPayload``, including one that is not
+    well-formed under RFC-MACP-0001 §7.3.1 (e.g. all-empty fields, or a
+    ``supersedes`` with empty sub-fields) -- hashing is a pure function of
+    the projected field values and MUST NOT be gated on validity
+    (RFC-MACP-0013 §6, "hashability"). Do not add a validation call here.
+    """
+    # No guard against an older macp-proto lacking `outcome_positive` /
+    # `supersedes`: the repo's pin is macp-proto>=0.1.6 and both fields have
+    # existed since well before that, so the fields are always present on
+    # the installed descriptor. Accessing a genuinely absent field would
+    # raise AttributeError from the generated proto class itself rather
+    # than silently under-projecting, so no additional guard is needed here.
+    preimage = LABEL.encode("ascii") + b":" + canonical_projection(payload)
+    digest = hashlib.sha256(preimage).hexdigest()
+    return f"sha256:{digest}"
+
+
+def is_canonical_commitment_hash(value: str) -> bool:
+    """Syntax predicate: ``^sha256:[0-9a-f]{64}$`` exactly (full match), no I/O.
+
+    Uses `re.fullmatch` rather than `match` + a trailing-``$`` pattern: `$`
+    alone matches immediately before a trailing ``\\n``, which would wrongly
+    accept ``"sha256:" + "a" * 64 + "\\n"``. `fullmatch` anchors both ends
+    with no such quirk, so no separate `strip()` check is needed.
+    """
+    return bool(_HASH_RE.fullmatch(value))

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk/envelope.py

@@ -14,6 +14,7 @@ from .constants import (
     MACP_VERSION,
 )
 from .errors import MacpSessionError
+from .validation import validate_commitment_hash
 
 # ── Outcome inference ────────────────────────────────────────────────
 
@@ -110,7 +111,14 @@ def _has_supersedes_field() -> bool:
 
 def build_commitment_ref(*, session_id: str, commitment_hash: str) -> core_pb2.CommitmentRef:
     """Build a ``CommitmentRef`` (macp-proto 0.1.3) pointing at a prior
-    commitment, for use as ``build_commitment_payload(supersedes=...)``."""
+    commitment, for use as ``build_commitment_payload(supersedes=...)``.
+
+    ``commitment_hash`` must be a canonical RFC-MACP-0013 commitment hash
+    (``sha256:`` followed by 64 lowercase hex digits) — see
+    ``commitment_hash()`` in ``macp_sdk.commitment_hash`` for computing one
+    from a ``CommitmentPayload``. Raises ``MacpSessionError`` otherwise.
+    """
+    validate_commitment_hash(commitment_hash)
     return core_pb2.CommitmentRef(session_id=session_id, commitment_hash=commitment_hash)
 
 
@@ -131,7 +139,10 @@ def build_commitment_payload(
     ``supersedes`` (macp-proto 0.1.3) optionally references a prior
     commitment this one revises, as a ``CommitmentRef`` of
     ``(session_id, commitment_hash)``. It is absent by default and unrelated
-    to proposal-mode ``supersedes_proposal_id``.
+    to proposal-mode ``supersedes_proposal_id``. ``supersedes.commitment_hash``
+    must be a canonical RFC-MACP-0013 hash (validated here even when the
+    ``CommitmentRef`` was constructed directly rather than via
+    ``build_commitment_ref``); raises ``MacpSessionError`` otherwise.
     """
     if outcome_positive is None:
         outcome_positive = infer_outcome_positive(action)
@@ -149,6 +160,7 @@ def build_commitment_payload(
     if supersedes is not None:
         if not _has_supersedes_field():
             raise MacpSessionError("CommitmentPayload.supersedes requires macp-proto >= 0.1.3")
+        validate_commitment_hash(supersedes.commitment_hash)
         kwargs["supersedes"] = supersedes
     return core_pb2.CommitmentPayload(**kwargs)
 

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk/projections.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from macp.modes.decision.v1 import decision_pb2
 from macp.v1 import envelope_pb2
 
-from .base_projection import BaseProjection
+from .base_projection import ANOMALY_DUPLICATE_VOTE, BaseProjection
 from .constants import MODE_DECISION
 
 
@@ -100,6 +100,24 @@ class DecisionProjection(BaseProjection):
         if message_type == "Vote":
             payload = decision_pb2.VotePayload()
             payload.ParseFromString(envelope.payload)
+            existing = self.votes.get(payload.proposal_id, {}).get(envelope.sender)
+            if existing is not None:
+                # First-wins (RFC-MACP-0007 §5.3: "the first accepted Vote
+                # stands"). A second, distinct Vote (its own message_id --
+                # redelivery of the same envelope never reaches here, see
+                # apply_envelope's dedup gate) from a sender who already
+                # voted on this proposal is discarded without mutating
+                # votes or phase. detail states facts only, no cause
+                # attribution.
+                self._record_anomaly(
+                    kind=ANOMALY_DUPLICATE_VOTE,
+                    message_type=envelope.message_type,
+                    message_id=envelope.message_id,
+                    sender=envelope.sender,
+                    subject_id=payload.proposal_id,
+                    detail=(f"kept first vote {existing.vote!r}; discarded {payload.vote!r}"),
+                )
+                return
             self.votes.setdefault(payload.proposal_id, {})[envelope.sender] = DecisionVoteRecord(
                 proposal_id=payload.proposal_id,
                 vote=payload.vote,

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk/quorum.py

@@ -6,7 +6,7 @@ from macp.modes.quorum.v1 import quorum_pb2
 from macp.v1 import envelope_pb2
 
 from .auth import AuthConfig
-from .base_projection import BaseProjection
+from .base_projection import ANOMALY_DUPLICATE_BALLOT, BaseProjection
 from .base_session import BaseSession
 from .constants import MODE_QUORUM
 from .envelope import build_envelope, serialize_message
@@ -41,9 +41,11 @@ class BallotRecord:
 class QuorumProjection(BaseProjection):
     """In-process state tracking for Quorum mode sessions.
 
-    Supports multiple concurrent approval requests within a single session.
-    Query methods accept a ``request_id`` parameter to target a specific
-    request.
+    RFC-MACP-0011 §5 rule 1 caps a session at one ``ApprovalRequest`` in
+    base v1. The ``requests`` / ``ballots`` maps are keyed by ``request_id``
+    because that is the identifier the protocol uses, not because multiple
+    concurrent requests are supported. Query methods accept a ``request_id``
+    parameter to target that single request.
     """
 
     MODE = MODE_QUORUM
@@ -73,22 +75,44 @@ class QuorumProjection(BaseProjection):
         if mt == "Approve":
             p = quorum_pb2.ApprovePayload()
             p.ParseFromString(envelope.payload)
-            self._set_ballot(p.request_id, envelope.sender, "approve", p.reason)
+            self._set_ballot(envelope, p.request_id, "approve", p.reason)
             return
 
         if mt == "Reject":
             p = quorum_pb2.RejectPayload()
             p.ParseFromString(envelope.payload)
-            self._set_ballot(p.request_id, envelope.sender, "reject", p.reason)
+            self._set_ballot(envelope, p.request_id, "reject", p.reason)
             return
 
         if mt == "Abstain":
             p = quorum_pb2.AbstainPayload()
             p.ParseFromString(envelope.payload)
-            self._set_ballot(p.request_id, envelope.sender, "abstain", p.reason)
-
-    def _set_ballot(self, request_id: str, sender: str, vote: str, reason: str) -> None:
+            self._set_ballot(envelope, p.request_id, "abstain", p.reason)
+
+    def _set_ballot(
+        self, envelope: envelope_pb2.Envelope, request_id: str, vote: str, reason: str
+    ) -> None:
+        # Single funnel for Approve/Reject/Abstain -- this is exactly what
+        # enforces RFC-MACP-0011 §5 rule 3's *across-type* cardinality rule
+        # ("at most one ballot across Approve, Reject, or Abstain"). First
+        # ballot per sender stands; which-of-two-stands is inferred from
+        # RFC-MACP-0007 §5.3 parity plus what the only runtime enforces
+        # (quorum.rs:164/184/204) -- RFC-0011 itself is silent on that.
+        sender = envelope.sender
         sender_map = self.ballots.setdefault(request_id, {})
+        existing = sender_map.get(sender)
+        if existing is not None:
+            # detail states facts only, no cause attribution. message_type
+            # here is the DISCARDED message's type, not the first ballot's.
+            self._record_anomaly(
+                kind=ANOMALY_DUPLICATE_BALLOT,
+                message_type=envelope.message_type,
+                message_id=envelope.message_id,
+                sender=sender,
+                subject_id=request_id,
+                detail=f"kept first ballot {existing.vote!r}; discarded {vote!r}",
+            )
+            return
         sender_map[sender] = BallotRecord(
             request_id=request_id,
             vote=vote,

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk/validation.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import re
 from collections.abc import Sequence
 
+from .commitment_hash import is_canonical_commitment_hash
 from .errors import MacpSessionError
 
 # A string with the structural shape of a UUID (36 chars, hyphens at
@@ -57,6 +58,22 @@ def validate_session_id(sid: str) -> None:
     )
 
 
+def validate_commitment_hash(value: str) -> None:
+    """Validate that *value* has the shape of a canonical commitment hash.
+
+    Mirrors the runtime's RFC-MACP-0013 syntax check: a valid
+    ``commitment_hash`` MUST match ``^sha256:[0-9a-f]{64}$`` exactly (see
+    `macp_sdk.commitment_hash.is_canonical_commitment_hash`). This is a pure
+    shape check — it does not (and cannot) verify that the digest was
+    actually produced by `macp_sdk.commitment_hash.commitment_hash` over the
+    referenced payload; that requires the payload itself.
+    """
+    if not is_canonical_commitment_hash(value):
+        raise MacpSessionError(
+            f"commitment_hash must match ^sha256:[0-9a-f]{{64}}$ (RFC-MACP-0013), got: {value!r}"
+        )
+
+
 def validate_vote(value: str) -> str:
     """Normalize *value* to uppercase and validate as APPROVE/REJECT/ABSTAIN."""
     normalized = value.upper()

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0/src/macp_sdk_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.6.0
+Version: 0.8.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0
@@ -22,7 +22,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: grpcio>=1.82.0rc2
 Requires-Dist: protobuf>=7.35.0
-Requires-Dist: macp-proto<0.1.9,>=0.1.6
+Requires-Dist: macp-proto<0.1.10,>=0.1.6
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -30,6 +30,7 @@ Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: grpc-stubs>=1.53; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
 Requires-Dist: jsonschema>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
@@ -127,7 +128,7 @@ if winner and not session.decision_projection.has_blocking_objection(winner):
 make setup              # pip install -e ".[dev,docs]"
 
 # Quality
-make lint               # ruff check
+make lint               # ruff check + ruff format --check
 make fmt                # ruff format
 make typecheck          # mypy strict
 make test               # unit tests + coverage gate (85% branch, from pyproject)
@@ -136,7 +137,7 @@ make test-all           # lint + typecheck + all tests
 make coverage           # HTML + terminal coverage report
 
 # Build
-make build              # sdist + wheel
+make build              # build sdist + wheel, then twine check
 
 # Proto definitions (provided by macp-proto package)
 make dev-link-protos    # link local proto package for development

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk_python.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/macp_sdk/auth.py
 src/macp_sdk/base_projection.py
 src/macp_sdk/base_session.py
 src/macp_sdk/client.py
+src/macp_sdk/commitment_hash.py
 src/macp_sdk/constants.py
 src/macp_sdk/decision.py
 src/macp_sdk/envelope.py

{macp_sdk_python-0.6.0 → macp_sdk_python-0.8.0}/src/macp_sdk_python.egg-info/requires.txt

@@ -1,6 +1,6 @@
 grpcio>=1.82.0rc2
 protobuf>=7.35.0
-macp-proto<0.1.9,>=0.1.6
+macp-proto<0.1.10,>=0.1.6
 
 [dev]
 pytest>=8.0
@@ -9,6 +9,7 @@ mypy>=1.10
 ruff>=0.5
 grpc-stubs>=1.53
 build>=1.0
+twine>=5.0
 jsonschema>=4.0
 
 [docs]

macp_sdk_python-0.6.0/src/macp_sdk/base_projection.py

@@ -1,52 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import ClassVar
-
-from macp.v1 import core_pb2, envelope_pb2
-
-
-class BaseProjection(ABC):
-    """Abstract base for in-process mode state tracking.
-
-    Maintains a local transcript and delegates mode-specific message handling
-    to subclasses.  Needed because the runtime's ``GetSession`` RPC returns
-    metadata only, not mode state or transcript.
-    """
-
-    MODE: ClassVar[str]
-
-    def __init__(self) -> None:
-        self.transcript: list[envelope_pb2.Envelope] = []
-        self.phase: str = ""
-        self.commitment: core_pb2.CommitmentPayload | None = None
-
-    @property
-    def is_committed(self) -> bool:
-        return self.commitment is not None
-
-    @property
-    def is_positive_outcome(self) -> bool | None:
-        """Return the outcome polarity, or ``None`` if not yet committed."""
-        if self.commitment is None:
-            return None
-        return getattr(self.commitment, "outcome_positive", True)
-
-    def apply_envelope(self, envelope: envelope_pb2.Envelope) -> None:
-        """Process an accepted envelope and update local state."""
-        if envelope.mode != self.MODE:
-            return
-        self.transcript.append(envelope)
-
-        if envelope.message_type == "Commitment":
-            payload = core_pb2.CommitmentPayload()
-            payload.ParseFromString(envelope.payload)
-            self.commitment = payload
-            self.phase = "Committed"
-            return
-
-        self._apply_mode_message(envelope)
-
-    @abstractmethod
-    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
-        """Handle a mode-specific (non-Commitment) envelope."""