fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/contracts.py

@@ -0,0 +1,307 @@
+"""Strict, deterministic contracts for subscription genesis planning."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from fdai_service_contracts.catalog_canonical import canonical_bytes as canonical_bytes
+from fdai_service_contracts.catalog_canonical import canonical_digest as canonical_digest
+
+_ID = re.compile(r"^[a-z][a-z0-9._-]{0,127}$")
+_ENVIRONMENTS = frozenset({"dev", "staging", "prod"})
+_CONNECTIVITY = frozenset({"online", "offline"})
+_HOSTS = frozenset({"existing-host", "managed-vm"})
+_TRANSPORTS = frozenset({"manual"})
+_ACCESS_METHODS = frozenset({"internal_ssh", "temporary_public_ssh", "bastion", "run_command"})
+
+
+class ApprovalClass(StrEnum):
+    """Approval strength required by one manifest entry."""
+
+    STANDARD = "standard"
+    HIGH_IMPACT = "high-impact"
+
+
+@dataclass(frozen=True, slots=True)
+class ProvisionProfile:
+    """Secret-free desired state selected by an operator."""
+
+    environment: str
+    region: str
+    target_binding: str
+    connectivity: str
+    host: str
+    transport: str
+    access_method: str
+    shadow_only: bool
+    approval_quorum: int
+    monthly_cost_ceiling: int
+
+    def __post_init__(self) -> None:
+        if self.environment not in _ENVIRONMENTS:
+            raise ValueError("environment is unsupported")
+        if _ID.fullmatch(self.region) is None:
+            raise ValueError("region MUST be a lowercase stable identifier")
+        if re.fullmatch(r"[0-9a-f]{64}", self.target_binding) is None:
+            raise ValueError("target_binding MUST be a lowercase SHA-256")
+        if self.connectivity not in _CONNECTIVITY:
+            raise ValueError("connectivity is unsupported")
+        if self.host not in _HOSTS:
+            raise ValueError("host is unsupported")
+        if self.transport not in _TRANSPORTS:
+            raise ValueError("transport is unsupported")
+        if self.access_method not in _ACCESS_METHODS:
+            raise ValueError("access_method is unsupported")
+        if not self.shadow_only:
+            raise ValueError("subscription genesis MUST start shadow-only")
+        if self.approval_quorum < 1:
+            raise ValueError("approval_quorum MUST be positive")
+        if self.monthly_cost_ceiling < 0:
+            raise ValueError("monthly_cost_ceiling MUST be non-negative")
+
+    @classmethod
+    def from_mapping(cls, value: Mapping[str, object]) -> ProvisionProfile:
+        """Decode a profile and reject unknown or missing fields."""
+
+        expected = {
+            "schema_version",
+            "environment",
+            "region",
+            "target_binding",
+            "connectivity",
+            "host",
+            "transport",
+            "access_method",
+            "shadow_only",
+            "approval_quorum",
+            "monthly_cost_ceiling",
+        }
+        _require_exact_keys(value, expected, "provision profile")
+        if value["schema_version"] != "fdai.provision-profile.v1":
+            raise ValueError("provision profile schema_version is unsupported")
+        return cls(
+            environment=_text(value, "environment"),
+            region=_text(value, "region"),
+            target_binding=_text(value, "target_binding"),
+            connectivity=_text(value, "connectivity"),
+            host=_text(value, "host"),
+            transport=_text(value, "transport"),
+            access_method=_text(value, "access_method"),
+            shadow_only=_bool(value, "shadow_only"),
+            approval_quorum=_int(value, "approval_quorum"),
+            monthly_cost_ceiling=_int(value, "monthly_cost_ceiling"),
+        )
+
+    def to_mapping(self) -> dict[str, object]:
+        """Return the canonical JSON-compatible profile."""
+
+        return {
+            "schema_version": "fdai.provision-profile.v1",
+            "environment": self.environment,
+            "region": self.region,
+            "target_binding": self.target_binding,
+            "connectivity": self.connectivity,
+            "host": self.host,
+            "transport": self.transport,
+            "access_method": self.access_method,
+            "shadow_only": self.shadow_only,
+            "approval_quorum": self.approval_quorum,
+            "monthly_cost_ceiling": self.monthly_cost_ceiling,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ManifestEntry:
+    """One finite, dependency-ordered provisioning responsibility."""
+
+    entry_id: str
+    owner: str
+    desired_state: str
+    prerequisites: tuple[str, ...]
+    approval_class: ApprovalClass
+    idempotency_key: str
+    timeout_seconds: int
+    no_progress_seconds: int
+    rollback_ref: str
+    observer: str
+
+    def __post_init__(self) -> None:
+        for label, value in (
+            ("entry_id", self.entry_id),
+            ("owner", self.owner),
+            ("desired_state", self.desired_state),
+            ("idempotency_key", self.idempotency_key),
+            ("rollback_ref", self.rollback_ref),
+            ("observer", self.observer),
+        ):
+            if _ID.fullmatch(value) is None:
+                raise ValueError(f"{label} MUST be a lowercase stable identifier")
+        if len(set(self.prerequisites)) != len(self.prerequisites):
+            raise ValueError("manifest prerequisites MUST be unique")
+        if any(_ID.fullmatch(item) is None for item in self.prerequisites):
+            raise ValueError("manifest prerequisites MUST be stable identifiers")
+        if self.entry_id in self.prerequisites:
+            raise ValueError("manifest entry cannot depend on itself")
+        if self.timeout_seconds < 1:
+            raise ValueError("timeout_seconds MUST be positive")
+        if not 1 <= self.no_progress_seconds <= self.timeout_seconds:
+            raise ValueError("no_progress_seconds MUST be within the stage timeout")
+
+    def to_mapping(self) -> dict[str, object]:
+        """Return canonical entry data."""
+
+        return {
+            "entry_id": self.entry_id,
+            "owner": self.owner,
+            "desired_state": self.desired_state,
+            "prerequisites": list(self.prerequisites),
+            "approval_class": self.approval_class.value,
+            "idempotency_key": self.idempotency_key,
+            "timeout_seconds": self.timeout_seconds,
+            "no_progress_seconds": self.no_progress_seconds,
+            "rollback_ref": self.rollback_ref,
+            "observer": self.observer,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class SubscriptionProvisioningManifest:
+    """Finite manifest whose digest seals one local plan."""
+
+    source_commit: str
+    profile_digest: str
+    entries: tuple[ManifestEntry, ...]
+
+    def __post_init__(self) -> None:
+        if re.fullmatch(r"[0-9a-f]{40}", self.source_commit) is None:
+            raise ValueError("source_commit MUST be a lowercase 40-character SHA")
+        if re.fullmatch(r"[0-9a-f]{64}", self.profile_digest) is None:
+            raise ValueError("profile_digest MUST be a lowercase SHA-256")
+        if not self.entries:
+            raise ValueError("provisioning manifest MUST contain entries")
+        ids = tuple(entry.entry_id for entry in self.entries)
+        if len(ids) != len(set(ids)):
+            raise ValueError("provisioning manifest entry ids MUST be unique")
+        known = set(ids)
+        for entry in self.entries:
+            unknown = set(entry.prerequisites) - known
+            if unknown:
+                raise ValueError(f"manifest entry {entry.entry_id!r} has unknown prerequisites")
+        _assert_acyclic(self.entries)
+
+    @property
+    def digest(self) -> str:
+        """Return the replay-stable manifest digest."""
+
+        return canonical_digest(self.to_mapping())
+
+    def to_mapping(self) -> dict[str, object]:
+        """Return canonical manifest data."""
+
+        return {
+            "schema_version": "fdai.subscription-provisioning-manifest.v1",
+            "source_commit": self.source_commit,
+            "profile_digest": self.profile_digest,
+            "entries": [entry.to_mapping() for entry in self.entries],
+        }
+
+
+def _assert_acyclic(entries: Sequence[ManifestEntry]) -> None:
+    by_id = {entry.entry_id: entry for entry in entries}
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(entry_id: str) -> None:
+        if entry_id in visiting:
+            raise ValueError("provisioning manifest dependency cycle detected")
+        if entry_id in visited:
+            return
+        visiting.add(entry_id)
+        for dependency in by_id[entry_id].prerequisites:
+            visit(dependency)
+        visiting.remove(entry_id)
+        visited.add(entry_id)
+
+    for key in sorted(by_id):
+        visit(key)
+
+
+def _require_exact_keys(
+    value: Mapping[str, object],
+    expected: set[str],
+    label: str,
+) -> None:
+    if set(value) != expected:
+        raise ValueError(f"{label} fields do not match the schema")
+
+
+def _text(value: Mapping[str, object], field: str) -> str:
+    item = value[field]
+    if not isinstance(item, str):
+        raise ValueError(f"{field} MUST be a string")
+    return item
+
+
+def _bool(value: Mapping[str, object], field: str) -> bool:
+    item = value[field]
+    if not isinstance(item, bool):
+        raise ValueError(f"{field} MUST be a boolean")
+    return item
+
+
+def _int(value: Mapping[str, object], field: str) -> int:
+    item = value[field]
+    if isinstance(item, bool) or not isinstance(item, int):
+        raise ValueError(f"{field} MUST be an integer")
+    return item
+
+
+def load_json_object(
+    data: bytes, *, label: str, max_bytes: int = 1_048_576, strict: bool = False
+) -> dict[str, Any]:
+    """Decode one bounded JSON object."""
+
+    if not data or len(data) > max_bytes:
+        raise ValueError(f"{label} is empty or exceeds its size limit")
+    try:
+        value = (
+            json.loads(
+                data.decode("utf-8"),
+                object_pairs_hook=_unique_json_object,
+                parse_constant=_reject_json_constant,
+                parse_float=_finite_json_float,
+            )
+            if strict
+            else json.loads(data)
+        )
+    except (ValueError, RecursionError) as exc:
+        raise ValueError(f"{label} is not valid JSON") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} MUST be a JSON object")
+    return value
+
+
+def _unique_json_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON field")
+        result[key] = value
+    return result
+
+
+def _reject_json_constant(value: str) -> object:
+    raise ValueError("non-finite JSON number")
+
+
+def _finite_json_float(value: str) -> float:
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError("non-finite JSON number")
+    return number

fdai_deployment_cli/control_package.py

@@ -0,0 +1,140 @@
+"""Verify one signed deployment-control wheelhouse for managed-host execution.
+
+The complete kit keeps its signed runtime payload: images, Terraform bundle, toolchain, and
+Console. A control package replaces only the managed-host ``fdai-deployment-cli`` installation,
+so a deployment-control repair needs a new signed wheelhouse instead of a new complete kit.
+The only package guarantee is one detached Ed25519 signature over ``SHA256SUMS``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import stat
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from fdai_deployment_cli.trust_roots import deployment_release_root_pem
+
+PACKAGE_ROOT = "package"
+_SUMS = "SHA256SUMS"
+_SIGNATURE = "SHA256SUMS.sig"
+_REQUIREMENTS = "requirements.txt"
+_SUM_LINE = re.compile(r"([0-9a-f]{64})  ([A-Za-z0-9._+-]+(?:/[A-Za-z0-9._+-]+)*)")
+_REQUIREMENT = re.compile(r"fdai-deployment-cli==([0-9]+\.[0-9]+\.[0-9]+)\n")
+_MAX_ARCHIVE_BYTES = 128 * 1024 * 1024
+_MAX_MEMBER_BYTES = 64 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ControlPackage:
+    """A locally verified signed wheelhouse and the digests that bind it to one run."""
+
+    archive: Path
+    archive_digest: str
+    sums_digest: str
+    version: str
+
+
+def verify_control_package(archive: Path, *, public_key_pem: bytes | None = None) -> ControlPackage:
+    """Verify signature, exact file set, and digests of one control-package archive.
+
+    Raises ``ValueError`` without secret or path values when the archive is not a regular
+    file, contains links or unsafe paths, lacks a valid signature, lists a different file set,
+    or does not install exactly one pinned ``fdai-deployment-cli`` version.
+    """
+
+    try:
+        details = archive.lstat()
+    except OSError as exc:
+        raise ValueError("control package archive is unavailable") from exc
+    if not stat.S_ISREG(details.st_mode) or details.st_size > _MAX_ARCHIVE_BYTES:
+        raise ValueError("control package archive must be a bounded regular file")
+    payload = archive.read_bytes()
+    files = _read_members(archive)
+    sums = files.pop(_SUMS, None)
+    signature = files.pop(_SIGNATURE, None)
+    if sums is None or signature is None:
+        raise ValueError("control package signature files are missing")
+    key = load_pem_public_key(public_key_pem or deployment_release_root_pem())
+    if not isinstance(key, Ed25519PublicKey):
+        raise ValueError("control package trust root must be Ed25519")
+    try:
+        key.verify(signature, sums)
+    except InvalidSignature as exc:
+        raise ValueError("control package signature is invalid") from exc
+    listed = _parse_sums(sums)
+    if set(listed) != set(files):
+        raise ValueError("control package file set differs from SHA256SUMS")
+    for relative, expected in listed.items():
+        if hashlib.sha256(files[relative]).hexdigest() != expected:
+            raise ValueError("control package file digest differs from SHA256SUMS")
+    requirement = _REQUIREMENT.fullmatch(files.get(_REQUIREMENTS, b"").decode("ascii", "replace"))
+    if requirement is None:
+        raise ValueError("control package must pin exactly fdai-deployment-cli")
+    version = requirement.group(1)
+    cli_wheels = [
+        name
+        for name in files
+        if name.startswith("wheels/fdai_deployment_cli-") and name.endswith(".whl")
+    ]
+    if cli_wheels != [f"wheels/fdai_deployment_cli-{version}-py3-none-any.whl"]:
+        raise ValueError("control package must contain exactly the pinned CLI wheel")
+    return ControlPackage(
+        archive=archive,
+        archive_digest=hashlib.sha256(payload).hexdigest(),
+        sums_digest=hashlib.sha256(sums).hexdigest(),
+        version=version,
+    )
+
+
+def _read_members(archive: Path) -> dict[str, bytes]:
+    """Read regular package members, rejecting links, devices, and escaping paths."""
+
+    files: dict[str, bytes] = {}
+    try:
+        with tarfile.open(archive, mode="r:gz") as bundle:
+            for member in bundle:
+                path = PurePosixPath(member.name)
+                if path.is_absolute() or ".." in path.parts or not path.parts:
+                    raise ValueError("control package member path is unsafe")
+                if path.parts[0] != PACKAGE_ROOT:
+                    raise ValueError("control package member is outside the package root")
+                if member.isdir():
+                    continue
+                if not member.isreg() or member.size > _MAX_MEMBER_BYTES:
+                    raise ValueError("control package member must be a bounded regular file")
+                relative = PurePosixPath(*path.parts[1:]).as_posix()
+                if relative in files or relative == ".":
+                    raise ValueError("control package member is duplicated")
+                extracted = bundle.extractfile(member)
+                if extracted is None:
+                    raise ValueError("control package member is unreadable")
+                files[relative] = extracted.read()
+    except (OSError, tarfile.TarError, EOFError) as exc:
+        raise ValueError("control package archive is unreadable") from exc
+    return files
+
+
+def _parse_sums(sums: bytes) -> dict[str, str]:
+    try:
+        text = sums.decode("ascii")
+    except UnicodeDecodeError as exc:
+        raise ValueError("control package SHA256SUMS is not ASCII") from exc
+    listed: dict[str, str] = {}
+    for line in text.splitlines():
+        match = _SUM_LINE.fullmatch(line)
+        if match is None or match.group(2) in listed:
+            raise ValueError("control package SHA256SUMS is malformed")
+        listed[match.group(2)] = match.group(1)
+    if not listed:
+        raise ValueError("control package SHA256SUMS is empty")
+    return listed
+
+
+__all__ = ["PACKAGE_ROOT", "ControlPackage", "verify_control_package"]

