omnius 1.0.841 → 1.0.843

package/dist/scripts/rapid-computer-use/photon_service.py

@@ -0,0 +1,700 @@
+#!/usr/bin/env python3
+"""Host-staged local Moondream point service. Importing this file never loads CUDA.
+
+Idle -> host load marker -> exact raw checkpoint tensors resident on CUDA.
+Host placement statement/approval -> explicit engine activation (warmup counted).
+A new placement statement/approval then admits each bounded point request.
+"""
+import argparse
+import base64
+import binascii
+from contextlib import contextmanager
+import ctypes
+import hashlib
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import importlib.metadata
+import io
+import json
+import os
+from pathlib import Path
+import secrets
+import socket
+import stat
+import sys
+import threading
+import time
+
+import model_gate as gate
+import point_benchmark as points
+import laya_service as host
+import gpu_lease
+
+MODEL = "moondream3.1-9B-A2B"
+WEIGHTS_REVISION = "1da27e6c2d2f9118de14560df456881dc62d91f3"
+WEIGHTS_SHA256 = "26dde16af961d3a486c7b86b9a34fc8487be7917f7e62324b751400ef4d391b4"
+WEIGHTS_BYTES = 10505269576
+RUNTIME_REVISION = "80640639279b18b2da61b08c06c550f8eaab6596d6d15978fd56f76707462cb7"
+TOKENIZER_REVISION = "35192e10a54e36eabe0a7cc57a2c1aab371cafc5"
+TOKENIZER_SHA256 = "0512fdcac4a5f9e7746cbefce4a468dc93bf0f93f11e701b84f8b31bff199e9c"
+MAX_REQUEST_BYTES = 28 * 1024 * 1024
+MAX_PIXELS = 16_777_216
+POINT_DEADLINE = 45
+STAGE_DEADLINE = 240  # Less than the broker's 300-second pending window.
+REQUEST_READ_DEADLINE = 5
+REQUIREMENTS_SHA256 = "87c1184a8f60b09040a6480b0ec421d386ca7b9cbb5034bb9ffb402c3c7d5aa9"
+CUDA12_PACKAGE = "nvidia-cuda-runtime-cu12"
+CUDA12_VERSION = "12.9.79"
+CUDA12_SHA256 = "256e6409e4f06f618e1fb53d4844a6b81cdded1013afa8ade40c22f99eb133b7"
+CUDA12_BYTES = 741088
+CUDA12_REQUIREMENTS_SHA256 = "10852e9e96696e60210053304a2c202a3b5eee2c0dd4a07044e8ea10f7e9302d"
+CUDA12_REQUIREMENTS = gate.DEFAULT_LOCK.with_name("photon-cuda12-compatibility.requirements.txt")
+CUDA12_SYMBOLS = ("cudaLibraryLoadData", "cudaLibraryLoadFromFile", "cudaLibraryGetKernel", "cudaLibraryUnload")
+RUNTIME_PACKAGES = {"moondream": "2.6.1", "kestrel": "0.9.1",
+                    "kestrel-native": "0.1.8", "kestrel-kernels": "0.7.4",
+                    CUDA12_PACKAGE: CUDA12_VERSION,
+                    **{f"kestrel-kernels-bundle-{letter}": "0.7.4" for letter in "abcdefgh"}}
+
+
+def installed_runtime_paths():
+    """Inventory installed executable/data bytes without importing CUDA modules."""
+    paths = set()
+    for name in RUNTIME_PACKAGES:
+        distribution = importlib.metadata.distribution(name)
+        for item in distribution.files or ():
+            if str(item).endswith(".pyc") or "__pycache__" in Path(item).parts:
+                continue
+            path = Path(distribution.locate_file(item)).resolve(strict=True)
+            gate.require(path.is_file(), "runtime manifest contains a non-file entry")
+            paths.add(str(path))
+    return paths
+
+
+def validate_manifest(manifest):
+    gate.require(manifest.get("schema") == "omnius.computer-use.photon-checkpoint.v1"
+                 and manifest.get("weights_revision") == WEIGHTS_REVISION
+                 and manifest.get("runtime_revision") == RUNTIME_REVISION,
+                 "Photon manifest differs from reviewed immutable pins")
+    weights, tokenizer = manifest.get("weights", {}), manifest.get("tokenizer", {})
+    gate.require(weights.get("sha256") == WEIGHTS_SHA256 and weights.get("bytes") == WEIGHTS_BYTES,
+                 "exact Moondream checkpoint bytes are required")
+    gate.require(tokenizer.get("revision") == TOKENIZER_REVISION
+                 and tokenizer.get("sha256") == TOKENIZER_SHA256, "exact Starmie tokenizer required")
+    versions = manifest.get("versions", {})
+    for name, version in RUNTIME_PACKAGES.items():
+        gate.require(versions.get(name) == version, f"missing exact runtime pin: {name}")
+    gate.require(4 <= len(versions) <= 200, "bounded runtime dependency manifest required")
+    for name, version in versions.items():
+        gate.require(importlib.metadata.version(name) == version, f"runtime dependency changed: {name}")
+    files = manifest.get("runtime_files", {})
+    gate.require(isinstance(files, dict) and 10 <= len(files) <= 5000,
+                 "installed runtime file hashes are required")
+    gate.require(set(files) == installed_runtime_paths(), "installed runtime inventory changed")
+    for filename, sha in files.items():
+        path = Path(filename)
+        gate.require(path.is_absolute() and path.is_file()
+                     and isinstance(sha, str) and len(sha) == 64
+                     and host.file_sha256(path) == sha, "installed runtime file hash mismatch")
+    validate_cuda12_manifest(manifest)
+
+
+def installed_cuda12_path():
+    distribution = importlib.metadata.distribution(CUDA12_PACKAGE)
+    return Path(distribution.locate_file("nvidia/cuda_runtime/lib/libcudart.so.12")).resolve(strict=True)
+
+
+def validate_cuda12_manifest(manifest):
+    expected_path = str(installed_cuda12_path())
+    gate.require(manifest.get("cuda12_runtime") == {
+        "package": CUDA12_PACKAGE, "version": CUDA12_VERSION, "path": expected_path,
+        "sha256": CUDA12_SHA256, "bytes": CUDA12_BYTES}, "exact isolated CUDA12 runtime identity required")
+    gate.require(manifest.get("runtime_files", {}).get(expected_path) == CUDA12_SHA256
+                 and manifest.get("compatibility_requirements_sha256") == CUDA12_REQUIREMENTS_SHA256,
+                 "CUDA12 runtime must belong to the pinned installed inventory")
+
+
+def loaded_cuda12_paths():
+    paths = set()
+    for line in Path("/proc/self/maps").read_text().splitlines():
+        fields = line.split(maxsplit=5)
+        if len(fields) == 6 and fields[5].startswith("/") and "libcudart.so.12" in Path(fields[5]).name:
+            paths.add(str(Path(fields[5]).resolve()))
+    return paths
+
+
+def prepare_manifest(weights, tokenizer, requirements, compatibility_requirements=CUDA12_REQUIREMENTS):
+    """Build a host-local receipt using file I/O and package metadata only."""
+    with Path(requirements).open("rb") as stream:
+        raw = stream.read(32 * 1024 + 1)
+    gate.require(hashlib.sha256(raw).hexdigest() == REQUIREMENTS_SHA256,
+                 "exact frozen CPython3.12 dependency plan required")
+    with Path(compatibility_requirements).open("rb") as stream:
+        compatibility_raw = stream.read(32 * 1024 + 1)
+    gate.require(hashlib.sha256(compatibility_raw).hexdigest() == CUDA12_REQUIREMENTS_SHA256,
+                 "exact isolated CUDA12 compatibility dependency plan required")
+    versions = {}
+    for line in raw.decode().splitlines():
+        if line and not line.startswith("#"):
+            name, rest = line.split("==", 1)
+            versions[name] = rest.split()[0]
+    versions[CUDA12_PACKAGE] = CUDA12_VERSION
+    for path, sha, size in ((weights, WEIGHTS_SHA256, WEIGHTS_BYTES), (tokenizer, TOKENIZER_SHA256, None)):
+        pinned = PinnedFile(path, sha, size)
+        pinned.close()
+    manifest = {"schema": "omnius.computer-use.photon-checkpoint.v1",
+                "weights_revision": WEIGHTS_REVISION, "runtime_revision": RUNTIME_REVISION,
+                "weights": {"path": str(Path(weights).resolve()), "sha256": WEIGHTS_SHA256, "bytes": WEIGHTS_BYTES},
+                "tokenizer": {"path": str(Path(tokenizer).resolve()), "revision": TOKENIZER_REVISION,
+                              "sha256": TOKENIZER_SHA256}, "versions": versions,
+                "requirements_sha256": REQUIREMENTS_SHA256,
+                "compatibility_requirements_sha256": CUDA12_REQUIREMENTS_SHA256,
+                "cuda12_runtime": {"package": CUDA12_PACKAGE, "version": CUDA12_VERSION,
+                                   "path": str(installed_cuda12_path()), "sha256": CUDA12_SHA256,
+                                   "bytes": CUDA12_BYTES},
+                "runtime_files": {path: host.file_sha256(path) for path in sorted(installed_runtime_paths())}}
+    validate_manifest(manifest)
+    return manifest
+
+
+class PinnedFile:
+    """Keep the checked inode open; loading cannot follow a replaced pathname."""
+    def __init__(self, path, sha256, expected_bytes=None):
+        self.fd = os.open(Path(path).resolve(strict=True), os.O_RDONLY | os.O_NOFOLLOW)
+        try:
+            info = os.fstat(self.fd)
+            gate.require(stat.S_ISREG(info.st_mode), "checkpoint must be a regular file")
+            if expected_bytes is not None:
+                gate.require(info.st_size == expected_bytes, "checkpoint byte count changed")
+            self.identity = self.stat_identity(info)
+            self.sha256 = sha256
+            digest = hashlib.sha256()
+            with os.fdopen(os.dup(self.fd), "rb") as stream:
+                for block in iter(lambda: stream.read(8 * 1024 * 1024), b""):
+                    digest.update(block)
+            gate.require(digest.hexdigest() == sha256, "checkpoint/tokenizer SHA-256 mismatch")
+            gate.require(self.stat_identity(os.fstat(self.fd)) == self.identity,
+                         "pinned file changed while hashing")
+        except BaseException:
+            os.close(self.fd)
+            self.fd = None
+            raise
+
+    @staticmethod
+    def stat_identity(info):
+        return (info.st_dev, info.st_ino, info.st_nlink, info.st_size, info.st_mtime_ns, info.st_ctime_ns)
+
+    @property
+    def path(self):
+        return f"/proc/self/fd/{self.fd}"
+
+    def assert_unchanged(self):
+        gate.require(self.fd is not None and self.stat_identity(os.fstat(self.fd)) == self.identity,
+                     "pinned file changed after hashing")
+        # Timestamp granularity can miss an equal-sized rewrite in the same tick.
+        gate.require(host.file_sha256(self.path) == self.sha256
+                     and self.stat_identity(os.fstat(self.fd)) == self.identity,
+                     "pinned file bytes changed after hashing")
+
+    def close(self):
+        if self.fd is not None:
+            os.close(self.fd)
+            self.fd = None
+
+
+def validate_request(value, model):
+    gate.require(isinstance(value, dict) and set(value) == {"model", "object", "image_url"},
+                 "point request requires only model, object and image_url")
+    gate.require(value["model"] == model, "request model differs from resident model")
+    gate.require(isinstance(value["object"], str) and 0 < len(value["object"].strip()) <= 1000,
+                 "bounded nonempty point query required")
+    encoded = value["image_url"]
+    prefix = "data:image/png;base64,"
+    gate.require(isinstance(encoded, str) and encoded.startswith(prefix)
+                 and len(encoded) <= MAX_REQUEST_BYTES, "bounded inline PNG required; URLs are forbidden")
+    try:
+        raw = base64.b64decode(encoded[len(prefix):], validate=True)
+    except (ValueError, binascii.Error) as error:
+        raise gate.GateError("invalid PNG base64") from error
+    gate.require(0 < len(raw) <= points.MAX_IMAGE_BYTES, "PNG exceeds byte bound")
+    width, height = points.png_dimensions(raw)
+    gate.require(width * height <= MAX_PIXELS, "PNG exceeds pixel budget")
+    return {"model": model, "object": value["object"], "image_bytes": raw}
+
+
+def validate_answer(value):
+    gate.require(isinstance(value, dict) and set(value) == {"points"}
+                 and isinstance(value["points"], list) and len(value["points"]) <= 100,
+                 "invalid bounded point result")
+    for point in value["points"]:
+        gate.require(isinstance(point, dict) and set(point) == {"x", "y"}
+                     and all(points.number(point.get(key)) and 0 <= point[key] < 1 for key in ("x", "y")),
+                     "model point is not finite normalized coordinates")
+    return value
+
+
+class LocalPhotonAdapter:
+    def __init__(self, manifest, authorized):
+        validate_manifest(manifest)
+        self.authorized = authorized
+        self.weights_file = PinnedFile(manifest["weights"]["path"], WEIGHTS_SHA256, WEIGHTS_BYTES)
+        self.tokenizer_file = PinnedFile(manifest["tokenizer"]["path"], TOKENIZER_SHA256)
+        self.cuda12_file = PinnedFile(manifest["cuda12_runtime"]["path"], CUDA12_SHA256, CUDA12_BYTES)
+        self.cuda12_library = None
+        self.manifest, self.client, self.runtime = manifest, None, None
+        self.warmup_requests = self.warmup_completed = 0
+        os.environ.update(HF_HUB_OFFLINE="1", TRANSFORMERS_OFFLINE="1",
+                          HF_HUB_DISABLE_TELEMETRY="1", TOKENIZERS_PARALLELISM="false")
+        os.environ.pop("MOONDREAM_API_KEY", None)
+        host.deny_outbound_runtime_connections()
+        # These are the first CUDA-capable imports, after the host's load marker.
+        import torch
+        from safetensors.torch import load_file
+        gate.require(torch.cuda.is_available() and torch.cuda.device_count() == 1,
+                     "strict CUDA requires exactly one reserved visible GPU")
+        props = torch.cuda.get_device_properties(0)
+        gate.require("A100" in props.name and props.total_memory >= 80_000 * 1024**2
+                     and props.major >= 8, "strict CUDA requires the reserved A100 80 GB")
+        self.torch = torch
+        self.guard = host.StrictCudaGuard(authorized, torch.is_tensor)
+        self.weights = load_file(self.weights_file.path, device="cuda:0")
+        self.weights_file.assert_unchanged()
+        gate.require(0 < len(self.weights) <= 10_000, "checkpoint tensor inventory exceeds bound")
+        self.assert_resident()
+        gate.require(sum(t.numel() * t.element_size() for t in self.weights.values()) > WEIGHTS_BYTES * .95,
+                     "full checkpoint tensors were not made resident")
+
+    @property
+    def engine_initialized(self):
+        return self.client is not None
+
+    def assert_resident(self):
+        if self.weights:
+            for tensor in self.weights.values():
+                self.guard.require_device(tensor.device)
+        else:
+            gate.require(self.runtime is not None, "no resident checkpoint or initialized engine")
+        if self.runtime is not None:
+            self.guard.require_device(self.runtime.device)
+            self.guard.assert_resident(self.runtime.model)
+            self.guard.assert_resident(self.runtime.region)
+        if self.cuda12_library is not None:
+            gate.require(loaded_cuda12_paths() == {self.manifest["cuda12_runtime"]["path"]},
+                         "loaded CUDA12 runtime differs from the exact isolated library")
+
+    def synchronize(self):
+        self.torch.cuda.synchronize(0)
+
+    def load_cuda12_runtime(self):
+        gate.require(self.authorized(), "CUDA library loading requires host engine authorization")
+        self.cuda12_file.assert_unchanged()
+        expected = {self.manifest["cuda12_runtime"]["path"]}
+        gate.require(loaded_cuda12_paths().issubset(expected), "competing CUDA12 runtime is already loaded")
+        # Use the checked inode. Its ELF SONAME satisfies Kestrel's later
+        # dlopen("libcudart.so.12") without consulting the old system runtime.
+        self.cuda12_library = ctypes.CDLL(self.cuda12_file.path, mode=ctypes.RTLD_GLOBAL)
+        gate.require(all(hasattr(self.cuda12_library, name) for name in CUDA12_SYMBOLS),
+                     "isolated CUDA12 runtime lacks required Library API symbols")
+        gate.require(loaded_cuda12_paths() == expected, "exact isolated CUDA12 library was not mapped")
+
+    def initialize_engine(self):
+        gate.require(self.authorized() and not self.engine_initialized,
+                     "engine activation requires fresh host inference authorization")
+        self.assert_resident()
+        self.weights_file.assert_unchanged()
+        self.tokenizer_file.assert_unchanged()
+        self.load_cuda12_runtime()
+        # No Kestrel/Moondream import or constructor ran before actual placement.
+        from kestrel.engine import core
+        from kestrel.models.moondream import runtime as md_runtime, weights as md_weights
+        from kestrel import model_download
+        from moondream.photon_client import PhotonClient
+
+        class LocalReporter:
+            """No cloud client, telemetry, credentials or external validation."""
+            @staticmethod
+            def _normalize_api_key(_key): return None
+            def __init__(self, *_args, **_kwargs): pass
+            async def validate_api_key(self): return False
+            def start(self): pass
+            async def shutdown(self): pass
+            def record_success(self, **_kwargs): pass
+            def record_error(self, **_kwargs): pass
+
+        @contextmanager
+        def resident_weights(path):
+            gate.require(self.authorized() and path == self.manifest["weights"]["path"],
+                         "engine requested unapproved checkpoint bytes")
+            self.assert_resident()
+            def get_tensor(name):
+                gate.require(name in self.weights, "engine requested a missing checkpoint tensor")
+                return self.weights[name]
+            get_tensor.keys = lambda: list(self.weights)
+            yield get_tensor
+
+        def no_download(*_args, **_kwargs):
+            raise host.StrictCudaError("implicit checkpoint downloads are disabled")
+
+        original_model, original_region = md_runtime.MoondreamModel, md_runtime.build_region_module
+        def guarded_model(*args, **kwargs):
+            return self.guard.install(original_model(*args, **kwargs))
+        def guarded_region(*args, **kwargs):
+            return self.guard.install(original_region(*args, **kwargs))
+        original_query = core.InferenceEngine.query
+        async def recorded_query(engine, *args, **kwargs):
+            gate.require(self.authorized() and not args and kwargs.get("settings", {}).get("max_tokens") == 1,
+                         "only the declared one-token startup query is allowed during activation")
+            self.warmup_requests += 1
+            result = await original_query(engine, **kwargs)
+            self.warmup_completed += 1
+            return result
+
+        # This is a dedicated owned service; patches persist for its lifetime.
+        core.PhotonReporter = LocalReporter
+        model_download.ensure_model_weights = no_download
+        model_download.probe_supported_model_configs = lambda *_args, **_kwargs: None
+        md_runtime.MoondreamModel, md_runtime.build_region_module = guarded_model, guarded_region
+        md_weights.safetensors_open = resident_weights
+        core.InferenceEngine.query = recorded_query
+        self.client = PhotonClient(model=MODEL, api_key=None, device="cuda:0",
+                                   model_path=self.manifest["weights"]["path"],
+                                   tokenizer_path=self.tokenizer_file.path,
+                                   max_batch_size=1, kv_cache_pages=8192,
+                                   enable_cuda_graphs=False, enable_prefix_cache=True,
+                                   decode_path="native", service_name="omnius_point_eval")
+        self.runtime = self.client._engine._runtimes[MODEL]
+        self.assert_resident()
+        gate.require(self.warmup_requests == self.warmup_completed == 1,
+                     "expected startup warmup was not measured exactly once")
+        # Engine parameters retain any shared tensors; discard only extra refs.
+        self.weights = {}
+        self.synchronize()
+        self.torch.cuda.empty_cache()
+        self.assert_resident()
+
+    def predict(self, request):
+        gate.require(self.authorized() and self.engine_initialized, "point inference is not authorized")
+        self.assert_resident()
+        from PIL import Image
+        with Image.open(io.BytesIO(request["image_bytes"])) as image:
+            gate.require(image.format == "PNG" and image.width * image.height <= MAX_PIXELS,
+                         "decoded image violates the PNG pixel bound")
+            image.load()
+            result = self.client.point(image.convert("RGB"), request["object"],
+                                       settings={"max_tokens": 64, "temperature": 0.0})
+        self.assert_resident()
+        return result
+
+
+class StagedPointService:
+    def __init__(self, selection, lock, manifest, manifest_sha, state_dir, lease_owner,
+                 adapter_factory=LocalPhotonAdapter, identity=None, cuda_scope=None,
+                 boot_id=None, clock=time.time, preflight=None, lease=None,
+                 timer_factory=threading.Timer, terminate=os._exit):
+        gate.validate_selection(selection, lock)
+        endpoint = gate.local_endpoint(selection["endpoint"])
+        gate.require(selection["model_id"] == "moondream-3.1" and selection["model"] == MODEL
+                     and selection["protocol"] == "moondream-point"
+                     and selection["weights_revision"] == WEIGHTS_REVISION
+                     and selection["runtime_revision"] == RUNTIME_REVISION,
+                     "service requires the exact pinned Moondream selection")
+        gate.require(endpoint.hostname == "127.0.0.1" and endpoint.path == "/v1/point"
+                     and len(selection["gpu_uuids"]) == 1, "one leased GPU and exact loopback point endpoint required")
+        self.identity = identity or gate.process_identity(os.getpid())
+        self.cuda_scope = cuda_scope or gate.process_cuda_scope(os.getpid())
+        gate.require(self.cuda_scope == selection["gpu_uuids"], "actual CUDA visibility differs from selection")
+        self.boot_id = boot_id or Path("/proc/sys/kernel/random/boot_id").read_text().strip()
+        self.selection, self.lock, self.manifest, self.manifest_sha = selection, lock, manifest, manifest_sha
+        self.state_dir = Path(state_dir)
+        self.state_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        info = self.state_dir.stat()
+        gate.require(info.st_uid == os.getuid() and stat.S_IMODE(info.st_mode) & 0o077 == 0,
+                     "state directory must be owner-only")
+        self.lease_owner, self.clock, self.adapter_factory = lease_owner, clock, adapter_factory
+        self.lease = lease or gpu_lease.ScopedGpuLease(lease_owner, selection["gpu_uuids"])
+        self.preflight = preflight or (lambda receipt: gate.verify_preflight(
+            selection, lock, receipt, gate.collect_snapshot(selection, receipt)))
+        self.timer_factory, self.terminate = timer_factory, terminate
+        self.stage, self.adapter, self.receipt = "idle", None, None
+        self.inference_active = False
+        self.mutex, self.nonce = threading.Lock(), secrets.token_hex(24)
+        self.service_code_hashes = self.current_code_hashes()
+        self.idle = {"schema": "omnius.computer-use.photon-idle.v1", "stage": "idle", "loaded": False,
+                     "server": self.identity, "startup_nonce": self.nonce, "selection": selection,
+                     "manifest_sha256": manifest_sha, "cuda_visible_devices": self.cuda_scope,
+                     "service_code_hashes": self.service_code_hashes, "lease_owner": lease_owner,
+                     "strict_cuda": True, "engine_initialized": False, "warmup_requests": 0}
+        gate.write_json(self.state_dir / "idle.json", self.idle)
+        self.write_state()
+
+    @staticmethod
+    def current_code_hashes():
+        return {Path(module.__file__).name: host.file_sha256(module.__file__)
+                for module in (sys.modules[__name__], gate, points, host, gpu_lease)}
+
+    def verify_service_code(self):
+        gate.require(self.current_code_hashes() == self.service_code_hashes,
+                     "reviewed service or shared gate source changed after startup")
+
+    def write_state(self, error=None):
+        gate.write_json(self.state_dir / "state.json", {
+            "schema": "omnius.computer-use.photon-service-state.v1", "stage": self.stage,
+            "server": self.identity, "startup_nonce": self.nonce,
+            "loaded": self.receipt is not None, "strict_cuda": True,
+            "engine_initialized": bool(self.adapter and self.adapter.engine_initialized),
+            "warmup_requests": getattr(self.adapter, "warmup_requests", 0),
+            "warmup_completed": getattr(self.adapter, "warmup_completed", 0),
+            **({"error": str(error)[:2000]} if error else {})})
+
+    def fail(self, error, fatal=False):
+        self.stage, self.inference_active = "failed", False
+        self.write_state(error)
+        if fatal:
+            self.terminate(124)
+
+    def timer(self, seconds, label):
+        timer = self.timer_factory(seconds, lambda: self.fail(f"{label} hard deadline exceeded", fatal=True))
+        timer.daemon = True
+        timer.start()
+        return timer
+
+    def verify_load_marker(self, marker):
+        gate.require(marker.get("schema") == "omnius.computer-use.load-authorization.v1",
+                     "host load authorization required")
+        for key in ("server", "startup_nonce", "manifest_sha256", "selection", "cuda_visible_devices", "service_code_hashes"):
+            gate.require(marker.get(key) == self.idle[key], f"load authorization mismatch: {key}")
+        issued, expires = marker.get("issued_at", 0), marker.get("expires_at", 0)
+        gate.require(points.number(issued) and points.number(expires)
+                     and issued <= self.clock() < expires and 0 < expires - issued <= 120,
+                     "load authorization is stale")
+        gate.require(isinstance(marker.get("preload_statement"), str)
+                     and 20 <= len(marker["preload_statement"]) <= 2000,
+                     "record actual process CUDA environment inspection before load")
+
+    def advance(self):
+        if self.stage == "idle" and (self.state_dir / "load-authorization.json").exists():
+            with self.mutex:
+                watchdog = None
+                try:
+                    self.verify_service_code()
+                    self.verify_load_marker(host.private_json(self.state_dir / "load-authorization.json"))
+                    self.stage = "loading_weights"
+                    self.write_state()
+                    watchdog = self.timer(STAGE_DEADLINE, "weight loading")
+                    self.adapter = self.adapter_factory(self.manifest, lambda: self.inference_active)
+                    self.adapter.assert_resident()
+                    self.adapter.synchronize()
+                    self.receipt = {**self.selection, "schema": "omnius.computer-use.resident-runtime.v1",
+                                    "service_mode": "leased-external", "loaded": True,
+                                    "attestation_source": "host-launcher", "server": self.identity,
+                                    "runners": [self.identity], "boot_id": self.boot_id,
+                                    "cuda_visible_devices": self.cuda_scope, "lease_owner": self.lease_owner,
+                                    "manifest_sha256": self.manifest_sha, "strict_cuda": True,
+                                    "resident_stage": "resident_weights", "engine_initialized": False,
+                                    "cuda12_runtime": self.manifest.get("cuda12_runtime"),
+                                    "cuda12_runtime_loaded": False,
+                                    "warmup_performed": False, "service_code_hashes": self.service_code_hashes}
+                    gate.write_json(self.state_dir / "resident-runtime.json", self.receipt)
+                    self.stage = "resident_weights"
+                    self.write_state()
+                except Exception as error:
+                    self.fail(error, fatal=watchdog is not None)
+                finally:
+                    if watchdog: watchdog.cancel()
+            return
+        if self.stage == "resident_weights" and (self.state_dir / "engine-authorization.json").exists():
+            try:
+                self.activate_engine()
+            except Exception:
+                pass  # State records the failure; unsafe CUDA failures terminate.
+
+    def active_approval(self, filename):
+        self.verify_service_code()
+        approval = host.private_json(self.state_dir / filename)
+        preflight = self.preflight(self.receipt)
+        gate.verify_approval(approval, preflight, self.clock())
+        return preflight
+
+    def activate_engine(self):
+        gate.require(self.mutex.acquire(blocking=False), "another operation is in progress")
+        watchdog = None
+        try:
+            gate.require(self.stage == "resident_weights", "engine requires resident weights and a new host approval")
+            self.active_approval("engine-authorization.json")
+            self.adapter.assert_resident()
+            watchdog = self.timer(STAGE_DEADLINE, "engine activation")
+            try:
+                self.lease.prepare()
+                self.stage, self.inference_active = "initializing_engine", True
+                self.write_state()
+                self.adapter.initialize_engine()
+                self.adapter.assert_resident()
+                self.adapter.synchronize()
+                self.lease.ready()
+                self.receipt = {**self.receipt, "resident_stage": "engine_ready", "engine_initialized": True,
+                                "cuda12_runtime_loaded": True,
+                                "cuda12_runtime_maps": sorted(loaded_cuda12_paths()),
+                                "warmup_performed": True, "warmup_requests": self.adapter.warmup_requests,
+                                "warmup_completed": self.adapter.warmup_completed,
+                                "warmup_max_output_tokens": 1, "activation_deadline_seconds": STAGE_DEADLINE}
+                gate.write_json(self.state_dir / "resident-runtime.json", self.receipt)
+                self.stage = "engine_ready"
+                self.write_state()
+            except Exception as error:
+                self.fail(error, fatal=True)
+                raise
+        finally:
+            self.inference_active = False
+            if watchdog: watchdog.cancel()
+            self.mutex.release()
+
+    def infer(self, value):
+        request = validate_request(value, self.selection["model"])
+        gate.require(self.mutex.acquire(blocking=False), "another operation is in progress")
+        watchdog = None
+        try:
+            gate.require(self.stage == "engine_ready" and self.adapter.engine_initialized,
+                         "engine initialization and fresh placement approval are required")
+            self.active_approval("inference-approval.json")
+            self.adapter.assert_resident()
+            watchdog = self.timer(POINT_DEADLINE, "point inference")
+            try:
+                self.lease.prepare()
+                self.inference_active = True
+                answer = validate_answer(self.adapter.predict(request))
+                self.adapter.assert_resident()
+                self.adapter.synchronize()
+                self.lease.ready()
+                return answer
+            except Exception as error:
+                self.fail(error, fatal=True)
+                raise
+        finally:
+            self.inference_active = False
+            if watchdog: watchdog.cancel()
+            self.mutex.release()
+
+
+class LocalServer(HTTPServer):
+    allow_reuse_address = False
+    request_queue_size = 4
+
+    def service_actions(self):
+        self.service.advance()
+
+
+class Handler(BaseHTTPRequestHandler):
+    def setup(self):
+        super().setup()
+        self.connection.settimeout(REQUEST_READ_DEADLINE)
+        # Socket inactivity timeouts alone allow a byte-drip request to run forever.
+        self.read_watchdog = threading.Timer(
+            getattr(self.server, "read_deadline", REQUEST_READ_DEADLINE), self.end_read)
+        self.read_watchdog.daemon = True
+        self.read_watchdog.start()
+
+    def end_read(self):
+        try:
+            self.connection.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+
+    def finish_read(self):
+        self.read_watchdog.cancel()
+
+    def finish(self):
+        self.finish_read()
+        super().finish()
+
+    def log_message(self, *_args): pass
+
+    def reply(self, status, value):
+        raw = json.dumps(value, allow_nan=False, separators=(",", ":")).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(raw)))
+        self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def do_GET(self):
+        self.finish_read()
+        if self.path != "/health": return self.reply(404, {"error": "unknown route"})
+        self.reply(200, {"stage": self.server.service.stage, "strict_cuda": True, "pid": os.getpid()})
+
+    def do_POST(self):
+        if self.path != "/v1/point": return self.reply(404, {"error": "unknown route"})
+        try:
+            gate.require(not self.headers.get("Transfer-Encoding"), "chunked requests are unsupported")
+            lengths = self.headers.get_all("Content-Length", [])
+            gate.require(len(lengths) == 1 and lengths[0].isascii() and lengths[0].isdigit(),
+                         "one bounded Content-Length is required")
+            length = int(lengths[0])
+            gate.require(0 < length <= MAX_REQUEST_BYTES, "request body exceeds bound")
+            gate.require(self.headers.get_content_type() == "application/json", "JSON content type required")
+            raw = self.rfile.read(length)
+            gate.require(len(raw) == length, "request body ended early")
+            value = gate.strict_json(raw)
+            validate_request(value, self.server.service.selection["model"])
+        except (gate.GateError, OSError, ValueError) as error:
+            return self.reply(400, {"error": str(error)[:1000]})
+        finally:
+            self.finish_read()
+        try:
+            self.reply(200, self.server.service.infer(value))
+        except Exception as error:
+            self.reply(503, {"error": str(error)[:1000], "stage": self.server.service.stage})
+
+
+def authorize_load(state_dir, statement, now=None):
+    now = time.time() if now is None else now
+    idle = host.private_json(Path(state_dir) / "idle.json")
+    gate.require(idle.get("schema") == "omnius.computer-use.photon-idle.v1" and idle.get("loaded") is False,
+                 "fresh Photon idle process receipt required")
+    gate.require(isinstance(statement, str) and 20 <= len(statement) <= 2000,
+                 "record actual process CUDA visibility before load")
+    marker = {**{key: idle[key] for key in ("server", "startup_nonce", "manifest_sha256", "selection", "cuda_visible_devices", "service_code_hashes")},
+              "schema": "omnius.computer-use.load-authorization.v1", "issued_at": now,
+              "expires_at": now + 120, "preload_statement": statement}
+    gate.write_json(Path(state_dir) / "load-authorization.json", marker)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    serve = commands.add_parser("serve")
+    for name in ("selection", "manifest", "state-dir"):
+        serve.add_argument("--" + name, type=Path, required=True)
+    serve.add_argument("--lease-owner", required=True)
+    serve.add_argument("--lock", type=Path, default=gate.DEFAULT_LOCK)
+    authorize = commands.add_parser("authorize-load")
+    authorize.add_argument("--state-dir", type=Path, required=True)
+    authorize.add_argument("--statement", required=True)
+    prepare = commands.add_parser("prepare-manifest", help="hash local files and metadata without importing CUDA")
+    for name in ("weights", "tokenizer", "requirements", "output"):
+        prepare.add_argument("--" + name, type=Path, required=True)
+    prepare.add_argument("--compatibility-requirements", type=Path, default=CUDA12_REQUIREMENTS)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "authorize-load":
+            authorize_load(args.state_dir, args.statement)
+            return 0
+        if args.command == "prepare-manifest":
+            gate.write_json(args.output, prepare_manifest(args.weights, args.tokenizer, args.requirements,
+                                                         args.compatibility_requirements))
+            print(json.dumps({"status": "prepared", "manifest": str(args.output),
+                              "manifest_sha256": host.file_sha256(args.output), "model_loaded": False}))
+            return 0
+        selection, lock = gate.read_json(args.selection), gate.read_json(args.lock)
+        manifest, sha = gate.read_json_hashed(args.manifest)
+        service = StagedPointService(selection, lock, manifest, sha, args.state_dir, args.lease_owner)
+        endpoint = gate.local_endpoint(selection["endpoint"])
+        with LocalServer(("127.0.0.1", endpoint.port), Handler) as server:
+            server.service = service
+            server.serve_forever(poll_interval=.25)
+        return 0
+    except (gate.GateError, OSError, ValueError) as error:
+        print(json.dumps({"status": "blocked", "error": str(error)}), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())