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

fdai_deployment_cli/runtime_stage.py

@@ -0,0 +1,82 @@
+"""Stage local runtime release bytes before the enclosing kit is signed."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from fdai_deployment_cli.offline_kit import (
+    _MAX_FILE_BYTES,
+    MANIFEST_NAME,
+    SIGNATURE_NAME,
+    _copy_verified_file,
+    _scan_tree,
+    _sha256_nofollow,
+)
+from fdai_deployment_cli.private_output import _open_private_parent
+from fdai_deployment_cli.runtime_release import load_runtime_release, validate_runtime_images
+
+
+def stage_runtime_release(
+    source: Path,
+    kit: Path,
+    *,
+    deployment_bundle: Path,
+    source_commit: str,
+    platform_tag: str,
+) -> str:
+    """Copy a complete local inventory without registry access or image execution.
+
+    V2 inventories also require valid service and ClamAV OCI content. Legacy v1
+    remains stageable for inspection, not complete preparation. This is release
+    assembly, not a signature or production-eligibility check. The caller supplies
+    a private kit directory and signs it after staging.
+    """
+    directory = _open_private_parent(kit / "runtime")
+    os.close(directory)
+    if any(
+        (kit / name).exists() or (kit / name).is_symlink()
+        for name in (MANIFEST_NAME, SIGNATURE_NAME)
+    ):
+        raise ValueError("runtime staging requires an unsigned kit")
+    release = load_runtime_release(
+        source,
+        expected_source_commit=source_commit,
+        expected_platform_tag=platform_tag,
+    )
+    bundle_details = deployment_bundle.lstat()
+    if bundle_details.st_size > _MAX_FILE_BYTES:
+        raise ValueError("deployment bundle exceeds the offline kit file size limit")
+    if release.deployment_bundle_sha256 != _sha256_nofollow(
+        deployment_bundle, expected=bundle_details
+    ):
+        raise ValueError("runtime inventory does not match the deployment bundle")
+    destination = kit / "runtime"
+    if destination.exists() or destination.is_symlink():
+        raise ValueError("runtime release destination already exists")
+    digests, sizes, _total = _scan_tree(source / "runtime")
+    with TemporaryDirectory(prefix=".runtime-", dir=kit) as temporary:
+        staging = Path(temporary)
+        payload = staging / "runtime"
+        payload.mkdir(mode=0o700)
+        for relative, digest in digests.items():
+            target = payload / relative
+            target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            _copy_verified_file(
+                source / "runtime" / relative,
+                target,
+                expected_digest=digest,
+                expected_size=sizes[relative],
+            )
+        copied = load_runtime_release(
+            staging,
+            expected_source_commit=source_commit,
+            expected_platform_tag=platform_tag,
+        )
+        if copied.digest != release.digest:
+            raise ValueError("runtime inventory changed during staging")
+        if copied.schema_version in {"fdai.runtime-release.v2", "fdai.runtime-release.v3"}:
+            validate_runtime_images(staging, copied)
+        payload.rename(destination)
+    return copied.digest

fdai_deployment_cli/runtime_support_installation.py

@@ -0,0 +1,215 @@
+"""Install verified runtime support from one signed aggregate lock."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.contracts import canonical_digest, load_json_object
+from fdai_deployment_cli.offline_kit import _read_regular as _read_kit_regular
+from fdai_deployment_cli.private_output import write_private_output
+from fdai_deployment_cli.standalone_host_state import private_json as _private_json
+from fdai_deployment_cli.support_install import (
+    _validate_requirements as _validate_support_requirements,
+)
+
+_DIGEST = re.compile(r"[0-9a-f]{64}")
+
+
+def install_runtime_support(
+    work_dir: Path, *, artifact_root: Path, kit_manifest_digest: str
+) -> None:
+    """Install the admitted hashed support lock and verify resumable completion."""
+
+    if _DIGEST.fullmatch(kit_manifest_digest) is None:
+        raise ValueError("runtime migration support kit binding is invalid")
+    support = artifact_root / "support/python"
+    inventory_path = support / "inventory.json"
+    requirements = support / "requirements/support.txt"
+    try:
+        inventory_bytes = _read_kit_regular(inventory_path, 4 * 1024 * 1024)
+        requirement_bytes = _read_kit_regular(requirements, 8 * 1024 * 1024)
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise ValueError("runtime migration support contract is unavailable") from exc
+    inventory = load_json_object(
+        inventory_bytes,
+        label="runtime support inventory",
+        max_bytes=4 * 1024 * 1024,
+    )
+    _validate_support_requirements(requirement_bytes)
+    if (
+        inventory.get("schema_version") != "fdai.runtime-wheelhouse.v1"
+        or inventory.get("artifact_kind") != "local-runtime-wheelhouse"
+        or inventory.get("status") != "complete"
+        or inventory.get("support_requirements") != "requirements/support.txt"
+    ):
+        raise ValueError("runtime migration support inventory is incomplete")
+    files = _mapping(inventory.get("files"), "runtime support file inventory")
+    expected_versions: dict[str, str] = {}
+    requirement_lines = set(requirement_bytes.decode("utf-8").splitlines())
+    for field in ("packages", "support_packages"):
+        records = _mapping(inventory.get(field), f"runtime support {field}")
+        for name, item in records.items():
+            record = _mapping(item, f"runtime support package {name}")
+            version, wheel = record.get("version"), record.get("wheel")
+            digest = files.get(wheel) if isinstance(wheel, str) else None
+            normalized = re.sub(r"[-_.]+", "-", name.casefold())
+            if (
+                not normalized
+                or not isinstance(version, str)
+                or not isinstance(wheel, str)
+                or not isinstance(digest, str)
+                or _DIGEST.fullmatch(digest) is None
+                or f"{name}=={version} --hash=sha256:{digest}" not in requirement_lines
+                or normalized in expected_versions
+            ):
+                raise ValueError("runtime migration support package contract is invalid")
+            expected_versions[normalized] = version
+    wheels = sorted(support.rglob("*.whl"))
+    if not wheels or any(not wheel.is_file() or wheel.is_symlink() for wheel in wheels):
+        raise ValueError("runtime migration support wheelhouse is invalid")
+    locations = sorted({wheel.parent for wheel in wheels}, key=str)
+    if not 1 <= len(locations) <= 64:
+        raise ValueError("runtime migration support wheel locations are invalid")
+
+    environment = work_dir / "runtime-venv"
+    receipt_path = work_dir / "runtime-support-installation.json"
+    retained_environment = environment.exists() or environment.is_symlink()
+    retained_receipt = receipt_path.exists() or receipt_path.is_symlink()
+    if retained_environment or retained_receipt:
+        if not retained_environment or not retained_receipt:
+            raise ValueError("runtime migration support installation is incomplete")
+        receipt = _private_json(receipt_path, "runtime support installation receipt")
+        if (
+            receipt.get("schema_version") != "fdai.runtime-support-installation.v1"
+            or receipt.get("kit_manifest_digest") != kit_manifest_digest
+            or receipt.get("inventory_digest") != hashlib.sha256(inventory_bytes).hexdigest()
+            or receipt.get("requirements_digest") != hashlib.sha256(requirement_bytes).hexdigest()
+            or receipt.get("dependencies_verified") is not True
+        ):
+            raise ValueError("runtime migration support receipt differs")
+        readback_digest = _runtime_support_readback(
+            environment, expected_versions=expected_versions, work_dir=work_dir
+        )
+        if receipt.get("package_readback_digest") != readback_digest:
+            raise ValueError("runtime migration support package readback differs")
+        return
+
+    _run(
+        (sys.executable, "-m", "venv", str(environment)),
+        cwd=work_dir,
+        timeout=120,
+        reason="runtime migration environment creation failed",
+    )
+    links = tuple(
+        argument for location in locations for argument in ("--find-links", str(location))
+    )
+    _run(
+        (
+            str(environment / "bin/pip"),
+            "install",
+            "--no-index",
+            "--no-cache-dir",
+            "--only-binary",
+            ":all:",
+            "--require-hashes",
+            *links,
+            "--requirement",
+            str(requirements),
+        ),
+        cwd=work_dir,
+        timeout=900,
+        reason="runtime migration support installation failed",
+    )
+    readback_digest = _runtime_support_readback(
+        environment, expected_versions=expected_versions, work_dir=work_dir
+    )
+    write_private_output(
+        receipt_path,
+        json.dumps(
+            {
+                "schema_version": "fdai.runtime-support-installation.v1",
+                "kit_manifest_digest": kit_manifest_digest,
+                "inventory_digest": hashlib.sha256(inventory_bytes).hexdigest(),
+                "requirements_digest": hashlib.sha256(requirement_bytes).hexdigest(),
+                "package_readback_digest": readback_digest,
+                "dependencies_verified": True,
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+        + "\n",
+    )
+
+
+def _runtime_support_readback(
+    environment: Path, *, expected_versions: dict[str, str], work_dir: Path
+) -> str:
+    pip = str(environment / "bin/pip")
+    _run(
+        (pip, "check"),
+        cwd=work_dir,
+        timeout=120,
+        reason="runtime migration support dependency check failed",
+    )
+    try:
+        entries = json.loads(
+            _capture(
+                (pip, "list", "--format=json"),
+                cwd=work_dir,
+                timeout=120,
+                reason="runtime migration support package readback failed",
+            )
+        )
+    except json.JSONDecodeError as exc:
+        raise ValueError("runtime migration support package readback is invalid") from exc
+    if not isinstance(entries, list):
+        raise ValueError("runtime migration support package readback is invalid")
+    observed: dict[str, str] = {}
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise ValueError("runtime migration support package readback is invalid")
+        name, version = entry.get("name"), entry.get("version")
+        if not isinstance(name, str) or not isinstance(version, str):
+            raise ValueError("runtime migration support package readback is invalid")
+        normalized = re.sub(r"[-_.]+", "-", name.casefold())
+        if normalized in observed:
+            raise ValueError("runtime migration support package readback contains duplicates")
+        observed[normalized] = version
+    if any(observed.get(name) != version for name, version in expected_versions.items()):
+        raise ValueError("runtime migration support packages differ from the signed inventory")
+    return canonical_digest(observed)
+
+
+def _run(command: tuple[str, ...], *, cwd: Path, timeout: int, reason: str) -> None:
+    result = subprocess.run(command, cwd=cwd, check=False, capture_output=True, timeout=timeout)
+    if result.returncode != 0:
+        raise ValueError(reason)
+
+
+def _capture(command: tuple[str, ...], *, cwd: Path, timeout: int, reason: str) -> str:
+    result = subprocess.run(
+        command,
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        raise ValueError(reason)
+    return result.stdout
+
+
+def _mapping(value: object, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or any(not isinstance(key, str) for key in value):
+        raise ValueError(f"{label} is invalid")
+    return {str(key): item for key, item in value.items()}
+
+
+__all__ = ["install_runtime_support"]

fdai_deployment_cli/simulation.py

@@ -0,0 +1,80 @@
+"""Deterministic no-mutation rehearsal of the genesis state machine."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from fdai_deployment_cli.contracts import SubscriptionProvisioningManifest, canonical_digest
+from fdai_deployment_cli.state import (
+    GENESIS_HASH,
+    ProvisionEvent,
+    RunState,
+    append_event,
+    read_journal,
+)
+
+
+def rehearse(
+    manifest: SubscriptionProvisioningManifest,
+    *,
+    run_id: str,
+    journal: Path,
+    interrupt_after: str | None = None,
+    started_at: datetime | None = None,
+) -> tuple[ProvisionEvent, ...]:
+    """Rehearse remaining stages and optionally stop after one completed stage."""
+
+    events = read_journal(journal) if journal.exists() else ()
+    if events and events[-1].run_id != run_id:
+        raise ValueError("simulation run_id does not match the existing journal")
+    if events and events[-1].context_digest != manifest.digest:
+        raise ValueError("simulation manifest does not match the existing journal")
+    if events and events[-1].state is RunState.READY:
+        return events
+    known_stages = {entry.entry_id for entry in manifest.entries}
+    if interrupt_after is not None and interrupt_after not in known_stages:
+        raise ValueError("simulation interrupt stage is not in the manifest")
+    completed = {event.stage for event in events if event.state is RunState.COMPLETED}
+    previous_digest = events[-1].digest if events else GENESIS_HASH
+    sequence = len(events)
+    base = started_at or datetime.now(UTC)
+    for entry in manifest.entries:
+        if entry.entry_id in completed:
+            continue
+        sequence += 1
+        event = ProvisionEvent(
+            run_id=run_id,
+            context_digest=manifest.digest,
+            sequence=sequence,
+            stage=entry.entry_id,
+            attempt=1,
+            state=RunState.COMPLETED,
+            occurred_at=(base + timedelta(microseconds=sequence)).isoformat(),
+            previous_digest=previous_digest,
+            reason_code="simulation-only",
+            evidence_digest=canonical_digest(
+                {"mode": "simulation", "stage": entry.entry_id, "status": "completed"}
+            ),
+        )
+        append_event(journal, event)
+        previous_digest = event.digest
+        if entry.entry_id == interrupt_after:
+            return read_journal(journal)
+    sequence += 1
+    ready = ProvisionEvent(
+        run_id=run_id,
+        context_digest=manifest.digest,
+        sequence=sequence,
+        stage="system-readiness",
+        attempt=1,
+        state=RunState.READY,
+        occurred_at=(base + timedelta(microseconds=sequence)).isoformat(),
+        previous_digest=previous_digest,
+        reason_code="simulation-only",
+        evidence_digest=canonical_digest(
+            {"mode": "simulation", "stage": "system-readiness", "status": "ready"}
+        ),
+    )
+    append_event(journal, ready)
+    return read_journal(journal)