manta-node 0.6b5.dev762__py3-none-any.whl → 0.6b5.dev768__py3-none-any.whl

manta_node/cli/_version_generated.py

@@ -4,7 +4,7 @@ This file is auto-generated at build time by scripts/generate_version.py.
 Do not edit manually.
 """
 
-__version__ = "2026.10.07.6c5d7e8c"
+__version__ = "2026.10.07.bfaeeedd"
 __build_date__ = "2026.10.07"
-__commit_id__ = "6c5d7e8c"
+__commit_id__ = "bfaeeedd"
 __package_version__ = "0.6b5"  # release-series base, moved by scripts/bump_version.py

manta_node/infrastructure/mqtt/command_handler.py

@@ -2,7 +2,9 @@ import asyncio
 import base64
 import inspect
 import json
+import os
 import re
+import time
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
 from logging import getLogger
@@ -11,7 +13,13 @@ from typing import cast
 
 import aiomqtt
 from manta_common.base_mqtt import MqttBase
-from manta_common.build.common.mqtt import MqMetricsSnapshot, MqTaskUpdate
+from manta_common.build.common.mqtt import (
+    MqMetricsSnapshot,
+    MqNodeUpdate,
+    MqNodeUpdateStatus,
+    MqTaskUpdate,
+    NodeUpdateState,
+)
 from manta_common.build.common.tasks import MqttTask, TaskStatus, TaskUpdate
 from manta_common.conversions import ID, b2x
 from manta_common.errors import (
@@ -24,13 +32,17 @@ from manta_common.retry import RetryPolicy
 from manta_common.traces import Tracer
 
 from ...seam import (
+    UPDATING_ENV,
     SeamClient,
     SeamError,
+    SeamState,
     SwitchOutcome,
     UpdateRequest,
+    is_safe_version_name,
 )
 from ...task_manager import LOG_FLUSH_INTERVAL, LogStream, TaskManager
 from ...tasks import TaskProgression
+from ...update_path import is_host_owned
 from ..filesystem.dataset_manager import DatasetManager
 from ..grpc.client import NodeClient
 from ..metrics.collector import Collector
@@ -42,6 +54,19 @@ TIMEOUT = 1  # s
 MAX_LOG_UPLOAD_ATTEMPTS = 5
 MAX_MQTT_CONNECT_FAILURES = 3
 
+# A restarted node replays the request that restarted it until the supervisor
+# answers with the terminal outcome. The supervisor holds the request in flight
+# for the return window (~40 s by default) before it can answer, so the replay
+# polls across that window with headroom; past it the platform's own deadline
+# settles the request.
+REPLAY_POLL_SECONDS = 2.0
+REPLAY_TIMEOUT_SECONDS = 120.0
+
+
+def _node_update_state(state) -> NodeUpdateState:
+    """Map a seam state to the wire enum; they mirror 1:1 (manta-common#291)."""
+    return NodeUpdateState[state.name]
+
 
 def _is_permanent_upload_rejection(exc: Exception) -> bool:
     """Whether the gRPC status carries a rejection the retry policy will not retry."""
@@ -312,14 +337,34 @@ class CommandHandler(Collector, MqttBase):
         """
         self.tracer.debug("Starting background task checker")
         checker = asyncio.create_task(self._ping_loop())
+        replayer = self._start_update_replay()
         try:
             await MqttBase.main(self)
         finally:
             checker.cancel()
-            try:
-                await checker
-            except asyncio.CancelledError:
-                pass
+            if replayer is not None:
+                replayer.cancel()
+            for task in (checker, replayer):
+                if task is None:
+                    continue
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+
+    def _start_update_replay(self) -> asyncio.Task | None:
+        """Start the replay of the update that restarted this node, if any.
+
+        The supervisor set ``MANTA_NODE_UPDATING`` on this boot when it restarted
+        the child for an in-flight update; the node asks for that request's
+        outcome once its MQTT loop is up (NF-8). No supervisor, or no such boot,
+        means no replay.
+        """
+        request_id = os.environ.get(UPDATING_ENV)
+        if not request_id or self._seam_client is None:
+            return None
+        self.tracer.info(f"Replaying in-flight update {request_id} for its outcome")
+        return asyncio.create_task(self.report_inflight_update(request_id))
 
     async def loop_tasks(self):
         """
@@ -703,35 +748,129 @@ class CommandHandler(Collector, MqttBase):
     async def update_node(self, payload: bytes):
         """Handle an `update_node` command from the Manager (the Manager path).
 
-        The Manager declares a pair and the node relays it to its supervisor over
-        the local seam. The payload carries the target pair and the fields the
-        seam's `UpdateRequest` needs; the node computes no ordering (mechanism
-        §6.2). With no supervisor the relay is inert, and the node reports that
-        rather than applying anything itself.
+        The Manager declares a target `manta-node` version in an `MqNodeUpdate`
+        (manta-common#291); the node validates it and relays it to its supervisor
+        over the local seam. The node computes no version ordering (mechanism
+        §6.2): it passes the declared sequence through and re-checks only
+        equality and staleness. With no supervisor the relay is inert, and the
+        node reports that rather than applying anything itself.
+
+        A host-owned node refuses the command before relaying (ADR-0042 D5) and
+        reports the refusal, so the platform's one-path rule holds even if a
+        command reaches it.
         """
-        try:
-            data = json.loads(payload)
-            request = UpdateRequest(
-                request_id=data["request_id"],
-                target=data["target"],
-                force=bool(data.get("force", False)),
-                declared_sequence=data.get("declared_sequence"),
+        request = self._parse_update(payload)
+        # One update path per node (ADR-0042 D5). The platform never sends to a
+        # host-owned node (it fails closed on the reported path); if one arrives
+        # anyway, refuse it here and report the refusal rather than applying it.
+        if is_host_owned():
+            await self.publish_update_status(
+                SwitchOutcome(
+                    request_id=request.request_id,
+                    state=SeamState.REFUSED,
+                    reason="this node is host-updated; the platform does not update it",
+                )
             )
-        except (ValueError, UnicodeDecodeError, KeyError, TypeError) as exc:
-            # A malformed payload — invalid JSON, missing request_id/target, or a
-            # wrong shape — is reported the same way, not left to escape as a
-            # bare KeyError past the dispatch's MantaError handling.
-            raise MantaMQTTError(f"Malformed update_node payload: {exc}") from exc
+            return
         outcome = await self.relay_update(request)
         if outcome is None:
             raise MantaNodeError(
                 "update_node received but no supervisor serves the seam"
             )
+        await self.publish_update_status(outcome)
+
+    @staticmethod
+    def _parse_update(payload: bytes) -> UpdateRequest:
+        """Validate an `MqNodeUpdate` and turn it into the seam's request.
+
+        A malformed payload — undecodable, or missing the version or the request
+        id — is a `MantaMQTTError`, not a bare decode error escaping the
+        dispatch's MantaError handling.
+        """
+        try:
+            command = MqNodeUpdate().parse(payload)
+        except Exception as exc:
+            raise MantaMQTTError(f"Malformed update_node payload: {exc}") from exc
+        if not command.node_package_version or not command.request_id:
+            raise MantaMQTTError(
+                "Malformed update_node payload: node_package_version and"
+                " request_id are both required"
+            )
+        if not is_safe_version_name(command.node_package_version):
+            # The declared version names a directory in the supervisor's version
+            # tree; a separator, `..` or an absolute path must never reach it.
+            raise MantaMQTTError(
+                "Malformed update_node payload: node_package_version is not a"
+                " valid version name"
+            )
+        return UpdateRequest(
+            request_id=command.request_id,
+            target=command.node_package_version,
+            force=bool(command.force),
+            declared_sequence=command.declared_sequence,
+        )
+
+    async def publish_update_status(self, outcome: SwitchOutcome) -> None:
+        """Publish an update outcome on `manager/update_node_status`.
+
+        The payload carries the node token, as every node → manager message does
+        (the manager validates it). QoS 1: the outcome is worth a redelivery
+        attempt, and the node may have just restarted.
+        """
         await self.publish_message(
             "manager/update_node_status",
-            outcome.to_bytes(),
+            MqNodeUpdateStatus(
+                token=self.node_client.secured_token,
+                request_id=outcome.request_id,
+                state=_node_update_state(outcome.state),
+                reason=outcome.reason,
+            ),
+            qos=1,
         )
 
+    async def report_inflight_update(self, request_id: str) -> None:
+        """Report the outcome of the update that restarted this node (NF-8).
+
+        The switch restarted the child, so the synchronous seam reply never
+        reached the process that sent the request. The supervisor named the
+        request in `MANTA_NODE_UPDATING` on this boot; the node replays it over
+        the seam and publishes the terminal outcome. While the switch is still in
+        flight the supervisor answers REFUSED, so the replay polls.
+
+        If no outcome ever arrives (the supervisor no longer holds one), nothing
+        is published: the platform's deadline settles the request. That is the
+        accepted behaviour, stated in the PR.
+        """
+        if self._seam_client is None:
+            return
+        deadline = time.monotonic() + REPLAY_TIMEOUT_SECONDS
+        while True:
+            outcome = await self._replay_once(request_id)
+            if outcome is not None and outcome.state is not SeamState.REFUSED:
+                self.tracer.info(
+                    f"Reporting outcome for in-flight update {request_id}:"
+                    f" {outcome.state.value}"
+                )
+                await self.publish_update_status(outcome)
+                return
+            if time.monotonic() >= deadline:
+                self.tracer.warning(
+                    f"No outcome for in-flight update {request_id} within"
+                    f" {REPLAY_TIMEOUT_SECONDS}s; the platform's deadline settles it"
+                )
+                return
+            await asyncio.sleep(REPLAY_POLL_SECONDS)
+
+    async def _replay_once(self, request_id: str) -> SwitchOutcome | None:
+        """Ask the supervisor once for a request's outcome; None if unreachable."""
+        try:
+            return await self._seam_client.request_update(
+                UpdateRequest(request_id=request_id, target="", replay=True)
+            )
+        except SeamError as exc:
+            self.tracer.warning(f"Update outcome replay failed: {exc}")
+            return None
+
     async def on_task_setup_failed(self, task: MqttTask, exc: Exception):
         """
         Publish a FAILED task update when task setup fails.

manta_node/node_orchestrator.py

@@ -16,6 +16,7 @@ from manta_common.build.common.informations import (
     NodeOverview,
     NodeStatus,
     NodeStatusEnum,
+    NodeUpdatePath,
 )
 from manta_common.build.common.system import Empty
 from manta_common.conversions import HEX_SIZE, ID, oid
@@ -38,9 +39,10 @@ from .infrastructure.mqtt.command_handler import CommandHandler
 from .infrastructure.process.executor import ProcessExecutor
 from .infrastructure.security.auth_agent import AuthAgent
 from .infrastructure.security.token_provider import InMemoryTokenProvider
-from .seam import seam_socket_path
+from .seam import UPDATING_ENV, seam_socket_path
 from .supervisor.seam import SocketSeamClient
 from .task_manager import TaskManager
+from .update_path import update_path as node_update_path
 
 __all__ = ["Node", "NodeFatalError"]
 
@@ -514,6 +516,7 @@ class Node:
         await self.check_manager_availability()
         try:
             version_info = get_full_version_info()
+            path = node_update_path()
             identification = NodeOverview(
                 self.metrics_collector.get_platform_info(
                     _execution_mode_from_config(self.config)
@@ -522,6 +525,11 @@ class Node:
                 node_package_version=version_info["package_version"],
                 node_build_version=version_info["version"],
                 common_core_version=get_common_core_version(),
+                # Set at install; unknown is UNSPECIFIED, which the platform
+                # fails closed on (never sends an update).
+                update_path=(
+                    NodeUpdatePath[path.upper()] if path else NodeUpdatePath.UNSPECIFIED
+                ),
             )
             registration = await self.node_client.register_node(identification)
 
@@ -691,7 +699,7 @@ class Node:
                     # attributed to the update, not read as a fleet disconnect
                     # (NF-8). The manager correlates the id; the node does not
                     # treat this as an unexpected loss.
-                    updating = os.environ.get("MANTA_NODE_UPDATING")
+                    updating = os.environ.get(UPDATING_ENV)
                     if updating:
                         self.tracer.info(
                             f"Restarting for in-flight update {updating};"

manta_node/seam.py

@@ -13,8 +13,8 @@ reason. Keeping it total (messages and the abstract client) means both sides can
 depend on it without a cycle.
 
 **Contract** (mechanism §6.4). The request carries `request_id` (idempotency),
-the `target` (a pair or set id — the node computes no ordering), `force`, and the
-`declared_sequence` the Manager passed through. The supervisor answers with a
+the `target` (the `manta-node` version — the node computes no ordering), `force`,
+and the `declared_sequence` the Manager passed through. The supervisor answers with a
 `state` and a `reason`. The switch restarts the child, so the outcome across a
 switch is observed **asynchronously** after the node comes back (NF-8); the seam
 carries initiation synchronously and the immediate outcome.
@@ -23,6 +23,7 @@ carries initiation synchronously and the immediate outcome.
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
@@ -32,6 +33,35 @@ from typing import Protocol, runtime_checkable
 # 0600 on the socket and its parent. It is local and same-user only (NF-9/NF-10).
 SEAM_SOCKET_NAME = "supervisor.sock"
 
+# The supervisor sets this on the child's env when it restarts the child for an
+# in-flight update. Its value is the request id; the restarted node replays that
+# request over the seam to learn the outcome the restart cut off (NF-8/NF-6: the
+# node never reads the supervisor's in-flight record; it asks).
+UPDATING_ENV = "MANTA_NODE_UPDATING"
+
+# A replay names the request it is asking about rather than a target. The
+# supervisor answers a replay from the completed outcome it holds, never by
+# running the lifecycle: a replay carries no target a switch could apply.
+REPLAY_IN_FLIGHT_REASON = "the request is still in flight"
+REPLAY_UNKNOWN_REASON = "no outcome for this request"
+
+# A target names a directory in the version tree. It arrives over the network
+# (the Manager's declared version), so it must be ONE safe path component: no
+# separator, no `..`, no absolute path, or `versions_dir() / target` would
+# resolve outside the tree. PEP 440 versions and the legacy pair id
+# (`manta-node@X+manta-common-core@Y`) both fit this positive set.
+_VERSION_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+@-]*$")
+MAX_VERSION_NAME = 200
+
+
+def is_safe_version_name(name: str) -> bool:
+    """Whether ``name`` is safe as a single version-tree directory component."""
+    return (
+        isinstance(name, str)
+        and 0 < len(name) <= MAX_VERSION_NAME
+        and _VERSION_NAME_RE.match(name) is not None
+    )
+
 
 def seam_socket_path() -> Path:
     """The Unix-socket path for the seam (in the node's state directory)."""
@@ -60,16 +90,19 @@ class SeamState(str, Enum):
 class UpdateRequest:
     """A request from the running node to its supervisor.
 
-    ``target`` is the pair (or a set id that resolves to one); the node computes
-    no ordering, it passes the declaration through. ``declared_sequence`` is the
-    Manager's order, opaque here. ``request_id`` de-duplicates: a repeat of a
-    request already in flight or completed is a no-op (NF-5).
+    ``target`` is the ``manta-node`` version the Manager declared; the node
+    computes no ordering, it passes the declaration through. ``declared_sequence``
+    is the Manager's order, opaque here. ``request_id`` de-duplicates: a repeat of
+    a request already in flight or completed is a no-op (NF-5). ``replay`` marks a
+    restarted node asking for the outcome of the request that restarted it: the
+    supervisor answers from the completed outcome and never runs the lifecycle.
     """
 
     request_id: str
     target: str
     force: bool = False
     declared_sequence: int | None = None
+    replay: bool = False
 
     def to_bytes(self) -> bytes:
         return json.dumps(
@@ -78,6 +111,7 @@ class UpdateRequest:
                 "target": self.target,
                 "force": self.force,
                 "declared_sequence": self.declared_sequence,
+                "replay": self.replay,
             }
         ).encode()
 
@@ -89,6 +123,7 @@ class UpdateRequest:
             target=data["target"],
             force=bool(data.get("force", False)),
             declared_sequence=data.get("declared_sequence"),
+            replay=bool(data.get("replay", False)),
         )
 
 

manta_node/supervisor/executor.py

@@ -3,11 +3,10 @@
 Mechanism §6.4's "executor" side. ``run_switch`` (``lifecycle.py``) is the state
 machine; this module supplies its four verbs as concrete system actions:
 
-- **fetch** — pull the candidate pair from PyPI into a version dir (NF-10, pull
-  only; ADR-0042 D2 says PyPI by default). At this stage the fetch materialises a
-  version dir naming the candidate and its interpreter; the wheel install itself is
-  the deploy-side apply (manta-deploy#1172), so the executor keeps the *decision*
-  and the *record* honest without duplicating the installer.
+- **fetch** — install the declared manta-node version into a version dir (NF-10, pull
+  only; ADR-0042 D2 says PyPI by default). The fetch either reuses a version dir
+  the fleet apply already materialised, or installs the declared version itself and
+  lets the wheel's pin pull the tested common-core (#509).
 - **verify** — NF-2: import the candidate entrypoint and call the reporting path in
   the candidate's own environment. The full closure check is the same subprocess
   check; a failure leaves the node on its current version.
@@ -30,7 +29,13 @@ import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 
-from ..seam import SeamState, SwitchOutcome, UpdateRequest
+from ..seam import (
+    SeamState,
+    SwitchOutcome,
+    UpdateRequest,
+    is_safe_version_name,
+)
+from . import sequence
 from . import switch as version_tree
 from .bounds import Bounds, load_bounds
 from .lifecycle import run_switch
@@ -90,7 +95,7 @@ def make_executor(
     *,
     bounds: Bounds | None = None,
     verify: Callable[[str, str | None], None] = verify_candidate,
-    child_python: str | None = None,
+    install: Callable[[str], str] = version_tree.install_version,
 ) -> Callable[[UpdateRequest], Awaitable[SwitchOutcome]]:
     """Build the seam handler: a request in, the lifecycle's outcome out.
 
@@ -110,16 +115,15 @@ def make_executor(
     switching = threading.Lock()
 
     def fetch(target: str) -> str:
-        # Pull-only (NF-10). If the deploy apply has already materialised the
-        # candidate's version dir (with its interpreter), use that interpreter —
-        # so verification runs in the candidate's own environment, not merely the
-        # supervisor's. Otherwise the candidate will run from the interpreter the
-        # supervisor boots children with. The wheel install is the deploy apply;
-        # the version dir is (re)materialised at STAGE.
+        # Pull-only (NF-10). A version dir the fleet path already materialised
+        # (with its interpreter) is reused, so verification runs in the
+        # candidate's own environment. Otherwise INSTALL it: the Manager path
+        # installs the declared manta-node version into a fresh version dir and
+        # lets the wheel's pin pull the common-core it was tested with (#509).
         manifest = version_tree.read_manifest(version_tree.versions_dir() / target)
         if manifest is not None:
             return manifest.python
-        return child_python or sys.executable
+        return install(target)
 
     def restart() -> None:
         control.restart()
@@ -134,6 +138,17 @@ def make_executor(
         return control.is_alive()
 
     async def handler(request: UpdateRequest) -> SwitchOutcome:
+        # The target names a directory in the version tree and arrives over the
+        # network, so refuse anything that is not one safe component before the
+        # path is ever built (a replay never reaches here: the seam server
+        # answers it from the outcome). Defence in depth behind the MQTT
+        # handler's own check.
+        if not is_safe_version_name(request.target):
+            return SwitchOutcome(
+                request_id=request.request_id,
+                state=SeamState.REFUSED,
+                reason="target is not a valid version name",
+            )
         # Refuse a second switch while one is in flight (NF-5): a switch restarts
         # the child and moves `current`, so concurrency there is a race, not a
         # queue. `acquire(blocking=False)` makes the check atomic.
@@ -144,6 +159,21 @@ def make_executor(
                 reason="a switch is already in flight",
             )
         try:
+            # STALE — refuse a request whose declared sequence is lower than the
+            # last accepted one (ADR-0042 D4). The sequence orders REQUESTS, not
+            # versions; the node computes no version ordering. A replay carries
+            # no sequence and is answered by the seam server before reaching here.
+            if request.declared_sequence is not None and not sequence.accept_sequence(
+                request.declared_sequence
+            ):
+                return SwitchOutcome(
+                    request_id=request.request_id,
+                    state=SeamState.REFUSED,
+                    reason=(
+                        "stale request: declared_sequence"
+                        f" {request.declared_sequence} is lower than the last accepted"
+                    ),
+                )
             # The lifecycle is synchronous (it blocks through the return window);
             # run it in a worker thread so it does not block the seam's event
             # loop, which is serving the socket the request arrived on.

manta_node/supervisor/inflight.py

@@ -21,12 +21,22 @@ from pathlib import Path
 from .records import read_json, write_json_atomic
 
 INFLIGHT_NAME = "inflight.json"
+# The last terminal outcome, written when a switch resolves and read when a
+# restarted node replays its request. It outlives the in-flight record and a
+# supervisor restart, so a replay is answered from the fact rather than from
+# memory alone (NF-1/NF-8). The node never reads this file: it asks the
+# supervisor over the seam (ADR-0041 D11).
+OUTCOME_NAME = "update_outcome.json"
 
 
 def inflight_path() -> Path:
     return Path.home() / ".manta" / "nodes" / INFLIGHT_NAME
 
 
+def outcome_path() -> Path:
+    return Path.home() / ".manta" / "nodes" / OUTCOME_NAME
+
+
 @dataclass(frozen=True)
 class InFlight:
     """The durable record of a switch in progress."""
@@ -80,3 +90,50 @@ def clear_inflight(path: Path | None = None) -> None:
 def deadline_from_now(window: float) -> float:
     """The deadline for a window that starts now (the window is about the switch)."""
     return time.time() + window
+
+
+@dataclass(frozen=True)
+class UpdateOutcome:
+    """The terminal outcome of one update request, durable for a replay.
+
+    ``state`` is a ``SeamState`` value string; the seam server converts it back
+    when it answers. Only a terminal (non-REFUSED) outcome is stored, so a replay
+    cannot read back a transient refusal as a verdict.
+    """
+
+    request_id: str
+    state: str
+    reason: str
+    detail: dict
+
+    def to_dict(self) -> dict:
+        return {
+            "request_id": self.request_id,
+            "state": self.state,
+            "reason": self.reason,
+            "detail": self.detail,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> UpdateOutcome:
+        return cls(
+            request_id=data["request_id"],
+            state=data["state"],
+            reason=data.get("reason", ""),
+            detail=data.get("detail", {}),
+        )
+
+
+def write_outcome(outcome: UpdateOutcome, path: Path | None = None) -> None:
+    write_json_atomic(path or outcome_path(), outcome.to_dict())
+
+
+def read_outcome(path: Path | None = None) -> UpdateOutcome | None:
+    """The last terminal outcome, or None when there is none/one is malformed."""
+    data = read_json(path or outcome_path())
+    if not data:
+        return None
+    try:
+        return UpdateOutcome.from_dict(data)
+    except (KeyError, TypeError, ValueError):
+        return None

manta_node/supervisor/lifecycle.py

@@ -50,7 +50,7 @@ class SwitchContext:
 
 
 class Fetcher(Protocol):
-    """Fetch a candidate pair; return the interpreter it will run from.
+    """Fetch a candidate version; return the interpreter it will run from.
 
     The interpreter names the candidate's **own environment**, which VERIFY runs
     in (NF-2). The version dir is materialised at STAGE, after verification.
@@ -109,12 +109,12 @@ def run_switch(
     """
     bounds = bounds or Bounds()
 
-    # NO-OP — applying the pair already current changes nothing (NF-5). Return
+    # NO-OP — applying the version already current changes nothing (NF-5). Return
     # before fetch/verify/stage/commit, so the child is NOT restarted: under B1 a
     # re-apply would otherwise be a full switch and restart the node for no change
     # (the daily loop that never converges). `force` does not bypass this: it is
     # the not-newer override, and a deliberate bounce is a unit restart.
-    if version_tree.is_current_pair(request.target):
+    if version_tree.is_current_version(request.target):
         return _outcome(request, SeamState.SKIPPED, "target is already current")
 
     last_good_dir = version_tree.selected()