fdai_deployment_cli/deadline_transport.py

@@ -0,0 +1,70 @@
+"""Bound an existing managed-host transport to one deployment deadline."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol
+
+from fdai_deployment_cli.deployment_deadline import DeploymentDeadline
+
+
+class DeploymentTransport(Protocol):
+    """Existing authenticated transport; this wrapper never chooses identity or target."""
+
+    def ssh(
+        self, remote_arguments: Sequence[str], *, timeout: int, input_text: str | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        """Run the unchanged remote command within the supplied process limit."""
+        ...
+
+    def copy_to(self, source: Path, destination: str, *, timeout: int) -> None:
+        """Copy the unchanged private file within the supplied process limit."""
+        ...
+
+
+class DeadlineTransport:
+    """Clamp every command and copy to the current budget without adding retries.
+
+    The caller still owns the underlying tunnel's context and cleanup. An operation
+    returning after expiry cannot advance the next stage or produce a ready receipt.
+    """
+
+    def __init__(
+        self,
+        transport: DeploymentTransport,
+        deadline: DeploymentDeadline,
+        *,
+        host_program: str | None = None,
+    ) -> None:
+        self._transport = transport
+        self._deadline = deadline
+        self.host_program = host_program
+
+    def ssh(
+        self, remote_arguments: Sequence[str], *, timeout: int, input_text: str | None = None
+    ) -> subprocess.CompletedProcess[str]:
+        """Preserve command/stdin while enforcing the current deadline before and after I/O."""
+
+        remaining = self._deadline.remaining(timeout)
+        try:
+            result = self._transport.ssh(remote_arguments, timeout=remaining, input_text=input_text)
+        except (OSError, subprocess.SubprocessError):
+            raise ValueError(
+                "standalone managed-host command failed; inspect retained evidence before recovery"
+            ) from None
+        self._deadline.remaining()
+        return result
+
+    def copy_to(self, source: Path, destination: str, *, timeout: int) -> None:
+        """Preserve transfer paths while enforcing the current deadline before and after I/O."""
+
+        remaining = self._deadline.remaining(timeout)
+        try:
+            self._transport.copy_to(source, destination, timeout=remaining)
+        except (OSError, subprocess.SubprocessError):
+            raise ValueError(
+                "standalone managed-host transfer failed; inspect retained evidence before recovery"
+            ) from None
+        self._deadline.remaining()

fdai_deployment_cli/deployment_cost.py

@@ -0,0 +1,131 @@
+"""Inspect the AKS compute portion of deployment cost without claiming a complete budget."""
+
+from __future__ import annotations
+
+from decimal import Decimal, ROUND_CEILING
+from pathlib import Path
+
+from fdai_deployment_cli.azure_retail_prices import read_linux_vm_price
+from fdai_deployment_cli.contracts import canonical_digest, load_json_object
+from fdai_deployment_cli.deployment_deadline import DeploymentDeadline
+from fdai_deployment_cli.private_output import read_private_bytes
+from fdai_deployment_cli.runtime_profile import RuntimeDeploymentProfile
+
+# Covers the default AKS profile (8 Standard_D4ds_v4 nodes at most) at public US rates.
+DEFAULT_MONTHLY_COST_CEILING = 1500
+
+
+def resolve_monthly_cost_ceiling(requested: int | None, *, retained: tuple[Path, ...]) -> int:
+    """Keep a retained run's ceiling so resume, recovery and teardown match its intent.
+
+    Only a run with no retained record receives the current default.
+    """
+    if requested is not None:
+        return requested
+    for path in retained:
+        if not path.is_file():
+            continue
+        value = load_json_object(
+            read_private_bytes(path, max_bytes=1_048_576), label=path.name
+        ).get("monthly_cost_ceiling")
+        if type(value) is not int or value < 0:
+            raise ValueError(
+                f"{path.name} records no usable monthly_cost_ceiling; pass --monthly-cost-ceiling"
+            )
+        return value
+    return DEFAULT_MONTHLY_COST_CEILING
+
+
+def resolve_work_dir_monthly_cost_ceiling(
+    requested: int | None, *, work_dir: Path, adopted_foundation: Path | None
+) -> int:
+    """Resolve the ceiling from the records a run in ``work_dir`` retains, in precedence order."""
+    retained: tuple[Path, ...] = (
+        work_dir / "source-intent.json",
+        work_dir / "run/profile.json",
+        work_dir / "foundation/profile.json",
+    )
+    if adopted_foundation is not None:
+        retained = (*retained, adopted_foundation / "profile.json")
+    return resolve_monthly_cost_ceiling(requested, retained=retained)
+
+
+def inspect_aks_compute_cost(
+    *,
+    profile: RuntimeDeploymentProfile,
+    region: str,
+    monthly_cost_ceiling: int,
+    timeout_seconds: int = 120,
+) -> dict[str, object]:
+    """Price maximum steady-state nodes for 730 hours; unpriced components remain explicit.
+
+    This is a partial projection, not a quote for the installation. It may block
+    an over-budget profile but cannot approve one, reserve capacity or cap bills.
+    """
+    if (
+        profile.runtime_platform.value != "aks"
+        or type(monthly_cost_ceiling) is not int
+        or monthly_cost_ceiling <= 0
+    ):
+        raise ValueError("AKS cost review requires an AKS profile and a positive ceiling")
+    deadline = DeploymentDeadline(timeout_seconds)
+    quotes = {
+        sku: read_linux_vm_price(sku=sku, region=region, timeout_seconds=deadline.remaining(90))
+        for sku in sorted({profile.system_node_sku, profile.user_node_sku})
+    }
+    lines = []
+    for pool, sku, count in (
+        ("system", profile.system_node_sku, profile.system_node_count),
+        ("user", profile.user_node_sku, profile.user_node_max_count),
+    ):
+        hourly = Decimal(str(quotes[sku]["hourly_rate"]))
+        monthly = (hourly * count * 730).quantize(Decimal("0.01"), rounding=ROUND_CEILING)
+        lines.append(
+            {
+                "pool": pool,
+                "sku": sku,
+                "node_count": count,
+                "hours": 730,
+                "hourly_rate_usd": str(hourly),
+                "monthly_estimate_usd": str(monthly),
+            }
+        )
+    total = sum((Decimal(str(line["monthly_estimate_usd"])) for line in lines), Decimal(0))
+    exceeded = total > monthly_cost_ceiling
+    result: dict[str, object] = {
+        "schema_version": "fdai.deployment-compute-cost.v1",
+        "stage": "cost-review",
+        "state": "blocked" if exceeded else "partial",
+        "reason_code": "aks_compute_exceeds_monthly_ceiling"
+        if exceeded
+        else "whole_installation_cost_incomplete",
+        "runtime_profile_digest": profile.digest,
+        "region": region,
+        "monthly_cost_ceiling_usd": monthly_cost_ceiling,
+        "monthly_compute_estimate_usd": str(total),
+        "lines": lines,
+        "quotes": quotes,
+        "excluded_costs": [
+            "surge-and-setup",
+            "foundation",
+            "aks-control-plane",
+            "disks",
+            "database",
+            "network",
+            "registry",
+            "storage",
+            "monitoring",
+            "event-bus",
+            "models",
+            "taxes",
+        ],
+        "whole_installation_cost_verified": False,
+        "setup_cost_verified": False,
+        "billing_cap_enforced": False,
+        "apply_authorized": False,
+        "deployment_ready": False,
+        "mutation_performed": False,
+    }
+    deadline.remaining()
+    result["receipt_digest"] = canonical_digest(result)
+    return result

fdai_deployment_cli/deployment_deadline.py

@@ -0,0 +1,28 @@
+"""Monotonic remaining-budget checks for standalone deployment stage scheduling."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+
+
+class DeploymentDeadline:
+    """Keep one invocation budget; expiry cannot authorize another stage or ready receipt.
+
+    This scheduler guard does not interrupt a running command. Callers pass its current
+    remaining budget to their bounded process or transport and preserve its cleanup path.
+    """
+
+    def __init__(self, seconds: int, *, clock: Callable[[], float] | None = None) -> None:
+        if type(seconds) is not int or seconds <= 0:
+            raise ValueError("standalone deployment timeout must be a positive integer")
+        self._clock = clock or time.monotonic
+        self._expires = self._clock() + seconds
+
+    def remaining(self, maximum: int | None = None) -> int:
+        """Return whole seconds left, capped by the stage limit, or stop on expiry."""
+
+        remaining = int(self._expires - self._clock())
+        if remaining <= 0:
+            raise TimeoutError("standalone deployment deadline has no remaining budget")
+        return remaining if maximum is None else min(maximum, remaining)