#!/usr/bin/env python3
"""Run E14 perception directly from the bounded Mission Core shadow stream."""

from __future__ import annotations

import argparse
import hashlib
import importlib.metadata
import io
import json
import math
import os
import platform
import queue
import re
import resource
import shutil
import struct
import sys
import threading
import time
from collections import Counter, deque
from contextlib import suppress
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any

import numpy as np
import run_e9_multirate_perception as e9
from e10_fusion_runtime import (
    CuboidCompletionTracker,
    ProjectionProfile,
    WorldStateProjector,
    canonical_json,
    clearance,
    distance_history,
    fuse_tracks,
    fusion_document,
    project_points,
    sha256,
)
from e15_shadow_runtime import (
    CameraFragmentMetadata,
    DecodedCameraFrame,
    PersistentFmp4Decoder,
    ShadowRuntimeError,
)
from run_e4_full_session_segmentation import _dependency_manifest, _load_model
from run_e4_full_session_segmentation import _profile as read_semantic_profile
from run_e4_full_session_segmentation import _validate_source as validate_semantic_source
from run_e5_instance_tracking import (
    TwoStageTracker,
    _detections,
    _infer,
    _load_valid_fov,
    _preprocess,
    _track_document,
    _validate_source,
    _verify_model,
)
from run_e8_realtime_tracking import FrameEnvelope, LatestWinsQueue
from run_e8_realtime_tracking import _read_profile as read_detector_profile
from run_e10_integrated_perception import (
    LatestSemantic,
    semantic_binding,
    semantic_worker,
)
from run_e10_integrated_perception import (
    read_profile as read_e14_profile,
)
from run_e12_shadow_transport_probe import (
    _connect,
    _decode_event,
    _read_server_frame,
    _send_client_frame,
)
from run_recorded_perception_epoch import (
    _artifact,
    _GpuTelemetry,
    _percentiles,
    _validate_job,
    _write_json,
)

from k1link.compute.inline_temporal import (
    PIPELINE_ID as INLINE_TEMPORAL_PIPELINE_ID,
)
from k1link.compute.inline_temporal import (
    StreamingSemanticStabilizer,
    TemporalStabilizer,
    read_inline_profile,
    stabilize_world_state,
)
from k1link.compute.lidar_contract import (
    K1_LIVE_LIDAR_PROFILE,
    LidarQualityMonitor,
    lidar_readiness_document,
)
from k1link.compute.live_perception import (
    LIVE_RESULT_MAX_PAYLOAD_BYTES,
    LiveSensorSynchronizer,
    encode_live_perception_result,
)
from k1link.data_plane import DecodedPointCloudView, DecodedPoseView
from k1link.device_plugins.xgrids_k1.protocol.normalizer import normalize_k1_message

PROFILE_SCHEMA = "missioncore.e15-shadow-inference-profile/v1"
PROJECTION_SCHEMA = "missioncore.e15-live-projection-pack/v1"
WORKER_PACKAGE_SCHEMA = "missioncore.e15-worker-package/v1"
REPORT_SCHEMA = "missioncore.e15-shadow-inference-report/v1"
RESULT_SCHEMA = "missioncore.e15-shadow-inference-result/v1"
IDENTITY_SCHEMA = "missioncore.e15-shadow-inference-identity/v1"
FUSION_SCHEMA = "missioncore.e15-shadow-fusion-frame/v1"
WORLD_SCHEMA = "missioncore.live-perception-world-state/v1"
SEMANTIC_SCHEMA = "missioncore.e15-shadow-semantic-frame/v1"
PIPELINE_ID = "shadow-fmp4-yolox-eomt-kb4-amodal-world-state/v1"


def arguments() -> argparse.Namespace:
    parser = argparse.ArgumentParser()
    commands = parser.add_subparsers(dest="command", required=True)
    for name in ("preflight", "run", "serve"):
        command = commands.add_parser(name)
        command.add_argument("--job", type=Path, required=True)
        command.add_argument("--live-profile", type=Path, required=True)
        command.add_argument("--e14-profile", type=Path, required=True)
        command.add_argument("--detector-profile", type=Path, required=True)
        command.add_argument("--semantic-profile", type=Path, required=True)
        command.add_argument("--valid-fov-root", type=Path, required=True)
        command.add_argument("--projection-pack", type=Path, required=True)
        command.add_argument("--model-root", type=Path, required=True)
        command.add_argument("--cache", type=Path, required=True)
        command.add_argument("--environment", type=Path, required=True)
        command.add_argument("--worker-package", type=Path, required=True)
        command.add_argument("--stability-profile", type=Path)
        if name in {"run", "serve"}:
            command.add_argument("--host", default="host.docker.internal")
            command.add_argument("--port", type=int, default=18012)
            command.add_argument(
                "--path",
                default=(
                    "/api/v1/device-plugins/"
                    "nodedc.device.xgrids-lixelkity-k1/live-perception-shadow"
                ),
            )
            command.add_argument("--triton-url", default="http://127.0.0.1:8000")
            command.add_argument("--max-duration-seconds", type=float, default=20.0)
            command.add_argument("--socket-timeout-seconds", type=float, default=30.0)
            command.add_argument("--free-bytes-floor", type=int, default=0)
            command.add_argument("--orchestrator-sha256", required=True)
            command.add_argument("--container-image", required=True)
        if name == "run":
            command.add_argument("--token-stdin", action="store_true")
            command.add_argument("--token", default="")
            command.add_argument("--output", type=Path, required=True)
        elif name == "serve":
            command.add_argument("--output-root", type=Path, required=True)
            command.add_argument("--listen-host", choices=("127.0.0.1",), default="127.0.0.1")
            command.add_argument("--listen-port", type=int, default=18020)
    return parser.parse_args()


def _read_object(path: Path) -> dict[str, Any]:
    value = json.loads(path.read_text(encoding="utf-8-sig"))
    if not isinstance(value, dict):
        raise RuntimeError(f"JSON root is not an object: {path}")
    return value


def read_live_profile(path: Path) -> tuple[dict[str, Any], str]:
    resolved = path.resolve(strict=True)
    profile = _read_object(resolved)
    source = profile.get("source")
    authority = profile.get("authority")
    transport = profile.get("transport")
    scheduling = profile.get("scheduling")
    temporal = profile.get("temporal")
    acceptance = profile.get("acceptance")
    if (
        profile.get("schema_version") != PROFILE_SCHEMA
        or profile.get("mode") not in {"replay-shadow-gate", "physical-shadow-gate"}
        or not all(
            isinstance(value, dict)
            for value in (source, authority, transport, scheduling, temporal, acceptance)
        )
        or source.get("source_id") != "sensor.camera.right"
        or source.get("resolution") != [800, 600]
        or source.get("calibration_slot") != "camera_1"
        or authority != {"commands_enabled": False, "navigation_or_safety_accepted": False}
        or transport.get("wire_schema") != "missioncore.live-perception-wire/v1"
        or transport.get("camera_media") != "persistent-fmp4-pyav"
    ):
        raise RuntimeError("LAB E15 live profile contract is invalid")
    integer_bounds = {
        "detector_queue_capacity": (1, 8),
        "semantic_queue_capacity": (1, 4),
        "semantic_sample_every_frames": (2, 30),
    }
    for key, (minimum, maximum) in integer_bounds.items():
        value = scheduling.get(key)
        if not isinstance(value, int) or isinstance(value, bool) or not minimum <= value <= maximum:
            raise RuntimeError("LAB E15 scheduling contract is invalid")
    if (
        not 100 <= float(scheduling.get("semantic_ttl_ms", 0)) <= 5000
        or not 0 <= float(scheduling.get("sensor_wait_ms", -1)) <= 100
        or not 1_048_576 <= int(transport.get("maximum_media_buffer_bytes", 0)) <= 64 * 1024 * 1024
        or not 2 <= int(transport.get("camera_metadata_capacity", 0)) <= 128
        or not 1 <= int(temporal.get("buffer_capacity_per_modality", 0)) <= 256
        or not 0.1 <= float(temporal.get("retention_seconds", 0)) <= 30
        or not 1 <= float(temporal.get("maximum_lidar_camera_delta_ms", 0)) <= 1000
        or not 1 <= float(temporal.get("maximum_pose_point_delta_ms", 0)) <= 1000
    ):
        raise RuntimeError("LAB E15 bounded runtime contract is invalid")
    fractions = (
        "detector_maximum_drop_fraction",
        "semantic_maximum_drop_fraction",
        "minimum_fresh_semantic_coverage",
        "minimum_fused_fraction",
    )
    if (
        int(acceptance.get("minimum_camera_frames", 0)) < 2
        or any(not 0 <= float(acceptance.get(key, -1)) <= 1 for key in fractions)
        or any(
            float(acceptance.get(key, 0)) <= 0
            for key in (
                "detector_minimum_effective_fps",
                "semantic_minimum_effective_fps",
                "semantic_maximum_p95_completion_age_ms",
                "maximum_p95_decode_age_ms",
                "maximum_p95_world_state_age_ms",
            )
        )
        or not all(
            isinstance(acceptance.get(key), bool)
            for key in (
                "require_zero_transport_gaps",
                "require_zero_camera_sequence_gaps",
                "require_zero_failures",
            )
        )
    ):
        raise RuntimeError("LAB E15 acceptance contract is invalid")
    return profile, sha256(resolved)


