manta-node 0.6b5.dev705__py3-none-any.whl → 0.6b5.dev707__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.d60eab69"
-__build_date__ = "2026.09.24"
-__commit_id__ = "d60eab69"
+__version__ = "2026.09.25.d14aac9a"
+__build_date__ = "2026.09.25"
+__commit_id__ = "d14aac9a"
 __package_version__ = "0.6b5"

manta_node/supervisor/lifecycle.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import time
 from collections.abc import Callable
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Protocol
 
 from ..seam import SeamState, SwitchOutcome, UpdateRequest
@@ -28,6 +29,11 @@ from .bounds import Bounds
 from .inflight import InFlight, clear_inflight, deadline_from_now, write_inflight
 from .switch import VersionTreeError
 
+# The free-space floor to stage a version dir. A version dir holds a full
+# dependency closure, so the check refuses well before the disk is full rather
+# than half-staging (NF-12). Operator-overridable via `run_switch`'s argument.
+MIN_FREE_BYTES = 500 * 1024 * 1024
+
 
 class LifecycleError(Exception):
     """A lifecycle step failed; the node stays on its current version (NF-3)."""
@@ -88,6 +94,7 @@ def run_switch(
     is_back: ReturnProbe,
     bounds: Bounds | None = None,
     now: Callable[[], float] = time.time,
+    min_free_bytes: int = MIN_FREE_BYTES,
 ) -> SwitchOutcome:
     """Run the lifecycle for one request and return its terminal outcome.
 
@@ -121,6 +128,16 @@ def run_switch(
     if not _within(bounds.verify, lambda: verify(candidate_dir, candidate_python)):
         return _outcome(request, SeamState.FAILED, "verification failed (no switch)")
 
+    # FREE SPACE — refuse before staging when there is no room for a full version
+    # dir (NF-12, §6.2). Refusing here, before any write, is what stops a
+    # half-staged tree: the node stays on its current version.
+    if not version_tree.has_room_for(min_free_bytes):
+        return _outcome(
+            request,
+            SeamState.REFUSED,
+            "insufficient free space to stage a version dir",
+        )
+
     # STAGE — materialise the candidate's version dir (idempotent), bounded.
     staged: dict = {}
 
@@ -145,11 +162,13 @@ def run_switch(
     try:
         if not _within(bounds.switch, lambda: version_tree.commit(target)):
             clear_inflight()
+            _reclaim_candidate(bounds, target, last_good_dir)
             return _outcome(
                 request, SeamState.FAILED, "switch exceeded its bound (repoint failed)"
             )
     except VersionTreeError as exc:
         clear_inflight()
+        _reclaim_candidate(bounds, target, last_good_dir)
         return _outcome(request, SeamState.FAILED, f"switch failed: {exc}")
 
     # RESTART onto the committed version, then wait for the return window. A
@@ -157,10 +176,18 @@ def run_switch(
     # the record rather than letting the exception escape.
     if not _within(bounds.switch, restart):
         clear_inflight()
+        _reclaim_candidate(bounds, target, last_good_dir)
         return _outcome(request, SeamState.DOWN, "restart failed after the switch")
 
     if is_back(record.deadline_epoch):
         clear_inflight()
+        # Reclaim on a SUCCESSFUL switch (NF-12/B-34): the tree stays bounded, and
+        # the current and last-good versions are never removed. No separate
+        # sweeper: reclamation rides the switch that made a version superseded.
+        protect = {target}
+        if last_good_dir is not None:
+            protect.add(last_good_dir)
+        version_tree.reclaim(bounds.retention_dirs, protect)
         return _outcome(
             request,
             SeamState.REPORTING,
@@ -172,6 +199,7 @@ def run_switch(
     if last_good is None:
         # Nothing to revert to: surface DOWN rather than claim success.
         clear_inflight()
+        _reclaim_candidate(bounds, target, last_good_dir)
         return _outcome(
             request, SeamState.DOWN, "no return and no last-good version to revert to"
         )
@@ -181,8 +209,13 @@ def run_switch(
             raise LifecycleError("restart after revert failed")
     except (VersionTreeError, LifecycleError) as exc:
         clear_inflight()
+        _reclaim_candidate(bounds, target, last_good_dir)
         return _outcome(request, SeamState.DOWN, f"revert failed: {exc}")
     clear_inflight()
+    # The candidate was superseded the moment the switch did not land: it is
+    # reclaimed even though the switch failed, so repeated failing switches do
+    # not grow the tree past the bound (NF-12). current/last-good are protected.
+    _reclaim_candidate(bounds, target, last_good_dir)
     return _outcome(
         request,
         SeamState.REVERTED,
@@ -191,6 +224,29 @@ def run_switch(
     )
 
 
+def _reclaim_candidate(
+    bounds: Bounds, candidate: Path, last_good_dir: Path | None
+) -> None:
+    """Reclaim after a switch that did NOT land: the candidate is superseded.
+
+    Called on every FAILED/REVERTED/DOWN path after staging, so repeated failing
+    switches do not grow the tree past ``retention_dirs`` (NF-12). The candidate is
+    removed first, then ``reclaim`` bounds the rest, protecting ``current`` and the
+    last good.
+
+    Whether the candidate is still current depends on the branch: a failed commit
+    leaves it non-current, but a switch whose commit succeeded and whose RESTART
+    then failed (or found no last good to revert to) has ``target`` AS ``current``.
+    ``remove_version`` therefore refuses to delete whatever ``current`` names, and
+    that check — not any assumption here — is what keeps the node runnable on those
+    DOWN paths. Keep it if the candidate could ever be current.
+    """
+    version_tree.remove_version(candidate)
+    current = version_tree.selected()
+    protect = {p for p in (current, last_good_dir) if p is not None}
+    version_tree.reclaim(bounds.retention_dirs, protect)
+
+
 def _within(bound: float, step: Callable[[], None]) -> bool:
     """Run ``step``; True if it completed, False if it raised or exceeded ``bound``.
 

