manta-node 0.6b5.dev703__py3-none-any.whl → 0.6b5.dev705__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.09.24.2d5e06c6"
+__version__ = "2026.09.24.d60eab69"
 __build_date__ = "2026.09.24"
-__commit_id__ = "2d5e06c6"
+__commit_id__ = "d60eab69"
 __package_version__ = "0.6b5"

manta_node/infrastructure/mqtt/command_handler.py

@@ -621,6 +621,8 @@ class CommandHandler(Collector, MqttBase):
                 await self.collect_information(payload)
             elif key == "stop_node":
                 await self.stop_node(payload)
+            elif key == "update_node":
+                await self.update_node(payload)
             else:
                 self.tracer.error(f"Not allowed method: {key}")
                 raise MantaMQTTError(
@@ -698,6 +700,38 @@ class CommandHandler(Collector, MqttBase):
             self.tracer.exception(f"Seam relay failed: {exc}")
             raise MantaNodeError(f"Supervisor seam unavailable: {exc}") from exc
 
+    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.
+        """
+        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"),
+            )
+        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
+        outcome = await self.relay_update(request)
+        if outcome is None:
+            raise MantaNodeError(
+                "update_node received but no supervisor serves the seam"
+            )
+        await self.publish_message(
+            "manager/update_node_status",
+            outcome.to_bytes(),
+        )
+
     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

@@ -38,6 +38,8 @@ 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 .supervisor.seam import SocketSeamClient
 from .task_manager import TaskManager
 
 __all__ = ["Node", "NodeFatalError"]
@@ -83,6 +85,18 @@ def _execution_mode_from_config(config) -> ExecutionMode:
     )
 
 
+def _seam_client_if_served():
+    """The node's seam client, when a supervisor serves the socket; else None.
+
+    The node relays an update to its supervisor over the local seam (2d). When
+    the socket is absent — no supervisor owns this node — the relay stays inert
+    and the node behaves exactly as before (the pre-2d path).
+    """
+    if seam_socket_path().exists():
+        return SocketSeamClient()
+    return None
+
+
 def _build_executor(config) -> TaskExecutor:
     """Build the ``TaskExecutor`` backend from the execution-mode config."""
     mode = config.execution.mode
@@ -589,6 +603,10 @@ class Node:
                 ping_interval=self.config.mqtt.ping_interval,
                 max_concurrent_tasks=self.config.tasks.max_concurrent,
                 task_timeout=self.config.tasks.task_timeout,
+                # The local seam to a supervisor, when one owns this node: the
+                # relay's client for the Manager path (2d). Absent when no
+                # supervisor serves the socket, so the relay stays inert.
+                seam_client=_seam_client_if_served(),
             )
 
             # Start the server for docker communications through
@@ -668,7 +686,19 @@ class Node:
                     and self.command_loop is not None
                     and not self.command_loop.cancelled()
                 ):
-                    self.tracer.info("Publishing node status to manager")
+                    # A restart the supervisor makes for an update carries the
+                    # request id in the env; the DISCONNECTED it publishes is then
+                    # 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")
+                    if updating:
+                        self.tracer.info(
+                            f"Restarting for in-flight update {updating};"
+                            " publishing DISCONNECTED attributed to the update"
+                        )
+                    else:
+                        self.tracer.info("Publishing node status to manager")
                     await self.command_handler.client.publish(
                         "manager/set_node_status",
                         NodeStatus(

manta_node/supervisor/bounds.py

@@ -0,0 +1,88 @@
+"""The switch lifecycle's bounds — config defaults, operator-overridable.
+
+Mechanism §8 "Bounds (config defaults)". These are **runtime config in the
+supervisor's own file** (``~/.manta/supervisor.toml``), not install-time
+constants: an operator can widen or tighten them per host. The defaults are the
+ones the design settled:
+
+- return window **40 s** (the fleet's proven 4x10 s, sustained);
+- per-state in-flight bounds: fetch <= 300 s, verify <= 60 s, stage <= 120 s,
+  switch <= 30 s (~600 s total);
+- retention: current + last good, <= 3 dirs.
+
+A bound is a **ceiling on one state**, not a promise the state takes that long:
+the executor moves on as soon as the state completes, and treats exceeding the
+bound as a failure of that state (which, before the switch, leaves the node on
+its current version — NF-3).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # Python 3.10 has no tomllib; the node floor allows it.
+    import tomli as tomllib
+
+# Bounds live beside the node's other supervisor state, never in a version tree.
+SUPERVISOR_CONFIG_NAME = "supervisor.toml"
+
+
+def supervisor_config_path() -> Path:
+    return Path.home() / ".manta" / SUPERVISOR_CONFIG_NAME
+
+
+@dataclass(frozen=True)
+class Bounds:
+    """The lifecycle's time bounds (seconds) and the retention bound (dirs)."""
+
+    return_window: float = 40.0
+    fetch: float = 300.0
+    verify: float = 60.0
+    stage: float = 120.0
+    switch: float = 30.0
+    retention_dirs: int = 3
+
+    def for_state(self, state: str) -> float:
+        """The in-flight bound for a lifecycle state name."""
+        return getattr(self, state)
+
+
+def load_bounds(path: Path | None = None) -> Bounds:
+    """Load bounds from the supervisor's config, falling back to the defaults.
+
+    A missing file, a partial table, or an unreadable/invalid one all fall back
+    to the defaults per key rather than failing: this runs on the update path, and
+    refusing an update over a typo in a bound would turn a cosmetic config error
+    into a stuck fleet. An unknown key is ignored (forward-compatible).
+    """
+    path = path or supervisor_config_path()
+    try:
+        raw = tomllib.loads(path.read_text())
+    except (FileNotFoundError, OSError, tomllib.TOMLDecodeError):
+        return Bounds()
+
+    table = raw.get("bounds", {})
+    if not isinstance(table, dict):
+        return Bounds()
+
+    known = set(Bounds.__dataclass_fields__)
+    values = {}
+    for key, value in table.items():
+        if key not in known:
+            continue
+        # The numeric bounds must be numbers, the retention bound an int. A
+        # wrong-typed value falls back to the default for that key rather than
+        # reaching the dataclass, where it would only fail on use.
+        if key == "retention_dirs":
+            if isinstance(value, int) and not isinstance(value, bool) and value > 0:
+                values[key] = value
+        elif (
+            isinstance(value, (int, float))
+            and not isinstance(value, bool)
+            and value > 0
+        ):
+            values[key] = float(value)
+    return Bounds(**values)

manta_node/supervisor/executor.py

@@ -0,0 +1,165 @@
+"""The supervisor's real seam executor: adapters that drive the switch lifecycle.
+
+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.
+- **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.
+- **restart** — restart the child onto the committed version (the process manager
+  supplies the handle).
+- **is_back** — wait out the return window for sustained liveness on the new
+  version (NF-8), polling the child's liveness.
+
+The supervisor is infrastructure: it decides nothing about versions, drift,
+fleets or outcomes (D6). It performs the verbs the node relayed.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from ..seam import SeamState, SwitchOutcome, UpdateRequest
+from . import switch as version_tree
+from .bounds import Bounds, load_bounds
+from .lifecycle import run_switch
+
+# How often the return probe checks child liveness within the window.
+RETURN_POLL_SECONDS = 2.0
+
+
+def verify_candidate(candidate_dir: str, python: str | None = None) -> None:
+    """Prove a candidate imports and reports its build, in its own environment.
+
+    NF-2 is three parts (imports, the reporting call, the full closure); this
+    invokes the candidate's own interpreter to import ``manta_node`` and call the
+    reporting path, which exercises all three within that interpreter's
+    environment. A non-zero exit means the candidate is not usable, and the caller
+    leaves the node on its current version (NF-3).
+    """
+    interpreter = python or sys.executable
+    try:
+        check = subprocess.run(
+            [
+                interpreter,
+                "-c",
+                (
+                    "import manta_node;"
+                    " from manta_node.cli.version import get_full_version_info;"
+                    " get_full_version_info()"
+                ),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        # A missing interpreter or a hung import is a verification failure, not a
+        # crash: the caller leaves the node on its current version (NF-3).
+        raise RuntimeError(
+            f"candidate {candidate_dir} failed verification: {exc!r}"
+        ) from exc
+    if check.returncode != 0:
+        raise RuntimeError(
+            f"candidate {candidate_dir} failed verification: {check.stderr.strip()}"
+        )
+
+
+@dataclass
+class ChildControl:
+    """The supervisor's handle on the child, for restart and liveness."""
+
+    restart: Callable[[], None]
+    is_alive: Callable[[], bool]
+
+
+def make_executor(
+    control: ChildControl,
+    *,
+    bounds: Bounds | None = None,
+    verify: Callable[[str, str | None], None] = verify_candidate,
+    child_python: str | None = None,
+) -> Callable[[UpdateRequest], Awaitable[SwitchOutcome]]:
+    """Build the seam handler: a request in, the lifecycle's outcome out.
+
+    ``fetch`` names the candidate's interpreter (the version dir materialise is
+    the deploy apply's job); ``verify`` runs in that interpreter's environment
+    (NF-2); ``restart`` and ``is_back`` come from the child control.
+
+    The handler is async and runs ``run_switch`` in a worker thread — but only
+    **one at a time**: a switch restarts the child and moves ``current``, so two
+    concurrent switches would race both. ``SeamServer`` dedupes by ``request_id``
+    only; a second, differently-ided request while one is switching is refused
+    here rather than run.
+    """
+    bounds = bounds or load_bounds()
+    # One switch at a time. Held across the whole lifecycle, so a second request
+    # (any request_id) is refused while one is in flight, not run concurrently.
+    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.
+        manifest = version_tree.read_manifest(version_tree.versions_dir() / target)
+        if manifest is not None:
+            return manifest.python
+        return child_python or sys.executable
+
+    def restart() -> None:
+        control.restart()
+
+    def is_back(deadline: float) -> bool:
+        # Sustained liveness on the new version, held past the window (NF-8): the
+        # child must be alive at the deadline, not merely once.
+        while time.time() < deadline:
+            if not control.is_alive():
+                return False
+            time.sleep(RETURN_POLL_SECONDS)
+        return control.is_alive()
+
+    async def handler(request: UpdateRequest) -> SwitchOutcome:
+        # 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.
+        if not switching.acquire(blocking=False):
+            return SwitchOutcome(
+                request_id=request.request_id,
+                state=SeamState.REFUSED,
+                reason="a switch is already in flight",
+            )
+        try:
+            # 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.
+            return await asyncio.to_thread(
+                run_switch,
+                request,
+                fetch=fetch,
+                verify=verify,
+                restart=restart,
+                is_back=is_back,
+                bounds=bounds,
+            )
+        finally:
+            switching.release()
+
+    return handler
+
+
+__all__ = ["ChildControl", "SeamState", "make_executor", "verify_candidate"]

manta_node/supervisor/inflight.py

@@ -0,0 +1,82 @@
+"""The durable in-flight record — the one place the deadline and last-good live.
+
+Mechanism §6.4, NF-6's supervisor carve-out. When a switch is in flight the
+supervisor writes this record: the **candidate** being made current, the
+**last-good** version to revert to, and the **deadline** (the return window's
+end). It is **supervisor-written and supervisor-read** — the node never touches
+it — so a supervisor restart re-evaluates it rather than losing the update in
+progress (NF-1/NF-8).
+
+It lives in the state dir beside the instances and the version tree, never inside
+a version dir (NF-6). It is cleared once the switch resolves (reported or
+reverted); its presence is the "an update is in flight" fact.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .records import read_json, write_json_atomic
+
+INFLIGHT_NAME = "inflight.json"
+
+
+def inflight_path() -> Path:
+    return Path.home() / ".manta" / "nodes" / INFLIGHT_NAME
+
+
+@dataclass(frozen=True)
+class InFlight:
+    """The durable record of a switch in progress."""
+
+    request_id: str
+    candidate: str
+    last_good: str | None
+    deadline_epoch: float
+
+    def to_dict(self) -> dict:
+        return {
+            "request_id": self.request_id,
+            "candidate": self.candidate,
+            "last_good": self.last_good,
+            "deadline_epoch": self.deadline_epoch,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> InFlight:
+        return cls(
+            request_id=data["request_id"],
+            candidate=data["candidate"],
+            last_good=data.get("last_good"),
+            deadline_epoch=float(data["deadline_epoch"]),
+        )
+
+    def expired(self, now: float | None = None) -> bool:
+        """True once the return window (the deadline) has passed."""
+        return (now if now is not None else time.time()) > self.deadline_epoch
+
+
+def write_inflight(record: InFlight, path: Path | None = None) -> None:
+    write_json_atomic(path or inflight_path(), record.to_dict())
+
+
+def read_inflight(path: Path | None = None) -> InFlight | None:
+    """The in-flight record, or None when no switch is in flight."""
+    data = read_json(path or inflight_path())
+    if not data:
+        return None
+    try:
+        return InFlight.from_dict(data)
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def clear_inflight(path: Path | None = None) -> None:
+    (path or inflight_path()).unlink(missing_ok=True)
+
+
+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

manta_node/supervisor/lifecycle.py

@@ -0,0 +1,207 @@
+"""The switch lifecycle — fetch, verify, stage, switch, restart, revert.
+
+Mechanism §6, ADR-0041 NF-1/NF-2/NF-3/NF-4/NF-8. This is the **real executor**
+the seam serves (the 2b/2c stub is replaced): a candidate is fetched, **verified
+in its own environment** before it can become current, staged into its own version
+dir, made current by the atomic pointer (the commit point, 2c), and the child is
+restarted. If the child does not come back **within the return window**, the
+supervisor **reverts** to the last good version, so a bad update is
+non-destructive and locally reversible without SSH (NF-3/NF-4).
+
+The steps are injected (`fetch`, `verify`, `restart`, `is_back`) so the state
+machine is tested against the contract in isolation — the supervisor's verbs are
+system actions, and the machine decides nothing about versions (D6). The real
+adapters (PyPI fetch, import/closure verification, child restart) are wired by the
+supervisor.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..seam import SeamState, SwitchOutcome, UpdateRequest
+from . import switch as version_tree
+from .bounds import Bounds
+from .inflight import InFlight, clear_inflight, deadline_from_now, write_inflight
+from .switch import VersionTreeError
+
+
+class LifecycleError(Exception):
+    """A lifecycle step failed; the node stays on its current version (NF-3)."""
+
+
+@dataclass
+class SwitchContext:
+    """The mutable state of one switch attempt."""
+
+    request: UpdateRequest
+    bounds: Bounds
+    last_good: str | None
+    candidate_dir: str | None = None
+
+
+class Fetcher(Protocol):
+    """Fetch a candidate pair; 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.
+    """
+
+    def __call__(self, target: str) -> str: ...
+
+
+class Verifier(Protocol):
+    """Prove the candidate usable in its own environment (NF-2)."""
+
+    def __call__(self, candidate_dir: str, python: str) -> None: ...
+
+
+class Restarter(Protocol):
+    """Restart the child onto the committed version."""
+
+    def __call__(self) -> None: ...
+
+
+class ReturnProbe(Protocol):
+    """Whether the child has come back (sustained) after the switch (NF-8)."""
+
+    def __call__(self, deadline: float) -> bool: ...
+
+
+def _outcome(
+    request: UpdateRequest, state: SeamState, reason: str, **detail
+) -> SwitchOutcome:
+    return SwitchOutcome(
+        request_id=request.request_id, state=state, reason=reason, detail=detail
+    )
+
+
+def run_switch(
+    request: UpdateRequest,
+    *,
+    fetch: Fetcher,
+    verify: Verifier,
+    restart: Restarter,
+    is_back: ReturnProbe,
+    bounds: Bounds | None = None,
+    now: Callable[[], float] = time.time,
+) -> SwitchOutcome:
+    """Run the lifecycle for one request and return its terminal outcome.
+
+    Terminal states: ``REPORTING`` (came back on the new version), ``REVERTED``
+    (no return within the window, reverted to the last good), ``FAILED`` (a
+    pre-switch step failed; nothing changed), ``DOWN`` (the switch happened and
+    the revert itself failed — the node is not running, surfaced honestly).
+
+    The in-flight record is written before the switch and cleared when the
+    lifecycle resolves, so a supervisor restart mid-window can re-evaluate it.
+    """
+    bounds = bounds or Bounds()
+    last_good_dir = version_tree.selected()
+    last_good = last_good_dir.name if last_good_dir else None
+    candidate_dir = request.target
+
+    # FETCH — bounded; the fetcher returns the candidate's own interpreter.
+    candidate_python: str | None = None
+
+    def do_fetch() -> None:
+        nonlocal candidate_python
+        candidate_python = fetch(request.target)
+
+    if not _within(bounds.fetch, do_fetch):
+        return _outcome(
+            request, SeamState.FAILED, "fetch exceeded its bound (no switch)"
+        )
+
+    # VERIFY — the candidate must be usable in its OWN environment (NF-2): the
+    # fetcher named the interpreter the candidate will run from.
+    if not _within(bounds.verify, lambda: verify(candidate_dir, candidate_python)):
+        return _outcome(request, SeamState.FAILED, "verification failed (no switch)")
+
+    # STAGE — materialise the candidate's version dir (idempotent), bounded.
+    staged: dict = {}
+
+    def do_stage() -> None:
+        staged["target"] = version_tree.materialise_version(
+            candidate_dir, candidate_python
+        )
+
+    if not _within(bounds.stage, do_stage):
+        return _outcome(request, SeamState.FAILED, "stage exceeded its bound or failed")
+    target = staged["target"]
+
+    record = InFlight(
+        request_id=request.request_id,
+        candidate=candidate_dir,
+        last_good=last_good,
+        deadline_epoch=deadline_from_now(bounds.return_window),
+    )
+    write_inflight(record)
+
+    # SWITCH — the commit point (NF-1), bounded.
+    try:
+        if not _within(bounds.switch, lambda: version_tree.commit(target)):
+            clear_inflight()
+            return _outcome(
+                request, SeamState.FAILED, "switch exceeded its bound (repoint failed)"
+            )
+    except VersionTreeError as exc:
+        clear_inflight()
+        return _outcome(request, SeamState.FAILED, f"switch failed: {exc}")
+
+    # RESTART onto the committed version, then wait for the return window. A
+    # restart that raises is a failed switch, not a crash: surface DOWN and clear
+    # the record rather than letting the exception escape.
+    if not _within(bounds.switch, restart):
+        clear_inflight()
+        return _outcome(request, SeamState.DOWN, "restart failed after the switch")
+
+    if is_back(record.deadline_epoch):
+        clear_inflight()
+        return _outcome(
+            request,
+            SeamState.REPORTING,
+            "came back on the new version",
+            candidate=candidate_dir,
+        )
+
+    # No return within the window: revert to the last good (NF-3/NF-4/NF-8).
+    if last_good is None:
+        # Nothing to revert to: surface DOWN rather than claim success.
+        clear_inflight()
+        return _outcome(
+            request, SeamState.DOWN, "no return and no last-good version to revert to"
+        )
+    try:
+        version_tree.commit(version_tree.versions_dir() / last_good)
+        if not _within(bounds.switch, restart):
+            raise LifecycleError("restart after revert failed")
+    except (VersionTreeError, LifecycleError) as exc:
+        clear_inflight()
+        return _outcome(request, SeamState.DOWN, f"revert failed: {exc}")
+    clear_inflight()
+    return _outcome(
+        request,
+        SeamState.REVERTED,
+        "no return within the window; reverted",
+        reverted_to=last_good,
+    )
+
+
+def _within(bound: float, step: Callable[[], None]) -> bool:
+    """Run ``step``; True if it completed, False if it raised or exceeded ``bound``.
+
+    A step that raises is a failure of that state, not a crash: before the switch
+    it leaves the node on its current version (NF-3). The time bound is enforced
+    by the step itself (a subprocess timeout / an HTTP timeout); this records the
+    comparison so the caller does not have to.
+    """
+    start = time.monotonic()
+    try:
+        step()
+    except Exception:
+        return False
+    return (time.monotonic() - start) <= bound

manta_node/supervisor/process.py

@@ -23,19 +23,37 @@ wrong one.
 from __future__ import annotations
 
 import argparse
+import asyncio
 import os
 import signal
 import subprocess
 import sys
+import threading
 import time
+import uuid
 from pathlib import Path
 
+from ..seam import (
+    SeamError,
+    SeamState,
+    SwitchOutcome,
+    UpdateRequest,
+    seam_socket_path,
+)
+from .bounds import load_bounds
+from .executor import ChildControl, make_executor
+from .inflight import read_inflight
 from .records import (
     supervisor_record,
     supervisor_record_path,
     write_json_atomic,
 )
-from .switch import boot_python, bootstrap_current
+from .seam import SeamServer, SocketSeamClient
+from .switch import boot_python, bootstrap_current, installed_pair_id
+
+# The child's env carries this when the supervisor restarts it for an in-flight
+# update, so the node can attribute the DISCONNECTED it publishes on the restart.
+UPDATING_ENV = "MANTA_NODE_UPDATING"
 
 # A child that exits more than RESTART_LIMIT times within RESTART_WINDOW_SECONDS
 # is a crash loop: the supervisor stops restarting and exits non-zero, so systemd
@@ -51,6 +69,9 @@ STDOUT_MAX_BYTES = 10 * 1024 * 1024
 # How long a terminal stop waits for the child to wind down before SIGKILL.
 STOP_GRACE_SECONDS = 10
 
+# How long to wait for the seam socket to appear after the server thread starts.
+SEAM_STARTUP_TIMEOUT_SECONDS = 5
+
 
 def _log_dir() -> Path:
     return Path.home() / ".manta" / "logs" / "nodes"
@@ -81,6 +102,13 @@ class Supervisor:
         self._stop = False
         self._child: subprocess.Popen | None = None
         self._restarts: list[float] = []
+        # Set by the seam executor when it wants the child restarted onto the
+        # committed version: the supervision loop respawns it and does NOT count
+        # the exit toward the crash-loop limit (a planned restart, not a crash).
+        self._restart_requested = threading.Event()
+        # The seam server, served in a background thread while the child runs.
+        self._seam_thread: threading.Thread | None = None
+        self._seam_server: SeamServer | None = None
 
     def _write_record(self, child_pid: int | None, state: str) -> None:
         write_json_atomic(
@@ -119,6 +147,61 @@ class Supervisor:
             return self.child_python
         return boot_python(self.child_python)
 
+    def _child_alive(self) -> bool:
+        return self._child is not None and self._child.poll() is None
+
+    def _restart_child(self) -> None:
+        """The seam executor's restart: wind the child down so the loop respawns it.
+
+        Marking the request first means the supervision loop treats the exit as
+        planned (respawn from `current`) rather than a crash toward the limit.
+        """
+        self._restart_requested.set()
+        self._signal_child(signal.SIGTERM)
+
+    def _child_control(self) -> ChildControl:
+        return ChildControl(restart=self._restart_child, is_alive=self._child_alive)
+
+    def _start_seam(self) -> None:
+        """Serve the seam on its socket in a background thread.
+
+        The supervision loop is synchronous (it blocks on the child); the seam
+        server is asyncio. A daemon thread with its own event loop lets the two
+        run side by side — requests arrive while the child is supervised. The
+        handler is the real lifecycle, driven by the child control.
+        """
+        handler = make_executor(
+            self._child_control(),
+            bounds=load_bounds(),
+            child_python=self.child_python,
+        )
+        server = SeamServer()
+        self._seam_server = server
+        self._seam_thread = threading.Thread(
+            target=self._serve_seam, args=(server, handler), daemon=True
+        )
+        self._seam_thread.start()
+        # Wait for the socket to appear, so a trigger issued right after startup
+        # finds a served socket rather than racing the bind.
+        for _ in range(SEAM_STARTUP_TIMEOUT_SECONDS * 100):
+            if seam_socket_path().exists():
+                return
+            time.sleep(0.01)
+        print(
+            "supervisor: seam socket did not appear within the startup window",
+            file=sys.stderr,
+        )
+
+    def _serve_seam(self, server: SeamServer, handler) -> None:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            loop.run_until_complete(server.start(handler))
+        except Exception as exc:  # the seam must not take the supervisor down
+            print(f"supervisor: seam server stopped: {exc!r}", file=sys.stderr)
+        finally:
+            loop.close()
+
     def _spawn(self) -> subprocess.Popen:
         # `--subprocess` is the existing hidden flag: the child does not write an
         # instance file, so exactly one writer (the supervisor) owns the records.
@@ -148,9 +231,21 @@ class Supervisor:
         stdout_path = log_dir / f"{self.alias}.supervisor.stdout"
         if stdout_path.exists() and stdout_path.stat().st_size >= STDOUT_MAX_BYTES:
             stdout_path.replace(stdout_path.with_name(f"{stdout_path.name}.1"))
+        # Mark the child when an update is in flight, so the node's DISCONNECTED
+        # on this restart is attributed to the update, not read as a fleet
+        # disconnect (NF-8, B-22). The node cannot read the supervisor's in-flight
+        # record (NF-6), so the supervisor passes the request id in the env.
+        env = None
+        record = read_inflight()
+        if record is not None:
+            env = {**os.environ, UPDATING_ENV: record.request_id}
         with open(stdout_path, "a") as stream:
             child = subprocess.Popen(
-                cmd, stdout=stream, stderr=stream, start_new_session=True
+                cmd,
+                stdout=stream,
+                stderr=stream,
+                start_new_session=True,
+                env=env,
             )
         # Publish the pid BEFORE returning: a signal that fires between here and
         # the caller's `_stop` check must be able to reach the child, not a gone
@@ -166,6 +261,10 @@ class Supervisor:
         # restarts; a host with no version pair skips this entirely.
         if self.version_pair:
             bootstrap_current(self.version_pair, self.child_python)
+            # Serve the seam on a version-tree node: a switch is meaningful only
+            # there, and it is where the executor has a tree to act on. The socket
+            # now exists while the supervisor runs, so a trigger is served.
+            self._start_seam()
         self._write_record(None, "starting")
 
         while not self._stop:
@@ -184,6 +283,13 @@ class Supervisor:
             if self._stop:
                 break
 
+            # A restart the seam executor asked for is planned, not a crash: it
+            # respawns from `current` and does not count toward the limit.
+            if self._restart_requested.is_set():
+                self._restart_requested.clear()
+                self._write_record(None, "restarting")
+                continue
+
             now = time.monotonic()
             self._restarts = [
                 t for t in self._restarts if now - t < RESTART_WINDOW_SECONDS
@@ -209,11 +315,54 @@ class Supervisor:
                 self._child.wait(timeout=STOP_GRACE_SECONDS)
             except subprocess.TimeoutExpired:
                 self._signal_child(signal.SIGKILL)
+        # Close the seam socket so a later supervisor is not left with a stale one
+        # to unlink. The server thread is a daemon and ends with the process.
+        seam_socket_path().unlink(missing_ok=True)
         supervisor_record_path(self.alias).unlink(missing_ok=True)
         return 0
 
 
+async def _apply_over_seam(request: UpdateRequest) -> SwitchOutcome:
+    """Submit one update request to a running supervisor over the seam."""
+    return await SocketSeamClient().request_update(request)
+
+
+def apply_command(argv: list[str]) -> int:
+    """`manta-supervisor apply <pair>` — the fleet path's local trigger (2d).
+
+    The fleet tooling runs this as the node's service user; it writes an
+    ``UpdateRequest`` to the supervisor's socket and prints the outcome. This is
+    the named trigger for the fleet path; the Manager path (Phase 3) submits the
+    same request from the node's MQTT relay instead.
+    """
+    parser = argparse.ArgumentParser(
+        prog="manta-supervisor apply",
+        description="Ask a running supervisor to apply a pair (writes the seam).",
+    )
+    parser.add_argument("pair", help="the pair (or set id) to apply")
+    parser.add_argument("--force", action="store_true", help="override the guard")
+    parser.add_argument("--request-id", help="idempotency key (fresh uuid by default)")
+    args = parser.parse_args(argv)
+
+    request = UpdateRequest(
+        request_id=args.request_id or uuid.uuid4().hex,
+        target=args.pair,
+        force=args.force,
+    )
+    try:
+        outcome = asyncio.run(_apply_over_seam(request))
+    except SeamError as exc:
+        print(f"manta-supervisor apply: {exc}", file=sys.stderr)
+        return 1
+    print(f"{outcome.state.value}: {outcome.reason}")
+    return 0 if outcome.state not in (SeamState.FAILED, SeamState.DOWN) else 1
+
+
 def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "apply":
+        return apply_command(argv[1:])
+
     parser = argparse.ArgumentParser(
         prog="manta-supervisor",
         description="Own a manta_node child and its restart (ADR-0041 boundary B1).",
@@ -230,16 +379,34 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "--pair",
         help=(
-            "the pair this node runs, for the immutable version tree (2c); when"
-            " set, the child boots from `current` and falls back to --python"
+            "the pair this node runs, for the immutable version tree (2c)."
+            " Defaults to the pair derived from the installed distributions, so"
+            " provisioning does not name a version: boot materialises the"
+            " in-place code as that pair's version dir, and the fleet apply later"
+            " installs a different pair into its own dir."
+        ),
+    )
+    parser.add_argument(
+        "--version-tree",
+        action="store_true",
+        help=(
+            "enable the version tree: serve the seam and boot the child from"
+            " `current`, using --pair or the derived pair. Off by default, so a"
+            " node runs the pre-2c path until the deploy enables it."
         ),
     )
     args = parser.parse_args(argv)
+    version_pair = None
+    if args.version_tree:
+        version_pair = args.pair or installed_pair_id()
+    elif args.pair:
+        # --pair alone still opts in, for a hand-run supervisor.
+        version_pair = args.pair
     return Supervisor(
         args.alias,
         args.config or args.alias,
         child_python=args.python,
-        version_pair=args.pair,
+        version_pair=version_pair,
     ).run()
 
 

manta_node/supervisor/seam.py

@@ -13,11 +13,11 @@ the 2b acceptance: the code can ship, be idle, and change nothing.
 ``0600`` on the socket and its parent directory. Local and same-user only
 (NF-9/NF-10).
 
-**What "execute" means here.** At 2b the supervisor has no version tree yet, so
-its executor is a stub: it records the request, idempotently, and answers
-``REQUESTED`` (or ``REFUSED`` for a repeat that is still in flight). The real
-fetch/verify/stage/switch/restart/revert lifecycle is 2c/2d; the seam's contract
-is what this lands.
+**What "execute" means here.** The server is transport and idempotency only: it
+hands each new request to the handler and returns the handler's outcome. The
+supervisor wires the **real lifecycle** (``lifecycle.run_switch`` via
+``executor.make_executor``) as that handler; ``stub_handler`` remains for a
+supervisor with no version tree, answering ``REQUESTED`` without acting.
 """
 
 from __future__ import annotations
@@ -91,8 +91,8 @@ class SeamServer:
                 await writer.wait_closed()
 
     async def _answer(self, request: UpdateRequest, handler) -> SwitchOutcome:
-        # Idempotency: a repeat of a completed request returns the same outcome;
-        # a repeat still in flight is refused, not run twice (NF-5).
+        # Idempotency: a repeat of a COMPLETED request returns the same outcome; a
+        # repeat still in flight is refused, not run twice (NF-5).
         if request.request_id in self._answered:
             return self._answered[request.request_id]
         if request.request_id in self._in_flight:
@@ -106,7 +106,11 @@ class SeamServer:
             outcome = await handler(request)
         finally:
             self._in_flight.discard(request.request_id)
-        self._answered[request.request_id] = outcome
+        # A REFUSED is not a completed request: caching it would make a later
+        # retry of the same id return the stale refusal instead of being tried
+        # (the idempotency contract is about *completed* requests).
+        if outcome.state is not SeamState.REFUSED:
+            self._answered[request.request_id] = outcome
         return outcome
 
     async def start(self, handler) -> None:

manta_node/supervisor/switch.py

@@ -8,11 +8,11 @@ and the child restart resolves deterministically to the version ``current`` name
 and a failed repoint leaves the previous version selected. There is no
 half-applied state.
 
-**2c is a no-op switch.** No candidate is fetched or verified here (that is 2d);
-2c materialises the *current* code as the first version dir and points ``current``
-at it, so the node runs the same code from a version dir. A version dir holds the
-pair's identity and the interpreter that runs it; the code itself is not copied at
-2c.
+**Bootstrapping is a no-op switch.** ``bootstrap_current`` materialises the
+*current* code as the first version dir and points ``current`` at it, so a node
+runs the same code from a version dir. ``materialise_version``/``commit`` are also
+the primitives the real switch lifecycle drives (``lifecycle.py``); a version dir
+holds the pair's identity and the interpreter that runs it.
 
 **State is never inside the tree** (NF-6). The tree lives beside the node's state
 (``~/.manta/nodes/``), and a version dir contains only code-side markers — never
@@ -24,6 +24,7 @@ from __future__ import annotations
 import os
 from dataclasses import dataclass
 from datetime import datetime, timezone
+from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 
 from .records import read_json, write_json_atomic
@@ -42,6 +43,27 @@ def versions_dir() -> Path:
     return Path.home() / ".manta" / "nodes" / VERSIONS_DIR_NAME
 
 
+def installed_pair_id() -> str:
+    """The pair id of the code currently installed, from distribution metadata.
+
+    The pair is named `<node-package>@<version>+<common-package>@<version>`, so a
+    version dir is self-describing and two different pairs never collide. Read
+    from installed metadata (stdlib only — the supervisor imports no
+    `manta_common`): this is the pair the in-place venv holds, which boot
+    materialises as the first version dir.
+    """
+
+    def safe(name: str) -> str:
+        try:
+            return version(name)
+        except PackageNotFoundError:
+            return "unknown"
+
+    return (
+        f"manta-node@{safe('manta_node')}+manta-common-core@{safe('manta-common-core')}"
+    )
+
+
 def current_link() -> Path:
     return Path.home() / ".manta" / "nodes" / CURRENT_LINK_NAME
 

{manta_node-0.6b5.dev703.dist-info → manta_node-0.6b5.dev705.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: manta_node
-Version: 0.6b5.dev703
+Version: 0.6b5.dev705
 Summary: Node side software of the Manta platform. It is responsible for the communication with the Manta Core and the execution of the tasks.
 Author-email: Hugo Miralles <hugo.miralles@manta-tech.io>, Matthew Thompson <matthew.thompson@manta-tech.io>
 License-Expression: AGPL-3.0-or-later

{manta_node-0.6b5.dev703.dist-info → manta_node-0.6b5.dev705.dist-info}/RECORD

@@ -1,12 +1,12 @@
 manta_node/__init__.py,sha256=bgGWXH3yQVhNf0v1ZGUBAy5Y51fqb0Y-EaLnocbcino,153
 manta_node/__main__.py,sha256=SjrJyuMg_ZFKV6WOVe3MrtWM8Qmu065dkKZYl4n2YLw,1665
-manta_node/node_orchestrator.py,sha256=K2UZAk-FHs1ERrwf5hTcrQC2AASG2J2eVlr-l45aDt4,28066
+manta_node/node_orchestrator.py,sha256=nfpNCM8wgnihKhZZ36GIizmyyaOdEOBhdfn7PqqTCrQ,29591
 manta_node/seam.py,sha256=wAI3uL1iuV6pmDOaBW7WZi7_V7-NsHQDP6C_gFIjCiA,4747
 manta_node/task_manager.py,sha256=xRE-yKdUW0FFR8vtX1jDwl1AxTbqVD_JS7QVR62GA00,38002
 manta_node/tasks.py,sha256=o837Hi-KFVJg9LF5iOtE8oD6UuTOfrEPWR-JOdhRGeY,6983
 manta_node/utils.py,sha256=Hw4Iw2jYQYsfVLVJuBMt-_rMFBeml3nCDE2jiiXc8YM,1155
 manta_node/cli/__init__.py,sha256=arzO3mXDJ-E2yeeytbZfN7mCswwxdQ43_QjyeL2E5yE,134
-manta_node/cli/_version_generated.py,sha256=imj5h8A2Tja7mN6z3U3IDqDRfT85YlddPTAqB1hpbfg,275
+manta_node/cli/_version_generated.py,sha256=Avtgxf4CTYxrwjUmb8TM92DAZRNRqrzV-eNId81M60o,275
 manta_node/cli/config_manager.py,sha256=BCju9zqzraviL3KrzRnB-vZQUY__Q5kuEqb7EdB8YdI,4409
 manta_node/cli/main.py,sha256=dZa6zrypWBvpN8hd4qpxevvlyNFhxKINCg1537NJ36w,4318
 manta_node/cli/version.py,sha256=3lrnIWpOosszBN-VsCBVLxDgpvCC7IB0aDIKx_3e7hI,3115
@@ -41,7 +41,7 @@ manta_node/infrastructure/metrics/__init__.py,sha256=ODGAj9s63F5jba2c3dQRMfNK6I4
 manta_node/infrastructure/metrics/collector.py,sha256=9ESw__Pc2tV6ldG5yhos2IS7T5Td59KxTIwDRZc_G4w,3067
 manta_node/infrastructure/metrics/metrics_collector.py,sha256=TI_9tRoIUunGx_BstVavK6VElig7Wc5mJ0kB4bFumVs,11048
 manta_node/infrastructure/mqtt/__init__.py,sha256=riXo1sXgO4YV6DHCmWRqK61BAmuGLdHiVdQFunAJadA,140
-manta_node/infrastructure/mqtt/command_handler.py,sha256=Ym8t0fA-qWjg8n0VDyYJYxCqulVH3lOJB1MjQHu5iZE,28110
+manta_node/infrastructure/mqtt/command_handler.py,sha256=aGJMPF8uAdeEw5xfE_WlL3-ROiSV_LCUXf5EpmZrbtk,29728
 manta_node/infrastructure/network/__init__.py,sha256=On3XLgycFQoc-fBCa5hFuFDfEJjmFy7Wl2CK3D2LkdI,478
 manta_node/infrastructure/network/event_registry.py,sha256=iWEfUJRzDnWjOrDinpYqVyIUpGKJjp7RZkjMDPfpplM,1661
 manta_node/infrastructure/network/factory.py,sha256=-LvHbBp5nBpQ7fyQT1T0pvK3aczZqWc9QNDW37brBeU,3897
@@ -53,13 +53,17 @@ manta_node/infrastructure/security/__init__.py,sha256=lI6vkbUmfmt0m363iO4HzuzVNo
 manta_node/infrastructure/security/auth_agent.py,sha256=WkPTg_g0gix7xomb_on_Ft3TNX0FpeqS7gwgJW9mTvk,11037
 manta_node/infrastructure/security/token_provider.py,sha256=u3bcbQYNBskFzunO-wOSZpGkDN_CU1BCB5HUbZTC4Vg,1832
 manta_node/supervisor/__init__.py,sha256=kgdoNce1tM4e7jvdxkdmnNJV1L92-NI2cRfYSdm9vsw,542
-manta_node/supervisor/process.py,sha256=3ODg2JP2H4T_y7NrP2ScNpLZ9JJIWXgZYoae83jr41Y,10306
+manta_node/supervisor/bounds.py,sha256=MlUfj0tYY-US348JsxYA-Ph5pSpgoOPlRdVTwmrPtZA,3181
+manta_node/supervisor/executor.py,sha256=a0JafVoTmtbIu87nwUtj08KAC-Q-u0Ajdn_ptyu9yoc,6833
+manta_node/supervisor/inflight.py,sha256=JOqwXYM928fpcQtYdoK7596eAg28KM70bh85cyQgX3Q,2663
+manta_node/supervisor/lifecycle.py,sha256=JE74H0ODt5_y997kliiVDiQAf1laYptNjkrnnfGdgK0,7411
+manta_node/supervisor/process.py,sha256=mWd2C4-S8NpupcLp0YbBEYmqQUQbrfMAZi5TF9UQ_cM,17504
 manta_node/supervisor/records.py,sha256=fUlL1SfmWpGnCbJ9956cuy0H3a7-aEF-B-naqbJiYoU,6405
-manta_node/supervisor/seam.py,sha256=zafKSWFeZClprftM0tYaTW3Ng7lxeFcndRIHplpSnf4,7708
-manta_node/supervisor/switch.py,sha256=6EcA4G7MHW66079ivUcUwvYrBtvF72Z9zJvc5dPTrp0,6598
-manta_node-0.6b5.dev703.dist-info/licenses/LICENSE,sha256=9mBgLhiB9goQPQjg9XQJ6FjgVxYw9Q8lyOZYkPGwF_c,34484
-manta_node-0.6b5.dev703.dist-info/METADATA,sha256=MoG9oAUzP6oIK3GesUaRDj-ZkypRqbmEDbNjI3P7Y2A,4231
-manta_node-0.6b5.dev703.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-manta_node-0.6b5.dev703.dist-info/entry_points.txt,sha256=uCwggRApalLEsYs1YxwTBN0-e9oMJAkMoBp01HaSdoY,110
-manta_node-0.6b5.dev703.dist-info/top_level.txt,sha256=nbT5J5WETuXM9UPoQckl29uUOq8wMYdRb9QDx5kAFeo,11
-manta_node-0.6b5.dev703.dist-info/RECORD,,
+manta_node/supervisor/seam.py,sha256=HomMFTDbc0dZQ9VrfGVhQxjiU7E23-zwyjZnLsnq6dc,8031
+manta_node/supervisor/switch.py,sha256=BUSvMdWyUfZmeEVSBmQ7wLNRD7troPxZ3pdg8tOGXo4,7433
+manta_node-0.6b5.dev705.dist-info/licenses/LICENSE,sha256=9mBgLhiB9goQPQjg9XQJ6FjgVxYw9Q8lyOZYkPGwF_c,34484
+manta_node-0.6b5.dev705.dist-info/METADATA,sha256=ajleN4PRTTgRVihXNc2WTZEatE_cgnmro32xQBBd1JY,4231
+manta_node-0.6b5.dev705.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+manta_node-0.6b5.dev705.dist-info/entry_points.txt,sha256=uCwggRApalLEsYs1YxwTBN0-e9oMJAkMoBp01HaSdoY,110
+manta_node-0.6b5.dev705.dist-info/top_level.txt,sha256=nbT5J5WETuXM9UPoQckl29uUOq8wMYdRb9QDx5kAFeo,11
+manta_node-0.6b5.dev705.dist-info/RECORD,,