def read_projection_pack(
    root: Path, expected_calibration_sha256: str
) -> tuple[ProjectionProfile, dict[str, Any]]:
    resolved = root.resolve(strict=True)
    manifest_path = resolved / "manifest.json"
    arrays_path = resolved / "projection.npz"
    manifest = _read_object(manifest_path)
    identity = manifest.get("identity")
    identity_sha256 = manifest.get("identity_sha256")
    artifact = manifest.get("artifact")
    if (
        manifest.get("schema_version") != PROJECTION_SCHEMA
        or not isinstance(identity, dict)
        or identity.get("schema_version") != PROJECTION_SCHEMA
        or identity.get("calibration_sha256") != expected_calibration_sha256
        or identity.get("source_id") != "sensor.camera.right"
        or identity.get("calibration_slot") != "camera_1"
        or not isinstance(identity_sha256, str)
        or hashlib.sha256(canonical_json(identity)).hexdigest() != identity_sha256
        or resolved.name != f"e15-live-projection-{identity_sha256}"
        or manifest.get("pack_id") != resolved.name
        or not isinstance(artifact, dict)
        or artifact.get("path") != arrays_path.name
        or artifact.get("byte_length") != arrays_path.stat().st_size
        or artifact.get("sha256") != sha256(arrays_path)
    ):
        raise RuntimeError("LAB E15 projection pack identity is invalid")
    with np.load(arrays_path, allow_pickle=False) as arrays:
        if set(arrays.files) != {
            "intrinsic_fx_fy_cx_cy",
            "distortion_kb4",
            "t_camera_from_lidar",
        }:
            raise RuntimeError("LAB E15 projection pack arrays changed")
        intrinsic = tuple(float(value) for value in arrays["intrinsic_fx_fy_cx_cy"])
        distortion = tuple(float(value) for value in arrays["distortion_kb4"])
        transform = np.asarray(arrays["t_camera_from_lidar"], dtype=np.float64)
    if len(intrinsic) != 4 or len(distortion) != 4 or transform.shape != (4, 4):
        raise RuntimeError("LAB E15 projection pack shapes changed")
    return (
        ProjectionProfile(
            width=800,
            height=600,
            intrinsic_fx_fy_cx_cy=intrinsic,
            distortion_kb4=distortion,
            t_camera_from_lidar=transform,
        ),
        manifest,
    )


def read_worker_package(root: Path) -> dict[str, Any]:
    resolved = root.resolve(strict=True)
    manifest_path = resolved / "manifest.json"
    manifest = _read_object(manifest_path)
    identity = manifest.get("identity")
    identity_sha256 = manifest.get("identity_sha256")
    artifacts = manifest.get("artifacts")
    if (
        manifest.get("schema_version") != WORKER_PACKAGE_SCHEMA
        or not isinstance(identity, dict)
        or identity.get("schema_version") != WORKER_PACKAGE_SCHEMA
        or identity.get("classification") != "minimal-live-worker-import-projection"
        or not isinstance(identity_sha256, str)
        or hashlib.sha256(canonical_json(identity)).hexdigest() != identity_sha256
        or manifest.get("package_id") != f"e15-worker-package-{identity_sha256}"
        or resolved.name != manifest.get("package_id")
        or not isinstance(artifacts, list)
        or len(artifacts) != 12
    ):
        raise RuntimeError("LAB E15 worker package identity is invalid")
    expected = set()
    for artifact in artifacts:
        if not isinstance(artifact, dict):
            raise RuntimeError("LAB E15 worker package artifact is invalid")
        relative = str(artifact.get("path", ""))
        path = resolved / relative
        if (
            not relative.startswith("k1link/")
            or relative in expected
            or not path.is_file()
            or path.is_symlink()
            or path.stat().st_size != artifact.get("byte_length")
            or sha256(path) != artifact.get("sha256")
        ):
            raise RuntimeError("LAB E15 worker package artifact changed")
        expected.add(relative)
    actual = {
        path.relative_to(resolved).as_posix() for path in resolved.rglob("*") if path.is_file()
    }
    if actual != expected | {"manifest.json"}:
        raise RuntimeError("LAB E15 worker package file set changed")
    return manifest


@dataclass(frozen=True, slots=True)
class _WireMessage:
    sequence: int
    topic: str
    payload: bytes
    received_at_epoch_ns: int
    received_monotonic_ns: int | None
    source: str = "live_mqtt"


@dataclass(slots=True)
class _TransportState:
    counts: Counter[str]
    payload_bytes: Counter[str]
    first_ingress_sequence: int | None = None
    last_ingress_sequence: int | None = None
    ingress_sequence_gaps: int = 0
    camera_sequence_gaps: int = 0
    last_camera_source_sequence: int | None = None
    session_id: str | None = None
    session_end_seen: bool = False
    timed_out: bool = False
    results_published: int = 0
    result_bytes_published: int = 0
    results_dropped: int = 0
    failures: list[BaseException] | None = None

    def __post_init__(self) -> None:
        if self.failures is None:
            self.failures = []