manta_node/supervisor/process.py

@@ -40,9 +40,11 @@ from ..seam import (
     UpdateRequest,
     seam_socket_path,
 )
+from . import switch as version_tree
 from .bounds import load_bounds
 from .executor import ChildControl, make_executor
 from .inflight import read_inflight
+from .lifecycle import MIN_FREE_BYTES
 from .records import (
     supervisor_record,
     supervisor_record_path,
@@ -358,10 +360,47 @@ def apply_command(argv: list[str]) -> int:
     return 0 if outcome.state not in (SeamState.FAILED, SeamState.DOWN) else 1
 
 
+def preflight_command(argv: list[str]) -> int:
+    """`manta-supervisor preflight <pair>` — may this node take another version?
+
+    **Local, not a socket verb.** It reads the node's own version tree and applies
+    the supervisor's room policy *without writing anything*; it needs no running
+    supervisor, so the fleet path can ask before it creates the version dir and the
+    refusal is early (NF-12 has teeth). The deploy only asks; the supervisor owns
+    the policy.
+
+    Output mirrors ``apply`` but echoes the pair: ``<state>: <pair>: <reason>``
+    (``ok`` / ``refused``), exiting **0** either way — the state is the verdict,
+    not the exit code.
+    """
+    parser = argparse.ArgumentParser(
+        prog="manta-supervisor preflight",
+        description="Check room for one more version dir before installing it.",
+    )
+    parser.add_argument("pair", help="the pair to be staged (for the message)")
+    parser.add_argument(
+        "--min-free-bytes",
+        type=int,
+        default=None,
+        help="override the free-space floor (defaults to the configured floor)",
+    )
+    args = parser.parse_args(argv)
+
+    floor = args.min_free_bytes if args.min_free_bytes is not None else MIN_FREE_BYTES
+    result = version_tree.preflight(floor)
+    state = "ok" if result.ok else "refused"
+    # The pair is echoed so an operator running preflight across several pairs
+    # can tell which line is which.
+    print(f"{state}: {args.pair}: {result.reason}")
+    return 0
+
+
 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:])
