macp-sdk-python 0.12.1__tar.gz → 0.14.0__tar.gz

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.12.1
+Version: 0.14.0
 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.12.1 → macp_sdk_python-0.14.0}/pyproject.toml

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

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/__init__.py

@@ -120,6 +120,7 @@ from .task import (
 from .validation import (
     validate_commitment_hash,
     validate_confidence,
+    validate_max_suspend_ms,
     validate_participant_count,
     validate_participants,
     validate_progress_scope,
@@ -133,6 +134,7 @@ from .validation import (
     validate_vote,
 )
 from .watchers import (
+    TERMINAL_SESSION_LIFECYCLE_EVENT_NAMES,
     ModeRegistryWatcher,
     PolicyChange,
     PolicyWatcher,
@@ -173,6 +175,7 @@ __all__ = [
     "SESSION_NOT_FOUND",
     "SESSION_NOT_OPEN",
     "STANDARD_MODES",
+    "TERMINAL_SESSION_LIFECYCLE_EVENT_NAMES",
     "UNAUTHENTICATED",
     "UNBOUNDED",
     "UNKNOWN_POLICY_VERSION",
@@ -263,6 +266,7 @@ __all__ = [
     "serialize_message",
     "validate_commitment_hash",
     "validate_confidence",
+    "validate_max_suspend_ms",
     "validate_participant_count",
     "validate_participants",
     "validate_progress_scope",

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/agent/participant.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import threading
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -418,9 +419,22 @@ class Participant:
             mode=mode,
             participant_id=participant_id,
         )
-        self._last_phase: str | None = None
+        # Seed from the projection's own initial phase: that phase is a
+        # constructor artifact, not an observed transition, so firing
+        # on_phase_change for it would report a change that never happened.
+        # This matters most for a mid-session joiner, whose first envelope
+        # otherwise re-announces a phase the session entered before it
+        # attached. None when no projection is registered for the mode -- the
+        # phase path is skipped entirely in that case.
+        self._last_phase: str | None = (
+            self._projection.phase if self._projection is not None else None
+        )
         self._transport = transport
         self._cancel_callback_server: Any | None = None
+        # Non-reentrant by design: an RLock would let a handler calling
+        # run() recursively (same thread) through, only to deadlock on the
+        # transport instead of raising a clear error.
+        self._run_lock = threading.Lock()
 
     @property
     def participant_id(self) -> str:
@@ -484,6 +498,9 @@ class Participant:
         point. As a fallback (for envelopes projections don't model — e.g.
         ``SessionCancel``), we fire terminal on the message type itself so
         clients always get a ``stop`` signal for end-of-session envelopes.
+        The fallback only fires when the projection has not already
+        reported a terminal phase, so a ``SessionCancel`` arriving after a
+        ``Commitment`` cannot produce a second ``on_terminal``.
         """
         if self._projection is not None:
             self._projection.apply_envelope(envelope)
@@ -496,6 +513,9 @@ class Participant:
         self._dispatcher.dispatch(message, ctx)
 
         fired_terminal = False
+        already_terminal = (
+            self._projection is not None and self._projection.phase in TERMINAL_PHASES
+        )
 
         # Phase transition path — drives both on_phase_change and on_terminal.
         if self._projection is not None:
@@ -521,7 +541,7 @@ class Participant:
         # Fallback for envelopes projections don't transition phase on —
         # principally ``SessionCancel``. Keeps terminal dispatch reliable
         # while the phase-driven path remains primary.
-        if not fired_terminal and envelope.message_type == "SessionCancel":
+        if not fired_terminal and not already_terminal and envelope.message_type == "SessionCancel":
             self._dispatcher.dispatch_terminal(TerminalResult(state="Cancelled"))
             self._stopped = True
 
@@ -566,8 +586,39 @@ class Participant:
         emits SessionStart + kickoff before opening the stream.
 
         Dispatches received events to registered handlers until the session
-        reaches a terminal state or ``stop()`` is called.
+        reaches a terminal state or ``stop()`` is called. The loop exits
+        after the current envelope finishes dispatching, not after the
+        next one arrives.
+
+        Teardown contract: a ``run()`` that ends with the participant
+        stopped also releases the cancel-callback listener (if one was
+        attached); a ``run()`` that ends with the participant still
+        runnable leaves it bound so a subsequent ``run()`` keeps its
+        cancel endpoint.
+
+        Not re-entrant: a *concurrent* call (from another thread, while
+        this one is still inside the loop) raises :class:`MacpSessionError`
+        instead of silently starting a second transport and interleaving
+        dispatches into shared state. This is a deliberate divergence from
+        ``macp-sdk-typescript``, whose ``run()`` returns silently in the
+        same situation -- a no-op is tolerable there because its single
+        event loop makes a second call almost always a same-task
+        programmer mistake, whereas a second Python thread believing it is
+        running an agent that is in fact doing nothing is a silent
+        liveness bug. A *sequential* call, made after a prior ``run()`` has
+        returned, is unaffected and behaves exactly as before.
         """
+        if not self._run_lock.acquire(blocking=False):
+            raise MacpSessionError(
+                f"Participant.run() is already executing for session {self._session_id!r}; "
+                "run() is not re-entrant"
+            )
+        try:
+            self._run()
+        finally:
+            self._run_lock.release()
+
+    def _run(self) -> None:
         logger.info(
             "participant %s joining session %s (mode=%s, initiator=%s)",
             self._participant_id,
@@ -600,8 +651,27 @@ class Participant:
                     self._process_envelope(message.raw)
                 else:
                     self._process_message(message)
+                if self._stopped:
+                    # A handler (or another thread) called stop() while this
+                    # envelope was being dispatched -- including the terminal
+                    # dispatch in _process_envelope, which sets _stopped itself.
+                    # Without this check the loop blocks on transport.start()'s
+                    # next yield, which on a quiet session may never come.
+                    break
         finally:
-            transport.stop()
+            try:
+                transport.stop()
+            except Exception:
+                logger.debug("transport stop failed during run() teardown", exc_info=True)
+            if self._stopped:
+                # Release the cancel-callback listener only when this
+                # participant has actually stopped -- which is also exactly
+                # when a further run() would be a no-op (the one-shot early
+                # return above reads the same flag). So the server is still
+                # bound on every exit from which a sequential run() can still
+                # do something, and is released on every exit after which it
+                # cannot.
+                self._close_cancel_callback_server()
 
     def _emit_initiator_envelopes(self) -> None:
         """Emit SessionStart + kickoff envelope as the initiator."""
@@ -658,6 +728,21 @@ class Participant:
         """Manually process a single envelope (for testing or polling transports)."""
         self._process_envelope(envelope)
 
+    def _close_cancel_callback_server(self) -> None:
+        """Close the bound cancel-callback HTTP server, if one was attached.
+
+        Idempotent and exception-safe: called from both :meth:`stop` and
+        ``run()``'s exit path (the latter only when this participant has
+        actually stopped), either of which may run first, or both.
+        """
+        server = self._cancel_callback_server
+        if server is not None:
+            self._cancel_callback_server = None
+            try:
+                server.close()
+            except Exception:
+                logger.exception("cancel_callback server close failed")
+
     def stop(self) -> None:
         """Signal the event loop to stop.
 
@@ -680,19 +765,17 @@ class Participant:
             cancel = getattr(transport, "cancel", None)
             if callable(cancel):
                 cancel()
-        server = self._cancel_callback_server
-        if server is not None:
-            self._cancel_callback_server = None
-            try:
-                server.close()
-            except Exception:
-                logger.exception("cancel_callback server close failed")
+        self._close_cancel_callback_server()
 
     def attach_cancel_callback_server(self, server: Any) -> None:
         """Attach a :class:`CancelCallbackServer` to this participant.
 
-        The server's lifetime is then tied to :meth:`stop` — the event
-        loop exit (or an incoming cancel POST that calls ``stop``) shuts
-        it down.
+        The server's lifetime is then tied to an actual stop: an
+        incoming cancel POST (or any other caller of :meth:`stop`)
+        shuts it down, and so does ``run()`` returning with the
+        participant stopped (e.g. a terminal envelope). A ``run()``
+        that returns with the participant still runnable leaves it
+        bound, so a subsequent ``run()`` keeps the same cancel
+        endpoint.
         """
         self._cancel_callback_server = server

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/agent/runner.py

@@ -6,6 +6,7 @@ import json
 import os
 from typing import Any
 
+from .._logging import logger
 from ..auth import AuthConfig
 from ..client import MacpClient
 from ..constants import DEFAULT_POLICY_VERSION
@@ -36,6 +37,23 @@ def _decode_extensions(raw: Any) -> dict[str, bytes]:
     bootstrap) defaults to ``{}``; a *present* value of the wrong type (a
     list, a string, ...) is equally malformed and raises rather than
     silently vanishing (#97 follow-up).
+
+    **Known, accepted ambiguity (issue #121):** trying base64 first means a
+    plain string that *happens* to also be syntactically valid base64 (e.g.
+    ``"abcd"`` or ``"pack"`` -- any string whose length is a multiple of 4
+    over the base64 alphabet) silently decodes as base64 bytes instead of
+    being treated as the literal string a bootstrap author intended. There
+    is no way to tell the two apart from the string alone, and this SDK is
+    the canonical source ``macp-sdk-typescript`` mirrors for interop, so
+    changing the heuristic would need a coordinated, versioned decision
+    across both SDKs (and likely a wire-shape change), not a local fix.
+    Decided: keep the heuristic as-is rather than add a disambiguation
+    mechanism -- it is a diagnosability/correctness-on-the-margins wart, not
+    a live bug, and the ``logger.debug`` call below at least makes a
+    base64-decode *failure* observable. A value that round-trips through
+    *both* interpretations without the caller noticing is the accepted
+    cost; callers who need an unambiguous literal string should route it
+    through a different field instead of ``extensions``.
     """
     if raw is None:
         return {}
@@ -51,6 +69,10 @@ def _decode_extensions(raw: Any) -> dict[str, bytes]:
             try:
                 decoded[str(key)] = base64.b64decode(value, validate=True)
             except (binascii.Error, ValueError):
+                logger.debug(
+                    "bootstrap extensions[%r] is not valid base64; using its raw UTF-8 bytes",
+                    key,
+                )
                 decoded[str(key)] = value.encode("utf-8")
         else:
             raise ValueError(

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/agent/strategies.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from typing import Any, Protocol
 
 from ..envelope import infer_outcome_positive
+from ..validation import validate_confidence, validate_recommendation
 from .types import HandlerContext, IncomingMessage, MessageHandler, SessionInfo
 
 # ── Evaluation ───────────────────────────────────────────────────────
@@ -26,9 +27,6 @@ class EvaluationStrategy(Protocol):
     def evaluate(self, proposal: dict[str, Any], context: SessionInfo) -> EvaluationResult: ...
 
 
-_VALID_RECOMMENDATIONS = frozenset({"APPROVE", "REVIEW", "BLOCK", "REJECT"})
-
-
 def evaluation_handler(strategy: EvaluationStrategy) -> MessageHandler:
     """Create a MessageHandler that evaluates proposals using the given strategy.
 
@@ -41,14 +39,8 @@ def evaluation_handler(strategy: EvaluationStrategy) -> MessageHandler:
         if message.message_type != "Proposal":
             return
         result = strategy.evaluate(message.payload, ctx.session)
-        recommendation = result.recommendation.upper()
-        if recommendation not in _VALID_RECOMMENDATIONS:
-            raise ValueError(
-                f"invalid recommendation {result.recommendation!r}: "
-                "must be one of APPROVE, REVIEW, BLOCK, REJECT"
-            )
-        if not (0.0 <= result.confidence <= 1.0):
-            raise ValueError(f"confidence must be in [0.0, 1.0], got {result.confidence}")
+        recommendation = validate_recommendation(result.recommendation)
+        validate_confidence(result.confidence)
         ctx.log(
             "evaluation: recommendation=%s confidence=%.2f reason=%s",
             recommendation,
@@ -254,7 +246,9 @@ def majority_voter(
     """Built-in voting strategy that votes ``APPROVE`` once the fraction of
     qualifying (non-``REVIEW``) evaluations recommending ``APPROVE``, for the
     most recently evaluated proposal, meets ``positive_threshold`` --
-    otherwise ``ABSTAIN``.
+    otherwise ``ABSTAIN``. ``should_vote`` applies the same qualifying/latest-
+    proposal rule: it returns ``True`` only when there is at least one
+    qualifying evaluation for ``decide_vote`` to actually decide from.
 
     Both ``should_vote`` and ``decide_vote`` read only from
     ``projection.evaluations``, never from votes already cast (issue #93 item
@@ -279,13 +273,29 @@ def majority_voter(
         def should_vote(self, projection: Any) -> bool:
             if projection is None:
                 return False
-            # Gate on Evaluations, not on votes already cast -- voting_handler
-            # already only calls should_vote() on an incoming Evaluation
-            # message, so this mirrors typescript-sdk's
-            # majorityVoter.shouldVote (strategies.ts:88:
-            # `projection.evaluations.length > 0`).
-            evaluations = getattr(projection, "evaluations", None)
-            return bool(evaluations)
+            evaluations = list(getattr(projection, "evaluations", None) or [])
+            if not evaluations:
+                return False
+            # Agree with decide_vote(): it votes on the most recently evaluated
+            # proposal and counts only qualifying (non-REVIEW) evaluations for
+            # that proposal, so should_vote() must ask the same question.
+            # RFC-MACP-0007 §4 (rfcs/RFC-MACP-0007-decision-mode.md:73): REVIEW
+            # evaluations "do not block or approve a proposal; they serve as
+            # informational analysis records only" -- a set of only REVIEWs has
+            # nothing decisive to vote on.
+            #
+            # Cross-SDK note: macp-sdk-typescript's majorityVoter
+            # (src/agent/strategies.ts:90-98) applies the same REVIEW filter but
+            # does NOT scope to a proposal -- its decideVote counts every
+            # decisive evaluation in the session. Python scopes both methods to
+            # the latest proposal, which is the stricter and more correct
+            # behaviour for a multi-proposal session (the vote is cast for one
+            # proposal_id). The difference is deliberate; see plan issue #121.
+            proposal_id = evaluations[-1].proposal_id
+            return any(
+                e.proposal_id == proposal_id and e.recommendation.upper() != "REVIEW"
+                for e in evaluations
+            )
 
         def decide_vote(self, projection: Any) -> VoteResult:
             evaluations = list(getattr(projection, "evaluations", None) or [])
@@ -334,7 +344,11 @@ def majority_committer(
     and the quorum has been met.
 
     Args:
-        quorum_size: Minimum number of votes before commitment (default ``1``).
+        quorum_size: Minimum number of positive votes for the winning proposal
+            required before committing (default ``1``). Counted from
+            ``vote_totals().get(winner, 0)``, not from the session's total
+            vote count, so votes cast for proposals that lost no longer help
+            clear the bar.
         action: The commitment action string (default ``"commit"``).
         authority_scope: The commitment authority scope (default ``"session"``).
     """
@@ -350,11 +364,20 @@ def majority_committer(
         def should_commit(self, projection: Any) -> bool:
             if projection is None:
                 return False
-            totals = projection.vote_totals()
-            total_votes = sum(totals.values())
-            if total_votes < self._quorum:
+            winner = projection.majority_winner()
+            if winner is None:
                 return False
-            return projection.majority_winner() is not None
+            # quorum_size is the bar for the WINNING proposal, not for the
+            # session's total vote count: vote_totals() is keyed by
+            # proposal_id (projections.py:167-181), so summing its values
+            # across proposals let the bar be cleared by votes cast for
+            # proposals that lost. Worked example, measured against a real
+            # DecisionProjection: p1=2 APPROVE, p2=1 APPROVE, quorum_size=3
+            # -> the old sum is 2+1=3 >= 3 and majority_winner() is "p1", so
+            # it committed a proposal holding 2 of the 3 votes the caller
+            # asked for. Matches macp-sdk-typescript's majorityCommitter
+            # (src/agent/strategies.ts:163-168).
+            return projection.vote_totals().get(winner, 0) >= self._quorum
 
         def decide_commitment(self, projection: Any) -> CommitmentResult:
             winner = projection.majority_winner()

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/auth.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from .errors import MacpSessionError
+
 
 @dataclass(frozen=True)
 class AuthConfig:
@@ -23,7 +25,7 @@ class AuthConfig:
 
     def __post_init__(self) -> None:
         if not self.bearer_token:
-            raise ValueError("bearer_token is required")
+            raise MacpSessionError("bearer_token is required")
 
     @classmethod
     def for_dev_agent(cls, agent_id: str, *, expected_sender: str | None = None) -> AuthConfig:

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/client.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import queue
 import threading
-from collections.abc import Callable, Iterator, Sequence
+from collections.abc import Callable, Generator, Iterator, Sequence
 from typing import Any
 
 import grpc
@@ -134,6 +134,21 @@ UNBOUNDED = _UnboundedTimeout()
 TimeoutValue = float | None | _UnboundedTimeout
 
 
+def _cancel_quietly(call: Any) -> None:
+    """Best-effort cancel of a server-streaming gRPC call.
+
+    Called from each ``watch_*`` generator's ``finally``, so it runs on
+    normal exhaustion, on an exception, and on ``GeneratorExit`` when a
+    consumer abandons the stream. Cancelling an already-finished call is
+    a no-op in grpcio; a cancel that raises must not replace whatever
+    the generator was already propagating.
+    """
+    try:
+        call.cancel()
+    except Exception:
+        logger.debug("stream cancel failed", exc_info=True)
+
+
 class MacpStream:
     _END = object()
 
@@ -674,6 +689,14 @@ class MacpClient:
     def list_roots(
         self, *, auth: AuthConfig | None = None, timeout: TimeoutValue = None
     ) -> core_pb2.ListRootsResponse:
+        """List the roots the runtime exposes.
+
+        The runtime does not populate roots yet and returns an empty list;
+        since runtime v0.5.0 it advertises this up front via
+        ``capabilities.roots.list_changed: false`` in ``Initialize``. The RPC
+        is wired and forward-compatible -- callers should treat an empty list
+        as "no roots advertised," not as an error.
+        """
         return self.stub.ListRoots(
             core_pb2.ListRootsRequest(),
             metadata=self._metadata(auth),
@@ -738,7 +761,7 @@ class MacpClient:
         *,
         auth: AuthConfig | None = None,
         timeout: TimeoutValue = None,
-    ) -> Iterator[core_pb2.WatchSessionsResponse]:
+    ) -> Generator[core_pb2.WatchSessionsResponse, None, None]:
         """Server-streaming RPC: yields session lifecycle events.
 
         The runtime emits an initial ``EVENT_TYPE_CREATED`` frame for every
@@ -760,6 +783,8 @@ class MacpClient:
             yield from call
         except grpc.RpcError as exc:
             raise self._transport_error_from_rpc(exc) from exc
+        finally:
+            _cancel_quietly(call)
 
     def register_ext_mode(
         self,
@@ -938,7 +963,7 @@ class MacpClient:
 
     def watch_policies(
         self, *, auth: AuthConfig | None = None, timeout: TimeoutValue = None
-    ) -> Iterator[policy_pb2.WatchPoliciesResponse]:
+    ) -> Generator[policy_pb2.WatchPoliciesResponse, None, None]:
         """Server-streaming RPC: yields governance policy change events.
 
         Auth is forwarded when available (``auth`` arg or ``client.auth``) but
@@ -955,6 +980,8 @@ class MacpClient:
             yield from call
         except grpc.RpcError as exc:
             raise self._transport_error_from_rpc(exc) from exc
+        finally:
+            _cancel_quietly(call)
 
     def open_stream(
         self, *, auth: AuthConfig | None = None, timeout: TimeoutValue = None
@@ -968,7 +995,7 @@ class MacpClient:
 
     def watch_mode_registry(
         self, *, auth: AuthConfig | None = None, timeout: TimeoutValue = None
-    ) -> Iterator[core_pb2.WatchModeRegistryResponse]:
+    ) -> Generator[core_pb2.WatchModeRegistryResponse, None, None]:
         """Server-streaming RPC: yields mode registry change events.
 
         Auth is forwarded when available but not required.
@@ -983,10 +1010,12 @@ class MacpClient:
             yield from call
         except grpc.RpcError as exc:
             raise self._transport_error_from_rpc(exc) from exc
+        finally:
+            _cancel_quietly(call)
 
     def watch_roots(
         self, *, auth: AuthConfig | None = None, timeout: TimeoutValue = None
-    ) -> Iterator[core_pb2.WatchRootsResponse]:
+    ) -> Generator[core_pb2.WatchRootsResponse, None, None]:
         """Server-streaming RPC: yields root change events.
 
         The runtime advertises ``roots.list_changed: false`` and does not yet
@@ -1003,10 +1032,12 @@ class MacpClient:
             yield from call
         except grpc.RpcError as exc:
             raise self._transport_error_from_rpc(exc) from exc
+        finally:
+            _cancel_quietly(call)
 
     def watch_signals(
         self, *, auth: AuthConfig | None = None, timeout: TimeoutValue = None
-    ) -> Iterator[core_pb2.WatchSignalsResponse]:
+    ) -> Generator[core_pb2.WatchSignalsResponse, None, None]:
         """Server-streaming RPC: yields ambient signal envelopes.
 
         Requires authentication since runtime v0.5.0 — an unauthenticated
@@ -1025,6 +1056,8 @@ class MacpClient:
             yield from call
         except grpc.RpcError as exc:
             raise self._transport_error_from_rpc(exc) from exc
+        finally:
+            _cancel_quietly(call)
 
     def send_signal(
         self,

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/envelope.py

@@ -14,7 +14,7 @@ from .constants import (
     MACP_VERSION,
 )
 from .errors import MacpSessionError
-from .validation import validate_commitment_hash
+from .validation import validate_commitment_hash, validate_max_suspend_ms
 
 # ── Outcome inference ────────────────────────────────────────────────
 
@@ -79,10 +79,7 @@ def build_session_start_payload(
     client-side here with a clear message. proto3 does not serialize a scalar
     ``0``, so the default keeps byte-compatibility with pre-0.1.5 payloads.
     """
-    if max_suspend_ms < 0:
-        raise MacpSessionError(
-            f"max_suspend_ms must be >= 0 (0 selects the runtime default), got {max_suspend_ms}"
-        )
+    validate_max_suspend_ms(max_suspend_ms)
     kwargs: dict[str, object] = dict(
         intent=intent,
         participants=list(participants),

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/handoff.py

@@ -82,8 +82,8 @@ class HandoffProjection(BaseProjection):
                 if handoff.status == "offered":
                     handoff.status = "context_sent"
                 handoff.context_content_type = p.content_type
-            if self.phase == "OfferPending":
-                self._set_phase("ContextSharing")
+                if self.phase == "OfferPending":
+                    self._set_phase("ContextSharing")
             return
 
         if mt == "HandoffAccept":

{macp_sdk_python-0.12.1 → macp_sdk_python-0.14.0}/src/macp_sdk/projections.py

@@ -67,6 +67,31 @@ class DecisionProjection(BaseProjection):
                 rationale=payload.rationale,
                 sender=envelope.sender,
             )
+            # A Proposal opens the evaluation window: the runtime advances the
+            # session's phase when it accepts the Proposal
+            # (macp-runtime/crates/macp-modes/src/mode/decision.rs:172) and then
+            # *requires* that phase before it will accept an Evaluation or
+            # Objection at all (ensure_can_deliberate, same file :71-77, gating
+            # :187 and :212) -- so reporting "Proposal" in this window describes a
+            # state the session is demonstrably not in. macp-sdk-typescript's
+            # DecisionProjection advances here too. "Proposal" is still the initial
+            # phase set in __init__ -- it is observable before the first mode
+            # message, it just no longer survives the Proposal itself.
+            #
+            # Guarded on the phase still being the initial one, NOT unconditional:
+            # _set_phase (base_projection.py) blocks regression only out of
+            # "Committed", so an unconditional call here would let a Proposal
+            # redelivered under a distinct message_id rewind "Voting" ->
+            # "Evaluation". RFC-MACP-0007 §5 rule 6
+            # (rfcs/RFC-MACP-0007-decision-mode.md:94) says a runtime MUST reject
+            # any Proposal/Evaluation/Objection after the first accepted Vote, and
+            # a message the runtime must reject certainly must not rewind our local
+            # phase. Same shape as handoff.py:85's `if self.phase ==
+            # "OfferPending"` guard. (macp-sdk-typescript/src/projections/
+            # decision.ts:55 is unconditional and has this latent gap even though
+            # its own Vote arm guards at :124-126 -- do not copy it.)
+            if self.phase == "Proposal":
+                self._set_phase("Evaluation")
             return
 
         if message_type == "Evaluation":
@@ -100,6 +125,17 @@ class DecisionProjection(BaseProjection):
         if message_type == "Vote":
             payload = decision_pb2.VotePayload()
             payload.ParseFromString(envelope.payload)
+            if payload.proposal_id not in self.proposals:
+                # A Vote for a proposal this projection never saw is ignored
+                # entirely -- no vote record, no phase advance, and deliberately
+                # NO anomaly. Rejecting an unknown proposal_id is the runtime's
+                # obligation (it has the full session state); a projection is a
+                # local, possibly partial view, and a mid-session joiner whose
+                # replay window starts after the Proposal legitimately never saw
+                # it. Recording an anomaly here would fire on conforming
+                # sessions. Same split, same shape as the guard issue #119
+                # shipped in proposal.py's Reject branch.
+                return
             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
@@ -132,7 +168,10 @@ class DecisionProjection(BaseProjection):
         """Count votes per proposal, keyed by proposal_id.
 
         ABSTAIN votes are tracked but excluded from the totals returned
-        here (which counts only APPROVE votes).
+        here (which counts only APPROVE votes). A proposal_id that received
+        no votes at all is **absent** from the returned dict -- not present
+        with a 0 value. Use ``.get(proposal_id, 0)`` when checking an
+        arbitrary proposal_id.
         """
         totals: dict[str, int] = {}
         for proposal_id, sender_votes in self.votes.items():