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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.8.0
+Version: 0.9.1
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macp-sdk-python"
-version = "0.8.0"
+version = "0.9.1"
 description = "Python SDK for the MACP Rust runtime"
 readme = "README.md"
 requires-python = ">=3.11"

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

@@ -95,6 +95,7 @@ from .validation import (
     validate_confidence,
     validate_participant_count,
     validate_participants,
+    validate_progress_scope,
     validate_recommendation,
     validate_required_field,
     validate_session_id,
@@ -218,6 +219,7 @@ __all__ = [
     "validate_confidence",
     "validate_participant_count",
     "validate_participants",
+    "validate_progress_scope",
     "validate_recommendation",
     "validate_required_field",
     "validate_session_id",

{macp_sdk_python-0.8.0 → macp_sdk_python-0.9.1}/src/macp_sdk/base_projection.py

@@ -207,7 +207,7 @@ class BaseProjection(ABC):
         #
         # 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
+        # task.py:102, handoff.py:70) 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
@@ -219,7 +219,7 @@ class BaseProjection(ABC):
         # 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
+        # third-party subclassing (see __init__.py:151), and upcoming
         # first-wins/anomaly-tracking logic must keep fallible work ahead
         # of mutations to keep this guarantee honest.
         #
@@ -242,7 +242,7 @@ class BaseProjection(ABC):
             # 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
+            # __init__.py:151) 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
@@ -267,7 +267,45 @@ class BaseProjection(ABC):
 
     @abstractmethod
     def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
-        """Handle a mode-specific (non-Commitment) envelope."""
+        """Handle a mode-specific (non-Commitment) envelope.
+
+        **Implementations MUST do all fallible work before any mutation**
+        ("raise-before-mutate"). Parse the payload (``ParseFromString``, the
+        one operation that realistically raises here), validate it, and
+        decide what to do — *then* assign ``self.phase`` or touch any
+        subclass collection. Never mutate and then run something that can
+        raise.
+
+        This is a real contract, not style advice, and it is what makes
+        ``apply_envelope``'s rollback sufficient. That rollback restores
+        ``transcript`` and the ``message_id`` dedup set only — it cannot
+        restore subclass state, because the base class has no way to know
+        what a subclass mutated (a slotted subclass has no ``__dict__`` to
+        snapshot, and deep-copying every projection per envelope would be a
+        real per-message cost). An implementation that mutates and then
+        raises therefore leaves *its own* state half-applied while
+        ``apply_envelope`` reports a clean rollback and invites the caller
+        to retry — a partial apply the base class cannot detect or undo.
+
+        Every implementation in this SDK honors this today (see the
+        per-branch parse-then-mutate ordering in ``projections.py``,
+        ``quorum.py``, ``task.py``, ``handoff.py``, and ``proposal.py``).
+        Two branches come close to the line: ``handoff.py``'s
+        ``HandoffAccept`` writes the record before reading
+        ``getattr(p, "implicit", False)``, and ``proposal.py``'s ``Reject``
+        appends before reading ``p.terminal`` and ``self.proposals.get(...)``.
+        Both are safe only because a defaulted ``getattr``, a protobuf field
+        read, and ``dict.get`` cannot raise — not because the ordering there
+        is exemplary.
+
+        ``tests/unit/test_projection_rollback_invariant.py`` pins the
+        ordering by feeding each branch a payload that cannot parse and
+        asserting no derived state moved. Note what that does *not* reach: a
+        branch that mutates and then does something else fallible (a raising
+        property, an ``int()``, a strict lookup) is not caught, because a
+        malformed payload never gets that far. The contract is broader than
+        the test — hence stating it here.
+        """
 
     def _record_anomaly(
         self,

{macp_sdk_python-0.8.0 → macp_sdk_python-0.9.1}/src/macp_sdk/client.py

@@ -24,6 +24,7 @@ from .errors import (
     MacpSessionError,
     MacpTransportError,
 )
+from .validation import validate_progress_scope
 
 # Public typing alias for inline stream-error callbacks. Parity with
 # typescript-sdk's ``InlineErrorCallback``. Receives the protobuf
@@ -962,10 +963,18 @@ class MacpClient:
     ) -> envelope_pb2.Ack:
         """Send a progress update.
 
-        When ``session_id`` and ``mode`` are empty, the progress is treated
-        as an *ambient* progress message routed through the signal broadcast
-        path.
+        Per RFC-MACP-0001 §6, ``Progress`` is legal in exactly two shapes:
+
+        * *ambient* -- ``session_id`` and ``mode`` both empty, routed through
+          the signal broadcast path; or
+        * *session-scoped* -- both non-empty.
+
+        Supplying exactly one of the two raises ``MacpSessionError`` naming
+        the mismatched field. The runtime rejects that mixed envelope with
+        ``INVALID_ENVELOPE``, so this only surfaces the failure earlier and
+        more clearly.
         """
+        validate_progress_scope(session_id, mode)
         auth_cfg = self._require_auth(auth)
         payload = build_progress_payload(
             progress_token=progress_token,

{macp_sdk_python-0.8.0 → macp_sdk_python-0.9.1}/src/macp_sdk/policy.py

@@ -155,7 +155,8 @@ class QuorumThreshold:
     ``quorum-rules.schema.json``: an approval count for ``n_of_m`` /
     ``weighted``, and an integer percentage 0-100 for ``percentage``. A
     fractional value (e.g. ``0.75``) is rejected by the runtime's schema
-    validation, so this is typed ``int`` and range-checked at build time.
+    validation, so this is typed ``int`` and ``build_quorum_policy`` rejects
+    a non-integer or out-of-range value at build time.
     """
 
     type: str = "n_of_m"
@@ -185,7 +186,21 @@ def build_quorum_policy(
 
     # Match the canonical schema's constraints before the runtime does, so a
     # bad descriptor fails immediately client-side instead of round-tripping
-    # to an INVALID_POLICY_DEFINITION from RegisterPolicy.
+    # to an INVALID_POLICY_DEFINITION from RegisterPolicy. Order matters:
+    # type first (a float or bool reaching the range checks below would
+    # compare fine numerically but produce a confusing message), then >= 0,
+    # then the percentage-specific <= 100 cap.
+    #
+    # bool is checked explicitly because isinstance(True, int) is True in
+    # Python -- QuorumThreshold(value=True) must not silently mean 1.
+    if isinstance(t.value, bool) or not isinstance(t.value, int):
+        raise MacpSessionError(
+            "quorum threshold value must be an integer (e.g. 75 for 75%), got "
+            f"{t.value!r}. The canonical quorum-rules schema declares "
+            "'value' as an integer for every threshold type; a fractional "
+            "value like 0.75 would produce a schema-invalid descriptor that "
+            "the runtime rejects at RegisterPolicy with worse diagnostics."
+        )
     if t.value < 0:
         raise MacpSessionError(f"quorum threshold value must be >= 0, got {t.value}")
     if t.type == "percentage" and t.value > 100:

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

@@ -122,6 +122,42 @@ def validate_signal_type(signal_type: str, data: bytes | None = None) -> None:
         raise MacpSessionError("signal_type must be non-empty when data is present")
 
 
+def validate_progress_scope(session_id: str, mode: str) -> None:
+    """Validate the ``Progress`` scope pairing (RFC-MACP-0001 §6).
+
+    ``Progress`` is legal in exactly two shapes -- *ambient* (``session_id``
+    and ``mode`` both empty) or *session-scoped* (both non-empty). An envelope
+    with exactly one of the two empty is a mixed shape that the runtime
+    rejects with ``INVALID_ENVELOPE``; raising here names the mismatched field
+    instead.
+
+    Unlike Signals, ``Progress`` is *not* required to be ambient -- this is a
+    tri-state rule, so neither field may be inferred from the other.
+
+    The emptiness test deliberately mirrors the runtime's
+    ``validate_envelope_shape`` **exactly**, including its asymmetry:
+    ``session_id`` is compared raw while ``mode`` is stripped first. Mirroring
+    rather than normalising is the only choice under which the SDK neither
+    accepts a shape the runtime rejects nor rejects one it accepts.
+    Concretely, a whitespace-only ``mode`` alongside an empty ``session_id``
+    is ambient to the runtime, so it stays ambient here.
+    """
+    session_id_empty = session_id == ""
+    mode_empty = mode.strip() == ""
+    if session_id_empty == mode_empty:
+        return
+    detail = (
+        f"mode is {mode!r} but session_id is empty"
+        if session_id_empty
+        else f"session_id is {session_id!r} but mode is empty"
+    )
+    raise MacpSessionError(
+        "Progress must be either ambient (session_id and mode both empty) or "
+        f"session-scoped (both non-empty), but {detail} (RFC-MACP-0001 §6). "
+        "Pass both fields for a session-scoped Progress, or neither for an ambient one."
+    )
+
+
 def validate_ttl_ms(ttl_ms: int) -> None:
     """Validate that *ttl_ms* is in [1, 86_400_000]."""
     if ttl_ms < 1 or ttl_ms > _MAX_TTL_MS:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.8.0
+Version: 0.9.1
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0