+    if argv and argv[0] == "preflight":
+        return preflight_command(argv[1:])
 
     parser = argparse.ArgumentParser(
         prog="manta-supervisor",

manta_node/supervisor/switch.py

@@ -22,7 +22,9 @@ the token, config or datasets.
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
+import shutil
+import sys
+from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
@@ -70,19 +72,31 @@ def current_link() -> Path:
 
 @dataclass(frozen=True)
 class Version:
-    """A version dir's identity: the pair and the interpreter that runs it."""
+    """A version dir's identity: the pair, the interpreter, and its size.
+
+    ``size_bytes`` is recorded once (see ``version_dir_bytes``) so the room check
+    is a manifest read, not a recursive walk of the dependency closure on every
+    switch. A version dir is immutable (NF-1), so a recorded size stays valid.
+    """
 
     pair: str
     python: str
     created: str
+    size_bytes: int | None = None
 
     def to_dict(self) -> dict:
-        return {"pair": self.pair, "python": self.python, "created": self.created}
+        data = {"pair": self.pair, "python": self.python, "created": self.created}
+        if self.size_bytes is not None:
+            data["size_bytes"] = self.size_bytes
+        return data
 
     @classmethod
     def from_dict(cls, data: dict) -> Version:
         return cls(
-            pair=data["pair"], python=data["python"], created=data.get("created", "")
+            pair=data["pair"],
+            python=data["python"],
+            created=data.get("created", ""),
+            size_bytes=data.get("size_bytes"),
         )
 
 
@@ -199,3 +213,225 @@ def is_pointer_target(target: Path) -> bool:
     """True when ``current`` resolves to ``target``."""
     link = current_link()
     return link.is_symlink() and Path(os.path.realpath(link)) == target
+
+
+def list_versions() -> list[Path]:
+    """The version dirs, oldest first.
+
+    Ordered by the manifest's ``created`` (a dir with no readable manifest sorts
+    first, so a corrupt one is reclaimed before a good one). Used by retention to
+    pick what to reclaim.
+    """
+    root = versions_dir()
+    if not root.is_dir():
+        return []
+
+    def created(p: Path) -> str:
+        manifest = read_manifest(p)
+        return manifest.created if manifest else ""
+
+    dirs = [p for p in root.iterdir() if p.is_dir()]
+    return sorted(dirs, key=created)
+
+
+def remove_version(version_dir: Path) -> bool:
+    """Remove one version dir and its contents; True if it is gone.
+
+    Best-effort, like ``reclaim``: a dir that cannot be removed is reported, not
+    raised — a stale dir must not fail the switch that is trying to discard it.
+    """
+    # Never remove the version `current` names, even if a caller asks: the boot
+    # path must always resolve to something runnable.
+    if os.path.realpath(version_dir) == os.path.realpath(current_link()):
+        return False
+    try:
+        for child in version_dir.iterdir():
+            if child.is_dir():
+                shutil.rmtree(child)
+            else:
+                child.unlink()
+        version_dir.rmdir()
+        return True
+    except OSError as exc:
+        print(f"retention: could not remove {version_dir}: {exc}", file=sys.stderr)
+        return False
+
+
+def reclaim(retention_dirs: int, protect: set[Path]) -> list[Path]:
+    """Remove the oldest versions beyond ``retention_dirs``, never a protected one.
+
+    NF-12/B-34: the version tree stays bounded, but the **current** and last-good
+    versions are never removed — ``protect`` names them. Returns the removed dirs.
+    Called on a successful switch, so there is no separate sweeper to start.
+    """
+    versions = list_versions()
+    protected = {os.path.realpath(p) for p in protect}
+    # Oldest first; drop the front until the count is within the bound, skipping
+    # a protected dir (do not count it as removable, but it still occupies a slot).
+    removed: list[Path] = []
+    keep = max(retention_dirs, 2)  # current + last good is the floor
+    for candidate in versions:
+        if len(versions) - len(removed) <= keep:
+            break
+        if os.path.realpath(candidate) in protected:
+            continue
+        if remove_version(candidate):
+            removed.append(candidate)
+    return removed
+
+
+def _free_bytes() -> int:
+    """Free bytes on the version tree's filesystem.
+
+    Checks the nearest existing ancestor: the tree may not exist yet on a fresh
+    node, and the capacity is the filesystem's either way.
+    """
+    probe = versions_dir()
+    while not probe.exists() and probe != probe.parent:
+        probe = probe.parent
+    return shutil.disk_usage(probe).free
+
+
+def version_dir_bytes(version_dir: Path) -> int:
+    """The on-disk size of a version dir.
+
+    Cached in the manifest once measured: a version dir is immutable (NF-1), so
+    the size does not change, and a switch on an ARM edge node must not re-walk a
+    full dependency closure. The first read measures and writes it back; every
+    later read is a manifest lookup. A dir with no readable manifest is measured
+    but not cached (there is nowhere to write it).
+    """
+    manifest = read_manifest(version_dir)
+    if manifest is not None and manifest.size_bytes is not None:
+        return manifest.size_bytes
+
+    total = 0
+    for path in version_dir.rglob("*"):
+        try:
+            if path.is_file():
+                total += path.stat().st_size
+        except OSError:
+            # A file that vanished mid-walk is not counted; the size is an
+            # estimate for the room check, not a ledger.
+            continue
+
+    if manifest is not None:
+        write_json_atomic(
+            version_dir / MANIFEST_NAME,
+            replace(manifest, size_bytes=total).to_dict(),
+        )
+    return total
+
+
+def largest_version_bytes() -> int:
+    """The size of the largest existing version dir, or 0 when the tree is empty.
+
+    This is the best available estimate of "what one more version dir costs":
+    the versions on this host are the same package and dependency closure, so the
+    largest already-present dir is a floor for the candidate's footprint. Sizes
+    come from each dir's manifest cache (see ``version_dir_bytes``), so this is
+    manifest reads, not recursive walks.
+    """
+    sizes = [version_dir_bytes(v) for v in list_versions()]
+    return max(sizes) if sizes else 0
+
+
+def candidate_bytes(min_bytes: int) -> int:
+    """The bytes the guard should require free for one more version dir.
+
+    The design (NF-12, §6.2) is "insufficient free space to stage a FULL version
+    dir", so the requirement is the largest existing version dir — known from the
+    tree — floored by ``min_bytes`` as a backstop for a fresh or tiny tree.
+    """
+    return max(largest_version_bytes(), min_bytes)
+
+
+def has_room_for(min_bytes: int) -> bool:
+    """True when the tree's filesystem has room for one more full version dir.
+
+    The free-space refusal (NF-12, mechanism §6.2): a node with no room to stage
+    a full version dir refuses the update rather than half-staging. The
+    requirement is ``candidate_bytes(min_bytes)`` — the largest existing version
+    dir, floored by ``min_bytes`` — not merely a fixed floor.
+    """
+    return _free_bytes() >= candidate_bytes(min_bytes)
+
+
+@dataclass(frozen=True)
+class Preflight:
+    """The supervisor's answer to "may this node take one more version dir?"."""
+
+    ok: bool
+    reason: str
+    free_bytes: int
+    required_bytes: int
+    versions: int
+    reclaimable: int
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "reason": self.reason,
+            "free_bytes": self.free_bytes,
+            "required_bytes": self.required_bytes,
+            "versions": self.versions,
+            "reclaimable": self.reclaimable,
+        }
+
+
+def preflight(min_free_bytes: int) -> Preflight:
+    """Whether the node can stage ONE more version dir, read-only.
+
+    The fleet path calls this **before** it creates anything, so a refusal is
+    early and the supervisor owns the policy — the same room requirement the STAGE
+    check uses (one policy, one place). Measures and decides; creates nothing.
+
+    The one refusal is **room**: the filesystem must have ``candidate_bytes`` free
+    for the candidate's contents (NF-12). Retention is **not** a refusal — a real
+    switch always brings the tree within its bound by reclaiming, so a small tree
+    has *more* headroom, not less. ``reclaimable`` is reported for observability;
+    it does not affect the verdict.
+
+    ``reclaimable`` is the count of existing dirs that could be removed while
+    protecting the two versions a switch holds: the candidate (not yet created)
+    and whatever is current right now.
+    """
+    free = _free_bytes()
+    required = candidate_bytes(min_free_bytes)
+    versions = list_versions()
+    current = selected()
+    # A real switch reclaims with `protect = {candidate, current-now}` — the
+    # candidate does not exist yet, so among EXISTING dirs only current is
+    # protected. (After the switch, today's current becomes the last good, which
+    # is why the two-versions-retained rule holds; but at preflight time the
+    # second protected slot is the not-yet-staged candidate, not another existing
+    # dir.) So every existing dir but current is reclaimable.
+    protected = {os.path.realpath(current)} if current is not None else set()
+    reclaimable = sum(1 for v in versions if os.path.realpath(v) not in protected)
+    # Retention is NOT a refusal here. A real switch always satisfies its bound:
+    # after the candidate lands, `reclaim` removes reclaimable dirs down to the
+    # configured keep, and since every existing dir but current is reclaimable the
+    # tree always reaches `min(N+1, keep) <= keep`. So retention cannot make an
+    # update fail; refusing on it would reject exactly the trees with the most
+    # headroom (a small tree under a larger bound). `reclaimable` is reported for
+    # observability, not as a gate.
+    if free < required:
+        return Preflight(
+            ok=False,
+            reason=(
+                f"insufficient free space: {free} < {required} bytes"
+                " (one version dir, floored at the minimum)"
+            ),
+            free_bytes=free,
+            required_bytes=required,
+            versions=len(versions),
+            reclaimable=reclaimable,
+        )
+    return Preflight(
+        ok=True,
+        reason="room for one more version dir is available",
+        free_bytes=free,
+        required_bytes=required,
+        versions=len(versions),
+        reclaimable=reclaimable,
+    )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: manta_node
-Version: 0.6b5.dev705
+Version: 0.6b5.dev707
 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.dev705.dist-info → manta_node-0.6b5.dev707.dist-info}/RECORD