class _RuntimeTelemetry:
    """Sample process, host-memory and bounded-queue state during one warm run."""

    def __init__(
        self,
        stream: Any,
        *,
        interval_seconds: float,
        snapshotters: dict[str, Any],
    ) -> None:
        if not 0.25 <= interval_seconds <= 10:
            raise RuntimeError("runtime telemetry interval is outside bounds")
        self._stream = stream
        self._interval = interval_seconds
        self._snapshotters = snapshotters
        self._stop = threading.Event()
        self._thread = threading.Thread(
            target=self._run,
            name="runtime-telemetry",
            daemon=True,
        )
        self._started = time.perf_counter()
        self._previous_wall = self._started
        self._previous_cpu = time.process_time()
        self.samples: deque[dict[str, Any]] = deque(maxlen=4096)

    def __enter__(self) -> _RuntimeTelemetry:
        self._thread.start()
        return self

    def __exit__(self, *_: object) -> None:
        self._stop.set()
        self._thread.join(timeout=self._interval + 5)
        self._sample()

    @staticmethod
    def _read_number(path: str) -> int | None:
        try:
            value = Path(path).read_text(encoding="ascii").strip()
            if value == "max":
                return None
            return int(value)
        except (OSError, ValueError):
            return None

    @staticmethod
    def _process_status() -> tuple[float, int]:
        rss_mib = 0.0
        thread_count = 0
        try:
            fields = Path("/proc/self/statm").read_text(encoding="ascii").split()
            rss_mib = int(fields[1]) * os.sysconf("SC_PAGE_SIZE") / 2**20
        except (OSError, ValueError, IndexError):
            pass
        try:
            for line in Path("/proc/self/status").read_text(encoding="ascii").splitlines():
                if line.startswith("Threads:"):
                    thread_count = int(line.split(":", 1)[1].strip())
                    break
        except (OSError, ValueError):
            pass
        return rss_mib, thread_count

    @staticmethod
    def _memory_status() -> tuple[float, float]:
        total_kib = 0
        available_kib = 0
        try:
            for line in Path("/proc/meminfo").read_text(encoding="ascii").splitlines():
                if line.startswith("MemTotal:"):
                    total_kib = int(line.split()[1])
                elif line.startswith("MemAvailable:"):
                    available_kib = int(line.split()[1])
        except (OSError, ValueError, IndexError):
            pass
        return total_kib / 1024, available_kib / 1024

    @staticmethod
    def _io_status() -> tuple[int, int]:
        read_bytes = 0
        write_bytes = 0
        try:
            for line in Path("/proc/self/io").read_text(encoding="ascii").splitlines():
                if line.startswith("read_bytes:"):
                    read_bytes = int(line.split(":", 1)[1].strip())
                elif line.startswith("write_bytes:"):
                    write_bytes = int(line.split(":", 1)[1].strip())
        except (OSError, ValueError):
            pass
        return read_bytes, write_bytes

    def _sample(self) -> None:
        now = time.perf_counter()
        process_cpu = time.process_time()
        wall_delta = max(1e-9, now - self._previous_wall)
        cpu_percent = max(0.0, (process_cpu - self._previous_cpu) / wall_delta * 100)
        self._previous_wall = now
        self._previous_cpu = process_cpu
        rss_mib, thread_count = self._process_status()
        memory_total_mib, memory_available_mib = self._memory_status()
        read_bytes, write_bytes = self._io_status()
        cgroup_current = self._read_number("/sys/fs/cgroup/memory.current")
        cgroup_limit = self._read_number("/sys/fs/cgroup/memory.max")
        queues: dict[str, Any] = {}
        for name, snapshotter in self._snapshotters.items():
            try:
                queues[name] = snapshotter()
            except (RuntimeError, ValueError, OSError):
                queues[name] = {"state": "snapshot-unavailable"}
        sample = {
            "schema_version": "missioncore.worker-runtime-telemetry/v1",
            "elapsed_seconds": round(now - self._started, 6),
            "process_cpu_percent": round(cpu_percent, 6),
            "process_rss_mib": round(rss_mib, 6),
            "process_threads": thread_count,
            "process_read_bytes": read_bytes,
            "process_write_bytes": write_bytes,
            "system_memory_total_mib": round(memory_total_mib, 6),
            "system_memory_available_mib": round(memory_available_mib, 6),
            "cgroup_memory_current_mib": (
                round(cgroup_current / 2**20, 6) if cgroup_current is not None else None
            ),
            "cgroup_memory_limit_mib": (
                round(cgroup_limit / 2**20, 6) if cgroup_limit is not None else None
            ),
            "queues": queues,
        }
        self.samples.append(sample)
        self._stream.write(json.dumps(sample, sort_keys=True) + "\n")
        self._stream.flush()

    def _run(self) -> None:
        while not self._stop.wait(self._interval):
            self._sample()

    def summary(self) -> dict[str, Any]:
        samples = list(self.samples)
        numeric_fields = (
            "process_cpu_percent",
            "process_rss_mib",
            "process_threads",
            "system_memory_available_mib",
            "cgroup_memory_current_mib",
        )
        summary: dict[str, Any] = {
            "sample_count": len(samples),
            "sample_capacity": self.samples.maxlen,
            "interval_seconds": self._interval,
        }
        for field in numeric_fields:
            values = [
                float(sample[field])
                for sample in samples
                if isinstance(sample.get(field), int | float)
            ]
            summary[field] = _percentiles(values)
        if samples:
            quarter = max(1, len(samples) // 4)
            early = [float(value["process_rss_mib"]) for value in samples[:quarter]]
            late = [float(value["process_rss_mib"]) for value in samples[-quarter:]]
            summary["rss_growth_mib"] = round(
                float(_percentiles(late)["p95"]) - float(_percentiles(early)["p95"]),
                6,
            )
            summary["final_queues"] = samples[-1]["queues"]
        else:
            summary["rss_growth_mib"] = 0.0
            summary["final_queues"] = {}
        return summary


def _send_client_binary_frame(stream: Any, payload: bytes) -> None:
    if not payload or len(payload) > LIVE_RESULT_MAX_PAYLOAD_BYTES + 256 * 1024 + 8:
        raise ShadowRuntimeError("live result websocket frame exceeds the bound")
    mask = os.urandom(4)
    length = len(payload)
    if length < 126:
        header = bytes((0x82, 0x80 | length))
    elif length <= 0xFFFF:
        header = bytes((0x82, 0x80 | 126)) + struct.pack("!H", length)
    else:
        header = bytes((0x82, 0x80 | 127)) + struct.pack("!Q", length)
    masked = bytes(value ^ mask[index % 4] for index, value in enumerate(payload))
    stream.write(header + mask + masked)
    stream.flush()


def _receiver(
    *,
    host: str,
    port: int,
    path: str,
    token: str,
    socket_timeout_seconds: float,
    max_duration_seconds: float,
    decoder: PersistentFmp4Decoder,
    synchronizer: LiveSensorSynchronizer,
    lidar_quality: LidarQualityMonitor,
    state: _TransportState,
    sensor_decode_ms: dict[str, list[float]],
    result_queue: queue.Queue[bytes],
    result_complete: threading.Event,
) -> None:
    import select

    connection = None
    stream = None
    sender_stop = threading.Event()
    sender_thread: threading.Thread | None = None
    write_lock = threading.Lock()
    try:
        connection, stream = _connect(host, port, path, token, socket_timeout_seconds)

        def send_results() -> None:
            try:
                while not sender_stop.is_set() or not result_queue.empty():
                    try:
                        payload = result_queue.get(timeout=0.05)
                    except queue.Empty:
                        continue
                    try:
                        with write_lock:
                            _send_client_binary_frame(stream, payload)
                        state.results_published += 1
                        state.result_bytes_published += len(payload)
                    finally:
                        result_queue.task_done()
            except BaseException as exc:
                assert state.failures is not None
                state.failures.append(exc)
                sender_stop.set()

        sender_thread = threading.Thread(
            target=send_results,
            name="lab-e15-result-publisher",
            daemon=True,
        )
        sender_thread.start()
        deadline = time.monotonic() + max_duration_seconds
        while time.monotonic() < deadline:
            if state.session_end_seen:
                if result_complete.is_set() and result_queue.empty():
                    break
                time.sleep(0.01)
                continue
            readable, _, _ = select.select(
                [connection],
                [],
                [],
                min(0.25, max(0.0, deadline - time.monotonic())),
            )
            if not readable:
                continue
            opcode, frame = _read_server_frame(stream)
            worker_received = time.perf_counter()
            if opcode == 0x8:
                break
            if opcode == 0x9:
                with write_lock:
                    _send_client_frame(stream, 0xA, frame)
                continue
            if opcode != 0x2:
                raise ShadowRuntimeError(f"unexpected websocket opcode: {opcode}")
            header, payload = _decode_event(frame)
            sequence = int(header["ingress_sequence"])
            if state.last_ingress_sequence is not None:
                if sequence <= state.last_ingress_sequence:
                    raise ShadowRuntimeError("shadow ingress sequence is not increasing")
                state.ingress_sequence_gaps += max(0, sequence - state.last_ingress_sequence - 1)
            if state.first_ingress_sequence is None:
                state.first_ingress_sequence = sequence
            state.last_ingress_sequence = sequence
            session_id = str(header["session_id"])
            if state.session_id is None:
                state.session_id = session_id
            elif state.session_id != session_id:
                raise ShadowRuntimeError("shadow session identity changed")
            modality = str(header["modality"])
            state.counts[modality] += 1
            state.payload_bytes[modality] += len(payload)
            if modality == "control":
                control = json.loads(payload)
                if control.get("event") == "session-end":
                    state.session_end_seen = True
                    decoder.finish_input()
            elif modality == "camera-init":
                decoder.feed_init(payload)
            elif modality == "camera-frame":
                camera_source_sequence = int(header["source_sequence"])
                expected_camera_sequence = (
                    1
                    if state.last_camera_source_sequence is None
                    else state.last_camera_source_sequence + 1
                )
                if camera_source_sequence < expected_camera_sequence:
                    raise ShadowRuntimeError(
                        "camera source sequence is not increasing: "
                        f"expected at least {expected_camera_sequence}, "
                        f"got {camera_source_sequence}"
                    )
                state.camera_sequence_gaps += camera_source_sequence - expected_camera_sequence
                state.last_camera_source_sequence = camera_source_sequence
                decoder.feed_segment(
                    CameraFragmentMetadata(
                        ingress_sequence=sequence,
                        source_sequence=camera_source_sequence,
                        captured_at_epoch_ns=int(header["captured_at_epoch_ns"]),
                        worker_received_monotonic=worker_received,
                    ),
                    payload,
                )
            elif modality in {"lidar", "pose"}:
                decode_started = time.perf_counter()
                normalized = normalize_k1_message(
                    _WireMessage(
                        sequence=int(header["source_sequence"]),
                        topic=str(header["source_id"]),
                        payload=payload,
                        received_at_epoch_ns=int(header["captured_at_epoch_ns"]),
                        received_monotonic_ns=int(header["received_monotonic_ns"]),
                    ),
                    processing_started_monotonic_ns=time.monotonic_ns(),
                )
                sensor_decode_ms[modality].append((time.perf_counter() - decode_started) * 1000)
                if modality == "lidar" and isinstance(normalized, DecodedPointCloudView):
                    lidar_quality.observe(normalized)
                    synchronizer.publish_point_cloud(normalized)
                elif modality == "pose" and isinstance(normalized, DecodedPoseView):
                    synchronizer.publish_pose(normalized)
                else:
                    raise ShadowRuntimeError("known sensor modality did not normalize")
        else:
            state.timed_out = True
    except BaseException as exc:
        assert state.failures is not None
        state.failures.append(exc)
    finally:
        decoder.finish_input()
        sender_stop.set()
        if sender_thread is not None:
            sender_thread.join(timeout=5)
            if sender_thread.is_alive():
                assert state.failures is not None
                state.failures.append(ShadowRuntimeError("live result publisher did not stop"))
        if stream is not None:
            with suppress(Exception), write_lock:
                _send_client_frame(stream, 0x8, b"")
            with suppress(Exception):
                stream.close()
        if connection is not None:
            with suppress(Exception):
                connection.close()


def _assert_disk(path: Path, floor: int) -> None:
    if floor < 0 or (floor and shutil.disk_usage(path).free < floor):
        raise RuntimeError("LAB E15 crossed the D-backed free-space floor")


def _common(args: argparse.Namespace) -> dict[str, Any]:
    job = _validate_job(args.job.resolve(strict=True))
    live, live_sha256 = read_live_profile(args.live_profile)
    e14, e14_sha256 = read_e14_profile(args.e14_profile)
    detector, detector_sha256 = read_detector_profile(args.detector_profile)
    semantic, semantic_sha256 = read_semantic_profile(args.semantic_profile)
    _validate_source(job, detector)
    validate_semantic_source(job, semantic)
    if live["source"] != detector["source"] or live["source"] != {
        key: semantic["source"][key]
        for key in ("source_id", "resolution", "calibration_slot", "calibration_sha256")
    }:
        raise RuntimeError("LAB E15 model/source binding changed")
    if live["source"] != e14["source"]:
        raise RuntimeError("LAB E15 differs from the accepted E14 source")
    replay = e14["replay"]
    scheduling = live["scheduling"]
    for key in (
        "detector_queue_capacity",
        "semantic_queue_capacity",
        "semantic_sample_every_frames",
        "semantic_ttl_ms",
    ):
        if scheduling[key] != replay[key]:
            raise RuntimeError("LAB E15 scheduling differs from accepted E14")
    projection, projection_manifest = read_projection_pack(
        args.projection_pack,
        live["source"]["calibration_sha256"],
    )
    valid_mask, valid_fov = _load_valid_fov(args.valid_fov_root, job, detector)
    detector_files = _verify_model(detector, args.model_root)
    dependency = _dependency_manifest(args.environment.resolve(strict=True))
    if dependency["identity"]["profile_sha256"] != semantic_sha256:
        raise RuntimeError("LAB E15 semantic dependency identity changed")
    worker_package = read_worker_package(args.worker_package)
    stability = None
    stability_sha256 = None
    if args.stability_profile is not None:
        stability, stability_sha256 = read_inline_profile(args.stability_profile)
        if stability["source"] != live["source"] or stability["authority"] != live["authority"]:
            raise RuntimeError("LAB E23 inline temporal source binding changed")
    return {
        "job": job,
        "live": live,
        "live_sha256": live_sha256,
        "e14": e14,
        "e14_sha256": e14_sha256,
        "detector": detector,
        "detector_sha256": detector_sha256,
        "semantic": semantic,
        "semantic_sha256": semantic_sha256,
        "projection": projection,
        "projection_manifest": projection_manifest,
        "valid_mask": valid_mask,
        "valid_fov": valid_fov,
        "detector_files": detector_files,
        "dependency": dependency,
        "worker_package": worker_package,
        "stability": stability,
        "stability_sha256": stability_sha256,
    }


def preflight(args: argparse.Namespace) -> int:
    import av
    import lz4
    import torch

    common = _common(args)
    if av.__version__ != common["live"]["transport"]["pyav_version"]:
        raise RuntimeError("LAB E15 PyAV version changed")
    if not torch.cuda.is_available():
        raise RuntimeError("CUDA is required for LAB E15")
    device = torch.device("cuda:0")
    processor, model, _labels, _lut, semantic_files = _load_model(
        common["semantic"], args.cache.resolve(strict=True), device
    )
    del processor, model, _labels, _lut
    torch.cuda.empty_cache()
    print(
        json.dumps(
            {
                "state": "preflight-ready",
                "live_profile_sha256": common["live_sha256"],
                "e14_profile_sha256": common["e14_sha256"],
                "projection_pack": common["projection_manifest"]["pack_id"],
                "worker_package": common["worker_package"]["package_id"],
                "stability_profile_sha256": common["stability_sha256"],
                "pyav": av.__version__,
                "lz4": getattr(lz4, "__version__", importlib.metadata.version("lz4")),
                "detector_files": common["detector_files"],
                "semantic_files": semantic_files,
                "cuda_device": torch.cuda.get_device_name(),
            },
            sort_keys=True,
        ),
        flush=True,
    )
    return 0


@dataclass(frozen=True, slots=True)
class _LoadedModels:
    common: dict[str, Any]
    device: Any
    infer_semantic: Any
    target_lut: np.ndarray[Any, Any]
    target_names: dict[int, str]
    semantic_files: list[dict[str, Any]]
    loaded_at_monotonic: float


def _load_models(args: argparse.Namespace, common: dict[str, Any]) -> _LoadedModels:
    import torch

    if not torch.cuda.is_available():
        raise RuntimeError("CUDA is required for LAB E15")
    loaded_at = time.perf_counter()
    device = torch.device("cuda:0")
    processor, semantic_model, _semantic_labels, target_lut, semantic_files = _load_model(
        common["semantic"], args.cache.resolve(strict=True), device
    )
    infer_semantic = e9._semantic_infer_factory(processor, semantic_model, device)
    target_names = {
        int(key): str(value) for key, value in common["semantic"]["target_taxonomy"].items()
    }
    warm = np.zeros((600, 800, 3), dtype=np.uint8)
    _infer(
        args.triton_url,
        common["detector"]["model"],
        _preprocess(warm, common["valid_mask"], common["detector"]),
    )
    infer_semantic(np.where(common["valid_mask"][..., None], warm, 0).astype(np.uint8))
    return _LoadedModels(
        common=common,
        device=device,
        infer_semantic=infer_semantic,
        target_lut=target_lut,
        target_names=target_names,
        semantic_files=semantic_files,
        loaded_at_monotonic=loaded_at,
    )


def run(args: argparse.Namespace, loaded: _LoadedModels | None = None) -> int:
    import av
    import torch
    import transformers
    from scipy.optimize import linear_sum_assignment

    if len(args.orchestrator_sha256) != 64:
        raise RuntimeError("LAB E15 orchestrator SHA-256 is invalid")
    token = sys.stdin.readline().strip() if args.token_stdin else args.token
    if not token or len(token) < 40:
        raise RuntimeError("LAB E15 shadow token is missing")
    common = _common(args) if loaded is None else loaded.common
    live = common["live"]
    e14 = common["e14"]
    detector = common["detector"]
    semantic = common["semantic"]
    projection = common["projection"]
    valid_mask = common["valid_mask"]
    if av.__version__ != live["transport"]["pyav_version"]:
        raise RuntimeError("LAB E15 PyAV version changed")
    output = args.output.resolve()
    if output.exists():
        raise RuntimeError("LAB E15 output must be absent")
    output.mkdir(mode=0o700, parents=True, exist_ok=False)
    _assert_disk(output, args.free_bytes_floor)
    disk_before = shutil.disk_usage(output).free

    if loaded is None:
        loaded = _load_models(args, common)
    target_names = loaded.target_names
    infer_semantic = loaded.infer_semantic
    semantic_files = loaded.semantic_files
    target_lut = loaded.target_lut
    stability = common["stability"]
    temporal_stabilizer = TemporalStabilizer(stability) if stability is not None else None
    semantic_stabilizer = StreamingSemanticStabilizer(stability) if stability is not None else None
    temporal_world_memory: dict[int, dict[str, Any]] = {}
    tracker = TwoStageTracker(detector["tracking"])
    linear_sum_assignment(np.zeros((1, 1), dtype=np.float64))
    torch.cuda.reset_peak_memory_stats()

    scheduling = live["scheduling"]
    temporal = live["temporal"]
    detector_queue = LatestWinsQueue(int(scheduling["detector_queue_capacity"]))
    semantic_queue = LatestWinsQueue(int(scheduling["semantic_queue_capacity"]))
    latest = LatestSemantic()
    synchronizer = LiveSensorSynchronizer(
        maximum_lidar_camera_delta_ms=float(temporal["maximum_lidar_camera_delta_ms"]),
        maximum_pose_point_delta_ms=float(temporal["maximum_pose_point_delta_ms"]),
        capacity_per_modality=int(temporal["buffer_capacity_per_modality"]),
        retention_seconds=float(temporal["retention_seconds"]),
    )
    lidar_quality = LidarQualityMonitor(K1_LIVE_LIDAR_PROFILE)
    first_camera_epoch_ns: list[int] = []
    last_camera_epoch_ns: list[int] = []
    decoded_frame_count = 0
    callback_failures: list[BaseException] = []

    def on_decoded(frame: DecodedCameraFrame) -> None:
        nonlocal decoded_frame_count
        try:
            if not first_camera_epoch_ns:
                first_camera_epoch_ns.append(frame.metadata.captured_at_epoch_ns)
            last_camera_epoch_ns[:] = [frame.metadata.captured_at_epoch_ns]
            session_seconds = (
                frame.metadata.captured_at_epoch_ns - first_camera_epoch_ns[0]
            ) / 1_000_000_000
            envelope = FrameEnvelope(
                frame_index=frame.frame_index,
                path=Path("/shadow/fmp4"),
                timeline={
                    "source_frame_index": frame.metadata.source_sequence - 1,
                    "source_sequence": frame.metadata.source_sequence,
                    "session_seconds": session_seconds,
                    "captured_at_epoch_ns": frame.metadata.captured_at_epoch_ns,
                    "ingress_sequence": frame.metadata.ingress_sequence,
                },
                scheduled_monotonic=frame.metadata.worker_received_monotonic,
                decoded_monotonic=frame.decoded_monotonic,
                image=frame.image,
                decode_ms=frame.decode_age_ms,
                source_release_lag_ms=0.0,
            )
            decoded_frame_count += 1
            detector_queue.publish(envelope)
            if frame.frame_index % int(scheduling["semantic_sample_every_frames"]) == 0:
                semantic_queue.publish(envelope)
        except BaseException as exc:
            callback_failures.append(exc)
            detector_queue.close()
            semantic_queue.close()

    decoder = PersistentFmp4Decoder(
        on_frame=on_decoded,
        width=800,
        height=600,
        maximum_buffer_bytes=int(live["transport"]["maximum_media_buffer_bytes"]),
        metadata_capacity=int(live["transport"]["camera_metadata_capacity"]),
    )
    transport = _TransportState(Counter(), Counter())
    result_queue: queue.Queue[bytes] = queue.Queue(maxsize=2)
    result_complete = threading.Event()
    sensor_decode_ms = {"lidar": [], "pose": []}
    semantic_errors: list[BaseException] = []
    semantic_latency = {
        name: []
        for name in (
            "queue_wait_ms",
            "valid_fov_fill_ms",
            "processor_ms",
            "host_to_device_ms",
            "forward_ms",
            "model_postprocess_ms",
            "processing_ms",
            "completion_age_ms",
        )
    }
    latency = {
        name: []
        for name in (
            "decode_age_ms",
            "queue_wait_ms",
            "detector_ms",
            "sensor_wait_ms",
            "projection_ms",
            "association_ms",
            "clearance_ms",
            "world_state_ms",
            "world_state_age_ms",
            "source_epoch_age_ms_unqualified",
        )
    }
    latency["temporal_2d_3d_ms"] = deque(maxlen=4096)
    status_counts: Counter[str] = Counter()
    fusion_state_counts: Counter[str] = Counter()
    rejection_counts: Counter[str] = Counter()
    fused_frames = 0
    accepted_cuboids = 0
    stabilized_cuboids = 0
    detector_failures = 0
    history = distance_history(int(e14["association"]["distance_history_frames"]))
    projector = WorldStateProjector(float(e14["world_state"]["velocity_history_limit_s"]))
    completion_tracker = CuboidCompletionTracker(e14["cuboid_completion"])
    semantic_path = output / "semantic-frames.jsonl"
    raw_fusion_path = output / "raw-fusion-frames.jsonl"
    fusion_path = output / "fusion-frames.jsonl"
    world_path = output / "world-state.jsonl"
    gpu_path = output / "gpu-telemetry.jsonl"
    runtime_path = output / "runtime-telemetry.jsonl"
    run_started = time.perf_counter()
    process_cpu_started = time.process_time()

    with (
        semantic_path.open("x", encoding="utf-8", newline="\n") as semantic_stream,
        raw_fusion_path.open("x", encoding="utf-8", newline="\n") as raw_fusion_stream,
        fusion_path.open("x", encoding="utf-8", newline="\n") as fusion_stream,
        world_path.open("x", encoding="utf-8", newline="\n") as world_stream,
        gpu_path.open("x", encoding="utf-8", newline="\n") as gpu_stream,
        runtime_path.open("x", encoding="utf-8", newline="\n") as runtime_stream,
        _GpuTelemetry(gpu_stream, 1.0) as gpu,
        _RuntimeTelemetry(
            runtime_stream,
            interval_seconds=1.0,
            snapshotters={
                "detector": detector_queue.snapshot,
                "semantic": semantic_queue.snapshot,
                "decoder": decoder.snapshot,
                "synchronizer": synchronizer.snapshot,
                "lidar_quality": lidar_quality.snapshot,
                "result": lambda: {
                    "capacity": result_queue.maxsize,
                    "depth": result_queue.qsize(),
                    "dropped_overflow": transport.results_dropped,
                    "published": transport.results_published,
                },
            },
        ) as runtime_telemetry,
    ):

        class SemanticResultStream:
            def __init__(self) -> None:
                self.count = 0

            def append(self, result: Any) -> None:
                semantic_stream.write(
                    json.dumps(
                        {
                            "schema_version": SEMANTIC_SCHEMA,
                            "frame_index": result.frame_index,
                            "source_frame_index": result.source_frame_index,
                            "session_seconds": result.session_seconds,
                            "completion_age_ms": result.completion_age_ms,
                            "mask_sha256": result.mask_sha256,
                            "class_pixels": result.class_pixels,
                        },
                        sort_keys=True,
                        separators=(",", ":"),
                        allow_nan=False,
                    )
                    + "\n"
                )
                self.count += 1

        completed_semantics = SemanticResultStream()
        semantic_thread = threading.Thread(
            target=semantic_worker,
            kwargs={
                "queue": semantic_queue,
                "latest": latest,
                "valid_mask": valid_mask,
                "target_lut": target_lut,
                "target_names": target_names,
                "infer": infer_semantic,
                "latency": semantic_latency,
                "completed": completed_semantics,
                "failures": semantic_errors,
                "stop_after_results": None,
                "transform_target": (
                    None if semantic_stabilizer is None else semantic_stabilizer.update
                ),
            },
            name="lab-e15-semantic",
            daemon=True,
        )
        semantic_thread.start()
        decoder.start()
        receiver_thread = threading.Thread(
            target=_receiver,
            kwargs={
                "host": args.host,
                "port": args.port,
                "path": args.path,
                "token": token,
                "socket_timeout_seconds": args.socket_timeout_seconds,
                "max_duration_seconds": args.max_duration_seconds,
                "decoder": decoder,
                "synchronizer": synchronizer,
                "lidar_quality": lidar_quality,
                "state": transport,
                "sensor_decode_ms": sensor_decode_ms,
                "result_queue": result_queue,
                "result_complete": result_complete,
            },
            name="lab-e15-shadow-receiver",
            daemon=True,
        )
        receiver_thread.start()

        decoder_watch_failures: list[BaseException] = []

        def watch_decoder() -> None:
            try:
                decoder.join(timeout_seconds=args.max_duration_seconds + 30)
            except BaseException as exc:
                decoder_watch_failures.append(exc)
            finally:
                detector_queue.close()
                semantic_queue.close()

        decoder_watcher = threading.Thread(
            target=watch_decoder,
            name="lab-e15-decoder-watch",
            daemon=True,
        )
        decoder_watcher.start()

        while (envelope := detector_queue.take()) is not None:
            started = time.perf_counter()
            latency["decode_age_ms"].append(float(envelope.decode_ms))
            latency["queue_wait_ms"].append(max(0.0, (started - envelope.decoded_monotonic) * 1000))
            try:
                detector_started = time.perf_counter()
                tensor = _preprocess(envelope.image, valid_mask, detector)
                output_tensor, _request_ms = _infer(args.triton_url, detector["model"], tensor)
                detections, _rejected = _detections(output_tensor, detector, valid_mask)
                tracks = tracker.update(detections, envelope.frame_index)
                latency["detector_ms"].append((time.perf_counter() - detector_started) * 1000)

                frame_seconds = float(envelope.timeline["session_seconds"])
                current_semantic = latest.snapshot()
                semantic_status, semantic_age = semantic_binding(
                    current_semantic,
                    frame_seconds,
                    float(scheduling["semantic_ttl_ms"]),
                )
                status_counts[semantic_status] += 1
                sensor_wait_started = time.perf_counter()
                binding = synchronizer.bind_camera(
                    int(envelope.timeline["captured_at_epoch_ns"]),
                    wait_seconds=float(scheduling["sensor_wait_ms"]) / 1000,
                )
                latency["sensor_wait_ms"].append((time.perf_counter() - sensor_wait_started) * 1000)
                fusions = ()
                points_lidar = np.empty((0, 3), dtype=np.float64)
                if binding.state != "fused-ready":
                    fusion_state = f"depth-unavailable-sync-gate:{binding.state}"
                elif semantic_status != "fresh" or current_semantic is None:
                    fusion_state = f"semantic-{semantic_status}"
                else:
                    assert binding.point_cloud is not None and binding.pose is not None
                    points_map = np.asarray(
                        binding.point_cloud.positions_xyz, dtype=np.float64
                    ).reshape((-1, 3))
                    position = binding.pose.position_xyz
                    quaternion = binding.pose.orientation_xyzw
                    projection_started = time.perf_counter()
                    pixels, depths, source_indices, points_lidar = project_points(
                        points_map,
                        position,
                        quaternion,
                        projection,
                    )
                    latency["projection_ms"].append(
                        (time.perf_counter() - projection_started) * 1000
                    )
                    association_started = time.perf_counter()
                    fusions = fuse_tracks(
                        tracks=[_track_document(track) for track in tracks],
                        semantic_map=current_semantic.mask,
                        pixels=pixels,
                        depths=depths,
                        source_indices=source_indices,
                        points_map=points_map,
                        points_lidar=points_lidar,
                        association=e14["association"],
                        distance_history=history,
                        completion_tracker=completion_tracker,
                        sensor_position_map=position,
                        session_seconds=frame_seconds,
                    )
                    latency["association_ms"].append(
                        (time.perf_counter() - association_started) * 1000
                    )
                    fusion_state = "fused"
                    fused_frames += 1
                fusion_state_counts[fusion_state] += 1
                accepted = [item for item in fusions if item.cuboid is not None]
                accepted_cuboids += len(accepted)
                for item in fusions:
                    rejection_counts[item.status] += 1
                clearance_started = time.perf_counter()
                clearance_state = clearance(points_lidar, e14["world_state"]["clearance"])
                latency["clearance_ms"].append((time.perf_counter() - clearance_started) * 1000)
                world_started = time.perf_counter()
                result_age = max(0.0, (world_started - envelope.scheduled_monotonic) * 1000)
                if result_age >= 1000:
                    health = "unavailable"
                elif result_age >= float(live["acceptance"]["maximum_p95_world_state_age_ms"]):
                    health = "stale"
                elif fusion_state != "fused":
                    health = "degraded"
                else:
                    health = "healthy"
                world = projector.project(
                    frame_index=envelope.frame_index,
                    source_frame_index=int(envelope.timeline["source_frame_index"]),
                    session_seconds=frame_seconds,
                    fusion_state=fusion_state,
                    fusions=fusions,
                    points_lidar=points_lidar,
                    clearance_state=clearance_state,
                    delivery={
                        "health": health,
                        "result_age_ms": result_age,
                        "semantic_status": semantic_status,
                        "semantic_source_age_ms": semantic_age,
                        "lidar_camera_delta_ms": binding.lidar_camera_delta_ms,
                        "pose_point_delta_ms": binding.pose_point_delta_ms,
                        "clock_qualification": "worker-ingress-only",
                    },
                )
                raw_fusion_objects = [fusion_document(item) for item in fusions]
                if temporal_stabilizer is None:
                    fusion_objects = raw_fusion_objects
                else:
                    temporal_started = time.perf_counter()
                    fusion_objects = temporal_stabilizer.update(
                        frame_index=envelope.frame_index,
                        session_seconds=frame_seconds,
                        objects=raw_fusion_objects,
                    )
                    world = stabilize_world_state(
                        world,
                        fusion_objects,
                        temporal_world_memory,
                    )
                    latency["temporal_2d_3d_ms"].append(
                        (time.perf_counter() - temporal_started) * 1000
                    )
                stabilized_cuboids += sum(
                    str(item.get("cuboid_status", "")).startswith("accepted-")
                    for item in fusion_objects
                )
                latency["world_state_ms"].append((time.perf_counter() - world_started) * 1000)
                result_age = max(0.0, (time.perf_counter() - envelope.scheduled_monotonic) * 1000)
                world["delivery"]["result_age_ms"] = result_age
                latency["world_state_age_ms"].append(result_age)
                latency["source_epoch_age_ms_unqualified"].append(
                    (time.time_ns() - int(envelope.timeline["captured_at_epoch_ns"])) / 1_000_000
                )
                fusion_row = {
                    "schema_version": FUSION_SCHEMA,
                    "frame_index": envelope.frame_index,
                    "source_frame_index": int(envelope.timeline["source_frame_index"]),
                    "session_seconds": frame_seconds,
                    "fusion_state": fusion_state,
                    "semantic_status": semantic_status,
                    "semantic_source_frame_index": (
                        None if current_semantic is None else current_semantic.source_frame_index
                    ),
                }
                raw_fusion_stream.write(
                    json.dumps(
                        {**fusion_row, "objects": raw_fusion_objects},
                        sort_keys=True,
                        separators=(",", ":"),
                        allow_nan=False,
                    )
                    + "\n"
                )
                fusion_stream.write(
                    json.dumps(
                        {**fusion_row, "objects": fusion_objects},
                        sort_keys=True,
                        separators=(",", ":"),
                        allow_nan=False,
                    )
                    + "\n"
                )
                world_stream.write(
                    json.dumps(
                        world,
                        sort_keys=True,
                        separators=(",", ":"),
                        allow_nan=False,
                    )
                    + "\n"
                )
                from PIL import Image

                encoded_image = io.BytesIO()
                Image.fromarray(envelope.image).save(
                    encoded_image,
                    format="JPEG",
                    quality=80,
                    optimize=False,
                )
                live_result = encode_live_perception_result(
                    frame_index=envelope.frame_index,
                    source_frame_index=int(envelope.timeline["source_frame_index"]),
                    session_seconds=frame_seconds,
                    captured_at_epoch_ns=int(envelope.timeline["captured_at_epoch_ns"]),
                    image_jpeg=encoded_image.getvalue(),
                    segmentation_mask=(
                        current_semantic.mask
                        if current_semantic is not None and semantic_status == "fresh"
                        else None
                    ),
                    objects=fusion_objects,
                    delivery=world["delivery"],
                )
                try:
                    result_queue.put_nowait(live_result)
                except queue.Full:
                    with suppress(queue.Empty):
                        result_queue.get_nowait()
                        result_queue.task_done()
                        transport.results_dropped += 1
                    result_queue.put_nowait(live_result)
            except Exception:
                detector_failures += 1
                raise

        result_complete.set()

        receiver_thread.join(timeout=args.max_duration_seconds + 10)
        decoder_watcher.join(timeout=30)
        semantic_thread.join(timeout=30)
        if receiver_thread.is_alive() or decoder_watcher.is_alive() or semantic_thread.is_alive():
            raise RuntimeError("LAB E15 runtime thread did not stop")
        if transport.failures or decoder_watch_failures or callback_failures or semantic_errors:
            failures = [
                *(transport.failures or []),
                *decoder_watch_failures,
                *callback_failures,
                *semantic_errors,
            ]
            summary = "; ".join(
                f"{type(failure).__name__}: {str(failure)[:240]}" for failure in failures[:8]
            )
            raise RuntimeError(f"LAB E15 runtime worker failed: {summary}")
        for stream in (
            semantic_stream,
            raw_fusion_stream,
            fusion_stream,
            world_stream,
        ):
            stream.flush()
            os.fsync(stream.fileno())

    run_wall = time.perf_counter() - run_started
    detector_state = detector_queue.snapshot()
    semantic_state = semantic_queue.snapshot()
    if not first_camera_epoch_ns or not last_camera_epoch_ns:
        raise RuntimeError("LAB E15 received no decoded camera interval")
    source_span = max(
        1e-9,
        (last_camera_epoch_ns[0] - first_camera_epoch_ns[0]) / 1_000_000_000,
    )
    detector_fps = int(detector_state["consumed"]) / max(source_span, run_wall, 1e-9)
    semantic_fps = int(semantic_state["consumed"]) / max(source_span, run_wall, 1e-9)
    semantic_scheduled = (
        (decoded_frame_count - 1) // int(scheduling["semantic_sample_every_frames"])
    ) + 1
    fresh_coverage = status_counts["fresh"] / max(1, int(detector_state["consumed"]))
    fused_fraction = fused_frames / max(1, int(detector_state["consumed"]))
    latency_summary = {name: _percentiles(values) for name, values in latency.items()}
    semantic_summary = {name: _percentiles(values) for name, values in semantic_latency.items()}
    sensor_decode_summary = {
        name: _percentiles(values) for name, values in sensor_decode_ms.items()
    }
    runtime_summary = runtime_telemetry.summary()
    temporal_track_summary = None if temporal_stabilizer is None else temporal_stabilizer.snapshot()
    temporal_semantic_summary = (
        None if semantic_stabilizer is None else semantic_stabilizer.snapshot()
    )
    acceptance = live["acceptance"]
    checks = {
        "minimum_camera_frames": decoded_frame_count >= int(acceptance["minimum_camera_frames"]),
        "camera_decoder_accounting": decoder.snapshot()["decoded_frames"]
        == transport.counts["camera-frame"],
        "detector_accounting": int(detector_state["consumed"])
        + int(detector_state["dropped_overflow"])
        == decoded_frame_count,
        "detector_minimum_effective_fps": detector_fps
        >= float(acceptance["detector_minimum_effective_fps"]),
        "detector_maximum_drop_fraction": int(detector_state["dropped_overflow"])
        / decoded_frame_count
        <= float(acceptance["detector_maximum_drop_fraction"]),
        "semantic_accounting": int(semantic_state["consumed"])
        + int(semantic_state["dropped_overflow"])
        == semantic_scheduled,
        "semantic_minimum_effective_fps": semantic_fps
        >= float(acceptance["semantic_minimum_effective_fps"]),
        "semantic_maximum_drop_fraction": int(semantic_state["dropped_overflow"])
        / semantic_scheduled
        <= float(acceptance["semantic_maximum_drop_fraction"]),
        "semantic_maximum_p95_completion_age_ms": float(
            semantic_summary["completion_age_ms"]["p95"]
        )
        <= float(acceptance["semantic_maximum_p95_completion_age_ms"]),
        "minimum_fresh_semantic_coverage": fresh_coverage
        >= float(acceptance["minimum_fresh_semantic_coverage"]),
        "minimum_fused_fraction": fused_fraction >= float(acceptance["minimum_fused_fraction"]),
        "maximum_p95_decode_age_ms": float(latency_summary["decode_age_ms"]["p95"])
        <= float(acceptance["maximum_p95_decode_age_ms"]),
        "maximum_p95_world_state_age_ms": float(latency_summary["world_state_age_ms"]["p95"])
        <= float(acceptance["maximum_p95_world_state_age_ms"]),
        "zero_transport_gaps": (
            transport.ingress_sequence_gaps == 0
            if acceptance["require_zero_transport_gaps"]
            else True
        ),
        "zero_camera_sequence_gaps": (
            transport.camera_sequence_gaps == 0
            if acceptance["require_zero_camera_sequence_gaps"]
            else True
        ),
        "session_end_seen": transport.session_end_seen,
        "zero_failures": (
            detector_failures == 0
            and not transport.failures
            and not callback_failures
            and not semantic_errors
            if acceptance["require_zero_failures"]
            else True
        ),
        "authority_remains_shadow_only": live["authority"]
        == {"commands_enabled": False, "navigation_or_safety_accepted": False},
    }
    if stability is not None:
        temporal_acceptance = stability["acceptance"]
        assert temporal_track_summary is not None
        assert temporal_semantic_summary is not None
        checks.update(
            {
                "temporal_camera_processing_p95": float(latency_summary["temporal_2d_3d_ms"]["p95"])
                <= float(temporal_acceptance["maximum_camera_frame_processing_p95_ms"]),
                "temporal_semantic_processing_p95": float(
                    temporal_semantic_summary["processing_ms"]["p95"]
                )
                <= float(temporal_acceptance["maximum_semantic_frame_processing_p95_ms"]),
                "temporal_track_state_bound": int(temporal_track_summary["peak_track_states"])
                <= int(temporal_acceptance["maximum_track_states_observed"]),
                "temporal_semantic_unsupported_change_reduction": float(
                    temporal_semantic_summary["unsupported_change_reduction_fraction"]
                )
                >= float(
                    temporal_acceptance["minimum_semantic_unsupported_change_reduction_fraction"]
                ),
                "temporal_rss_growth_bound": float(runtime_summary["rss_growth_mib"])
                <= float(temporal_acceptance["maximum_rss_growth_mib"]),
                "temporal_authority_remains_shadow_only": stability["authority"]
                == {
                    "commands_enabled": False,
                    "navigation_or_safety_accepted": False,
                },
            }
        )
    accepted = all(checks.values())
    identity = {
        "schema_version": IDENTITY_SCHEMA,
        "pipeline": (PIPELINE_ID if stability is None else INLINE_TEMPORAL_PIPELINE_ID),
        "session_id": transport.session_id,
        "bootstrap_job_id": common["job"]["job_id"],
        "source_id": live["source"]["source_id"],
        "profiles": {
            "live_sha256": common["live_sha256"],
            "e14_sha256": common["e14_sha256"],
            "detector_sha256": common["detector_sha256"],
            "semantic_sha256": common["semantic_sha256"],
            "stability_sha256": common["stability_sha256"],
        },
        "projection_pack": {
            "id": common["projection_manifest"]["pack_id"],
            "identity_sha256": common["projection_manifest"]["identity_sha256"],
        },
        "lidar_evidence": lidar_readiness_document(K1_LIVE_LIDAR_PROFILE),
        "worker_package": {
            "id": common["worker_package"]["package_id"],
            "identity_sha256": common["worker_package"]["identity_sha256"],
        },
        "valid_fov": common["valid_fov"],
        "models": {
            "detector": detector["model"],
            "detector_files": common["detector_files"],
            "semantic": semantic["model"],
            "semantic_files": semantic_files,
        },
        "runtime": {
            "runner_sha256": sha256(Path(__file__).resolve(strict=True)),
            "media_runtime_sha256": sha256(
                Path(__file__).with_name("e15_shadow_runtime.py").resolve(strict=True)
            ),
            "orchestrator_sha256": args.orchestrator_sha256,
            "container_image": args.container_image,
            "pyav": av.__version__,
            "lz4": importlib.metadata.version("lz4"),
        },
        "authority": live["authority"],
    }
    identity_sha256 = hashlib.sha256(canonical_json(identity)).hexdigest()
    result_id = f"e15-shadow-inference-{identity_sha256}"
    metrics = {
        "source_span_seconds": source_span,
        "run_wall_seconds": run_wall,
        "transport": {
            "counts": dict(sorted(transport.counts.items())),
            "payload_bytes": dict(sorted(transport.payload_bytes.items())),
            "first_ingress_sequence": transport.first_ingress_sequence,
            "last_ingress_sequence": transport.last_ingress_sequence,
            "ingress_sequence_gaps": transport.ingress_sequence_gaps,
            "camera_sequence_gaps": transport.camera_sequence_gaps,
            "session_end_seen": transport.session_end_seen,
            "timed_out": transport.timed_out,
            "results_published": transport.results_published,
            "result_bytes_published": transport.result_bytes_published,
            "results_dropped": transport.results_dropped,
        },
        "decoder": decoder.snapshot(),
        "detector": {
            "effective_fps": detector_fps,
            "queue": detector_state,
        },
        "semantic": {
            "effective_fps": semantic_fps,
            "fresh_coverage": fresh_coverage,
            "status_counts": dict(status_counts),
            "queue": semantic_state,
            "latency_ms": semantic_summary,
        },
        "fusion": {
            "fused_frames": fused_frames,
            "fused_fraction": fused_fraction,
            "accepted_cuboids": accepted_cuboids,
            "stabilized_cuboids": stabilized_cuboids,
            "state_counts": dict(fusion_state_counts),
            "rejection_counts": dict(rejection_counts),
            "synchronizer": synchronizer.snapshot(),
            "sensor_decode_ms": sensor_decode_summary,
        },
        "lidar_quality": lidar_quality.snapshot(),
        "latency_ms": latency_summary,
        "temporal_stability": {
            "enabled": stability is not None,
            "profile_sha256": common["stability_sha256"],
            "tracking_2d_3d": temporal_track_summary,
            "semantic": temporal_semantic_summary,
            "world_memory_objects": len(temporal_world_memory),
        },
        "gpu_telemetry": gpu.summary(),
        "runtime_telemetry": runtime_summary,
        "process_cpu_seconds": time.process_time() - process_cpu_started,
        "process_peak_rss_mib": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024,
        "cuda_peak_memory_allocated_mib": torch.cuda.max_memory_allocated() / 2**20,
        "cuda_peak_memory_reserved_mib": torch.cuda.max_memory_reserved() / 2**20,
        "disk": {
            "free_bytes_before": disk_before,
            "free_bytes_after": shutil.disk_usage(output).free,
            "free_bytes_floor": args.free_bytes_floor,
        },
    }
    report = {
        "schema_version": REPORT_SCHEMA,
        "result_id": result_id,
        "created_at_utc": datetime.now(UTC)
        .isoformat(timespec="milliseconds")
        .replace("+00:00", "Z"),
        "state": "accepted" if accepted else "rejected",
        "ground_truth": False,
        "identity": identity,
        "runtime": {
            "hostname": platform.node(),
            "python": platform.python_version(),
            "numpy": np.__version__,
            "torch": torch.__version__,
            "transformers": transformers.__version__,
            "scipy": importlib.metadata.version("scipy"),
            "gpu": torch.cuda.get_device_name(),
        },
        "metrics": metrics,
        "acceptance": {
            "accepted": accepted,
            "checks": checks,
            "commands_enabled": False,
            "navigation_or_safety_accepted": False,
        },
        "limitations": [
            "Shadow diagnostic authority only; no commands or navigation output.",
            "Camera/LiDAR matching uses recorded host arrival time, not a hardware clock.",
            "K1 LiDAR is a vendor map increment, not an admitted raw sensor sweep.",
            "K1 LiDAR has no admitted per-point time, ring, scan geometry or IMU stream.",
            "Cross-host source epoch age is diagnostic and excluded from acceptance.",
            "COCO and Cityscapes models are not forest-domain or safety validated.",
            "Amodal cuboids infer unobserved volume from class priors.",
            *(
                [
                    "E23 temporal outputs are inline bounded shadow diagnostics, "
                    "not validated driving or safety authority."
                ]
                if stability is not None
                else []
            ),
        ],
    }
    report_path = output / "run-report.json"
    _write_json(report_path, report)
    artifacts = [
        _artifact(semantic_path, "e15-semantic-frames", "application/x-ndjson", SEMANTIC_SCHEMA),
        _artifact(
            raw_fusion_path,
            "e23-raw-fusion-frames",
            "application/x-ndjson",
            FUSION_SCHEMA,
        ),
        _artifact(fusion_path, "e15-fusion-frames", "application/x-ndjson", FUSION_SCHEMA),
        _artifact(world_path, "e15-world-state", "application/x-ndjson", WORLD_SCHEMA),
        _artifact(gpu_path, "worker-gpu-telemetry", "application/x-ndjson"),
        _artifact(
            runtime_path,
            "worker-runtime-telemetry",
            "application/x-ndjson",
            "missioncore.worker-runtime-telemetry/v1",
        ),
        _artifact(report_path, "e15-run-report", "application/json", REPORT_SCHEMA),
    ]
    _write_json(
        output / "result.json",
        {
            "schema_version": RESULT_SCHEMA,
            "result_id": result_id,
            "identity_sha256": identity_sha256,
            "identity": identity,
            "created_at_utc": report["created_at_utc"],
            "acceptance_state": report["state"],
            "ground_truth": False,
            "publication_scope": "live-shadow-diagnostic-only",
            "frames_processed": int(detector_state["consumed"]),
            "artifacts": artifacts,
        },
    )
    print(
        json.dumps(
            {
                "result_id": result_id,
                "accepted": accepted,
                "frames": int(detector_state["consumed"]),
                "detector_fps": detector_fps,
                "semantic_fps": semantic_fps,
                "fused_fraction": fused_fraction,
                "world_state_age_p95_ms": latency_summary["world_state_age_ms"]["p95"],
                "accepted_cuboids": accepted_cuboids,
                "inline_temporal": stability is not None,
                "temporal_2d_3d_p95_ms": latency_summary["temporal_2d_3d_ms"]["p95"],
            },
            sort_keys=True,
        ),
        flush=True,
    )
    return 0 if accepted else 2


_CONTROL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")


def _persistent_run_arguments(
    service_args: argparse.Namespace,
    request: dict[str, Any],
) -> argparse.Namespace:
    request_id = request.get("request_id")
    output_name = request.get("output_name")
    token = request.get("token")
    requested_duration = request.get(
        "max_duration_seconds",
        service_args.max_duration_seconds,
    )
    if (
        not isinstance(request_id, str)
        or _CONTROL_ID.fullmatch(request_id) is None
        or not isinstance(output_name, str)
        or _CONTROL_ID.fullmatch(output_name) is None
        or output_name in {".", ".."}
        or not isinstance(token, str)
        or not 40 <= len(token) <= 512
        or not isinstance(requested_duration, int | float)
        or isinstance(requested_duration, bool)
        or not math.isfinite(float(requested_duration))
        or not 5 <= float(requested_duration) <= float(service_args.max_duration_seconds)
    ):
        raise RuntimeError("persistent worker request contract is invalid")
    output_root = service_args.output_root.resolve(strict=True)
    output = (output_root / output_name).resolve()
    if output.parent != output_root or output.exists():
        raise RuntimeError("persistent worker output target is invalid")
    values = vars(service_args).copy()
    values.update(
        command="run",
        output=output,
        token=token,
        token_stdin=False,
        max_duration_seconds=float(requested_duration),
    )
    values.pop("output_root", None)
    values.pop("listen_host", None)
    values.pop("listen_port", None)
    return argparse.Namespace(**values)


def serve(args: argparse.Namespace) -> int:
    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

    import av
    import torch

    common = _common(args)
    if av.__version__ != common["live"]["transport"]["pyav_version"]:
        raise RuntimeError("LAB E15 PyAV version changed")
    output_root = args.output_root.resolve(strict=True)
    _assert_disk(output_root, args.free_bytes_floor)
    load_started = time.perf_counter()
    loaded = _load_models(args, common)
    model_load_seconds = time.perf_counter() - load_started
    run_lock = threading.Lock()
    state = {"busy": False, "completed_runs": 0, "failed_runs": 0}

    class Handler(BaseHTTPRequestHandler):
        server_version = "MissionCorePersistentPerception/1"
        sys_version = ""

        def log_message(self, _format: str, *_values: object) -> None:
            return

        def _send(self, status: int, document: dict[str, Any]) -> None:
            payload = json.dumps(
                document,
                sort_keys=True,
                separators=(",", ":"),
                allow_nan=False,
            ).encode("utf-8")
            self.send_response(status)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(payload)))
            self.send_header("Cache-Control", "no-store")
            self.send_header("X-Content-Type-Options", "nosniff")
            self.end_headers()
            self.wfile.write(payload)

        def do_GET(self) -> None:
            if self.path != "/health":
                self._send(404, {"ok": False, "error": "not-found"})
                return
            self._send(
                200,
                {
                    "ok": True,
                    "state": "busy" if state["busy"] else "ready",
                    "models_loaded": True,
                    "model_load_seconds": model_load_seconds,
                    "completed_runs": state["completed_runs"],
                    "failed_runs": state["failed_runs"],
                    "authority": common["live"]["authority"],
                    "gpu": torch.cuda.get_device_name(),
                },
            )

        def do_POST(self) -> None:
            if self.path != "/run":
                self._send(404, {"ok": False, "error": "not-found"})
                return
            content_type = self.headers.get("Content-Type", "").split(";", 1)[0]
            try:
                length = int(self.headers.get("Content-Length", ""))
            except ValueError:
                length = -1
            if content_type != "application/json" or not 2 <= length <= 4096:
                self._send(400, {"ok": False, "error": "invalid-request"})
                return
            if not run_lock.acquire(blocking=False):
                self._send(409, {"ok": False, "error": "worker-busy"})
                return
            state["busy"] = True
            request_id = "invalid"
            try:
                document = json.loads(self.rfile.read(length))
                if not isinstance(document, dict):
                    raise RuntimeError("persistent worker request is not an object")
                request_id = str(document.get("request_id", "invalid"))
                run_args = _persistent_run_arguments(args, document)
                document["token"] = None
                exit_code = run(run_args, loaded)
                state["completed_runs"] += 1
                self._send(
                    200,
                    {
                        "ok": exit_code == 0,
                        "request_id": request_id,
                        "exit_code": exit_code,
                        "models_reused": True,
                    },
                )
            except Exception as exc:
                state["failed_runs"] += 1
                print(
                    json.dumps(
                        {
                            "event": "persistent-worker-run-failed",
                            "request_id": request_id,
                            "error_type": type(exc).__name__,
                            "error": str(exc)[:1000],
                        },
                        sort_keys=True,
                    ),
                    flush=True,
                )
                self._send(
                    422,
                    {
                        "ok": False,
                        "request_id": request_id,
                        "error": type(exc).__name__,
                    },
                )
            finally:
                state["busy"] = False
                run_lock.release()

    server = ThreadingHTTPServer((args.listen_host, args.listen_port), Handler)
    print(
        json.dumps(
            {
                "state": "persistent-worker-ready",
                "listen_host": args.listen_host,
                "listen_port": args.listen_port,
                "model_load_seconds": model_load_seconds,
                "models_loaded": True,
                "commands_enabled": False,
                "navigation_or_safety_accepted": False,
            },
            sort_keys=True,
        ),
        flush=True,
    )
    try:
        server.serve_forever(poll_interval=0.25)
    finally:
        server.server_close()
    return 0


def main() -> int:
    args = arguments()
    if args.command == "preflight":
        return preflight(args)
    if args.command == "serve":
        return serve(args)
    return run(args)


if __name__ == "__main__":
    raise SystemExit(main())