@@ -6,7 +6,7 @@ manta_node/task_manager.py,sha256=xRE-yKdUW0FFR8vtX1jDwl1AxTbqVD_JS7QVR62GA00,38
 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=Avtgxf4CTYxrwjUmb8TM92DAZRNRqrzV-eNId81M60o,275
+manta_node/cli/_version_generated.py,sha256=oq-vrYUSYqZEeiOos3Fqzj9GAI7ShLAmLb-7xD8MTio,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
@@ -56,14 +56,14 @@ manta_node/supervisor/__init__.py,sha256=kgdoNce1tM4e7jvdxkdmnNJV1L92-NI2cRfYSdm
 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/lifecycle.py,sha256=SA-xJqlxwbLa37fvp0W_YbUZbrRz9vQJDpg6vvuokpI,10303
+manta_node/supervisor/process.py,sha256=N5WvNCJnJR3c6I4uqBPPFqgEdCI9rFulHyGem9Shc-I,19155
 manta_node/supervisor/records.py,sha256=fUlL1SfmWpGnCbJ9956cuy0H3a7-aEF-B-naqbJiYoU,6405
 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,,
+manta_node/supervisor/switch.py,sha256=iWLukvuxynK3NU26iIk0qhkwrRPUyJuutV67QA3aLO8,16732
+manta_node-0.6b5.dev707.dist-info/licenses/LICENSE,sha256=9mBgLhiB9goQPQjg9XQJ6FjgVxYw9Q8lyOZYkPGwF_c,34484
+manta_node-0.6b5.dev707.dist-info/METADATA,sha256=uOmOaIVFbJllDFQMjCOr4zfNlYc-Qq9V4VaBk6uHYDg,4231
+manta_node-0.6b5.dev707.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+manta_node-0.6b5.dev707.dist-info/entry_points.txt,sha256=uCwggRApalLEsYs1YxwTBN0-e9oMJAkMoBp01HaSdoY,110
+manta_node-0.6b5.dev707.dist-info/top_level.txt,sha256=nbT5J5WETuXM9UPoQckl29uUOq8wMYdRb9QDx5kAFeo,11
+manta_node-0.6b5.dev707.dist-info/RECORD,,